shelving 1.22.2 → 1.23.0

package/transform/DataTransform.js

@@ -1,4 +1,4 @@
-import { deriveData } from "../util/index.js";
+import { transformData } from "../util/index.js";
 import { Transform } from "./Transform.js";
 /** Set of transforms that can be appled to an object's properties. */
 export class DataTransform extends Transform {
@@ -6,8 +6,8 @@ export class DataTransform extends Transform {
         super();
         this.transforms = transforms;
     }
-    derive(existing) {
-        return deriveData(existing, this.transforms);
+    transform(existing) {
+        return transformData(existing, this.transforms);
     }
     /** Return a new object with the specified additional transform. */
     prop(key, transform) {

package/transform/IncrementTransform.d.ts

@@ -8,5 +8,5 @@ export declare class IncrementTransform extends Transform<number> {
     static DECREMENT_ONE: IncrementTransform;
     readonly amount: number;
     constructor(amount: number);
-    derive(existing?: unknown): number;
+    transform(existing?: unknown): number;
 }

package/transform/IncrementTransform.js

@@ -8,7 +8,7 @@ export class IncrementTransform extends Transform {
         super();
         this.amount = amount;
     }
-    derive(existing) {
+    transform(existing) {
         return typeof existing === "number" ? existing + this.amount : this.amount;
     }
 }

package/transform/RemoveEntriesTransform.d.ts

@@ -4,7 +4,7 @@ import { Transform } from "./Transform.js";
 export declare class RemoveEntriesTransform<T> extends Transform<ImmutableObject<T>> implements Iterable<string> {
     readonly props: ImmutableArray<string>;
     constructor(...props: ImmutableArray<string>);
-    derive(existing?: unknown): ImmutableObject<T>;
+    transform(existing?: unknown): ImmutableObject<T>;
     /** Iterate over the entry keys. */
     [Symbol.iterator](): Iterator<string, void>;
 }

package/transform/RemoveEntriesTransform.js

@@ -6,7 +6,7 @@ export class RemoveEntriesTransform extends Transform {
         super();
         this.props = props;
     }
-    derive(existing) {
+    transform(existing) {
         return isObject(existing) ? withoutEntries(existing, this.props) : {};
     }
     /** Iterate over the entry keys. */

package/transform/RemoveItemsTransform.d.ts

@@ -4,7 +4,7 @@ import { Transform } from "./Transform.js";
 export declare class RemoveItemsTransform<T> extends Transform<ImmutableArray<T>> implements Iterable<T> {
     readonly items: ImmutableArray<T>;
     constructor(...items: ImmutableArray<T>);
-    derive(existing?: ImmutableArray<T> | unknown): ImmutableArray<T>;
+    transform(existing?: ImmutableArray<T> | unknown): ImmutableArray<T>;
     /** Iterate over the items. */
     [Symbol.iterator](): Iterator<T, void>;
 }

package/transform/RemoveItemsTransform.js

@@ -6,7 +6,7 @@ export class RemoveItemsTransform extends Transform {
         super();
         this.items = items;
     }
-    derive(existing) {
+    transform(existing) {
         return isArray(existing) ? withoutItems(existing, this.items) : this.items;
     }
     /** Iterate over the items. */

package/transform/Transform.d.ts

@@ -1,9 +1,9 @@
-import { Derivable } from "../util/index.js";
+import { Transformable } from "../util/index.js";
 /**
  * An object that transforms an existing value value into a new value with its `transform()` method.
  * - Probably has a configuration that accompanies it.
  */
-export declare abstract class Transform<T> implements Derivable<T, T> {
+export declare abstract class Transform<T> implements Transformable<T, T> {
     /** Apply this transform to a value. */
-    abstract derive(existing?: unknown): T;
+    abstract transform(existing?: unknown): T;
 }

package/transform/hydrations.d.ts

@@ -11,5 +11,5 @@ export declare const TRANSFORM_HYDRATIONS: {
     removeItems: typeof RemoveItemsTransform;
     addEntries: typeof AddEntriesTransform;
     removeEntries: typeof RemoveEntriesTransform;
-    transforms: typeof DataTransform;
+    transformData: typeof DataTransform;
 };

package/transform/hydrations.js

@@ -11,6 +11,6 @@ export const TRANSFORM_HYDRATIONS = {
     removeItems: RemoveItemsTransform,
     addEntries: AddEntriesTransform,
     removeEntries: RemoveEntriesTransform,
-    transforms: DataTransform,
+    transformData: DataTransform,
 };
 TRANSFORM_HYDRATIONS;

package/transform/util.js

@@ -2,7 +2,7 @@ import { Feedback } from "../feedback/Feedback.js";
 import { InvalidFeedback } from "../feedback/InvalidFeedback.js";
 import { DataSchema } from "../schema/DataSchema.js";
 import { DataTransform, Transform } from "../transform/index.js";
-import { derive, validate, toProps } from "../util/index.js";
+import { transform, validate, toProps } from "../util/index.js";
 /** Validate a transform against a validator. */
 export function validateTransform(unsafeTransform, validator) {
     if (validator instanceof DataSchema && unsafeTransform instanceof DataTransform) {
@@ -11,7 +11,7 @@ export function validateTransform(unsafeTransform, validator) {
         return safeTransforms === unsafeTransforms ? unsafeTransform : new DataTransform(safeTransforms);
     }
     else {
-        validate(derive(undefined, unsafeTransform), validator);
+        validate(transform(undefined, unsafeTransform), validator);
         return unsafeTransform;
     }
 }

package/util/clone.js

@@ -1,6 +1,6 @@
 import { isArray } from "./array.js";
 import { isObject } from "./object.js";
-import { deriveArray, deriveObject } from "./derive.js";
+import { transformArray, transformObject } from "./transform.js";
 /** Does an object implement `Cloneable` */
 export const isCloneable = (v) => isObject(v) && typeof v.cloneable === "function";
 /** Shallow clone a value. */
@@ -19,7 +19,7 @@ export function deepClone(value, recursor = deepClone) {
 export function cloneArray(input, recursor = shallowClone) {
     if (isCloneable(input))
         return input.clone();
-    const output = deriveArray(input, recursor);
+    const output = transformArray(input, recursor);
     Object.setPrototypeOf(output, Object.getPrototypeOf(input));
     return output;
 }
@@ -27,7 +27,7 @@ export function cloneArray(input, recursor = shallowClone) {
 export function cloneObject(input, recursor = shallowClone) {
     if (isCloneable(input))
         return input.clone();
-    const output = deriveObject(input, recursor);
+    const output = transformObject(input, recursor);
     Object.setPrototypeOf(input, Object.getPrototypeOf(input));
     return output;
 }

package/util/filter.d.ts

@@ -2,7 +2,7 @@ import type { ImmutableArray } from "./array.js";
 import type { ImmutableMap } from "./map.js";
 import { Entry } from "./entry.js";
 import { ImmutableObject } from "./object.js";
-import { Deriver } from "./derive.js";
+import { Transformer } from "./transform.js";
 /** Object that can match an item against a target with its `match()` function. */
 export interface Matchable<L, R> {
     match(item: L, target: R): boolean;
@@ -52,9 +52,9 @@ export declare function filterObject<L, R>(object: ImmutableObject<L>, matcher:
 export declare function filterMap<L>(input: ImmutableMap<L>, matcher: Matcher<Entry<L>, void>): ImmutableMap<L>;
 export declare function filterMap<L, R>(input: ImmutableMap<L>, matcher: Matcher<Entry<L>, R>, target: R): ImmutableMap<L>;
 /** Derive a value and match it against a target value. */
-export declare class MatchDerived<L, LL, R> implements Matchable<L, R> {
-    private _deriver;
+export declare class TransformMatcher<L, LL, R> implements Matchable<L, R> {
+    private _transformer;
     private _matcher;
-    constructor(deriver: Deriver<L, LL>, matcher?: Matcher<LL, R>);
+    constructor(transformer: Transformer<L, LL>, matcher?: Matcher<LL, R>);
     match(item: L, target: R): boolean;
 }

package/util/filter.js

@@ -1,5 +1,5 @@
 import { ASC } from "./sort.js";
-import { derive } from "./derive.js";
+import { transform } from "./transform.js";
 export function match(item, matcher, target) {
     return typeof matcher === "function" ? matcher(item, target) : matcher.match(item, target);
 }
@@ -51,12 +51,12 @@ export function filterMap(input, matcher, target) {
     return output.size === input.size ? input : output;
 }
 /** Derive a value and match it against a target value. */
-export class MatchDerived {
-    constructor(deriver, matcher = IS) {
-        this._deriver = deriver;
+export class TransformMatcher {
+    constructor(transformer, matcher = IS) {
+        this._transformer = transformer;
         this._matcher = matcher;
     }
     match(item, target) {
-        return match(derive(item, this._deriver), this._matcher, target);
+        return match(transform(item, this._transformer), this._matcher, target);
     }
 }

package/util/hydrate.d.ts

@@ -1,6 +1,6 @@
 import type { Class } from "./class.js";
 import { Data } from "./data.js";
-import { Derivable } from "./derive.js";
+import { Transformable } from "./transform.js";
 import { ImmutableObject } from "./object.js";
 /**
  * A set of hydrations describes a set of string keys and the class constructor to be dehydrated and rehydrated.
@@ -30,15 +30,15 @@ export declare function hydrate(value: unknown, hydrations: Hydrations): unknown
 export declare type DehydratedObject<T extends Data> = T & {
     readonly _type: string;
 };
-/** Deriver that hydrates a value with a set of hydrations. */
-export declare class Hydrator implements Derivable<unknown, unknown> {
+/** Hydrates a value with a set of hydrations. */
+export declare class Hydrator implements Transformable<unknown, unknown> {
     private _hydrations;
     constructor(hydrations: Hydrations);
-    derive(value: unknown): unknown;
+    transform(value: unknown): unknown;
 }
-/** Deriver that dehydrates a value with a set of hydrations. */
-export declare class Dehydrator implements Derivable<unknown, unknown> {
+/** Dehydrates a value with a set of hydrations. */
+export declare class Dehydrator implements Transformable<unknown, unknown> {
     private _hydrations;
     constructor(hydrations: Hydrations);
-    derive(value: unknown): unknown;
+    transform(value: unknown): unknown;
 }

package/util/hydrate.js

@@ -1,6 +1,6 @@
 import { AssertionError } from "../error/index.js";
 import { isData } from "./data.js";
-import { deriveArray, deriveObject } from "./derive.js";
+import { transformArray, transformObject } from "./transform.js";
 import { isPlainObject } from "./object.js";
 /**
  * Deeply dehydrate a class instance based on a set of `Hydrations`
@@ -13,7 +13,7 @@ import { isPlainObject } from "./object.js";
  * @throws `Error` if the value is a class instance that cannot be dehydrated (i.e. is not matched by any constructor in `hydrations`).
  */
 export function dehydrate(value, hydrations) {
-    return new Dehydrator(hydrations).derive(value);
+    return new Dehydrator(hydrations).transform(value);
 }
 /**
  * Deeply hydrate a class instance based on a set of `Hydrations`
@@ -23,44 +23,44 @@ export function dehydrate(value, hydrations) {
  * - Note: the recursion in this function does not currently protect against infinite loops.
  */
 export function hydrate(value, hydrations) {
-    return new Hydrator(hydrations).derive(value);
+    return new Hydrator(hydrations).transform(value);
 }
 /** Is an unknown value a dehydrated object with a `_type` key. */
 const isDehydrated = (v) => typeof v._type === "string";
-/** Deriver that hydrates a value with a set of hydrations. */
+/** Hydrates a value with a set of hydrations. */
 export class Hydrator {
     constructor(hydrations) {
         this._hydrations = hydrations;
     }
-    derive(value) {
+    transform(value) {
         if (value instanceof Array)
-            return deriveArray(value, this);
+            return transformArray(value, this);
         if (isPlainObject(value)) {
             if (!isDehydrated(value))
-                return deriveObject(value, this);
+                return transformObject(value, this);
             const { _type, ...props } = value;
             const hydration = this._hydrations[_type];
             if (hydration)
-                return { __proto__: hydration.prototype, ...deriveObject(props, this) };
+                return { __proto__: hydration.prototype, ...transformObject(props, this) };
             throw new AssertionError(`Cannot hydrate "${_type}" object`, value);
         }
         return value;
     }
 }
-/** Deriver that dehydrates a value with a set of hydrations. */
+/** Dehydrates a value with a set of hydrations. */
 export class Dehydrator {
     constructor(hydrations) {
         this._hydrations = hydrations;
     }
-    derive(value) {
+    transform(value) {
         if (value instanceof Array)
-            return deriveArray(value, this);
+            return transformArray(value, this);
         if (isPlainObject(value))
-            return deriveObject(value, this);
+            return transformObject(value, this);
         if (isData(value)) {
             for (const [_type, hydration] of Object.entries(this._hydrations))
                 if (value instanceof hydration)
-                    return { _type, ...deriveObject(value, this) };
+                    return { _type, ...transformObject(value, this) };
             throw new AssertionError(`Cannot dehydrate object`, value);
         }
         return value;

package/util/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./array.js";
 export * from "./assert.js";
+export * from "./async.js";
 export * from "./boolean.js";
 export * from "./class.js";
 export * from "./clone.js";
@@ -7,7 +8,6 @@ export * from "./constants.js";
 export * from "./data.js";
 export * from "./date.js";
 export * from "./debug.js";
-export * from "./derive.js";
 export * from "./diff.js";
 export * from "./entry.js";
 export * from "./equal.js";
@@ -23,13 +23,13 @@ export * from "./null.js";
 export * from "./number.js";
 export * from "./object.js";
 export * from "./observable.js";
-export * from "./async.js";
 export * from "./random.js";
 export * from "./search.js";
 export * from "./serialise.js";
 export * from "./sort.js";
 export * from "./string.js";
 export * from "./template.js";
+export * from "./transform.js";
 export * from "./undefined.js";
 export * from "./units.js";
 export * from "./url.js";

package/util/index.js

@@ -1,5 +1,6 @@
 export * from "./array.js";
 export * from "./assert.js";
+export * from "./async.js";
 export * from "./boolean.js";
 export * from "./class.js";
 export * from "./clone.js";
@@ -7,7 +8,6 @@ export * from "./constants.js";
 export * from "./data.js";
 export * from "./date.js";
 export * from "./debug.js";
-export * from "./derive.js";
 export * from "./diff.js";
 export * from "./entry.js";
 export * from "./equal.js";
@@ -23,13 +23,13 @@ export * from "./null.js";
 export * from "./number.js";
 export * from "./object.js";
 export * from "./observable.js";
-export * from "./async.js";
 export * from "./random.js";
 export * from "./search.js";
 export * from "./serialise.js";
 export * from "./sort.js";
 export * from "./string.js";
 export * from "./template.js";
+export * from "./transform.js";
 export * from "./undefined.js";
 export * from "./units.js";
 export * from "./url.js";

package/util/observable.d.ts

@@ -1,6 +1,6 @@
 import { Dispatcher } from "./function.js";
 import { Handler } from "./error.js";
-import { Deriver } from "./derive.js";
+import { Transformer } from "./transform.js";
 import { Validator } from "./validate.js";
 /** Function that ends a subscription. */
 export declare type Unsubscriber = () => void;
@@ -78,10 +78,10 @@ export declare class ThroughObserver<T> extends AbstractObserver<T, T> {
 export declare class OnceObserver<T> extends ThroughObserver<T> {
     next(value: T): void;
 }
-/** Oserver that derives its next values with a deriver. */
-export declare class DeriveObserver<I, O> extends AbstractObserver<I, O> {
-    protected _deriver: Deriver<I, O>;
-    constructor(deriver: Deriver<I, O>, target: Observer<O>);
+/** Oserver that transforms its next values with a transformer. */
+export declare class TransformObserver<I, O> extends AbstractObserver<I, O> {
+    protected _transformer: Transformer<I, O>;
+    constructor(transformer: Transformer<I, O>, target: Observer<O>);
     next(value: I): void;
 }
 /** Observer that validates its next values with a validator. */

package/util/observable.js

@@ -2,7 +2,7 @@ import { ConditionError } from "../error/index.js";
 import { BLACKHOLE, dispatch } from "./function.js";
 import { logError } from "./error.js";
 import { isData } from "./data.js";
-import { derive } from "./derive.js";
+import { transform } from "./transform.js";
 import { validate } from "./validate.js";
 /** Is an unknown object an object implementing `Observable` */
 export const isObservable = (v) => isData(v) && typeof v.subscribe === "function";
@@ -103,17 +103,17 @@ export class OnceObserver extends ThroughObserver {
         this.complete();
     }
 }
-/** Oserver that derives its next values with a deriver. */
-export class DeriveObserver extends AbstractObserver {
-    constructor(deriver, target) {
+/** Oserver that transforms its next values with a transformer. */
+export class TransformObserver extends AbstractObserver {
+    constructor(transformer, target) {
         super(target);
-        this._deriver = deriver;
+        this._transformer = transformer;
     }
     next(value) {
         const target = this._target;
         if (!target)
             throw new ConditionError("Observer is closed");
-        dispatchNext(target, derive(value, this._deriver));
+        dispatchNext(target, transform(value, this._transformer));
     }
 }
 /** Observer that validates its next values with a validator. */

package/util/sort.d.ts

@@ -2,7 +2,7 @@ import { ImmutableObject } from "./object.js";
 import { ImmutableMap } from "./map.js";
 import type { Entry } from "./entry.js";
 import { ImmutableArray } from "./array.js";
-import { Deriver } from "./derive.js";
+import { Transformer } from "./transform.js";
 /** Object that can rank two values using its `rank()` function. */
 export interface Rankable<T> {
     rank(left: T, right: T): number;
@@ -53,9 +53,9 @@ export declare function sortObject<T>(input: ImmutableObject<T>, ranker?: Ranker
 /** Sort a map using a ranker (defaults to sorting by key in ascending order). */
 export declare function sortMap<T>(input: ImmutableMap<T>, ranker?: Ranker<Entry<T>>): ImmutableMap<T>;
 /** Derive a value and match it against a target value. */
-export declare class RankDerived<T, TT> implements Rankable<T> {
-    private _deriver;
+export declare class TransformRanker<T, TT> implements Rankable<T> {
+    private _transformer;
     private _ranker;
-    constructor(deriver: Deriver<T, TT>, ranker?: Ranker<TT>);
+    constructor(transformer: Transformer<T, TT>, ranker?: Ranker<TT>);
     rank(left: T, right: T): number;
 }

package/util/sort.js

@@ -1,4 +1,4 @@
-import { derive } from "./derive.js";
+import { transform } from "./transform.js";
 /** Rank two values with a `Ranker`. */
 export function rank(left, ranker, right) {
     return typeof ranker === "function" ? ranker(left, right) : ranker.rank(left, right);
@@ -90,7 +90,6 @@ export const VALUE_DESC = ([, l], [, r]) => DESC(l, r);
  *
  * @param items The actual list of items that's sorted in place.
  * @param ranker A rank function that takes a left/right value and returns 1/0/-1 (like `Array.prototype.sort()`).
- * @param deriver A deriving function that picks the specific value to sort from out of the full value.
  * @param leftPointer Index in the set of items to start sorting on.
  * @param rightPointer Index in the set of items to stop sorting on.
  *
@@ -161,12 +160,12 @@ export function sortMap(input, ranker = KEY_ASC) {
     return _quicksort(array, ranker) ? new Map(array) : input;
 }
 /** Derive a value and match it against a target value. */
-export class RankDerived {
-    constructor(deriver, ranker = ASC) {
-        this._deriver = deriver;
+export class TransformRanker {
+    constructor(transformer, ranker = ASC) {
+        this._transformer = transformer;
         this._ranker = ranker;
     }
     rank(left, right) {
-        return rank(derive(left, this._deriver), this._ranker, derive(right, this._deriver));
+        return rank(transform(left, this._transformer), this._ranker, transform(right, this._transformer));
     }
 }

package/util/transform.d.ts

@@ -0,0 +1,88 @@
+import type { Entry } from "./entry.js";
+import type { ArrayType, ImmutableArray } from "./array.js";
+import type { ImmutableMap } from "./map.js";
+import { ImmutableObject } from "./object.js";
+import { Data, Value, Prop } from "./data.js";
+/** Object that can be applied to an input to generate an output with its `apply()` method. */
+export interface Transformable<I, O> {
+    transform(input: I): O;
+}
+/** Any applier (useful for `extends AnyTransformr` clauses). */
+export declare type AnyTransformable = Transformable<any, any>;
+/** Function that takes an input value and returns a value transformed from it, or an applier with matching arguments. */
+export declare type Transformer<I, O> = Transformable<I, O> | ((input: I) => O) | O;
+/** Any transformer (useful for `extends AnyTransformr` clauses). */
+export declare type AnyTransformer = Transformer<any, any>;
+/** Extract the transformed type from a transformer. */
+export declare type TransformedType<T extends AnyTransformer> = T extends Transformer<unknown, infer TT> ? TT : never;
+/** Is an unknown value a transformer. */
+export declare const isTransformer: <T extends unknown>(v: unknown) => v is T;
+/** Is an unknown value a derivable. */
+export declare const isTransformable: <T extends AnyTransformable>(v: unknown) => v is T;
+/** Transform a value using a transformer. */
+export declare function transform<I, O>(input: I, transformer: (v: I) => O): O;
+export declare function transform<I, O>(input: I, transformer: Transformer<I, O>): O;
+/**
+ * Apply a transformer to each item in a set of items and yield the transformed item.
+ *
+ * @yield Transformed items after calling `transformer()` on each.
+ * @returns Number of items that changed.
+ */
+export declare function transformItems<I, O>(items: Iterable<I>, transformer: (input: I) => O): Iterable<O>;
+export declare function transformItems<I, O>(items: Iterable<I>, transformer: Transformer<I, O>): Iterable<O>;
+/**
+ * Apply a transformer to each item in an array and return the transformed array.
+ *
+ * @param arr The input array or map-like object or iterable to iterate over.
+ * @param mapper Mapping function that receives the value and key and returns the corresponding value.
+ * - Mapper can return a promise. If it does will return a Promise that resolves once every value has resolved.
+ * - Return the `SKIP` symbol from the mapper to skip that property and not include it in the output object.
+ * - `SKIP` is useful because using `filter(Boolean)` doesn't currently filter in TypeScript (and requires another loop anyway).
+ * - Mapper can be a non-function static value and all the values will be set to that value.
+ *
+ * @return The mapped array.
+ * - Immutable so if the values don't change then the same instance will be returned.
+ */
+export declare function transformArray<T extends ImmutableArray>(arr: T, transformer: Transformer<ArrayType<T>, ArrayType<T>>): T;
+export declare function transformArray<I, O>(arr: Iterable<I>, transformer: (v: I) => O): ImmutableArray<O>;
+export declare function transformArray<I, O>(arr: Iterable<I>, transformer: Transformer<I, O>): ImmutableArray<O>;
+/**
+ * Transform the _values_ of a set of entries using a transformer.
+ * @yield Transformed entry after calling transforming the new value for each entry.
+ */
+export declare function transformValues<I, O>(entries: Iterable<Entry<I>>, transformer: (v: I) => O): Iterable<Entry<O>>;
+export declare function transformValues<I, O>(entries: Iterable<Entry<I>>, transformer: Transformer<I, O>): Iterable<Entry<O>>;
+/**
+ * Transform the _values_ of a map using a transformer.
+ * @return New map after transforming its values.
+ */
+export declare function transformMap<I, O>(map: ImmutableMap<I>, transformer: (v: I) => O): ImmutableMap<O>;
+export declare function transformMap<I, O>(map: ImmutableMap<I>, transformer: Transformer<I, O>): ImmutableMap<O>;
+/**
+ * Transform the _values_ of an object using a transformer.
+ * @return New object after transforming its entries.
+ */
+export declare function transformObject<T extends Data>(obj: T, transformer: Transformer<Value<T>, Value<T>>): T;
+export declare function transformObject<I extends Data, O extends {
+    [K in keyof I]: unknown;
+}>(obj: I, transformer: Transformer<Value<I>, Value<O>>): O;
+export declare function transformObject<I, O>(obj: ImmutableObject<I>, transformer: (v: I) => O): ImmutableObject<O>;
+export declare function transformObject<I, O>(obj: ImmutableObject<I>, transformer: Transformer<I, O>): ImmutableObject<O>;
+/** Set of named transformers for a data object. */
+export declare type Transformers<T extends Data> = {
+    readonly [K in keyof T]?: Transformer<T[K], T[K]>;
+};
+/** Complete set of named transformers for a data object (i.e. every prop has a transformer specified). */
+export declare type RequiredTransformers<T extends Data> = {
+    readonly [K in keyof T]: Transformer<T[K], T[K]>;
+};
+/**
+ * Transform the props of a data object using a set of transforms.
+ * @yields Valid new prop entries for the data object (only changed values are yielded).
+ */
+export declare function transformProps<T extends Data>(existing: T, transformers: Transformers<T>): Generator<Prop<T>, void>;
+/**
+ * Transform a new data object using a set of transformers for its props.
+ * @returns New object with changed props (or the same object if no changes were made).
+ */
+export declare function transformData<T extends Data>(existing: T, transformers: Transformers<T>): T;

package/util/transform.js

@@ -0,0 +1,48 @@
+import { isFunction } from "./function.js";
+import { toProps, isData } from "./data.js";
+import { WatchIterator } from "./iterate.js";
+/** Is an unknown value a transformer. */
+export const isTransformer = (v) => typeof v === "function" || isTransformable(v);
+/** Is an unknown value a derivable. */
+export const isTransformable = (v) => isData(v) && typeof v.transform === "function";
+export function transform(input, transformer) {
+    return isFunction(transformer) ? transformer(input) : isTransformable(transformer) ? transformer.transform(input) : transformer;
+}
+export function* transformItems(items, transformer) {
+    for (const item of items)
+        yield transform(item, transformer);
+}
+export function transformArray(arr, transformer) {
+    return Array.from(transformItems(arr, transformer));
+}
+export function* transformValues(entries, transformer) {
+    for (const [k, v] of entries)
+        yield [k, transform(v, transformer)];
+}
+export function transformMap(map, transformer) {
+    return new Map(transformValues(map, transformer));
+}
+export function transformObject(obj, transformer) {
+    return Object.fromEntries(transformValues(Object.entries(obj), transformer));
+}
+/**
+ * Transform the props of a data object using a set of transforms.
+ * @yields Valid new prop entries for the data object (only changed values are yielded).
+ */
+export function* transformProps(existing, transformers) {
+    for (const [k, v] of toProps(transformers)) {
+        const current = existing[k];
+        const transformed = transform(current, v);
+        if (transformed !== current)
+            yield [k, transformed];
+    }
+}
+/**
+ * Transform a new data object using a set of transformers for its props.
+ * @returns New object with changed props (or the same object if no changes were made).
+ */
+export function transformData(existing, transformers) {
+    const watcher = new WatchIterator(transformProps(existing, transformers));
+    const transformed = Object.fromEntries(watcher);
+    return watcher.count ? { ...existing, ...transformed } : existing;
+}