@rangojs/router 0.4.0 → 0.4.1

package/dist/types.backup/urls/pattern-types.d.ts

@@ -1,166 +0,0 @@
-import type { TrailingSlashMode } from "../types.js";
-import type { AllUseItems, UrlPatternsBrand } from "../route-types.js";
-import type { SearchSchema } from "../search-params.js";
-import { RESPONSE_TYPE } from "./response-types.js";
-import type { DefaultEnv } from "../types.js";
-import type { PathHelpers } from "./path-helper-types.js";
-/**
- * Builder function accepted by urls() and as a shorthand for routes()/urls option.
- * When passed directly to routes() or createRouter({ urls }), it is wrapped in urls() automatically.
- */
-export type UrlBuilder<TEnv = DefaultEnv, TItems extends readonly (AllUseItems | readonly AllUseItems[])[] = readonly AllUseItems[]> = (helpers: PathHelpers<TEnv>) => TItems;
-/**
- * Sentinel type for unnamed routes.
- * Using a branded string instead of `never` prevents TypeScript from
- * widening array type inference when mixing named and unnamed routes.
- */
-export type UnnamedRoute = "$unnamed";
-/**
- * Sentinel type for include() mounts that stay local to the mounted module.
- * This keeps child route names out of the parent/global type map while still
- * allowing the mounted module to use its own local route names internally.
- *
- * Branded with a symbol key so it cannot be accidentally produced by user code.
- */
-declare const LOCAL_ONLY_BRAND: unique symbol;
-export type LocalOnlyInclude = string & {
-    [LOCAL_ONLY_BRAND]: void;
-};
-/**
- * Options for path() function
- */
-/**
- * Options for the `ppr` path option (PPR shell caching — Axis 2, see
- * docs/design/ppr-shell-resume.md and the /ppr skill). Declaring
- * `ppr: true | PartialPrerenderProps` on a page route opts that DOCUMENT into
- * shell capture: the rendered HTML shell (everything that is not a live hole) is
- * cached and, on a later GET, flushed immediately while fizz resumes only the
- * holes. Serving is integral to the router — there is no middleware to mount;
- * the shell store is the app-level `createRouter({ cache })` store (which must
- * implement the `getShell`/`putShell` family).
- */
-export interface PartialPrerenderProps {
-    /**
-     * Shell time-to-live in seconds. Defaults to 300 (`ppr: true` uses the same
-     * default).
-     */
-    ttl?: number;
-    /**
-     * Stale-while-revalidate window in seconds: a stale shell is still served
-     * while a background recapture refreshes it.
-     */
-    swr?: number;
-    /**
-     * Operational tags attached to the captured shell entry for
-     * `updateTag()`/`revalidateTag()`-driven eviction. UNIONED with the tags the
-     * capture render auto-collects (the shell's own non-loader request tags).
-     */
-    tags?: string[];
-    /**
-     * Upper bound (serialized UTF-8 bytes) on the capture data snapshot riding
-     * inside the shell entry. The snapshot duplicates every cache-store value
-     * the capture pinned, so a page over a large cache() segment can push the
-     * entry toward store value limits (Cloudflare KV caps a value at 25 MiB).
-     * Over the cap the snapshot is skipped: the shell is still stored and
-     * served, but pinned reads fall back to the live store, so drifted cached
-     * content can hydration-mismatch and be repaired client-side (the
-     * pre-snapshot behavior). Reported once per key. Defaults to 8 MiB.
-     */
-    maxSnapshotBytes?: number;
-    /**
-     * Capture settle budget in MILLISECONDS (default 15000). Bounds the whole
-     * background capture: the wait for deferred shell material — top-level
-     * pushed handle promises (`ctx.use(Meta)(promise.then(...))` and friends)
-     * are AWAITED and their settled values baked into the stored shell — AND
-     * the fizz prerender deadline. Declare it to tighten the budget below the
-     * default or when a route's shell material takes longer than 15s to
-     * settle. A budget that expires with pushes still pending REFUSES the
-     * capture (the route stays MISS with the once-per-key warning) — a shell
-     * with missing head material is never stored. Capture is background work
-     * (waitUntil), so a longer budget costs latency-to-HIT only, never a served
-     * response; the platform waitUntil lifetime (workerd: ~30s past response
-     * completion) is the physical ceiling — the default's derivation lives in
-     * docs/design/ppr-shell-resume.md (Cost model). Build-time captures
-     * (Prerender+ppr, producer B) honor the same budget with no platform
-     * ceiling. Non-finite or sub-1ms values fall back to the default.
-     */
-    captureTimeout?: number;
-}
-export interface PathOptions<TName extends string = string, TSearch extends SearchSchema = {}> {
-    /** Route name for href() lookups */
-    name?: TName;
-    /**
-     * PPR shell caching opt-in for this page route (document-level). `true` uses
-     * the default policy (ttl 300); an object sets ttl/swr/tags. See
-     * {@link PartialPrerenderProps}. Routes without this option are pure axis 1 —
-     * no capture, no store reads, no logs.
-     */
-    ppr?: boolean | PartialPrerenderProps;
-    /** Search param schema for typed query parameters */
-    search?: TSearch;
-    /** Trailing slash behavior: "never" (redirect /path/ to /path), "always" (redirect /path to /path/), "ignore" (match both) */
-    trailingSlash?: TrailingSlashMode;
-    /** Response type marker (set by path.json(), etc.) */
-    [RESPONSE_TYPE]?: string;
-}
-/**
- * Result of urls() - contains the route definitions
- */
-export interface UrlPatterns<TEnv = any, TRoutes extends Record<string, any> = Record<string, string>, TResponses extends Record<string, unknown> = Record<string, unknown>> {
-    /** Internal: compiled handler function */
-    readonly handler: () => AllUseItems[];
-    /** Internal: trailing slash config per route name */
-    readonly trailingSlash: Record<string, TrailingSlashMode>;
-    /** Brand for type checking */
-    readonly [UrlPatternsBrand]: void;
-    /** Environment type brand (phantom) */
-    readonly _env?: TEnv;
-    /** Routes type brand (phantom) - carries route name -> pattern mapping */
-    readonly _routes?: TRoutes;
-    /** Responses type brand (phantom) - carries route name -> response data type mapping */
-    readonly _responses?: TResponses;
-}
-/**
- * Extract the phantom env type carried by a UrlPatterns value.
- */
-export type UrlPatternsEnv<T> = T extends UrlPatterns<infer TEnv, any, any> ? TEnv : never;
-/**
- * Guards `routes()` env compatibility without over-constraining.
- *
- * - An env-agnostic block (its env is `unknown` — e.g. a shared urls() module,
- *   or an app that does not augment `Rango.Env`) attaches to any router.
- * - A block carrying a concrete env is accepted only when the router env
- *   (`TRouterEnv`) satisfies it; resolves to `never` otherwise, so a
- *   `urls<{ DB: D1Database }>()` cannot be mounted on a `createRouter<{}>()`.
- *
- * Use as `patterns: T & EnvCompatible<T, TEnv>` so `T` still infers from the
- * argument — a bare `EnvCompatible<T, TEnv>` parameter sits in a non-inferrable
- * conditional position and would collapse `T` to its constraint.
- *
- * Known limitation: `TRouterEnv extends ...` distributes over a union router env,
- * so a `urls<A>()` block is accepted on `createRouter<A | B>()` even though the
- * `B` arm cannot supply `A`'s env. Suppressing distribution with
- * `[TRouterEnv] extends [...]` would close that edge but breaks the common
- * generic-`TEnv` call sites (a deferred type parameter can't resolve the tuple
- * conditional, so the intersection stops reducing to `T`). A router has one env,
- * so a union env is not a supported pattern; the distributive form is kept.
- */
-export type EnvCompatible<TPatterns, TRouterEnv> = unknown extends UrlPatternsEnv<TPatterns> ? TPatterns : TRouterEnv extends UrlPatternsEnv<TPatterns> ? TPatterns : never;
-/**
- * Options for include()
- */
-export interface IncludeOptions<TNamePrefix extends string = string> {
-    /**
-     * Name prefix for all routes in this pattern set.
-     *
-     * - `{ name: "blog" }` — children become `blog.index`, `blog.detail`, etc.
-     *   Visible in generated route types and resolvable globally via `reverse("blog.index")`.
-     * - `{ name: "" }` — children merge into the parent namespace with no prefix.
-     *   Equivalent to defining the routes inline at the include site.
-     * - Omitted — children live in a private local scope, hidden from the
-     *   generated route map and global reverse resolution. Only dot-local
-     *   reverse (e.g. `reverse(".child")`) works from inside the module.
-     */
-    name?: TNamePrefix;
-}
-export {};

