@spfn/core 0.3.0-beta.3 → 0.3.0-beta.30

package/dist/db/index.d.ts

@@ -397,27 +397,6 @@ declare function getDatabaseInfo(): {
     providerKind?: string;
 };
 
-/**
- * Reconnect Trigger — Query-error driven pool rebuild
- *
- * Complements the periodic health check with a fast-path: when application
- * queries start failing with connection-level errors, we do not wait up to
- * DB_HEALTH_CHECK_INTERVAL (default 60s) to notice. A sliding-window counter
- * trips a force-reconnect as soon as the failure rate crosses a threshold.
- *
- * Why this exists:
- *  - postgres.js transparently drops dead sockets and opens new ones on the
- *    next query. A single `SELECT 1` on the periodic interval can therefore
- *    false-pass while user-facing queries keep hitting the remaining dead
- *    sockets in the pool.
- *  - This module observes real query errors and, when it sees a burst of
- *    connection-level failures, calls triggerForceReconnect() which performs
- *    the same atomic-swap rebuild as the health check.
- *
- * Configuration (env vars, hardcoded defaults):
- *  - DB_RECONNECT_ERROR_THRESHOLD (default 3): errors needed in window
- *  - DB_RECONNECT_ERROR_WINDOW_MS (default 10000): sliding window size
- */
 /**
  * Determine whether an error looks like a pool/connection failure
  *
@@ -505,7 +484,7 @@ declare function checkConnection(client: Sql): Promise<boolean>;
 interface DrizzleConfigOptions {
     /** Database connection URL (defaults to process.env.DATABASE_URL) */
     databaseUrl?: string;
-    /** Schema files glob pattern or array of patterns (defaults to './src/server/entities/\*\*\/*.ts') */
+    /** Schema entry file(s), directories or glob pattern(s). Default: './src/server/entities/\*\*\/*.ts', or the registry `DRIZZLE_SCHEMA_PATH` (./src/server/entities/config.ts) when that scan finds no entity file; `schemaRegistry` reports the registry when both exist */
     schema?: string | string[];
     /** Migration output directory (defaults to './src/server/drizzle') */
     out?: string;
@@ -521,8 +500,6 @@ interface DrizzleConfigOptions {
     expandGlobs?: boolean;
     /** PostgreSQL schema filter for push/introspect commands */
     schemaFilter?: string[];
-    /** Auto-detect PostgreSQL schemas from entity files (requires expandGlobs: true) */
-    autoDetectSchemas?: boolean;
     /** Migration prefix strategy (default: 'timestamp') */
     migrationPrefix?: 'index' | 'timestamp' | 'unix' | 'none';
 }
