@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.141

package/src/search-params.ts

@@ -2,13 +2,21 @@
  * Search parameter schema types and runtime utilities.
  *
  * Provides a lightweight schema system for typed query parameters.
- * When a route defines a `search` schema, ctx.searchParams becomes
- * a typed object with parsed values instead of raw URLSearchParams.
+ * When a route defines a `search` schema, ctx.search provides a typed
+ * object with parsed values. ctx.searchParams always remains a standard
+ * URLSearchParams instance.
  */
 
-// ============================================================================
-// Schema Types
-// ============================================================================
+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 =
@@ -22,10 +30,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;
 
@@ -54,27 +58,37 @@ 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; page?: number; sort?: string }
+ * // { q: string | undefined; page?: number; sort?: string }
  */
-export type ResolveSearchSchema<T extends SearchSchema> = Simplify<{
-  [K in RequiredKeys<T> & string]: ResolveBaseType<BaseType<T[K]>>;
-} & {
-  [K in OptionalKeys<T> & string]?: ResolveBaseType<BaseType<T[K]>>;
-}>;
+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 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.
@@ -87,19 +101,17 @@ type GlobalRouteMap = keyof RSCRouter.RegisteredRoutes extends never
  * // { q: string; page?: number }
  * ```
  */
-export type RouteSearchParams<
-  TName extends string,
-  TRouteMap = never,
-> = [TRouteMap] extends [never]
+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>
-      : {}
-    : {};
+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.
@@ -112,50 +124,62 @@ type ExtractAndResolveSearch<TRouteMap, TName> =
  * // { slug: string }
  * ```
  */
-export type RouteParams<
-  TName extends string,
-  TRouteMap = never,
-> = [TRouteMap] extends [never]
+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>
-        : {}
-    : {};
+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}?`
-      ? { [K in Name]?: string } & ExtractParamsFromPattern<`/${Rest}`>
-      : Param extends `${infer Name}(${string})`
-        ? { [K in Name]: string } & ExtractParamsFromPattern<`/${Rest}`>
-        : { [K in Param]: string } & ExtractParamsFromPattern<`/${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}?`
-        ? { [K in Name]?: string }
-        : Param extends `${infer Name}(${string})`
-          ? { [K in Name]: string }
-          : { [K in Param]: string }
+      ? 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 }
       : {};
 
-// ============================================================================
-// Runtime Parser
-// ============================================================================
-
 /**
  * Parse URLSearchParams into a typed object using the given schema.
  *
  * - `"string"` / `"string?"` - kept as-is
- * - `"number"` / `"number?"` - coerced via `Number()`; NaN treated as missing
+ * - `"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 required params are set to their zero value (empty string / 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,
@@ -169,25 +193,24 @@ export function parseSearchParams<T extends SearchSchema>(
     const raw = searchParams.get(key);
 
     if (raw === null) {
-      if (!isOptional) {
-        // Required param missing: use zero value
-        if (baseType === "string") result[key] = "";
-        else if (baseType === "number") result[key] = 0;
-        else if (baseType === "boolean") result[key] = false;
-      }
-      // Optional params are omitted (undefined)
+      // Missing params are omitted (undefined) regardless of required/optional
       continue;
     }
 
     if (baseType === "string") {
       result[key] = raw;
     } else if (baseType === "number") {
-      const num = Number(raw);
-      if (Number.isNaN(num)) {
-        if (!isOptional) result[key] = 0;
-      } else {
-        result[key] = num;
+      // 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";
     }
@@ -196,23 +219,17 @@ 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.
+ * Skips `undefined` and `null` values. Preserves insertion order (no sort).
  */
-export function serializeSearchParams(
-  params: Record<string, unknown>,
-): string {
-  const parts: string[] = [];
+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;
-    parts.push(
-      `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`,
-    );
+    pairs.push([key, String(value)]);
   }
-  return parts.join("&");
+  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-loader-promise.ts

@@ -0,0 +1,149 @@
+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. 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([]);
+  }
+  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;
+}