@rangojs/router 0.4.0 → 0.4.2

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

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

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

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

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

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

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

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

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

@@ -1,43 +0,0 @@
-/**
- * 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[]>;