@svgrid/enterprise 1.2.0 → 2.0.0

package/src/sveltekit/sql-source.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from 'vitest'
+import type { ServerRequest } from '@svgrid/grid'
+import type { EntitySchema } from '../schema'
+import { createSqlDataSource, type SqlExecutor } from './sql-source'
+
+type Customer = { id: string; name: string; age: number }
+
+const schema: EntitySchema<Customer> = {
+  name: 'customers',
+  idField: 'id',
+  fields: [
+    { field: 'id', type: 'text', primaryKey: true },
+    { field: 'name', type: 'text' },
+    { field: 'age', type: 'number' },
+  ],
+}
+
+/** Records every (sql, params) and returns queued results per call. */
+function recorder(results: Array<ReadonlyArray<Record<string, unknown>>>) {
+  const calls: Array<{ sql: string; params: unknown[] }> = []
+  let i = 0
+  const execute: SqlExecutor = async (sql, params) => {
+    calls.push({ sql, params })
+    return results[i++] ?? []
+  }
+  return { execute, calls }
+}
+
+const req = (p: Partial<ServerRequest>): ServerRequest => ({
+  startRow: 0,
+  endRow: 50,
+  pageIndex: 0,
+  pageSize: 50,
+  sortModel: [],
+  filterModel: {},
+  ...p,
+})
+
+describe('createSqlDataSource reads', () => {
+  it('builds a parameterized SELECT + COUNT and maps the result', async () => {
+    const { execute, calls } = recorder([
+      [{ id: '1', name: 'Ann', age: 30 }],
+      [{ count: 7 }],
+    ])
+    const src = createSqlDataSource({ schema, table: 'customers', execute })
+    const res = await src.getRows(
+      req({
+        filterModel: { columns: { age: { operator: 'greaterThan', value: '20' } } },
+        sortModel: [{ id: 'name', desc: false }],
+        startRow: 50,
+        pageSize: 25,
+      }),
+    )
+
+    expect(res.rowCount).toBe(7)
+    expect(res.rows[0]?.name).toBe('Ann')
+
+    expect(calls[0]!.sql).toBe(
+      'SELECT * FROM "customers" WHERE "age" > ? ORDER BY "name" ASC LIMIT 25 OFFSET 50',
+    )
+    expect(calls[0]!.params).toEqual([20])
+    expect(calls[1]!.sql).toBe('SELECT COUNT(*) AS count FROM "customers" WHERE "age" > ?')
+    expect(calls[1]!.params).toEqual([20])
+  })
+
+  it('honors the Postgres dialect ($ placeholders)', async () => {
+    const { execute, calls } = recorder([[], [{ count: 0 }]])
+    const src = createSqlDataSource({
+      schema,
+      table: 'customers',
+      execute,
+      dialect: { placeholders: '$', ilike: true },
+    })
+    await src.getRows(req({ filterModel: { columns: { name: { operator: 'contains', value: 'a' } } } }))
+    expect(calls[0]!.sql).toContain('"name" ILIKE $1')
+  })
+})
+
+describe('createSqlDataSource writes', () => {
+  it('creates with a parameterized INSERT ... RETURNING', async () => {
+    const { execute, calls } = recorder([[{ id: '9', name: 'Zoe', age: 41 }]])
+    const src = createSqlDataSource({ schema, table: 'customers', execute })
+    const created = await src.createRow({ id: '9', name: 'Zoe', age: 41 })
+    expect(created).toEqual({ id: '9', name: 'Zoe', age: 41 })
+    expect(calls[0]!.sql).toBe(
+      'INSERT INTO "customers" ("id", "name", "age") VALUES (?, ?, ?) RETURNING *',
+    )
+    expect(calls[0]!.params).toEqual(['9', 'Zoe', 41])
+  })
+
+  it('updates by id with SET + WHERE', async () => {
+    const { execute, calls } = recorder([[{ id: '9', name: 'Zoe', age: 42 }]])
+    const src = createSqlDataSource({ schema, table: 'customers', execute })
+    await src.updateRow('9', { age: 42 })
+    expect(calls[0]!.sql).toBe('UPDATE "customers" SET "age" = ? WHERE "id" = ? RETURNING *')
+    expect(calls[0]!.params).toEqual([42, '9'])
+  })
+
+  it('deletes by id', async () => {
+    const { execute, calls } = recorder([[]])
+    const src = createSqlDataSource({ schema, table: 'customers', execute })
+    await src.deleteRow('9')
+    expect(calls[0]!.sql).toBe('DELETE FROM "customers" WHERE "id" = ?')
+    expect(calls[0]!.params).toEqual(['9'])
+  })
+
+  it('omits RETURNING and echoes input when returning:false (MySQL)', async () => {
+    const { execute, calls } = recorder([[]])
+    const src = createSqlDataSource({ schema, table: 'customers', execute, returning: false })
+    const created = await src.createRow({ id: '1', name: 'A', age: 1 })
+    expect(calls[0]!.sql).not.toContain('RETURNING')
+    expect(created).toEqual({ id: '1', name: 'A', age: 1 })
+  })
+
+  it('getAggregate emits a GROUP BY with quoted identifiers', async () => {
+    const { execute, calls } = recorder([[{ category: 'x', value: 10 }, { category: 'y', value: 5 }]])
+    const src = createSqlDataSource({ schema, table: 'customers', execute })
+    const out = await src.getAggregate({ dimension: 'name', measure: 'age', reduce: 'sum' })
+    expect(calls[0]!.sql).toBe('SELECT "name" AS category, SUM("age") AS value FROM "customers" GROUP BY "name" ORDER BY value DESC')
+    expect(out).toEqual([{ category: 'x', value: 10 }, { category: 'y', value: 5 }])
+  })
+
+  it('getAggregate uses COUNT(*) for reduce:count', async () => {
+    const { execute, calls } = recorder([[]])
+    const src = createSqlDataSource({ schema, table: 'customers', execute })
+    await src.getAggregate({ dimension: 'name', reduce: 'count' })
+    expect(calls[0]!.sql).toContain('COUNT(*) AS value')
+    expect(calls[0]!.sql).toContain('GROUP BY "name"')
+  })
+
+  it('getAggregate with no dimension emits a single total (no GROUP BY) - a KPI', async () => {
+    const { execute, calls } = recorder([[{ value: 42 }]])
+    const src = createSqlDataSource({ schema, table: 'customers', execute })
+    const out = await src.getAggregate({ measure: 'age', reduce: 'sum' })
+    expect(calls[0]!.sql).toBe('SELECT SUM("age") AS value FROM "customers"')
+    expect(calls[0]!.sql).not.toContain('GROUP BY')
+    expect(out).toEqual([{ category: '', value: 42 }])
+  })
+})
+
+// A schema whose fields are renamed relative to their DB columns (the Drizzle
+// `createdAt: timestamp('created_at')` case).
+type Ev = { id: string; startsAt: string }
+const renamedSchema: EntitySchema<Ev> = {
+  name: 'events',
+  idField: 'id',
+  fields: [
+    { field: 'id', dbColumn: 'event_id', type: 'text', primaryKey: true },
+    { field: 'startsAt', dbColumn: 'starts_at', type: 'datetime' },
+  ],
+}
+
+describe('createSqlDataSource honors dbColumn (renamed columns)', () => {
+  it('SELECTs the real columns aliased back to the field names', async () => {
+    const { execute, calls } = recorder([[{ id: '1', startsAt: 'x' }], [{ count: 1 }]])
+    const src = createSqlDataSource({ schema: renamedSchema, table: 'events', execute })
+    await src.getRows(req({ sortModel: [{ id: 'startsAt', desc: true }] }))
+    expect(calls[0]!.sql).toContain('SELECT "event_id" AS "id", "starts_at" AS "startsAt" FROM "events"')
+    expect(calls[0]!.sql).toContain('ORDER BY "starts_at" DESC') // sort uses the DB column
+  })
+
+  it('filters on the real column', async () => {
+    const { execute, calls } = recorder([[], [{ count: 0 }]])
+    const src = createSqlDataSource({ schema: renamedSchema, table: 'events', execute })
+    await src.getRows(req({ filterModel: { columns: { startsAt: { operator: 'contains', value: '2026' } } } }))
+    // The WHERE predicate targets the real DB column, not the field name.
+    expect(calls[0]!.sql).toContain('LOWER("starts_at") LIKE')
+    expect(calls[0]!.sql).not.toContain('LOWER("startsAt")')
+  })
+
+  it('INSERT / UPDATE write the real columns and RETURNING aliases back', async () => {
+    const { execute, calls } = recorder([[{ id: '9', startsAt: 'y' }]])
+    const src = createSqlDataSource({ schema: renamedSchema, table: 'events', execute })
+    await src.createRow({ id: '9', startsAt: 'y' })
+    expect(calls[0]!.sql).toContain('INSERT INTO "events" ("event_id", "starts_at")')
+    expect(calls[0]!.sql).toContain('RETURNING "event_id" AS "id", "starts_at" AS "startsAt"')
+  })
+
+  it('getAggregate reduces the real measure column', async () => {
+    const { execute, calls } = recorder([[{ value: 3 }]])
+    const src = createSqlDataSource({ schema: renamedSchema, table: 'events', execute })
+    await src.getAggregate({ dimension: 'startsAt', reduce: 'count' })
+    expect(calls[0]!.sql).toContain('GROUP BY "starts_at"')
+  })
+})

