@mandujs/core 0.13.0 → 0.13.2

package/src/filling/context.ts

@@ -9,7 +9,8 @@ import type { ZodSchema } from "zod";
 import type { ContractSchema, ContractMethod } from "../contract/schema";
 import type { InferBody, InferHeaders, InferParams, InferQuery, InferResponse } from "../contract/types";
 import { ContractValidator, type ContractValidatorOptions } from "../contract/validator";
-import { type FillingDeps, createDefaultDeps, globalDeps } from "./deps";
+import { type FillingDeps, globalDeps } from "./deps";
+import { createSSEConnection, type SSEOptions, type SSEConnection } from "./sse";
 
 type ContractInput<
   TContract extends ContractSchema,
@@ -531,6 +532,28 @@ export class ManduContext {
     return this.withCookies(response);
   }
 
+  /**
+   * Create a Server-Sent Events (SSE) response.
+   *
+   * @example
+   * return ctx.sse((sse) => {
+   *   sse.event("ready", { ok: true });
+   *   const stop = sse.heartbeat(15000);
+   *   sse.onClose(() => stop());
+   * });
+   */
+  sse(setup?: (connection: SSEConnection) => void | Promise<void>, options: SSEOptions = {}): Response {
+    const connection = createSSEConnection(this.request.signal, options);
+
+    if (setup) {
+      Promise.resolve(setup(connection)).catch(() => {
+        void connection.close();
+      });
+    }
+
+    return this.withCookies(connection.response);
+  }
+
   // ============================================
   // 🥟 상태 저장 (Lifecycle → Handler 전달)
   // ============================================

package/src/filling/deps.ts

