turbine-orm 0.27.0 → 0.28.0

package/dist/client.js

@@ -68,6 +68,29 @@ const ISOLATION_LEVELS = {
  * rejecting loudly before it reaches the database.
  */
 const GUC_NAME_REGEX = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
+/**
+ * The read-only `QueryInterface` operations that a read-replica setup may route
+ * to a replica pool. Every other method (all writes, plus internals) stays on
+ * the primary. Kept as a Set so the routing proxy's `get` trap is O(1).
+ */
+const READ_OPERATIONS = new Set([
+    'findMany',
+    'findFirst',
+    'findUnique',
+    'findFirstOrThrow',
+    'findUniqueOrThrow',
+    'count',
+    'aggregate',
+    'groupBy',
+    'findManyStream',
+]);
+/**
+ * Internal marker on the config object that tells the `TurbineClient`
+ * constructor to build a lightweight "primary-only" view sharing an existing
+ * client's primary pool, dialect, query options, and middleware — instead of
+ * creating a fresh pool. Produced solely by `$primary()`; never public.
+ */
+const PRIMARY_VIEW = Symbol('turbine.primaryView');
 // ---------------------------------------------------------------------------
 // TransactionClient — provides typed table accessors within a transaction
 // ---------------------------------------------------------------------------
@@ -210,7 +233,55 @@ export class TurbineClient {
     ownsPool = true;
     /** Active LISTEN subscriptions — torn down on disconnect() so it never hangs */
     activeSubscriptions = new Set();
+    /**
+     * Read-replica pools in round-robin order. Empty when no replicas are
+     * configured, in which case `table()` takes the original single-pool path.
+     */
+    replicaPools;
+    /**
+     * The subset of {@link replicaPools} that Turbine created from connection
+     * strings and must close on `disconnect()`. External replica pools are not
+     * listed here (caller owns their lifecycle).
+     */
+    ownedReplicaPools;
+    /** Rotating index for round-robin replica selection (advances per read op). */
+    replicaCursor = 0;
+    /** Per-replica `table → QueryInterface` caches, indexed like {@link replicaPools}. */
+    replicaTableCaches;
+    /** Cache of per-table routing proxies (only used when replicas are present). */
+    routingProxyCache = new Map();
+    /** Lazily-built, cached primary-only view returned by {@link $primary}. */
+    primaryView;
     constructor(config = {}, schema) {
+        // Primary-only view: $primary() constructs this to share the parent's
+        // primary pool + derived state instead of creating a fresh pool. It owns
+        // no pool and no replicas, so every operation (reads included) runs on the
+        // primary and disconnect() is a no-op on the shared pool.
+        const seed = config[PRIMARY_VIEW];
+        if (seed) {
+            const parent = seed.parent;
+            this.schema = schema;
+            this.logging = parent.logging;
+            this.dialect = parent.dialect;
+            this.errorMessagesSafe = parent.errorMessagesSafe;
+            this.queryOptions = parent.queryOptions;
+            this.middlewares = parent.middlewares; // shared reference: $use on parent flows through
+            this.pool = parent.pool;
+            this.ownsPool = false;
+            this.replicaPools = [];
+            this.ownedReplicaPools = [];
+            this.replicaTableCaches = [];
+            for (const tableName of Object.keys(schema.tables)) {
+                const camelName = tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+                if (!(camelName in this)) {
+                    Object.defineProperty(this, camelName, {
+                        get: () => this.table(tableName),
+                        enumerable: true,
+                    });
+                }
+            }
+            return;
+        }
         // Constructing without schema metadata previously crashed deep in the
         // constructor with an opaque "Cannot read properties of undefined
         // (reading 'tables')". Fail fast with an actionable message instead.
@@ -234,11 +305,16 @@ export class TurbineClient {
          * of returning a string is correct and matches the generated TypeScript type
          * (numeric → string). Users who want number can cast explicitly in SQL.
          */
-        // Only register the int8 parser when we own the pg driver. External
-        // pools (Neon HTTP, Vercel Postgres) may ship their own pg-types fork
-        // and rely on their own parser configuration — don't mutate global state
-        // we don't own.
-        if (!config.pool && !TurbineClient.int8ParserRegistered) {
+        // Only register the int8 parser when the PRIMARY pool is Turbine-owned.
+        // External pools (Neon HTTP, Vercel Postgres) may ship their own pg-types
+        // fork and rely on their own parser configuration — registration is
+        // process-global, so flipping it because a string replica exists alongside
+        // an external primary would silently change the external primary's parsing
+        // too. String replicas configured next to an external primary therefore
+        // inherit the caller's parser configuration (documented). Registration is
+        // constructor-gated by the static flags, so it happens at most once.
+        const ownsAnyPool = !config.pool;
+        if (ownsAnyPool && !TurbineClient.int8ParserRegistered) {
             pg.types.setTypeParser(20, (val) => {
                 const n = Number(val);
                 return Number.isSafeInteger(n) ? n : val;
@@ -251,7 +327,7 @@ export class TurbineClient {
         // ORM convention (Prisma, Rails, Django) — and the only interpretation
         // that round-trips what Postgres stores — is UTC. Same ownership rule as
         // the int8 parser: never mutate parser state on external pools.
-        if (!config.pool && config.utcTimestamps !== false && !TurbineClient.utcTimestampParserRegistered) {
+        if (ownsAnyPool && config.utcTimestamps !== false && !TurbineClient.utcTimestampParserRegistered) {
             pg.types.setTypeParser(1114, (val) => new Date(`${val.replace(' ', 'T')}Z`));
             TurbineClient.utcTimestampParserRegistered = true;
         }
@@ -267,6 +343,7 @@ export class TurbineClient {
             utcTimestamps: config.utcTimestamps,
             relationLoadStrategy: config.relationLoadStrategy,
             jsonEncoding: config.jsonEncoding,
+            globalFilters: config.globalFilters,
             preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),
             sqlCache: config.sqlCache ?? true,
             dialect: config.dialect,
@@ -331,6 +408,34 @@ export class TurbineClient {
                 console.log(`[turbine] Pool created — max ${poolConfig.max} connections, ${Object.keys(schema.tables).length} tables`);
             }
         }
+        // Build read-replica pools (if any). String entries become owned pg.Pools
+        // sharing the primary's tuning knobs; PgCompatPool entries are external and
+        // used as-is. Replica selection is round-robin in this array order.
+        this.replicaPools = [];
+        this.ownedReplicaPools = [];
+        for (const replica of config.replicas ?? []) {
+            if (typeof replica === 'string') {
+                const replicaPool = new pg.Pool({
+                    connectionString: replica,
+                    max: config.poolSize ?? 10,
+                    idleTimeoutMillis: config.idleTimeoutMs ?? 30_000,
+                    connectionTimeoutMillis: config.connectionTimeoutMs ?? 5_000,
+                    ...(config.ssl !== undefined ? { ssl: config.ssl } : {}),
+                });
+                replicaPool.on('error', (err) => {
+                    console.error('[turbine] Unexpected replica pool error:', err.message);
+                });
+                this.replicaPools.push(replicaPool);
+                this.ownedReplicaPools.push(replicaPool);
+            }
+            else {
+                this.replicaPools.push(replica);
+            }
+        }
+        this.replicaTableCaches = this.replicaPools.map(() => new Map());
+        if (this.logging && this.replicaPools.length > 0) {
+            console.log(`[turbine] ${this.replicaPools.length} read replica(s) configured (${this.ownedReplicaPools.length} owned)`);
+        }
         // Auto-create typed table accessors for all tables in the schema
         for (const tableName of Object.keys(schema.tables)) {
             const camelName = tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
@@ -382,8 +487,14 @@ export class TurbineClient {
      */
     $use(middleware) {
         this.middlewares.push(middleware);
-        // Clear table cache so new QueryInterfaces pick up the middleware
+        // Clear table caches so new QueryInterfaces pick up the middleware. Covers
+        // the primary cache plus, when replicas are configured, the routing proxies
+        // and per-replica caches. The primary-view (if built) shares the middleware
+        // array by reference, so its QueryInterfaces observe the new middleware too.
         this.tableCache.clear();
+        this.routingProxyCache.clear();
+        for (const cache of this.replicaTableCaches)
+            cache.clear();
     }
     // -------------------------------------------------------------------------
     // Event emitter — subscribe to query lifecycle events
@@ -422,17 +533,110 @@ export class TurbineClient {
     /**
      * Get a QueryInterface for a table.
      * Results are cached — calling `table('users')` twice returns the same instance.
+     *
+     * When read replicas are configured, this returns a thin routing proxy: the
+     * read-only operations in {@link READ_OPERATIONS} are dispatched to a
+     * round-robin replica-bound QueryInterface (so an entire read — base rows and
+     * any batched sub-queries — runs against a single consistent replica), while
+     * writes and every other member fall through to the primary-bound instance.
+     * With no replicas the original single-pool instance is returned directly.
      */
     table(name) {
+        if (this.replicaPools.length === 0) {
+            return this.primaryTableQI(name);
+        }
+        let proxy = this.routingProxyCache.get(name);
+        if (!proxy) {
+            proxy = this.createRoutingAccessor(name);
+            this.routingProxyCache.set(name, proxy);
+        }
+        return proxy;
+    }
+    /** Get (and cache) the primary-pool-bound QueryInterface for a table. */
+    primaryTableQI(name) {
         let qi = this.tableCache.get(name);
         if (!qi) {
-            qi = this.queryOptions?.queryInterfaceFactory
-                ? this.queryOptions.queryInterfaceFactory(this.pool, name, this.schema, this.middlewares, this.queryOptions)
-                : new QueryInterface(this.pool, name, this.schema, this.middlewares, this.queryOptions);
+            qi = this.buildTableQI(this.pool, name);
             this.tableCache.set(name, qi);
         }
         return qi;
     }
+    /**
+     * Advance the round-robin cursor and return the QueryInterface bound to the
+     * selected replica pool for `name` (cached per replica).
+     */
+    nextReplicaTableQI(name) {
+        const index = this.replicaCursor % this.replicaPools.length;
+        // Reset before overflow so the cursor never grows unbounded.
+        this.replicaCursor = this.replicaCursor + 1 >= Number.MAX_SAFE_INTEGER ? 0 : this.replicaCursor + 1;
+        // index is always in-bounds (`% length`); the pools/cache entries exist.
+        const cache = this.replicaTableCaches[index];
+        const pool = this.replicaPools[index];
+        let qi = cache.get(name);
+        if (!qi) {
+            qi = this.buildTableQI(pool, name);
+            cache.set(name, qi);
+        }
+        return qi;
+    }
+    /** Construct a QueryInterface bound to `pool` (honoring any injected factory). */
+    buildTableQI(pool, name) {
+        const asPgPool = pool;
+        return this.queryOptions?.queryInterfaceFactory
+            ? this.queryOptions.queryInterfaceFactory(asPgPool, name, this.schema, this.middlewares, this.queryOptions)
+            : new QueryInterface(asPgPool, name, this.schema, this.middlewares, this.queryOptions);
+    }
+    /**
+     * Build the read/write routing proxy for a table. The proxy targets the
+     * primary QueryInterface (so writes, `build*`, and every non-read member work
+     * unchanged); read operations are intercepted and dispatched to a replica.
+     */
+    createRoutingAccessor(name) {
+        const primaryQI = this.primaryTableQI(name);
+        const client = this;
+        return new Proxy(primaryQI, {
+            get(target, prop, receiver) {
+                if (typeof prop === 'string' && READ_OPERATIONS.has(prop)) {
+                    // Pick the replica at CALL time so round-robin advances per operation.
+                    return (...args) => {
+                        const replicaQI = client.nextReplicaTableQI(name);
+                        const method = replicaQI[prop];
+                        if (typeof method !== 'function') {
+                            return Reflect.get(target, prop, receiver);
+                        }
+                        return method.apply(replicaQI, args);
+                    };
+                }
+                return Reflect.get(target, prop, receiver);
+            },
+        });
+    }
+    /**
+     * Return a view of this client that pins EVERY operation — reads included —
+     * to the primary pool, bypassing replica routing. Use it to read your own
+     * write without replication lag, or for any read that must see the latest
+     * committed data.
+     *
+     * The view shares the primary pool, schema, dialect, query options, and
+     * middleware; it owns nothing, so its `disconnect()` is a no-op. When no
+     * replicas are configured this simply returns the client itself (already
+     * primary-only). The view is cached — repeated calls return the same instance.
+     *
+     * @example
+     * ```ts
+     * await db.users.create({ data: { email: 'a@b.com' } });
+     * // Read-after-write: guaranteed to see the row just inserted.
+     * const user = await db.$primary().users.findFirst({ where: { email: 'a@b.com' } });
+     * ```
+     */
+    $primary() {
+        if (this.replicaPools.length === 0)
+            return this;
+        if (!this.primaryView) {
+            this.primaryView = new TurbineClient({ [PRIMARY_VIEW]: { parent: this } }, this.schema);
+        }
+        return this.primaryView;
+    }
     // -------------------------------------------------------------------------
     // Pipeline — batch multiple queries into one round-trip
     // -------------------------------------------------------------------------
@@ -573,29 +777,13 @@ export class TurbineClient {
             client.release();
         }
     }
-    // -------------------------------------------------------------------------
-    // $transaction — Prisma-style typed transaction API
-    // -------------------------------------------------------------------------
-    /**
-     * Execute a function within a database transaction with full typed table accessors.
-     *
-     * The `tx` object provides the same table accessor API as the main client.
-     * Supports nested transactions via SAVEPOINTs, timeouts, and isolation levels.
-     *
-     * @example
-     * ```ts
-     * await db.$transaction(async (tx) => {
-     *   const user = await tx.users.create({ data: { email: 'a@b.com' } });
-     *   await tx.posts.create({ data: { userId: user.id, title: 'Hello' } });
-     * });
-     *
-     * // With options:
-     * await db.$transaction(async (tx) => {
-     *   // ...
-     * }, { timeout: 5000, isolationLevel: 'Serializable' });
-     * ```
-     */
-    async $transaction(fn, options) {
+    async $transaction(fnOrQueries, options) {
+        // Batch overload: an array of DeferredQuery objects runs atomically inside
+        // one BEGIN…COMMIT, reusing the raw transaction machinery below.
+        if (Array.isArray(fnOrQueries)) {
+            return this.transactionBatch(fnOrQueries);
+        }
+        const fn = fnOrQueries;
         const client = await this.pool.connect();
         const timeout = options?.timeout;
         /**
@@ -711,6 +899,38 @@ export class TurbineClient {
             releaseOnce();
         }
     }
+    /**
+     * Execute a batch of {@link DeferredQuery} objects atomically inside one
+     * transaction. Backs the `$transaction([...])` array overload. Reuses the raw
+     * {@link transaction} machinery (BEGIN/COMMIT/ROLLBACK + connection release);
+     * queries run sequentially on the single transaction connection and each
+     * result is passed through its query's `transform`.
+     */
+    async transactionBatch(queries) {
+        if (queries.length === 0) {
+            return [];
+        }
+        return this.transaction(async (client) => {
+            const results = [];
+            for (const dq of queries) {
+                let raw;
+                try {
+                    // Non-RETURNING engines (resultStrategy 'reselect', e.g. MySQL)
+                    // attach a reselect plan that runs the write plus a follow-up SELECT;
+                    // running dq.sql alone would transform a row-less write result.
+                    raw =
+                        this.dialect.resultStrategy === 'reselect' && dq.reselect
+                            ? await dq.reselect((sql, params) => client.query(sql, params))
+                            : await client.query(dq.sql, dq.params);
+                }
+                catch (err) {
+                    throw wrapPgError(err);
+                }
+                results.push(dq.transform(raw));
+            }
+            return results;
+        });
+    }
     /**
      * Convenience wrapper around `$transaction` for the multi-tenant / RLS case:
      * runs `fn` inside a transaction with the given session GUCs applied via
@@ -867,9 +1087,22 @@ export class TurbineClient {
             }
             this.activeSubscriptions.clear();
         }
+        // Close owned (string-configured) replica pools regardless of whether the
+        // primary is owned — external replica pools are left untouched (caller owns
+        // their lifecycle), same contract as an external primary.
+        for (const replicaPool of this.ownedReplicaPools) {
+            try {
+                await replicaPool.end();
+            }
+            catch (err) {
+                if (this.logging) {
+                    console.error('[turbine] Error closing replica pool:', err.message);
+                }
+            }
+        }
         if (!this.ownsPool) {
             if (this.logging) {
-                console.log('[turbine] disconnect() skipped — external pool is not owned by Turbine');
+                console.log('[turbine] disconnect() skipped — external primary pool is not owned by Turbine');
             }
             return;
         }

package/dist/dialect.d.ts

@@ -47,6 +47,14 @@ export interface UpsertStatementInput {
     conflictColumns: string[];
     /** SQL-ready update SET clauses. */
     updateSetClauses: string[];
+    /**
+     * Optional SQL-ready predicate (no `WHERE` keyword) restricting the
+     * conflict-UPDATE to matching rows — used by global filters (soft-delete /
+     * multi-tenancy) so an upsert never resurrects/steals a row outside the
+     * filter. Only honored by dialects that set
+     * {@link Dialect.supportsUpsertUpdateWhere}; others must never receive it.
+     */
+    updateWhere?: string;
     /** Optional SQL-ready RETURNING selection. */
     returning?: string;
 }
@@ -270,6 +278,15 @@ export interface Dialect {
     wrapJsonSubresult(subquery: string, fallback: string): string;
     /** Whether INSERT/UPDATE/DELETE support RETURNING rows. */
     readonly supportsReturning: boolean;
+    /**
+     * Whether {@link buildUpsertStatement} honors {@link UpsertStatementInput.updateWhere}
+     * (a predicate on the conflict-UPDATE, e.g. Postgres `ON CONFLICT … DO UPDATE
+     * SET … WHERE …`). Global filters only push a conflict-UPDATE predicate when
+     * this is true, so engines whose upsert cannot express one (MySQL
+     * `ON DUPLICATE KEY UPDATE`) never receive an orphaned parameter. Optional —
+     * absent is treated as `false`.
+     */
+    readonly supportsUpsertUpdateWhere?: boolean;
     /** Whether this dialect/engine supports pgvector distance ops (KNN / distance WHERE). */
     readonly supportsVector: boolean;
     /** Whether this dialect/engine supports LISTEN/NOTIFY realtime pub/sub. */

package/dist/dialect.js

@@ -12,6 +12,7 @@ export const postgresDialect = {
     name: 'postgresql',
     resultStrategy: 'returning',
     supportsReturning: true,
+    supportsUpsertUpdateWhere: true,
     supportsILike: true,
     jsonPathSupport: 'native',
     emptyJsonArrayLiteral: "'[]'::json",
@@ -85,6 +86,7 @@ export const postgresDialect = {
     buildUpsertStatement(input) {
         return (`INSERT INTO ${input.table} (${input.insertColumns.join(', ')}) VALUES (${input.valuePlaceholders.join(', ')})` +
             ` ON CONFLICT (${input.conflictColumns.join(', ')}) DO UPDATE SET ${input.updateSetClauses.join(', ')}` +
+            (input.updateWhere ? ` WHERE ${input.updateWhere}` : '') +
             this.buildReturningClause(input.returning));
     },
     buildInsensitiveLike(column, paramRef) {

package/dist/generate.d.ts

@@ -16,6 +16,13 @@ export interface GenerateOptions {
     outDir?: string;
     /** Redact connection string from generated comments */
     connectionString?: string;
+    /**
+     * Also emit `zod.ts` with per-table `XSchema` / `XCreateSchema` /
+     * `XUpdateSchema` Zod validators (H1). The file imports the user-side `zod`
+     * package — it is never imported by Turbine's runtime, so Zod stays out of the
+     * library's dependency graph. Default: `false`.
+     */
+    zod?: boolean;
 }
 export declare function generate(options: GenerateOptions): {
     outDir: string;
@@ -27,3 +34,13 @@ export declare function generate(options: GenerateOptions): {
  * generator output without writing files to disk.
  */
 export declare function generateTypes(schema: SchemaMetadata): string;
+/**
+ * Generate the contents of `zod.ts`. Emits, per table, `XSchema` (the full
+ * row), `XCreateSchema` (PK/defaulted/nullable columns optional, STORED
+ * generated columns omitted), and `XUpdateSchema` (PK + STORED generated
+ * columns omitted, every remaining column optional). Exported so tests can pin
+ * the output without writing files.
+ */
+export declare function generateZod(schema: SchemaMetadata): string;
+export declare function generateMetadata(schema: SchemaMetadata): string;
+export declare function generateIndex(schema: SchemaMetadata): string;