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

package/src/search-params.ts

@@ -0,0 +1,235 @@
+/**
+ * Search parameter schema types and runtime utilities.
+ *
+ * Provides a lightweight schema system for typed query parameters.
+ * When a route defines a `search` schema, ctx.search provides a typed
+ * object with parsed values. ctx.searchParams always remains a standard
+ * URLSearchParams instance.
+ */
+
+import { encodeKV } from "./encode-kv.js";
+
+/**
+ * Decimal-number grammar for `"number"` search params: optional sign, digits
+ * with optional fraction, optional exponent. Deliberately excludes hex (`0x`),
+ * `Infinity`, and empty/whitespace so `Number()`'s lenient coercions
+ * (`Number("")===0`, `Number("0x10")===16`, `Number("Infinity")===Infinity`)
+ * do not slip non-decimal values into typed search.
+ */
+const DECIMAL_NUMBER_RE = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
+
+/** Supported scalar types for search params (append ? for optional). */
+export type SearchSchemaValue =
+  | "string"
+  | "number"
+  | "boolean"
+  | "string?"
+  | "number?"
+  | "boolean?";
+
+/** A search schema maps param names to their type descriptors. */
+export type SearchSchema = Record<string, SearchSchemaValue>;
+
+/** Strip trailing `?` from a schema value to get the base type. */
+type BaseType<T extends string> = T extends `${infer B}?` ? B : T;
+
+/** Map a base type string to its TypeScript type. */
+type ResolveBaseType<T extends string> = T extends "string"
+  ? string
+  : T extends "number"
+    ? number
+    : T extends "boolean"
+      ? boolean
+      : never;
+
+/** Keys whose schema value does NOT end with `?`. */
+type RequiredKeys<T extends SearchSchema> = {
+  [K in keyof T]: T[K] extends `${string}?` ? never : K;
+}[keyof T];
+
+/** Keys whose schema value ends with `?`. */
+type OptionalKeys<T extends SearchSchema> = {
+  [K in keyof T]: T[K] extends `${string}?` ? K : never;
+}[keyof T];
+
+/** Flatten an intersection type into a single object type. */
+type Simplify<T> = { [K in keyof T]: T[K] };
+
+/**
+ * Resolve a SearchSchema to its typed object.
+ *
+ * Both required and optional params resolve to `T | undefined` at the handler
+ * level. The required/optional distinction is a consumer-facing contract
+ * (e.g., for href() and reverse() autocomplete) — it tells callers which
+ * params the route expects, but the handler must still check for undefined
+ * since the framework cannot trust the client to send all required params.
+ *
+ * @example
+ * type S = { q: "string"; page: "number?"; sort: "string?" };
+ * type R = ResolveSearchSchema<S>;
+ * // { q: string | undefined; page?: number; sort?: string }
+ */
+export type ResolveSearchSchema<T extends SearchSchema> = Simplify<
+  {
+    [K in RequiredKeys<T> & string]:
+      | ResolveBaseType<BaseType<T[K]>>
+      | undefined;
+  } & {
+    [K in OptionalKeys<T> & string]?: ResolveBaseType<BaseType<T[K]>>;
+  }
+>;
+
+// ============================================================================
+// Route-Level Type Extraction
+// ============================================================================
+
+/** Resolve the global route map from RegisteredRoutes or GeneratedRouteMap. */
+type GlobalRouteMap = keyof Rango.RegisteredRoutes extends never
+  ? keyof Rango.GeneratedRouteMap extends never
+    ? Record<string, string>
+    : Rango.GeneratedRouteMap
+  : Rango.RegisteredRoutes;
+
+/**
+ * Extract the resolved search params type for a named route.
+ * Looks up the search schema from the route map and resolves it.
+ *
+ * @example
+ * ```typescript
+ * // Given: path("/search", handler, { name: "search", search: { q: "string", page: "number?" } })
+ * type Params = RouteSearchParams<"search">;
+ * // { q: string; page?: number }
+ * ```
+ */
+export type RouteSearchParams<TName extends string, TRouteMap = never> = [
+  TRouteMap,
+] extends [never]
+  ? ExtractAndResolveSearch<GlobalRouteMap, TName>
+  : ExtractAndResolveSearch<TRouteMap, TName>;
+
+type ExtractAndResolveSearch<TRouteMap, TName> = TName extends keyof TRouteMap
+  ? TRouteMap[TName] extends { readonly search: infer S extends SearchSchema }
+    ? ResolveSearchSchema<S>
+    : {}
+  : {};
+
+/**
+ * Extract the route params type for a named route.
+ * Looks up the path pattern from the route map and extracts params.
+ *
+ * @example
+ * ```typescript
+ * // Given: path("/blog/:slug", handler, { name: "blogPost" })
+ * type Params = RouteParams<"blogPost">;
+ * // { slug: string }
+ * ```
+ */
+export type RouteParams<TName extends string, TRouteMap = never> = [
+  TRouteMap,
+] extends [never]
+  ? ExtractRouteParamsFromMap<GlobalRouteMap, TName>
+  : ExtractRouteParamsFromMap<TRouteMap, TName>;
+
+type ExtractRouteParamsFromMap<TRouteMap, TName> = TName extends keyof TRouteMap
+  ? TRouteMap[TName] extends string
+    ? ExtractParamsFromPattern<TRouteMap[TName]>
+    : TRouteMap[TName] extends { readonly path: infer P extends string }
+      ? ExtractParamsFromPattern<P>
+      : {}
+  : {};
+
+/** Parse "a|b|c" into "a" | "b" | "c" */
+type ParseConstraint<T extends string> =
+  T extends `${infer First}|${infer Rest}` ? First | ParseConstraint<Rest> : T;
+
+/** Minimal inline param extraction (avoids importing from types.ts to prevent circular deps). */
+type ExtractParamsFromPattern<T extends string> =
+  T extends `${string}:${infer Param}/${infer Rest}`
+    ? Param extends `${infer Name}(${infer C})?`
+      ? {
+          [K in Name]?: ParseConstraint<C>;
+        } & ExtractParamsFromPattern<`/${Rest}`>
+      : Param extends `${infer Name}(${infer C})`
+        ? {
+            [K in Name]: ParseConstraint<C>;
+          } & ExtractParamsFromPattern<`/${Rest}`>
+        : Param extends `${infer Name}?`
+          ? { [K in Name]?: string } & ExtractParamsFromPattern<`/${Rest}`>
+          : { [K in Param]: string } & ExtractParamsFromPattern<`/${Rest}`>
+    : T extends `${string}:${infer Param}`
+      ? Param extends `${infer Name}(${infer C})?`
+        ? { [K in Name]?: ParseConstraint<C> }
+        : Param extends `${infer Name}(${infer C})`
+          ? { [K in Name]: ParseConstraint<C> }
+          : Param extends `${infer Name}?`
+            ? { [K in Name]?: string }
+            : { [K in Param]: string }
+      : {};
+
+/**
+ * Parse URLSearchParams into a typed object using the given schema.
+ *
+ * - `"string"` / `"string?"` - kept as-is
+ * - `"number"` / `"number?"` - parsed as a finite decimal number. Accepts an
+ *   optional sign, digits with optional fraction, and optional exponent
+ *   (e.g. `42`, `-3.5`, `1e3`). Empty/whitespace-only, non-decimal forms
+ *   (`0x10`), and non-finite (`Infinity`) are treated as missing (omitted),
+ *   NOT coerced to `0`/`16`/`Infinity`.
+ * - `"boolean"` / `"boolean?"` - `"true"` / `"1"` -> true, `"false"` / `"0"` / `""` -> false
+ *
+ * Missing params (both required and optional) are omitted from the result
+ * (undefined). The required/optional distinction is a consumer-facing contract
+ * only — the handler must check for undefined.
+ */
+export function parseSearchParams<T extends SearchSchema>(
+  searchParams: URLSearchParams,
+  schema: T,
+): ResolveSearchSchema<T> {
+  const result: Record<string, unknown> = {};
+
+  for (const [key, descriptor] of Object.entries(schema)) {
+    const isOptional = descriptor.endsWith("?");
+    const baseType = isOptional ? descriptor.slice(0, -1) : descriptor;
+    const raw = searchParams.get(key);
+
+    if (raw === null) {
+      // Missing params are omitted (undefined) regardless of required/optional
+      continue;
+    }
+
+    if (baseType === "string") {
+      result[key] = raw;
+    } else if (baseType === "number") {
+      // Trim, then require a valid decimal numeral and a finite result.
+      // Empty/whitespace, hex (0x10), and Infinity are treated as missing
+      // (omitted) — not coerced to 0/16/Infinity by Number()'s lenient rules.
+      const trimmed = raw.trim();
+      if (trimmed !== "" && DECIMAL_NUMBER_RE.test(trimmed)) {
+        const num = Number(trimmed);
+        if (Number.isFinite(num)) {
+          result[key] = num;
+        }
+      }
+      // Anything else treated as missing (undefined)
+    } else if (baseType === "boolean") {
+      result[key] = raw === "true" || raw === "1";
+    }
+  }
+
+  return result as ResolveSearchSchema<T>;
+}
+
+/**
+ * Serialize a typed search params object to a query string (without leading `?`).
+ * Skips `undefined` and `null` values. Preserves insertion order (no sort).
+ */
+export function serializeSearchParams(params: Record<string, unknown>): string {
+  // Pre-filter null/undefined and coerce values to strings here so encodeKV
+  // (which never inspects values) reproduces this call site's exact output.
+  const pairs: [string, string][] = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null) continue;
+    pairs.push([key, String(value)]);
+  }
+  return encodeKV(pairs);
+}

package/src/segment-content-promise.ts

@@ -0,0 +1,67 @@
+import type { ReactNode } from "react";
+
+/**
+ * Stable Promise wrappers keyed on the component itself. Objects (React
+ * elements, functions, lazy payloads) land in a WeakMap so entries GC when
+ * the underlying component is released; primitives (string, number, boolean,
+ * null) land in a Map so memoization still applies to text-/null-backed
+ * segments like those in partial-update flows. Keeping this cache outside
+ * the segment eliminates preservation fields on ResolvedSegment — it survives
+ * reconciliation naturally because the component ref is what's stable.
+ *
+ * Browser-only. On the server each SSR render needs a fresh pending promise
+ * so Suspense can emit the loading fallback HTML before content streams. A
+ * shared already-resolved promise has `.status === "fulfilled"` attached by
+ * React on its first observation — subsequent `use()` calls return
+ * synchronously without suspending, so the Suspense fallback never makes it
+ * into the initial HTML. Route-definition components share refs across
+ * requests, so a global cache would leak tracked state between renders.
+ */
+const IS_BROWSER = typeof window !== "undefined";
+const objectContentCache = IS_BROWSER
+  ? new WeakMap<object, Promise<ReactNode>>()
+  : null;
+const primitiveContentCache = IS_BROWSER
+  ? new Map<unknown, Promise<ReactNode>>()
+  : null;
+
+/**
+ * Return a stable Promise wrapping `component`, memoized on the component ref.
+ *
+ * A fresh `Promise.resolve(component)` each render would suspend for one
+ * microtask and briefly commit the loading fallback inside Suspender — the
+ * intercept / parallel-slot flicker this indirection prevents. Reusing the
+ * same Promise ref keeps React's `use()` in "known fulfilled" state after
+ * the first observation.
+ *
+ * @internal
+ */
+export function getMemoizedContentPromise(
+  component: ReactNode,
+): Promise<ReactNode> {
+  if (component instanceof Promise) {
+    return component as Promise<ReactNode>;
+  }
+
+  if (!objectContentCache || !primitiveContentCache) {
+    return Promise.resolve(component);
+  }
+
+  if (component !== null && typeof component === "object") {
+    const cached = objectContentCache.get(component);
+    if (cached) {
+      return cached;
+    }
+    const promise = Promise.resolve(component);
+    objectContentCache.set(component, promise);
+    return promise;
+  }
+
+  const cached = primitiveContentCache.get(component);
+  if (cached) {
+    return cached;
+  }
+  const promise = Promise.resolve(component);
+  primitiveContentCache.set(component, promise);
+  return promise;
+}

package/src/segment-fragments.ts

@@ -0,0 +1,165 @@
+/**
+ * Segment Flight-fragment envelopes (PPR fast-path payload splice, issue #700).
+ *
+ * On a shell-HIT tail, replayed (baked) segments do NOT round-trip through the
+ * server codec (deserialize -> re-serialize) per request. The stored RSC
+ * fragment STRINGS ride the outgoing payload verbatim inside these envelopes
+ * — the outer Flight render copies a string instead of re-serializing a whole
+ * element tree — and the CONSUMER expands each envelope through its own Flight
+ * deserializer: the SSR resume pass (ssr/ssr-root.tsx), browser hydration, and
+ * capability-gated partial navigation/prefetch decoders. Each fragment is its
+ * own row space, decoded independently, exactly like the segment codec's
+ * per-record decode — so there is no Flight row-id collision or shared-row
+ * dedupe hazard.
+ *
+ * Envelopes appear ONLY on fields that hold ReactNodes (component / layout /
+ * loading). A plain object is never a valid ReactNode, so the marker cannot
+ * collide with legitimate segment content; loader data fields (consumer data,
+ * any shape) are never enveloped.
+ *
+ * This module is shared client/server code (browser + SSR + RSC import it) —
+ * it must stay dependency-free: no plugin-rsc, no request-context.
+ */
+
+import type { ResolvedSegment } from "./types.js";
+
+/** Partial-request capability gate for browser-side fragment expansion. */
+export const SEGMENT_FRAGMENT_CAPABILITY_HEADER: string =
+  "X-Rango-Fragment-Passthrough";
+
+/** One-shot request marker that forces server-side fragment validation. */
+export const SEGMENT_FRAGMENT_RECOVERY_HEADER: string =
+  "X-Rango-Fragment-Recovery";
+
+/** A stored fragment failed in its consumer-side Flight decoder. */
+export class SegmentFragmentDecodeError extends Error {
+  readonly cause: unknown;
+
+  constructor(cause: unknown) {
+    super("Failed to decode a stored RSC segment fragment");
+    this.name = "SegmentFragmentDecodeError";
+    this.cause = cause;
+  }
+}
+
+/**
+ * One RSC-encoded fragment traveling inside an RscPayload segment field.
+ * `f` is the stored Flight document (segment-codec output) for that field.
+ */
+export interface SegmentFlightFragment {
+  __rangoFragment: 1;
+  f: string;
+}
+
+/** Wrap a stored fragment string for the wire. */
+export function segmentFragment(encoded: string): SegmentFlightFragment {
+  return { __rangoFragment: 1, f: encoded };
+}
+
+/** True iff `value` is a fragment envelope (see collision note in the header). */
+export function isSegmentFragment(
+  value: unknown,
+): value is SegmentFlightFragment {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __rangoFragment?: unknown }).__rangoFragment === 1 &&
+    typeof (value as { f?: unknown }).f === "string"
+  );
+}
+
+/**
+ * A consumer-side Flight deserializer: the browser's or the SSR runtime's
+ * createFromReadableStream (each resolves client references through its own
+ * module map, exactly as it does for the outer payload stream). Non-generic
+ * so both environments' generic createFromReadableStream signatures assign
+ * directly.
+ */
+export type FragmentDecoder = (
+  stream: ReadableStream<Uint8Array>,
+) => Promise<unknown>;
+
+/** One-chunk byte stream over an encoded fragment (local: this module must not
+ *  import segment-codec, which pulls plugin-rsc into client bundles). */
+function fragmentToStream(encoded: string): ReadableStream<Uint8Array> {
+  const bytes = new TextEncoder().encode(encoded);
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+/** The segment fields that may carry an envelope (ReactNode fields only). */
+const FRAGMENT_FIELDS = ["component", "layout", "loading"] as const;
+
+/**
+ * Expand every fragment envelope in `segments` IN PLACE via `decode`,
+ * in parallel. A payload with no envelopes (every non-shell-HIT payload) costs
+ * one synchronous field scan. A failing fragment decode rejects the whole
+ * expansion: the caller's payload promise rejects, which on the SSR side
+ * errors the HIT tail (serveShellHit then schedules the healing recapture) —
+ * the same posture as a parseable-but-mismatched postponed blob.
+ */
+export async function expandSegmentFragments(
+  segments: ResolvedSegment[] | undefined,
+  decode: FragmentDecoder,
+): Promise<void> {
+  if (!segments || segments.length === 0) return;
+  const decodes: Promise<void>[] = [];
+  for (const segment of segments) {
+    for (const field of FRAGMENT_FIELDS) {
+      const value = segment[field];
+      if (isSegmentFragment(value)) {
+        // Promise.resolve() adoption is load-bearing: some deserializers
+        // (react-server-dom's Flight client) return a THENABLE Chunk whose
+        // .then returns undefined — chaining directly would push undefined
+        // into the barrier and Promise.all would not wait for the decode.
+        decodes.push(
+          Promise.resolve(decode(fragmentToStream(value.f))).then((node) => {
+            segment[field] = node as ResolvedSegment[typeof field];
+          }),
+        );
+      }
+    }
+  }
+  if (decodes.length > 0) await Promise.all(decodes);
+}
+
+/**
+ * Expand every envelope in an RscPayload-shaped object, in place. Decode
+ * failures use a distinct error so partial navigation can retry once through
+ * the server's decode-and-evict path. The
+ * hasSegmentFragments pre-scan keeps envelope-free payloads — every
+ * non-replay response — to one synchronous field walk; this runs on every
+ * navigation and prefetch decode.
+ */
+export async function expandPayloadFragments(
+  payload: { metadata?: { segments?: ResolvedSegment[] } },
+  decode: FragmentDecoder,
+): Promise<void> {
+  const segments = payload.metadata?.segments;
+  if (!hasSegmentFragments(segments)) return;
+  try {
+    await expandSegmentFragments(segments, decode);
+  } catch (error) {
+    throw new SegmentFragmentDecodeError(error);
+  }
+}
+
+/**
+ * True when any segment carries an unexpanded envelope. Cheap scan used by
+ * consumers that only need to know whether an expansion pass is required.
+ */
+export function hasSegmentFragments(
+  segments: ResolvedSegment[] | undefined,
+): boolean {
+  if (!segments) return false;
+  for (const segment of segments) {
+    for (const field of FRAGMENT_FIELDS) {
+      if (isSegmentFragment(segment[field])) return true;
+    }
+  }
+  return false;
+}

package/src/segment-loader-promise.ts

@@ -0,0 +1,167 @@
+import type { ResolvedSegment } from "./types.js";
+import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
+
+/**
+ * Cache of aggregate Promise.all results keyed on the first loader's
+ * `loaderData` reference. Each entry holds the source refs it was built from
+ * plus the resulting Promise/array; lookup scans entries for the matching
+ * source array (typically a single entry, since distinct loader groups rarely
+ * share a first source). Object first-refs live in a WeakMap (auto-GC);
+ * primitive first-refs (strings/numbers/booleans/null) live in a Map so
+ * loaders that resolve to primitive data are memoized too. The per-key array
+ * is capped (MAX_ENTRIES_PER_KEY, oldest evicted) so a long session under a
+ * stable first-ref does not grow it without bound.
+ *
+ * Keying externally means reconciliation's fresh segment objects no longer
+ * drop memoization — the cache survives as long as the underlying loader
+ * segments do, and GC collects entries when those loaders are released
+ * (object keys only).
+ *
+ * Browser-only. On the server each SSR render needs a fresh Promise so
+ * Suspense can actually suspend and emit the loading fallback HTML before
+ * content streams. A shared already-resolved promise has `.status` attached
+ * by React on first `use()`; subsequent observations return synchronously
+ * and skip the fallback. The zero-loader case is especially prone because
+ * every empty-loader site would otherwise share one promise across requests.
+ */
+const IS_BROWSER = typeof window !== "undefined";
+
+interface LoaderCacheEntry {
+  sources: any[];
+  // buildLoaderPromise always returns a Promise, so the cached value is never a
+  // bare array. The public getMemoizedLoaderPromise return type stays broader
+  // (Promise<any[]> | any[]) to mirror its siblings.
+  promise: Promise<any[]>;
+}
+
+// Cap the per-key entries array. A stable first-ref (e.g. a layout loader whose
+// loaderData object survives reconciliation across navigations) keeps its
+// WeakMap/Map key alive, while a per-route loader whose ref changes each
+// navigation appends a brand-new sources array under that same live key on
+// every navigation. Nothing was ever removed, so the array grew linearly with
+// navigation count, pinning each stale Promise + sources array from GC — a
+// steady client-side leak over a long session. Only the current render's combo
+// needs to stay warm; evict the oldest beyond the cap.
+const MAX_ENTRIES_PER_KEY = 8;
+
+const objectLoaderCache = IS_BROWSER
+  ? new WeakMap<object, LoaderCacheEntry[]>()
+  : null;
+const primitiveLoaderCache = IS_BROWSER
+  ? new Map<unknown, LoaderCacheEntry[]>()
+  : null;
+
+// In the browser, a single shared empty aggregate is safe (and desirable) —
+// reusing the same resolved promise keeps React's `use()` in a known-fulfilled
+// state across renders. On the server it would leak `.status = "fulfilled"`
+// across requests and skip the Suspense fallback, so we rebuild on each call.
+const SHARED_EMPTY_LOADER_PROMISE: Promise<any[]> | null = IS_BROWSER
+  ? Promise.resolve([])
+  : null;
+
+function hasSameReferences(a: any[], b: any[]): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Build a fresh aggregate Promise.all over the loaders' resolved data refs.
+ * Unlike getMemoizedLoaderPromise this never caches, so each call yields a new
+ * Promise — correct for sites that await the result immediately (a shared,
+ * already-resolved promise would leak React's `.status` across server requests
+ * and skip the Suspense fallback).
+ *
+ * @internal
+ */
+export function buildLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]> {
+  if (loaders.length === 0) {
+    return Promise.resolve([]);
+  }
+  // Debug tap (browser only): log when each PENDING loader promise settles —
+  // i.e. when its data actually lands from the flight stream — independent of
+  // when the tree build awaits it. `.then(cb, cb)` observes on a branch, so
+  // rejections still propagate to the real consumers untouched.
+  if (INTERNAL_RANGO_DEBUG && IS_BROWSER) {
+    const tapStart = performance.now();
+    for (const loader of loaders) {
+      if (loader.loaderData instanceof Promise) {
+        const settle = (outcome: string) => () =>
+          console.log(
+            `[Browser][segments] loader ${loader.loaderId} ${outcome} @ ${Math.round(performance.now())}ms`,
+            { msSinceRequested: Math.round(performance.now() - tapStart) },
+          );
+        loader.loaderData.then(settle("settled"), settle("rejected"));
+      }
+    }
+  }
+  return Promise.all(
+    loaders.map((loader) =>
+      loader.loaderData instanceof Promise
+        ? loader.loaderData
+        : Promise.resolve(loader.loaderData),
+    ),
+  );
+}
+
+function isObjectLike(value: unknown): value is object {
+  return (
+    value !== null && (typeof value === "object" || typeof value === "function")
+  );
+}
+
+/**
+ * Memoize an aggregate Promise.all for a set of loader segments. Reusing the
+ * same aggregate across renders — invalidated only when any underlying
+ * loader.loaderData ref changes — keeps React's `use()` in "known fulfilled"
+ * state and prevents a fresh Promise.all from suspending (and briefly
+ * committing the Suspense fallback) on every partial update that doesn't
+ * actually change loader data.
+ *
+ * @internal
+ */
+export function getMemoizedLoaderPromise(
+  loaders: ResolvedSegment[],
+): Promise<any[]> | any[] {
+  if (loaders.length === 0) {
+    return SHARED_EMPTY_LOADER_PROMISE ?? buildLoaderPromise(loaders);
+  }
+  if (!objectLoaderCache || !primitiveLoaderCache) {
+    return buildLoaderPromise(loaders);
+  }
+
+  const sources = loaders.map((loader) => loader.loaderData);
+  const first = sources[0];
+  const entries = isObjectLike(first)
+    ? objectLoaderCache.get(first)
+    : primitiveLoaderCache.get(first);
+
+  if (entries) {
+    for (const entry of entries) {
+      if (hasSameReferences(entry.sources, sources)) {
+        return entry.promise;
+      }
+    }
+  }
+
+  const promise = buildLoaderPromise(loaders);
+  const newEntry: LoaderCacheEntry = { sources, promise };
+  if (entries) {
+    // Bound the array: drop the oldest entry before appending when at the cap.
+    if (entries.length >= MAX_ENTRIES_PER_KEY) {
+      entries.shift();
+    }
+    entries.push(newEntry);
+  } else if (isObjectLike(first)) {
+    objectLoaderCache.set(first, [newEntry]);
+  } else {
+    primitiveLoaderCache.set(first, [newEntry]);
+  }
+  return promise;
+}