@mandujs/core 0.5.7 → 0.7.0

package/src/client/serialize.ts

@@ -0,0 +1,404 @@
+/**
+ * Mandu Props Serialization 📦
+ * Fresh 스타일 고급 직렬화/역직렬화
+ *
+ * @see https://fresh.deno.dev/docs/concepts/islands
+ *
+ * 지원 타입:
+ * - 원시형: null, boolean, number, string, bigint, undefined
+ * - 특수 객체: Date, URL, RegExp, Map, Set
+ * - 순환 참조
+ * - 중첩 객체/배열
+ */
+
+// ============================================
+// 타입 마커
+// ============================================
+
+const TYPE_MARKERS = {
+  /** undefined */
+  UNDEFINED: "\x00_",
+  /** Date */
+  DATE: "\x00D",
+  /** URL */
+  URL: "\x00U",
+  /** RegExp */
+  REGEXP: "\x00R",
+  /** Map */
+  MAP: "\x00M",
+  /** Set */
+  SET: "\x00S",
+  /** 순환 참조 */
+  REF: "\x00$",
+  /** BigInt */
+  BIGINT: "\x00B",
+  /** Symbol (제한적 지원) */
+  SYMBOL: "\x00Y",
+  /** Error */
+  ERROR: "\x00E",
+} as const;
+
+// ============================================
+// 직렬화
+// ============================================
+
+/**
+ * 직렬화 컨텍스트 (순환 참조 추적)
+ */
+interface SerializeContext {
+  /** 이미 본 객체 → 인덱스 */
+  seen: Map<object, number>;
+  /** 참조 테이블 */
+  refs: object[];
+}
+
+/**
+ * Props 직렬화
+ *
+ * @example
+ * ```typescript
+ * const props = {
+ *   date: new Date(),
+ *   url: new URL('https://example.com'),
+ *   items: new Set([1, 2, 3]),
+ *   cache: new Map([['key', 'value']]),
+ * };
+ *
+ * const json = serializeProps(props);
+ * // 클라이언트로 전송
+ * ```
+ */
+export function serializeProps(props: Record<string, unknown>): string {
+  const ctx: SerializeContext = { seen: new Map(), refs: [] };
+  return JSON.stringify(serialize(props, ctx));
+}
+
+/**
+ * 값 직렬화 (재귀)
+ */
+function serialize(value: unknown, ctx: SerializeContext): unknown {
+  // null
+  if (value === null) return null;
+
+  // undefined
+  if (value === undefined) return TYPE_MARKERS.UNDEFINED;
+
+  // 원시형
+  if (typeof value === "boolean" || typeof value === "number") {
+    return value;
+  }
+
+  if (typeof value === "string") {
+    // 타입 마커와 충돌 방지 (첫 문자가 \x00인 경우)
+    if (value.startsWith("\x00")) {
+      return "\x00\x00" + value;
+    }
+    return value;
+  }
+
+  if (typeof value === "bigint") {
+    return TYPE_MARKERS.BIGINT + value.toString();
+  }
+
+  if (typeof value === "symbol") {
+    // Symbol은 description만 보존
+    return TYPE_MARKERS.SYMBOL + (value.description ?? "");
+  }
+
+  // 함수는 직렬화 불가
+  if (typeof value === "function") {
+    console.warn("[Mandu Serialize] Functions cannot be serialized, skipping");
+    return undefined;
+  }
+
+  // 객체 순환 참조 체크
+  if (typeof value === "object") {
+    const existing = ctx.seen.get(value);
+    if (existing !== undefined) {
+      return TYPE_MARKERS.REF + existing;
+    }
+
+    const idx = ctx.refs.length;
+    ctx.seen.set(value, idx);
+    ctx.refs.push(value);
+  }
+
+  // Date
+  if (value instanceof Date) {
+    return TYPE_MARKERS.DATE + value.toISOString();
+  }
+
+  // URL
+  if (value instanceof URL) {
+    return TYPE_MARKERS.URL + value.href;
+  }
+
+  // RegExp
+  if (value instanceof RegExp) {
+    return TYPE_MARKERS.REGEXP + value.toString();
+  }
+
+  // Error
+  if (value instanceof Error) {
+    return [
+      TYPE_MARKERS.ERROR,
+      value.name,
+      value.message,
+      value.stack ?? "",
+    ];
+  }
+
+  // Map
+  if (value instanceof Map) {
+    const entries: [unknown, unknown][] = [];
+    for (const [k, v] of value.entries()) {
+      entries.push([serialize(k, ctx), serialize(v, ctx)]);
+    }
+    return [TYPE_MARKERS.MAP, ...entries];
+  }
+
+  // Set
+  if (value instanceof Set) {
+    const items: unknown[] = [];
+    for (const item of value) {
+      items.push(serialize(item, ctx));
+    }
+    return [TYPE_MARKERS.SET, ...items];
+  }
+
+  // 배열
+  if (Array.isArray(value)) {
+    return value.map((item) => serialize(item, ctx));
+  }
+
+  // 일반 객체
+  const result: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as object)) {
+    const serialized = serialize(v, ctx);
+    if (serialized !== undefined) {
+      result[k] = serialized;
+    }
+  }
+  return result;
+}
+
+// ============================================
+// 역직렬화
+// ============================================
+
+/**
+ * 역직렬화 컨텍스트 (순환 참조 복원)
+ */
+interface DeserializeContext {
+  refs: unknown[];
+}
+
+/**
+ * Props 역직렬화
+ *
+ * @example
+ * ```typescript
+ * // 서버에서 받은 JSON
+ * const json = '{"date":"\x00D2025-01-28T00:00:00.000Z"}';
+ *
+ * const props = deserializeProps(json);
+ * console.log(props.date instanceof Date); // true
+ * ```
+ */
+export function deserializeProps(json: string): Record<string, unknown> {
+  const ctx: DeserializeContext = { refs: [] };
+  const parsed = JSON.parse(json);
+  return deserialize(parsed, ctx) as Record<string, unknown>;
+}
+
+/**
+ * 값 역직렬화 (재귀)
+ */
+function deserialize(value: unknown, ctx: DeserializeContext): unknown {
+  // null
+  if (value === null) return null;
+
+  // 문자열 → 타입 마커 체크
+  if (typeof value === "string") {
+    // undefined
+    if (value === TYPE_MARKERS.UNDEFINED) return undefined;
+
+    // 이스케이프된 문자열 (\x00\x00 → \x00)
+    if (value.startsWith("\x00\x00")) {
+      return value.slice(2);
+    }
+
+    // Date
+    if (value.startsWith(TYPE_MARKERS.DATE)) {
+      return new Date(value.slice(2));
+    }
+
+    // URL
+    if (value.startsWith(TYPE_MARKERS.URL)) {
+      return new URL(value.slice(2));
+    }
+
+    // RegExp
+    if (value.startsWith(TYPE_MARKERS.REGEXP)) {
+      const str = value.slice(2);
+      const match = str.match(/^\/(.*)\/([gimsuy]*)$/);
+      if (match) {
+        return new RegExp(match[1], match[2]);
+      }
+      return str; // 파싱 실패 시 문자열 반환
+    }
+
+    // BigInt
+    if (value.startsWith(TYPE_MARKERS.BIGINT)) {
+      return BigInt(value.slice(2));
+    }
+
+    // Symbol
+    if (value.startsWith(TYPE_MARKERS.SYMBOL)) {
+      return Symbol(value.slice(2));
+    }
+
+    // 순환 참조
+    if (value.startsWith(TYPE_MARKERS.REF)) {
+      const idx = parseInt(value.slice(2), 10);
+      return ctx.refs[idx];
+    }
+
+    return value;
+  }
+
+  // 원시형
+  if (typeof value === "boolean" || typeof value === "number") {
+    return value;
+  }
+
+  // 배열 → 특수 타입 체크
+  if (Array.isArray(value)) {
+    const marker = value[0];
+
+    // Error
+    if (marker === TYPE_MARKERS.ERROR) {
+      const [, name, message, stack] = value as [string, string, string, string];
+      const error = new Error(message);
+      error.name = name;
+      if (stack) error.stack = stack;
+      ctx.refs.push(error);
+      return error;
+    }
+
+    // Map
+    if (marker === TYPE_MARKERS.MAP) {
+      const map = new Map();
+      ctx.refs.push(map);
+      for (let i = 1; i < value.length; i++) {
+        const [k, v] = value[i] as [unknown, unknown];
+        map.set(deserialize(k, ctx), deserialize(v, ctx));
+      }
+      return map;
+    }
+
+    // Set
+    if (marker === TYPE_MARKERS.SET) {
+      const set = new Set();
+      ctx.refs.push(set);
+      for (let i = 1; i < value.length; i++) {
+        set.add(deserialize(value[i], ctx));
+      }
+      return set;
+    }
+
+    // 일반 배열
+    const arr: unknown[] = [];
+    ctx.refs.push(arr);
+    for (const item of value) {
+      arr.push(deserialize(item, ctx));
+    }
+    return arr;
+  }
+
+  // 일반 객체
+  if (typeof value === "object") {
+    const obj: Record<string, unknown> = {};
+    ctx.refs.push(obj);
+    for (const [k, v] of Object.entries(value)) {
+      obj[k] = deserialize(v, ctx);
+    }
+    return obj;
+  }
+
+  return value;
+}
+
+// ============================================
+// 유틸리티
+// ============================================
+
+/**
+ * 직렬화 가능 여부 체크
+ */
+export function isSerializable(value: unknown): boolean {
+  if (value === null || value === undefined) return true;
+
+  const type = typeof value;
+  if (type === "boolean" || type === "number" || type === "string" || type === "bigint") {
+    return true;
+  }
+
+  if (type === "function" || type === "symbol") {
+    return false;
+  }
+
+  if (value instanceof Date || value instanceof URL || value instanceof RegExp) {
+    return true;
+  }
+
+  if (value instanceof Map || value instanceof Set) {
+    return true;
+  }
+
+  if (Array.isArray(value)) {
+    return value.every(isSerializable);
+  }
+
+  if (type === "object") {
+    return Object.values(value as object).every(isSerializable);
+  }
+
+  return false;
+}
+
+/**
+ * SSR에서 클라이언트로 props 전달용 스크립트 생성
+ */
+export function generatePropsScript(
+  islandId: string,
+  props: Record<string, unknown>
+): string {
+  const json = serializeProps(props);
+  const escaped = json
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026");
+
+  return `<script type="application/json" data-mandu-props="${islandId}">${escaped}</script>`;
+}
+
+/**
+ * 클라이언트에서 props 스크립트 파싱
+ */
+export function parsePropsScript(islandId: string): Record<string, unknown> | null {
+  if (typeof document === "undefined") return null;
+
+  const script = document.querySelector(
+    `script[data-mandu-props="${islandId}"]`
+  ) as HTMLScriptElement | null;
+
+  if (!script?.textContent) return null;
+
+  try {
+    return deserializeProps(script.textContent);
+  } catch (err) {
+    console.error(`[Mandu] Failed to parse props for island ${islandId}:`, err);
+    return null;
+  }
+}