@@ -1,238 +1,238 @@
-/**
- * DNA-002: Dependency Injection Pattern
- *
- * Filling 핸들러의 의존성을 명시적으로 주입
- * - 테스트 시 목킹 용이
- * - 의존성 역전 원칙 (DIP) 준수
- * - 외부 서비스와의 결합도 감소
- */
-
-/**
- * 데이터베이스 의존성 인터페이스
- */
-export interface DbDeps {
-  /**
-   * SQL 쿼리 실행
-   */
-  query: <T>(sql: string, params?: unknown[]) => Promise<T>;
-
-  /**
-   * 트랜잭션 실행
-   */
-  transaction: <T>(fn: () => Promise<T>) => Promise<T>;
-}
-
-/**
- * 캐시 의존성 인터페이스
- */
-export interface CacheDeps {
-  /**
-   * 캐시에서 값 조회
-   */
-  get: <T>(key: string) => Promise<T | null>;
-
-  /**
-   * 캐시에 값 저장
-   * @param ttl - Time to live (초 단위)
-   */
-  set: <T>(key: string, value: T, ttl?: number) => Promise<void>;
-
-  /**
-   * 캐시에서 값 삭제
-   */
-  delete: (key: string) => Promise<void>;
-
-  /**
-   * 패턴에 맞는 키 삭제
-   */
-  deletePattern?: (pattern: string) => Promise<void>;
-}
-
-/**
- * 로거 의존성 인터페이스
- */
-export interface LoggerDeps {
-  debug: (msg: string, data?: unknown) => void;
-  info: (msg: string, data?: unknown) => void;
-  warn: (msg: string, data?: unknown) => void;
-  error: (msg: string, data?: unknown) => void;
-}
-
-/**
- * 이벤트 버스 의존성 인터페이스
- */
-export interface EventBusDeps {
-  /**
-   * 이벤트 발행
-   */
-  emit: (event: string, payload: unknown) => void;
-
-  /**
-   * 이벤트 구독
-   */
-  on: (event: string, handler: (payload: unknown) => void) => () => void;
-}
-
-/**
- * Filling 핸들러 의존성 타입
- *
- * 모든 필드는 선택적 → 필요한 것만 주입
- */
-export interface FillingDeps {
-  /**
-   * 데이터베이스 접근
-   */
-  db?: DbDeps;
-
-  /**
-   * 캐시 접근
-   */
-  cache?: CacheDeps;
-
-  /**
-   * HTTP 클라이언트
-   */
-  fetch?: typeof fetch;
-
-  /**
-   * 로거
-   */
-  logger?: LoggerDeps;
-
-  /**
-   * 이벤트 버스
-   */
-  events?: EventBusDeps;
-
-  /**
-   * 현재 시간 (테스트용)
-   */
-  now?: () => Date;
-
-  /**
-   * UUID 생성 (테스트용)
-   */
-  uuid?: () => string;
-
-  /**
-   * 커스텀 의존성
-   */
-  [key: string]: unknown;
-}
-
-/**
- * 기본 의존성 생성
- *
- * @example
- * ```ts
- * const deps = createDefaultDeps();
- * console.log(deps.now()); // 현재 시간
- * ```
- */
-export function createDefaultDeps(): FillingDeps {
-  return {
-    fetch: globalThis.fetch,
-    logger: {
-      debug: (msg, data) => console.debug(`[DEBUG] ${msg}`, data ?? ""),
-      info: (msg, data) => console.info(`[INFO] ${msg}`, data ?? ""),
-      warn: (msg, data) => console.warn(`[WARN] ${msg}`, data ?? ""),
-      error: (msg, data) => console.error(`[ERROR] ${msg}`, data ?? ""),
-    },
-    now: () => new Date(),
-    uuid: () => crypto.randomUUID(),
-  };
-}
-
-/**
- * 테스트용 목 의존성 생성 헬퍼
- *
- * @example
- * ```ts
- * const mockDeps = createMockDeps({
- *   db: {
- *     query: vi.fn().mockResolvedValue([{ id: 1, name: "Test" }]),
- *     transaction: vi.fn(fn => fn()),
- *   },
- *   now: () => new Date("2025-01-01"),
- * });
- * ```
- */
-export function createMockDeps(overrides: Partial<FillingDeps> = {}): FillingDeps {
-  const noop = () => {};
-  const asyncNoop = async () => {};
-
-  return {
-    db: {
-      query: async () => [] as any,
-      transaction: async (fn) => fn(),
-    },
-    cache: {
-      get: async () => null,
-      set: asyncNoop,
-      delete: asyncNoop,
-    },
-    fetch: async () => new Response(),
-    logger: {
-      debug: noop,
-      info: noop,
-      warn: noop,
-      error: noop,
-    },
-    events: {
-      emit: noop,
-      on: () => noop,
-    },
-    now: () => new Date("2025-01-01T00:00:00Z"),
-    uuid: () => "00000000-0000-0000-0000-000000000000",
-    ...overrides,
-  };
-}
-
-/**
- * 의존성 병합 (기본값 + 커스텀)
- */
-export function mergeDeps(
-  base: FillingDeps,
-  overrides: Partial<FillingDeps>
-): FillingDeps {
-  return { ...base, ...overrides };
-}
-
-/**
- * 의존성 컨테이너 (싱글톤 관리)
- */
-class DepsContainer {
-  private deps: FillingDeps = createDefaultDeps();
-
-  /**
-   * 전역 의존성 설정
-   */
-  set(deps: Partial<FillingDeps>): void {
-    this.deps = mergeDeps(this.deps, deps);
-  }
-
-  /**
-   * 전역 의존성 가져오기
-   */
-  get(): FillingDeps {
-    return this.deps;
-  }
-
-  /**
-   * 기본값으로 리셋
-   */
-  reset(): void {
-    this.deps = createDefaultDeps();
-  }
-}
-
-/**
- * 전역 의존성 컨테이너
- */
-export const globalDeps = new DepsContainer();
-
-/**
- * 의존성 주입 데코레이터 타입
- * (향후 클래스 기반 핸들러 지원 시)
- */
-export type InjectDeps<T extends keyof FillingDeps> = Pick<FillingDeps, T>;
+/**
+ * DNA-002: Dependency Injection Pattern
+ *
+ * Filling 핸들러의 의존성을 명시적으로 주입
+ * - 테스트 시 목킹 용이
+ * - 의존성 역전 원칙 (DIP) 준수
+ * - 외부 서비스와의 결합도 감소
+ */
+
+/**
+ * 데이터베이스 의존성 인터페이스
+ */
+export interface DbDeps {
+  /**
+   * SQL 쿼리 실행
+   */
+  query: <T>(sql: string, params?: unknown[]) => Promise<T>;
+
+  /**
+   * 트랜잭션 실행
+   */
+  transaction: <T>(fn: () => Promise<T>) => Promise<T>;
+}
+
+/**
+ * 캐시 의존성 인터페이스
+ */
+export interface CacheDeps {
+  /**
+   * 캐시에서 값 조회
+   */
+  get: <T>(key: string) => Promise<T | null>;
+
+  /**
+   * 캐시에 값 저장
+   * @param ttl - Time to live (초 단위)
+   */
+  set: <T>(key: string, value: T, ttl?: number) => Promise<void>;
+
+  /**
+   * 캐시에서 값 삭제
+   */
+  delete: (key: string) => Promise<void>;
+
+  /**
+   * 패턴에 맞는 키 삭제
+   */
+  deletePattern?: (pattern: string) => Promise<void>;
+}
+
+/**
+ * 로거 의존성 인터페이스
+ */
+export interface LoggerDeps {
+  debug: (msg: string, data?: unknown) => void;
+  info: (msg: string, data?: unknown) => void;
+  warn: (msg: string, data?: unknown) => void;
+  error: (msg: string, data?: unknown) => void;
+}
+
+/**
+ * 이벤트 버스 의존성 인터페이스
+ */
+export interface EventBusDeps {
+  /**
+   * 이벤트 발행
+   */
+  emit: (event: string, payload: unknown) => void;
+
+  /**
+   * 이벤트 구독
+   */
+  on: (event: string, handler: (payload: unknown) => void) => () => void;
+}
+
+/**
+ * Filling 핸들러 의존성 타입
+ *
+ * 모든 필드는 선택적 → 필요한 것만 주입
+ */
+export interface FillingDeps {
+  /**
+   * 데이터베이스 접근
+   */
+  db?: DbDeps;
+
+  /**
+   * 캐시 접근
+   */
+  cache?: CacheDeps;
+
+  /**
+   * HTTP 클라이언트
+   */
+  fetch?: typeof fetch;
+
+  /**
+   * 로거
+   */
+  logger?: LoggerDeps;
+
+  /**
+   * 이벤트 버스
+   */
+  events?: EventBusDeps;
+
+  /**
+   * 현재 시간 (테스트용)
+   */
+  now?: () => Date;
+
+  /**
+   * UUID 생성 (테스트용)
+   */
+  uuid?: () => string;
+
+  /**
+   * 커스텀 의존성
+   */
+  [key: string]: unknown;
+}
+
+/**
+ * 기본 의존성 생성
+ *
+ * @example
+ * ```ts
+ * const deps = createDefaultDeps();
+ * console.log(deps.now()); // 현재 시간
+ * ```
+ */
+export function createDefaultDeps(): FillingDeps {
+  return {
+    fetch: globalThis.fetch,
+    logger: {
+      debug: (msg, data) => console.debug(`[DEBUG] ${msg}`, data ?? ""),
+      info: (msg, data) => console.info(`[INFO] ${msg}`, data ?? ""),
+      warn: (msg, data) => console.warn(`[WARN] ${msg}`, data ?? ""),
+      error: (msg, data) => console.error(`[ERROR] ${msg}`, data ?? ""),
+    },
+    now: () => new Date(),
+    uuid: () => crypto.randomUUID(),
+  };
+}
+
+/**
+ * 테스트용 목 의존성 생성 헬퍼
+ *
+ * @example
+ * ```ts
+ * const mockDeps = createMockDeps({
+ *   db: {
+ *     query: vi.fn().mockResolvedValue([{ id: 1, name: "Test" }]),
+ *     transaction: vi.fn(fn => fn()),
+ *   },
+ *   now: () => new Date("2025-01-01"),
+ * });
+ * ```
+ */
+export function createMockDeps(overrides: Partial<FillingDeps> = {}): FillingDeps {
+  const noop = () => {};
+  const asyncNoop = async () => {};
+
+  return {
+    db: {
+      query: async () => [] as any,
+      transaction: async (fn) => fn(),
+    },
+    cache: {
+      get: async () => null,
+      set: asyncNoop,
+      delete: asyncNoop,
+    },
+    fetch: async () => new Response(),
+    logger: {
+      debug: noop,
+      info: noop,
+      warn: noop,
+      error: noop,
+    },
+    events: {
+      emit: noop,
+      on: () => noop,
+    },
+    now: () => new Date("2025-01-01T00:00:00Z"),
+    uuid: () => "00000000-0000-0000-0000-000000000000",
+    ...overrides,
+  };
+}
+
+/**
+ * 의존성 병합 (기본값 + 커스텀)
+ */
+export function mergeDeps(
+  base: FillingDeps,
+  overrides: Partial<FillingDeps>
+): FillingDeps {
+  return { ...base, ...overrides };
+}
+
+/**
+ * 의존성 컨테이너 (싱글톤 관리)
+ */
+class DepsContainer {
+  private deps: FillingDeps = createDefaultDeps();
+
+  /**
+   * 전역 의존성 설정
+   */
+  set(deps: Partial<FillingDeps>): void {
+    this.deps = mergeDeps(this.deps, deps);
+  }
+
+  /**
+   * 전역 의존성 가져오기
+   */
+  get(): FillingDeps {
+    return this.deps;
+  }
+
+  /**
+   * 기본값으로 리셋
+   */
+  reset(): void {
+    this.deps = createDefaultDeps();
+  }
+}
+
+/**
+ * 전역 의존성 컨테이너
+ */
+export const globalDeps = new DepsContainer();
+
+/**
+ * 의존성 주입 데코레이터 타입
+ * (향후 클래스 기반 핸들러 지원 시)
+ */
+export type InjectDeps<T extends keyof FillingDeps> = Pick<FillingDeps, T>;

