@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

package/src/vite/utils/prerender-utils.ts

@@ -0,0 +1,268 @@
+import { createHash } from "node:crypto";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { resolve } from "node:path";
+
+import { escapeRegExp } from "../../regex-escape.js";
+import { encodePathRemainder } from "../../router/url-params.js";
+
+export function encodePathParam(value: unknown): string {
+  return encodePathRemainder(String(value), encodeURIComponent);
+}
+
+export function substituteRouteParams(
+  pattern: string,
+  params: Record<string, string>,
+  encode: (value: string) => string = encodeURIComponent,
+): string {
+  let result = pattern;
+  let hadOmittedOptional = false;
+
+  for (const [key, value] of Object.entries(params)) {
+    const escaped = escapeRegExp(key);
+    // Named catch-all `:key+` / `:key*` (issue #634). Like the runtime reverse,
+    // the value is multi-segment: encode each segment and keep the `/` separators
+    // (a whole-value encode would turn `a/b` into `a%2Fb`), and consume the
+    // trailing modifier so it does not leak into the URL. `*` (zero-or-more)
+    // absent collapses via the trailing cleanup below.
+    const catchAllRe = new RegExp(`:${escaped}[+*]`);
+    if (catchAllRe.test(result)) {
+      if (value === "") {
+        result = result.replace(catchAllRe, "");
+        hadOmittedOptional = true;
+      } else {
+        result = result.replace(catchAllRe, encodePathRemainder(value, encode));
+      }
+      continue;
+    }
+    if (value === "") {
+      result = result.replace(
+        new RegExp(`:${escaped}(\\([^)]*\\))?(?!\\?)`),
+        "",
+      );
+      result = result.replace(`*${key}`, "");
+    } else {
+      result = result.replace(
+        new RegExp(`:${escaped}(\\([^)]*\\))?\\??`),
+        encode(value),
+      );
+      result = result.replace(`*${key}`, encode(value));
+    }
+  }
+
+  result = result.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?\?/g, () => {
+    hadOmittedOptional = true;
+    return "";
+  });
+
+  if (hadOmittedOptional) {
+    const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+    result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
+    if (hadTrailingSlash && !result.endsWith("/")) result += "/";
+  }
+
+  return result;
+}
+
+export async function runWithConcurrency<T>(
+  items: T[],
+  concurrency: number,
+  fn: (item: T) => Promise<void>,
+): Promise<void> {
+  const limit = Math.max(1, Math.min(concurrency, items.length));
+  if (limit <= 1) {
+    for (const item of items) await fn(item);
+    return;
+  }
+  let nextIndex = 0;
+  // On first failure (the default prerender.onError: "fail" re-throws), stop
+  // scheduling new work so the remaining workers don't keep running full RSC
+  // renders before the build aborts. The first error is surfaced after all
+  // in-flight workers settle, preserving the throw-to-fail-build behavior.
+  let firstError: unknown;
+  let failed = false;
+  async function worker() {
+    while (nextIndex < items.length && !failed) {
+      const idx = nextIndex++;
+      try {
+        await fn(items[idx]);
+      } catch (err) {
+        if (!failed) {
+          failed = true;
+          firstError = err;
+        }
+        return;
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: limit }, () => worker()));
+  if (failed) throw firstError;
+}
+
+export function groupByConcurrency<T extends { concurrency: number }>(
+  entries: T[],
+): { concurrency: number; entries: T[] }[] {
+  const map = new Map<number, T[]>();
+  for (const entry of entries) {
+    const key = entry.concurrency;
+    let group = map.get(key);
+    if (!group) {
+      group = [];
+      map.set(key, group);
+    }
+    group.push(entry);
+  }
+  return Array.from(map.entries(), ([concurrency, items]) => ({
+    concurrency,
+    entries: items,
+  }));
+}
+
+export function notifyOnError(
+  registry: Map<string, any>,
+  error: unknown,
+  phase: "prerender" | "static",
+  routeKey?: string,
+  pathname?: string,
+  skipped?: boolean,
+): void {
+  for (const [, routerInstance] of registry) {
+    const onError = routerInstance.onError;
+    if (!onError) continue;
+
+    const errorObj = error instanceof Error ? error : new Error(String(error));
+    const syntheticUrl = new URL("http://prerender" + (pathname || "/"));
+    const context = {
+      error: errorObj,
+      phase,
+      request: new Request(syntheticUrl),
+      url: syntheticUrl,
+      pathname: syntheticUrl.pathname,
+      method: "GET",
+      routeKey,
+      metadata: skipped ? { skipped: true } : undefined,
+    };
+
+    try {
+      const result = onError(context);
+      if (result instanceof Promise) {
+        result.catch((cbErr: unknown) => {
+          console.error(`[Build.onError] Callback error:`, cbErr);
+        });
+      }
+    } catch (cbErr) {
+      console.error(`[Build.onError] Callback error:`, cbErr);
+    }
+    break; // Only notify the first router with onError
+  }
+}
+
+/**
+ * Resolve a thrown build-time render error into the prerender build's policy and
+ * log a per-entry line. A `Skip` (or any render error under `prerender.onError:
+ * "warn"`) logs and returns so the caller skips the entry; a render error under
+ * the default "fail" logs FAIL, notifies `onError`, and re-throws to fail the
+ * build. Shared by `expandPrerenderRoutes` (prerender) and `renderStaticHandlers`
+ * (static) so the Skip/warn/fail policy lives in one place. `label` is the padded
+ * URL / handler name for the log line; `elapsed` is the per-entry duration string.
+ */
+export function resolvePrerenderError(
+  registry: Map<string, any>,
+  error: any,
+  onError: "fail" | "warn",
+  label: string,
+  elapsed: string,
+  phase: "prerender" | "static",
+  routeKey?: string,
+  pathname?: string,
+): void {
+  const isSkip = error?.name === "Skip";
+  if (isSkip || onError === "warn") {
+    if (isSkip) {
+      console.log(`[rango]   SKIP ${label} (${elapsed}ms) - ${error.message}`);
+    } else {
+      console.warn(
+        `[rango]   WARN ${label} (${elapsed}ms) - render error, not pre-rendered (prerender.onError: "warn"): ${error.message}`,
+      );
+    }
+    notifyOnError(registry, error, phase, routeKey, pathname, true);
+    return;
+  }
+  console.error(`[rango]   FAIL ${label} (${elapsed}ms) - ${error.message}`);
+  notifyOnError(registry, error, phase, routeKey, pathname);
+  throw error;
+}
+
+function getStagedAssetDir(projectRoot: string): string {
+  return resolve(projectRoot, "node_modules/.rangojs-router-build/rsc-assets");
+}
+
+export function resetStagedBuildAssets(projectRoot: string): void {
+  rmSync(getStagedAssetDir(projectRoot), { recursive: true, force: true });
+}
+
+/**
+ * Write one content-hashed `export default <value>;` asset module into `dir`
+ * (created if needed) and return its file name. Identical payloads dedupe to
+ * one file (the hash is the content). Shared by the staged prerender/static
+ * flow (stageBuildAssetModule below) and the shell prerender phase, which
+ * writes directly into the final RSC assets dir — it runs after buildApp,
+ * past the staging/copy window.
+ */
+export function writeBuildAssetModule(
+  dir: string,
+  prefix: "__pr" | "__st" | "__ps",
+  exportValue: string,
+): string {
+  mkdirSync(dir, { recursive: true });
+
+  const contentHash = createHash("sha256")
+    .update(exportValue)
+    .digest("hex")
+    .slice(0, 8);
+  const fileName = `${prefix}-${contentHash}.js`;
+  const filePath = resolve(dir, fileName);
+
+  if (!existsSync(filePath)) {
+    writeFileSync(filePath, `export default ${exportValue};\n`);
+  }
+
+  return fileName;
+}
+
+export function stageBuildAssetModule(
+  projectRoot: string,
+  prefix: "__pr" | "__st",
+  exportValue: string,
+): string {
+  return writeBuildAssetModule(
+    getStagedAssetDir(projectRoot),
+    prefix,
+    exportValue,
+  );
+}
+
+export function copyStagedBuildAssets(
+  projectRoot: string,
+  fileNames: Iterable<string>,
+): number {
+  const stagedDir = getStagedAssetDir(projectRoot);
+  const distAssetsDir = resolve(projectRoot, "dist/rsc/assets");
+  mkdirSync(distAssetsDir, { recursive: true });
+
+  let totalBytes = 0;
+  for (const fileName of new Set(fileNames)) {
+    const stagedPath = resolve(stagedDir, fileName);
+    const distPath = resolve(distAssetsDir, fileName);
+    copyFileSync(stagedPath, distPath);
+    totalBytes += statSync(stagedPath).size;
+  }
+
+  return totalBytes;
+}

