@spooky-sync/query-builder 0.0.1-canary.7 → 0.0.1-canary.71

package/skills/sp00ky-query-builder/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: sp00ky-query-builder
+description: >-
+  Type-safe query builder for SurrealDB used by the Sp00ky framework. Use when
+  defining schemas (SchemaStructure), building queries with QueryBuilder, handling
+  relationships (one/many cardinality), or working with Sp00ky type helpers like
+  TableNames, GetTable, TableModel, and QueryResult.
+metadata:
+  author: sp00ky-sync
+  version: "0.0.1"
+---
+
+# Sp00ky Query Builder
+
+`@spooky-sync/query-builder` provides the type-safe schema definition format and query builder used throughout the Sp00ky framework.
+
+## Schema Definition
+
+Sp00ky schemas are defined as `const` objects satisfying `SchemaStructure`. They are typically generated by the Sp00ky CLI (`spooky generate`), but can be written by hand.
+
+```typescript
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+
+export const schema = {
+  tables: [
+    {
+      name: 'user',
+      columns: {
+        id: { type: 'string', optional: false },
+        email: { type: 'string', optional: false },
+        name: { type: 'string', optional: true },
+      },
+      primaryKey: ['id'],
+    },
+    {
+      name: 'post',
+      columns: {
+        id: { type: 'string', optional: false },
+        title: { type: 'string', optional: false },
+        body: { type: 'string', optional: false },
+        author: { type: 'string', optional: false, recordId: true },
+      },
+      primaryKey: ['id'],
+    },
+  ],
+  relationships: [
+    { from: 'post', field: 'author', to: 'user', cardinality: 'one' },
+    { from: 'user', field: 'posts', to: 'post', cardinality: 'many' },
+  ],
+  backends: {},
+} as const satisfies SchemaStructure;
+```
+
+### Column Types
+
+The `type` field maps to TypeScript types:
+
+| ValueType   | TypeScript Type |
+|-------------|-----------------|
+| `'string'`  | `string`        |
+| `'number'`  | `number`        |
+| `'boolean'` | `boolean`       |
+| `'null'`    | `null`          |
+| `'json'`    | `unknown`       |
+
+Set `optional: true` to make a field nullable (`T | null`).
+Set `recordId: true` to indicate a field stores a SurrealDB RecordId.
+
+## QueryBuilder API
+
+The `QueryBuilder` class provides a fluent, chainable API for constructing type-safe queries.
+
+```typescript
+import { QueryBuilder } from '@spooky-sync/query-builder';
+
+// Create a query builder for the "post" table
+const query = new QueryBuilder(schema, 'post')
+  .where({ author: 'user:alice' })
+  .select('id', 'title', 'body')
+  .orderBy('title', 'desc')
+  .limit(10)
+  .offset(0)
+  .related('author')
+  .build();
+```
+
+### Chain Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `where` | `.where(conditions)` | Filter by field values. String IDs are auto-parsed to RecordId. |
+| `select` | `.select(...fields)` | Pick specific fields. Can only be called once per query. |
+| `orderBy` | `.orderBy(field, 'asc' \| 'desc')` | Sort results. Default direction is `'asc'`. |
+| `limit` | `.limit(count)` | Limit the number of results. |
+| `offset` | `.offset(count)` | Skip the first N results. |
+| `one` | `.one()` | Return a single object instead of an array. Implicitly sets `limit(1)`. |
+| `related` | `.related(field, modifier?)` | Include related data via subquery. See [Relationships](#relationships). |
+| `build` | `.build()` | Finalize the query into a `FinalQuery` object. |
+
+### Relationships
+
+Use `.related()` to include related tables. Relationships must be declared in the schema.
+
+```typescript
+// One-to-one: post has one author
+new QueryBuilder(schema, 'post')
+  .related('author')
+  .build();
+
+// One-to-many: user has many posts
+new QueryBuilder(schema, 'user')
+  .related('posts')
+  .build();
+
+// Nested relationship with modifier
+new QueryBuilder(schema, 'user')
+  .related('posts', (q) => q.orderBy('title', 'asc').limit(5))
+  .build();
+```
+
+Cardinality is inferred from the schema. For `'one'` relationships, the result is an object. For `'many'`, it is an array.
+
+## Backend Schema
+
+The `backends` field in `SchemaStructure` defines available HTTP backends, their outbox tables, and typed routes. This is generated by `spooky generate` from your `sp00ky.yml` config and OpenAPI spec.
+
+### Schema Structure
+
+```typescript
+export interface SchemaStructure {
+  // ...tables, relationships...
+  readonly backends: Record<string, HTTPOutboxBackendDefinition>;
+}
+
+export interface HTTPOutboxBackendDefinition {
+  readonly outboxTable: string;  // The SurrealDB table used as the outbox (e.g., 'job')
+  readonly routes: Record<string, HTTPBackendRouteDefinition>;
+}
+
+export interface HTTPBackendRouteDefinition {
+  readonly args: Record<string, HTTPBackendRouteArgsDefinition>;
+}
+
+export interface HTTPBackendRouteArgsDefinition {
+  readonly type: ValueType;      // 'string' | 'number' | 'boolean' | 'null' | 'json'
+  readonly optional: boolean;
+}
+```
+
+### Generated Example
+
+Given a `sp00ky.yml` with an `api` backend and an OpenAPI spec defining a `/spookify` route with an `id` parameter, `spooky generate` produces:
+
+```typescript
+export const schema = {
+  // ...tables, relationships...
+  backends: {
+    "api": {
+      outboxTable: 'job' as const,
+      routes: {
+        "/spookify": {
+          args: {
+            "id": {
+              type: 'string' as const,
+              optional: false as const
+            },
+          }
+        },
+      }
+    },
+  },
+} as const satisfies SchemaStructure;
+```
+
+### Backend Type Helpers
+
+- `BackendNames<S>` — Union of all backend name strings (e.g., `'api'`)
+- `BackendRoutes<S, B>` — Union of all route paths for backend `B` (e.g., `'/spookify'`)
+- `RoutePayload<S, B, R>` — Typed payload object for route `R` on backend `B`. Required args become required fields, optional args become optional fields. Types are mapped from `ValueType` to TypeScript types.
+
+These types are used by `db.run()` to provide full type safety — backend name, route path, and payload are all checked at compile time.
+
+## Type Helpers
+
+See [references/type-helpers.md](references/type-helpers.md) for a full reference of all type utilities.
+
+Key types:
+
+- `TableNames<S>` — Union of all table name strings
+- `GetTable<S, Name>` — Extract a table definition by name
+- `TableModel<T>` — Convert a table's columns to a TypeScript object type
+- `QueryResult<S, TableName, RelatedFields, IsOne>` — The full result type including related fields
+- `BackendNames<S>`, `BackendRoutes<S, B>`, `RoutePayload<S, B, R>` — Backend/run type helpers
+
+## Common Pitfalls
+
+1. **String IDs are auto-converted**: When you pass `'user:alice'` in a `where()`, it is automatically parsed into a SurrealDB `RecordId`. If the string does not contain `:`, and the field is named `id`, the table name is prepended.
+
+2. **`select()` can only be called once**: Calling it twice throws an error. Combine all fields in one call.
+
+3. **Schema must use `as const satisfies SchemaStructure`**: Without `as const`, TypeScript cannot infer literal types for table names and relationships, and type safety is lost.

package/skills/sp00ky-query-builder/references/type-helpers.md

@@ -0,0 +1,80 @@
+# Type Helpers Reference
+
+## Schema Types
+
+### `SchemaStructure`
+
+The top-level schema interface:
+
+```typescript
+interface SchemaStructure {
+  readonly tables: readonly {
+    readonly name: string;
+    readonly columns: Record<string, ColumnSchema>;
+    readonly primaryKey: readonly string[];
+  }[];
+  readonly relationships: readonly {
+    readonly from: string;
+    readonly field: string;
+    readonly to: string;
+    readonly cardinality: 'one' | 'many';
+  }[];
+  readonly backends: Record<string, HTTPOutboxBackendDefinition>;
+  readonly access?: Record<string, AccessDefinition>;
+  readonly buckets?: readonly BucketDefinitionSchema[];
+}
+```
+
+### `ColumnSchema`
+
+```typescript
+interface ColumnSchema {
+  readonly type: 'string' | 'number' | 'boolean' | 'null' | 'json';
+  readonly optional: boolean;
+  readonly dateTime?: boolean;
+  readonly recordId?: boolean;
+}
+```
+
+## Table Type Helpers
+
+| Type | Description |
+|------|-------------|
+| `TableNames<S>` | Union of all table name strings from the schema |
+| `GetTable<S, Name>` | Extract a specific table definition by name |
+| `TableModel<T>` | Convert a table's `columns` record into a TypeScript object type |
+| `TableFieldNames<T>` | Union of all column names for a table |
+
+### Example
+
+```typescript
+type MySchema = typeof schema;
+type Tables = TableNames<MySchema>; // 'user' | 'post'
+type UserTable = GetTable<MySchema, 'user'>; // The user table definition
+type UserModel = TableModel<UserTable>; // { id: string; email: string; name: string | null }
+```
+
+## Relationship Type Helpers
+
+| Type | Description |
+|------|-------------|
+| `TableRelationships<S, TableName>` | All relationship definitions originating from a table |
+| `RelationshipFields<S, TableName>` | Union of relationship field names for a table |
+| `GetRelationship<S, TableName, Field>` | Get a specific relationship by table and field name |
+
+## Result Type Helpers
+
+| Type | Description |
+|------|-------------|
+| `QueryResult<S, TableName, RelatedFields, IsOne>` | The full query result type. If `IsOne` is `true`, returns a single object; otherwise an array. Includes related fields merged into the base model. |
+| `RelatedFieldsMap` | A record mapping field names to `{ to, cardinality, relatedFields }` |
+
+## Backend Type Helpers
+
+| Type | Description |
+|------|-------------|
+| `BackendNames<S>` | Union of all backend names |
+| `BackendRoutes<S, B>` | Union of all route paths for a backend |
+| `RoutePayload<S, B, R>` | The typed payload object for a specific route |
+| `BucketNames<S>` | Union of all bucket names |
+| `BucketConfig<S, B>` | Configuration for a specific bucket |

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');
@@ -270,11 +340,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 +463,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,7 @@ import type {
   RelatedQuery,
   SchemaAwareQueryModifier,
   SchemaAwareQueryModifierBuilder,
+  WhereInput,
 } from './types';
 import type {
   TableNames,
@@ -172,7 +173,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 +235,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 +301,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;
   }
@@ -412,7 +414,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;
@@ -641,6 +643,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 +754,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

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,25 @@
 /**
  * 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;
 }
 
 /**
@@ -62,6 +71,7 @@ export type TypeNameToTypeMap = {
   boolean: boolean;
   null: null;
   json: unknown;
+  Uint8Array: Uint8Array;
 };
 
 /**

package/src/types.ts

@@ -36,9 +36,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 +78,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 +109,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 +124,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 +170,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,