package/src/filling/filling.ts

@@ -7,6 +7,16 @@ import { ManduContext, NEXT_SYMBOL, ValidationError } from "./context";
 import { AuthenticationError, AuthorizationError } from "./auth";
 import { ErrorClassifier, formatErrorResponse, ErrorCode } from "../error";
 import { createContract, type ContractDefinition, type ContractInstance } from "../contract";
+import {
+  type LifecycleStore,
+  type OnRequestHandler,
+  type BeforeHandleHandler,
+  type AfterHandleHandler,
+  type OnErrorHandler,
+  type AfterResponseHandler,
+  createLifecycleStore,
+  executeLifecycle,
+} from "../runtime/lifecycle";
 
 /** Handler function type */
 export type Handler = (ctx: ManduContext) => Response | Promise<Response>;
@@ -41,6 +51,7 @@ interface FillingConfig<TLoaderData = unknown> {
   guards: Guard[];
   methodGuards: Map<HttpMethod, Guard[]>;
   loader?: Loader<TLoaderData>;
+  lifecycle: LifecycleStore;
 }
 
 /**
@@ -68,6 +79,7 @@ export class ManduFilling<TLoaderData = unknown> {
     handlers: new Map(),
     guards: [],
     methodGuards: new Map(),
+    lifecycle: createLifecycleStore(),
   };
 
   // ============================================
@@ -218,6 +230,90 @@ export class ManduFilling<TLoaderData = unknown> {
     return this.guard(guardFn, ...methods);
   }
 
+  // ============================================
+  // 🥟 Lifecycle Hooks (Elysia 스타일)
+  // ============================================
+
+  /**
+   * 요청 시작 시 실행
+   * @example
+   * ```typescript
+   * .onRequest((ctx) => {
+   *   console.log('Request:', ctx.req.method, ctx.req.url);
+   * })
+   * ```
+   */
+  onRequest(fn: OnRequestHandler): this {
+    this.config.lifecycle.onRequest.push({ fn, scope: "local" });
+    return this;
+  }
+
+  /**
+   * 핸들러 전 실행 (Guard 역할)
+   * Response 반환 시 체인 중단
+   * @example
+   * ```typescript
+   * .beforeHandle((ctx) => {
+   *   if (!ctx.get('user')) {
+   *     return ctx.unauthorized();
+   *   }
+   *   // void 반환 시 계속 진행
+   * })
+   * ```
+   */
+  beforeHandle(fn: BeforeHandleHandler): this {
+    this.config.lifecycle.beforeHandle.push({ fn, scope: "local" });
+    return this;
+  }
+
+  /**
+   * 핸들러 후 실행 (응답 변환)
+   * @example
+   * ```typescript
+   * .afterHandle((ctx, response) => {
+   *   // 응답 헤더 추가
+   *   response.headers.set('X-Request-Id', crypto.randomUUID());
+   *   return response;
+   * })
+   * ```
+   */
+  afterHandle(fn: AfterHandleHandler): this {
+    this.config.lifecycle.afterHandle.push({ fn, scope: "local" });
+    return this;
+  }
+
+  /**
+   * 에러 발생 시 실행
+   * Response 반환 시 에러 응답으로 사용
+   * @example
+   * ```typescript
+   * .onError((ctx, error) => {
+   *   console.error('Error:', error);
+   *   return ctx.json({ error: error.message }, 500);
+   * })
+   * ```
+   */
+  onError(fn: OnErrorHandler): this {
+    this.config.lifecycle.onError.push({ fn, scope: "local" });
+    return this;
+  }
+
+  /**
+   * 응답 후 실행 (비동기, 응답에 영향 없음)
+   * 로깅, 메트릭 수집 등에 사용
+   * @example
+   * ```typescript
+   * .afterResponse((ctx) => {
+   *   console.log('Response sent:', ctx.req.url);
+   *   metrics.increment('requests');
+   * })
+   * ```
+   */
+  afterResponse(fn: AfterResponseHandler): this {
+    this.config.lifecycle.afterResponse.push({ fn, scope: "local" });
+    return this;
+  }
+
   // ============================================
   // 🥟 Execution
   // ============================================