@rangojs/router 0.0.0-experimental.32 → 0.0.0-experimental.3232cd17

package/src/search-params.ts

@@ -7,10 +7,6 @@
  * URLSearchParams instance.
  */
 
-// ============================================================================
-// Schema Types
-// ============================================================================
-
 /** Supported scalar types for search params (append ? for optional). */
 export type SearchSchemaValue =
   | "string"
@@ -23,10 +19,6 @@ export type SearchSchemaValue =
 /** A search schema maps param names to their type descriptors. */
 export type SearchSchema = Record<string, SearchSchemaValue>;
 
-// ============================================================================
-// Type-Level Schema Resolution
-// ============================================================================
-
 /** Strip trailing `?` from a schema value to get the base type. */
 type BaseType<T extends string> = T extends `${infer B}?` ? B : T;
 
@@ -81,11 +73,11 @@ export type ResolveSearchSchema<T extends SearchSchema> = Simplify<
 // ============================================================================
 
 /** Resolve the global route map from RegisteredRoutes or GeneratedRouteMap. */
-type GlobalRouteMap = keyof RSCRouter.RegisteredRoutes extends never
-  ? keyof RSCRouter.GeneratedRouteMap extends never
+type GlobalRouteMap = keyof Rango.RegisteredRoutes extends never
+  ? keyof Rango.GeneratedRouteMap extends never
     ? Record<string, string>
-    : RSCRouter.GeneratedRouteMap
-  : RSCRouter.RegisteredRoutes;
+    : Rango.GeneratedRouteMap
+  : Rango.RegisteredRoutes;
 
 /**
  * Extract the resolved search params type for a named route.
@@ -163,10 +155,6 @@ type ExtractParamsFromPattern<T extends string> =
             : { [K in Param]: string }
       : {};
 
-// ============================================================================
-// Runtime Parser
-// ============================================================================
-
 /**
  * Parse URLSearchParams into a typed object using the given schema.
  *
@@ -210,10 +198,6 @@ export function parseSearchParams<T extends SearchSchema>(
   return result as ResolveSearchSchema<T>;
 }
 
-// ============================================================================
-// Runtime Serializer
-// ============================================================================
-
 /**
  * Serialize a typed search params object to a query string (without leading `?`).
  * Skips `undefined` and `null` values.

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-loader-promise.ts

@@ -0,0 +1,134 @@
+import type { ResolvedSegment } from "./types.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 — bounded in
+ * practice by the application's loader set.
+ *
+ * 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[]>;
+}
+
+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([]);
+  }
+  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) {
+    entries.push(newEntry);
+  } else if (isObjectLike(first)) {
+    objectLoaderCache.set(first, [newEntry]);
+  } else {
+    primitiveLoaderCache.set(first, [newEntry]);
+  }
+  return promise;
+}