suaveplan/openspec/archive/2026-04-19-enterprise-templates/proposal.md

OpenSpec Change: enterprise-templates

• Change ID: enterprise-templates
• Package: @suaveplan/templates
• Category: universal
• Target path: packages/universal/templates
• Status: PROPOSED
• Date: 2026-04-19
• Reference spec: /mnt/s/web/suaveplan/enterprise/templates.md

Summary

Greenfield implementation of @suaveplan/templates for the genesis branch. The existing main-branch templates package provides the baseline public-API surface to preserve; this change delivers an enterprise-grade plugin-based template engine with type-safe contexts, variable interpolation (dot-notation, array-index), transform plugins (case, regex, split), dynamic plugins (counter, datetime with injectable clock, uuid with injectable RNG), control-flow plugins (conditional, loop), configurable delimiters, preset bundles, structured errors extending @suaveplan/error, Zod schemas, OTel instrumentation, property-based tests, and benchmarks.

Current-state audit (genesis)

The package does not exist on genesis yet — this is a fresh build.

Available workspace deps on genesis

Package	Available
@suaveplan/error	✅
@suaveplan/types	✅
@suaveplan/logger	✅
@suaveplan/opentelemetry	❌ not yet built — use @opentelemetry/api directly
@suaveplan/schema-registry	❌ not yet built — export Zod schemas directly
@suaveplan/i18n	❌ not yet built — skip i18n integration
@suaveplan/datetime	❌ not yet built — createDateTimePlugin uses native Date internally via injectable Clock

External deps (via catalog):

• zod → catalog:forms
• @opentelemetry/api → catalog:observability
• tslib → catalog:build

Dev deps (via catalog):

• vitest, @vitest/coverage-istanbul → catalog:testing
• fast-check → catalog:testing
• mitata → catalog:testing

Preserved public API surface (from main branch)

Parse state

• createParseState(maxDepth?) → ParseState — creates initial parse state with counters, depth, cache, and custom maps
• cloneParseState(state) → ParseState — deep-clones a parse state (counters, cache, custom maps)
• clearCounters(state) → void — resets all named counters to zero
• getCounter(state, name) → number — returns current value of a named counter (0 if not set)
• resetCounter(state, name) → void — resets a single named counter to zero

Core engine

• TemplateEngine<TContext> class — generic over TContext extending TemplateContext
  • constructor(options?: TemplateEngineOptions)
  • .use(plugin) → this — registers a plugin, re-sorts by priority descending
  • .usePreset(preset) → this — registers all plugins from a preset
  • .remove(name) → this — removes a plugin by name
  • .getPlugins() → readonly Plugin<TContext>[]
  • .parse(template, context, options?) → string — synchronous render
  • .parseAsync(template, context, options?) → Promise<string> — async render
  • .compile(template) → CompiledTemplate<TContext> — returns reusable compiled template object

Control flow plugins

• createConditionalPlugin() → Plugin — {condition}...{/condition} blocks; evaluates truthy context values
• createLoopPlugin() → Plugin — {loop:items}...{/loop} blocks; iterates over arrays in context

Dynamic variable plugins

• createCounterPlugin() → Plugin — {_counter:name:start:pad} — stateful named counters with zero-padding
• createDateTimePlugin(opts?) → Plugin — {_datetime:pattern} — date/time formatting with injectable Clock
• createUuidPlugin(opts?) → Plugin — {_uuid} / {_nanoid:length} — UUID v4 and nano-ID generation with injectable Rng

Transform plugins

• createCaseTransformPlugin() → Plugin — {value|upper}, {value|lower}, {value|title}, {value|camel}, {value|snake}, {value|kebab} — string case transforms
• createRegexPlugin(patterns) → Plugin — applies caller-supplied regex replacements to resolved values
• createStringSplitPlugin() → Plugin — {value|split:sep:index} — splits on separator and returns element at index

Variable resolution plugins

• createArrayIndexPlugin() → Plugin — {items[0]} — zero-based array index access in context
• createDotNotationPlugin() → Plugin — {user.name} — nested property access via dot path

Presets

• minimalPreset() → PluginPreset — dot-notation + array-index only
• standardPreset() → PluginPreset — dot-notation, array-index, case transforms, counter, datetime, uuid
• fullPreset() → PluginPreset — standard + regex + string-split + conditional
• fullPresetWithLoops() → PluginPreset — full + loop plugin

Types (all exported)

