Rec — Record Utilities

Plain JavaScript objects serving as dictionaries — typed as Record<string, A> — are the most ubiquitous data structures in any TypeScript application. We use them for configurations, lookup tables, and serialized payloads.

However, working with records in functional pipelines introduces two common points of friction:

They are data-first: Modifying objects natively forces us to write verbose, inline spreads inside our pipe chains: (obj) => ({ ...obj, key: value }).
They are unsafe: Accessing a missing key via bracket notation (obj[key]) silently returns undefined at runtime, bypassing the type system and causing errors downstream.

Rec solves both issues. It provides a small, highly optimized collection of data-last, curried utilities designed to compose cleanly in pipelines, returning explicit Maybe values for safe, crash-free key lookups.

Safe Key Lookup

Rec.lookup retrieves the value associated with a key, wrapping it in a Maybe container to make key absence explicit in your types:

import { pipe } from "@nlozgachev/pipelined/composition";
import { Maybe } from "@nlozgachev/pipelined/core";
import { Rec } from "@nlozgachev/pipelined/data";

const settings = { theme: "dark", language: "en" };

pipe(settings, Rec.lookup("theme")); // Some("dark")
pipe(settings, Rec.lookup("font"));  // None (not undefined)

This integrates naturally with other pipelines:

const serverTimeout = pipe(
  configPayload,
  Rec.lookup("timeout"),
  Maybe.map((s) => Number(s)),
  Maybe.filter((n) => !isNaN(n)),
  Maybe.getOrElse(() => 30000), // Secure fallback
);

Transforming Values

Rec.map transforms every value inside a record, returning a new record with the original keys preserved:

pipe({ a: 1, b: 2 }, Rec.map((n) => n * 10)); // { a: 10, b: 20 }

If the transformation requires the key as well as the value, Rec.mapWithKey passes both to your callback:

pipe({ a: 1, b: 2 }, Rec.mapWithKey((key, value) => `${key}_${value}`));
// { a: "a_1", b: "b_2" }

Filtering Values

Rec.filter keeps only the entries whose values satisfy a predicate.
Rec.filterWithKey passes both the key and the value to the predicate:

// Keep only values greater than 1:
pipe({ a: 1, b: 2, c: 3 }, Rec.filter((n) => n > 1)); // { b: 2, c: 3 }

// Keep values where the key matches a specific prefix and value is non-zero:
pipe(
  { a: 1, b: 0, c: 3 },
  Rec.filterWithKey((key, value) => key !== "a" && value > 0),
); // { c: 3 }

Picking and Omitting Keys

Rec.pick returns a new record containing only the specified keys.
Rec.omit returns a new record with the specified keys removed.

Both utilities are fully type-safe. pick returns a precise Pick<A, K> type and omit returns a precise Omit<A, K> type, ensuring the compiler tracks exactly which properties survive the pipeline:

const baseProfile = { id: "123", name: "Alice", email: "alice@example.com" };

const summary = pipe(baseProfile, Rec.pick("id", "name")); // { id: "123", name: "Alice" }
const publicView = pipe(baseProfile, Rec.omit("email"));   // { id: "123", name: "Alice" }

Merging Records

Rec.merge combines two records, returning a fresh object. Keys present in the second record override those in the first record, behaving identically to standard object spreads:

pipe(
  { a: 1, b: 2 },
  Rec.merge({ b: 99, c: 3 }),
); // { a: 1, b: 99, c: 3 }

Keys, Values, and Entries

Rec provides utilities to extract arrays of keys, values, or entries:

const coordinates = { x: 10, y: 20 };

Rec.keys(coordinates);    // ["x", "y"]
Rec.values(coordinates);  // [10, 20]
Rec.entries(coordinates); // [["x", 10], ["y", 20]]

Rec.from.entries is the inverse constructor, building a record from an array of key-value pairs:

Rec.from.entries([["a", 1], ["b", 2]]); // { a: 1, b: 2 }

You can pair entries and from.entries to easily perform structural record mappings:

// Upper-casing all keys in a record:
const rawInput = { firstName: "Alice", lastName: "Smith" };

const parsed = pipe(
  rawInput,
  Rec.entries,
  (entries) => entries.map(([key, value]) => [key.toUpperCase(), value] as const),
  Rec.from.entries,
); // { FIRSTNAME: "Alice", LASTNAME: "Smith" }

Sizing and Verification

Rec.is.empty({});         // true
Rec.is.empty({ a: 1 });   // false

Rec.size({ a: 1, b: 2 }); // 2

Traversing and Sequencing Records

When a record contains values that wrap effectful computations, you may want to aggregate those individual effects into a single container holding the mapped record. Rec.traverse and Rec.sequence provide drawers for traversing and sequencing records, short-circuiting on the first failure.

