@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/dist/types.backup/segment-fragments.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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) and browser hydration
+ * (browser/rsc-router.tsx). 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";
+/**
+ * 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 declare function segmentFragment(encoded: string): SegmentFlightFragment;
+/** True iff `value` is a fragment envelope (see collision note in the header). */
+export declare function isSegmentFragment(value: unknown): value is SegmentFlightFragment;
+/**
+ * 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>;
+/**
+ * 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 declare function expandSegmentFragments(segments: ResolvedSegment[] | undefined, decode: FragmentDecoder): Promise<void>;
+/**
+ * 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 declare function hasSegmentFragments(segments: ResolvedSegment[] | undefined): boolean;

package/dist/types.backup/segment-loader-promise.d.ts

@@ -0,0 +1,22 @@
+import type { ResolvedSegment } from "./types.js";
+/**
+ * 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 declare function buildLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]>;
+/**
+ * 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 declare function getMemoizedLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]> | any[];

package/dist/types.backup/segment-system.d.ts

@@ -0,0 +1,84 @@
+import { type ReactNode, type ComponentType } from "react";
+import type { ResolvedSegment, RootLayoutProps } from "./types.js";
+export declare function restoreParallelLoaderMarkers(segments: ResolvedSegment[]): ResolvedSegment[];
+/**
+ * Options for renderSegments
+ */
+export interface RenderSegmentsOptions {
+    /**
+     * If true, this render is for a server action response.
+     * In browser during actions, we await component promises to prevent
+     * UI flickering/suspense during optimistic updates.
+     */
+    isAction?: boolean;
+    /**
+     * If true, force awaiting all loaders instead of streaming with Suspense.
+     * Used for popstate (back/forward) navigation where we want instant rendering
+     * from cache without showing loading skeletons.
+     */
+    forceAwait?: boolean;
+    /**
+     * Intercept segments to inject into the tree.
+     * These are parallel segments from intercept routes that need to be
+     * associated with their parent layout's named outlet.
+     *
+     * Passed separately for explicit handling - makes the flow clearer
+     * and easier to debug than relying on ID pattern matching.
+     */
+    interceptSegments?: ResolvedSegment[];
+    /**
+     * Root layout component that wraps the entire application.
+     * When provided, wraps both route content and the error boundary,
+     * preventing the app shell from unmounting during errors (avoids FOUC).
+     */
+    rootLayout?: ComponentType<RootLayoutProps>;
+}
+/**
+ * Render segments into a React tree with proper layout nesting
+ *
+ * Layouts nest using OutletProvider; a layout receives the inner content via
+ * its `<Outlet />`. Parallel segments do NOT render as inline Fragment siblings
+ * — they flow through OutletContext.parallel and are resolved where a layout
+ * places `<ParallelOutlet name="@sidebar" />` (or `<Outlet name="@sidebar" />`).
+ *
+ * The result is always wrapped in RootErrorBoundary so unhandled errors never
+ * blank the screen. When `options.rootLayout` is provided it wraps the error
+ * boundary at the OUTERMOST level (so the app shell survives errors).
+ *
+ * Error segments are treated like route segments - they render their fallback
+ * component in place of the failed segment. When an error occurs in a handler,
+ * loader, or middleware, the router creates an error segment with the nearest
+ * error boundary's fallback component.
+ *
+ * NotFound segments are similar to error segments but are triggered by
+ * DataNotFoundError (thrown via notFound()). They render the nearest
+ * notFoundBoundary's fallback component.
+ *
+ * @param segments - Array of resolved segments to render
+ * @returns Promise resolving to the ReactNode tree (the function is async)
+ *
+ * @example
+ * ```typescript
+ * const segments = [
+ *   { id: 'L0.0', type: 'layout', component: <BlogLayout /> },
+ *   { id: 'L0R1', type: 'route', component: <BlogPost /> },
+ *   { id: 'L0R1.@sidebar', type: 'parallel', component: <Sidebar />, slot: '@sidebar' }
+ * ];
+ *
+ * // BlogLayout renders <Outlet /> for the route and
+ * // <ParallelOutlet name="@sidebar" /> for the parallel slot.
+ * const tree = await renderSegments(segments, { rootLayout: RootLayout });
+ * // Results in (outermost first):
+ * // <RootLayout>
+ * //   <RootErrorBoundary>
+ * //     <OutletProvider segment={BlogLayout} parallel={[Sidebar]}>
+ * //       <BlogPost />
+ * //     </OutletProvider>
+ * //   </RootErrorBoundary>
+ * // </RootLayout>
+ *
+ * // For server actions, pass isAction to await components:
+ * const tree = await renderSegments(segments, { isAction: true });
+ * ```
+ */
+export declare function renderSegments(segments: ResolvedSegment[], options?: RenderSegmentsOptions): Promise<ReactNode>;

