mega-framework 0.1.5 → 0.1.7

package/types/core/i18n.d.ts

@@ -0,0 +1,178 @@
+/**
+ * i18n 등록 결과 요약(디버그·테스트용).
+ * @typedef {Object} I18nSummary
+ * @property {boolean} enabled - 등록 여부.
+ * @property {string} default - 기본 언어.
+ * @property {string} fallback - fallback 언어.
+ * @property {string[]} available - 지원 언어 목록.
+ * @property {string} cookieName - locale 쿠키 이름.
+ * @property {boolean} autoComplete - saveMissing(dev 자동 키 생성) 활성 여부.
+ * @property {import('i18next').i18n | null} instance - 생성된 i18next 인스턴스(미등록 시 null).
+ */
+/**
+ * 정규화된 i18n 설정.
+ * @typedef {Object} NormalizedI18n
+ * @property {string} default
+ * @property {string} fallback
+ * @property {string[]} available
+ * @property {string} cookieName
+ * @property {{ enabled: boolean, dir: string|null, debounceMs: number }} autoComplete
+ * @property {string|null} localesDir
+ * @property {Record<string, any>} resources
+ * @property {boolean} exposeTranslations
+ * @property {string} translationsPath
+ */
+/**
+ * 앱 `i18n` config 를 정규화한다. falsy 면 미옵트인(`null`).
+ *
+ * 잘못된 형태는 **fail-fast** 로 throw 한다(silent 보정 X). `available` 이 배열이 아니거나 비었으면
+ * 부팅 에러로 드러내, locale 미설정이 런타임에 조용히 fallback 으로 뭉개지지 않게 한다.
+ *
+ * @param {unknown} i18n - `MegaI18nAppConfig`(default/available/fallback/cookieName/autoComplete/...).
+ * @returns {NormalizedI18n | null}
+ * @throws {Error} `available` 가 비-배열/빈 배열 등 명백한 오설정.
+ */
+export function normalizeI18n(i18n: unknown): NormalizedI18n | null;
+/**
+ * `<dir>/<scope>/<lng>.json` 디렉터리 구조에서 locale 리소스를 로드한다(ADR-039 scope 분리 레이아웃,
+ * 04-data-models §768). 파일이 없으면 건너뛴다(빈 namespace). 부팅 시 1회 동기 읽기.
+ *
+ * @param {string|null} dir - locale 루트 디렉터리. null 이면 빈 리소스.
+ * @param {object} opts
+ * @param {string[]} opts.available - 로드할 언어 목록.
+ * @param {{ warn?: Function }} [opts.logger]
+ * @returns {Record<string, Record<string, object>>} `{ <lng>: { <scope>: {...} } }` i18next resources 형태.
+ */
+export function loadLocaleResources(dir: string | null, { available, logger }?: {
+    available: string[];
+    logger?: {
+        warn?: Function;
+    };
+}): Record<string, Record<string, object>>;
+/**
+ * saveMissing 디바운스 writer 를 만든다 — axion 패턴(ADR-037).
+ *
+ * `(lng, scope, key, value)` 누락 키를 모아 `<dir>/<scope>/<lng>.json` 파일에 **기존 키 보존**하며
+ * 병합 저장한다. 같은 파일의 연속 호출은 `debounceMs` 동안 흡수(타이머 1개)하고, flush 시:
+ *   1. 기존 파일 읽어 base 로(없으면 {}),
+ *   2. 모아둔 누락 키를 dot-notation 으로 set(기존 키 안 건드림),
+ *   3. tmp 파일 작성 → `rename`(원자적 쓰기 — 부분 파일 노출 방지),
+ *   4. `timer.unref()` 라 보류 중 타이머가 프로세스 종료를 막지 않음.
+ *
+ * 쓰기 실패는 비치명적(dev 편의 기능) — warn 후 다음 호출에 재시도.
+ *
+ * @param {object} opts
+ * @param {string} opts.dir - locale 루트 디렉터리.
+ * @param {number} opts.debounceMs
+ * @param {{ debug?: Function, warn?: Function }} [opts.logger]
+ * @returns {{ enqueue: (lng: string, scope: string, key: string, value: string) => void, flushAll: () => Promise<void>, _pendingCount: () => number }}
+ */
+export function createMissingKeyWriter({ dir, debounceMs, logger }: {
+    dir: string;
+    debounceMs: number;
+    logger?: {
+        debug?: Function;
+        warn?: Function;
+    };
+}): {
+    enqueue: (lng: string, scope: string, key: string, value: string) => void;
+    flushAll: () => Promise<void>;
+    _pendingCount: () => number;
+};
+/**
+ * 요청 Cookie 헤더에서 locale 쿠키를 읽어 유효 언어로 결정한다(ADR-038 — 쿠키만).
+ *
+ * 쿠키가 없거나 `available` 에 없는 값이면 `default` 로 폴백한다(조용한 클램프 — 변조·구식 쿠키 방어).
+ *
+ * @param {string|undefined} cookieHeader - `req.headers.cookie`.
+ * @param {object} opts
+ * @param {string} opts.cookieName
+ * @param {string[]} opts.available
+ * @param {string} opts.default
+ * @returns {string} 결정된 언어.
+ */
+export function detectLocale(cookieHeader: string | undefined, { cookieName, available, default: def }: {
+    cookieName: string;
+    available: string[];
+    default: string;
+}): string;
+/**
+ * Fastify 인스턴스에 i18n(`i18next`) 을 자동 등록한다 — 요청별 언어 결정·`req.t`·scope 번들·관측성.
+ *
+ * `i18n` 이 falsy 면 **미등록**(옵트인). session.js / multipart.js 형제 패턴. 호출 순서는 라우트 등록
+ * 이전 어디든 무방하다(onRequest hook + request 부착이라 라우트 순서와 무관).
+ *
+ * @param {import('fastify').FastifyInstance} fastify - 대상 앱 Fastify 인스턴스.
+ * @param {Object} opts
+ * @param {unknown} opts.i18n - `MegaI18nAppConfig`. falsy 면 미등록.
+ * @param {string} [opts.appName] - 앱 이름(메트릭 라벨·로그용).
+ * @param {{ debug?: Function, warn?: Function }} [opts.logger] - 흐름 길목 debug 로그(선택).
+ * @returns {I18nSummary}
+ */
+export function registerI18n(fastify: import("fastify").FastifyInstance, { i18n, appName, logger }?: {
+    i18n: unknown;
+    appName?: string;
+    logger?: {
+        debug?: Function;
+        warn?: Function;
+    };
+}): I18nSummary;
+/** locale 쿠키 기본 이름 (04-data-models §394 `cookieName: 'mega.lang'`). */
+export const DEFAULT_I18N_COOKIE: "mega.lang";
+/** scope 분리 고정 namespace 2종 (ADR-039). server=에러·검증, client=SPA UI. */
+export const I18N_SCOPES: readonly string[];
+/** server scope = 기본 namespace — `ctx.t()` 가 자동 선택(ADR-039). */
+export const DEFAULT_SCOPE: "server";
+/** saveMissing 디바운스 기본값 (ms, ADR-037 axion 패턴). */
+export const DEFAULT_DEBOUNCE_MS: 500;
+/**
+ * i18n 등록 결과 요약(디버그·테스트용).
+ */
+export type I18nSummary = {
+    /**
+     * - 등록 여부.
+     */
+    enabled: boolean;
+    /**
+     * - 기본 언어.
+     */
+    default: string;
+    /**
+     * - fallback 언어.
+     */
+    fallback: string;
+    /**
+     * - 지원 언어 목록.
+     */
+    available: string[];
+    /**
+     * - locale 쿠키 이름.
+     */
+    cookieName: string;
+    /**
+     * - saveMissing(dev 자동 키 생성) 활성 여부.
+     */
+    autoComplete: boolean;
+    /**
+     * - 생성된 i18next 인스턴스(미등록 시 null).
+     */
+    instance: import("i18next").i18n | null;
+};
+/**
+ * 정규화된 i18n 설정.
+ */
+export type NormalizedI18n = {
+    default: string;
+    fallback: string;
+    available: string[];
+    cookieName: string;
+    autoComplete: {
+        enabled: boolean;
+        dir: string | null;
+        debounceMs: number;
+    };
+    localesDir: string | null;
+    resources: Record<string, any>;
+    exposeTranslations: boolean;
+    translationsPath: string;
+};

