error-codes

Purpose

Defines and freezes the complete error-code registry for @suaveplan/templates using the defineCodes utility from @suaveplan/error. Every error thrown by the template engine carries one of these stable codes, enabling consumer code to programmatically inspect and react to error conditions without relying on string matching against human-readable messages. The TEMPLATE. namespace prefix ensures global uniqueness across the project.

Features

Seven stable error codes prefixed with TEMPLATE..
Codes are frozen at module load time — defineCodes returns a Readonly object so no code can be modified or added after import.
The TemplateCode union type is derived from the registry using typeof TEMPLATE_CODES, so adding a new code automatically extends the type.
Used by TemplateError, PluginError, and MaxDepthError constructors to tag every thrown error.

Usage: Basic Example

import { TEMPLATE_CODES } from "@suaveplan/templates/errors/error-codes";

try {
    engine.parse("{missing}", {});
} catch (err) {
    if (err instanceof TemplateError && err.code === TEMPLATE_CODES.MISSING_VARIABLE) {
        console.log("Missing variable:", err.renderContext);
    }
}

Usage: Advanced Example

import { TEMPLATE_CODES } from "@suaveplan/templates/errors/error-codes";
import type { TemplateCode } from "@suaveplan/templates/errors/error-codes";

function isTemplateError(code: TemplateCode): boolean {
    return Object.values(TEMPLATE_CODES).includes(code);
}

// Inspect the full registry programmatically
console.log(Object.keys(TEMPLATE_CODES));
// → ["PARSE_ERROR", "MISSING_VARIABLE", "PLUGIN_CONFLICT", "PLUGIN_ERROR", "RENDER_ERROR", "MAX_DEPTH", "INVALID_CONFIG"]

API Reference

`TEMPLATE_CODES`

A frozen Record<string, string> with the following keys:

Key	Value	Thrown by
`PARSE_ERROR`	`"TEMPLATE.PARSE_ERROR"`	Engine catch-all for unexpected parse failures
`MISSING_VARIABLE`	`"TEMPLATE.MISSING_VARIABLE"`	When `throwOnError` is set and a variable is absent
`PLUGIN_CONFLICT`	`"TEMPLATE.PLUGIN_CONFLICT"`	`engine.use()` with a duplicate plugin name
`PLUGIN_ERROR`	`"TEMPLATE.PLUGIN_ERROR"`	When a plugin's `transform()` throws unexpectedly
`RENDER_ERROR`	`"TEMPLATE.RENDER_ERROR"`	General render pipeline failure
`MAX_DEPTH`	`"TEMPLATE.MAX_DEPTH"`	Recursive render depth exceeds `maxDepth`
`INVALID_CONFIG`	`"TEMPLATE.INVALID_CONFIG"`	Invalid engine construction options

`TemplateCode`

type TemplateCode = (typeof TEMPLATE_CODES)[keyof typeof TEMPLATE_CODES]

Union of all string literal values in TEMPLATE_CODES. Used as the generic type parameter for TemplateError, PluginError, and MaxDepthError to enforce that every error carries a known code.

Implementation Notes

defineCodes("TEMPLATE", [...]) from @suaveplan/error constructs the registry by prefixing each code name with "TEMPLATE." and freezing the result with Object.freeze. This prevents accidental mutation in consumer code.
The registry is exported as a named constant rather than individual string literals to prevent typo-based drift between the registered codes and their usage sites; all usages should reference TEMPLATE_CODES.SOME_CODE rather than string literals.
The as const assertion on the code-name array is required so TypeScript infers a tuple of string literals rather than string[], enabling precise inference of TemplateCode.

3.5 KiB Raw Blame History