shelving 1.236.0 → 1.236.2

package/schema/URLSchema.js

@@ -5,13 +5,26 @@ import { getURL } from "../util/url.js";
 import { NULLABLE } from "./NullableSchema.js";
 import { StringSchema } from "./StringSchema.js";
 /**
- * Type of `StringSchema` that defines a valid URL string.
- * - Checks URL scheme against a whitelist (always), and checks URL domain against a whitelist (optional).
- * - URLs are limited to 512 characters, but generally these won't be data: URIs so this is a reasonable limit.
+ * Schema that defines a valid absolute or relative URL string.
+ *
+ * - Checks the URL scheme against a whitelist (always), and resolves relative URLs against `base` when set.
+ * - URLs are limited to 512 characters, but generally these won't be `data:` URIs so this is a reasonable limit.
+ *
+ * @example
+ * 	const schema = new URLSchema({ base: "https://example.com" });
+ * 	schema.validate("/page") // "https://example.com/page"
+ * @see https://dhoulb.github.io/shelving/schema/URLSchema/URLSchema
  */
 export class URLSchema extends StringSchema {
+    /** Base URL that relative URLs are resolved against, or `undefined` when not set. */
     base;
+    /** Whitelist of allowed URL schemes, e.g. `["https:", "http:"]`. */
     schemes;
+    /**
+     * Create a new `URLSchema`.
+     *
+     * @param options Options for the schema (`base`, `schemes`, plus inherited string options like `one`, `title`, `value`).
+     */
     constructor({ one = "URL", title = "URL", base, schemes = HTTP_SCHEMES, ...options }) {
         super({
             one,
@@ -25,7 +38,17 @@ export class URLSchema extends StringSchema {
         this.base = getURL(base)?.href;
         this.schemes = schemes;
     }
-    // Override to validate the URL and check the schemes and hosts against the whitelists.
+    /**
+     * Validate an unknown input value and return a normalised absolute URL string.
+     *
+     * - Override to validate the URL and check the scheme and host against the whitelists.
+     *
+     * @param unsafeValue The unknown input value to validate.
+     * @returns The valid, fully-resolved URL string.
+     * @throws `string` error message if the value is empty, malformed, or uses a disallowed scheme.
+     * @example schema.validate("https://www.google.com") // "https://www.google.com/"
+     * @see https://dhoulb.github.io/shelving/schema/URLSchema/URLSchema/validate
+     */
     validate(unsafeValue) {
         const str = super.validate(unsafeValue);
         const url = getURL(str, this.base);
@@ -35,15 +58,47 @@ export class URLSchema extends StringSchema {
             throw `Invalid ${this.one} scheme`;
         return url.href;
     }
+    /**
+     * Sanitize a string before validation by stripping all whitespace.
+     *
+     * - URLs never contain whitespace (a real space must be `%20`-encoded), so strip it entirely.
+     *
+     * @param str The raw string to sanitize.
+     * @returns The sanitized string with all whitespace removed.
+     * @example schema.sanitize(" https://a.com ") // "https://a.com"
+     * @see https://dhoulb.github.io/shelving/schema/URLSchema/URLSchema/sanitize
+     */
     sanitize(str) {
         // URLs never contain whitespace (a real space must be `%20`-encoded), so strip it entirely.
         return sanitizeWord(str);
     }
+    /**
+     * Format a validated URL string for display.
+     *
+     * @param value The valid URL string to format.
+     * @returns The URL formatted as a human-readable string.
+     * @example schema.format("https://www.google.com/") // "www.google.com"
+     * @see https://dhoulb.github.io/shelving/schema/URLSchema/URLSchema/format
+     */
     format(value) {
         return formatURL(value, this.base, this.format);
     }
 }
-/** Valid URL string, e.g. `https://www.google.com` */
+/**
+ * Valid URL string, e.g. `https://www.google.com`.
+ *
+ * *Factory for `URLSchema`.*
+ *
+ * @example URL_SCHEMA.validate("https://www.google.com") // "https://www.google.com/"
+ * @see https://dhoulb.github.io/shelving/schema/URLSchema/URL_SCHEMA
+ */
 export const URL_SCHEMA = new URLSchema({});
-/** Valid URL string, e.g. `https://www.google.com`, or `null` */
+/**
+ * Valid URL string, e.g. `https://www.google.com`, or `null`.
+ *
+ * *Factory for `NullableSchema`.*
+ *
+ * @example NULLABLE_URL_SCHEMA.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/URLSchema/NULLABLE_URL_SCHEMA
+ */
 export const NULLABLE_URL_SCHEMA = NULLABLE(URL_SCHEMA);

package/schema/UUIDSchema.d.ts

@@ -1,14 +1,47 @@
 import { StringSchema, type StringSchemaOptions } from "./StringSchema.js";
 /**
- * Type of `StringSchema` that defines a valid UUID (versions 1-5). Defaults to any-version validation.
+ * Schema that defines a valid UUID string (versions 1-5). Defaults to any-version validation.
+ *
  * - Input is trimmed and lowercased.
- * - Falsy values are converted to empty string.
+ * - Falsy values are converted to an empty string.
+ *
+ * @example
+ * 	const schema = new UUIDSchema({});
+ * 	schema.validate("F47AC10B-58CC-4372-A567-0E02B2C3D479") // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+ * @see https://dhoulb.github.io/shelving/schema/UUIDSchema/UUIDSchema
  */
 export declare class UUIDSchema extends StringSchema {
+    /**
+     * Create a new `UUIDSchema`.
+     *
+     * @param options Options for the schema (inherited string options like `one`, `title`, `value`).
+     */
     constructor({ one, title, ...rest }?: Omit<StringSchemaOptions, "input" | "min" | "max" | "match" | "rows">);
+    /**
+     * Sanitize a string before validation by normalising it into a canonical UUID.
+     *
+     * @param str The raw string to sanitize.
+     * @returns The sanitized UUID, or an empty string when the input is not a valid UUID.
+     * @example schema.sanitize("F47AC10B58CC4372A5670E02B2C3D479") // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+     * @see https://dhoulb.github.io/shelving/schema/UUIDSchema/UUIDSchema/sanitize
+     */
     sanitize(str: string): string;
 }
-/** Any valid UUID (versions 1-5) */
+/**
+ * Any valid UUID (versions 1-5).
+ *
+ * *Factory for `UUIDSchema`.*
+ *
+ * @example UUID.validate("F47AC10B-58CC-4372-A567-0E02B2C3D479") // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+ * @see https://dhoulb.github.io/shelving/schema/UUIDSchema/UUID
+ */
 export declare const UUID: UUIDSchema;
-/** Any valid UUID (versions 1-5) or null */
+/**
+ * Any valid UUID (versions 1-5), or `null`.
+ *
+ * *Factory for `NullableSchema`.*
+ *
+ * @example NULLABLE_UUID.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/UUIDSchema/NULLABLE_UUID
+ */
 export declare const NULLABLE_UUID: import("./NullableSchema.js").NullableSchema<string>;

package/schema/UUIDSchema.js

@@ -2,11 +2,22 @@ import { getUUID } from "../util/uuid.js";
 import { NULLABLE } from "./NullableSchema.js";
 import { StringSchema } from "./StringSchema.js";
 /**
- * Type of `StringSchema` that defines a valid UUID (versions 1-5). Defaults to any-version validation.
+ * Schema that defines a valid UUID string (versions 1-5). Defaults to any-version validation.
+ *
  * - Input is trimmed and lowercased.
- * - Falsy values are converted to empty string.
+ * - Falsy values are converted to an empty string.
+ *
+ * @example
+ * 	const schema = new UUIDSchema({});
+ * 	schema.validate("F47AC10B-58CC-4372-A567-0E02B2C3D479") // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+ * @see https://dhoulb.github.io/shelving/schema/UUIDSchema/UUIDSchema
  */
 export class UUIDSchema extends StringSchema {
+    /**
+     * Create a new `UUIDSchema`.
+     *
+     * @param options Options for the schema (inherited string options like `one`, `title`, `value`).
+     */
     constructor({ one = "UUID", title = "UUID", ...rest } = {}) {
         super({
             one,
@@ -17,11 +28,33 @@ export class UUIDSchema extends StringSchema {
             rows: 1,
         });
     }
+    /**
+     * Sanitize a string before validation by normalising it into a canonical UUID.
+     *
+     * @param str The raw string to sanitize.
+     * @returns The sanitized UUID, or an empty string when the input is not a valid UUID.
+     * @example schema.sanitize("F47AC10B58CC4372A5670E02B2C3D479") // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+     * @see https://dhoulb.github.io/shelving/schema/UUIDSchema/UUIDSchema/sanitize
+     */
     sanitize(str) {
         return getUUID(str) || "";
     }
 }
-/** Any valid UUID (versions 1-5) */
+/**
+ * Any valid UUID (versions 1-5).
+ *
+ * *Factory for `UUIDSchema`.*
+ *
+ * @example UUID.validate("F47AC10B-58CC-4372-A567-0E02B2C3D479") // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+ * @see https://dhoulb.github.io/shelving/schema/UUIDSchema/UUID
+ */
 export const UUID = new UUIDSchema({ title: "ID" });
-/** Any valid UUID (versions 1-5) or null */
+/**
+ * Any valid UUID (versions 1-5), or `null`.
+ *
+ * *Factory for `NullableSchema`.*
+ *
+ * @example NULLABLE_UUID.validate(null) // null
+ * @see https://dhoulb.github.io/shelving/schema/UUIDSchema/NULLABLE_UUID
+ */
 export const NULLABLE_UUID = NULLABLE(UUID);

package/sequence/DeferredSequence.d.ts

@@ -1,9 +1,19 @@
 import type { Deferred } from "../util/async.js";
 import type { Nullable } from "../util/null.js";
 import { Sequence } from "./Sequence.js";
+/**
+ * Result representing a rejection in a `DeferredSequence`, carrying the thrown `reason`.
+ *
+ * @see https://dhoulb.github.io/shelving/sequence/DeferredSequence/DeferredErrorResult
+ */
 export type DeferredErrorResult = {
     readonly reason: unknown;
 };
+/**
+ * Pending result of a `DeferredSequence` — either a standard `IteratorResult` or a `DeferredErrorResult` rejection.
+ *
+ * @see https://dhoulb.github.io/shelving/sequence/DeferredSequence/DeferredResult
+ */
 export type DeferredResult<T, R> = IteratorResult<T, R | undefined> | DeferredErrorResult;
 /**
  * Deferred sequence of values that can be async iterated and new values can be published.
@@ -11,6 +21,14 @@ export type DeferredResult<T, R> = IteratorResult<T, R | undefined> | DeferredEr
  * - Implements `Promise` so the next result can be awaited.
  * - Implements `AsyncIterable` so values can be iterated over using `for await...of`
  * - Call `resolve(value)` to publish the next value, `reject(reason?)` to publish an error, or `done(value?)` to signal completion.
+ *
+ * @example
+ * 	const seq = new DeferredSequence<number>();
+ * 	(async () => { for await (const n of seq) console.log(n); })();
+ * 	seq.resolve(1);
+ * 	seq.resolve(2);
+ * 	seq.done();
+ * @see https://dhoulb.github.io/shelving/sequence/DeferredSequence/DeferredSequence
  */
 export declare class DeferredSequence<T = void, R = void, N = void> extends Sequence<T, R, N> implements Deferred<T>, Promise<T> {
     /** Lazy deferred that stores iterator values. */
@@ -19,30 +37,58 @@ export declare class DeferredSequence<T = void, R = void, N = void> extends Sequ
     private _promiseDeferred;
     /** Next iterator result to reject the deferred to (on next microtask). */
     private _next;
-    /** Get the next promise to be resolved/rejected. */
+    /**
+     * Next promise to be resolved/rejected with the upcoming value.
+     *
+     * @see https://dhoulb.github.io/shelving/sequence/DeferredSequence/DeferredSequence/promise
+     */
     get promise(): Promise<T>;
     /**
      * Resolve the current deferred in the sequence with a value.
      * - Sends a `{ value: X }` to any iterators.
+     *
+     * @param value Value to publish to iterators and awaiting promises.
+     * @example seq.resolve(123);
+     * @see https://dhoulb.github.io/shelving/sequence/DeferredSequence/DeferredSequence/resolve
      */
     resolve(value: T): void;
     /**
-     * Reject the current deferred in the sequence.
+     * Reject the current deferred in the sequence with an error.
+     * - Sends a `{ reason: X }` to any iterators, causing `for await` loops to throw.
+     *
+     * @param reason Error or other thrown value to publish to iterators and awaiting promises.
+     * @example seq.reject(new Error("Stop"));
+     * @see https://dhoulb.github.io/shelving/sequence/DeferredSequence/DeferredSequence/reject
      */
     reject(reason: unknown): void;
     /**
      * Signal that the sequence is done, causing any active `for await` loops to exit cleanly.
      * - Sends a `{ done: true, value: R }` to any iterators.
+     *
+     * @param value Optional final return value for the sequence.
+     * @example seq.done();
+     * @see https://dhoulb.github.io/shelving/sequence/DeferredSequence/DeferredSequence/done
      */
     done(value?: R | undefined): void;
     /**
      * Cancel the current resolution or rejection.
      * - Iterators will contain to wait for a next value.
+     *
+     * @example seq.cancel();
+     * @see https://dhoulb.github.io/shelving/sequence/DeferredSequence/DeferredSequence/cancel
      */
     cancel(): void;
     /** Fulfill the current deferred by resolving or rejecting both the iterator deferred and the promise deferred. */
     private _fulfill;
-    /** Resolve the current deferred from a sequence of values. */
+    /**
+     * Resolve the current deferred from a sequence of values.
+     * - Iterates `sequence`, republishing each value through this deferred sequence and yielding it on.
+     *
+     * @param sequence Source async iterable to forward values from.
+     * @returns An async iterator yielding each forwarded value.
+     * @example for await (const v of seq.through(source)) console.log(v);
+     * @see https://dhoulb.github.io/shelving/sequence/DeferredSequence/DeferredSequence/through
+     */
     through(sequence: AsyncIterable<T>): AsyncIterator<T>;
     next(_next?: N | undefined): Promise<IteratorResult<T, R | undefined>>;
     then<X = T, Y = never>(onNext?: Nullable<(v: T) => X | PromiseLike<X>>, onError?: Nullable<(r: unknown) => Y | PromiseLike<Y>>): Promise<X | Y>;

package/sequence/DeferredSequence.js

@@ -7,6 +7,14 @@ import { Sequence } from "./Sequence.js";
  * - Implements `Promise` so the next result can be awaited.
  * - Implements `AsyncIterable` so values can be iterated over using `for await...of`
  * - Call `resolve(value)` to publish the next value, `reject(reason?)` to publish an error, or `done(value?)` to signal completion.
+ *
+ * @example
+ * 	const seq = new DeferredSequence<number>();
+ * 	(async () => { for await (const n of seq) console.log(n); })();
+ * 	seq.resolve(1);
+ * 	seq.resolve(2);
+ * 	seq.done();
+ * @see https://dhoulb.github.io/shelving/sequence/DeferredSequence/DeferredSequence
  */
 export class DeferredSequence extends Sequence {
     /** Lazy deferred that stores iterator values. */
@@ -15,7 +23,11 @@ export class DeferredSequence extends Sequence {
     _promiseDeferred;
     /** Next iterator result to reject the deferred to (on next microtask). */
     _next;
-    /** Get the next promise to be resolved/rejected. */
+    /**
+     * Next promise to be resolved/rejected with the upcoming value.
+     *
+     * @see https://dhoulb.github.io/shelving/sequence/DeferredSequence/DeferredSequence/promise
+     */
     get promise() {
         this._promiseDeferred ||= createDeferred();
         return this._promiseDeferred.promise;
@@ -23,13 +35,22 @@ export class DeferredSequence extends Sequence {
     /**
      * Resolve the current deferred in the sequence with a value.
      * - Sends a `{ value: X }` to any iterators.
+     *
+     * @param value Value to publish to iterators and awaiting promises.
+     * @example seq.resolve(123);
+     * @see https://dhoulb.github.io/shelving/sequence/DeferredSequence/DeferredSequence/resolve
      */
     resolve(value) {
         this._next = { value };
         queueMicrotask(() => this._fulfill());
     }
     /**
-     * Reject the current deferred in the sequence.
+     * Reject the current deferred in the sequence with an error.
+     * - Sends a `{ reason: X }` to any iterators, causing `for await` loops to throw.
+     *
+     * @param reason Error or other thrown value to publish to iterators and awaiting promises.
+     * @example seq.reject(new Error("Stop"));
+     * @see https://dhoulb.github.io/shelving/sequence/DeferredSequence/DeferredSequence/reject
      */
     reject(reason) {
         this._next = { reason };
@@ -38,6 +59,10 @@ export class DeferredSequence extends Sequence {
     /**
      * Signal that the sequence is done, causing any active `for await` loops to exit cleanly.
      * - Sends a `{ done: true, value: R }` to any iterators.
+     *
+     * @param value Optional final return value for the sequence.
+     * @example seq.done();
+     * @see https://dhoulb.github.io/shelving/sequence/DeferredSequence/DeferredSequence/done
      */
     done(value) {
         this._next = { done: true, value };
@@ -46,6 +71,9 @@ export class DeferredSequence extends Sequence {
     /**
      * Cancel the current resolution or rejection.
      * - Iterators will contain to wait for a next value.
+     *
+     * @example seq.cancel();
+     * @see https://dhoulb.github.io/shelving/sequence/DeferredSequence/DeferredSequence/cancel
      */
     cancel() {
         this._next = undefined;
@@ -70,7 +98,15 @@ export class DeferredSequence extends Sequence {
             }
         }
     }
-    /** Resolve the current deferred from a sequence of values. */
+    /**
+     * Resolve the current deferred from a sequence of values.
+     * - Iterates `sequence`, republishing each value through this deferred sequence and yielding it on.
+     *
+     * @param sequence Source async iterable to forward values from.
+     * @returns An async iterator yielding each forwarded value.
+     * @example for await (const v of seq.through(source)) console.log(v);
+     * @see https://dhoulb.github.io/shelving/sequence/DeferredSequence/DeferredSequence/through
+     */
     async *through(sequence) {
         for await (const item of sequence) {
             this.resolve(item);

package/sequence/InspectSequence.d.ts

@@ -8,25 +8,79 @@ import { ThroughSequence } from "./ThroughSequence.js";
  * 	for await (const next of capture) console.log("YIELDED", next);
  * 	console.log("FIRST", watch.first);
  * 	console.log("RETURNED", watch.returned);
+ * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence
  */
 export declare class InspectSequence<T, R, N> extends ThroughSequence<T, R, N> {
-    /** Get the number of results received by this iterator so far. */
+    /**
+     * The number of values yielded by the source sequence so far.
+     *
+     * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence/count
+     */
     get count(): number;
     private _count;
-    /** Is the iteration done? */
+    /**
+     * Whether the source sequence has finished iterating (i.e. it has returned).
+     *
+     * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence/done
+     */
     get done(): boolean;
     private _done;
-    /** The first yielded value (throws if the iteration yielded no values, i.e. `this.count === 0`). */
+    /**
+     * The first value yielded by the source sequence.
+     *
+     * - Throws if the iteration yielded no values yet, i.e. `this.count === 0`.
+     *
+     * @throws {UnexpectedError} If iteration has not yielded any value yet.
+     * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence/first
+     */
     get first(): T;
     private _first;
-    /** The last yielded value (throws if the iteration yielded no values, i.e. `this.count === 0`). */
+    /**
+     * The last value yielded by the source sequence.
+     *
+     * - Throws if the iteration yielded no values yet, i.e. `this.count === 0`.
+     *
+     * @throws {UnexpectedError} If iteration has not yielded any value yet.
+     * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence/last
+     */
     get last(): T;
     private _last;
-    /** The returned value (throws if the iteration is not done, i.e. `this.done === false`). */
+    /**
+     * The value returned by the source sequence when it finished.
+     *
+     * - Throws if the iteration is not done yet, i.e. `this.done === false`.
+     *
+     * @throws {UnexpectedError} If iteration is not done yet.
+     * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence/returned
+     */
     get returned(): R | undefined;
     private _returned;
+    /**
+     * Advance the source sequence by one step, recording the yielded or returned value.
+     *
+     * @param value Optional value passed into the source sequence's `next()`.
+     * @returns Promise resolving to the next `IteratorResult` from the source sequence.
+     * @example const { value, done } = await watch.next()
+     * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence/next
+     */
     next(value?: N | undefined): Promise<IteratorResult<T, R | undefined>>;
+    /**
+     * Finish the source sequence early, recording the returned value.
+     *
+     * @param value Optional value to return from the source sequence.
+     * @returns Promise resolving to the final `IteratorResult` from the source sequence.
+     * @example await watch.return()
+     * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence/return
+     */
     return(value?: R | undefined | PromiseLike<R | undefined>): Promise<IteratorResult<T, R | undefined>>;
+    /**
+     * Throw an error into the source sequence, recording the resulting value.
+     *
+     * @param reason The reason to throw into the source sequence.
+     * @returns Promise resolving to the `IteratorResult` produced after throwing.
+     * @example await watch.throw(new Error("stop"))
+     * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence/throw
+     */
     throw(reason?: unknown): Promise<IteratorResult<T, R | undefined>>;
     /** Capture a result. */
     private _inspect;

package/sequence/InspectSequence.js

@@ -12,19 +12,35 @@ const _NOVALUE = Symbol("shelving/InspectSequence.NOVALUE");
  * 	for await (const next of capture) console.log("YIELDED", next);
  * 	console.log("FIRST", watch.first);
  * 	console.log("RETURNED", watch.returned);
+ * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence
  */
 export class InspectSequence extends ThroughSequence {
-    /** Get the number of results received by this iterator so far. */
+    /**
+     * The number of values yielded by the source sequence so far.
+     *
+     * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence/count
+     */
     get count() {
         return this._count;
     }
     _count = 0;
-    /** Is the iteration done? */
+    /**
+     * Whether the source sequence has finished iterating (i.e. it has returned).
+     *
+     * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence/done
+     */
     get done() {
         return this._done;
     }
     _done = false;
-    /** The first yielded value (throws if the iteration yielded no values, i.e. `this.count === 0`). */
+    /**
+     * The first value yielded by the source sequence.
+     *
+     * - Throws if the iteration yielded no values yet, i.e. `this.count === 0`.
+     *
+     * @throws {UnexpectedError} If iteration has not yielded any value yet.
+     * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence/first
+     */
     get first() {
         if (this._first === _NOVALUE)
             throw new UnexpectedError("Iteration not started", {
@@ -34,7 +50,14 @@ export class InspectSequence extends ThroughSequence {
         return this._first;
     }
     _first = _NOVALUE;
-    /** The last yielded value (throws if the iteration yielded no values, i.e. `this.count === 0`). */
+    /**
+     * The last value yielded by the source sequence.
+     *
+     * - Throws if the iteration yielded no values yet, i.e. `this.count === 0`.
+     *
+     * @throws {UnexpectedError} If iteration has not yielded any value yet.
+     * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence/last
+     */
     get last() {
         if (this._last === _NOVALUE)
             throw new UnexpectedError("Iteration not started", {
@@ -44,7 +67,14 @@ export class InspectSequence extends ThroughSequence {
         return this._last;
     }
     _last = _NOVALUE;
-    /** The returned value (throws if the iteration is not done, i.e. `this.done === false`). */
+    /**
+     * The value returned by the source sequence when it finished.
+     *
+     * - Throws if the iteration is not done yet, i.e. `this.done === false`.
+     *
+     * @throws {UnexpectedError} If iteration is not done yet.
+     * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence/returned
+     */
     get returned() {
         if (this._returned === _NOVALUE)
             throw new UnexpectedError("Iteration not done", {
@@ -55,12 +85,36 @@ export class InspectSequence extends ThroughSequence {
     }
     _returned = _NOVALUE;
     // Override to watch returned values.
+    /**
+     * Advance the source sequence by one step, recording the yielded or returned value.
+     *
+     * @param value Optional value passed into the source sequence's `next()`.
+     * @returns Promise resolving to the next `IteratorResult` from the source sequence.
+     * @example const { value, done } = await watch.next()
+     * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence/next
+     */
     async next(value) {
         return this._inspect(await super.next(value));
     }
+    /**
+     * Finish the source sequence early, recording the returned value.
+     *
+     * @param value Optional value to return from the source sequence.
+     * @returns Promise resolving to the final `IteratorResult` from the source sequence.
+     * @example await watch.return()
+     * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence/return
+     */
     async return(value) {
         return this._inspect(await super.return(value));
     }
+    /**
+     * Throw an error into the source sequence, recording the resulting value.
+     *
+     * @param reason The reason to throw into the source sequence.
+     * @returns Promise resolving to the `IteratorResult` produced after throwing.
+     * @example await watch.throw(new Error("stop"))
+     * @see https://dhoulb.github.io/shelving/sequence/InspectSequence/InspectSequence/throw
+     */
     async throw(reason) {
         return this._inspect(await super.throw(reason));
     }

package/sequence/LazySequence.d.ts

@@ -1,11 +1,31 @@
 import { type StartCallback } 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 declare class LazySequence<T = void, R = void, N = void> extends ThroughSequence<T, R, N> implements AsyncDisposable {
     private _iterators;
     private _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(): number;
+    /**
+     * 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: AsyncIterator<T, R, N>, start: StartCallback);
     [Symbol.asyncIterator](): LazyIterator<T, R, N>;
     [Symbol.asyncDispose](): Promise<void>;
@@ -13,12 +33,20 @@ export declare class LazySequence<T = void, R = void, N = void> extends ThroughS
      * 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: LazyIterator<T, R, N>): void;
     /**
      * 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: LazyIterator<T, R, N>): void;
 }