@spfn/core 0.2.0-beta.53 → 0.2.0-beta.54

package/dist/db/index.d.ts

@@ -81,6 +81,13 @@ interface PoolConfig {
     max: number;
     /** Idle connection timeout in seconds */
     idleTimeout: number;
+    /**
+     * Maximum connections for the read-replica pool. Defaults to `max`. Set
+     * separately (DB_POOL_READ_MAX) so a master-replica app can size the two
+     * pools independently and keep `write.max + read.max` under the server's
+     * `max_connections` (otherwise each process opens up to 2 × max).
+     */
+    readMax?: number;
 }
 /**
  * Retry configuration for exponential backoff algorithm
@@ -1039,6 +1046,15 @@ interface TransactionalOptions {
      * ```
      */
     timeout?: number;
+    /**
+     * Idle-in-transaction timeout in milliseconds — Postgres reclaims the pooled
+     * connection if the transaction sits idle (e.g. the handler awaits external
+     * I/O) longer than this. A backstop against pool starvation, not a license
+     * to do non-DB work inside a transaction. `0` disables it.
+     *
+     * @default 30000 (30s) or TRANSACTION_IDLE_TIMEOUT environment variable
+     */
+    idleTimeout?: number;
 }
 /**
  * Transaction middleware for Hono routes
@@ -1129,6 +1145,21 @@ interface RunInTransactionOptions {
      * ```
      */
     timeout?: number;
