shelving 1.97.0 → 1.98.0

package/db/ItemReference.d.ts

@@ -1,9 +1,8 @@
 import type { DeleteChange, SetChange, UpdateChange } from "./Change.js";
 import type { AsyncProvider, Provider } from "../provider/Provider.js";
-import type { Stop } from "../util/activity.js";
 import type { ImmutableArray } from "../util/array.js";
+import type { Callback, ErrorCallback, StopCallback } from "../util/callback.js";
 import type { Data } from "../util/data.js";
-import type { Dispatch, Handler } from "../util/function.js";
 import type { Query } from "../util/query.js";
 import type { Updates } from "../util/update.js";
 /** Item data with a string ID that uniquely identifies it. */
@@ -62,7 +61,7 @@ declare abstract class AbstractItemReference<T extends Data = Data> implements A
     getDelete(): DeleteChange;
     toString(): string;
     /** Subscribe to this item. */
-    subscribe(onNext?: Dispatch<ItemValue<T>>, onError?: Handler): Stop;
+    subscribe(onNext?: Callback<ItemValue<T>>, onError?: ErrorCallback): StopCallback;
     [Symbol.asyncIterator](): AsyncIterator<ItemValue<T>>;
 }
 /** Reference to an item in a synchronous database. */

package/db/ItemState.d.ts

@@ -1,6 +1,6 @@
 import type { AsyncItemReference, ItemData, ItemReference, ItemValue } from "./ItemReference.js";
+import type { StopCallback } from "../util/callback.js";
 import type { Data } from "../util/data.js";
-import type { Dispatch } from "../util/function.js";
 import { BooleanState } from "../state/BooleanState.js";
 import { State } from "../state/State.js";
 /** Hold the current state of a item. */
@@ -18,5 +18,5 @@ export declare class ItemState<T extends Data = Data> extends State<ItemValue<T>
     /** Refresh this state if data in the cache is older than `maxAge` (in milliseconds). */
     refreshStale(maxAge: number): void;
     /** Subscribe this state to the source provider. */
-    connectSource(): Dispatch;
+    connectSource(): StopCallback;
 }

package/db/ItemState.js

@@ -1,5 +1,5 @@
 import { CacheProvider } from "../provider/CacheProvider.js";
-import { LazyDeferredSequence } from "../sequence/LazyDeferredSequence.js";
+import { SwitchingDeferredSequence } from "../sequence/SwitchingDeferredSequence.js";
 import { BooleanState } from "../state/BooleanState.js";
 import { State } from "../state/State.js";
 import { getRequired } from "../util/null.js";
