shelving 1.202.0 → 1.204.0

package/api/provider/APIProvider.d.ts

@@ -32,7 +32,7 @@ export declare abstract class APIProvider<P = unknown, R = unknown> implements A
      * @throws {RequiredError} if this endpoint's path has `{placeholders}` but `payload` is not a data object.
      * @throws {RequiredError} if this is a `HEAD` or `GET` request but `payload` is not a data object.
      */
-    abstract getRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
+    abstract createRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
     /** Fetch a `Resource` using this provider (defaults to Javascript `fetch()` API). */
     abstract fetch(request: Request): Promise<Response>;
     /**

package/api/provider/APIProvider.js

@@ -2,7 +2,7 @@
 export class APIProvider {
     /** Send a payload to an `Endpoint` and retrieve the result. */
     async call(endpoint, payload, options, caller) {
-        const request = this.getRequest(endpoint, payload, options, caller);
+        const request = this.createRequest(endpoint, payload, options, caller);
         const response = await this.fetch(request);
         return this.parseResponse(endpoint, response, caller);
     }

package/api/provider/ClientAPIProvider.d.ts

@@ -17,7 +17,7 @@ export interface ClientAPIProviderOptions {
      */
     readonly url: PossibleURL;
     /**
-     * Options used for HTTP requests created with `this.getRequest()` and `this.fetch()`
+     * Options used for HTTP requests created with `this.createRequest()` and `this.fetch()`
      * - Omits `signal` because it's not relevant at the provider level.
      */
     readonly options?: Omit<RequestOptions, "signal">;
@@ -33,24 +33,24 @@ export interface ClientAPIProviderOptions {
  * - Can be used on a server environment to make outgoing API calls, or in a browser environment to call a server API.
  * - Renders endpoint paths and query params into the URL and sends body payloads as JSON.
  * - Parses JSON responses and throws `ResponseError` for non-2xx responses.
- * - Extendable with custom request-building and response-parsing logic by overriding `getRequest()` and `parseResponse()`.
+ * - Extendable with custom request-building and response-parsing logic by overriding `createRequest()` and `parseResponse()`.
  * - Wrap in `ValidationAPIProvider` to add automatic validation of request payloads and response results against endpoint schemas.
  */
 export declare class ClientAPIProvider<P = unknown, R = unknown> extends APIProvider<P, R> {
     /** The common base URL for all rendered endpoint requests. */
     readonly url: URL;
-    /** Default options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
+    /** Default options used for HTTP requests created with `this.createRequest()` and `this.fetch()` */
     readonly options: RequestOptions;
     /** Timeout in milliseconds before the request is aborted, or `0` for no timeout. */
     readonly timeout: number;
     constructor({ url, options, timeout }: ClientAPIProviderOptions);
     renderURL<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, caller?: AnyCaller): URL;
-    getRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
-    /** Internal implementation function for `getRequest()` used for requests that have no body. */
-    protected _getHeadRequest(method: RequestHeadMethod, //
+    createRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
+    /** Internal implementation function for `createRequest()` used for requests that have no body. */
+    protected _createHeadRequest(method: RequestHeadMethod, //
     url: PossibleURL, params: Nullish<PossibleURIParams>, options: RequestOptions, caller: AnyCaller): Request;
-    /** Internal implementation function for `getRequest()` used for requests that have a body.  */
-    protected _getBodyRequest(method: RequestBodyMethod, //
+    /** Internal implementation function for `createRequest()` used for requests that have a body.  */
+    protected _createBodyRequest(method: RequestBodyMethod, //
     url: PossibleURL, payload: P, options: RequestOptions, caller: AnyCaller): Request;
     fetch(request: Request): Promise<Response>;
     parseResponse<PP extends P, RR extends R>(_endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;

package/api/provider/ClientAPIProvider.js

@@ -1,7 +1,7 @@
 import { ResponseError } from "../../error/ResponseError.js";
 import { isData } from "../../util/data.js";
 import { getMessage } from "../../util/error.js";
-import { assertRequestHeadPayload, getHeadRequest, getRequest, isRequestHeadMethod, mergeRequestOptions, parseResponseBody, } from "../../util/http.js";
+import { assertRequestHeadPayload, createHeadRequest, createRequest, isRequestHeadMethod, mergeRequestOptions, parseResponseBody, } from "../../util/http.js";
 import { omitProps } from "../../util/object.js";
 import { withURIParams } from "../../util/uri.js";
 import { requireBaseURL, requireURL } from "../../util/url.js";
@@ -11,13 +11,13 @@ import { APIProvider } from "./APIProvider.js";
  * - Can be used on a server environment to make outgoing API calls, or in a browser environment to call a server API.
  * - Renders endpoint paths and query params into the URL and sends body payloads as JSON.
  * - Parses JSON responses and throws `ResponseError` for non-2xx responses.
- * - Extendable with custom request-building and response-parsing logic by overriding `getRequest()` and `parseResponse()`.
+ * - Extendable with custom request-building and response-parsing logic by overriding `createRequest()` and `parseResponse()`.
  * - Wrap in `ValidationAPIProvider` to add automatic validation of request payloads and response results against endpoint schemas.
  */
 export class ClientAPIProvider extends APIProvider {
     /** The common base URL for all rendered endpoint requests. */
     url;
-    /** Default options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
+    /** Default options used for HTTP requests created with `this.createRequest()` and `this.fetch()` */
     options;
     /** Timeout in milliseconds before the request is aborted, or `0` for no timeout. */
     timeout;
@@ -43,7 +43,7 @@ export class ClientAPIProvider extends APIProvider {
         }
         return url;
     }
-    getRequest(endpoint, payload, options, caller = this.getRequest) {
+    createRequest(endpoint, payload, options, caller = this.createRequest) {
         // Render the path into the base URL.
         const url = this.renderURL(endpoint, payload, caller);
         // Merge the param options with `this.options`
@@ -52,20 +52,20 @@ export class ClientAPIProvider extends APIProvider {
         const mergedOptions = mergeRequestOptions({ signal, ...this.options }, options);
         // HEAD or GET requests need no payload because it was already rendered into the URL as `?query` params by `this.renderURL()`
         if (isRequestHeadMethod(endpoint.method))
-            return this._getHeadRequest(endpoint.method, url, undefined, mergedOptions, caller);
+            return this._createHeadRequest(endpoint.method, url, undefined, mergedOptions, caller);
         // Body request.
         const body = isData(payload) ? omitProps(payload, ...endpoint.placeholders) : payload; // Omit any params that have already been embedded as `{placeholders}`.
-        return this._getBodyRequest(endpoint.method, url, body, mergedOptions, caller);
+        return this._createBodyRequest(endpoint.method, url, body, mergedOptions, caller);
     }
-    /** Internal implementation function for `getRequest()` used for requests that have no body. */
-    _getHeadRequest(method, //
+    /** Internal implementation function for `createRequest()` used for requests that have no body. */
+    _createHeadRequest(method, //
     url, params, options, caller) {
-        return getHeadRequest(method, url, params, options, caller);
+        return createHeadRequest(method, url, params, options, caller);
     }
-    /** Internal implementation function for `getRequest()` used for requests that have a body.  */
-    _getBodyRequest(method, //
+    /** Internal implementation function for `createRequest()` used for requests that have a body.  */
+    _createBodyRequest(method, //
     url, payload, options, caller) {
-        return getRequest(method, url, payload, options, caller);
+        return createRequest(method, url, payload, options, caller);
     }
     // Override to set default functionality of a client provider to send requests over the network with `fetch()` and parse responses with `parseResponse()`.
     async fetch(request) {

package/api/provider/DebugAPIProvider.d.ts

@@ -4,7 +4,7 @@ import type { Endpoint } from "../endpoint/Endpoint.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /** Provider that logs everything to the console in some detail to help diagnose issues in development. */
 export declare class DebugAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
-    getRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
+    createRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
     fetch(request: Request): Promise<Response>;
     parseResponse<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
 }

package/api/provider/DebugAPIProvider.js

@@ -3,9 +3,9 @@ import { debugFullRequest, debugFullResponse, debugRequest } from "../../util/de
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /** Provider that logs everything to the console in some detail to help diagnose issues in development. */
 export class DebugAPIProvider extends ThroughAPIProvider {
-    getRequest(endpoint, payload, options, caller = this.getRequest) {
+    createRequest(endpoint, payload, options, caller = this.createRequest) {
         try {
-            const request = super.getRequest(endpoint, payload, options, caller);
+            const request = super.createRequest(endpoint, payload, options, caller);
             console.debug(`${ANSI_WAITING} ${endpoint.toString()}`, payload);
             return request;
         }

package/api/provider/JSONAPIProvider.d.ts

@@ -5,7 +5,7 @@ import type { Endpoint } from "../endpoint/Endpoint.js";
 import { ClientAPIProvider } from "./ClientAPIProvider.js";
 /** API provider that always sends request bodies as JSON and parses responses as JSON. */
 export declare class JSONAPIProvider<P = unknown, R = unknown> extends ClientAPIProvider<P, R> {
-    protected _getBodyRequest(method: RequestBodyMethod, url: PossibleURL, payload: P, options: RequestOptions, caller: AnyCaller): Request;
+    protected _createBodyRequest(method: RequestBodyMethod, url: PossibleURL, payload: P, options: RequestOptions, caller: AnyCaller): Request;
     /**
      * Parse a JSON `Response` for an endpoint.
      *

package/api/provider/JSONAPIProvider.js

@@ -1,11 +1,11 @@
 import { ResponseError } from "../../error/ResponseError.js";
 import { getMessage } from "../../util/error.js";
-import { getJSONRequest, parseResponseJSON } from "../../util/http.js";
+import { createJSONRequest, parseResponseJSON } from "../../util/http.js";
 import { ClientAPIProvider } from "./ClientAPIProvider.js";
 /** API provider that always sends request bodies as JSON and parses responses as JSON. */
 export class JSONAPIProvider extends ClientAPIProvider {
-    _getBodyRequest(method, url, payload, options, caller) {
-        return getJSONRequest(method, url, payload, options, caller);
+    _createBodyRequest(method, url, payload, options, caller) {
+        return createJSONRequest(method, url, payload, options, caller);
     }
     /**
      * Parse a JSON `Response` for an endpoint.

package/api/provider/MockAPIProvider.d.ts

@@ -29,7 +29,7 @@ export declare class MockAPIProvider<P = unknown, R = unknown> extends ThroughAP
     readonly responseCalls: MockAPIResponseCall[];
     readonly handler: RequestHandler;
     constructor(handler?: RequestHandler, source?: APIProvider<P, R>);
-    getRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
+    createRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
     parseResponse<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
     fetch(request: Request): Promise<Response>;
 }

package/api/provider/MockAPIProvider.js

@@ -19,9 +19,9 @@ export class MockAPIProvider extends ThroughAPIProvider {
         super(source);
         this.handler = handler;
     }
-    // Override `getRequest()` to log the endpoint and payload before delegating to the source provider for request building.
-    getRequest(endpoint, payload, options, caller = this.getRequest) {
-        const request = super.getRequest(endpoint, payload, options, caller);
+    // Override `createRequest()` to log the endpoint and payload before delegating to the source provider for request building.
+    createRequest(endpoint, payload, options, caller = this.createRequest) {
+        const request = super.createRequest(endpoint, payload, options, caller);
         this.requestCalls.push({ endpoint, payload, options, request });
         return request;
     }

package/api/provider/ThroughAPIProvider.d.ts

@@ -12,7 +12,7 @@ export declare class ThroughAPIProvider<P, R> extends APIProvider<P, R> implemen
     readonly source: APIProvider<P, R>;
     constructor(source: APIProvider<P, R>);
     renderURL<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, caller?: AnyCaller): URL;
-    getRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
+    createRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
     parseResponse<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
     fetch(request: Request): Promise<Response>;
     [Symbol.asyncDispose](): Promise<void>;

package/api/provider/ThroughAPIProvider.js

@@ -16,8 +16,8 @@ export class ThroughAPIProvider extends APIProvider {
     renderURL(endpoint, payload, caller = this.renderURL) {
         return this.source.renderURL(endpoint, payload, caller);
     }
-    getRequest(endpoint, payload, options, caller = this.getRequest) {
-        return this.source.getRequest(endpoint, payload, options, caller);
+    createRequest(endpoint, payload, options, caller = this.createRequest) {
+        return this.source.createRequest(endpoint, payload, options, caller);
     }
     parseResponse(endpoint, response, caller = this.parseResponse) {
         return this.source.parseResponse(endpoint, response, caller);

package/api/provider/ValidationAPIProvider.d.ts

@@ -4,6 +4,6 @@ import type { Endpoint } from "../endpoint/Endpoint.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /** Validate an asynchronous source provider (source can have any type because validation guarantees the type). */
 export declare class ValidationAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
-    getRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
+    createRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
     parseResponse<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
 }

package/api/provider/ValidationAPIProvider.js

@@ -2,9 +2,9 @@ import { ResponseError } from "../../error/ResponseError.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /** Validate an asynchronous source provider (source can have any type because validation guarantees the type). */
 export class ValidationAPIProvider extends ThroughAPIProvider {
-    getRequest(endpoint, payload, options, caller = this.getRequest) {
+    createRequest(endpoint, payload, options, caller = this.createRequest) {
         // Validate payload — let thrown strings bubble up as user-readable messages for e.g. form handlers.
-        return super.getRequest(endpoint, endpoint.payload.validate(payload), options, caller);
+        return super.createRequest(endpoint, endpoint.payload.validate(payload), options, caller);
     }
     async parseResponse(endpoint, response, caller = this.parseResponse) {
         try {

package/api/provider/XMLAPIProvider.d.ts

@@ -6,7 +6,7 @@ import type { Endpoint } from "../endpoint/Endpoint.js";
 import { ClientAPIProvider } from "./ClientAPIProvider.js";
 /** API provider that always sends request bodies as XML and parses responses as plain text. */
 export declare class XMLAPIProvider<P extends Data = Data, R extends string = string> extends ClientAPIProvider<P, R> {
-    protected _getBodyRequest(method: RequestBodyMethod, url: PossibleURL, payload: P, options: RequestOptions, caller: AnyCaller): Request;
+    protected _createBodyRequest(method: RequestBodyMethod, url: PossibleURL, payload: P, options: RequestOptions, caller: AnyCaller): Request;
     /**
      * Parse a text `Response` for an endpoint.
      *

package/api/provider/XMLAPIProvider.js

@@ -1,10 +1,10 @@
 import { ResponseError } from "../../error/ResponseError.js";
-import { getXMLRequest } from "../../util/http.js";
+import { createXMLRequest } from "../../util/http.js";
 import { ClientAPIProvider } from "./ClientAPIProvider.js";
 /** API provider that always sends request bodies as XML and parses responses as plain text. */
 export class XMLAPIProvider extends ClientAPIProvider {
-    _getBodyRequest(method, url, payload, options, caller) {
-        return getXMLRequest(method, url, payload, options, caller);
+    _createBodyRequest(method, url, payload, options, caller) {
+        return createXMLRequest(method, url, payload, options, caller);
     }
     /**
      * Parse a text `Response` for an endpoint.

package/db/provider/PostgreSQLProvider.d.ts

@@ -1,6 +1,7 @@
-import type { Data, DataPath } from "../../util/data.js";
+import type { Data } from "../../util/data.js";
 import type { Identifier } from "../../util/item.js";
 import type { QueryFilter } from "../../util/query.js";
+import type { Segments } from "../../util/string.js";
 import type { Update } from "../../util/update.js";
 import { type SQLFragment, SQLProvider } from "./SQLProvider.js";
 /** Abstract PostgreSQL provider with JSONB function support for nested keys, array containment, and array mutations. */
@@ -8,7 +9,7 @@ export declare abstract class PostgreSQLProvider<I extends Identifier = Identifi
     /** Get the Postgres JSONB path for the nested segments of a key, e.g. `{"b","c"}`. */
     private sqlPath;
     /** Get the Postgres JSONB extract syntax, e.g. `"a" #>> {"b","c"}` */
-    sqlExtract(key: DataPath): SQLFragment;
+    sqlExtract(key: Segments): SQLFragment;
     sqlUpdate(update: Update): SQLFragment;
     sqlFilter(filter: QueryFilter): SQLFragment;
 }

package/db/provider/SQLProvider.d.ts

@@ -1,5 +1,6 @@
 import type { ImmutableArray } from "../../util/array.js";
-import type { Data, DataPath } from "../../util/data.js";
+import type { Data } from "../../util/data.js";
+import type { Segments } from "../../util/index.js";
 import type { Identifier, Item, Items, ItemsSequence, OptionalItem, OptionalItemSequence } from "../../util/item.js";
 import { type Query, type QueryFilter, type QueryOrder } from "../../util/query.js";
 import { type Update, type Updates } from "../../util/update.js";
@@ -32,8 +33,8 @@ export declare abstract class SQLProvider<I extends Identifier = Identifier, T e
     sql(strings: TemplateStringsArray, ...values: ImmutableArray<unknown>): SQLFragment;
     /** Define an SQL fragment for an identifier, e.g. `"myTable"` */
     sqlIdentifier(name: string): SQLFragment;
-    /** Define an SQL fragment that extracts a deeply nested calue for comparison, e.g. `"a" #>> {"b","c"}` in Postgres */
-    sqlExtract(key: DataPath): SQLFragment;
+    /** Define an SQL fragment that extracts a deeply nested value for comparison, e.g. `"a" #>> {"b","c"}` in Postgres */
+    sqlExtract(key: Segments): SQLFragment;
     /** Define an SQL fragment to generate a series of values with a separator, e.g. `"a" = 1 AND "b" = 2` */
     sqlConcat(values: ImmutableArray<SQLFragment>, separator?: string, before?: string, after?: string): SQLFragment;
     /** Define an SQL fragment for setting a list of values, e.g. `"a" = 1, "b" = 2` */

package/db/provider/SQLProvider.js

@@ -78,7 +78,7 @@ export class SQLProvider extends DBProvider {
     sqlIdentifier(name) {
         return { strings: [_escapeIdentifier(name)], values: [] };
     }
-    /** Define an SQL fragment that extracts a deeply nested calue for comparison, e.g. `"a" #>> {"b","c"}` in Postgres */
+    /** Define an SQL fragment that extracts a deeply nested value for comparison, e.g. `"a" #>> {"b","c"}` in Postgres */
     sqlExtract(key) {
         if (key.length > 1)
             throw new UnimplementedError("SQLProvider does not support nested filter keys");

package/db/provider/SQLiteProvider.d.ts

@@ -1,6 +1,7 @@
-import type { Data, DataPath } from "../../util/data.js";
+import type { Data } from "../../util/data.js";
 import type { Identifier } from "../../util/item.js";
 import type { QueryFilter } from "../../util/query.js";
+import type { Segments } from "../../util/string.js";
 import type { Update } from "../../util/update.js";
 import type { Collection } from "../collection/Collection.js";
 import { type SQLFragment, SQLProvider } from "./SQLProvider.js";
@@ -16,7 +17,7 @@ export declare abstract class SQLiteProvider<I extends Identifier = Identifier,
     /** Get the SQLite JSON path for the nested segments of a key (everything after the column name), e.g. `$.b.c` */
     private sqlPath;
     /** Get the SQLite JSON extract syntax, e.g. `json_extract("a", $.b.c)` */
-    sqlExtract(key: DataPath): SQLFragment;
+    sqlExtract(key: Segments): SQLFragment;
     sqlUpdate(update: Update): SQLFragment;
     sqlFilter(filter: QueryFilter): SQLFragment;
 }

package/extract/DirectoryExtractor.d.ts

@@ -0,0 +1,42 @@
+import type { ImmutableDictionary } from "../util/dictionary.js";
+import { type DirectoryElement } from "../util/element.js";
+import { type AbsolutePath, type Matchables, type Path } from "../util/index.js";
+import { Extractor } from "./Extractor.js";
+import { FileExtractor } from "./FileExtractor.js";
+/** Options for a directory extractor. */
+export interface DirectoryExtractorOptions {
+    /** Filenames to treat as the directory's index file. Matched case-insensitively. */
+    readonly index?: Matchables;
+    /**
+     * Extractor dispatch table keyed by file extension (with leading dot, e.g. `".md"`).
+     * - Files with no matching extractor are silently skipped.
+     * - Defaults to `.md` (markdown), `.ts` (TypeScript), and `.txt` (plain text).
+     */
+    readonly extractors?: ImmutableDictionary<FileExtractor>;
+    /** Absolute base path used to resolve relative paths passed to `extract()`. */
+    readonly base?: AbsolutePath;
+    /**
+     * Glob patterns for entries to skip — applied to both files and directories.
+     * - Defaults to test and spec files: `["*.test.ts", "*.test.tsx", "*.spec.ts", "*.spec.tsx"]`.
+     * - Hidden entries (`.`-prefixed), underscore-prefixed entries, and `node_modules` are always skipped on top of these patterns.
+     */
+    readonly ignore?: Matchables;
+}
+/**
+ * Extractor that walks a directory on disk and produces a `DirectoryElement` tree.
+ * - Recursively descends into subdirectories.
+ * - Detects an index file (e.g. `README.md`) and absorbs its content/description/title as the directory's own.
+ * - Dispatches non-index files to a matching `FileExtractor` based on extension; files with no matching extractor are silently skipped.
+ * - Merges file elements that share the same `key` (e.g. `TEMPLATE.md` and `template.ts`) using each extractor's `priority`.
+ * - Throws if a directory and a file (or two directories) share the same `key`.
+ */
+export declare class DirectoryExtractor extends Extractor<Path, DirectoryElement> {
+    private readonly _indexes;
+    private readonly _extractors;
+    private readonly _base;
+    private readonly _ignore;
+    constructor({ index, extractors, base, ignore }?: DirectoryExtractorOptions);
+    extract(path: Path): Promise<DirectoryElement>;
+    private _extractDirectory;
+    private _extractChild;
+}

package/extract/DirectoryExtractor.js

@@ -0,0 +1,127 @@
+import { readdir } from "node:fs/promises";
+import { mergeElements } from "../util/element.js";
+import { splitFileExtension } from "../util/file.js";
+import { anyMatch, requirePath, splitAbsolutePath } from "../util/index.js";
+import { requireSlug } from "../util/string.js";
+import { Extractor, mergeTreeElements } from "./Extractor.js";
+import { FileExtractor } from "./FileExtractor.js";
+import { MarkdownExtractor } from "./MarkdownExtractor.js";
+import { TypescriptExtractor } from "./TypescriptExtractor.js";
+/**
+ * Default list of filenames patterns treated as the directory's index file.
+ * - Matched case-insensitively (all entries stored lowercase).
+ * - If matched but no extractor is registered for the file's extension, the index is silently skipped.
+ */
+const DEFAULT_INDEX = [/^readme\.txt$/i, /^readme\.md$/i, /^index\.md$/i, /^index\.ts$/i, /^index\.tsx$/i];
+/** Default file extractor dispatch by extension. */
+const DEFAULT_EXTRACTORS = {
+    md: new MarkdownExtractor(),
+    ts: new TypescriptExtractor(),
+    tsx: new TypescriptExtractor(),
+    txt: new FileExtractor(),
+};
+/**
+ * Default ignore patterns.
+ * - Skip test and spec files.
+ * - Skip `node_modules` directories.
+ * - Skip hidden `.` prefixed and underscore-prefixed files and directories.
+ */
+const DEFAULT_IGNORE = [/\.test\.tsx?$/i, /\.spec\.tsx?$/i, /^node_modules$/i, /^[_.]/i];
+/**
+ * Merge two tree elements, favouring the one with the highest priority.
+ * - We merge together elements with the same `key:` (e.g. `TEMPLATE.md` and `template.ts`).
+ * - `title` and `description` are taken from the higher-priority element.
+ * - `content` and `children` of both elements are merged (with the higher-priority element's content/children first).
+ */
+function _mergeChild(existing, next) {
+    if (!existing)
+        return next;
+    return next.priority > existing.priority
+        ? { element: mergeTreeElements(next.element, existing.element), priority: next.priority }
+        : { element: mergeTreeElements(existing.element, next.element), priority: existing.priority };
+}
+/**
+ * Extractor that walks a directory on disk and produces a `DirectoryElement` tree.
+ * - Recursively descends into subdirectories.
+ * - Detects an index file (e.g. `README.md`) and absorbs its content/description/title as the directory's own.
+ * - Dispatches non-index files to a matching `FileExtractor` based on extension; files with no matching extractor are silently skipped.
+ * - Merges file elements that share the same `key` (e.g. `TEMPLATE.md` and `template.ts`) using each extractor's `priority`.
+ * - Throws if a directory and a file (or two directories) share the same `key`.
+ */
+export class DirectoryExtractor extends Extractor {
+    _indexes;
+    _extractors;
+    _base;
+    _ignore;
+    constructor({ index = DEFAULT_INDEX, extractors = DEFAULT_EXTRACTORS, base, ignore = DEFAULT_IGNORE } = {}) {
+        super();
+        this._indexes = index;
+        this._extractors = extractors;
+        this._base = base;
+        this._ignore = ignore;
+    }
+    extract(path) {
+        return this._extractDirectory(requirePath(path, this._base, this.extract));
+    }
+    async _extractDirectory(path) {
+        const name = splitAbsolutePath(path).at(-1) ?? "";
+        const entries = await readdir(path, { withFileTypes: true });
+        // Keep track of the current index entry and children by key, so we can merge same-key elements.
+        let index;
+        const items = {};
+        for (const entry of entries) {
+            // Should we ignore this entry?
+            if (anyMatch(entry.name, ...this._ignore))
+                continue;
+            // Extract the child element and possibly merge it.
+            const child = await this._extractChild(path, entry);
+            if (child) {
+                // Is this entry an index? If so, we'll treat it as the directory itself and merge it with any existing index entry if needed.
+                if (anyMatch(entry.name, ...this._indexes)) {
+                    index = _mergeChild(index, child);
+                }
+                else {
+                    const key = child.element.key;
+                    items[key] = _mergeChild(items[key], child);
+                }
+            }
+        }
+        const children = Object.values(items).map(({ element }) => element);
+        return {
+            type: "tree-directory",
+            key: requireSlug(name),
+            props: {
+                path,
+                name,
+                // `title` is only set when the absorbed index file has a confident one (e.g. README H1).
+                // Renderers fall back to `name` otherwise.
+                title: index?.element.props.title,
+                description: index?.element.props.description,
+                content: index?.element.props.content,
+                children: mergeElements(index?.element.props.children, children),
+            },
+        };
+    }
+    async _extractChild(base, entry) {
+        const name = entry.name;
+        const path = requirePath(name, base);
+        if (entry.isDirectory()) {
+            return {
+                element: await this._extractDirectory(path),
+                priority: this.priority,
+            };
+        }
+        else if (entry.isFile()) {
+            const [base, extension] = splitFileExtension(name);
+            if (!base || !extension)
+                return; // Skip files with no base name or extension.
+            const extractor = this._extractors[extension];
+            if (!extractor)
+                return; // Skip files with no registered extractor (including non-matching index files).
+            return {
+                element: await extractor.extract(Bun.file(path)),
+                priority: extractor.priority,
+            };
+        }
+    }
+}

package/extract/Extractor.d.ts

@@ -0,0 +1,24 @@
+import { type TreeElement } from "../util/element.js";
+/**
+ * Base class for an extractor that converts input into a tree element.
+ * - Extractors are composable: outer extractors delegate to inner extractors.
+ * - The output type is always a `TreeElement` (or a more specific subtype like `TreeElement`).
+ */
+export declare abstract class Extractor<I, O extends TreeElement = TreeElement> {
+    /** Extract a tree element from the given input. */
+    abstract extract(input: I): Partial<O> | Promise<Partial<O>>;
+    /**
+     * Priority used to resolve same-key collisions when merging elements.
+     * - Higher-priority elements contribute their `title`, `description`, `path` to the merged result.
+     * - Higher-priority elements a prefixed (rather than suffixed) in `children` and `content` when merged.
+     * - Defaults to `0`; subclasses override (e.g. `MarkdownExtractor` is `10`).
+     */
+    readonly priority: number;
+}
+/**
+ * Merge two file elements with the same `key`.
+ * - `title` and `path` are taken from `primary` (the higher-priority element).
+ * - `description` is taken from `primary` if set, otherwise from `secondary`.
+ * - `content` and `children` from both are concatenated (primary first).
+ */
+export declare function mergeTreeElements<T extends TreeElement>(primary: T, secondary: TreeElement): T;

package/extract/Extractor.js

@@ -0,0 +1,30 @@
+import { mergeElements } from "../util/element.js";
+/**
+ * Base class for an extractor that converts input into a tree element.
+ * - Extractors are composable: outer extractors delegate to inner extractors.
+ * - The output type is always a `TreeElement` (or a more specific subtype like `TreeElement`).
+ */
+export class Extractor {
+    /**
+     * Priority used to resolve same-key collisions when merging elements.
+     * - Higher-priority elements contribute their `title`, `description`, `path` to the merged result.
+     * - Higher-priority elements a prefixed (rather than suffixed) in `children` and `content` when merged.
+     * - Defaults to `0`; subclasses override (e.g. `MarkdownExtractor` is `10`).
+     */
+    priority = 0;
+}
+export function mergeTreeElements(primary, secondary) {
+    return {
+        ...primary,
+        type: primary.type,
+        key: primary.key,
+        props: {
+            ...primary.props,
+            title: primary.props.title,
+            path: primary.props.path,
+            description: primary.props.description ?? secondary.props.description,
+            content: mergeElements(primary.props.content, secondary.props.content),
+            children: mergeElements(primary.props.children, secondary.props.children),
+        },
+    };
+}

package/extract/FileExtractor.d.ts

@@ -0,0 +1,22 @@
+import type { BunFile } from "bun";
+import type { FileElement, FileElementProps } from "../util/element.js";
+import { Extractor } from "./Extractor.js";
+/**
+ * Base extractor for a file in a tree.
+ * - Reads the file's content as text and stores it in `content`.
+ * - Sets `key` to the slugified basename (without extension).
+ * - Does NOT set `title` — `title` is only set by subclasses that have a confident source for one
+ *   (e.g. `MarkdownExtractor` uses the first `<h1>`). Renderers fall back to `name` when missing.
+ * - Subclasses (e.g. `MarkdownExtractor`, `TypescriptExtractor`) override `extractProps()` to parse the content into richer elements.
+ */
+export declare class FileExtractor extends Extractor<BunFile, FileElement> {
+    extract(file: BunFile): Promise<FileElement>;
+    /**
+     * Build the file element props from the extracted content.
+     * - `name` is the basename including extension (e.g. `"array.ts"`).
+     * - `base` is the basename without extension (e.g. `"array"`) — useful as a title fallback.
+     * - Override to parse `text` into richer elements (content/children/description) and to set
+     *   `title` if a confident title is available.
+     */
+    extractProps(name: string, content: string): FileElementProps;
+}

package/extract/FileExtractor.js

@@ -0,0 +1,34 @@
+import { splitFileExtension } from "../util/file.js";
+import { isAbsolutePath, splitAbsolutePath } from "../util/index.js";
+import { requireSlug } from "../util/string.js";
+import { Extractor } from "./Extractor.js";
+/**
+ * Base extractor for a file in a tree.
+ * - Reads the file's content as text and stores it in `content`.
+ * - Sets `key` to the slugified basename (without extension).
+ * - Does NOT set `title` — `title` is only set by subclasses that have a confident source for one
+ *   (e.g. `MarkdownExtractor` uses the first `<h1>`). Renderers fall back to `name` when missing.
+ * - Subclasses (e.g. `MarkdownExtractor`, `TypescriptExtractor`) override `extractProps()` to parse the content into richer elements.
+ */
+export class FileExtractor extends Extractor {
+    async extract(file) {
+        const path = file.name ?? "unnamed";
+        const name = isAbsolutePath(path) ? (splitAbsolutePath(path).at(-1) ?? "unnamed") : path;
+        const [base = name] = splitFileExtension(name);
+        return {
+            type: "tree-file",
+            key: requireSlug(base),
+            props: this.extractProps(name, await file.text()),
+        };
+    }
+    /**
+     * Build the file element props from the extracted content.
+     * - `name` is the basename including extension (e.g. `"array.ts"`).
+     * - `base` is the basename without extension (e.g. `"array"`) — useful as a title fallback.
+     * - Override to parse `text` into richer elements (content/children/description) and to set
+     *   `title` if a confident title is available.
+     */
+    extractProps(name, content) {
+        return { name, content };
+    }
+}