@telorun/templating 0.4.1 → 0.6.0

package/src/engines/cel.ts

@@ -4,7 +4,49 @@ import {
   validateChainAgainstSchema,
 } from "../cel/analyze.js";
 import { compileExpression } from "../cel/compile.js";
-import type { EngineDiagnostic, TemplatingEngine } from "../engine.js";
+import type { AnalyzeEnv, EngineDiagnostic, TemplatingEngine } from "../engine.js";
+
+/** Statically analyze one CEL expression against the effective context schema:
+ *  parse → extract member-access chains → validate each chain → flag nullable
+ *  access. Single source of truth shared by the `!cel` engine (one expression)
+ *  and the `!sql` engine (one per `${{ }}` interpolation), so diagnostic wording
+ *  can't drift between them. */
+export function analyzeCelExpression(source: string, env: AnalyzeEnv): EngineDiagnostic[] {
+  const out: EngineDiagnostic[] = [];
+
+  let parsed: ReturnType<typeof env.celEnv.parse>;
+  try {
+    parsed = env.celEnv.parse(source);
+  } catch (e) {
+    out.push({
+      code: "CEL_SYNTAX_ERROR",
+      message: e instanceof Error ? e.message : String(e),
+    });
+    return out;
+  }
+
+  if (!env.contextSchema) return out;
+
+  const chains = extractAccessChains(parsed.ast);
+  for (const chain of chains) {
+    const err = validateChainAgainstSchema(chain, env.contextSchema as Record<string, any>);
+    if (err) out.push({ code: "CEL_UNKNOWN_FIELD", message: err });
+  }
+
+  for (const issue of findNullableAccessIssues(
+    parsed.ast,
+    env.contextSchema as Record<string, any>,
+  )) {
+    // Index access (member "[index]") attaches without a dot; a named field
+    // attaches with one — so the suggested CEL stays valid either way.
+    const access = issue.member === "[index]" ? issue.member : `.${issue.member}`;
+    out.push({
+      code: "CEL_NULLABLE_ACCESS",
+      message: `'${issue.path}' may be null — guard it (e.g. '${issue.path} != null && …' or '${issue.path} == null ? … : ${issue.path}${access}') before accessing '${access}'`,
+    });
+  }
+  return out;
+}
 
 /** The `!cel` engine. Treats the entire tagged scalar as a single CEL
  *  expression — no `${{ }}` wrapping. Analysis runs the same chain validator
@@ -19,39 +61,6 @@ export const celEngine: TemplatingEngine = {
   },
 
   analyze(source, env) {
-    const out: EngineDiagnostic[] = [];
-
-    let parsed: ReturnType<typeof env.celEnv.parse>;
-    try {
-      parsed = env.celEnv.parse(source);
-    } catch (e) {
-      out.push({
-        code: "CEL_SYNTAX_ERROR",
-        message: e instanceof Error ? e.message : String(e),
-      });
-      return out;
-    }
-
-    if (!env.contextSchema) return out;
-
-    const chains = extractAccessChains(parsed.ast);
-    for (const chain of chains) {
-      const err = validateChainAgainstSchema(chain, env.contextSchema as Record<string, any>);
-      if (err) out.push({ code: "CEL_UNKNOWN_FIELD", message: err });
-    }
-
-    for (const issue of findNullableAccessIssues(
-      parsed.ast,
-      env.contextSchema as Record<string, any>,
-    )) {
-      // Index access (member "[index]") attaches without a dot; a named field
-      // attaches with one — so the suggested CEL stays valid either way.
-      const access = issue.member === "[index]" ? issue.member : `.${issue.member}`;
-      out.push({
-        code: "CEL_NULLABLE_ACCESS",
-        message: `'${issue.path}' may be null — guard it (e.g. '${issue.path} != null && …' or '${issue.path} == null ? … : ${issue.path}${access}') before accessing '${access}'`,
-      });
-    }
-    return out;
+    return analyzeCelExpression(source, env);
   },
 };

package/src/engines/sql.ts

@@ -0,0 +1,44 @@
+import { isParameterizedSql, type CompiledValue, type ParameterizedSql } from "@telorun/sdk";
+import { analyzeCelExpression } from "./cel.js";
+import { compileString, toParameterized, TEMPLATE_REGEX } from "../cel/compile.js";
+import type { TemplatingEngine } from "../engine.js";
+
+export { isParameterizedSql, type ParameterizedSql };
+
+/** The `!sql` engine. Treats the tagged scalar as a SQL string with `${{ }}`
+ *  interpolations whose values are *bound*, not spliced. Unlike `!cel` (one bare
+ *  expression) it keeps the literal text and each interpolation separate: at
+ *  runtime `call()` returns a {@link ParameterizedSql} the consumer turns into a
+ *  parameterized query. Generic expansion passes that object through untouched
+ *  (it is the `call()` result), so it survives the step-level input expansion. */
+export const sqlEngine: TemplatingEngine = {
+  name: "sql",
+  language: "sql",
+
+  compile(source, env) {
+    const inner = compileString(source, env.celEnv);
+    return {
+      __compiled: true,
+      source,
+      call: (ctx: Record<string, unknown>): ParameterizedSql => {
+        const { fragments, values } = toParameterized(inner, ctx);
+        return { __teloParameterized: true, fragments, values };
+      },
+    } satisfies CompiledValue;
+  },
+
+  analyze(source, env) {
+    // Each `${{ }}` interpolation is its own CEL expression; reuse the shared
+    // per-expression analyzer so diagnostics match the `!cel` engine exactly.
+    return expressionsOf(source).flatMap((expr) => analyzeCelExpression(expr, env));
+  },
+};
+
+/** Extract each `${{ expr }}` body from a `!sql` template source. */
+function expressionsOf(source: string): string[] {
+  const exprs: string[] = [];
+  for (const m of source.matchAll(TEMPLATE_REGEX)) {
+    exprs.push(m[1]!.trim());
+  }
+  return exprs;
+}

package/src/index.ts

@@ -1,7 +1,15 @@
 export { buildCelEnvironment, type CelHandlers } from "./cel/environment.js";
+export {
+  celFunctionCatalog,
+  CEL_FUNCTIONS,
+  type CelFunctionInfo,
+  type CelFunctionDoc,
+  type CelFunctionCategory,
+} from "./cel/catalog.js";
 export {
   compileExpression,
   compileString,
+  toParameterized,
   TEMPLATE_REGEX,
   EXACT_TEMPLATE_REGEX,
 } from "./cel/compile.js";
@@ -16,6 +24,7 @@ export { walkCelExpressions } from "./cel/walk.js";
 export { celEngine } from "./engines/cel.js";
 export { literalEngine } from "./engines/literal.js";
 export { refEngine } from "./engines/ref.js";
+export { sqlEngine, isParameterizedSql, type ParameterizedSql } from "./engines/sql.js";
 
 export { TemplatingEngineRegistry } from "./registry.js";
 export { builtinEngines, createDefaultRegistry, defaultRegistry } from "./builtins.js";