package/dist/types.backup/urls/response-types.d.ts

@@ -1,67 +0,0 @@
-import type { ContextVar } from "../context-var.js";
-import type { ReverseFunction } from "../reverse.js";
-import type { DefaultReverseRouteMap, DefaultVars } from "../types/global-namespace.js";
-import type { UseItems, ResponseRouteUseItem } from "../route-types.js";
-import type { RequestScope } from "../types/request-scope.js";
-/**
- * Reverse function for response handler contexts.
- * Global names get autocomplete and param validation from the generated route map.
- * Local `.name` calls are accepted but not validated (scope unknown at type level).
- */
-type ResponseReverseFunction = [DefaultReverseRouteMap] extends [
-    Record<string, string>
-] ? (name: string, params?: Record<string, string>, search?: Record<string, unknown>) => string : ReverseFunction<DefaultReverseRouteMap> & {
-    (name: `.${string}`, params?: Record<string, string>, search?: Record<string, unknown>): string;
-};
-/**
- * Symbol marking a route as a response route (non-RSC).
- * Stored on PathOptions and UrlPatterns to signal the trie to short-circuit.
- */
-export declare const RESPONSE_TYPE: unique symbol;
-/**
- * Shared shape of a response-route handler: a function returning TReturn (or a
- * promise of it), plus an optional composable `use` thunk merged at mount time.
- */
-type ResponseHandlerOf<TReturn, TParams = Record<string, string>, TEnv = any> = ((ctx: ResponseHandlerContext<TParams, TEnv>) => TReturn | Promise<TReturn>) & {
-    /** Composable default DSL items merged when the handler is mounted. */
-    use?: () => UseItems<ResponseRouteUseItem>;
-};
-/**
- * Handler that must return Response (not ReactNode).
- * Used by path.image(), path.stream(), path.any() (binary/streaming data).
- */
-export type ResponseHandler<TParams = Record<string, string>, TEnv = any> = ResponseHandlerOf<Response, TParams, TEnv>;
-/**
- * JSON-serializable value type for auto-wrap support.
- */
-export type JsonValue = string | number | boolean | null | JsonValue[] | {
-    [key: string]: JsonValue;
-};
-/**
- * Handler for JSON response routes.
- * Can return a plain JSON-serializable value (auto-wrapped) or Response (pass-through).
- */
-export type JsonResponseHandler<TParams = Record<string, string>, TEnv = any> = ResponseHandlerOf<JsonValue | Response, TParams, TEnv>;
-/**
- * Handler for text-based response routes (text, html, xml).
- * Can return a string (auto-wrapped) or Response (pass-through).
- */
-export type TextResponseHandler<TParams = Record<string, string>, TEnv = any> = ResponseHandlerOf<string | Response, TParams, TEnv>;
-/**
- * Lighter handler context for response routes.
- * No ctx.use() (no loaders). Supports setting response headers via ctx.header().
- * Use the standalone cookies() function for cookie mutations.
- */
-export interface ResponseHandlerContext<TParams = Record<string, string>, TEnv = any> extends RequestScope<TEnv> {
-    params: TParams;
-    /** @internal Phantom property for params type invariance. Prevents mounting handlers on wrong routes. */
-    readonly _paramCheck?: (params: TParams) => TParams;
-    reverse: ResponseReverseFunction;
-    /** Read a variable set by middleware via ctx.set(key, value) or ctx.set(ContextVar, value). */
-    get: {
-        <T>(contextVar: ContextVar<T>): T | undefined;
-    } & (<K extends keyof DefaultVars>(key: K) => DefaultVars[K]);
-    /** Set a response header. Merged into the auto-wrapped or pass-through Response. */
-    header: (name: string, value: string) => void;
-}
-export {};