package/src/vite/utils/shared-utils.ts

@@ -0,0 +1,283 @@
+import type { Plugin, ResolvedConfig } from "vite";
+import * as Vite from "vite";
+import { isAbsolute, resolve } from "node:path";
+import { getPublishedPackageName } from "./package-resolution.js";
+import { performanceTracksOptimizeDepsPlugin } from "../plugins/performance-tracks.js";
+import {
+  VIRTUAL_ENTRY_BROWSER,
+  getVirtualEntrySSR,
+  getVirtualEntryRSC,
+  getVirtualEntryRSCHost,
+  getVirtualVersionContent,
+  VIRTUAL_IDS,
+} from "../plugins/virtual-entries.js";
+import type { HeadScriptsOption } from "../plugin-types.js";
+
+// Cloudflare preset: @cloudflare/vite-plugin sets optimizeDeps.entries (string
+// or array) on the rsc environment. Single source for both the discovery plugin
+// and the version injector so they target the same entry.
+export function resolveRscEntryFromConfig(
+  config: ResolvedConfig,
+): string | undefined {
+  const entries = (config.environments as any)?.["rsc"]?.optimizeDeps?.entries;
+  if (typeof entries === "string") return entries;
+  if (Array.isArray(entries) && entries.length > 0) return entries[0];
+  return undefined;
+}
+
+/**
+ * Rolldown plugin to provide the version virtual module during dependency
+ * optimization. Vite 8 optimizes deps with Rolldown (a Rollup-style plugin
+ * pipeline that is separate from the main plugin set), so this is a
+ * resolveId/load plugin under optimizeDeps.rolldownOptions. Any dep pulled into
+ * optimization that imports the version virtual module gets a "dev" stub here;
+ * the real VERSION is injected into runtime modules by the version plugin.
+ */
+const versionRolldownPlugin = {
+  name: "@rangojs/router-version",
+  resolveId(id: string): string | undefined {
+    if (id === VIRTUAL_IDS.version) return "\0" + VIRTUAL_IDS.version;
+    return undefined;
+  },
+  load(id: string): string | undefined {
+    if (id === "\0" + VIRTUAL_IDS.version) {
+      return getVirtualVersionContent("dev");
+    }
+    return undefined;
+  },
+};
+
+/**
+ * Shared Rolldown options for dependency optimization (Vite 8).
+ * Includes the version stub plugin and the performance-tracks RSDW patch.
+ */
+export const sharedRolldownOptions: {
+  plugins: any[];
+} = {
+  plugins: [versionRolldownPlugin, performanceTracksOptimizeDepsPlugin()],
+};
+
+/**
+ * Normalize an explicit `hostRouter` option into the specifier emitted as the
+ * host entry's `import ... from "<path>"`, and — for the forms that resolve
+ * unambiguously against the project root — verify the file exists (failing with
+ * a rango message instead of a downstream bundler "failed to resolve").
+ *
+ * Only a BARE specifier ("src/worker.rsc.tsx") that exists under the root is
+ * rewritten (to "./src/...") so it is not read as a package. A bare specifier
+ * that does NOT exist under the root is passed through VERBATIM: it may be a
+ * Vite alias ("@/worker.rsc.tsx"), an imports-map entry ("#app/worker"), or a
+ * workspace package the bundler resolves — rewriting or rejecting those was a
+ * regression (aliases worked before normalization existed). "./"/"../", a
+ * leading-slash (Vite root-relative), and a filesystem-absolute path are
+ * emitted unchanged — Vite resolves each. A leading-slash path and a
+ * filesystem-absolute path are indistinguishable on POSIX, so both are treated
+ * as "rooted": passed through WITHOUT an existence check (guessing between the
+ * two would wrongly reject a valid file — this was a regression the first time
+ * the check was added). Only the explicitly-relative forms, which resolve
+ * unambiguously against the root, fail fast with a rango message.
+ *
+ * `exists` is injected so the logic is unit-testable without a real filesystem.
+ */
+export function normalizeHostRouterEntry(
+  rawInput: string,
+  root: string,
+  exists: (absPath: string) => boolean,
+): string {
+  const raw = rawInput.replaceAll("\\", "/");
+  const isRelative = raw.startsWith("./") || raw.startsWith("../");
+  const isRooted = raw.startsWith("/") || isAbsolute(rawInput);
+  if (isRooted) return raw;
+  if (isRelative) {
+    if (!exists(resolve(root, raw))) {
+      throw new Error(
+        `[rango] hostRouter entry not found: "${rawInput}" (resolved under ` +
+          `${root}). Point it at your createHostRouter() module, e.g. ` +
+          `rango({ hostRouter: "./src/worker.rsc.tsx" }).`,
+      );
+    }
+    return raw;
+  }
+  // Bare specifier: an existing root-relative file gets the explicit "./";
+  // anything else (alias, imports-map, package) is the bundler's to resolve.
+  return exists(resolve(root, raw)) ? "./" + raw : raw;
+}
+
+/**
+ * Create a virtual modules plugin for default entry files.
+ * Provides virtual module content when entries use VIRTUAL_IDS (no custom entry configured).
+ */
+export function createVirtualEntriesPlugin(
+  entries: { client: string; ssr: string; rsc?: string },
+  routerPathRef?: { path?: string; kind?: "router" | "host" },
+  options?: { headScripts?: HeadScriptsOption },
+): Plugin {
+  // Build virtual modules map based on which entries use virtual IDs
+  const virtualModules: Record<string, string> = {};
+
+  if (entries.client === VIRTUAL_IDS.browser) {
+    virtualModules[VIRTUAL_IDS.browser] = VIRTUAL_ENTRY_BROWSER;
+  }
+  if (entries.ssr === VIRTUAL_IDS.ssr) {
+    virtualModules[VIRTUAL_IDS.ssr] = getVirtualEntrySSR(options?.headScripts);
+  }
+
+  // RSC entry is resolved lazily in load() because routerPath may be
+  // set after plugin creation (e.g. by the auto-discover config() hook).
+  // Track all known virtual IDs for resolveId (content is separate).
+  const knownIds = new Set(Object.keys(virtualModules));
+  if (entries.rsc === VIRTUAL_IDS.rsc) {
+    knownIds.add(VIRTUAL_IDS.rsc);
+  }
+
+  return {
+    name: "@rangojs/router:virtual-entries",
+    enforce: "pre",
+
+    resolveId(id) {
+      if (knownIds.has(id)) {
+        return "\0" + id;
+      }
+      // Handle if the id already has the null prefix (RSC plugin wrapper imports)
+      if (id.startsWith("\0") && knownIds.has(id.slice(1))) {
+        return id;
+      }
+      return null;
+    },
+
+    load(id) {
+      if (id.startsWith("\0virtual:rsc-router/")) {
+        const virtualId = id.slice(1);
+        if (virtualId in virtualModules) {
+          return virtualModules[virtualId];
+        }
+        // Lazy RSC entry: routerPath may have been set by a config() hook
+        if (virtualId === VIRTUAL_IDS.rsc && routerPathRef?.path) {
+          const raw = routerPathRef.path.startsWith(".")
+            ? "/" + routerPathRef.path.slice(2) // ./src/router.tsx -> /src/router.tsx
+            : routerPathRef.path;
+          // Normalize backslashes for Windows (path.join/slice preserve native separators)
+          const absoluteRouterPath = raw.replaceAll("\\", "/");
+          return routerPathRef.kind === "host"
+            ? getVirtualEntryRSCHost(absoluteRouterPath)
+            : getVirtualEntryRSC(absoluteRouterPath);
+        }
+      }
+      return null;
+    },
+  };
+}
+
+// Matches rollup's FILE_NAME_CONFLICT message and reports whether the colliding
+// file is a content-hashed asset, e.g.
+//   The emitted file "assets/index-DlGNrvnU.css" overwrites a previously ...
+//   The emitted file "assets/inter-latin-Dx4kXJAl.woff2" overwrites a ...
+// The match is UNANCHORED on purpose: by the time the warning reaches this user
+// onwarn handler, Vite's logger has wrapped rollup's raw message with an ANSI
+// color sequence and a "[CODE] " label, e.g.
+//   "[FILE_NAME_CONFLICT] The emitted file \"...\" overwrites ..."
+// A "^The emitted file" anchor sits behind that prefix and never matches; and
+// Vite also strips the JSON.stringify quotes rollup puts around the filename, so
+// the match is UNANCHORED and quote-OPTIONAL ("?...?"?). The non-whitespace
+// capture stops at the space before "overwrites" (Vite's unquoted display form)
+// or the closing quote (raw rollup form); either way it carries no ANSI.
+// A content-hashed name ends with a "-" separator + a Vite content hash. The
+// hash is a FIXED-LENGTH base64url run ([A-Za-z0-9_-], default 8), so it can
+// itself contain "-"/"_": it CANNOT be located by splitting on the last "-"
+// (that lands inside the hash whenever it carries a dash, e.g. "...-Cabi7G8-" ->
+// "" or "...-CkhJZR-_" -> "_", which let those conflicts leak). Instead take the
+// trailing HASH_LEN chars and require the "-" separator right before them. The
+// hash must hold an uppercase letter or digit (a real hash is never an
+// all-lowercase word), so stable names like "assets/manifest.json" or
+// "assets/loading-skeleton.css" still surface as potential genuine overwrites.
+function isContentHashedAssetConflict(message: string | undefined): boolean {
+  if (!message) return false;
+  const match =
+    /The emitted file "?([^"\s]+)"? overwrites a previously emitted file/.exec(
+      message,
+    );
+  if (!match) return false;
+  const fileName = match[1];
+  const base = fileName.slice(fileName.lastIndexOf("/") + 1);
+  const dot = base.lastIndexOf(".");
+  if (dot <= 0) return false;
+  const stem = base.slice(0, dot);
+  // HASH_LEN tracks Vite's default [hash] width; bump it if an app sets a custom
+  // assetFileNames hash length.
+  const HASH_LEN = 8;
+  if (stem.length < HASH_LEN + 1 || stem[stem.length - HASH_LEN - 1] !== "-") {
+    return false;
+  }
+  const hash = stem.slice(-HASH_LEN);
+  return /^[A-Za-z0-9_-]+$/.test(hash) && /[A-Z0-9]/.test(hash);
+}
+
+/**
+ * Suppress known harmless warnings: "use client" directives, sourcemap errors,
+ * mixed imports (expected for router internals), empty bundles, and content-hashed
+ * asset collisions from @vitejs/plugin-rsc copying RSC-env assets to the client bundle.
+ */
+export function onwarn(
+  warning: Vite.Rollup.RollupLog,
+  defaultHandler: (warning: Vite.Rollup.RollupLog) => void,
+): void {
+  if (
+    warning.code === "MODULE_LEVEL_DIRECTIVE" ||
+    warning.code === "SOURCEMAP_ERROR" ||
+    warning.code === "EMPTY_BUNDLE" ||
+    warning.code === "INEFFECTIVE_DYNAMIC_IMPORT"
+  ) {
+    return;
+  }
+  if (
+    warning.code === "FILE_NAME_CONFLICT" &&
+    isContentHashedAssetConflict(warning.message)
+  ) {
+    return;
+  }
+  if (warning.message?.includes("Sourcemap is likely to be incorrect")) {
+    return;
+  }
+  if (
+    warning.plugin === "vite:reporter" &&
+    warning.message?.includes(
+      "dynamic import will not move module into another chunk",
+    )
+  ) {
+    return;
+  }
+  defaultHandler(warning);
+}
+
+/**
+ * All of `browser/prefetch/` belongs to the eager "router" chunk — including
+ * the modules reachable only via loader.ts's dynamic import. #766 split those
+ * into a separate lazy chunk to trim the eager runtime (~2.3 KB gzip), but
+ * production's `defaultPrefetch: "viewport"` loads them on almost every page,
+ * so the split became a document -> router -> runtime request waterfall
+ * (measured 502 ms critical-path latency in a deployed worker). Same-chunk
+ * placement resolves the dynamic import without a network fetch
+ * (`Promise.resolve().then(...)` in the emitted chunk), and the merged chunk
+ * gzips smaller than the two chunks did apart. Do not re-split without new
+ * information (AGENTS.md, Bundle hygiene, rejected optimizations).
+ */
+export function getManualChunks(id: string): string | undefined {
+  const normalized = Vite.normalizePath(id);
+
+  if (
+    normalized.includes("node_modules/react/") ||
+    normalized.includes("node_modules/react-dom/") ||
+    normalized.includes("node_modules/react-server-dom-webpack/") ||
+    normalized.includes("node_modules/@vitejs/plugin-rsc/")
+  ) {
+    return "react";
+  }
+  const packageName = getPublishedPackageName();
+  if (
+    normalized.includes(`node_modules/${packageName}/`) ||
+    /\/packages\/(rsc-router|rangojs-router)\/(src|dist)\//.test(normalized)
+  ) {
+    return "router";
+  }
+  return undefined;
+}

