shelving 1.189.2 → 1.190.0

package/package.json

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

package/store/ArrayStore.d.ts

@@ -1,8 +1,8 @@
 import type { ImmutableArray, PossibleArray } from "../util/array.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> {
+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. */

package/store/ArrayStore.js

@@ -1,7 +1,7 @@
 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(requireArray(value, undefined, undefined, ArrayStore));

package/store/BooleanStore.d.ts

@@ -1,6 +1,6 @@
 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);
     protected _convert(input: unknown): boolean;
     protected _equal(a: boolean, b: boolean): boolean;

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 { ValueStore } from "./ValueStore.js";
+import { BusyStore } from "./BusyStore.js";
 /** Store a data object. */
-export declare class DataStore<T extends Data> extends ValueStore<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. */
@@ -16,7 +16,7 @@ export declare class DataStore<T extends Data> extends ValueStore<T> {
     set<K extends DataKey<T>>(name: K, value: T[K]): void;
 }
 /** Store an optional data object. */
-export declare class OptionalDataStore<T extends Data> extends ValueStore<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. */

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 { ValueStore } from "./ValueStore.js";
+import { BusyStore } from "./BusyStore.js";
 /** Store a data object. */
-export class DataStore extends ValueStore {
+export class DataStore extends BusyStore {
     /** Get the data of this store. */
     get data() {
         return this.value;
@@ -27,7 +27,7 @@ export class DataStore extends ValueStore {
     }
 }
 /** Store an optional data object. */
-export class OptionalDataStore extends ValueStore {
+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"));

package/store/DictionaryStore.d.ts

@@ -1,8 +1,8 @@
 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>);
     protected _convert(possible: PossibleDictionary<T>): ImmutableDictionary<T>;
     /** Get the length of the current value of this store. */

package/store/DictionaryStore.js

@@ -1,9 +1,9 @@
 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));

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,18 +8,13 @@ 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;
-    protected _convert(value: T | typeof NONE): T | typeof NONE;
-    protected _read(value: T | typeof NONE): T;
-    constructor(value: T | typeof NONE, callback?: FetchCallback<T>);
+    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`.
@@ -28,7 +23,6 @@ export declare class FetchStore<T> extends Store<T | typeof NONE, T> {
      */
     refresh(): Promise<boolean> | boolean;
     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.
@@ -40,7 +34,7 @@ export declare class FetchStore<T> extends Store<T | typeof NONE, T> {
      * 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`.
@@ -49,13 +43,6 @@ export declare class FetchStore<T> extends Store<T | typeof NONE, T> {
     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.
-     * - 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.
-     */
+    refreshStale(maxAge: number): Promise<boolean> | boolean;
     abort(): void;
-    [Symbol.asyncDispose](): Promise<void>;
 }

package/store/FetchStore.js

@@ -1,43 +1,37 @@
 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 = new BooleanStore(false);