package/dist/types.backup/urls/type-extraction.d.ts

@@ -1,157 +0,0 @@
-import type { JsonSerialize } from "../serialize.js";
-import type { TypedRouteItem, TypedIncludeItem, TypedLayoutItem, TypedCacheItem, TypedTransitionItem } from "../route-types.js";
-import type { LocalOnlyInclude, UnnamedRoute } from "./pattern-types.js";
-/**
- * Prefix route names with a given prefix (e.g., "blog" + "post" = "blog.post")
- *
- * Filters out plain `string` index signatures to prevent dynamically-generated
- * routes from poisoning the route map. When TypeScript encounters very large
- * route sets (5000+ routes via Array.from), it may give up computing specific
- * types and fall back to Record<string, string>. Without filtering, PrefixRoutes
- * would map `string` to `${prefix}.${string}`, creating an index signature that
- * accepts ANY prefixed name and defeats type-safe route checking.
- *
- * Uses `string extends K` (conservative filter):
- * - Drops `string` keys (TypeScript fallback) -> prevents `[x: `site.${string}`]`
- * - Keeps template literal patterns like `item${number}` from Array.from loops,
- *   which are imprecise but still allow writing paths like `/shop/product/1`
- *
- * A more aggressive alternative (`{} extends Record<K, 1>`) would also drop
- * template literal patterns. We chose conservative because loop-generated routes
- * with `${number}` patterns still provide some value: they don't appear in
- * named-routes.gen.ts or IDE autocomplete, but they do let you manually write
- * valid paths without type errors.
- */
-type PrefixRoutes<TRoutes extends Record<string, any>, TPrefix extends string> = TPrefix extends "" ? TRoutes : {
-    [K in keyof TRoutes as K extends string ? string extends K ? never : `${TPrefix}.${K}` : never]: TRoutes[K];
-};
-/**
- * Prefix route patterns with a URL prefix (e.g., "/blog" + "/:slug" = "/blog/:slug")
- */
-type PrefixPatterns<TRoutes extends Record<string, any>, TUrlPrefix extends string> = {
-    [K in keyof TRoutes]: TRoutes[K] extends string ? `${TUrlPrefix}${TRoutes[K]}` : TRoutes[K] extends {
-        readonly path: infer P extends string;
-        readonly search: infer S;
-    } ? {
-        readonly path: `${TUrlPrefix}${P}`;
-        readonly search: S;
-    } : TRoutes[K];
-};
-/**
- * Convert a union type to an intersection type.
- * Used to combine route maps from multiple siblings without recursive tuple processing.
- */
-type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
-/**
- * Extract routes from a single item (path, include, layout, cache with children)
- */
-type ExtractRoutesFromItem<T> = T extends TypedRouteItem<infer TName, infer TPattern, any, infer TSearch> ? TName extends string ? string extends TName ? {} : TName extends UnnamedRoute ? {} : {} extends TSearch ? {
-    [K in TName]: TPattern;
-} : {
-    [K in TName]: {
-        readonly path: TPattern;
-        readonly search: TSearch;
-    };
-} : {} : T extends TypedIncludeItem<infer TRoutes, infer TNamePrefix, infer TUrlPrefix> ? TNamePrefix extends LocalOnlyInclude ? {} : TNamePrefix extends string ? TUrlPrefix extends string ? PrefixRoutes<PrefixPatterns<TRoutes, TUrlPrefix>, TNamePrefix> : PrefixRoutes<TRoutes, TNamePrefix> : TUrlPrefix extends string ? PrefixPatterns<TRoutes, TUrlPrefix> : TRoutes : T extends TypedLayoutItem<infer TChildRoutes> ? TChildRoutes : T extends TypedCacheItem<infer TChildRoutes> ? TChildRoutes : T extends TypedTransitionItem<infer TChildRoutes> ? TChildRoutes : {};
-/**
- * Extract routes from an array of items using mapped types.
- * Uses UnionToIntersection to combine routes without recursive tuple processing,
- * removing the sibling limit that was caused by TypeScript recursion limits.
- */
-type ExtractRoutesFromItems<T extends readonly any[]> = T extends readonly any[] ? UnionToIntersection<{
-    [K in keyof T]: ExtractRoutesFromItem<T[K]>;
-}[number]> extends infer R ? [
-    R
-] extends [never] ? {} : R extends Record<string, any> ? R : {} : {} : {};
-/**
- * Main utility: extract route map from urls() callback return type
- * Uses mapped types for sibling processing (no sibling limit).
- */
-export type ExtractRoutes<T extends readonly any[]> = ExtractRoutesFromItems<T>;
-/**
- * Prefix keys of a Record<string, unknown> with a dot-separated prefix.
- * Used for response type maps through include().
- * Same index signature filter as PrefixRoutes (see comment there).
- */
-type PrefixKeys<T extends Record<string, unknown>, TPrefix extends string> = TPrefix extends "" ? T : {
-    [K in keyof T as K extends string ? string extends K ? never : `${TPrefix}.${K}` : never]: T[K];
-};
-/**
- * Extract response data types from a single item.
- * Parallel to ExtractRoutesFromItem but extracts name -> TData mapping.
- */
-type ExtractResponsesFromItem<T> = T extends TypedRouteItem<infer TName, any, infer TData> ? TName extends string ? string extends TName ? {} : TName extends UnnamedRoute ? {} : {
-    [K in TName]: TData;
-} : {} : T extends TypedIncludeItem<any, infer TNamePrefix, any, infer TResponses> ? TNamePrefix extends LocalOnlyInclude ? {} : TNamePrefix extends string ? TResponses extends Record<string, unknown> ? PrefixKeys<TResponses, TNamePrefix> : {} : TResponses extends Record<string, unknown> ? TResponses : {} : T extends TypedLayoutItem<any, infer TChildResponses> ? TChildResponses extends Record<string, unknown> ? TChildResponses : {} : T extends TypedCacheItem<any, infer TChildResponses> ? TChildResponses extends Record<string, unknown> ? TChildResponses : {} : T extends TypedTransitionItem<any, infer TChildResponses> ? TChildResponses extends Record<string, unknown> ? TChildResponses : {} : {};
-/**
- * Extract responses from an array of items using mapped types.
- * Parallel to ExtractRoutesFromItems.
- */
-type ExtractResponsesFromItems<T extends readonly any[]> = T extends readonly any[] ? UnionToIntersection<{
-    [K in keyof T]: ExtractResponsesFromItem<T[K]>;
-}[number]> extends infer R ? [
-    R
-] extends [never] ? {} : R extends Record<string, unknown> ? R : {} : {} : {};
-/**
- * Main utility: extract response data type map from urls() callback return type.
- * Parallel to ExtractRoutes.
- */
-export type ExtractResponses<T extends readonly any[]> = ExtractResponsesFromItems<T>;
-/**
- * RFC 9457 (problem+json) error body returned by JSON response routes on a
- * non-2xx status. Sent verbatim as the response body (not wrapped) with
- * content-type `application/problem+json`.
- *
- * @example
- * ```typescript
- * const res = await fetch(url);
- * if (!res.ok) {
- *   const problem: ProblemDetails = await res.json();
- *   console.log(problem.code, problem.detail); // "NOT_FOUND", "Product not found"
- *   return;
- * }
- * const product = await res.json(); // bare value, no envelope
- * ```
- */
-export interface ProblemDetails {
-    /**
-     * URI reference identifying the problem type. Omitted in this phase (per RFC
-     * 9457 an absent `type` is treated as `"about:blank"` — no semantics beyond
-     * the HTTP status); per-route problem-type URIs arrive with the
-     * declared-errors map later.
-     */
-    type?: string;
-    /** Short, human-readable summary (the HTTP status reason phrase). */
-    title: string;
-    /** The HTTP status code. */
-    status: number;
-    /** Human-readable explanation specific to this occurrence (the error message). */
-    detail: string;
-    /** Stable machine-readable error code (`RouterError.code`, else `"INTERNAL"`). */
-    code: string;
-    /** Stack trace, included in development only. */
-    stack?: string;
-}
-/**
- * Extract the JSON response payload type for a named route from a UrlPatterns
- * instance. JSON response routes send the handler's return value verbatim
- * (bare), so this resolves to the wire value a consumer receives — no envelope.
- *
- * @example
- * ```typescript
- * const apiPatterns = urls(({ path }) => [
- *   path.json("/health", (ctx) => ({ status: "ok", timestamp: Date.now() }), { name: "health" }),
- * ]);
- *
- * type HealthData = RouteResponse<typeof apiPatterns, "health">;
- * // { status: string; timestamp: number }
- * ```
- *
- * The payload is the JSON wire shape (via `Rango.JsonSerialize`), matching
- * `Rango.PathResponse` and what `fetch().then(r => r.json())` actually yields —
- * e.g. a `Date` field resolves as `string`.
- */
-export type RouteResponse<TPatterns, TName extends string> = TPatterns extends {
-    readonly _responses?: infer R;
-} ? TName extends keyof R ? JsonSerialize<Exclude<R[TName], Response>> : never : never;
-export {};

