@orkestrel/template 0.0.5 → 0.0.7

package/README.md

@@ -1,6 +1,14 @@
 # @orkestrel/template
 
-TODO: one-line description. Part of the `@orkestrel` line.
+> A named, versionable template layer: `{{name}}` tokens in a `content`
+> string, resolved against a values record by a single-pass fill engine, and
+> registered and looked up by id through a self-owning `TemplateManager`.
+
+Declare a template with the `createTemplate` function, fill it against the
+values record your caller supplies, and register it in a `TemplateManager`
+where several templates are looked up by id. Reach for `validate` where you
+need to know which placeholders a fill would reject before you run it. Part of
+the `@orkestrel` line.
 
 ## Install
 
@@ -8,17 +16,31 @@ TODO: one-line description. Part of the `@orkestrel` line.
 npm install @orkestrel/template
 ```
 
+## Requirements
+
+- Node.js >= 22.12.0
+- Runtime dependencies `@orkestrel/contract` and `@orkestrel/emitter`
+
 ## Usage
 
 ```ts
-import { createTemplate } from '@orkestrel/template'
+import { createTemplate, createTemplateManager } from '@orkestrel/template'
 
-const instance = createTemplate({ id: 'example' })
+const greeting = createTemplate({ name: 'greeting', content: 'Hi {{name}}' })
+greeting.fill({ name: 'Ada' }) // 'Hi Ada'
+
+const templates = createTemplateManager({ templates: [greeting] })
+templates.fill(greeting.id, { name: 'Grace' }) // 'Hi Grace'
 ```
 
+An unresolved required placeholder is governed by `TemplateFillOptions.missing`,
+which defaults to `'error'` and throws a `TemplateError` coded `MISSING`.
+`'empty'` substitutes `''` instead, and `'literal'` re-emits the original
+`{{name}}` token.
+
 ## Guide
 
-For the full surface, see [`guides/src/template.md`](guides/src/template.md).
+For the full surface, see [`guides/template.md`](guides/template.md).
 
 ## License
 

package/dist/src/core/index.cjs

@@ -3,18 +3,18 @@ let _orkestrel_contract = require("@orkestrel/contract");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 //#region src/core/constants.ts
 /**
-* The single-pass `{{name}}` substitution pattern shared by `Template#fill`
-* and `Template#validate`.
+* Holds the single-pass `{{name}}` substitution pattern shared by
+* `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
@@ -23,13 +23,20 @@ let _orkestrel_emitter = require("@orkestrel/emitter");
 * instance's mutable `lastIndex` across scans.
 */
 var FILL_PATTERN = /\\\{\{|\{\{([^{}]+?)\}\}/g;
-/** Default `missing` policy for `Template#fill` / `TemplateManager#fill` when unspecified. */
+/**
+* Holds `'error'`, the default `missing` policy for `Template#fill` /
+* `TemplateManager#fill` when unspecified.
+*/
 var DEFAULT_MISSING_POLICY = "error";
