shelving/util/transformmodule

Map and transform values across arrays, objects, dictionaries, and async sequences. These are higher-order utilities that apply a function to every element or property of a collection.

Things to know:

  • mapItems() is a generator — it yields lazily and does not produce an array. Use mapArray() when you need an ImmutableArray.
  • transformObject() returns the same reference when none of the transforms change a value, making it safe for equality checks and memoisation.
  • mapSequence() is for AsyncIterable streams; it is an async generator.

Usage

Arrays and iterables

ts
import { mapItems, mapArray } from "shelving/util";

const doubled = mapArray([1, 2, 3], x => x * 2); // [2, 4, 6]

// Lazy — does not allocate an array:
for (const v of mapItems([1, 2, 3], x => x * 2)) { ... }

Objects

ts
import { mapProps, transformObject } from "shelving/util";

// Map all property values through a transform.
mapProps({ a: 1, b: 2 }, ([, v]) => v * 10); // { a: 10, b: 20 }

// Selectively transform named properties; same ref returned if nothing changed.
const result = transformObject(
  { name: "dave", age: 30 },
  { name: s => s.toUpperCase() },
); // { name: "DAVE", age: 30 }

Dictionaries

ts
import { mapDictionary } from "shelving/util";

mapDictionary({ x: 1, y: 2 }, v => v + 100); // { x: 101, y: 102 }

Entries

ts
import { mapEntries, mapEntryValues } from "shelving/util";

// mapEntries passes the full [key, value] entry to the transform.
// mapEntryValues passes only the value.
const entries: [string, number][] = [["a", 1], ["b", 2]];
Array.from(mapEntryValues(entries, v => v * 2)); // [["a", 2], ["b", 4]]

Async sequences

ts
import { mapSequence } from "shelving/util";

async function* process(stream: AsyncIterable<string>) {
  yield* mapSequence(stream, line => line.trim());
}

Functions

Go

mapItems()function

Lazily transform every item in an iterable.

mapItems(items: Iterable<I>, transform: (v: I, ...args: A) => O, ...args: A): Iterable<O>
Go

mapArray()function

Transform every item of an iterable into a new array.

mapArray(arr: Iterable<I>, transform: (v: I, ...args: A) => O, ...args: A): ImmutableArray<O>
Go

mapProps()function

Transform the values of an object's props into a new object.

mapProps(obj: I, transform: (prop: Prop<I>, ...args: A) => Value<O>, ...args: A): O
Go

mapDictionary()function

Transform the values of a dictionary into a new dictionary.

mapDictionary(dictionary: ImmutableDictionary<I>, transform: (value: I, ...args: A) => O, ...args: A): ImmutableDictionary<O>
Go

mapEntries()function

Lazily transform the values of a set of entries, keeping each key.

mapEntries(entries: Iterable<Entry<K, I>>, transform: (entry: Entry<K, I>, ...args: A) => O, ...args: A): Iterable<Entry<K, O>>
Go

mapEntryValues()function

Lazily transform the values of a set of entries, keeping each key.

mapEntryValues(entries: Iterable<Entry<K, I>>, transform: (value: I, ...args: A) => O, ...args: A): Iterable<Entry<K, O>>
Go

transformObject()function

Transform an object using a set of named transforms.

transformObject(obj: T, transforms: Transforms<T, T | Partial<T>, A>, ...args: A): T
transformObject(obj: T | Partial<T>, transforms: Transforms<T, T | Partial<T>, A>, ...args: A): Partial<T>
transformObject(obj: I, transforms: Transforms<I, O | Partial<O>, A>, ...args: A): O
transformObject(obj: I | Partial<I>, transforms: Transforms<I, O | Partial<O>, A>, ...args: A): Partial<O>
Go

mapSequence()function

Lazily transform items in an async sequence as they are yielded.

mapSequence(sequence: AsyncIterable<I>, transform: (input: I, ...args: A) => O | PromiseLike<O>, ...args: A): AsyncIterable<O>

Types

Go

Transformstype

Set of named transforms for a data object, keyed by prop name (or undefined to skip the transform for that prop).

{
	readonly [K in keyof I]?: (input: I[K], ...args: A) => O[K];
}