@orkestrel/template 0.0.6 → 0.0.8

package/dist/src/core/index.d.cts

@@ -1,11 +1,12 @@
-import { ContractShape } from '@orkestrel/contract';
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { FieldPath } from '@orkestrel/contract';
+import type { ContractShape } from '@orkestrel/contract';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { FieldPath } from '@orkestrel/contract';
 
 /**
- * Creates a template.
+ * Creates a working {@link TemplateInterface} from a {@link TemplateOptions}
+ * bag, backed by the `Template` class.
  *
  * @param options - The template's `name` / `content`, an optional `id`
  *   (defaults to a generated UUID), `placeholders`, catalog metadata, and
@@ -13,18 +14,31 @@ import { FieldPath } from '@orkestrel/contract';
  * @returns A working {@link TemplateInterface}
  * @throws {@link TemplateError} Thrown when `options.placeholders` declares a duplicate `name` or an empty `path` (coded `INVALID`)
      *
-     * @example
+     * @example Create a template and a registry
      * ```ts
-     * import { createTemplate } from '@src/core'
+     * import { createTemplate, createTemplateManager } from '@orkestrel/template'
      *
      * const greeting = createTemplate({ name: 'greeting', content: 'Hi {{name}}' })
      * greeting.fill({ name: 'Ada' }) // 'Hi Ada'
+     *
+     * const templates = createTemplateManager({
+     * 	templates: [
+     * 		{ id: 'greeting', name: 'greeting', content: 'Hi {{name}}', category: 'mail' },
+     * 		{ id: 'farewell', name: 'farewell', content: 'Bye {{name}}', category: 'mail' },
+     * 		{ id: 'alert', name: 'alert', content: 'Alert: {{reason}}', category: 'ops' },
+     * 	],
+     * })
+     * templates.fill('greeting', { name: 'Ada' }) // 'Hi Ada'
+     * templates.find({ category: 'mail' }).map((one) => one.id) // ['greeting', 'farewell']
+     * templates.has('alert') // true
+     * templates.has('missing') // false
      * ```
      */
  export declare function createTemplate(options: TemplateOptions): TemplateInterface;
 
  /**
-  * Creates a template registry.
+  * Creates a working {@link TemplateManagerInterface}, optionally seeded with
+  * the templates the options carry, backed by the `TemplateManager` class.
   *
   * @param options - Optional initial `templates` seed collection and
   *   manager-wide `missing` / `locale` fill defaults, emitter `on` hooks, and
@@ -44,10 +58,16 @@ import { FieldPath } from '@orkestrel/contract';
       */
   export declare function createTemplateManager(options?: TemplateManagerOptions): TemplateManagerInterface;
 
-  /** Holds the default `locale` for `Template#fill` / `TemplateManager#fill` when unspecified. */
+  /**
+   * Holds `'en-US'`, the default `locale` for `Template#fill` /
+   * `TemplateManager#fill` when unspecified.
+   */
   export declare const DEFAULT_LOCALE = "en-US";
 