-/** Default `locale` for `Template#fill` / `TemplateManager#fill` when unspecified. */
+/**
+* Holds `'en-US'`, the default `locale` for `Template#fill` /
+* `TemplateManager#fill` when unspecified.
+*/
 var DEFAULT_LOCALE = "en-US";
 /**
-* 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.
 */
 var UNSAFE_FIELD_SEGMENTS = Object.freeze([
 	"__proto__",
@@ -39,15 +46,16 @@ var UNSAFE_FIELD_SEGMENTS = Object.freeze([
 //#endregion
 //#region src/core/errors.ts
 /**
-* 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`).
 */
 var TemplateError = class extends Error {
 	code;
@@ -60,17 +68,17 @@ var TemplateError = class extends Error {
 	}
 };
 /**
-* Narrow an unknown caught value to a {@link TemplateError}.
+* Narrows an unknown caught value to a {@link TemplateError}.
 *
 * @param value - The value to test (typically a `catch` binding)
-* @returns `true` when `value` is a {@link TemplateError}
+* @returns True if `value` is a {@link TemplateError}; false otherwise
 *
 * @example
 * ```ts
 * import { isTemplateError } from '@src/core'
 *
 * try {
-* 	manager.template('missing')
+* 	manager.fill('missing')
 * } catch (error) {
 * 	if (isTemplateError(error) && error.code === 'NOTFOUND') return
 * }
@@ -82,13 +90,14 @@ function isTemplateError(value) {
 //#endregion
 //#region src/core/helpers.ts
 /**
-* Format a resolved fill value for substitution into a template's `content`.
+* Formats a resolved fill value for substitution into a template's `content`.
 *
 * @remarks
-* A finite number renders with the given locale's thousand grouping (via
+* A finite number renders with the given locale's thousand grouping (through
 * `toLocaleString`); every other value — including `null` — String-coerces.
-* `null` therefore renders as the literal string `'null'`, intentionally
-* mirroring `interpolateMessage`'s coercion parity (see `fillTemplate`). An
+* `null` therefore renders as the literal string `'null'`, matching
+* `String(value)` exactly, so a resolved `null` is visible in the output
+* rather than silently empty. An
 * invalid BCP-47 `locale` tag throws a `RangeError` from the underlying
 * `toLocaleString` call when `value` is a finite number — this is a caller
 * error (an invalid locale argument), by design, and is not caught here.
@@ -110,15 +119,15 @@ function formatValue(value, locale) {
 	return String(value);
 }
 /**
-* Resolve a field path against a fill-values record, refusing any path that
+* Resolves a field path against a fill-values record, refusing any path that
 * touches a prototype-pollution-unsafe segment.
 *
 * @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`.
@@ -140,29 +149,68 @@ function resolveSafeField(record, path) {
 	return (0, _orkestrel_contract.resolveField)(record, path);
 }
 /**
-* Substitute every `{{name}}` token in `content` in a single pass.
+* Resolves one `{{name}}` token against the declared placeholders and the
+* fill-values record.
+*
+* @remarks
+* The single implementation of the token rule `fillTemplate` and
+* `Template#validate` both apply, so the two can never drift: the declared
+* {@link TemplatePlaceholder} sharing the token's `name` (exact match)
+* supplies its `path`, falling back to the token split on `.`; the value
+* resolves through `resolveSafeField`, so any segment in
+* `UNSAFE_FIELD_SEGMENTS` yields `undefined` without ever calling
+* `resolveField`; `required` is `true` for an undeclared token and for a
+* declared placeholder whose `required` is not `false`. The token is passed
+* already trimmed. `fallback` is not applied here — it is read from
+* `declared` by each caller, because `fill` substitutes it and `validate`
+* only counts it.
+*
+* @param record - The fill-values record the token resolves against
+* @param placeholders - The declared placeholders the token matches by name
+* @param token - The trimmed token text, without its `{{` / `}}` delimiters
+* @returns The {@link TemplateTokenResolution} for the token
+*
+* @example
+* ```ts
+* import { resolveToken } from '@src/core'
+*
+* resolveToken({ name: 'Ada' }, [], 'name').value // 'Ada'
+* resolveToken({}, [{ name: 'nickname', required: false }], 'nickname').required // false
+* ```
+*/
+function resolveToken(record, placeholders, token) {
+	const declared = placeholders.find((placeholder) => placeholder.name === token);
+	return {
+		value: resolveSafeField(record, declared?.path ?? token.split(".")),
+		declared,
+		required: declared === void 0 || declared.required !== false
+	};
+}
+/**
+* Substitutes every `{{name}}` token in `content` in a single pass.
 *
 * @remarks
 * Uses a fresh `RegExp` clone of `FILL_PATTERN` per call (never sharing its
 * `lastIndex`) and a single `String#replace` scan — substituted output is
-* never re-scanned. For each token: the matching declared
+* 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 via `formatValue`; an
+* 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 `{{`.
 *
-* PARITY: called with no declared `placeholders` and `{ missing: 'empty' }`,
-* this reproduces `interpolateMessage` (`@src/core` sibling
-* `interpret`) vector-for-vector. KNOWN DIVERGENCE: `FILL_PATTERN`'s token
-* class (`[^{}]`) excludes `{`, where `interpolateMessage`'s (`[^}]`) allows
-* it — a token containing `{` therefore behaves differently here.
+* Called with no declared `placeholders` and `{ missing: 'empty' }`, this is a
+* bare interpolation over `content` — every token resolves by dotted path
+* against the values record and every unresolved token emits `''`.
+* `FILL_PATTERN`'s token class (`[^{}]`) excludes `{`, so a token containing
+* `{` never matches and the surrounding `{{` stays literal.
 *
 * @param content - The template content carrying `{{name}}` tokens
 * @param values - The values tokens resolve against
@@ -188,14 +236,12 @@ function fillTemplate(content, values, options) {
 	const result = content.replace(pattern, (matchText, rawToken) => {
 		if (rawToken === void 0) return "{{";
 		const token = rawToken.trim();
-		const declared = placeholders.find((placeholder) => placeholder.name === token);
-		const path = declared?.path ?? token.split(".");
-		const value = resolveSafeField(record, path);
+		const { value, declared, required } = resolveToken(record, placeholders, token);
 		if (value !== void 0) return formatValue(value, locale);
 		if (declared?.fallback !== void 0) return formatValue(declared.fallback, locale);
 		if (missing === "literal") return matchText;
 		if (missing === "empty") return "";
-		if ((declared === void 0 || declared.required !== false) && !seen.has(token)) {
+		if (required && !seen.has(token)) {
 			seen.add(token);
 			missingNames.push(token);
 		}
@@ -204,8 +250,10 @@ function fillTemplate(content, values, options) {
 	if (missing === "error" && missingNames.length > 0) throw new TemplateError("MISSING", `Missing required placeholder(s): ${missingNames.join(", ")}`, { missing: missingNames });
 	return result;
 }
+//#endregion
+//#region src/core/shapers.ts
 /**
-* Build the `@orkestrel/contract` object shape describing a template's
+* Builds the `@orkestrel/contract` object shape describing a template's
 * declared placeholders.
 *
 * @remarks
@@ -234,15 +282,17 @@ function placeholderShape(placeholders) {
 	return (0, _orkestrel_contract.objectShape)(properties);
 }
 //#endregion
-//#region src/core/Template.ts
+//#region src/core/templates/Template.ts
 /**
-* A named, versionable template — `{{name}}` tokens in `content`, filled
-* against a values record.
+* Represents a named, versionable template — `{{name}}` tokens in `content`,
+* filled against a values record — implementing `TemplateInterface` exactly.
 *
 * @remarks
 * `missing` / `locale` seed this instance's default {@link TemplateFillOptions},
 * overridable per `fill` call. Its `parameters()` contract (built from
-* `placeholders` via `placeholderShape`) compiles once, in the constructor.
+* `placeholders` through `placeholderShape`) compiles once, in the constructor.
+*
+* @throws {@link TemplateError} Thrown when `options.placeholders` declares a duplicate `name` or an empty `path` (coded `INVALID`)
 *
 * @example
 * ```ts
@@ -251,6 +301,9 @@ function placeholderShape(placeholders) {
 * ```
 */
 var Template = class {
+	#missing;
+	#locale;
+	#contract;
 	id;
 	name;
 	content;
@@ -259,9 +312,6 @@ var Template = class {
 	description;
 	category;
 	tags;
-	#missing;
-	#locale;
-	#contract;
 	constructor(options) {
 		const placeholders = options.placeholders ?? [];
 		const seenNames = /* @__PURE__ */ new Set();
@@ -283,7 +333,7 @@ var Template = class {
 		this.#contract = (0, _orkestrel_contract.createContract)(placeholderShape(this.placeholders));
 	}
 	/**
-	* The plain, JSON-serializable data this template carries.
+	* Returns the plain, JSON-serializable data this template carries.
 	*
 	* @returns The {@link TemplateDefinition} record
 	*
@@ -306,11 +356,12 @@ var Template = class {
 		};
 	}
 	/**
-	* Substitute every `{{name}}` token in `content` against `values`.
+	* Substitutes every `{{name}}` token in `content` against `values`.
 	*
 	* @param values - The values tokens resolve against
 	* @param options - Per-call overrides for this instance's `missing` / `locale` defaults
 	* @returns The substituted content
+	* @throws {@link TemplateError} Thrown when a required placeholder stays unresolved under the `'error'` policy (coded `MISSING`)
 	*
 	* @example
 	* ```ts
@@ -326,7 +377,7 @@ var Template = class {
 		});
 	}
 	/**
-	* Report which required placeholders would stay unresolved, and which
+	* Reports which required placeholders would stay unresolved, and which
 	* `values` keys go unused, without producing output.
 	*
 	* @remarks
@@ -335,10 +386,11 @@ var Template = class {
 	* predicts `fill`'s `'error'`-{@link MissingPolicy} outcome exactly — a
 	* token reported here as missing is precisely a token that would throw
 	* under `fill(values, { missing: 'error' })`. For each distinct token
-	* (first-appearance order, trimmed): a declared {@link TemplatePlaceholder}
+	* (first-appearance order, trimmed): `resolveToken` applies the one shared
+	* token rule `fill` also applies — a declared {@link TemplatePlaceholder}
 	* sharing its `name` supplies `path` (falling back to the token split on
-	* `.`); the value resolves via `resolveSafeField`. The token is `missing`
-	* only when the value is unresolved AND no `fallback` is declared AND the
+	* `.`), and the value resolves through `resolveSafeField`. The token is `missing`
+	* 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.
 	*
@@ -366,10 +418,8 @@ var Template = class {
 			const token = rawToken.trim();
 			if (seen.has(token)) continue;
 			seen.add(token);
-			const declared = this.placeholders.find((placeholder) => placeholder.name === token);
-			const resolved = resolveSafeField(record, declared?.path ?? token.split("."));
-			const required = declared === void 0 || declared.required !== false;
-			if (resolved === void 0 && declared?.fallback === void 0 && required) missing.push(token);
+			const { value, declared, required } = resolveToken(record, this.placeholders, token);
+			if (value === void 0 && declared?.fallback === void 0 && required) missing.push(token);
 		}
 		const declaredNames = new Set(this.placeholders.map((placeholder) => placeholder.name));
 		const extra = Object.keys(record).filter((key) => !declaredNames.has(key));
@@ -380,7 +430,7 @@ var Template = class {
 		};
 	}
 	/**
-	* Project this template's placeholders to the open tool-parameters record
+	* Projects this template's placeholders to the open tool-parameters record
 	* shape.
 	*
 	* @returns The compiled parameters record, or `undefined` when `schemaToParameters` yields none
@@ -400,24 +450,25 @@ var Template = class {
 	}
 };
 //#endregion
-//#region src/core/TemplateManager.ts
+//#region src/core/templates/TemplateManager.ts
 /**
-* 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 (AGENTS §9.1 singular/plural accessors, §9.2 batch
-* `remove` overloads, §13 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 is ALL-OR-NOTHING: any id absent from
-* the registry leaves the collection untouched and returns `false`.
+* 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
 * ```ts
@@ -450,11 +501,11 @@ var TemplateManager = class {
 	get emitter() {
 		return this.#emitter;
 	}
-	get size() {
+	get count() {
 		return this.#templates.size;
 	}
 	/**
-	* Register a template — a constructed {@link TemplateInterface} (kept
+	* Registers a template — a constructed {@link TemplateInterface} (kept
 	* as-is) or a plain {@link TemplateOptions} bag (constructed into a
 	* `Template` with this manager's `missing` / `locale` defaults applied
 	* wherever the bag omits them).
@@ -462,6 +513,7 @@ var TemplateManager = class {
 	* @param template - The template instance or options to register
 	* @param options - `replace` — overwrite an existing entry sharing the same id instead of throwing
 	* @returns The registered {@link TemplateInterface}
+	* @throws {@link TemplateError} Thrown when the id is already registered and `options.replace` is not `true` (coded `CONFLICT`), or when an options bag declares a duplicate placeholder `name` or an empty `path` (coded `INVALID`)
 	*
 	* @example
 	* ```ts
@@ -476,19 +528,16 @@ var TemplateManager = class {
 		return instance;
 	}
 	/**
-	* Look up a registered template by id.
+	* Returns one registered {@link TemplateInterface} by id.
 	*
 	* @param id - The template id
-	* @returns The registered {@link TemplateInterface}
-	* @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
+	* @returns The registered {@link TemplateInterface}, or `undefined` when `id` is unregistered
 	*/
 	template(id) {
-		const instance = this.#templates.get(id);
-		if (instance === void 0) this.#throwNotFound(id);
-		return instance;
+		return this.#templates.get(id);
 	}
 	/**
-	* List every registered template.
+	* Lists every registered template.
 	*
 	* @returns A snapshot array of every registered {@link TemplateInterface}
 	*/
@@ -496,8 +545,8 @@ var TemplateManager = class {
 		return [...this.#templates.values()];
 	}
 	/**
-	* Filter 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
@@ -512,10 +561,10 @@ var TemplateManager = class {
 		});
 	}
 	/**
-	* Test whether a template id is registered.
+	* Tests whether a template id is registered.
 	*
 	* @param id - The template id
-	* @returns `true` when `id` is registered
+	* @returns True if `id` is registered; false otherwise
 	*/
 	has(id) {
 		return this.#templates.has(id);
@@ -533,34 +582,58 @@ var TemplateManager = class {
 			this.#emitter.emit("remove", instance);
 			return true;
 		}
-		for (const id of target) if (!this.#templates.has(id)) return false;
+		let all = true;
 		for (const id of target) {
 			const instance = this.#templates.get(id);
-			if (instance === void 0) continue;
+			if (instance === void 0) {
+				all = false;
+				continue;
+			}
 			this.#templates.delete(id);
 			this.#emitter.emit("remove", instance);
 		}
-		return true;
+		return all;
 	}
-	/** Remove every registered template, emitting `clear`. */
+	/** Removes every registered template, emitting `clear`. */
 	clear() {
 		this.#templates.clear();
 		this.#emitter.emit("clear");
 	}
 	/**
-	* Fill a registered template by id.
+	* Tears down the registry: drops every registered template and destroys the
+	* owned emitter. Idempotent.
+	*
+	* @remarks
+	* Teardown is not an observable registry operation and the emitter is being
+	* released, so this emits neither `clear` nor `remove`. The emitter is torn
+	* down last, after the registry is dropped.
+	*
+	* @example
+	* ```ts
+	* const manager = new TemplateManager()
+	* manager.destroy()
+	* manager.emitter.destroyed // true
+	* ```
+	*/
+	destroy() {
+		this.#templates.clear();
+		this.#emitter.destroy();
+	}
+	/**
+	* Fills a registered template by id.
 	*
 	* @param id - The template id
 	* @param values - The values tokens resolve against
 	* @param options - Per-call overrides for the template's `missing` / `locale` defaults
 	* @returns The substituted content
 	* @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
+	* @throws {@link TemplateError} Thrown when a required placeholder stays unresolved under the `'error'` policy (coded `MISSING`)
 	*/
 	fill(id, values, options) {
-		return this.template(id).fill(values, options);
+		return this.#require(id).fill(values, options);
 	}
 	/**
-	* Validate values against a registered template by id.
+	* Validates values against a registered template by id.
 	*
 	* @param id - The template id
 	* @param values - The values to check
@@ -568,17 +641,17 @@ var TemplateManager = class {
 	* @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
 	*/
 	validate(id, values) {
-		return this.template(id).validate(values);
+		return this.#require(id).validate(values);
 	}
 	/**
-	* Project a registered template's parameters by id.
+	* Projects a registered template's parameters by id.
 	*
 	* @param id - The template id
 	* @returns The compiled parameters record, or `undefined` when the template has none
 	* @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
 	*/
 	parameters(id) {
-		return this.template(id).parameters();
+		return this.#require(id).parameters();
 	}
 	#instantiate(template) {
 		if (this.#isInstance(template)) return template;
@@ -591,38 +664,56 @@ var TemplateManager = class {
 	#isInstance(template) {
 		return "fill" in template && typeof template.fill === "function" && "validate" in template && typeof template.validate === "function" && "parameters" in template && typeof template.parameters === "function";
 	}
-	#throwNotFound(id) {
-		throw new TemplateError("NOTFOUND", `Unknown template id: ${id}`, { id });
+	#require(id) {
+		const instance = this.#templates.get(id);
+		if (instance === void 0) throw new TemplateError("NOTFOUND", `Unknown template id: ${id}`, { id });
+		return instance;
 	}
 };
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create 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
 *   `missing` / `locale` fill defaults
 * @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
 * ```
 */
 function createTemplate(options) {
 	return new Template(options);
 }
 /**
-* Create 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
 *   an `error` handler
 * @returns A working {@link TemplateManagerInterface}
+* @throws {@link TemplateError} Thrown when a seeded `options.templates` bag declares a duplicate placeholder `name` or an empty `path` (coded `INVALID`)
 *
 * @example
 * ```ts
@@ -652,5 +743,6 @@ exports.formatValue = formatValue;
 exports.isTemplateError = isTemplateError;
 exports.placeholderShape = placeholderShape;
 exports.resolveSafeField = resolveSafeField;
+exports.resolveToken = resolveToken;
 
 //# sourceMappingURL=index.cjs.map