package/types/core/index.d.ts

@@ -0,0 +1,28 @@
+export { MegaApp } from "./mega-app.js";
+export { MegaWsPresence } from "./ws-presence.js";
+export { MegaServer } from "./mega-server.js";
+export { MegaService } from "./mega-service.js";
+export { MegaCluster } from "./mega-cluster.js";
+export { loadRoutes } from "./routes-loader.js";
+export { buildErrorHandler } from "./error-mapper.js";
+export { loadAndValidateConfig } from "./config-loader.js";
+export { MegaWebSocketController } from "./ws-controller.js";
+export { MegaHubLink } from "./hub-link.js";
+export { createSessionCleanupSchedule } from "./session-cleanup-schedule.js";
+export { Router, MegaRouteError } from "./router.js";
+export { bootApp, buildBootContext } from "./boot.js";
+export { wrapEnvelope, errorEnvelope, synthesizeEnvelopeResponseSchema, ENVELOPE_MARK } from "./envelope.js";
+export { buildHttpPipeline, wrapPreHandler, composeTransform, composeAfter } from "./pipeline.js";
+export { ajvErrorToValidationError, MAX_VALIDATION_DETAILS } from "./ajv-mapper.js";
+export { buildHttpCtx, getHttpCtx, buildAdapterAccessors } from "./ctx-builder.js";
+export { createWsMessage, validateWsMessage, parseWsMessage, generateMessageId, WS_MESSAGE_SCHEMA, WS_PROTOCOL_VERSION, WS_TYPE_PATTERN } from "./ws-message.js";
+export { MegaWsConnection, driveWsConnection, createPlainCodec, createAspCodec, rejectUpgrade, CLOSE_CODE_DECRYPT_FAILED, CLOSE_CODE_INTERNAL_ERROR } from "./ws-upgrade.js";
+export { buildPerMessageDeflate, checkCompressionConfig, COMPRESSION_DEFAULTS } from "./ws-compression.js";
+export { validateGlobalConfig, validateAppConfig, validateHostCollisions } from "./config-validator.js";
+export { registerSecurityPlugins, DEFAULT_RATE_LIMIT } from "./security.js";
+export { registerSession, generateSid, readSession } from "./session.js";
+export { createSessionStore, SESSION_STORE_DRIVERS } from "./session-store.js";
+export { registerI18n, normalizeI18n, detectLocale, loadLocaleResources, createMissingKeyWriter, DEFAULT_I18N_COOKIE, I18N_SCOPES } from "./i18n.js";
+export { registerTemplate, MegaTemplate, normalizeViews, resolveViewPath, renderView, VIEW_ENGINE } from "./template.js";
+export { registerStaticAssets, normalizeStaticAssets, DEFAULT_STATIC_PREFIX } from "./static-assets.js";
+export { registerOpenapi, normalizeOpenapi, DEFAULT_OPENAPI_PATH } from "./openapi.js";