package/src/sveltekit/sql-source.ts

@@ -0,0 +1,166 @@
+/**
+ * createSqlDataSource - a production `ServerDataSource` backed by any SQL
+ * database. It plans the read with `planQuery` + `planToSql`, and builds
+ * parameterized INSERT / UPDATE / DELETE for writes. You supply one thing: an
+ * `execute(sql, params)` that runs a query and returns rows. Every SQL client
+ * SvelteKit teams use provides that - Drizzle (`db.execute`), postgres.js,
+ * better-sqlite3, mysql2 - so this is the turnkey "point at your database"
+ * adapter, the sibling of `createInMemoryDataSource`.
+ *
+ * All values are parameterized; identifiers come from the schema-whitelisted
+ * plan and are quoted. No string interpolation of user input.
+ *
+ * Drizzle (Postgres) example:
+ *
+ *     import { sql } from 'drizzle-orm'
+ *     const source = createSqlDataSource({
+ *       schema: customerSchema,
+ *       table: 'customers',
+ *       dialect: { placeholders: '$', ilike: true },
+ *       execute: (text, params) =>
+ *         db.execute(sql.raw(text, params)).then((r) => r.rows),
+ *     })
+ */
+import type { RowData, ServerRequest, ServerResult } from '@svgrid/grid'
+import { resolveIdField, type EntitySchema } from '../schema'
+import { nudgeEnterprise } from '../license'
+import { planQuery } from './query-plan'
+import { planToSql, type SqlDialect } from './sql'
+import type { WritableDataSource } from './types'
+import type { AggregateBucket, AggregateRequest, AggregateSource } from '../sources/aggregate'
+
+const SQL_AGG: Record<'sum' | 'avg' | 'min' | 'max', string> = { sum: 'SUM', avg: 'AVG', min: 'MIN', max: 'MAX' }
+
+/** Run a parameterized query, resolving to the result rows. */
+export type SqlExecutor = (
+  sql: string,
+  params: unknown[],
+) => Promise<ReadonlyArray<Record<string, unknown>>>
+
+export type SqlDataSourceConfig<TData extends RowData> = {
+  schema: EntitySchema<TData>
+  /** Table (or view) name. Quoted per the dialect; not interpolated raw. */
+  table: string
+  execute: SqlExecutor
+  dialect?: SqlDialect
+  /**
+   * Append `RETURNING *` to writes and return the row the database echoes back
+   * (Postgres / SQLite). Set false for MySQL, where the input is returned as-is.
+   * Default true.
+   */
+  returning?: boolean
+}
+
+function quoter(dialect: SqlDialect) {
+  const q = dialect.quote ?? '"'
+  return (name: string) => `${q}${name.replace(new RegExp(q, 'g'), q + q)}${q}`
+}
+
+function binder(dialect: SqlDialect, params: unknown[]) {
+  return (value: unknown) => {
+    params.push(value)
+    if (dialect.placeholders === '$') return `$${params.length}`
+    if (dialect.placeholders === '@') return `@p${params.length}`
+    return '?'
+  }
+}
+
+const squish = (sql: string) => sql.replace(/\s+/g, ' ').trim()
+
+export function createSqlDataSource<TData extends RowData>(
+  config: SqlDataSourceConfig<TData>,
+): WritableDataSource<TData> & AggregateSource {
+  nudgeEnterprise('Studio') // soft-gate; never blocks, safe on the server
+  const { schema, table, execute } = config
+  const dialect = config.dialect ?? {}
+  const returning = config.returning ?? true
+  const id = quoter(dialect)
+  const idField = resolveIdField(schema)
+
+  // Column mapping: when a field has a `dbColumn` (e.g. Drizzle `created_at` vs
+  // key `createdAt`), read/write the real column and alias it back to the field.
+  // With no renames, everything is identity - the emitted SQL is byte-identical.
+  const dbCol = new Map(schema.fields.filter((f) => f.dbColumn).map((f) => [f.field, f.dbColumn!]))
+  const hasRenames = dbCol.size > 0
+  const columnOf = (field: string): string => dbCol.get(field) ?? field
+  const col = (field: string): string => id(columnOf(field))
+  const projection = hasRenames
+    ? schema.fields.map((f) => `${id(columnOf(f.field))} AS ${id(f.field)}`).join(', ')
+    : '*'
+  const planDialect: SqlDialect = hasRenames ? { ...dialect, column: columnOf } : dialect
+  const RET = returning ? ` RETURNING ${projection}` : ''
+
+  return {
+    async getRows(request: ServerRequest): Promise<ServerResult<TData>> {
+      const plan = planQuery(schema, request)
+      const sql = planToSql(plan, planDialect)
+      const t = id(table)
+      const rowsSql = squish(
+        `SELECT ${projection} FROM ${t} ${sql.whereText} ${sql.orderByText} LIMIT ${sql.limit} OFFSET ${sql.offset}`,
+      )
+      const countSql = squish(`SELECT COUNT(*) AS count FROM ${t} ${sql.whereText}`)
+      const rows = await execute(rowsSql, sql.params)
+      const countRows = await execute(countSql, sql.params)
+      const rowCount = Number(countRows[0]?.count ?? rows.length)
+      return { rows: rows as ReadonlyArray<TData>, rowCount }
+    },
+
+    async createRow(input: Partial<TData>): Promise<TData> {
+      const cols = Object.keys(input)
+      if (cols.length === 0) throw new Error('createSqlDataSource: createRow needs at least one field')
+      const params: unknown[] = []
+      const bind = binder(dialect, params)
+      const values = cols.map((c) => bind((input as RowData)[c]))
+      const sql = squish(
+        `INSERT INTO ${id(table)} (${cols.map(col).join(', ')}) VALUES (${values.join(', ')})${RET}`,
+      )
+      const rows = await execute(sql, params)
+      return (rows[0] ?? input) as TData
+    },
+
+    async updateRow(rowIdValue: string, patch: Partial<TData>): Promise<TData> {
+      const cols = Object.keys(patch)
+      if (cols.length === 0) throw new Error('createSqlDataSource: updateRow needs at least one field')
+      const params: unknown[] = []
+      const bind = binder(dialect, params)
+      const sets = cols.map((c) => `${col(c)} = ${bind((patch as RowData)[c])}`)
+      const where = `${col(idField)} = ${bind(rowIdValue)}`
+      const sql = squish(`UPDATE ${id(table)} SET ${sets.join(', ')} WHERE ${where}${RET}`)
+      const rows = await execute(sql, params)
+      return (rows[0] ?? { ...patch, [idField]: rowIdValue }) as TData
+    },
+
+    async deleteRow(rowIdValue: string): Promise<void> {
+      const params: unknown[] = []
+      const bind = binder(dialect, params)
+      const sql = squish(`DELETE FROM ${id(table)} WHERE ${col(idField)} = ${bind(rowIdValue)}`)
+      await execute(sql, params)
+    },
+
+    async getAggregate(request: AggregateRequest): Promise<AggregateBucket[]> {
+      // Server-side GROUP BY. Identifiers are schema-quoted (no interpolation of
+      // user input); the WHERE + params come from the shared query plan.
+      const plan = planQuery(schema, {
+        startRow: 0, endRow: 0, pageIndex: 0, pageSize: 0, sortModel: [],
+        filterModel: request.filterModel ?? {},
+      })
+      const sql = planToSql(plan, planDialect)
+      const fn =
+        request.reduce === 'count' || !request.measure
+          ? 'COUNT(*)'
+          : `${SQL_AGG[request.reduce]}(${col(request.measure)})`
+      // No dimension -> a single grand total (a KPI), no GROUP BY.
+      if (!request.dimension) {
+        const text = squish(`SELECT ${fn} AS value FROM ${id(table)} ${sql.whereText}`)
+        const rows = await execute(text, sql.params)
+        return [{ category: '', value: Number(rows[0]?.value ?? 0) }]
+      }
+      const dim = col(request.dimension)
+      const text = squish(
+        `SELECT ${dim} AS category, ${fn} AS value FROM ${id(table)} ${sql.whereText} GROUP BY ${dim} ORDER BY value DESC`,
+      )
+      const rows = await execute(text, sql.params)
+      return rows.map((r) => ({ category: String(r.category ?? ''), value: Number(r.value ?? 0) }))
+    },
+  }
+}

