@spfn/core 0.2.0-beta.5 → 0.2.0-beta.50

package/dist/db/index.d.ts

@@ -273,6 +273,36 @@ declare function initDatabase(options?: DatabaseOptions): Promise<{
  * ```
  */
 declare function closeDatabase(): Promise<void>;
+/**
+ * Force an immediate database pool rebuild
+ *
+ * Destroys the current postgres.js pool(s) and rebuilds them with the same
+ * configuration passed to the original `initDatabase()` call (or whatever
+ * was detected from environment variables). Uses the same atomic-swap
+ * strategy as the periodic health check: new connections are created and
+ * tested BEFORE the old ones are torn down, so `getDatabase()` callers never
+ * observe a missing instance.
+ *
+ * Use this when application code detects that the pool is stuck and does not
+ * want to wait for the next periodic health check tick. Concurrent calls are
+ * coalesced — if a reconnect is already in progress, this resolves to `false`
+ * without starting a second one.
+ *
+ * @param reason - Short label describing why the rebuild was requested (for logs)
+ * @returns `true` if a reconnection ran, `false` if one was already in-flight.
+ *          Resolves after the rebuild completes (success or max retries exhausted).
+ *
+ * @example
+ * ```typescript
+ * import { forceReconnectDatabase } from '@spfn/core/db';
+ *
+ * app.post('/admin/db/reconnect', async (c) => {
+ *     const ran = await forceReconnectDatabase('admin_request');
+ *     return c.json({ reconnected: ran });
+ * });
+ * ```
+ */
+declare function forceReconnectDatabase(reason?: string): Promise<boolean>;
 /**
  * Get database connection info (for debugging)
  *
@@ -308,6 +338,60 @@ declare function getDatabaseInfo(): {
     isReplica: boolean;
 };
 
+/**
+ * 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
+ *
+ * Returns true when any layer in the error chain exposes a connection-level
+ * code (postgres.js driver code, Node network errno, PG SQLSTATE class 08 etc.)
+ * or is an instance of our own ConnectionError wrapper.
+ *
+ * Returns false for query errors (syntax, constraint violations, etc.) — those
+ * should NOT trigger a pool rebuild.
+ */
+declare function isConnectionLevelError(error: unknown): boolean;
+/**
+ * Reset the internal error counter
+ *
+ * Exposed for tests that need a clean slate between cases. Does not clear
+ * the WeakSet (which is GC-backed and self-cleans with error lifetimes).
+ */
+declare function resetConnectionErrorCounter(): void;
+/**
+ * Report a database error to the reconnect trigger
+ *
+ * Call this from any site that catches a query error before rethrowing.
+ * It is a no-op for non-connection-level errors. When the threshold is
+ * crossed it calls triggerForceReconnect() in the background — callers
+ * should NOT await it.
+ *
+ * Safe to call from any context: catches its own errors so it cannot
+ * disrupt the calling catch block. Deduplicates across error-chain
+ * re-wrapping so one failure counts exactly once regardless of how many
+ * catch layers it passes through.
+ */
+declare function reportDatabaseError(error: unknown): void;
+
 /**
  * Create database connection with exponential backoff retry strategy
  *
@@ -376,6 +460,12 @@ interface DrizzleConfigOptions {
     packageFilter?: string;
     /** Expand glob patterns to actual file paths (useful for Drizzle Studio) */
     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';
 }
 /**
  * Detect database dialect from connection URL
@@ -407,6 +497,21 @@ declare function getDrizzleConfig(options?: DrizzleConfigOptions): {
     dbCredentials: {
         url: string;
     };
+    migrations: {
+        prefix: "timestamp" | "none" | "index" | "unix";
+    };
+    schemaFilter?: undefined;
+} | {
+    schema: string | string[];
+    out: string;
+    dialect: "postgresql" | "mysql" | "sqlite";
+    dbCredentials: {
+        url: string;
+    };
+    schemaFilter: string[] | undefined;
+    migrations: {
+        prefix: "timestamp" | "none" | "index" | "unix";
+    };
 };
 /**
  * Generate drizzle.config.ts file content
@@ -462,7 +567,7 @@ declare function timestamps(): {
 /**
  * Foreign key reference to another table
  *
- * Creates a bigserial column with cascade delete.
+ * Creates a bigint column with cascade delete.
  * Type-safe: ensures the reference points to a valid PostgreSQL column.
  *
  * @param name - Column name (e.g., 'author' creates 'author_id')
@@ -482,7 +587,7 @@ declare function timestamps(): {
  */
 declare function foreignKey<T extends PgColumn>(name: string, reference: () => T, options?: {
     onDelete?: 'cascade' | 'set null' | 'restrict' | 'no action';
-}): drizzle_orm.NotNull<drizzle_orm_pg_core.PgBigSerial53BuilderInitial<`${string}_id`>>;
+}): drizzle_orm.NotNull<drizzle_orm_pg_core.PgBigInt53BuilderInitial<`${string}_id`>>;
 /**
  * Optional foreign key reference (nullable)
  *
@@ -502,7 +607,7 @@ declare function foreignKey<T extends PgColumn>(name: string, reference: () => T
  */
 declare function optionalForeignKey<T extends PgColumn>(name: string, reference: () => T, options?: {
     onDelete?: 'cascade' | 'set null' | 'restrict' | 'no action';
-}): drizzle_orm_pg_core.PgBigSerial53BuilderInitial<`${string}_id`>;
+}): drizzle_orm_pg_core.PgBigInt53BuilderInitial<`${string}_id`>;
 /**
  * UUID primary key
  *
@@ -833,6 +938,10 @@ declare function getSchemaInfo(packageName: string): {
  * Uses Record<string, unknown> to accept any schema shape
  */
 type TransactionDB = PostgresJsDatabase<Record<string, unknown>>;
+/**
+ * afterCommit callback type
+ */
+type AfterCommitCallback = () => void | Promise<void>;
 /**
  * Transaction context stored in AsyncLocalStorage
  */
@@ -842,7 +951,15 @@ type TransactionContext = {
     /** Unique transaction ID for logging and tracing */
     txId: string;
     level: number;
+    /** Callbacks to execute after root transaction commits */
+    afterCommitCallbacks: AfterCommitCallback[];
 };
+/**
+ * Get current transaction object and metadata from AsyncLocalStorage
+ *
+ * @returns TransactionContext if available, null otherwise
+ */
+declare function getTransactionContext(): TransactionContext | null;
 /**
  * Get current transaction from AsyncLocalStorage
  *
@@ -862,6 +979,31 @@ declare function getTransaction(): TransactionDB | null;
  */
 declare function runWithTransaction<T>(tx: TransactionDB, txId: string, // Add txId parameter
 callback: () => Promise<T>): Promise<T>;
+/**
+ * Register a callback to run after the current transaction commits
+ *
+ * - 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
+ * - 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';
+ *
+ * async function submit(spaceId: string, chatId: string)
+ * {
+ *     const publication = await publicationRepo.create({...});
+ *     await requestRepo.updateStatusAtomically(...);
+ *
+ *     onAfterCommit(() => generateArticle(spaceId, chatId, publication.id));
+ *
+ *     return publication;
+ * }
+ * ```
+ */
+declare function onAfterCommit(callback: AfterCommitCallback): void;
 
 /**
  * Transaction middleware options
@@ -942,6 +1084,78 @@ interface TransactionalOptions {
  */
 declare function Transactional(options?: TransactionalOptions): hono_types.MiddlewareHandler<any, string, {}, Response>;
 
+/**
+ * Transaction runner options
+ */
+interface RunInTransactionOptions {
+    /**
+     * Slow transaction warning threshold in milliseconds
+     * @default 1000 (1 second)
+     */
+    slowThreshold?: number;
+    /**
+     * Enable transaction logging
+     * @default true
+     */
+    enableLogging?: boolean;
+    /**
+     * Transaction timeout in milliseconds
+     *
+     * Sets PostgreSQL `statement_timeout` to enforce database-level timeout.
+     * If transaction exceeds this duration, PostgreSQL will automatically cancel
+     * the query and rollback the transaction, ensuring data consistency.
+     *
+     * Behavior:
+     * - `timeout: 0` - Disables timeout (unlimited execution time)
+     * - `timeout: null` - Uses default (30s or TRANSACTION_TIMEOUT env var)
+     * - `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.
+     *
+     * @default 30000 (30 seconds) or TRANSACTION_TIMEOUT environment variable
+     *
+     * @example
+     * ```typescript
+     * // Use default timeout (30s)
+     * await runInTransaction(callback);
+     *
+     * // Disable timeout for long-running operations
+     * await runInTransaction(callback, { timeout: 0 });
+     *
+     * // Set custom timeout (60s)
+     * await runInTransaction(callback, { timeout: 60000 });
+     * ```
+     */
+    timeout?: number;
+    /**
+     * Context string for logging (e.g., 'migration:add-user', 'script:cleanup')
+     * @default 'transaction'
+     */
+    context?: string;
+}
+/**
+ * Run a callback function within a database transaction
+ *
+ * Automatically manages transaction lifecycle:
+ * - Commits on success
+ * - Rolls back on error
+ * - Tracks execution time
+ * - Warns about slow transactions
+ * - Enforces timeout if configured
+ *
+ * Errors are propagated to the caller without modification.
+ * Caller is responsible for error handling and conversion.
+ *
+ * @param callback - Function to execute within transaction
+ * @param options - Transaction options
+ * @returns Result of callback function
+ * @throws TransactionError if database not initialized or timeout exceeded
+ * @throws Any error thrown by callback function
+ */
+declare function runInTransaction<T>(callback: (tx: TransactionDB) => Promise<T>, options?: RunInTransactionOptions): Promise<T>;
+
 /**
  * PostgreSQL Error Conversion Utilities
  *
@@ -1550,4 +1764,4 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
     protected _count<T extends PgTable>(table: T, where?: Record<string, any> | SQL | undefined): Promise<number>;
 }
 
-export { BaseRepository, type DatabaseClients, type DrizzleConfigOptions, type PoolConfig, RepositoryError, type RetryConfig, type TransactionContext, type TransactionDB, Transactional, type TransactionalOptions, auditFields, checkConnection, closeDatabase, count, create, createDatabaseConnection, createDatabaseFromEnv, createMany, createSchema, deleteMany, deleteOne, detectDialect, enumText, findMany, findOne, foreignKey, fromPostgresError, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, id, initDatabase, optionalForeignKey, packageNameToSchema, publishingFields, runWithTransaction, setDatabase, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };
+export { type AfterCommitCallback, BaseRepository, type DatabaseClients, type DrizzleConfigOptions, type PoolConfig, RepositoryError, type RetryConfig, type RunInTransactionOptions, type TransactionContext, type TransactionDB, Transactional, type TransactionalOptions, auditFields, checkConnection, closeDatabase, count, create, createDatabaseConnection, createDatabaseFromEnv, createMany, createSchema, deleteMany, deleteOne, detectDialect, enumText, findMany, findOne, forceReconnectDatabase, foreignKey, fromPostgresError, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, getTransactionContext, id, initDatabase, isConnectionLevelError, onAfterCommit, optionalForeignKey, packageNameToSchema, publishingFields, reportDatabaseError, resetConnectionErrorCounter, runInTransaction, runWithTransaction, setDatabase, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };