shelving 1.84.2 → 1.85.0

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.84.2",
+	"version": "1.85.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -65,25 +65,25 @@
 	},
 	"devDependencies": {
 		"@google-cloud/firestore": "^5.0.2",
-		"@types/jest": "^28.1.7",
-		"@types/react": "^18.0.17",
+		"@types/jest": "^28.1.8",
+		"@types/react": "^18.0.21",
 		"@types/react-dom": "^18.0.4",
-		"@typescript-eslint/eslint-plugin": "^5.33.1",
-		"@typescript-eslint/parser": "^5.33.1",
+		"@typescript-eslint/eslint-plugin": "^5.39.0",
+		"@typescript-eslint/parser": "^5.39.0",
 		"dpdm": "^3.9.0",
-		"esbuild": "^0.15.7",
+		"esbuild": "^0.15.10",
 		"esbuild-jest": "^0.5.0",
-		"eslint": "^8.22.0",
+		"eslint": "^8.25.0",
 		"eslint-config-prettier": "^8.5.0",
 		"eslint-plugin-import": "^2.26.0",
 		"eslint-plugin-prettier": "^4.0.0",
-		"firebase": "^9.9.3",
+		"firebase": "^9.11.0",
 		"jest": "^28.1.0",
 		"jest-ts-webcompat-resolver": "^1.0.0",
 		"prettier": "^2.6.2",
 		"react": "^18.1.0",
 		"react-dom": "^18.1.0",
-		"typescript": "^4.6.4"
+		"typescript": "^4.8.4"
 	},
 	"peerDependencies": {
 		"@google-cloud/firestore": ">=4.0.0",

package/react/useItem.js

@@ -15,7 +15,7 @@ export class ItemState extends State {
         const table = (_a = getOptionalSource(CacheProvider, db.provider)) === null || _a === void 0 ? void 0 : _a.memory.getTable(collection);
         const time = table ? table.getItemTime(id) : null;
         const isCached = typeof time === "number";
-        super(table && isCached ? table.getItem(id) : State.NOVALUE, table ? new LazyDeferredSequence(() => this.connect(table.getCachedItemSequence(id))) : undefined);
+        super(table && isCached ? table.getItem(id) : State.NOVALUE, table ? new LazyDeferredSequence(() => this.from(table.getCachedItemSequence(id))) : undefined);
         this.busy = new BooleanState();
         /** Refresh this state from the source provider. */
         this.refresh = () => {
@@ -55,7 +55,7 @@ export class ItemState extends State {
     }
     /** Subscribe this state to the source provider. */
     connectSource() {
-        return this.connect(this.ref);
+        return this.from(this.ref);
     }
 }
 export function useItem(ref) {

package/react/useQuery.js

@@ -15,7 +15,7 @@ export class QueryState extends State {
         const table = (_a = getOptionalSource(CacheProvider, db.provider)) === null || _a === void 0 ? void 0 : _a.memory.getTable(collection);
         const time = table ? table.getQueryTime(ref) : null;
         const isCached = typeof time === "number";
-        super(table && isCached ? table.getQuery(ref) : State.NOVALUE, table ? new LazyDeferredSequence(() => this.connect(table.getCachedQuerySequence(ref))) : undefined);
+        super(table && isCached ? table.getQuery(ref) : State.NOVALUE, table ? new LazyDeferredSequence(() => this.from(table.getCachedQuerySequence(ref))) : undefined);
         this.busy = new BooleanState();
         this._hasMore = false;
         /** Refresh this state from the source provider. */
@@ -87,7 +87,7 @@ export class QueryState extends State {
     }
     /** Subscribe this state to the source provider. */
     connectSource() {
-        return this.connect(this.ref);
+        return this.from(this.ref);
     }
     async _loadMore() {
         this.busy.set(true);

package/schema/AllowSchema.d.ts

@@ -1,24 +1,26 @@
 import type { Entry } from "../util/entry.js";
 import { ImmutableRequiredMap, PossibleMap, PossibleStringMap } from "../util/map.js";
 import { Schema, SchemaOptions } from "./Schema.js";
+/** Allowed options for `AllowSchama` */
+export declare type AllowSchemaOptions<K, T> = Omit<SchemaOptions, "value"> & {
+    allow: PossibleMap<K, T>;
+};
 /** Define a valid value from an allowed set of values. */
 export declare class AllowSchema<K, T> extends Schema<K> implements Iterable<Entry<K, T>> {
-    readonly value: K | null;
+    readonly value: K;
     readonly allow: ImmutableRequiredMap<K, T>;
-    constructor({ allow, value, ...options }: SchemaOptions & {
-        allow: PossibleMap<K, T>;
-        value?: K | null;
-    });
+    constructor({ allow, ...options }: AllowSchemaOptions<K, T>);
     validate(value?: unknown): K;
     /** Iterate over the the allowed options in `[key, value]` format. */
     [Symbol.iterator](): Iterator<Entry<K, T>>;
 }
-/** Define a valid string value from an allowed set of values. */
+/** Allowed options for `AllowStringSchama` */
+export declare type AllowStringSchemaOptions<K extends string, T> = Omit<SchemaOptions, "value"> & {
+    allow: PossibleStringMap<K, T>;
+};
+/** Define a valid string value from an allowed set of string values. */
 export declare class AllowStringSchema<K extends string, T> extends AllowSchema<K, T> {
-    constructor({ allow, ...options }: SchemaOptions & {
-        allow: PossibleStringMap<K, T>;
-        value?: K | null;
-    });
+    constructor({ allow, ...options }: AllowStringSchemaOptions<K, T>);
     validator(value?: unknown): K;
 }
 /** Valid value from an allowed set of values. */

package/schema/AllowSchema.js

@@ -1,13 +1,14 @@
 import { getString } from "../util/string.js";
 import { getRequiredMap, isMapKey } from "../util/map.js";
 import { InvalidFeedback } from "../feedback/InvalidFeedback.js";
+import { getFirstItem } from "../util/array.js";
 import { Schema } from "./Schema.js";
 /** Define a valid value from an allowed set of values. */
 export class AllowSchema extends Schema {
-    constructor({ allow, value = null, ...options }) {
+    constructor({ allow, ...options }) {
         super(options);
         this.allow = getRequiredMap(allow);
-        this.value = value;
+        this.value = getFirstItem(this.allow.keys());
     }
     validate(value = this.value) {
         if (isMapKey(this.allow, value))
@@ -19,7 +20,7 @@ export class AllowSchema extends Schema {
         return this.allow[Symbol.iterator]();
     }
 }
-/** Define a valid string value from an allowed set of values. */
+/** Define a valid string value from an allowed set of string values. */
 export class AllowStringSchema extends AllowSchema {
     constructor({ allow, ...options }) {
         super({ allow: getRequiredMap(allow), ...options });

package/schema/ArraySchema.d.ts

@@ -1,6 +1,14 @@
 import { ImmutableArray } from "../util/array.js";
 import { Validator } from "../util/validate.js";
 import { Schema, SchemaOptions } from "./Schema.js";
+/** Allowed options for `ArraySchema` */
+export declare type ArraySchemaOptions<T> = SchemaOptions & {
+    readonly value?: ImmutableArray;
+    readonly items: Validator<T>;
+    readonly min?: number;
+    readonly max?: number | null;
+    readonly unique?: boolean;
+};
 /**
  * Define a valid array.
  *
@@ -34,13 +42,7 @@ export declare class ArraySchema<T> extends Schema<ImmutableArray<T>> {
     readonly unique: boolean;
     readonly min: number;
     readonly max: number | null;
-    constructor({ value, items, unique, min, max, ...options }: SchemaOptions & {
-        readonly value?: ImmutableArray;
-        readonly items: Validator<T>;
-        readonly min?: number;
-        readonly max?: number | null;
-        readonly unique?: boolean;
-    });
+    constructor({ value, items, unique, min, max, ...options }: ArraySchemaOptions<T>);
     validate(unsafeValue?: unknown): ImmutableArray<T>;
 }
 /** Valid array with specifed items. */

package/schema/BooleanSchema.d.ts

@@ -1,10 +1,12 @@
 import { Schema, SchemaOptions } from "./Schema.js";
+/** Allowed options for `BooleanSchema` */
+export declare type BooleanSchemaOptions = SchemaOptions & {
+    readonly value?: boolean;
+};
 /** Define a valid boolean. */
 export declare class BooleanSchema extends Schema<boolean> {
     readonly value: boolean;
-    constructor({ value, ...options }: SchemaOptions & {
-        readonly value?: boolean;
-    });
+    constructor({ value, ...options }: BooleanSchemaOptions);
     validate(unsafeValue?: unknown): boolean;
 }
 /** Valid boolean. */

package/schema/DataSchema.d.ts

@@ -2,14 +2,16 @@ import type { Data, Datas } from "../util/data.js";
 import { Validators } from "../util/validate.js";
 import { OptionalSchema } from "./OptionalSchema.js";
 import { Schema, SchemaOptions } from "./Schema.js";
+/** Allowed options for `DataSchema` */
+export declare type DataSchemaOptions<T extends Data> = SchemaOptions & {
+    readonly props: Validators<T>;
+    readonly value?: Partial<T>;
+};
 /** Validate a data object. */
 export declare class DataSchema<T extends Data> extends Schema<T> {
     readonly value: Partial<T>;
     readonly props: Validators<T>;
-    constructor({ value, props, ...options }: SchemaOptions & {
-        readonly props: Validators<T>;
-        readonly value?: Partial<T>;
-    });
+    constructor({ value, props, ...options }: DataSchemaOptions<T>);
     validate(unsafeValue?: unknown): T;
 }
 /** Set of named data schemas. */

package/schema/DateSchema.d.ts

@@ -1,15 +1,17 @@
 import { PossibleDate } from "../util/date.js";
 import { Schema, SchemaOptions } from "./Schema.js";
+/** Allowed options for `DateSchema` */
+export declare type DateSchemaOptions = SchemaOptions & {
+    readonly value?: PossibleDate;
+    readonly min?: PossibleDate | null;
+    readonly max?: PossibleDate | null;
+};
 /** Define a valid date in YMD format, e.g. `2005-09-12` */
 export declare class DateSchema extends Schema<string> {
     readonly value: PossibleDate;
     readonly min: Date | null;
     readonly max: Date | null;
-    constructor({ value, min, max, ...options }: SchemaOptions & {
-        readonly value?: PossibleDate;
-        readonly min?: PossibleDate | null;
-        readonly max?: PossibleDate | null;
-    });
+    constructor({ value, min, max, ...options }: DateSchemaOptions);
     validate(unsafeValue?: unknown): string;
 }
 /** Valid date, e.g. `2005-09-12` (required because falsy values are invalid). */

package/schema/DictionarySchema.d.ts

@@ -1,18 +1,20 @@
 import { ImmutableDictionary } from "../util/dictionary.js";
 import { Validator } from "../util/validate.js";
 import { Schema, SchemaOptions } from "./Schema.js";
+/** Allowed options for `DictionarySchema` */
+export declare type DictionarySchemaOptions<T> = SchemaOptions & {
+    readonly items: Validator<T>;
+    readonly value?: ImmutableDictionary;
+    readonly min?: number | null;
+    readonly max?: number | null;
+};
 /** Validate a dictionary object (whose props are all the same with string keys). */
 export declare class DictionarySchema<T> extends Schema<ImmutableDictionary<T>> {
     readonly value: ImmutableDictionary;
     readonly items: Validator<T>;
     readonly min: number | null;
     readonly max: number | null;
-    constructor({ value, items, min, max, ...rest }: SchemaOptions & {
-        readonly items: Validator<T>;
-        readonly value?: ImmutableDictionary;
-        readonly min?: number | null;
-        readonly max?: number | null;
-    });
+    constructor({ value, items, min, max, ...rest }: DictionarySchemaOptions<T>);
     validate(unsafeValue?: unknown): ImmutableDictionary<T>;
 }
 /** Valid dictionary object with specifed items. */

package/schema/LinkSchema.d.ts

@@ -1,4 +1,9 @@
 import { StringSchema, StringSchemaOptions } from "./StringSchema.js";
+/** Allowed options for `LinkSchema` */
+export declare type LinkSchemaOptions = StringSchemaOptions & {
+    readonly schemes?: string[];
+    readonly hosts?: string[] | null;
+};
 /**
  * Type of `StringSchema` that defines a valid URL.
  * - Checks URL scheme against a whitelist (always), and checks URL domain against a whitelist (optional).
@@ -11,10 +16,7 @@ export declare class LinkSchema extends StringSchema {
     readonly max = 512;
     readonly schemes: string[];
     readonly hosts: string[] | null;
-    constructor({ schemes, hosts, ...rest }: StringSchemaOptions & {
-        readonly schemes?: string[];
-        readonly hosts?: string[] | null;
-    });
+    constructor({ schemes, hosts, ...rest }: LinkSchemaOptions);
     validate(unsafeValue: unknown): string;
 }
 /** Valid link, e.g. `https://www.google.com` */

package/schema/NumberSchema.d.ts

@@ -1,16 +1,18 @@
 import { Schema, SchemaOptions } from "./Schema.js";
+/** Allowed options for `NumberSchema` */
+export declare type NumberSchemaOptions = SchemaOptions & {
+    readonly value?: number | null;
+    readonly min?: number | null;
+    readonly max?: number | null;
+    readonly step?: number | null;
+};
 /** Schema that defines a valid number. */
 export declare class NumberSchema extends Schema<number> {
     readonly value: number | null;
     readonly min: number | null;
     readonly max: number | null;
     readonly step: number | null;
-    constructor({ value, min, max, step, ...rest }: SchemaOptions & {
-        readonly value?: number | null;
-        readonly min?: number | null;
-        readonly max?: number | null;
-        readonly step?: number | null;
-    });
+    constructor({ value, min, max, step, ...rest }: NumberSchemaOptions);
     validate(unsafeValue?: unknown): number;
 }
 /** Valid number, e.g. `2048.12345` or `0` zero. */

package/schema/Schema.d.ts

@@ -2,11 +2,13 @@ import type { Validatable } from "../util/validate.js";
 /** Options allowed by a `Schema` instance. */
 export declare type SchemaOptions = {
     /** Title of the schema, e.g. for using as the title of a corresponding field. */
-    readonly title?: string;
+    readonly title?: string | null;
     /** Description of the schema, e.g. for using as a description in a corresponding field. */
-    readonly description?: string;
+    readonly description?: string | null;
     /** Placeholder of the schema, e.g. for using as a placeholder in a corresponding field. */
-    readonly placeholder?: string;
+    readonly placeholder?: string | null;
+    /** Default value for the schema if `validate()` is called with an `undefined` value. */
+    readonly value?: unknown;
 };
 /**
  * Schema is an object instance with a `validate()` method.
@@ -14,15 +16,15 @@ export declare type SchemaOptions = {
  * - `validate()` returns `Invalid` if value was not valid.
  */
 export declare abstract class Schema<T extends unknown = unknown> implements Validatable<T> {
-    /** Title, e.g. for showing in fields. */
-    readonly title?: string;
-    /** Description, e.g. for showing in fields. */
-    readonly description?: string;
-    /** Placeholder, e.g. for showing in fields. */
-    readonly placeholder?: string;
-    /** Default value. */
-    readonly value?: unknown;
-    constructor({ title, description, placeholder }: SchemaOptions);
+    /** Title of the schema, e.g. for using as the title of a corresponding field. */
+    readonly title: string | null;
+    /** Description of the schema, e.g. for using as a description in a corresponding field. */
+    readonly description: string | null;
+    /** Placeholder of the schema, e.g. for using as a placeholder in a corresponding field. */
+    readonly placeholder: string | null;
+    /** Default value for the schema if `validate()` is called with an `undefined` value. */
+    readonly value: unknown;
+    constructor({ title, description, placeholder, value }: SchemaOptions);
     /** Every schema must implement a `validate()` method. */
     abstract validate(unsafeValue: unknown): T;
 }

package/schema/Schema.js

@@ -4,9 +4,10 @@
  * - `validate()` returns `Invalid` if value was not valid.
  */
 export class Schema {
-    constructor({ title = "", description = "", placeholder = "" }) {
+    constructor({ title = null, description = null, placeholder = null, value }) {
         this.title = title;
         this.description = description;
         this.placeholder = placeholder;
+        this.value = value;
     }
 }

package/schema/ThroughSchema.d.ts

@@ -1,10 +1,12 @@
 import type { Sourceable } from "../util/source.js";
-import { Schema } from "./Schema.js";
+import { Schema, SchemaOptions } from "./Schema.js";
+/** Allowed options for `ThroughSchama` */
+export declare type ThroughSchemaOptions<T> = SchemaOptions & {
+    source: Schema<T>;
+};
 /** Schema that passes through to a source schema. */
 export declare abstract class ThroughSchema<T> extends Schema<T> implements Sourceable<Schema<T>> {
     readonly source: Schema<T>;
-    constructor({ source, ...props }: ConstructorParameters<typeof Schema>[0] & {
-        source: Schema<T>;
-    });
+    constructor({ source, ...props }: ThroughSchemaOptions<T>);
     validate(unsafeValue: unknown): T;
 }

package/schema/TimeSchema.d.ts

@@ -1,5 +1,12 @@
 import { PossibleTime, Time } from "../util/time.js";
 import { Schema, SchemaOptions } from "./Schema.js";
+/** Allowed options for `TimeSchama` */
+export declare type TimeSchemaOptions = SchemaOptions & {
+    readonly value?: PossibleTime;
+    readonly min?: PossibleTime | null;
+    readonly max?: PossibleTime | null;
+    readonly step?: number | null;
+};
 /** Define a valid time in 24h hh:mm:ss.fff format, e.g. `23:59` or `24:00 */
 export declare class TimeSchema extends Schema<string> {
     readonly value: PossibleTime;
@@ -10,12 +17,7 @@ export declare class TimeSchema extends Schema<string> {
      * - Note: `<input type="time">` elements expect `step=""` to be  in _seconds_ so you need to multiply this by `1000`
      */
     readonly step: number | null;
-    constructor({ value, min, max, step, ...options }: SchemaOptions & {
-        readonly value?: PossibleTime;
-        readonly min?: PossibleTime | null;
-        readonly max?: PossibleTime | null;
-        readonly step?: number | null;
-    });
+    constructor({ value, min, max, step, ...options }: TimeSchemaOptions);
     validate(unsafeValue?: unknown): string;
 }
 /** Valid time, e.g. `2005-09-12` (required because falsy values are invalid). */

package/sequence/DeferredSequence.d.ts

@@ -1,4 +1,4 @@
-import type { Dispatch, Handler } from "../util/function.js";
+import type { Dispatch, Handler, Stop } from "../util/function.js";
 import { AbstractSequence } from "./AbstractSequence.js";
 /**
  * Deferred sequence of values.
@@ -21,10 +21,12 @@ export declare class DeferredSequence<T = void, R = void> extends AbstractSequen
     private _nextReason;
     /** Fulfill the current deferred by resolving or rejecting it. */
     private readonly _fulfill;
+    /** Resolve the current deferred from a sequence of values. */
+    resolveSequence(sequence: AsyncIterable<T>): AsyncIterable<T>;
     next(): Promise<IteratorResult<T, R>>;
     then<X = T, Y = never>(onNext?: (v: T) => X | PromiseLike<X>, onError?: (r: unknown) => Y | PromiseLike<Y>): Promise<X | Y>;
     catch<Y>(onError: (r: unknown) => Y | PromiseLike<Y>): Promise<T | Y>;
     finally(onFinally: () => void): Promise<T>;
     /** Subscrbe to the value of the sequence with a callback until the returned stop function is called. */
-    subscribe(onNext: Dispatch<[T]>, onError?: Handler): Dispatch;
+    subscribe(onNext: Dispatch<[T]>, onError?: Handler): Stop;
 }

package/sequence/DeferredSequence.js

@@ -43,6 +43,13 @@ export class DeferredSequence extends AbstractSequence {
     get value() {
         return (this._deferred || (this._deferred = new Deferred()));
     }
+    /** Resolve the current deferred from a sequence of values. */
+    async *resolveSequence(sequence) {
+        for await (const item of sequence) {
+            this.resolve(item);
+            yield item;
+        }
+    }
     // Implement `AsyncIterator`
     async next() {
         return { value: await this.value };

package/state/State.d.ts

@@ -1,4 +1,4 @@
-import type { Dispatch } from "../util/function.js";
+import { Dispatch, Handler, Stop } from "../util/function.js";
 import { DeferredSequence } from "../sequence/DeferredSequence.js";
 /** Any `State` instance. */
 export declare type AnyState = State<any>;
@@ -12,7 +12,7 @@ export declare type AnyState = State<any>;
  * - To set the state to be loading, use the `State.NOVALUE` constant or a `Promise` value.
  * - To set the state to an explicit value, use that value or another `State` instance with a value.
  * */
-export declare class State<T> {
+export declare class State<T> implements AsyncIterable<T> {
     /** The `NOVALUE` symbol indicates no value has been received by a `State` instance. */
     static readonly NOVALUE: unique symbol;
     /** Deferred sequence this state uses to issue values as they change. */
@@ -33,6 +33,11 @@ export declare class State<T> {
     set(value: T): void;
     /** Set the value of the state as values are pulled from a sequence. */
     setSequence(sequence: AsyncIterable<T>): AsyncIterable<T>;
-    /** Connect this state to a source until the returned stop function is called. */
-    connect(sequence: AsyncIterable<T>): Dispatch;
+    /** Pull values from a source sequence until the returned stop function is called. */
+    from(source: AsyncIterable<T>, onError?: Handler): Stop;
+    /** Push values to another state or callback to this state until the returned stop function is called. */
+    to(target: State<T> | Dispatch<[T]>, onError?: Handler): Stop;
+    [Symbol.asyncIterator](): AsyncIterator<T, any, undefined>;
 }
+/** Is an unknown value a `State` instance. */
+export declare const isState: <T extends AnyState>(v: unknown) => v is T;

package/state/State.js

@@ -51,10 +51,33 @@ export class State {
             yield value;
         }
     }
-    /** Connect this state to a source until the returned stop function is called. */
-    connect(sequence) {
-        return runSequence(this.setSequence(sequence));
+    /** Pull values from a source sequence until the returned stop function is called. */
+    from(source, onError) {
+        return runSequence(this.setSequence(source), onError);
+    }
+    /** Push values to another state or callback to this state until the returned stop function is called. */
+    to(target, onError) {
+        if (isState(target)) {
+            return runSequence(target.setSequence(this), onError);
+        }
+        else {
+            return runSequence(this, target, onError);
+        }
+    }
+    // Implement `AsyncIterable`
+    // Issues the current value of the state first, then any subsequent values that are issued.
+    [Symbol.asyncIterator]() {
+        // If this is still loading yield the next value as soon as we get one.
+        if (this.loading)
+            return this.next[Symbol.asyncIterator]();
+        // If this has a current value then yield the current value immediately, then the rest of the sequence.
+        // But! If additional values are set synchronously, only the yield the final one. Use a new `DeferredSequence` to make sure this happens cleanly.
+        const deferred = new DeferredSequence();
+        deferred.resolve(this.value);
+        return deferred.resolveSequence(this.next)[Symbol.asyncIterator]();
     }
 }
 /** The `NOVALUE` symbol indicates no value has been received by a `State` instance. */
 State.NOVALUE = Symbol("shelving/State.NOVALUE");
+/** Is an unknown value a `State` instance. */
+export const isState = (v) => v instanceof State;

package/update/DataUpdate.d.ts

@@ -10,7 +10,7 @@ import { Update } from "./Update.js";
  * - If a prop contains an `Update` instance, the existing value is updated.
  */
 export declare type Updates<T extends Data = Data> = {
-    readonly [K in keyof T]?: T[K] | Update<T[K]>;
+    readonly [K in keyof T]?: T[K] | Update<T[K]> | undefined;
 };
 /**
  * Validate a set of updates against a set of validators.
@@ -30,5 +30,7 @@ export declare class DataUpdate<T extends Data = Data> extends Update<T> impleme
     update<K extends DataKey<T>>(key: Nullish<K>, value: T[K] | Update<T[K]>): this;
     transform(data: T): T;
     validate(validator: Validator<T>): this;
-    [Symbol.iterator](): Iterator<DataProp<Updates<T>>, void>;
+    [Symbol.iterator](): Iterator<DataProp<{
+        readonly [K in keyof T]: T[K] | Update<T[K]>;
+    }>, void>;
 }

package/util/merge.d.ts

@@ -18,7 +18,7 @@ export declare const exactMerge: MergeRecursor;
  * - Will be merged instance otherwise.
  */
 export declare function shallowMerge<L extends ImmutableObject, R extends ImmutableObject>(left: L, right: R): L & R;
-export declare function shallowMerge<L extends unknown, R extends unknown>(left: ImmutableArray<L>, right: ImmutableArray<R>): ImmutableArray<L | R>;
+export declare function shallowMerge<L, R>(left: ImmutableArray<L>, right: ImmutableArray<R>): ImmutableArray<L | R>;
 export declare function shallowMerge<R>(left: unknown, right: R): R;
 /**
  * Deeply merge two unknown values.
@@ -32,7 +32,7 @@ export declare function shallowMerge<R>(left: unknown, right: R): R;
  * - Will be a new merged instance otherwise.
  */
 export declare function deepMerge<L extends ImmutableObject, R extends ImmutableObject>(left: L, right: R): L & R;
-export declare function deepMerge<L extends unknown, R extends unknown>(left: ImmutableArray<L>, right: ImmutableArray<R>): ImmutableArray<L | R>;
+export declare function deepMerge<L, R>(left: ImmutableArray<L>, right: ImmutableArray<R>): ImmutableArray<L | R>;
 export declare function deepMerge<R>(left: unknown, right: R): R;
 /**
  * Merge two arrays.
@@ -45,7 +45,7 @@ export declare function deepMerge<R>(left: unknown, right: R): R;
  * - Will be `left` instance if no items were added.
  * - Will be a new merged array otherwise.
  */
-export declare function mergeArray<L extends unknown, R extends unknown>(left: ImmutableArray<L>, right: ImmutableArray<R>): ImmutableArray<L | R>;
+export declare function mergeArray<L, R>(left: ImmutableArray<L>, right: ImmutableArray<R> | ImmutableArray<L>): ImmutableArray<L | R>;
 /**
  * Merge two data objects.
  *

package/util/merge.js

@@ -1,4 +1,4 @@
-import { isArray } from "./array.js";
+import { isArray, withArrayItems } from "./array.js";
 import { isObject } from "./object.js";
 // Internal shared by shallow/deep merge.
 function _merge(left, right, recursor) {
@@ -21,17 +21,6 @@ export function shallowMerge(left, right) {
 export function deepMerge(left, right) {
     return _merge(left, right, deepMerge);
 }
-/**
- * Merge two arrays.
- * - Values are considered unique so values will not appear twice.
- * - Arrays have no concept of `deep merge` because array keys are not stable.
- * - Use an map/object data structure instead for values that need to be deeply mergeable (only use arrays for primitive values).
- *
- * @returns Merged array.
- * - Values that appear in both arrays will not be added twice.
- * - Will be `left` instance if no items were added.
- * - Will be a new merged array otherwise.
- */
 export function mergeArray(left, right) {
     if (left === right)
         return right;
@@ -39,11 +28,7 @@ export function mergeArray(left, right) {
         return left;
     if (!left.length)
         return right;
-    const merged = left.slice();
-    for (const v of right)
-        if (!merged.includes(v))
-            merged.push(v);
-    return merged.length === left.length ? left : merged;
+    return withArrayItems(left, ...right);
 }
 export function mergeObject(left, right, recursor = exactMerge) {
     if (left === right)

package/util/sequence.d.ts

@@ -1,22 +1,18 @@
 import { SIGNAL } from "./constants.js";
 import { Handler, Stop, AsyncDispatch, Dispatch } from "./function.js";
-/** Slightly modify the definition of `AsyncIterable` to default `R` and `N` to `void` */
-export declare interface AsyncIterable<T, R = void, N = void> {
-    [Symbol.asyncIterator](): AsyncIterator<T, R, N>;
-}
 /**
  * Is a value an async iterable object?
  * - Any object with a `Symbol.iterator` property is iterable.
  * - Note: Array and Map instances etc will return true because they implement `Symbol.iterator`
  */
-export declare const isAsyncIterable: <T extends AsyncIterable<unknown, void, void>>(value: unknown) => value is T;
+export declare const isAsyncIterable: <T extends AsyncIterable<unknown>>(value: unknown) => value is T;
 /** Infinite sequence that yields until a `SIGNAL` is received. */
-export declare function repeatUntil<T, R>(source: AsyncIterable<T, R>, ...signals: [Promise<typeof SIGNAL>, ...Promise<typeof SIGNAL>[]]): AsyncIterable<T, R | typeof SIGNAL>;
+export declare function repeatUntil<T>(source: AsyncIterable<T>, ...signals: [Promise<typeof SIGNAL>, ...Promise<typeof SIGNAL>[]]): AsyncIterable<T>;
 /** Infinite sequence that yields every X milliseconds (yields a count of the number of iterations). */
 export declare function repeatDelay(ms: number): AsyncIterable<number>;
 /** Dispatch items in a sequence to a (possibly async) callback. */
-export declare function dispatchSequence<T, R>(sequence: AsyncIterable<T, R>, onNext: AsyncDispatch<[T]>): AsyncIterable<T>;
+export declare function dispatchSequence<T>(sequence: AsyncIterable<T>, onNext: AsyncDispatch<[T]>): AsyncIterable<T>;
 /** Get the first value from an async iterator. **/
-export declare function getNextValue<T, R>(sequence: AsyncIterable<T, R>): Promise<T>;
+export declare function getNextValue<T>(sequence: AsyncIterable<T>): Promise<T>;
 /** Pull values from a sequence until the returned function is called. */
-export declare function runSequence<T, R>(sequence: AsyncIterable<T, R>, onNext?: Dispatch<[T]>, onError?: Handler): Stop;
+export declare function runSequence<T>(sequence: AsyncIterable<T>, onNext?: Dispatch<[T]>, onError?: Handler): Stop;

package/util/transform.d.ts

@@ -6,15 +6,25 @@ import { ImmutableDictionary } from "./dictionary.js";
 export interface Transformable<I, O> {
     transform(input: I): O;
 }
+/** Object that transforms an input value into an output value with its `transform()` method. */
+export interface AsyncTransformable<I, O> {
+    transform(input: I): O | PromiseLike<O>;
+}
 /** Is an unknown value a transformable. */
 export declare const isTransformable: <T extends Transformable<unknown, unknown>>(v: unknown) => v is T;
 /** Function that can transform an input value into an output value. */
 export declare type Transform<I, O> = (input: I) => O;
+/** Function that can transform an input value into an output value. */
+export declare type AsyncTransform<I, O> = (input: I) => O | PromiseLike<O>;
 /** Something that can transform an input value into an output value (or a plain value). */
 export declare type Transformer<I, O> = Transformable<I, O> | Transform<I, O> | O;
+/** Something that can transform an input value into an output value (or a plain value). */
+export declare type AsyncTransformer<I, O> = AsyncTransformable<I, O> | AsyncTransform<I, O> | O;
 /** 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: (v: I) => O | PromiseLike<O>): O | PromiseLike<O>;
 export declare function transform<I, O>(input: I, transformer: Transformer<I, O>): O;
+export declare function transform<I, O>(input: I, transformer: AsyncTransformer<I, O>): O;
 /** Modify a set of items using a transformer. */
 export declare function mapItems<I, O>(items: Iterable<I>, transformer: Transformer<I, O>): Iterable<O>;
 /** Modify the items of an array using a transformer. */
@@ -27,11 +37,13 @@ export declare function mapObject<I extends ImmutableObject, O extends Immutable
 export declare const mapDictionary: <I, O>(dictionary: ImmutableDictionary<I>, transformer: Transformer<I, O>) => ImmutableDictionary<O>;
 /** Modify the values of a set of entries using a transformer. */
 export declare function mapEntries<K, I, O>(entries: Iterable<Entry<K, I>>, transformer: Transformer<I, O>): Iterable<Entry<K, O>>;
-/** Set of named transformers for a data object. */
+/** Set of named transformers for a data object (or `undefined` to skip the transform). */
 export declare type Transformers<T extends ImmutableObject> = {
-    readonly [K in keyof T]?: Transformer<T[K], T[K]>;
+    readonly [K in keyof T]?: Transformer<T[K], T[K]> | undefined;
 };
 /** Transform an object using a set of named transformers. */
 export declare function transformObject<T extends ImmutableObject>(obj: T, transforms: Transformers<T>): T;
 /** Transform a dictionary object using a set of named transformers. */
 export declare const transformDictionary: <T>(dict: ImmutableDictionary<T>, transforms: Transformers<ImmutableDictionary<T>>) => ImmutableDictionary<T>;
+/** Transform items in a sequence as they are yielded using a (potentially async) transformer. */
+export declare function mapSequence<L, R>(sequence: AsyncIterable<L>, transformer: AsyncTransformer<L, R>): AsyncIterable<R>;

package/util/transform.js

@@ -29,7 +29,13 @@ export function transformObject(obj, transforms) {
 }
 function* _transformObjectProps(obj, transforms) {
     for (const [k, v] of getProps(transforms))
-        yield [k, transform(obj[k], v)];
+        if (v !== undefined)
+            yield [k, transform(obj[k], v)];
 }
 /** Transform a dictionary object using a set of named transformers. */
 export const transformDictionary = transformObject;
+/** Transform items in a sequence as they are yielded using a (potentially async) transformer. */
+export async function* mapSequence(sequence, transformer) {
+    for await (const item of sequence)
+        yield transform(item, transformer);
+}