@@ -19,7 +19,7 @@ export class ItemState extends State {
         const { provider, collection, id } = ref;
         const table = (_a = getOptionalSource(CacheProvider, provider)) === null || _a === void 0 ? void 0 : _a.memory.getTable(collection);
         const time = table ? table.getQueryTime(ref) : null;
-        const next = table ? new LazyDeferredSequence(() => this.from(table.getCachedItemSequence(id), () => typeof table.getItemTime(id) === "number")) : undefined;
+        const next = table ? new SwitchingDeferredSequence(sequence => sequence.from(table.getCachedItemSequence(id))) : undefined;
         super(table && typeof time === "number" ? { value: table.getItem(id), time, next } : { next });
         this.busy = new BooleanState();
         /** Refresh this state from the source provider. */

package/db/QueryReference.d.ts

@@ -1,8 +1,7 @@
 import type { ItemArray, ItemData, ItemQuery, ItemValue } from "./ItemReference.js";
 import type { AsyncProvider, Provider } from "../provider/Provider.js";
-import type { Stop } from "../util/activity.js";
+import type { Callback, ErrorCallback, StopCallback } from "../util/callback.js";
 import type { Data } from "../util/data.js";
-import type { Dispatch, Handler } from "../util/function.js";
 import type { Updates } from "../util/update.js";
 /** Reference to a set of items in a sync or async provider. */
 declare abstract class AbstractQueryReference<T extends Data = Data> implements AsyncIterable<ItemArray<T>> {
@@ -63,7 +62,7 @@ declare abstract class AbstractQueryReference<T extends Data = Data> implements
     abstract delete(): number | PromiseLike<number>;
     toString(): string;
     /** Subscribe to this item. */
-    subscribe(onNext?: Dispatch<ItemArray<T>>, onError?: Handler): Stop;
+    subscribe(onNext?: Callback<ItemArray<T>>, onError?: ErrorCallback): StopCallback;
     [Symbol.asyncIterator](): AsyncIterator<ItemArray<T>>;
 }
 /** Reference to a set of items in a provider. */

package/db/QueryState.d.ts

@@ -1,6 +1,6 @@
 import type { ItemArray, ItemData, ItemValue } from "./ItemReference.js";
 import type { AsyncQueryReference, QueryReference } from "./QueryReference.js";
-import type { Stop } from "../util/activity.js";
+import type { StopCallback } from "../util/callback.js";
 import type { Data } from "../util/data.js";
 import { BooleanState } from "../state/BooleanState.js";
 import { State } from "../state/State.js";
@@ -31,7 +31,7 @@ export declare class QueryState<T extends Data = Data> extends State<ItemArray<T
     /** Refresh this state if data in the cache is older than `maxAge` (in milliseconds). */
     refreshStale(maxAge: number): void;
     /** Subscribe this state to the source provider. */
-    connectSource(): Stop;
+    connectSource(): StopCallback;
     /**
      * Load more items after the last once.
      * - Promise that needs to be handled.

package/db/QueryState.js

@@ -1,5 +1,5 @@
 import { CacheProvider } from "../provider/CacheProvider.js";
-import { LazyDeferredSequence } from "../sequence/LazyDeferredSequence.js";
+import { SwitchingDeferredSequence } from "../sequence/SwitchingDeferredSequence.js";
 import { BooleanState } from "../state/BooleanState.js";
 import { State } from "../state/State.js";
 import { getOptionalFirstItem, getOptionalLastItem } from "../util/array.js";
@@ -41,7 +41,7 @@ export class QueryState extends State {
         const { provider, collection, query } = ref;
         const table = (_a = getOptionalSource(CacheProvider, provider)) === null || _a === void 0 ? void 0 : _a.memory.getTable(collection);
         const time = table ? table.getQueryTime(ref) : null;
-        const next = table ? new LazyDeferredSequence(() => this.from(table.getCachedQuerySequence(ref))) : undefined;
+        const next = table ? new SwitchingDeferredSequence(sequence => sequence.from(table.getCachedQuerySequence(ref))) : undefined;
         super(table && typeof time === "number" ? { value: table.getQuery(ref), time, next } : { next });
         this.busy = new BooleanState();
         this._hasMore = false;

package/firestore/client/FirestoreClientProvider.js

@@ -1,5 +1,5 @@
 import { addDoc, collection, deleteDoc, doc, documentId, getDoc, getDocs, increment, limit, onSnapshot, orderBy, query, setDoc, updateDoc, where } from "firebase/firestore";
-import { LazyDeferredSequence } from "../../sequence/LazyDeferredSequence.js";
+import { SwitchingDeferredSequence } from "../../sequence/SwitchingDeferredSequence.js";
 import { getObject } from "../../util/object.js";
 import { getFilters, getLimit, getOrders } from "../../util/query.js";
 import { mapItems } from "../../util/transform.js";
@@ -60,9 +60,9 @@ export class FirestoreClientProvider {
         return _getItemValue(await getDoc(doc(this._firestore, c, id)));
     }
     getItemSequence(c, id) {
-        return new LazyDeferredSequence(({ resolve, reject }) => onSnapshot(doc(this._firestore, c, id), //
+        return new SwitchingDeferredSequence(sequence => onSnapshot(doc(this._firestore, c, id), //
         //
-        snapshot => resolve(_getItemValue(snapshot)), reject));
+        snapshot => sequence.resolve(_getItemValue(snapshot)), reason => sequence.reject(reason)));
     }
     async addItem(c, data) {
         const reference = await addDoc(collection(this._firestore, c), data);
@@ -81,9 +81,9 @@ export class FirestoreClientProvider {
         return _getItems(await getDocs(_getQuery(this._firestore, c, q)));
     }
     getQuerySequence(c, q) {
-        return new LazyDeferredSequence(({ resolve, reject }) => onSnapshot(_getQuery(this._firestore, c, q), //
+        return new SwitchingDeferredSequence(sequence => onSnapshot(_getQuery(this._firestore, c, q), //
         //
-        snapshot => resolve(_getItems(snapshot)), reject));
+        snapshot => sequence.resolve(_getItems(snapshot)), reason => sequence.reject(reason)));
     }
     async setQuery(c, q, data) {
         const snapshot = await getDocs(_getQuery(this._firestore, c, q));

package/firestore/server/FirestoreServerProvider.js

@@ -1,5 +1,5 @@
 import { FieldPath, FieldValue, Firestore } from "@google-cloud/firestore";
-import { LazyDeferredSequence } from "../../sequence/LazyDeferredSequence.js";
+import { SwitchingDeferredSequence } from "../../sequence/SwitchingDeferredSequence.js";
 import { getObject } from "../../util/object.js";
 import { getFilters, getLimit, getOrders } from "../../util/query.js";
 import { mapItems } from "../../util/transform.js";
@@ -58,8 +58,8 @@ export class FirestoreServerProvider {
     }
     getItemSequence(c, id) {
         const ref = this._firestore.collection(c).doc(id);
-        return new LazyDeferredSequence(({ resolve, reject }) => ref.onSnapshot(snapshot => resolve(_getItemValue(snapshot)), //
-        reject));
+        return new SwitchingDeferredSequence(sequence => ref.onSnapshot(snapshot => sequence.resolve(_getItemValue(snapshot)), //
+        sequence.reject));
     }
     async addItem(c, data) {
         return (await this._firestore.collection(c).add(data)).id;
@@ -78,8 +78,8 @@ export class FirestoreServerProvider {
     }
     getQuerySequence(c, q) {
         const ref = _getQuery(this._firestore, c, q);
-        return new LazyDeferredSequence(({ resolve, reject }) => ref.onSnapshot(snapshot => resolve(_getItemArray(snapshot)), //
-        reject));
+        return new SwitchingDeferredSequence(sequence => ref.onSnapshot(snapshot => sequence.resolve(_getItemArray(snapshot)), //
+        sequence.reject));
     }
     async setQuery(c, q, data) {
         return await bulkWrite(this._firestore, c, q, (w, s) => void w.set(s.ref, data));

package/iterate/AbstractGenerator.d.ts

@@ -1,6 +1,6 @@
 /** Abstract generator designed to be extended that implements the full generator protocol. */
 export declare abstract class AbstractGenerator<T, R, N> implements Generator<T, R, N> {
-    readonly [Symbol.toStringTag]: string;
+    readonly [Symbol.toStringTag] = "Generator";
     abstract next(value: N): IteratorResult<T, R>;
     throw(thrown: Error | unknown): IteratorResult<T, R>;
     return(value: R): IteratorResult<T, R>;

package/iterate/AbstractGenerator.js

@@ -1,13 +1,9 @@
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
 var _a;
-import { setPrototype } from "../util/class.js";
 /** Abstract generator designed to be extended that implements the full generator protocol. */
 export class AbstractGenerator {
+    constructor() {
+        this[_a] = "Generator";
+    }
     throw(thrown) {
         // Default behaviour for a generator is to throw the error back out of the iterator and not continue.
         throw thrown;
@@ -21,6 +17,3 @@ export class AbstractGenerator {
         return this;
     }
 }
-__decorate([
-    setPrototype(Symbol.toStringTag, "Generator")
-], AbstractGenerator.prototype, _a, void 0);

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.97.0",
+	"version": "1.98.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",

package/react/useState.js

@@ -1,5 +1,5 @@
 import { useEffect, useState as useReactState } from "react";
-import { dispatch } from "../util/function.js";
+import { call } from "../util/callback.js";
 import { mapArray } from "../util/transform.js";
 import { isDefined } from "../util/undefined.js";
 export function useState(...states) {
@@ -7,7 +7,7 @@ export function useState(...states) {
     useEffect(() => {
         const rerender = () => setValue({});
         const stops = mapArray(states, _startState, rerender);
-        return () => stops.filter(isDefined).forEach(dispatch);
+        return () => stops.filter(isDefined).forEach(call);
     }, states);
     return states.length <= 1 ? states[0] : states;
 }

package/sequence/AbstractSequence.d.ts

@@ -1,6 +1,6 @@
 /** Sequence of values designed to be extended that implements the full async generator protocol. */
 export declare abstract class AbstractSequence<T, R> implements AsyncGenerator<T, R, void> {
-    readonly [Symbol.toStringTag]: string;
+    readonly [Symbol.toStringTag] = "Sequence";
     abstract next(): Promise<IteratorResult<T, R>>;
     return(returnValue: R | PromiseLike<R>): Promise<IteratorResult<T, R>>;
     throw(reason: Error | unknown): Promise<IteratorResult<T, R>>;

package/sequence/AbstractSequence.js

@@ -1,13 +1,9 @@
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
 var _a;
-import { setPrototype } from "../util/class.js";
 /** Sequence of values designed to be extended that implements the full async generator protocol. */
 export class AbstractSequence {
+    constructor() {
+        this[_a] = "Sequence";
+    }
     async return(returnValue) {
         // Default behaviour for a generator is to return `done: true` and the input value.
         return { done: true, value: await returnValue };
@@ -21,6 +17,3 @@ export class AbstractSequence {
         return this;
     }
 }
-__decorate([
-    setPrototype(Symbol.toStringTag, "Sequence")
-], AbstractSequence.prototype, _a, void 0);

package/sequence/DeferredSequence.d.ts

@@ -1,24 +1,25 @@
-import type { Stop } from "../util/activity.js";
-import type { Dispatch, Handler } from "../util/function.js";
+import type { Deferred } from "../util/async.js";
+import type { Callback, ErrorCallback, StopCallback } from "../util/callback.js";
 import { AbstractSequence } from "./AbstractSequence.js";
 /**
- * Deferred sequence of values.
+ * Deferred sequence of values that can be async iterated and new values can be published.
  * - Implements `AsyncIterable` so values can be iterated over using `for await...of`
  * - Implements `Promise` so the next value can be awaited.
+ * - Implements `Deferred` so next values can be resolved or rejected.
  */
-export declare class DeferredSequence<T = void, R = void> extends AbstractSequence<T, R> implements Promise<T> {
+export declare class DeferredSequence<T = void, R = void> extends AbstractSequence<T, R> implements Deferred<T>, Promise<T> {
     /**
      * Next deferred to be rejected/resolved, or `undefined` if we haven't requested one yet..
      * - Only create the deferred on demand, because we don't want to reject a deferred that isn't used to or it would throw an unhandled promise error.
      */
     private _deferred;
     /** Get the next promise to be deferred/rejected. */
-    get value(): Promise<T>;
+    get promise(): Promise<T>;
     /** Resolve the current deferred in the sequence. */
-    readonly resolve: (value: T) => void;
+    readonly resolve: Callback<T>;
     private _nextValue;
     /** Reject the current deferred in the sequence. */
-    readonly reject: (reason: Error | unknown) => void;
+    readonly reject: ErrorCallback;
     private _nextReason;
     /** Fulfill the current deferred by resolving or rejecting it. */
     private readonly _fulfill;
@@ -29,7 +30,7 @@ export declare class DeferredSequence<T = void, R = void> extends AbstractSequen
     /** Resolve the current deferred from a sequence of values. */
     through(sequence: AsyncIterable<T>): AsyncIterable<T>;
     /** Pull values from a source sequence until the returned stop function is called. */
-    from(source: AsyncIterable<T>, onError?: Handler): Stop;
+    from(source: AsyncIterable<T>, onError?: ErrorCallback): StopCallback;
     /** Subscrbe to the value of the sequence with a callback until the returned stop function is called. */
-    to(onNext: Dispatch<T>, onError?: Handler): Stop;
+    to(onNext: Callback<T>, onError?: ErrorCallback): StopCallback;
 }

package/sequence/DeferredSequence.js

@@ -4,22 +4,23 @@ import { AbstractSequence } from "./AbstractSequence.js";
 /** Used when the deferred sequence has no value or reason queued. */
 const _NOVALUE = Symbol("shelving/DeferredSequence.NOVALUE");
 /**
- * Deferred sequence of values.
+ * Deferred sequence of values that can be async iterated and new values can be published.
  * - Implements `AsyncIterable` so values can be iterated over using `for await...of`
  * - Implements `Promise` so the next value can be awaited.
+ * - Implements `Deferred` so next values can be resolved or rejected.
  */
 export class DeferredSequence extends AbstractSequence {
     constructor() {
         super(...arguments);
         /** Resolve the current deferred in the sequence. */
-        this.resolve = (value) => {
+        this.resolve = value => {
             this._nextValue = value;
             this._nextReason = _NOVALUE;
             queueMicrotask(this._fulfill);
         };
         this._nextValue = _NOVALUE;
         /** Reject the current deferred in the sequence. */
-        this.reject = (reason) => {
+        this.reject = reason => {
             this._nextValue = _NOVALUE;
             this._nextReason = reason;
             queueMicrotask(this._fulfill);
@@ -40,22 +41,22 @@ export class DeferredSequence extends AbstractSequence {
         };
     }
     /** Get the next promise to be deferred/rejected. */
-    get value() {
+    get promise() {
         return (this._deferred || (this._deferred = getDeferred())).promise;
     }
     // Implement `AsyncIterator`
     async next() {
-        return { value: await this.value };
+        return { value: await this.promise };
     }
     // Implement `Promise`
     then(onNext, onError) {
-        return this.value.then(onNext, onError);
+        return this.promise.then(onNext, onError);
     }
     catch(onError) {
-        return this.value.catch(onError);
+        return this.promise.catch(onError);
     }
     finally(onFinally) {
-        return this.value.finally(onFinally);
+        return this.promise.finally(onFinally);
     }
     /** Resolve the current deferred from a sequence of values. */
     async *through(sequence) {

package/sequence/SwitchingDeferredSequence.d.ts

@@ -0,0 +1,8 @@
+import type { StartCallback } from "../util/callback.js";
+import { DeferredSequence } from "./DeferredSequence.js";
+/** Deferred sequence of values that switches on when it has iterators that are iterating, and off when all iterators are done. */
+export declare class SwitchingDeferredSequence<T = void, R = void> extends DeferredSequence<T, R> {
+    private readonly _switch;
+    constructor(start: StartCallback<DeferredSequence<T, R>>);
+    [Symbol.asyncIterator](): AsyncGenerator<T, R, void>;
+}

package/sequence/SwitchingDeferredSequence.js

@@ -0,0 +1,13 @@
+import { SwitchingSet } from "../util/switch.js";
+import { DeferredSequence } from "./DeferredSequence.js";
+import { SwitchingSequence } from "./SwitchingSequence.js";
+/** Deferred sequence of values that switches on when it has iterators that are iterating, and off when all iterators are done. */
+export class SwitchingDeferredSequence extends DeferredSequence {
+    constructor(start) {
+        super();
+        this._switch = new SwitchingSet(() => start(this));
+    }
+    [Symbol.asyncIterator]() {
+        return new SwitchingSequence(this, this._switch);
+    }
+}

package/sequence/SwitchingSequence.d.ts

@@ -0,0 +1,10 @@
+import type { PossibleSwitch } from "../util/switch.js";
+import { ThroughSequence } from "./ThroughSequence.js";
+/** Async generator that switches on when it has iterators that are iterating, and off when all iterators are done. */
+export declare class SwitchingSequence<T, R> extends ThroughSequence<T, R> implements ThroughSequence<T, R> {
+    private readonly _switch;
+    constructor(source: AsyncIterator<T, R>, switchable: PossibleSwitch<AsyncIterator<T, R>>);
+    next(): Promise<IteratorResult<T, R>>;
+    return(value: R | PromiseLike<R>): Promise<IteratorResult<T, R>>;
+    throw(reason: Error | unknown): Promise<IteratorResult<T, R>>;
+}

package/sequence/SwitchingSequence.js

@@ -0,0 +1,52 @@
+import { getSwitch } from "../util/switch.js";
+import { ThroughSequence } from "./ThroughSequence.js";
+/** Async generator that switches on when it has iterators that are iterating, and off when all iterators are done. */
+export class SwitchingSequence extends ThroughSequence {
+    constructor(source, switchable) {
+        super(source);
+        this._switch = getSwitch(switchable);
+    }
+    async next() {
+        this._switch.start(this); // Register this in anticipation that it'll continue iterating.
+        try {
+            const result = await super.next();
+            if (result.done)
+                this._switch.stop(this); // Deregister this.
+            else
+                this._switch.start(this); // Register this.
+            return result;
+        }
+        catch (caught) {
+            this._switch.stop(this);
+            throw caught;
+        }
+    }
+    async return(value) {
+        try {
+            const result = await super.return(value);
+            if (result.done)
+                this._switch.stop(this); // Deregister this.
+            else
+                this._switch.start(this); // Stop this.
+            return result;
+        }
+        catch (caught) {
+            this._switch.stop(this);
+            throw caught;
+        }
+    }
+    async throw(reason) {
+        try {
+            const result = await super.throw(reason);
+            if (result.done)
+                this._switch.stop(this); // Deregister this.
+            else
+                this._switch.start(this); // Start this.
+            return result;
+        }
+        catch (caught) {
+            this._switch.stop(this);
+            throw caught;
+        }
+    }
+}

package/sequence/index.d.ts

@@ -1,6 +1,6 @@
 export * from "./AbstractSequence.js";
 export * from "./DeferredSequence.js";
 export * from "./InspectSequence.js";
-export * from "./RegisteringSequence.js";
-export * from "./LazyDeferredSequence.js";
+export * from "./SwitchingSequence.js";
+export * from "./SwitchingDeferredSequence.js";
 export * from "./ThroughSequence.js";

package/sequence/index.js

@@ -1,6 +1,6 @@
 export * from "./AbstractSequence.js";
 export * from "./DeferredSequence.js";
 export * from "./InspectSequence.js";
-export * from "./RegisteringSequence.js";
-export * from "./LazyDeferredSequence.js";
+export * from "./SwitchingSequence.js";
+export * from "./SwitchingDeferredSequence.js";
 export * from "./ThroughSequence.js";

package/state/State.d.ts

@@ -1,5 +1,4 @@
-import type { Stop } from "../util/activity.js";
-import type { Dispatch, Handler } from "../util/function.js";
+import type { Callback, ErrorCallback, StopCallback } from "../util/callback.js";
 import type { Validatable } from "../util/validate.js";
 import { DeferredSequence } from "../sequence/DeferredSequence.js";
 /** Any `State` instance. */
@@ -45,9 +44,9 @@ export declare class State<T> implements AsyncIterable<T>, Validatable<T> {
     /** Set the value of the state as values are pulled from a sequence. */
     through(sequence: AsyncIterable<T>): AsyncIterable<T>;
     /** Pull values from a source sequence until the returned stop function is called. */
-    from(source: AsyncIterable<T>, onError?: Handler): Stop;
+    from(source: AsyncIterable<T>, onError?: ErrorCallback): StopCallback;
     /** Push values to another state or callback to this state until the returned stop function is called. */
-    to(target: Dispatch<T>, onError?: Handler): Stop;
+    to(target: Callback<T>, onError?: ErrorCallback): StopCallback;
     [Symbol.asyncIterator](): AsyncIterator<T>;
     /** Validate data set on this state. */
     validate(value: T): T;

package/util/async.d.ts

@@ -1,4 +1,4 @@
-import type { Dispatch, Handler } from "./function.js";
+import type { Callback, ErrorCallback } from "./callback.js";
 /** Is a value an asynchronous value implementing a `then()` function. */
 export declare const isAsync: <T>(value: T | PromiseLike<T>) => value is PromiseLike<T>;
 /** Is a value a synchronous value. */
@@ -21,16 +21,16 @@ export declare function runMicrotasks(): Promise<void>;
 export declare abstract class AbstractPromise<T> extends Promise<T> {
     static get [Symbol.species](): PromiseConstructor;
     /** Resolve this promise with a value. */
-    protected readonly _resolve: Dispatch<T>;
+    protected readonly _resolve: Callback<T>;
     /** Reject this promise with a reason. */
-    protected readonly _reject: Handler;
+    protected readonly _reject: ErrorCallback;
     constructor();
 }
 /** Deferred allows you to access the internal resolve/reject callbacks of a `Promise` */
 export type Deferred<T> = {
     promise: Promise<T>;
-    resolve: Dispatch<T>;
-    reject: Handler;
+    resolve: Callback<T>;
+    reject: ErrorCallback;
 };
 /**
  * Get a deferred to access the `resolve()` and `reject()` functions of a promise.

package/util/callback.d.ts

@@ -0,0 +1,22 @@
+/** Callback function that receives a dispatched value. */
+export type Callback<T = void> = (value: T) => void;
+/** Callback function that receives a dispatched value. */
+export type AsyncCallback<T = void> = (value: T) => void | PromiseLike<void>;
+/** Callback function that handles an error. */
+export type ErrorCallback = (reason: Error | unknown) => void;
+/** Callback function that starts something (and returns an optional stop callback). */
+export type StartCallback<T> = (value: T) => StopCallback;
+/** Callback function that stops something. */
+export type StopCallback = () => void;
+/** Safely call a callback function (possibly with a value). */
+export declare function call(callback: () => void | PromiseLike<void>): void;
+export declare function call<T>(callback: (value: T) => void | PromiseLike<void>, value: T): void;
+/** Return a callback function that safely calls a callback function (possibly with a value). */
+export declare function called<T>(dispatcher: AsyncCallback<T>): Callback<T>;
+/** Safely call a callback method (possibly wth a value). */
+export declare function callMethod<M extends string | symbol>(obj: {
+    [K in M]: () => void | PromiseLike<void>;
+}, key: M): void;
+export declare function callMethod<T, M extends string | symbol>(obj: {
+    [K in M]: (value: T) => void | PromiseLike<void>;
+}, key: M, value: T): void;

package/util/callback.js

@@ -0,0 +1,26 @@
+import { isAsync } from "./async.js";
+import { logError } from "./error.js";
+export function call(callback, value) {
+    try {
+        const result = callback(value);
+        if (isAsync(result))
+            result.then(undefined, logError);
+    }
+    catch (thrown) {
+        logError(thrown);
+    }
+}
+/** Return a callback function that safely calls a callback function (possibly with a value). */
+export function called(dispatcher) {
+    return (value) => call(dispatcher, value);
+}
+export function callMethod(obj, key, value) {
+    try {
+        const result = obj[key](value);
+        if (isAsync(result))
+            result.then(undefined, logError);
+    }
+    catch (thrown) {
+        logError(thrown);
+    }
+}

package/util/class.d.ts

@@ -5,34 +5,9 @@ export type Constructor<T, A extends Arguments> = new (...args: A) => T;
 export type AnyConstructor = new (...args: any) => any;
 /** Class prototype that can be used with `instanceof` (string name, as per `Function`, and a prototype field matching the object). */
 export type Class<T> = new (...args: any) => T;
-export declare const abc: Class<String>;
 /** Is a given value a class constructor? */
 export declare const isConstructor: <T extends AnyConstructor>(value: unknown) => value is T;
 /** Is a value an instance of a class? */
 export declare const isInstance: <T>(value: unknown, type: Class<T>) => value is T;
 /** Assert that a value is an instance of something. */
 export declare function assertInstance<T>(value: T | unknown, type: Class<T>): asserts value is T;
-/** Decorator to bind a class method lazily on first access. */
-export declare function bindMethod<O, T, A>(target: O, key: string, { value: method }: TypedPropertyDescriptor<(...args: A[]) => T>): TypedPropertyDescriptor<(...args: A[]) => T>;
-/**
- * Decorator to cache the result of a class method.
- * - Use this if a method computes an expensive value and you want to use it multiple times.
- * - Gets the method's result the first time the property is accessed, then saves that returned value in the object forever.
- */
-export declare function cacheMethod<O, T, A extends Arguments>(target: O, key: string, { value: method }: TypedPropertyDescriptor<(this: O, ...args: A) => T>): TypedPropertyDescriptor<(this: O, ...args: A) => T>;
-/**
- * Decorator to cache the result of a class property getter.
- * - Gets the result the first time the property is accessed, then saves that returned value in the object forever.
- */
-export declare function cacheGetter<T>(target: Object, key: string, { get }: TypedPropertyDescriptor<T>): TypedPropertyDescriptor<T>;
-/**
- * Decorator to set a property on an class's prototype not the class itself.
- *
- * @example
- * 		class MyClass {
- * 			@setPrototype("myProp", "myValue!") readonly myProp!: string;
- * 		}
- */
-export declare function setPrototype<K extends PropertyKey, T>(key: K, value: T): (prototype: {
-    [J in K]: T;
-}, k: K) => void;

package/util/class.js

@@ -1,8 +1,5 @@
-/* eslint-disable @typescript-eslint/ban-types */
 import { AssertionError } from "../error/AssertionError.js";
 import { debug } from "./debug.js";
-import { assertFunction } from "./function.js";
-export const abc = String;
 /** Is a given value a class constructor? */
 export const isConstructor = (value) => typeof value === "function" && value.toString().startsWith("class");
 /** Is a value an instance of a class? */
@@ -12,61 +9,3 @@ export function assertInstance(value, type) {
     if (!(value instanceof type))
         throw new AssertionError(`Must be instance of ${debug(type)}`, value);
 }
-/** Decorator to bind a class method lazily on first access. */
-export function bindMethod(target, key, { value: method }) {
-    assertFunction(method);
-    return {
-        configurable: true,
-        get() {
-            const bound = method.bind(target);
-            Object.defineProperty(target, key, { value: bound, configurable: false, writable: false, enumerable: false });
-            return bound;
-        },
-    };
-}
-/**
- * Decorator to cache the result of a class method.
- * - Use this if a method computes an expensive value and you want to use it multiple times.
- * - Gets the method's result the first time the property is accessed, then saves that returned value in the object forever.
- */
-export function cacheMethod(target, key, { value: method }) {
-    assertFunction(method);
-    return {
-        configurable: true,
-        get() {
-            return (...args) => {
-                const value = method.call(target, ...args);
-                Object.defineProperty(target, key, { value: () => value, configurable: false, writable: false, enumerable: false });
-                return value;
-            };
-        },
-    };
-}
-/**
- * Decorator to cache the result of a class property getter.
- * - Gets the result the first time the property is accessed, then saves that returned value in the object forever.
- */
-export function cacheGetter(target, key, { get }) {
-    assertFunction(get);
-    return {
-        configurable: true,
-        get() {
-            const value = get.call(this);
-            Object.defineProperty(this, key, { value, configurable: false, writable: false, enumerable: false });
-            return value;
-        },
-    };
-}
-/**
- * Decorator to set a property on an class's prototype not the class itself.
- *
- * @example
- * 		class MyClass {
- * 			@setPrototype("myProp", "myValue!") readonly myProp!: string;
- * 		}
- */
-export function setPrototype(key, value) {
-    return (prototype) => {
-        prototype[key] = value;
-    };
-}

package/util/error.d.ts

@@ -1,3 +1,3 @@
 /** Handle an error by logging it to the console. */
-import type { Handler } from "./function.js";
-export declare const logError: Handler;
+import type { ErrorCallback } from "./callback.js";
+export declare const logError: ErrorCallback;

package/util/function.d.ts

@@ -12,19 +12,3 @@ export type Arguments = readonly unknown[];
 export declare const PASSTHROUGH: <T>(value: T) => T;
 /** Function that does nothing with its arguments and always returns void. */
 export declare const BLACKHOLE: (...args: Arguments) => void | undefined;
-/** Function that receives a dispatched value. */
-export type Dispatch<T = void> = (value: T) => void;
-/** Function that receives a dispatched value. */
-export type AsyncDispatch<T = void> = (value: T) => void | PromiseLike<void>;
-/** Safely dispatch a value to a dispatcher function. */
-export declare function dispatch(func: () => void | PromiseLike<void>): void;
-export declare function dispatch<T>(func: (value: T) => void | PromiseLike<void>, value: T): void;
-export declare function dispatch<T>(func: AsyncDispatch<T>, value: T): void;
-/** Return a function that dispatches a value to a dispatcher function. */
-export declare function dispatched<T>(dispatcher: Dispatch<T>): Dispatch<T>;
-/** Safely dispatch a value to a dispatcher method on an object. */
-export declare function dispatchMethod<T, M extends string | symbol>(obj: {
-    [K in M]: AsyncDispatch<T>;
-}, key: M, value: T): void;
-/** Function that handles an error. */
-export type Handler = (reason: Error | unknown) => void;

package/util/function.js

@@ -1,6 +1,4 @@
 import { AssertionError } from "../error/AssertionError.js";
-import { isAsync } from "./async.js";
-import { logError } from "./error.js";
 /** Is a value a function? */
 export const isFunction = (value) => typeof value === "function";
 /** Assert that a value is a function. */
@@ -12,28 +10,3 @@ export function assertFunction(value) {
 export const PASSTHROUGH = (value) => value;
 /** Function that does nothing with its arguments and always returns void. */
 export const BLACKHOLE = () => undefined;
-export function dispatch(func, value) {
-    try {
-        const result = func(value);
-        if (isAsync(result))
-            result.then(undefined, logError);
-    }
-    catch (thrown) {
-        logError(thrown);
-    }
-}
-/** Return a function that dispatches a value to a dispatcher function. */
-export function dispatched(dispatcher) {
-    return (value) => dispatch(dispatcher, value);
-}
-/** Safely dispatch a value to a dispatcher method on an object. */
-export function dispatchMethod(obj, key, value) {
-    try {
-        const result = obj[key](value);
-        if (isAsync(result))
-            result.then(BLACKHOLE, logError);
-    }
-    catch (thrown) {
-        logError(thrown);
-    }
-}

package/util/index.d.ts

@@ -1,4 +1,3 @@
-export * from "./activity.js";
 export * from "./array.js";
 export * from "./assert.js";
 export * from "./async.js";
@@ -35,6 +34,7 @@ export * from "./serialise.js";
 export * from "./sort.js";
 export * from "./source.js";
 export * from "./string.js";
+export * from "./switch.js";
 export * from "./template.js";
 export * from "./time.js";
 export * from "./timeout.js";

package/util/index.js

@@ -1,4 +1,3 @@
-export * from "./activity.js";
 export * from "./array.js";
 export * from "./assert.js";
 export * from "./async.js";
@@ -35,6 +34,7 @@ export * from "./serialise.js";
 export * from "./sort.js";
 export * from "./source.js";
 export * from "./string.js";
+export * from "./switch.js";
 export * from "./template.js";
 export * from "./time.js";
 export * from "./timeout.js";

package/util/sequence.d.ts

@@ -1,5 +1,4 @@
-import type { Stop } from "./activity.js";
-import type { AsyncDispatch, Dispatch, Handler } from "./function.js";
+import type { AsyncCallback, Callback, ErrorCallback, StopCallback } from "./callback.js";
 import { STOP } from "./constants.js";
 /**
  * Is a value an async iterable object?
@@ -12,8 +11,8 @@ export declare function repeatUntil<T>(source: AsyncIterable<T>, ...signals: [Pr
 /** 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>(sequence: AsyncIterable<T>, onNext: AsyncDispatch<T>): AsyncIterable<T>;
+export declare function dispatchSequence<T>(sequence: AsyncIterable<T>, onNext: AsyncCallback<T>): AsyncIterable<T>;
 /** Get the first value from an async iterator. **/
 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>(sequence: AsyncIterable<T>, onNext?: Dispatch<T>, onError?: Handler): Stop;
+export declare function runSequence<T>(sequence: AsyncIterable<T>, onNext?: Callback<T>, onError?: ErrorCallback): StopCallback;

package/util/sequence.js

@@ -1,8 +1,8 @@
 import { RequiredError } from "../error/RequiredError.js";
 import { getDeferred, getDelay } from "./async.js";
+import { call } from "./callback.js";
 import { STOP } from "./constants.js";
 import { logError } from "./error.js";
-import { dispatch } from "./function.js";
 /**
  * Is a value an async iterable object?
  * - Any object with a `Symbol.iterator` property is iterable.
@@ -38,7 +38,7 @@ export async function* repeatDelay(ms) {
 /** Dispatch items in a sequence to a (possibly async) callback. */
 export async function* dispatchSequence(sequence, onNext) {
     for await (const item of sequence) {
-        dispatch(onNext, item);
+        call(onNext, item);
         yield item;
     }
 }

package/util/switch.d.ts

@@ -0,0 +1,33 @@
+import type { StartCallback } from "./callback.js";
+/** Something that can be started or stopped. */
+export interface Switch<T> {
+    /** Start the thing. */
+    start(value: T): void;
+    /** Stop the thing. */
+    stop(value: T): void;
+}
+/** Something that can become an `Switch` */
+export type PossibleSwitch<T> = StartCallback<T> | Switch<T>;
+/**
+ * Wrap a `StartCallback` and create a `Switch`
+ * - Ensures that the start and stop callbacks are only called once.
+ */
+export declare class StartSwitch<T> implements Switch<T> {
+    private readonly _start;
+    private _stop;
+    constructor(start: StartCallback<T>);
+    start(v: T): void;
+    stop(): void;
+}
+/** Turn a possible switch into a switch. */
+export declare const getSwitch: <T>(v: PossibleSwitch<T>) => Switch<T>;
+/** Set of items that starts a switch when it has items and stops it when it has no items. */
+export declare class SwitchingSet<T> extends Set<T> implements Switch<T> {
+    private readonly _switch;
+    constructor(input: PossibleSwitch<Set<T>>);
+    add(value: T): this;
+    delete(value: T): boolean;
+    clear(): void;
+    start(value: T): void;
+    stop(value: T): void;
+}

package/util/switch.js

@@ -0,0 +1,49 @@
+import { isFunction } from "./function.js";
+/**
+ * Wrap a `StartCallback` and create a `Switch`
+ * - Ensures that the start and stop callbacks are only called once.
+ */
+export class StartSwitch {
+    constructor(start) {
+        this._stop = undefined;
+        this._start = start;
+    }
+    start(v) {
+        this._stop || (this._stop = this._start(v));
+    }
+    stop() {
+        if (this._stop)
+            this._stop = void this._stop();
+    }
+}
+/** Turn a possible switch into a switch. */
+export const getSwitch = (v) => (isFunction(v) ? new StartSwitch(v) : v);
+/** Set of items that starts a switch when it has items and stops it when it has no items. */
+export class SwitchingSet extends Set {
+    constructor(input) {
+        super();
+        this._switch = getSwitch(input);
+    }
+    add(value) {
+        super.add(value);
+        this._switch.start(this);
+        return this;
+    }
+    delete(value) {
+        const deleted = super.delete(value);
+        if (!this.size)
+            this._switch.stop(this);
+        return deleted;
+    }
+    clear() {
+        this.clear();
+        this._switch.stop(this);
+    }
+    // Implement `Switch`
+    start(value) {
+        this.add(value);
+    }
+    stop(value) {
+        this.delete(value);
+    }
+}

package/util/timeout.d.ts

@@ -1,4 +1,4 @@
-import type { Dispatch } from "./function.js";
+import type { Callback } from "./callback.js";
 /**
  * Create a new Timeout.
  *
@@ -13,7 +13,7 @@ export declare class Timeout {
     private _callback;
     private _ms;
     private _timeout;
-    constructor(callback?: Dispatch | null, ms?: number);
+    constructor(callback?: Callback | undefined, ms?: number);
     /** Is a timeout currently set? */
     get exists(): boolean;
     /**
@@ -21,8 +21,7 @@ export declare class Timeout {
      * @param callback
      * @param ms The delay for this timeout (in ms).
      */
-    set(callback?: Dispatch | null, ms?: number): void;
-    private _run;
+    set(callback?: Callback | undefined, ms?: number): void;
     /** Cancel any existing timeout.. */
     clear(): void;
 }

package/util/timeout.js

@@ -9,13 +9,8 @@
  * @param ms The default delay for any created timeouts (in ms).
  */
 export class Timeout {
-    constructor(callback = null, ms = 0) {
-        this._timeout = null;
-        this._run = () => {
-            this._timeout = null;
-            if (this._callback)
-                this._callback();
-        };
+    constructor(callback = undefined, ms = 0) {
+        this._timeout = undefined;
         this._callback = callback;
         this._ms = ms;
     }
@@ -37,7 +32,7 @@ export class Timeout {
     clear() {
         const timeout = this._timeout;
         if (timeout) {
-            this._timeout = null;
+            this._timeout = undefined;
             clearTimeout(timeout);
         }
     }

package/sequence/LazyDeferredSequence.d.ts

@@ -1,9 +0,0 @@
-import type { Start } from "../util/activity.js";
-import { DeferredSequence } from "./DeferredSequence.js";
-/** Deferred sequence of values that lazily calls a start function when it has iterators that are iterating, and stops the activity when all iterators are done. */
-export declare class LazyDeferredSequence<T = void, R = void> extends DeferredSequence<T, R> {
-    /** Store a list of iterators currently iterating over this iterable. */
-    private readonly _iterators;
-    constructor(start: Start<DeferredSequence<T, R>>);
-    [Symbol.asyncIterator](): AsyncGenerator<T, R, void>;
-}

package/sequence/LazyDeferredSequence.js

@@ -1,14 +0,0 @@
-import { LazySet } from "../util/activity.js";
-import { DeferredSequence } from "./DeferredSequence.js";
-import { RegisteringSequence } from "./RegisteringSequence.js";
-/** Deferred sequence of values that lazily calls a start function when it has iterators that are iterating, and stops the activity when all iterators are done. */
-export class LazyDeferredSequence extends DeferredSequence {
-    constructor(start) {
-        super();
-        this._iterators = new LazySet(() => start(this));
-    }
-    // Implement `AsyncIterable`
-    [Symbol.asyncIterator]() {
-        return new RegisteringSequence(this, this._iterators);
-    }
-}

package/sequence/RegisteringSequence.d.ts

@@ -1,9 +0,0 @@
-import { ThroughSequence } from "./ThroughSequence.js";
-/** Async generator that registers itself with a `Set` when it's iterating, and deregisters itself again when it stops. */
-export declare class RegisteringSequence<T, R> extends ThroughSequence<T, R> {
-    private _set;
-    constructor(source: AsyncIterator<T, R>, set: Set<AsyncIterator<T, R>>);
-    next(): Promise<IteratorResult<T, R>>;
-    return(value: R | PromiseLike<R>): Promise<IteratorResult<T, R>>;
-    throw(reason: Error | unknown): Promise<IteratorResult<T, R>>;
-}

package/sequence/RegisteringSequence.js

@@ -1,51 +0,0 @@
-import { ThroughSequence } from "./ThroughSequence.js";
-/** Async generator that registers itself with a `Set` when it's iterating, and deregisters itself again when it stops. */
-export class RegisteringSequence extends ThroughSequence {
-    constructor(source, set) {
-        super(source);
-        this._set = set;
-    }
-    async next() {
-        this._set.add(this); // Register this in anticipation that it'll continue iterating.
-        try {
-            const result = await super.next();
-            if (result.done)
-                this._set.delete(this); // Deregister this.
-            else
-                this._set.add(this); // Register this.
-            return result;
-        }
-        catch (caught) {
-            this._set.delete(this);
-            throw caught;
-        }
-    }
-    async return(value) {
-        try {
-            const result = await super.return(value);
-            if (result.done)
-                this._set.delete(this); // Deregister this.
-            else
-                this._set.add(this); // Register this.
-            return result;
-        }
-        catch (caught) {
-            this._set.delete(this);
-            throw caught;
-        }
-    }
-    async throw(reason) {
-        try {
-            const result = await super.throw(reason);
-            if (result.done)
-                this._set.delete(this); // Deregister this.
-            else
-                this._set.add(this); // Register this.
-            return result;
-        }
-        catch (caught) {
-            this._set.delete(this);
-            throw caught;
-        }
-    }
-}

package/util/activity.d.ts

@@ -1,34 +0,0 @@
-import type { Dispatch } from "./function.js";
-/** Function that starts something. */
-export type Start<T = void> = (value: T) => Stop | void;
-/** Function that stops something. */
-export type Stop = Dispatch;
-/** Something that can be started and stopped. */
-export interface Activity<T = void> {
-    /** Start this activity. */
-    start(value: T): void;
-    /** Stop this activity. */
-    stop(): void;
-}
-/** Wrap a `Start` function to create an `Activity` object. */
-export declare class StartActivity<T = void> implements Activity<T> {
-    private readonly _start;
-    private _stop;
-    constructor(start: Start<T>);
-    start(value: T): void;
-    stop(): void;
-}
-/** Set of items that starts/stops an `Activity` when it has items. */
-export declare class LazySet<T> extends Set<T> {
-    private readonly _activity;
-    constructor(start: Start<Set<T>>);
-    add(value: T): this;
-    delete(value: T): boolean;
-}
-/** Map of items that starts/stops an `Activity` when it has items. */
-export declare class LazyMap<K, T> extends Map<K, T> {
-    private readonly _activity;
-    constructor(start: Start<Map<K, T>>);
-    set(key: K, value: T): this;
-    delete(key: K): boolean;
-}

package/util/activity.js

@@ -1,50 +0,0 @@
-import { BLACKHOLE } from "./function.js";
-/** Wrap a `Start` function to create an `Activity` object. */
-export class StartActivity {
-    constructor(start) {
-        this._start = start;
-    }
-    start(value) {
-        this._stop || (this._stop = this._start(value) || BLACKHOLE);
-    }
-    stop() {
-        if (this._stop)
-            this._stop = void this._stop();
-    }
-}
-/** Set of items that starts/stops an `Activity` when it has items. */
-export class LazySet extends Set {
-    constructor(start) {
-        super();
-        this._activity = new StartActivity(start);
-    }
-    add(value) {
-        super.add(value);
-        this._activity.start(this);
-        return this;
-    }
-    delete(value) {
-        const deleted = super.delete(value);
-        if (!this.size)
-            this._activity.stop();
-        return deleted;
-    }
-}
-/** Map of items that starts/stops an `Activity` when it has items. */
-export class LazyMap extends Map {
-    constructor(start) {
-        super();
-        this._activity = new StartActivity(start);
-    }
-    set(key, value) {
-        super.set(key, value);
-        this._activity.start(this);
-        return this;
-    }
-    delete(key) {
-        const deleted = super.delete(key);
-        if (!this.size)
-            this._activity.stop();
-        return deleted;
-    }
-}