@spfn/core 0.1.0-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,379 @@
+export { AppFactory, ServerConfig, createServer, startServer } from './server/index.js';
+export { A as AutoRouteLoader, R as RouteInfo, a as RouteStats, l as loadRoutes } from './auto-loader-C44TcLmM.js';
+export { b as bind } from './bind-pssq1NRT.js';
+export { d as HttpMethod, I as InferContract, c as RouteContext, R as RouteContract, a as RouteHandler, i as isHttpMethod } from './types-SlzTr8ZO.js';
+import { K as DatabaseError } from './postgres-errors-CY_Es8EJ.js';
+export { a5 as ConnectionError, D as DbConnectionType, aa as DeadlockError, m as DrizzleConfigOptions, a4 as DrizzleTable, ab as DuplicateEntryError, Y as FilterCondition, V as FilterOperator, _ as FilterResult, X as FilterValue, Z as Filters, a7 as NotFoundError, y as Page, x as Pageable, a3 as PaginationMeta, a2 as PaginationParams, a6 as QueryError, n as Repository, t as RepositoryScope, a0 as SortCondition, $ as SortDirection, a1 as SortResult, G as TransactionContext, a9 as TransactionError, T as Transactional, I as TransactionalOptions, a8 as ValidationError, W as WrappedDb, O as applyPagination, L as buildFilters, M as buildSort, p as clearRepositoryCache, U as countTotal, S as createPaginationMeta, d as db, k as detectDialect, B as foreignKey, J as fromPostgresError, l as generateDrizzleConfigFile, a as getDb, j as getDrizzleConfig, g as getRawDb, o as getRepository, q as getRepositoryCacheSize, u as getScopedCacheSize, r as getScopedRepository, E as getTransaction, z as id, v as isInRepositoryScope, C as optionalForeignKey, N as orFilters, F as runWithTransaction, A as timestamps, w as withRepositoryScope } from './postgres-errors-CY_Es8EJ.js';
+import { Redis, Cluster } from 'ioredis';
+import { Context, Next } from 'hono';
+import 'hono/cors';
+import '@hono/node-server';
+import 'hono/utils/http-status';
+import '@sinclair/typebox';
+import 'drizzle-orm/postgres-js';
+import 'drizzle-orm/pg-core';
+import 'postgres';
+import 'drizzle-orm/pg-core/query-builders/raw';
+import 'drizzle-orm';
+
+/**
+ * Redis factory with automatic environment variable detection
+ * Supports: Single, Master-Replica, Sentinel, Cluster
+ */
+
+interface RedisClients {
+    /** Primary Redis for writes (or both read/write if no replica) */
+    write?: Redis | Cluster;
+    /** Replica Redis for reads (optional, falls back to write) */
+    read?: Redis | Cluster;
+}
+/**
+ * Create Redis client(s) from environment variables
+ *
+ * Supported patterns (priority order):
+ * 1. Single instance: REDIS_URL
+ * 2. Master-Replica: REDIS_WRITE_URL + REDIS_READ_URL
+ * 3. Sentinel: REDIS_SENTINEL_HOSTS + REDIS_MASTER_NAME
+ * 4. Cluster: REDIS_CLUSTER_NODES
+ *
+ * @returns Redis client(s) or undefined if no configuration found
+ *
+ * @example
+ * ```bash
+ * # Single (most common)
+ * REDIS_URL=redis://localhost:6379
+ * REDIS_URL=rediss://secure.redis.com:6380  # TLS
+ *
+ * # Master-Replica
+ * REDIS_WRITE_URL=redis://master:6379
+ * REDIS_READ_URL=redis://replica:6379
+ *
+ * # Sentinel
+ * REDIS_SENTINEL_HOSTS=sentinel1:26379,sentinel2:26379
+ * REDIS_MASTER_NAME=mymaster
+ * REDIS_PASSWORD=secret
+ *
+ * # Cluster
+ * REDIS_CLUSTER_NODES=node1:6379,node2:6379,node3:6379
+ * REDIS_PASSWORD=secret
+ * ```
+ */
+declare function createRedisFromEnv(): Promise<RedisClients>;
+/**
+ * Create single Redis client (backward compatibility)
+ * Only returns write instance
+ */
+declare function createSingleRedisFromEnv(): Promise<Redis | Cluster | undefined>;
+
+/**
+ * Global Redis instance manager
+ * Provides singleton access to Redis across all modules
+ * Supports Master-Replica pattern with separate read/write instances
+ */
+
+/**
+ * Get global Redis write instance
+ *
+ * @returns Redis write instance or undefined if not initialized
+ *
+ * @example
+ * ```typescript
+ * import { getRedis } from '@spfn/core/cache';
+ *
+ * const redis = getRedis();
+ * if (redis) {
+ *   await redis.set('key', 'value');
+ * }
+ * ```
+ */
+declare function getRedis(): Redis | Cluster | undefined;
+/**
+ * Get global Redis read instance (falls back to write if no replica)
+ *
+ * @returns Redis read instance or write instance as fallback
+ *
+ * @example
+ * ```typescript
+ * import { getRedisRead } from '@spfn/core/cache';
+ *
+ * const redis = getRedisRead();
+ * if (redis) {
+ *   const value = await redis.get('key');
+ * }
+ * ```
+ */
+declare function getRedisRead(): Redis | Cluster | undefined;
+/**
+ * Set global Redis instances (for testing or manual configuration)
+ *
+ * @param write - Redis write instance
+ * @param read - Redis read instance (optional, defaults to write)
+ *
+ * @example
+ * ```typescript
+ * import { setRedis } from '@spfn/core/cache';
+ * import Redis from 'ioredis';
+ *
+ * const write = new Redis('redis://master:6379');
+ * const read = new Redis('redis://replica:6379');
+ * setRedis(write, read);
+ * ```
+ */
+declare function setRedis(write: Redis | Cluster | undefined, read?: Redis | Cluster | undefined): void;
+/**
+ * Initialize Redis from environment variables
+ * Automatically called by startServer()
+ *
+ * Supported environment variables:
+ * - REDIS_URL (single instance)
+ * - REDIS_WRITE_URL + REDIS_READ_URL (master-replica)
+ * - REDIS_SENTINEL_HOSTS + REDIS_MASTER_NAME (sentinel)
+ * - REDIS_CLUSTER_NODES (cluster)
+ * - REDIS_TLS_REJECT_UNAUTHORIZED (TLS config)
+ *
+ * @returns Object with write and read instances
+ *
+ * @example
+ * ```typescript
+ * import { initRedis } from '@spfn/core/cache';
+ *
+ * // Manual initialization (not needed if using startServer)
+ * const { write, read } = await initRedis();
+ * ```
+ */
+declare function initRedis(): Promise<{
+    write?: Redis | Cluster;
+    read?: Redis | Cluster;
+}>;
+/**
+ * Close all Redis connections and cleanup
+ *
+ * @example
+ * ```typescript
+ * import { closeRedis } from '@spfn/core/cache';
+ *
+ * // During graceful shutdown
+ * await closeRedis();
+ * ```
+ */
+declare function closeRedis(): Promise<void>;
+/**
+ * Get Redis connection info (for debugging)
+ */
+declare function getRedisInfo(): {
+    hasWrite: boolean;
+    hasRead: boolean;
+    isReplica: boolean;
+};
+
+/**
+ * Logger Type Definitions
+ *
+ * 로깅 시스템 타입 정의
+ *
+ * ✅ 구현 완료:
+ * - LogLevel 타입 정의
+ * - LogMetadata 인터페이스
+ * - Transport 인터페이스
+ * - 환경별 설정 타입
+ *
+ * 🔗 관련 파일:
+ * - src/logger/logger.ts (Logger 클래스)
+ * - src/logger/transports/ (Transport 구현체)
+ * - src/logger/config.ts (설정)
+ */
+/**
+ * 로그 레벨
+ * debug < info < warn < error < fatal
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+
+/**
+ * Logger Adapter Interface
+ *
+ * Logger 구현을 추상화하는 Adapter 인터페이스
+ * Pino, Winston, Custom 등 다양한 구현체로 교체 가능
+ *
+ * ✅ 구현 완료:
+ * - LoggerAdapter 인터페이스 정의
+ * - Child logger 지원
+ * - Error + Context 지원
+ *
+ * 💡 향후 고려사항:
+ * - Winston Adapter
+ * - Bunyan Adapter
+ *
+ * 🔗 관련 파일:
+ * - src/logger/adapters/pino.ts (Pino 구현)
+ * - src/logger/adapters/custom.ts (Custom 구현)
+ * - src/logger/index.ts (Adapter 선택)
+ */
+
+/**
+ * Logger Adapter 인터페이스
+ *
+ * 모든 Logger 구현체는 이 인터페이스를 구현해야 함
+ */
+interface LoggerAdapter {
+    /**
+     * Child logger 생성
+     */
+    child(module: string): LoggerAdapter;
+    /**
+     * Debug 로그
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Info 로그
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Warn 로그
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, error: Error, context?: Record<string, unknown>): void;
+    /**
+     * Error 로그
+     */
+    error(message: string, context?: Record<string, unknown>): void;
+    error(message: string, error: Error, context?: Record<string, unknown>): void;
+    /**
+     * Fatal 로그
+     */
+    fatal(message: string, context?: Record<string, unknown>): void;
+    fatal(message: string, error: Error, context?: Record<string, unknown>): void;
+    /**
+     * 리소스 정리
+     */
+    close?(): Promise<void>;
+}
+
+/**
+ * Logger Adapter Factory
+ *
+ * Adapter creation and initialization logic
+ */
+
+/**
+ * Singleton Logger instance
+ */
+declare const logger: LoggerAdapter;
+
+/**
+ * Request Logger Middleware
+ *
+ * Automatic API request/response logging middleware
+ *
+ * ✅ Features:
+ * - Automatic request start/completion logging
+ * - Response time measurement
+ * - Automatic error logging
+ * - Request ID generation (distributed tracing)
+ * - Sensitive data masking
+ * - Exclude path configuration (health checks, etc.)
+ *
+ * 💡 Benefits:
+ * - Automatic monitoring of all API requests
+ * - Identify performance bottlenecks
+ * - Easy error tracking
+ *
+ * 💡 Usage:
+ * ```typescript
+ * import { RequestLogger } from '@spfn/core';
+ *
+ * app.use(RequestLogger());
+ * ```
+ *
+ * 🔗 Related files:
+ * - src/logger/ (Logger)
+ * - src/index.ts (Export)
+ */
+
+/**
+ * Request Logger configuration
+ */
+interface RequestLoggerConfig {
+    /**
+     * Paths to exclude from logging (health checks, etc.)
+     */
+    excludePaths?: string[];
+    /**
+     * Field names to mask for sensitive data
+     */
+    sensitiveFields?: string[];
+    /**
+     * Slow request threshold (ms)
+     */
+    slowRequestThreshold?: number;
+}
+/**
+ * Mask sensitive data with circular reference handling
+ *
+ * Optimizations:
+ * - Pre-computes lowercase fields to avoid repeated toLowerCase() calls
+ * - Handles circular references with WeakSet
+ */
+declare function maskSensitiveData(obj: any, sensitiveFields: string[], seen?: WeakSet<object>): any;
+/**
+ * Request Logger middleware
+ */
+declare function RequestLogger(config?: RequestLoggerConfig): (c: Context, next: Next) => Promise<void>;
+
+/**
+ * Error Handler Middleware
+ *
+ * Generic middleware that converts errors with statusCode to HTTP responses
+ *
+ * ✅ Features:
+ * - Convert any error with statusCode property to appropriate HTTP status codes
+ * - Error logging (log level by status code)
+ * - Environment-specific error response format (Production/Development)
+ * - Stack trace inclusion (development only)
+ * - Support for additional error details
+ *
+ * 💡 Design:
+ * - Domain-independent (doesn't depend on specific error types)
+ * - Works with any error that has a statusCode property
+ * - Follows dependency inversion principle
+ */
+
+/**
+ * Error handler options
+ */
+interface ErrorHandlerOptions {
+    /**
+     * Include stack trace in response
+     * @default process.env.NODE_ENV !== 'production'
+     */
+    includeStack?: boolean;
+    /**
+     * Enable error logging
+     * @default true
+     */
+    enableLogging?: boolean;
+}
+/**
+ * Error handler middleware
+ *
+ * Used in Hono's onError hook
+ *
+ * @example
+ * ```typescript
+ * const app = new Hono();
+ * app.onError(ErrorHandler());
+ * ```
+ */
+declare function ErrorHandler(options?: ErrorHandlerOptions): (err: Error, c: Context) => Response | Promise<Response>;
+
+/**
+ * Error Utility Functions
+ *
+ * Generic error type checking utilities
+ */
+
+/**
+ * Check if error is a DatabaseError
+ */
+declare function isDatabaseError(error: unknown): error is DatabaseError;
+
+export { DatabaseError, ErrorHandler, type ErrorHandlerOptions, type LogLevel, type LoggerAdapter, type RedisClients, RequestLogger, type RequestLoggerConfig, closeRedis, createRedisFromEnv, createSingleRedisFromEnv, getRedis, getRedisInfo, getRedisRead, initRedis, isDatabaseError, logger, maskSensitiveData, setRedis };