package/src/sveltekit/sql.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest'
+import type { QueryPlan } from './query-plan'
+import { planToSql } from './sql'
+
+const base: QueryPlan = { where: [], search: null, orderBy: [], limit: 50, offset: 0 }
+
+describe('planToSql', () => {
+  it('emits parameterized predicates with ANSI defaults', () => {
+    const plan: QueryPlan = {
+      ...base,
+      where: [
+        { field: 'age', op: 'gt', value: 30 },
+        { field: 'name', op: 'contains', value: 'ann' },
+      ],
+    }
+    const sql = planToSql(plan)
+    expect(sql.whereText).toBe('WHERE "age" > ? AND LOWER("name") LIKE LOWER(?)')
+    expect(sql.params).toEqual([30, '%ann%'])
+  })
+
+  it('supports the Postgres dialect: $ placeholders and ILIKE', () => {
+    const plan: QueryPlan = { ...base, where: [{ field: 'name', op: 'startsWith', value: 'A' }] }
+    const sql = planToSql(plan, { placeholders: '$', ilike: true })
+    expect(sql.whereText).toBe('WHERE "name" ILIKE $1')
+    expect(sql.params).toEqual(['A%'])
+  })
+
+  it('supports SQL Server @p placeholders', () => {
+    const plan: QueryPlan = { ...base, where: [{ field: 'age', op: 'gt', value: 30 }] }
+    const sql = planToSql(plan, { placeholders: '@' })
+    expect(sql.whereText).toBe('WHERE "age" > @p1')
+    expect(sql.params).toEqual([30])
+  })
+
+  it('renders between, isBlank, and in', () => {
+    const plan: QueryPlan = {
+      ...base,
+      where: [
+        { field: 'age', op: 'between', value: 20, valueTo: 40 },
+        { field: 'note', op: 'isBlank' },
+        { field: 'tier', op: 'in', values: ['free', 'pro'] },
+      ],
+    }
+    const sql = planToSql(plan)
+    expect(sql.where).toBe(
+      '"age" BETWEEN ? AND ? AND ("note" IS NULL OR "note" = \'\') AND "tier" IN (?, ?)',
+    )
+    expect(sql.params).toEqual([20, 40, 'free', 'pro'])
+  })
+
+  it('an empty `in` matches nothing', () => {
+    const sql = planToSql({ ...base, where: [{ field: 'tier', op: 'in', values: [] }] })
+    expect(sql.where).toBe('1 = 0')
+    expect(sql.params).toEqual([])
+  })
+
+  it('appends a global search as an OR group after the column predicates', () => {
+    const plan: QueryPlan = {
+      ...base,
+      where: [{ field: 'age', op: 'gt', value: 1 }],
+      search: { term: 'acme', fields: ['name', 'tier'] },
+    }
+    const sql = planToSql(plan)
+    expect(sql.where).toBe(
+      '"age" > ? AND (LOWER("name") LIKE LOWER(?) OR LOWER("tier") LIKE LOWER(?))',
+    )
+    expect(sql.params).toEqual([1, '%acme%', '%acme%'])
+  })
+
+  it('builds order by and leaves where empty when there are no predicates', () => {
+    const sql = planToSql({ ...base, orderBy: [{ field: 'name', desc: false }, { field: 'age', desc: true }] })
+    expect(sql.whereText).toBe('')
+    expect(sql.orderByText).toBe('ORDER BY "name" ASC, "age" DESC')
+  })
+
+  it('escapes identifier quote chars', () => {
+    const sql = planToSql({ ...base, where: [{ field: 'we"ird', op: 'eq', value: 1 }] })
+    expect(sql.where).toBe('"we""ird" = ?')
+  })
+})

