@mandujs/core 0.23.0 → 0.25.0

package/src/client/router.ts

@@ -15,6 +15,7 @@ import {
 } from "./window-state";
 import { LRUCache } from "../utils/lru-cache";
 import { LIMITS } from "../constants";
+import { registerCacheSize } from "../observability/metrics";
 
 // ========== Types ==========
 
@@ -158,6 +159,12 @@ interface CompiledPattern {
 
 const patternCache = new LRUCache<string, CompiledPattern>(LIMITS.ROUTER_PATTERN_CACHE);
 
+// Phase 17 — expose the cache size to the /_mandu/heap + /_mandu/metrics
+// endpoints so long-running processes can detect runaway growth.
+// The registration happens at module init — safe to call once per process
+// because `registerCacheSize` replaces any prior reporter under the same key.
+registerCacheSize("patternCache", () => patternCache.size);
+
 /**
  * 패턴을 정규식으로 컴파일
  */
@@ -435,40 +442,105 @@ export function getNavigationState(): NavigationState {
 // ========== Link Click Handler ==========
 
 /**
- * 링크 클릭 이벤트 핸들러 (이벤트 위임용)
+ * Issue #193 — Link click handler (event delegation).
+ *
+ * Mandu v0.22+ reversed the default from opt-in to opt-out SPA navigation.
+ * Every internal same-origin `<a href="/...">` click is intercepted and
+ * routed through the client-side router unless one of the explicit escape
+ * hatches fires:
+ *
+ *   - `data-no-spa`                 → per-link opt-out (always skip).
+ *   - `<a>` without `href`          → degenerate anchor, let the browser decide.
+ *   - `href="#fragment"`            → same-page anchor, browser handles scroll.
+ *   - `href="mailto:"` / `tel:` /   → non-http schemes the browser owns.
+ *     `javascript:` / `data:` / …
+ *   - `target="_blank" / "_top" /   → any target other than `_self` means the
+ *     "_parent" / "framename"         user wants a new browsing context.
+ *   - `download` attribute present  → file download, never a navigation.
+ *   - Modifier keys (Ctrl / Cmd /   → browser shortcut for new tab, bookmark,
+ *     Shift / Alt)                    save, or save-as.
+ *   - Non-left click                → middle-click opens a new tab, right-click
+ *                                     opens context menu.
+ *   - `event.defaultPrevented`      → another listener already handled it.
+ *   - Cross-origin href             → full document navigation required.
+ *
+ * The legacy opt-in attribute `data-mandu-link` still works for
+ * backward compatibility — it is simply a no-op under the new default
+ * because we already intercept by default. Teams that want the old
+ * opt-in behavior back can set `spa: false` in `mandu.config.ts`, which
+ * surfaces as `window.__MANDU_SPA__ === false` and re-introduces the
+ * requirement that `<a>` tags carry `data-mandu-link`.
  */
 function handleLinkClick(event: MouseEvent): void {
-  // 기본 동작 조건 체크
+  // Pre-filter: obvious browser-owned events.
   if (
     event.defaultPrevented ||
-    event.button !== 0 ||
-    event.metaKey ||
-    event.altKey ||
-    event.ctrlKey ||
-    event.shiftKey
+    event.button !== 0 ||  // middle-click / right-click — browser decides.
+    event.metaKey ||       // Cmd (macOS) — new tab.
+    event.altKey ||        // Alt — "save-as" in most browsers.
+    event.ctrlKey ||       // Ctrl (Windows/Linux) — new tab.
+    event.shiftKey         // Shift — new window / bookmark.
   ) {
     return;
   }
 
-  // 가장 가까운 앵커 태그 찾기
-  const anchor = (event.target as HTMLElement).closest("a");
+  // Find the closest anchor ancestor — users commonly nest `<span>` /
+  // `<img>` inside `<a>` and the event target is the inner element.
+  const anchor = (event.target as HTMLElement | null)?.closest("a");
   if (!anchor) return;
 
-  // data-mandu-link 속성이 있는 링크만 처리
-  if (!anchor.hasAttribute("data-mandu-link")) return;
+  // Escape hatch 1: explicit per-link opt-out always wins.
+  if (anchor.hasAttribute("data-no-spa")) return;
+
+  // Escape hatch 2: global config `spa: false` — reverts to the legacy
+  // opt-in behavior (only `data-mandu-link` intercepts). SSR injects
+  // `window.__MANDU_SPA__ = false` when the user sets `spa: false`.
+  const spaGlobal = (globalThis as { window?: { __MANDU_SPA__?: boolean } }).window?.__MANDU_SPA__;
+  if (spaGlobal === false && !anchor.hasAttribute("data-mandu-link")) return;
 
+  // `<a>` without `href` is a degenerate anchor — the browser will not
+  // navigate, but a listener somewhere might. Don't intercept.
   const href = anchor.getAttribute("href");
   if (!href) return;
 
-  // 외부 링크 체크
+  // Same-page fragment link — let the browser handle scroll / focus.
+  if (href.startsWith("#")) return;
+
+  // `target` other than `_self` (or absent) signals the user wants a
+  // new browsing context. `target="_blank"` is the common case but we
+  // also pass through `_top`, `_parent`, and framed targets.
+  const target = anchor.getAttribute("target");
+  if (target && target !== "_self") return;
+
+  // `download` attribute means the user wants to save the resource,
+  // never navigate to it.
+  if (anchor.hasAttribute("download")) return;
+
+  // URL parsing — catches both cross-origin and non-http schemes.
+  let url: URL;
   try {
-    const url = new URL(href, window.location.origin);
-    if (url.origin !== window.location.origin) return;
+    url = new URL(href, window.location.origin);
   } catch {
+    // Malformed href — let the browser produce its own error.
     return;
   }
 
-  // 기본 동작 방지 및 Client-side 네비게이션
+  // Only same-origin http(s) navigations are eligible for SPA handling.
+  // `mailto:`, `tel:`, `javascript:`, `data:`, `blob:`, chrome-extension,
+  // etc. all fail this check because `new URL("mailto:foo@bar").origin`
+  // is the string `"null"` (spec-defined), never equal to
+  // `window.location.origin`.
+  if (url.origin !== window.location.origin) return;
+
+  // Only intercept http / https schemes. Defense-in-depth against any
+  // exotic same-origin scheme we haven't considered (e.g. a custom
+  // protocol handler installed by a browser extension).
+  if (url.protocol !== "http:" && url.protocol !== "https:") return;
+
+  // All clear — prevent the default full-page navigation and hand off
+  // to the client-side router. `href` preserves the user's original
+  // string (relative paths, fragments, query strings) so the router
+  // can normalize as needed.
   event.preventDefault();
   navigate(href);
 }
@@ -828,3 +900,9 @@ if (typeof window !== "undefined") {
 // can exercise the schema-check path directly without round-tripping
 // through `window.__MANDU_ROUTER_REVALIDATE__`.
 export { applyHDRUpdate as _testOnly_applyHDRUpdate };
+
+// Issue #193: export the link-click handler for unit tests so we can
+// drive every exclusion case without installing a real DOM click
+// listener. Keeping this under a `_testOnly_` prefix to signal it is
+// not part of the public API.
+export { handleLinkClick as _testOnly_handleLinkClick };

package/src/client/use-fetch.ts

@@ -1,239 +1,243 @@
-/**
- * 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 };
-}
+/**
+ * Mandu useFetch Composable
+ * SSR 데이터 중복 방지 + pending/error 상태 + 클라이언트 캐시
+ */
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import { LRUCache } from "../utils/lru-cache";
+import { registerCacheSize } from "../observability/metrics";
+
+// ========== 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 엔트리) ==========
+//
+// Phase 17 — swapped hand-rolled Map for `LRUCache` so `get()` actually
+// promotes the entry to most-recently-used (was FIFO before). Size is
+// registered with the observability module for `/_mandu/heap` + the
+// Prometheus `mandu_cache_entries{cache="fetchCache"}` series.
+
+const MAX_CACHE_SIZE = 200;
+
+interface CacheEntry { data: unknown; timestamp: number; }
+const fetchCache = new LRUCache<string, CacheEntry>({ maxSize: MAX_CACHE_SIZE });
+registerCacheSize("fetchCache", () => fetchCache.size);
+
+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 {
+  // LRUCache handles eviction — we just set.
+  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 };
+}