@spfn/core 0.2.0-beta.34 → 0.2.0-beta.36

package/dist/db/index.d.ts

@@ -994,6 +994,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
  *
@@ -1602,4 +1674,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 { type AfterCommitCallback, 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, onAfterCommit, 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, foreignKey, fromPostgresError, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, id, initDatabase, onAfterCommit, optionalForeignKey, packageNameToSchema, publishingFields, runInTransaction, runWithTransaction, setDatabase, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };

package/dist/db/index.js

@@ -1,6 +1,7 @@
 import { drizzle } from 'drizzle-orm/postgres-js';
 import { env } from '@spfn/core/config';
 import { logger } from '@spfn/core/logger';
+import net from 'net';
 import postgres from 'postgres';
 import { QueryError, ConnectionError, DeadlockError, TransactionError, ConstraintViolationError, DuplicateEntryError, DatabaseError } from '@spfn/core/errors';
 import { parseNumber, parseBoolean } from '@spfn/core/env';
@@ -10,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 { count as count$1, sql, eq, and } from 'drizzle-orm';
+import { sql, count as count$1, eq, and } from 'drizzle-orm';
 
 // src/db/manager/factory.ts
 function parseUniqueViolation(message) {
@@ -129,6 +130,12 @@ function fromPostgresError(error) {
 }
 
 // src/db/manager/connection.ts
+function getSocketFamily() {
+  const family = process.env.DATABASE_SOCKET_FAMILY;
+  if (family === "4") return 4;
+  if (family === "6") return 6;
+  return void 0;
+}
 var dbLogger = logger.child("@spfn/core:database");
 var DEFAULT_CONNECT_TIMEOUT = 10;
 function delay(ms) {
@@ -189,10 +196,21 @@ async function createDatabaseConnection(connectionString, poolConfig, retryConfi
   let client;
   for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt++) {
     try {
+      const socketFamily = getSocketFamily();
       client = postgres(connectionString, {
         max: poolConfig.max,
         idle_timeout: poolConfig.idleTimeout,
-        connect_timeout: DEFAULT_CONNECT_TIMEOUT
+        connect_timeout: DEFAULT_CONNECT_TIMEOUT,
+        ...socketFamily && {
+          socket: ({ host, port }) => new Promise((resolve, reject) => {
+            const socket = new net.Socket();
+            socket.on("error", reject);
+            socket.connect(
+              { port: port[0], host: host[0], family: socketFamily },
+              () => resolve(socket)
+            );
+          })
+        }
       });
       await client`SELECT 1 as test`;
       if (attempt > 0) {
@@ -1900,6 +1918,6 @@ var BaseRepository = class {
   }
 };
 
-export { BaseRepository, RepositoryError, Transactional, 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, onAfterCommit, optionalForeignKey, packageNameToSchema, publishingFields, runWithTransaction, setDatabase, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };
+export { BaseRepository, RepositoryError, Transactional, 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, onAfterCommit, optionalForeignKey, packageNameToSchema, publishingFields, runInTransaction, runWithTransaction, setDatabase, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map