package/dist/types.backup/urls/urls-function.d.ts

@@ -1,24 +0,0 @@
-import type { DefaultEnv } from "../types.js";
-import type { AllUseItems } from "../route-types.js";
-import type { UrlPatterns } from "./pattern-types.js";
-import type { PathHelpers } from "./path-helper-types.js";
-import type { ExtractRoutes, ExtractResponses } from "./type-extraction.js";
-/**
- * Define URL patterns with Django-inspired syntax
- *
- * Replaces map() as the entry point for route definitions.
- * URL patterns are now visible at the definition site via path().
- *
- * @example
- * ```typescript
- * export const blogPatterns = urls(({ path, layout, loader }) => [
- *   layout(BlogLayout, () => [
- *     path("/", BlogIndex, { name: "index" }),
- *     path("/:slug", BlogPost, { name: "post" }, () => [
- *       loader(PostLoader),
- *     ]),
- *   ]),
- * ]);
- * ```
- */
-export declare function urls<TEnv = DefaultEnv, const TItems extends readonly (AllUseItems | readonly AllUseItems[])[] = readonly AllUseItems[]>(builder: (helpers: PathHelpers<TEnv>) => TItems): UrlPatterns<TEnv, ExtractRoutes<TItems>, ExtractResponses<TItems>>;

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

