@mandujs/core 0.54.32 → 0.55.0-beta.1

package/src/runtime/ppr.ts

@@ -1,74 +1,74 @@
-/**
- * Mandu Partial Prerendering (PPR)
- *
- * Caches the static HTML shell (header, sidebar, layout) at build/first-request time,
- * then injects fresh dynamic data (loader results) per request.
- *
- * Result: TTFB of a static page + freshness of a dynamic page.
- *
- * The shell is the expensive part (React render tree traversal).
- * Data injection is cheap (JSON serialization into a script tag).
- */
-
-import { escapeJsonForInlineScript } from "./escape";
-import { serializeProps } from "../client/serialize";
-
-/**
- * PPR shell marker injected at the end of cached HTML.
- * Everything before this marker is the static shell; everything after
- * (closing tags, data scripts) is regenerated per request.
- */
-export const PPR_SHELL_MARKER = "<!--mandu:ppr-split-->";
-
-/**
- * Strip the closing </body></html> and any trailing whitespace from
- * a full SSR HTML string, then append the shell marker.
- * The result is safe to cache and later concatenated with fresh data.
- */
-export function extractShellHtml(fullHtml: string): string {
-  // Remove trailing </body></html> (case-insensitive, whitespace-tolerant)
-  const trimmed = fullHtml.replace(/<\/body>\s*<\/html>\s*$/i, "");
-  return trimmed + PPR_SHELL_MARKER;
-}
-
-/**
- * Build a streaming Response that:
- *   1. Sends the cached shell immediately (near-zero TTFB)
- *   2. Appends a script tag with fresh loader data
- *   3. Closes with </body></html>
- */
-export function createPPRResponse(
-  shellHtml: string,
-  routeId: string,
-  loaderData: unknown,
-): Response {
-  const encoder = new TextEncoder();
-
-  // Build the data payload once; avoid doing work inside the stream callback
-  const serialized = serializeProps({ serverData: loaderData });
-  const escaped = escapeJsonForInlineScript(serialized);
-  const dataScript =
-    `<script>window.__MANDU_DATA__=window.__MANDU_DATA__||{};` +
-    `window.__MANDU_DATA__[${JSON.stringify(routeId)}]=${escaped}</script>`;
-
-  const stream = new ReadableStream<Uint8Array>({
-    start(controller) {
-      // (a) Cached shell -- everything up to the split marker (inclusive)
-      controller.enqueue(encoder.encode(shellHtml));
-      // (b) Fresh data script
-      controller.enqueue(encoder.encode(dataScript));
-      // (c) Close the document
-      controller.enqueue(encoder.encode("</body></html>"));
-      controller.close();
-    },
-  });
-
-  return new Response(stream, {
-    status: 200,
-    headers: {
-      "Content-Type": "text/html; charset=utf-8",
-      "X-Content-Type-Options": "nosniff",
-      "X-Mandu-PPR": "shell-hit",
-    },
-  });
-}
+/**
+ * Mandu Partial Prerendering (PPR)
+ *
+ * Caches the static HTML shell (header, sidebar, layout) at build/first-request time,
+ * then injects fresh dynamic data (loader results) per request.
+ *
+ * Result: TTFB of a static page + freshness of a dynamic page.
+ *
+ * The shell is the expensive part (React render tree traversal).
+ * Data injection is cheap (JSON serialization into a script tag).
+ */
+
+import { escapeJsonForInlineScript } from "./escape";
+import { serializeProps } from "../client/serialize";
+
+/**
+ * PPR shell marker injected at the end of cached HTML.
+ * Everything before this marker is the static shell; everything after
+ * (closing tags, data scripts) is regenerated per request.
+ */
+export const PPR_SHELL_MARKER = "<!--mandu:ppr-split-->";
+
+/**
+ * Strip the closing </body></html> and any trailing whitespace from
+ * a full SSR HTML string, then append the shell marker.
+ * The result is safe to cache and later concatenated with fresh data.
+ */
+export function extractShellHtml(fullHtml: string): string {
+  // Remove trailing </body></html> (case-insensitive, whitespace-tolerant)
+  const trimmed = fullHtml.replace(/<\/body>\s*<\/html>\s*$/i, "");
+  return trimmed + PPR_SHELL_MARKER;
+}
+
+/**
+ * Build a streaming Response that:
+ *   1. Sends the cached shell immediately (near-zero TTFB)
+ *   2. Appends a script tag with fresh loader data
+ *   3. Closes with </body></html>
+ */
+export function createPPRResponse(
+  shellHtml: string,
+  routeId: string,
+  loaderData: unknown,
+): Response {
+  const encoder = new TextEncoder();
+
+  // Build the data payload once; avoid doing work inside the stream callback
+  const serialized = serializeProps({ serverData: loaderData });
+  const escaped = escapeJsonForInlineScript(serialized);
+  const dataScript =
+    `<script>window.__MANDU_DATA__=window.__MANDU_DATA__||{};` +
+    `window.__MANDU_DATA__[${JSON.stringify(routeId)}]=${escaped}</script>`;
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      // (a) Cached shell -- everything up to the split marker (inclusive)
+      controller.enqueue(encoder.encode(shellHtml));
+      // (b) Fresh data script
+      controller.enqueue(encoder.encode(dataScript));
+      // (c) Close the document
+      controller.enqueue(encoder.encode("</body></html>"));
+      controller.close();
+    },
+  });
+
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/html; charset=utf-8",
+      "X-Content-Type-Options": "nosniff",
+      "X-Mandu-PPR": "shell-hit",
+    },
+  });
+}

