@orkestrel/template 0.0.1

package/dist/src/core/index.js

@@ -0,0 +1,639 @@
+import { createContract, isFiniteNumber, objectShape, optionalShape, resolveField, schemaToParameters, stringShape } from "@orkestrel/contract";
+import { Emitter } from "@orkestrel/emitter";
+//#region src/core/constants.ts
+/**
+* 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
+* (`\{{` — 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
+* (`token.trim()`) before using it as a lookup name, so `'{{ name }}'` still
+* resolves `'name'`. The pattern intentionally 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
+* whitespace tolerance without the backtracking hazard. Every call site
+* builds a fresh `RegExp` from `.source` / `.flags` rather than sharing this
+* instance's mutable `lastIndex` across scans.
+*/
+var FILL_PATTERN = /\\\{\{|\{\{([^{}]+?)\}\}/g;
+/** Default `missing` policy for `Template#fill` / `TemplateManager#fill` when unspecified. */
+var DEFAULT_MISSING_POLICY = "error";
+/** 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.
+*/
+var UNSAFE_FIELD_SEGMENTS = Object.freeze([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+//#endregion
+//#region src/core/errors.ts
+/**
+* An error thrown by the template layer.
+*
+* @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.
+*/
+var TemplateError = class extends Error {
+	code;
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "TemplateError";
+		this.code = code;
+		this.context = context;
+	}
+};
+/**
+* Narrow 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}
+*
+* @example
+* ```ts
+* import { isTemplateError } from '@src/core'
+*
+* try {
+* 	manager.template('missing')
+* } catch (error) {
+* 	if (isTemplateError(error) && error.code === 'NOTFOUND') return
+* }
+* ```
+*/
+function isTemplateError(value) {
+	return value instanceof TemplateError;
+}
+//#endregion
+//#region src/core/helpers.ts
+/**
+* Format a resolved fill value for substitution into a template's `content`.
+*
+* @remarks
+* A finite number renders with the given locale's thousand grouping (via
+* `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
+* 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.
+*
+* @param value - The resolved value to format
+* @param locale - The locale used for finite-number formatting
+* @returns The formatted string
+*
+* @example
+* ```ts
+* import { formatValue } from '@src/core'
+*
+* formatValue(5010, 'en-US') // '5,010'
+* formatValue(null, 'en-US') // 'null'
+* ```
+*/
+function formatValue(value, locale) {
+	if (isFiniteNumber(value)) return value.toLocaleString(locale);
+	return String(value);
+}
+/**
+* Resolve 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
+* `UNSAFE_FIELD_SEGMENTS` (`'__proto__'`, `'constructor'`, `'prototype'`), the
+* 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`.
+*
+* @param record - The fill-values record to resolve against
+* @param path - The field path — a single segment or a segment array
+* @returns The resolved value, or `undefined` when unresolved or the path is unsafe
+*
+* @example
+* ```ts
+* import { resolveSafeField } from '@src/core'
+*
+* resolveSafeField({ a: { b: 1 } }, ['a', 'b']) // 1
+* resolveSafeField({}, ['__proto__', 'polluted']) // undefined
+* ```
+*/
+function resolveSafeField(record, path) {
+	if ((Array.isArray(path) ? path : [path]).some((segment) => UNSAFE_FIELD_SEGMENTS.includes(segment))) return void 0;
+	return resolveField(record, path);
+}
+/**
+* Substitute 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
+* {@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
+* 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
+* 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.
+*
+* @param content - The template content carrying `{{name}}` tokens
+* @param values - The values tokens resolve against
+* @param options - `missing` (default `'error'`), `locale` (default `'en-US'`), and the declared `placeholders` (default none) tokens resolve against
+* @returns The substituted content
+*
+* @example
+* ```ts
+* import { fillTemplate } from '@src/core'
+*
+* fillTemplate('Hi {{name}}', { name: 'Ada' }) // 'Hi Ada'
+* fillTemplate('Limit {{limit}}', { limit: 5010 }, { missing: 'empty' }) // 'Limit 5,010'
+* ```
+*/
+function fillTemplate(content, values, options) {
+	const placeholders = options?.placeholders ?? [];
+	const missing = options?.missing ?? "error";
+	const locale = options?.locale ?? "en-US";
+	const record = values ?? {};
+	const missingNames = [];
+	const seen = /* @__PURE__ */ new Set();
+	const pattern = new RegExp(FILL_PATTERN.source, FILL_PATTERN.flags);
+	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);
+		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)) {
+			seen.add(token);
+			missingNames.push(token);
+		}
+		return "";
+	});
+	if (missing === "error" && missingNames.length > 0) throw new TemplateError("MISSING", `Missing required placeholder(s): ${missingNames.join(", ")}`, { missing: missingNames });
+	return result;
+}
+/**
+* Build the `@orkestrel/contract` object shape describing a template's
+* declared placeholders.
+*
+* @remarks
+* Each placeholder becomes a `stringShape` carrying its `description`;
+* `required === false` wraps it in `optionalShape`. Used by `Template` to
+* compile its `parameters()` contract once per instance.
+*
+* @param placeholders - The declared placeholders to shape
+* @returns The contract shape for `createContract`
+*
+* @example
+* ```ts
+* import { placeholderShape } from '@src/core'
+* import { createContract } from '@orkestrel/contract'
+*
+* const contract = createContract(placeholderShape([{ name: 'city' }]))
+* ```
+*/
+function placeholderShape(placeholders) {
+	const properties = {};
+	for (const placeholder of placeholders) {
+		const field = stringShape({ description: placeholder.description });
+		properties[placeholder.name] = placeholder.required === false ? optionalShape(field) : field;
+	}
+	return objectShape(properties);
+}
+//#endregion
+//#region src/core/Template.ts
+/**
+* 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.
+*
+* @example
+* ```ts
+* const greeting = new Template({ name: 'greeting', content: 'Hi {{name}}' })
+* greeting.fill({ name: 'Ada' }) // 'Hi Ada'
+* ```
+*/
+var Template = class {
+	id;
+	name;
+	content;
+	placeholders;
+	summary;
+	description;
+	category;
+	tags;
+	#missing;
+	#locale;
+	#contract;
+	constructor(options) {
+		const placeholders = options.placeholders ?? [];
+		const seenNames = /* @__PURE__ */ new Set();
+		for (const placeholder of placeholders) {
+			if (seenNames.has(placeholder.name)) throw new TemplateError("INVALID", `Duplicate placeholder name: ${placeholder.name}`, { name: placeholder.name });
+			seenNames.add(placeholder.name);
+			if (Array.isArray(placeholder.path) && placeholder.path.length === 0) throw new TemplateError("INVALID", `Placeholder path must not be empty: ${placeholder.name}`, { name: placeholder.name });
+		}
+		this.id = typeof options.id === "string" ? options.id : crypto.randomUUID();
+		this.name = options.name;
+		this.content = options.content;
+		this.placeholders = placeholders;
+		this.summary = options.summary;
+		this.description = options.description;
+		this.category = options.category;
+		this.tags = options.tags;
+		this.#missing = options.missing ?? "error";
+		this.#locale = options.locale ?? "en-US";
+		this.#contract = createContract(placeholderShape(this.placeholders));
+	}
+	/**
+	* The plain, JSON-serializable data this template carries.
+	*
+	* @returns The {@link TemplateDefinition} record
+	*
+	* @example
+	* ```ts
+	* const instance = new Template({ name: 'greeting', content: 'Hi {{name}}' })
+	* instance.definition().name // 'greeting'
+	* ```
+	*/
+	definition() {
+		return {
+			id: this.id,
+			name: this.name,
+			content: this.content,
+			placeholders: this.placeholders,
+			summary: this.summary,
+			description: this.description,
+			category: this.category,
+			tags: this.tags
+		};
+	}
+	/**
+	* Substitute 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
+	*
+	* @example
+	* ```ts
+	* const instance = new Template({ name: 'greeting', content: 'Hi {{name}}' })
+	* instance.fill({ name: 'Ada' }) // 'Hi Ada'
+	* ```
+	*/
+	fill(values, options) {
+		return fillTemplate(this.content, values, {
+			missing: options?.missing ?? this.#missing,
+			locale: options?.locale ?? this.#locale,
+			placeholders: this.placeholders
+		});
+	}
+	/**
+	* Report which required placeholders would stay unresolved, and which
+	* `values` keys go unused, without producing output.
+	*
+	* @remarks
+	* Content-token driven: scans `this.content` for every `{{name}}` token
+	* (skipping escaped `\{{` matches) the same way `fill` does, so `validate`
+	* 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}
+	* 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
+	* placeholder is required (`required !== false`, including undeclared
+	* tokens). `extra` lists every `values` key with no declared placeholder.
+	*
+	* @param values - The values to check
+	* @returns The {@link TemplateValidationResult}
+	*
+	* @example
+	* ```ts
+	* const instance = new Template({
+	* 	name: 'greeting',
+	* 	content: 'Hi {{name}}',
+	* 	placeholders: [{ name: 'name' }],
+	* })
+	* instance.validate({}).missing // ['name']
+	* ```
+	*/
+	validate(values) {
+		const record = values ?? {};
+		const missing = [];
+		const seen = /* @__PURE__ */ new Set();
+		const pattern = new RegExp(FILL_PATTERN.source, FILL_PATTERN.flags);
+		for (const match of this.content.matchAll(pattern)) {
+			const rawToken = match[1];
+			if (rawToken === void 0) continue;
+			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 declaredNames = new Set(this.placeholders.map((placeholder) => placeholder.name));
+		const extra = Object.keys(record).filter((key) => !declaredNames.has(key));
+		return {
+			valid: missing.length === 0,
+			missing,
+			extra
+		};
+	}
+	/**
+	* Project this template's placeholders to the open tool-parameters record
+	* shape.
+	*
+	* @returns The compiled parameters record, or `undefined` when `schemaToParameters` yields none
+	*
+	* @example
+	* ```ts
+	* const instance = new Template({
+	* 	name: 'greeting',
+	* 	content: 'Hi {{name}}',
+	* 	placeholders: [{ name: 'name' }],
+	* })
+	* instance.parameters()
+	* ```
+	*/
+	parameters() {
+		return schemaToParameters(this.#contract.schema);
+	}
+};
+//#endregion
+//#region src/core/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).
+*
+* @remarks
+* `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`.
+*
+* @example
+* ```ts
+* import { TemplateManager } from '@src/core'
+*
+* const manager = new TemplateManager()
+* const instance = manager.register({ name: 'greeting', content: 'Hi {{name}}' })
+* manager.fill(instance.id, { name: 'Ada' }) // 'Hi Ada'
+* ```
+*/
+var TemplateManager = class {
+	#templates = /* @__PURE__ */ new Map();
+	#emitter;
+	#missing;
+	#locale;
+	constructor(options) {
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		this.#missing = options?.missing ?? "error";
+		this.#locale = options?.locale ?? "en-US";
+		for (const template of options?.templates ?? []) {
+			const instance = this.#instantiate(template);
+			this.#templates.set(instance.id, instance);
+		}
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get size() {
+		return this.#templates.size;
+	}
+	/**
+	* Register 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).
+	*
+	* @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}
+	*
+	* @example
+	* ```ts
+	* const instance = manager.register({ id: 'greeting', name: 'greeting', content: 'Hi {{name}}' })
+	* ```
+	*/
+	register(template, options) {
+		const instance = this.#instantiate(template);
+		if (this.#templates.get(instance.id) !== void 0 && options?.replace !== true) throw new TemplateError("CONFLICT", `Template already registered: ${instance.id}`, { id: instance.id });
+		this.#templates.set(instance.id, instance);
+		this.#emitter.emit("register", instance);
+		return instance;
+	}
+	/**
+	* Look up a registered template by id.
+	*
+	* @param id - The template id
+	* @returns The registered {@link TemplateInterface}
+	* @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
+	*/
+	template(id) {
+		const instance = this.#templates.get(id);
+		if (instance === void 0) this.#throwNotFound(id);
+		return instance;
+	}
+	/**
+	* List every registered template.
+	*
+	* @returns A snapshot array of every registered {@link TemplateInterface}
+	*/
+	templates() {
+		return [...this.#templates.values()];
+	}
+	/**
+	* Filter 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
+	* @returns The matching templates
+	*/
+	find(query) {
+		if (query === void 0) return this.templates();
+		return this.templates().filter((instance) => {
+			if (query.name !== void 0 && instance.name !== query.name) return false;
+			if (query.category !== void 0 && instance.category !== query.category) return false;
+			if (query.tag !== void 0 && !(instance.tags ?? []).includes(query.tag)) return false;
+			return true;
+		});
+	}
+	/**
+	* Test whether a template id is registered.
+	*
+	* @param id - The template id
+	* @returns `true` when `id` is registered
+	*/
+	has(id) {
+		return this.#templates.has(id);
+	}
+	remove(target) {
+		if (target === void 0) {
+			for (const instance of this.#templates.values()) this.#emitter.emit("remove", instance);
+			this.#templates.clear();
+			return;
+		}
+		if (typeof target === "string") {
+			const instance = this.#templates.get(target);
+			if (instance === void 0) return false;
+			this.#templates.delete(target);
+			this.#emitter.emit("remove", instance);
+			return true;
+		}
+		for (const id of target) if (!this.#templates.has(id)) return false;
+		for (const id of target) {
+			const instance = this.#templates.get(id);
+			if (instance === void 0) continue;
+			this.#templates.delete(id);
+			this.#emitter.emit("remove", instance);
+		}
+		return true;
+	}
+	/** Remove every registered template, emitting `clear`. */
+	clear() {
+		this.#templates.clear();
+		this.#emitter.emit("clear");
+	}
+	/**
+	* Fill 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
+	*/
+	fill(id, values, options) {
+		return this.template(id).fill(values, options);
+	}
+	/**
+	* Validate values against a registered template by id.
+	*
+	* @param id - The template id
+	* @param values - The values to check
+	* @returns The {@link TemplateValidationResult}
+	* @throws {@link TemplateError} coded `NOTFOUND` when `id` is unknown
+	*/
+	validate(id, values) {
+		return this.template(id).validate(values);
+	}
+	/**
+	* Project 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();
+	}
+	#instantiate(template) {
+		if (this.#isInstance(template)) return template;
+		return new Template({
+			...template,
+			missing: template.missing ?? this.#missing,
+			locale: template.locale ?? this.#locale
+		});
+	}
+	#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 });
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Create 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}
+*
+* @example
+* ```ts
+* import { createTemplate } from '@src/core'
+*
+* const greeting = createTemplate({ name: 'greeting', content: 'Hi {{name}}' })
+* greeting.fill({ name: 'Ada' }) // 'Hi Ada'
+* ```
+*/
+function createTemplate(options) {
+	return new Template(options);
+}
+/**
+* Create 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}
+*
+* @example
+* ```ts
+* import { createTemplateManager } from '@src/core'
+*
+* const templates = createTemplateManager({
+* 	templates: [{ id: 'greeting', name: 'greeting', content: 'Hi {{name}}' }],
+* })
+* templates.fill('greeting', { name: 'Ada' }) // 'Hi Ada'
+* ```
+*/
+function createTemplateManager(options) {
+	return new TemplateManager(options);
+}
+//#endregion
+export { DEFAULT_LOCALE, DEFAULT_MISSING_POLICY, FILL_PATTERN, Template, TemplateError, TemplateManager, UNSAFE_FIELD_SEGMENTS, createTemplate, createTemplateManager, fillTemplate, formatValue, isTemplateError, placeholderShape, resolveSafeField };
+
+//# sourceMappingURL=index.js.map