@mandujs/core 0.10.0 → 0.12.0

package/src/filling/filling.ts

@@ -1,10 +1,13 @@
 /**
  * Mandu Filling - 만두소 🥟
  * 체이닝 API로 비즈니스 로직 정의
+ *
+ * DNA-002: 의존성 주입 패턴 지원
  */
 
 import { ManduContext, ValidationError } from "./context";
 import { AuthenticationError, AuthorizationError } from "./auth";
+import { type FillingDeps, globalDeps } from "./deps";
 import { ErrorClassifier, formatErrorResponse, ErrorCode } from "../error";
 import { TIMEOUTS } from "../constants";
 import { createContract, type ContractDefinition, type ContractInstance } from "../contract";
@@ -310,9 +313,10 @@ export class ManduFilling<TLoaderData = unknown> {
     request: Request,
     params: Record<string, string> = {},
     routeContext?: { routeId: string; pattern: string },
-    options?: ExecuteOptions
+    options?: ExecuteOptions & { deps?: FillingDeps }
   ): Promise<Response> {
-    const ctx = new ManduContext(request, params);
+    const deps = options?.deps ?? globalDeps.get();
+    const ctx = new ManduContext(request, params, deps);
     const method = request.method.toUpperCase() as HttpMethod;
     const handler = this.config.handlers.get(method);
     if (!handler) {

package/src/filling/index.ts

@@ -1,5 +1,7 @@
 /**
  * Mandu Filling Module - 만두소 🥟
+ *
+ * DNA-002: 의존성 주입 패턴 지원
  */
 
 export { ManduContext, ValidationError, CookieManager } from "./context";
@@ -19,3 +21,19 @@ export {
   createRoleGuard,
 } from "./auth";
 export type { BaseUser, UserWithRole, UserWithRoles } from "./auth";
+
+// DNA-002: Dependency Injection
+export {
+  createDefaultDeps,
+  createMockDeps,
+  mergeDeps,
+  globalDeps,
+} from "./deps";
+export type {
+  FillingDeps,
+  DbDeps,
+  CacheDeps,
+  LoggerDeps,
+  EventBusDeps,
+  InjectDeps,
+} from "./deps";

package/src/index.ts

@@ -5,7 +5,8 @@ export * from "./guard";
 export * from "./report";
 export * from "./filling";
 export * from "./change";
-export * from "./error";
+export * from "./errors";
+export * from "./logging";
 export * from "./slot";
 export * from "./bundler";
 export * from "./contract";

package/src/logging/index.ts

@@ -0,0 +1,22 @@
+/**
+ * DNA-008: Structured Logging System
+ *
+ * 구조화된 로깅 시스템
+ * - Transport 기반 다중 출력
+ * - 동적 전송 추가/제거
+ * - 레벨별 필터링
+ */
+
+export {
+  transportRegistry,
+  attachLogTransport,
+  detachLogTransport,
+  entryToTransportRecord,
+  createConsoleTransport,
+  createBufferTransport,
+  createFilteredTransport,
+  createBatchTransport,
+  type LogTransport,
+  type LogTransportRecord,
+  type TransportRegistration,
+} from "./transports.js";

package/src/logging/transports.ts

@@ -0,0 +1,365 @@
+/**
+ * DNA-008: Structured Logging - Transport System
+ *
+ * 로그 전송 레지스트리
+ * - 다중 전송 지원 (콘솔, 파일, 외부 서비스)
+ * - 동적 전송 추가/제거
+ * - 레벨별 필터링
+ */
+
+import type { LogLevel, LogEntry } from "../runtime/logger.js";
+
+/**
+ * 로그 전송 레코드 (Transport에 전달되는 데이터)
+ */
+export interface LogTransportRecord {
+  /** 타임스탬프 (ISO 문자열) */
+  timestamp: string;
+  /** 로그 레벨 */
+  level: LogLevel;
+  /** 요청 ID */
+  requestId?: string;
+  /** HTTP 메서드 */
+  method?: string;
+  /** 요청 경로 */
+  path?: string;
+  /** HTTP 상태 코드 */
+  status?: number;
+  /** 응답 시간 (ms) */
+  duration?: number;
+  /** 에러 정보 */
+  error?: {
+    message: string;
+    stack?: string;
+    code?: string;
+  };
+  /** 커스텀 메타데이터 */
+  meta?: Record<string, unknown>;
+  /** 느린 요청 여부 */
+  slow?: boolean;
+  /** 원본 LogEntry (필요시 접근) */
+  raw?: LogEntry;
+}
+
+/**
+ * 로그 전송 함수 타입
+ */
+export type LogTransport = (record: LogTransportRecord) => void | Promise<void>;
+
+/**
+ * 전송 등록 정보
+ */
+export interface TransportRegistration {
+  /** 전송 ID */
+  id: string;
+  /** 전송 함수 */
+  transport: LogTransport;
+  /** 최소 로그 레벨 (이 레벨 이상만 전송) */
+  minLevel?: LogLevel;
+  /** 활성화 여부 */
+  enabled: boolean;
+}
+
+/**
+ * 로그 레벨 우선순위
+ */
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+/**
+ * 전역 전송 레지스트리
+ */
+class TransportRegistry {
+  private transports = new Map<string, TransportRegistration>();
+
+  /**
+   * 전송 추가
+   *
+   * @example
+   * ```ts
+   * attachLogTransport("file", async (record) => {
+   *   await appendFile("app.log", JSON.stringify(record) + "\n");
+   * });
+   * ```
+   */
+  attach(
+    id: string,
+    transport: LogTransport,
+    options: { minLevel?: LogLevel; enabled?: boolean } = {}
+  ): void {
+    this.transports.set(id, {
+      id,
+      transport,
+      minLevel: options.minLevel,
+      enabled: options.enabled ?? true,
+    });
+  }
+
+  /**
+   * 전송 제거
+   */
+  detach(id: string): boolean {
+    return this.transports.delete(id);
+  }
+
+  /**
+   * 전송 활성화/비활성화
+   */
+  setEnabled(id: string, enabled: boolean): void {
+    const registration = this.transports.get(id);
+    if (registration) {
+      registration.enabled = enabled;
+    }
+  }
+
+  /**
+   * 모든 전송에 로그 전달
+   */
+  async dispatch(record: LogTransportRecord): Promise<void> {
+    const recordLevel = LEVEL_PRIORITY[record.level];
+
+    const promises: Promise<void>[] = [];
+
+    for (const registration of this.transports.values()) {
+      if (!registration.enabled) continue;
+
+      // 레벨 필터링
+      if (registration.minLevel) {
+        const minLevel = LEVEL_PRIORITY[registration.minLevel];
+        if (recordLevel < minLevel) continue;
+      }
+
+      try {
+        const result = registration.transport(record);
+        if (result instanceof Promise) {
+          promises.push(result.catch((err) => {
+            console.error(`[Log Transport] Error in ${registration.id}:`, err);
+          }));
+        }
+      } catch (err) {
+        console.error(`[Log Transport] Error in ${registration.id}:`, err);
+      }
+    }
+
+    await Promise.all(promises);
+  }
+
+  /**
+   * 동기적으로 모든 전송에 로그 전달 (비동기 전송은 fire-and-forget)
+   */
+  dispatchSync(record: LogTransportRecord): void {
+    const recordLevel = LEVEL_PRIORITY[record.level];
+
+    for (const registration of this.transports.values()) {
+      if (!registration.enabled) continue;
+
+      if (registration.minLevel) {
+        const minLevel = LEVEL_PRIORITY[registration.minLevel];
+        if (recordLevel < minLevel) continue;
+      }
+
+      try {
+        const result = registration.transport(record);
+        if (result instanceof Promise) {
+          // 비동기 결과는 무시 (fire-and-forget)
+          result.catch((err) => {
+            console.error(`[Log Transport] Error in ${registration.id}:`, err);
+          });
+        }
+      } catch (err) {
+        console.error(`[Log Transport] Error in ${registration.id}:`, err);
+      }
+    }
+  }
+
+  /**
+   * 등록된 전송 목록
+   */
+  list(): TransportRegistration[] {
+    return Array.from(this.transports.values());
+  }
+
+  /**
+   * 전송 존재 여부
+   */
+  has(id: string): boolean {
+    return this.transports.has(id);
+  }
+
+  /**
+   * 모든 전송 제거
+   */
+  clear(): void {
+    this.transports.clear();
+  }
+
+  /**
+   * 전송 개수
+   */
+  get size(): number {
+    return this.transports.size;
+  }
+}
+
+/**
+ * 전역 전송 레지스트리 인스턴스
+ */
+export const transportRegistry = new TransportRegistry();
+
+/**
+ * 로그 전송 추가 (편의 함수)
+ *
+ * @example
+ * ```ts
+ * // 파일 전송
+ * attachLogTransport("file", async (record) => {
+ *   await fs.appendFile("app.log", JSON.stringify(record) + "\n");
+ * }, { minLevel: "info" });
+ *
+ * // 외부 서비스 전송
+ * attachLogTransport("datadog", async (record) => {
+ *   await fetch("https://http-intake.logs.datadoghq.com/...", {
+ *     method: "POST",
+ *     body: JSON.stringify(record),
+ *   });
+ * }, { minLevel: "warn" });
+ * ```
+ */
+export function attachLogTransport(
+  id: string,
+  transport: LogTransport,
+  options?: { minLevel?: LogLevel; enabled?: boolean }
+): void {
+  transportRegistry.attach(id, transport, options);
+}
+
+/**
+ * 로그 전송 제거 (편의 함수)
+ */
+export function detachLogTransport(id: string): boolean {
+  return transportRegistry.detach(id);
+}
+
+/**
+ * LogEntry를 LogTransportRecord로 변환
+ */
+export function entryToTransportRecord(entry: LogEntry): LogTransportRecord {
+  return {
+    timestamp: entry.timestamp,
+    level: entry.level,
+    requestId: entry.requestId,
+    method: entry.method,
+    path: entry.path,
+    status: entry.status,
+    duration: entry.duration,
+    error: entry.error ? {
+      message: entry.error.message,
+      stack: entry.error.stack,
+    } : undefined,
+    slow: entry.slow,
+    raw: entry,
+  };
+}
+
+// ============================================
+// Built-in Transports
+// ============================================
+
+/**
+ * 콘솔 전송 (기본)
+ */
+export function createConsoleTransport(options: {
+  format?: "json" | "pretty";
+} = {}): LogTransport {
+  const { format = "pretty" } = options;
+
+  return (record) => {
+    const output = format === "json"
+      ? JSON.stringify(record)
+      : `[${record.timestamp}] ${record.level.toUpperCase()} ${record.method ?? ""} ${record.path ?? ""} ${record.status ?? ""} ${record.duration ? record.duration.toFixed(0) + "ms" : ""}`;
+
+    switch (record.level) {
+      case "error":
+        console.error(output);
+        break;
+      case "warn":
+        console.warn(output);
+        break;
+      default:
+        console.log(output);
+    }
+  };
+}
+
+/**
+ * 메모리 버퍼 전송 (테스트용)
+ */
+export function createBufferTransport(buffer: LogTransportRecord[]): LogTransport {
+  return (record) => {
+    buffer.push(record);
+  };
+}
+
+/**
+ * 필터링 전송 래퍼
+ */
+export function createFilteredTransport(
+  transport: LogTransport,
+  filter: (record: LogTransportRecord) => boolean
+): LogTransport {
+  return (record) => {
+    if (filter(record)) {
+      return transport(record);
+    }
+  };
+}
+
+/**
+ * 배치 전송 (성능 최적화)
+ */
+export function createBatchTransport(
+  flush: (records: LogTransportRecord[]) => void | Promise<void>,
+  options: {
+    maxSize?: number;
+    flushInterval?: number;
+  } = {}
+): { transport: LogTransport; flush: () => Promise<void>; stop: () => void } {
+  const { maxSize = 100, flushInterval = 5000 } = options;
+
+  const buffer: LogTransportRecord[] = [];
+  let timer: ReturnType<typeof setInterval> | null = null;
+
+  const doFlush = async () => {
+    if (buffer.length === 0) return;
+    const records = buffer.splice(0, buffer.length);
+    await flush(records);
+  };
+
+  timer = setInterval(() => {
+    doFlush().catch((err) => {
+      console.error("[Batch Transport] Flush error:", err);
+    });
+  }, flushInterval);
+
+  return {
+    transport: (record) => {
+      buffer.push(record);
+      if (buffer.length >= maxSize) {
+        doFlush().catch((err) => {
+          console.error("[Batch Transport] Flush error:", err);
+        });
+      }
+    },
+    flush: doFlush,
+    stop: () => {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+    },
+  };
+}

package/src/plugins/index.ts

@@ -0,0 +1,38 @@
+/**
+ * DNA-001: Plugin System
+ *
+ * Mandu 플러그인 시스템
+ * - Guard 프리셋 플러그인
+ * - 빌드 플러그인
+ * - 로거 전송 플러그인
+ * - MCP 도구 플러그인
+ * - 미들웨어 플러그인
+ */
+
+export {
+  PluginRegistry,
+  globalPluginRegistry,
+  definePlugin,
+} from "./registry";
+
+export type {
+  Plugin,
+  PluginApi,
+  PluginCategory,
+  PluginMeta,
+  PluginHooks,
+  GuardPresetPlugin,
+  GuardRule,
+  GuardRuleContext,
+  GuardViolation,
+  LayerDefinition,
+  ImportInfo,
+  ExportInfo,
+  BuildPlugin,
+  BuildContext,
+  BuildResult,
+  LoggerTransportPlugin,
+  LogEntry,
+  McpToolPlugin,
+  MiddlewarePlugin,
+} from "./types";