Skip to main content

namespace Deep

undocumented

Interfaces

NameDescription
Deep.WithType<T>Typed and curried Deep API, used in situations where the target type is known but the value will be applied later.

Namespaces

NameDescription
MatchThe type to determine the allowed input values for the match function.
PatchA type to determine the allowed input type for the patch function.
Pathundocumented
SelectorType defining the allowed selectors on an object of type T. Selectors can be: - a path string into type T. - a function receiving a Protected version of type T, and returning an arbitrary value. - a tuple of Selectors for type T - an object where the property values are Selectors for type T.

Functions

getAt

Returns the value resulting from selecting the given path in the given source object. It supports optional chaining for nullable values or values that may be undefined, and also for accessing objects inside an array. There is currently no support for forcing non-null (the ! operator).

Definition

export declare function getAt<T, P extends Path.Get<T>>(source: T, path: P): Path.Result<T, P>;

Type parameters
NameDescription
Tthe object type to select in
Pa Path in object type T

Parameters

NameTypeDescription
sourceTthe object to select in
pathPthe path into the object
example
const value = { a: { b: { c: [{ d: 5 }, { d: 6 }] } } }
Deep.getAt(value, 'a.b');
// => { c: 5 }
Deep.getAt(value, 'a.b.c');
// => [{ d: 5 }, { d: 5 }]
Deep.getAt(value, 'a.b.c[1]');
// => { d: 6 }
Deep.getAt(value, 'a.b.c[1]?.d');
// => 6

getAtWith

Returns a function that gets the value at the given string path inside an object.

Definition

export declare function getAtWith<T, P extends Path.Get<T>>(path: P): (source: T) => Path.Result<T, P>;

Type parameters
NameDescription
Tthe input value type
Pthe string literal path type in the object

Parameters

NameTypeDescription
pathPthe string path in the object
example
const items = [{ a: { b:  1, c: 'a' } }, { a: { b: 2, c: 'b' } }];
items.map(Deep.getAtWith('a.c'));
// => ['a', 'b']

match

Returns true if the given value object matches the given matcher, false otherwise.

Definition

export declare function match<T, C extends Partial<T> = Partial<T>>(source: T, matcher: Match<T, C>, failureLog?: Match.FailureLog): boolean;

Type parameters
NameDescription
Tthe input value type
Cutility type

Parameters