package/CLAUDE.md

@@ -1,43 +0,0 @@
-# @rangojs/router
-
-Run `/rango` first to understand the API. Skills are in `node_modules/@rangojs/router/skills/`.
-
-## Tree-Structure-Critical Files (DO NOT MODIFY without understanding)
-
-The following files control the React tree structure. Changing the tree structure
-(element types, nesting depth, or keys at any position) between SSR, navigation,
-and action renders will cause React to remount components, destroying client state
-like `useActionState`, refs, and local state. This is extremely hard to debug.
-
-**Protected files:**
-
-- `src/segment-system.tsx` - `renderSegments()` builds the React tree from segments.
-  The `loading` property determines tree structure:
-  - `undefined` / `null` -> OutletProvider directly (no boundary)
-  - `false` -> LoaderBoundary + OutletProvider (boundary, no RouteContentWrapper)
-  - truthy (ReactNode) -> LoaderBoundary + OutletProvider + RouteContentWrapper
-
-- `src/route-content-wrapper.tsx` - `LoaderBoundary` and `RouteContentWrapper`.
-  These add structural depth (Suspense boundaries) to the React tree.
-
-- `src/browser/server-action-bridge.ts` - Merges server action segments with
-  cached segments. Must preserve cached `loading` values to prevent tree drift.
-
-- `src/browser/partial-update.ts` - Merges navigation segments with cached segments.
-
-**Rules:**
-
-1. Never change the conditional logic in `renderSegments()` that decides between
-   LoaderBoundary/RouteContentWrapper/OutletProvider without verifying all three
-   render paths (SSR, navigation, action) produce identical tree structures.
-
-2. Never add or remove wrapper elements (Suspense, div, Fragment) around segment
-   content without checking that the same wrappers exist in ALL render paths.
-
-3. When merging segments (action bridge, partial update), always preserve the
-   cached `loading` value if it differs from the server value. The server may
-   return different `loading` values based on `isSSR` context.
-
-4. Run `pnpm --filter @rangojs/router exec playwright test loader-behavior` after
-   any changes to these files. The skipSSR action tests specifically catch tree
-   structure regressions.

