turbine-orm 0.5.0 → 0.7.0

package/dist/pipeline.js

@@ -1,5 +1,5 @@
 /**
- * @batadata/turbine — Pipeline execution
+ * turbine-orm — Pipeline execution
  *
  * Pipelines batch multiple independent queries into a single database round-trip.
  * Instead of N sequential awaits (N round-trips), you get 1 round-trip for all N queries.
@@ -15,6 +15,7 @@
  * we simulate it by running queries concurrently on a single connection or via
  * a multi-statement batch.
  */
+import { wrapPgError } from './errors.js';
 // ---------------------------------------------------------------------------
 // Pipeline executor
 // ---------------------------------------------------------------------------
@@ -52,7 +53,13 @@ export async function executePipeline(pool, queries) {
         // Future: use actual Postgres pipeline protocol for true pipelining.
         const results = [];
         for (const q of queries) {
-            const raw = await client.query(q.sql, q.params);
+            let raw;
+            try {
+                raw = await client.query(q.sql, q.params);
+            }
+            catch (err) {
+                throw wrapPgError(err);
+            }
             results.push(q.transform(raw));
         }
         await client.query('COMMIT');

package/dist/query.d.ts

@@ -1,11 +1,11 @@
 /**
- * @batadata/turbine — Query builder
+ * turbine-orm — Query builder
  *
  * Each table accessor (db.users, db.posts, etc.) returns a QueryInterface<T>
  * that builds parameterized SQL and executes it through the connection pool.
  *
  * Nested relations use json_build_object + json_agg subqueries for single-query
- * resolution — the technique that benchmarks proved 2-3x faster than Prisma.
+ * resolution — a PostgreSQL-native approach that eliminates N+1 query patterns.
  *
  * Schema-driven: all column names, types, and relations come from introspected
  * metadata — nothing is hardcoded.
@@ -61,10 +61,22 @@ export type WhereClause<T> = {
     /** Relation filters — keyed by relation name, value is { some, every, none } */
     [relationName: string]: unknown;
 };
+/**
+ * Unparameterized with clause — accepts any relation name.
+ * Used internally by the query builder at runtime.
+ */
 export interface WithClause {
     [relation: string]: true | WithOptions;
 }
