shelving 1.236.0 → 1.236.2

package/sequence/LazySequence.js

@@ -1,14 +1,34 @@
 import { awaitDispose } from "../util/dispose.js";
 import { Starter } from "../util/start.js";
 import { ThroughSequence } from "./ThroughSequence.js";
-/** Sequence of values that calls a `StartCallback` when it has iterators that are iterating, and calls the corresponding `StopCallback` when all iterators have finished. */
+/**
+ * Sequence of values that calls a `StartCallback` when it has iterators that are iterating, and calls the corresponding `StopCallback` when all iterators have finished.
+ * - The `start` callback runs lazily on the first active iterator and the returned stop callback runs when the last iterator finishes.
+ *
+ * @example
+ * 	const seq = new LazySequence(source, () => {
+ * 		const timer = setInterval(tick, 1000);
+ * 		return () => clearInterval(timer); // Stop callback.
+ * 	});
+ * @see https://dhoulb.github.io/shelving/sequence/LazySequence/LazySequence
+ */
 export class LazySequence extends ThroughSequence {
     _iterators = new Set(); // Keep track of the iterators that are iterating.
     _starter;
-    /** Get the number of iterators currently registered. */
+    /**
+     * Number of iterators currently registered as iterating.
+     *
+     * @see https://dhoulb.github.io/shelving/sequence/LazySequence/LazySequence/iterators
+     */
     get iterators() {
         return this._iterators.size;
     }
+    /**
+     * Create a new `LazySequence`.
+     *
+     * @param source Async iterator to pull values from.
+     * @param start Callback run when the first iterator starts; its returned stop callback runs when the last iterator finishes.
+     */
     constructor(source, start) {
         super(source);
         this._starter = new Starter(start);
@@ -27,6 +47,10 @@ export class LazySequence extends ThroughSequence {
      * An iterator started iterating.
      * - Add this iterator to the register.
      * - Start the starter if this is the first iterator.
+     *
+     * @param iterator The iterator that has started iterating.
+     * @example sequence.start(iterator);
+     * @see https://dhoulb.github.io/shelving/sequence/LazySequence/LazySequence/start
      */
     start(iterator) {
         const before = this._iterators.size;
@@ -38,6 +62,10 @@ export class LazySequence extends ThroughSequence {
      * An iterator stopped iterating.
      * - Add this iterator to the register
      * - Stop the starter if this is the last iterator.
+     *
+     * @param iterator The iterator that has stopped iterating.
+     * @example sequence.stop(iterator);
+     * @see https://dhoulb.github.io/shelving/sequence/LazySequence/LazySequence/stop
      */
     stop(iterator) {
         const before = this._iterators.size;

package/sequence/Sequence.d.ts

@@ -6,6 +6,12 @@
  * - Key constraint is that a generator only runs one time through and keeps track of its status.
  * - This means when a generator throws, further requests to `next()` will always return `done: true`
  * - This class does not provide that guarantee or have that constraint.
+ *
+ * @example
+ * 	class NumberSequence extends Sequence<number, void, void> {
+ * 		async next() { return { done: false, value: Math.random() }; }
+ * 	}
+ * @see https://dhoulb.github.io/shelving/sequence/Sequence/Sequence
  */
 export declare abstract class Sequence<T, R, N> implements AsyncIterable<T, R | undefined, N | undefined>, AsyncIterator<T, R | undefined, N | undefined>, AsyncDisposable {
     readonly [Symbol.toStringTag] = "Sequence";
@@ -18,6 +24,7 @@ export declare abstract class Sequence<T, R, N> implements AsyncIterable<T, R |
      * - Will be the `N` next value on subsequent calls.
      *
      * @returns An incomplete iterator result with `done: false` and `value: T`.
+     * @see https://dhoulb.github.io/shelving/sequence/Sequence/Sequence/next
      */
     abstract next(value?: N | undefined): Promise<IteratorResult<T, R | undefined>>;
     /**
@@ -30,6 +37,7 @@ export declare abstract class Sequence<T, R, N> implements AsyncIterable<T, R |
      * - Will be `undefined` on the first call.
      *
      * @returns A completed iterator result with `done: true`.
+     * @see https://dhoulb.github.io/shelving/sequence/Sequence/Sequence/return
      */
     return(value?: R | undefined | PromiseLike<R | undefined>): Promise<IteratorResult<T, R | undefined>>;
     /**
@@ -38,6 +46,9 @@ export declare abstract class Sequence<T, R, N> implements AsyncIterable<T, R |
      * - Subclasses can override this to recover from errors or perform cleanup.
      *
      * @param reason Error or other thrown value to send into the iterator.
+     * @returns A completed iterator result with `done: true` if a subclass recovers from the error.
+     * @throws The `reason` value by default — subclasses may override to recover instead.
+     * @see https://dhoulb.github.io/shelving/sequence/Sequence/Sequence/throw
      */
     throw(reason?: unknown): Promise<IteratorResult<T, R | undefined>>;
     [Symbol.asyncIterator](): AsyncIterator<T, R | undefined, N | undefined>;

package/sequence/Sequence.js

@@ -6,6 +6,12 @@
  * - Key constraint is that a generator only runs one time through and keeps track of its status.
  * - This means when a generator throws, further requests to `next()` will always return `done: true`
  * - This class does not provide that guarantee or have that constraint.
+ *
+ * @example
+ * 	class NumberSequence extends Sequence<number, void, void> {
+ * 		async next() { return { done: false, value: Math.random() }; }
+ * 	}
+ * @see https://dhoulb.github.io/shelving/sequence/Sequence/Sequence
  */
 export class Sequence {
     [Symbol.toStringTag] = "Sequence";
@@ -19,6 +25,7 @@ export class Sequence {
      * - Will be `undefined` on the first call.
      *
      * @returns A completed iterator result with `done: true`.
+     * @see https://dhoulb.github.io/shelving/sequence/Sequence/Sequence/return
      */
     async return(value) {
         // Default behaviour for a generator is to return `done: true` and repeat back input value.
@@ -30,6 +37,9 @@ export class Sequence {
      * - Subclasses can override this to recover from errors or perform cleanup.
      *
      * @param reason Error or other thrown value to send into the iterator.
+     * @returns A completed iterator result with `done: true` if a subclass recovers from the error.
+     * @throws The `reason` value by default — subclasses may override to recover instead.
+     * @see https://dhoulb.github.io/shelving/sequence/Sequence/Sequence/throw
      */
     async throw(reason) {
         // Default behaviour for a generator is to throw the error back out of the iterator and not continue.

package/sequence/ThroughSequence.d.ts

@@ -3,9 +3,24 @@ import { Sequence } from "./Sequence.js";
  * Async iterable that pulls values from a source async iterable.
  * - Can be used to turn an `AsyncIterator` into an `AsyncIterableIterator`
  * - Can be used to ensure `throw()` and `return()` are always set on an `AsyncIterator`
+ *
+ * @example
+ * 	const seq = new ThroughSequence(someAsyncIterator);
+ * 	for await (const value of seq) console.log(value);
+ * @see https://dhoulb.github.io/shelving/sequence/ThroughSequence/ThroughSequence
  */
 export declare class ThroughSequence<T, R, N> extends Sequence<T, R | undefined, N | undefined> {
+    /**
+     * Source async iterator that this sequence pulls values from.
+     *
+     * @see https://dhoulb.github.io/shelving/sequence/ThroughSequence/ThroughSequence/source
+     */
     readonly source: AsyncIterator<T, R | undefined, N | undefined>;
+    /**
+     * Create a new `ThroughSequence` wrapping a source iterator.
+     *
+     * @param source Async iterator to pull values from.
+     */
     constructor(source: AsyncIterator<T, R | undefined, N | undefined>);
     next(value?: N | undefined): Promise<IteratorResult<T, R | undefined>>;
     return(value?: R | undefined | PromiseLike<R | undefined>): Promise<IteratorResult<T, R | undefined>>;

package/sequence/ThroughSequence.js

@@ -4,9 +4,24 @@ import { Sequence } from "./Sequence.js";
  * Async iterable that pulls values from a source async iterable.
  * - Can be used to turn an `AsyncIterator` into an `AsyncIterableIterator`
  * - Can be used to ensure `throw()` and `return()` are always set on an `AsyncIterator`
+ *
+ * @example
+ * 	const seq = new ThroughSequence(someAsyncIterator);
+ * 	for await (const value of seq) console.log(value);
+ * @see https://dhoulb.github.io/shelving/sequence/ThroughSequence/ThroughSequence
  */
 export class ThroughSequence extends Sequence {
+    /**
+     * Source async iterator that this sequence pulls values from.
+     *
+     * @see https://dhoulb.github.io/shelving/sequence/ThroughSequence/ThroughSequence/source
+     */
     source;
+    /**
+     * Create a new `ThroughSequence` wrapping a source iterator.
+     *
+     * @param source Async iterator to pull values from.
+     */
     constructor(source) {
         super();
         this.source = source;

package/store/ArrayStore.d.ts

@@ -1,28 +1,91 @@
 import type { ImmutableArray, PossibleArray } from "../util/array.js";
 import type { AnyCaller } from "../util/function.js";
 import { BusyStore } from "./BusyStore.js";
-/** Store an array. */
+/**
+ * Store an immutable array of items, with helpers to read and mutate its contents.
+ * - Accepts any `PossibleArray<T>` as input and normalises it to an `ImmutableArray<T>`.
+ * - Mutations (`add()`, `delete()`, `toggle()`) replace the stored array with an immutable updated copy.
+ * - Iterable, so you can `for (const item of store)`.
+ *
+ * @param value The initial array value (defaults to an empty array).
+ * @example
+ * const store = new ArrayStore([1, 2, 3]);
+ * store.add(4); // [1, 2, 3, 4]
+ * store.first; // 1
+ * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore
+ */
 export declare class ArrayStore<T> extends BusyStore<ImmutableArray<T>, PossibleArray<T>> implements Iterable<T> {
     constructor(value?: PossibleArray<T>);
     protected _convert(input: PossibleArray<T>, caller: AnyCaller): ImmutableArray<T>;
-    /** Get the first item in this store or `null` if this query has no items. */
+    /**
+     * Get the first item in this store, or `undefined` if it has no items.
+     *
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/optionalFirst
+     */
     get optionalFirst(): T | undefined;
-    /** Get the last item in this store or `null` if this query has no items. */
+    /**
+     * Get the last item in this store, or `undefined` if it has no items.
+     *
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/optionalLast
+     */
     get optionalLast(): T | undefined;
-    /** Get the first item in this store. */
+    /**
+     * Get the first item in this store, or throw `RequiredError` if it has no items.
+     *
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/first
+     */
     get first(): T;
-    /** Get the last item in this store. */
+    /**
+     * Get the last item in this store, or throw `RequiredError` if it has no items.
+     *
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/last
+     */
     get last(): T;
-    /** Does the document have at least one result. */
+    /**
+     * Whether this store has at least one item.
+     *
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/exists
+     */
     get exists(): boolean;
-    /** Get the length of the current value of this store. */
+    /**
+     * Get the number of items in the current value of this store.
+     *
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/count
+     */
     get count(): number;
-    /** Add items to this array. */
+    /**
+     * Add one or more items to this array.
+     * - Duplicate items (already present in the array) are skipped.
+     *
+     * @param items The items to add.
+     * @returns Nothing.
+     * @example store.add(4, 5);
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/add
+     */
     add(...items: T[]): void;
-    /** Remove items from this array. */
+    /**
+     * Remove one or more items from this array.
+     *
+     * @param items The items to remove.
+     * @returns Nothing.
+     * @example store.delete(2, 3);
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/delete
+     */
     delete(...items: T[]): void;
-    /** Toggle items in this array. */
+    /**
+     * Toggle one or more items in this array (add if absent, remove if present).
+     *
+     * @param items The items to toggle.
+     * @returns Nothing.
+     * @example store.toggle(1, 4);
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/toggle
+     */
     toggle(...items: T[]): void;
-    /** Iterate over the items. */
+    /**
+     * Iterate over the items in this store's current array.
+     *
+     * @returns An iterator over the items.
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/[Symbol.iterator]
+     */
     [Symbol.iterator](): Iterator<T, void>;
 }

package/store/ArrayStore.js

@@ -1,6 +1,18 @@
 import { getFirst, getLast, omitArrayItems, requireArray, requireFirst, requireLast, toggleArrayItems, withArrayItems, } from "../util/array.js";
 import { BusyStore } from "./BusyStore.js";
-/** Store an array. */
+/**
+ * Store an immutable array of items, with helpers to read and mutate its contents.
+ * - Accepts any `PossibleArray<T>` as input and normalises it to an `ImmutableArray<T>`.
+ * - Mutations (`add()`, `delete()`, `toggle()`) replace the stored array with an immutable updated copy.
+ * - Iterable, so you can `for (const item of store)`.
+ *
+ * @param value The initial array value (defaults to an empty array).
+ * @example
+ * const store = new ArrayStore([1, 2, 3]);
+ * store.add(4); // [1, 2, 3, 4]
+ * store.first; // 1
+ * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore
+ */
 export class ArrayStore extends BusyStore {
     // Override to set default value to `[]` and convert possible arrays.
     constructor(value = []) {
@@ -10,43 +22,94 @@ export class ArrayStore extends BusyStore {
     _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 the first item in this store, or `undefined` if it has no items.
+     *
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/optionalFirst
+     */
     get optionalFirst() {
         return getFirst(this.value);
     }
-    /** Get the last item in this store or `null` if this query has no items. */
+    /**
+     * Get the last item in this store, or `undefined` if it has no items.
+     *
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/optionalLast
+     */
     get optionalLast() {
         return getLast(this.value);
     }
-    /** Get the first item in this store. */
+    /**
+     * Get the first item in this store, or throw `RequiredError` if it has no items.
+     *
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/first
+     */
     get first() {
         return requireFirst(this.value);
     }
-    /** Get the last item in this store. */
+    /**
+     * Get the last item in this store, or throw `RequiredError` if it has no items.
+     *
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/last
+     */
     get last() {
         return requireLast(this.value);
     }
-    /** Does the document have at least one result. */
+    /**
+     * Whether this store has at least one item.
+     *
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/exists
+     */
     get exists() {
         return !!this.value.length;
     }
-    /** Get the length of the current value of this store. */
+    /**
+     * Get the number of items in the current value of this store.
+     *
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/count
+     */
     get count() {
         return this.value.length;
     }
-    /** Add items to this array. */
+    /**
+     * Add one or more items to this array.
+     * - Duplicate items (already present in the array) are skipped.
+     *
+     * @param items The items to add.
+     * @returns Nothing.
+     * @example store.add(4, 5);
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/add
+     */
     add(...items) {
         this.value = withArrayItems(this.value, ...items);
     }
-    /** Remove items from this array. */
+    /**
+     * Remove one or more items from this array.
+     *
+     * @param items The items to remove.
+     * @returns Nothing.
+     * @example store.delete(2, 3);
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/delete
+     */
     delete(...items) {
         this.value = omitArrayItems(this.value, ...items);
     }
-    /** Toggle items in this array. */
+    /**
+     * Toggle one or more items in this array (add if absent, remove if present).
+     *
+     * @param items The items to toggle.
+     * @returns Nothing.
+     * @example store.toggle(1, 4);
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/toggle
+     */
     toggle(...items) {
         this.value = toggleArrayItems(this.value, ...items);
     }
-    /** Iterate over the items. */
+    /**
+     * Iterate over the items in this store's current array.
+     *
+     * @returns An iterator over the items.
+     * @see https://dhoulb.github.io/shelving/store/ArrayStore/ArrayStore/[Symbol.iterator]
+     */
     [Symbol.iterator]() {
         return this.value.values();
     }

package/store/BooleanStore.d.ts

@@ -1,9 +1,26 @@
 import { Store } from "./Store.js";
-/** Store a boolean. */
+/**
+ * Store a boolean value.
+ * - Any input is coerced to a boolean via `!!input`, so truthy/falsy values are accepted.
+ * - Defaults to `false`.
+ *
+ * @param value The initial boolean value (defaults to `false`).
+ * @example
+ * const store = new BooleanStore();
+ * store.value = 1; // true (coerced)
+ * store.toggle(); // now false
+ * @see https://dhoulb.github.io/shelving/store/BooleanStore/BooleanStore
+ */
 export declare class BooleanStore extends Store<boolean, unknown> {
     constructor(value?: boolean);
     protected _convert(input: unknown): boolean;
     protected _equal(a: boolean, b: boolean): boolean;
-    /** Toggle the current boolean value. */
+    /**
+     * Toggle the current boolean value.
+     *
+     * @returns Nothing.
+     * @example store.toggle(); // `true` becomes `false`, `false` becomes `true`
+     * @see https://dhoulb.github.io/shelving/store/BooleanStore/BooleanStore/toggle
+     */
     toggle(): void;
 }

package/store/BooleanStore.js

@@ -1,5 +1,16 @@
 import { Store } from "./Store.js";
-/** Store a boolean. */
+/**
+ * Store a boolean value.
+ * - Any input is coerced to a boolean via `!!input`, so truthy/falsy values are accepted.
+ * - Defaults to `false`.
+ *
+ * @param value The initial boolean value (defaults to `false`).
+ * @example
+ * const store = new BooleanStore();
+ * store.value = 1; // true (coerced)
+ * store.toggle(); // now false
+ * @see https://dhoulb.github.io/shelving/store/BooleanStore/BooleanStore
+ */
 export class BooleanStore extends Store {
     // Override to set default value to `false`
     constructor(value = false) {
@@ -13,7 +24,13 @@ export class BooleanStore extends Store {
     _equal(a, b) {
         return a === b;
     }
-    /** Toggle the current boolean value. */
+    /**
+     * Toggle the current boolean value.
+     *
+     * @returns Nothing.
+     * @example store.toggle(); // `true` becomes `false`, `false` becomes `true`
+     * @see https://dhoulb.github.io/shelving/store/BooleanStore/BooleanStore/toggle
+     */
     toggle() {
         this.value = !this.value;
     }

package/store/BusyStore.d.ts

@@ -2,9 +2,21 @@ import { BooleanStore } from "./BooleanStore.js";
 import { Store, type StoreInput } from "./Store.js";
 /**
  * Store that tracks its busy status via a separate `this.busy` store.
- * - "busy" means the store is awaiting a new value.
+ * - "busy" means the store is awaiting a new (async) value.
+ * - `this.busy` becomes `true` when `await()` starts and `false` when `abort()` is called (which also happens whenever a value or `reason` is set).
+ *
+ * @example
+ * const store = new BusyStore(123);
+ * store.value = fetchValue();
+ * store.busy.value; // true while the promise is pending
+ * @see https://dhoulb.github.io/shelving/store/BusyStore/BusyStore
  */
 export declare class BusyStore<T, TT = T> extends Store<T, TT> {
+    /**
+     * Boolean store that is `true` while this store is awaiting a new value.
+     *
+     * @see https://dhoulb.github.io/shelving/store/BusyStore/BusyStore/busy
+     */
     readonly busy: BooleanStore;
     await(pending: PromiseLike<StoreInput<TT>>): Promise<boolean>;
     abort(): void;

package/store/BusyStore.js

@@ -3,9 +3,21 @@ 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.
+ * - "busy" means the store is awaiting a new (async) value.
+ * - `this.busy` becomes `true` when `await()` starts and `false` when `abort()` is called (which also happens whenever a value or `reason` is set).
+ *
+ * @example
+ * const store = new BusyStore(123);
+ * store.value = fetchValue();
+ * store.busy.value; // true while the promise is pending
+ * @see https://dhoulb.github.io/shelving/store/BusyStore/BusyStore
  */
 export class BusyStore extends Store {
+    /**
+     * Boolean store that is `true` while this store is awaiting a new value.
+     *
+     * @see https://dhoulb.github.io/shelving/store/BusyStore/BusyStore/busy
+     */
     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).

package/store/DataStore.d.ts

@@ -2,35 +2,138 @@ import type { Data, DataKey } from "../util/data.js";
 import type { AnyCaller } from "../util/function.js";
 import type { Updates } from "../util/update.js";
 import { BusyStore } from "./BusyStore.js";
-/** Store a data object. */
+/**
+ * Store a data object, with helpers to read and update individual props.
+ * - `update()`, `set()` replace the stored object with an immutable updated copy.
+ *
+ * @example
+ * const store = new DataStore({ name: "Dave", age: 40 });
+ * store.set("age", 41);
+ * store.get("name"); // "Dave"
+ * @see https://dhoulb.github.io/shelving/store/DataStore/DataStore
+ */
 export declare class DataStore<T extends Data> extends BusyStore<T> {
-    /** Get the data of this store. */
+    /**
+     * Get the current data of this store.
+     * - Supports suspense-like reads: throws a `Promise` while loading or the error `reason` on failure (inherited from `Store.value`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/DataStore/DataStore/data
+     */
     get data(): T;
-    /** Set the data of this store. */
+    /**
+     * Set the data of this store.
+     *
+     * @see https://dhoulb.github.io/shelving/store/DataStore/DataStore/data
+     */
     set data(data: T);
-    /** Update several props in this data. */
+    /**
+     * Update several props in this data.
+     *
+     * @param updates The set of prop updates to apply.
+     * @returns Nothing.
+     * @example store.update({ age: 41, "name": "Dave" });
+     * @see https://dhoulb.github.io/shelving/store/DataStore/DataStore/update
+     */
     update(updates: Updates<T>): void;
-    /** Update a single named prop in this data. */
+    /**
+     * Get a single named prop from this data.
+     *
+     * @param name The name of the prop to read.
+     * @returns The current value of the named prop.
+     * @example store.get("name"); // "Dave"
+     * @see https://dhoulb.github.io/shelving/store/DataStore/DataStore/get
+     */
     get<K extends DataKey<T>>(name: K): T[K];
-    /** Update a single named prop in this data. */
+    /**
+     * Set a single named prop in this data.
+     *
+     * @param name The name of the prop to set.
+     * @param value The new value for the prop.
+     * @returns Nothing.
+     * @example store.set("age", 41);
+     * @see https://dhoulb.github.io/shelving/store/DataStore/DataStore/set
+     */
     set<K extends DataKey<T>>(name: K, value: T[K]): void;
 }
-/** Store an optional data object. */
+/**
+ * Store a data object that may be `undefined` (e.g. a document that may not exist).
+ * - Reading `data` or calling `require()` throws `RequiredError` when the value is `undefined`.
+ * - `delete()` sets the value back to `undefined`.
+ *
+ * @example
+ * const store = new OptionalDataStore<{ name: string }>(undefined);
+ * store.exists; // false
+ * store.data = { name: "Dave" };
+ * store.delete(); // back to undefined
+ * @see https://dhoulb.github.io/shelving/store/DataStore/OptionalDataStore
+ */
 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 the current data of this store, or throw if it is not set.
+     * - Supports suspense-like reads: throws a `Promise` while loading or the error `reason` on failure (inherited from `Store.value`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/DataStore/OptionalDataStore/data
+     */
     get data(): T;
-    /** Set the data of this store. */
+    /**
+     * Set the data of this store.
+     *
+     * @see https://dhoulb.github.io/shelving/store/DataStore/OptionalDataStore/data
+     */
     set data(data: T);
-    /** Does the data exist or not? */
+    /**
+     * Whether the data currently exists (is not `undefined`).
+     *
+     * @see https://dhoulb.github.io/shelving/store/DataStore/OptionalDataStore/exists
+     */
     get exists(): boolean;
-    /** Require the data for this data store, or throw `RequiredError` if it is not set. */
+    /**
+     * Require the data of this store, or throw `RequiredError` if it is not set.
+     *
+     * @param caller The function to attribute a thrown `RequiredError` to (defaults to `this.require`).
+     * @returns The current data.
+     * @throws {RequiredError} If the data is `undefined`.
+     * @example store.require(); // throws if no data is set
+     * @see https://dhoulb.github.io/shelving/store/DataStore/OptionalDataStore/require
+     */
     require(caller?: AnyCaller): T;
-    /** Update several props in this data. */
+    /**
+     * Update several props in this data.
+     *
+     * @param updates The set of prop updates to apply.
+     * @returns Nothing.
+     * @throws {RequiredError} If the data is `undefined`.
+     * @example store.update({ name: "Dave" });
+     * @see https://dhoulb.github.io/shelving/store/DataStore/OptionalDataStore/update
+     */
     update(updates: Updates<T>): void;
-    /** Update a single named prop in this data. */
+    /**
+     * Get a single named prop from this data.
+     *
+     * @param name The name of the prop to read.
+     * @returns The current value of the named prop.
+     * @throws {RequiredError} If the data is `undefined`.
+     * @example store.get("name");
+     * @see https://dhoulb.github.io/shelving/store/DataStore/OptionalDataStore/get
+     */
     get<K extends DataKey<T>>(name: K): T[K];
-    /** Update a single named prop in this data. */
+    /**
+     * Set a single named prop in this data.
+     *
+     * @param name The name of the prop to set.
+     * @param value The new value for the prop.
+     * @returns Nothing.
+     * @throws {RequiredError} If the data is `undefined`.
+     * @example store.set("name", "Dave");
+     * @see https://dhoulb.github.io/shelving/store/DataStore/OptionalDataStore/set
+     */
     set<K extends DataKey<T>>(name: K, value: T[K]): void;
-    /** Set the data to `undefined`. */
+    /**
+     * Set the data to `undefined`.
+     *
+     * @returns Nothing.
+     * @example store.delete();
+     * @see https://dhoulb.github.io/shelving/store/DataStore/OptionalDataStore/delete
+     */
     delete(): void;
 }