shelving 1.236.0 → 1.236.2

package/extract/FileExtractor.d.ts

@@ -10,14 +10,32 @@ import { Extractor } from "./Extractor.js";
  *   and used by `MergingExtractor` to pair siblings (`{base}.md` + `{base}.ts`) and by `PackageExtractor` to look up sources.
  * - Does NOT set `title` — `title` is only set by subclasses that have a confident source for one (e.g. `MarkupExtractor` uses the first `<h1>`). Renderers fall back to `name` when missing.
  * - Subclasses (e.g. `MarkupExtractor`, `TypescriptExtractor`) override `extractProps()` to parse the content into richer elements.
+ *
+ * @example new FileExtractor().extract(Bun.file("/abs/path/notes.txt"))
+ * @see https://dhoulb.github.io/shelving/extract/FileExtractor/FileExtractor
  */
 export declare class FileExtractor extends Extractor<BunFile, TreeElement> {
+    /**
+     * Read a file and build a `tree-element` from its text content.
+     *
+     * @param file The Bun file to read; its `name` must be an absolute path.
+     * @returns A promise resolving to the file's `tree-element`, keyed by its verbatim filename.
+     * @throws RequiredError If the file has no name or its path is not absolute.
+     * @example await new FileExtractor().extract(Bun.file("/abs/path/notes.txt"))
+     * @see https://dhoulb.github.io/shelving/extract/FileExtractor/FileExtractor/extract
+     */
     extract(file: BunFile): Promise<TreeElement>;
     /**
      * Build the file element props from the extracted content.
      * - `name` is the basename without extension (e.g. `"array"`) — display-ready, used by menus, cards, and URL paths.
      * - Override to parse `text` into richer elements (content/children/description) and to set
      *   `title` if a confident title is available.
+     *
+     * @param name The basename of the file without extension (e.g. `"array"`).
+     * @param content The raw text content of the file.
+     * @returns The element props, always including a `name`; the base implementation stores `content` verbatim.
+     * @example extractProps("notes", "Some text") // { name: "notes", content: "Some text" }
+     * @see https://dhoulb.github.io/shelving/extract/FileExtractor/FileExtractor/extractProps
      */
     extractProps(name: string, content: string): Partial<TreeElementProps> & {
         name: string;

package/extract/FileExtractor.js

@@ -11,8 +11,20 @@ import { Extractor } from "./Extractor.js";
  *   and used by `MergingExtractor` to pair siblings (`{base}.md` + `{base}.ts`) and by `PackageExtractor` to look up sources.
  * - Does NOT set `title` — `title` is only set by subclasses that have a confident source for one (e.g. `MarkupExtractor` uses the first `<h1>`). Renderers fall back to `name` when missing.
  * - Subclasses (e.g. `MarkupExtractor`, `TypescriptExtractor`) override `extractProps()` to parse the content into richer elements.
+ *
+ * @example new FileExtractor().extract(Bun.file("/abs/path/notes.txt"))
+ * @see https://dhoulb.github.io/shelving/extract/FileExtractor/FileExtractor
  */
 export class FileExtractor extends Extractor {
+    /**
+     * Read a file and build a `tree-element` from its text content.
+     *
+     * @param file The Bun file to read; its `name` must be an absolute path.
+     * @returns A promise resolving to the file's `tree-element`, keyed by its verbatim filename.
+     * @throws RequiredError If the file has no name or its path is not absolute.
+     * @example await new FileExtractor().extract(Bun.file("/abs/path/notes.txt"))
+     * @see https://dhoulb.github.io/shelving/extract/FileExtractor/FileExtractor/extract
+     */
     async extract(file) {
         const source = file.name;
         if (!source || !isAbsolutePath(source))
@@ -32,6 +44,12 @@ export class FileExtractor extends Extractor {
      * - `name` is the basename without extension (e.g. `"array"`) — display-ready, used by menus, cards, and URL paths.
      * - Override to parse `text` into richer elements (content/children/description) and to set
      *   `title` if a confident title is available.
+     *
+     * @param name The basename of the file without extension (e.g. `"array"`).
+     * @param content The raw text content of the file.
+     * @returns The element props, always including a `name`; the base implementation stores `content` verbatim.
+     * @example extractProps("notes", "Some text") // { name: "notes", content: "Some text" }
+     * @see https://dhoulb.github.io/shelving/extract/FileExtractor/FileExtractor/extractProps
      */
     extractProps(name, content) {
         return { name, content };

package/extract/IndexExtractor.d.ts

@@ -2,7 +2,11 @@ import { type Matchables } from "../util/regexp.js";
 import type { TreeElement } from "../util/tree.js";
 import type { Extractor } from "./Extractor.js";
 import { ThroughExtractor } from "./ThroughExtractor.js";
-/** Options for an `IndexExtractor`. */
+/**
+ * Options for an `IndexExtractor`.
+ *
+ * @see https://dhoulb.github.io/shelving/extract/IndexExtractor/IndexExtractorOptions
+ */
 export interface IndexExtractorOptions {
     /**
      * Filename patterns treated as a parent's index. Matched case-insensitively against each child element's `key`.
@@ -16,9 +20,40 @@ export interface IndexExtractorOptions {
  * - The matched child's `title`, `description`, `content`, and `children` are folded into the parent.
  * - The matched child is removed from the parent's children list.
  * - Purely name-based: it doesn't care whether an element is a directory or a file — any element with children is processed, deepest level first.
+ *
+ * @example
+ * ```ts
+ * const extractor = new IndexExtractor(new DirectoryExtractor());
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/extract/IndexExtractor
  */
 export declare class IndexExtractor<I> extends ThroughExtractor<I, TreeElement> {
     private readonly _index;
+    /**
+     * Wrap a source extractor so each element's index child is absorbed into the element itself.
+     *
+     * @param source Upstream extractor that produces the `tree-element` tree to process.
+     * @param options Options including the `index` filename patterns.
+     *
+     * @example
+     * ```ts
+     * const extractor = new IndexExtractor(new DirectoryExtractor());
+     * ```
+     */
     constructor(source: Extractor<I, TreeElement>, { index }?: IndexExtractorOptions);
+    /**
+     * Extract the source tree and absorb each element's index child into its parent.
+     *
+     * @param input Input forwarded to the wrapped source extractor.
+     * @returns The source tree with index children folded into their parents.
+     *
+     * @example
+     * ```ts
+     * const tree = await new IndexExtractor(source).extract(input);
+     * ```
+     *
+     * @see https://dhoulb.github.io/shelving/extract/IndexExtractor/extract
+     */
     extract(input: I): Promise<TreeElement>;
 }

package/extract/IndexExtractor.js

@@ -14,13 +14,44 @@ const DEFAULT_INDEX = [/^readme\.txt$/i, /^readme\.md$/i, /^index\.md$/i, /^inde
  * - The matched child's `title`, `description`, `content`, and `children` are folded into the parent.
  * - The matched child is removed from the parent's children list.
  * - Purely name-based: it doesn't care whether an element is a directory or a file — any element with children is processed, deepest level first.
+ *
+ * @example
+ * ```ts
+ * const extractor = new IndexExtractor(new DirectoryExtractor());
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/extract/IndexExtractor
  */
 export class IndexExtractor extends ThroughExtractor {
     _index;
+    /**
+     * Wrap a source extractor so each element's index child is absorbed into the element itself.
+     *
+     * @param source Upstream extractor that produces the `tree-element` tree to process.
+     * @param options Options including the `index` filename patterns.
+     *
+     * @example
+     * ```ts
+     * const extractor = new IndexExtractor(new DirectoryExtractor());
+     * ```
+     */
     constructor(source, { index = DEFAULT_INDEX } = {}) {
         super(source);
         this._index = index;
     }
+    /**
+     * Extract the source tree and absorb each element's index child into its parent.
+     *
+     * @param input Input forwarded to the wrapped source extractor.
+     * @returns The source tree with index children folded into their parents.
+     *
+     * @example
+     * ```ts
+     * const tree = await new IndexExtractor(source).extract(input);
+     * ```
+     *
+     * @see https://dhoulb.github.io/shelving/extract/IndexExtractor/extract
+     */
     async extract(input) {
         const root = await this.source.extract(input);
         return _absorbIndex(root, this._index);

package/extract/MarkupExtractor.d.ts

@@ -8,8 +8,21 @@ import { FileExtractor } from "./FileExtractor.js";
  * - When a `title` is found, strips the leading `# h1` from `content` so renderers (which show
  *   `title` separately) don't display the heading twice.
  * - Sets `description` to the first prose paragraph as a plain-text summary (used for card listings and `<meta>`).
+ *
+ * @example new MarkupExtractor().extract(Bun.file("/abs/path/README.md"))
+ * @see https://dhoulb.github.io/shelving/extract/MarkupExtractor/MarkupExtractor
  */
 export declare class MarkupExtractor extends FileExtractor {
+    /**
+     * Build the file element props for a Markdown file — storing the text as `content` and deriving `title` and `description`.
+     * - When a `# h1` title is found it is stripped from `content` so it isn't rendered twice.
+     *
+     * @param name The basename of the file without extension.
+     * @param text The raw Markdown source.
+     * @returns The element props with `name`, `content`, and (when present) `title` and `description`.
+     * @example new MarkupExtractor().extractProps("guide", "# Guide\n\nIntro text.")
+     * @see https://dhoulb.github.io/shelving/extract/MarkupExtractor/MarkupExtractor/extractProps
+     */
     extractProps(name: string, text: string): Partial<TreeElementProps> & {
         name: string;
     };
@@ -22,6 +35,8 @@ export declare class MarkupExtractor extends FileExtractor {
  *
  * @param text The markdown source string (a markdown file's text, or a JSDoc description).
  * @returns An object whose `title` and `description` are each a plain string, or `undefined` when absent.
+ * @example extractMarkdownProps("# Title\n\nSome intro.") // { title: "Title", description: "Some intro." }
+ * @see https://dhoulb.github.io/shelving/extract/MarkupExtractor/extractMarkdownProps
  */
 export declare function extractMarkdownProps(text: string): {
     title: string | undefined;

package/extract/MarkupExtractor.js

@@ -9,8 +9,21 @@ import { FileExtractor } from "./FileExtractor.js";
  * - When a `title` is found, strips the leading `# h1` from `content` so renderers (which show
  *   `title` separately) don't display the heading twice.
  * - Sets `description` to the first prose paragraph as a plain-text summary (used for card listings and `<meta>`).
+ *
+ * @example new MarkupExtractor().extract(Bun.file("/abs/path/README.md"))
+ * @see https://dhoulb.github.io/shelving/extract/MarkupExtractor/MarkupExtractor
  */
 export class MarkupExtractor extends FileExtractor {
+    /**
+     * Build the file element props for a Markdown file — storing the text as `content` and deriving `title` and `description`.
+     * - When a `# h1` title is found it is stripped from `content` so it isn't rendered twice.
+     *
+     * @param name The basename of the file without extension.
+     * @param text The raw Markdown source.
+     * @returns The element props with `name`, `content`, and (when present) `title` and `description`.
+     * @example new MarkupExtractor().extractProps("guide", "# Guide\n\nIntro text.")
+     * @see https://dhoulb.github.io/shelving/extract/MarkupExtractor/MarkupExtractor/extractProps
+     */
     extractProps(name, text) {
         const { title, description } = extractMarkdownProps(text);
         // The title `# h1` is surfaced separately as `title`, so strip it from the body to avoid rendering it twice.
@@ -25,6 +38,8 @@ export class MarkupExtractor extends FileExtractor {
  *
  * @param text The markdown source string (a markdown file's text, or a JSDoc description).
  * @returns An object whose `title` and `description` are each a plain string, or `undefined` when absent.
+ * @example extractMarkdownProps("# Title\n\nSome intro.") // { title: "Title", description: "Some intro." }
+ * @see https://dhoulb.github.io/shelving/extract/MarkupExtractor/extractMarkdownProps
  */
 export function extractMarkdownProps(text) {
     let title;

package/extract/MergingExtractor.d.ts

@@ -2,7 +2,11 @@ import type { ImmutableDictionary } from "../util/dictionary.js";
 import type { TreeElement } from "../util/tree.js";
 import type { Extractor } from "./Extractor.js";
 import { ThroughExtractor } from "./ThroughExtractor.js";
-/** Options for a `MergingExtractor`. */
+/**
+ * Options for a `MergingExtractor`.
+ *
+ * @see https://dhoulb.github.io/shelving/extract/MergingExtractor/MergingExtractorOptions
+ */
 export interface MergingExtractorOptions {
     /**
      * Templated key pairs that should merge. Each key is a `{base}` template matched against the secondary element's key;
@@ -19,9 +23,40 @@ export interface MergingExtractorOptions {
  * - The primary (winning) element keeps its `key`, `source`, and `type`; the secondary's `title`, `description`,
  *   `content`, and `children` are folded in via `mergeTreeElements()`.
  * - A secondary with no matching primary is left in place — pure prose files (e.g. `concepts.md` with no `concepts.ts`) stand alone.
+ *
+ * @example
+ * ```ts
+ * const extractor = new MergingExtractor(new DirectoryExtractor());
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/extract/MergingExtractor
  */
 export declare class MergingExtractor<I> extends ThroughExtractor<I, TreeElement> {
     private readonly _merges;
+    /**
+     * Wrap a source extractor so its produced tree has same-template sibling elements merged.
+     *
+     * @param source Upstream extractor that produces the `tree-element` tree to merge.
+     * @param options Options including the `merges` template map.
+     *
+     * @example
+     * ```ts
+     * const extractor = new MergingExtractor(new DirectoryExtractor());
+     * ```
+     */
     constructor(source: Extractor<I, TreeElement>, { merges }?: MergingExtractorOptions);
+    /**
+     * Extract the source tree and merge same-template sibling elements at every level.
+     *
+     * @param input Input forwarded to the wrapped source extractor.
+     * @returns The source tree with matching sibling elements merged together.
+     *
+     * @example
+     * ```ts
+     * const tree = await new MergingExtractor(source).extract(input);
+     * ```
+     *
+     * @see https://dhoulb.github.io/shelving/extract/MergingExtractor/extract
+     */
     extract(input: I): Promise<TreeElement>;
 }

package/extract/MergingExtractor.js

@@ -18,13 +18,44 @@ const DEFAULT_MERGES = {
  * - The primary (winning) element keeps its `key`, `source`, and `type`; the secondary's `title`, `description`,
  *   `content`, and `children` are folded in via `mergeTreeElements()`.
  * - A secondary with no matching primary is left in place — pure prose files (e.g. `concepts.md` with no `concepts.ts`) stand alone.
+ *
+ * @example
+ * ```ts
+ * const extractor = new MergingExtractor(new DirectoryExtractor());
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/extract/MergingExtractor
  */
 export class MergingExtractor extends ThroughExtractor {
     _merges;
+    /**
+     * Wrap a source extractor so its produced tree has same-template sibling elements merged.
+     *
+     * @param source Upstream extractor that produces the `tree-element` tree to merge.
+     * @param options Options including the `merges` template map.
+     *
+     * @example
+     * ```ts
+     * const extractor = new MergingExtractor(new DirectoryExtractor());
+     * ```
+     */
     constructor(source, { merges = DEFAULT_MERGES } = {}) {
         super(source);
         this._merges = merges;
     }
+    /**
+     * Extract the source tree and merge same-template sibling elements at every level.
+     *
+     * @param input Input forwarded to the wrapped source extractor.
+     * @returns The source tree with matching sibling elements merged together.
+     *
+     * @example
+     * ```ts
+     * const tree = await new MergingExtractor(source).extract(input);
+     * ```
+     *
+     * @see https://dhoulb.github.io/shelving/extract/MergingExtractor/extract
+     */
     async extract(input) {
         const root = await this.source.extract(input);
         return _mergeElement(root, this._merges);

package/extract/ModuleExtractor.d.ts

@@ -1,6 +1,10 @@
 import type { DocumentationElement, TreeElement } from "../util/tree.js";
 import { Extractor } from "./Extractor.js";
-/** Input for a `ModuleExtractor`. */
+/**
+ * Input for a `ModuleExtractor`.
+ *
+ * @see https://dhoulb.github.io/shelving/extract/ModuleExtractor/ModuleExtractorInput
+ */
 export interface ModuleExtractorInput {
     /** Display name for the module, derived from the package.json export key (e.g. `"util/string"`, `"firestore/client"`). */
     readonly name: string;
@@ -17,7 +21,27 @@ export interface ModuleExtractorInput {
  *   `IndexExtractor` are expected to have run upstream so `.md` siblings and `README.md` are already folded in).
  * - The module's `children` are every `tree-documentation` element found by deep-walking the source — flattened across
  *   files and subdirectories, but never descending into a `tree-documentation`'s own members.
+ *
+ * @example
+ * ```ts
+ * const module = new ModuleExtractor().extract({ name: "util/string", source });
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/extract/ModuleExtractor
  */
 export declare class ModuleExtractor extends Extractor<ModuleExtractorInput, DocumentationElement> {
+    /**
+     * Build a `kind: "module"` `DocumentationElement` from a source file or directory element.
+     *
+     * @param input Module name and source element to build from.
+     * @returns `tree-documentation` element of `kind: "module"` with flattened documented children.
+     *
+     * @example
+     * ```ts
+     * const module = new ModuleExtractor().extract({ name: "util/string", source });
+     * ```
+     *
+     * @see https://dhoulb.github.io/shelving/extract/ModuleExtractor/extract
+     */
     extract({ name, source }: ModuleExtractorInput): DocumentationElement;
 }

package/extract/ModuleExtractor.js

@@ -7,8 +7,28 @@ import { Extractor } from "./Extractor.js";
  *   `IndexExtractor` are expected to have run upstream so `.md` siblings and `README.md` are already folded in).
  * - The module's `children` are every `tree-documentation` element found by deep-walking the source — flattened across
  *   files and subdirectories, but never descending into a `tree-documentation`'s own members.
+ *
+ * @example
+ * ```ts
+ * const module = new ModuleExtractor().extract({ name: "util/string", source });
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/extract/ModuleExtractor
  */
 export class ModuleExtractor extends Extractor {
+    /**
+     * Build a `kind: "module"` `DocumentationElement` from a source file or directory element.
+     *
+     * @param input Module name and source element to build from.
+     * @returns `tree-documentation` element of `kind: "module"` with flattened documented children.
+     *
+     * @example
+     * ```ts
+     * const module = new ModuleExtractor().extract({ name: "util/string", source });
+     * ```
+     *
+     * @see https://dhoulb.github.io/shelving/extract/ModuleExtractor/extract
+     */
     extract({ name, source }) {
         const children = _collectChildren(source);
         return {

package/extract/PackageExtractor.d.ts

@@ -3,7 +3,11 @@ import { type AbsolutePath, type Path } from "../util/path.js";
 import type { TreeElement } from "../util/tree.js";
 import { Extractor } from "./Extractor.js";
 import { ModuleExtractor } from "./ModuleExtractor.js";
-/** Options for a `PackageExtractor`. */
+/**
+ * Options for a `PackageExtractor`.
+ *
+ * @see https://dhoulb.github.io/shelving/extract/PackageExtractor/PackageExtractorOptions
+ */
 export interface PackageExtractorOptions {
     /**
      * Pre-extracted source tree the `package.json` exports resolve against — typically the result of
@@ -30,13 +34,44 @@ export interface PackageExtractorOptions {
  * - Each export's *target* extension (e.g. the `.js` in `"./util/*.js"`) is mapped to source extensions via `extensions`, so built `.js` paths resolve to their `.ts` sources.
  * - The `"."` root export is skipped — its content is the root tree element itself.
  * - Throws if a static export key has no matching source element in the tree.
+ *
+ * @example
+ * ```ts
+ * const tree = await new PackageExtractor({ tree: sourceTree }).extract("package.json");
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/extract/PackageExtractor
  */
 export declare class PackageExtractor extends Extractor<Path, TreeElement> {
     private readonly _tree;
     private readonly _extensions;
     private readonly _module;
     private readonly _base;
+    /**
+     * Create a package extractor bound to a pre-extracted source tree.
+     *
+     * @param options Options including the source `tree`, `extensions` mapping, `module` extractor, and `base` path.
+     *
+     * @example
+     * ```ts
+     * const extractor = new PackageExtractor({ tree: sourceTree });
+     * ```
+     */
     constructor({ tree, extensions, module, base }: PackageExtractorOptions);
+    /**
+     * Read a `package.json` and produce a flat tree of one module element per export entry.
+     *
+     * @param packageJson Path of the `package.json` to read — resolved against the configured `base`.
+     * @returns Promise of the root `tree-element` whose children are the module elements.
+     * @throws Error If a static export key has no matching source element in the tree, or a wildcard export is malformed.
+     *
+     * @example
+     * ```ts
+     * const tree = await new PackageExtractor({ tree: sourceTree }).extract("package.json");
+     * ```
+     *
+     * @see https://dhoulb.github.io/shelving/extract/PackageExtractor/extract
+     */
     extract(packageJson: Path): Promise<TreeElement>;
     /** Source extensions to try for an export `target`, derived from the target's own extension via the `extensions` mapping. */
     private _sourceExtensions;

package/extract/PackageExtractor.js

@@ -18,12 +18,29 @@ const DEFAULT_EXTENSIONS = {
  * - Each export's *target* extension (e.g. the `.js` in `"./util/*.js"`) is mapped to source extensions via `extensions`, so built `.js` paths resolve to their `.ts` sources.
  * - The `"."` root export is skipped — its content is the root tree element itself.
  * - Throws if a static export key has no matching source element in the tree.
+ *
+ * @example
+ * ```ts
+ * const tree = await new PackageExtractor({ tree: sourceTree }).extract("package.json");
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/extract/PackageExtractor
  */
 export class PackageExtractor extends Extractor {
     _tree;
     _extensions;
     _module;
     _base;
+    /**
+     * Create a package extractor bound to a pre-extracted source tree.
+     *
+     * @param options Options including the source `tree`, `extensions` mapping, `module` extractor, and `base` path.
+     *
+     * @example
+     * ```ts
+     * const extractor = new PackageExtractor({ tree: sourceTree });
+     * ```
+     */
     constructor({ tree, extensions = DEFAULT_EXTENSIONS, module = new ModuleExtractor(), base }) {
         super();
         this._tree = tree;
@@ -31,6 +48,20 @@ export class PackageExtractor extends Extractor {
         this._module = module;
         this._base = base;
     }
+    /**
+     * Read a `package.json` and produce a flat tree of one module element per export entry.
+     *
+     * @param packageJson Path of the `package.json` to read — resolved against the configured `base`.
+     * @returns Promise of the root `tree-element` whose children are the module elements.
+     * @throws Error If a static export key has no matching source element in the tree, or a wildcard export is malformed.
+     *
+     * @example
+     * ```ts
+     * const tree = await new PackageExtractor({ tree: sourceTree }).extract("package.json");
+     * ```
+     *
+     * @see https://dhoulb.github.io/shelving/extract/PackageExtractor/extract
+     */
     async extract(packageJson) {
         const pkgPath = requirePath(packageJson, this._base, this.extract);
         const pkg = (await Bun.file(pkgPath).json());

package/extract/ThroughExtractor.d.ts

@@ -4,10 +4,31 @@ import { Extractor } from "./Extractor.js";
  * Base class for an extractor that wraps another extractor.
  * - Subclasses delegate to `source` and (optionally) transform the input before or the output after.
  * - Composes the same way `Through*Provider` chains do — chain multiple `ThroughExtractor`s to build up behaviour.
+ *
+ * @example new MergingExtractor(new DirectoryExtractor()) // a ThroughExtractor wrapping a source extractor
+ * @see https://dhoulb.github.io/shelving/extract/ThroughExtractor/ThroughExtractor
  */
 export declare abstract class ThroughExtractor<I, O extends TreeElement = TreeElement> extends Extractor<I, O> {
+    /**
+     * The wrapped source extractor this through extractor delegates to.
+     * @see https://dhoulb.github.io/shelving/extract/ThroughExtractor/ThroughExtractor/source
+     */
     readonly source: Extractor<I, O>;
+    /**
+     * Create a `ThroughExtractor` wrapping a source extractor.
+     *
+     * @param source The inner extractor to delegate to.
+     * @see https://dhoulb.github.io/shelving/extract/ThroughExtractor/ThroughExtractor
+     */
     constructor(source: Extractor<I, O>);
-    /** Default implementation forwards to `source.extract()`. Subclasses override to do work before or after. */
+    /**
+     * Extract from the input by forwarding to `source.extract()`.
+     * - Default implementation is a pass-through; subclasses override to do work before or after.
+     *
+     * @param input The input value to extract from.
+     * @returns The extracted `TreeElement`, or a promise resolving to one.
+     * @example await myThroughExtractor.extract(input)
+     * @see https://dhoulb.github.io/shelving/extract/ThroughExtractor/ThroughExtractor/extract
+     */
     extract(input: I): O | Promise<O>;
 }

package/extract/ThroughExtractor.js

@@ -3,14 +3,35 @@ import { Extractor } from "./Extractor.js";
  * Base class for an extractor that wraps another extractor.
  * - Subclasses delegate to `source` and (optionally) transform the input before or the output after.
  * - Composes the same way `Through*Provider` chains do — chain multiple `ThroughExtractor`s to build up behaviour.
+ *
+ * @example new MergingExtractor(new DirectoryExtractor()) // a ThroughExtractor wrapping a source extractor
+ * @see https://dhoulb.github.io/shelving/extract/ThroughExtractor/ThroughExtractor
  */
 export class ThroughExtractor extends Extractor {
+    /**
+     * The wrapped source extractor this through extractor delegates to.
+     * @see https://dhoulb.github.io/shelving/extract/ThroughExtractor/ThroughExtractor/source
+     */
     source;
+    /**
+     * Create a `ThroughExtractor` wrapping a source extractor.
+     *
+     * @param source The inner extractor to delegate to.
+     * @see https://dhoulb.github.io/shelving/extract/ThroughExtractor/ThroughExtractor
+     */
     constructor(source) {
         super();
         this.source = source;
     }
-    /** Default implementation forwards to `source.extract()`. Subclasses override to do work before or after. */
+    /**
+     * Extract from the input by forwarding to `source.extract()`.
+     * - Default implementation is a pass-through; subclasses override to do work before or after.
+     *
+     * @param input The input value to extract from.
+     * @returns The extracted `TreeElement`, or a promise resolving to one.
+     * @example await myThroughExtractor.extract(input)
+     * @see https://dhoulb.github.io/shelving/extract/ThroughExtractor/ThroughExtractor/extract
+     */
     extract(input) {
         return this.source.extract(input);
     }

package/extract/TypescriptExtractor.d.ts

@@ -13,8 +13,29 @@ import { FileExtractor } from "./FileExtractor.js";
  * - Members declared with the `override` or `declare` modifier are skipped — the base class already documents overrides, and `declare` members are ambient type-only re-declarations rather than new API.
  * - Keys are the raw declared `name` (case-preserving) so case-distinct exports like `Collection` and `COLLECTION` stay separate.
  * - The file element itself has no `title` — a TS source file has no confident title source; renderers fall back to `name`.
+ *
+ * @example
+ * ```ts
+ * const element = new TypescriptExtractor().extractProps("string.ts", sourceText);
+ * ```
+ *
+ * @see https://dhoulb.github.io/shelving/extract/TypescriptExtractor
  */
 export declare class TypescriptExtractor extends FileExtractor {
+    /**
+     * Parse a TypeScript source file into the props of a `tree-element`.
+     *
+     * @param name Filename of the source (used as the source file name and the element `name`).
+     * @param text Full TypeScript source text to parse.
+     * @returns Partial `tree-element` props with `name`, `description`, `content`, and `children`.
+     *
+     * @example
+     * ```ts
+     * const props = new TypescriptExtractor().extractProps("string.ts", sourceText);
+     * ```
+     *
+     * @see https://dhoulb.github.io/shelving/extract/TypescriptExtractor/extractProps
+     */
     extractProps(name: string, text: string): Partial<TreeElementProps> & {
         name: string;
     };