NameTypeDescription
sourceTthe value to match (should be a plain object)
matcherMatch<T, C>a matcher object or a function taking the matcher API and returning a match object
failureLogMatch.FailureLog(optional) a string array that can be passed to collect reasons why the match failed
example
const input = { a: 1, b: { c: true, d: 'a' } }
match(input, { a: 1 }) // => true
match(input, { a: 2 }) // => false
match(input, { a: (v) => v > 10 }) // => false
match(input, { b: { c: true }}) // => true
match(input, (['every', { a: (v) => v > 0 }, { b: { c: true } }]) // => true
match(input, { b: { c: (v, parent, root) => v && parent.d.length > 0 && root.a > 0 } })
// => true

matchAt

Returns true if the given value object matches the given matcher at the given path, false otherwise.

Definition

export declare function matchAt<T, P extends Path.Get<T>>(source: T, path: P, matcher: Match<Path.Result<T, P>>): boolean;

Type parameters
NameDescription
Tthe input value type
Pthe string literal path type in the object

Parameters

NameTypeDescription
sourceTthe input value
pathPthe string path in the object
matcherMatch<Path.Result<T, P>>a matcher object or a function taking the matcher API and returning a match object
example
const input = { a: 1, b: { c: true, d: 'a' } }
Deep.matchAt(input, 'b', { c: true })
// => true

matchAtWith

Returns a function that matches a given value with the given matcher at the given string path.

Definition

export declare function matchAtWith<T, P extends Path.Get<T>, TE extends T = T>(path: P, matcher: Match<Path.Result<T & TE, P>>): (source: T) => boolean;

Type parameters
NameDescription
Tthe patch value type
Pthe string literal path type in the object
TEutility type

Parameters

NameTypeDescription
pathPthe string path in the object
matcherMatch<Path.Result<T & TE, P>>a matcher object that matches input values.
example
const items = [{ a: { b:  1, c: 'a' } }, { a: { b: 2, c: 'b' } }];
items.filter(Deep.matchAtWith('a.b', 2));
// => [{ a: 2, b: 'b' }]

matchWith

Returns a function that matches a given value with the given matcher.

Definition

export declare function matchWith<T>(matcher: Match<T>): (source: T) => boolean;

Type parameters
NameDescription
Tthe patch value type

Parameters

NameTypeDescription
matcherMatch<T>a matcher object that matches input values.
example
const items = [{ a: 1, b: 'a' }, { a: 2, b: 'b' }];
items.filter(Deep.matchWith({ a: 2 }));
// => [{ a: 2, b: 'b' }]

patch

Returns an immutably updated version of the given value where the given patchItems have been applied to the result. The Rimbu patch notation is as follows: - if the target is a simple value or array, the patch can be the same type or a function returning the same type - if the target is a tuple (array of fixed length), the patch be the same type or an object containing numeric keys with patches indicating the tuple index to patch - if the target is an object, the patch can be the same type, or an array containing partial keys with their patches for the object

Definition

export declare function patch<T, TE extends T = T, TT = T>(value: T, patchItem: Patch<TE, T & TT>): T;

Type parameters
NameDescription
Tthe type of the value to patch
TEa utility type
TTa utility type

Parameters

NameTypeDescription
valueTthe input value to patch
patchItemPatch<TE, T & TT>the Patch value to apply to the input value
example
const input = { a: 1, b: { c: true, d: 'a' } }
patch(input, [{ a: 2 }]) // => { a: 2, b: { c: true, d: 'a' } }
patch(input, [{ b: [{ c: (v) => !v }] }] )
// => { a: 1, b: { c: false, d: 'a' } }
patch(input: [{ a: (v) => v + 1, b: [{ d: 'q' }] }] )
// => { a: 2, b: { c: true, d: 'q' } }

patchAt

Patches the value at the given path in the source to the given value. Because the path to update must exist in the source object, optional chaining and array indexing is not allowed.

Definition

export declare function patchAt<T, P extends Path.Set<T>, C = Path.Result<T, P>>(source: T, path: P, patchItem: Patch<Path.Result<T, P>, Path.Result<T, P> & C>): T;

Type parameters
NameDescription
T
P
C

Parameters

NameTypeDescription
sourceTthe object to update
pathPthe path in the object to update
patchItemPatch<Path.Result<T, P>, Path.Result<T, P> & C>the patch for the value at the given path
example
const value = { a: { b: { c: 5 } } };
Deep.patchAt(value, 'a.b.c', v => v + 5);
// => { a: { b: { c: 6 } } }

patchAtWith

Returns a function that patches a given value with the given patchItems at the given path.

Definition

export declare function patchAtWith<T, P extends Path.Set<T>, TE extends T = T, TT = T>(path: P, patchItem: Patch<Path.Result<TE, P>, Path.Result<TT, P>>): (source: T) => T;

Type parameters
NameDescription
Tthe patch value type
Pthe string literal path type in the object
TEutility type
TTutility type

Parameters

NameTypeDescription
pathPthe string path in the object
patchItemPatch<Path.Result<TE, P>, Path.Result<TT, P>>the Patch definition to update the value at the given path in T with.
example
const items = [{ a: { b:  1, c: 'a' } }, { a: { b: 2, c: 'b' } }];
items.map(Deep.patchAtWith('a', [{ b: (v) => v + 1 }]));
// => [{ a: { b: 2, c: 'a' } }, { a: { b: 3, c: 'b' } }]

patchWith

Returns a function that patches a given source with the given patchItems.

Definition

export declare function patchWith<T, TE extends T = T, TT = T>(patchItem: Patch<TT, TE>): (source: TE) => T;

Type parameters
NameDescription
Tthe patch value type
TEutility type
TTutility type

Parameters

NameTypeDescription
patchItemPatch<TT, TE>the Patch definition to update the given value of type T with.
example
const items = [{ a: 1, b: 'a' }, { a: 2, b: 'b' }];
items.map(Deep.patchWith([{ a: v => v + 1 }]));
// => [{ a: 2, b: 'a' }, { a: 3, b: 'b' }]

protect

Returns the same value wrapped in the Protected type.

Definition

export declare function protect<T>(source: T): Protected<T>;

Type parameters
NameDescription
Tthe source value type

Parameters

NameTypeDescription
sourceTthe value to wrap
note

does not perform any runtime protection, it is only a utility to easily add the Protected type to a value

example
const obj = Deep.protect({ a: 1, b: { c: true, d: [1] } })
obj.a = 2 // compiler error: a is readonly
obj.b.c = false // compiler error: c is readonly
obj.b.d.push(2) // compiler error: d is a readonly array
(obj as any).b.d.push(2) // will actually mutate the object

select

Returns the result of applying the given selector shape to the given source value.

Definition

export declare function select<T, SL extends Selector<T>>(source: T, selector: Selector.Shape<SL>): Selector.Result<T, SL>;

Type parameters
NameDescription
Tthe patch value type
SLthe selector shape type

Parameters

NameTypeDescription
sourceTthe source value to select from
selectorSelector.Shape<SL>a shape indicating the selection from the source values
example
const item = { a: { b:  1, c: 'a' } };
Deep.select(item, { q: 'a.c', y: ['a.b', 'a.c'], z: (v) => v.a.b + 1 });
// => { q: 'a', y: [1, 'a'], z: 2 }

selectAt

Returns the result of applying the given selector shape to the given source value.

Definition

export declare function selectAt<T, P extends Path.Get<T>, SL extends Selector<Path.Result<T, P>>>(source: T, path: P, selector: Selector.Shape<SL>): Selector.Result<Path.Result<T, P>, SL>;

Type parameters
NameDescription
Tthe patch value type
Pthe string literal path type in the object
SLthe selector shape type

Parameters

NameTypeDescription
sourceTthe source value to select from
pathPthe string path in the object
selectorSelector.Shape<SL>a shape indicating the selection from the source value at the given path
example
const item = { a: { b:  1, c: 'a' } };
Deep.selectAt(item, 'a', { q: 'c', z: ['b', v => v.b + 1] as const });
// => { q: 'a', z: [1, 2] }

selectAtWith

Returns a function that selects a certain shape from a given value with the given selector at the given string path.

Definition

export declare function selectAtWith<T, P extends Path.Get<T>, SL extends Selector<Path.Result<T, P>>>(path: P, selector: Selector.Shape<SL>): (source: T) => Selector.Result<Path.Result<T, P>, SL>;

Type parameters
NameDescription
Tthe patch value type
Pthe string literal path type in the object
SLthe selector shape type

Parameters

NameTypeDescription
pathPthe string path in the object
selectorSelector.Shape<SL>a shape indicating the selection from the source values
example
const items = [{ a: { b:  1, c: 'a' } }, { a: { b: 2, c: 'b' } }];
items.map(Deep.selectAtWith('a', { q: 'c', z: ['b', v => v.b + 1] as const }));
// => [{ q: 'a', z: [1, 2] }, { q: 'b', z: [2, 3] }]

selectWith

Returns a function that selects a certain shape from a given value with the given selector.

Definition

export declare function selectWith<T, SL extends Selector<T>>(selector: Selector.Shape<SL>): (source: T) => Selector.Result<T, SL>;

Type parameters
NameDescription
Tthe patch value type
SLthe selector shape type

Parameters

NameTypeDescription
selectorSelector.Shape<SL>a shape indicating the selection from the source values
example
const items = [{ a: { b:  1, c: 'a' } }, { a: { b: 2, c: 'b' } }];
items.map(Deep.selectWith({ q: 'a.c', z: ['a.b', v => v.a.b + 1] as const }));
// => [{ q: 'a', z: [1, 2] }, { q: 'b', z: [2, 3] }]

withType

Returns a curried API with a known target type. This can be useful for using the methods in contexts where the target type can be inferred from the usage.

Definition

export declare function withType<T>(): WithType<T>;

Type parameters
NameDescription
Tthe target type
example
const s = { a: 1, b: { c: 'a', d: true }}
const upd = Deep.withType<typeof s>().patchWith([{ d: (v) => !v }])
upd(s)
// => { a: 1, b: { c: 'a', d: false }}