package/src/sveltekit/sql.ts

@@ -0,0 +1,131 @@
+/**
+ * `planToSql` - turn a `QueryPlan` into a portable, parameterized SQL fragment.
+ * This is the backend seam for every SQL database: Drizzle, postgres.js,
+ * better-sqlite3, mysql2. It emits only a WHERE body, an ORDER BY body, and a
+ * params array - never a full statement - so you keep control of the SELECT,
+ * the table, joins, and execution.
+ *
+ * All values are parameterized (never interpolated) and every identifier comes
+ * from the plan, which `planQuery` already whitelisted against the schema - so
+ * there is no SQL-injection surface here.
+ *
+ * Drizzle usage (Postgres):
+ *
+ *     import { sql } from 'drizzle-orm'
+ *     const { whereText, orderByText, params, limit, offset } =
+ *       planToSql(plan, { placeholders: '$', ilike: true })
+ *     const rows = await db.execute(
+ *       sql.raw(`select * from customers ${whereText} ${orderByText} limit ${limit} offset ${offset}`, params)
+ *     )
+ *
+ * (Or map `plan.where` to Drizzle operators directly - the plan is the seam
+ * either way.)
+ */
+import type { PlanPredicate, QueryPlan } from './query-plan'
+
+export type SqlDialect = {
+  /** Identifier quote char. Default `"` (ANSI / Postgres / SQLite). MySQL: `` ` ``. */
+  quote?: string
+  /** Placeholder style: `'?'` (SQLite / MySQL), `'$'` for `$1, $2` (Postgres), or `'@'` for `@p1, @p2` (SQL Server). Default `'?'`. */
+  placeholders?: '?' | '$' | '@'
+  /** Use `ILIKE` for case-insensitive matching (Postgres) instead of `LOWER(col) LIKE LOWER(?)`. */
+  ilike?: boolean
+  /** Map a schema `field` to its real DB column. Default: identity. Lets renamed columns (Drizzle `created_at` vs key `createdAt`) plan correctly. */
+  column?: (field: string) => string
+}
+
+export type SqlPlan = {
+  /** WHERE body without the keyword, e.g. `"age" > ? AND "name" ILIKE ?`. Empty string when no predicates. */
+  where: string
+  /** WHERE body with the leading `WHERE ` keyword, or `''`. */
+  whereText: string
+  /** ORDER BY body without the keyword, e.g. `"name" ASC, "age" DESC`. */
+  orderBy: string
+  /** ORDER BY body with the leading `ORDER BY ` keyword, or `''`. */
+  orderByText: string
+  params: unknown[]
+  limit: number
+  offset: number
+}
+
+export function planToSql(plan: QueryPlan, dialect: SqlDialect = {}): SqlPlan {
+  const q = dialect.quote ?? '"'
+  const useIlike = dialect.ilike ?? false
+  const params: unknown[] = []
+
+  const ph = () => {
+    if (dialect.placeholders === '$') return `$${params.length}`
+    if (dialect.placeholders === '@') return `@p${params.length}`
+    return '?'
+  }
+  const bind = (v: unknown): string => {
+    params.push(v)
+    return ph()
+  }
+  const columnFor = dialect.column ?? ((f: string) => f)
+  const id = (field: string) => {
+    const c = columnFor(field)
+    return `${q}${c.replace(new RegExp(q, 'g'), q + q)}${q}`
+  }
+
+  const like = (field: string, pattern: string): string => {
+    const p = bind(pattern)
+    return useIlike ? `${id(field)} ILIKE ${p}` : `LOWER(${id(field)}) LIKE LOWER(${p})`
+  }
+
+  const clauses: string[] = []
+
+  for (const pred of plan.where) {
+    clauses.push(predicateSql(pred, { id, bind, like }))
+  }
+
+  if (plan.search && plan.search.fields.length > 0) {
+    const term = `%${plan.search.term}%`
+    const ors = plan.search.fields.map((f) => like(f, term))
+    clauses.push(`(${ors.join(' OR ')})`)
+  }
+
+  const where = clauses.join(' AND ')
+  const orderBy = plan.orderBy.map((o) => `${id(o.field)} ${o.desc ? 'DESC' : 'ASC'}`).join(', ')
+
+  return {
+    where,
+    whereText: where ? `WHERE ${where}` : '',
+    orderBy,
+    orderByText: orderBy ? `ORDER BY ${orderBy}` : '',
+    params,
+    limit: plan.limit,
+    offset: plan.offset,
+  }
+}
+
+function predicateSql(
+  pred: PlanPredicate,
+  ctx: { id: (f: string) => string; bind: (v: unknown) => string; like: (f: string, p: string) => string },
+): string {
+  const { id, bind, like } = ctx
+  const col = id(pred.field)
+  switch (pred.op) {
+    case 'eq':
+      return `${col} = ${bind(pred.value)}`
+    case 'contains':
+      return like(pred.field, `%${pred.value}%`)
+    case 'startsWith':
+      return like(pred.field, `${pred.value}%`)
+    case 'gt':
+      return `${col} > ${bind(pred.value)}`
+    case 'lt':
+      return `${col} < ${bind(pred.value)}`
+    case 'between':
+      return `${col} BETWEEN ${bind(pred.value)} AND ${bind(pred.valueTo)}`
+    case 'isBlank':
+      return `(${col} IS NULL OR ${col} = '')`
+    case 'in': {
+      const vals = pred.values ?? []
+      if (vals.length === 0) return '1 = 0' // empty IN () matches nothing
+      return `${col} IN (${vals.map((v) => bind(v)).join(', ')})`
+    }
+    default:
+      return '1 = 1'
+  }
+}