@mandujs/core 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/client/index.ts

@@ -89,6 +89,15 @@ export {
   useRouterState,
 } from "./hooks";
 
+// Props Serialization (Fresh 스타일)
+export {
+  serializeProps,
+  deserializeProps,
+  isSerializable,
+  generatePropsScript,
+  parsePropsScript,
+} from "./serialize";
+
 // Re-export as Mandu namespace for consistent API
 import { island, wrapComponent } from "./island";
 import { hydrateIslands, initializeRuntime } from "./runtime";

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
   // ============================================

package/src/runtime/compose.ts

@@ -0,0 +1,222 @@
+/**
+ * Mandu Middleware Compose 🔗
+ * Hono 스타일 미들웨어 조합 패턴
+ *
+ * @see https://github.com/honojs/hono/blob/main/src/compose.ts
+ */
+
+import type { ManduContext } from "../filling/context";
+
+/**
+ * Next 함수 타입
+ */
+export type Next = () => Promise<void>;
+
+/**
+ * 미들웨어 함수 타입
+ * - Response 반환: 체인 중단 (Guard 역할)
+ * - void 반환: 다음 미들웨어 실행
+ */
+export type Middleware = (
+  ctx: ManduContext,
+  next: Next
+) => Response | void | Promise<Response | void>;
+
+/**
+ * 에러 핸들러 타입
+ */
+export type ErrorHandler = (
+  error: Error,
+  ctx: ManduContext
+) => Response | Promise<Response>;
+
+/**
+ * NotFound 핸들러 타입
+ */
+export type NotFoundHandler = (ctx: ManduContext) => Response | Promise<Response>;
+
+/**
+ * 미들웨어 엔트리 (메타데이터 포함)
+ */
+export interface MiddlewareEntry {
+  fn: Middleware;
+  name?: string;
+  isAsync?: boolean;
+}
+
+/**
+ * Compose 옵션
+ */
+export interface ComposeOptions {
+  onError?: ErrorHandler;
+  onNotFound?: NotFoundHandler;
+}
+
+/**
+ * 미들웨어 함수들을 하나의 실행 함수로 조합
+ *
+ * @example
+ * ```typescript
+ * const middleware = [
+ *   { fn: async (ctx, next) => { console.log('before'); await next(); console.log('after'); } },
+ *   { fn: async (ctx, next) => { return ctx.ok({ data: 'hello' }); } },
+ * ];
+ *
+ * const handler = compose(middleware, {
+ *   onError: (err, ctx) => ctx.json({ error: err.message }, 500),
+ *   onNotFound: (ctx) => ctx.notFound(),
+ * });
+ *
+ * const response = await handler(context);
+ * ```
+ */
+export function compose(
+  middleware: MiddlewareEntry[],
+  options: ComposeOptions = {}
+): (ctx: ManduContext) => Promise<Response> {
+  const { onError, onNotFound } = options;
+
+  return async (ctx: ManduContext): Promise<Response> => {
+    let index = -1;
+    let finalResponse: Response | undefined;
+
+    /**
+     * 미들웨어 순차 실행
+     * @param i 현재 인덱스
+     */
+    async function dispatch(i: number): Promise<void> {
+      // next() 이중 호출 방지
+      if (i <= index) {
+        throw new Error("next() called multiple times");
+      }
+      index = i;
+
+      const entry = middleware[i];
+
+      if (!entry) {
+        // 모든 미들웨어 통과 후 핸들러 없음
+        if (!finalResponse && onNotFound) {
+          finalResponse = await onNotFound(ctx);
+        }
+        return;
+      }
+
+      try {
+        const result = await entry.fn(ctx, () => dispatch(i + 1));
+
+        // Response 반환 시 체인 중단
+        if (result instanceof Response) {
+          finalResponse = result;
+          return;
+        }
+      } catch (err) {
+        if (err instanceof Error && onError) {
+          finalResponse = await onError(err, ctx);
+          return;
+        }
+        throw err;
+      }
+    }
+
+    await dispatch(0);
+
+    // 응답이 없으면 404
+    if (!finalResponse) {
+      if (onNotFound) {
+        finalResponse = await onNotFound(ctx);
+      } else {
+        finalResponse = new Response("Not Found", { status: 404 });
+      }
+    }
+
+    return finalResponse;
+  };
+}
+
+/**
+ * 미들웨어 배열 생성 헬퍼
+ *
+ * @example
+ * ```typescript
+ * const mw = createMiddleware([
+ *   authGuard,
+ *   rateLimitGuard,
+ *   mainHandler,
+ * ]);
+ * ```
+ */
+export function createMiddleware(
+  fns: Middleware[]
+): MiddlewareEntry[] {
+  return fns.map((fn, i) => ({
+    fn,
+    name: fn.name || `middleware_${i}`,
+    isAsync: fn.constructor.name === "AsyncFunction",
+  }));
+}
+
+/**
+ * 미들웨어 체인 빌더
+ *
+ * @example
+ * ```typescript
+ * const chain = new MiddlewareChain()
+ *   .use(authGuard)
+ *   .use(rateLimitGuard)
+ *   .use(mainHandler)
+ *   .onError((err, ctx) => ctx.json({ error: err.message }, 500))
+ *   .build();
+ *
+ * const response = await chain(ctx);
+ * ```
+ */
+export class MiddlewareChain {
+  private middleware: MiddlewareEntry[] = [];
+  private errorHandler?: ErrorHandler;
+  private notFoundHandler?: NotFoundHandler;
+
+  /**
+   * 미들웨어 추가
+   */
+  use(fn: Middleware, name?: string): this {
+    this.middleware.push({
+      fn,
+      name: name || fn.name || `middleware_${this.middleware.length}`,
+      isAsync: fn.constructor.name === "AsyncFunction",
+    });
+    return this;
+  }
+
+  /**
+   * 에러 핸들러 설정
+   */
+  onError(handler: ErrorHandler): this {
+    this.errorHandler = handler;
+    return this;
+  }
+
+  /**
+   * NotFound 핸들러 설정
+   */
+  onNotFound(handler: NotFoundHandler): this {
+    this.notFoundHandler = handler;
+    return this;
+  }
+
+  /**
+   * 미들웨어 체인 빌드
+   */
+  build(): (ctx: ManduContext) => Promise<Response> {
+    return compose(this.middleware, {
+      onError: this.errorHandler,
+      onNotFound: this.notFoundHandler,
+    });
+  }
+
+  /**
+   * 미들웨어 목록 조회
+   */
+  getMiddleware(): MiddlewareEntry[] {
+    return [...this.middleware];
+  }
+}