package/src/browser/lru-cache.ts

@@ -1,69 +0,0 @@
-/**
- * Simple LRU (Least Recently Used) cache implementation
- * Used for caching navigation segments to enable instant back/forward
- */
-export class LRUCache<K, V> {
-  private cache = new Map<K, V>();
-  private maxSize: number;
-
-  constructor(maxSize: number) {
-    this.maxSize = maxSize;
-  }
-
-  get(key: K): V | undefined {
-    if (!this.cache.has(key)) {
-      return undefined;
-    }
-
-    // Move to end (most recently used)
-    const value = this.cache.get(key)!;
-    this.cache.delete(key);
-    this.cache.set(key, value);
-    return value;
-  }
-
-  set(key: K, value: V): void {
-    // If key exists, delete it first to update position
-    if (this.cache.has(key)) {
-      this.cache.delete(key);
-    }
-
-    this.cache.set(key, value);
-
-    // Evict oldest entries if over capacity
-    while (this.cache.size > this.maxSize) {
-      const oldestKey = this.cache.keys().next().value;
-      if (oldestKey !== undefined) {
-        this.cache.delete(oldestKey);
-      }
-    }
-  }
-
-  has(key: K): boolean {
-    if (!this.cache.has(key)) {
-      return false;
-    }
-
-    // Move to end (most recently used) - same as get()
-    const value = this.cache.get(key)!;
-    this.cache.delete(key);
-    this.cache.set(key, value);
-    return true;
-  }
-
-  delete(key: K): boolean {
-    return this.cache.delete(key);
-  }
-
-  clear(): void {
-    this.cache.clear();
-  }
-
-  keys(): IterableIterator<K> {
-    return this.cache.keys();
-  }
-
-  get size(): number {
-    return this.cache.size;
-  }
-}