package/dist/types.backup/serialize.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Wire-type serialization transforms.
+ *
+ * The type a handler or loader returns on the server is frequently NOT the type
+ * a client receives after serialization. These transforms model that boundary so
+ * consumer-facing types (e.g. `Rango.PathResponse`) describe the wire value, not
+ * the source value.
+ *
+ * Two serializers, two transforms — they are intentionally NOT interchangeable:
+ *
+ * - `JsonSerialize<T>` models plain `JSON.stringify` (`path.json()` /
+ *   `fetch().then(r => r.json())`). Lossy: `Date -> string`, `undefined` /
+ *   functions / symbols dropped, `Map`/`Set` -> `{}`. `bigint` *throws* (no wire
+ *   value), so it collapses the whole result to `never`. Honors `toJSON()`.
+ * - `FlightSerialize<T>` models React RSC Flight (loaders, RSC props, cache).
+ *   High fidelity: `Date`/`Map`/`Set`/`bigint`/typed arrays/`Promise` are
+ *   preserved; ordinary functions and non-global symbols do not cross.
+ *
+ * ## Overriding (full-transform replacement)
+ *
+ * Because `Rango.JsonSerialize` / `Rango.FlightSerialize` are type *aliases*, TS
+ * cannot let you redefine them directly (aliases don't merge). Instead each alias
+ * consults a generic override slot — augment it with a single member that is your
+ * complete transform. Delegate to the built-in for the cases you don't change:
+ *
+ * ```ts
+ * declare global {
+ *   namespace Rango {
+ *     interface FlightSerializeOverride<T> {
+ *       app: T extends Money ? number : Rango.FlightSerializeBuiltin<T>;
+ *     }
+ *   }
+ * }
+ * // now Rango.FlightSerialize<Money> is number; everything else is the built-in.
+ * ```
+ *
+ * Provide exactly one member: the slot is read as `Override<T>[keyof Override<T>]`,
+ * so multiple members union (and conflict). The built-in recurses through the
+ * override-aware alias, so an override applies at every nesting level.
+ */
+import type { ReactNode } from "react";
+type JsonPrimitive = string | number | boolean | null;
+type AnyFunction = (...args: never[]) => unknown;
+/**
+ * Internal marker for a value that makes `JSON.stringify` throw (`bigint`, or a
+ * `toJSON()` returning one). Distinct from `never`, which means "omitted":
+ * `undefined`/function/symbol-valued keys are dropped, and such array slots
+ * become `null`. A throwing value has no valid JSON wire form, so it propagates
+ * up through every container and is excluded at the public boundary (`bigint`
+ * alone -> `never`; `{ id: bigint }` -> `never`).
+ */
+declare const JSON_THROWS: unique symbol;
+type JsonThrows = typeof JSON_THROWS;
+/** True if union `U` contains the throw marker. */
+type HasThrow<U> = [Extract<U, JsonThrows>] extends [never] ? false : true;
+/** Map a JSON array/tuple: propagate a throw; else omitted elements become null. */
+type JsonSerializeArray<T extends readonly unknown[]> = HasThrow<{
+    [K in keyof T]: JsonRawResolve<T[K]>;
+}[number]> extends true ? JsonThrows : {
+    [K in keyof T]: [JsonRawResolve<T[K]>] extends [never] ? null : JsonRawResolve<T[K]>;
+};
+/** Map a JSON object: propagate a throw; else drop omitted keys. */
+type JsonSerializeObject<T> = HasThrow<{
+    [K in keyof T]: JsonRawResolve<T[K]>;
+}[keyof T]> extends true ? JsonThrows : {
+    [K in keyof T as [JsonRawResolve<T[K]>] extends [never] ? never : K]: JsonRawResolve<T[K]>;
+};
+/**
+ * Built-in JSON rules, *raw* (may yield the throw marker). Honors `toJSON()` (so
+ * `Date -> string` and any class with `toJSON()` serialize correctly), preserves
+ * JSON primitives and literals, omits functions / symbols / `undefined`,
+ * collapses `Map`/`Set` to `{}`, and marks `bigint` as throwing. Recurses through
+ * the override-aware resolver, so registered overrides apply at every level.
+ */
+type JsonSerializeBuiltinRaw<T> = T extends {
+    toJSON(...args: never[]): infer R;
+} ? JsonRawResolve<R> : T extends JsonPrimitive ? T : T extends bigint ? JsonThrows : T extends AnyFunction ? never : T extends symbol ? never : T extends undefined ? never : T extends readonly unknown[] ? JsonSerializeArray<T> : T extends ReadonlyMap<unknown, unknown> ? {} : T extends ReadonlySet<unknown> ? {} : T extends object ? JsonSerializeObject<T> : never;
+/** Override-aware raw JSON resolution (the recursion entry). */
+type JsonRawResolve<T> = [keyof Rango.JsonSerializeOverride<T>] extends [never] ? JsonSerializeBuiltinRaw<T> : Rango.JsonSerializeOverride<T>[keyof Rango.JsonSerializeOverride<T>];
+/**
+ * Model the result of round-tripping a value through `JSON.stringify` /
+ * `JSON.parse`. A registered `Rango.JsonSerializeOverride` replaces the transform
+ * wholesale; otherwise the built-in rules apply. Throwing values collapse to
+ * `never`.
+ */
+export type JsonSerialize<T> = Exclude<JsonRawResolve<T>, JsonThrows>;
+/**
+ * Built-in Flight rules. Mirrors React's `ReactClientValue` contract: primitives
+ * including `bigint`, `undefined`, `null`, symbols, `Date`, `ArrayBuffer` and
+ * typed-array views, `Map`, `Set`, `FormData`, `Blob`, `Promise`,
+ * `ReadableStream`, and (async) iterables are preserved; ordinary functions
+ * resolve to `never`. JSX (`ReactNode`, and the async-node union
+ * `ReactNode | Promise<ReactNode>`) is preserved as-is via a non-distributive
+ * leaf, so handle/loader returns that carry JSX round-trip unchanged. Recurses
+ * through the override-aware `FlightSerialize`.
+ *
+ * The source of truth is React's own contract, which is intentionally NOT
+ * semver-stable across RSC framework APIs — this tracks the React version Rango
+ * pins. See:
+ * https://react.dev/reference/rsc/use-client#serializable-types-returned-by-server-components
+ *
+ * Type-level limitations (not detectable structurally, so not modeled): class
+ * instances and null-prototype objects are rejected by React at runtime but pass
+ * here as their structural shape; non-global symbols are rejected at runtime but
+ * `symbol` is preserved here; Server Functions would need an override to be
+ * distinguished from ordinary functions (which resolve to `never`).
+ */
+type FlightSerializeBuiltinRaw<T> = [T] extends [ReactNode | Promise<ReactNode>] ? T : T extends string | number | boolean | bigint | symbol | null | undefined ? T : T extends AnyFunction ? never : T extends Date ? Date : T extends ArrayBuffer ? ArrayBuffer : T extends ArrayBufferView ? T : T extends FormData ? FormData : T extends Blob ? Blob : T extends Map<infer K, infer V> ? Map<FlightSerialize<K>, FlightSerialize<V>> : T extends Set<infer V> ? Set<FlightSerialize<V>> : T extends Promise<infer V> ? Promise<FlightSerialize<V>> : T extends ReadableStream<infer V> ? ReadableStream<FlightSerialize<V>> : T extends readonly unknown[] ? {
+    [K in keyof T]: FlightSerialize<T[K]>;
+} : T extends AsyncIterable<infer V> ? AsyncIterable<FlightSerialize<V>> : T extends Iterable<infer V> ? Iterable<FlightSerialize<V>> : T extends object ? {
+    [K in keyof T]: FlightSerialize<T[K]>;
+} : never;
+/**
+ * Model React RSC Flight serialization. A registered `Rango.FlightSerializeOverride`
+ * replaces the transform wholesale; otherwise the built-in rules apply.
+ */
+export type FlightSerialize<T> = [
+    keyof Rango.FlightSerializeOverride<T>
+] extends [never] ? FlightSerializeBuiltinRaw<T> : Rango.FlightSerializeOverride<T>[keyof Rango.FlightSerializeOverride<T>];
+type GlobalJsonSerialize<T> = JsonSerialize<T>;
+type GlobalJsonSerializeBuiltin<T> = JsonSerializeBuiltinRaw<T>;
+type GlobalFlightSerialize<T> = FlightSerialize<T>;
+type GlobalFlightSerializeBuiltin<T> = FlightSerializeBuiltinRaw<T>;
+/**
+ * Ambient serialization transforms and their override slots on the `Rango`
+ * namespace. Available with no import wherever the router's types are in scope,
+ * alongside `Rango.Path` / `Rango.PathResponse`.
+ *
+ * `Rango.JsonSerialize` is what `Rango.PathResponse` applies; `Rango.FlightSerialize`
+ * is exposed for RSC/loader/cache wire types and must NOT be used for `path.json()`.
+ * `Rango.JsonSerializeBuiltin` / `Rango.FlightSerializeBuiltin` are the defaults,
+ * exported so an override can delegate to them.
+ */
+declare global {
+    namespace Rango {
+        /**
+         * Full-transform override slot for `Rango.JsonSerialize`. Empty by default;
+         * augment with one member that is your complete transform (delegate to
+         * `Rango.JsonSerializeBuiltin<T>` for the cases you don't change).
+         */
+        interface JsonSerializeOverride<T> {
+        }
+        /**
+         * Full-transform override slot for `Rango.FlightSerialize`. Empty by default;
+         * augment with one member that is your complete transform (delegate to
+         * `Rango.FlightSerializeBuiltin<T>` for the cases you don't change).
+         */
+        interface FlightSerializeOverride<T> {
+        }
+        /** Wire type after `JSON.stringify` (`path.json()` / `fetch().json()`). */
+        type JsonSerialize<T> = GlobalJsonSerialize<T>;
+        /**
+         * Built-in `JsonSerialize` rules, for an override to delegate to. Raw: a
+         * `bigint`-bearing type yields the internal throw marker here, which
+         * `Rango.JsonSerialize` excludes to `never` at the boundary.
+         */
+        type JsonSerializeBuiltin<T> = GlobalJsonSerializeBuiltin<T>;
+        /** Wire type after RSC Flight serialization (loaders / RSC props / cache). */
+        type FlightSerialize<T> = GlobalFlightSerialize<T>;
+        /** Built-in `FlightSerialize` rules, for an override to delegate to. */
+        type FlightSerializeBuiltin<T> = GlobalFlightSerializeBuiltin<T>;
+    }
+}
+export {};