@jarenjs/db 0.34.0

package/src/emit.js

@@ -0,0 +1,393 @@
+//@ts-check
+/**
+ * @file Plan → SQL through a dialect. This is the query layer's shared
+ * emitter, the same division of labour as `createDialect`'s DDL/DML
+ * builders: structural SQL composition lives here, every
+ * dialect-varying spelling (identifiers, parameters, string literals,
+ * JSON access, `json_type`, `typeof`, string-operator forms, NULLS
+ * placement, EXPLAIN phrasing) comes from the dialect. Values are
+ * NEVER interpolated into the text: every literal and every external
+ * becomes an ordered parameter slot, which is what makes injection
+ * structurally impossible.
+ *
+ * Every emitted predicate is TOTAL (two-valued) by construction — the
+ * `json_type` guards from the truth table in ARCHITECTURE.md — so
+ * `NOT`/`AND`/`OR` compose classically and SQL's three-valued NULL
+ * logic never decides a row.
+ */
+
+/**
+ * @typedef {{ external: string } | { literal: unknown }} ParamSlot
+ */
+
+/**
+ * Emit one plan as SQL plus its ordered parameter slots.
+ * @param {import('./algebra.js').Plan} plan
+ * @param {any} dialect
+ * @param {{ table: string, keyColumn: string, docColumn: string }} physical
+ * @returns {{ sql: string, slots: ParamSlot[] }}
+ */
+export function emitPlan(plan, dialect, physical) {
+  const q = dialect.quoteIdentifier;
+  const docColumn = q(physical.docColumn);
+  /** @type {ParamSlot[]} */
+  const slots = [];
+  const param = (slot) => {
+    slots.push(slot);
+    return dialect.parameterRef(slots.length, 'external' in slot ? slot.external : 'value');
+  };
+
+  /** SQL for a ref's VALUE: the generated column when one exists. */
+  const valueOf = (ref) =>
+    (ref.column !== null ? q(ref.column) : dialect.jsonExtract(docColumn, pathTextOf(ref)));
+  const pathTextOf = (ref) => {
+    const text = dialect.jsonPathText(ref.segments);
+    if (text === null) {
+      // the planner never promotes an unrepresentable path; reaching
+      // this is an internal inconsistency, not a user error
+      throw new Error('emit: a promoted path is not representable in the dialect JSON path grammar');
+    }
+    return text;
+  };
+  /** The presence/type discriminator, always over the document column. */
+  const typeOf = (ref) => dialect.jsonTypeOf(docColumn, pathTextOf(ref));
+
+  const sl = dialect.stringLiteral;
+  const NUMERIC = () => `(${sl('integer')}, ${sl('real')})`;
+
+  /**
+   * The guarded, total comparison forms of the truth table.
+   * @param {any} pred
+   * @returns {string}
+   */
+  const emitCmp = (pred) => {
+    const jt = typeOf(pred.ref);
+    const value = valueOf(pred.ref);
+    const symbol = { eq: '=', ne: '<>', lt: '<', le: '<=', gt: '>', ge: '>=' }[pred.op];
+    if ('lit' in pred.operand) {
+      const lit = pred.operand.lit;
+      const kind = typeof lit === 'number' ? 'number' : 'string';
+      const typeGuard = kind === 'number'
+        ? `${jt} IN ${NUMERIC()}`
+        : `${jt} = ${sl('text')}`;
+      if (pred.op === 'ne') {
+        // present AND (other type OR value differs): cross-type ne is
+        // true for a PRESENT value, false for a missing one
+        const notType = kind === 'number'
+          ? `${jt} NOT IN ${NUMERIC()}`
+          : `${jt} <> ${sl('text')}`;
+        return `(${jt} IS NOT NULL AND (${notType} OR ${value} <> ${param({ literal: lit })}))`;
+      }
+      // the presence prefix keeps the form TOTAL: `NULL IN (...)` is
+      // NULL, and a NULL escaping through a NOT flips a row's fate
+      return `(${jt} IS NOT NULL AND ${typeGuard} AND ${value} ${symbol} ${param({ literal: lit })})`;
+    }
+    // external operand: its JSON type is only knowable at bind time —
+    // guard BOTH sides per branch (text with text, number with number)
+    const name = pred.operand.ext;
+    const textBranch = `(${jt} IS NOT NULL AND ${jt} = ${sl('text')} AND `
+      + `${dialect.valueTypeOf(param({ external: name }))} = ${sl('text')} AND `
+      + `${value} ${pred.op === 'ne' ? '=' : symbol} ${param({ external: name })})`;
+    const numberBranch = `(${jt} IS NOT NULL AND ${jt} IN ${NUMERIC()} AND `
+      + `${dialect.valueTypeOf(param({ external: name }))} IN ${NUMERIC()} AND `
+      + `${value} ${pred.op === 'ne' ? '=' : symbol} ${param({ external: name })})`;
+    const equalInSomeBranch = `(${textBranch} OR ${numberBranch})`;
+    return pred.op === 'ne'
+      ? `(${jt} IS NOT NULL AND NOT ${equalInSomeBranch})`
+      : equalInSomeBranch;
+  };
+
+  /**
+   * @param {import('./algebra.js').PlanPredicate} pred
+   * @returns {string}
+   */
+  const emitPred = (pred) => {
+    switch (pred.p) {
+      case 'and':
+        return `(${pred.items.map(emitPred).join(' AND ')})`;
+      case 'or':
+        return `(${pred.items.map(emitPred).join(' OR ')})`;
+      case 'not':
+        return `NOT ${emitPred(pred.item)}`;
+      case 'const':
+        return pred.value ? dialect.booleanLiteral(true) : dialect.booleanLiteral(false);
+      case 'cmp':
+        return emitCmp(pred);
+      case 'typeIs': {
+        const jt = typeOf(pred.ref);
+        if (pred.types.length === 0) {
+          // bare existence: positive is $exists, negative is $empty
+          return pred.positive ? `${jt} IS NOT NULL` : `${jt} IS NULL`;
+        }
+        const list = pred.types.map(sl).join(', ');
+        return pred.positive
+          ? (pred.types.length === 1
+            ? `(${jt} IS NOT NULL AND ${jt} = ${sl(pred.types[0])})`
+            : `(${jt} IS NOT NULL AND ${jt} IN (${list}))`)
+          : `(${jt} IS NOT NULL AND ${jt} NOT IN (${list}))`;
+      }
+      case 'udf':
+        // the registered deterministic predicate: reads the row's
+        // document as JSON text, answers 1 or 0 (always total)
+        return `${pred.name}(${dialect.jsonText(docColumn)})`;
+      case 'strop': {
+        const jt = typeOf(pred.ref);
+        const value = valueOf(pred.ref);
+        const bind = () => param({ literal: /** @type {any} */ (pred.operand).lit });
+        const form = pred.kind === 'starts'
+          ? dialect.strStartsWith(value, bind(), bind())
+          : pred.kind === 'ends'
+            ? dialect.strEndsWith(value, bind(), bind(), bind())
+            : dialect.strContains(value, bind());
+        return `(${jt} IS NOT NULL AND ${jt} = ${sl('text')} AND ${form})`;
+      }
+      default:
+        throw new Error(`emit: unknown predicate node '${/** @type {any} */ (pred).p}'`);
+    }
+  };
+
+  const selection = plan.aggregate === null
+    ? `${dialect.jsonText(docColumn)} AS ${q('doc')}`
+    : plan.aggregate.fn === 'count'
+      ? `COUNT(*) AS ${q('value')}`
+      : `${plan.aggregate.fn.toUpperCase()}(${valueOf(plan.aggregate.ref)}) AS ${q('value')}`;
+
+  let sql = `SELECT ${selection} FROM ${q(physical.table)}`;
+  if (plan.filter !== null) sql += ` WHERE ${emitPred(plan.filter)}`;
+  if (plan.aggregate === null) {
+    const terms = (plan.order ?? []).map((term) => {
+      // Jaren's default sorts an empty key least: NULLS FIRST when
+      // ascending, NULLS LAST when descending — and mirrored for
+      // $empty: 'greatest' (probed against the engine)
+      const nullsFirst = term.emptyGreatest === term.desc;
+      return `${valueOf(term.ref)} ${term.desc ? 'DESC' : 'ASC'}${dialect.orderNulls(nullsFirst)}`;
+    });
+    // the collection is a SEQUENCE: its order is insertion (row
+    // identity) order, and the engine's sort is stable — the identity
+    // tiebreaker reproduces both, and without it the database is free
+    // to answer in index order
+    terms.push(dialect.rowIdentity());
+    sql += ` ORDER BY ${terms.join(', ')}`;
+  }
+  if (plan.window !== null && plan.aggregate === null) {
+    sql += ` ${dialect.limitClause(plan.window.limit, plan.window.offset)}`;
+  }
+  return { sql, slots };
+}
+
+// ————— The entity document kind (one emitter layer, two kinds) —————
+
+/**
+ * The entity predicate emitters, shared by the entity plan emitter
+ * and the graph-load builder: given an alias and its document column,
+ * emit one predicate with the flavor-correct forms.
+ * @param {any} dialect
+ * @param {(slot: ParamSlot) => string} param
+ * @returns {{ emitPred: (aliasSql: string, docSql: string, pred: any) => string }}
+ */
+export function createEntityPredicateEmitters(dialect, param) {
+  const q = dialect.quoteIdentifier;
+  const sl = dialect.stringLiteral;
+  const NUMERIC = () => `(${sl('integer')}, ${sl('real')})`;
+  const pathTextOf = (ref) => {
+    const text = dialect.jsonPathText(ref.segments);
+    if (text === null)
+      throw new Error('emit: a promoted entity path is not representable');
+    return text;
+  };
+
+  const emitDocPred = (docSql, pred) => {
+    const jt = dialect.jsonTypeOf(docSql, pathTextOf(pred.ref));
+    const value = dialect.jsonExtract(docSql, pathTextOf(pred.ref));
+    if (pred.p === 'typeIs') {
+      if (pred.types.length === 0)
+        return pred.positive ? `${jt} IS NOT NULL` : `${jt} IS NULL`;
+      const list = pred.types.map(sl).join(', ');
+      return pred.positive
+        ? `(${jt} IS NOT NULL AND ${pred.types.length === 1
+          ? `${jt} = ${sl(pred.types[0])}` : `${jt} IN (${list})`})`
+        : `(${jt} IS NOT NULL AND ${jt} NOT IN (${list}))`;
+    }
+    if (pred.p === 'strop') {
+      const bind = () => param({ literal: pred.operand.lit });
+      const form = pred.kind === 'starts'
+        ? dialect.strStartsWith(value, bind(), bind())
+        : pred.kind === 'ends'
+          ? dialect.strEndsWith(value, bind(), bind(), bind())
+          : dialect.strContains(value, bind());
+      return `(${jt} IS NOT NULL AND ${jt} = ${sl('text')} AND ${form})`;
+    }
+    const lit = pred.operand.lit;
+    const symbol = { eq: '=', ne: '<>', lt: '<', le: '<=', gt: '>', ge: '>=' }[pred.op];
+    const kind = typeof lit === 'number' ? 'number' : 'string';
+    if (pred.op === 'ne') {
+      const notType = kind === 'number'
+        ? `${jt} NOT IN ${NUMERIC()}` : `${jt} <> ${sl('text')}`;
+      return `(${jt} IS NOT NULL AND (${notType} OR ${value} <> ${param({ literal: lit })}))`;
+    }
+    const typeGuard = kind === 'number'
+      ? `${jt} IN ${NUMERIC()}` : `${jt} = ${sl('text')}`;
+    return `(${jt} IS NOT NULL AND ${typeGuard} AND ${value} ${symbol} ${param({ literal: lit })})`;
+  };
+
+  const emitColumnPred = (aliasSql, pred) => {
+    const column = `${aliasSql}.${q(pred.ref.column)}`;
+    if (pred.p === 'typeIs') {
+      if (pred.types.length === 0)
+        return pred.positive ? `${column} IS NOT NULL` : `${column} IS NULL`;
+      if (pred.types[0] === 'null')
+        return pred.positive ? dialect.booleanLiteral(false) : `${column} IS NOT NULL`;
+      const wanted = pred.types[0] === 'true' ? 1 : 0;
+      return pred.positive
+        ? `(${column} IS NOT NULL AND ${column} = ${param({ literal: wanted })})`
+        : `(${column} IS NOT NULL AND ${column} <> ${param({ literal: wanted })})`;
+    }
+    if (pred.p === 'strop') {
+      const bind = () => param({ literal: pred.operand.lit });
+      const form = pred.kind === 'starts'
+        ? dialect.strStartsWith(column, bind(), bind())
+        : pred.kind === 'ends'
+          ? dialect.strEndsWith(column, bind(), bind(), bind())
+          : dialect.strContains(column, bind());
+      return `(${column} IS NOT NULL AND ${form})`;
+    }
+    const symbol = { eq: '=', ne: '<>', lt: '<', le: '<=', gt: '>', ge: '>=' }[pred.op];
+    if ('ext' in pred.operand) {
+      const guard = pred.ref.storage === 'string'
+        ? `${dialect.valueTypeOf(param({ external: pred.operand.ext }))} = ${sl('text')}`
+        : `${dialect.valueTypeOf(param({ external: pred.operand.ext }))} IN ${NUMERIC()}`;
+      return `(${column} IS NOT NULL AND ${guard} AND ${column} ${pred.op === 'ne' ? '<>' : symbol} ${param({ external: pred.operand.ext })})`;
+    }
+    const lit = pred.operand.lit;
+    const litKind = typeof lit === 'number' ? 'number' : typeof lit === 'string' ? 'string' : 'other';
+    const storageKind = pred.ref.storage === 'string' ? 'string'
+      : pred.ref.storage === 'boolean' ? 'boolean' : 'number';
+    if (storageKind === 'boolean' || litKind === 'other' || storageKind !== litKind)
+      return pred.op === 'ne' ? `${column} IS NOT NULL` : dialect.booleanLiteral(false);
+    return `(${column} IS NOT NULL AND ${column} ${symbol} ${param({ literal: lit })})`;
+  };
+
+  // an epoch comparison: the derived integer column narrows through
+  // its index with ±1s slack (Z-normalized strings sharing a second
+  // prefix sit within one second, so the range is a superset of the
+  // codepoint comparison), and the document string decides exactly —
+  // the engine's lexicographic semantics, whatever precision the
+  // stored values carry
+  const emitEpochPred = (aliasSql, docSql, pred) => {
+    const column = `${aliasSql}.${q(pred.ref.column)}`;
+    const value = dialect.jsonExtract(docSql, pathTextOf(pred.ref));
+    const symbol = { eq: '=', lt: '<', le: '<=', gt: '>', ge: '>=' }[pred.op];
+    const range = pred.op === 'gt' || pred.op === 'ge'
+      ? `${column} >= ${param({ literal: pred.epoch - 1000 })}`
+      : pred.op === 'lt' || pred.op === 'le'
+        ? `${column} <= ${param({ literal: pred.epoch + 1000 })}`
+        : `${column} >= ${param({ literal: pred.epoch - 1000 })} AND ${column} <= ${param({ literal: pred.epoch + 1000 })}`;
+    return `(${column} IS NOT NULL AND ${range} AND ${value} ${symbol} ${param({ literal: pred.operand.lit })})`;
+  };
+
+  const emitPred = (aliasSql, docSql, pred) => {
+    if (pred.p === 'and')
+      return `(${pred.items.map((item) => emitPred(aliasSql, docSql, item)).join(' AND ')})`;
+    if (pred.p === 'or')
+      return `(${pred.items.map((item) => emitPred(aliasSql, docSql, item)).join(' OR ')})`;
+    if (pred.p === 'not') return `NOT ${emitPred(aliasSql, docSql, pred.item)}`;
+    if (pred.p === 'const')
+      return pred.value ? dialect.booleanLiteral(true) : dialect.booleanLiteral(false);
+    if (pred.ref?.flavor === 'entity-column')
+      return emitColumnPred(aliasSql, pred);
+    if (pred.ref?.flavor === 'entity-epoch') {
+      // only an instant comparison uses the column; presence, type
+      // tests, string operators and non-instant literals ride the
+      // guarded document forms, which stay sound for any stored value
+      if (pred.p === 'cmp' && 'epoch' in pred)
+        return emitEpochPred(aliasSql, docSql, pred);
+      return emitDocPred(docSql, pred);
+    }
+    return emitDocPred(docSql, pred);
+  };
+  return { emitPred };
+}
+
+/**
+ * Emit an entity plan (`entity-select` or `entity-join`) as SQL plus
+ * ordered parameter slots. Entity-COLUMN refs compare real typed
+ * columns with TOTAL forms and no `json_type` guard — a column-mapped
+ * property has no present-`null` (§9.3), so presence IS `IS NOT
+ * NULL`; entity-EPOCH refs compare the derived integer column against
+ * a plan-time epoch translation; entity-DOC refs ride the phase-A
+ * guarded truth table over the entity's JSONB column. Join emission
+ * appends BOTH bindings' row identities in binding order, which is
+ * exactly the engine's nested-loop order — determinism the oracle
+ * depends on.
+ * @param {any} plan - from `planEntityQuery`
+ * @param {any} dialect
+ * @param {(entity: string) => { table: string }} physicalOf
+ * @returns {{ sql: string, slots: ParamSlot[] }}
+ */
+export function emitEntityPlan(plan, dialect, physicalOf) {
+  const q = dialect.quoteIdentifier;
+  /** @type {ParamSlot[]} */
+  const slots = [];
+  const param = (slot) => {
+    slots.push(slot);
+    return dialect.parameterRef(slots.length, 'external' in slot ? slot.external : 'value');
+  };
+
+  const aliases = new Map(plan.bindings.map((binding, i) => [
+    binding.name, { alias: q(`t${i}`), entity: binding.entity },
+  ]));
+  const aliasOf = (bindingName) => aliases.get(bindingName).alias;
+  const docOf = (bindingName) => `${aliasOf(bindingName)}.${q('doc')}`;
+
+  const pathTextOf = (ref) => {
+    const text = dialect.jsonPathText(ref.segments);
+    if (text === null)
+      throw new Error('emit: a promoted entity path is not representable');
+    return text;
+  };
+
+  const emitters = createEntityPredicateEmitters(dialect, param);
+  const emitPred = (bindingName, pred) =>
+    emitters.emitPred(aliasOf(bindingName), docOf(bindingName), pred);
+
+  const ret = plan.ret;
+  // every returned column plus the document rendered to text; the
+  // caller merges them back into the entity shape
+  const selection = plan.aggregate === 'count'
+    ? `COUNT(*) AS ${q('value')}`
+    : `${aliasOf(ret)}.*, ${dialect.jsonText(docOf(ret))} AS ${q('__doc')}`;
+
+  let sql = `SELECT ${selection} FROM `;
+  sql += plan.bindings
+    .map((binding) => `${q(physicalOf(binding.entity).table)} AS ${aliasOf(binding.name)}`)
+    .join(' JOIN ');
+  if (plan.joinOn !== null) {
+    sql += ` ON ${aliasOf(plan.joinOn.left.binding)}.${q(plan.joinOn.left.column)}`
+      + ` = ${aliasOf(plan.joinOn.right.binding)}.${q(plan.joinOn.right.column)}`;
+  }
+  const filterSql = plan.filters
+    .filter((entry) => entry.filter !== null)
+    .map((entry) => emitPred(entry.binding, entry.filter));
+  if (filterSql.length > 0) sql += ` WHERE ${filterSql.join(' AND ')}`;
+
+  if (plan.aggregate === null) {
+    const terms = (plan.order ?? []).map((term) => {
+      // only a plain mapped column orders by its column; an epoch
+      // path orders by the document string — codepoint order, exactly
+      // the engine's — because mixed stored precisions would let the
+      // integer column sort differently
+      const value = term.ref.flavor === 'entity-column'
+        ? `${aliasOf(term.binding)}.${q(term.ref.column)}`
+        : dialect.jsonExtract(docOf(term.binding), pathTextOf(term.ref));
+      const nullsFirst = term.emptyGreatest === term.desc;
+      return `${value} ${term.desc ? 'DESC' : 'ASC'}${dialect.orderNulls(nullsFirst)}`;
+    });
+    // the engine's nested-loop order: binding-order row identities
+    for (const binding of plan.bindings)
+      terms.push(`${aliasOf(binding.name)}.${dialect.rowIdentity()}`);
+    sql += ` ORDER BY ${terms.join(', ')}`;
+    if (plan.window !== null)
+      sql += ` ${dialect.limitClause(plan.window.limit, plan.window.offset)}`;
+  }
+  return { sql, slots };
+}