@checkstack/template-engine 0.2.0

package/src/filters.ts

@@ -0,0 +1,145 @@
+import type { Filter, FilterRegistry } from "./types";
+
+/**
+ * Create an empty filter registry.
+ */
+export function createFilterRegistry(): FilterRegistry {
+  const filters = new Map<string, Filter>();
+  return {
+    register(name, filter) {
+      filters.set(name, filter);
+    },
+    get(name) {
+      return filters.get(name);
+    },
+    has(name) {
+      return filters.has(name);
+    },
+    list() {
+      return [...filters.keys()].toSorted();
+    },
+  };
+}
+
+/**
+ * Create a registry pre-loaded with the default filter set.
+ *
+ * Filters intentionally do NOT throw on null/undefined — they pass it
+ * through. Operators can chain `| default("...")` to substitute a value.
+ */
+export function createDefaultFilterRegistry(): FilterRegistry {
+  const registry = createFilterRegistry();
+  registry.register("default", filterDefault);
+  registry.register("upper", filterUpper);
+  registry.register("lower", filterLower);
+  registry.register("capitalize", filterCapitalize);
+  registry.register("trim", filterTrim);
+  registry.register("truncate", filterTruncate);
+  registry.register("length", filterLength);
+  registry.register("json", filterJson);
+  registry.register("iso", filterIso);
+  registry.register("date", filterDate);
+  registry.register("join", filterJoin);
+  registry.register("replace", filterReplace);
+  registry.register("not", filterNot);
+  return registry;
+}
+
+// ─── Built-ins ─────────────────────────────────────────────────────────────
+
+function filterDefault(value: unknown, fallback: unknown): unknown {
+  if (value === null || value === undefined || value === "") return fallback;
+  return value;
+}
+
+function filterUpper(value: unknown): unknown {
+  return typeof value === "string" ? value.toUpperCase() : value;
+}
+
+function filterLower(value: unknown): unknown {
+  return typeof value === "string" ? value.toLowerCase() : value;
+}
+
+function filterCapitalize(value: unknown): unknown {
+  if (typeof value !== "string" || value.length === 0) return value;
+  return value[0]!.toUpperCase() + value.slice(1);
+}
+
+function filterTrim(value: unknown): unknown {
+  return typeof value === "string" ? value.trim() : value;
+}
+
+function filterTruncate(value: unknown, length: unknown): unknown {
+  if (typeof value !== "string") return value;
+  const n = typeof length === "number" ? length : Number(length);
+  if (!Number.isFinite(n) || n <= 0) return value;
+  if (value.length <= n) return value;
+  return value.slice(0, n) + "…";
+}
+
+function filterLength(value: unknown): unknown {
+  if (typeof value === "string" || Array.isArray(value)) return value.length;
+  if (value && typeof value === "object") return Object.keys(value).length;
+  return 0;
+}
+
+function filterJson(value: unknown): unknown {
+  return JSON.stringify(value);
+}
+
+function filterIso(value: unknown): unknown {
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "string" || typeof value === "number") {
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? value : d.toISOString();
+  }
+  return value;
+}
+
+function filterDate(value: unknown, format: unknown): unknown {
+  const fmt = typeof format === "string" ? format : "ISO";
+  let date: Date | undefined;
+  if (value instanceof Date) date = value;
+  else if (typeof value === "string" || typeof value === "number") {
+    const d = new Date(value);
+    if (!Number.isNaN(d.getTime())) date = d;
+  }
+  if (!date) return value;
+  if (fmt === "ISO") return date.toISOString();
+  if (fmt === "date") return date.toISOString().slice(0, 10);
+  if (fmt === "time") return date.toISOString().slice(11, 19);
+  if (fmt === "unix") return Math.floor(date.getTime() / 1000);
+  if (fmt === "rfc2822") return date.toUTCString();
+  return date.toISOString();
+}
+
+function filterJoin(value: unknown, separator: unknown): unknown {
+  if (!Array.isArray(value)) return value;
+  const sep = typeof separator === "string" ? separator : ", ";
+  return value.map(String).join(sep);
+}
+
+function filterReplace(value: unknown, search: unknown, replacement: unknown): unknown {
+  if (typeof value !== "string") return value;
+  if (typeof search !== "string") return value;
+  const repl = typeof replacement === "string" ? replacement : "";
+  return value.split(search).join(repl);
+}
+
+function filterNot(value: unknown): unknown {
+  return !isTruthy(value);
+}
+
+/**
+ * Centralised truthiness rule. Mirrors JavaScript's notion plus: empty
+ * string is falsy, empty arrays are falsy, empty plain objects are falsy.
+ * Exported so the renderer can share the same rule with filters.
+ */
+export function isTruthy(value: unknown): boolean {
+  if (value === null || value === undefined) return false;
+  if (value === false || value === 0) return false;
+  if (typeof value === "string") return value.length > 0;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === "object") return Object.keys(value).length > 0;
+  return Boolean(value);
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./errors";
+export * from "./parser";
+export * from "./renderer";
+export * from "./filters";
+export * from "./types";
+export * from "./ast";