• TemplateContext — Record<string, unknown>
• PluginPriority — enum: CRITICAL = 95, HIGH = 80, MEDIUM = 50, LOW = 20, MINIMAL = 5
• ParseState — { counters: Map<string, number>; depth: number; maxDepth: number; cache: Map<string, unknown>; custom: Map<string, unknown> }
• PluginMatch — { match: string; groups: RegExpMatchArray | null; index: number }
• PluginResult — string | Promise<string> | typeof SKIP_PLUGIN
• SKIP_PLUGIN — symbol — return from Plugin.transform to skip this match
• Plugin<TContext> — { name, priority, pattern, async?, transform(), init?(), cleanup?() }
• PluginPreset<TContext> — { name, plugins: Plugin<TContext>[] }
• TemplateEngineOptions — { maxDepth?, throwOnError?, enableCache?, onError? }
• ParseOptions — { maxDepth?, async? }
• CompiledTemplate<TContext> — { source, parse(context), parseAsync(context) }
• TemplateError — error with template, context, cause fields (genesis: extends SuaveplanError)
• PluginError — error with pluginName, match, cause fields (genesis: extends SuaveplanError)
• MaxDepthError — error with depth, maxDepth fields (genesis: extends SuaveplanError)

Utilities (all exported)

• escapeRegex(str) → string — escapes regex metacharacters
• isEscaped(template, index) → boolean — checks if a character at index is backslash-escaped
• unescapeTemplate(str) → string — removes template escape characters
• formatDate(date, pattern) → string — formats a Date using YYYY MM DD HH mm ss SSS tokens
• getNestedValue(obj, path) → unknown — resolves dot-path into a plain object
• hasNestedPath(obj, path) → boolean — checks dot-path existence without throwing
• setNestedValue(obj, path, value) → void — sets a value at a dot-path (creates intermediate objects)
• pad(value, length, char?, left?) → string — pads a string or number to a target length
• generateUuid() → string — UUID v4 (genesis: uses injectable Rng; falls back to crypto.randomUUID)
• generateNanoid(length?) → string — URL-safe nano ID (genesis: uses injectable Rng)

New additions for genesis

Structured errors

All error classes extend SuaveplanError from @suaveplan/error with stable defineCodes error codes:

• TemplateError base extends SuaveplanError; code namespace TEMPLATE.*
• PluginError extends TemplateError; code TEMPLATE.PLUGIN_ERROR
• MaxDepthError extends TemplateError; code TEMPLATE.MAX_DEPTH
• Additional codes: TEMPLATE.PARSE_ERROR, TEMPLATE.MISSING_VARIABLE, TEMPLATE.PLUGIN_CONFLICT, TEMPLATE.RENDER_ERROR

Zod schemas

• TemplateEngineOptionsSchema — validates TemplateEngineOptions at the boundary
• ParseOptionsSchema — validates ParseOptions
• PluginPrioritySchema — validates priority integer in [0, 100]

Injectable clock (DateTimePlugin)

• createDateTimePlugin({ clock?: Clock }) — accepts Clock from @suaveplan/types; defaults to Date.now() when no clock is injected; enables deterministic date rendering in tests via FakeClock

Injectable RNG (UuidPlugin, generateUuid, generateNanoid)

• createUuidPlugin({ rng?: Rng }) — accepts Rng from @suaveplan/types for deterministic UUID/nanoid generation in tests
• generateUuid(rng?) and generateNanoid(length?, rng?) accept optional Rng; fall back to crypto.randomUUID / Math.random when omitted

OTel instrumentation

• Counter template.render.total — attributes: outcome (success | error), preset (engine preset label if set)
• Histogram template.render.duration_ms — latency per .parse() / .parseAsync() call
• Counter template.plugin.calls.total — attributes: plugin_name, outcome (success | skip | error)
• All instruments are no-op when no OTel exporter is registered

Property-based tests (fast-check)

• Idempotent rendering: re-parsing an already-rendered output with the same context produces the same string (no side-effect variables in the result)
• Counter monotone: getCounter value never decreases across successive .parse() calls with the counter plugin
• Dot-notation round-trip: getNestedValue(obj, path) after setNestedValue(obj, path, value) returns value for any safe path
• Jitter-free assertion: PluginPriority enum values are strictly ordered MINIMAL < LOW < MEDIUM < HIGH < CRITICAL

Benchmarks (mitata)

• Render a 100-variable dot-notation template — 10 000 iterations
• Plugin call overhead baseline: single no-op plugin on a 1-token template — 100 000 iterations
• formatDate formatting — 100 000 iterations
• getNestedValue 5-level deep path — 100 000 iterations

Impact

• Adds one new package: packages/universal/templates
• Adds one new spec capability: templates
• No existing package consumers on genesis yet