@spfn/core 0.3.0-beta.2 → 0.3.0-beta.21

package/dist/db/index.d.ts

@@ -246,7 +246,7 @@ declare function getDatabase<TDatabase extends DrizzleDatabase = DefaultDatabase
  * // Set custom database instances (testing)
  * const writeClient = postgres('postgresql://primary:5432/mydb');
  * const readClient = postgres('postgresql://replica:5432/mydb');
- * setDatabase(drizzle(writeClient), drizzle(readClient));
+ * setDatabase(drizzle({ client: writeClient }), drizzle({ client: readClient }));
  *
  * // Clear instances (not recommended - use closeDatabase() instead)
  * setDatabase(undefined, undefined);
@@ -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 before the root transaction commits (still inside it) */
+    beforeCommitCallbacks: BeforeCommitCallback[];
     /** Callbacks to execute after root transaction commits */
     afterCommitCallbacks: AfterCommitCallback[];
+    /** Callbacks to execute after the root transaction rolled back */
+    afterRollbackCallbacks: AfterRollbackCallback[];
+    /** Serializes the savepoint frames opened directly off THIS context */
+    nestedFrames: NestedFrameGate;
 };
 /**
  * Get current transaction object and metadata from AsyncLocalStorage
@@ -1187,7 +1210,7 @@ callback: () => Promise<T>): Promise<T>;
  *
  * @example
  * ```typescript
- * import { onAfterCommit } from '@spfn/core/db/transaction';
+ * import { onAfterCommit } from '@spfn/core/db';
  *
  * async function submit(spaceId: string, chatId: string)
  * {
@@ -1201,6 +1224,77 @@ 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: callbacks bubble up to root transaction
+ * - 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 after the ROOT transaction 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: callbacks bubble up to root transaction. A nested
+ *   rollback that the root survives does NOT fire them; these hooks are about
+ *   the root transaction's fate, not a savepoint's
+ * - Callbacks run outside the transaction context (new connection for DB access)
+ * - 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 +1339,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 +1391,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 +1429,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 +1471,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 +1524,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 +1847,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 +2173,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 };