@@ -1 +0,0 @@
-export * from "./urls/index.js";

package/dist/types.backup/use-loader.d.ts

@@ -1,150 +0,0 @@
-import type { LoaderDefinition, LoadOptions } from "./types.js";
-export type LoadFunction<T> = (options?: LoadOptions) => Promise<T>;
-export interface UseLoaderResult<T> {
-    data: T;
-    isLoading: boolean;
-    error: Error | null;
-    load: LoadFunction<T>;
-    refetch: LoadFunction<T>;
-}
-export interface UseFetchLoaderResult<T> {
-    data: T | undefined;
-    isLoading: boolean;
-    error: Error | null;
-    load: LoadFunction<T>;
-    refetch: LoadFunction<T>;
-}
-export interface UseLoaderOptions {
-    throwOnError?: boolean;
-    key?: string;
-    refreshGroup?: string | string[];
-}
-/**
- * Hook to access loader data from route context (strict version)
- *
- * Use this when the loader is registered on the route via `loader()`.
- * The data is guaranteed to exist - throws an error if not found.
- *
- * For on-demand fetching or when loader might not be in context,
- * use `useFetchLoader` instead.
- *
- * @param loader - The loader definition (must be registered on route)
- * @param options - Optional configuration
- * @returns Object with data (guaranteed), isLoading, error, load, and refetch
- * @throws Error if loader data is not found in context
- *
- * @example Basic usage - accessing route loader data
- * ```tsx
- * "use client";
- * import { useLoader } from "rsc-router/client";
- * import { CartLoader } from "../loaders/cart";
- *
- * // In route definition: loader(CartLoader)
- *
- * export function CartIcon() {
- *   const { data } = useLoader(CartLoader);
- *   // data is guaranteed to be CartData, not CartData | undefined
- *   return <span>Cart ({data.items.length})</span>;
- * }
- * ```
- */
-export declare function useLoader<T>(loader: LoaderDefinition<T>, options?: UseLoaderOptions): UseLoaderResult<Rango.FlightSerialize<T>>;
-/**
- * Hook to access loader data with optional fetching (flexible version)
- *
- * Use this when:
- * - The loader might not be registered on the route
- * - You want to fetch data on-demand from the client
- * - You're building a reusable component that doesn't assume route context
- *
- * If the loader IS registered on the route, it will still get the initial
- * data from context - you just have to handle the `undefined` case in types.
- *
- * @param loader - The loader definition
- * @param options - Optional configuration
- * @returns Object with data (may be undefined), isLoading, error, load, and refetch
- *
- * @example On-demand fetching
- * ```tsx
- * "use client";
- * import { useFetchLoader } from "rsc-router/client";
- * import { SearchLoader } from "../loaders/search";
- *
- * export function SearchResults() {
- *   const { data, load, isLoading } = useFetchLoader(SearchLoader);
- *
- *   const handleSearch = async (query: string) => {
- *     await load({ params: { query } });
- *   };
- *
- *   return (
- *     <div>
- *       <button onClick={() => handleSearch("test")}>Search</button>
- *       {isLoading && <span>Loading...</span>}
- *       {data?.results.map(r => <div key={r.id}>{r.name}</div>)}
- *     </div>
- *   );
- * }
- * ```
- *
- * @example With route context (hybrid usage)
- * ```tsx
- * // Loader registered on route: loader(UserLoader)
- * // useFetchLoader still works - gets initial data from context
- * const { data, load } = useFetchLoader(UserLoader);
- * // data is UserData | undefined (even though it will have initial value)
- * ```
- */
-export declare function useFetchLoader<T>(loader: LoaderDefinition<T>, options?: UseLoaderOptions): UseFetchLoaderResult<Rango.FlightSerialize<T>>;
-/**
- * Get a stable function that refreshes loaders by cross-loader group tag.
- *
- * The returned `refresh(groups)` takes one group name or an array of names and
- * re-runs every currently-mounted read tagged with ANY of them, with a plain GET
- * against the current route URL. This is the cross-loader counterpart to the
- * single-loader `key`: use it to refresh a set of DIFFERENT loaders together
- * (e.g. profile + orders after an account switch). Members are tagged via
- * `useLoader(Loader, { refreshGroup })` / `useFetchLoader(Loader, { refreshGroup })`,
- * where `refreshGroup` is one name or several.
- *
- * Passing the group(s) to the returned function rather than to the hook lets a
- * single `useRefreshLoaders()` instance refresh different groups depending on
- * context, and lets one call refresh several groups at once — their members are
- * unioned and deduped, so a loader tagged into two of the named groups is fetched
- * exactly once.
- *
- * Group refresh never render-throws: a failing member surfaces its error via
- * that read's `error` state, and the returned promise rejects with an
- * `AggregateError` of the failures so the caller can handle them at the await
- * site. Each loader is refreshed in place — no params, no body, no mutations.
- *
- * @example
- * ```tsx
- * "use client";
- * import { useLoader, useRefreshLoaders } from "rsc-router/client";
- *
- * function Profile() {
- *   const { data } = useLoader(ProfileLoader, { key: userId, refreshGroup: "account" });
- *   return <span>{data.name}</span>;
- * }
- * function Orders() {
- *   // Tagged into two groups: refreshed by "account" (the whole set) or "orders".
- *   const { data } = useLoader(OrdersLoader, {
- *     key: userId,
- *     refreshGroup: ["account", "orders"],
- *   });
- *   return <span>{data.count} orders</span>;
- * }
- * function RefreshButtons() {
- *   const refresh = useRefreshLoaders();
- *   return (
- *     <>
- *       <button onClick={() => refresh("account")}>Refresh account</button>
- *       <button onClick={() => refresh("orders")}>Refresh orders</button>
- *       <button onClick={() => refresh(["account", "orders"])}>Refresh both</button>
- *     </>
- *   );
- * }
- * ```
- */
-export declare function useRefreshLoaders(): (groups: string | string[]) => Promise<void>;