+export class FetchStore extends BusyStore {
     // 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.
+    // 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 reset the invalidation state.
     // Setting a value means this store is no longer invalid.
-    _convert(value) {
-        if (!isAsync(value))
+    write(input) {
+        if (input !== SKIP)
             this._invalidation = 0;
-        return value;
+        super.write(input);
     }
     // 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);
+    // 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) {
@@ -66,12 +60,6 @@ export class FetchStore extends Store {
         }
     }
     _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;
-        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.
@@ -103,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.
-     * - 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.
-     */
+    // 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._aborter?.abort(ABORT);
         this._aborter = undefined;
         this._pendingRefresh = undefined;
-        this.busy.value = false;
         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,13 +1,13 @@
 import type { AnyCaller } from "../util/function.js";
 import type { AbsolutePath, PossiblePath } from "../util/path.js";
-import { Store } from "./Store.js";
+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 Store<PossiblePath, AbsolutePath> {
+export declare class PathStore extends BusyStore<AbsolutePath, PossiblePath> {
     readonly base: AbsolutePath;
     constructor(path?: string, base?: AbsolutePath);
     protected _convert(possible: PossiblePath, caller: AnyCaller): AbsolutePath;

package/store/PathStore.js

@@ -1,12 +1,12 @@
 import { isPathActive, isPathProud, requirePath } from "../util/path.js";
-import { Store } from "./Store.js";
+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 Store {
+export class PathStore extends BusyStore {
     base;
     // Override to set default path to `.` and base to `/`
     constructor(path = ".", base = "/") {

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

@@ -1,13 +1,17 @@
 import { DeferredSequence } from "../sequence/DeferredSequence.js";
-import { NONE } from "../util/constants.js";
+import { NONE, SKIP } from "../util/constants.js";
 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,17 +22,18 @@ 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.
@@ -40,33 +45,36 @@ export declare abstract class Store<I, O> implements AsyncIterable<O, void, void
      * - 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(input: 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.
-     * - Called only while getting values.
-     * - Override in subclasses to change getting behaviour.
+     * - Override in subclasses to change conversion behaviour.
+     * - Warning: With no override, default behaviour is to just assert TT is T (unsafe).
      */
-    protected abstract _convert(value: I, caller?: AnyCaller): O | typeof NONE;
+    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;
-    /** 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;
+    get value(): T;
     /**
-     * Called while reading values. Can be used to override get behaviour.
+     * 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!
      */
-    protected _read(value: O | typeof NONE): O;
+    read(): StoreInternal<T>;
     /**
      * Time (in milliseconds) this store was last updated with a new value.
      * - Will be `undefined` if the value is still loading.
@@ -93,43 +101,25 @@ export declare abstract class Store<I, O> implements AsyncIterable<O, void, void
     protected set starter(start: PossibleStarter<[this]>);
     private _starter;
     /** Store is initiated with a value, or `NONE` to put it in a "loading" state. */
-    constructor(value: O | typeof NONE);
+    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.
-     *
-     * @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 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).
-     * @param args Any arguments to pass to the callback.
-     *
-     * @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.
+     * 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.
@@ -147,14 +137,14 @@ export declare abstract class Store<I, O> implements AsyncIterable<O, void, void
      *
      * @throws {never} Never throws — safe to call without handling the return value.
      */
-    await(pending: PromiseLike<I>): Promise<boolean>;
+    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;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/store/Store.js

@@ -1,6 +1,6 @@
 import { DeferredSequence } from "../sequence/DeferredSequence.js";
 import { isAsync } from "../util/async.js";
-import { NONE } from "../util/constants.js";
+import { NONE, SKIP } from "../util/constants.js";
 import { awaitDispose } from "../util/dispose.js";
 import { isDeepEqual } from "../util/equal.js";
 import { getStarter } from "../util/start.js";
@@ -14,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. */
@@ -38,38 +39,53 @@ export class 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(input) {
-        if (isAsync(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 {
-            this.abort();
-            this._reason = undefined;
-            const storage = this._convert(input);
-            if (storage === NONE) {
-                // Put the store into a loading state.
-                this._time = undefined;
-                this._value = storage;
-                this.next.cancel();
-            }
-            else if (this._value === NONE || !this._equal(storage, this._value)) {
-                // Set this changed value.
-                this._time = Date.now();
-                this._value = storage;
-                this.next.resolve(this._read(storage));
-            }
+        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);
         }
     }
-    /** Internal storage for current value. */
-    _value;
+    /**
+     * 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.
      *
@@ -79,16 +95,18 @@ export class Store {
     get value() {
         if (this._reason !== undefined)
             throw this._reason;
-        return this._read(this._value);
+        const value = this.read();
+        if (value === NONE)
+            throw this.next;
+        return value;
     }
     /**
-     * Called while reading values. Can be used to override get behaviour.
+     * 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(value) {
-        if (value === NONE)
-            throw this.next;
-        return value;
+    read() {
+        return this._value;
     }
     /**
      * Time (in milliseconds) this store was last updated with a new value.
@@ -141,32 +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.
-     *
-     * @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 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) {
@@ -175,24 +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).
-     * @param args Any arguments to pass to the callback.
-     *
-     * @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.
+     * 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.
@@ -218,7 +222,7 @@ export class Store {
         try {
             const value = await pending;
             if (this._pendingValue === pending) {
-                this.value = value;
+                this.write(value);
                 return true;
             }
             return false;
@@ -265,3 +269,15 @@ export class Store {
         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,9 +1,9 @@
 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);
     protected _convert(value: PossibleURL, caller: AnyCaller): URL;

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) {

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,13 +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).
- * - 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 | typeof NONE, T> {
-    constructor(value?: T | typeof NONE);
-    protected _convert(value: T | typeof NONE): T | typeof NONE;
-}

package/store/LoadingStore.js

@@ -1,19 +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).
- * - 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);
-    }
-    // Override to passthrough.
-    _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 and does no conversion. */
-export declare class ValueStore<T> extends Store<T, T> {
-    protected _convert(value: T): T;
-}

package/store/ValueStore.js

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