okengine 0.2.6 → 0.3.2

package/src/elements/store/sql-condition.ts

@@ -1,6 +1,6 @@
 /**
- * Compile Drizzle SQL operators (`eq`, `and`, `lt`, …) and plain equality
- * maps into `WHERE` SQL + bound params for {@link SqlConnection}.
+ * Compile Drizzle SQL operators (`eq`, `and`, `or`, `lt`, `like`, …) and plain
+ * equality maps into `WHERE` SQL + bound params for {@link SqlConnection}.
  *
  * Table-agnostic query-builder support — not domain helpers.
  */
@@ -11,7 +11,18 @@ export type WhereMap = Readonly<Record<string, unknown>>;
 /** One compiled predicate (`col op ?`). */
 export interface CompiledPredicate {
   readonly column: string;
-  readonly op: "=" | "<" | ">" | "<=" | ">=" | "!=";
+  readonly op:
+    | "="
+    | "<"
+    | ">"
+    | "<="
+    | ">="
+    | "!="
+    | "like"
+    | "ilike"
+    | "in"
+    | "is null"
+    | "is not null";
   readonly value: unknown;
 }
 
@@ -22,6 +33,21 @@ export interface CompiledWhere {
   readonly predicates: readonly CompiledPredicate[];
 }
 
+/** One compiled `ORDER BY` term. */
+export interface CompiledOrder {
+  readonly column: string;
+  readonly direction: "ASC" | "DESC";
+}
+
+/** Intermediate compiled node — a leaf comparison or a joined group. */
+interface CompiledNode {
+  readonly clause: string;
+  readonly params: readonly unknown[];
+  readonly predicates: readonly CompiledPredicate[];
+}
+
+const EMPTY_NODE: CompiledNode = { clause: "", params: [], predicates: [] };
+
 /**
  * True when `value` looks like a Drizzle `SQL` wrapper (`eq` / `and` / …).
  *
@@ -35,12 +61,37 @@ export function isDrizzleSql(value: unknown): boolean {
   );
 }
 
+/** Marker for {@link andWhere} — avoids importing `drizzle-orm` here. */
+export interface AndCondition {
+  readonly [andConditionBrand]: true;
+  readonly conditions: readonly unknown[];
+}
+const andConditionBrand: unique symbol = Symbol("oke.and");
+
+/**
+ * Join conditions with `AND` without importing `drizzle-orm`.
+ * `undefined` entries are dropped; a single remaining condition compiles
+ * bare.
+ *
+ * @param conditions - Equality maps or Drizzle SQL
+ */
+export function andWhere(...conditions: readonly unknown[]): unknown {
+  const kept = conditions.filter((c) => c !== undefined && c !== null);
+  if (kept.length === 1) return kept[0];
+  return { [andConditionBrand]: true, conditions: kept } satisfies AndCondition;
+}
+
 /**
  * Compile a where input into SQL.
  *
  * Accepts:
  * - plain {@link WhereMap} equality maps
- * - Drizzle `SQL` from `eq` / `and` / `lt` / …
+ * - Drizzle `SQL` from `eq` / `and` / `or` / `lt` / `like` / …
+ * - {@link AndCondition} from {@link andWhere}
+ *
+ * Nested `and(...)` / `or(...)` compile to parenthesized groups — `or` is
+ * never flattened into `AND`. Unsupported operators throw rather than
+ * silently dropping predicates.
  *
  * @param where - Condition
  */
@@ -50,40 +101,96 @@ export function compileWhere(where: unknown): CompiledWhere {
   }
 
   if (isDrizzleSql(where)) {
-    const predicates = extractPredicates(where);
-    return predicatesToWhere(predicates);
+    const node = compileSqlNode(where);
+    return { clause: node.clause, params: node.params, predicates: node.predicates };
+  }
+
+  if (isAndCondition(where)) {
+    const children = where.conditions.map(compileWhere).filter((c) => c.clause !== "");
+    if (children.length === 0) return { clause: "", params: [], predicates: [] };
+    if (children.length === 1) return children[0]!;
+    return {
+      clause: children.map((c) => `(${c.clause})`).join(" AND "),
+      params: children.flatMap((c) => c.params),
+      predicates: children.flatMap((c) => c.predicates),
+    };
   }
 
   if (typeof where === "object" && !Array.isArray(where)) {
-    const predicates: CompiledPredicate[] = Object.entries(
-      where as WhereMap,
-    ).map(([column, value]) => ({
-      column,
-      op: "=" as const,
-      value,
-    }));
+    const predicates: CompiledPredicate[] = Object.entries(where as WhereMap).map(
+      ([column, value]) => ({
+        column,
+        op: "=" as const,
+        value,
+      }),
+    );
     return predicatesToWhere(predicates);
   }
 