package/dist/types.backup/vercel/index.d.ts

@@ -1,10 +0,0 @@
-/**
- * Vercel preset integration surface for @rangojs/router.
- *
- * Imported via `@rangojs/router/vercel`. Vercel-only helpers live here so
- * Node/other-platform consumers never pull them in. The Vercel cache store
- * (`VercelCacheStore`) is exported from `@rangojs/router/cache`, mirroring the
- * Cloudflare split where the store lives in `/cache` and the tracing helper in
- * the platform subpath.
- */
-export { createVercelTracing, type VercelTracingOptions } from "./tracing.js";

package/dist/types.backup/vercel/tracing.d.ts

@@ -1,70 +0,0 @@
-/**
- * Vercel OpenTelemetry tracing integration.
- *
- * Bridges the router's performance phases (request, middleware, action,
- * loaders, handler, render, ssr) onto OpenTelemetry spans so they show up in
- * Vercel's trace waterfall next to the platform's automatic spans, with correct
- * nesting. Vercel exposes tracing through OpenTelemetry (not a native import-free
- * API like Cloudflare), so this is a thin convenience over `createOTelTracing`:
- * it reads the global OTel tracer that `@vercel/otel`'s `registerOTel()` installs.
- *
- * Usage (vercel preset). A Rango/Vite app does NOT auto-load `instrumentation.ts`
- * the way Next.js does, so export the tracing config from there and import it —
- * the import is what runs `registerOTel()`. A standalone `registerOTel()` that
- * nothing imports is a silent no-op (the tracer never registers, spans drop):
- *
- *   // instrumentation.ts
- *   import { registerOTel } from "@vercel/otel";
- *   import { createVercelTracing } from "@rangojs/router/vercel";
- *   registerOTel({ serviceName: "my-app" });
- *   export const tracing = createVercelTracing();
- *
- *   // router.tsx — importing `tracing` runs instrumentation.ts (and registerOTel)
- *   import { createRouter } from "@rangojs/router";
- *   import { tracing } from "./instrumentation.js";
- *   export const router = createRouter({ tracing });
- *
- * Two runtime caveats inherited from the platform:
- *   - Node.js runtime only. Vercel custom spans are unsupported on the Edge
- *     runtime; `startActiveSpan` also needs an AsyncLocalStorage context manager
- *     (which @vercel/otel configures on Node) for spans to nest correctly.
- *   - `registerOTel()` must run before the first request. Reading the tracer via
- *     `trace.getTracer` here is safe even if it runs first — the API's proxy
- *     tracer delegates to the provider once registered — but no provider means
- *     every span is a no-op (the request behaves exactly as if tracing were off).
- *
- * Whether spans are actually exported is governed by your OTel setup / Vercel
- * tracing destination, not by this adapter.
- */
-import { type OTelActiveSpanTracer } from "../router/telemetry-otel.js";
-import type { RouterTracingConfig, TracingToggleOptions } from "../router/tracing.js";
-/**
- * Options for createVercelTracing. Extends the shared
- * {@link TracingToggleOptions} (`enabled` + per-phase `spans`) with the
- * Vercel-specific tracer selectors.
- */
-export interface VercelTracingOptions extends TracingToggleOptions {
-    /**
-     * OTel instrumentation-scope name passed to `trace.getTracer()`. Defaults to
-     * `"rango"`. Ignored when `tracer` is provided.
-     */
-    tracerName?: string;
-    /**
-     * Explicit tracer override. Defaults to the global OTel tracer
-     * (`trace.getTracer(tracerName)`) — the provider `@vercel/otel`'s
-     * `registerOTel()` installs. Pass this to bridge onto a tracer you own.
-     */
-    tracer?: OTelActiveSpanTracer;
-}
-/**
- * Create the tracing config for a Vercel router. Pass the result to
- * `createRouter({ tracing })`. Spans are emitted for the request, middleware,
- * action, loaders, handler, render, and ssr phases; pass `spans` to turn
- * individual phases off.
- *
- * @see createOTelTracing (`@rangojs/router`) for the underlying adapter on any
- *   platform with an OpenTelemetry SDK.
- * @see createCloudflareTracing (`@rangojs/router/cloudflare`) for the same slot
- *   using Cloudflare Workers native custom spans.
- */
-export declare function createVercelTracing(options?: VercelTracingOptions): RouterTracingConfig;