@spooky-sync/core 0.0.1-canary.33 → 0.0.1-canary.331

package/src/services/database/plan-render.test.ts

@@ -0,0 +1,159 @@
+import { describe, it, expect } from 'vitest';
+import type { QueryPlan } from '@spooky-sync/query-builder';
+import { renderBaseSelectSurql, renderRelationFetchSurql } from './plan-render';
+import { buildWindowMaterializationPlan } from '../../query/window-query';
+
+describe('renderBaseSelectSurql', () => {
+  it('renders projection, where, order, limit, offset', () => {
+    const plan: QueryPlan = {
+      table: 'post',
+      select: ['title', 'body'],
+      where: [{ field: 'published', op: '=', value: true }],
+      orderBy: [['created', 'desc']],
+      limit: 10,
+      offset: 20,
+    };
+    const { sql, vars } = renderBaseSelectSurql(plan);
+    expect(sql).toBe('SELECT title, body FROM post WHERE published = $__p0 ORDER BY created desc LIMIT 10 START 20;');
+    expect(vars).toEqual({ __p0: true });
+  });
+
+  it('renders OR groups and comparison ops', () => {
+    const plan: QueryPlan = {
+      table: 'game',
+      where: [
+        { or: [{ field: 'white', op: '=', value: 'u:1' }, { field: 'black', op: '=', value: 'u:1' }] },
+        { field: 'moves', op: '>=', value: 5 },
+      ],
+    };
+    const { sql, vars } = renderBaseSelectSurql(plan);
+    expect(sql).toBe('SELECT * FROM game WHERE (white = $__p0 OR black = $__p1) AND moves >= $__p2;');
+    expect(vars).toEqual({ __p0: 'u:1', __p1: 'u:1', __p2: 5 });
+  });
+
+  it('honors paramRef and swap without binding a new var', () => {
+    const plan: QueryPlan = {
+      table: 't',
+      where: [{ field: 'tags', op: 'CONTAINS', value: undefined, paramRef: 'tag', swap: true }],
+    };
+    const { sql, vars } = renderBaseSelectSurql(plan, { tag: 'x' });
+    expect(sql).toBe('SELECT * FROM t WHERE $tag CONTAINS tags;');
+    expect(vars).toEqual({ tag: 'x' });
+  });
+});
+
+// Regression guard for the "authors + comments don't load" class: any filter on
+// a RecordId column (`id`) must coerce its string value with
+// `type::record(<string> …)`. On SurrealDB `id = "thread:x"` (string) never
+// matches a RecordId, so a base select filtered by id resolves EMPTY and its
+// whole `.related()` subtree (author, comments) loads nothing. The string-based
+// MemStore in relation-resolver.test.ts can't catch this (it compares keys as
+// strings), so these assert the rendered SurrealQL directly — both the parent
+// (base select) and child (relation fetch) sides.
+describe('record-id coercion (authors/comments loading regression)', () => {
+  it('coerces a base-select `id = <value>` filter to a record id', () => {
+    const plan: QueryPlan = { table: 'thread', where: [{ field: 'id', op: '=', value: 'thread:abc' }] };
+    const { sql, vars } = renderBaseSelectSurql(plan);
+    expect(sql).toBe('SELECT * FROM thread WHERE id = type::record(<string> $__p0);');
+    expect(vars).toEqual({ __p0: 'thread:abc' });
+  });
+
+  it('coerces a base-select `id = $paramRef` filter (the ThreadDetail path)', () => {
+    const plan: QueryPlan = { table: 'thread', where: [{ field: 'id', op: '=', value: undefined, paramRef: 'id' }] };
+    const { sql } = renderBaseSelectSurql(plan, { id: 'thread:abc' });
+    expect(sql).toBe('SELECT * FROM thread WHERE id = type::record(<string> $id);');
+  });
+
+  it('does NOT coerce non-id fields (plain string/bool columns stay literal)', () => {
+    const plan: QueryPlan = {
+      table: 'thread',
+      where: [{ field: 'title', op: '=', value: 'hi' }, { field: 'published', op: '=', value: true }],
+    };
+    const { sql } = renderBaseSelectSurql(plan);
+    expect(sql).toBe('SELECT * FROM thread WHERE title = $__p0 AND published = $__p1;');
+  });
+
+  // Regression guard for the thread-detail "crossed results → 404" bug: a
+  // slave-mode node carries BOTH a baked `value` and a `paramRef` (= the field
+  // name). Materialization MUST bind `params[paramRef]` (the query's identity),
+  // NOT the baked value — otherwise a stale/other plan whose baked id ≠ the
+  // query's params would surface a different record's row. So rendering a plan
+  // baked to id-A with params for id-B must filter by B.
+  it('slave-mode node binds params over the baked value (records follow identity)', () => {
+    const planBakedToA: QueryPlan = {
+      table: 'thread',
+      where: [{ field: 'id', op: '=', value: 'thread:A', paramRef: 'id' }],
+    };
+    const { sql, vars } = renderBaseSelectSurql(planBakedToA, { id: 'thread:B' });
+    expect(sql).toBe('SELECT * FROM thread WHERE id = type::record(<string> $id);');
+    expect(vars).toEqual({ id: 'thread:B' }); // B wins — the baked A is ignored
+  });
+
+  it('slave-mode node falls back to the baked value when the param is absent', () => {
+    const plan: QueryPlan = {
+      table: 'thread',
+      where: [{ field: 'id', op: '=', value: 'thread:A', paramRef: 'id' }],
+    };
+    const { sql, vars } = renderBaseSelectSurql(plan, {}); // no params.id
+    expect(sql).toBe('SELECT * FROM thread WHERE id = type::record(<string> $__p0);');
+    expect(vars).toEqual({ __p0: 'thread:A' });
+  });
+
+  it('coerces `id` inside an OR group too', () => {
+    const plan: QueryPlan = {
+      table: 'thread',
+      where: [{ or: [{ field: 'id', op: '=', value: 'thread:a' }, { field: 'id', op: '=', value: 'thread:b' }] }],
+    };
+    const { sql } = renderBaseSelectSurql(plan);
+    expect(sql).toBe(
+      'SELECT * FROM thread WHERE (id = type::record(<string> $__p0) OR id = type::record(<string> $__p1));'
+    );
+  });
+
+  it('relation fetch coerces its matchField keys (the .118 fix — kept locked)', () => {
+    const { sql } = renderRelationFetchSurql({ table: 'user', matchField: 'id', keys: ['user:1'] });
+    expect(sql).toContain('id IN $__keys.map(|$__k| type::record(<string> $__k))');
+  });
+});
+
+describe('renderRelationFetchSurql', () => {
+  it('builds a WHERE ... IN $__keys batch fetch, omitting LIMIT', () => {
+    const { sql, vars } = renderRelationFetchSurql({
+      table: 'comment',
+      matchField: 'post',
+      keys: ['post:1', 'post:2'],
+      where: [{ field: 'hidden', op: '=', value: false }],
+      orderBy: [['rank', 'asc']],
+    });
+    expect(sql).toBe('SELECT * FROM comment WHERE post IN $__keys.map(|$__k| type::record(<string> $__k)) AND hidden = $__p0 ORDER BY rank asc;');
+    expect(vars).toEqual({ __keys: ['post:1', 'post:2'], __p0: false });
+  });
+});
+
+describe('buildWindowMaterializationPlan', () => {
+  it('restricts to the id-set for offset queries, dropping where/limit/offset', () => {
+    const plan: QueryPlan = {
+      table: 'post',
+      where: [{ field: 'x', op: '=', value: 1 }],
+      orderBy: [['created', 'desc']],
+      limit: 10,
+      offset: 20,
+      relations: [{ alias: 'a', table: 'u', cardinality: 'one', foreignKeyField: 'a' }],
+    };
+    const win = buildWindowMaterializationPlan(plan, ['post:5', 'post:6']);
+    expect(win).toEqual({
+      table: 'post',
+      orderBy: [['created', 'desc']],
+      relations: [{ alias: 'a', table: 'u', cardinality: 'one', foreignKeyField: 'a' }],
+      ids: ['post:5', 'post:6'],
+      where: undefined,
+      limit: undefined,
+      offset: undefined,
+    });
+  });
+
+  it('returns null for non-offset queries (keep normal path)', () => {
+    expect(buildWindowMaterializationPlan({ table: 'post', limit: 10 }, ['post:1'])).toBeNull();
+    expect(buildWindowMaterializationPlan({ table: 'post', offset: 0 }, ['post:1'])).toBeNull();
+  });
+});

