turbine-orm 0.7.0 → 0.7.1

package/dist/generate.js

@@ -60,8 +60,33 @@ function generatedFileHeader() {
         '',
     ];
 }
-function generateTypes(schema) {
+/**
+ * Generate the contents of `types.ts` (entity interfaces, *Create / *Update,
+ * and *Relations brand-field interfaces). Exported so tests can pin the
+ * generator output without writing files to disk.
+ */
+export function generateTypes(schema) {
     const lines = [...generatedFileHeader()];
+    // We import UpdateOperatorInput so generated *Update types can express
+    // atomic increment / decrement / multiply / divide / set operators on
+    // numeric columns (TASK-3.4).
+    //
+    // RelationDescriptor is the brand-field interface that lets `WithResult`
+    // recurse through nested `with` clauses at any depth. The generator emits
+    // each `*Relations` member as a `RelationDescriptor<Target, Cardinality,
+    // TargetRelations>` so users get full deep `with`-clause type inference
+    // out of the box (TASK-2.1).
+    lines.push("import type { RelationDescriptor, UpdateOperatorInput } from 'turbine-orm';");
+    lines.push('');
+    // Pre-compute which tables have relations so we know whether to thread
+    // `${TargetType}Relations` (for deep inference) or `{}` (the no-relations
+    // default) into each `RelationDescriptor`. Built once up-front because
+    // relations can point at tables we haven't iterated to yet.
+    const tablesWithRelations = new Set();
+    for (const t of Object.values(schema.tables)) {
+        if (Object.keys(t.relations).length > 0)
+            tablesWithRelations.add(t.name);
+    }
     // Generate enum types
     for (const [enumName, labels] of Object.entries(schema.enums)) {
         const typeName = snakeToPascal(enumName);
@@ -103,27 +128,33 @@ function generateTypes(schema) {
         lines.push('};');
         lines.push('');
         // --- Update input type (all fields optional except PK) ---
+        // Numeric columns additionally accept `UpdateOperatorInput<number>` so
+        // users can write `{ viewCount: { increment: 1 } }` without an `as any`.
         const nonPkCols = table.columns.filter((c) => !table.primaryKey.includes(c.name));
         lines.push(`/** Input type for updating a row in \`${table.name}\` */`);
         lines.push(`export type ${typeName}Update = {`);
         for (const col of nonPkCols) {
-            lines.push(`  ${col.field}?: ${col.tsType};`);
+            lines.push(`  ${col.field}?: ${updateFieldType(col.tsType)};`);
         }
         lines.push('};');
         lines.push('');
         // --- Relations map (for type-safe `with` clauses) ---
+        //
+        // Each relation is emitted as a `RelationDescriptor<Target, Cardinality,
+        // TargetRelations>` brand-field interface. This is what enables the
+        // recursive `WithResult` type to walk through nested `with` clauses at
+        // any depth — `RelationRelations<R[K]>` reads the third type parameter
+        // and threads it into the next recursion step. If the target table has
+        // no relations of its own, the descriptor uses `{}` (the default).
         const hasRelations = Object.keys(table.relations).length > 0;
         if (hasRelations) {
             lines.push(`/** Available relations for the \`${table.name}\` table */`);
             lines.push(`export interface ${typeName}Relations {`);
             for (const [relName, rel] of Object.entries(table.relations)) {
                 const targetType = entityName(rel.to);
-                if (rel.type === 'hasMany') {
-                    lines.push(`  ${relName}: ${targetType}[];`);
-                }
-                else {
-                    lines.push(`  ${relName}: ${targetType} | null;`);
-                }
+                const cardinality = rel.type === 'hasMany' ? "'many'" : "'one'";
+                const targetRelations = tablesWithRelations.has(rel.to) ? `${targetType}Relations` : '{}';
+                lines.push(`  ${relName}: RelationDescriptor<${targetType}, ${cardinality}, ${targetRelations}>;`);
             }
             lines.push('}');
             lines.push('');
@@ -227,8 +258,8 @@ function generateIndex(schema) {
     const tableEntries = Object.values(schema.tables);
     const lines = [
         ...generatedFileHeader(),
-        "import { TurbineClient as BaseTurbineClient, QueryInterface } from 'turbine-orm';",
-        "import type { TurbineConfig } from 'turbine-orm';",
+        "import { TurbineClient as BaseTurbineClient, TransactionClient as BaseTransactionClient, QueryInterface } from 'turbine-orm';",
+        "import type { TurbineConfig, TransactionOptions } from 'turbine-orm';",
         "import { SCHEMA } from './metadata.js';",
     ];
     // Import all entity types and relations maps
@@ -241,6 +272,41 @@ function generateIndex(schema) {
     }
     lines.push(`import type { ${typeImports.join(', ')} } from './types.js';`);
     lines.push('');
+    // -------------------------------------------------------------------------
+    // TypedTransactionClient — same typed table accessors as TurbineClient,
+    // but scoped to a single transaction connection. The runtime instance is
+    // an ordinary `TransactionClient` from turbine-orm; this declaration just
+    // teaches TypeScript about the auto-attached accessors so users get
+    // autocomplete inside `db.$transaction(async (tx) => tx.users.create(...))`.
+    // -------------------------------------------------------------------------
+    lines.push('/**');
+    lines.push(' * Transaction-scoped client with the same typed table accessors as TurbineClient.');
+    lines.push(' * Created automatically by `db.$transaction(async (tx) => ...)` — never instantiate');
+    lines.push(' * directly. All queries run on a dedicated connection within a BEGIN/COMMIT block.');
+    lines.push(' */');
+    lines.push('export class TypedTransactionClient extends BaseTransactionClient {');
+    for (const table of tableEntries) {
+        const typeName = entityName(table.name);
+        const accessor = snakeToCamelStr(table.name);
+        const hasRelations = Object.keys(table.relations).length > 0;
+        const genericArgs = hasRelations ? `${typeName}, ${typeName}Relations` : typeName;
+        lines.push(`  /** Query interface for the \`${table.name}\` table (transaction-scoped) */`);
+        lines.push(`  declare readonly ${accessor}: QueryInterface<${genericArgs}>;`);
+    }
+    lines.push('}');
+    lines.push('');
+    // Augment the class with a typed `$transaction` overload via interface
+    // merging. This adds an additional callable signature whose callback
+    // parameter is narrowed to `TypedTransactionClient`, while the base
+    // signature (callback parameter `BaseTransactionClient`) remains valid.
+    lines.push('export interface TypedTransactionClient {');
+    lines.push('  /**');
+    lines.push('   * Nested transaction via SAVEPOINT. The callback receives a typed');
+    lines.push('   * `TypedTransactionClient` so all table accessors auto-complete.');
+    lines.push('   */');
+    lines.push('  $transaction<R>(fn: (tx: TypedTransactionClient) => Promise<R>): Promise<R>;');
+    lines.push('}');
+    lines.push('');
     // Generate the client class with JSDoc
     lines.push('/**');
     lines.push(' * Generated Turbine client with typed table accessors.');
@@ -275,6 +341,22 @@ function generateIndex(schema) {
     lines.push('  }');
     lines.push('}');
     lines.push('');
+    // Augment TurbineClient via interface merging with a typed $transaction
+    // overload. The callback parameter is narrowed to `TypedTransactionClient`
+    // so users get autocomplete on `tx.users`, `tx.posts`, etc. The base
+    // signature (callback parameter `BaseTransactionClient`) remains valid as
+    // an overload, so prior usage continues to typecheck.
+    lines.push('export interface TurbineClient {');
+    lines.push('  /**');
+    lines.push('   * Run a callback inside a transaction. The callback receives a typed');
+    lines.push('   * `TypedTransactionClient` with autocompletion for every table accessor.');
+    lines.push('   */');
+    lines.push('  $transaction<R>(');
+    lines.push('    fn: (tx: TypedTransactionClient) => Promise<R>,');
+    lines.push('    options?: TransactionOptions,');
+    lines.push('  ): Promise<R>;');
+    lines.push('}');
+    lines.push('');
     // Factory function with JSDoc
     lines.push('/**');
     lines.push(' * Create a new Turbine client instance.');
@@ -316,4 +398,32 @@ function quoteIfNeeded(s) {
 function snakeToCamelStr(s) {
     return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
 }
+/**
+ * Build the update-input field type for a column. Numeric columns become
+ * `T | UpdateOperatorInput<number> | null?` so users can write atomic
+ * operators (`{ increment: 1 }`, `{ multiply: 2 }`, etc.) without casts.
+ *
+ * The check is purely structural — if the column's TS type contains
+ * `'number'` (e.g. `number`, `number | null`), it's eligible. Other
+ * scalar types (`string`, `boolean`, `Date`, `unknown`, `Buffer`,
+ * `Date | null`, etc.) pass through unchanged.
+ */
+function updateFieldType(tsType) {
+    // Strip parens for the regex check; preserve the original string in the output.
+    if (containsNumberType(tsType)) {
+        return `${tsType} | UpdateOperatorInput<number>`;
+    }
+    return tsType;
+}
+/**
+ * Detect whether a TypeScript type expression contains the `number` primitive
+ * as a top-level union member. Conservative on purpose — only matches
+ * `number`, `number | null`, `null | number`, etc., not `number[]` or
+ * `Record<string, number>`.
+ */
+function containsNumberType(tsType) {
+    // Tokenize on `|` and check each member.
+    const parts = tsType.split('|').map((p) => p.trim());
+    return parts.some((p) => p === 'number');
+}
 //# sourceMappingURL=generate.js.map

package/dist/index.d.ts

@@ -33,11 +33,11 @@
  * ```
  */
 export { type Middleware, type MiddlewareNext, type MiddlewareParams, type PgCompatPool, type PgCompatPoolClient, type PgCompatQueryResult, TransactionClient, type TransactionOptions, TurbineClient, type TurbineConfig, } from './client.js';
-export { CheckConstraintError, CircularRelationError, ConnectionError, ForeignKeyError, MigrationError, NotFoundError, NotNullViolationError, RelationError, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
+export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, type ErrorMessageMode, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
 export { type GenerateOptions, generate } from './generate.js';
 export { type IntrospectOptions, introspect } from './introspect.js';
 export { executePipeline, type PipelineResults } from './pipeline.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, type CountArgs, type CreateArgs, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GroupByArgs, type JsonFilter, type OrderDirection, QueryInterface, type RelationFilter, type TypedWithClause, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type WithClause, type WithOptions, type WithResult, } from './query.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, type CountArgs, type CreateArgs, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GroupByArgs, type JsonFilter, type OrderDirection, QueryInterface, type RelationDescriptor, type RelationFilter, type TypedWithClause, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type WithClause, type WithOptions, type WithResult, } from './query.js';
 export type { ColumnMetadata, IndexMetadata, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
 export { ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnType, type ColumnTypeName, column, defineSchema, type SchemaDef, type TableDef, table, } from './schema-builder.js';

package/dist/index.js

@@ -35,7 +35,7 @@
 // Client
 export { TransactionClient, TurbineClient, } from './client.js';
 // Error types
-export { CheckConstraintError, CircularRelationError, ConnectionError, ForeignKeyError, MigrationError, NotFoundError, NotNullViolationError, RelationError, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
+export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
 // Code generation
 export { generate } from './generate.js';
 // Introspection

package/dist/query.d.ts

@@ -72,12 +72,26 @@ export interface WithClause {
  * Relation-aware with clause. When R (the relations map) is provided,
  * only keys from R are autocompleted. Used in public method signatures
  * so the compiler can narrow the return type.
+ *
+ * For typed maps, each relation accepts either `true` (default include) or a
+ * {@link WithOptions} object whose nested `with` is keyed against the relation
+ * target's own relations interface — this is what enables deep
+ * `WithResult` inference.
  */
 export type TypedWithClause<R extends object = {}> = [keyof R] extends [never] ? WithClause : {
-    [K in keyof R]?: true | WithOptions;
+    [K in keyof R]?: true | WithOptions<RelationRelations<R[K]> & object>;
 };
-export interface WithOptions<_T = unknown> {
-    with?: WithClause;
+/**
+ * Options for an included relation.
+ *
+ * Generic over `NestedR` — the relations interface of the *target* entity —
+ * so the nested `with` clause is autocompleted with the correct relation keys
+ * and so {@link WithResult} can recursively infer the return type. Defaults to
+ * `{}` (no relation suggestions) for callers that use the unparameterized
+ * {@link WithClause}.
+ */
+export interface WithOptions<NestedR extends object = {}> {
+    with?: TypedWithClause<NestedR>;
     where?: Record<string, unknown>;
     orderBy?: Record<string, OrderDirection>;
     limit?: number;
@@ -86,18 +100,87 @@ export interface WithOptions<_T = unknown> {
     /** Exclude these fields from the relation */
     omit?: Record<string, boolean>;
 }
+/**
+ * A relation descriptor used by generated `*Relations` interfaces to make deep
+ * `with` clause inference work. It bundles three pieces of information that
+ * `WithResult` needs to recurse through nested relations:
+ *
+ *  - `__target`     — the target entity type (e.g. `Post`)
+ *  - `__cardinality`— `'many'` for hasMany, `'one'` for belongsTo / hasOne
+ *  - `__relations`  — the target entity's relations interface (for further recursion)
+ *
+ * **Generator contract (Track 3):** the code generator emits `*Relations`
+ * interfaces in the following shape so that `WithResult` can walk arbitrary
+ * nesting depth:
+ *
+ * ```ts
+ * export interface UserRelations {
+ *   posts:   RelationDescriptor<Post,    'many', PostRelations>;
+ *   profile: RelationDescriptor<Profile, 'one',  ProfileRelations>;
+ * }
+ * ```
+ *
+ * The brand fields are phantom — they exist only for type inference and have
+ * no runtime representation. The runtime always sees the parsed entity values
+ * (arrays for hasMany, single object or null for belongsTo / hasOne) — see the
+ * cardinality projection inside {@link WithResult}.
+ *
+ * **Backward compatibility:** legacy generated code emitted bare types
+ * (`posts: Post[]`, `profile: Profile | null`). `WithResult` still accepts that
+ * shape via a fallback branch — it just cannot recurse into nested `with` for
+ * those relations until the generator is updated.
+ *
+ * @typeParam Target      - The entity type the relation points at.
+ * @typeParam Cardinality - `'many'` (array) or `'one'` (single object | null).
+ * @typeParam Relations   - The target entity's own `*Relations` interface, or
+ *                          `{}` if the target has no relations of its own.
+ */
+export interface RelationDescriptor<Target, Cardinality extends 'one' | 'many', Relations extends object = {}> {
+    readonly __target?: Target;
+    readonly __cardinality?: Cardinality;
+    readonly __relations?: Relations;
+}
+/** Extract the target entity from a relation descriptor or bare relation type. */
+type RelationTarget<Rel> = Rel extends RelationDescriptor<infer Target, infer _C, infer _R> ? Target : Rel extends Array<infer Item> ? Item : Rel extends infer One | null ? One : Rel;
+/** Extract the target's relations map from a relation descriptor (or `{}` for bare types). */
+type RelationRelations<Rel> = Rel extends RelationDescriptor<infer _T, infer _C, infer R> ? R : {};
+/** Project the target type into its runtime shape (array for many, single for one). */
+type ApplyCardinality<Rel, Resolved> = Rel extends RelationDescriptor<infer _T, infer Cardinality, infer _R> ? Cardinality extends 'many' ? Resolved[] : Resolved | null : Rel extends Array<infer _Item> ? Resolved[] : Resolved | null;
 /**
  * Compute the result type when relations are included via `with`.
  *
- * - When R is the default ({}) or W is empty, resolves to plain T.
- * - When R is a real relations map and W specifies relation keys, merges matching
- *   relation types from R onto T.
+ * Recursively walks the `with` clause, looking up each relation in `R` and:
  *
- * @typeParam T - Base entity type (e.g. User)
- * @typeParam R - Relations map (e.g. { posts: Post[]; profile: Profile | null })
- * @typeParam W - The with clause object (e.g. { posts: true })
+ *  1. If the relation is included with `true` (or no nested `with`), the
+ *     relation's bare resolved type is grafted onto `T` (e.g. `posts: Post[]`).
+ *  2. If the relation is included with a nested `with: {...}`, the recursion
+ *     looks up the target entity's relations interface (via the
+ *     {@link RelationDescriptor} brand fields the generator emits) and
+ *     recursively applies `WithResult` to the nested target. Cardinality is
+ *     re-applied at each level so a hasMany relation stays an array even after
+ *     deep nesting.
+ *
+ * **When `R` is `{}` (the default):** the recursion short-circuits and the
+ * function returns plain `T` — preserving the existing untyped escape hatch
+ * for callers that have not generated typed clients.
+ *
+ * **When `R` does not contain the requested relations:** the unknown keys are
+ * ignored (the runtime will throw a `RelationError`, but the type system stays
+ * permissive so the legacy `WithClause` index signature still typechecks).
+ *
+ * @typeParam T - Base entity type (e.g. `User`).
+ * @typeParam R - Relations map for `T` (e.g.
+ *                `{ posts: RelationDescriptor<Post, 'many', PostRelations>; ... }`).
+ *                Legacy bare shapes (`{ posts: Post[]; profile: Profile | null }`)
+ *                are also accepted, but cannot recurse beyond one level.
+ * @typeParam W - The `with` clause the user passed (e.g. `{ posts: true }` or
+ *                `{ posts: { with: { comments: true } } }`).
  */
-export type WithResult<T, R extends object, W> = [keyof R] extends [never] ? T : [keyof W & keyof R] extends [never] ? T : T & Pick<R, keyof W & keyof R>;
+export type WithResult<T, R extends object, W> = [keyof R] extends [never] ? T : W extends object ? [keyof W & keyof R] extends [never] ? T : T & {
+    [K in keyof W & keyof R]: W[K] extends true ? ApplyCardinality<R[K], RelationTarget<R[K]>> : W[K] extends {
+        with?: infer NestedW;
+    } ? NestedW extends object ? ApplyCardinality<R[K], WithResult<RelationTarget<R[K]>, RelationRelations<R[K]> & object, NestedW>> : ApplyCardinality<R[K], RelationTarget<R[K]>> : ApplyCardinality<R[K], RelationTarget<R[K]>>;
+} : T;
 export interface FindUniqueArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>> {
     where: WhereClause<T>;
     select?: Record<string, boolean>;
@@ -311,7 +394,13 @@ type MiddlewareFn = (params: {
 export interface QueryInterfaceOptions {
     /** Default LIMIT applied to findMany() when no limit is specified */
     defaultLimit?: number;
-    /** Log a warning when findMany() is called without a limit */
+    /**
+     * Log a one-time warning when {@link QueryInterface.findMany} is called
+     * without a `limit`. Defaults to `true` so that accidental unbounded
+     * queries are surfaced loudly during development. Pass `false` to silence
+     * the warning entirely (e.g. for CLI tooling that intentionally streams
+     * full tables).
+     */
     warnOnUnlimited?: boolean;
 }
 export declare class QueryInterface<T extends object, R extends object = {}> {
@@ -324,10 +413,25 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly middlewares;
     private readonly defaultLimit?;
     private readonly warnOnUnlimited;
+    /**
+     * Tracks tables that have already triggered an unlimited-query warning so
+     * the user is not spammed once per row. Per-instance state — each
+     * QueryInterface is bound to a single table, so this set will only ever
+     * contain at most one entry, but using a Set keeps the API consistent with
+     * the audit's "Set<string>" guidance and leaves room for future
+     * cross-table sharing.
+     */
+    private readonly warnedTables;
     /** Pre-computed column type lookups (avoids linear scans per query) */
     private readonly columnPgTypeMap;
     private readonly columnArrayTypeMap;
     constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
+    /**
+     * Reset the per-instance unlimited-query warning dedupe set.
+     * Exposed for tests so a single test process can verify the warning fires
+     * exactly once per table without bleeding state between assertions.
+     */
+    resetUnlimitedWarnings(): void;
     /**
      * Execute a pool.query with an optional timeout.
      * If timeout is set, races the query against a timer and rejects on expiry.
@@ -347,6 +451,17 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     findUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): Promise<WithResult<T, R, W> | null>;
     buildFindUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): DeferredQuery<T | null>;
     findMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): Promise<WithResult<T, R, W>[]>;
+    /**
+     * Emit a one-time `console.warn` when {@link findMany} is called without an
+     * explicit `limit`/`take` and `warnOnUnlimited` has not been disabled.
+     *
+     * Deduped per QueryInterface instance via {@link warnedTables} so a busy
+     * loop calling `db.users.findMany()` thousands of times only logs once.
+     * Suppressed when `defaultLimit` is configured (the caller has already
+     * opted in to a bounded query) and when the user passed an explicit
+     * `limit`, `take`, or `cursor`.
+     */
+    private maybeWarnUnlimited;
     buildFindMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T[]>;
     /**
      * Stream rows from a findMany query using PostgreSQL cursors.

package/dist/query.js

@@ -71,6 +71,14 @@ function isWhereOperator(value) {
 const UPDATE_OPERATOR_KEYS = new Set(['set', 'increment', 'decrement', 'multiply', 'divide']);
 /** Known JSONB operator keys */
 const JSONB_OPERATOR_KEYS = new Set(['path', 'equals', 'contains', 'hasKey']);
+/**
+ * JSONB operator keys that are *unique* to {@link JsonFilter} — they cannot
+ * appear in any other where-filter shape, so the presence of one of these is
+ * an unambiguous signal that the user meant a JSON filter. Used by the
+ * strict-validation path so that `{ contains: 'foo' }` (which is also a valid
+ * `WhereOperator` for LIKE) is not misclassified.
+ */
+const JSONB_UNIQUE_KEYS = new Set(['path', 'equals', 'hasKey']);
 /** Check if a value is a JSONB filter object */
 function isJsonFilter(value) {
     if (value === null ||
@@ -83,8 +91,27 @@ function isJsonFilter(value) {
     const keys = Object.keys(value);
     return keys.length > 0 && keys.some((k) => JSONB_OPERATOR_KEYS.has(k));
 }
+/**
+ * Returns the first JSON-unique key found in `value`, or `null` if none.
+ * Used to drive the strict-validation error message.
+ */
+function findJsonUniqueKey(value) {
+    for (const k of Object.keys(value)) {
+        if (JSONB_UNIQUE_KEYS.has(k))
+            return k;
+    }
+    return null;
+}
 /** Known Array operator keys */
 const ARRAY_OPERATOR_KEYS = new Set(['has', 'hasEvery', 'hasSome', 'isEmpty']);
+/**
+ * Array operator keys that are *unique* to {@link ArrayFilter}. None of the
+ * array operators currently overlap with `WhereOperator` or `JsonFilter`, so
+ * this set equals {@link ARRAY_OPERATOR_KEYS}; it is kept as a separate
+ * constant so a future overlap (e.g. a `contains` for arrays) is easy to
+ * carve out.
+ */
+const ARRAY_UNIQUE_KEYS = new Set(['has', 'hasEvery', 'hasSome', 'isEmpty']);
 /** Check if a value is an Array filter object */
 function isArrayFilter(value) {
     if (value === null ||
@@ -97,6 +124,17 @@ function isArrayFilter(value) {
     const keys = Object.keys(value);
     return keys.length > 0 && keys.some((k) => ARRAY_OPERATOR_KEYS.has(k));
 }
+/**
+ * Returns the first array-unique key found in `value`, or `null` if none.
+ * Used to drive the strict-validation error message.
+ */
+function findArrayUniqueKey(value) {
+    for (const k of Object.keys(value)) {
+        if (ARRAY_UNIQUE_KEYS.has(k))
+            return k;
+    }
+    return null;
+}
 // ---------------------------------------------------------------------------
 // LRU cache — bounded SQL template cache to prevent memory leaks
 // ---------------------------------------------------------------------------
@@ -146,6 +184,15 @@ export class QueryInterface {
     middlewares;
     defaultLimit;
     warnOnUnlimited;
+    /**
+     * Tracks tables that have already triggered an unlimited-query warning so
+     * the user is not spammed once per row. Per-instance state — each
+     * QueryInterface is bound to a single table, so this set will only ever
+     * contain at most one entry, but using a Set keeps the API consistent with
+     * the audit's "Set<string>" guidance and leaves room for future
+     * cross-table sharing.
+     */
+    warnedTables = new Set();
     /** Pre-computed column type lookups (avoids linear scans per query) */
     columnPgTypeMap;
     columnArrayTypeMap;
@@ -160,7 +207,10 @@ export class QueryInterface {
         this.tableMeta = meta;
         this.middlewares = middlewares ?? [];
         this.defaultLimit = options?.defaultLimit;
-        this.warnOnUnlimited = options?.warnOnUnlimited ?? false;
+        // Default to ON: surfacing accidental full-table scans is more valuable
+        // than the (small) risk of noisy logs. Callers explicitly opt out with
+        // `warnOnUnlimited: false`.
+        this.warnOnUnlimited = options?.warnOnUnlimited !== false;
         // Pre-compute column type lookup maps (TASK-26)
         this.columnPgTypeMap = new Map();
         this.columnArrayTypeMap = new Map();
@@ -169,6 +219,14 @@ export class QueryInterface {
             this.columnArrayTypeMap.set(col.name, col.pgArrayType);
         }
     }
+    /**
+     * Reset the per-instance unlimited-query warning dedupe set.
+     * Exposed for tests so a single test process can verify the warning fires
+     * exactly once per table without bleeding state between assertions.
+     */
+    resetUnlimitedWarnings() {
+        this.warnedTables.clear();
+    }
     /**
      * Execute a pool.query with an optional timeout.
      * If timeout is set, races the query against a timer and rejects on expiry.
@@ -300,17 +358,37 @@ export class QueryInterface {
     // findMany
     // -------------------------------------------------------------------------
     async findMany(args) {
-        // Warn if no limit specified and warnOnUnlimited is enabled
-        const hasExplicitLimit = args?.limit !== undefined || args?.take !== undefined;
-        if (this.warnOnUnlimited && !hasExplicitLimit) {
-            console.warn(`[turbine] findMany() called without limit on table "${this.table}". Set defaultLimit in config to prevent unbounded queries.`);
-        }
+        this.maybeWarnUnlimited(args);
         return this.executeWithMiddleware('findMany', (args ?? {}), async () => {
             const deferred = this.buildFindMany(args);
             const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout);
             return deferred.transform(result);
         });
     }
+    /**
+     * Emit a one-time `console.warn` when {@link findMany} is called without an
+     * explicit `limit`/`take` and `warnOnUnlimited` has not been disabled.
+     *
+     * Deduped per QueryInterface instance via {@link warnedTables} so a busy
+     * loop calling `db.users.findMany()` thousands of times only logs once.
+     * Suppressed when `defaultLimit` is configured (the caller has already
+     * opted in to a bounded query) and when the user passed an explicit
+     * `limit`, `take`, or `cursor`.
+     */
+    maybeWarnUnlimited(args) {
+        if (!this.warnOnUnlimited)
+            return;
+        if (this.defaultLimit !== undefined)
+            return;
+        const hasExplicitLimit = args?.limit !== undefined || args?.take !== undefined || args?.cursor !== undefined;
+        if (hasExplicitLimit)
+            return;
+        if (this.warnedTables.has(this.table))
+            return;
+        this.warnedTables.add(this.table);
+        console.warn(`[turbine] warning: findMany on "${this.table}" has no limit — this will fetch every row. ` +
+            'Pass `limit` or set `warnOnUnlimited: false` in config to silence.');
+    }
     buildFindMany(args) {
         const { sql: whereSql, params } = args?.where ? this.buildWhere(args.where) : { sql: '', params: [] };
         const columnsList = this.resolveColumns(args?.select, args?.omit);
@@ -1261,6 +1339,16 @@ export class QueryInterface {
                     andClauses.push(...jsonClauses);
                     continue;
                 }
+                // Strict validation: a JSON-only operator on a non-JSON column was almost
+                // certainly a typo or schema mismatch. Silently falling through to plain
+                // equality (the previous behaviour) wasted hours of debugging time. Only
+                // throw when the operator is unambiguously JSON-specific — `contains` is
+                // shared with WhereOperator's LIKE so it must continue to fall through.
+                const jsonKey = findJsonUniqueKey(value);
+                if (jsonKey) {
+                    throw new ValidationError(`[turbine] Column "${rawColumn}" on table "${this.table}" is not a JSON column ` +
+                        `(actual type: ${colType}); cannot apply JSON operator '${jsonKey}'.`);
+                }
             }
             // Handle Array filter operators (for array columns)
             if (typeof value === 'object' && !Array.isArray(value) && isArrayFilter(value)) {
@@ -1270,6 +1358,14 @@ export class QueryInterface {
                     andClauses.push(...arrayClauses);
                     continue;
                 }
+                // Strict validation: array operators (`has`, `hasEvery`, ...) on a
+                // non-array column always indicate a mistake. None of these keys
+                // overlap with other filter shapes so we can throw unconditionally.
+                const arrayKey = findArrayUniqueKey(value);
+                if (arrayKey) {
+                    throw new ValidationError(`[turbine] Column "${rawColumn}" on table "${this.table}" is not an array column ` +
+                        `(actual type: ${colType}); cannot apply array operator '${arrayKey}'.`);
+                }
             }
             // Handle operator objects
             if (isWhereOperator(value)) {

package/dist/schema-builder.d.ts

@@ -56,17 +56,50 @@ export interface ColumnConfig {
     maxLength: number | null;
 }
 export interface TableDef {
-    /** Table name (set during defineSchema) */
+    /**
+     * DDL-facing table name (snake_case). This is the name used when generating
+     * `CREATE TABLE` and other DDL statements. Set automatically during
+     * `defineSchema()` by converting the JS-facing accessor key from camelCase
+     * to snake_case (e.g. `postTags` → `post_tags`).
+     */
     name: string;
+    /**
+     * JS-facing accessor name (camelCase). This is the original key the user
+     * supplied to `defineSchema({ ... })` and is used as the property name on
+     * the generated `TurbineClient` (e.g. `db.postTags`). For schemas that
+     * already use snake_case keys, this matches `name`.
+     */
+    accessor: string;
     /** Column definitions keyed by camelCase field name */
     columns: Record<string, ColumnConfig>;
+    /**
+     * Optional composite primary key. When present, takes precedence over any
+     * column-level `primaryKey: true` flags. Column names listed here are the
+     * camelCase JS-facing field names — they will be converted to snake_case
+     * when emitted as a `PRIMARY KEY (...)` table constraint.
+     */
+    primaryKey?: readonly string[];
+}
+/**
+ * User-facing input shape for a single table when using the object format.
+ * The optional `primaryKey` field declares a composite primary key.
+ */
+export interface TableInput {
+    /** Optional composite primary key (camelCase field names) */
+    primaryKey?: readonly string[];
+    /** Column definitions keyed by camelCase field name */
+    [columnName: string]: ColumnDef | readonly string[] | undefined;
 }
 export interface SchemaDef {
-    /** All tables keyed by table name */
+    /**
+     * All tables keyed by their JS-facing accessor name (camelCase, exactly as
+     * the user wrote them in `defineSchema({ ... })`). The DDL-facing snake_case
+     * name is available as `tables[key].name`.
+     */
     tables: Record<string, TableDef>;
 }
 /** Input format: table name -> column defs (object format) or TableDef (legacy builder) */
-type SchemaInput = Record<string, Record<string, ColumnDef> | TableDef>;
+type SchemaInput = Record<string, Record<string, ColumnDef> | TableDef | TableInput>;
 /**
  * Define the full database schema using plain objects.
  *