@spfn/core 0.2.0-beta.8 → 0.3.0-beta.1

package/dist/env/loader.d.ts

@@ -1,17 +1,27 @@
 /**
  * Environment Variable Loader
  *
- * Next.js 스타일의 환경변수 파일 로딩
+ * Next.js 스타일의 환경변수 파일 로딩 (환경별 분리 지원)
+ *
+ * 로딩 우선순위 (낮음 -> 높음, 나중 파일이 덮어씀):
+ * 1. .env                   - 기본값 (committed)
+ * 2. .env.{NODE_ENV}        - 환경별 오버라이드 (committed)
+ * 3. .env.local             - 로컬 오버라이드 (gitignored, test에서 스킵)
+ * 4. .env.{NODE_ENV}.local  - 환경별 시크릿 (gitignored)
+ * 5. .env.server            - 서버 전용 (gitignored, Next.js 미로드)
  *
  * @example
  * ```typescript
  * import { loadEnv } from '@spfn/core/env/loader';
  *
- * // SPFN 서버 진입점에서 호출
+ * // 기본 사용 (NODE_ENV 자동 감지)
  * loadEnv();
  *
- * // 이후 스키마 검증
- * const env = createEnvRegistry(envSchema).validate();
+ * // 특정 환경 지정
+ * loadEnv({ nodeEnv: 'production' });
+ *
+ * // 서버 레이어 제외 (Next.js 클라이언트용)
+ * loadEnv({ server: false });
  * ```
  *
  * @module env/loader
@@ -25,6 +35,16 @@ interface LoadEnvOptions {
      * @default process.cwd()
      */
     cwd?: string;
