@mandujs/core 0.18.21 → 0.19.0

package/src/router/fs-routes.ts

@@ -51,49 +51,43 @@ export interface GenerateOptions {
  * FSRouteConfig를 RouteSpec으로 변환
  */
 export function fsRouteToRouteSpec(fsRoute: FSRouteConfig): RouteSpec {
-  const routeSpec: RouteSpec = {
+  const base = {
     id: fsRoute.id,
     pattern: fsRoute.pattern,
-    kind: fsRoute.kind,
     module: fsRoute.module,
   };
 
-  // 페이지 라우트의 경우
   if (fsRoute.kind === "page") {
-    routeSpec.componentModule = fsRoute.componentModule;
-
-    // Island (클라이언트 모듈)
-    if (fsRoute.clientModule) {
-      routeSpec.clientModule = fsRoute.clientModule;
-      routeSpec.hydration = fsRoute.hydration ?? {
-        strategy: "island",
-        priority: "visible",
-        preload: false,
-      };
-    }
-
-    // Layout 체인
-    if (fsRoute.layoutChain && fsRoute.layoutChain.length > 0) {
-      routeSpec.layoutChain = fsRoute.layoutChain;
-    }
-
-    // Loading UI
-    if (fsRoute.loadingModule) {
-      routeSpec.loadingModule = fsRoute.loadingModule;
-    }
-
-    // Error UI
-    if (fsRoute.errorModule) {
-      routeSpec.errorModule = fsRoute.errorModule;
-    }
+    const pageRoute: RouteSpec = {
+      ...base,
+      kind: "page" as const,
+      componentModule: fsRoute.componentModule ?? "",
+      ...(fsRoute.clientModule
+        ? {
+            clientModule: fsRoute.clientModule,
+            hydration: fsRoute.hydration ?? {
+              strategy: "island" as const,
+              priority: "visible" as const,
+              preload: false,
+            },
+          }
+        : {}),
+      ...(fsRoute.layoutChain && fsRoute.layoutChain.length > 0
+        ? { layoutChain: fsRoute.layoutChain }
+        : {}),
+      ...(fsRoute.loadingModule ? { loadingModule: fsRoute.loadingModule } : {}),
+      ...(fsRoute.errorModule ? { errorModule: fsRoute.errorModule } : {}),
+    };
+    return pageRoute;
   }
 
-  // API 라우트의 경우
-  if (fsRoute.kind === "api" && fsRoute.methods) {
-    routeSpec.methods = fsRoute.methods;
-  }
-
-  return routeSpec;
+  // API 라우트
+  const apiRoute: RouteSpec = {
+    ...base,
+    kind: "api" as const,
+    ...(fsRoute.methods ? { methods: fsRoute.methods } : {}),
+  };
+  return apiRoute;
 }
 
 /**

package/src/runtime/logger.test.ts

@@ -62,7 +62,7 @@ describe("logger", () => {
 
       log.onError(ctx, error);
 
-      expect(ctx.get("__mandu_logger_error")).toBe(error);
+      expect(ctx.get<Error>("__mandu_logger_error")).toBe(error);
     });
 
     test("afterHandle은 응답을 저장하고 반환", () => {
@@ -72,7 +72,7 @@ describe("logger", () => {
 
       const result = log.afterHandle(ctx, response);
 
-      expect(ctx.get("__mandu_logger_response")).toBe(response);
+      expect(ctx.get<Response>("__mandu_logger_response")).toBe(response);
       expect(result).toBe(response);
     });
   });
@@ -147,7 +147,7 @@ describe("logger", () => {
 
       log.onRequest(ctx);
 
-      expect(ctx.get("__mandu_logger_request_id")).toBe("custom-POST-123");
+      expect(ctx.get<string>("__mandu_logger_request_id")).toBe("custom-POST-123");
     });
   });
 

package/src/runtime/logger.ts

@@ -639,7 +639,7 @@ export function applyLogger(
   loggerInstance: ReturnType<typeof logger>
 ): void {
   lifecycle.onRequest.push({ fn: loggerInstance.onRequest, scope: "global" });
-  lifecycle.onError.push({ fn: loggerInstance.onError as any, scope: "global" });
+  lifecycle.onError.push({ fn: loggerInstance.onError as (ctx: ManduContext, error: Error) => void, scope: "global" });
   lifecycle.afterHandle.push({ fn: loggerInstance.afterHandle, scope: "global" });
   lifecycle.afterResponse.push({ fn: loggerInstance.afterResponse, scope: "global" });
 }

package/src/runtime/server.ts

@@ -1,8 +1,8 @@
 import type { Server } from "bun";
-import type { RoutesManifest, HydrationConfig } from "../spec/schema";
+import type { RoutesManifest, RouteSpec, HydrationConfig } from "../spec/schema";
 import type { BundleManifest } from "../bundler/types";
 import type { ManduFilling } from "../filling/filling";
-import { ManduContext } from "../filling/context";
+import { ManduContext, type CookieManager } from "../filling/context";
 import { Router } from "./router";
 import { renderSSR, renderStreamingResponse } from "./ssr";
 import { type ErrorFallbackProps } from "./boundary";
@@ -872,6 +872,7 @@ async function handleApiRoute(
 
 interface PageLoadResult {
   loaderData: unknown;
+  cookies?: CookieManager;
 }
 
 /**
@@ -888,6 +889,7 @@ async function loadPageData(
   // 1. PageHandler 방식 (신규 - filling 포함)
   const pageHandler = registry.pageHandlers.get(route.id);
   if (pageHandler) {
+    let cookies: CookieManager | undefined;
     try {
       const registration = await pageHandler();
       const component = registration.component as RouteComponent;
@@ -897,6 +899,9 @@ async function loadPageData(
       if (registration.filling?.hasLoader()) {
         const ctx = new ManduContext(req, params);
         loaderData = await registration.filling.executeLoader(ctx);
+        if (ctx.cookies.hasPendingCookies()) {
+          cookies = ctx.cookies;
+        }
       }
     } catch (error) {
       const pageError = createPageLoadErrorResponse(
@@ -908,7 +913,7 @@ async function loadPageData(
       return err(pageError);
     }
 
-    return ok({ loaderData });
+    return ok({ loaderData, cookies });
   }
 
   // 2. PageLoader 방식 (레거시 호환)
@@ -917,17 +922,24 @@ async function loadPageData(
     try {
       const module = await loader();
       const exported: unknown = module.default;
+      const exportedObj = exported as Record<string, unknown> | null;
       const component = typeof exported === "function"
         ? (exported as RouteComponent)
-        : (exported as any)?.component ?? exported;
+        : (exportedObj?.component ?? exported);
       registry.registerRouteComponent(route.id, component as RouteComponent);
 
       // filling이 있으면 loader 실행
-      const filling = typeof exported === "object" && exported !== null ? (exported as any)?.filling : null;
+      let cookies: CookieManager | undefined;
+      const filling = typeof exported === "object" && exported !== null ? (exportedObj as Record<string, unknown>)?.filling as ManduFilling | null : null;
       if (filling?.hasLoader?.()) {
         const ctx = new ManduContext(req, params);
         loaderData = await filling.executeLoader(ctx);
+        if (ctx.cookies.hasPendingCookies()) {
+          cookies = ctx.cookies;
+        }
       }
+
+      return ok({ loaderData, cookies });
     } catch (error) {
       const pageError = createPageLoadErrorResponse(
         route.id,
@@ -952,7 +964,8 @@ async function renderPageSSR(
   params: Record<string, string>,
   loaderData: unknown,
   url: string,
-  registry: ServerRegistry
+  registry: ServerRegistry,
+  cookies?: CookieManager
 ): Promise<Result<Response>> {
   const settings = registry.settings;
   const defaultAppCreator = createDefaultAppFactory(registry);
@@ -981,7 +994,7 @@ async function renderPageSSR(
       : settings.streaming;
 
     if (useStreaming) {
-      return ok(await renderStreamingResponse(app, {
+      const streamingResponse = await renderStreamingResponse(app, {
         title: `${route.id} - Mandu`,
         isDev: settings.isDev,
         hmrPort: settings.hmrPort,
@@ -1006,11 +1019,12 @@ async function renderPageSSR(
             });
           }
         },
-      }));
+      });
+      return ok(cookies ? cookies.applyToResponse(streamingResponse) : streamingResponse);
     }
 
     // 기존 renderToString 방식
-    return ok(renderSSR(app, {
+    const ssrResponse = renderSSR(app, {
       title: `${route.id} - Mandu`,
       isDev: settings.isDev,
       hmrPort: settings.hmrPort,
@@ -1021,7 +1035,8 @@ async function renderPageSSR(
       enableClientRouter: true,
       routePattern: route.pattern,
       cssPath: settings.cssPath,
-    }));
+    });
+    return ok(cookies ? cookies.applyToResponse(ssrResponse) : ssrResponse);
   } catch (error) {
     const ssrError = createSSRErrorResponse(
       route.id,
@@ -1051,21 +1066,22 @@ async function handlePageRoute(
     return loadResult;
   }
 
-  const { loaderData } = loadResult.value;
+  const { loaderData, cookies } = loadResult.value;
 
   // 2. Client-side Routing: 데이터만 반환 (JSON)
   if (url.searchParams.has("_data")) {
-    return ok(Response.json({
+    const jsonResponse = Response.json({
       routeId: route.id,
       pattern: route.pattern,
       params,
       loaderData: loaderData ?? null,
       timestamp: Date.now(),
-    }));
+    });
+    return ok(cookies ? cookies.applyToResponse(jsonResponse) : jsonResponse);
   }
 
   // 3. SSR 렌더링
-  return renderPageSSR(route, params, loaderData, req.url, registry);
+  return renderPageSSR(route, params, loaderData, req.url, registry, cookies);
 }
 
 // ---------- Main Request Dispatcher ----------
@@ -1127,18 +1143,19 @@ async function handleRequestInternal(
     return handlePageRoute(req, url, route, params, registry);
   }
 
-  // 4. 알 수 없는 라우트 종류
+  // 4. 알 수 없는 라우트 종류 — exhaustiveness check
+  const _exhaustive: never = route;
   return err({
     errorType: "FRAMEWORK_BUG",
     code: "MANDU_F003",
     httpStatus: 500,
-    message: `Unknown route kind: ${route.kind}`,
+    message: `Unknown route kind: ${(_exhaustive as RouteSpec).kind}`,
     summary: "알 수 없는 라우트 종류 - 프레임워크 버그",
     fix: {
       file: ".mandu/routes.manifest.json",
       suggestion: "라우트의 kind는 'api' 또는 'page'여야 합니다",
     },
-    route: { id: route.id, pattern: route.pattern },
+    route: { id: (_exhaustive as RouteSpec).id, pattern: (_exhaustive as RouteSpec).pattern },
     timestamp: new Date().toISOString(),
   });
 }

package/src/runtime/stable-selector.ts

@@ -11,8 +11,7 @@ function fnv1a64Hex(input: string): string {
 
 function getBuildSaltFallback(): string {
   try {
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    const salt = (typeof process !== "undefined" && (process as any)?.env?.MANDU_BUILD_SALT) as string | undefined;
+    const salt = (typeof process !== "undefined" && process.env?.MANDU_BUILD_SALT) as string | undefined;
     return salt ?? "dev";
   } catch {
     return "dev";

package/src/runtime/streaming-ssr.ts

@@ -244,6 +244,15 @@ function validateCriticalData(data: Record<string, unknown> | undefined, isDev:
 
 // ========== Streaming Warnings ==========
 
+/**
+ * Streaming 경고 상태 (module-level, globalThis as any 제거)
+ */
+const streamingWarnings = {
+  _warned: false,
+  markWarned() { this._warned = true; },
+  hasWarned() { return this._warned; },
+};
+
 /**
  * 프록시/버퍼링 관련 경고 (개발 모드)
  */
@@ -685,9 +694,9 @@ export async function renderToStream(
   validateCriticalData(criticalData, isDev);
 
   // 스트리밍 주의사항 경고 (첫 요청 시 1회만)
-  if (isDev && !(globalThis as any).__MANDU_STREAMING_WARNED__) {
+  if (isDev && !streamingWarnings.hasWarned()) {
     warnStreamingCaveats(isDev);
-    (globalThis as any).__MANDU_STREAMING_WARNED__ = true;
+    streamingWarnings.markWarned();
   }
 
   const encoder = new TextEncoder();

package/src/seo/index.ts

@@ -102,6 +102,11 @@ export type {
   JsonLd,
   JsonLdType,
 
+  // Template Literal Types
+  OGProperty,
+  TwitterProperty,
+  MetaProperty,
+
   // Google SEO 최적화
   GoogleMeta,
   FormatDetection,

package/src/seo/integration/ssr.ts

@@ -118,12 +118,12 @@ export function resolveSEOSync(staticMetadata: Metadata): SEOResult {
       resolvedTitle = { absolute: staticMetadata.title, template: null }
     } else if ('absolute' in staticMetadata.title) {
       resolvedTitle = {
-        absolute: staticMetadata.title.absolute,
+        absolute: staticMetadata.title.absolute ?? '',
         template: staticMetadata.title.template ?? null,
       }
     } else if ('default' in staticMetadata.title) {
       resolvedTitle = {
-        absolute: staticMetadata.title.default,
+        absolute: staticMetadata.title.default ?? '',
         template: staticMetadata.title.template ?? null,
       }
     }

package/src/seo/resolve/url.ts

@@ -27,6 +27,9 @@ export function normalizeMetadataBase(
 /**
  * 상대 URL을 절대 URL로 변환
  */
+export function resolveUrl(url: URL, metadataBase: URL | null): URL;
+export function resolveUrl(url: string | null | undefined, metadataBase: URL | null): URL | null;
+export function resolveUrl(url: string | URL | null | undefined, metadataBase: URL | null): URL | null;
 export function resolveUrl(
   url: string | URL | null | undefined,
   metadataBase: URL | null
@@ -69,6 +72,10 @@ export function resolveUrl(
 /**
  * URL을 문자열로 변환 (렌더링용)
  */
+export function urlToString(url: URL): string;
+export function urlToString(url: string): string;
+export function urlToString(url: null | undefined): null;
+export function urlToString(url: URL | string | null | undefined): string | null;
 export function urlToString(url: URL | string | null | undefined): string | null {
   if (!url) return null
   if (url instanceof URL) return url.href

package/src/seo/types.ts

@@ -223,6 +223,19 @@ export interface ResolvedVerification {
   other: Record<string, string[]> | null
 }
 
+// ============================================================================
+// Template Literal Types for Meta Properties
+// ============================================================================
+
+/** OpenGraph meta property name (og:title, og:description, etc.) */
+export type OGProperty = `og:${string}`;
+
+/** Twitter meta property name (twitter:card, twitter:site, etc.) */
+export type TwitterProperty = `twitter:${string}`;
+
+/** Union of well-known meta property prefixes plus arbitrary strings */
+export type MetaProperty = OGProperty | TwitterProperty | string;
+
 // ============================================================================
 // Open Graph Types
 // ============================================================================

package/src/spec/schema.ts

@@ -59,68 +59,34 @@ export type RouteKind = z.infer<typeof RouteKind>;
 export const SpecHttpMethod = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]);
 export type SpecHttpMethod = z.infer<typeof SpecHttpMethod>;
 
-export const RouteSpec = z
+// ---- 공통 필드 ----
+const RouteSpecBase = {
+  id: z.string().min(1, "id는 필수입니다"),
+  pattern: z.string().startsWith("/", "pattern은 /로 시작해야 합니다"),
+  module: z.string().min(1, "module 경로는 필수입니다"),
+  slotModule: z.string().optional(),
+  clientModule: z.string().optional(),
+  contractModule: z.string().optional(),
+  hydration: HydrationConfig.optional(),
+  loader: LoaderConfig.optional(),
+  streaming: z.boolean().optional(),
+};
+
+// ---- Page 라우트 ----
+export const PageRouteSpec = z
   .object({
-    id: z.string().min(1, "id는 필수입니다"),
-    pattern: z.string().startsWith("/", "pattern은 /로 시작해야 합니다"),
-    kind: RouteKind,
-
-    // HTTP 메서드 (API용)
+    ...RouteSpecBase,
+    kind: z.literal("page"),
+    // page 필수
+    componentModule: z.string().min(1, "kind가 'page'인 경우 componentModule은 필수입니다"),
+    // page 전용 optional
     methods: z.array(SpecHttpMethod).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(),
-
-    // Contract 모듈 (API 스키마 정의) [NEW]
-    contractModule: z.string().optional(),
-
-    // Hydration 설정 [NEW]
-    hydration: HydrationConfig.optional(),
-
-    // Loader 설정 [NEW]
-    loader: LoaderConfig.optional(),
-
-    // Streaming SSR 설정 [NEW v0.9.18]
-    // - true: 이 라우트에 Streaming SSR 적용
-    // - false: 이 라우트에 전통적 SSR 적용
-    // - undefined: 서버 설정 따름
-    streaming: z.boolean().optional(),
-
-    // Layout 체인 [NEW v0.9.33]
-    // - 페이지에 적용할 레이아웃 모듈 경로 배열
-    // - 배열 순서: 외부 → 내부 (Root → Parent → Child)
     layoutChain: z.array(z.string()).optional(),
-
-    // Loading UI 모듈 경로 [NEW v0.9.33]
     loadingModule: z.string().optional(),
-
-    // Error UI 모듈 경로 [NEW v0.9.33]
     errorModule: z.string().optional(),
   })
   .refine(
     (route) => {
-      if (route.kind === "page" && !route.componentModule) {
-        return false;
-      }
-      return true;
-    },
-    {
-      message: "kind가 'page'인 경우 componentModule은 필수입니다",
-      path: ["componentModule"],
-    }
-  )
-  .refine(
-    (route) => {
-      // clientModule이 있으면 hydration.strategy가 none이 아니어야 함
       if (route.clientModule && route.hydration?.strategy === "none") {
         return false;
       }
@@ -132,6 +98,46 @@ export const RouteSpec = z
     }
   );
 
+export type PageRouteSpec = z.infer<typeof PageRouteSpec>;
+
+// ---- API 라우트 ----
+export const ApiRouteSpec = z.object({
+  ...RouteSpecBase,
+  kind: z.literal("api"),
+  // api 전용
+  methods: z.array(SpecHttpMethod).optional(),
+  // page 전용 필드도 optional로 허용 (호환성)
+  componentModule: z.string().optional(),
+  layoutChain: z.array(z.string()).optional(),
+  loadingModule: z.string().optional(),
+  errorModule: z.string().optional(),
+});
+
+export type ApiRouteSpec = z.infer<typeof ApiRouteSpec>;
+
+// ---- discriminatedUnion ----
+export const RouteSpec = z.discriminatedUnion("kind", [
+  // PageRouteSpec에 .refine()이 적용되어 있으므로 내부 shape를 직접 사용
+  z.object({
+    ...RouteSpecBase,
+    kind: z.literal("page"),
+    componentModule: z.string().min(1, "kind가 'page'인 경우 componentModule은 필수입니다"),
+    methods: z.array(SpecHttpMethod).optional(),
+    layoutChain: z.array(z.string()).optional(),
+    loadingModule: z.string().optional(),
+    errorModule: z.string().optional(),
+  }),
+  z.object({
+    ...RouteSpecBase,
+    kind: z.literal("api"),
+    methods: z.array(SpecHttpMethod).optional(),
+    componentModule: z.string().optional(),
+    layoutChain: z.array(z.string()).optional(),
+    loadingModule: z.string().optional(),
+    errorModule: z.string().optional(),
+  }),
+]);
+
 export type RouteSpec = z.infer<typeof RouteSpec>;
 
 // ========== Manifest ==========
@@ -166,6 +172,28 @@ export const RoutesManifest = z
 
 export type RoutesManifest = z.infer<typeof RoutesManifest>;
 
+// ========== Assertion Functions ==========
+
+/**
+ * Asserts that the given route is a page route.
+ * After this call, TypeScript narrows the type to PageRouteSpec.
+ */
+export function assertPageRoute(route: RouteSpec): asserts route is PageRouteSpec {
+  if (route.kind !== "page") {
+    throw new Error(`Expected page route, got "${route.kind}" (id: ${route.id})`);
+  }
+}
+
+/**
+ * Asserts that the given route is an API route.
+ * After this call, TypeScript narrows the type to ApiRouteSpec.
+ */
+export function assertApiRoute(route: RouteSpec): asserts route is ApiRouteSpec {
+  if (route.kind !== "api") {
+    throw new Error(`Expected API route, got "${route.kind}" (id: ${route.id})`);
+  }
+}
+
 // ========== 유틸리티 함수 ==========
 
 /**

package/src/types/branded.ts

@@ -0,0 +1,56 @@
+/**
+ * Branded Types - Nominal typing for string identifiers
+ *
+ * Prevents accidental mixing of different ID types at compile time.
+ * All branded types are structurally compatible with plain strings at runtime.
+ *
+ * @example
+ * ```typescript
+ * const col = collectionId("blog");
+ * const entry = entryId("hello-world");
+ * // col and entry are both strings at runtime,
+ * // but TypeScript treats them as distinct types.
+ * ```
+ */
+
+declare const __brand: unique symbol;
+
+/**
+ * Brand utility type - creates nominal types from structural types.
+ * The brand exists only at the type level and has zero runtime cost.
+ */
+export type Brand<T, B extends string> = T & { readonly [__brand]: B };
+
+/** Branded string identifying a content collection */
+export type CollectionId = Brand<string, "CollectionId">;
+
+/** Branded string identifying a content entry within a collection */
+export type EntryId = Brand<string, "EntryId">;
+
+/** Branded string containing sanitized HTML (XSS-safe) */
+export type SafeHTML = Brand<string, "SafeHTML">;
+
+/** Branded string identifying a route in the manifest */
+export type RouteId = Brand<string, "RouteId">;
+
+// -- Constructor functions --
+
+/** Create a branded CollectionId from a plain string */
+export function collectionId(id: string): CollectionId {
+  return id as CollectionId;
+}
+
+/** Create a branded EntryId from a plain string */
+export function entryId(id: string): EntryId {
+  return id as EntryId;
+}
+
+/** Create a branded SafeHTML from a sanitized string */
+export function safeHTML(html: string): SafeHTML {
+  return html as SafeHTML;
+}
+
+/** Create a branded RouteId from a plain string */
+export function routeId(id: string): RouteId {
+  return id as RouteId;
+}

package/src/types/index.ts

@@ -0,0 +1 @@
+export * from "./branded";

package/src/utils/hasher.test.ts

@@ -146,25 +146,25 @@ describe("normalizeForHash", () => {
       ["a", 2],
       ["m", 3],
     ]);
-    const normalized = normalizeForHash({ data: map }) as any;
+    const normalized = normalizeForHash({ data: map }) as Record<string, Record<string, unknown>>;
 
     expect(normalized.data.__type__).toBe("Map");
-    expect(normalized.data.entries[0][0]).toBe("a"); // 정렬됨
+    expect((normalized.data.entries as string[][])[0][0]).toBe("a"); // 정렬됨
   });
 
   it("should handle Set as sorted array", () => {
     const set = new Set([3, 1, 2]);
-    const normalized = normalizeForHash({ data: set }) as any;
+    const normalized = normalizeForHash({ data: set }) as Record<string, Record<string, unknown>>;
 
     expect(normalized.data.__type__).toBe("Set");
     expect(normalized.data.items).toEqual([1, 2, 3]); // 정렬됨
   });
 
   it("should detect circular references", () => {
-    const obj: any = { a: 1 };
+    const obj: Record<string, unknown> = { a: 1 };
     obj.self = obj;
 
-    const normalized = normalizeForHash(obj) as any;
+    const normalized = normalizeForHash(obj) as Record<string, unknown>;
     expect(normalized.self).toBe("__circular__");
   });
 
@@ -184,7 +184,7 @@ describe("normalizeForHash", () => {
 
   it("should normalize Error objects", () => {
     const error = new TypeError("test error");
-    const normalized = normalizeForHash({ error }) as any;
+    const normalized = normalizeForHash({ error }) as Record<string, Record<string, unknown>>;
 
     expect(normalized.error.__type__).toBe("Error");
     expect(normalized.error.name).toBe("TypeError");