@mandujs/core 0.24.0 → 0.25.0

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 };
+}

package/src/config/mandu.ts

@@ -96,6 +96,29 @@ export interface ManduConfig {
    * Default: `true`.
    */
   prefetch?: boolean;
+  /**
+   * Issue #193 — Enable opt-out SPA navigation. When `true` (default)
+   * Mandu intercepts every internal same-origin `<a href="/...">` click
+   * and routes it through the client-side router, using the View
+   * Transitions API where available for a zero-flash experience. Plain
+   * `<a href="/about">` tags "just work" without a component wrapper.
+   *
+   * Escape hatches (the anchor always falls through to the browser):
+   *   - Per-link opt-out: `data-no-spa` on the `<a>` tag.
+   *   - External / cross-origin `href`.
+   *   - `mailto:` / `tel:` / `javascript:` / etc. (non-http schemes).
+   *   - `target="_blank"` (any `target` other than `_self`).
+   *   - `download` attribute.
+   *   - Modifier keys (Ctrl / Cmd / Shift / Alt) or middle/right-click.
+   *
+   * Global opt-out: set this field to `false` to revert to the legacy
+   * opt-in behavior, where only `<a data-mandu-link href="/...">` is
+   * intercepted. This is a breaking-change escape hatch for projects
+   * that relied on the pre-v0.22 default.
+   *
+   * Default: `true`.
+   */
+  spa?: boolean;
   server?: {
     port?: number;
     hostname?: string;
@@ -151,6 +174,30 @@ export interface ManduConfig {
      * a no-op in prod regardless of value.
      */
     devtools?: boolean;
+    /**
+     * Issue #196 — Auto-run `scripts/prebuild-*.ts` before `mandu dev`
+     * boots, and re-run them when files under `contentDir` change in
+     * watch mode.
+     *
+     *   - `true`      → always run discovered prebuild scripts, regardless
+     *                   of whether `content/` exists (useful for projects
+     *                   that ship generators that write outside `content/`).
+     *   - `false`     → never auto-run. User stays responsible for the
+     *                   chain (`bun scripts/prebuild-*.ts && mandu dev`).
+     *   - `undefined` → default. Auto-enabled iff the project has a
+     *                   `content/` directory OR at least one
+     *                   `scripts/prebuild-*.ts`. Silent no-op otherwise.
+     *
+     * See `@mandujs/core/content/prebuild` for the discovery + execution
+     * contract.
+     */
+    autoPrebuild?: boolean;
+    /**
+     * Issue #196 — Directory whose changes trigger a watch-mode
+     * prebuild re-run. Defaults to `"content"`. Ignored when
+     * `autoPrebuild === false`. Relative to project root.
+     */
+    contentDir?: string;
   };
   fsRoutes?: {
     routesDir?: string;
@@ -165,6 +212,23 @@ export interface ManduConfig {
   };
   /** Phase 12.1 — `mandu test` configuration block. */
   test?: TestConfig;
+  /**
+   * Phase 17 — observability endpoint toggles.
+   *
+   * Both fields default to `undefined`, which means "use mode default":
+   *   - dev mode → endpoint exposed
+   *   - prod mode → endpoint hidden unless `MANDU_DEBUG_HEAP=1`
+   *
+   * Explicit `true` / `false` overrides the mode default, so operators
+   * can opt-in to exposing metrics in prod (for a trusted internal
+   * network) or opt-out in dev (for a clean test harness).
+   */
+  observability?: {
+    /** `/_mandu/heap` JSON exposure toggle. */
+    heapEndpoint?: boolean;
+    /** `/_mandu/metrics` Prometheus text exposure toggle. */
+    metricsEndpoint?: boolean;
+  };
   plugins?: ManduPlugin[];
   hooks?: Partial<ManduHooks>;
 }

package/src/config/validate.ts

@@ -110,6 +110,18 @@ const DevConfigSchema = z
      * force on / off. Only applies in dev mode.
      */
     devtools: z.boolean().optional(),
+    /**
+     * Issue #196 — auto-run `scripts/prebuild-*.ts` before `mandu dev`.
+     * `undefined` = default (auto-enabled when content/ OR prebuild
+     * scripts exist); explicit `true` / `false` forces on / off.
+     */
+    autoPrebuild: z.boolean().optional(),
+    /**
+     * Issue #196 — directory whose changes trigger a watch-mode
+     * prebuild re-run. Non-empty to keep chokidar from trying to watch
+     * an empty pattern. Default `"content"`.
+     */
+    contentDir: z.string().min(1).default("content"),
   })
   .strict();
 
@@ -189,6 +201,20 @@ const TestConfigSchema = z
   })
   .strict();
 
+/**
+ * Phase 17 — observability endpoint config (strict).
+ *
+ * Shape mirrors `ServerOptions.observability`; both fields omit a
+ * default so the runtime can distinguish "not set" (use mode default)
+ * from "explicit false" (force off even in dev).
+ */
+const ObservabilityConfigSchema = z
+  .object({
+    heapEndpoint: z.boolean().optional(),
+    metricsEndpoint: z.boolean().optional(),
+  })
+  .strict();
+
 const AdapterConfigSchema = z.custom<ManduAdapter | undefined>(
   (value) =>
     value === undefined ||
@@ -237,6 +263,14 @@ export const ManduConfigSchema = z
      * Set `false` to suppress the ~500-byte prefetch IIFE.
      */
     prefetch: z.boolean().default(true),
+    /**
+     * Issue #193 — Opt-out SPA navigation. Default `true`.
+     * When `true`, plain `<a href="/...">` clicks are intercepted by
+     * the client-side router (per-link escape hatch: `data-no-spa`).
+     * Set `false` to revert to the legacy opt-in behavior, where only
+     * `<a data-mandu-link>` is intercepted.
+     */
+    spa: z.boolean().default(true),
     server: ServerConfigSchema.default({}),
     guard: GuardConfigSchema.default({}),
     build: BuildConfigSchema.default({}),
@@ -244,6 +278,7 @@ export const ManduConfigSchema = z
     fsRoutes: FsRoutesConfigSchema.default({}),
     seo: SeoConfigSchema.default({}),
     test: TestConfigSchema.default({}),
+    observability: ObservabilityConfigSchema.default({}),
     plugins: z.array(ManduPluginSchema).optional(),
     hooks: ManduHooksSchema.optional(),
   })