@omg-dev/server 0.4.24

package/src/predicate.ts

@@ -0,0 +1,440 @@
+// ── Predicate engine ─────────────────────────────────────────────────────────
+//
+// A small JSON predicate AST that compiles to BOTH a parameterized SQL WHERE
+// clause and an equivalent in-memory JS row matcher. The duality is the
+// load-bearing piece: subscribers send a JSON predicate to narrow their
+// initial snapshot (SQL path), and the same compiled JS function decides
+// on every write whether a changed row enters or leaves their result set
+// (used in Phase 3 for delta computation).
+//
+// Wire format is deliberately small — every operator widens the surface
+// for predicate-translation bugs and the SQLite/JS semantics that differ
+// between them (collation, NULL behavior, type coercion). Adding new
+// operators is fine; doing so loosely is not. Each operator's SQL and JS
+// emitters are tested side-by-side against the same random rows in
+// predicate.test.ts to keep them honest.
+//
+// Column names go through IDENTIFIER_RE before they reach the SQL emitter
+// so the WHERE clause stays interpolation-safe. Values are always bound as
+// parameters — never string-concatenated.
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export type Literal = string | number | boolean | null
+
+export type Predicate =
+  | { op: "and"; clauses: Predicate[] }
+  | { op: "or"; clauses: Predicate[] }
+  | { op: "not"; clause: Predicate }
+  | { op: "eq"; column: string; value: Literal }
+  | { op: "ne"; column: string; value: Literal }
+  | { op: "gt"; column: string; value: number | string }
+  | { op: "gte"; column: string; value: number | string }
+  | { op: "lt"; column: string; value: number | string }
+  | { op: "lte"; column: string; value: number | string }
+  | { op: "in"; column: string; values: Literal[] }
+  | { op: "like"; column: string; pattern: string }
+  | { op: "isNull"; column: string }
+  | { op: "isNotNull"; column: string }
+
+export class PredicateValidationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "PredicateValidationError"
+  }
+}
+
+const IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/
+
+// Bound a malicious / accidental client from sending pathological trees.
+// These are deliberately small — the predicate engine is meant for filter
+// expressions that fit on a screen, not arbitrary query plans.
+const MAX_DEPTH = 32
+const MAX_CLAUSES = 256
+
+// ── Validation ───────────────────────────────────────────────────────────────
+
+export function validatePredicate(node: unknown): asserts node is Predicate {
+  validateAtDepth(node, 0)
+}
+
+function validateAtDepth(node: unknown, depth: number): asserts node is Predicate {
+  if (depth > MAX_DEPTH) {
+    throw new PredicateValidationError(`predicate nested too deep (>${MAX_DEPTH})`)
+  }
+  if (!node || typeof node !== "object" || Array.isArray(node)) {
+    throw new PredicateValidationError("predicate must be an object")
+  }
+  const n = node as { op: unknown }
+  if (typeof n.op !== "string") {
+    throw new PredicateValidationError("predicate missing 'op'")
+  }
+
+  switch (n.op) {
+    case "and":
+    case "or": {
+      const m = n as unknown as { clauses?: unknown }
+      if (!Array.isArray(m.clauses)) {
+        throw new PredicateValidationError(`'${n.op}' requires 'clauses' array`)
+      }
+      if (m.clauses.length === 0) {
+        throw new PredicateValidationError(`'${n.op}' requires at least one clause`)
+      }
+      if (m.clauses.length > MAX_CLAUSES) {
+        throw new PredicateValidationError(`'${n.op}' has too many clauses (>${MAX_CLAUSES})`)
+      }
+      for (const c of m.clauses) validateAtDepth(c, depth + 1)
+      return
+    }
+    case "not": {
+      const m = n as unknown as { clause?: unknown }
+      validateAtDepth(m.clause, depth + 1)
+      return
+    }
+    case "eq":
+    case "ne": {
+      const m = n as unknown as { column?: unknown; value?: unknown }
+      requireColumn(m.column)
+      requireLiteral(m.value)
+      return
+    }
+    case "gt":
+    case "gte":
+    case "lt":
+    case "lte": {
+      const m = n as unknown as { column?: unknown; value?: unknown }
+      requireColumn(m.column)
+      // Ordering operators reject booleans and null — those have no
+      // meaningful ordering in either SQLite or JS.
+      const v = m.value
+      if (v === null || typeof v === "boolean") {
+        throw new PredicateValidationError(`'${n.op}' value must be number or string, got ${v === null ? "null" : "boolean"}`)
+      }
+      if (typeof v !== "number" && typeof v !== "string") {
+        throw new PredicateValidationError(`'${n.op}' value must be number or string`)
+      }
+      if (typeof v === "number" && !Number.isFinite(v)) {
+        throw new PredicateValidationError(`'${n.op}' value must be a finite number`)
+      }
+      return
+    }
+    case "in": {
+      const m = n as unknown as { column?: unknown; values?: unknown }
+      requireColumn(m.column)
+      if (!Array.isArray(m.values)) {
+        throw new PredicateValidationError("'in' requires 'values' array")
+      }
+      if (m.values.length === 0) {
+        throw new PredicateValidationError("'in' values must be non-empty")
+      }
+      if (m.values.length > MAX_CLAUSES) {
+        throw new PredicateValidationError(`'in' has too many values (>${MAX_CLAUSES})`)
+      }
+      for (const v of m.values) requireLiteral(v)
+      return
+    }
+    case "like": {
+      const m = n as unknown as { column?: unknown; pattern?: unknown }
+      requireColumn(m.column)
+      if (typeof m.pattern !== "string") {
+        throw new PredicateValidationError("'like' requires string 'pattern'")
+      }
+      return
+    }
+    case "isNull":
+    case "isNotNull": {
+      const m = n as unknown as { column?: unknown }
+      requireColumn(m.column)
+      return
+    }
+    default:
+      throw new PredicateValidationError(`unknown op: ${String(n.op)}`)
+  }
+}
+
+function requireColumn(c: unknown): asserts c is string {
+  if (typeof c !== "string" || !IDENTIFIER_RE.test(c)) {
+    throw new PredicateValidationError(`invalid column: ${String(c)}`)
+  }
+}
+
+function requireLiteral(v: unknown): asserts v is Literal {
+  if (v === null) return
+  const t = typeof v
+  if (t !== "string" && t !== "number" && t !== "boolean") {
+    throw new PredicateValidationError(`unsupported literal: ${t}`)
+  }
+  if (t === "number" && !Number.isFinite(v as number)) {
+    throw new PredicateValidationError("non-finite numbers (NaN/Infinity) not allowed")
+  }
+}
+
+// ── SQL emitter ──────────────────────────────────────────────────────────────
+
+export interface CompiledSql {
+  /** Parenthesized SQL fragment safe to AND with other WHERE conditions. */
+  sql: string
+  /** Bound parameters in left-to-right order. */
+  params: unknown[]
+}
+
+export function compileToSql(pred: Predicate): CompiledSql {
+  const params: unknown[] = []
+  const sql = emitSql(pred, params)
+  return { sql, params }
+}
+
+function emitSql(p: Predicate, params: unknown[]): string {
+  switch (p.op) {
+    case "and":
+      return `(${p.clauses.map(c => emitSql(c, params)).join(" AND ")})`
+    case "or":
+      return `(${p.clauses.map(c => emitSql(c, params)).join(" OR ")})`
+    case "not":
+      return `(NOT ${emitSql(p.clause, params)})`
+    case "eq":
+      params.push(encodeLiteral(p.value))
+      return `${p.column} = ?`
+    case "ne":
+      params.push(encodeLiteral(p.value))
+      return `${p.column} != ?`
+    case "gt":
+      params.push(encodeLiteral(p.value))
+      return `${p.column} > ?`
+    case "gte":
+      params.push(encodeLiteral(p.value))
+      return `${p.column} >= ?`
+    case "lt":
+      params.push(encodeLiteral(p.value))
+      return `${p.column} < ?`
+    case "lte":
+      params.push(encodeLiteral(p.value))
+      return `${p.column} <= ?`
+    case "in": {
+      for (const v of p.values) params.push(encodeLiteral(v))
+      return `${p.column} IN (${p.values.map(() => "?").join(", ")})`
+    }
+    case "like":
+      params.push(p.pattern)
+      return `${p.column} LIKE ?`
+    case "isNull":
+      return `${p.column} IS NULL`
+    case "isNotNull":
+      return `${p.column} IS NOT NULL`
+  }
+}
+
+// SQLite stores booleans as INTEGER 0/1 — coerce on the way to a bound param
+// so an `eq done true` predicate hits a `done = 1` row.
+function encodeLiteral(v: Literal): unknown {
+  if (typeof v === "boolean") return v ? 1 : 0
+  return v
+}
+
+// ── JS emitter ───────────────────────────────────────────────────────────────
+//
+// SQLite uses three-valued logic — a comparison involving NULL is UNKNOWN
+// (not FALSE), and AND/OR/NOT propagate UNKNOWN per the SQL truth tables.
+// The top-level WHERE keeps only rows whose result is exactly TRUE, so
+// NOT UNKNOWN excludes a row (it does NOT flip to TRUE the way a naive
+// two-valued NOT would).
+//
+// The JS emitter therefore tracks UNKNOWN as the literal value `null` in
+// an internal TriState evaluator, then collapses to `boolean` at the top.
+// Without this, `NOT (NULL >= 'x')` returns TRUE in JS but UNKNOWN in
+// SQLite — the property test in predicate.test.ts proves the difference.
+
+type TriState = true | false | null
+
+/**
+ * Compile to a row matcher. The row is the *decoded* shape — same flavour
+ * as what auto-crud returns to REST clients (booleans as `true`/`false`,
+ * arrays as JS arrays, etc). Subscribers feed decoded rows in.
+ */
+export function compileToJs(pred: Predicate): (row: Record<string, unknown>) => boolean {
+  const tri = compileToTri(pred)
+  return (row) => tri(row) === true
+}
+
+function compileToTri(pred: Predicate): (row: Record<string, unknown>) => TriState {
+  switch (pred.op) {
+    case "and": {
+      const cs = pred.clauses.map(compileToTri)
+      return (r) => {
+        // SQL AND: any FALSE → FALSE; any UNKNOWN (without FALSE) → UNKNOWN;
+        // all TRUE → TRUE.
+        let seenNull = false
+        for (const c of cs) {
+          const v = c(r)
+          if (v === false) return false
+          if (v === null) seenNull = true
+        }
+        return seenNull ? null : true
+      }
+    }
+    case "or": {
+      const cs = pred.clauses.map(compileToTri)
+      return (r) => {
+        // SQL OR: any TRUE → TRUE; any UNKNOWN (without TRUE) → UNKNOWN;
+        // all FALSE → FALSE.
+        let seenNull = false
+        for (const c of cs) {
+          const v = c(r)
+          if (v === true) return true
+          if (v === null) seenNull = true
+        }
+        return seenNull ? null : false
+      }
+    }
+    case "not": {
+      const c = compileToTri(pred.clause)
+      return (r) => {
+        const v = c(r)
+        if (v === null) return null
+        return !v
+      }
+    }
+    case "eq": {
+      const { column, value } = pred
+      return (r) => {
+        const cv = r[column]
+        if (cv === null || cv === undefined) return null
+        if (value === null) return null
+        return valuesEqual(cv, value)
+      }
+    }
+    case "ne": {
+      const { column, value } = pred
+      return (r) => {
+        const cv = r[column]
+        if (cv === null || cv === undefined) return null
+        if (value === null) return null
+        return !valuesEqual(cv, value)
+      }
+    }
+    case "gt": {
+      const { column, value } = pred
+      return (r) => triCompare(r[column], value, (n) => n > 0)
+    }
+    case "gte": {
+      const { column, value } = pred
+      return (r) => triCompare(r[column], value, (n) => n >= 0)
+    }
+    case "lt": {
+      const { column, value } = pred
+      return (r) => triCompare(r[column], value, (n) => n < 0)
+    }
+    case "lte": {
+      const { column, value } = pred
+      return (r) => triCompare(r[column], value, (n) => n <= 0)
+    }
+    case "in": {
+      const { column, values } = pred
+      return (r) => {
+        const cv = r[column]
+        if (cv === null || cv === undefined) return null
+        // SQL `x IN (..., NULL, ...)` returns TRUE if x equals a non-null
+        // entry, otherwise UNKNOWN if any NULL is in the list, otherwise
+        // FALSE. Mirror that.
+        let seenNull = false
+        for (const x of values) {
+          if (x === null) { seenNull = true; continue }
+          if (valuesEqual(cv, x)) return true
+        }
+        return seenNull ? null : false
+      }
+    }
+    case "like": {
+      const { column, pattern } = pred
+      const re = likeToRegExp(pattern)
+      return (r) => {
+        const cv = r[column]
+        if (cv === null || cv === undefined) return null
+        // Non-string columns under LIKE — SQLite coerces with TEXT
+        // affinity; we stringify for the same effective result.
+        const s = typeof cv === "string" ? cv : String(cv)
+        return re.test(s)
+      }
+    }
+    case "isNull": {
+      const { column } = pred
+      // isNull is total — never UNKNOWN.
+      return (r) => r[column] === null || r[column] === undefined
+    }
+    case "isNotNull": {
+      const { column } = pred
+      return (r) => r[column] !== null && r[column] !== undefined
+    }
+  }
+}
+
+function triCompare(
+  a: unknown,
+  b: number | string,
+  pick: (n: number) => boolean,
+): TriState {
+  if (a === null || a === undefined) return null
+  const n = orderedCompare(a, b)
+  if (Number.isNaN(n)) return null
+  return pick(n)
+}
+
+// ── JS comparison helpers ────────────────────────────────────────────────────
+
+/**
+ * Equality with SQLite-ish semantics:
+ *  - NULL is never equal to anything (including NULL) → false. Use isNull
+ *    if you want NULL matching.
+ *  - boolean ↔ 0/1 matches (so a decoded `true` matches a stored `1` row
+ *    if anyone hands us a raw row by accident).
+ *  - Number/string types compare loosely so an unquoted JSON literal
+ *    matches the matching DB column.
+ */
+function valuesEqual(a: unknown, b: Literal): boolean {
+  if (a === null || a === undefined) return false
+  if (typeof b === "boolean") {
+    if (typeof a === "boolean") return a === b
+    if (typeof a === "number") return (b ? 1 : 0) === a
+    return false
+  }
+  if (b === null) return false
+  // string-string and number-number are strict.
+  if (typeof a === typeof b) return a === b
+  // Mixed-type compare: stringify both sides, mirroring SQLite's TEXT
+  // affinity behaviour for `=` between INTEGER and TEXT.
+  return String(a) === String(b)
+}
+
+/**
+ * Returns -1 / 0 / +1, or NaN if either side is null/undefined or types
+ * don't permit ordering. Callers treat NaN as "predicate false" — same as
+ * SQL where any comparison involving NULL yields UNKNOWN.
+ */
+function orderedCompare(a: unknown, b: number | string): number {
+  if (a === null || a === undefined) return NaN
+  if (typeof b === "number") {
+    const av = typeof a === "number" ? a : Number(a)
+    if (!Number.isFinite(av)) return NaN
+    return av < b ? -1 : av > b ? 1 : 0
+  }
+  // string ordering — lexicographic, matching SQLite's BINARY collation.
+  const as = typeof a === "string" ? a : String(a)
+  return as < b ? -1 : as > b ? 1 : 0
+}
+
+/**
+ * Translate a SQL LIKE pattern to a JS RegExp. SQLite LIKE is
+ * case-insensitive for ASCII by default — we mirror that with the `i` flag.
+ * `%` matches any run of characters; `_` matches exactly one. No escape
+ * handling yet — adding `ESCAPE '\\'` is a Phase 6 concern.
+ */
+function likeToRegExp(pattern: string): RegExp {
+  let re = "^"
+  for (const ch of pattern) {
+    if (ch === "%") re += ".*"
+    else if (ch === "_") re += "."
+    else re += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  }
+  re += "$"
+  return new RegExp(re, "i")
+}