-  throw new TypeError(
-    "sql where: expected equality map or Drizzle SQL condition",
+  throw new TypeError("sql where: expected equality map or Drizzle SQL condition");
+}
+
+function isAndCondition(value: unknown): value is AndCondition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as AndCondition)[andConditionBrand] === true
   );
 }
 
 /**
- * Turn predicates into `col = ? AND …` form.
+ * Compile Drizzle `asc()` / `desc()` terms into `ORDER BY` entries.
+ * Bare column references default to `ASC`.
+ *
+ * @param orders - Order terms (`asc(col)` / `desc(col)` SQL or columns)
+ */
+export function compileOrderBy(orders: readonly unknown[]): readonly CompiledOrder[] {
+  return orders.map((order) => {
+    if (isDrizzleSql(order)) {
+      let column: string | undefined;
+      let text = "";
+      for (const chunk of chunksOf(order)) {
+        if (isDrizzleSql(chunk)) {
+          throw new TypeError("orderBy(): nested SQL is not supported");
+        }
+        const chunkString = chunkText(chunk);
+        if (chunkString !== undefined) {
+          text += chunkString;
+          continue;
+        }
+        const col = asColumn(chunk);
+        if (col === undefined) {
+          throw new TypeError("orderBy(): expected drizzle asc()/desc() SQL");
+        }
+        if (column !== undefined) {
+          throw new TypeError("orderBy(): one column per term");
+        }
+        column = col;
+      }
+      if (column === undefined) {
+        throw new TypeError("orderBy(): expected drizzle asc()/desc() SQL");
+      }
+      const dir = text.trim().toLowerCase();
+      if (dir === "" || dir === "asc") return { column, direction: "ASC" } as const;
+      if (dir === "desc") return { column, direction: "DESC" } as const;
+      throw new TypeError(`orderBy(): unsupported direction ${JSON.stringify(text.trim())}`);
+    }
+    const col = asColumn(order);
+    if (col !== undefined) return { column: col, direction: "ASC" } as const;
+    throw new TypeError("orderBy(): expected drizzle asc()/desc() SQL or a column");
+  });
+}
+
+/**
+ * Turn predicates into `col = ? AND …` form (plain equality maps only).
  *
  * @param predicates - Ordered predicates
  */
