@voyantjs/templating 0.96.0

package/README.md

@@ -0,0 +1,10 @@
+# @voyantjs/templating
+
+Liquid/Mustache template rendering and syntax validation, extracted from
+`@voyantjs/utils` into a lean package (`liquidjs` only — no Drizzle, no
+`@voyantjs/db`, no pdf-lib). This lets contract packages that need template
+validation (e.g. `@voyantjs/legal-contracts`, whose contract bodies are Liquid
+templates) depend on it without pulling the data layer.
+
+`@voyantjs/utils/template-renderer` re-exports everything here, so existing
+import paths are unchanged.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./template-renderer.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./template-renderer.js";

package/dist/template-renderer.d.ts

@@ -0,0 +1,23 @@
+export type StructuredTemplateBodyFormat = "html" | "markdown" | "lexical_json";
+/**
+ * Optional render hooks. `missingValuePlaceholder` substitutes a
+ * literal (typically `"-"`) for any output tag whose resolved value is
+ * null / undefined / empty-string. Numbers (including 0) and
+ * booleans are stringified as-is — they aren't "missing".
+ */
+export interface RenderTemplateOptions {
+    missingValuePlaceholder?: string;
+}
+export interface TemplateSyntaxIssue {
+    message: string;
+}
+export declare function renderMustacheTemplate(body: string, variables: Record<string, unknown>, options?: RenderTemplateOptions): string;
+/**
+ * Parse-check Liquid syntax without rendering. Rich-text editors can split
+ * Liquid delimiters across HTML blocks; validating the raw body catches those
+ * templates before they are persisted or previewed.
+ */
+export declare function validateStructuredTemplateSyntax(body: string, bodyFormat: StructuredTemplateBodyFormat): TemplateSyntaxIssue[];
+export declare function renderStringTemplate(body: string, variables: Record<string, unknown>, options?: RenderTemplateOptions): string;
+export declare function renderStructuredTemplate(body: string, bodyFormat: StructuredTemplateBodyFormat, variables: Record<string, unknown>, options?: RenderTemplateOptions): string;
+//# sourceMappingURL=template-renderer.d.ts.map

package/dist/template-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-renderer.d.ts","sourceRoot":"","sources":["../src/template-renderer.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,4BAA4B,GAAG,MAAM,GAAG,UAAU,GAAG,cAAc,CAAA;AA+I/E;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,uBAAuB,CAAC,EAAE,MAAM,CAAA;CACjC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAA;CAChB;AAiCD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,MAAM,CAMR;AA4BD;;;;GAIG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,4BAA4B,GACvC,mBAAmB,EAAE,CA+BvB;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,MAAM,CASR;AAiBD,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,4BAA4B,EACxC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,MAAM,CAgCR"}

package/dist/template-renderer.js