package/src/runtime/rate-limit.ts

@@ -187,7 +187,7 @@ export function createRateLimitResponse(
  *
  * @example
  * ```typescript
- * import { createRateLimiter } from '@mandujs/core/runtime/server';
+ * import { createRateLimiter } from '@mandujs/core/compat/runtime/server';
  *
  * const limiter = createRateLimiter({ max: 5, windowMs: 60000 });
  *

package/src/runtime/redirect.ts

@@ -44,7 +44,7 @@ const DEFAULT_REDIRECT_STATUS: RedirectStatus = 302;
 const VALID_REDIRECT_STATUS = new Set<number>([301, 302, 303, 307, 308]);
 
 /** Internal brand — identifies Response objects minted by `redirect()`. */
-export const REDIRECT_BRAND: unique symbol = Symbol.for("@mandujs/core/redirect");
+export const REDIRECT_BRAND: unique symbol = Symbol.for("@mandujs/core/compat/redirect");
 
 /** Options for tuning a redirect response. */
 export interface RedirectOptions {

package/src/runtime/registry.ts

@@ -1,171 +1,171 @@
-/**
- * Runtime manifest registry.
- *
- * This module provides the **official** accessor for generated content at
- * runtime. User code must NEVER `import` anything under `.mandu/generated/`
- * or any path containing `/generated/` — the guard rule
- * `INVALID_GENERATED_IMPORT` catches that at build time.
- *
- * Why the indirection?
- *
- * - **Hot reload** — in dev, generated modules are rebuilt and re-imported.
- *   A direct ESM import caches the first version; the registry re-reads the
- *   current manifest on every access.
- * - **Determinism** — compiled binaries (`bun build --compile`) embed a
- *   fixed manifest. Direct imports would bypass the embedded copy and fail.
- * - **ESM cache invalidation** — see #184. Transitive generated modules get
- *   stuck on stale copies when hot-reload fires; the registry's `getManifest`
- *   is the single choke point that the bundled importer invalidates cleanly.
- *
- * @see https://mandujs.com/docs/architect/generated-access
- */
-import type { RoutesManifest, RouteSpec } from "../spec/schema";
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Generated artifact map
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Map of generated artifacts keyed by well-known names.
- *
- * Extend this interface (via module augmentation) in consumers that emit
- * their own generated artifacts — collections, resources, db schemas, etc.
- *
- * @example Module augmentation
- * ```ts
- * declare module "@mandujs/core/runtime" {
- *   interface GeneratedRegistry {
- *     collections: Record<string, CollectionIndex>;
- *   }
- * }
- * ```
- */
-export interface GeneratedRegistry {
-  /** Route manifest — the single source of truth for page/API routes. */
-  routes: RoutesManifest;
-}
-
-/** Union of well-known generated artifact keys. */
-export type GeneratedKey = keyof GeneratedRegistry;
-
-/** Typed accessor — narrows the return shape from the key. */
-export type GeneratedShape<K extends GeneratedKey> = GeneratedRegistry[K];
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Global registry state
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * The live manifest, populated by `registerManifest()` (typically driven by
- * `registerManifestHandlers()` from `@mandujs/cli`). Kept on `globalThis`
- * so reloading the core module in dev does not lose registration.
- */
-declare global {
-  // eslint-disable-next-line no-var
-  var __MANDU_MANIFEST__: Partial<GeneratedRegistry> | undefined;
-}
-
-function ensureGlobalSlot(): Partial<GeneratedRegistry> {
-  if (!globalThis.__MANDU_MANIFEST__) {
-    globalThis.__MANDU_MANIFEST__ = {};
-  }
-  return globalThis.__MANDU_MANIFEST__;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Public API
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Register a generated artifact under a well-known key.
- *
- * Called by the framework (typically from `registerManifestHandlers()` in
- * `@mandujs/cli`) during server boot. User code normally does not call this
- * directly — the only exception is tests that want to seed a manifest.
- *
- * @example Test setup
- * ```ts
- * import { registerManifest, clearGeneratedRegistry } from "@mandujs/core/runtime";
- *
- * beforeEach(() => clearGeneratedRegistry());
- * registerManifest("routes", { version: 1, routes: [] });
- * ```
- */
-export function registerManifest<K extends GeneratedKey>(
-  key: K,
-  value: GeneratedShape<K>,
-): void {
-  const slot = ensureGlobalSlot();
-  slot[key] = value;
-}
-
-/**
- * Read a generated artifact by key. Throws a helpful error if the manifest
- * has not been registered yet — this almost always means the server boot
- * skipped `registerManifestHandlers()` or the test forgot to seed fixtures.
- *
- * @example Reading the route manifest
- * ```ts
- * import { getGenerated } from "@mandujs/core/runtime";
- *
- * const manifest = getGenerated("routes");
- * for (const route of manifest.routes) {
- *   console.log(route.id, route.pattern);
- * }
- * ```
- *
- * @throws {Error} when the key has not been registered
- */
-export function getGenerated<K extends GeneratedKey>(key: K): GeneratedShape<K> {
-  const slot = globalThis.__MANDU_MANIFEST__;
-  if (!slot || !(key in slot) || slot[key] === undefined) {
-    throw new Error(
-      `[Mandu] Generated artifact "${String(key)}" not registered. ` +
-        `Call registerManifestHandlers() during server boot, or seed the ` +
-        `manifest with registerManifest("${String(key)}", …) in tests. ` +
-        `See https://mandujs.com/docs/architect/generated-access`,
-    );
-  }
-  return slot[key] as GeneratedShape<K>;
-}
-
-/**
- * Return the registered artifact, or `undefined` if absent. Prefer
- * `getGenerated()` for the common case — this variant exists for hot paths
- * where absence is not an error (e.g., optional collections).
- */
-export function tryGetGenerated<K extends GeneratedKey>(
-  key: K,
-): GeneratedShape<K> | undefined {
-  const slot = globalThis.__MANDU_MANIFEST__;
-  return slot?.[key] as GeneratedShape<K> | undefined;
-}
-
-/**
- * Return the full routes manifest. Thin wrapper around `getGenerated("routes")`
- * kept for call-site readability.
- *
- * @throws {Error} when no manifest has been registered yet
- */
-export function getManifest(): RoutesManifest {
-  return getGenerated("routes");
-}
-
-/**
- * Find a single route by its stable ID. Returns `undefined` if no match.
- * Use this instead of `manifest.routes.find(…)` at call sites that already
- * want the readability of a named helper.
- */
-export function getRouteById(id: string): RouteSpec | undefined {
-  const manifest = tryGetGenerated("routes");
-  if (!manifest) return undefined;
-  return manifest.routes.find((route) => route.id === id);
-}
-
-/**
- * Clear all registered artifacts. Test-only — production code should never
- * call this.
- */
-export function clearGeneratedRegistry(): void {
-  globalThis.__MANDU_MANIFEST__ = {};
-}
+/**
+ * Runtime manifest registry.
+ *
+ * This module provides the **official** accessor for generated content at
+ * runtime. User code must NEVER `import` anything under `.mandu/generated/`
+ * or any path containing `/generated/` — the guard rule
+ * `INVALID_GENERATED_IMPORT` catches that at build time.
+ *
+ * Why the indirection?
+ *
+ * - **Hot reload** — in dev, generated modules are rebuilt and re-imported.
+ *   A direct ESM import caches the first version; the registry re-reads the
+ *   current manifest on every access.
+ * - **Determinism** — compiled binaries (`bun build --compile`) embed a
+ *   fixed manifest. Direct imports would bypass the embedded copy and fail.
+ * - **ESM cache invalidation** — see #184. Transitive generated modules get
+ *   stuck on stale copies when hot-reload fires; the registry's `getManifest`
+ *   is the single choke point that the bundled importer invalidates cleanly.
+ *
+ * @see https://mandujs.com/docs/architect/generated-access
+ */
+import type { RoutesManifest, RouteSpec } from "../spec/schema";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Generated artifact map
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Map of generated artifacts keyed by well-known names.
+ *
+ * Extend this interface (via module augmentation) in consumers that emit
+ * their own generated artifacts — collections, resources, db schemas, etc.
+ *
+ * @example Module augmentation
+ * ```ts
+ * declare module "@mandujs/core/runtime" {
+ *   interface GeneratedRegistry {
+ *     collections: Record<string, CollectionIndex>;
+ *   }
+ * }
+ * ```
+ */
+export interface GeneratedRegistry {
+  /** Route manifest — the single source of truth for page/API routes. */
+  routes: RoutesManifest;
+}
+
+/** Union of well-known generated artifact keys. */
+export type GeneratedKey = keyof GeneratedRegistry;
+
+/** Typed accessor — narrows the return shape from the key. */
+export type GeneratedShape<K extends GeneratedKey> = GeneratedRegistry[K];
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Global registry state
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * The live manifest, populated by `registerManifest()` (typically driven by
+ * `registerManifestHandlers()` from `@mandujs/cli`). Kept on `globalThis`
+ * so reloading the core module in dev does not lose registration.
+ */
+declare global {
+  // eslint-disable-next-line no-var
+  var __MANDU_MANIFEST__: Partial<GeneratedRegistry> | undefined;
+}
+
+function ensureGlobalSlot(): Partial<GeneratedRegistry> {
+  if (!globalThis.__MANDU_MANIFEST__) {
+    globalThis.__MANDU_MANIFEST__ = {};
+  }
+  return globalThis.__MANDU_MANIFEST__;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Public API
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Register a generated artifact under a well-known key.
+ *
+ * Called by the framework (typically from `registerManifestHandlers()` in
+ * `@mandujs/cli`) during server boot. User code normally does not call this
+ * directly — the only exception is tests that want to seed a manifest.
+ *
+ * @example Test setup
+ * ```ts
+ * import { registerManifest, clearGeneratedRegistry } from "@mandujs/core/runtime";
+ *
+ * beforeEach(() => clearGeneratedRegistry());
+ * registerManifest("routes", { version: 1, routes: [] });
+ * ```
+ */
+export function registerManifest<K extends GeneratedKey>(
+  key: K,
+  value: GeneratedShape<K>,
+): void {
+  const slot = ensureGlobalSlot();
+  slot[key] = value;
+}
+
+/**
+ * Read a generated artifact by key. Throws a helpful error if the manifest
+ * has not been registered yet — this almost always means the server boot
+ * skipped `registerManifestHandlers()` or the test forgot to seed fixtures.
+ *
+ * @example Reading the route manifest
+ * ```ts
+ * import { getGenerated } from "@mandujs/core/runtime";
+ *
+ * const manifest = getGenerated("routes");
+ * for (const route of manifest.routes) {
+ *   console.log(route.id, route.pattern);
+ * }
+ * ```
+ *
+ * @throws {Error} when the key has not been registered
+ */
+export function getGenerated<K extends GeneratedKey>(key: K): GeneratedShape<K> {
+  const slot = globalThis.__MANDU_MANIFEST__;
+  if (!slot || !(key in slot) || slot[key] === undefined) {
+    throw new Error(
+      `[Mandu] Generated artifact "${String(key)}" not registered. ` +
+        `Call registerManifestHandlers() during server boot, or seed the ` +
+        `manifest with registerManifest("${String(key)}", …) in tests. ` +
+        `See https://mandujs.com/docs/architect/generated-access`,
+    );
+  }
+  return slot[key] as GeneratedShape<K>;
+}
+
+/**
+ * Return the registered artifact, or `undefined` if absent. Prefer
+ * `getGenerated()` for the common case — this variant exists for hot paths
+ * where absence is not an error (e.g., optional collections).
+ */
+export function tryGetGenerated<K extends GeneratedKey>(
+  key: K,
+): GeneratedShape<K> | undefined {
+  const slot = globalThis.__MANDU_MANIFEST__;
+  return slot?.[key] as GeneratedShape<K> | undefined;
+}
+
+/**
+ * Return the full routes manifest. Thin wrapper around `getGenerated("routes")`
+ * kept for call-site readability.
+ *
+ * @throws {Error} when no manifest has been registered yet
+ */
+export function getManifest(): RoutesManifest {
+  return getGenerated("routes");
+}
+
+/**
+ * Find a single route by its stable ID. Returns `undefined` if no match.
+ * Use this instead of `manifest.routes.find(…)` at call sites that already
+ * want the readability of a named helper.
+ */
+export function getRouteById(id: string): RouteSpec | undefined {
+  const manifest = tryGetGenerated("routes");
+  if (!manifest) return undefined;
+  return manifest.routes.find((route) => route.id === id);
+}
+
+/**
+ * Clear all registered artifacts. Test-only — production code should never
+ * call this.
+ */
+export function clearGeneratedRegistry(): void {
+  globalThis.__MANDU_MANIFEST__ = {};
+}

package/src/runtime/request-middleware.ts

@@ -1,31 +1,31 @@
-import {
-  compose as composeMiddleware,
-  type ComposedHandler,
-  type FinalHandler,
-} from "../middleware/compose";
-import type { Middleware } from "../middleware/define";
-
-export type { ComposedHandler, FinalHandler };
-
-export function buildRequestMiddlewareChain(
-  middleware: Middleware[] | undefined
-): ComposedHandler | undefined {
-  return middleware && middleware.length > 0
-    ? composeMiddleware(...middleware)
-    : undefined;
-}
-
-export interface RunRequestMiddlewareOptions {
-  req: Request;
-  middlewareChain: ComposedHandler | undefined;
-  finalHandler: FinalHandler;
-  skipMiddleware?: boolean;
-}
-
-export async function runRequestMiddleware(
-  options: RunRequestMiddlewareOptions
-): Promise<Response | undefined> {
-  const { req, middlewareChain, finalHandler, skipMiddleware = false } = options;
-  if (skipMiddleware || !middlewareChain) return undefined;
-  return middlewareChain(req, finalHandler);
-}
+import {
+  compose as composeMiddleware,
+  type ComposedHandler,
+  type FinalHandler,
+} from "../middleware/compose";
+import type { Middleware } from "../middleware/define";
+
+export type { ComposedHandler, FinalHandler };
+
+export function buildRequestMiddlewareChain(
+  middleware: Middleware[] | undefined
+): ComposedHandler | undefined {
+  return middleware && middleware.length > 0
+    ? composeMiddleware(...middleware)
+    : undefined;
+}
+
+export interface RunRequestMiddlewareOptions {
+  req: Request;
+  middlewareChain: ComposedHandler | undefined;
+  finalHandler: FinalHandler;
+  skipMiddleware?: boolean;
+}
+
+export async function runRequestMiddleware(
+  options: RunRequestMiddlewareOptions
+): Promise<Response | undefined> {
+  const { req, middlewareChain, finalHandler, skipMiddleware = false } = options;
+  if (skipMiddleware || !middlewareChain) return undefined;
+  return middlewareChain(req, finalHandler);
+}

package/src/runtime/router.test.ts

@@ -157,10 +157,10 @@ describe("Wildcard Matching", () => {
 
     const result = router.match("/docs");
 
-    expect(result).not.toBeNull();
-    expect(result!.route.id).toBe("docs");
-    expect(result!.params).toEqual({ path: "" });
-  });
+    expect(result).not.toBeNull();
+    expect(result!.route.id).toBe("docs");
+    expect(result!.params).toEqual({ path: "" });
+  });
 
   test("optional wildcard matches with remaining path", () => {
     const router = createRouter([

package/src/runtime/router.ts

@@ -415,10 +415,10 @@ export class Router {
             route,
           };
 
-          // Optional wildcard base paths are matched from wildcardConfig so
-          // the named wildcard param is still materialized as an empty string.
-          return;
-        }
+          // Optional wildcard base paths are matched from wildcardConfig so
+          // the named wildcard param is still materialized as an empty string.
+          return;
+        }
 
         // Regular parameter: :param
         const paramName = seg.slice(1);
@@ -526,12 +526,12 @@ export class Router {
       if (node.wildcardConfig.optional) {
         if (this.debug) {
           console.log(`[Router] Optional wildcard match: ${node.wildcardConfig.route.id} with empty path`);
-        }
-        return {
-          route: node.wildcardConfig.route,
-          params: { ...params, [node.wildcardConfig.name]: "" },
-        };
-      }
+        }
+        return {
+          route: node.wildcardConfig.route,
+          params: { ...params, [node.wildcardConfig.name]: "" },
+        };
+      }
       // Non-optional wildcard: /files/:path* does NOT match /files
       if (this.debug) {
         console.log(`[Router] Wildcard policy: ${pathname} does not match non-optional wildcard`);