@mandujs/core 0.3.4 → 0.4.0

package/src/filling/filling.ts

@@ -15,10 +15,14 @@ export type Guard = (ctx: ManduContext) => symbol | Response | Promise<symbol |
 /** HTTP methods */
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
 
-interface FillingConfig {
+/** Loader function type - SSR 데이터 로딩 */
+export type Loader<T = unknown> = (ctx: ManduContext) => T | Promise<T>;
+
+interface FillingConfig<TLoaderData = unknown> {
   handlers: Map<HttpMethod, Handler>;
   guards: Guard[];
   methodGuards: Map<HttpMethod, Guard[]>;
+  loader?: Loader<TLoaderData>;
 }
 
 /**
@@ -30,14 +34,64 @@ interface FillingConfig {
  *   .get(ctx => ctx.ok({ message: 'Hello!' }))
  *   .post(ctx => ctx.created({ id: 1 }))
  * ```
+ *
+ * @example with loader
+ * ```typescript
+ * export default Mandu.filling<{ todos: Todo[] }>()
+ *   .loader(async (ctx) => {
+ *     const todos = await db.todos.findMany();
+ *     return { todos };
+ *   })
+ *   .get(ctx => ctx.ok(ctx.get('loaderData')))
+ * ```
  */
-export class ManduFilling {
-  private config: FillingConfig = {
+export class ManduFilling<TLoaderData = unknown> {
+  private config: FillingConfig<TLoaderData> = {
     handlers: new Map(),
     guards: [],
     methodGuards: new Map(),
   };
 
+  // ============================================
+  // 🥟 SSR Loader
+  // ============================================
+
+  /**
+   * Define SSR data loader
+   * 페이지 렌더링 전 서버에서 데이터를 로드합니다.
+   * 로드된 데이터는 클라이언트로 전달되어 hydration에 사용됩니다.
+   *
+   * @example
+   * ```typescript
+   * .loader(async (ctx) => {
+   *   const todos = await db.todos.findMany();
+   *   return { todos, user: ctx.get('user') };
+   * })
+   * ```
+   */
+  loader(loaderFn: Loader<TLoaderData>): this {
+    this.config.loader = loaderFn;
+    return this;
+  }
+
+  /**
+   * Execute loader and return data
+   * @internal Used by SSR runtime
+   */
+  async executeLoader(ctx: ManduContext): Promise<TLoaderData | undefined> {
+    if (!this.config.loader) {
+      return undefined;
+    }
+    return await this.config.loader(ctx);
+  }
+
+  /**
+   * Check if loader is defined
+   */
+  hasLoader(): boolean {
+    return !!this.config.loader;
+  }
+
   // ============================================
   // 🥟 HTTP Method Handlers
   // ============================================
@@ -242,9 +296,26 @@ export const Mandu = {
    * export default Mandu.filling()
    *   .get(ctx => ctx.ok({ message: 'Hello!' }))
    * ```
+   *
+   * @example with loader data type
+   * ```typescript
+   * import { Mandu } from '@mandujs/core'
+   *
+   * interface LoaderData {
+   *   todos: Todo[];
+   *   user: User | null;
+   * }
+   *
+   * export default Mandu.filling<LoaderData>()
+   *   .loader(async (ctx) => {
+   *     const todos = await db.todos.findMany();
+   *     return { todos, user: null };
+   *   })
+   *   .get(ctx => ctx.ok(ctx.get('loaderData')))
+   * ```
    */
-  filling(): ManduFilling {
-    return new ManduFilling();
+  filling<TLoaderData = unknown>(): ManduFilling<TLoaderData> {
+    return new ManduFilling<TLoaderData>();
   },
 
   /**

package/src/index.ts

@@ -7,3 +7,4 @@ export * from "./filling";
 export * from "./change";
 export * from "./error";
 export * from "./slot";
+export * from "./bundler";

package/src/runtime/ssr.ts

@@ -1,14 +1,120 @@
 import { renderToString } from "react-dom/server";
 import type { ReactElement } from "react";
+import type { BundleManifest } from "../bundler/types";
+import type { HydrationConfig, HydrationPriority } from "../spec/schema";
 
 export interface SSROptions {
   title?: string;
   lang?: string;
+  /** 서버에서 로드한 데이터 (클라이언트로 전달) */
+  serverData?: Record<string, unknown>;
+  /** Hydration 설정 */
+  hydration?: HydrationConfig;
+  /** 번들 매니페스트 */
+  bundleManifest?: BundleManifest;
+  /** 라우트 ID (island 식별용) */
+  routeId?: string;
+  /** 추가 head 태그 */
+  headTags?: string;
+  /** 추가 body 끝 태그 */
+  bodyEndTags?: string;
+}
+
+/**
+ * SSR 데이터를 안전하게 직렬화
+ */
+function serializeServerData(data: Record<string, unknown>): string {
+  // XSS 방지를 위한 이스케이프
+  const json = JSON.stringify(data)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/'/g, "\\u0027");
+
+  return `<script id="__MANDU_DATA__" type="application/json">${json}</script>
+<script>window.__MANDU_DATA__ = JSON.parse(document.getElementById('__MANDU_DATA__').textContent);</script>`;
+}
+
+/**
+ * Hydration 스크립트 태그 생성
+ */
+function generateHydrationScripts(
+  routeId: string,
+  manifest: BundleManifest
+): string {
+  const scripts: string[] = [];
+
+  // Runtime 로드
+  if (manifest.shared.runtime) {
+    scripts.push(`<script type="module" src="${manifest.shared.runtime}"></script>`);
+  }
+
+  // Vendor 로드
+  if (manifest.shared.vendor) {
+    scripts.push(`<script type="module" src="${manifest.shared.vendor}"></script>`);
+  }
+
+  // Island 번들 로드
+  const bundle = manifest.bundles[routeId];
+  if (bundle) {
+    // Preload (선택적)
+    scripts.push(`<link rel="modulepreload" href="${bundle.js}">`);
+    scripts.push(`<script type="module" src="${bundle.js}"></script>`);
+  }
+
+  return scripts.join("\n");
+}
+
+/**
+ * Island 래퍼로 컨텐츠 감싸기
+ */
+export function wrapWithIsland(
+  content: string,
+  routeId: string,
+  priority: HydrationPriority = "visible"
+): string {
+  return `<div data-mandu-island="${routeId}" data-mandu-priority="${priority}">${content}</div>`;
 }
 
 export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
-  const { title = "Mandu App", lang = "ko" } = options;
-  const content = renderToString(element);
+  const {
+    title = "Mandu App",
+    lang = "ko",
+    serverData,
+    hydration,
+    bundleManifest,
+    routeId,
+    headTags = "",
+    bodyEndTags = "",
+  } = options;
+
+  let content = renderToString(element);
+
+  // Island 래퍼 적용 (hydration 필요 시)
+  const needsHydration =
+    hydration && hydration.strategy !== "none" && routeId && bundleManifest;
+
+  if (needsHydration) {
+    content = wrapWithIsland(content, routeId, hydration.priority);
+  }
+
+  // 서버 데이터 스크립트
+  let dataScript = "";
+  if (serverData && routeId) {
+    const wrappedData = {
+      [routeId]: {
+        serverData,
+        timestamp: Date.now(),
+      },
+    };
+    dataScript = serializeServerData(wrappedData);
+  }
+
+  // Hydration 스크립트
+  let hydrationScripts = "";
+  if (needsHydration && bundleManifest) {
+    hydrationScripts = generateHydrationScripts(routeId, bundleManifest);
+  }
 
   return `<!doctype html>
 <html lang="${lang}">
@@ -16,9 +122,13 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>${title}</title>
+  ${headTags}
 </head>
 <body>
   <div id="root">${content}</div>
+  ${dataScript}
+  ${hydrationScripts}
+  ${bodyEndTags}
 </body>
 </html>`;
 }
@@ -36,3 +146,33 @@ export function renderSSR(element: ReactElement, options: SSROptions = {}): Resp
   const html = renderToHTML(element, options);
   return createHTMLResponse(html);
 }
+
+/**
+ * Hydration이 포함된 SSR 렌더링
+ *
+ * @example
+ * ```typescript
+ * const response = await renderWithHydration(
+ *   <TodoList todos={todos} />,
+ *   {
+ *     title: "할일 목록",
+ *     routeId: "todos",
+ *     serverData: { todos },
+ *     hydration: { strategy: "island", priority: "visible" },
+ *     bundleManifest,
+ *   }
+ * );
+ * ```
+ */
+export async function renderWithHydration(
+  element: ReactElement,
+  options: SSROptions & {
+    routeId: string;
+    serverData: Record<string, unknown>;
+    hydration: HydrationConfig;
+    bundleManifest: BundleManifest;
+  }
+): Promise<Response> {
+  const html = renderToHTML(element, options);
+  return createHTMLResponse(html);
+}

package/src/spec/schema.ts

@@ -1,16 +1,90 @@
 import { z } from "zod";
 
+// ========== Hydration 설정 ==========
+
+export const HydrationStrategy = z.enum(["none", "island", "full", "progressive"]);
+export type HydrationStrategy = z.infer<typeof HydrationStrategy>;
+
+export const HydrationPriority = z.enum(["immediate", "visible", "idle", "interaction"]);
+export type HydrationPriority = z.infer<typeof HydrationPriority>;
+
+export const HydrationConfig = z.object({
+  /**
+   * Hydration 전략
+   * - none: 순수 Static HTML (JS 없음)
+   * - island: Slot 영역만 hydrate (기본값)
+   * - full: 전체 페이지 hydrate
+   * - progressive: 점진적 hydrate
+   */
+  strategy: HydrationStrategy,
+
+  /**
+   * Hydration 우선순위
+   * - immediate: 페이지 로드 즉시
+   * - visible: 뷰포트에 보일 때 (기본값)
+   * - idle: 브라우저 idle 시
+   * - interaction: 사용자 상호작용 시
+   */
+  priority: HydrationPriority.default("visible"),
+
+  /**
+   * 번들 preload 여부
+   */
+  preload: z.boolean().default(false),
+});
+
+export type HydrationConfig = z.infer<typeof HydrationConfig>;
+
+// ========== Loader 설정 ==========
+
+export const LoaderConfig = z.object({
+  /**
+   * SSR 시 데이터 로딩 타임아웃 (ms)
+   */
+  timeout: z.number().positive().default(5000),
+
+  /**
+   * 로딩 실패 시 fallback 데이터
+   */
+  fallback: z.record(z.unknown()).optional(),
+});
+
+export type LoaderConfig = z.infer<typeof LoaderConfig>;
+
+// ========== Route 설정 ==========
+
 export const RouteKind = z.enum(["page", "api"]);
 export type RouteKind = z.infer<typeof RouteKind>;
 
+export const HttpMethod = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]);
+export type HttpMethod = z.infer<typeof HttpMethod>;
+
 export const RouteSpec = z
   .object({
     id: z.string().min(1, "id는 필수입니다"),
     pattern: z.string().startsWith("/", "pattern은 /로 시작해야 합니다"),
     kind: RouteKind,
+
+    // HTTP 메서드 (API용)
+    methods: z.array(HttpMethod).optional(),
+
+    // 서버 모듈 (generated route handler)
     module: z.string().min(1, "module 경로는 필수입니다"),
+
+    // 페이지 컴포넌트 모듈 (generated)
     componentModule: z.string().optional(),
+
+    // 서버 슬롯 (비즈니스 로직)
     slotModule: z.string().optional(),
+
+    // 클라이언트 슬롯 (interactive 로직) [NEW]
+    clientModule: z.string().optional(),
+
+    // Hydration 설정 [NEW]
+    hydration: HydrationConfig.optional(),
+
+    // Loader 설정 [NEW]
+    loader: LoaderConfig.optional(),
   })
   .refine(
     (route) => {
@@ -23,10 +97,25 @@ export const RouteSpec = z
       message: "kind가 'page'인 경우 componentModule은 필수입니다",
       path: ["componentModule"],
     }
+  )
+  .refine(
+    (route) => {
+      // clientModule이 있으면 hydration.strategy가 none이 아니어야 함
+      if (route.clientModule && route.hydration?.strategy === "none") {
+        return false;
+      }
+      return true;
+    },
+    {
+      message: "clientModule이 있으면 hydration.strategy는 'none'이 아니어야 합니다",
+      path: ["hydration"],
+    }
   );
 
 export type RouteSpec = z.infer<typeof RouteSpec>;
 
+// ========== Manifest ==========
+
 export const RoutesManifest = z
   .object({
     version: z.number().int().positive(),
@@ -56,3 +145,46 @@ export const RoutesManifest = z
   );
 
 export type RoutesManifest = z.infer<typeof RoutesManifest>;
+
+// ========== 유틸리티 함수 ==========
+
+/**
+ * 기본 hydration 설정 반환
+ */
+export function getDefaultHydration(route: RouteSpec): HydrationConfig {
+  // clientModule이 있으면 island, 없으면 none
+  if (route.clientModule) {
+    return {
+      strategy: "island",
+      priority: "visible",
+      preload: false,
+    };
+  }
+  return {
+    strategy: "none",
+    priority: "visible",
+    preload: false,
+  };
+}
+
+/**
+ * 라우트의 실제 hydration 설정 반환 (기본값 적용)
+ */
+export function getRouteHydration(route: RouteSpec): HydrationConfig {
+  if (route.hydration) {
+    return {
+      strategy: route.hydration.strategy,
+      priority: route.hydration.priority ?? "visible",
+      preload: route.hydration.preload ?? false,
+    };
+  }
+  return getDefaultHydration(route);
+}
+
+/**
+ * Hydration이 필요한 라우트인지 확인
+ */
+export function needsHydration(route: RouteSpec): boolean {
+  const hydration = getRouteHydration(route);
+  return route.kind === "page" && hydration.strategy !== "none";
+}