@spooky-sync/query-builder 0.0.1-canary.13 → 0.0.1-canary.131

package/src/query-builder.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, expectTypeOf } from 'vitest';
 import { QueryBuilder, buildQueryFromOptions } from './query-builder';
 import { RecordId } from 'surrealdb';
-import type { TableNames, TableModel, GetTable } from './table-schema';
+import type { TableModel } from './table-schema';
 
 // Schema for testing the new array-based API
 const testSchema = {
@@ -92,6 +92,76 @@ describe('QueryBuilder', () => {
     });
   });
 
+  it('should build a comparison operator condition via { _op, _val }', () => {
+    const builder = new QueryBuilder(testSchema, 'user', (q) => q.selectQuery);
+    builder.where({ created_at: { _op: '<=', _val: 5 } });
+    const result = builder.build().run();
+
+    expect(result.query).toBe('SELECT * FROM user WHERE created_at <= $created_at;');
+    expect(result.vars).toEqual({ created_at: 5 });
+  });
+
+  it('should build an OR group via _or with position-indexed params', () => {
+    const builder = new QueryBuilder(testSchema, 'user', (q) => q.selectQuery);
+    builder.where({ _or: [{ username: 'x' }, { email: 'x' }] });
+    const result = builder.build().run();
+
+    expect(result.query).toBe('SELECT * FROM user WHERE (username = $or0 OR email = $or1);');
+    expect(result.vars).toEqual({ or0: 'x', or1: 'x' });
+  });
+
+  it('should not collide an _or branch with a top-level condition on the same field', () => {
+    // Mirrors the game filter where a color filter (white = me) coexists with an
+    // opponent OR on white/black: the OR branch must use its own param name.
+    const builder = new QueryBuilder(testSchema, 'user', (q) => q.selectQuery);
+    builder.where({ username: 'me', _or: [{ username: 'opp' }, { email: 'opp' }] });
+    const result = builder.build().run();
+
+    expect(result.query).toBe(
+      'SELECT * FROM user WHERE username = $username AND (username = $or0 OR email = $or1);'
+    );
+    expect(result.vars).toEqual({ username: 'me', or0: 'opp', or1: 'opp' });
+  });
+
+  it('should combine equality + comparison + OR group + order/limit/offset', () => {
+    // The shape the filtered game list produces: scope equality, a date floor as
+    // an integer sort_index comparison, an opponent OR group, paginated.
+    const builder = new QueryBuilder(testSchema, 'user', (q) => q.selectQuery);
+    builder
+      .where({ email: 'e', created_at: { _op: '<=', _val: 5 }, _or: [{ username: 'p' }, { email: 'p' }] })
+      .orderBy('created_at', 'asc')
+      .limit(50)
+      .offset(0);
+    const result = builder.build().run();
+
+    expect(result.query).toBe(
+      'SELECT * FROM user WHERE email = $email AND created_at <= $created_at AND ' +
+        '(username = $or0 OR email = $or1) ORDER BY created_at asc LIMIT 50 START 0;'
+    );
+    expect(result.vars).toEqual({ email: 'e', created_at: 5, or0: 'p', or1: 'p' });
+  });
+
+  it('should produce a stable hash for the same logical filtered query', () => {
+    const make = () =>
+      new QueryBuilder(testSchema, 'user', (q) => q.selectQuery)
+        .where({ email: 'e', _or: [{ username: 'p' }, { email: 'p' }] })
+        .orderBy('created_at', 'asc')
+        .limit(50)
+        .offset(0)
+        .build()
+        .run();
+    expect(make().hash).toBe(make().hash);
+
+    const different = new QueryBuilder(testSchema, 'user', (q) => q.selectQuery)
+      .where({ email: 'e', _or: [{ username: 'q' }, { email: 'q' }] })
+      .orderBy('created_at', 'asc')
+      .limit(50)
+      .offset(0)
+      .build()
+      .run();
+    expect(different.hash).not.toBe(make().hash);
+  });
+
   it('should build query with select fields', () => {
     const builder = new QueryBuilder(testSchema, 'user', (q) => q.selectQuery);
     builder.select('username', 'email');
@@ -181,6 +251,23 @@ describe('Relationship Queries', () => {
       'SELECT *, (SELECT *, (SELECT * FROM user WHERE id=$parent.author LIMIT 1)[0] AS author FROM comment WHERE thread=$parent.id) AS comments FROM thread;'
     );
   });
+
+  // An unknown relationship (e.g. a table owned by a devOnly backend that a
+  // free/Cloudflare deployment never provisions, so codegen drops it from the
+  // client schema) must be SKIPPED, not throw — otherwise it takes the whole
+  // query (and its other `.related()` siblings) down. This is what left the
+  // ThreadDetail page stuck on "Loading..." when `jobs` disappeared.
+  it('skips an unknown relationship instead of throwing', () => {
+    const builder = new QueryBuilder(testSchema, 'thread', (q) => q.selectQuery);
+    expect(() => {
+      builder.related('author' as any);
+      builder.related('does_not_exist' as any); // must NOT throw
+    }).not.toThrow();
+    const result = builder.build().run();
+    // The valid relation is still projected; the unknown one is simply absent.
+    expect(result.query).toContain('AS author');
+    expect(result.query).not.toContain('does_not_exist');
+  });
 });
 
 describe('buildQueryFromOptions', () => {
@@ -270,11 +357,15 @@ describe('Edge Cases', () => {
 describe('Type Tests', () => {
   it('should enforce correct table names', () => {
     // Valid table names should work
+    // oxlint-disable-next-line no-new
     new QueryBuilder(testSchema, 'user');
+    // oxlint-disable-next-line no-new
     new QueryBuilder(testSchema, 'thread');
+    // oxlint-disable-next-line no-new
     new QueryBuilder(testSchema, 'comment');
 
     // @ts-expect-error - invalid table name should not compile
+    // oxlint-disable-next-line no-new
     new QueryBuilder(testSchema, 'invalid_table');
   });
 
@@ -389,9 +480,6 @@ describe('Type Tests', () => {
 });
 
 describe('Schema Metadata Integration', () => {
-  // Using testSchema from top-level scope
-  type TestSchemaMetadata = typeof testSchema;
-
   it('should accept testSchema in constructor', () => {
     const builder = new QueryBuilder(testSchema, 'thread', (q) => q.selectQuery);
 

package/src/query-builder.ts

@@ -7,6 +7,12 @@ import type {
   RelatedQuery,
   SchemaAwareQueryModifier,
   SchemaAwareQueryModifierBuilder,
+  WhereInput,
+  QueryPlan,
+  RelationPlan,
+  WhereNode,
+  WhereComparison,
+  ComparisonOp,
 } from './types';
 import type {
   TableNames,
@@ -172,7 +178,7 @@ export class InnerQuery<
 /**
  * Helper type to get the model type for a related table
  */
-type GetRelatedModel<S extends SchemaStructure, RelatedTableName extends string> =
+type _GetRelatedModel<S extends SchemaStructure, RelatedTableName extends string> =
   RelatedTableName extends TableNames<S> ? TableModel<GetTable<S, RelatedTableName>> : never;
 
 /**
@@ -234,6 +240,7 @@ export class FinalQuery<
   S extends SchemaStructure,
   TableName extends TableNames<S>,
   T extends { columns: Record<string, ColumnSchema> },
+  // oxlint-disable-next-line no-unused-vars -- RelatedFields is used externally for type inference
   RelatedFields extends RelatedFieldsMap,
   IsOne extends boolean,
   R = void,
@@ -299,7 +306,7 @@ class SchemaAwareQueryModifierBuilderImpl<
     private readonly schema: S
   ) {}
 
-  where(conditions: Partial<TableModel<GetTable<S, TableName>>>): this {
+  where(conditions: WhereInput<TableModel<GetTable<S, TableName>>>): this {
     this.options.where = { ...this.options.where, ...conditions };
     return this;
   }
@@ -365,9 +372,18 @@ class SchemaAwareQueryModifierBuilderImpl<
       );
 
       if (!relationship) {
-        throw new Error(
-          `Relationship '${String(relatedField)}' not found for table '${this.tableName}'`
-        );
+        // No such relationship in the client schema — e.g. a table owned by a
+        // devOnly backend (the outbox `job`) that a free/Cloudflare deployment
+        // never provisions, so codegen omits it + its relationships. Skip the
+        // projection instead of throwing, which would take the whole query
+        // (and its other `.related()` siblings — author, comments) down.
+        // Mirrors the server's "unpermitted subquery → empty" degradation.
+        if (typeof console !== 'undefined') {
+          console.warn(
+            `[sp00ky] .related('${String(relatedField)}') skipped — no such relationship on '${this.tableName}' in the client schema`
+          );
+        }
+        return this as any;
       }
 
       const relatedTable = relationship.to;
@@ -412,7 +428,7 @@ export class QueryBuilder<
    * Add additional where conditions
    */
   where(
-    conditions: Partial<TableModel<GetTable<S, TableName>>>
+    conditions: WhereInput<TableModel<GetTable<S, TableName>>>
   ): QueryBuilder<S, TableName, R, RelatedFields, IsOne> {
     this.options.where = { ...this.options.where, ...conditions };
     return this;
@@ -515,7 +531,15 @@ export class QueryBuilder<
     );
 
     if (!relationship) {
-      throw new Error(`Relationship '${String(field)}' not found for table '${this.tableName}'`);
+      // See the note on the other `.related()` overload: skip an unknown
+      // relationship (warn) rather than throwing, so a table absent from the
+      // client schema (e.g. the free-plan `job` outbox) can't crash the query.
+      if (typeof console !== 'undefined') {
+        console.warn(
+          `[sp00ky] .related('${String(field)}') skipped — no such relationship on '${this.tableName}' in the client schema`
+        );
+      }
+      return this as any;
     }
 
     // Determine cardinality and modifier based on arguments
@@ -641,6 +665,7 @@ export function extractSubqueryQueryInfos<S extends SchemaStructure>(
     if (relationship) {
       // Determine foreign key field
       // rel.alias is guaranteed to be defined if relationship is found (matched r.field)
+      // oxlint-disable-next-line no-non-null-assertion -- alias is guaranteed defined when relationship is found
       let foreignKeyField = rel.alias!;
 
       if (relationship.cardinality === 'many') {
@@ -751,32 +776,52 @@ export function buildQueryFromOptions<TModel extends GenericModel, IsOne extends
   const vars: Record<string, unknown> = {};
   if (parsedWhere && Object.keys(parsedWhere).length > 0) {
     const conditions: string[] = [];
-    for (const [key, value] of Object.entries(parsedWhere)) {
-      const varName = key;
 
-      // Handle operator objects { _op, _val }
+    // Build a single condition for `field`, binding its value under `varName`.
+    // Supports operator objects `{ _op, _val, _swap }` (e.g. `{ _op: '<=', _val:
+    // 5 }`); a `$`-prefixed string `_val` references an existing param verbatim.
+    // Plain values mean equality (`field = $varName`).
+    const buildCondition = (field: string, value: unknown, varName: string): string => {
       if (value && typeof value === 'object' && '_op' in value && '_val' in value) {
         const { _op, _val, _swap } = value as { _op: string; _val: unknown; _swap?: boolean };
-
-        let rightSide = '';
+        let rightSide: string;
         if (typeof _val === 'string' && _val.startsWith('$')) {
           rightSide = _val;
         } else {
           vars[varName] = _val;
           rightSide = `$${varName}`;
         }
+        return _swap ? `${rightSide} ${_op} ${field}` : `${field} ${_op} ${rightSide}`;
+      }
+      vars[varName] = value;
+      return `${field} = $${varName}`;
+    };
 
-        if (_swap) {
-          conditions.push(`${rightSide} ${_op} ${key}`);
-        } else {
-          conditions.push(`${key} ${_op} ${rightSide}`);
+    for (const [key, value] of Object.entries(parsedWhere)) {
+      // OR-group: `{ _or: [ {field: val}, {field: {_op,_val}}, ... ] }` compiles
+      // to one parenthesised `(c1 OR c2 ...)` conjunct. Each branch condition gets
+      // a unique, position-indexed param name (`or0`, `or1`, …) so it never
+      // collides with a top-level condition on the same field (e.g. a `white =
+      // $white` filter alongside an opponent `_or` on white/black) — keeping the
+      // surql + vars, and thus the query hash, stable and deterministic.
+      if (key === '_or' && Array.isArray(value)) {
+        const orParts: string[] = [];
+        let i = 0;
+        for (const branch of value) {
+          if (branch && typeof branch === 'object') {
+            for (const [bField, bVal] of Object.entries(branch as Record<string, unknown>)) {
+              orParts.push(buildCondition(bField, bVal, `or${i++}`));
+            }
+          }
         }
-      } else {
-        vars[varName] = value;
-        conditions.push(`${key} = $${varName}`);
+        if (orParts.length > 0) conditions.push(`(${orParts.join(' OR ')})`);
+        continue;
       }
+
+      conditions.push(buildCondition(key, value, key));
     }
-    query += ` WHERE ${conditions.join(' AND ')}`;
+
+    if (conditions.length > 0) query += ` WHERE ${conditions.join(' AND ')}`;
   }
 
   // Add PATCH for UPDATE
@@ -815,7 +860,167 @@ export function buildQueryFromOptions<TModel extends GenericModel, IsOne extends
       0
     ),
     vars: Object.keys(vars).length > 0 ? vars : undefined,
+    // Engine-neutral plan mirrors the SELECT above for non-SurrealQL backends.
+    // Only SELECT carries a plan; the isOne→limit=1 mutation above is already
+    // reflected in `options.limit`, so the plan sees it too.
+    plan: method === 'SELECT' ? buildQueryPlan(tableName, options, schema) : undefined,
+  };
+}
+
+/**
+ * Build the engine-neutral {@link QueryPlan} for a SELECT. Mirrors the string
+ * assembly in {@link buildQueryFromOptions} / {@link buildSubquery} exactly so a
+ * non-SurrealQL backend produces results identical to the SurrealQL path.
+ */
+function buildQueryPlan<TModel extends GenericModel, IsOne extends boolean>(
+  tableName: string,
+  options: QueryOptions<TModel, IsOne>,
+  schema: SchemaStructure
+): QueryPlan {
+  const plan: QueryPlan = { table: tableName };
+
+  if (options.select && options.select.length > 0 && !options.select.includes('*')) {
+    plan.select = options.select.filter((f) => f !== '*') as string[];
+  }
+
+  const parsedWhere = options.where
+    ? (parseObjectIdsToRecordId(options.where, tableName) as Record<string, unknown>)
+    : undefined;
+  if (parsedWhere && Object.keys(parsedWhere).length > 0) {
+    const nodes = buildWhereNodes(parsedWhere);
+    if (nodes.length > 0) plan.where = nodes;
+  }
+
+  if (options.orderBy && Object.keys(options.orderBy).length > 0) {
+    plan.orderBy = Object.entries(options.orderBy).map(
+      ([field, direction]) => [field, direction as 'asc' | 'desc']
+    );
+  }
+
+  if (options.limit !== undefined) plan.limit = options.limit;
+  if (options.offset !== undefined) plan.offset = options.offset;
+
+  if (options.related && options.related.length > 0) {
+    plan.relations = options.related.map((rel) => buildRelationPlan(rel, schema));
+  }
+
+  return plan;
+}
+
+/**
+ * Engine-neutral counterpart of {@link buildSubquery}. Resolves the same
+ * cardinality / foreign-key / nested-relation metadata but returns a structured
+ * {@link RelationPlan} instead of a SurrealQL subquery string.
+ */
+function buildRelationPlan(
+  rel: RelatedQuery & { foreignKeyField?: string },
+  schema: SchemaStructure
+): RelationPlan {
+  const { relatedTable, alias, modifier, cardinality } = rel;
+  // Same fallback chain as buildSubquery (`rel.foreignKeyField || alias`); the
+  // top-level foreignKeyField is already reverse-resolved by `.related()`.
+  const foreignKeyField = (rel.foreignKeyField || alias || relatedTable) as string;
+
+  const plan: RelationPlan = {
+    alias: (alias || relatedTable) as string,
+    table: relatedTable,
+    cardinality,
+    foreignKeyField,
   };
+
+  if (modifier) {
+    const modifierBuilder = new SchemaAwareQueryModifierBuilderImpl(relatedTable, schema);
+    modifier(modifierBuilder as any);
+    const subOptions = modifierBuilder._getOptions();
+
+    if (subOptions.select && subOptions.select.length > 0 && !subOptions.select.includes('*')) {
+      plan.select = subOptions.select.filter((f) => f !== '*') as string[];
+    }
+
+    if (subOptions.where && Object.keys(subOptions.where).length > 0) {
+      const parsedSubWhere = parseObjectIdsToRecordId(subOptions.where, relatedTable) as Record<
+        string,
+        unknown
+      >;
+      const nodes = buildWhereNodes(parsedSubWhere);
+      if (nodes.length > 0) plan.where = nodes;
+    }
+
+    if (subOptions.orderBy && Object.keys(subOptions.orderBy).length > 0) {
+      plan.orderBy = Object.entries(subOptions.orderBy).map(
+        ([field, direction]) => [field, direction as 'asc' | 'desc']
+      );
+    }
+
+    if (subOptions.limit !== undefined) plan.limit = subOptions.limit;
+
+    // Nested relations: re-resolve exactly as buildSubquery does — the child's
+    // foreignKeyField comes from the relatedTable-based lookup, not the reverse
+    // heuristic used for top-level relations.
+    if (subOptions.related && subOptions.related.length > 0) {
+      const resolvedNestedRels = subOptions.related.map((nestedRel) => {
+        const relationship = schema.relationships.find(
+          (r) => r.from === relatedTable && r.field === nestedRel.alias
+        );
+        if (relationship) {
+          const nestedForeignKeyField =
+            relationship.cardinality === 'many' ? relatedTable : (nestedRel.alias as string);
+          return {
+            ...nestedRel,
+            relatedTable: relationship.to,
+            cardinality: relationship.cardinality,
+            foreignKeyField: nestedForeignKeyField,
+          } as RelatedQuery & { foreignKeyField: string };
+        }
+        return nestedRel;
+      });
+      plan.relations = resolvedNestedRels.map((nestedRel) => buildRelationPlan(nestedRel, schema));
+    }
+  }
+
+  // one-to-one gets an implicit per-parent LIMIT 1 (matches buildSubquery).
+  if (cardinality === 'one' && plan.limit === undefined) {
+    plan.limit = 1;
+  }
+
+  return plan;
+}
+
+/**
+ * Convert a parsed WHERE object (string IDs already → RecordId) into the
+ * engine-neutral {@link WhereNode}[] conjunction. Mirrors the `_or` / comparison
+ * / equality handling in {@link buildQueryFromOptions}. A `$`-prefixed `_val`
+ * becomes a `paramRef` (with the leading `$` stripped).
+ */
+function buildWhereNodes(parsedWhere: Record<string, unknown>): WhereNode[] {
+  const toComparison = (field: string, value: unknown): WhereComparison => {
+    if (value && typeof value === 'object' && '_op' in value && '_val' in value) {
+      const { _op, _val, _swap } = value as ComparisonOp;
+      if (typeof _val === 'string' && _val.startsWith('$')) {
+        return { field, op: _op, value: undefined, paramRef: _val.slice(1), swap: _swap };
+      }
+      return { field, op: _op, value: _val, swap: _swap };
+    }
+    return { field, op: '=', value };
+  };
+
+  const nodes: WhereNode[] = [];
+  for (const [key, value] of Object.entries(parsedWhere)) {
+    if (key === '_or' && Array.isArray(value)) {
+      const or: WhereComparison[] = [];
+      for (const branch of value) {
+        if (branch && typeof branch === 'object') {
+          for (const [bField, bVal] of Object.entries(branch as Record<string, unknown>)) {
+            or.push(toComparison(bField, bVal));
+          }
+        }
+      }
+      if (or.length > 0) nodes.push({ or });
+      continue;
+    }
+    nodes.push(toComparison(key, value));
+  }
+  return nodes;
 }
 
 /**

package/src/repro_relationship.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { QueryBuilder, SchemaStructure } from './index';
+import { QueryBuilder } from './index';
 
 describe('QueryBuilder Relationship Inference', () => {
   const schema = {

package/src/table-schema.ts

@@ -1,16 +1,30 @@
 /**
  * Supported value types in the schema
  */
-export type ValueType = 'string' | 'number' | 'boolean' | 'null' | 'json';
+export type ValueType = 'string' | 'number' | 'boolean' | 'null' | 'json' | 'Uint8Array';
 
 /**
  * Column metadata defining the type and optionality of a field
  */
+/**
+ * CRDT types supported by Sp00ky's Loro integration
+ */
+export type CrdtType = 'text' | 'map' | 'list' | 'counter';
+
 export interface ColumnSchema {
   readonly type: ValueType;
   readonly optional: boolean;
   readonly dateTime?: boolean;
   readonly recordId?: boolean;
+  readonly crdt?: CrdtType;
+  readonly cursor?: boolean;
+  /** True for `TYPE bytes` columns. Runtime values are `Uint8Array`. */
+  readonly bytes?: boolean;
+  /**
+   * True for `TYPE array<...>` columns. `type` then names the ELEMENT type, so
+   * the runtime value is `ElementType[]` (e.g. `array<string>` → `string[]`).
+   */
+  readonly array?: boolean;
 }
 
 /**
@@ -62,16 +76,25 @@ export type TypeNameToTypeMap = {
   boolean: boolean;
   null: null;
   json: unknown;
+  Uint8Array: Uint8Array;
 };
 
+/**
+ * The element/base TS type of a column, wrapping in an array for `array: true`
+ * columns (where `type` names the element type).
+ */
+export type ColumnBaseTSType<T extends ColumnSchema> = T extends { array: true }
+  ? TypeNameToTypeMap[T['type']][]
+  : TypeNameToTypeMap[T['type']];
+
 /**
  * Convert a column type to its TypeScript type
  */
 export type ColumnToTSType<T extends ColumnSchema> = T extends {
   optional: true;
 }
-  ? TypeNameToTypeMap[T['type']] | null
-  : TypeNameToTypeMap[T['type']];
+  ? ColumnBaseTSType<T> | null
+  : ColumnBaseTSType<T>;
 
 /**
  * Helper to extract relationship field names for a table

package/src/types.ts

@@ -23,6 +23,79 @@ export interface QueryInfo {
   query: string;
   hash: number;
   vars?: Record<string, unknown>;
+  /**
+   * Engine-neutral description of the same SELECT, used by non-SurrealQL local
+   * cache backends (e.g. SQLite) that cannot parse the `query` string. Only
+   * populated for `SELECT` (undefined for LIVE/UPDATE/DELETE). See `QueryPlan`.
+   */
+  plan?: QueryPlan;
+}
+
+/**
+ * A single WHERE comparison. `value` is the resolved value (string IDs already
+ * converted to `RecordId`); when `paramRef` is set the condition references an
+ * existing query param verbatim (`$name`) instead of an inline value. `swap`
+ * flips the operands (`value op field`), mirroring `ComparisonOp._swap`.
+ */
+export interface WhereComparison {
+  field: string;
+  op: ComparisonOp['_op'];
+  value: unknown;
+  paramRef?: string;
+  swap?: boolean;
+}
+
+/** A parenthesised `(c1 OR c2 …)` group, from a `_or` fragment. */
+export interface WhereOr {
+  or: WhereComparison[];
+}
+
+/**
+ * Engine-neutral WHERE: a top-level conjunction (AND) of comparisons and/or
+ * OR-groups. Mirrors `buildQueryFromOptions`'s condition assembly exactly.
+ */
+export type WhereNode = WhereComparison | WhereOr;
+
+/**
+ * Engine-neutral description of a SELECT query. Backends render it to their own
+ * dialect (SurrealQL, SQLite, …). Relations are resolved by the caller via
+ * level-ordered decomposition rather than nested projection, so `relations`
+ * carries the tree rather than a flattened subquery string.
+ */
+export interface QueryPlan {
+  table: string;
+  /** Projection field names; undefined means all (`*`). */
+  select?: string[];
+  where?: WhereNode[];
+  orderBy?: [field: string, direction: 'asc' | 'desc'][];
+  limit?: number;
+  offset?: number;
+  relations?: RelationPlan[];
+  /**
+   * Window materialization: when set, the base rows are EXACTLY these record
+   * ids (the window the SSP already computed), ignoring `where`/`limit`/
+   * `offset`. `orderBy`, `select` and `relations` still apply. Set by
+   * {@link buildWindowMaterializationPlan}; see `window-query.ts`.
+   */
+  ids?: unknown[];
+}
+
+/**
+ * One `.related()` edge in a {@link QueryPlan}. Correlation:
+ * - `one`  → parent[`foreignKeyField`] = child.id  (attach `bucket[0] ?? null`)
+ * - `many` → child[`foreignKeyField`] = parent.id   (attach `bucket`)
+ * `limit`/`orderBy` are applied PER PARENT during decomposition.
+ */
+export interface RelationPlan {
+  alias: string;
+  table: string;
+  cardinality: 'one' | 'many';
+  foreignKeyField: string;
+  select?: string[];
+  where?: WhereNode[];
+  orderBy?: [field: string, direction: 'asc' | 'desc'][];
+  limit?: number;
+  relations?: RelationPlan[];
 }
 
 export interface RelatedQuery {
@@ -36,9 +109,40 @@ export interface RelatedQuery {
   cardinality: 'one' | 'many';
 }
 
+/**
+ * Comparison-operator descriptor for a single WHERE field, e.g.
+ * `{ _op: '<=', _val: 5 }` → `field <= $field`. A `$`-prefixed string `_val`
+ * references an existing query param verbatim; `_swap: true` flips the operands
+ * (`$val _op field`). Plain values still mean equality (`field = $field`).
+ */
+export interface ComparisonOp {
+  _op: '=' | '!=' | '>' | '>=' | '<' | '<=' | (string & {});
+  _val: unknown;
+  _swap?: boolean;
+}
+
+/** A single WHERE field value: an equality value or a comparison descriptor. */
+export type WhereFieldValue<V> = V | ComparisonOp;
+
+/** A flat conjunction of field conditions (equality or comparison). */
+export type WhereConditions<TModel extends GenericModel> = {
+  [K in keyof TModel]?: WhereFieldValue<TModel[K]>;
+};
+
+/**
+ * WHERE input for `.where()`. Supports equality (`{ field: value }`), comparison
+ * operators (`{ field: { _op, _val } }`), and a single top-level `_or` group of
+ * condition fragments that compile to a parenthesised `(... OR ...)` conjunct —
+ * e.g. `{ _or: [{ white: x }, { black: x }] }` → `(white = $or0 OR black = $or1)`.
+ * Backward-compatible with plain `Partial<TModel>` equality objects.
+ */
+export type WhereInput<TModel extends GenericModel> = WhereConditions<TModel> & {
+  _or?: WhereConditions<TModel>[];
+};
+
 export interface QueryOptions<TModel extends GenericModel, IsOne extends boolean> {
   select?: ((keyof TModel & string) | '*')[];
-  where?: Partial<TModel>;
+  where?: WhereInput<TModel>;
   limit?: number;
   offset?: number;
   orderBy?: Partial<Record<keyof TModel, 'asc' | 'desc'>>;
@@ -47,10 +151,10 @@ export interface QueryOptions<TModel extends GenericModel, IsOne extends boolean
   isOne?: IsOne;
 }
 
-export interface LiveQueryOptions<TModel extends GenericModel> extends Omit<
+export type LiveQueryOptions<TModel extends GenericModel> = Omit<
   QueryOptions<TModel, boolean>,
   'orderBy'
-> {}
+>;
 
 // Import schema types for schema-aware modifiers
 import type {
@@ -78,7 +182,7 @@ export type SchemaAwareQueryModifier<
 
 // Simplified query builder interface for modifying subqueries
 export interface QueryModifierBuilder<TModel extends GenericModel> {
-  where(conditions: Partial<TModel>): this;
+  where(conditions: WhereInput<TModel>): this;
   select(...fields: ((keyof TModel & string) | '*')[]): this;
   limit(count: number): this;
   offset(count: number): this;
@@ -93,7 +197,7 @@ export interface SchemaAwareQueryModifierBuilder<
   TableName extends TableNames<S>,
   RelatedFields extends Record<string, any> = {},
 > {
-  where(conditions: Partial<TableModel<GetTable<S, TableName>>>): this;
+  where(conditions: WhereInput<TableModel<GetTable<S, TableName>>>): this;
   select(...fields: ((keyof TableModel<GetTable<S, TableName>> & string) | '*')[]): this;
   limit(count: number): this;
   offset(count: number): this;
@@ -139,6 +243,7 @@ export type RelationshipFields<TModel extends GenericModel> = {
  * Simplified to directly access the nested structure
  */
 export type InferRelatedModelFromMetadata<
+  // oxlint-disable-next-line no-unused-vars -- Schema is used as a generic constraint
   Schema extends GenericSchema,
   TableName extends string,
   FieldName extends string,