@orkestrel/template 0.0.5 → 0.0.6

package/README.md

@@ -1,6 +1,12 @@
 # @orkestrel/template
 
-TODO: one-line description. Part of the `@orkestrel` line.
+A stateful template registry and filler with typed placeholders — `{{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
+`TemplateManager`. Every fill lookup refuses a prototype-pollution-unsafe
+field path: any segment in `UNSAFE_FIELD_SEGMENTS` (`__proto__`,
+`constructor`, `prototype`) is refused before the record is ever read. Part of
+the `@orkestrel` line.
 
 ## Install
 
@@ -8,17 +14,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,8 +3,8 @@ 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
@@ -23,13 +23,14 @@ 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 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 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 — a fill lookup
+* refuses to resolve ANY path containing one, treating the placeholder as
+* unresolved.
 */
 var UNSAFE_FIELD_SEGMENTS = Object.freeze([
 	"__proto__",
@@ -39,7 +40,7 @@ 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.
 *
 * @remarks
 * Thrown for: a required placeholder staying unresolved under the `error`
@@ -60,17 +61,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 +83,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,7 +112,7 @@ 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
@@ -140,16 +142,55 @@ 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`
 * 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
@@ -158,11 +199,11 @@ function resolveSafeField(record, path) {
 * {@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 +229,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 +243,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 +275,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.
 *
 * @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 +294,9 @@ function placeholderShape(placeholders) {
 * ```
 */
 var Template = class {
+	#missing;
+	#locale;
+	#contract;
 	id;
 	name;
 	content;
@@ -259,9 +305,6 @@ var Template = class {
 	description;
 	category;
 	tags;
-	#missing;
-	#locale;
-	#contract;
 	constructor(options) {
 		const placeholders = options.placeholders ?? [];
 		const seenNames = /* @__PURE__ */ new Set();
@@ -283,7 +326,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 +349,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 +370,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,9 +379,10 @@ 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`
+	* `.`), and the value resolves through `resolveSafeField`. The token is `missing`
 	* only when the value is unresolved AND 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 +411,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 +423,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,12 +443,12 @@ 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
+* 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 (AGENTS §9.1 singular/plural accessors, §9.2 batch
-* `remove` overloads, §13 emitter ownership).
+* and validates by id, with singular/plural accessors, batch `remove`
+* overloads, and emitter ownership.
 *
 * @remarks
 * `register` accepts either a constructed {@link TemplateInterface} (kept
@@ -416,8 +459,8 @@ var Template = class {
 * 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`.
+* emit. The batch `remove(ids)` form removes every present id and returns
+* `true` only when every listed id was present.
 *
 * @example
 * ```ts
@@ -450,11 +493,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 +505,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 +520,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,7 +537,7 @@ var TemplateManager = class {
 		return [...this.#templates.values()];
 	}
 	/**
-	* Filter registered templates by name / category / tag — every supplied
+	* Filters registered templates by name / category / tag — every supplied
 	* field must match (logical AND).
 	*
 	* @param query - The {@link TemplateQuery} to filter by; omit for every registered template
@@ -512,10 +553,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 +574,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 +633,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,19 +656,22 @@ 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 template.
 *
 * @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
 * ```ts
@@ -617,12 +685,13 @@ function createTemplate(options) {
 	return new Template(options);
 }
 /**
-* Create a template registry.
+* Creates a template registry.
 *
 * @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 +721,6 @@ exports.formatValue = formatValue;
 exports.isTemplateError = isTemplateError;
 exports.placeholderShape = placeholderShape;
 exports.resolveSafeField = resolveSafeField;
+exports.resolveToken = resolveToken;
 
 //# sourceMappingURL=index.cjs.map