@spfn/core 0.1.0-alpha.88 → 0.2.0-beta.1

package/dist/db/index.d.ts

@@ -4,22 +4,23 @@ import * as drizzle_orm from 'drizzle-orm';
 import { SQL } from 'drizzle-orm';
 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-BNNmLTJE.js';
+import * as hono_types from 'hono/types';
+import { DatabaseError } from '@spfn/core/errors';
 
 /**
  * Database Configuration
  *
- * DB 연결 및 Connection Pool 설정
+ * Database connection and connection pool configuration.
  *
- * ✅ 구현 완료:
- * - 환경별 Connection Pool 설정
- * - 재시도 설정 (Exponential Backoff)
- * - 환경변수 기반 설정
- *
- * 🔗 관련 파일:
- * - src/server/core/db/connection.ts (연결 로직)
- * - src/server/core/db/index.ts (메인 export)
+ * Features:
+ * - Environment-specific connection pool configuration
+ * - Retry configuration with exponential backoff
+ * - Environment variable-based configuration
+ * - Health check and monitoring configuration
+ *
+ * Related files:
+ * - src/server/core/db/connection.ts (connection logic)
+ * - src/server/core/db/index.ts (main exports)
  */
 
 interface DatabaseClients {
@@ -71,19 +72,29 @@ interface DatabaseOptions {
     monitoring?: Partial<MonitoringConfig>;
 }
 /**
- * Connection Pool 설정
+ * Connection pool configuration
+ *
+ * Controls the maximum number of connections and idle timeout behavior.
  */
 interface PoolConfig {
+    /** Maximum number of connections in the pool */
     max: number;
+    /** Idle connection timeout in seconds */
     idleTimeout: number;
 }
 /**
- * 재시도 설정
+ * Retry configuration for exponential backoff algorithm
+ *
+ * Controls retry behavior when connection attempts fail.
  */
 interface RetryConfig {
+    /** Maximum number of retry attempts */
     maxRetries: number;
+    /** Initial delay between retries in milliseconds */
     initialDelay: number;
+    /** Maximum delay cap in milliseconds */
     maxDelay: number;
+    /** Exponential backoff factor (delay multiplier) */
     factor: number;
 }
 
@@ -96,12 +107,12 @@ interface RetryConfig {
  * Create database client(s) from environment variables
  *
  * Supported patterns (priority order):
- * 1. Single primary: DATABASE_URL
- * 2. Primary + Replica: DATABASE_WRITE_URL + DATABASE_READ_URL
- * 3. Legacy replica: DATABASE_URL + DATABASE_REPLICA_URL
+ * 1. Primary + Replica: DATABASE_WRITE_URL + DATABASE_READ_URL
+ * 2. Single primary: DATABASE_URL
  *
  * @param options - Optional database configuration (pool settings, etc.)
- * @returns Database client(s) or undefined if no configuration found
+ * @returns Database client(s)
+ * @throws {Error} If no database configuration is found or connection fails
  *
  * @example
  * ```bash
@@ -111,10 +122,6 @@ interface RetryConfig {
  * # Primary + Replica
  * DATABASE_WRITE_URL=postgresql://primary:5432/mydb
  * DATABASE_READ_URL=postgresql://replica:5432/mydb
- *
- * # Legacy (backward compatibility)
- * DATABASE_URL=postgresql://primary:5432/mydb
- * DATABASE_REPLICA_URL=postgresql://replica:5432/mydb
  * ```
  *
  * @example
@@ -128,36 +135,54 @@ interface RetryConfig {
 declare function createDatabaseFromEnv(options?: DatabaseOptions): Promise<DatabaseClients>;
 
 /**
- * Global Database instance manager
- * Provides singleton access to database across all modules
- * Supports Primary + Replica pattern with separate read/write instances
+ * Database Manager Types
  */
 
 /**
  * DB connection type
  */
 type DbConnectionType = 'read' | 'write';
+
+/**
+ * Global Database instance manager
+ * Provides singleton access to database across all modules
+ * Supports Primary + Replica pattern with separate read/write instances
+ */
+
 /**
- * Get global database write instance
+ * Get global database instance
  *
- * @returns Database write instance or undefined if not initialized
+ * @param type - Connection type ('read' or 'write', defaults to 'write')
+ * @returns Database instance (never undefined)
+ * @throws Error if database is not initialized
  *
  * @example
  * ```typescript
  * import { getDatabase } from '@spfn/core/db';
  *
+ * // Always returns a valid instance or throws
  * const db = getDatabase();
- * if (db) {
- *   const users = await db.select().from(usersTable);
- * }
+ * const users = await db.select().from(usersTable);
+ *
+ * // For read operations (uses replica if available, falls back to primary)
+ * const dbRead = getDatabase('read');
+ * const posts = await dbRead.select().from(postsTable);
  * ```
  */
-declare function getDatabase(type?: DbConnectionType): PostgresJsDatabase<Record<string, unknown>> | undefined;
+declare function getDatabase(type?: DbConnectionType): PostgresJsDatabase<Record<string, unknown>>;
 /**
  * Set global database instances (for testing or manual configuration)
  *
- * @param write - Database write instance
- * @param read - Database read instance (optional, defaults to write)
+ * This function directly sets database instances without creating connections
+ * or performing validation. It's primarily intended for testing scenarios.
+ *
+ * @param write - Database write instance (pass undefined to clear)
+ * @param read - Database read instance (optional, defaults to write, pass undefined to clear)
+ *
+ * @remarks
+ * **Important:** To properly close database connections with cleanup, use `closeDatabase()` instead.
+ * This function only updates the global instances without closing the underlying connections.
+ * Setting both to undefined will clear the instances but leave connections open, which may cause resource leaks.
  *
  * @example
  * ```typescript
@@ -165,9 +190,13 @@ declare function getDatabase(type?: DbConnectionType): PostgresJsDatabase<Record
  * import { drizzle } from 'drizzle-orm/postgres-js';
  * import postgres from 'postgres';
  *
+ * // Set custom database instances (testing)
  * const writeClient = postgres('postgresql://primary:5432/mydb');
  * const readClient = postgres('postgresql://replica:5432/mydb');
  * setDatabase(drizzle(writeClient), drizzle(readClient));
+ *
+ * // Clear instances (not recommended - use closeDatabase() instead)
+ * setDatabase(undefined, undefined);
  * ```
  */
 declare function setDatabase(write: PostgresJsDatabase<Record<string, unknown>> | undefined, read?: PostgresJsDatabase<Record<string, unknown>> | undefined): void;
@@ -178,7 +207,6 @@ declare function setDatabase(write: PostgresJsDatabase<Record<string, unknown>>
  * Supported environment variables:
  * - DATABASE_URL (single primary)
  * - DATABASE_WRITE_URL + DATABASE_READ_URL (primary + replica)
- * - DATABASE_URL + DATABASE_REPLICA_URL (legacy replica)
  * - DB_POOL_MAX (connection pool max size)
  * - DB_POOL_IDLE_TIMEOUT (connection idle timeout in seconds)
  * - DB_HEALTH_CHECK_ENABLED (enable health checks, default: true)
@@ -247,6 +275,32 @@ declare function initDatabase(options?: DatabaseOptions): Promise<{
 declare function closeDatabase(): Promise<void>;
 /**
  * Get database connection info (for debugging)
+ *
+ * Returns the current state of database connections without throwing errors.
+ * Useful for health checks, monitoring, and debugging initialization issues.
+ *
+ * @returns Connection status information
+ * - `hasWrite`: Whether write database instance is initialized
+ * - `hasRead`: Whether read database instance is initialized
+ * - `isReplica`: Whether read and write are different instances (Primary + Replica setup)
+ *
+ * @example
+ * ```typescript
+ * import { getDatabaseInfo } from '@spfn/core/db';
+ *
+ * const info = getDatabaseInfo();
+ * console.log(`Write: ${info.hasWrite}, Read: ${info.hasRead}, Replica: ${info.isReplica}`);
+ *
+ * // Check before using database
+ * if (!info.hasWrite) {
+ *   console.warn('Database not initialized');
+ * }
+ *
+ * // Detect Primary + Replica setup
+ * if (info.isReplica) {
+ *   console.log('Using Primary + Replica configuration');
+ * }
+ * ```
  */
 declare function getDatabaseInfo(): {
     hasWrite: boolean;
@@ -255,19 +309,49 @@ declare function getDatabaseInfo(): {
 };
 
 /**
- * Exponential Backoff로 DB 연결 생성
+ * Create database connection with exponential backoff retry strategy
+ *
+ * Attempts to establish a database connection with automatic retries using
+ * exponential backoff with jitter. Non-retryable errors (authentication,
+ * database not found, SSL issues) fail immediately.
+ *
+ * Retry Strategy:
+ * - Exponential backoff: delay = initialDelay * (factor ^ attempt)
+ * - Jitter: randomized delay between 50-100% of calculated delay
+ * - Max delay cap: prevents excessive wait times
  *
- * @param connectionString - PostgreSQL 연결 문자열
- * @param poolConfig - Connection Pool 설정
- * @param retryConfig - 재시도 설정
- * @returns PostgreSQL 클라이언트
+ * @param connectionString - PostgreSQL connection string
+ * @param poolConfig - Connection pool configuration
+ * @param retryConfig - Retry configuration (max attempts, delays, etc.)
+ * @returns PostgreSQL client instance
+ * @throws ConnectionError if connection fails after all retries or on non-retryable errors
+ *
+ * @example
+ * ```typescript
+ * const client = await createDatabaseConnection(
+ *   'postgresql://localhost:5432/mydb',
+ *   { max: 20, idleTimeout: 30 },
+ *   { maxRetries: 5, initialDelay: 100, maxDelay: 10000, factor: 2 }
+ * );
+ * ```
  */
 declare function createDatabaseConnection(connectionString: string, poolConfig: PoolConfig, retryConfig: RetryConfig): Promise<postgres.Sql<{}>>;
 /**
- * DB 연결 상태 확인
+ * Check database connection health
+ *
+ * Uses the client's configured timeout settings (connect_timeout, etc.).
+ * Executes a simple SELECT query to verify the connection is alive.
  *
- * @param client - PostgreSQL 클라이언트
- * @returns 연결 가능 여부
+ * @param client - PostgreSQL client to check
+ * @returns true if connection is healthy, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isHealthy = await checkConnection(client);
+ * if (!isHealthy) {
+ *   console.error('Database connection is down');
+ * }
+ * ```
  */
 declare function checkConnection(client: Sql): Promise<boolean>;
 
@@ -290,6 +374,8 @@ interface DrizzleConfigOptions {
     disablePackageDiscovery?: boolean;
     /** Only include schemas from specific package (e.g., '@spfn/cms') */
     packageFilter?: string;
+    /** Expand glob patterns to actual file paths (useful for Drizzle Studio) */
+    expandGlobs?: boolean;
 }
 /**
  * Detect database dialect from connection URL
@@ -348,32 +434,28 @@ declare function id(): drizzle_orm.IsPrimaryKey<drizzle_orm.NotNull<drizzle_orm_
  * 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.
+ * updatedAt must be manually updated in your application code.
  *
- * @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 }),
- * });
+ * // Manual update
+ * await db.update(users)
+ *     .set({
+ *         email: 'new@example.com',
+ *         updatedAt: new Date()
+ *     })
+ *     .where(eq(users.id, userId));
  * ```
  */
-declare function timestamps(options?: {
-    autoUpdate?: boolean;
-}): {
+declare function timestamps(): {
     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">>>;
 };
@@ -421,6 +503,256 @@ 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`>;
+/**
+ * UUID primary key
+ *
+ * Creates a UUID column as primary key with automatic default value generation.
+ * Useful for distributed systems or when you need globally unique identifiers.
+ *
+ * @returns uuid primary key column with gen_random_uuid() default
+ *
+ * @example
+ * ```typescript
+ * export const sessions = pgTable('sessions', {
+ *     id: uuid(),
+ *     userId: foreignKey('user', () => users.id),
+ *     ...timestamps(),
+ * });
+ * ```
+ */
+declare function uuid(): drizzle_orm.IsPrimaryKey<drizzle_orm.NotNull<drizzle_orm.HasDefault<drizzle_orm_pg_core.PgUUIDBuilderInitial<"id">>>>;
+/**
+ * Audit fields for tracking record creators and updaters
+ *
+ * Adds createdBy and updatedBy fields for user tracking.
+ * Typically stores user IDs, emails, or usernames.
+ *
+ * @returns Object with createdBy and updatedBy columns
+ *
+ * @example
+ * ```typescript
+ * export const posts = pgTable('posts', {
+ *     id: id(),
+ *     title: text('title'),
+ *     ...timestamps(),
+ *     ...auditFields(),
+ * });
+ *
+ * // Usage in route
+ * await db.insert(posts).values({
+ *     title: 'New Post',
+ *     createdBy: currentUser.email,
+ * });
+ * ```
+ */
+declare function auditFields(): {
+    createdBy: drizzle_orm_pg_core.PgTextBuilderInitial<"created_by", [string, ...string[]]>;
+    updatedBy: drizzle_orm_pg_core.PgTextBuilderInitial<"updated_by", [string, ...string[]]>;
+};
+/**
+ * Publishing fields for content management
+ *
+ * Tracks when and by whom content was published.
+ * Useful for CMS, blog posts, articles, etc.
+ *
+ * @returns Object with publishedAt and publishedBy columns
+ *
+ * @example
+ * ```typescript
+ * export const articles = pgTable('articles', {
+ *     id: id(),
+ *     title: text('title'),
+ *     status: text('status'), // draft/published/archived
+ *     ...publishingFields(),
+ *     ...timestamps(),
+ * });
+ *
+ * // Publishing an article
+ * await db.update(articles)
+ *     .set({
+ *         status: 'published',
+ *         publishedAt: new Date(),
+ *         publishedBy: currentUser.email,
+ *     })
+ *     .where(eq(articles.id, articleId));
+ * ```
+ */
+declare function publishingFields(): {
+    publishedAt: drizzle_orm_pg_core.PgTimestampBuilderInitial<"published_at">;
+    publishedBy: drizzle_orm_pg_core.PgTextBuilderInitial<"published_by", [string, ...string[]]>;
+};
+/**
+ * Custom verification timestamp field
+ *
+ * Creates a nullable timestamp field for tracking verification status.
+ * Useful for email verification, phone verification, etc.
+ *
+ * @param fieldName - Field name in camelCase (e.g., 'emailVerified', 'phoneVerified')
+ * @returns Object with verification timestamp column (converts to snake_case + '_at')
+ *
+ * @example
+ * ```typescript
+ * export const users = pgTable('users', {
+ *     id: id(),
+ *     email: text('email'),
+ *     phone: text('phone'),
+ *     ...verificationTimestamp('emailVerified'),  // emailVerifiedAt -> email_verified_at
+ *     ...verificationTimestamp('phoneVerified'),  // phoneVerifiedAt -> phone_verified_at
+ *     ...timestamps(),
+ * });
+ *
+ * // Verify email
+ * await db.update(users)
+ *     .set({ emailVerifiedAt: new Date() })
+ *     .where(eq(users.email, userEmail));
+ * ```
+ */
+declare function verificationTimestamp(fieldName: string): {
+    [x: string]: drizzle_orm_pg_core.PgTimestampBuilderInitial<string>;
+};
+/**
+ * Soft delete fields
+ *
+ * Adds deletedAt and deletedBy for logical deletion.
+ * Records are marked as deleted instead of being physically removed.
+ *
+ * @returns Object with deletedAt and deletedBy columns
+ *
+ * @example
+ * ```typescript
+ * export const posts = pgTable('posts', {
+ *     id: id(),
+ *     title: text('title'),
+ *     ...timestamps(),
+ *     ...softDelete(),
+ * });
+ *
+ * // Soft delete
+ * await db.update(posts)
+ *     .set({
+ *         deletedAt: new Date(),
+ *         deletedBy: currentUser.email,
+ *     })
+ *     .where(eq(posts.id, postId));
+ *
+ * // Query only non-deleted records
+ * const activePosts = await db.select()
+ *     .from(posts)
+ *     .where(isNull(posts.deletedAt));
+ * ```
+ */
+declare function softDelete(): {
+    deletedAt: drizzle_orm_pg_core.PgTimestampBuilderInitial<"deleted_at">;
+    deletedBy: drizzle_orm_pg_core.PgTextBuilderInitial<"deleted_by", [string, ...string[]]>;
+};
+/**
+ * UTC timestamp field
+ *
+ * Creates a timezone-aware timestamp column (TIMESTAMPTZ) that stores values in UTC.
+ * PostgreSQL automatically converts between client timezone and UTC.
+ * Chain with .notNull(), .defaultNow(), etc. for additional constraints.
+ *
+ * @param fieldName - Database column name (in snake_case)
+ * @param mode - Data type mode: 'date' (Date object) or 'string' (ISO string)
+ * @returns Timestamp column with timezone support
+ *
+ * @example
+ * ```typescript
+ * export const users = pgTable('users', {
+ *     id: id(),
+ *     email: text('email'),
+ *
+ *     // Nullable timestamp
+ *     emailVerifiedAt: utcTimestamp('email_verified_at'),
+ *
+ *     // Required with default
+ *     lastLoginAt: utcTimestamp('last_login_at').defaultNow().notNull(),
+ *
+ *     // String mode
+ *     processedAt: utcTimestamp('processed_at', 'string'),
+ *
+ *     ...timestamps(),
+ * });
+ * ```
+ */
+declare function utcTimestamp(fieldName: string, mode?: 'date' | 'string'): drizzle_orm_pg_core.PgTimestampBuilderInitial<string>;
+/**
+ * Type-safe enum text field
+ *
+ * Creates a text column with enum constraint.
+ * Chain with .notNull(), .default(), etc. for additional constraints.
+ *
+ * @param fieldName - Database column name (e.g., 'status', 'role', 'provider')
+ * @param values - Const array of allowed values
+ * @returns Text column with enum constraint
+ *
+ * @example
+ * ```typescript
+ * export const USER_STATUSES = ['active', 'inactive', 'suspended'] as const;
+ * export type UserStatus = typeof USER_STATUSES[number];
+ *
+ * export const SOCIAL_PROVIDERS = ['google', 'github', 'kakao'] as const;
+ * export type SocialProvider = typeof SOCIAL_PROVIDERS[number];
+ *
+ * export const users = pgTable('users', {
+ *     id: id(),
+ *     // Nullable
+ *     role: enumText('role', USER_STATUSES),
+ *
+ *     // Required
+ *     provider: enumText('provider', SOCIAL_PROVIDERS).notNull(),
+ *
+ *     // Required with default
+ *     status: enumText('status', USER_STATUSES).default('active').notNull(),
+ *
+ *     ...timestamps(),
+ * });
+ * ```
+ */
+declare function enumText<T extends readonly [string, ...string[]]>(fieldName: string, values: T): drizzle_orm_pg_core.PgTextBuilderInitial<string, drizzle_orm.Writable<T & [string, ...string[]]>>;
+/**
+ * Type-safe JSONB field
+ *
+ * Creates a JSONB column with required type parameter to ensure type safety.
+ * Prevents the common mistake of using jsonb without type annotation,
+ * which would result in `unknown` type and require type assertions.
+ *
+ * Chain with .notNull(), .default(), etc. for additional constraints.
+ *
+ * @param fieldName - Database column name (in snake_case)
+ * @returns JSONB column with specified type
+ *
+ * @example
+ * ```typescript
+ * // Define your types
+ * type LabelValue =
+ *   | { type: 'text'; content: string }
+ *   | { type: 'image'; url: string; alt?: string };
+ *
+ * type CachedContent = Record<string, LabelValue>;
+ *
+ * export const cmsPublishedCache = pgTable('published_cache', {
+ *     id: id(),
+ *     section: text('section').notNull(),
+ *
+ *     // Type-safe JSONB field - no more `as any` needed!
+ *     content: typedJsonb<CachedContent>('content').notNull(),
+ *
+ *     ...timestamps(),
+ * });
+ *
+ * // Usage in route - no type assertion needed
+ * const cache = await db.select().from(cmsPublishedCache)...;
+ * const labels = cache.content; // Type: CachedContent ✅
+ *
+ * // For simple objects
+ * metadata: typedJsonb<Record<string, any>>('metadata'),
+ *
+ * // For arrays
+ * tags: typedJsonb<string[]>('tags').notNull(),
+ * ```
+ */
+declare function typedJsonb<T>(fieldName: string): drizzle_orm.$Type<drizzle_orm_pg_core.PgJsonbBuilderInitial<string>, T>;
 
 /**
  * Database Schema Helper
@@ -436,9 +768,9 @@ declare function optionalForeignKey<T extends PgColumn>(name: string, reference:
  * @example
  * ```typescript
  * // @spfn/cms → spfn_cms schema
- * import { createFunctionSchema } from '@spfn/core/db';
+ * import { createSchema } from '@spfn/core/db';
  *
- * const schema = createFunctionSchema('@spfn/cms');
+ * const schema = createSchema('@spfn/cms');
  *
  * export const labels = schema.table('labels', {
  *   id: id(),
@@ -447,7 +779,7 @@ declare function optionalForeignKey<T extends PgColumn>(name: string, reference:
  * // Creates table: spfn_cms.labels
  * ```
  */
-declare function createFunctionSchema(packageName: string): drizzle_orm_pg_core.PgSchema<string>;
+declare function createSchema(packageName: string): drizzle_orm_pg_core.PgSchema<string>;
 /**
  * Convert package name to PostgreSQL schema name
  *
@@ -608,7 +940,7 @@ interface TransactionalOptions {
  * - Measures and records execution time
  * - Warns about slow transactions (default: > 1s)
  */
-declare function Transactional(options?: TransactionalOptions): hono.MiddlewareHandler<any, string, {}>;
+declare function Transactional(options?: TransactionalOptions): hono_types.MiddlewareHandler<any, string, {}, Response>;
 
 /**
  * PostgreSQL Error Conversion Utilities
@@ -881,4 +1213,341 @@ 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 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 };
+/**
+ * Base Repository Pattern
+ *
+ * Provides automatic database instance management with transaction context support.
+ * Eliminates the need for manual `getDatabaseOrThrow()` calls in repository classes.
+ *
+ * Features:
+ * - Automatic transaction context detection and usage
+ * - Read/Write connection separation (with replica support)
+ * - Type-safe schema generics
+ * - Consistent database access pattern across all repositories
+ * - Enhanced error tracking with repository context
+ *
+ * @example Basic Repository
+ * ```typescript
+ * import { BaseRepository } from '@spfn/core/db';
+ * import { users } from './schema';
+ * import { eq } from 'drizzle-orm';
+ *
+ * export class UserRepository extends BaseRepository {
+ *     async findById(id: string) {
+ *         // Uses read replica when available
+ *         return await this.readDb
+ *             .select()
+ *             .from(users)
+ *             .where(eq(users.id, id));
+ *     }
+ *
+ *     async create(data: NewUser) {
+ *         // Uses write primary
+ *         return await this.db
+ *             .insert(users)
+ *             .values(data)
+ *             .returning();
+ *     }
+ * }
+ * ```
+ *
+ * @example With Transactions
+ * ```typescript
+ * import { runWithTransaction } from '@spfn/core/db';
+ *
+ * const userRepo = new UserRepository();
+ *
+ * await runWithTransaction(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
+ * });
+ * ```
+ *
+ * @example With Custom Schema Type
+ * ```typescript
+ * import type { AppSchema } from './schema';
+ *
+ * export class UserRepository extends BaseRepository<AppSchema> {
+ *     // Now this.db and this.readDb are typed with AppSchema
+ * }
+ * ```
+ *
+ * @example With Enhanced Error Tracking
+ * ```typescript
+ * export class UserRepository extends BaseRepository {
+ *     async updateStatus(id: string, status: string) {
+ *         // Errors will include repository context automatically
+ *         return await this.db
+ *             .update(users)
+ *             .set({ status })
+ *             .where(eq(users.id, id))
+ *             .returning();
+ *     }
+ * }
+ * // On error: logs will show "UserRepository" context
+ * ```
+ */
+
+/**
+ * Enhanced error class that includes repository context
+ */
+declare class RepositoryError extends Error {
+    readonly repository: string;
+    readonly method?: string | undefined;
+    readonly table?: string | undefined;
+    readonly originalError?: Error | undefined;
+    constructor(message: string, repository: string, method?: string | undefined, table?: string | undefined, originalError?: Error | undefined);
+}
+/**
+ * Base Repository class for database operations
+ *
+ * Provides automatic database instance management with transaction support.
+ * Extend this class to create domain-specific repositories.
+ *
+ * The repository automatically detects if running within a transaction context
+ * and uses the appropriate database instance:
+ * - Inside transaction: Uses transaction DB
+ * - Outside transaction: Uses global DB instance (with read/write separation)
+ *
+ * @template TSchema - Database schema type (defaults to Record<string, unknown>)
+ */
+declare abstract class BaseRepository<TSchema extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Write database instance
+     *
+     * Automatically resolves to:
+     * - Transaction DB if running within transaction context
+     * - Global write (primary) instance otherwise
+     *
+     * Use this for INSERT, UPDATE, DELETE operations.
+     *
+     * @example
+     * ```typescript
+     * async create(data: NewUser) {
+     *     return await this.db.insert(users).values(data).returning();
+     * }
+     * ```
+     */
+    protected get db(): PostgresJsDatabase<TSchema>;
+    /**
+     * Read database instance
+     *
+     * Automatically resolves to:
+     * - Transaction DB if running within transaction context
+     * - Global read (replica) instance otherwise
+     *
+     * Use this for SELECT operations to leverage read replicas
+     * and reduce load on the primary database.
+     *
+     * @example
+     * ```typescript
+     * async findById(id: string) {
+     *     return await this.readDb
+     *         .select()
+     *         .from(users)
+     *         .where(eq(users.id, id));
+     * }
+     * ```
+     */
+    protected get readDb(): PostgresJsDatabase<TSchema>;
+    /**
+     * Wrap query execution with repository context
+     *
+     * Enhances error messages with repository information to make debugging easier.
+     * When an error occurs, it will include:
+     * - Repository class name
+     * - Method name
+     * - Table name (if provided)
+     * - Original error details
+     *
+     * @param queryFn - Query function to execute
+     * @param context - Context information (operation name, table name, etc.)
+     * @returns Query result
+     * @throws RepositoryError with enhanced context
+     *
+     * @example
+     * ```typescript
+     * async findById(id: number) {
+     *     return await this.withContext(
+     *         () => this.readDb.select().from(users).where(eq(users.id, id)),
+     *         { method: 'findById', table: 'users' }
+     *     );
+     * }
+     * ```
+     */
+    protected withContext<T>(queryFn: () => Promise<T>, context?: {
+        method?: string;
+        table?: string;
+    }): Promise<T>;
+    /**
+     * Find a single record
+     *
+     * @param table - Drizzle table schema
+     * @param where - Object or SQL condition
+     * @returns Single record or null
+     *
+     * @example
+     * ```typescript
+     * // Object-based
+     * const user = await this._findOne(users, { id: 1 });
+     *
+     * // SQL-based
+     * const user = await this._findOne(users, eq(users.id, 1));
+     * ```
+     */
+    protected _findOne<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined): Promise<T['$inferSelect'] | null>;
+    /**
+     * Find multiple records
+     *
+     * @param table - Drizzle table schema
+     * @param options - Query options
+     * @returns Array of records
+     *
+     * @example
+     * ```typescript
+     * const users = await this._findMany(users, {
+     *     where: { active: true },
+     *     orderBy: desc(users.createdAt),
+     *     limit: 10
+     * });
+     * ```
+     */
+    protected _findMany<T extends PgTable>(table: T, options?: {
+        where?: Record<string, any> | SQL | undefined;
+        orderBy?: SQL | SQL[];
+        limit?: number;
+        offset?: number;
+    }): Promise<T['$inferSelect'][]>;
+    /**
+     * Create a new record
+     *
+     * @param table - Drizzle table schema
+     * @param data - Insert data
+     * @returns Created record
+     *
+     * @example
+     * ```typescript
+     * const user = await this._create(users, {
+     *     email: 'test@example.com',
+     *     name: 'Test User'
+     * });
+     * ```
+     */
+    protected _create<T extends PgTable>(table: T, data: T['$inferInsert']): Promise<T['$inferSelect']>;
+    /**
+     * Create multiple records
+     *
+     * @param table - Drizzle table schema
+     * @param data - Array of insert data
+     * @returns Array of created records
+     *
+     * @example
+     * ```typescript
+     * const users = await this._createMany(users, [
+     *     { email: 'user1@example.com', name: 'User 1' },
+     *     { email: 'user2@example.com', name: 'User 2' }
+     * ]);
+     * ```
+     */
+    protected _createMany<T extends PgTable>(table: T, data: T['$inferInsert'][]): Promise<T['$inferSelect'][]>;
+    /**
+     * Upsert a record (INSERT or UPDATE on conflict)
+     *
+     * @param table - Drizzle table schema
+     * @param data - Insert data
+     * @param options - Conflict resolution options
+     * @returns Upserted record
+     *
+     * @example
+     * ```typescript
+     * const cache = await this._upsert(cache, {
+     *     key: 'config',
+     *     value: {...}
+     * }, {
+     *     target: [cache.key],
+     *     set: { value: data.value, updatedAt: new Date() }
+     * });
+     * ```
+     */
+    protected _upsert<T extends PgTable>(table: T, data: T['$inferInsert'], options: {
+        target: PgColumn[];
+        set?: Partial<T['$inferInsert']> | Record<string, SQL | any>;
+    }): Promise<T['$inferSelect']>;
+    /**
+     * Update a single record
+     *
+     * @param table - Drizzle table schema
+     * @param where - Object or SQL condition
+     * @param data - Update data
+     * @returns Updated record or null
+     *
+     * @example
+     * ```typescript
+     * const user = await this._updateOne(users,
+     *     { id: 1 },
+     *     { name: 'Updated Name' }
+     * );
+     * ```
+     */
+    protected _updateOne<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined, data: Partial<T['$inferInsert']>): Promise<T['$inferSelect'] | null>;
+    /**
+     * Update multiple records
+     *
+     * @param table - Drizzle table schema
+     * @param where - Object or SQL condition
+     * @param data - Update data
+     * @returns Array of updated records
+     *
+     * @example
+     * ```typescript
+     * const users = await this._updateMany(users,
+     *     { role: 'user' },
+     *     { verified: true }
+     * );
+     * ```
+     */
+    protected _updateMany<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined, data: Partial<T['$inferInsert']>): Promise<T['$inferSelect'][]>;
+    /**
+     * Delete a single record
+     *
+     * @param table - Drizzle table schema
+     * @param where - Object or SQL condition
+     * @returns Deleted record or null
+     *
+     * @example
+     * ```typescript
+     * const user = await this._deleteOne(users, { id: 1 });
+     * ```
+     */
+    protected _deleteOne<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined): Promise<T['$inferSelect'] | null>;
+    /**
+     * Delete multiple records
+     *
+     * @param table - Drizzle table schema
+     * @param where - Object or SQL condition
+     * @returns Array of deleted records
+     *
+     * @example
+     * ```typescript
+     * const users = await this._deleteMany(users, { verified: false });
+     * ```
+     */
+    protected _deleteMany<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined): Promise<T['$inferSelect'][]>;
+    /**
+     * Count records
+     *
+     * @param table - Drizzle table schema
+     * @param where - Optional object or SQL condition
+     * @returns Number of records
+     *
+     * @example
+     * ```typescript
+     * const total = await this._count(users);
+     * const activeUsers = await this._count(users, { active: true });
+     * ```
+     */
+    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 };