package/src/parser.ts

@@ -0,0 +1,340 @@
+import type {
+  Expr,
+  TemplateNode,
+} from "./ast";
+import { TemplateParseError, pointRange } from "./errors";
+import { Tokenizer, type Token, type TokenKind } from "./tokenizer";
+import type { ParsedCondition, ParsedTemplate, SourceRange } from "./types";
+
+/**
+ * Parse a template string — literal text interleaved with `{{ expr }}`
+ * blocks — into a `ParsedTemplate` that can be rendered.
+ */
+export function parseTemplate(source: string): ParsedTemplate {
+  const tokens = new Tokenizer(source).tokenize();
+  const parser = new Parser(tokens, source);
+  const nodes = parser.parseTemplateNodes();
+  return { version: 1, nodes, source };
+}
+
+/**
+ * Parse a single expression with no surrounding text. Used for conditions
+ * (`when: "..."` fields, `condition` action guards, trigger filters).
+ *
+ * The input is the raw expression source — the parser does NOT expect or
+ * accept surrounding `{{ }}`.
+ */
+export function parseCondition(source: string): ParsedCondition {
+  // Wrap source so the tokenizer enters expression mode.
+  const wrapped = `{{${source}}}`;
+  const tokens = new Tokenizer(wrapped).tokenize();
+  const parser = new Parser(tokens, wrapped);
+  // Skip the synthesized EXPR_OPEN.
+  parser.expect("EXPR_OPEN");
+  const expr = parser.parseExpression();
+  parser.expect("EXPR_CLOSE");
+  return { version: 1, root: expr, source };
+}
+
+class Parser {
+  private pos = 0;
+
+  constructor(
+    private readonly tokens: Token[],
+    private readonly source: string,
+  ) {}
+
+  parseTemplateNodes(): TemplateNode[] {
+    const nodes: TemplateNode[] = [];
+    while (!this.eof()) {
+      const t = this.peek();
+      if (t.kind === "LITERAL") {
+        this.advance();
+        nodes.push({ kind: "text", value: t.value, range: t.range });
+      } else if (t.kind === "EXPR_OPEN") {
+        const start = t.range.start;
+        this.advance();
+        const expr = this.parseExpression();
+        const close = this.expect("EXPR_CLOSE");
+        nodes.push({
+          kind: "expression",
+          expression: expr,
+          range: { start, end: close.range.end },
+        });
+      } else {
+        throw new TemplateParseError({
+          message: `Unexpected token ${t.kind} at top level`,
+          source: this.source,
+          range: t.range,
+        });
+      }
+    }
+    return nodes;
+  }
+
+  /**
+   * Parse an expression with full operator precedence.
+   *
+   * Grammar (lowest precedence first):
+   *
+   *   expression := ternary
+   *   ternary    := pipe ('?' expression ':' expression)?
+   *   pipe       := or ('|' IDENT ('(' args ')')?)*
+   *   or         := and ('||' and)*
+   *   and        := eq ('&&' eq)*
+   *   eq         := cmp (('==' | '!=') cmp)*
+   *   cmp        := unary (('<' | '>' | '<=' | '>=') unary)*
+   *   unary      := '!' unary | primary
+   *   primary    := literal | identifier (member | index)* | '(' expression ')'
+   */
+  parseExpression(): Expr {
+    return this.parseTernary();
+  }
+
+  private parseTernary(): Expr {
+    const cond = this.parsePipe();
+    if (this.match("QUESTION")) {
+      const consequent = this.parseExpression();
+      this.expect("COLON");
+      const alternate = this.parseExpression();
+      return {
+        kind: "ternary",
+        condition: cond,
+        consequent,
+        alternate,
+        range: this.span(cond.range, alternate.range),
+      };
+    }
+    return cond;
+  }
+
+  private parsePipe(): Expr {
+    let value = this.parseOr();
+    while (this.match("PIPE")) {
+      const filterTok = this.expect("IDENT");
+      const args: Expr[] = [];
+      if (this.match("LPAREN")) {
+        if (!this.check("RPAREN")) {
+          args.push(this.parseExpression());
+          while (this.match("COMMA")) {
+            args.push(this.parseExpression());
+          }
+        }
+        this.expect("RPAREN");
+      }
+      value = {
+        kind: "pipe",
+        value,
+        filter: filterTok.value,
+        args,
+        range: this.span(
+          value.range,
+          args.length > 0 ? args.at(-1)!.range : filterTok.range,
+        ),
+      };
+    }
+    return value;
+  }
+
+  private parseOr(): Expr {
+    let left = this.parseAnd();
+    while (this.check("OR")) {
+      const opTok = this.advance();
+      const right = this.parseAnd();
+      left = {
+        kind: "binary",
+        op: "||",
+        left,
+        right,
+        range: this.span(left.range, right.range),
+      };
+      void opTok;
+    }
+    return left;
+  }
+
+  private parseAnd(): Expr {
+    let left = this.parseEquality();
+    while (this.check("AND")) {
+      this.advance();
+      const right = this.parseEquality();
+      left = {
+        kind: "binary",
+        op: "&&",
+        left,
+        right,
+        range: this.span(left.range, right.range),
+      };
+    }
+    return left;
+  }
+
+  private parseEquality(): Expr {
+    let left = this.parseComparison();
+    while (this.check("EQ") || this.check("NEQ")) {
+      const opTok = this.advance();
+      const right = this.parseComparison();
+      left = {
+        kind: "binary",
+        op: opTok.kind === "EQ" ? "==" : "!=",
+        left,
+        right,
+        range: this.span(left.range, right.range),
+      };
+    }
+    return left;
+  }
+
+  private parseComparison(): Expr {
+    let left = this.parseUnary();
+    while (
+      this.check("LT") ||
+      this.check("GT") ||
+      this.check("LTE") ||
+      this.check("GTE")
+    ) {
+      const opTok = this.advance();
+      const right = this.parseUnary();
+      const op =
+        opTok.kind === "LT"
+          ? "<"
+          : opTok.kind === "GT"
+            ? ">"
+            : opTok.kind === "LTE"
+              ? "<="
+              : ">=";
+      left = {
+        kind: "binary",
+        op,
+        left,
+        right,
+        range: this.span(left.range, right.range),
+      };
+    }
+    return left;
+  }
+
+  private parseUnary(): Expr {
+    if (this.check("NOT")) {
+      const opTok = this.advance();
+      const operand = this.parseUnary();
+      return {
+        kind: "unary",
+        op: "!",
+        operand,
+        range: this.span(opTok.range, operand.range),
+      };
+    }
+    return this.parsePostfix();
+  }
+
+  private parsePostfix(): Expr {
+    let expr = this.parsePrimary();
+    // Member / index access chain
+    while (this.check("DOT") || this.check("LBRACKET")) {
+      if (this.match("DOT")) {
+        const propTok = this.expect("IDENT");
+        expr = {
+          kind: "member",
+          object: expr,
+          property: propTok.value,
+          range: this.span(expr.range, propTok.range),
+        };
+      } else {
+        this.expect("LBRACKET");
+        const indexExpr = this.parseExpression();
+        const closeTok = this.expect("RBRACKET");
+        expr = {
+          kind: "index",
+          object: expr,
+          index: indexExpr,
+          range: this.span(expr.range, closeTok.range),
+        };
+      }
+    }
+    return expr;
+  }
+
+  private parsePrimary(): Expr {
+    const t = this.peek();
+    if (t.kind === "NUMBER") {
+      this.advance();
+      return { kind: "literal", value: Number(t.value), range: t.range };
+    }
+    if (t.kind === "STRING") {
+      this.advance();
+      return { kind: "literal", value: t.value, range: t.range };
+    }
+    if (t.kind === "TRUE") {
+      this.advance();
+      return { kind: "literal", value: true, range: t.range };
+    }
+    if (t.kind === "FALSE") {
+      this.advance();
+      return { kind: "literal", value: false, range: t.range };
+    }
+    if (t.kind === "NULL") {
+      this.advance();
+      return { kind: "literal", value: null, range: t.range };
+    }
+    if (t.kind === "IDENT") {
+      this.advance();
+      return { kind: "identifier", name: t.value, range: t.range };
+    }
+    if (t.kind === "LPAREN") {
+      this.advance();
+      const inner = this.parseExpression();
+      this.expect("RPAREN");
+      return inner;
+    }
+    throw new TemplateParseError({
+      message: `Unexpected token ${t.kind} (${t.value || "EOF"}) in expression`,
+      source: this.source,
+      range: t.range.start.line === 0 ? pointRange(t.range.start) : t.range,
+    });
+  }
+
+  // ─── Token utilities ─────────────────────────────────────────────────────
+
+  private peek(): Token {
+    return this.tokens[this.pos]!;
+  }
+
+  private advance(): Token {
+    const t = this.tokens[this.pos]!;
+    this.pos += 1;
+    return t;
+  }
+
+  private check(kind: TokenKind): boolean {
+    return this.peek().kind === kind;
+  }
+
+  private match(kind: TokenKind): boolean {
+    if (this.check(kind)) {
+      this.advance();
+      return true;
+    }
+    return false;
+  }
+
+  expect(kind: TokenKind): Token {
+    const t = this.peek();
+    if (t.kind !== kind) {
+      throw new TemplateParseError({
+        message: `Expected ${kind} but found ${t.kind}`,
+        source: this.source,
+        range: t.range,
+      });
+    }
+    return this.advance();
+  }
+
+  private eof(): boolean {
+    return this.peek().kind === "EOF";
+  }
+
+  private span(a: SourceRange, b: SourceRange): SourceRange {
+    return { start: a.start, end: b.end };
+  }
+}