@@ -0,0 +1,282 @@
+import { Liquid } from "liquidjs";
+const liquid = new Liquid({
+    strictFilters: false,
+    strictVariables: false,
+    jsTruthy: true,
+});
+liquid.registerFilter("json", (value) => JSON.stringify(value ?? null));
+function parseNumber(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === "string" && value.trim() !== "") {
+        const n = Number.parseFloat(value);
+        return Number.isFinite(n) ? n : null;
+    }
+    return null;
+}
+/**
+ * `currency` — Intl.NumberFormat currency style. Expects a decimal amount
+ * (`123.45`). Example: `{{ amount | currency: "EUR", "en-US" }}` →
+ * `"€123.45"`. Falls back to `String(value)` when the value isn't a number.
+ */
+liquid.registerFilter("currency", (value, currency = "EUR", locale = "en-US") => {
+    const num = parseNumber(value);
+    if (num === null)
+        return String(value ?? "");
+    return new Intl.NumberFormat(String(locale), {
+        style: "currency",
+        currency: String(currency || "EUR"),
+    }).format(num);
+});
+/**
+ * `cents` — Shortcut for formatting integer cents (`12345` → `"€123.45"`).
+ * Saves every template from `{{ (amountCents | divided_by: 100) | currency: ... }}`.
+ */
+liquid.registerFilter("cents", (value, currency = "EUR", locale = "en-US") => {
+    const num = parseNumber(value);
+    if (num === null)
+        return String(value ?? "");
+    return new Intl.NumberFormat(String(locale), {
+        style: "currency",
+        currency: String(currency || "EUR"),
+    }).format(num / 100);
+});
+/**
+ * `format_date` — ISO/string/Date → locale-formatted date. Second arg chooses
+ * the preset: `"short"` (`01/15/2026`), `"medium"` (default, `Jan 15, 2026`),
+ * `"long"` (`January 15, 2026`), `"iso"` (`2026-01-15`), or `"time"`
+ * (delegates to `format_time` — `08:30`). Pair with a locale for
+ * Romanian/etc.: `{{ startsAt | format_date: "medium", "ro-RO" }}`.
+ */
+liquid.registerFilter("format_date", (value, preset = "medium", locale = "en-US") => {
+    if (value === null || value === undefined || value === "")
+        return "";
+    const date = value instanceof Date ? value : new Date(String(value));
+    if (Number.isNaN(date.getTime()))
+        return String(value);
+    const p = String(preset ?? "medium").toLowerCase();
+    if (p === "iso")
+        return date.toISOString().slice(0, 10);
+    if (p === "time") {
+        // Delegate to `format_time`'s default short shape so authors
+        // can pipe a single `format_date: "time"` without remembering
+        // to switch filters.
+        return date.toLocaleTimeString(String(locale), { hour: "2-digit", minute: "2-digit" });
+    }
+    const options = p === "short"
+        ? { year: "numeric", month: "2-digit", day: "2-digit" }
+        : p === "long"
+            ? { year: "numeric", month: "long", day: "numeric" }
+            : { year: "numeric", month: "short", day: "numeric" };
+    return date.toLocaleDateString(String(locale), options);
+});
+/**
+ * `format_time` — ISO/string/Date → locale-formatted time-of-day.
+ * Second arg picks the preset: `"short"` (default, `08:30`),
+ * `"medium"` (`08:30:42`), `"iso"` (`08:30:42` — same as medium but
+ * always 24-hour). Locale defaults to `en-US`; pass `"ro-RO"` etc.
+ * for locale-aware formatting (12 vs. 24 hour). Falls back to the
+ * raw value when not parseable.
+ *
+ * Examples:
+ *   `{{ contract.signedAt | format_time }}`               → `"08:30"`
+ *   `{{ contract.signedAt | format_time: "medium" }}`     → `"08:30:42"`
+ *   `{{ contract.signedAt | format_time: "short", "ro-RO" }}` → `"08:30"`
+ */
+liquid.registerFilter("format_time", (value, preset = "short", locale = "en-US") => {
+    if (value === null || value === undefined || value === "")
+        return "";
+    const date = value instanceof Date ? value : new Date(String(value));
+    if (Number.isNaN(date.getTime()))
+        return String(value);
+    const p = String(preset ?? "short").toLowerCase();
+    if (p === "iso") {
+        // 24-hour HH:MM:SS regardless of locale, useful for audit-
+        // trail copy where consistency beats locale courtesy.
+        return date.toISOString().slice(11, 19);
+    }
+    const options = p === "medium"
+        ? { hour: "2-digit", minute: "2-digit", second: "2-digit" }
+        : { hour: "2-digit", minute: "2-digit" };
+    return date.toLocaleTimeString(String(locale), options);
+});
+function resolvePath(obj, path) {
+    if (obj === null || obj === undefined)
+        return undefined;
+    const segments = [];
+    const parts = path.split(".");
+    for (const part of parts) {
+        if (!part)
+            continue;
+        const indexMatches = [...part.matchAll(/([^[\]]+)|\[(\d+)\]/g)];
+        for (const match of indexMatches) {
+            if (match[1] !== undefined)
+                segments.push(match[1]);
+            else if (match[2] !== undefined)
+                segments.push(Number.parseInt(match[2], 10));
+        }
+    }
+    let current = obj;
+    for (const seg of segments) {
+        if (current === null || current === undefined)
+            return undefined;
+        if (typeof seg === "number") {
+            if (!Array.isArray(current))
+                return undefined;
+            current = current[seg];
+        }
+        else {
+            if (typeof current !== "object")
+                return undefined;
+            current = current[seg];
+        }
+    }
+    return current;
+}
+function stringifyValue(value, placeholder) {
+    if (value === null || value === undefined)
+        return placeholder ?? "";
+    if (typeof value === "string") {
+        return value === "" && placeholder ? placeholder : value;
+    }
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return JSON.stringify(value);
+}
+const MUSTACHE_RE = /\{\{\s*([^}]+?)\s*\}\}/g;
+const LIQUID_CONTROL_RE = /\{%-?[\s\S]*?-?%\}/;
+const LIQUID_FILTER_RE = /\{\{[\s\S]*\|[\s\S]*\}\}/;
+const LIQUID_OUTPUT_RE = /\{\{\s*([^}]+?)\s*\}\}/g;
+const LIQUID_DELIMITER_RE = /\{\{|\{%/;
+const HAS_DEFAULT_FILTER_RE = /\|\s*default\s*:/i;
+/**
+ * Inject `| default: <fallback>` into every Liquid output tag that
+ * doesn't already chain a `default:` filter. Applied AFTER the rest of
+ * the filter chain so transformations like `cents` / `format_date`
+ * still run; they return empty strings on missing input, which the
+ * `default` filter then replaces with the fallback. Output tags whose
+ * authors already wired their own `default: "..."` are left alone.
+ */
+function injectDefaultFilter(body, fallback) {
+    return body.replace(LIQUID_OUTPUT_RE, (full, inner) => {
+        if (HAS_DEFAULT_FILTER_RE.test(inner))
+            return full;
+        return `{{ ${inner.trim()} | default: ${JSON.stringify(fallback)} }}`;
+    });
+}
+export function renderMustacheTemplate(body, variables, options) {
+    const placeholder = options?.missingValuePlaceholder;
+    return body.replace(MUSTACHE_RE, (_, path) => {
+        const resolved = resolvePath(variables, path.trim());
+        return stringifyValue(resolved, placeholder);
+    });
+}
+function shouldUseLiquid(body) {
+    return LIQUID_CONTROL_RE.test(body) || LIQUID_FILTER_RE.test(body);
+}
+function validateStringTemplateSyntax(body) {
+    if (!LIQUID_DELIMITER_RE.test(body))
+        return [];
+    try {
+        liquid.parse(body);
+        return [];
+    }
+    catch (error) {
+        return [{ message: error instanceof Error ? error.message : String(error) }];
+    }
+}
+function collectLexicalTextIssues(node, issues) {
+    if (typeof node.text === "string") {
+        issues.push(...validateStringTemplateSyntax(node.text));
+    }
+    if (Array.isArray(node.children)) {
+        for (const child of node.children) {
+            collectLexicalTextIssues(child, issues);
+        }
+    }
+}
+/**
+ * Parse-check Liquid syntax without rendering. Rich-text editors can split
+ * Liquid delimiters across HTML blocks; validating the raw body catches those
+ * templates before they are persisted or previewed.
+ */
+export function validateStructuredTemplateSyntax(body, bodyFormat) {
+    if (bodyFormat !== "lexical_json") {
+        return validateStringTemplateSyntax(body);
+    }
+    try {
+        const parsed = JSON.parse(body);
+        const issues = [];
+        if (Array.isArray(parsed)) {
+            for (const entry of parsed) {
+                if (entry && typeof entry === "object") {
+                    collectLexicalTextIssues(entry, issues);
+                }
+            }
+            return issues;
+        }
+        if (parsed && typeof parsed === "object") {
+            const obj = parsed;
+            if (obj.root && typeof obj.root === "object") {
+                collectLexicalTextIssues(obj.root, issues);
+                return issues;
+            }
+            collectLexicalTextIssues(obj, issues);
+            return issues;
+        }
+        return [];
+    }
+    catch {
+        return validateStringTemplateSyntax(body);
+    }
+}
+export function renderStringTemplate(body, variables, options) {
+    if (!shouldUseLiquid(body)) {
+        return renderMustacheTemplate(body, variables, options);
+    }
+    const processedBody = options?.missingValuePlaceholder
+        ? injectDefaultFilter(body, options.missingValuePlaceholder)
+        : body;
+    return liquid.parseAndRenderSync(processedBody, variables);
+}
+function walkLexical(node, variables, options) {
+    const next = { ...node };
+    if (typeof next.text === "string") {
+        next.text = renderStringTemplate(next.text, variables, options);
+    }
+    if (Array.isArray(next.children)) {
+        next.children = next.children.map((child) => walkLexical(child, variables, options));
+    }
+    return next;
+}
+export function renderStructuredTemplate(body, bodyFormat, variables, options) {
+    if (bodyFormat === "lexical_json") {
+        try {
+            const parsed = JSON.parse(body);
+            if (Array.isArray(parsed)) {
+                return JSON.stringify(parsed.map((entry) => {
+                    if (entry && typeof entry === "object") {
+                        return walkLexical(entry, variables, options);
+                    }
+                    return entry;
+                }));
+            }
+            if (parsed && typeof parsed === "object") {
+                const obj = parsed;
+                if (obj.root && typeof obj.root === "object") {
+                    const result = {
+                        ...obj,
+                        root: walkLexical(obj.root, variables, options),
+                    };
+                    return JSON.stringify(result);
+                }
+                return JSON.stringify(walkLexical(obj, variables, options));
+            }
+            return body;
+        }
+        catch {
+            return renderStringTemplate(body, variables, options);
+        }
+    }
+    return renderStringTemplate(body, variables, options);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@voyantjs/templating",
+  "version": "0.96.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./template-renderer": "./src/template-renderer.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "test": "vitest run --passWithNoTests",
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "prepack": "pnpm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      },
+      "./template-renderer": {
+        "types": "./dist/template-renderer.d.ts",
+        "import": "./dist/template-renderer.js",
+        "default": "./dist/template-renderer.js"
+      }
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "dependencies": {
+    "liquidjs": "^10.24.0"
+  },
+  "devDependencies": {
+    "@voyantjs/voyant-typescript-config": "workspace:*",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voyantjs/voyant.git",
+    "directory": "packages/templating"
+  }
+}