-export interface WithOptions {
+/**
+ * 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.
+ */
+export type TypedWithClause<R extends object = {}> = [keyof R] extends [never] ? WithClause : {
+    [K in keyof R]?: true | WithOptions;
+};
+export interface WithOptions<_T = unknown> {
     with?: WithClause;
     where?: Record<string, unknown>;
     orderBy?: Record<string, OrderDirection>;
@@ -74,22 +86,34 @@ export interface WithOptions {
     /** Exclude these fields from the relation */
     omit?: Record<string, boolean>;
 }
-export interface FindUniqueArgs<T> {
+/**
+ * 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.
+ *
+ * @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 })
+ */
+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 interface FindUniqueArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>> {
     where: WhereClause<T>;
     select?: Record<string, boolean>;
     omit?: Record<string, boolean>;
-    with?: WithClause;
+    with?: W;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
 }
-export interface FindManyArgs<T> {
+export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>> {
     where?: WhereClause<T>;
     select?: Record<string, boolean>;
     omit?: Record<string, boolean>;
     orderBy?: Record<string, OrderDirection>;
     limit?: number;
     offset?: number;
-    with?: WithClause;
+    with?: W;
     /** Cursor-based pagination: start after this row */
     cursor?: Partial<T>;
     /** Number of records to take (used with cursor) */
@@ -99,6 +123,10 @@ export interface FindManyArgs<T> {
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
 }
+export interface FindManyStreamArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>> extends FindManyArgs<T, R, W> {
+    /** Number of rows to fetch per internal FETCH batch (default: 100) */
+    batchSize?: number;
+}
 export interface CreateArgs<T> {
     data: Partial<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
@@ -111,27 +139,71 @@ export interface CreateManyArgs<T> {
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
 }
+/**
+ * Atomic update operators for a field.
+ *
+ * `set` works on any type; `increment`, `decrement`, `multiply`, and `divide`
+ * are only valid on numeric fields. They generate SQL like
+ * `col = col + $n` (and the corresponding `-`, `*`, `/` variants) instead of
+ * plain absolute assignments, so they are safe against concurrent writers —
+ * the database performs the math atomically.
+ *
+ * @example
+ *   db.posts.update({ where: { id: 5 }, data: { viewCount: { increment: 1 } } });
+ */
+export type UpdateOperatorInput<V> = {
+    set: V;
+} | (V extends number ? {
+    increment: number;
+} : never) | (V extends number ? {
+    decrement: number;
+} : never) | (V extends number ? {
+    multiply: number;
+} : never) | (V extends number ? {
+    divide: number;
+} : never);
+/**
+ * Update data — each field can be a plain value or an atomic operator object.
+ * Back-compatible with `Partial<T>`: plain values still typecheck unchanged.
+ */
+export type UpdateInput<T> = {
+    [K in keyof T]?: T[K] | UpdateOperatorInput<T[K]>;
+};
 export interface UpdateArgs<T> {
     where: WhereClause<T>;
-    data: Partial<T>;
+    data: UpdateInput<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
+    /**
+     * Opt in to running this mutation when `where` resolves to an empty
+     * predicate (e.g. `{}` or `{ id: undefined }`). Default `false` — an
+     * empty predicate throws `ValidationError` to catch the common case of
+     * a filter value accidentally being `undefined`. Set this to `true` only
+     * when an unconditional mutation is the intended behaviour.
+     */
+    allowFullTableScan?: boolean;
 }
 export interface UpdateManyArgs<T> {
     where: WhereClause<T>;
-    data: Partial<T>;
+    data: UpdateInput<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
+    /** See {@link UpdateArgs.allowFullTableScan}. */
+    allowFullTableScan?: boolean;
 }
 export interface DeleteArgs<T> {
     where: WhereClause<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
+    /** See {@link UpdateArgs.allowFullTableScan}. */
+    allowFullTableScan?: boolean;
 }
 export interface DeleteManyArgs<T> {
     where: WhereClause<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
+    /** See {@link UpdateArgs.allowFullTableScan}. */
+    allowFullTableScan?: boolean;
 }
 export interface UpsertArgs<T> {
     where: WhereClause<T>;
@@ -158,8 +230,6 @@ export interface GroupByArgs<T> {
     _min?: Partial<Record<keyof T & string, boolean>>;
     /** Maximum value of fields in each group */
     _max?: Partial<Record<keyof T & string, boolean>>;
-    /** Having clause for filtering groups */
-    having?: Record<string, unknown>;
     /** Order groups */
     orderBy?: Record<string, OrderDirection>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
@@ -244,7 +314,7 @@ export interface QueryInterfaceOptions {
     /** Log a warning when findMany() is called without a limit */
     warnOnUnlimited?: boolean;
 }
-export declare class QueryInterface<T extends object> {
+export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly pool;
     private readonly table;
     private readonly schema;
@@ -261,6 +331,7 @@ export declare class QueryInterface<T extends object> {
     /**
      * Execute a pool.query with an optional timeout.
      * If timeout is set, races the query against a timer and rejects on expiry.
+     * pg driver errors are translated to typed Turbine errors via wrapPgError.
      */
     private queryWithTimeout;
     /**
@@ -273,21 +344,32 @@ export declare class QueryInterface<T extends object> {
      * To intercept queries before SQL generation, use the raw() method instead.
      */
     private executeWithMiddleware;
+    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>[]>;
+    buildFindMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T[]>;
     /**
-     * Generate a cache key for a query shape.
-     * Same where-keys + same with-clause = same SQL template.
+     * Stream rows from a findMany query using PostgreSQL cursors.
+     * Returns an AsyncIterable that yields individual rows, fetching in batches internally.
+     *
+     * Uses DECLARE CURSOR within a dedicated transaction on a single pooled connection.
+     * The cursor is automatically closed and the connection released when iteration
+     * completes or is terminated early (e.g. `break` from `for await`).
+     *
+     * @example
+     * ```ts
+     * for await (const user of db.users.findManyStream({ where: { orgId: 1 }, batchSize: 500 })) {
+     *   process.stdout.write(`${user.email}\n`);
+     * }
+     * ```
      */
-    private cacheKey;
-    findUnique(args: FindUniqueArgs<T>): Promise<T | null>;
-    buildFindUnique(args: FindUniqueArgs<T>): DeferredQuery<T | null>;
-    findMany(args?: FindManyArgs<T>): Promise<T[]>;
-    buildFindMany(args?: FindManyArgs<T>): DeferredQuery<T[]>;
-    findFirst(args?: FindManyArgs<T>): Promise<T | null>;
-    buildFindFirst(args?: FindManyArgs<T>): DeferredQuery<T | null>;
-    findFirstOrThrow(args?: FindManyArgs<T>): Promise<T>;
-    buildFindFirstOrThrow(args?: FindManyArgs<T>): DeferredQuery<T>;
-    findUniqueOrThrow(args: FindUniqueArgs<T>): Promise<T>;
-    buildFindUniqueOrThrow(args: FindUniqueArgs<T>): DeferredQuery<T>;
+    findManyStream<W extends TypedWithClause<R> = {}>(args?: FindManyStreamArgs<T, R, W>): AsyncGenerator<WithResult<T, R, W>, void, undefined>;
+    findFirst<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): Promise<WithResult<T, R, W> | null>;
+    buildFindFirst<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T | null>;
+    findFirstOrThrow<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): Promise<WithResult<T, R, W>>;
+    buildFindFirstOrThrow<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T>;
+    findUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): Promise<WithResult<T, R, W>>;
+    buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): DeferredQuery<T>;
     create(args: CreateArgs<T>): Promise<T>;
     buildCreate(args: CreateArgs<T>): DeferredQuery<T>;
     createMany(args: CreateManyArgs<T>): Promise<T[]>;
@@ -325,8 +407,33 @@ export declare class QueryInterface<T extends object> {
     private toColumn;
     /** Convert camelCase field name to a double-quoted SQL identifier */
     private toSqlColumn;
+    /**
+     * Build a single SET clause entry for update/updateMany.
+     *
+     * Supports plain values and atomic operator objects ({ set, increment,
+     * decrement, multiply, divide }). An operator object is detected ONLY when
+     * it has EXACTLY one key that is one of the 5 operator keys — this avoids
+     * misinterpreting JSON column values like `{ set: 'x' }` as operators
+     * (real operator objects always have exactly one key, and a plain JSON
+     * payload that happens to have a single `set` key is extremely unusual).
+     * Multi-key objects are always treated as plain (JSON) values.
+     *
+     * Returns the SQL fragment (e.g., `"view_count" = "view_count" + $3`) and
+     * pushes any required params onto the shared params array so that WHERE
+     * clause numbering continues correctly afterward.
+     */
+    private buildSetClause;
     /** Build WHERE clause from a where object (supports operators, NULL, OR) */
     private buildWhere;
+    /**
+     * Refuse mutations with an empty predicate unless explicitly opted in.
+     *
+     * An empty `where` (e.g. `{}` or `{ id: undefined }`) resolves to a
+     * mutation with no filter — a common footgun when a caller's filter
+     * value accidentally resolves to `undefined`. This guard throws
+     * `ValidationError` in that case unless `allowFullTableScan: true`.
+     */
+    private assertMutationHasPredicate;
     /**
      * Build the inner WHERE expression (without the WHERE keyword).
      * Returns null if no conditions exist.
@@ -355,24 +462,138 @@ export declare class QueryInterface<T extends object> {
     /** Parse a row that may contain JSON nested relation columns */
     private parseNestedRow;
     /**
-     * Build a SELECT clause with nested relation subqueries.
+     * Build a SELECT clause that includes both base columns and nested relation subqueries.
+     *
+     * For each relation specified in the `with` clause, this method generates a correlated
+     * subquery using PostgreSQL's `json_agg(json_build_object(...))` pattern. The result
+     * is a single SQL SELECT clause that resolves the full object tree in one query --
+     * no N+1 problem.
+     *
+     * **How it works:**
+     * 1. Resolves the base columns for the root table (all columns, or a subset via `columnsList`).
+     * 2. Iterates over each key in the `with` clause, looking up the relation definition.
+     * 3. For each relation, delegates to {@link buildRelationSubquery} to generate a
+     *    correlated subquery that returns JSON (array for hasMany, object for belongsTo/hasOne).
+     * 4. Each subquery is aliased as the relation name in the final SELECT.
      *
-     * Uses json_build_object + json_agg — the same approach as the raw-pg benchmark
-     * queries. Generates a single SQL statement that resolves the full object tree.
+     * **aliasCounter:** A shared `{ n: number }` object is passed through all nesting levels.
+     * Each call to `buildRelationSubquery` increments it to produce unique table aliases
+     * (`t0`, `t1`, `t2`, ...) across arbitrarily deep relation trees, preventing alias
+     * collisions in the generated SQL.
      *
-     * Nested where values are parameterized via the shared params array to prevent
-     * SQL injection.
+     * **Example output:**
+     * ```sql
+     * "users"."id", "users"."name", "users"."email",
+     * (SELECT COALESCE(json_agg(json_build_object('id', t0."id", 'title', t0."title")), '[]'::json)
+     *   FROM "posts" t0 WHERE t0."user_id" = "users"."id") AS "posts"
+     * ```
+     *
+     * @param table - The root table name (e.g. `"users"`).
+     * @param withClause - An object mapping relation names to their include specs
+     *                     (`true` for default inclusion, or `WithOptions` for select/omit/where/orderBy/limit).
+     * @param params - Shared parameter array for parameterized values (`$1`, `$2`, ...).
+     *                 Nested where/limit values are pushed here to prevent SQL injection.
+     * @param columnsList - Optional subset of columns to include in the SELECT. When `null`
+     *                      or omitted, all columns from the table's schema metadata are used.
+     * @param depth - Current nesting depth, passed through to {@link buildRelationSubquery}
+     *                for circular-relation detection. Defaults to `0` at the top level.
+     * @param path - Breadcrumb trail of relation names traversed so far, used in error
+     *               messages when circular or too-deep nesting is detected.
+     * @returns A complete SELECT clause string (without the `SELECT` keyword) containing
+     *          base columns and relation subqueries.
      */
     private buildSelectWithRelations;
     /**
-     * Build a json_agg subquery for a relation.
+     * Generate a correlated subquery that returns JSON for a single relation.
+     *
+     * This is the core of Turbine's single-query nested relation strategy. For a given
+     * relation (e.g. `posts` on a `users` query), it produces a self-contained SQL subquery
+     * that PostgreSQL evaluates per parent row, returning either a JSON array (hasMany) or
+     * a single JSON object (belongsTo / hasOne).
+     *
+     * ### Algorithm overview
+     *
+     * 1. **Alias generation:** Allocates a unique alias (`t0`, `t1`, ...) from the shared
+     *    `aliasCounter` so that deeply nested subqueries never collide.
+     *
+     * 2. **Column resolution:** Honors `select` / `omit` options to control which columns
+     *    appear in the output JSON.
+     *
+     * 3. **`json_build_object`:** Builds a JSON object for each row by mapping camelCase
+     *    field names to their column values:
+     *    ```sql
+     *    json_build_object('id', t0."id", 'title', t0."title", 'createdAt', t0."created_at")
+     *    ```
+     *
+     * 4. **`json_agg` wrapping (hasMany):** For one-to-many relations, wraps the
+     *    `json_build_object` call in `json_agg(...)` to aggregate all matching child rows
+     *    into a JSON array. Uses `COALESCE(..., '[]'::json)` so the result is never NULL.
+     *    For belongsTo / hasOne, no aggregation is used -- just the single JSON object
+     *    with `LIMIT 1`.
+     *
+     * 5. **Correlation (WHERE clause):** Links the subquery to the parent row:
+     *    - **hasMany:** `alias.foreignKey = parentRef.referenceKey`
+     *      (e.g. `t0."user_id" = "users"."id"` -- child FK points to parent PK)
+     *    - **belongsTo / hasOne:** `alias.referenceKey = parentRef.foreignKey`
+     *      (e.g. `t0."id" = "posts"."author_id"` -- parent FK points to child PK)
+     *
+     * 6. **Recursion:** If the spec includes a nested `with` clause, this method calls
+     *    itself recursively for each nested relation, passing the current alias as
+     *    `parentRef`. The nested subquery appears as an additional key in the
+     *    `json_build_object` call, wrapped in `COALESCE(..., '[]'::json)`.
+     *    Depth is incremented and capped at 10 to guard against circular relations.
+     *
+     * 7. **LIMIT / ORDER BY wrapping:** For hasMany relations with `limit` or `orderBy`,
+     *    the query is restructured into a two-level form:
+     *    ```sql
+     *    SELECT COALESCE(json_agg(json_build_object(...)), '[]'::json)
+     *    FROM (
+     *      SELECT t0.* FROM "posts" t0
+     *      WHERE t0."user_id" = "users"."id"
+     *      ORDER BY t0."created_at" DESC
+     *      LIMIT $1
+     *    ) t0i
+     *    ```
+     *    This ensures LIMIT and ORDER BY apply to the raw rows *before* `json_agg`
+     *    aggregation. Without the inner subquery, LIMIT would be meaningless because
+     *    `json_agg` produces a single aggregated row.
+     *
+     * 8. **Parameter threading:** All user-supplied values (where filters, limit) are
+     *    pushed to the shared `params` array with `$N` placeholders. No string
+     *    interpolation of user data ever occurs -- all identifiers go through
+     *    `quoteIdent()` and all values are parameterized.
      *
-     * All user-supplied values in nested where clauses are parameterized
-     * through the shared params array — no string interpolation.
+     * ### Example output (hasMany with nested relation)
+     * ```sql
+     * SELECT COALESCE(json_agg(json_build_object(
+     *   'id', t0."id",
+     *   'title', t0."title",
+     *   'comments', COALESCE((
+     *     SELECT COALESCE(json_agg(json_build_object('id', t1."id", 'body', t1."body")), '[]'::json)
+     *     FROM "comments" t1 WHERE t1."post_id" = t0."id"
+     *   ), '[]'::json)
+     * )), '[]'::json) FROM "posts" t0 WHERE t0."user_id" = "users"."id"
+     * ```
      *
-     * @param parentRef - The alias (or table name) of the parent in the outer query.
-     *                    Used for the correlated WHERE clause: `child.fk = parentRef.pk`.
-     * @param aliasCounter - Shared counter for generating unique aliases across nested levels.
+     * @param relDef - The relation definition from schema metadata (contains `to`, `type`,
+     *                 `foreignKey`, `referenceKey`).
+     * @param spec - Either `true` (include with defaults) or a `WithOptions` object that
+     *               can specify `select`, `omit`, `where`, `orderBy`, `limit`, and nested `with`.
+     * @param params - Shared parameter array. User-supplied values are pushed here and
+     *                 referenced as `$1`, `$2`, etc. in the generated SQL.
+     * @param parentRef - The alias (e.g. `"t0"`) or table name (e.g. `"users"`) of the
+     *                    parent query. Used to build the correlated WHERE clause that ties
+     *                    child rows to their parent row.
+     * @param aliasCounter - Shared mutable counter (`{ n: number }`) for generating unique
+     *                       table aliases (`t0`, `t1`, `t2`, ...) across all nesting levels.
+     *                       Each call increments `n` by 1.
+     * @param depth - Current nesting depth (starts at `0`). Incremented on each recursive
+     *                call. If it reaches 10, a {@link CircularRelationError} is thrown.
+     * @param path - Breadcrumb trail of relation/table names traversed so far
+     *               (e.g. `["users", "posts", "comments"]`). Used in the error message
+     *               when circular or too-deep nesting is detected.
+     * @returns A complete SQL subquery string (without surrounding parentheses) that
+     *          evaluates to a JSON array (hasMany) or a JSON object (belongsTo/hasOne).
      */
     private buildRelationSubquery;
     /**