-function predicatesToWhere(
-  predicates: readonly CompiledPredicate[],
-): CompiledWhere {
+function predicatesToWhere(predicates: readonly CompiledPredicate[]): CompiledWhere {
   if (predicates.length === 0) {
     return { clause: "", params: [], predicates: [] };
   }
-  const clause = predicates
-    .map((p) => `${quoteIdent(p.column)} ${p.op} ?`)
-    .join(" AND ");
+  const clause = predicates.map((p) => `${quoteIdent(p.column)} ${p.op} ?`).join(" AND ");
   return {
     clause,
     params: predicates.map((p) => p.value),
@@ -92,41 +199,145 @@ function predicatesToWhere(
 }
 
 /**
- * Walk Drizzle `queryChunks` and collect simple binary comparisons.
+ * Recursively compile one Drizzle `SQL` node. Nodes with nested `SQL`
+ * children are groups joined by `AND` / `OR` (detected from the separator
+ * chunks Drizzle emits); nodes without are leaf comparisons.
  *
- * @param node - Drizzle SQL or nested chunk
+ * @param node - Drizzle SQL wrapper
  */
-function extractPredicates(node: unknown): CompiledPredicate[] {
-  const out: CompiledPredicate[] = [];
-  walk(node, out);
-  return out;
+function compileSqlNode(node: unknown): CompiledNode {
+  const chunks = chunksOf(node);
+  const nested = chunks.filter(isDrizzleSql);
+
+  if (nested.length === 0) {
+    return compileLeaf(chunks);
+  }
+
+  // Group level: only structural parens and ` and ` / ` or ` separators may
+  // appear next to nested conditions — anything else is a loud failure.
+  let joiner: "AND" | "OR" | undefined;
+  for (const chunk of chunks) {
+    if (isDrizzleSql(chunk)) continue;
+    const text = chunkText(chunk);
+    if (text === undefined) {
+      throw new TypeError("sql where: unsupported mixed condition");
+    }
+    const token = text.trim().toLowerCase();
+    if (token === "" || token === "(" || token === ")") continue;
+    if (token === "and" || token === "or") {
+      const next = token.toUpperCase() as "AND" | "OR";
+      if (joiner !== undefined && joiner !== next) {
+        throw new TypeError("sql where: mixed AND/OR at one level — parenthesize explicitly");
+      }
+      joiner = next;
+      continue;
+    }
+    throw new TypeError(`sql where: unsupported fragment ${JSON.stringify(text)}`);
+  }
+
+  const children = nested.map(compileSqlNode).filter((c) => c.clause !== "");
+  if (children.length === 0) return EMPTY_NODE;
+  if (children.length === 1) return children[0] ?? EMPTY_NODE;
+  const sep = joiner ?? "AND";
+  return {
+    clause: children.map((c) => `(${c.clause})`).join(` ${sep} `),
+    params: children.flatMap((c) => c.params),
+    predicates: children.flatMap((c) => c.predicates),
+  };
 }
 
-function walk(node: unknown, out: CompiledPredicate[]): void {
-  if (!node || typeof node !== "object") return;
-  const chunks = (node as { queryChunks?: unknown[] }).queryChunks;
-  if (!Array.isArray(chunks)) return;
+/**
+ * Compile a leaf node (`col op ?`) from chunks with no nested `SQL`.
+ * Structural paren chunks are ignored; every other chunk must be part of the
+ * comparison or it throws. `is null` / `is not null` bind no value; `in`
+ * binds one placeholder per array element.
+ *
+ * @param chunks - Drizzle query chunks
+ */
+function compileLeaf(chunks: readonly unknown[]): CompiledNode {
+  let column: string | undefined;
+  let op: CompiledPredicate["op"] | undefined;
+  let value: unknown;
+  let state: "start" | "column" | "op" | "done" = "start";
 
-  // Flatten nested SQL wrappers first so we can scan for col / op / param.
-  const flat: unknown[] = [];
-  for (const c of chunks) {
-    if (c && typeof c === "object" && "queryChunks" in (c as object)) {
-      walk(c, out);
-    } else {
-      flat.push(c);
+  for (const chunk of chunks) {
+    if (Array.isArray(chunk)) {
+      if (state !== "op" || op !== "in") {
+        throw new TypeError("sql where: unsupported condition shape");
+      }
+      const values = chunk.map(asInArrayValue);
+      value = values;
+      state = "done";
+      continue;
+    }
+    const text = chunkText(chunk);
+    if (text !== undefined) {
+      const token = text.trim().replace(/\)+$/, "");
+      if (token === "" || token === "(" || token === ")") continue;
+      if (state === "column") {
+        op = asOperator(token);
+        if (op === undefined) {
+          throw new TypeError(`sql where: unsupported operator ${JSON.stringify(token)}`);
+        }
+        state = op === "is null" || op === "is not null" ? "done" : "op";
+        continue;
+      }
+      throw new TypeError(`sql where: unsupported fragment ${JSON.stringify(text)}`);
     }
+    const col = asColumn(chunk);
+    if (col !== undefined) {
+      if (state !== "start") {
+        throw new TypeError("sql where: unsupported condition shape");
+      }
+      column = col;
+      state = "column";
+      continue;
+    }
+    const param = asParamValue(chunk);
+    if (param.found) {
+      if (state !== "op") {
+        throw new TypeError("sql where: unsupported condition shape");
+      }
+      value = param.value;
+      state = "done";
+      continue;
+    }
+    throw new TypeError("sql where: unsupported condition chunk");
   }
 
-  for (let i = 0; i < flat.length; i++) {
-    const col = asColumn(flat[i]);
-    if (!col) continue;
-    const op = asOperator(flat[i + 1]);
-    if (!op) continue;
-    const param = asParam(flat[i + 2]);
-    if (param === undefined) continue;
-    out.push({ column: col, op, value: param });
-    i += 2;
+  if (state === "start") return EMPTY_NODE;
+  if (state !== "done" || column === undefined || op === undefined) {
+    throw new TypeError("sql where: incomplete condition");
+  }
+  const predicate: CompiledPredicate = { column, op, value };
+  if (op === "is null" || op === "is not null") {
+    return { clause: `${quoteIdent(column)} ${op}`, params: [], predicates: [predicate] };
+  }
+  if (op === "in") {
+    const values = value as readonly unknown[];
+    const placeholders = values.map(() => "?").join(", ");
+    return {
+      clause: `${quoteIdent(column)} in (${placeholders})`,
+      params: [...values],
+      predicates: [predicate],
+    };
   }
+  return {
+    clause: `${quoteIdent(column)} ${op} ?`,
+    params: [value],
+    predicates: [predicate],
+  };
+}
+
+function chunksOf(node: unknown): readonly unknown[] {
+  return (node as { queryChunks: unknown[] }).queryChunks;
+}
+
+/** Joined text of a Drizzle `StringChunk` (`{ value: string[] }`). */
+function chunkText(chunk: unknown): string | undefined {
+  if (!chunk || typeof chunk !== "object") return undefined;
+  const value = (chunk as { value?: unknown }).value;
+  return Array.isArray(value) ? value.join("") : undefined;
 }
 
 function asColumn(chunk: unknown): string | undefined {
@@ -135,16 +346,8 @@ function asColumn(chunk: unknown): string | undefined {
   return typeof name === "string" && name.length > 0 ? name : undefined;
 }
 
-function asOperator(chunk: unknown): CompiledPredicate["op"] | undefined {
-  if (!chunk || typeof chunk !== "object") return undefined;
-  const value = (chunk as { value?: unknown }).value;
-  const text = Array.isArray(value)
-    ? value.join("")
-    : typeof value === "string"
-      ? value
-      : "";
-  const trimmed = text.trim();
-  switch (trimmed) {
+function asOperator(token: string): CompiledPredicate["op"] | undefined {
+  switch (token.toLowerCase()) {
     case "=":
       return "=";
     case "<":
@@ -158,18 +361,43 @@ function asOperator(chunk: unknown): CompiledPredicate["op"] | undefined {
     case "!=":
     case "<>":
       return "!=";
+    case "like":
+      return "like";
+    case "ilike":
+      return "ilike";
+    case "in":
+      return "in";
+    case "is null":
+      return "is null";
+    case "is not null":
+      return "is not null";
     default:
       return undefined;
   }
 }
 
-function asParam(chunk: unknown): unknown {
-  if (!chunk || typeof chunk !== "object") return undefined;
-  if (!("value" in (chunk as object))) return undefined;
-  // StringChunk also has `.value` (array of strings) — skip those.
-  if (Array.isArray((chunk as { value: unknown }).value)) return undefined;
-  if ((chunk as { name?: unknown }).name) return undefined;
-  return (chunk as { value: unknown }).value;
+/** Unwrap one element of a Drizzle `inArray` value array. */
+function asInArrayValue(item: unknown): unknown {
+  const param = asParamValue(item);
+  if (!param.found) {
+    throw new TypeError("sql where: unsupported in-list value");
+  }
+  return param.value;
+}
+
+/**
+ * Param values arrive either as Drizzle `Param` instances (wrapped by
+ * `bindIfParam`) or as raw primitives interpolated by `sql` templates
+ * (`like`, `ilike`, …).
+ */
+function asParamValue(chunk: unknown): { readonly found: boolean; readonly value?: unknown } {
+  if (chunk === undefined) return { found: false };
+  if (chunk === null || typeof chunk !== "object") return { found: true, value: chunk };
+  if (Array.isArray(chunk)) return { found: false };
+  if (!("value" in (chunk as object))) return { found: false };
+  if (Array.isArray((chunk as { value: unknown }).value)) return { found: false };
+  if ((chunk as { name?: unknown }).name) return { found: false };
+  return { found: true, value: (chunk as { value: unknown }).value };
 }
 
 /**

package/src/elements/store/sql-session.test.ts

@@ -0,0 +1,135 @@
+/**
+ * SqlStoreHandle surface lock — single-table SQL session only.
+ *
+ * Relational `with:` / Drizzle RQB (`db.query.*.findMany({ with })`) is a
+ * documented limitation: effects, cache keys, and PII masking assume one
+ * table per call, so no relational query surface may appear on the handle.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { and, desc, eq, like, lt, or } from "drizzle-orm";
+import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { sqliteDriver } from "../../drivers/sqlite.ts";
+import type { SqlConnection } from "../../drivers/types.ts";
+import { createSqlStoreHandle, type SqlStoreHandle } from "./sql-session.ts";
+
+const posts = sqliteTable("posts", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  createdAt: integer("created_at").notNull(),
+});
+
+async function openHandle(): Promise<{ handle: SqlStoreHandle; conn: SqlConnection }> {
+  const conn = await sqliteDriver.connect({
+    client: new Database(":memory:"),
+    role: "primary",
+  });
+  const handle = createSqlStoreHandle("sql:app", {
+    connection: conn,
+    classifications: new Map(),
+    routedRole: "primary",
+    domainDdl: "ensure",
+  });
+  return { handle, conn };
+}
+
+describe("SqlStoreHandle — no relational query surface (path b)", () => {
+  test("created handle exposes exactly the single-table surface", async () => {
+    const db = new Database(":memory:");
+    const conn = await sqliteDriver.connect({ client: db, role: "primary" });
+    const handle = createSqlStoreHandle("sql:app", {
+      connection: conn,
+      classifications: new Map(),
+      routedRole: "primary",
+      domainDdl: "ensure",
+    });
+
+    expect(Object.keys(handle).sort()).toEqual(
+      [
+        "ref",
+        "routedRole",
+        "driverId",
+        "select",
+        "insert",
+        "update",
+        "findById",
+        "delete",
+        "exists",
+        "increment",
+        "raw",
+        "count",
+        "page",
+        "ensureTable",
+      ].sort(),
+    );
+
+    // No Drizzle RQB / with: surface — ever.
+    expect("query" in handle).toBe(false);
+    expect("findMany" in handle).toBe(false);
+    expect("findFirst" in handle).toBe(false);
+    expect("with" in handle).toBe(false);
+
+    await conn.close();
+  });
+});
+
+describe("SqlStoreHandle — orderBy / limit select chain", () => {
+  test("orderBy + limit without where", async () => {
+    const { handle, conn } = await openHandle();
+    await handle.insert(posts).values({ id: "p1", title: "one", createdAt: 100 });
+    await handle.insert(posts).values({ id: "p2", title: "two", createdAt: 300 });
+    await handle.insert(posts).values({ id: "p3", title: "three", createdAt: 200 });
+
+    const rows = await handle.select().from(posts).orderBy(desc(posts.createdAt)).limit(2);
+    expect(rows.map((r) => r.id)).toEqual(["p2", "p3"]);
+    await conn.close();
+  });
+
+  test("limit directly on from() — no where required", async () => {
+    const { handle, conn } = await openHandle();
+    await handle.insert(posts).values({ id: "p1", title: "one", createdAt: 100 });
+    await handle.insert(posts).values({ id: "p2", title: "two", createdAt: 300 });
+
+    const rows = await handle.select().from(posts).limit(1);
+    expect(rows).toHaveLength(1);
+    await conn.close();
+  });
+
+  test("composite cursor predicate: where → orderBy → limit", async () => {
+    const { handle, conn } = await openHandle();
+    await handle.insert(posts).values({ id: "p1", title: "one", createdAt: 100 });
+    await handle.insert(posts).values({ id: "p2", title: "two", createdAt: 300 });
+    await handle.insert(posts).values({ id: "p3", title: "three", createdAt: 200 });
+    // Tie on createdAt=200 with an id that sorts after the cursor id.
+    await handle.insert(posts).values({ id: "p0", title: "four", createdAt: 200 });
+
+    const order = [desc(posts.createdAt), desc(posts.id)] as const;
+    const page1 = await handle
+      .select()
+      .from(posts)
+      .orderBy(...order)
+      .limit(2);
+    expect(page1.map((r) => r.id)).toEqual(["p2", "p3"]);
+
+    // (createdAt, id) < (200, "p3") — the second page of a keyset cursor.
+    const page2 = await handle
+      .select()
+      .from(posts)
+      .where(or(lt(posts.createdAt, 200), and(eq(posts.createdAt, 200), lt(posts.id, "p3"))))
+      .orderBy(...order)
+      .limit(2);
+    expect(page2.map((r) => r.id)).toEqual(["p0", "p1"]);
+    await conn.close();
+  });
+
+  test("like filters rows through the session (sqlite ASCII-insensitive)", async () => {
+    const { handle, conn } = await openHandle();
+    await handle.insert(posts).values({ id: "p1", title: "alpha", createdAt: 100 });
+    await handle.insert(posts).values({ id: "p2", title: "bravo", createdAt: 200 });
+
+    const rows = await handle.select().from(posts).where(like(posts.title, "A%"));
+    expect(rows.map((r) => r.id)).toEqual(["p1"]);
+    await conn.close();
+  });
+});