shelving 1.188.6 → 1.189.0

package/api/endpoint/util.js

@@ -1,6 +1,6 @@
 import { MethodNotAllowedError, NotFoundError } from "../../error/RequestError.js";
 import { ValueError } from "../../error/ValueError.js";
-import { getDictionary } from "../../util/dictionary.js";
+import { requireDictionary } from "../../util/dictionary.js";
 import { getResponse, isRequestMethod, parseRequestBody } from "../../util/http.js";
 import { isPlainObject } from "../../util/object.js";
 import { requireURL } from "../../util/url.js";
@@ -19,7 +19,7 @@ export function handleEndpoints(base, handlers, request, context, caller = handl
         const pathParams = handler.endpoint.match(method, targetPath, caller);
         if (!pathParams)
             continue;
-        const params = searchParams.size ? { ...getDictionary(searchParams), ...pathParams } : pathParams;
+        const params = searchParams.size ? { ...requireDictionary(searchParams), ...pathParams } : pathParams;
         return _handleEndpoint(handler, params, request, context, handleEndpoints);
     }
     throw new NotFoundError("No matching endpoint", { received: targetPath, caller });

package/package.json

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

package/store/ArrayStore.d.ts

@@ -1,9 +1,11 @@
-import type { ImmutableArray } from "../util/array.js";
+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<ImmutableArray<T>> implements Iterable<T> {
+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>;
     /** 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,10 +1,14 @@
-import { getFirst, getLast, omitArrayItems, requireFirst, requireLast, toggleArrayItems, withArrayItems } from "../util/array.js";
+import { getFirst, getLast, omitArrayItems, requireArray, requireFirst, requireLast, toggleArrayItems, withArrayItems, } from "../util/array.js";
 import { Store } from "./Store.js";
 /** Store an array. */
 export class ArrayStore extends Store {
     constructor(value = []) {
         super(value);
     }
+    // Implement to automatically convert `PossibleArray`
+    convert(value, caller = this.convert) {
+        return requireArray(value, undefined, undefined, caller);
+    }
     /** Get the first item in this store or `null` if this query has no items. */
     get optionalFirst() {
         return getFirst(this.value);

package/store/BooleanStore.d.ts

@@ -1,8 +1,7 @@
-import type { NONE } from "../util/constants.js";
 import { Store } from "./Store.js";
 /** Store a boolean. */
-export declare class BooleanStore extends Store<boolean> {
-    constructor(value?: boolean | typeof NONE);
+export declare class BooleanStore extends Store<unknown, boolean> {
+    convert(value: unknown): boolean;
     /** Toggle the current boolean value. */
     toggle(): void;
     isEqual(a: boolean, b: boolean): boolean;

package/store/BooleanStore.js

@@ -1,8 +1,9 @@
 import { Store } from "./Store.js";
 /** Store a boolean. */
 export class BooleanStore extends Store {
-    constructor(value = false) {
-        super(value);
+    // Override to automatically convert to boolean.
+    convert(value) {
+        return !!value;
     }
     /** Toggle the current boolean value. */
     toggle() {

package/store/DataStore.d.ts

@@ -3,7 +3,7 @@ import type { AnyCaller } from "../util/function.js";
 import type { Updates } from "../util/update.js";
 import { Store } from "./Store.js";
 /** Store a data object. */
-export declare class DataStore<T extends Data> extends Store<T> {
+export declare class DataStore<T extends Data> extends Store<T, T> {
     /** Get the data of this store. */
     get data(): T;
     /** Set the data of this store. */
@@ -14,9 +14,10 @@ export declare class DataStore<T extends Data> extends Store<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> {
+export declare class OptionalDataStore<T extends Data> extends Store<T | undefined, 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. */
@@ -33,4 +34,5 @@ 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

@@ -25,6 +25,10 @@ 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 {
@@ -63,4 +67,8 @@ export class OptionalDataStore extends Store {
     delete() {
         this.value = undefined;
     }
+    // Implement to passthrough.
+    convert(value) {
+        return value;
+    }
 }

package/store/DictionaryStore.d.ts

@@ -1,9 +1,10 @@
-import type { DictionaryItem, ImmutableDictionary } from "../util/dictionary.js";
+import type { DictionaryItem, ImmutableDictionary, PossibleDictionary } from "../util/dictionary.js";
 import type { Updates } from "../util/update.js";
 import { Store } from "./Store.js";
 /** Store a dictionary object. */
-export declare class DictionaryStore<T> extends Store<ImmutableDictionary<T>> implements Iterable<DictionaryItem<T>> {
-    constructor(value?: ImmutableDictionary<T>);
+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>;
     /** 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,11 +1,16 @@
-import { getDictionaryItems, omitDictionaryItems } from "../util/dictionary.js";
+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";
 /** Store a dictionary object. */
 export class DictionaryStore extends Store {
-    constructor(value = {}) {
-        super(value);
+    // 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) {
+        return requireDictionary(possible);
     }
     /** Get the length of the current value of this store. */
     get count() {

package/store/FetchStore.d.ts

@@ -9,7 +9,7 @@ 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.
  */
-export declare class FetchStore<T> extends Store<T> {
+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.
@@ -20,6 +20,7 @@ export declare class FetchStore<T> extends Store<T> {
     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;
     /**
      * Fetch the result for this store now.
      * - Triggered automatically when someone reads `value` or `loading`.

package/store/FetchStore.js

@@ -1,6 +1,6 @@
 import { RequiredError } from "../error/RequiredError.js";
 import { isAsync } from "../util/async.js";
-import { ABORTED, NONE } from "../util/constants.js";
+import { ABORT, NONE } from "../util/constants.js";
 import { awaitDispose } from "../util/dispose.js";
 import { BooleanStore } from "./BooleanStore.js";
 import { Store } from "./Store.js";
@@ -42,6 +42,10 @@ export class FetchStore extends Store {
         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`.
@@ -55,7 +59,7 @@ export class FetchStore extends Store {
         if (this._inflight)
             return this._inflight;
         // Cancel any existing controller and create a fresh one for this fetch.
-        this._controller?.abort(ABORTED);
+        this._controller?.abort(ABORT);
         this._controller = new AbortController();
         try {
             const value = this._fetch(this._controller.signal);
@@ -122,7 +126,7 @@ export class FetchStore extends Store {
      * - Any pending `await()` result will be silently discarded.
      */
     abort() {
-        this._controller?.abort(ABORTED);
+        this._controller?.abort(ABORT);
         this._controller = undefined;
         this._inflight = undefined;
         this.busy.value = false;

package/store/LoadingStore.d.ts

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,16 @@
+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/PathStore.d.ts

@@ -1,10 +1,11 @@
-import type { AbsolutePath } from "../util/path.js";
+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<AbsolutePath> {
-    constructor(path?: string);
-    get value(): AbsolutePath;
-    set value(path: string);
+export declare class PathStore extends Store<PossiblePath, AbsolutePath> {
+    readonly base: AbsolutePath;
+    constructor(path?: string, base?: AbsolutePath);
+    convert(possible: PossiblePath, caller: AnyCaller): AbsolutePath;
     /** 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

@@ -2,15 +2,15 @@ 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 {
-    constructor(path = ".") {
-        super(requirePath(path));
+    base;
+    // Override to set default path to `.` and base to `/`
+    constructor(path = ".", base = "/") {
+        super(requirePath(path, base, PathStore));
+        this.base = base;
     }
-    // Override to clean the path on set.
-    get value() {
-        return super.value;
-    }
-    set value(path) {
-        super.value = requirePath(path, super.value);
+    // Implement to convert a possible path to an absolute path (relative to `this.base`).
+    convert(possible, caller) {
+        return requirePath(possible, this.base, caller);
     }
     /** Based on the current store path, is a path active? */
     isActive(path) {

package/store/PayloadFetchStore.d.ts

@@ -1,6 +1,6 @@
 import type { NONE } from "../util/constants.js";
 import { FetchStore } from "./FetchStore.js";
-import { Store } from "./Store.js";
+import { ValueStore } from "./ValueStore.js";
 export type PayloadFetchCallback<P, R> = (payload: P) => 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: Store<P>;
+    readonly payload: ValueStore<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 { Store } from "./Store.js";
+import { ValueStore } from "./ValueStore.js";
 /**
  * Store that fetches its values from a remote source by sending a payload to them.
  *
@@ -16,7 +16,7 @@ export class PayloadFetchStore extends FetchStore {
     payload;
     // Override to save initial payload and callback.
     constructor(payload, value, callback) {
-        const payloadStore = new Store(payload);
+        const payloadStore = new ValueStore(payload);
         super(value, callback && (() => callback(payloadStore.value)));
         this.payload = payloadStore;
         void _iterate(this);

package/store/Store.d.ts

@@ -1,9 +1,13 @@
 import { DeferredSequence } from "../sequence/DeferredSequence.js";
-import { NONE } from "../util/constants.js";
-import type { Arguments } from "../util/function.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>;
+export type AnyStore = Store<any, any>;
+/** Callback that sets a store's value (possibly asynchronously). */
+export type StoreCallback<I, A extends Arguments = []> = (...args: A) => I | PromiseLike<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>;
 /**
  * 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`
@@ -13,10 +17,18 @@ export type AnyStore = Store<any>;
  * @param initial The initial value for this store, a `Promise` that resolves to the initial value, a source `Subscribable` to subscribe to, or another `Store` instance to take the initial value from and subscribe to.
  * - 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.
+ * - 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.
  */
-export declare class Store<T> implements AsyncIterable<T, void, void>, AsyncDisposable {
+export declare abstract class Store<I, O> implements AsyncIterable<O, void, void>, AsyncDisposable {
     /** Deferred sequence this store uses to issue values as they change. */
-    readonly next: DeferredSequence<T, void, void>;
+    readonly next: DeferredSequence<O, 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.
@@ -29,14 +41,20 @@ export declare class Store<T> implements AsyncIterable<T, void, void>, AsyncDisp
      * @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(): T;
+    get value(): O;
     /**
-     * Set the value of this store .
-     * - Silently discards any pending `await()` calls.
+     * 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.
      */
-    set value(value: T | typeof NONE | PromiseLike<T | typeof NONE>);
+    set value(value: I | PromiseLike<I>);
     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;
     /**
      * Time (in milliseconds) this store was last updated with a new value.
      * - Will be `undefined` if the value is still loading.
@@ -62,16 +80,16 @@ export declare class Store<T> implements AsyncIterable<T, void, void>, AsyncDisp
     protected set starter(start: PossibleStarter<[this]>);
     private _starter;
     /** Store is initiated with an initial store. */
-    constructor(value: T | typeof NONE);
+    constructor(value: O | typeof NONE);
     /** Set the value of this store as values are pulled from a sequence. */
-    through(sequence: AsyncIterable<T>): AsyncIterable<T>;
+    through(sequence: AsyncIterable<I>): AsyncIterable<I>;
     /**
      * 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 extends Arguments = []>(callback: (...args: A) => T | PromiseLike<T>, ...args: A): Promise<boolean> | boolean;
+    call<A extends Arguments>(callback: StoreCallback<I, A>, ...args: A): Promise<boolean> | boolean;
     /**
      * Reduce the current value using a reducer callback that receives the current value.
      *
@@ -84,7 +102,7 @@ export declare class Store<T> implements AsyncIterable<T, void, void>, AsyncDisp
      * @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.
      */
-    reduce<A extends Arguments = []>(reducer: (value: T, ...args: A) => T | PromiseLike<T>, ...args: A): Promise<boolean> | boolean;
+    reduce<A extends Arguments>(reducer: StoreReducer<I, O, A>, ...args: A): Promise<boolean> | boolean;
     /**
      * Await an async value and save it to this store.
      * - Saves the resolved value.
@@ -96,16 +114,16 @@ export declare class Store<T> implements AsyncIterable<T, void, void>, AsyncDisp
      * @returns `true` if the value was applied, `false` if superseded, aborted, or errored.
      * @throws {never} Never throws — safe to call without handling the return value.
      */
-    await(asyncValue: PromiseLike<T | typeof NONE>): Promise<boolean>;
-    private _pendingValue;
+    await(pending: PromiseLike<I>): Promise<boolean>;
+    private _pending;
     /**
      * 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<T, void, void>;
+    [Symbol.asyncIterator](): AsyncIterator<O, void, void>;
     private _iterating;
     /** Compare two values for this store and return whether they are equal. */
-    isEqual(a: T, b: T): boolean;
+    isEqual(a: O, b: O): boolean;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/store/Store.js

@@ -1,6 +1,7 @@
 import { DeferredSequence } from "../sequence/DeferredSequence.js";
 import { isAsync } from "../util/async.js";
-import { NONE } from "../util/constants.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";
 import { getStarter } from "../util/start.js";
@@ -13,6 +14,14 @@ import { getStarter } from "../util/start.js";
  * @param initial The initial value for this store, a `Promise` that resolves to the initial value, a source `Subscribable` to subscribe to, or another `Store` instance to take the initial value from and subscribe to.
  * - 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.
+ * - 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.
  */
 export class Store {
     /** Deferred sequence this store uses to issue values as they change. */
@@ -39,9 +48,13 @@ export class Store {
         return this._value;
     }
     /**
-     * Set the value of this store .
-     * - Silently discards any pending `await()` calls.
+     * 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.
      */
     set value(value) {
         if (isAsync(value)) {
@@ -50,15 +63,23 @@ export class Store {
         else {
             this.abort();
             this._reason = undefined;
-            if (value === NONE) {
+            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 = value;
+                this._value = v;
                 this.next.cancel();
             }
-            else if (this._value === NONE || !this.isEqual(value, this._value)) {
+            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 = value;
-                this.next.resolve(value);
+                this._value = v;
+                this.next.resolve(v);
             }
         }
     }
@@ -162,33 +183,33 @@ export class Store {
      * @returns `true` if the value was applied, `false` if superseded, aborted, or errored.
      * @throws {never} Never throws — safe to call without handling the return value.
      */
-    async await(asyncValue) {
+    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._pendingValue = asyncValue;
+        this._pending = pending;
         try {
-            const value = await asyncValue;
-            if (this._pendingValue === asyncValue) {
+            const value = await pending;
+            if (this._pending === pending) {
                 this.value = value;
                 return true;
             }
             return false;
         }
         catch (reason) {
-            if (this._pendingValue === asyncValue) {
+            if (this._pending === pending) {
                 this.reason = reason;
             }
             return false;
         }
     }
-    _pendingValue = undefined;
+    _pending = 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._pendingValue = undefined;
+        this._pending = undefined;
     }
     // Implement `AsyncIterator`
     // Issues the current value of this store first, then any subsequent values that are issued.

package/store/URLStore.d.ts

@@ -1,12 +1,12 @@
+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";
 /** Store a URL, e.g. `https://top.com/a/b/c` */
-export declare class URLStore extends Store<URL> {
+export declare class URLStore extends Store<PossibleURL, URL> {
     readonly base: URL | undefined;
     constructor(url: PossibleURL, base?: PossibleURL);
-    set value(url: PossibleURL);
-    get value(): URL;
+    convert(value: PossibleURL, caller?: AnyCaller): URL;
     get href(): URLString;
     set href(href: URLString);
     get origin(): URLString;

package/store/URLStore.js

@@ -5,22 +5,21 @@ import { Store } from "./Store.js";
 /** Store a URL, e.g. `https://top.com/a/b/c` */
 export class URLStore extends Store {
     base;
+    // Override to convert possible URL to URL.
     constructor(url, base) {
         const baseURL = getURL(base);
-        super(requireURL(url, baseURL));
+        super(requireURL(url, baseURL, URLStore));
         this.base = baseURL;
     }
-    set value(url) {
-        super.value = requireURL(url, this.base, getSetter(this, "value"));
-    }
-    get value() {
-        return super.value;
+    // Override to convert possible URL to URL (relative to `this.base`).
+    convert(value, caller = this.convert) {
+        return requireURL(value, this.base, caller);
     }
     get href() {
         return this.value.href;
     }
     set href(href) {
-        this.value = requireURL(href, this.base, getSetter(this, "href"));
+        this.value = href;
     }
     get origin() {
         return this.value.origin;

package/store/ValueStore.d.ts

@@ -0,0 +1,5 @@
+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

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

package/store/index.d.ts

@@ -3,7 +3,9 @@ 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,7 +3,9 @@ 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/util/constants.d.ts

@@ -30,7 +30,9 @@ export declare const NBSP = "\u00A0";
 export declare const THINSP = "\u2009";
 /** Non-breaking narrow space (goes between numbers and their corresponding units). */
 export declare const NNBSP = "\u202F";
-/** The `ABORTED` symbol indicates something was manually aborted. */
-export declare const ABORTED: unique symbol;
+/** The `ABORT` symbol indicates something was manually aborted. */
+export declare const ABORT: unique symbol;
 /** The `NONE` symbol indicates something is nothing. */
 export declare const NONE: unique symbol;
+/** The `SKIP` symbol indicates something should be silently skipped. */
+export declare const SKIP: unique symbol;

package/util/constants.js

@@ -30,7 +30,9 @@ export const NBSP = "\xA0";
 export const THINSP = "\u2009";
 /** Non-breaking narrow space (goes between numbers and their corresponding units). */
 export const NNBSP = "\u202F";
-/** The `ABORTED` symbol indicates something was manually aborted. */
-export const ABORTED = Symbol("shelving/ABORTED");
+/** The `ABORT` symbol indicates something was manually aborted. */
+export const ABORT = Symbol("shelving/ABORT");
 /** The `NONE` symbol indicates something is nothing. */
 export const NONE = Symbol("shelving/NONE");
+/** The `SKIP` symbol indicates something should be silently skipped. */
+export const SKIP = Symbol("shelving/SKIP");

package/util/data.d.ts

@@ -84,9 +84,6 @@ export type FlatData<T extends NestedData> = Resolve<UnionToIntersection<T[keyof
 export declare function isData(value: unknown): value is Data;
 /** Assert that an unknown value is a data object. */
 export declare function assertData(value: unknown, caller?: AnyCaller): asserts value is Data;
-/** Convert a data object or set of `DataProp` props for that object back into the full object. */
-export declare function getData<T extends Data>(input: T): T;
-export declare function getData<T extends Data>(input: T | Iterable<DataProp<T>>): Partial<T>;
 /** Is an unknown value the key for an own prop of a data object. */
 export declare const isDataProp: <T extends Data>(data: T, key: unknown) => key is DataKey<T>;
 /** Assert that an unknown value is the key for an own prop of a data object. */

package/util/data.js

@@ -1,5 +1,4 @@
 import { RequiredError } from "../error/RequiredError.js";
-import { isIterable } from "./iterate.js";
 import { isObject, isPlainObject } from "./object.js";
 /** Is an unknown value a data object? */
 export function isData(value) {
@@ -10,9 +9,6 @@ export function assertData(value, caller = assertData) {
     if (!isPlainObject(value))
         throw new RequiredError("Must be data object", { received: value, caller });
 }
-export function getData(input) {
-    return isIterable(input) ? Object.fromEntries(input) : input;
-}
 /** Is an unknown value the key for an own prop of a data object. */
 export const isDataProp = (data, key) => typeof key === "string" && Object.hasOwn(data, key);
 /** Assert that an unknown value is the key for an own prop of a data object. */

package/util/dictionary.d.ts

@@ -18,7 +18,7 @@ export declare function isDictionary(value: unknown): value is ImmutableDictiona
 /** Assert that an unknown value is a dictionary object */
 export declare function assertDictionary(value: unknown, caller?: AnyCaller): asserts value is ImmutableDictionary;
 /** Convert a possible dictionary into a dictionary. */
-export declare function getDictionary<T>(dict: PossibleDictionary<T>): ImmutableDictionary<T>;
+export declare function requireDictionary<T>(dict: PossibleDictionary<T>): ImmutableDictionary<T>;
 /** Turn a dictionary object into a set of props. */
 export declare function getDictionaryItems<T>(input: ImmutableDictionary<T>): readonly DictionaryItem<T>[];
 export declare function getDictionaryItems<T>(input: PossibleDictionary<T>): Iterable<DictionaryItem<T>>;

package/util/dictionary.js

@@ -12,7 +12,7 @@ export function assertDictionary(value, caller = assertDictionary) {
         throw new ValueError("Must be dictionary object", { received: value, caller });
 }
 /** Convert a possible dictionary into a dictionary. */
-export function getDictionary(dict) {
+export function requireDictionary(dict) {
     return isDictionary(dict) ? dict : Object.fromEntries(dict);
 }
 export function getDictionaryItems(input) {

package/util/path.d.ts

@@ -6,10 +6,12 @@ export type AbsolutePath = `/` | `/${string}`;
 export type RelativePath = `.` | `./${string}` | `..` | `../${string}`;
 /** Either an absolute path string or a relative path string. */
 export type Path = AbsolutePath | RelativePath;
+/** Things that can be converted to a path. */
+export type PossiblePath = string | URL;
 /** Is a string path an absolute path? */
-export declare function isAbsolutePath(path: string): path is AbsolutePath;
+export declare function isAbsolutePath(path: Path): path is AbsolutePath;
 /** Is a string path an absolute path? */
-export declare function isRelativePath(path: string): path is RelativePath;
+export declare function isRelativePath(path: Path): path is RelativePath;
 /**
  * Resolve a relative or absolute path and return the absolute path, or `undefined` if not a valid path.
  * - Uses `new URL` to do path processing, so URL strings can also be resolved.
@@ -19,7 +21,7 @@ export declare function isRelativePath(path: string): path is RelativePath;
  * @param base Absolute path used for resolving relative paths in `possible`
  * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
  */
-export declare function getPath(value: Nullish<string | URL>, base?: AbsolutePath): AbsolutePath | undefined;
+export declare function getPath(value: Nullish<PossiblePath>, base?: AbsolutePath): AbsolutePath | undefined;
 /**
  * Resolve a relative or absolute path and return the path, or throw `RequiredError` if not a valid path.
  * - Internally uses `new URL` to do path processing but shouldn't ever reveal that fact.
@@ -29,7 +31,7 @@ export declare function getPath(value: Nullish<string | URL>, base?: AbsolutePat
  * @param base Absolute path used for resolving relative paths in `possible`
  * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
  */
-export declare function requirePath(value: string | URL, base?: AbsolutePath, caller?: AnyCaller): AbsolutePath;
+export declare function requirePath(value: PossiblePath, base?: AbsolutePath, caller?: AnyCaller): AbsolutePath;
 /** Is a target path active? */
 export declare function isPathActive(target: AbsolutePath, current: AbsolutePath): boolean;
 /** Is a target path proud (i.e. is the current path, or is a child of the current path)? */

package/util/path.js

@@ -42,7 +42,7 @@ export function getPath(value, base) {
 export function requirePath(value, base, caller = requirePath) {
     const path = getPath(value, base);
     if (!path)
-        throw new RequiredError("Invalid URL", { received: value, caller });
+        throw new RequiredError("Invalid path", { received: value, caller });
     return path;
 }
 /** Is a target path active? */

package/util/sequence.d.ts

@@ -1,7 +1,7 @@
-import { ABORTED } from "./constants.js";
+import { ABORT } from "./constants.js";
 import type { ErrorCallback, ValueCallback } from "./function.js";
 export interface IteratorAbortResult<R> {
-    done: typeof ABORTED;
+    done: typeof ABORT;
     value: R;
 }
 /** An extension of  */

package/util/sequence.js

@@ -1,9 +1,9 @@
 import { UnexpectedError } from "../error/UnexpectedError.js";
 import { getDeferred, getDelay } from "./async.js";
-import { ABORTED } from "./constants.js";
+import { ABORT } from "./constants.js";
 /** Turn a `Promise<R>` into an `IteratorAbortResult<R>` */
 async function _awaitAbort(value) {
-    return { done: ABORTED, value: await value };
+    return { done: ABORT, value: await value };
 }
 /** Call an iterator's `return()` method (if it exists) with an initial value, and return the `value` it returns. */
 async function _iteratorReturn(iterator, initial, caller) {
@@ -35,7 +35,7 @@ export async function* repeatUntil(source, ...signals) {
             ]);
             if (done) {
                 // For aborts, tell the iterator we're no longer using it.
-                if (done === ABORTED)
+                if (done === ABORT)
                     return _iteratorReturn(iterator, value, repeatUntil);
                 // Don't need to do this for `done: true` results from the iterator, because we assume the iterator stopped itself.
                 return value;
@@ -81,7 +81,7 @@ export async function* callSequence(sequence, callback) {
 export function runSequence(sequence, onNext, onError, onReturn) {
     const { promise, resolve } = getDeferred();
     void _runSequenceIterator(sequence[Symbol.asyncIterator](), promise, onNext, onError, onReturn);
-    return (value) => resolve({ done: ABORTED, value });
+    return (value) => resolve({ done: ABORT, value });
 }
 async function _runSequenceIterator(iterator, stopped, onNext, onError, onReturn) {
     let n;
@@ -90,7 +90,7 @@ async function _runSequenceIterator(iterator, stopped, onNext, onError, onReturn
             const { done, value } = await Promise.race([stopped, iterator.next(n)]);
             if (done) {
                 // For manual aborts tell the iterator we're no longer using it.
-                if (done === ABORTED) {
+                if (done === ABORT) {
                     const v = await _iteratorReturn(iterator, value, runSequence);
                     return onReturn?.(v);
                 }