@@ -551,6 +528,8 @@ declare function detectDialect(url: string): 'postgresql' | 'mysql' | 'sqlite';
  */
 declare function getDrizzleConfig(options?: DrizzleConfigOptions): {
     schema: string | string[];
+    schemaSource: string;
+    schemaRegistry: string | undefined;
     out: string;
     dialect: "postgresql" | "mysql" | "sqlite";
     dbCredentials: {
@@ -562,6 +541,8 @@ declare function getDrizzleConfig(options?: DrizzleConfigOptions): {
     schemaFilter?: undefined;
 } | {
     schema: string | string[];
+    schemaSource: string;
+    schemaRegistry: string | undefined;
     out: string;
     dialect: "postgresql" | "mysql" | "sqlite";
     dbCredentials: {
@@ -573,10 +554,29 @@ declare function getDrizzleConfig(options?: DrizzleConfigOptions): {
     };
 };
 /**
- * Generate drizzle.config.ts file content
+ * The schema fields a rendered drizzle.config.ts needs
+ */
+interface RenderableDrizzleConfig {
+    schema: string | string[];
+    out: string;
+    dialect: string;
+    dbCredentials: Record<string, unknown>;
+    schemaFilter?: string[];
+    migrations?: Record<string, unknown>;
+}
+/**
+ * Render an already-resolved config as drizzle.config.ts source, schema
+ * paths made absolute for Drizzle Studio
  *
- * @param options - Configuration options
- * @returns File content as string
+ * @param config - Result of getDrizzleConfig, possibly with the schema replaced
+ * @param cwd - Base for relative schema paths (default: process.cwd())
+ */
+declare function renderDrizzleConfig(config: RenderableDrizzleConfig, cwd?: string): string;
+/**
+ * Generate drizzle.config.ts source from options: resolve the config, then render it
+ *
+ * @param options - Configuration options (see getDrizzleConfig)
+ * @returns drizzle.config.ts source
  */
 declare function generateDrizzleConfigFile(options?: DrizzleConfigOptions): string;
 
@@ -1139,6 +1139,23 @@ type TransactionDB<TDatabase extends DrizzleDatabase = DefaultDatabase> = Databa
  * afterCommit callback type
  */
 type AfterCommitCallback = () => void | Promise<void>;
+/**
+ * beforeCommit callback type
+ */
+type BeforeCommitCallback = () => void | Promise<void>;
+/**
+ * afterRollback callback type
+ */
+type AfterRollbackCallback = () => void | Promise<void>;
+/**
+ * Serializes the savepoint frames opened directly off one transaction context
+ *
+ * @see createNestedFrameGate
+ */
+type NestedFrameGate = {
+    /** Run `frame` once every frame queued before it on this context has finished */
+    run<T>(frame: () => Promise<T>): Promise<T>;
+};
 /**
  * Transaction context stored in AsyncLocalStorage
  */
@@ -1148,8 +1165,14 @@ type TransactionContext<TDatabase extends DrizzleDatabase = DrizzleDatabase> = {
     /** Unique transaction ID for logging and tracing */
     txId: string;
     level: number;
-    /** Callbacks to execute after root transaction commits */
+    /** beforeCommit callbacks registered in THIS frame (root or savepoint) */
+    beforeCommitCallbacks: BeforeCommitCallback[];
+    /** afterCommit callbacks registered in THIS frame (root or savepoint) */
     afterCommitCallbacks: AfterCommitCallback[];
+    /** afterRollback callbacks registered in THIS frame (root or savepoint) */
+    afterRollbackCallbacks: AfterRollbackCallback[];
+    /** Serializes the savepoint frames opened directly off THIS context */
+    nestedFrames: NestedFrameGate;
 };
 /**
  * Get current transaction object and metadata from AsyncLocalStorage
@@ -1181,13 +1204,18 @@ callback: () => Promise<T>): Promise<T>;
  *
  * - Inside a transaction: queued and executed after root transaction commits
  * - Outside a transaction: executed immediately (already "committed")
- * - Nested transactions: callbacks bubble up to root transaction
+ * - Nested transactions: the callback belongs to the savepoint that registered
+ *   it. It reaches the root only if that savepoint (and every one around it)
+ *   resolved; a savepoint that rolls back drops it, even when the root commits
+ * - A hook registered after its frame (root or savepoint) has settled is
+ *   dropped: the frame's queue was handed on, or discarded, when it settled.
+ *   Register hooks in the awaited call chain, not from detached work
  * - Callbacks run outside transaction context (new connection for DB access)
  * - Errors are logged but never thrown (commit already succeeded)
  *
  * @example
  * ```typescript
- * import { onAfterCommit } from '@spfn/core/db/transaction';
+ * import { onAfterCommit } from '@spfn/core/db';
  *
  * async function submit(spaceId: string, chatId: string)
  * {
@@ -1201,6 +1229,100 @@ callback: () => Promise<T>): Promise<T>;
  * ```
  */
 declare function onAfterCommit(callback: AfterCommitCallback): void;
+/**
+ * Register a callback to run just before the current transaction commits
+ *
+ * - Inside a transaction: queued and executed after the root callback resolves,
+ *   while the transaction is still open — the callback MAY run statements and
+ *   they are part of the same commit
+ * - Outside a transaction: executed immediately with a WARNING (same rationale as
+ *   onAfterCommit — there is nothing left to commit), and the abort semantics
+ *   below do not apply: there is no transaction for a throw to roll back
+ * - Nested transactions: the callback belongs to the savepoint that registered
+ *   it. A savepoint that resolved hands it to the root, where it still runs
+ *   before the root's COMMIT (never at the savepoint); one that rolls back
+ *   drops it, and the root commits without it
+ * - A hook registered after its frame (root or savepoint) has settled is
+ *   dropped: the frame's queue was handed on, or discarded, when it settled.
+ *   Register hooks in the awaited call chain, not from detached work
+ * - Callbacks run in registration order, inside the transaction context
+ *   (getTransaction() returns the live tx)
+ * - The queue is snapshot before the pass, so a callback registered BY a
+ *   beforeCommit callback does not run for this commit — it would otherwise
+ *   grow the queue mid-iteration and loop forever inside the open transaction
+ * - A throw ABORTS: later callbacks are skipped, the transaction rolls back,
+ *   the error propagates to the caller, and afterRollback callbacks fire
+ *
+ * @example
+ * ```typescript
+ * import { runInTransaction, onBeforeCommit } from '@spfn/core/db';
+ *
+ * async function transfer(fromId: string, toId: string, amount: number)
+ * {
+ *     // The transaction is what gives the check teeth — registered outside one,
+ *     // the callback runs immediately and its throw aborts nothing.
+ *     await runInTransaction(async () =>
+ *     {
+ *         await accountRepo.debit(fromId, amount);
+ *         await accountRepo.credit(toId, amount);
+ *
+ *         // Last-moment invariant check: a throw here rolls the whole transfer back.
+ *         onBeforeCommit(() => assertNoNegativeBalance(fromId));
+ *     });
+ * }
+ * ```
+ */
+declare function onBeforeCommit(callback: BeforeCommitCallback): void;
+/**
+ * Register a callback to run after the current transaction rolled back
+ *
+ * - Inside a transaction: queued and executed once the work registered with it
+ *   is rolled back, before the causing error leaves runInTransaction / the
+ *   middleware
+ * - Outside a transaction: no-op with a warning — there is no rollback to wait for
+ * - Nested transactions: the callback belongs to the savepoint that registered
+ *   it. If that savepoint rolls back, the callback runs right then, awaited
+ *   before the error leaves the nested runInTransaction, and never again — the
+ *   root's own afterRollback callbacks do not run when the root commits. If the
+ *   savepoint resolved, the callback passes to the root and runs only if the
+ *   root rolls back
+ * - After a ROOT rollback, callbacks run outside any transaction context (new
+ *   connection for DB access). After a SAVEPOINT rollback the root is still
+ *   open: getTransactionContext() is the parent's, so DB work in the callback
+ *   joins the parent transaction and commits or rolls back with it
+ * - A statement that FAILS in a savepoint's callback aborts the parent
+ *   transaction: the error is logged and swallowed here, but the root's next
+ *   statement then fails with 25P02 (current transaction is aborted). If the
+ *   root runs none, its COMMIT fails with the callback's error. Either way,
+ *   everything the root wrote rolls back. A compensation may call
+ *   runInTransaction itself — that opens a savepoint on the parent, which
+ *   contains such a failure — and hooks it registers belong to the parent
+ * - A hook registered after its frame (root or savepoint) has settled is
+ *   dropped: the frame's queue was handed on, or discarded, when it settled.
+ *   Register hooks in the awaited call chain, not from detached work
+ * - Errors are logged but never thrown: the original error keeps propagating
+ *   unchanged, never replaced by a callback failure
+ *
+ * @example
+ * ```typescript
+ * import { runInTransaction, onAfterRollback } from '@spfn/core/db';
+ *
+ * async function importAvatar(userId: string, file: Blob)
+ * {
+ *     // Upload first: external I/O never belongs inside the transaction.
+ *     const key = await objectStore.put(file);
+ *
+ *     await runInTransaction(async () =>
+ *     {
+ *         await userRepo.updateAvatar(userId, key);
+ *
+ *         // The upload cannot roll back on its own — undo it if the write never lands.
+ *         onAfterRollback(() => objectStore.delete(key));
+ *     });
+ * }
+ * ```
+ */
+declare function onAfterRollback(callback: AfterRollbackCallback): void;
 
 /**
  * Transaction middleware options
@@ -1245,6 +1367,21 @@ interface TransactionalOptions {
      * @default 30000 (30s) or TRANSACTION_IDLE_TIMEOUT environment variable
      */
     idleTimeout?: number;
+    /**
+     * Run in an independent transaction instead of joining an ambient one.
+     *
+     * Only bites when the middleware itself runs nested — a sub-app mounted
+     * under a route that already applied `Transactional()`, or a handler invoked
+     * from inside `runInTransaction`. By default that inner run takes a SAVEPOINT
+     * on the outer transaction; `requiresNew: true` gives it a real `BEGIN` on a
+     * second pooled connection, with its own timeouts and its own hook queues.
+     *
+     * See `RunInTransactionOptions.requiresNew` for the pool and self-deadlock
+     * costs — they apply here unchanged.
+     *
+     * @default false
+     */
+    requiresNew?: boolean;
 }
 /**
  * Transaction middleware for Hono routes
@@ -1282,6 +1419,9 @@ interface TransactionalOptions {
  * - Success: Auto-commit
  * - Error: Auto-rollback
  * - Detects context.error to trigger rollback
+ * - Hooks: this delegates to runInTransaction, so onBeforeCommit, onAfterCommit
+ *   and onAfterRollback behave exactly as they do there. afterRollback callbacks
+ *   have already run by the time the error reaches the conversion below.
  *
  * 📊 Transaction logging:
  * - Auto-logs transaction start/commit/rollback
@@ -1317,8 +1457,12 @@ interface RunInTransactionOptions {
      * - `timeout: undefined` - Uses default (30s or TRANSACTION_TIMEOUT env var)
      * - `timeout: N` - Sets timeout to N milliseconds (1 to 2147483647)
      *
-     * Note: Timeout is only applied to root transactions. Nested transactions
-     * (SAVEPOINTs) inherit the timeout from the outer transaction.
+     * Note: Timeout is only applied to root transactions. A nested call takes a
+     * SAVEPOINT on the outer transaction's connection, where the outer
+     * transaction's `SET LOCAL statement_timeout` is already in force — so the
+     * nested call genuinely inherits it, and its own `timeout` is ignored (a
+     * warning is logged when the caller passed one explicitly). A
+     * `requiresNew: true` call is a root and gets its own.
      *
      * @default 30000 (30 seconds) or TRANSACTION_TIMEOUT environment variable
      *
@@ -1355,6 +1499,48 @@ interface RunInTransactionOptions {
      * @default 'transaction'
      */
     context?: string;
+    /**
+     * Run in an independent transaction instead of joining an ambient one.
+     *
+     * By default a call made while another transaction is open takes a SAVEPOINT
+     * on that transaction's connection: its writes commit or roll back with the
+     * outer transaction. `requiresNew: true` opens a real `BEGIN` on a SECOND
+     * pooled connection instead, so the work commits on its own and survives an
+     * outer rollback — an audit trail or a failed-attempt record, for example.
+     *
+     * Being a root transaction, it gets its own `statement_timeout`,
+     * `idle_in_transaction_session_timeout`, and its OWN hook queues:
+     * `onBeforeCommit` / `onAfterCommit` / `onAfterRollback` registered inside it
+     * fire on ITS outcome, not the outer transaction's.
+     *
+     * Two costs, both consequences of the second connection:
+     * - It holds a second connection for its whole duration, so it counts twice
+     *   against the pool. Keep it short and don't fan it out.
+     * - It cannot see the outer transaction's uncommitted writes, and it BLOCKS
+     *   on any row the outer transaction has locked. Since the outer transaction
+     *   is waiting for this call to return, that block is a self-deadlock that
+     *   only `statement_timeout` breaks. Never touch rows the outer transaction
+     *   wrote.
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * await runInTransaction(async () =>
+     * {
+     *     await orderRepo.create(order);
+     *
+     *     // Lands even if the order below rolls the outer transaction back.
+     *     await runInTransaction(
+     *         () => auditRepo.record('order.attempted', order.id),
+     *         { requiresNew: true },
+     *     );
+     *
+     *     await inventoryRepo.reserve(order.items);   // may throw
+     * });
+     * ```
+     */
+    requiresNew?: boolean;
 }
 /**
  * Run a callback function within a database transaction
@@ -1366,6 +1552,15 @@ interface RunInTransactionOptions {
  * - Warns about slow transactions
  * - Enforces timeout if configured
  *
+ * Called with a transaction already open on the async call chain, it takes a
+ * SAVEPOINT on that transaction rather than opening an independent one: the work
+ * runs on the same connection, sees the outer transaction's uncommitted writes,
+ * and commits with it. A throw that the caller catches unwinds to the SAVEPOINT
+ * and leaves the outer transaction healthy; a throw that propagates rolls the
+ * whole thing back. Nested calls off one transaction are serialized — see
+ * `openTransaction` — so `Promise.all` over them runs them one at a time. Pass
+ * `requiresNew: true` for an independent transaction on its own connection.
+ *
  * Errors are propagated to the caller without modification.
  * Caller is responsible for error handling and conversion.
  *
@@ -1680,11 +1875,11 @@ declare function count<T extends PgTable>(table: T, where?: WhereObject<InferSel
  *
  * @example With Transactions
  * ```typescript
- * import { runWithTransaction } from '@spfn/core/db';
+ * import { runInTransaction } from '@spfn/core/db';
  *
  * const userRepo = new UserRepository();
  *
- * await runWithTransaction(async () => {
+ * await runInTransaction(async () => {
  *     // Both db and readDb automatically use the transaction context
  *     const user = await userRepo.create({ name: 'John' });
  *     await userRepo.findById(user.id); // Uses same transaction
@@ -2006,4 +2201,4 @@ declare abstract class BaseRepository<TRelations extends AnyRelations = EmptyRel
     protected _count<T extends PgTable>(table: T, where?: Record<string, any> | SQL | undefined): Promise<number>;
 }
 
-export { type AfterCommitCallback, BaseRepository, type DatabaseClients, type DatabaseInitOptions, type DatabaseOptions, type DatabaseProvider, type DatabaseTransaction, type DefaultDatabase, type DrizzleConfigOptions, type DrizzleDatabase, type FunctionMigrationEntry, type FunctionMigrationInfo, type MigrationStatus, type MigrationStatusDb, type MigrationTargetStatus, PROJECT_MIGRATIONS_TABLE, PROJECT_TARGET_NAME, type PoolConfig, RUN_MIGRATIONS_HINT, type RepositoryDatabase, RepositoryError, type RetryConfig, type RunInTransactionOptions, type TransactionContext, type TransactionDB, Transactional, type TransactionalOptions, auditFields, checkConnection, closeDatabase, collectMigrationStatus, count, countPendingMigrations, create, createDatabaseConnection, createDatabaseFromEnv, createMany, createSchema, deleteMany, deleteOne, detectDialect, discoverFunctionMigrations, enumText, filterPendingEntries, findMany, findOne, forceReconnectDatabase, foreignKey, formatPendingMigrations, fromPostgresError, functionMigrationsTable, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, getTransactionContext, hasMigrationTargets, id, initDatabase, isConnectionLevelError, migrationTargets, onAfterCommit, optionalForeignKey, packageNameToSchema, pendingMigrationTargets, pendingMigrationsSummary, projectMigrationsDir, publishingFields, readMigrationEntries, reportDatabaseError, resetConnectionErrorCounter, runInTransaction, runWithTransaction, setDatabase, setDatabaseProvider, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };
+export { type AfterCommitCallback, type AfterRollbackCallback, BaseRepository, type BeforeCommitCallback, type DatabaseClients, type DatabaseInitOptions, type DatabaseOptions, type DatabaseProvider, type DatabaseTransaction, type DefaultDatabase, type DrizzleConfigOptions, type DrizzleDatabase, type FunctionMigrationEntry, type FunctionMigrationInfo, type MigrationStatus, type MigrationStatusDb, type MigrationTargetStatus, type NestedFrameGate, PROJECT_MIGRATIONS_TABLE, PROJECT_TARGET_NAME, type PoolConfig, RUN_MIGRATIONS_HINT, type RenderableDrizzleConfig, type RepositoryDatabase, RepositoryError, type RetryConfig, type RunInTransactionOptions, type TransactionContext, type TransactionDB, Transactional, type TransactionalOptions, auditFields, checkConnection, closeDatabase, collectMigrationStatus, count, countPendingMigrations, create, createDatabaseConnection, createDatabaseFromEnv, createMany, createSchema, deleteMany, deleteOne, detectDialect, discoverFunctionMigrations, enumText, filterPendingEntries, findMany, findOne, forceReconnectDatabase, foreignKey, formatPendingMigrations, fromPostgresError, functionMigrationsTable, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, getTransactionContext, hasMigrationTargets, id, initDatabase, isConnectionLevelError, migrationTargets, onAfterCommit, onAfterRollback, onBeforeCommit, optionalForeignKey, packageNameToSchema, pendingMigrationTargets, pendingMigrationsSummary, projectMigrationsDir, publishingFields, readMigrationEntries, renderDrizzleConfig, reportDatabaseError, resetConnectionErrorCounter, runInTransaction, runWithTransaction, setDatabase, setDatabaseProvider, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };