shelving 1.236.0 → 1.236.2

package/store/DataStore.js

@@ -3,63 +3,166 @@ import { getGetter } from "../util/class.js";
 import { withProp } from "../util/object.js";
 import { updateData } 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 class DataStore extends BusyStore {
-    /** 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() {
         return this.value;
     }
-    /** 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) {
         this.value = data;
     }
-    /** 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) {
         this.value = updateData(this.data, updates);
     }
-    /** 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(name) {
         return this.data[name];
     }
-    /** 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(name, value) {
         this.value = withProp(this.data, name, value);
     }
 }
-/** 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 class OptionalDataStore extends BusyStore {
-    /** 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() {
         return this.require(getGetter(this, "data"));
     }
-    /** 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) {
         this.value = data;
     }
-    /** 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() {
         return !!this.value;
     }
-    /** 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 = this.require) {
         const data = this.value;
         if (!data)
             throw new RequiredError("Data is empty", { caller });
         return data;
     }
-    /** 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) {
         this.value = updateData(this.require(this.update), updates);
     }
-    /** 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(name) {
         return this.require(this.get)[name];
     }
-    /** 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(name, value) {
         this.value = withProp(this.require(this.set), name, value);
     }
-    /** 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() {
         this.value = undefined;
     }

package/store/DictionaryStore.d.ts

@@ -1,22 +1,80 @@
 import type { DictionaryItem, ImmutableDictionary, PossibleDictionary } from "../util/dictionary.js";
 import type { Updates } from "../util/update.js";
 import { BusyStore } from "./BusyStore.js";
-/** Store a dictionary object. */
+/**
+ * Store a dictionary object (string-keyed map of values), with helpers to read and mutate its entries.
+ * - Accepts any `PossibleDictionary<T>` as input and normalises it to an `ImmutableDictionary<T>`.
+ * - Mutations replace the stored dictionary with an immutable updated copy.
+ * - Iterable, yielding `[key, value]` entry tuples.
+ *
+ * @param value The initial dictionary value (defaults to an empty dictionary).
+ * @example
+ * const store = new DictionaryStore<number>({ a: 1, b: 2 });
+ * store.set("c", 3);
+ * store.get("a"); // 1
+ * @see https://dhoulb.github.io/shelving/store/DictionaryStore/DictionaryStore
+ */
 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. */
+    /**
+     * Get the number of entries in the current value of this store.
+     *
+     * @see https://dhoulb.github.io/shelving/store/DictionaryStore/DictionaryStore/count
+     */
     get count(): number;
-    /** Set a named entry in this object with a different value. */
+    /**
+     * Update several entries in this dictionary.
+     *
+     * @param updates The set of entry updates to apply.
+     * @returns Nothing.
+     * @example store.update({ a: 10, b: 20 });
+     * @see https://dhoulb.github.io/shelving/store/DictionaryStore/DictionaryStore/update
+     */
     update(updates: Updates<ImmutableDictionary<T>>): void;
-    /** Remove a named entry from this object. */
+    /**
+     * Remove one or more named entries from this dictionary.
+     *
+     * @param keys The keys of the entries to remove.
+     * @returns Nothing.
+     * @example store.deleteItems("a", "b");
+     * @see https://dhoulb.github.io/shelving/store/DictionaryStore/DictionaryStore/deleteItems
+     */
     deleteItems(...keys: string[]): void;
-    /** Get an item in this dictionary. */
+    /**
+     * Get a single named item from this dictionary, or `undefined` if it is not set.
+     *
+     * @param name The key of the item to read.
+     * @returns The item value, or `undefined` if it is not present.
+     * @example store.get("a"); // 1
+     * @see https://dhoulb.github.io/shelving/store/DictionaryStore/DictionaryStore/get
+     */
     get(name: string): T | undefined;
-    /** Set an item in this dictionary. */
+    /**
+     * Set a single named item in this dictionary.
+     *
+     * @param name The key of the item to set.
+     * @param value The new value for the item.
+     * @returns Nothing.
+     * @example store.set("a", 10);
+     * @see https://dhoulb.github.io/shelving/store/DictionaryStore/DictionaryStore/set
+     */
     set(name: string, value: T): void;
-    /** Delete an item (or several items) in this dictionary. */
+    /**
+     * Delete one or more named items from this dictionary.
+     *
+     * @param name The key of the first item to delete.
+     * @param names Additional keys to delete.
+     * @returns Nothing.
+     * @example store.delete("a", "b");
+     * @see https://dhoulb.github.io/shelving/store/DictionaryStore/DictionaryStore/delete
+     */
     delete(name: string, ...names: string[]): void;
-    /** Iterate over the entries of the object. */
+    /**
+     * Iterate over the `[key, value]` entries of this dictionary.
+     *
+     * @returns An iterator over the dictionary's entry tuples.
+     * @see https://dhoulb.github.io/shelving/store/DictionaryStore/DictionaryStore/[Symbol.iterator]
+     */
     [Symbol.iterator](): Iterator<DictionaryItem<T>>;
 }

package/store/DictionaryStore.js

@@ -2,7 +2,19 @@ import { EMPTY_DICTIONARY, getDictionaryItems, omitDictionaryItems, requireDicti
 import { omitProps, withProp } from "../util/object.js";
 import { updateData } from "../util/update.js";
 import { BusyStore } from "./BusyStore.js";
-/** Store a dictionary object. */
+/**
+ * Store a dictionary object (string-keyed map of values), with helpers to read and mutate its entries.
+ * - Accepts any `PossibleDictionary<T>` as input and normalises it to an `ImmutableDictionary<T>`.
+ * - Mutations replace the stored dictionary with an immutable updated copy.
+ * - Iterable, yielding `[key, value]` entry tuples.
+ *
+ * @param value The initial dictionary value (defaults to an empty dictionary).
+ * @example
+ * const store = new DictionaryStore<number>({ a: 1, b: 2 });
+ * store.set("c", 3);
+ * store.get("a"); // 1
+ * @see https://dhoulb.github.io/shelving/store/DictionaryStore/DictionaryStore
+ */
 export class DictionaryStore extends BusyStore {
     // Override to set default value to empty dictionary.
     constructor(value = EMPTY_DICTIONARY) {
@@ -12,31 +24,77 @@ export class DictionaryStore extends BusyStore {
     _convert(possible) {
         return requireDictionary(possible);
     }
-    /** Get the length of the current value of this store. */
+    /**
+     * Get the number of entries in the current value of this store.
+     *
+     * @see https://dhoulb.github.io/shelving/store/DictionaryStore/DictionaryStore/count
+     */
     get count() {
         return Object.keys(this.value).length;
     }
-    /** Set a named entry in this object with a different value. */
+    /**
+     * Update several entries in this dictionary.
+     *
+     * @param updates The set of entry updates to apply.
+     * @returns Nothing.
+     * @example store.update({ a: 10, b: 20 });
+     * @see https://dhoulb.github.io/shelving/store/DictionaryStore/DictionaryStore/update
+     */
     update(updates) {
         this.value = updateData(this.value, updates);
     }
-    /** Remove a named entry from this object. */
+    /**
+     * Remove one or more named entries from this dictionary.
+     *
+     * @param keys The keys of the entries to remove.
+     * @returns Nothing.
+     * @example store.deleteItems("a", "b");
+     * @see https://dhoulb.github.io/shelving/store/DictionaryStore/DictionaryStore/deleteItems
+     */
     deleteItems(...keys) {
         this.value = omitDictionaryItems(this.value, ...keys);
     }
-    /** Get an item in this dictionary. */
+    /**
+     * Get a single named item from this dictionary, or `undefined` if it is not set.
+     *
+     * @param name The key of the item to read.
+     * @returns The item value, or `undefined` if it is not present.
+     * @example store.get("a"); // 1
+     * @see https://dhoulb.github.io/shelving/store/DictionaryStore/DictionaryStore/get
+     */
     get(name) {
         return this.value[name];
     }
-    /** Set an item in this dictionary. */
+    /**
+     * Set a single named item in this dictionary.
+     *
+     * @param name The key of the item to set.
+     * @param value The new value for the item.
+     * @returns Nothing.
+     * @example store.set("a", 10);
+     * @see https://dhoulb.github.io/shelving/store/DictionaryStore/DictionaryStore/set
+     */
     set(name, value) {
         this.value = withProp(this.value, name, value);
     }
-    /** Delete an item (or several items) in this dictionary. */
+    /**
+     * Delete one or more named items from this dictionary.
+     *
+     * @param name The key of the first item to delete.
+     * @param names Additional keys to delete.
+     * @returns Nothing.
+     * @example store.delete("a", "b");
+     * @see https://dhoulb.github.io/shelving/store/DictionaryStore/DictionaryStore/delete
+     */
     delete(name, ...names) {
         this.value = omitProps(this.value, name, ...names);
     }
-    /** Iterate over the entries of the object. */
+    /**
+     * Iterate over the `[key, value]` entries of this dictionary.
+     *
+     * @returns An iterator over the dictionary's entry tuples.
+     * @see https://dhoulb.github.io/shelving/store/DictionaryStore/DictionaryStore/[Symbol.iterator]
+     */
     [Symbol.iterator]() {
         return getDictionaryItems(this.value)[Symbol.iterator]();
     }

package/store/FetchStore.d.ts

@@ -1,18 +1,39 @@
 import { type NONE } from "../util/constants.js";
 import { BusyStore } from "./BusyStore.js";
 import type { AsyncStoreInput, StoreInput } from "./Store.js";
-/** Zero passed to `refresh()` means "always refresh this value" (this is the default). */
+/**
+ * `maxAge` of zero passed to `refresh()` means "always refresh this value" (this is the default).
+ *
+ * @see https://dhoulb.github.io/shelving/store/FetchStore/ALWAYS_REFRESH
+ */
 export declare const ALWAYS_REFRESH = 0;
-/** Infinity passed to `refresh()` means "only refresh if this value is not loaded or invalid". */
+/**
+ * `maxAge` of `Infinity` passed to `refresh()` means "only refresh if this value is not loaded or invalid".
+ *
+ * @see https://dhoulb.github.io/shelving/store/FetchStore/AVOID_REFRESH
+ */
 export declare const AVOID_REFRESH: number;
-/** Callback for a callback fetch store. */
+/**
+ * Callback that fetches the next value for a `FetchStore`.
+ * - Receives the current `AbortSignal` so it can cancel in-flight HTTP requests when the fetch is aborted.
+ * - May return a value synchronously or a `PromiseLike` resolving to one (which the store will await).
+ *
+ * @see https://dhoulb.github.io/shelving/store/FetchStore/FetchCallback
+ */
 export type FetchCallback<T> = (signal: AbortSignal) => StoreInput<T> | PromiseLike<StoreInput<T>>;
 /**
- * Store that fetches its values from a remote source.
+ * Store that fetches its values from a remote source on demand.
+ * - Reading `value` or `loading` optimistically triggers a fetch so the value is available next time.
+ * - Fetches are de-duplicated, can be aged out with `maxAge`, and can be forced stale with `invalidate()`.
+ * - Provide a `callback` to fetch values, or subclass and override `this._fetch()` for custom behaviour.
  *
  * @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.
+ * @example
+ * const store = new FetchStore(NONE, async signal => (await fetch("/api/thing", { signal })).json());
+ * store.value; // throws a `Promise` while loading, then resolves to the fetched value
+ * @see https://dhoulb.github.io/shelving/store/FetchStore/FetchStore
  */
 export declare class FetchStore<T, TT = T> extends BusyStore<T, TT> {
     get loading(): boolean;
@@ -30,13 +51,20 @@ export declare class FetchStore<T, TT = T> extends BusyStore<T, TT> {
      * - `0` zero means "always refresh" (this is the default).
      * - `Infinity` means "refresh only if store is still in a loading state.
      * - Any other value may or may not be stale based on `this.age`
+     * @returns `true` if the value was set synchronously, `false` if no refresh happened, or a `Promise` resolving to whether the awaited fetch succeeded.
+     * @throws {never} Never throws — fetch errors are stored as `reason` instead.
+     * @example store.refresh(MINUTE); // refresh only if the current value is older than a minute
+     * @see https://dhoulb.github.io/shelving/store/FetchStore/FetchStore/refresh
      */
     refresh(maxAge?: number): Promise<boolean> | boolean;
     private _pendingRefresh;
     /**
      * Current `AbortSignal` for this store's in-flight fetch.
      * - Created lazily; a new signal is issued each time `refresh()` starts a new fetch or `abort()` is called.
-     * - Triggers `abort()` so any current awaits are cancelled.
+     * - Reading this triggers `abort()` so any current awaits are cancelled.
+     *
+     * @returns A fresh `AbortSignal` for the next fetch.
+     * @see https://dhoulb.github.io/shelving/store/FetchStore/FetchStore/signal
      */
     get signal(): AbortSignal;
     private _aborter;
@@ -46,11 +74,20 @@ export declare class FetchStore<T, TT = T> extends BusyStore<T, TT> {
      */
     protected _fetch(signal: AbortSignal): AsyncStoreInput<TT>;
     private _callback;
-    /** Whether this store is has currently been invalidated and needs a refresh. */
+    /**
+     * Whether this store has currently been invalidated and needs a refresh.
+     *
+     * @returns `true` if a refresh is pending after an `invalidate()` call, otherwise `false`.
+     * @see https://dhoulb.github.io/shelving/store/FetchStore/FetchStore/invalidated
+     */
     get invalidated(): boolean;
     /**
      * Invalidate this store so a new fetch is triggered on the next read of `loading` or `value`.
      * - Triggers `abort()` so any current awaits are cancelled.
+     *
+     * @returns Nothing.
+     * @example store.invalidate(); // next read of `value` refetches
+     * @see https://dhoulb.github.io/shelving/store/FetchStore/FetchStore/invalidate
      */
     invalidate(): void;
     private _invalidation;

package/store/FetchStore.js

@@ -2,16 +2,31 @@ import { RequiredError } from "../error/RequiredError.js";
 import { isAsync } from "../util/async.js";
 import { ABORT, SKIP } from "../util/constants.js";
 import { BusyStore } from "./BusyStore.js";
-/** Zero passed to `refresh()` means "always refresh this value" (this is the default). */
+/**
+ * `maxAge` of zero passed to `refresh()` means "always refresh this value" (this is the default).
+ *
+ * @see https://dhoulb.github.io/shelving/store/FetchStore/ALWAYS_REFRESH
+ */
 export const ALWAYS_REFRESH = 0;
-/** Infinity passed to `refresh()` means "only refresh if this value is not loaded or invalid". */
+/**
+ * `maxAge` of `Infinity` passed to `refresh()` means "only refresh if this value is not loaded or invalid".
+ *
+ * @see https://dhoulb.github.io/shelving/store/FetchStore/AVOID_REFRESH
+ */
 export const AVOID_REFRESH = Infinity;
 /**
- * Store that fetches its values from a remote source.
+ * Store that fetches its values from a remote source on demand.
+ * - Reading `value` or `loading` optimistically triggers a fetch so the value is available next time.
+ * - Fetches are de-duplicated, can be aged out with `maxAge`, and can be forced stale with `invalidate()`.
+ * - Provide a `callback` to fetch values, or subclass and override `this._fetch()` for custom behaviour.
  *
  * @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.
+ * @example
+ * const store = new FetchStore(NONE, async signal => (await fetch("/api/thing", { signal })).json());
+ * store.value; // throws a `Promise` while loading, then resolves to the fetched value
+ * @see https://dhoulb.github.io/shelving/store/FetchStore/FetchStore
  */
 export class FetchStore extends BusyStore {
     // Override to trigger a refresh when `this.loading` is read.
@@ -56,6 +71,10 @@ export class FetchStore extends BusyStore {
      * - `0` zero means "always refresh" (this is the default).
      * - `Infinity` means "refresh only if store is still in a loading state.
      * - Any other value may or may not be stale based on `this.age`
+     * @returns `true` if the value was set synchronously, `false` if no refresh happened, or a `Promise` resolving to whether the awaited fetch succeeded.
+     * @throws {never} Never throws — fetch errors are stored as `reason` instead.
+     * @example store.refresh(MINUTE); // refresh only if the current value is older than a minute
+     * @see https://dhoulb.github.io/shelving/store/FetchStore/FetchStore/refresh
      */
     refresh(maxAge = ALWAYS_REFRESH) {
         if (this._pendingRefresh)
@@ -78,7 +97,10 @@ export class FetchStore extends BusyStore {
     /**
      * Current `AbortSignal` for this store's in-flight fetch.
      * - Created lazily; a new signal is issued each time `refresh()` starts a new fetch or `abort()` is called.
-     * - Triggers `abort()` so any current awaits are cancelled.
+     * - Reading this triggers `abort()` so any current awaits are cancelled.
+     *
+     * @returns A fresh `AbortSignal` for the next fetch.
+     * @see https://dhoulb.github.io/shelving/store/FetchStore/FetchStore/signal
      */
     get signal() {
         this.abort();
@@ -96,13 +118,22 @@ export class FetchStore extends BusyStore {
         return this._callback(signal);
     }
     _callback;
-    /** Whether this store is has currently been invalidated and needs a refresh. */
+    /**
+     * Whether this store has currently been invalidated and needs a refresh.
+     *
+     * @returns `true` if a refresh is pending after an `invalidate()` call, otherwise `false`.
+     * @see https://dhoulb.github.io/shelving/store/FetchStore/FetchStore/invalidated
+     */
     get invalidated() {
         return !!this._invalidation;
     }
     /**
      * Invalidate this store so a new fetch is triggered on the next read of `loading` or `value`.
      * - Triggers `abort()` so any current awaits are cancelled.
+     *
+     * @returns Nothing.
+     * @example store.invalidate(); // next read of `value` refetches
+     * @see https://dhoulb.github.io/shelving/store/FetchStore/FetchStore/invalidate
      */
     invalidate() {
         this.abort();

package/store/PathStore.d.ts

@@ -3,20 +3,59 @@ import type { AbsolutePath, RelativePath } from "../util/path.js";
 import { BusyStore } from "./BusyStore.js";
 /**
  * Store an absolute path, e.g. `/a/b/c`
+ * - Accepts absolute or relative paths as input and normalises them to an absolute path against `this.base`.
+ * - Provides helpers to test whether other paths are active or proud relative to the current path.
  *
- * @param path: The initial value for the store.
- * @param base: The base path to resolve relative paths against.
+ * @param path The initial value for the store (defaults to `.`, resolved against `base`).
+ * @param base The base path to resolve relative paths against (defaults to `/`).
+ * @example
+ * const store = new PathStore("/a/b");
+ * store.isActive("/a/b"); // true
+ * store.getPath("c"); // "/a/b/c"
+ * @see https://dhoulb.github.io/shelving/store/PathStore/PathStore
  */
 export declare class PathStore extends BusyStore<AbsolutePath, AbsolutePath | RelativePath> {
+    /**
+     * Base path that relative inputs are resolved against.
+     *
+     * @see https://dhoulb.github.io/shelving/store/PathStore/PathStore/base
+     */
     readonly base: AbsolutePath;
     constructor(path?: AbsolutePath | RelativePath, base?: AbsolutePath);
     protected _convert(possible: AbsolutePath | RelativePath, caller: AnyCaller): AbsolutePath;
     protected _equal(a: AbsolutePath, b: AbsolutePath): boolean;
-    /** Based on the current store path, is a path active? */
+    /**
+     * Based on the current store path, is a path active (i.e. equal to the current path)?
+     *
+     * @param path The absolute path to test.
+     * @returns `true` if `path` matches the current path, otherwise `false`.
+     * @example store.isActive("/a/b");
+     * @see https://dhoulb.github.io/shelving/store/PathStore/PathStore/isActive
+     */
     isActive(path: AbsolutePath): boolean;
-    /** Based on the current store path, is a path proud (i.e. a child of the current store path)? */
+    /**
+     * Based on the current store path, is a path proud (i.e. an ancestor of the current store path)?
+     *
+     * @param path The absolute path to test.
+     * @returns `true` if `path` is at or above the current path in the hierarchy, otherwise `false`.
+     * @example store.isProud("/a"); // true when current path is "/a/b"
+     * @see https://dhoulb.github.io/shelving/store/PathStore/PathStore/isProud
+     */
     isProud(path: AbsolutePath): boolean;
-    /** Get an absolute path from a path relative to the current store path. */
+    /**
+     * Get an absolute path from a path relative to the current store path.
+     *
+     * @param path The absolute or relative path to resolve.
+     * @returns The resolved absolute path.
+     * @example store.getPath("c"); // "/a/b/c" when current path is "/a/b"
+     * @see https://dhoulb.github.io/shelving/store/PathStore/PathStore/getPath
+     */
     getPath(path: AbsolutePath | RelativePath): AbsolutePath;
+    /**
+     * Return the current path as a string.
+     *
+     * @returns The current absolute path.
+     * @see https://dhoulb.github.io/shelving/store/PathStore/PathStore/toString
+     */
     toString(): string;
 }