@spfn/core 0.1.0-alpha.64 → 0.1.0-alpha.68

package/dist/database-errors-CoPrcOpq.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Database Error Classes
+ *
+ * Type-safe error handling with custom error class hierarchy
+ * Mapped to HTTP status codes for API responses
+ */
+/**
+ * Base Database Error
+ *
+ * Base class for all database-related errors
+ */
+declare class DatabaseError<TDetails extends Record<string, unknown> = Record<string, unknown>> extends Error {
+    readonly statusCode: number;
+    readonly details?: TDetails;
+    readonly timestamp: Date;
+    constructor(message: string, statusCode?: number, details?: TDetails);
+    /**
+     * Serialize error for API response
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        statusCode: number;
+        details: TDetails | undefined;
+        timestamp: string;
+    };
+}
+/**
+ * Connection Error (503 Service Unavailable)
+ *
+ * Database connection failure, connection pool exhaustion, etc.
+ */
+declare class ConnectionError extends DatabaseError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Query Error (500 Internal Server Error)
+ *
+ * SQL query execution failure, syntax errors, etc.
+ */
+declare class QueryError extends DatabaseError {
+    constructor(message: string, statusCode?: number, details?: Record<string, any>);
+}
+/**
+ * Not Found Error (404 Not Found)
+ *
+ * Requested resource does not exist
+ */
+declare class NotFoundError extends QueryError {
+    constructor(resource: string, id: string | number);
+}
+/**
+ * Constraint Violation Error (400 Bad Request)
+ *
+ * Database constraint violation (NOT NULL, CHECK, FOREIGN KEY, etc.)
+ * This is different from HTTP ValidationError which validates request input
+ */
+declare class ConstraintViolationError extends QueryError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Transaction Error (500 Internal Server Error)
+ *
+ * Transaction start/commit/rollback failure
+ */
+declare class TransactionError extends DatabaseError {
+    constructor(message: string, statusCode?: number, details?: Record<string, any>);
+}
+/**
+ * Deadlock Error (409 Conflict)
+ *
+ * Database deadlock detected
+ */
+declare class DeadlockError extends TransactionError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Duplicate Entry Error (409 Conflict)
+ *
+ * Unique constraint violation (e.g., duplicate email)
+ */
+declare class DuplicateEntryError extends QueryError {
+    constructor(field: string, value: string | number);
+}
+
+export { ConnectionError as C, DatabaseError as D, NotFoundError as N, QueryError as Q, TransactionError as T, ConstraintViolationError as a, DeadlockError as b, DuplicateEntryError as c };

package/dist/db/index.d.ts

@@ -1,10 +1,11 @@
 import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import postgres, { Sql } from 'postgres';
-export { c as DrizzleConfigOptions, h as TransactionContext, n as TransactionDB, T as Transactional, j as TransactionalOptions, d as detectDialect, f as foreignKey, b as fromPostgresError, a as generateDrizzleConfigFile, g as getDrizzleConfig, e as getTransaction, i as id, o as optionalForeignKey, r as runWithTransaction, t as timestamps } from '../postgres-errors-lw1aRUFe.js';
-import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
-import { PgTable, PgColumn } from 'drizzle-orm/pg-core';
+import * as drizzle_orm from 'drizzle-orm';
 import { SQL } from 'drizzle-orm';
-import 'hono';
+import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
+import { PgColumn, PgTable } from 'drizzle-orm/pg-core';
+import * as hono from 'hono';
+import { D as DatabaseError } from '../database-errors-CoPrcOpq.js';
 
 /**
  * Database Configuration
@@ -151,7 +152,7 @@ type DbConnectionType = 'read' | 'write';
  * }
  * ```
  */
-declare function getDatabase(type?: DbConnectionType): PostgresJsDatabase | undefined;
+declare function getDatabase(type?: DbConnectionType): PostgresJsDatabase<Record<string, unknown>> | undefined;
 /**
  * Set global database instances (for testing or manual configuration)
  *
@@ -169,7 +170,7 @@ declare function getDatabase(type?: DbConnectionType): PostgresJsDatabase | unde
  * setDatabase(drizzle(writeClient), drizzle(readClient));
  * ```
  */
-declare function setDatabase(write: PostgresJsDatabase | undefined, read?: PostgresJsDatabase | undefined): void;
+declare function setDatabase(write: PostgresJsDatabase<Record<string, unknown>> | undefined, read?: PostgresJsDatabase<Record<string, unknown>> | undefined): void;
 /**
  * Initialize database from environment variables
  * Automatically called by server startup
@@ -217,8 +218,8 @@ declare function setDatabase(write: PostgresJsDatabase | undefined, read?: Postg
  * ```
  */
 declare function initDatabase(options?: DatabaseOptions): Promise<{
-    write?: PostgresJsDatabase;
-    read?: PostgresJsDatabase;
+    write?: PostgresJsDatabase<Record<string, unknown>>;
+    read?: PostgresJsDatabase<Record<string, unknown>>;
 }>;
 /**
  * Close all database connections and cleanup
@@ -269,6 +270,157 @@ declare function createDatabaseConnection(connectionString: string, poolConfig:
  */
 declare function checkConnection(client: Sql): Promise<boolean>;
 
+/**
+ * Drizzle Kit configuration generator
+ * Automatically generates drizzle.config.ts from environment variables
+ */
+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?: string | string[];
+    /** Migration output directory (defaults to './src/server/drizzle') */
+    out?: string;
+    /** Database dialect (auto-detected from URL if not provided) */
+    dialect?: 'postgresql' | 'mysql' | 'sqlite';
+    /** Current working directory for discovering package schemas */
+    cwd?: string;
+    /** Disable automatic package schema discovery */
+    disablePackageDiscovery?: boolean;
+    /** Only include schemas from specific package (e.g., '@spfn/cms') */
+    packageFilter?: string;
+}
+/**
+ * Detect database dialect from connection URL
+ */
+declare function detectDialect(url: string): 'postgresql' | 'mysql' | 'sqlite';
+/**
+ * Generate Drizzle Kit configuration
+ *
+ * @param options - Configuration options
+ * @returns Drizzle Kit configuration object
+ *
+ * @example
+ * ```ts
+ * // Zero-config (reads from process.env.DATABASE_URL)
+ * const config = getDrizzleConfig();
+ *
+ * // Custom config
+ * const config = getDrizzleConfig({
+ *   databaseUrl: 'postgresql://localhost/mydb',
+ *   schema: './src/db/schema/*.ts',
+ *   out: './migrations',
+ * });
+ * ```
+ */
+declare function getDrizzleConfig(options?: DrizzleConfigOptions): {
+    schema: string | string[];
+    out: string;
+    dialect: "postgresql" | "mysql" | "sqlite";
+    dbCredentials: {
+        url: string;
+    };
+};
+/**
+ * Generate drizzle.config.ts file content
+ *
+ * @param options - Configuration options
+ * @returns File content as string
+ */
+declare function generateDrizzleConfigFile(options?: DrizzleConfigOptions): string;
+
+/**
+ * Standard auto-incrementing primary key
+ *
+ * @returns bigserial primary key column
+ *
+ * @example
+ * ```typescript
+ * export const users = pgTable('users', {
+ *     id: id(),
+ *     // ...
+ * });
+ * ```
+ */
+declare function id(): drizzle_orm.IsPrimaryKey<drizzle_orm.NotNull<drizzle_orm_pg_core.PgBigSerial53BuilderInitial<"id">>>;
+/**
+ * Standard timestamp fields (createdAt, updatedAt)
+ *
+ * Both fields are timezone-aware, auto-set to current time on creation.
+ * When autoUpdate is enabled, updatedAt will be automatically updated on record updates.
+ *
+ * @param options - Optional configuration
+ * @param options.autoUpdate - Automatically update updatedAt on record updates (default: false)
+ * @returns Object with createdAt and updatedAt columns
+ *
+ * @example
+ * ```typescript
+ * // Without auto-update
+ * export const users = pgTable('users', {
+ *     id: id(),
+ *     email: text('email'),
+ *     ...timestamps(),
+ * });
+ *
+ * // With auto-update
+ * export const posts = pgTable('posts', {
+ *     id: id(),
+ *     title: text('title'),
+ *     ...timestamps({ autoUpdate: true }),
+ * });
+ * ```
+ */
+declare function timestamps(options?: {
+    autoUpdate?: boolean;
+}): {
+    createdAt: drizzle_orm.NotNull<drizzle_orm.HasDefault<drizzle_orm_pg_core.PgTimestampBuilderInitial<"created_at">>>;
+    updatedAt: drizzle_orm.NotNull<drizzle_orm.HasDefault<drizzle_orm_pg_core.PgTimestampBuilderInitial<"updated_at">>>;
+};
+/**
+ * Foreign key reference to another table
+ *
+ * Creates a bigserial 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')
+ * @param reference - Reference to parent table column
+ * @param options - Optional foreign key options
+ *
+ * @example
+ * ```typescript
+ * import { users } from './users';
+ *
+ * export const posts = pgTable('posts', {
+ *     id: id(),
+ *     authorId: foreignKey('author', () => users.id),
+ *     ...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`>>;
+/**
+ * Optional foreign key reference (nullable)
+ *
+ * Type-safe: ensures the reference points to a valid PostgreSQL column.
+ *
+ * @param name - Column name (e.g., 'author' creates 'author_id')
+ * @param reference - Reference to parent table column
+ * @param options - Optional foreign key options
+ *
+ * @example
+ * ```typescript
+ * export const posts = pgTable('posts', {
+ *     id: id(),
+ *     authorId: optionalForeignKey('author', () => users.id),
+ * });
+ * ```
+ */
+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`>;
+
 /**
  * Database Schema Helper
  *
@@ -330,6 +482,161 @@ declare function getSchemaInfo(packageName: string): {
     scope: string | null;
 };
 
+/**
+ * AsyncLocalStorage-based Transaction Context
+ *
+ * Uses Node.js AsyncLocalStorage to propagate transactions throughout the async call chain.
+ *
+ * Features:
+ * - AsyncLocalStorage-based context management
+ * - Type-safe transaction propagation across async chains
+ * - Transaction ID tracking for debugging and tracing
+ * - Nested transaction detection and logging
+ * - Transaction nesting level tracking
+ */
+
+/**
+ * Transaction database type
+ * Uses Record<string, unknown> to accept any schema shape
+ */
+type TransactionDB = PostgresJsDatabase<Record<string, unknown>>;
+/**
+ * Transaction context stored in AsyncLocalStorage
+ */
+type TransactionContext = {
+    /** The actual Drizzle transaction object */
+    tx: TransactionDB;
+    /** Unique transaction ID for logging and tracing */
+    txId: string;
+    level: number;
+};
+/**
+ * Get current transaction from AsyncLocalStorage
+ *
+ * @returns Transaction if available, null otherwise
+ */
+declare function getTransaction(): TransactionDB | null;
+/**
+ * Run a function within a transaction context
+ *
+ * The transaction will be available to all async operations within the callback
+ * via getTransaction().
+ *
+ * @param tx - Drizzle transaction object
+ * @param txId - Unique ID for the transaction
+ * @param callback - Function to run within transaction context
+ * @returns Result of the callback
+ */
+declare function runWithTransaction<T>(tx: TransactionDB, txId: string, // Add txId parameter
+callback: () => Promise<T>): Promise<T>;
+
+/**
+ * Transaction middleware options
+ */
+interface TransactionalOptions {
+    /**
+     * Slow transaction warning threshold in milliseconds
+     * @default 1000 (1 second)
+     */
+    slowThreshold?: number;
+    /**
+     * Enable transaction logging
+     * @default true
+     */
+    enableLogging?: boolean;
+    /**
+     * Transaction timeout in milliseconds
+     *
+     * If transaction exceeds this duration, it will be aborted with TransactionError.
+     *
+     * @default 30000 (30 seconds) or TRANSACTION_TIMEOUT environment variable
+     *
+     * @example
+     * ```typescript
+     * // Default timeout (30s or TRANSACTION_TIMEOUT env var)
+     * Transactional()
+     *
+     * // Custom timeout for specific route (60s)
+     * Transactional({ timeout: 60000 })
+     *
+     * // Disable timeout
+     * Transactional({ timeout: 0 })
+     * ```
+     */
+    timeout?: number;
+}
+/**
+ * Transaction middleware for Hono routes
+ *
+ * Automatically wraps route handlers in a database transaction.
+ * Commits on success, rolls back on error.
+ *
+ * @example
+ * ```typescript
+ * // In your route file
+ * export const middlewares = [Transactional()];
+ *
+ * export async function POST(c: RouteContext) {
+ *   // All DB operations run in a transaction
+ *   const [user] = await db.insert(users).values(body).returning();
+ *   await db.insert(profiles).values({ userId: user.id });
+ *   // Auto-commits on success
+ *   return c.json(user, 201);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom options
+ * export const middlewares = [
+ *   Transactional({
+ *     slowThreshold: 2000,    // Warn if transaction takes > 2s
+ *     enableLogging: false,   // Disable logging
+ *     timeout: 60000,         // 60 second timeout for long operations
+ *   })
+ * ];
+ * ```
+ *
+ * 🔄 Transaction behavior:
+ * - Success: Auto-commit
+ * - Error: Auto-rollback
+ * - Detects context.error to trigger rollback
+ *
+ * 📊 Transaction logging:
+ * - Auto-logs transaction start/commit/rollback
+ * - Measures and records execution time
+ * - Warns about slow transactions (default: > 1s)
+ */
+declare function Transactional(options?: TransactionalOptions): hono.MiddlewareHandler<any, string, {}>;
+
+/**
+ * PostgreSQL Error Conversion Utilities
+ *
+ * Converts PostgreSQL-specific error codes to custom error types
+ * @see https://www.postgresql.org/docs/current/errcodes-appendix.html
+ */
+
+/**
+ * Convert PostgreSQL error to custom DatabaseError
+ *
+ * Maps PostgreSQL error codes to appropriate error classes with correct status codes
+ *
+ * @param error - PostgreSQL error object (from pg driver or Drizzle)
+ * @returns Custom DatabaseError instance
+ *
+ * @example
+ * ```typescript
+ * import { fromPostgresError } from '@spfn/core/db';
+ *
+ * try {
+ *   await db.insert(users).values(data);
+ * } catch (pgError) {
+ *   throw fromPostgresError(pgError);
+ * }
+ * ```
+ */
+declare function fromPostgresError(error: any): DatabaseError;
+
 /**
  * Database Helper Functions
  *
@@ -573,4 +880,4 @@ declare function deleteMany<T extends PgTable>(table: T, where: WhereObject<Infe
  */
 declare function count<T extends PgTable>(table: T, where?: WhereObject<InferSelectModel<T>> | SQL | undefined): Promise<number>;
 
-export { type DatabaseClients, type PoolConfig, type RetryConfig, checkConnection, closeDatabase, count, create, createDatabaseConnection, createDatabaseFromEnv, createFunctionSchema, createMany, deleteMany, deleteOne, findMany, findOne, getDatabase, getDatabaseInfo, getSchemaInfo, initDatabase, packageNameToSchema, setDatabase, updateMany, updateOne, upsert };
+export { type DatabaseClients, type DrizzleConfigOptions, type PoolConfig, type RetryConfig, type TransactionContext, type TransactionDB, Transactional, type TransactionalOptions, checkConnection, closeDatabase, count, create, createDatabaseConnection, createDatabaseFromEnv, createFunctionSchema, createMany, deleteMany, deleteOne, detectDialect, findMany, findOne, foreignKey, fromPostgresError, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, id, initDatabase, optionalForeignKey, packageNameToSchema, runWithTransaction, setDatabase, timestamps, updateMany, updateOne, upsert };

package/dist/db/index.js

@@ -1009,10 +1009,10 @@ var QueryError = class extends DatabaseError {
     this.name = "QueryError";
   }
 };
-var ValidationError = class extends QueryError {
+var ConstraintViolationError = class extends QueryError {
   constructor(message, details) {
     super(message, 400, details);
-    this.name = "ValidationError";
+    this.name = "ConstraintViolationError";
   }
 };
 var TransactionError = class extends DatabaseError {
@@ -1077,11 +1077,11 @@ function fromPostgresError(error) {
     case "23000":
     // integrity_constraint_violation
     case "23001":
-      return new ValidationError(message, { code, constraint: "integrity" });
+      return new ConstraintViolationError(message, { code, constraint: "integrity" });
     case "23502":
-      return new ValidationError(message, { code, constraint: "not_null" });
+      return new ConstraintViolationError(message, { code, constraint: "not_null" });
     case "23503":
-      return new ValidationError(message, { code, constraint: "foreign_key" });
+      return new ConstraintViolationError(message, { code, constraint: "foreign_key" });
     case "23505":
       const parsed = parseUniqueViolation(message);
       if (parsed) {
@@ -1089,7 +1089,7 @@ function fromPostgresError(error) {
       }
       return new DuplicateEntryError("field", "value");
     case "23514":
-      return new ValidationError(message, { code, constraint: "check" });
+      return new ConstraintViolationError(message, { code, constraint: "check" });
     // Class 40 — Transaction Rollback
     case "40000":
     // transaction_rollback