@rangojs/router 0.1.1 → 0.4.0

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

@@ -0,0 +1,226 @@
+/**
+ * Custom error classes for Rango
+ *
+ * All errors include:
+ * - Descriptive names for easy identification
+ * - Cause property for structured debugging data
+ */
+/**
+ * Options for error construction
+ */
+interface ErrorOptions {
+    cause?: unknown;
+}
+/**
+ * Thrown when no route matches the requested pathname
+ */
+export declare class RouteNotFoundError extends Error {
+    name: "RouteNotFoundError";
+    cause?: unknown;
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare function isRouteNotFoundError(error: unknown): error is RouteNotFoundError;
+/**
+ * Thrown when data is not found (e.g., product with ID doesn't exist)
+ * Use this in handlers/loaders to trigger the nearest notFoundBoundary
+ *
+ * @example
+ * ```typescript
+ * route("products.detail", async (ctx) => {
+ *   const product = await db.products.get(ctx.params.slug);
+ *   if (!product) throw new DataNotFoundError("Product not found");
+ *   return <ProductDetail product={product} />;
+ * });
+ * ```
+ */
+export declare class DataNotFoundError extends Error {
+    name: "DataNotFoundError";
+    cause?: unknown;
+    constructor(message?: string, options?: ErrorOptions);
+}
+/**
+ * Convenience function to throw a DataNotFoundError
+ * Shorter syntax for common not-found scenarios
+ *
+ * @example
+ * ```typescript
+ * const product = await db.products.get(slug);
+ * if (!product) throw notFound("Product not found");
+ * // or simply:
+ * if (!product) throw notFound();
+ * ```
+ */
+export declare function notFound(message?: string): never;
+/**
+ * Thrown when middleware execution fails
+ */
+export declare class MiddlewareError extends Error {
+    name: "MiddlewareError";
+    cause?: unknown;
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a route handler fails
+ */
+export declare class HandlerError extends Error {
+    name: "HandlerError";
+    cause?: unknown;
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when segment building fails
+ */
+export declare class BuildError extends Error {
+    name: "BuildError";
+    cause?: unknown;
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a route-definition DSL helper (route/layout/loader/cache/…) is
+ * called outside an active urls()/map() builder, so there is no
+ * AsyncLocalStorage build context to attach to. The message names the specific
+ * helper and how to fix it; the `cause` records the mechanical reason so the
+ * failure mode is identifiable (not conflated with an unrelated throw).
+ */
+export declare class DslContextError extends Error {
+    name: "DslContextError";
+    cause?: unknown;
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a network request fails (server unreachable, no internet, etc.)
+ * This error triggers the root error boundary with retry capability.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await fetch(url);
+ * } catch (error) {
+ *   if (error instanceof TypeError) {
+ *     throw new NetworkError("Unable to connect to server", { cause: error });
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+export declare class NetworkError extends Error {
+    name: "NetworkError";
+    cause?: unknown;
+    /** The URL that failed to fetch */
+    url?: string;
+    /** Whether this was during an action, navigation, or revalidation */
+    operation?: "action" | "navigation" | "revalidation";
+    constructor(message?: string, options?: ErrorOptions & {
+        url?: string;
+        operation?: "action" | "navigation" | "revalidation";
+    });
+}
+/**
+ * Check if an error is a network-level failure (server unreachable, no internet)
+ * These are typically TypeError from fetch when the network request itself fails.
+ */
+export declare function isNetworkError(error: unknown): boolean;
+/**
+ * Structured error for JSON response routes.
+ * Thrown by handlers to return a typed error envelope with a specific HTTP status.
+ *
+ * Unlike standard Error, RouterError messages are always exposed to the client
+ * (the developer intentionally crafted them for consumers).
+ *
+ * @example
+ * ```typescript
+ * path("/products/:id", (ctx) => {
+ *   const product = products.find(p => p.id === ctx.params.id);
+ *   if (!product) throw new RouterError("NOT_FOUND", "Product not found", { status: 404 });
+ *   return product;
+ * }, { name: "productDetail" })
+ * ```
+ */
+export declare class RouterError extends Error {
+    name: "RouterError";
+    code: string;
+    status: number;
+    cause?: unknown;
+    constructor(code: string, message: string, options?: {
+        status?: number;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown inside a Prerender or Static handler at build time to signal
+ * "skip this entry, log it, and continue with the rest."
+ *
+ * When thrown, the entry is excluded from the pre-render manifest
+ * but the build continues normally. Regular throws (non-Skip)
+ * stop all further pre-rendering and fail the build.
+ *
+ * @example
+ * ```typescript
+ * export const BlogPost = Prerender(
+ *   async () => allPosts.map(p => ({ slug: p.slug })),
+ *   async (ctx) => {
+ *     const post = await getPost(ctx.params.slug);
+ *     if (post.draft) throw new Skip(`"${ctx.params.slug}" is a draft`);
+ *     return <PostPage post={post} />;
+ *   },
+ * );
+ * ```
+ */
+export declare class Skip extends Error {
+    name: "Skip";
+    cause?: unknown;
+    constructor(message?: string, options?: ErrorOptions);
+}
+/**
+ * Type guard to check if a thrown value is a Skip signal.
+ */
+export declare function isSkip(value: unknown): value is Skip;
+/**
+ * Thrown by the partial updater when the server responds with a redirect payload
+ * that carries location state. Caught by navigate() to re-navigate to the
+ * redirect target with the server-set state merged into history.pushState.
+ *
+ * Not an Error subclass -- this is a control flow signal, not a failure.
+ */
+export declare class ServerRedirect {
+    readonly url: string;
+    readonly state: Record<string, unknown> | undefined;
+    readonly name = "ServerRedirect";
+    constructor(url: string, state: Record<string, unknown> | undefined);
+}
+/**
+ * Thrown when route handler returns invalid type
+ */
+export declare class InvalidHandlerError extends Error {
+    name: "InvalidHandlerError";
+    cause?: unknown;
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Internal invariant assertion for development-time checks
+ *
+ * @internal
+ * @param condition - Condition that must be true
+ * @param message - Error message to throw if condition is false
+ * @throws {Error} If condition is false
+ *
+ * @example
+ * ```typescript
+ * invariant(user !== null, 'User must be defined');
+ * invariant(node.type === 'layout', `Expected layout, got ${node.type}`);
+ * ```
+ */
+export declare function invariant(condition: any, message: string): asserts condition;
+/**
+ * Sanitize errors for production - prevents leaking sensitive information
+ *
+ * SECURITY CRITICAL:
+ * - In production: NEVER send stack traces, file paths, or internal state
+ * - In development: Show full error details for debugging
+ * - ALWAYS consume error.stack to prevent memory leaks
+ *
+ * @param error - Error to sanitize
+ * @returns Response suitable for sending to client
+ */
+export declare function sanitizeError(error: unknown): Response;
+export {};

package/dist/types.backup/escape-script.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Escape a JSON (or JSON-derived) string for safe embedding inside an HTML
+ * <script> element via dangerouslySetInnerHTML. Without this a value containing
+ * "</script>" closes the tag early — the rest of the page leaks as raw HTML, and
+ * in an executable script the trailing content runs. Escaping "<" defeats the
+ * early close; ">" and "&" are escaped for completeness so the serialized payload
+ * can never form HTML syntax. The result is still valid JSON and a valid JS
+ * string literal (\uXXXX escapes are legal in both) and re-parses identically.
+ *
+ * Used by every site that interpolates JSON.stringify(...) into inline <script>
+ * content: the JSON-LD meta descriptors (handles/MetaTags) and the FOUC theme
+ * init script (theme/theme-script).
+ */
+export declare function escapeJsonForScript(json: string): string;
+/**
+ * Escape an inline <script> body so it cannot terminate or corrupt the document.
+ * Two sequences are rewritten, each via a JS escape that is valid in string,
+ * template, regex (including the `u`/`v` flags), and JSON contexts — so the body
+ * still parses identically as code AND as JSON (application/json, ld+json):
+ * - "</script" -> "<\/script": stops a literal close tag inside the body from
+ *   ending the element early. `\/` is a valid JSON escape and a valid regex escape.
+ * - "<!--": the "!" (U+0021) is emitted as a unicode escape (see the replacement
+ *   string below), so the literal "<!--" token never reaches the HTML parser. A
+ *   literal "<!--" puts the parser into the "script data escaped" state and a
+ *   following "<script" into "script data DOUBLE escaped", where the real
+ *   "</script>" no longer closes the element — `var x = "<!--<script>"` would
+ *   swallow the rest of the document. The unicode-escape form decodes back to "!"
+ *   in string/template/JSON/regex contexts, unlike "\!" (invalid JSON, invalid
+ *   /u-regex escape).
+ * Real operators such as `a < b` and `a && b` are untouched (unlike
+ * escapeJsonForScript, which \u-escapes every "<", "&", ">").
+ *
+ * GUARANTEE / LIMITATION: value-preserving for the contexts where these sequences
+ * legitimately appear — string/template literals, regexes (incl. `u`/`v`), and
+ * JSON. It is NOT source-text-preserving (e.g. String.raw`</script>` sees the
+ * extra backslash), and it cannot rewrite "</script"/"<!--" that appear as bare
+ * code (a legacy `<!--` line comment, or `</script` outside any literal) — neither
+ * occurs in valid script payloads. Not a general sanitizer for arbitrary UNTRUSTED
+ * source; for untrusted dynamic data, JSON-encode it and read it back, rather than
+ * inlining it as code.
+ *
+ * Used by the Script handle's <Scripts> renderer for inline `children`.
+ */
+export declare function escapeScriptBody(js: string): string;

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

@@ -0,0 +1,93 @@
+/**
+ * Handle definition for accumulating data across route segments.
+ *
+ * Handles allow server-side route handlers to pass accumulated data to client
+ * components. Unlike loaders (which fetch data for specific routes), handles
+ * accumulate data across all matched route segments.
+ *
+ * @example
+ * ```ts
+ * // Define a handle (name auto-generated from file + export).
+ * // Default collect is the identity: one array per segment that pushed.
+ * export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+ *   (segments) => segments.flat(), // opt into a single flat list
+ * );
+ *
+ * // Use in handler
+ * const push = ctx.use(Breadcrumbs);
+ * push({ label: "Home", href: "/" });
+ *
+ * // Consume on client
+ * const crumbs = useHandle(Breadcrumbs);
+ * ```
+ */
+export interface Handle<TData, TAccumulated = TData[][]> {
+    /**
+     * Brand to distinguish handles from loaders in ctx.use()
+     */
+    readonly __brand: "handle";
+    /**
+     * Auto-generated unique ID for this handle (used as key in storage)
+     * Format: "filePath#ExportName" in dev, "hash#ExportName" in production
+     */
+    readonly $$id: string;
+}
+export declare function getCollectFn(id: string): ((segments: unknown[][]) => unknown) | undefined;
+/**
+ * Create a handle definition for accumulating data across route segments.
+ *
+ * The $$id is auto-generated by the Vite exposeInternalIds plugin based on
+ * file path and export name. No manual naming required.
+ *
+ * @param collect - Optional collect function. Default: pass the per-segment data
+ *   through as-is (one array per segment that pushed, in segment order). Lossless,
+ *   so a consumer can tell which/how-many segments contributed. Opt into a single
+ *   flat list with `(segments) => segments.flat()`.
+ * @param __injectedId - Auto-injected by Vite plugin, do not provide manually
+ *
+ * @example
+ * ```ts
+ * // Default: per-segment grouping, as-is
+ * export const Pushed = createHandle<string>();
+ * // Result type: string[][]  (e.g. [["a"], ["b", "c"]])
+ *
+ * // Opt into a single flat list
+ * export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+ *   (segments) => segments.flat()
+ * );
+ * // Result type: BreadcrumbItem[]
+ *
+ * // Custom: last value wins
+ * export const PageTitle = createHandle<string, string>(
+ *   (segments) => segments.flat().at(-1) ?? "Default Title"
+ * );
+ * // Result type: string
+ *
+ * // Custom: object merge
+ * export const Meta = createHandle<Partial<MetaTags>, MetaTags>(
+ *   (segments) => Object.assign({ robots: "index,follow" }, ...segments.flat())
+ * );
+ * // Result type: MetaTags
+ *
+ * // Custom: dedupe by href (TAccumulated must be given — a custom collect that
+ * // returns a flat array no longer matches the default TData[][])
+ * export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+ *   (segments) => {
+ *     const all = segments.flat();
+ *     return all.filter((item, i) => all.findIndex(x => x.href === item.href) === i);
+ *   }
+ * );
+ * ```
+ */
+export declare function createHandle<TData, TAccumulated = TData[][]>(collect?: (segments: TData[][]) => TAccumulated, __injectedId?: string): Handle<TData, TAccumulated>;
+export declare function isHandle(value: unknown): value is Handle<unknown, unknown>;
+/**
+ * Collect handle data from a HandleData map, applying the handle's collect
+ * function over segments in order. Shared between server-side rendered()
+ * reads and client-side useHandle().
+ *
+ * @param handle - The handle to collect data for
+ * @param data - Full handle data map (handleName -> segmentId -> entries[])
+ * @param segmentOrder - Segment IDs in parent -> child resolution order
+ */
+export declare function collectHandleData<TData, TAccumulated>(handle: Handle<TData, TAccumulated>, data: Record<string, Record<string, unknown[]>>, segmentOrder: string[]): TAccumulated;

package/dist/types.backup/handles/MetaTags.d.ts

@@ -0,0 +1,17 @@
+import type { MetaDescriptorBase } from "../router/types.js";
+export declare function renderMetaDescriptor(descriptor: MetaDescriptorBase, index: number): React.ReactNode;
+/**
+ * Renders all collected meta descriptors from route handlers.
+ *
+ * Place this component inside the `<head>` element of your document.
+ * It will automatically update when meta descriptors change during navigation.
+ *
+ * When theme is enabled in router config, also renders the theme initialization
+ * script to prevent FOUC (flash of unstyled content).
+ *
+ * Deferred (Promise) meta descriptors are resolved BEFORE MetaTags renders —
+ * server-side on the full/SSR render, client-side before apply on navigation
+ * (resolve-by-default) — so MetaTags only ever receives resolved descriptors and
+ * never suspends.
+ */
+export declare function MetaTags(): React.ReactNode;

package/dist/types.backup/handles/Scripts.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Renders the scripts collected by the Script handle into the document.
+ *
+ * Place `<Scripts />` inside `<head>` (default) and, if you push body scripts,
+ * `<Scripts position="body" />` at the top of `<body>`. Each site renders the
+ * configs whose `position` matches; the request CSP nonce is applied
+ * automatically to every DOCUMENT-RENDERED <script> (consumers never pass it). An
+ * async script first encountered on a soft navigation is injected client-side
+ * where the nonce is unavailable, so it carries no nonce and relies on
+ * 'strict-dynamic' (or a host allowance) — see the nonce caveat in the /scripts
+ * skill.
+ *
+ * EXECUTION CONTRACT — see the Script handle's docs. Inline + ordered (defer)
+ * scripts are document-load: they execute only when present in the initial HTML,
+ * so this component FREEZES that set after hydration (the initializer below runs
+ * once) — a later soft navigation never inserts an inert <script> (React creates
+ * client-mounted scripts via innerHTML, which the HTML spec makes non-executing).
+ * Async external scripts are React resources and stay reactive: React loads them
+ * on first encounter, including after navigation, deduped by src.
+ *
+ * @example
+ * ```tsx
+ * <html>
+ *   <head>
+ *     <MetaTags />
+ *     <Scripts />
+ *   </head>
+ *   <body>
+ *     <Scripts position="body" />
+ *     {children}
+ *   </body>
+ * </html>
+ * ```
+ */
+import { type ReactNode } from "react";
+export declare function Scripts({ position, }?: {
+    position?: "head" | "body";
+}): ReactNode;

package/dist/types.backup/handles/breadcrumbs.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Built-in Breadcrumbs handle for accumulating breadcrumb items across route segments.
+ *
+ * Each layout/route pushes breadcrumb items via `ctx.use(Breadcrumbs)`.
+ * Items are collected in parent-to-child order with automatic deduplication
+ * by `href`: each href keeps its FIRST position but takes the LAST value, so a
+ * child re-pushing a parent href refreshes the label without reordering the trail.
+ *
+ * @example
+ * ```tsx
+ * // In route handler
+ * route("/blog/:slug", (ctx) => {
+ *   const breadcrumb = ctx.use(Breadcrumbs);
+ *   breadcrumb({ label: "Blog", href: "/blog" });
+ *   breadcrumb({ label: post.title, href: `/blog/${ctx.params.slug}` });
+ * });
+ *
+ * // In client component (consume with useHandle)
+ * const crumbs = useHandle(Breadcrumbs);
+ * crumbs.map((c) => <a href={c.href}>{c.label}</a>);
+ * ```
+ */
+import type { ReactNode } from "react";
+import { type Handle } from "../handle.js";
+/**
+ * A single breadcrumb item.
+ *
+ * @property label - Display text for the breadcrumb
+ * @property href - URL the breadcrumb links to
+ * @property content - Optional extra content (sync or async) rendered alongside the label
+ */
+export interface BreadcrumbItem {
+    label: string;
+    href: string;
+    content?: ReactNode | Promise<ReactNode>;
+}
+/**
+ * Built-in handle for accumulating breadcrumb navigation items.
+ *
+ * Use `ctx.use(Breadcrumbs)` in route handlers to push breadcrumb items.
+ * Use `useHandle(Breadcrumbs)` in client components to consume them.
+ */
+export declare const Breadcrumbs: Handle<BreadcrumbItem, BreadcrumbItem[]>;

package/dist/types.backup/handles/deferred-resolution.d.ts

@@ -0,0 +1,53 @@
+import type { HandleData, HandleStore } from "../server/handle-store.js";
+/**
+ * Runtime-neutral resolution of deferred (Promise) handle values. Shared by the
+ * server full-render path (resolve before the payload is finalized so SSR sees
+ * resolved values) and the client soft-nav path (NavigationProvider resolves
+ * each yield before applying it). Pure — imports only `isThenable` — so it is
+ * safe in both the RSC server environment AND the browser.
+ *
+ * Resolution is SHALLOW: only an entry that is ITSELF a thenable is awaited. A
+ * value that merely contains a promise (e.g. `{ data: somePromise }`) is a
+ * non-thenable, so the `isThenable` check skips it and it passes through verbatim
+ * — the nested promise is the consumer's responsibility. Resolution runs each
+ * entry through `Promise.all` with a per-entry `try/catch` (NOT `allSettled`), so
+ * one rejecting entry is dropped without rejecting the batch or aborting siblings.
+ */
+/**
+ * Handle names ($$id) whose snapshot carries a deferred (top-level Promise)
+ * value. Used by the client to decide which buckets to hold-and-resolve, and
+ * `.size > 0` answers "does this snapshot have any deferred value".
+ */
+export declare function deferredHandleNames(data: HandleData): Set<string>;
+/**
+ * Snapshot with deferred (Promise) values awaited (shallow — only top-level
+ * thenables). A rejected deferred is dropped, and a deferred that resolves to
+ * `null`/`undefined` is dropped (the `.defer({ else })` skip semantics), so a
+ * nullish deferred slot never reaches a collector. Sync (non-thenable) values —
+ * including a legitimate sync `null` push — pass through unchanged.
+ */
+export declare function resolveDeferredHandleValues(data: HandleData): Promise<HandleData>;
+/**
+ * Full-render handle stream: a one-shot async generator that yields the FINAL
+ * handle snapshot with every top-level deferred value resolved. Drop-in for
+ * `handleStore.stream()` on full / HTML renders (initial load, 404, progressive
+ * enhancement), where the consumer drains the generator to completion before
+ * rendering anyway — so the single final yield is equivalent to the streamed
+ * yields' converged state, and the SSR markup plus the first sync `useHandle`
+ * read see resolved values. `getData()` seals the store and awaits the handler
+ * barrier; `resolveDeferredHandleValues` then awaits the pushed-value promises.
+ * A hung handle promise blocks the full render like any unresolved await (no
+ * handle-specific timeout). Partial / action payloads keep streaming via
+ * `handleStore.stream()`.
+ */
+export declare function resolvedHandleStream(handleStore: HandleStore): AsyncGenerator<HandleData, void, unknown>;
+/**
+ * Resolve the deferred (Promise) values in ONE segment's handle bucket
+ * (`handleName -> entries[]`). Same shallow + drop-rejections rule as
+ * {@link resolveDeferredHandleValues}, but for the segment-keyed shape the
+ * prerender/static collection paths use (`getDataForSegment`). Prerender is a
+ * build-time cache, so the baked artifact must hold resolved values — a hit
+ * replays them into the segment system, where collect/useHandle expect resolved
+ * data.
+ */
+export declare function resolveSegmentHandleValues(segHandles: Record<string, unknown[]>): Promise<Record<string, unknown[]>>;

package/dist/types.backup/handles/is-thenable.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Single thenable predicate for the resolve-by-default handle machinery
+ * (`handles/deferred-resolution.ts`, its sole owner) — it decides which top-level
+ * handle entries are deferred (`Promise`) values to await before any consumer
+ * sees them, and which pass through verbatim.
+ *
+ * Requires a CALLABLE `then` (`typeof obj.then === "function"`), not merely a
+ * `"then" in obj` membership check, so a non-promise carrying a `then` field
+ * (e.g. a serialized shape `{ then: 5 }`) is treated as a plain sync value rather
+ * than awaited. A single predicate keeps that classification consistent.
+ */
+export declare function isThenable(value: unknown): value is PromiseLike<unknown>;

package/dist/types.backup/handles/meta.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Built-in Meta handle for managing document metadata across route segments.
+ *
+ * Provides automatic deduplication: later routes override earlier ones
+ * for the same meta key (title, name, property, etc.)
+ *
+ * @example
+ * ```tsx
+ * // In route handler
+ * route("product/:id", (ctx) => {
+ *   const meta = ctx.use(Meta);
+ *   meta({ title: "Product Details" });
+ *   meta({ name: "description", content: "..." });
+ *   meta({ property: "og:title", content: "..." });
+ * });
+ *
+ * // In layout (renders the collected meta tags)
+ * function RootLayout() {
+ *   return (
+ *     <html>
+ *       <head>
+ *         <MetaTags />
+ *       </head>
+ *       ...
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+import { type Handle } from "../handle.js";
+import type { MetaDescriptor } from "../router/types.js";
+/**
+ * Built-in handle for managing document metadata.
+ *
+ * Use `ctx.use(Meta)` in route handlers to push meta descriptors.
+ * Use `<MetaTags />` component to render them in the document head.
+ *
+ * Deferred (Promise) descriptors are resolved before collectMeta runs
+ * (resolve-by-default), so they participate in deduplication and `%s`
+ * title-templating identically to synchronous descriptors. A descriptor that
+ * resolves to `null`/`undefined` (or rejects) is dropped.
+ */
+export declare const Meta: Handle<MetaDescriptor, MetaDescriptor[]>;