+    /**
+     * Idle-in-transaction timeout in milliseconds (root transactions only).
+     *
+     * Sets PostgreSQL `idle_in_transaction_session_timeout`: if the transaction
+     * sits open without running a query for longer than this — e.g. while the
+     * handler awaits external I/O inside the transaction — Postgres terminates
+     * the session and rolls back, reclaiming the pooled connection instead of
+     * letting one stuck request hold it (and its row locks) indefinitely.
+     *
+     * Do not put external I/O inside a transaction; this is a backstop, not a
+     * license. `0` disables it.
+     *
+     * @default 30000 (30s) or TRANSACTION_IDLE_TIMEOUT environment variable
+     */
+    idleTimeout?: number;
     /**
      * Context string for logging (e.g., 'migration:add-user', 'script:cleanup')
      * @default 'transaction'
@@ -1633,6 +1664,32 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
         limit?: number;
         offset?: number;
     }): Promise<T['$inferSelect'][]>;
+    /**
+     * Keyset (cursor) pagination — O(limit) instead of OFFSET's O(offset).
+     *
+     * Pages by a strictly-ordered, unique column instead of a numeric offset, so a
+     * deep page doesn't scan and discard everything before it. Pass the cursor
+     * column's value from the last row of the previous page as `after`; omit it for
+     * the first page. The column must be unique and the sole sort key (e.g. an
+     * auto-increment id or a ULID).
+     *
+     * @example
+     * ```typescript
+     * const page1 = await this._findManyKeyset(users, { cursorColumn: users.id, limit: 20 });
+     * const page2 = await this._findManyKeyset(users, {
+     *     cursorColumn: users.id,
+     *     after: page1.at(-1)?.id,
+     *     limit: 20,
+     * });
+     * ```
+     */
+    protected _findManyKeyset<T extends PgTable>(table: T, options: {
+        cursorColumn: PgColumn;
+        limit: number;
+        after?: string | number | bigint | Date;
+        order?: 'asc' | 'desc';
+        where?: Record<string, any> | SQL | undefined;
+    }): Promise<T['$inferSelect'][]>;
     /**
      * Create a new record
      *

package/dist/db/index.js

@@ -11,7 +11,7 @@ import { bigserial, timestamp, bigint, uuid as uuid$1, text, jsonb, pgSchema } f
 import { AsyncLocalStorage } from 'async_hooks';
 import { createMiddleware } from 'hono/factory';
 import { randomUUID } from 'crypto';
-import { sql, count as count$1, eq, and } from 'drizzle-orm';
+import { sql, count as count$1, lt, gt, and, desc, asc, eq } from 'drizzle-orm';
 
 // src/db/manager/factory.ts
 function parseUniqueViolation(message) {
@@ -344,9 +344,12 @@ function parseEnvBoolean(key, defaultValue) {
   }
 }
 function getPoolConfig(options) {
+  const max = options?.max ?? parseEnvNumber("DB_POOL_MAX", 20, 10);
   return {
-    max: options?.max ?? parseEnvNumber("DB_POOL_MAX", 20, 10),
-    idleTimeout: options?.idleTimeout ?? parseEnvNumber("DB_POOL_IDLE_TIMEOUT", 30, 20)
+    max,
+    idleTimeout: options?.idleTimeout ?? parseEnvNumber("DB_POOL_IDLE_TIMEOUT", 30, 20),
+    // Defaults to the write `max`; DB_POOL_READ_MAX lets ops size the replica pool separately
+    readMax: options?.readMax ?? parseEnvNumber("DB_POOL_READ_MAX", max, max)
   };
 }
 function getRetryConfig() {
@@ -415,8 +418,9 @@ async function createWriteReadClients(writeUrl, readUrl, poolConfig, retryConfig
     dbLogger2.error("Failed to connect to write database", errorObj);
     throw new Error(`Write database connection failed: ${errorObj.message}`, { cause: error });
   }
+  const readPoolConfig = { ...poolConfig, max: poolConfig.readMax ?? poolConfig.max };
   try {
-    readClient = await createDatabaseConnection(readUrl, poolConfig, retryConfig);
+    readClient = await createDatabaseConnection(readUrl, readPoolConfig, retryConfig);
     return {
       write: drizzle(writeClient),
       read: drizzle(readClient),
@@ -1412,6 +1416,7 @@ async function runInTransaction(callback, options = {}) {
     context = "transaction"
   } = options;
   const timeout = options.timeout ?? defaultTimeout;
+  const idleTimeout = options.idleTimeout ?? env.TRANSACTION_IDLE_TIMEOUT;
   const txId = `tx_${randomUUID()}`;
   const validateAndThrow = (condition, message, logMessage, metadata) => {
     if (condition) {
@@ -1489,6 +1494,9 @@ async function runInTransaction(callback, options = {}) {
       if (timeout > 0 && !isNested) {
         await tx.execute(sql.raw(`SET LOCAL statement_timeout = ${timeout}`));
       }
+      if (idleTimeout > 0 && !isNested) {
+        await tx.execute(sql.raw(`SET LOCAL idle_in_transaction_session_timeout = ${idleTimeout}`));
+      }
       return await runWithTransaction(tx, txId, async () => {
         const innerResult = await callback(tx);
         if (!isNested) {
@@ -1507,7 +1515,8 @@ async function runInTransaction(callback, options = {}) {
           txId,
           context,
           duration: `${duration}ms`,
-          threshold: `${slowThreshold}ms`
+          threshold: `${slowThreshold}ms`,
+          hint: "A transaction holds a pooled connection (and row locks) for its whole duration. If this is slow because of non-DB work (external API, etc.) inside the transaction, move that work out \u2014 it starves the connection pool."
         });
       } else {
         txLogger2.debug("Transaction committed", {
@@ -1546,7 +1555,8 @@ async function runInTransaction(callback, options = {}) {
           duration: `${duration}ms`,
           threshold: `${slowThreshold}ms`,
           error: error instanceof Error ? error.message : String(error),
-          errorType: error instanceof Error ? error.name : "Unknown"
+          errorType: error instanceof Error ? error.name : "Unknown",
+          hint: "If the error is an idle-in-transaction timeout, the transaction held a pooled connection while awaiting non-DB work (external API, etc.). Move that work out of the transaction."
         });
       } else {
         txLogger2.error("Transaction rolled back", {
@@ -1896,14 +1906,51 @@ var BaseRepository = class {
       const orderByArray = Array.isArray(options.orderBy) ? options.orderBy : [options.orderBy];
       query = query.orderBy(...orderByArray);
     }
-    if (options?.limit) {
-      query = query.limit(options.limit);
+    const maxRows = env.DB_MAX_ROWS;
+    const requestedLimit = options?.limit && options.limit > 0 ? options.limit : void 0;
+    const effectiveLimit = maxRows > 0 ? Math.min(requestedLimit ?? maxRows, maxRows) : requestedLimit;
+    if (effectiveLimit) {
+      query = query.limit(effectiveLimit);
     }
     if (options?.offset) {
       query = query.offset(options.offset);
     }
     return query;
   }
+  /**
+   * Keyset (cursor) pagination — O(limit) instead of OFFSET's O(offset).
+   *
+   * Pages by a strictly-ordered, unique column instead of a numeric offset, so a
+   * deep page doesn't scan and discard everything before it. Pass the cursor
+   * column's value from the last row of the previous page as `after`; omit it for
+   * the first page. The column must be unique and the sole sort key (e.g. an
+   * auto-increment id or a ULID).
+   *
+   * @example
+   * ```typescript
+   * const page1 = await this._findManyKeyset(users, { cursorColumn: users.id, limit: 20 });
+   * const page2 = await this._findManyKeyset(users, {
+   *     cursorColumn: users.id,
+   *     after: page1.at(-1)?.id,
+   *     limit: 20,
+   * });
+   * ```
+   */
+  async _findManyKeyset(table, options) {
+    const { cursorColumn, after, order = "asc", where } = options;
+    const maxRows = env.DB_MAX_ROWS;
+    const limit = maxRows > 0 ? Math.min(options.limit, maxRows) : options.limit;
+    const baseWhere = where ? isSQLWrapper(where) ? where : buildWhereFromObject(table, where) : void 0;
+    const cursorPredicate = after !== void 0 ? order === "desc" ? lt(cursorColumn, after) : gt(cursorColumn, after) : void 0;
+    const whereClause = baseWhere && cursorPredicate ? and(baseWhere, cursorPredicate) : cursorPredicate ?? baseWhere;
+    let query = this.readDb.select().from(table);
+    if (whereClause) {
+      query = query.where(whereClause);
+    }
+    query = query.orderBy(order === "desc" ? desc(cursorColumn) : asc(cursorColumn));
+    query = query.limit(limit);
+    return query;
+  }
   /**
    * Create a new record
    *