@rangojs/router 0.5.1 → 0.6.0

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

@@ -1,56 +0,0 @@
-/**
- * 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

@@ -1,22 +0,0 @@
-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

@@ -1,84 +0,0 @@
-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

@@ -1,164 +0,0 @@
-/**
- * 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 {};