shelving 1.189.0 → 1.189.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.189.0",
+	"version": "1.189.2",
 	"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";
 /** 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>;
+    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

@@ -2,12 +2,13 @@ import { getFirst, getLast, omitArrayItems, requireArray, requireFirst, requireL
 import { Store } from "./Store.js";
 /** Store an array. */
 export class ArrayStore extends Store {
+    // 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,8 +1,9 @@
 import { Store } from "./Store.js";
 /** Store a boolean. */
 export declare class BooleanStore extends Store<unknown, boolean> {
-    convert(value: unknown): boolean;
+    constructor(value?: 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,16 +1,20 @@
 import { Store } from "./Store.js";
 /** Store a boolean. */
 export class BooleanStore extends Store {
+    // 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/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 { ValueStore } from "./ValueStore.js";
 /** Store a data object. */
-export declare class DataStore<T extends Data> extends Store<T, T> {
+export declare class DataStore<T extends Data> extends ValueStore<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 ValueStore<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 { ValueStore } from "./ValueStore.js";
 /** Store a data object. */
-export class DataStore extends Store {
+export class DataStore extends ValueStore {
     /** 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 ValueStore {
     /** 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

@@ -4,7 +4,7 @@ import { Store } from "./Store.js";
 /** Store a dictionary object. */
 export declare class DictionaryStore<T> extends Store<PossibleDictionary<T>, ImmutableDictionary<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

@@ -9,7 +9,7 @@ export class DictionaryStore extends Store {
         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

@@ -17,28 +17,25 @@ export declare class FetchStore<T> extends Store<T | typeof NONE, T> {
      */
     readonly busy: BooleanStore;
     get loading(): boolean;
-    get value(): T;
-    set value(value: T | typeof NONE | PromiseLike<T | typeof NONE>);
+    protected _convert(value: T | typeof NONE): T | typeof NONE;
+    protected _read(value: T | typeof NONE): T;
     constructor(value: T | typeof NONE, callback?: FetchCallback<T>);
-    convert(value: T | typeof NONE): T | typeof NONE;
     /**
      * 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;
+    await(pending: PromiseLike<T>): Promise<boolean>;
     /**
      * 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.
@@ -47,7 +44,7 @@ export declare class FetchStore<T> extends Store<T | typeof NONE, T> {
     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;
@@ -55,8 +52,8 @@ export declare class FetchStore<T> extends Store<T | typeof NONE, T> {
     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.
+     * - Sends `ABORT` to the current `AbortSignal` and clears the controller (a new signal will be created on the next read or fetch).
+     * - Clears the inflight promise or await and resets busy state.
      * - Any pending `await()` result will be silently discarded.
      */
     abort(): void;

package/store/FetchStore.js

@@ -16,55 +16,47 @@ export class FetchStore extends 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.
+    busy = new BooleanStore(false);
+    // Override to trigger a refresh when `this.loading` is read.
+    // Reading `loading` signals intent to use the value, so we optimistically start fetching so the value is available.
     get loading() {
         const loading = super.loading;
         if (loading || this._invalidation)
             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.
+    _convert(value) {
+        if (!isAsync(value))
+            this._invalidation = 0;
+        return value;
     }
-    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`
+    // Reading `value` signals intent to use the value, so we optimistically start fetching so the value is available.
+    _read(value) {
+        if (value === NONE)
+            void this.refresh();
+        return super._read(value);
     }
+    // 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 +65,24 @@ export class FetchStore extends Store {
             return false;
         }
     }
-    _inflight = undefined;
-    async _refresh(asyncValue) {
+    _pendingRefresh = undefined;
+    // Overload to set `this.busy` to `true` when we start awaiting a value.
+    // Gets set back to `false` when `abort()` is called.
+    await(pending) {
         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;
-        }
+        return super.await(pending);
     }
     /**
      * 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 +95,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();
@@ -121,14 +109,14 @@ export class FetchStore extends Store {
     }
     /**
      * 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.
+     * - Sends `ABORT` to the current `AbortSignal` and clears the controller (a new signal will be created on the next read or fetch).
+     * - Clears the inflight promise or await and resets busy state.
      * - Any pending `await()` result will be silently discarded.
      */
     abort() {
-        this._controller?.abort(ABORT);
-        this._controller = undefined;
-        this._inflight = undefined;
+        this._aborter?.abort(ABORT);
+        this._aborter = undefined;
+        this._pendingRefresh = undefined;
         this.busy.value = false;
         super.abort(); // clears _pendingValue
     }

package/store/LoadingStore.d.ts

@@ -2,9 +2,12 @@ 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.
+ * - Throws a `Promise` if the user attempts to read a store that is still loading (i.e. its value is still `NONE`).
+ *
+ * @example const v = this.value; // Might throw `Promise` if internal storage value is `NONE`
+ * @example if (!this.loading) const v = this.value; // Won't throw because we know the value is loaded.
  */
-export declare class LoadingStore<T> extends Store<T, T | typeof NONE> {
+export declare class LoadingStore<T> extends Store<T | typeof NONE, T> {
     constructor(value?: T | typeof NONE);
-    convert(value: T | typeof NONE): T | typeof NONE;
+    protected _convert(value: T | typeof NONE): T | typeof NONE;
 }

package/store/LoadingStore.js

@@ -2,15 +2,18 @@ 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.
+ * - Throws a `Promise` if the user attempts to read a store that is still loading (i.e. its value is still `NONE`).
+ *
+ * @example const v = this.value; // Might throw `Promise` if internal storage value is `NONE`
+ * @example if (!this.loading) const v = this.value; // Won't throw because we know the value is loaded.
  */
 export class LoadingStore extends Store {
     // Override to default to `NONE`
     constructor(value = NONE) {
         super(value);
     }
-    // Implement to allow `NONE`
-    convert(value) {
+    // Override to passthrough.
+    _convert(value) {
         return value;
     }
 }

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` */
+/**
+ * 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 Store<PossiblePath, AbsolutePath> {
     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,6 +1,11 @@
 import { isPathActive, isPathProud, requirePath } from "../util/path.js";
 import { Store } from "./Store.js";
-/** Store an absolute path, e.g. `/a/b/c` */
+/**
+ * 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 Store {
     base;
     // Override to set default path to `.` and base to `/`
@@ -8,10 +13,14 @@ export class PathStore extends Store {
         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/Store.d.ts

@@ -1,5 +1,5 @@
 import { DeferredSequence } from "../sequence/DeferredSequence.js";
-import { NONE, SKIP } from "../util/constants.js";
+import { NONE } from "../util/constants.js";
 import type { AnyCaller, Arguments } from "../util/function.js";
 import { type PossibleStarter } from "../util/start.js";
 /** Any `Store` instance. */
@@ -35,13 +35,6 @@ export declare abstract class Store<I, O> implements AsyncIterable<O, void, void
      * - 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.
@@ -51,10 +44,29 @@ export declare abstract class Store<I, O> implements AsyncIterable<O, void, void
      * - 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: I | PromiseLike<I>);
+    /**
+     * Convert input type to internal storage type.
+     * - Called only while getting values.
+     * - Override in subclasses to change getting behaviour.
+     */
+    protected abstract _convert(value: I, caller?: AnyCaller): O | typeof NONE;
+    /** 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;
+    /** Compare two values for this store and return whether they are equal. */
+    protected _equal(a: O, b: O): boolean;
+    /**
+     * 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(): O;
+    /**
+     * Called while reading values. Can be used to override get behaviour.
+     * - Override in subclasses to change getting behaviour.
+     */
+    protected _read(value: O | typeof NONE): O;
     /**
      * Time (in milliseconds) this store was last updated with a new value.
      * - Will be `undefined` if the value is still loading.
@@ -76,10 +88,11 @@ 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. */
+    /** Store is initiated with a value, or `NONE` to put it in a "loading" state. */
     constructor(value: O | typeof NONE);
     /** Set the value of this store as values are pulled from a sequence. */
     through(sequence: AsyncIterable<I>): AsyncIterable<I>;
@@ -87,7 +100,17 @@ export declare abstract class Store<I, O> implements AsyncIterable<O, void, void
      * 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.
+     * @param callback The callback function to call that should return a value to set on this store.
+     * 		@param args Any additional input values for the reducer.
+     * 		@returns New value for this store (possibly async).
+     * @param args Any arguments to pass to the callback.
+     *
+     * @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.
      */
     call<A extends Arguments>(callback: StoreCallback<I, A>, ...args: A): Promise<boolean> | boolean;
     /**
@@ -97,10 +120,14 @@ export declare abstract class Store<I, O> implements AsyncIterable<O, void, void
      * 		@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.
+     * @param 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.
+     *
+     * @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.
      */
     reduce<A extends Arguments>(reducer: StoreReducer<I, O, A>, ...args: A): Promise<boolean> | boolean;
     /**
@@ -111,11 +138,17 @@ 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;
+    private _pendingValue;
     /**
      * Abort any current pending `await()` call.
      * - The pending call's result will be silently discarded and its error will not be stored.
@@ -123,7 +156,5 @@ export declare abstract class Store<I, O> implements AsyncIterable<O, void, void
     abort(): void;
     [Symbol.asyncIterator](): AsyncIterator<O, 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,7 +1,6 @@
 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 { NONE } from "../util/constants.js";
 import { awaitDispose } from "../util/dispose.js";
 import { isDeepEqual } from "../util/equal.js";
 import { getStarter } from "../util/start.js";
@@ -32,20 +31,7 @@ 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;
-    }
-    /**
-     * 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() {
-        if (this._reason !== undefined)
-            throw this._reason;
-        if (this._value === NONE)
-            throw this.next;
-        return this._value;
+        return this._value === NONE && this.reason === undefined;
     }
     /**
      * Set the value of this store.
@@ -56,34 +42,54 @@ export class Store {
      * - 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) {
-        if (isAsync(value)) {
-            void this.await(value);
+    set value(input) {
+        if (isAsync(input)) {
+            void this.await(input);
         }
         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.
+            const storage = this._convert(input);
+            if (storage === NONE) {
+                // Put the store into a loading state.
                 this._time = undefined;
-                this._value = v;
+                this._value = storage;
                 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.
+            else if (this._value === NONE || !this._equal(storage, this._value)) {
+                // Set this changed value.
                 this._time = Date.now();
-                this._value = v;
-                this.next.resolve(v);
+                this._value = storage;
+                this.next.resolve(this._read(storage));
             }
         }
     }
+    /** Internal storage for current value. */
     _value;
+    /** Compare two values for this store and return whether they are equal. */
+    _equal(a, b) {
+        return isDeepEqual(a, b);
+    }
+    /**
+     * 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() {
+        if (this._reason !== undefined)
+            throw this._reason;
+        return this._read(this._value);
+    }
+    /**
+     * Called while reading values. Can be used to override get behaviour.
+     * - Override in subclasses to change getting behaviour.
+     */
+    _read(value) {
+        if (value === NONE)
+            throw this.next;
+        return value;
+    }
     /**
      * Time (in milliseconds) this store was last updated with a new value.
      * - Will be `undefined` if the value is still loading.
@@ -117,6 +123,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 +133,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();
@@ -142,7 +149,17 @@ export class Store {
      * 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.
+     * @param callback The callback function to call that should return a value to set on this store.
+     * 		@param args Any additional input values for the reducer.
+     * 		@returns New value for this store (possibly async).
+     * @param args Any arguments to pass to the callback.
+     *
+     * @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.
      */
     call(callback, ...args) {
         try {
@@ -164,10 +181,14 @@ export class 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.
+     * @param 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.
+     *
+     * @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.
      */
     reduce(reducer, ...args) {
         return this.call(reducer, this.value, ...args);
@@ -180,36 +201,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) {
+            if (this._pendingValue === pending) {
                 this.value = 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 +245,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,10 +259,6 @@ 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.

package/store/URLStore.d.ts

@@ -6,7 +6,8 @@ import { Store } from "./Store.js";
 export declare class URLStore extends Store<PossibleURL, URL> {
     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

@@ -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/ValueStore.d.ts

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

package/store/ValueStore.js

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