shelving 1.189.1 → 1.190.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.189.1",
+	"version": "1.190.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/store/ArrayStore.d.ts

@@ -1,11 +1,10 @@
 import type { ImmutableArray, PossibleArray } from "../util/array.js";
-import type { NONE } from "../util/constants.js";
 import type { AnyCaller } from "../util/function.js";
-import { Store } from "./Store.js";
+import { BusyStore } from "./BusyStore.js";
 /** Store an array. */
-export declare class ArrayStore<T> extends Store<PossibleArray<T>, ImmutableArray<T>> implements Iterable<T> {
-    constructor(value?: ImmutableArray<T> | typeof NONE);
-    convert(value: PossibleArray<T>, caller?: AnyCaller): ImmutableArray<T>;
+export declare class ArrayStore<T> extends BusyStore<ImmutableArray<T>, PossibleArray<T>> implements Iterable<T> {
+    constructor(value?: PossibleArray<T>);
+    protected _convert(input: PossibleArray<T>, caller: AnyCaller): ImmutableArray<T>;
     /** Get the first item in this store or `null` if this query has no items. */
     get optionalFirst(): T | undefined;
     /** Get the last item in this store or `null` if this query has no items. */

package/store/ArrayStore.js

@@ -1,13 +1,14 @@
 import { getFirst, getLast, omitArrayItems, requireArray, requireFirst, requireLast, toggleArrayItems, withArrayItems, } from "../util/array.js";
-import { Store } from "./Store.js";
+import { BusyStore } from "./BusyStore.js";
 /** Store an array. */
-export class ArrayStore extends Store {
+export class ArrayStore extends BusyStore {
+    // Override to set default value to `[]` and convert possible arrays.
     constructor(value = []) {
-        super(value);
+        super(requireArray(value, undefined, undefined, ArrayStore));
     }
-    // Implement to automatically convert `PossibleArray`
-    convert(value, caller = this.convert) {
-        return requireArray(value, undefined, undefined, caller);
+    // Implement to convert possible arrays.
+    _convert(input, caller) {
+        return requireArray(input, undefined, undefined, caller);
     }
     /** Get the first item in this store or `null` if this query has no items. */
     get optionalFirst() {

package/store/BooleanStore.d.ts

@@ -1,9 +1,9 @@
 import { Store } from "./Store.js";
 /** Store a boolean. */
-export declare class BooleanStore extends Store<unknown, boolean> {
+export declare class BooleanStore extends Store<boolean, unknown> {
     constructor(value?: boolean);
-    convert(value: unknown): boolean;
+    protected _convert(input: unknown): boolean;
+    protected _equal(a: boolean, b: boolean): boolean;
     /** Toggle the current boolean value. */
     toggle(): void;
-    isEqual(a: boolean, b: boolean): boolean;
 }

package/store/BooleanStore.js

@@ -1,20 +1,20 @@
 import { Store } from "./Store.js";
 /** Store a boolean. */
 export class BooleanStore extends Store {
-    // Override to set default value to false.
+    // Override to set default value to `false`
     constructor(value = false) {
         super(value);
     }
     // Override to automatically convert to boolean.
-    convert(value) {
-        return !!value;
+    _convert(input) {
+        return !!input;
+    }
+    // Override for fast equality.
+    _equal(a, b) {
+        return a === b;
     }
     /** Toggle the current boolean value. */
     toggle() {
         this.value = !this.value;
     }
-    // Override for fast equality.
-    isEqual(a, b) {
-        return a === b;
-    }
 }

package/store/BusyStore.d.ts

@@ -0,0 +1,12 @@
+import { BooleanStore } from "./BooleanStore.js";
+import { Store } from "./Store.js";
+/**
+ * Store that tracks its busy status via a separate `this.busy` store.
+ * - "busy" means the store is awaiting a new value.
+ */
+export declare class BusyStore<T, TT = T> extends Store<T, TT> {
+    readonly busy: BooleanStore;
+    await(pending: PromiseLike<TT>): Promise<boolean>;
+    abort(): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/store/BusyStore.js

@@ -0,0 +1,27 @@
+import { awaitDispose } from "../util/dispose.js";
+import { BooleanStore } from "./BooleanStore.js";
+import { Store } from "./Store.js";
+/**
+ * Store that tracks its busy status via a separate `this.busy` store.
+ * - "busy" means the store is awaiting a new value.
+ */
+export class BusyStore extends Store {
+    busy = new BooleanStore(false);
+    // Overload to set `this.busy` to `true` when we start awaiting a value.
+    // Gets set back to `false` when `abort()` is called (this also happens whenever a value or reason is set).
+    await(pending) {
+        this.busy.value = true;
+        return super.await(pending);
+    }
+    // Override to set busy to false on abort.
+    // This also happens whenever a value or reaosn is set.
+    abort() {
+        this.busy.value = false;
+        super.abort();
+    }
+    // Implement `AsyncDisposable`.
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(() => this.abort(), this.busy, // Send `done: true` to any iterators of the busy store.
+        super[Symbol.asyncDispose]());
+    }
+}

package/store/DataStore.d.ts

@@ -1,9 +1,9 @@
 import type { Data, DataKey } from "../util/data.js";
 import type { AnyCaller } from "../util/function.js";
 import type { Updates } from "../util/update.js";
-import { Store } from "./Store.js";
+import { BusyStore } from "./BusyStore.js";
 /** Store a data object. */
-export declare class DataStore<T extends Data> extends Store<T, T> {
+export declare class DataStore<T extends Data> extends BusyStore<T> {
     /** Get the data of this store. */
     get data(): T;
     /** Set the data of this store. */
@@ -14,10 +14,9 @@ export declare class DataStore<T extends Data> extends Store<T, T> {
     get<K extends DataKey<T>>(name: K): T[K];
     /** Update a single named prop in this data. */
     set<K extends DataKey<T>>(name: K, value: T[K]): void;
-    convert(value: T): T;
 }
 /** Store an optional data object. */
-export declare class OptionalDataStore<T extends Data> extends Store<T | undefined, T | undefined> {
+export declare class OptionalDataStore<T extends Data> extends BusyStore<T | undefined> {
     /** Get current data value of this store (or throw `Promise` that resolves to the next required value). */
     get data(): T;
     /** Set the data of this store. */
@@ -34,5 +33,4 @@ export declare class OptionalDataStore<T extends Data> extends Store<T | undefin
     set<K extends DataKey<T>>(name: K, value: T[K]): void;
     /** Set the data to `undefined`. */
     delete(): void;
-    convert(value: T): T;
 }

package/store/DataStore.js

@@ -2,9 +2,9 @@ import { RequiredError } from "../error/RequiredError.js";
 import { getGetter } from "../util/class.js";
 import { withProp } from "../util/object.js";
 import { updateData } from "../util/update.js";
-import { Store } from "./Store.js";
+import { BusyStore } from "./BusyStore.js";
 /** Store a data object. */
-export class DataStore extends Store {
+export class DataStore extends BusyStore {
     /** Get the data of this store. */
     get data() {
         return this.value;
@@ -25,13 +25,9 @@ export class DataStore extends Store {
     set(name, value) {
         this.value = withProp(this.data, name, value);
     }
-    // Implement to passthrough.
-    convert(value) {
-        return value;
-    }
 }
 /** Store an optional data object. */
-export class OptionalDataStore extends Store {
+export class OptionalDataStore extends BusyStore {
     /** Get current data value of this store (or throw `Promise` that resolves to the next required value). */
     get data() {
         return this.require(getGetter(this, "data"));
@@ -67,8 +63,4 @@ export class OptionalDataStore extends Store {
     delete() {
         this.value = undefined;
     }
-    // Implement to passthrough.
-    convert(value) {
-        return value;
-    }
 }

package/store/DictionaryStore.d.ts

@@ -1,10 +1,10 @@
 import type { DictionaryItem, ImmutableDictionary, PossibleDictionary } from "../util/dictionary.js";
 import type { Updates } from "../util/update.js";
-import { Store } from "./Store.js";
+import { BusyStore } from "./BusyStore.js";
 /** Store a dictionary object. */
-export declare class DictionaryStore<T> extends Store<PossibleDictionary<T>, ImmutableDictionary<T>> implements Iterable<DictionaryItem<T>> {
+export declare class DictionaryStore<T> extends BusyStore<ImmutableDictionary<T>, PossibleDictionary<T>> implements Iterable<DictionaryItem<T>> {
     constructor(value?: PossibleDictionary<T>);
-    convert(possible: PossibleDictionary<T>): ImmutableDictionary<T>;
+    protected _convert(possible: PossibleDictionary<T>): ImmutableDictionary<T>;
     /** Get the length of the current value of this store. */
     get count(): number;
     /** Set a named entry in this object with a different value. */

package/store/DictionaryStore.js

@@ -1,15 +1,15 @@
 import { EMPTY_DICTIONARY, getDictionaryItems, omitDictionaryItems, requireDictionary } from "../util/dictionary.js";
 import { omitProps, withProp } from "../util/object.js";
 import { updateData } from "../util/update.js";
-import { Store } from "./Store.js";
+import { BusyStore } from "./BusyStore.js";
 /** Store a dictionary object. */
-export class DictionaryStore extends Store {
+export class DictionaryStore extends BusyStore {
     // Override to set default value to empty dictionary.
     constructor(value = EMPTY_DICTIONARY) {
         super(requireDictionary(value));
     }
     // Override to convert a possible dictionary to a dictionary on set.
-    convert(possible) {
+    _convert(possible) {
         return requireDictionary(possible);
     }
     /** Get the length of the current value of this store. */

package/store/FetchStore.d.ts

@@ -1,6 +1,6 @@
-import { NONE } from "../util/constants.js";
-import { BooleanStore } from "./BooleanStore.js";
-import { Store } from "./Store.js";
+import { type NONE } from "../util/constants.js";
+import { BusyStore } from "./BusyStore.js";
+import type { StoreInput } from "./Store.js";
 /** Callback for a callback fetch store. */
 export type FetchCallback<T> = (signal: AbortSignal) => T | PromiseLike<T>;
 /**
@@ -8,57 +8,41 @@ export type FetchCallback<T> = (signal: AbortSignal) => T | PromiseLike<T>;
  *
  * @param value The initial value for the store, or `NONE` if it does not have one yet.
  * @param callback An optional callback that, if set, will be called when the `refresh()` method is invoked to fetch the next value.
+ * - Override `this._fetch()` in subclasses to define custom fetching behaviour for a subclass.
  */
-export declare class FetchStore<T> extends Store<T | typeof NONE, T> {
-    /**
-     * Store that indicates the busy state of this store.
-     * - `true` while a refresh is in-flight, `false` otherwise.
-     * - Can be subscribed to for e.g. loading spinners.
-     */
-    readonly busy: BooleanStore;
+export declare class FetchStore<T, TT = T> extends BusyStore<T, TT> {
     get loading(): boolean;
-    get value(): T;
-    set value(value: T | typeof NONE | PromiseLike<T | typeof NONE>);
-    constructor(value: T | typeof NONE, callback?: FetchCallback<T>);
-    convert(value: T | typeof NONE): T | typeof NONE;
+    write(input: StoreInput<TT>): void;
+    read(): import("./Store.js").StoreInternal<T>;
+    constructor(value: T | typeof NONE, callback?: FetchCallback<TT>);
     /**
      * Fetch the result for this store now.
      * - Triggered automatically when someone reads `value` or `loading`.
-     * - Concurrent calls while a fetch is in-flight return the same promise (deduplication).
+     * - Refreshes are de-duplicated. Concurrent calls while a fetch is in-flight return the same promise.
      * - Never throws — errors are stored as `reason`.
-     *
-     * @returns `true` if the fetch completed and the value was applied, `false` if aborted or superseded.
-     * @returns Synchronous `boolean` if the callback returned a synchronous value.
      */
     refresh(): Promise<boolean> | boolean;
-    private _inflight;
-    private _refresh;
+    private _pendingRefresh;
     /**
      * Current `AbortSignal` for this store's in-flight fetch.
      * - Created lazily; a new signal is issued each time `refresh()` starts a new fetch or `abort()` is called.
+     * - Triggers `abort()` so any current awaits are cancelled.
      */
     get signal(): AbortSignal;
-    private _controller;
+    private _aborter;
     /**
      * Call the fetch callback to get the next value.
      * @param signal `AbortSignal` for the current fetch — passed through to the callback so it can cancel HTTP requests etc.
      */
-    protected _fetch(signal: AbortSignal): T | PromiseLike<T>;
+    protected _fetch(signal: AbortSignal): TT | PromiseLike<TT>;
     private _callback;
     /**
      * Invalidate this store so a new fetch is triggered on the next read of `loading` or `value`.
-     * - Also aborts any current in-flight fetch.
+     * - Triggers `abort()` so any current awaits are cancelled.
      */
     invalidate(): void;
     private _invalidation;
     /** Re-fetch now if the current value is older than `maxAge` milliseconds or has been invalidated. */
-    refreshStale(maxAge: number): Promise<void>;
-    /**
-     * Abort any current in-flight fetch and pending async operation.
-     * - Aborts the current `AbortSignal` and clears the controller (a new signal will be created on the next read or fetch).
-     * - Clears the in-flight promise and resets busy state.
-     * - Any pending `await()` result will be silently discarded.
-     */
+    refreshStale(maxAge: number): Promise<boolean> | boolean;
     abort(): void;
-    [Symbol.asyncDispose](): Promise<void>;
 }

package/store/FetchStore.js

@@ -1,70 +1,56 @@
 import { RequiredError } from "../error/RequiredError.js";
 import { isAsync } from "../util/async.js";
-import { ABORT, NONE } from "../util/constants.js";
-import { awaitDispose } from "../util/dispose.js";
-import { BooleanStore } from "./BooleanStore.js";
-import { Store } from "./Store.js";
+import { ABORT, SKIP } from "../util/constants.js";
+import { BusyStore } from "./BusyStore.js";
 /**
  * Store that fetches its values from a remote source.
  *
  * @param value The initial value for the store, or `NONE` if it does not have one yet.
  * @param callback An optional callback that, if set, will be called when the `refresh()` method is invoked to fetch the next value.
+ * - Override `this._fetch()` in subclasses to define custom fetching behaviour for a subclass.
  */
-export class FetchStore extends Store {
-    /**
-     * Store that indicates the busy state of this store.
-     * - `true` while a refresh is in-flight, `false` otherwise.
-     * - Can be subscribed to for e.g. loading spinners.
-     */
-    busy;
-    // Override to possibly trigger a fetch when `this.loading` is read.
-    // Reading `loading` signals intent to use the value, so we start a fetch if needed.
+export class FetchStore extends BusyStore {
+    // Override to trigger a refresh when `this.loading` is read.
+    // Calling `store.loading` signals intent to use the value.
+    // We optimistically refresh so the value is available the next time the user wants it.
     get loading() {
         const loading = super.loading;
-        if (loading || this._invalidation)
+        if (this._invalidation || loading)
             void this.refresh();
         return loading;
     }
-    // Override to possibly trigger a fetch if `this.value` is still loading.
-    // Reading `value` signals intent to use the value, so we start a fetch if needed.
-    get value() {
-        if (super.loading)
-            void this.refresh();
-        return super.value;
+    // Override to reset the invalidation state.
+    // Setting a value means this store is no longer invalid.
+    write(input) {
+        if (input !== SKIP)
+            this._invalidation = 0;
+        super.write(input);
     }
-    set value(value) {
-        super.value = value; // calls Store.set value() which calls this.abort() then _applyValue()
-        // Setting a value resets the invalid state.
-        this._invalidation = 0;
+    // Override to trigger refresh on `NONE`
+    // Calling `store.value` signals intent to use the value.
+    // We optimistically refresh so the value is available the next time the user wants it.
+    read() {
+        this.loading; // Ping loading to possibly trigger the intiial fetch.
+        return super.read();
     }
+    // Override to create to save `callback`
     constructor(value, callback) {
         super(value);
-        this.busy = new BooleanStore(value === NONE);
         this._callback = callback;
     }
-    // Implement to allow `NONE`
-    convert(value) {
-        return value;
-    }
     /**
      * Fetch the result for this store now.
      * - Triggered automatically when someone reads `value` or `loading`.
-     * - Concurrent calls while a fetch is in-flight return the same promise (deduplication).
+     * - Refreshes are de-duplicated. Concurrent calls while a fetch is in-flight return the same promise.
      * - Never throws — errors are stored as `reason`.
-     *
-     * @returns `true` if the fetch completed and the value was applied, `false` if aborted or superseded.
-     * @returns Synchronous `boolean` if the callback returned a synchronous value.
      */
     refresh() {
-        if (this._inflight)
-            return this._inflight;
-        // Cancel any existing controller and create a fresh one for this fetch.
-        this._controller?.abort(ABORT);
-        this._controller = new AbortController();
+        if (this._pendingRefresh)
+            return this._pendingRefresh;
         try {
-            const value = this._fetch(this._controller.signal);
+            const value = this._fetch(this.signal); // Retrieving a new signal calls `abort()` which cancels the previous one.
             if (isAsync(value))
-                return (this._inflight = this._refresh(value));
+                return (this._pendingRefresh = this.await(value));
             this.value = value;
             return true;
         }
@@ -73,28 +59,18 @@ export class FetchStore extends Store {
             return false;
         }
     }
-    _inflight = undefined;
-    async _refresh(asyncValue) {
-        this.busy.value = true;
-        try {
-            const refreshed = await this.await(asyncValue);
-            if (refreshed)
-                this._invalidation = 0;
-            return refreshed;
-        }
-        finally {
-            this.busy.value = false;
-            this._inflight = undefined;
-        }
-    }
+    _pendingRefresh = undefined;
     /**
      * Current `AbortSignal` for this store's in-flight fetch.
      * - Created lazily; a new signal is issued each time `refresh()` starts a new fetch or `abort()` is called.
+     * - Triggers `abort()` so any current awaits are cancelled.
      */
     get signal() {
-        return (this._controller ||= new AbortController()).signal;
+        this.abort();
+        this._aborter = new AbortController();
+        return this._aborter.signal;
     }
-    _controller;
+    _aborter;
     /**
      * Call the fetch callback to get the next value.
      * @param signal `AbortSignal` for the current fetch — passed through to the callback so it can cancel HTTP requests etc.
@@ -107,7 +83,7 @@ export class FetchStore extends Store {
     _callback;
     /**
      * Invalidate this store so a new fetch is triggered on the next read of `loading` or `value`.
-     * - Also aborts any current in-flight fetch.
+     * - Triggers `abort()` so any current awaits are cancelled.
      */
     invalidate() {
         this.abort();
@@ -115,26 +91,18 @@ export class FetchStore extends Store {
     }
     _invalidation = 0;
     /** Re-fetch now if the current value is older than `maxAge` milliseconds or has been invalidated. */
-    async refreshStale(maxAge) {
+    refreshStale(maxAge) {
         if (this._invalidation || this.age > maxAge)
-            await this.refresh();
+            return this.refresh();
+        return true;
     }
-    /**
-     * Abort any current in-flight fetch and pending async operation.
-     * - Aborts the current `AbortSignal` and clears the controller (a new signal will be created on the next read or fetch).
-     * - Clears the in-flight promise and resets busy state.
-     * - Any pending `await()` result will be silently discarded.
-     */
+    // Override to abort any current in-flight fetch and pending async operation.
+    // - Sends `ABORT` to the current `AbortSignal` and clears the controller (a new signal will be created on the next read or fetch).
+    // - Any pending `await()` result will be silently discarded.
     abort() {
-        this._controller?.abort(ABORT);
-        this._controller = undefined;
-        this._inflight = undefined;
-        this.busy.value = false;
+        this._aborter?.abort(ABORT);
+        this._aborter = undefined;
+        this._pendingRefresh = undefined;
         super.abort(); // clears _pendingValue
     }
-    // Implement `AsyncDisposable`.
-    async [Symbol.asyncDispose]() {
-        await awaitDispose(() => this.abort(), this.busy, // Send `done: true` to any iterators of the busy store.
-        super[Symbol.asyncDispose]());
-    }
 }

package/store/PathStore.d.ts

@@ -1,11 +1,17 @@
 import type { AnyCaller } from "../util/function.js";
 import type { AbsolutePath, PossiblePath } from "../util/path.js";
-import { Store } from "./Store.js";
-/** Store an absolute path, e.g. `/a/b/c` */
-export declare class PathStore extends Store<PossiblePath, AbsolutePath> {
+import { BusyStore } from "./BusyStore.js";
+/**
+ * Store an absolute path, e.g. `/a/b/c`
+ *
+ * @param path: The initial value for the store.
+ * @param base: The base path to resolve relative paths against.
+ */
+export declare class PathStore extends BusyStore<AbsolutePath, PossiblePath> {
     readonly base: AbsolutePath;
     constructor(path?: string, base?: AbsolutePath);
-    convert(possible: PossiblePath, caller: AnyCaller): AbsolutePath;
+    protected _convert(possible: PossiblePath, caller: AnyCaller): AbsolutePath;
+    protected _equal(a: AbsolutePath, b: AbsolutePath): boolean;
     /** Based on the current store path, is a path active? */
     isActive(path: AbsolutePath): boolean;
     /** Based on the current store path, is a path proud (i.e. a child of the current store path)? */

package/store/PathStore.js

@@ -1,17 +1,26 @@
 import { isPathActive, isPathProud, requirePath } from "../util/path.js";
-import { Store } from "./Store.js";
-/** Store an absolute path, e.g. `/a/b/c` */
-export class PathStore extends Store {
+import { BusyStore } from "./BusyStore.js";
+/**
+ * Store an absolute path, e.g. `/a/b/c`
+ *
+ * @param path: The initial value for the store.
+ * @param base: The base path to resolve relative paths against.
+ */
+export class PathStore extends BusyStore {
     base;
     // Override to set default path to `.` and base to `/`
     constructor(path = ".", base = "/") {
         super(requirePath(path, base, PathStore));
         this.base = base;
     }
-    // Implement to convert a possible path to an absolute path (relative to `this.base`).
-    convert(possible, caller) {
+    // Override to convert a possible path to an absolute path (relative to `this.base`).
+    _convert(possible, caller) {
         return requirePath(possible, this.base, caller);
     }
+    // Override for fast equality.
+    _equal(a, b) {
+        return a === b;
+    }
     /** Based on the current store path, is a path active? */
     isActive(path) {
         return isPathActive(this.value, path);

package/store/PayloadFetchStore.d.ts

@@ -1,7 +1,7 @@
 import type { NONE } from "../util/constants.js";
 import { FetchStore } from "./FetchStore.js";
-import { ValueStore } from "./ValueStore.js";
-export type PayloadFetchCallback<P, R> = (payload: P) => R | PromiseLike<R>;
+import { Store } from "./Store.js";
+export type PayloadFetchCallback<P, R> = (payload: P, signal: AbortSignal) => R | PromiseLike<R>;
 /**
  * Store that fetches its values from a remote source by sending a payload to them.
  *
@@ -14,7 +14,7 @@ export declare class PayloadFetchStore<P, R> extends FetchStore<R> {
      * Store keeping the current payload to send to the fetch on send.
      * - New payloads can be set using `this.payload.value`
      */
-    readonly payload: ValueStore<P>;
+    readonly payload: Store<P>;
     constructor(payload: P, value: R | typeof NONE, callback?: PayloadFetchCallback<P, R>);
     [Symbol.asyncDispose](): Promise<void>;
 }

package/store/PayloadFetchStore.js

@@ -1,6 +1,6 @@
 import { awaitDispose } from "../util/dispose.js";
 import { FetchStore } from "./FetchStore.js";
-import { ValueStore } from "./ValueStore.js";
+import { Store } from "./Store.js";
 /**
  * Store that fetches its values from a remote source by sending a payload to them.
  *
@@ -16,8 +16,8 @@ export class PayloadFetchStore extends FetchStore {
     payload;
     // Override to save initial payload and callback.
     constructor(payload, value, callback) {
-        const payloadStore = new ValueStore(payload);
-        super(value, callback && (() => callback(payloadStore.value)));
+        const payloadStore = new Store(payload);
+        super(value, callback && (signal => callback(payloadStore.value, signal)));
         this.payload = payloadStore;
         void _iterate(this);
     }

package/store/Store.d.ts

@@ -4,10 +4,14 @@ import type { AnyCaller, Arguments } from "../util/function.js";
 import { type PossibleStarter } from "../util/start.js";
 /** Any `Store` instance. */
 export type AnyStore = Store<any, any>;
+/** Values that a store natively knows how to process as inputs. */
+export type StoreInput<I> = I | typeof SKIP | typeof NONE;
+/** Internal storage value for a store. */
+export type StoreInternal<O> = O | typeof NONE;
 /** Callback that sets a store's value (possibly asynchronously). */
-export type StoreCallback<I, A extends Arguments = []> = (...args: A) => I | PromiseLike<I>;
+export type StoreCallback<I, A extends Arguments = []> = (...args: A) => StoreInput<I> | PromiseLike<StoreInput<I>>;
 /** Reducer that receives a store's current value and sets the stores next value (possibly asynchronously). */
-export type StoreReducer<I, O, A extends Arguments = []> = (value: O, ...args: A) => I | PromiseLike<I>;
+export type StoreReducer<I, O, A extends Arguments = []> = (value: O, ...args: A) => StoreInput<I> | PromiseLike<StoreInput<I>>;
 /**
  * Store that retains its most recent value and is async-iterable to allow values to be observed.
  * - Current value can be read at `store.value` and `store.data`
@@ -18,43 +22,59 @@ export type StoreReducer<I, O, A extends Arguments = []> = (value: O, ...args: A
  * - To set this store to be loading, use the `NONE` constant or a `Promise` value.
  * - To set this store to an explicit value, use that value or another `Store` instance with a value.
  *
- * @param I The "input type" for this store.
- * - Indicates what values `this.value` can be set to.
+ * @param T The "main type" for this store.
+ * - Indicates what values `this.value` will return.
  * - Methods that set values like `this.call()` and `this.await()` can also accept these values.
- * @param O The "output type" for this store.
- * - Indicates what value `this.value` will return.
- * - Must extend the input type `I`.
- * - Defaults to I.
+ * @param TT The "input type" for this store.
+ * - Indicates what additional input types `this.value` can convert to `T`
+ * - Defaults to `T` (no conversion).
+ * - Override conversion by overriding `this._convert(v: TT): T`
+ * - Warning: With no override, default behaviour is to just assert TT is T (unsafe).
  */
-export declare abstract class Store<I, O> implements AsyncIterable<O, void, void>, AsyncDisposable {
+export declare class Store<T, TT = T> implements AsyncIterable<T, void, void>, AsyncDisposable {
     /** Deferred sequence this store uses to issue values as they change. */
-    readonly next: DeferredSequence<O, void, void>;
+    readonly next: DeferredSequence<T, void, void>;
     /**
      * Store is considered to be "loading" if it has no value or error.
      * - Calling `this.value` will throw `this.reason` if there's an error reason set, or a `Promise` if there's no value set.
      * - Calling `this.loading` is a way to check if this store has a value without triggering those throws.
      */
     get loading(): boolean;
-    /**
-     * Get the current value of this store.
-     *
-     * @throws {Promise} if this store currently has no value (resolves when this store receives its next value or error).
-     * @throws {unknown} if this store currently has an error.
-     */
-    get value(): O;
     /**
      * Set the value of this store.
      * - Sets any sync values.
      * - Awaits any async values.
      * - Setting value the `NONE` symbol indicates the store has no value so should be in a "loading" state.
-     * - Setting value to `SKIP` indicates the value should be silently ignored (sometimes it's helpful to have a way to skip setting entirely).
+     * - Setting value to `SKIP` indicates the value should be silently ignored (sometimes it's helpful to have a way to skip a write entirely).
      * - Setting value to the same as the existing value
      * - If this store has any pending `await()` calls they are aborted and their results are silently discarded.
      */
-    set value(value: I | PromiseLike<I>);
+    set value(input: StoreInput<TT> | PromiseLike<StoreInput<TT>>);
+    /** Write a synchronous value to this store. */
+    write(input: StoreInput<TT>): void;
+    /**
+     * Convert input type to internal storage type.
+     * - Override in subclasses to change conversion behaviour.
+     * - Warning: With no override, default behaviour is to just assert TT is T (unsafe).
+     */
+    protected _convert(input: TT, _caller?: AnyCaller): T;
+    /** Compare two values for this store and return whether they are equal. */
+    protected _equal(a: T, b: T): boolean;
+    /** Internal storage for current value. */
     private _value;
-    /** Convert a possible value for this store into an actual value of this store. */
-    abstract convert(possible: I, _caller?: AnyCaller): O | typeof NONE | typeof SKIP;
+    /**
+     * Get the current value of this store.
+     *
+     * @throws {Promise} if this store currently is in a "loading" state (resolves when a value is set).
+     * @throws {unknown} if this store currently has an error.
+     */
+    get value(): T;
+    /**
+     * Called to read values. Can be used to override get behaviour.
+     * - Override in subclasses to change getting behaviour.
+     * - Note: doesn't throw `reason` if there is one!
+     */
+    read(): StoreInternal<T>;
     /**
      * Time (in milliseconds) this store was last updated with a new value.
      * - Will be `undefined` if the value is still loading.
@@ -76,33 +96,30 @@ export declare abstract class Store<I, O> implements AsyncIterable<O, void, void
      * Set a starter for this store to allow a function to execute when this store has subscribers or not.
      *
      * @todo DH: Change this significantly. Not happy with how it's settable like this. It should be set in `constructor()`?
+     *  - Also would love some internal hooks
      */
     protected set starter(start: PossibleStarter<[this]>);
     private _starter;
-    /** Store is initiated with an initial store. */
-    constructor(value: O | typeof NONE);
+    /** Store is initiated with a value, or `NONE` to put it in a "loading" state. */
+    constructor(value: StoreInternal<T>);
     /** Set the value of this store as values are pulled from a sequence. */
-    through(sequence: AsyncIterable<I>): AsyncIterable<I>;
+    through(sequence: AsyncIterable<TT>): AsyncIterable<TT>;
     /**
-     * Call a callback that returns a new value (possibly async) for this store.
-     * - Errors are stored as `reason`; never throws.
-     *
-     * @returns `true` if the value was applied, `false` if an error occurred or the result was superseded.
+     * Call a callback and save the returned value to this store.
      */
-    call<A extends Arguments>(callback: StoreCallback<I, A>, ...args: A): Promise<boolean> | boolean;
+    call<A extends Arguments>(callback: StoreCallback<TT, A>, ...args: A): Promise<boolean> | boolean;
     /**
-     * Reduce the current value using a reducer callback that receives the current value.
-     *
-     * @param reducer The callback function to call that should return a value to set on this store.
-     * 		@param value The current value of this store.
-     * 		@param args Any additional input values for the reducer.
-     * 		@returns New value for this store (possibly async).
-     * @oaram args Any arguments to pass to the callback.
-     *
-     * @throws {Promise} if this store currently has no value (resolves when this store receives its next value or error).
-     * @throws {unknown} if this store currently has an error reason set.
+     * Send the current value to a callback and save the returned value to this store.
+     */
+    reduce<A extends Arguments>(reducer: StoreReducer<TT, T, A>, ...args: A): Promise<boolean> | boolean;
+    /**
+     * Run a callback and ignore any returned value.
+     */
+    run<A extends Arguments>(callback: (...args: A) => void | PromiseLike<void>, ...args: A): Promise<boolean> | boolean;
+    /**
+     * Send the current value to a callback and ignore any returned value.
      */
-    reduce<A extends Arguments>(reducer: StoreReducer<I, O, A>, ...args: A): Promise<boolean> | boolean;
+    send<A extends Arguments>(callback: (value: T, ...args: A) => void | PromiseLike<void>, ...args: A): Promise<boolean> | boolean;
     /**
      * Await an async value and save it to this store.
      * - Saves the resolved value.
@@ -111,19 +128,23 @@ export declare abstract class Store<I, O> implements AsyncIterable<O, void, void
      * - Silently discarded if `await()` is called again.
      * - Silently discarded if `abort()` is called.
      *
-     * @returns `true` if the value was applied, `false` if superseded, aborted, or errored.
+     * @param pending The pending value to await.
+     *
+     * @returns {true} If the callback returned a value and it was set.
+     * @returns {false} If the callback threw.
+     * @returns {Promise<true>} If the callback returned a promise and it resolved.
+     * @returns {Promise<false>} If the callback returned a promise and it rejected, or `abort()` was called before it resolved.
+     *
      * @throws {never} Never throws — safe to call without handling the return value.
      */
-    await(pending: PromiseLike<I>): Promise<boolean>;
-    private _pending;
+    await(pending: PromiseLike<StoreInput<TT>>): Promise<boolean>;
+    private _pendingValue;
     /**
      * Abort any current pending `await()` call.
      * - The pending call's result will be silently discarded and its error will not be stored.
      */
     abort(): void;
-    [Symbol.asyncIterator](): AsyncIterator<O, void, void>;
+    [Symbol.asyncIterator](): AsyncIterator<T, void, void>;
     private _iterating;
-    /** Compare two values for this store and return whether they are equal. */
-    isEqual(a: O, b: O): boolean;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/store/Store.js

@@ -1,6 +1,5 @@
 import { DeferredSequence } from "../sequence/DeferredSequence.js";
 import { isAsync } from "../util/async.js";
-import { getSetter } from "../util/class.js";
 import { NONE, SKIP } from "../util/constants.js";
 import { awaitDispose } from "../util/dispose.js";
 import { isDeepEqual } from "../util/equal.js";
@@ -15,13 +14,14 @@ import { getStarter } from "../util/start.js";
  * - To set this store to be loading, use the `NONE` constant or a `Promise` value.
  * - To set this store to an explicit value, use that value or another `Store` instance with a value.
  *
- * @param I The "input type" for this store.
- * - Indicates what values `this.value` can be set to.
+ * @param T The "main type" for this store.
+ * - Indicates what values `this.value` will return.
  * - Methods that set values like `this.call()` and `this.await()` can also accept these values.
- * @param O The "output type" for this store.
- * - Indicates what value `this.value` will return.
- * - Must extend the input type `I`.
- * - Defaults to I.
+ * @param TT The "input type" for this store.
+ * - Indicates what additional input types `this.value` can convert to `T`
+ * - Defaults to `T` (no conversion).
+ * - Override conversion by overriding `this._convert(v: TT): T`
+ * - Warning: With no override, default behaviour is to just assert TT is T (unsafe).
  */
 export class Store {
     /** Deferred sequence this store uses to issue values as they change. */
@@ -32,58 +32,82 @@ export class Store {
      * - Calling `this.loading` is a way to check if this store has a value without triggering those throws.
      */
     get loading() {
-        return this._value === NONE && this._reason === undefined;
+        return this._value === NONE && this.reason === undefined;
     }
+    /**
+     * Set the value of this store.
+     * - Sets any sync values.
+     * - Awaits any async values.
+     * - Setting value the `NONE` symbol indicates the store has no value so should be in a "loading" state.
+     * - Setting value to `SKIP` indicates the value should be silently ignored (sometimes it's helpful to have a way to skip a write entirely).
+     * - Setting value to the same as the existing value
+     * - If this store has any pending `await()` calls they are aborted and their results are silently discarded.
+     */
+    set value(input) {
+        if (isAsync(input))
+            void this.await(input);
+        else
+            this.write(input);
+    }
+    /** Write a synchronous value to this store. */
+    write(input) {
+        this.abort();
+        this._reason = undefined;
+        if (input === SKIP) {
+            // Skip this value entirely.
+            return;
+        }
+        else if (input === NONE) {
+            // Put the store into a loading state.
+            this._time = undefined;
+            this._value = NONE;
+            this.next.cancel();
+            return;
+        }
+        const storage = this._convert(input);
+        if (this._value === NONE || !this._equal(storage, this._value)) {
+            // Set this changed value.
+            this._time = Date.now();
+            this._value = storage;
+            this.next.resolve(storage);
+        }
+    }
+    /**
+     * Convert input type to internal storage type.
+     * - Override in subclasses to change conversion behaviour.
+     * - Warning: With no override, default behaviour is to just assert TT is T (unsafe).
+     */
+    _convert(input, _caller) {
+        return input;
+    }
+    /** Compare two values for this store and return whether they are equal. */
+    _equal(a, b) {
+        return isDeepEqual(a, b);
+    }
+    /** Internal storage for current value. */
+    _value;
     /**
      * Get the current value of this store.
      *
-     * @throws {Promise} if this store currently has no value (resolves when this store receives its next value or error).
+     * @throws {Promise} if this store currently is in a "loading" state (resolves when a value is set).
      * @throws {unknown} if this store currently has an error.
      */
     get value() {
         if (this._reason !== undefined)
             throw this._reason;
-        if (this._value === NONE)
+        const value = this.read();
+        if (value === NONE)
             throw this.next;
-        return this._value;
+        return value;
     }
     /**
-     * Set the value of this store.
-     * - Sets any sync values.
-     * - Awaits any async values.
-     * - Setting value the `NONE` symbol indicates the store has no value so should be in a "loading" state.
-     * - Setting value to `SKIP` indicates the value should be silently ignored (sometimes it's helpful to have a way to skip setting entirely).
-     * - Setting value to the same as the existing value
-     * - If this store has any pending `await()` calls they are aborted and their results are silently discarded.
+     * Called to read values. Can be used to override get behaviour.
+     * - Override in subclasses to change getting behaviour.
+     * - Note: doesn't throw `reason` if there is one!
      */
-    set value(value) {
-        if (isAsync(value)) {
-            void this.await(value);
-        }
-        else {
-            this.abort();
-            this._reason = undefined;
-            const v = value === NONE || value === SKIP
-                ? value || typeof SKIP
-                : this.convert(value, getSetter(this, "value"));
-            if (v === NONE) {
-                // Put the store back into a loading state.
-                this._time = undefined;
-                this._value = v;
-                this.next.cancel();
-            }
-            else if (v === SKIP) {
-                // Silently skip this set value call.
-            }
-            else if (this._value === NONE || !this.isEqual(v, this._value)) {
-                // Set this value.
-                this._time = Date.now();
-                this._value = v;
-                this.next.resolve(v);
-            }
-        }
+    read() {
+        return this._value;
     }
-    _value;
     /**
      * Time (in milliseconds) this store was last updated with a new value.
      * - Will be `undefined` if the value is still loading.
@@ -117,6 +141,7 @@ export class Store {
      * Set a starter for this store to allow a function to execute when this store has subscribers or not.
      *
      * @todo DH: Change this significantly. Not happy with how it's settable like this. It should be set in `constructor()`?
+     *  - Also would love some internal hooks
      */
     set starter(start) {
         if (this._starter)
@@ -126,7 +151,7 @@ export class Store {
             this._starter.start(this); // Start the new starter if we're already iterating.
     }
     _starter;
-    /** Store is initiated with an initial store. */
+    /** Store is initiated with a value, or `NONE` to put it in a "loading" state. */
     constructor(value) {
         this._value = value;
         this._time = value === NONE ? -Infinity : Date.now();
@@ -134,22 +159,19 @@ export class Store {
     /** Set the value of this store as values are pulled from a sequence. */
     async *through(sequence) {
         for await (const value of sequence) {
-            this.value = value;
+            this.write(value);
             yield value;
         }
     }
     /**
-     * Call a callback that returns a new value (possibly async) for this store.
-     * - Errors are stored as `reason`; never throws.
-     *
-     * @returns `true` if the value was applied, `false` if an error occurred or the result was superseded.
+     * Call a callback and save the returned value to this store.
      */
     call(callback, ...args) {
         try {
             const value = callback(...args);
             if (isAsync(value))
                 return this.await(value);
-            this.value = value;
+            this.write(value);
             return true;
         }
         catch (thrown) {
@@ -158,20 +180,23 @@ export class Store {
         }
     }
     /**
-     * Reduce the current value using a reducer callback that receives the current value.
-     *
-     * @param reducer The callback function to call that should return a value to set on this store.
-     * 		@param value The current value of this store.
-     * 		@param args Any additional input values for the reducer.
-     * 		@returns New value for this store (possibly async).
-     * @oaram args Any arguments to pass to the callback.
-     *
-     * @throws {Promise} if this store currently has no value (resolves when this store receives its next value or error).
-     * @throws {unknown} if this store currently has an error reason set.
+     * Send the current value to a callback and save the returned value to this store.
      */
     reduce(reducer, ...args) {
         return this.call(reducer, this.value, ...args);
     }
+    /**
+     * Run a callback and ignore any returned value.
+     */
+    run(callback, ...args) {
+        return this.call(_callSkipped, callback, ...args);
+    }
+    /**
+     * Send the current value to a callback and ignore any returned value.
+     */
+    send(callback, ...args) {
+        return this.call(_callSkipped, callback, this.value, ...args);
+    }
     /**
      * Await an async value and save it to this store.
      * - Saves the resolved value.
@@ -180,36 +205,42 @@ export class Store {
      * - Silently discarded if `await()` is called again.
      * - Silently discarded if `abort()` is called.
      *
-     * @returns `true` if the value was applied, `false` if superseded, aborted, or errored.
+     * @param pending The pending value to await.
+     *
+     * @returns {true} If the callback returned a value and it was set.
+     * @returns {false} If the callback threw.
+     * @returns {Promise<true>} If the callback returned a promise and it resolved.
+     * @returns {Promise<false>} If the callback returned a promise and it rejected, or `abort()` was called before it resolved.
+     *
      * @throws {never} Never throws — safe to call without handling the return value.
      */
     async await(pending) {
         // Keep track of the value that is being awaited.
         // If `_pendingValue` changes while waiting for `asyncValue` to resolve, another call to `await()` has `set value`, `set reason`, or `abort()` has invalidated this one.
         // If that happens we silently discard the resolved value/reason of this await call.
-        this._pending = pending;
+        this._pendingValue = pending;
         try {
             const value = await pending;
-            if (this._pending === pending) {
-                this.value = value;
+            if (this._pendingValue === pending) {
+                this.write(value);
                 return true;
             }
             return false;
         }
         catch (reason) {
-            if (this._pending === pending) {
+            if (this._pendingValue === pending) {
                 this.reason = reason;
             }
             return false;
         }
     }
-    _pending = undefined;
+    _pendingValue = undefined;
     /**
      * Abort any current pending `await()` call.
      * - The pending call's result will be silently discarded and its error will not be stored.
      */
     abort() {
-        this._pending = undefined;
+        this._pendingValue = undefined;
     }
     // Implement `AsyncIterator`
     // Issues the current value of this store first, then any subsequent values that are issued.
@@ -218,10 +249,11 @@ export class Store {
         this._starter?.start(this);
         this._iterating++;
         try {
-            if (this._reason !== undefined)
-                throw this._reason;
-            if (this._value !== NONE)
-                yield this._value;
+            const reason = this.reason;
+            if (reason !== undefined)
+                throw reason;
+            if (!this.loading)
+                yield this.value;
             yield* this.next;
         }
         finally {
@@ -231,13 +263,21 @@ export class Store {
         }
     }
     _iterating = 0;
-    /** Compare two values for this store and return whether they are equal. */
-    isEqual(a, b) {
-        return isDeepEqual(a, b);
-    }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {
         await awaitDispose(this._starter, // Stop the starter.
         this.next);
     }
 }
+/** Call a callback but always return or resolve to `SKIP` */
+function _callSkipped(callback, ...args) {
+    const value = callback(...args);
+    if (isAsync(value))
+        return _awaitSkipped(value);
+    return SKIP;
+}
+/** Await a promise but resolve to `SKIP` */
+async function _awaitSkipped(pending) {
+    await pending;
+    return SKIP;
+}

package/store/URLStore.d.ts

@@ -1,12 +1,13 @@
 import type { AnyCaller } from "../util/function.js";
 import { type PossibleURIParams, type URIParams, type URIScheme } from "../util/uri.js";
 import { type PossibleURL, type URL, type URLString } from "../util/url.js";
-import { Store } from "./Store.js";
+import { BusyStore } from "./BusyStore.js";
 /** Store a URL, e.g. `https://top.com/a/b/c` */
-export declare class URLStore extends Store<PossibleURL, URL> {
+export declare class URLStore extends BusyStore<URL, PossibleURL> {
     readonly base: URL | undefined;
     constructor(url: PossibleURL, base?: PossibleURL);
-    convert(value: PossibleURL, caller?: AnyCaller): URL;
+    protected _convert(value: PossibleURL, caller: AnyCaller): URL;
+    protected _equal(a: URL, b: URL): boolean;
     get href(): URLString;
     set href(href: URLString);
     get origin(): URLString;
@@ -45,6 +46,5 @@ export declare class URLStore extends Store<PossibleURL, URL> {
     omitParams(...keys: string[]): URL;
     /** Return the current URL with an additional param. */
     omitParam(key: string): URL;
-    isEqual(a: URL, b: URL): boolean;
     toString(): string;
 }

package/store/URLStore.js

@@ -1,9 +1,9 @@
 import { getGetter, getSetter } from "../util/class.js";
 import { clearURIParams, getURIParam, getURIParams, omitURIParams, requireURIParam, withURIParam, withURIParams, } from "../util/uri.js";
 import { getURL, requireURL } from "../util/url.js";
-import { Store } from "./Store.js";
+import { BusyStore } from "./BusyStore.js";
 /** Store a URL, e.g. `https://top.com/a/b/c` */
-export class URLStore extends Store {
+export class URLStore extends BusyStore {
     base;
     // Override to convert possible URL to URL.
     constructor(url, base) {
@@ -12,9 +12,13 @@ export class URLStore extends Store {
         this.base = baseURL;
     }
     // Override to convert possible URL to URL (relative to `this.base`).
-    convert(value, caller = this.convert) {
+    _convert(value, caller) {
         return requireURL(value, this.base, caller);
     }
+    // Override for fast equality.
+    _equal(a, b) {
+        return a.href === b.href;
+    }
     get href() {
         return this.value.href;
     }
@@ -101,10 +105,6 @@ export class URLStore extends Store {
     omitParam(key) {
         return omitURIParams(this.value, key);
     }
-    // Override `equal()` to just compare the hrefs.
-    isEqual(a, b) {
-        return a.href === b.href;
-    }
     toString() {
         return this.href;
     }

package/store/index.d.ts

@@ -3,9 +3,7 @@ export * from "./BooleanStore.js";
 export * from "./DataStore.js";
 export * from "./DictionaryStore.js";
 export * from "./FetchStore.js";
-export * from "./LoadingStore.js";
 export * from "./PathStore.js";
 export * from "./PayloadFetchStore.js";
 export * from "./Store.js";
 export * from "./URLStore.js";
-export * from "./ValueStore.js";

package/store/index.js

@@ -3,9 +3,7 @@ export * from "./BooleanStore.js";
 export * from "./DataStore.js";
 export * from "./DictionaryStore.js";
 export * from "./FetchStore.js";
-export * from "./LoadingStore.js";
 export * from "./PathStore.js";
 export * from "./PayloadFetchStore.js";
 export * from "./Store.js";
 export * from "./URLStore.js";
-export * from "./ValueStore.js";

package/store/LoadingStore.d.ts

@@ -1,10 +0,0 @@
-import { NONE } from "../util/constants.js";
-import { Store } from "./Store.js";
-/**
- * Store that is explicitly allows a "loading" state when it has no value (which is also the default value).
- * - Note: All stores have know how to interpret `NONE` — this subclass simply _allows_ that through its types.
- */
-export declare class LoadingStore<T> extends Store<T, T | typeof NONE> {
-    constructor(value?: T | typeof NONE);
-    convert(value: T | typeof NONE): T | typeof NONE;
-}

package/store/LoadingStore.js

@@ -1,16 +0,0 @@
-import { NONE } from "../util/constants.js";
-import { Store } from "./Store.js";
-/**
- * Store that is explicitly allows a "loading" state when it has no value (which is also the default value).
- * - Note: All stores have know how to interpret `NONE` — this subclass simply _allows_ that through its types.
- */
-export class LoadingStore extends Store {
-    // Override to default to `NONE`
-    constructor(value = NONE) {
-        super(value);
-    }
-    // Implement to allow `NONE`
-    convert(value) {
-        return value;
-    }
-}

package/store/ValueStore.d.ts

@@ -1,5 +0,0 @@
-import { Store } from "./Store.js";
-/** Store that just stores a simple value. */
-export declare class ValueStore<T> extends Store<T, T> {
-    convert(value: T): T;
-}

package/store/ValueStore.js

@@ -1,8 +0,0 @@
-import { Store } from "./Store.js";
-/** Store that just stores a simple value. */
-export class ValueStore extends Store {
-    // Implement to passthrough.
-    convert(value) {
-        return value;
-    }
-}