Rec.traverse.Maybe maps a Maybe-returning function over the values of a record. If every value produces a Some, it returns Some of the updated record. If any value maps to None, the entire operation returns None:

import { Maybe } from "@nlozgachev/pipelined/core";
import { Rec } from "@nlozgachev/pipelined/data";

const parseNum = (s: string) => s === "NaN" ? Maybe.make.none() : Maybe.make.some(Number(s));

pipe({ a: "1", b: "2" }, Rec.traverse.Maybe(parseNum)); // Some({ a: 1, b: 2 })
pipe({ a: "1", b: "NaN" }, Rec.traverse.Maybe(parseNum)); // None

Rec.sequence.Maybe takes a record where every value is already a Maybe and collapses it into a single Maybe of a record:

Rec.sequence.Maybe({ a: Maybe.make.some(1), b: Maybe.make.some(2) }); // Some({ a: 1, b: 2 })
Rec.sequence.Maybe({ a: Maybe.make.some(1), b: Maybe.make.none() }); // None

Similarly, Rec.traverse.Result and Rec.sequence.Result aggregate fallible computations:

import { Result } from "@nlozgachev/pipelined/core";

const validateStock = (quantity: number) =>
  quantity < 0 ? Result.make.err("Negative stock not allowed") : Result.make.ok(quantity);

pipe({ apples: 10, oranges: 5 }, Rec.traverse.Result(validateStock)); // Ok({ apples: 10, oranges: 5 })
pipe({ apples: 10, oranges: -1 }, Rec.traverse.Result(validateStock)); // Err("Negative stock not allowed")

Non-Empty Records

Sometimes, you need compile-time assurance that a record contains at least one key-value pair. You can represent this with the branded type Rec.NonEmpty<A> and refine standard records using the type guard Rec.is.nonEmpty.

const userRecord = { admin: "Alice" };

if (Rec.is.nonEmpty(userRecord)) {
  // Inside this block, userRecord is typed as Rec.NonEmpty<string>
}

You can create a non-empty record directly using Rec.NonEmpty.singleton or parse a standard record using Rec.NonEmpty.from.Record:

const singletonRec = Rec.NonEmpty.singleton("main", 42); // Rec.NonEmpty<number>

const parsedRec = Rec.NonEmpty.from.Record(userRecord); // Some(Rec.NonEmpty<string>)
const emptyRec = Rec.NonEmpty.from.Record({});          // None

Operating on Rec.NonEmpty<A> ensures that operations which would normally return standard arrays (which could be empty) instead return guaranteed non-empty arrays (Arr.NonEmpty). For example, extracting keys, values, or entries from a non-empty record returns Arr.NonEmpty:

const users = Rec.NonEmpty.singleton("admin", "Alice");

Rec.NonEmpty.keys(users);    // Arr.NonEmpty<string> (e.g. ["admin"])
Rec.NonEmpty.values(users);  // Arr.NonEmpty<string> (e.g. ["Alice"])
Rec.NonEmpty.entries(users); // Arr.NonEmpty<readonly [string, string]> (e.g. [["admin", "Alice"]])

You can also reduce the values of a non-empty record without providing an initial accumulator seed, since there is guaranteed to be at least one value:

const scores = Rec.NonEmpty.singleton("math", 95);
pipe(scores, Rec.NonEmpty.reduce((a, b) => a + b)); // 95

Additionally, Rec.map and Rec.mapWithKey preserve the non-empty status of the record in their return types:

const doubled = Rec.map((n: number) => n * 2)(scores); // Rec.NonEmpty<number>

For more details on operating with guaranteed non-empty data structures, see the dedicated Non-Empty Collections Guide.

Problems it solves

Type-safe payload sanitization: When preparing API responses, stripping private data (such as password hashes, secret tokens, or internal flags) using Rec.omit or retaining allowed fields via Rec.pick narrows the TypeScript type statically, preventing accidental access to omitted properties downstream.
Transforming record values in ingestion pipelines: When processing dynamic dictionaries (such as converting string prices to numbers or status strings to enums), Rec.map and Rec.filter apply transformations point-free within pipe workflows while preserving key structure.
Payload key migration and renaming (Rec.mapKeys): When ingesting third-party webhook payloads or migrating legacy API schemas (such as converting snake_case keys to camelCase), Rec.mapKeys transforms object keys immutably across entire dictionaries.
Safe dynamic property retrieval: When looking up runtime keys in configuration objects, user attributes, or localized string tables, direct index access (obj[key]) returns undefined without static warnings. Rec.get returns a Maybe<V>, requiring explicit presence handling before operating on values.
Merging multi-layer configuration records: Combining default theme tokens with user style overrides or merging localized message catalogs without mutating input objects.