package/src/filling/index.ts

@@ -8,6 +8,10 @@ export { ManduContext, ValidationError, CookieManager } from "./context";
 export type { CookieOptions } from "./context";
 export { ManduFilling, ManduFillingFactory, LoaderTimeoutError } from "./filling";
 export type { Handler, Guard, HttpMethod, Loader, LoaderOptions } from "./filling";
+export { SSEConnection, createSSEConnection } from "./sse";
+export type { SSEOptions, SSESendOptions, SSECleanup } from "./sse";
+export { resolveResumeCursor, catchupFromCursor, mergeUniqueById } from "./sse-catchup";
+export type { SSECursor, CatchupResult, CatchupOptions } from "./sse-catchup";
 
 // Auth Guards
 export {

package/src/filling/sse-catchup.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "bun:test";
+import { catchupFromCursor, mergeUniqueById, resolveResumeCursor } from "./sse-catchup";
+
+describe("sse catch-up primitives", () => {
+  const snapshot = [
+    { id: "m1", text: "first" },
+    { id: "m2", text: "second" },
+    { id: "m3", text: "third" },
+  ];
+
+  it("resolves Last-Event-ID cursor", () => {
+    const req = new Request("http://localhost/stream", {
+      headers: { "Last-Event-ID": "m2" },
+    });
+
+    expect(resolveResumeCursor(req)).toBe("m2");
+  });
+
+  it("returns delta list when cursor exists", () => {
+    const result = catchupFromCursor({ cursorId: "m1", snapshot });
+
+    expect(result.mode).toBe("delta");
+    expect(result.items.map((m) => m.id)).toEqual(["m2", "m3"]);
+  });
+
+  it("falls back to snapshot when cursor is missing", () => {
+    const result = catchupFromCursor({ snapshot });
+
+    expect(result.mode).toBe("snapshot");
+    expect(result.reason).toBe("missing-cursor");
+    expect(result.items.map((m) => m.id)).toEqual(["m1", "m2", "m3"]);
+  });
+
+  it("falls back to snapshot when cursor is unknown", () => {
+    const result = catchupFromCursor({ cursorId: "missing", snapshot });
+
+    expect(result.mode).toBe("snapshot");
+    expect(result.reason).toBe("unknown-cursor");
+    expect(result.items.map((m) => m.id)).toEqual(["m1", "m2", "m3"]);
+  });
+
+  it("merges incoming messages idempotently", () => {
+    const base = [
+      { id: "m1", text: "first" },
+      { id: "m2", text: "second" },
+    ];
+    const incoming = [
+      { id: "m2", text: "second-dup" },
+      { id: "m3", text: "third" },
+    ];
+
+    const merged = mergeUniqueById(base, incoming);
+
+    expect(merged.map((m) => m.id)).toEqual(["m1", "m2", "m3"]);
+  });
+});

package/src/filling/sse-catchup.ts

@@ -0,0 +1,67 @@
+export interface SSECursor {
+  id: string;
+}
+
+export interface CatchupResult<T> {
+  mode: "delta" | "snapshot";
+  items: T[];
+  reason?: "missing-cursor" | "unknown-cursor";
+}
+
+export interface CatchupOptions<T extends SSECursor> {
+  cursorId?: string | null;
+  snapshot: readonly T[];
+}
+
+/**
+ * Resolve resume cursor from Last-Event-ID header.
+ */
+export function resolveResumeCursor(request: Request): string | undefined {
+  const raw = request.headers.get("last-event-id")?.trim();
+  return raw ? raw : undefined;
+}
+
+/**
+ * Return reconnect catch-up list if cursor exists, otherwise full snapshot fallback.
+ */
+export function catchupFromCursor<T extends SSECursor>(options: CatchupOptions<T>): CatchupResult<T> {
+  const { cursorId, snapshot } = options;
+
+  if (!cursorId) {
+    return {
+      mode: "snapshot",
+      reason: "missing-cursor",
+      items: [...snapshot],
+    };
+  }
+
+  const index = snapshot.findIndex((item) => item.id === cursorId);
+  if (index < 0) {
+    return {
+      mode: "snapshot",
+      reason: "unknown-cursor",
+      items: [...snapshot],
+    };
+  }
+
+  return {
+    mode: "delta",
+    items: snapshot.slice(index + 1),
+  };
+}
+
+/**
+ * Idempotent merge utility for reconnect + snapshot mix.
+ */
+export function mergeUniqueById<T extends SSECursor>(base: readonly T[], incoming: readonly T[]): T[] {
+  const seen = new Set(base.map((item) => item.id));
+  const merged = [...base];
+
+  for (const item of incoming) {
+    if (seen.has(item.id)) continue;
+    seen.add(item.id);
+    merged.push(item);
+  }
+
+  return merged;
+}