package/src/services/database/plan-render.ts

@@ -0,0 +1,108 @@
+import type { QueryPlan, WhereNode, WhereComparison } from '@spooky-sync/query-builder';
+import type { OrderBy, RelationFetch } from './cache-engine';
+
+/**
+ * Render helpers that turn an engine-neutral {@link QueryPlan} into a concrete
+ * dialect. Two consumers: `SurrealCacheEngine` (SurrealQL) and, indirectly, the
+ * SQLite worker (which uses the SQL variants). Relations are NOT rendered here —
+ * they are resolved by `resolveRelations` via the {@link RelationFetch}
+ * primitive, so both engines share the exact same decomposition.
+ */
+
+export interface RenderedQuery {
+  sql: string;
+  vars: Record<string, unknown>;
+}
+
+interface RenderCtx {
+  vars: Record<string, unknown>;
+  n: number;
+}
+
+function bind(ctx: RenderCtx, value: unknown): string {
+  const name = `__p${ctx.n++}`;
+  ctx.vars[name] = value;
+  return `$${name}`;
+}
+
+function renderComparisonSurql(c: WhereComparison, ctx: RenderCtx): string {
+  // Prefer the query's own param (`paramRef`) so a filter materializes from
+  // `params` (the query's identity), not a baked literal — this is what slaves
+  // a query's rows to its id. A pure `$`-ref node has no `value`, so it always
+  // uses the param. A slave-mode node also carries `value` as a fallback for
+  // when the param is absent (e.g. a non-column field stripped by parseParams).
+  const useParam =
+    c.paramRef !== undefined &&
+    (c.value === undefined || Object.prototype.hasOwnProperty.call(ctx.vars, c.paramRef));
+  const rawRight = useParam ? `$${c.paramRef}` : bind(ctx, c.value);
+  // `id` is a RecordId, but correlation/filter values arrive as record-id
+  // STRINGS (e.g. "thread:abc"). On SurrealDB `id = "thread:abc"` never matches
+  // (string ≠ record), so a base select filtered by id (e.g. the ThreadDetail
+  // query `… FROM thread WHERE id = $id`) resolves empty — and its whole
+  // `.related()` subtree (author, comments) then loads nothing. Coerce with
+  // `type::record(<string> …)` (idempotent if already a RecordId), mirroring
+  // renderRelationFetchSurql's matchField coercion.
+  const right =
+    c.field === 'id' ? `type::record(<string> ${rawRight})` : rawRight;
+  return c.swap ? `${right} ${c.op} ${c.field}` : `${c.field} ${c.op} ${right}`;
+}
+
+/** Render a WHERE conjunction (AND of comparisons / OR-groups) to SurrealQL. */
+export function renderWhereSurql(nodes: WhereNode[], ctx: RenderCtx): string {
+  return nodes
+    .map((node) => {
+      if ('or' in node) {
+        return `(${node.or.map((c) => renderComparisonSurql(c, ctx)).join(' OR ')})`;
+      }
+      return renderComparisonSurql(node, ctx);
+    })
+    .join(' AND ');
+}
+
+function renderOrderBy(orderBy: OrderBy): string {
+  return ` ORDER BY ${orderBy.map(([f, d]) => `${f} ${d}`).join(', ')}`;
+}
+
+/**
+ * Render the BASE of a SELECT (no relations) to SurrealQL. `params` supplies
+ * pre-existing bound params (e.g. `$__win` for windowing, or `paramRef` values)
+ * and is merged into the returned vars.
+ */
+export function renderBaseSelectSurql(
+  plan: QueryPlan,
+  params: Record<string, unknown> = {}
+): RenderedQuery {
+  const ctx: RenderCtx = { vars: { ...params }, n: 0 };
+  const projection = plan.select && plan.select.length > 0 ? plan.select.join(', ') : '*';
+  let sql = `SELECT ${projection} FROM ${plan.table}`;
+  if (plan.where && plan.where.length > 0) {
+    sql += ` WHERE ${renderWhereSurql(plan.where, ctx)}`;
+  }
+  if (plan.orderBy && plan.orderBy.length > 0) sql += renderOrderBy(plan.orderBy);
+  if (plan.limit !== undefined) sql += ` LIMIT ${plan.limit}`;
+  if (plan.offset !== undefined) sql += ` START ${plan.offset}`;
+  return { sql: `${sql};`, vars: ctx.vars };
+}
+
+/**
+ * Render a batched relation fetch to SurrealQL:
+ * `SELECT <select> FROM <table> WHERE <matchField> IN $__keys [AND <where>] [ORDER BY]`.
+ * The resolver re-applies per-parent ORDER/LIMIT after grouping, so LIMIT is
+ * intentionally omitted here.
+ */
+export function renderRelationFetchSurql(req: RelationFetch): RenderedQuery {
+  const ctx: RenderCtx = { vars: { __keys: req.keys }, n: 0 };
+  const projection =
+    req.select && req.select.length > 0 ? ['id', ...req.select].join(', ') : '*';
+  // The correlation keys arrive as record-id STRINGS (`"user:abc"`), but the
+  // matched column (`id`, or a `record<…>` foreign key) is a RecordId. In
+  // SurrealDB `id IN ["user:abc"]` never matches (string ≠ record), so every
+  // `.related()` field would resolve empty. Coerce each key to a record id with
+  // `type::record(<string> …)` (idempotent if a key is already a RecordId).
+  let sql = `SELECT ${projection} FROM ${req.table} WHERE ${req.matchField} IN $__keys.map(|$__k| type::record(<string> $__k))`;
+  if (req.where && req.where.length > 0) {
+    sql += ` AND ${renderWhereSurql(req.where, ctx)}`;
+  }
+  if (req.orderBy && req.orderBy.length > 0) sql += renderOrderBy(req.orderBy);
+  return { sql: `${sql};`, vars: ctx.vars };
+}