package/src/runtime/index.ts

@@ -3,3 +3,5 @@ export * from "./router";
 export * from "./server";
 export * from "./cors";
 export * from "./env";
+export * from "./compose";
+export * from "./lifecycle";

package/src/runtime/lifecycle.ts

@@ -0,0 +1,360 @@
+/**
+ * Mandu Lifecycle Hooks 🔄
+ * Elysia 스타일 라이프사이클 훅 체계
+ *
+ * @see https://elysiajs.com/life-cycle/overview.html
+ *
+ * 요청 흐름:
+ * 1. onRequest    - 요청 시작
+ * 2. onParse      - 바디 파싱 (POST, PUT, PATCH)
+ * 3. beforeHandle - 핸들러 전 (Guard 역할)
+ * 4. [Handler]    - 메인 핸들러 실행
+ * 5. afterHandle  - 핸들러 후 (응답 변환)
+ * 6. mapResponse  - 응답 매핑
+ * 7. afterResponse - 응답 후 (로깅, 정리)
+ *
+ * 에러 발생 시:
+ * - onError       - 에러 핸들링
+ */
+
+import type { ManduContext } from "../filling/context";
+
+/**
+ * 훅 스코프
+ * - global: 모든 라우트에 적용
+ * - scoped: 현재 플러그인/라우트 그룹에 적용
+ * - local: 현재 라우트에만 적용
+ */
+export type HookScope = "global" | "scoped" | "local";
+
+/**
+ * 훅 컨테이너
+ */
+export interface HookContainer<T extends Function = Function> {
+  fn: T;
+  scope: HookScope;
+  name?: string;
+  checksum?: number; // 중복 제거용
+}
+
+// ============================================
+// 훅 타입 정의
+// ============================================
+
+/** 요청 시작 훅 */
+export type OnRequestHandler = (ctx: ManduContext) => void | Promise<void>;
+
+/** 바디 파싱 훅 */
+export type OnParseHandler = (ctx: ManduContext) => void | Promise<void>;
+
+/** 핸들러 전 훅 (Guard 역할) - Response 반환 시 체인 중단 */
+export type BeforeHandleHandler = (
+  ctx: ManduContext
+) => Response | void | Promise<Response | void>;
+
+/** 핸들러 후 훅 - 응답 변환 가능 */
+export type AfterHandleHandler = (
+  ctx: ManduContext,
+  response: Response
+) => Response | Promise<Response>;
+
+/** 응답 매핑 훅 */
+export type MapResponseHandler = (
+  ctx: ManduContext,
+  response: Response
+) => Response | Promise<Response>;
+
+/** 응답 후 훅 (비동기, 응답에 영향 없음) */
+export type AfterResponseHandler = (ctx: ManduContext) => void | Promise<void>;
+
+/** 에러 핸들링 훅 - Response 반환 시 에러 응답으로 사용 */
+export type OnErrorHandler = (
+  ctx: ManduContext,
+  error: Error
+) => Response | void | Promise<Response | void>;
+
+// ============================================
+// 라이프사이클 스토어
+// ============================================
+
+/**
+ * 라이프사이클 훅 스토어
+ */
+export interface LifecycleStore {
+  onRequest: HookContainer<OnRequestHandler>[];
+  onParse: HookContainer<OnParseHandler>[];
+  beforeHandle: HookContainer<BeforeHandleHandler>[];
+  afterHandle: HookContainer<AfterHandleHandler>[];
+  mapResponse: HookContainer<MapResponseHandler>[];
+  afterResponse: HookContainer<AfterResponseHandler>[];
+  onError: HookContainer<OnErrorHandler>[];
+}
+
+/**
+ * 빈 라이프사이클 스토어 생성
+ */
+export function createLifecycleStore(): LifecycleStore {
+  return {
+    onRequest: [],
+    onParse: [],
+    beforeHandle: [],
+    afterHandle: [],
+    mapResponse: [],
+    afterResponse: [],
+    onError: [],
+  };
+}
+
+// ============================================
+// 라이프사이클 실행
+// ============================================
+
+/**
+ * 라이프사이클 실행 옵션
+ */
+export interface ExecuteOptions {
+  /** 바디 파싱이 필요한 메서드 */
+  parseBodyMethods?: string[];
+}
+
+const DEFAULT_PARSE_BODY_METHODS = ["POST", "PUT", "PATCH"];
+
+/**
+ * 라이프사이클 실행
+ *
+ * @param lifecycle 라이프사이클 스토어
+ * @param ctx ManduContext
+ * @param handler 메인 핸들러
+ * @param options 옵션
+ *
+ * @example
+ * ```typescript
+ * const lifecycle = createLifecycleStore();
+ * lifecycle.onRequest.push({ fn: (ctx) => console.log('Request started'), scope: 'local' });
+ * lifecycle.beforeHandle.push({ fn: authGuard, scope: 'local' });
+ *
+ * const response = await executeLifecycle(
+ *   lifecycle,
+ *   ctx,
+ *   async () => ctx.ok({ data: 'hello' })
+ * );
+ * ```
+ */
+export async function executeLifecycle(
+  lifecycle: LifecycleStore,
+  ctx: ManduContext,
+  handler: () => Promise<Response>,
+  options: ExecuteOptions = {}
+): Promise<Response> {
+  const { parseBodyMethods = DEFAULT_PARSE_BODY_METHODS } = options;
+  let response: Response;
+
+  try {
+    // 1. onRequest
+    for (const hook of lifecycle.onRequest) {
+      await hook.fn(ctx);
+    }
+
+    // 2. onParse (바디가 있는 메서드만)
+    if (parseBodyMethods.includes(ctx.req.method)) {
+      for (const hook of lifecycle.onParse) {
+        await hook.fn(ctx);
+      }
+    }
+
+    // 3. beforeHandle (Guard 역할)
+    for (const hook of lifecycle.beforeHandle) {
+      const result = await hook.fn(ctx);
+      if (result instanceof Response) {
+        // Response 반환 시 체인 중단, afterHandle/mapResponse 건너뜀
+        response = result;
+        // afterResponse는 실행
+        scheduleAfterResponse(lifecycle.afterResponse, ctx);
+        return response;
+      }
+    }
+
+    // 4. 메인 핸들러 실행
+    response = await handler();
+
+    // 5. afterHandle
+    for (const hook of lifecycle.afterHandle) {
+      response = await hook.fn(ctx, response);
+    }
+
+    // 6. mapResponse
+    for (const hook of lifecycle.mapResponse) {
+      response = await hook.fn(ctx, response);
+    }
+
+    // 7. afterResponse (비동기)
+    scheduleAfterResponse(lifecycle.afterResponse, ctx);
+
+    return response;
+  } catch (err) {
+    // onError 처리
+    const error = err instanceof Error ? err : new Error(String(err));
+
+    for (const hook of lifecycle.onError) {
+      const result = await hook.fn(ctx, error);
+      if (result instanceof Response) {
+        // afterResponse는 에러 시에도 실행
+        scheduleAfterResponse(lifecycle.afterResponse, ctx);
+        return result;
+      }
+    }
+
+    // 에러 핸들러가 Response를 반환하지 않으면 재throw
+    throw error;
+  }
+}
+
+/**
+ * afterResponse 훅 비동기 실행 (응답 후)
+ */
+function scheduleAfterResponse(
+  hooks: HookContainer<AfterResponseHandler>[],
+  ctx: ManduContext
+): void {
+  if (hooks.length === 0) return;
+
+  // queueMicrotask로 응답 후 실행
+  queueMicrotask(async () => {
+    for (const hook of hooks) {
+      try {
+        await hook.fn(ctx);
+      } catch (err) {
+        console.error("[Mandu] afterResponse hook error:", err);
+      }
+    }
+  });
+}
+
+// ============================================
+// 라이프사이클 빌더
+// ============================================
+
+/**
+ * 라이프사이클 빌더
+ *
+ * @example
+ * ```typescript
+ * const lifecycle = new LifecycleBuilder()
+ *   .onRequest((ctx) => console.log('Request:', ctx.req.url))
+ *   .beforeHandle(authGuard)
+ *   .afterHandle((ctx, res) => {
+ *     // 응답 헤더 추가
+ *     res.headers.set('X-Custom', 'value');
+ *     return res;
+ *   })
+ *   .onError((ctx, err) => ctx.json({ error: err.message }, 500))
+ *   .build();
+ * ```
+ */
+export class LifecycleBuilder {
+  private store: LifecycleStore = createLifecycleStore();
+
+  /**
+   * 요청 시작 훅 추가
+   */
+  onRequest(fn: OnRequestHandler, scope: HookScope = "local"): this {
+    this.store.onRequest.push({ fn, scope });
+    return this;
+  }
+
+  /**
+   * 바디 파싱 훅 추가
+   */
+  onParse(fn: OnParseHandler, scope: HookScope = "local"): this {
+    this.store.onParse.push({ fn, scope });
+    return this;
+  }
+
+  /**
+   * 핸들러 전 훅 추가 (Guard 역할)
+   */
+  beforeHandle(fn: BeforeHandleHandler, scope: HookScope = "local"): this {
+    this.store.beforeHandle.push({ fn, scope });
+    return this;
+  }
+
+  /**
+   * 핸들러 후 훅 추가
+   */
+  afterHandle(fn: AfterHandleHandler, scope: HookScope = "local"): this {
+    this.store.afterHandle.push({ fn, scope });
+    return this;
+  }
+
+  /**
+   * 응답 매핑 훅 추가
+   */
+  mapResponse(fn: MapResponseHandler, scope: HookScope = "local"): this {
+    this.store.mapResponse.push({ fn, scope });
+    return this;
+  }
+
+  /**
+   * 응답 후 훅 추가
+   */
+  afterResponse(fn: AfterResponseHandler, scope: HookScope = "local"): this {
+    this.store.afterResponse.push({ fn, scope });
+    return this;
+  }
+
+  /**
+   * 에러 핸들링 훅 추가
+   */
+  onError(fn: OnErrorHandler, scope: HookScope = "local"): this {
+    this.store.onError.push({ fn, scope });
+    return this;
+  }
+
+  /**
+   * 라이프사이클 스토어 빌드
+   */
+  build(): LifecycleStore {
+    return { ...this.store };
+  }
+
+  /**
+   * 다른 라이프사이클과 병합
+   */
+  merge(other: LifecycleStore): this {
+    this.store.onRequest.push(...other.onRequest);
+    this.store.onParse.push(...other.onParse);
+    this.store.beforeHandle.push(...other.beforeHandle);
+    this.store.afterHandle.push(...other.afterHandle);
+    this.store.mapResponse.push(...other.mapResponse);
+    this.store.afterResponse.push(...other.afterResponse);
+    this.store.onError.push(...other.onError);
+    return this;
+  }
+}
+
+// ============================================
+// 유틸리티
+// ============================================
+
+/**
+ * 훅 중복 제거 (checksum 기반)
+ */
+export function deduplicateHooks<T extends HookContainer>(hooks: T[]): T[] {
+  const seen = new Set<number>();
+  return hooks.filter((hook) => {
+    if (hook.checksum === undefined) return true;
+    if (seen.has(hook.checksum)) return false;
+    seen.add(hook.checksum);
+    return true;
+  });
+}
+
+/**
+ * 스코프별 훅 필터링
+ */
+export function filterHooksByScope<T extends HookContainer>(
+  hooks: T[],
+  scopes: HookScope[]
+): T[] {
+  return hooks.filter((hook) => scopes.includes(hook.scope));
+}