-  /** Holds the default `missing` policy for `Template#fill` / `TemplateManager#fill` when unspecified. */
+  /**
+   * Holds `'error'`, the default `missing` policy for `Template#fill` /
+   * `TemplateManager#fill` when unspecified.
+   */
   export declare const DEFAULT_MISSING_POLICY: MissingPolicy;
 
   /**
@@ -55,14 +75,14 @@ import { FieldPath } from '@orkestrel/contract';
    * `Template#fill` and `Template#validate`.
    *
    * @remarks
-   * Global-flagged, two-alternative pattern: a match of the FIRST alternative
+   * Global-flagged, two-alternative pattern: a match of the first alternative
    * (`\{{` — a literal backslash followed by `{{`) means "emit a literal
    * `{{`" — the escape hatch for content that must show `{{` without
    * triggering substitution. A match that instead populates capture group 1
    * (`\{{([^{}]+?)\}\}`) means "substitute the named token" — group 1 is the
-   * RAW (untrimmed) token text between the braces; every call site trims it
+   * untrimmed token text between the braces; every call site trims it
    * (`token.trim()`) before using it as a lookup name, so `'{{ name }}'` still
-   * resolves `'name'`. The pattern intentionally does NOT wrap the token in
+   * resolves `'name'`. The pattern deliberately does not wrap the token in
    * `\s*` — an unclosed `'{{' + ' '.repeat(n)` with no closing `}}` would
    * otherwise force the regex engine into catastrophic backtracking over the
    * whitespace run (O(n^2)); trimming after the match keeps the same
@@ -81,13 +101,13 @@ import { FieldPath } from '@orkestrel/contract';
    * never re-scanned. Each token resolves through `resolveToken`, the one rule
    * `Template#validate` also applies: the matching declared
    * {@link TemplatePlaceholder} (exact `name`) supplies its `path` (falling
-   * back to the token split on `.`); ANY path segment in `UNSAFE_FIELD_SEGMENTS`
+   * back to the token split on `.`); any path segment in `UNSAFE_FIELD_SEGMENTS`
    * makes the token unresolved without ever calling `resolveField` (a
    * prototype-pollution guard). A resolved value formats through `formatValue`; an
    * unresolved value falls back to the placeholder's `fallback` when declared;
    * otherwise `options.missing` governs — `'literal'` re-emits the original
    * `{{name}}` text, `'empty'` emits `''`, and `'error'` emits `''` for every
-   * token but collects EVERY unresolved required token (an undeclared token, or
+   * token but collects every unresolved required token (an undeclared token, or
    * a declared token with `required !== false`) and throws one
    * {@link TemplateError} coded `MISSING` listing them all, in first-appearance
    * order, once the scan completes. An escaped `\{{` emits a literal `{{`.
@@ -199,9 +219,9 @@ import { FieldPath } from '@orkestrel/contract';
    * @remarks
    * A prototype-pollution guard shared by `fillTemplate` and `Template#validate`
    * so the two stay in lockstep: `path` normalizes to a segment array (a bare
-   * string `path` becomes a single-segment array); if ANY segment appears in
+   * string `path` becomes a single-segment array); if any segment appears in
    * `UNSAFE_FIELD_SEGMENTS` (`'__proto__'`, `'constructor'`, `'prototype'`), the
-   * lookup is refused and `undefined` is returned WITHOUT ever calling
+   * lookup is refused and `undefined` is returned without ever calling
    * `resolveField` — a path like `['__proto__', 'polluted']` can never reach
    * the record's actual prototype chain through this function. Every other
    * path resolves through `@orkestrel/contract`'s `resolveField`.
@@ -254,7 +274,7 @@ import { FieldPath } from '@orkestrel/contract';
 
   /**
    * Represents a named, versionable template — `{{name}}` tokens in `content`,
-   * filled against a values record.
+   * filled against a values record — implementing `TemplateInterface` exactly.
    *
    * @remarks
    * `missing` / `locale` seed this instance's default {@link TemplateFillOptions},
@@ -321,7 +341,7 @@ import { FieldPath } from '@orkestrel/contract';
          * token rule `fill` also applies — a declared {@link TemplatePlaceholder}
          * sharing its `name` supplies `path` (falling back to the token split on
          * `.`), and the value resolves through `resolveSafeField`. The token is `missing`
-         * only when the value is unresolved AND no `fallback` is declared AND the
+         * only when the value is unresolved, no `fallback` is declared, and the
          * placeholder is required (`required !== false`, including undeclared
          * tokens). `extra` lists every `values` key with no declared placeholder.
          *
@@ -381,15 +401,16 @@ import { FieldPath } from '@orkestrel/contract';
        }
 
        /**
-        * Represents an error thrown by the template layer.
+        * Represents an error thrown by the template layer — a machine-readable
+        * {@link TemplateErrorCode} and an optional `context` record naming the
+        * offending id or placeholder name.
         *
         * @remarks
         * Thrown for: a required placeholder staying unresolved under the `error`
         * {@link MissingPolicy} (`MISSING`), an unknown template id
         * (`NOTFOUND`), `createTemplate` handed invalid data (`INVALID`), and
         * `TemplateManagerInterface#register` handed an id already present without
-        * `options.replace` (`CONFLICT`). `context`, when present, carries the
-        * offending id / name.
+        * `options.replace` (`CONFLICT`).
         */
        export declare class TemplateError extends Error {
            readonly code: TemplateErrorCode;
@@ -434,17 +455,13 @@ import { FieldPath } from '@orkestrel/contract';
        export declare type TemplateFillValues = Readonly<Record<string, unknown>>;
 
        /**
-        * Declares the template contract — exact bijection with `Template`.
+        * Declares the template contract a consumer holds — the readonly template
+        * record and the `definition`, `fill`, `validate`, and `parameters` calls
+        * over it.
         *
         * @remarks
-        * `definition` returns the plain {@link TemplateDefinition} data. `fill`
-        * substitutes every `{{name}}` token in `content` against `values`,
-        * honoring `options.missing` for unresolved required placeholders. `validate`
-        * reports which required placeholders are unresolved (`missing`) and which
-        * supplied `values` keys are unused (`extra`) without producing output.
-        * `parameters` projects this template's placeholders to the open
-        * tool-parameters record shape (`schemaToParameters`'s return type from
-        * `@orkestrel/contract`).
+        * `Template` implements this contract exactly, so the class exposes these
+        * members and no other public behavior.
         */
        export declare interface TemplateInterface {
            readonly id: string;
@@ -455,28 +472,53 @@ import { FieldPath } from '@orkestrel/contract';
            readonly description?: string;
            readonly category?: string;
            readonly tags?: readonly string[];
+           /** Returns the plain, JSON-serializable template data. */
            definition(): TemplateDefinition;
+           /**
+            * Substitutes every `{{name}}` token in `content` against `values`.
+            *
+            * @remarks
+            * `options.missing` governs an unresolved required placeholder, defaulting
+            * to the instance's own {@link MissingPolicy}.
+            */
            fill(values?: TemplateFillValues, options?: TemplateFillOptions): string;
+           /**
+            * Reports which required placeholders would stay unresolved, and which
+            * `values` keys go unused.
+            *
+            * @remarks
+            * The unresolved names arrive as `missing` and the unused keys as `extra`,
+            * and neither reading produces output.
+            */
            validate(values?: TemplateFillValues): TemplateValidationResult;
+           /**
+            * Projects the declared placeholders to the open tool-parameters record
+            * shape.
+            *
+            * @remarks
+            * The shape is `schemaToParameters`'s return type from
+            * `@orkestrel/contract`.
+            */
            parameters(): Readonly<Record<string, unknown>> | undefined;
        }
 
        /**
-        * Represents the template registry — a self-owning, id-keyed record-holder for the
-        * {@link TemplateInterface} instances a consumer registers, looks up, fills,
-        * and validates by id, with singular/plural accessors, batch `remove`
-        * overloads, and emitter ownership.
+        * Represents the template registry — a self-owning, id-keyed record-holder for
+        * the {@link TemplateInterface} instances a consumer registers, looks up,
+        * fills, and validates by id — implementing `TemplateManagerInterface`
+        * exactly.
         *
         * @remarks
-        * `register` accepts either a constructed {@link TemplateInterface} (kept
+        * Singular and plural accessors, the batch `remove` overloads, and ownership
+        * of the emitter all sit here. `register` accepts either a constructed {@link TemplateInterface} (kept
         * as-is, including its own `missing` / `locale` defaults) or a plain
         * {@link TemplateOptions} bag — constructed into a `Template` with this
         * manager's `missing` / `locale` defaults applied wherever the bag omits
         * them. A duplicate `id` throws a {@link TemplateError} coded `CONFLICT`
         * unless `options.replace` is `true`, in which case the existing entry is
-        * overwritten. `options.templates` SEEDS the registry at construction
-        * WITHOUT emitting `register` — only calls to `register` after construction
-        * emit. The batch `remove(ids)` form removes every present id and returns
+        * overwritten. `options.templates` seeds the registry at construction without
+        * emitting `register` — only calls to `register` after construction emit.
+        * The batch `remove(ids)` form removes every present id and returns
         * `true` only when every listed id was present.
         *
         * @example
@@ -524,8 +566,8 @@ import { FieldPath } from '@orkestrel/contract';
              */
             templates(): readonly TemplateInterface[];
             /**
-             * Filters registered templates by name / category / tag — every supplied
-             * field must match (logical AND).
+             * Filters registered templates by `name`, `category`, and `tag` — every
+             * supplied field must match.
              *
              * @param query - The {@link TemplateQuery} to filter by; omit for every registered template
              * @returns The matching templates
@@ -619,36 +661,67 @@ import { FieldPath } from '@orkestrel/contract';
                   };
 
                   /**
-                   * Declares the template registry — a self-owning, id-keyed record-holder with
-                   * singular/plural accessors and batch overloads.
+                   * Declares the registry contract a consumer holds — a self-owning, id-keyed
+                   * record-holder with singular and plural accessors over the templates it
+                   * registers.
                    *
                    * @remarks
-                   * `register` accepts either a constructed {@link TemplateInterface} or a
-                   * plain {@link TemplateOptions} bag (constructed internally), and throws a
-                   * {@link TemplateError} coded `CONFLICT` when the id already exists unless
-                   * `options.replace` is `true`. `template` returns `undefined` for an unknown
-                   * id; `fill`, `validate`, and `parameters` throw `NOTFOUND` for one, because
-                   * each needs a template to proceed. `remove()` removes every registered
-                   * template. `remove`'s batch form removes every present id and reports
-                   * `true` only when all listed ids were present. `destroy` tears the registry
-                   * down — it drops every registered template, destroys the owned emitter, emits
-                   * nothing, and is idempotent.
+                   * `TemplateManager` implements this contract exactly, so the class exposes
+                   * these members and no other public behavior. The by-id calls split on what
+                   * an unknown id means to each: `template` reports its absence as `undefined`,
+                   * while `fill`, `validate`, and `parameters` throw a {@link TemplateError}
+                   * coded `NOTFOUND`, because each needs a template to proceed.
                    */
                   export declare interface TemplateManagerInterface {
                       readonly emitter: EmitterInterface<TemplateManagerEventMap>;
                       readonly count: number;
+                      /**
+                       * Registers one template, or overwrites the entry sharing its id when
+                       * `options.replace` is `true`, and emits `register`.
+                       *
+                       * @remarks
+                       * The template arrives as a constructed {@link TemplateInterface} or as a
+                       * plain {@link TemplateOptions} bag, which is constructed internally. A
+                       * duplicate id without `options.replace` throws a {@link TemplateError}
+                       * coded `CONFLICT`.
+                       */
                       register(template: TemplateInterface | TemplateOptions, options?: TemplateRegisterOptions): TemplateInterface;
+                      /** Returns one registered template by id, or `undefined` when the id is unregistered. */
                       template(id: string): TemplateInterface | undefined;
+                      /** Lists every registered template. */
                       templates(): readonly TemplateInterface[];
+                      /** Filters registered templates by `name`, `category`, and `tag` — every supplied field must match. */
                       find(query?: TemplateQuery): readonly TemplateInterface[];
+                      /** Reports whether a template with the given id is registered. */
                       has(id: string): boolean;
+                      /**
+                       * Removes the listed templates by id, one template by id, or every
+                       * registered template, emitting `remove` once per removed template.
+                       *
+                       * @remarks
+                       * The batch form removes every present id and reports `true` only when
+                       * every listed id was present, so one absent id turns the answer `false`
+                       * while the present ids still remove. The no-argument form removes every
+                       * registered template and reports nothing.
+                       */
                       remove(ids: readonly string[]): boolean;
                       remove(id: string): boolean;
                       remove(): void;
+                      /** Removes every registered template, emitting `clear`. */
                       clear(): void;
+                      /**
+                       * Tears the registry down: drops every registered template and destroys the
+                       * owned emitter. Idempotent.
+                       *
+                       * @remarks
+                       * Teardown emits nothing, because the emitter is being released.
+                       */
                       destroy(): void;
+                      /** Fills a registered template by id. */
                       fill(id: string, values?: TemplateFillValues, options?: TemplateFillOptions): string;
+                      /** Validates values against a registered template by id. */
                       validate(id: string, values?: TemplateFillValues): TemplateValidationResult;
+                      /** Projects a registered template's parameters by id. */
                       parameters(id: string): Readonly<Record<string, unknown>> | undefined;
                   }
 
@@ -759,9 +832,9 @@ import { FieldPath } from '@orkestrel/contract';
                   }
 
                   /**
-                   * Lists the prototype-pollution-unsafe field-path segments — a fill lookup
-                   * refuses to resolve ANY path containing one, treating the placeholder as
-                   * unresolved.
+                   * Lists the prototype-pollution-unsafe field-path segments `'__proto__'`,
+                   * `'constructor'`, and `'prototype'` — a fill lookup refuses to resolve a path
+                   * containing one of them, treating the placeholder as unresolved.
                    */
                   export declare const UNSAFE_FIELD_SEGMENTS: readonly string[];