+    /**
+     * NODE_ENV 값 (환경별 .env 파일 결정)
+     * @default process.env.NODE_ENV || 'local'
+     */
+    nodeEnv?: string;
+    /**
+     * 서버 전용 파일 포함 여부 (.env.server)
+     * @default true
+     */
+    server?: boolean;
     /**
      * 디버그 모드 (로드된 파일 로깅)
      * @default false
@@ -52,24 +72,11 @@ interface LoadEnvResult {
 /**
  * 프로젝트 루트의 환경변수 파일들을 규칙에 따라 로드
  *
- * Next.js 스타일의 우선순위를 따름:
- * - .env → .env.local → .env.server → .env.server.local
- * - 나중에 로드된 값이 이전 값을 덮어씀
+ * 모든 파일을 파싱 후 머지한 뒤 process.env에 한번에 적용.
+ * 이미 process.env에 존재하는 키는 덮어쓰지 않음 (플랫폼 주입 보호).
  *
  * @param options - 로드 옵션
  * @returns 로드 결과 (로드된 파일, 키 목록)
- *
- * @example
- * ```typescript
- * // 기본 사용
- * loadEnv();
- *
- * // 커스텀 경로
- * loadEnv({ cwd: '/path/to/project' });
- *
- * // 디버그 모드
- * loadEnv({ debug: true });
- * ```
  */
 declare function loadEnv(options?: LoadEnvOptions): LoadEnvResult;
 /**

package/dist/env/loader.js

@@ -5,58 +5,65 @@ import { logger } from '@spfn/core/logger';
 
 // src/env/loader.ts
 var envLogger = logger.child("@spfn/core:env-loader");
-var ENV_FILES = [
-  ".env",
-  ".env.local",
-  ".env.server",
-  ".env.server.local"
-];
+function getEnvFiles(nodeEnv, server) {
+  const files = [
+    ".env",
+    `.env.${nodeEnv}`
+  ];
+  if (nodeEnv !== "test") {
+    files.push(".env.local");
+  }
+  files.push(`.env.${nodeEnv}.local`);
+  if (server) {
+    files.push(".env.server");
+  }
+  return files;
+}
 function parseEnvFile(filePath) {
   if (!existsSync(filePath)) {
     return null;
   }
-  const content = readFileSync(filePath, "utf-8");
-  return parse(content);
+  return parse(readFileSync(filePath, "utf-8"));
 }
 function loadEnv(options = {}) {
   const {
     cwd = process.cwd(),
+    nodeEnv = process.env.NODE_ENV || "local",
+    server = true,
     debug = false,
     override = false
   } = options;
+  const envFiles = getEnvFiles(nodeEnv, server);
   const loadedFiles = [];
-  const loadedKeys = /* @__PURE__ */ new Set();
-  for (const fileName of ENV_FILES) {
+  const existingKeys = new Set(Object.keys(process.env));
+  const merged = {};
+  for (const fileName of envFiles) {
     const filePath = resolve(cwd, fileName);
     const parsed = parseEnvFile(filePath);
     if (parsed === null) {
       continue;
     }
     loadedFiles.push(fileName);
-    for (const [key, value] of Object.entries(parsed)) {
-      if (!override && process.env[key] !== void 0) {
-        continue;
-      }
-      process.env[key] = value;
-      loadedKeys.add(key);
+    Object.assign(merged, parsed);
+  }
+  const loadedKeys = [];
+  for (const [key, value] of Object.entries(merged)) {
+    if (!override && existingKeys.has(key)) {
+      continue;
     }
+    process.env[key] = value;
+    loadedKeys.push(key);
   }
   if (debug && loadedFiles.length > 0) {
     envLogger.debug(`Loaded env files: ${loadedFiles.join(", ")}`);
-    envLogger.debug(`Loaded ${loadedKeys.size} environment variables`);
+    envLogger.debug(`Loaded ${loadedKeys.length} environment variables`);
   }
-  return {
-    loadedFiles,
-    loadedKeys: Array.from(loadedKeys)
-  };
+  return { loadedFiles, loadedKeys };
 }
 var isEnvLoaded = false;
 function loadEnvOnce(options = {}) {
   if (isEnvLoaded) {
-    return {
-      loadedFiles: [],
-      loadedKeys: []
-    };
+    return { loadedFiles: [], loadedKeys: [] };
   }
   isEnvLoaded = true;
   return loadEnv(options);

package/dist/env/loader.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/env/loader.ts"],"names":[],"mappings":";;;;;;AAwBA,IAAM,SAAA,GAAY,MAAA,CAAO,KAAA,CAAM,uBAAuB,CAAA;AAkCtD,IAAM,SAAA,GAAY;AAAA,EACd,MAAA;AAAA,EACA,YAAA;AAAA,EACA,aAAA;AAAA,EACA;AACJ,CAAA;AAKA,SAAS,aAAa,QAAA,EACtB;AACI,EAAA,IAAI,CAAC,UAAA,CAAW,QAAQ,CAAA,EACxB;AACI,IAAA,OAAO,IAAA;AAAA,EACX;AAEA,EAAA,MAAM,OAAA,GAAU,YAAA,CAAa,QAAA,EAAU,OAAO,CAAA;AAC9C,EAAA,OAAO,MAAM,OAAO,CAAA;AACxB;AAwCO,SAAS,OAAA,CAAQ,OAAA,GAA0B,EAAC,EACnD;AACI,EAAA,MAAM;AAAA,IACF,GAAA,GAAM,QAAQ,GAAA,EAAI;AAAA,IAClB,KAAA,GAAQ,KAAA;AAAA,IACR,QAAA,GAAW;AAAA,GACf,GAAI,OAAA;AAEJ,EAAA,MAAM,cAAwB,EAAC;AAC/B,EAAA,MAAM,UAAA,uBAAiB,GAAA,EAAY;AAEnC,EAAA,KAAA,MAAW,YAAY,SAAA,EACvB;AACI,IAAA,MAAM,QAAA,GAAW,OAAA,CAAQ,GAAA,EAAK,QAAQ,CAAA;AACtC,IAAA,MAAM,MAAA,GAAS,aAAa,QAAQ,CAAA;AAEpC,IAAA,IAAI,WAAW,IAAA,EACf;AACI,MAAA;AAAA,IACJ;AAEA,IAAA,WAAA,CAAY,KAAK,QAAQ,CAAA;AAEzB,IAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,MAAM,CAAA,EAChD;AAEI,MAAA,IAAI,CAAC,QAAA,IAAY,OAAA,CAAQ,GAAA,CAAI,GAAG,MAAM,MAAA,EACtC;AACI,QAAA;AAAA,MACJ;AAEA,MAAA,OAAA,CAAQ,GAAA,CAAI,GAAG,CAAA,GAAI,KAAA;AACnB,MAAA,UAAA,CAAW,IAAI,GAAG,CAAA;AAAA,IACtB;AAAA,EACJ;AAEA,EAAA,IAAI,KAAA,IAAS,WAAA,CAAY,MAAA,GAAS,CAAA,EAClC;AACI,IAAA,SAAA,CAAU,MAAM,CAAA,kBAAA,EAAqB,WAAA,CAAY,IAAA,CAAK,IAAI,CAAC,CAAA,CAAE,CAAA;AAC7D,IAAA,SAAA,CAAU,KAAA,CAAM,CAAA,OAAA,EAAU,UAAA,CAAW,IAAI,CAAA,sBAAA,CAAwB,CAAA;AAAA,EACrE;AAEA,EAAA,OAAO;AAAA,IACH,WAAA;AAAA,IACA,UAAA,EAAY,KAAA,CAAM,IAAA,CAAK,UAAU;AAAA,GACrC;AACJ;AAKA,IAAI,WAAA,GAAc,KAAA;AAQX,SAAS,WAAA,CAAY,OAAA,GAA0B,EAAC,EACvD;AACI,EAAA,IAAI,WAAA,EACJ;AACI,IAAA,OAAO;AAAA,MACH,aAAa,EAAC;AAAA,MACd,YAAY;AAAC,KACjB;AAAA,EACJ;AAEA,EAAA,WAAA,GAAc,IAAA;AACd,EAAA,OAAO,QAAQ,OAAO,CAAA;AAC1B;AAKO,SAAS,iBAAA,GAChB;AACI,EAAA,WAAA,GAAc,KAAA;AAClB","file":"loader.js","sourcesContent":["/**\n * Environment Variable Loader\n *\n * Next.js 스타일의 환경변수 파일 로딩\n *\n * @example\n * ```typescript\n * import { loadEnv } from '@spfn/core/env/loader';\n *\n * // SPFN 서버 진입점에서 호출\n * loadEnv();\n *\n * // 이후 스키마 검증\n * const env = createEnvRegistry(envSchema).validate();\n * ```\n *\n * @module env/loader\n */\n\nimport { existsSync, readFileSync } from 'node:fs';\nimport { resolve } from 'node:path';\nimport { parse } from 'dotenv';\nimport { logger } from '@spfn/core/logger';\n\nconst envLogger = logger.child('@spfn/core:env-loader');\n\n/**\n * loadEnv 옵션\n */\nexport interface LoadEnvOptions\n{\n    /**\n     * 프로젝트 루트 경로\n     * @default process.cwd()\n     */\n    cwd?: string;\n\n    /**\n     * 디버그 모드 (로드된 파일 로깅)\n     * @default false\n     */\n    debug?: boolean;\n\n    /**\n     * 기존 process.env 값 덮어쓰기 허용\n     * @default false\n     */\n    override?: boolean;\n}\n\n/**\n * 환경변수 파일 로딩 순서 (우선순위 낮음 → 높음)\n *\n * 1. .env              - 기본값 (커밋 O)\n * 2. .env.local        - 로컬 오버라이드 (커밋 X)\n * 3. .env.server       - 서버 전용 기본값 (커밋 O)\n * 4. .env.server.local - 서버 전용 민감정보 (커밋 X)\n */\nconst ENV_FILES = [\n    '.env',\n    '.env.local',\n    '.env.server',\n    '.env.server.local',\n] as const;\n\n/**\n * 단일 .env 파일 파싱\n */\nfunction parseEnvFile(filePath: string): Record<string, string> | null\n{\n    if (!existsSync(filePath))\n    {\n        return null;\n    }\n\n    const content = readFileSync(filePath, 'utf-8');\n    return parse(content);\n}\n\n/**\n * 환경변수 로드 결과\n */\nexport interface LoadEnvResult\n{\n    /**\n     * 로드된 파일 목록\n     */\n    loadedFiles: string[];\n\n    /**\n     * 로드된 환경변수 키 목록\n     */\n    loadedKeys: string[];\n}\n\n/**\n * 프로젝트 루트의 환경변수 파일들을 규칙에 따라 로드\n *\n * Next.js 스타일의 우선순위를 따름:\n * - .env → .env.local → .env.server → .env.server.local\n * - 나중에 로드된 값이 이전 값을 덮어씀\n *\n * @param options - 로드 옵션\n * @returns 로드 결과 (로드된 파일, 키 목록)\n *\n * @example\n * ```typescript\n * // 기본 사용\n * loadEnv();\n *\n * // 커스텀 경로\n * loadEnv({ cwd: '/path/to/project' });\n *\n * // 디버그 모드\n * loadEnv({ debug: true });\n * ```\n */\nexport function loadEnv(options: LoadEnvOptions = {}): LoadEnvResult\n{\n    const {\n        cwd = process.cwd(),\n        debug = false,\n        override = false,\n    } = options;\n\n    const loadedFiles: string[] = [];\n    const loadedKeys = new Set<string>();\n\n    for (const fileName of ENV_FILES)\n    {\n        const filePath = resolve(cwd, fileName);\n        const parsed = parseEnvFile(filePath);\n\n        if (parsed === null)\n        {\n            continue;\n        }\n\n        loadedFiles.push(fileName);\n\n        for (const [key, value] of Object.entries(parsed))\n        {\n            // 기존 값이 있고 override가 false면 스킵\n            if (!override && process.env[key] !== undefined)\n            {\n                continue;\n            }\n\n            process.env[key] = value;\n            loadedKeys.add(key);\n        }\n    }\n\n    if (debug && loadedFiles.length > 0)\n    {\n        envLogger.debug(`Loaded env files: ${loadedFiles.join(', ')}`);\n        envLogger.debug(`Loaded ${loadedKeys.size} environment variables`);\n    }\n\n    return {\n        loadedFiles,\n        loadedKeys: Array.from(loadedKeys),\n    };\n}\n\n/**\n * 환경변수가 이미 로드되었는지 확인하는 플래그\n */\nlet isEnvLoaded = false;\n\n/**\n * 환경변수를 한 번만 로드 (중복 호출 방지)\n *\n * @param options - 로드 옵션\n * @returns 로드 결과 (이미 로드된 경우 빈 결과)\n */\nexport function loadEnvOnce(options: LoadEnvOptions = {}): LoadEnvResult\n{\n    if (isEnvLoaded)\n    {\n        return {\n            loadedFiles: [],\n            loadedKeys: [],\n        };\n    }\n\n    isEnvLoaded = true;\n    return loadEnv(options);\n}\n\n/**\n * 환경변수 로드 상태 리셋 (테스트용)\n */\nexport function resetEnvLoadState(): void\n{\n    isEnvLoaded = false;\n}\n"]}
+{"version":3,"sources":["../../src/env/loader.ts"],"names":[],"mappings":"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","file":"loader.js","sourcesContent":["/**\n * Environment Variable Loader\n *\n * Next.js 스타일의 환경변수 파일 로딩 (환경별 분리 지원)\n *\n * 로딩 우선순위 (낮음 -> 높음, 나중 파일이 덮어씀):\n * 1. .env                   - 기본값 (committed)\n * 2. .env.{NODE_ENV}        - 환경별 오버라이드 (committed)\n * 3. .env.local             - 로컬 오버라이드 (gitignored, test에서 스킵)\n * 4. .env.{NODE_ENV}.local  - 환경별 시크릿 (gitignored)\n * 5. .env.server            - 서버 전용 (gitignored, Next.js 미로드)\n *\n * @example\n * ```typescript\n * import { loadEnv } from '@spfn/core/env/loader';\n *\n * // 기본 사용 (NODE_ENV 자동 감지)\n * loadEnv();\n *\n * // 특정 환경 지정\n * loadEnv({ nodeEnv: 'production' });\n *\n * // 서버 레이어 제외 (Next.js 클라이언트용)\n * loadEnv({ server: false });\n * ```\n *\n * @module env/loader\n */\n\nimport { existsSync, readFileSync } from 'node:fs';\nimport { resolve } from 'node:path';\nimport { parse } from 'dotenv';\nimport { logger } from '@spfn/core/logger';\n\nconst envLogger = logger.child('@spfn/core:env-loader');\n\n/**\n * loadEnv 옵션\n */\nexport interface LoadEnvOptions\n{\n    /**\n     * 프로젝트 루트 경로\n     * @default process.cwd()\n     */\n    cwd?: string;\n\n    /**\n     * NODE_ENV 값 (환경별 .env 파일 결정)\n     * @default process.env.NODE_ENV || 'local'\n     */\n    nodeEnv?: string;\n\n    /**\n     * 서버 전용 파일 포함 여부 (.env.server)\n     * @default true\n     */\n    server?: boolean;\n\n    /**\n     * 디버그 모드 (로드된 파일 로깅)\n     * @default false\n     */\n    debug?: boolean;\n\n    /**\n     * 기존 process.env 값 덮어쓰기 허용\n     * @default false\n     */\n    override?: boolean;\n}\n\n/**\n * 환경변수 로드 결과\n */\nexport interface LoadEnvResult\n{\n    /**\n     * 로드된 파일 목록\n     */\n    loadedFiles: string[];\n\n    /**\n     * 로드된 환경변수 키 목록\n     */\n    loadedKeys: string[];\n}\n\n/**\n * NODE_ENV에 따른 .env 파일 목록 생성 (우선순위 낮음 -> 높음)\n *\n * 더 구체적인 파일이 승리:\n * - environment > base\n * - server > shared\n * - local > committed\n */\nfunction getEnvFiles(nodeEnv: string, server: boolean): string[]\n{\n    const files: string[] = [\n        '.env',\n        `.env.${nodeEnv}`,\n    ];\n\n    // test 환경에서는 .env.local 스킵 (테스트 결정론성 보장)\n    if (nodeEnv !== 'test')\n    {\n        files.push('.env.local');\n    }\n\n    files.push(`.env.${nodeEnv}.local`);\n\n    if (server)\n    {\n        files.push('.env.server');\n    }\n\n    return files;\n}\n\n/**\n * 단일 .env 파일 파싱\n */\nfunction parseEnvFile(filePath: string): Record<string, string> | null\n{\n    if (!existsSync(filePath))\n    {\n        return null;\n    }\n\n    return parse(readFileSync(filePath, 'utf-8'));\n}\n\n/**\n * 프로젝트 루트의 환경변수 파일들을 규칙에 따라 로드\n *\n * 모든 파일을 파싱 후 머지한 뒤 process.env에 한번에 적용.\n * 이미 process.env에 존재하는 키는 덮어쓰지 않음 (플랫폼 주입 보호).\n *\n * @param options - 로드 옵션\n * @returns 로드 결과 (로드된 파일, 키 목록)\n */\nexport function loadEnv(options: LoadEnvOptions = {}): LoadEnvResult\n{\n    const {\n        cwd = process.cwd(),\n        nodeEnv = process.env.NODE_ENV || 'local',\n        server = true,\n        debug = false,\n        override = false,\n    } = options;\n\n    const envFiles = getEnvFiles(nodeEnv, server);\n    const loadedFiles: string[] = [];\n\n    // 1) 기존 process.env 키 스냅샷 저장\n    const existingKeys = new Set(Object.keys(process.env));\n\n    // 2) 모든 .env 파일 파싱 후 머지 (나중 파일이 승리)\n    const merged: Record<string, string> = {};\n\n    for (const fileName of envFiles)\n    {\n        const filePath = resolve(cwd, fileName);\n        const parsed = parseEnvFile(filePath);\n\n        if (parsed === null)\n        {\n            continue;\n        }\n\n        loadedFiles.push(fileName);\n        Object.assign(merged, parsed);\n    }\n\n    // 3) 머지된 결과를 process.env에 적용\n    const loadedKeys: string[] = [];\n\n    for (const [key, value] of Object.entries(merged))\n    {\n        // 기존 process.env에 이미 있는 키는 스킵 (override가 false일 때)\n        if (!override && existingKeys.has(key))\n        {\n            continue;\n        }\n\n        process.env[key] = value;\n        loadedKeys.push(key);\n    }\n\n    if (debug && loadedFiles.length > 0)\n    {\n        envLogger.debug(`Loaded env files: ${loadedFiles.join(', ')}`);\n        envLogger.debug(`Loaded ${loadedKeys.length} environment variables`);\n    }\n\n    return { loadedFiles, loadedKeys };\n}\n\n/**\n * 환경변수가 이미 로드되었는지 확인하는 플래그\n */\nlet isEnvLoaded = false;\n\n/**\n * 환경변수를 한 번만 로드 (중복 호출 방지)\n *\n * @param options - 로드 옵션\n * @returns 로드 결과 (이미 로드된 경우 빈 결과)\n */\nexport function loadEnvOnce(options: LoadEnvOptions = {}): LoadEnvResult\n{\n    if (isEnvLoaded)\n    {\n        return { loadedFiles: [], loadedKeys: [] };\n    }\n\n    isEnvLoaded = true;\n\n    return loadEnv(options);\n}\n\n/**\n * 환경변수 로드 상태 리셋 (테스트용)\n */\nexport function resetEnvLoadState(): void\n{\n    isEnvLoaded = false;\n}\n"]}

package/dist/errors/index.d.ts

@@ -179,6 +179,14 @@ declare class DatabaseError<TDetails extends Record<string, unknown> = Record<st
         statusCode?: number;
         details?: TDetails;
     });
+    /**
+     * Whether this error's message/details are derived from the raw database
+     * driver (SQL text, table/column/constraint names, parameter values) and
+     * therefore must NOT be exposed to clients in production. Defined as a
+     * prototype getter so it is never serialized into the response by toJSON().
+     * Subclasses with a safe, constructed message override this to `false`.
+     */
+    get internal(): boolean;
 }
 /**
  * Connection Error (503 Service Unavailable)
@@ -215,6 +223,7 @@ declare class EntityNotFoundError extends QueryError {
         resource: string;
         id: string | number;
     });
+    get internal(): boolean;
 }
 /**
  * Constraint Violation Error (400 Bad Request)
@@ -263,6 +272,7 @@ declare class DuplicateEntryError extends QueryError {
         field: string;
         value: string | number;
     });
+    get internal(): boolean;
 }
 
 type databaseErrors_ConnectionError = ConnectionError;