@mandujs/core 0.18.22 → 0.19.2

package/src/client/rpc.ts

@@ -0,0 +1,140 @@
+/**
+ * Mandu RPC Client
+ * Contract 정의에서 타입 안전한 API 클라이언트 생성
+ */
+
+// ========== Types ==========
+
+/** RPC 클라이언트 에러 */
+export class RpcError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly body: unknown
+  ) {
+    super(`API Error ${status}`);
+    this.name = "RpcError";
+  }
+}
+
+export interface RpcRequestOptions {
+  query?: Record<string, unknown>;
+  body?: unknown;
+  params?: Record<string, string>;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+}
+
+export interface RpcClientOptions {
+  /** API base URL (기본: 현재 origin) */
+  baseUrl?: string;
+  /** 공통 헤더 */
+  headers?: Record<string, string>;
+  /** 커스텀 fetch (테스트용) */
+  fetch?: typeof globalThis.fetch;
+}
+
+// ========== Implementation ==========
+
+/**
+ * Contract 기반 타입 안전 RPC 클라이언트 생성
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from "@mandujs/core/client";
+ * import type todoContract from "../spec/contracts/api-todos.contract";
+ *
+ * const api = createClient<typeof todoContract>("/api/todos");
+ *
+ * // 타입 추론 동작
+ * const { todos } = await api.get({ query: { page: 2 } });
+ * const { id } = await api.post({ body: { title: "New" } });
+ * ```
+ */
+export function createClient<TContract = unknown>(
+  path: string,
+  options?: RpcClientOptions
+): RpcMethods {
+  const baseFetch = options?.fetch ?? globalThis.fetch;
+  const baseUrl = options?.baseUrl ?? "";
+  const baseHeaders = options?.headers ?? {};
+
+  function makeRequest(method: string) {
+    return async (input?: RpcRequestOptions): Promise<unknown> => {
+      const url = new URL(`${baseUrl}${path}`, typeof window !== "undefined" ? window.location.origin : "http://localhost");
+
+      // URL 파라미터 치환
+      if (input?.params) {
+        let resolvedPath = url.pathname;
+        for (const [key, value] of Object.entries(input.params)) {
+          resolvedPath = resolvedPath.replace(`:${key}`, encodeURIComponent(value));
+        }
+        // 미해결 파라미터 검출
+        if (resolvedPath.includes(":")) {
+          throw new RpcError(0, `Unresolved path params in "${resolvedPath}". Check your params object.`);
+        }
+        url.pathname = resolvedPath;
+      }
+
+      // Query 파라미터
+      if (input?.query) {
+        for (const [key, value] of Object.entries(input.query)) {
+          if (value !== undefined && value !== null) {
+            url.searchParams.set(key, String(value));
+          }
+        }
+      }
+
+      const headers: Record<string, string> = {
+        ...baseHeaders,
+        ...input?.headers,
+        "Accept": "application/json",
+      };
+
+      const fetchOptions: RequestInit = {
+        method: method.toUpperCase(),
+        headers,
+        signal: input?.signal,
+      };
+
+      // Body (GET/HEAD 제외)
+      if (input?.body && method !== "GET" && method !== "HEAD") {
+        fetchOptions.body = JSON.stringify(input.body);
+        headers["Content-Type"] = "application/json";
+      }
+
+      const response = await baseFetch(url.toString(), fetchOptions);
+
+      if (!response.ok) {
+        let body: unknown;
+        try {
+          body = await response.json();
+        } catch {
+          body = await response.text().catch(() => null);
+        }
+        throw new RpcError(response.status, body);
+      }
+
+      const contentType = response.headers.get("content-type") ?? "";
+      if (contentType.includes("application/json")) {
+        return response.json();
+      }
+      return response.text();
+    };
+  }
+
+  return {
+    get: makeRequest("GET"),
+    post: makeRequest("POST"),
+    put: makeRequest("PUT"),
+    patch: makeRequest("PATCH"),
+    delete: makeRequest("DELETE"),
+  };
+}
+
+export interface RpcMethods {
+  get: (input?: RpcRequestOptions) => Promise<unknown>;
+  post: (input?: RpcRequestOptions) => Promise<unknown>;
+  put: (input?: RpcRequestOptions) => Promise<unknown>;
+  patch: (input?: RpcRequestOptions) => Promise<unknown>;
+  delete: (input?: RpcRequestOptions) => Promise<unknown>;
+}

package/src/client/runtime.ts

@@ -11,12 +11,13 @@ import { getHydratedRoots, getServerData as getGlobalServerData } from "./window
 /**
  * Hydration 상태 추적
  */
-export interface HydrationState {
-  total: number;
-  hydrated: number;
-  failed: number;
-  pending: Set<string>;
-}
+export interface HydrationState {
+  total: number;
+  hydrated: number;
+  failed: number;
+  recoverableErrors: number;
+  pending: Set<string>;
+}
 
 /**
  * Hydration 우선순위
@@ -34,14 +35,15 @@ export function getServerData<T = unknown>(islandId: string): T | undefined {
 /**
  * Hydration 상태 조회 (DOM 기반)
  */
-export function getHydrationState(): Readonly<HydrationState> {
-  if (typeof document === "undefined") {
-    return { total: 0, hydrated: 0, failed: 0, pending: new Set() };
-  }
-
-  const islands = document.querySelectorAll<HTMLElement>("[data-mandu-island]");
-  const hydrated = document.querySelectorAll<HTMLElement>("[data-mandu-hydrated]");
-  const failed = document.querySelectorAll<HTMLElement>("[data-mandu-error]");
+export function getHydrationState(): Readonly<HydrationState> {
+  if (typeof document === "undefined") {
+    return { total: 0, hydrated: 0, failed: 0, recoverableErrors: 0, pending: new Set() };
+  }
+
+  const islands = document.querySelectorAll<HTMLElement>("[data-mandu-island]");
+  const hydrated = document.querySelectorAll<HTMLElement>("[data-mandu-hydrated]");
+  const failed = document.querySelectorAll<HTMLElement>("[data-mandu-error]");
+  const recoverableErrors = document.querySelectorAll<HTMLElement>("[data-mandu-recoverable-error]");
 
   const pending = new Set<string>();
   islands.forEach((el) => {
@@ -51,13 +53,14 @@ export function getHydrationState(): Readonly<HydrationState> {
     }
   });
 
-  return {
-    total: islands.length,
-    hydrated: hydrated.length,
-    failed: failed.length,
-    pending,
-  };
-}
+  return {
+    total: islands.length,
+    hydrated: hydrated.length,
+    failed: failed.length,
+    recoverableErrors: recoverableErrors.length,
+    pending,
+  };
+}
 
 /**
  * 특정 Island unmount

package/src/client/use-fetch.ts

@@ -0,0 +1,239 @@
+/**
+ * Mandu useFetch Composable
+ * SSR 데이터 중복 방지 + pending/error 상태 + 클라이언트 캐시
+ */
+
+import { useState, useEffect, useCallback, useRef } from "react";
+
+// ========== Types ==========
+
+export interface UseFetchOptions<T = unknown> {
+  query?: Record<string, string | number>;
+  headers?: Record<string, string>;
+  method?: string;
+  body?: unknown;
+  /** SSR 데이터 있으면 클라이언트 fetch 생략 (기본: true) */
+  dedupe?: boolean;
+  /** SSR에서 전달된 초기 데이터 */
+  initialData?: T;
+  /** 캐시 유지 시간 (ms, 0이면 캐시 안 함) */
+  cacheTime?: number;
+  /** 자동 실행 여부 (기본: true) */
+  immediate?: boolean;
+  /** 응답 변환 함수 */
+  transform?: (data: unknown) => T;
+}
+
+export interface UseFetchReturn<T> {
+  data: T | null;
+  error: Error | null;
+  loading: boolean;
+  refresh: () => Promise<void>;
+  mutate: (updater: T | ((prev: T | null) => T)) => void;
+}
+
+// ========== Cache (LRU, 최대 200 엔트리) ==========
+
+const MAX_CACHE_SIZE = 200;
+
+interface CacheEntry { data: unknown; timestamp: number; }
+const fetchCache = new Map<string, CacheEntry>();
+
+function getCached(key: string, maxAge: number): unknown | undefined {
+  const entry = fetchCache.get(key);
+  if (!entry) return undefined;
+  if (Date.now() - entry.timestamp > maxAge) {
+    fetchCache.delete(key);
+    return undefined;
+  }
+  return entry.data;
+}
+
+function setCache(key: string, data: unknown): void {
+  // LRU: 오래된 것부터 제거
+  if (fetchCache.size >= MAX_CACHE_SIZE) {
+    const oldest = fetchCache.keys().next().value;
+    if (oldest !== undefined) fetchCache.delete(oldest);
+  }
+  fetchCache.set(key, { data, timestamp: Date.now() });
+}
+
+function stableStringify(value: unknown): string {
+  if (value === undefined || value === null) return "";
+  if (typeof value !== "object") return String(value);
+  // 키를 정렬하여 삽입 순서에 무관한 안정적 직렬화
+  const obj = value as Record<string, unknown>;
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(obj).sort()) {
+    sorted[key] = obj[key];
+  }
+  return JSON.stringify(sorted);
+}
+
+export function buildFetchCacheKey(
+  url: string,
+  options: {
+    queryKey?: string;
+    method?: string;
+    headersKey?: string;
+    bodyKey?: string;
+  } = {}
+): string {
+  return [
+    (options.method ?? "GET").toUpperCase(),
+    url,
+    options.queryKey ?? "",
+    options.headersKey ?? "",
+    options.bodyKey ?? "",
+  ].join("::");
+}
+
+function buildUrl(url: string, query?: Record<string, string | number>): string {
+  if (!query || Object.keys(query).length === 0) return url;
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined && value !== null) {
+      params.set(key, String(value));
+    }
+  }
+  return `${url}${url.includes("?") ? "&" : "?"}${params.toString()}`;
+}
+
+// ========== Hook ==========
+
+/**
+ * 데이터 페칭 훅 — SSR 중복 방지, 캐싱, pending/error 상태 관리
+ *
+ * @example
+ * ```tsx
+ * const { data, loading, error, refresh } = useFetch<Post[]>("/api/posts", {
+ *   query: { page: 1 },
+ *   cacheTime: 300_000,
+ * });
+ *
+ * const { data, mutate } = useFetch<Todo[]>("/api/todos");
+ * const addTodo = (todo: Todo) => mutate(prev => [...(prev ?? []), todo]);
+ * ```
+ */
+export function useFetch<T = unknown>(
+  url: string,
+  options?: UseFetchOptions<T>
+): UseFetchReturn<T> {
+  const {
+    query,
+    headers,
+    method = "GET",
+    body,
+    dedupe = true,
+    initialData,
+    cacheTime = 0,
+    immediate = true,
+    transform,
+  } = options ?? {};
+
+  // 안정적 직렬화 — useRef로 이전 값과 비교하여 변경 시에만 갱신
+  const queryStr = stableStringify(query);
+  const headersStr = stableStringify(headers);
+  const bodyStr = stableStringify(body);
+
+  const prevQueryRef = useRef(queryStr);
+  const prevHeadersRef = useRef(headersStr);
+  const prevBodyRef = useRef(bodyStr);
+
+  const stableQuery = prevQueryRef.current === queryStr ? prevQueryRef.current : (prevQueryRef.current = queryStr);
+  const stableHeaders = prevHeadersRef.current === headersStr ? prevHeadersRef.current : (prevHeadersRef.current = headersStr);
+  const stableBody = prevBodyRef.current === bodyStr ? prevBodyRef.current : (prevBodyRef.current = bodyStr);
+
+  const cacheKey = buildFetchCacheKey(url, {
+    queryKey: stableQuery,
+    method,
+    headersKey: stableHeaders,
+    bodyKey: stableBody,
+  });
+
+  // URL/query 변경 감지
+  const prevCacheKeyRef = useRef(cacheKey);
+
+  const [data, setData] = useState<T | null>(() => {
+    if (initialData !== undefined) return initialData;
+    if (cacheTime > 0) {
+      const cached = getCached(cacheKey, cacheTime);
+      if (cached !== undefined) return (transform ? transform(cached) : cached) as T;
+    }
+    return null;
+  });
+  const [error, setError] = useState<Error | null>(null);
+  const [loading, setLoading] = useState(!data && immediate);
+  const abortRef = useRef<AbortController | null>(null);
+
+  // URL/query 변경 시 data 초기화 (useEffect로 React 규칙 준수)
+  useEffect(() => {
+    if (prevCacheKeyRef.current === cacheKey) return;
+    prevCacheKeyRef.current = cacheKey;
+
+    if (cacheTime > 0) {
+      const cached = getCached(cacheKey, cacheTime);
+      if (cached !== undefined) {
+        setData((transform ? transform(cached) : cached) as T);
+        return;
+      }
+    }
+    setData(null);
+  }, [cacheKey, cacheTime, transform]);
+
+  const fetchData = useCallback(async () => {
+    abortRef.current?.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    setLoading(true);
+    setError(null);
+
+    try {
+      const fetchUrl = buildUrl(url, query);
+      const response = await fetch(fetchUrl, {
+        method,
+        headers: { "Accept": "application/json", ...headers },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      if (controller.signal.aborted) return;
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+
+      // Content-Type 확인 후 파싱
+      const contentType = response.headers.get("content-type") ?? "";
+      let result: unknown;
+      if (contentType.includes("application/json")) {
+        result = await response.json();
+      } else if (response.status === 204) {
+        result = null;
+      } else {
+        result = await response.text();
+      }
+
+      if (transform) result = transform(result);
+      setData(result as T);
+
+      if (cacheTime > 0) setCache(cacheKey, result);
+    } catch (e) {
+      if (e instanceof DOMException && e.name === "AbortError") return;
+      setError(e instanceof Error ? e : new Error(String(e)));
+    } finally {
+      if (!controller.signal.aborted) setLoading(false);
+    }
+  }, [url, method, stableQuery, stableHeaders, stableBody, cacheTime, cacheKey, transform]);
+
+  useEffect(() => {
+    if (!immediate) return;
+    if (data && dedupe) return;
+    fetchData();
+    return () => { abortRef.current?.abort(); };
+  }, [fetchData, immediate, dedupe]);
+
+  const mutate = useCallback((updater: T | ((prev: T | null) => T)) => {
+    setData(prev => typeof updater === "function" ? (updater as (prev: T | null) => T)(prev) : updater);
+  }, []);
+
+  return { data, error, loading, refresh: fetchData, mutate };
+}

package/src/client/use-head.ts

@@ -0,0 +1,197 @@
+/**
+ * Mandu useHead / useSeoMeta
+ * SSR + 클라이언트에서 <head> 태그를 선언적으로 관리
+ */
+
+import { useEffect, useRef } from "react";
+
+// ========== Types ==========
+
+export interface HeadTag {
+  tag: "title" | "meta" | "link" | "script" | "style";
+  attrs?: Record<string, string>;
+  children?: string;
+}
+
+export interface HeadConfig {
+  title?: string;
+  meta?: Array<{ name?: string; property?: string; content: string; httpEquiv?: string }>;
+  link?: Array<{ rel: string; href: string; [key: string]: string }>;
+}
+
+export interface SeoMetaConfig {
+  title?: string;
+  description?: string;
+  ogTitle?: string;
+  ogDescription?: string;
+  ogImage?: string;
+  ogUrl?: string;
+  ogType?: string;
+  twitterCard?: "summary" | "summary_large_image" | "app" | "player";
+  twitterTitle?: string;
+  twitterDescription?: string;
+  twitterImage?: string;
+  canonical?: string;
+  robots?: string;
+}
+
+// ========== SSR Head Collection ==========
+
+/** SSR 렌더링 중 수집된 head 태그 */
+let ssrHeadTags: string[] = [];
+
+/** SSR 렌더링 전 초기화 */
+export function resetSSRHead(): void {
+  ssrHeadTags = [];
+}
+
+/** SSR 렌더링 후 수집된 head 태그 반환 */
+export function getSSRHeadTags(): string {
+  return ssrHeadTags.join("\n");
+}
+
+function pushSSRTag(html: string): void {
+  if (typeof window === "undefined") {
+    ssrHeadTags.push(html);
+  }
+}
+
+// ========== Client-side DOM Management ==========
+
+const managedElements = new Set<Element>();
+
+function updateClientHead(tags: HeadTag[]): void {
+  if (typeof document === "undefined") return;
+
+  // 이전 managed 태그 제거
+  for (const el of managedElements) {
+    el.remove();
+  }
+  managedElements.clear();
+
+  // 새 태그 삽입
+  for (const tag of tags) {
+    if (tag.tag === "title") {
+      document.title = tag.children ?? "";
+      continue;
+    }
+
+    const el = document.createElement(tag.tag);
+    if (tag.attrs) {
+      for (const [key, value] of Object.entries(tag.attrs)) {
+        el.setAttribute(key, value);
+      }
+    }
+    if (tag.children) {
+      el.textContent = tag.children;
+    }
+    el.setAttribute("data-mandu-head", "");
+    document.head.appendChild(el);
+    managedElements.add(el);
+  }
+}
+
+// ========== Hooks ==========
+
+/**
+ * 선언적 <head> 태그 관리
+ *
+ * @example
+ * ```tsx
+ * useHead({
+ *   title: "My Page",
+ *   meta: [{ name: "description", content: "Page description" }],
+ *   link: [{ rel: "canonical", href: "https://example.com/page" }],
+ * });
+ * ```
+ */
+export function useHead(config: HeadConfig): void {
+  const tags: HeadTag[] = [];
+
+  if (config.title) {
+    tags.push({ tag: "title", children: config.title });
+    // SSR: title은 별도 처리 (renderToHTML의 title 옵션 대신)
+    pushSSRTag(`<title>${escapeHtml(config.title)}</title>`);
+  }
+
+  if (config.meta) {
+    for (const meta of config.meta) {
+      const attrs: Record<string, string> = { content: meta.content };
+      if (meta.name) attrs.name = meta.name;
+      if (meta.property) attrs.property = meta.property;
+      if (meta.httpEquiv) attrs["http-equiv"] = meta.httpEquiv;
+      tags.push({ tag: "meta", attrs });
+      pushSSRTag(`<meta ${Object.entries(attrs).map(([k, v]) => `${k}="${escapeHtml(v)}"`).join(" ")}>`);
+    }
+  }
+
+  if (config.link) {
+    for (const link of config.link) {
+      tags.push({ tag: "link", attrs: link });
+      pushSSRTag(`<link ${Object.entries(link).map(([k, v]) => `${k}="${escapeHtml(v)}"`).join(" ")}>`);
+    }
+  }
+
+  // 클라이언트: DOM 업데이트
+  const prevTagsRef = useRef<HeadTag[]>([]);
+
+  useEffect(() => {
+    prevTagsRef.current = tags;
+    updateClientHead(tags);
+
+    return () => {
+      // unmount 시 정리
+      for (const el of managedElements) {
+        el.remove();
+      }
+      managedElements.clear();
+    };
+  }, [JSON.stringify(config)]);
+}
+
+/**
+ * SEO 메타 태그 전용 — 간편 API
+ *
+ * @example
+ * ```tsx
+ * useSeoMeta({
+ *   title: "Blog Post Title",
+ *   description: "Post excerpt...",
+ *   ogTitle: "Blog Post Title",
+ *   ogImage: "/images/cover.jpg",
+ *   twitterCard: "summary_large_image",
+ * });
+ * ```
+ */
+export function useSeoMeta(config: SeoMetaConfig): void {
+  const headConfig: HeadConfig = {
+    meta: [],
+    link: [],
+  };
+
+  if (config.title) headConfig.title = config.title;
+  if (config.description) headConfig.meta!.push({ name: "description", content: config.description });
+  if (config.robots) headConfig.meta!.push({ name: "robots", content: config.robots });
+
+  // Open Graph
+  if (config.ogTitle) headConfig.meta!.push({ property: "og:title", content: config.ogTitle });
+  if (config.ogDescription) headConfig.meta!.push({ property: "og:description", content: config.ogDescription });
+  if (config.ogImage) headConfig.meta!.push({ property: "og:image", content: config.ogImage });
+  if (config.ogUrl) headConfig.meta!.push({ property: "og:url", content: config.ogUrl });
+  if (config.ogType) headConfig.meta!.push({ property: "og:type", content: config.ogType });
+
+  // Twitter
+  if (config.twitterCard) headConfig.meta!.push({ name: "twitter:card", content: config.twitterCard });
+  if (config.twitterTitle) headConfig.meta!.push({ name: "twitter:title", content: config.twitterTitle });
+  if (config.twitterDescription) headConfig.meta!.push({ name: "twitter:description", content: config.twitterDescription });
+  if (config.twitterImage) headConfig.meta!.push({ name: "twitter:image", content: config.twitterImage });
+
+  // Canonical
+  if (config.canonical) headConfig.link!.push({ rel: "canonical", href: config.canonical });
+
+  useHead(headConfig);
+}
+
+function escapeHtml(str: string): string {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}