RecordX overview
Generic, framework-agnostic extensions to Effect’s Record module.
Added in v0.0.0
Table of contents
combining
deepMerge
Deep-merges two JSON values, with b winning on conflicts.
Plain objects (per PredicateX.unsafeIsRecord) are merged recursively, key-by-key; every other shape — primitives, arrays, and impostors like Map/Date/class instances — is replaced wholesale by b. If either side isn’t a plain object, b is returned as-is. Neither input is mutated. Reach for it to layer partial JSON overrides on top of a base.
Signature
export declare const deepMerge: ((b: unknown) => (a: unknown) => unknown) & ((a: unknown, b: unknown) => unknown)
Example
import { RecordX } from "@nunofyobiz/effect-extras"
import { pipe } from "effect"
const defaults = { editor: { fontSize: 14, theme: "light" }, plugins: ["spellcheck"] }
const saved = { editor: { theme: "dark" }, plugins: ["formatter"] }
// Keep the default font size, override the theme, and replace the plugin list.
assert.deepStrictEqual(RecordX.deepMerge(defaults, saved), {
editor: { fontSize: 14, theme: "dark" },
plugins: ["formatter"]
})
// The pipeable form layers saved settings onto the same defaults.
assert.deepStrictEqual(pipe(defaults, RecordX.deepMerge(saved)), {
editor: { fontSize: 14, theme: "dark" },
plugins: ["formatter"]
})
Added in v0.0.0
deleteByPath
Immutably deletes the value at a path from a JSON object, pruning any parent objects left empty by the deletion.
Walks path from the root; when it resolves to an existing key, that key is removed and every ancestor that becomes empty as a result is removed too. Returns Some(newObject) when the path existed (so callers can tell something changed), or None when it was absent or object isn’t a plain object. The input is never mutated. Use it to remove a nested setting and avoid leaving empty settings sections behind. An empty path or traversal into a leaf or array also returns None.
Signature
export declare const deleteByPath: ((path: readonly string[]) => (object: unknown) => Option.Option<unknown>) &
((object: unknown, path: readonly string[]) => Option.Option<unknown>)
Example
import { RecordX } from "@nunofyobiz/effect-extras"
import { Option, pipe } from "effect"
// Remove the only editor setting, so the empty editor section disappears too.
assert.deepStrictEqual(RecordX.deleteByPath({ editor: { theme: "dark" } }, ["editor", "theme"]), Option.some({}))
// A saved font size keeps the editor section present after removing the theme.
assert.deepStrictEqual(
RecordX.deleteByPath({ editor: { theme: "dark", fontSize: 14 } }, ["editor", "theme"]),
Option.some({ editor: { fontSize: 14 } })
)
// An unsaved setting has nothing to delete, including in the pipeable form.
assert.deepStrictEqual(pipe({ theme: "dark" }, RecordX.deleteByPath(["zoom"])), Option.none())
Added in v0.0.0
constructors
collectBy
Indexes an iterable of values into a Record, keying each value by the result of identify.
Builds a lookup table from a collection: every value is stored under the key identify(value). When two values produce the same key the later one wins, so the result holds the last value seen per key. Useful for turning a list of records into a by-id map.
Signature
export declare const collectBy: (<K extends string | symbol, V>(
identify: (v: V) => K
) => (values: Iterable<V>) => Record<K, V>) &
(<K extends string | symbol, V>(values: Iterable<V>, identify: (v: V) => K) => Record<K, V>)
Example
import { pipe } from "effect"
import { RecordX } from "@nunofyobiz/effect-extras"
const products = [
{ id: "mug", price: 12 },
{ id: "notebook", price: 8 },
{ id: "mug", price: 10 } // The later price replaces the earlier mug entry.
]
// Build a product lookup using the latest entry for each id.
assert.deepStrictEqual(
RecordX.collectBy(products, (product) => product.id),
{ mug: { id: "mug", price: 10 }, notebook: { id: "notebook", price: 8 } }
)
// The pipeable form builds the same lookup.
assert.deepStrictEqual(
pipe(
products,
RecordX.collectBy((product) => product.id)
),
{ mug: { id: "mug", price: 10 }, notebook: { id: "notebook", price: 8 } }
)
Added in v0.0.0
conversions
keysAs
Re-types the keys of a Record to a different key type K2 without touching the runtime value.
A purely type-level reinterpretation: the record is returned as-is, but the compiler now treats its keys as K2 instead of the inferred K1. Use it at a boundary where you know the keys conform to a narrower branded or literal key type that TypeScript can’t infer from the value alone. It performs no validation — the caller is responsible for the keys actually matching K2.
Signature
export declare const keysAs: <K2 extends PropertyKey>() => <K1 extends PropertyKey, V>(
record: Record<K1, V>
) => Record<K2, V>
Example
import { RecordX } from "@nunofyobiz/effect-extras"
type ProductId = "mug" | "notebook"
const prices: Record<string, number> = { mug: 12, notebook: 8 }
const byProduct = RecordX.keysAs<ProductId>()(prices)
// Treat the known product keys as ProductId; values and the reference stay the same.
assert.deepStrictEqual(byProduct, { mug: 12, notebook: 8 })
assert.strictEqual(byProduct, prices)
Added in v0.0.0
getters
takeFirstWhere
Returns the smallest value of record (per order) that matches predicate, narrowed to the refined type B, or Option.none() if none match.
Use it to find the lowest-ranked eligible value in a lookup table. Only own enumerable string-keyed values participate; keys do not affect the ranking.
Signature
export declare const takeFirstWhere: (<K extends PropertyKey, A, B extends A>(
predicate: Predicate.Refinement<A, B>,
order: Order.Order<B>
) => (record: Record<K, A>) => Option.Option<B>) &
(<K extends PropertyKey, A, B extends A>(
record: Record<K, A>,
predicate: Predicate.Refinement<A, B>,
order: Order.Order<B>
) => Option.Option<B>)
Example
import { Option, Order, Predicate, pipe } from "effect"
import { RecordX } from "@nunofyobiz/effect-extras"
const prices: Record<string, number | null> = { mug: 12, notebook: 8, lamp: null }
// Find the cheapest listed product, ignoring the unavailable lamp.
assert.deepStrictEqual(RecordX.takeFirstWhere(prices, Predicate.isNumber, Order.Number), Option.some(8))
// The pipeable form finds the same listed price.
assert.deepStrictEqual(pipe(prices, RecordX.takeFirstWhere(Predicate.isNumber, Order.Number)), Option.some(8))
Added in v0.0.0
takeLast
Returns the largest value of record according to order, wrapped in an Option so empty records are handled safely.
Use it to find a maximum, such as the highest price in a product lookup. Only own enumerable string-keyed values participate; an empty record yields Option.none(). Reverse the order to select the minimum instead.
Signature
export declare const takeLast: (<K extends PropertyKey, A>(
order: Order.Order<A>
) => (record: Record<K, A>) => Option.Option<A>) &
(<K extends PropertyKey, A>(record: Record<K, A>, order: Order.Order<A>) => Option.Option<A>)
Example
import { Option, Order, pipe } from "effect"
import { RecordX } from "@nunofyobiz/effect-extras"
// Select the highest product price without needing to sort the lookup yourself.
assert.deepStrictEqual(RecordX.takeLast({ mug: 12, notebook: 8, lamp: 35 }, Order.Number), Option.some(35))
// An empty price lookup has no maximum.
assert.deepStrictEqual(pipe({}, RecordX.takeLast(Order.Number)), Option.none())
Added in v0.0.0
takeLastWhere
Returns the largest value of record (per order) that matches predicate, narrowed to the refined type B, or Option.none() if none match.
Use it to find the highest-ranked eligible value in a lookup table. Only own enumerable string-keyed values participate; keys do not affect the ranking.
Signature
export declare const takeLastWhere: (<K extends PropertyKey, A, B extends A>(
predicate: Predicate.Refinement<A, B>,
order: Order.Order<B>
) => (record: Record<K, A>) => Option.Option<B>) &
(<K extends PropertyKey, A, B extends A>(
record: Record<K, A>,
predicate: Predicate.Refinement<A, B>,
order: Order.Order<B>
) => Option.Option<B>)
Example
import { Option, Order, Predicate, pipe } from "effect"
import { RecordX } from "@nunofyobiz/effect-extras"
const prices: Record<string, number | null> = { mug: 12, notebook: 8, lamp: null }
// Find the highest listed price, ignoring the unavailable lamp.
assert.deepStrictEqual(RecordX.takeLastWhere(prices, Predicate.isNumber, Order.Number), Option.some(12))
// No available products means there is no price to return.
assert.deepStrictEqual(pipe({ lamp: null }, RecordX.takeLastWhere(Predicate.isNumber, Order.Number)), Option.none())
Added in v0.0.0
guards
isNonEmptyRecord
Returns true when record has at least one own enumerable string key. Use it to check whether a settings or lookup record contains entries before processing it. Symbol keys and inherited entries do not count; the guard preserves the existing record type rather than proving any particular key exists.
Signature
export declare const isNonEmptyRecord: <K extends PropertyKey, V>(record: Record<K, V>) => record is Record<K, V>
Example
import { RecordX } from "@nunofyobiz/effect-extras"
// A saved theme counts as a setting; an empty settings record has no entries.
assert.deepStrictEqual(RecordX.isNonEmptyRecord({ theme: "dark" }), true)
assert.deepStrictEqual(RecordX.isNonEmptyRecord({}), false)
Added in v0.0.0
instances
deepMergeReducer
Combines settings or other object-valued layers from left to right using {@link deepMerge}, with later layers winning on conflicts.
deepMergeReducer.combineAll(layers) folds an iterable of object layers left-to-right via {@link deepMerge}. Use it when defaults and multiple sets of overrides need to become one object. Its initialValue is {}, an identity for object-valued layers, but not for every unknown value. An empty list yields {}, and a single object layer retains its contents.
Signature
export declare const deepMergeReducer: Reducer.Reducer<unknown>
Example
import { RecordX } from "@nunofyobiz/effect-extras"
// Saved preferences override defaults; workspace settings override both.
assert.deepStrictEqual(
RecordX.deepMergeReducer.combineAll([
{ editor: { fontSize: 14, theme: "light" } },
{ editor: { theme: "dark" }, autosave: true },
{ autosave: false }
]),
{ editor: { fontSize: 14, theme: "dark" }, autosave: false }
)
// No settings layers produce an empty settings object.
assert.deepStrictEqual(RecordX.deepMergeReducer.combineAll([]), {})
Added in v0.0.0
mapping
modifyIfExists
Modifies the value at key in self with f, leaving the record unchanged if the key doesn’t exist. Use it to adjust a saved setting only when the user has already supplied it.
Record.modify returns Option<Record> — None when the key is absent. This helper provides the common “do nothing if absent” semantics. The modifier is never invoked when the key is missing.
Signature
export declare const modifyIfExists: {
<K extends string, A>(key: NoInfer<K>, f: (a: A) => A): (self: Record<K, A>) => Record<K, A>
<K extends string, A>(self: Record<K, A>, key: NoInfer<K>, f: (a: A) => A): Record<K, A>
}
Example
import { pipe } from "effect"
import { RecordX } from "@nunofyobiz/effect-extras"
const settings: Record<string, number> = { fontSize: 14, lineHeight: 20 }
// Increase the saved font size without changing the other settings.
assert.deepStrictEqual(
RecordX.modifyIfExists(settings, "fontSize", (size) => size + 2),
{ fontSize: 16, lineHeight: 20 }
)
// An unsaved setting stays absent, and its modifier is never called.
assert.deepStrictEqual(
RecordX.modifyIfExists(settings, "zoom", (zoom) => zoom + 1),
settings
)
// The pipeable form makes the same font-size adjustment.
assert.deepStrictEqual(
pipe(
settings,
RecordX.modifyIfExists("fontSize", (size) => size + 2)
),
{ fontSize: 16, lineHeight: 20 }
)
Added in v0.0.0
upsert
Inserts or updates the value at key, deriving the new value from the current one via upsert.
The upsert function receives an Option of the existing value — Option.some(value) when the key is present, Option.none() when it’s absent — and returns the value to store. This unifies “insert if missing” and “update if present” into a single pass, with Option.match as the natural way to handle both cases.
Signature
export declare const upsert: (<K extends string | symbol, V>(
key: K,
upsert: (existingValue: Option.Option<V>) => V
) => (record: Record<K, V>) => Record<K, V>) &
(<K extends string | symbol, V>(
record: Record<K, V>,
key: K,
upsert: (existingValue: Option.Option<V>) => V
) => Record<K, V>)
Example
import { Option, pipe } from "effect"
import { RecordX } from "@nunofyobiz/effect-extras"
const bump = Option.match({
onNone: () => 1,
onSome: (n: number) => n + 1
})
// Count another view of a product already in the lookup.
assert.deepStrictEqual(RecordX.upsert({ mug: 1 }, "mug", bump), { mug: 2 })
// The first view of an unlisted product starts its count at one.
const views: Record<string, number> = { mug: 1 }
assert.deepStrictEqual(pipe(views, RecordX.upsert("notebook", bump)), {
mug: 1,
notebook: 1
})
Added in v0.0.0
transformations
canonicalize
Canonicalizes a JSON value by recursively sorting object keys; arrays keep their order.
Use it for stable serialization or comparison of JSON values that differ only in object key order. Plain objects (per PredicateX.unsafeIsRecord) and arrays become fresh containers with recursively canonicalized values; other leaves pass through unchanged. Only own enumerable string keys are retained. Keys sort ascending, subject to JavaScript’s numeric ordering of integer keys. Array order is preserved and the input is never mutated.
Signature
export declare const canonicalize: (value: unknown) => unknown
Example
import { RecordX } from "@nunofyobiz/effect-extras"
const settings = { theme: "dark", editor: { tabSize: 2, fontSize: 14 } }
// Different insertion orders now serialize to the same settings string.
assert.deepStrictEqual(
JSON.stringify(RecordX.canonicalize(settings)),
JSON.stringify({ editor: { fontSize: 14, tabSize: 2 }, theme: "dark" })
)
// Plugin priority stays in array order, and a theme string passes through.
assert.deepStrictEqual(RecordX.canonicalize(["formatter", "spellcheck"]), ["formatter", "spellcheck"])
assert.deepStrictEqual(RecordX.canonicalize("dark"), "dark")
Added in v0.0.0
unsafe
getOrThrow
Returns the value at key in record, throwing an Error if the key is absent.
Only own keys count, including symbols and keys with undefined values. The throwing counterpart to Record.get (which returns an Option). The thrown error names the missing key and lists the record’s existing keys to aid debugging. Reach for {@link getOrThrowWith} when you need a custom error; prefer Record.get whenever absence is a real possibility.
Signature
export declare const getOrThrow: (<K extends string | symbol>(key: K) => <V>(record: Record<K, V>) => V) &
(<K extends string | symbol, V>(record: Record<K, V>, key: K) => V)
Example
import { pipe } from "effect"
import { RecordX } from "@nunofyobiz/effect-extras"
const prices: Record<string, number> = { mug: 12, notebook: 8 }
// Read a price when the product is required to exist.
assert.deepStrictEqual(RecordX.getOrThrow(prices, "mug"), 12)
// The pipeable form retrieves the same price.
assert.deepStrictEqual(pipe(prices, RecordX.getOrThrow("mug")), 12)
// An unlisted product throws instead of silently returning undefined.
assert.throws(() => RecordX.getOrThrow(prices, "lamp"))
Added in v0.0.0
getOrThrowWith
Returns the value at key in record, throwing the result of onNone(key) if the key is absent.
Like {@link getOrThrow}, but lets the caller supply the thrown value (an Error, a string, or any custom failure) computed from the missing key. Use it when the default “key not found” message isn’t descriptive enough for the call site.
Signature
export declare const getOrThrowWith: (<K extends string | symbol>(
key: K,
onNone: (key: K) => unknown
) => <V>(record: Record<K, V>) => V) &
(<K extends string | symbol, V>(record: Record<K, V>, key: K, onNone: (key: K) => unknown) => V)
Example
import { pipe } from "effect"
import { RecordX } from "@nunofyobiz/effect-extras"
const prices: Record<string, number> = { mug: 12 }
const onNone = (key: string) => new Error(`No price listed for ${key}`)
// A listed price is returned without creating a failure.
assert.deepStrictEqual(RecordX.getOrThrowWith(prices, "mug", onNone), 12)
// The pipeable form reads the same price.
assert.deepStrictEqual(pipe(prices, RecordX.getOrThrowWith("mug", onNone)), 12)
// A missing product throws the caller's descriptive error.
assert.throws(() => RecordX.getOrThrowWith(prices, "lamp", onNone), /No price listed for lamp/)
Added in v0.0.0