@rangojs/router 0.5.1 → 0.6.0

package/dist/types.backup/types/cache-types.d.ts

@@ -1,191 +0,0 @@
-/**
- * Context passed to cache condition/key/tags functions.
- *
- * This is a subset of RequestContext that's guaranteed to be available
- * during cache key generation (before middleware runs).
- *
- * Note: While the full RequestContext is passed, middleware-set variables
- * read via `ctx.get()` may not be populated yet since cache lookup happens
- * before middleware execution.
- */
-export type { RequestContext as CacheContext } from "../server/request-context.js";
-/**
- * Cache configuration options for cache() DSL
- *
- * Controls how segments, layouts, and loaders are cached.
- * Cache configuration inherits down the route tree unless overridden.
- *
- * @example
- * ```typescript
- * // Basic caching with TTL
- * cache({ ttl: 60 }, () => [
- *   layout(<BlogLayout />),
- *   route("post/:slug"),
- * ])
- *
- * // With stale-while-revalidate
- * cache({ ttl: 60, swr: 300 }, () => [
- *   route("product/:id"),
- * ])
- *
- * // Conditional caching
- * cache({
- *   ttl: 300,
- *   condition: (ctx) => !ctx.request.headers.get('x-preview'),
- * }, () => [...])
- *
- * // Custom cache key
- * cache({
- *   ttl: 300,
- *   key: (ctx) => `product-${ctx.params.id}-${ctx.searchParams.get('variant')}`,
- * }, () => [...])
- *
- * // With tags for invalidation
- * cache({
- *   ttl: 300,
- *   tags: (ctx) => [`product:${ctx.params.id}`, 'products'],
- * }, () => [...])
- * ```
- */
-export interface CacheOptions<TEnv = unknown> {
-    /**
-     * Time-to-live in seconds.
-     * After this period, cached content is considered stale.
-     */
-    ttl: number;
-    /**
-     * Stale-while-revalidate window in seconds (after TTL).
-     * During this window, stale content is served immediately while
-     * fresh content is fetched in the background via waitUntil.
-     *
-     * @example
-     * // TTL: 60s, SWR: 300s
-     * // 0-60s: FRESH (serve from cache)
-     * // 60-360s: STALE (serve from cache, revalidate in background)
-     * // 360s+: EXPIRED (cache miss, fetch fresh)
-     */
-    swr?: number;
-    /**
-     * Override the cache store for this boundary.
-     * When specified, this boundary and its children use this store
-     * instead of the app-level store from handler config.
-     *
-     * Useful for:
-     * - Different backends per route section (memory vs KV vs Redis)
-     * - Loader-specific caching strategies
-     * - Hot data in fast cache, cold data in larger/slower cache
-     *
-     * Tag invalidation caveat: a per-boundary store becomes reachable by
-     * `updateTag()` / `revalidateTag()` once this boundary is resolved in the
-     * current process. If the store is *durable* (shared across processes) and the
-     * very first request to a fresh worker is an `updateTag`/`revalidateTag` for a
-     * tag held only in this store - before this boundary is matched - that
-     * invalidation can miss it. For data you invalidate by tag, prefer the
-     * app-level store (always reachable), or ensure the boundary is warmed.
-     *
-     * @example
-     * ```typescript
-     * const kvStore = new CloudflareKVStore(env.CACHE_KV);
-     * const memoryStore = new MemorySegmentCacheStore({ defaults: { ttl: 10 } });
-     *
-     * // Fast memory cache for hot data
-     * cache({ store: memoryStore }, () => [
-     *   route("dashboard"),
-     * ])
-     *
-     * // KV for larger, less frequently accessed data
-     * cache({ store: kvStore, ttl: 3600 }, () => [
-     *   route("archive/:year"),
-     * ])
-     * ```
-     */
-    store?: import("../cache/types.js").SegmentCacheStore;
-    /**
-     * Conditional cache read function.
-     * Return false to skip cache for this request (always fetch fresh).
-     *
-     * Has access to full RequestContext including env, request, params, cookies, etc.
-     * Note: Middleware-set variables read via `ctx.get()` may not be populated yet.
-     *
-     * @example
-     * ```typescript
-     * condition: (ctx) => {
-     *   // Skip cache for preview mode
-     *   if (ctx.request.headers.get('x-preview')) return false;
-     *   // Skip cache for authenticated users
-     *   if (ctx.request.headers.has('authorization')) return false;
-     *   return true;
-     * }
-     * ```
-     */
-    condition?: (ctx: import("../server/request-context.js").RequestContext<TEnv>) => boolean;
-    /**
-     * Custom cache key function - FULL OVERRIDE.
-     * Bypasses default key generation AND store's keyGenerator.
-     *
-     * Has access to full RequestContext including env, request, params, cookies, etc.
-     * Note: Middleware-set variables read via `ctx.get()` may not be populated yet.
-     *
-     * @example
-     * ```typescript
-     * // Include query params in cache key
-     * key: (ctx) => `product-${ctx.params.id}-${ctx.searchParams.get('variant')}`
-     *
-     * // Include env bindings
-     * key: (ctx) => `${ctx.env.REGION}:product:${ctx.params.id}`
-     *
-     * // Include cookies
-     * key: (ctx) => `${cookies().get('locale')?.value ?? 'en'}:${ctx.pathname}`
-     * ```
-     */
-    key?: (ctx: import("../server/request-context.js").RequestContext<TEnv>) => string | Promise<string>;
-    /**
-     * Tags for cache invalidation.
-     * Can be a static array or a function that returns tags.
-     *
-     * The built-in `MemorySegmentCacheStore` and `CFCacheStore` index by tag.
-     * Invalidate on demand with `updateTag(...tags)` (awaitable, read-your-own-writes;
-     * for server actions) or `revalidateTag(...tags)` (background hard-purge, not
-     * awaited; for route handlers / webhooks). For `CFCacheStore`, distributed
-     * invalidation requires a `kv` namespace (markers live in that same namespace).
-     *
-     * @example
-     * ```typescript
-     * // Static tags
-     * tags: ['products', 'catalog']
-     *
-     * // Dynamic tags
-     * tags: (ctx) => [`product:${ctx.params.id}`, 'products']
-     * ```
-     */
-    tags?: string[] | ((ctx: import("../server/request-context.js").RequestContext<TEnv>) => string[]);
-}
-/**
- * Partial cache options for cache() DSL.
- *
- * When `ttl` is not specified, it will use the default from cache config.
- * This allows cache() calls to inherit app-level defaults:
- *
- * @example
- * ```typescript
- * // App-level default (in handler config)
- * cache: { store: myStore, defaults: { ttl: 60 } }
- *
- * // Route-level (inherits ttl from defaults)
- * cache(() => [
- *   route("products"),
- * ])
- *
- * // Override with explicit ttl
- * cache({ ttl: 300 }, () => [...])
- * ```
- */
-export type PartialCacheOptions<TEnv = unknown> = Partial<CacheOptions<TEnv>>;
-/**
- * Cache entry configuration stored in EntryData.
- * Represents the resolved cache config for a segment.
- */
-export interface EntryCacheConfig {
-    /** Cache options (false means caching disabled for this entry) - ttl is optional, uses defaults */
-    options: PartialCacheOptions | false;
-}

package/dist/types.backup/types/error-types.d.ts

@@ -1,114 +0,0 @@
-/**
- * Phase where the error occurred during request handling.
- *
- * Coverage notes:
- * - "routing": Invoked when route matching fails (router.ts, rsc/handler.ts)
- * - "manifest": Reserved for manifest loading errors (not currently invoked)
- * - "middleware": Reserved for middleware execution errors (errors propagate to handler phase)
- * - "loader": Invoked when loader execution fails (router.ts via wrapLoaderWithErrorHandling, rsc/handler.ts)
- * - "handler": Invoked when route/layout handler execution fails (router.ts)
- * - "rendering": Invoked during SSR rendering errors (ssr/index.tsx, separate callback)
- * - "action": Invoked when server action execution fails (rsc/handler.ts, router.ts)
- * - "revalidation": Invoked when revalidation fails (router.ts, conditional with action)
- * - "origin": Invoked when cross-origin request validation rejects a request (rsc/handler.ts)
- * - "unknown": Fallback for unclassified errors (not currently invoked)
- */
-export type ErrorPhase = "routing" | "manifest" | "middleware" | "loader" | "handler" | "rendering" | "action" | "revalidation" | "cache" | "prerender" | "static" | "origin" | "unknown";
-/**
- * Comprehensive context passed to onError callback
- *
- * Provides all available information about where and when an error occurred
- * during request handling. The callback can use this for logging, monitoring,
- * error tracking services, or custom error responses.
- *
- * @example
- * ```typescript
- * const router = createRouter<AppEnv>({
- *   onError: (context) => {
- *     // Log to error tracking service
- *     errorTracker.capture({
- *       error: context.error,
- *       phase: context.phase,
- *       url: context.request.url,
- *       route: context.routeKey,
- *       userId: context.env?.user?.id,
- *     });
- *
- *     // Log to console with context
- *     console.error(`[${context.phase}] Error in ${context.routeKey}:`, {
- *       message: context.error.message,
- *       segment: context.segmentId,
- *       duration: context.duration,
- *     });
- *   },
- * });
- * ```
- */
-export interface OnErrorContext<TEnv = any> {
-    error: Error;
-    phase: ErrorPhase;
-    request: Request;
-    url: URL;
-    pathname: string;
-    method: string;
-    /** Matched route key (if available) e.g., "shop.products.detail" */
-    routeKey?: string;
-    /** Route params (if available) e.g., { slug: "headphones" } */
-    params?: Record<string, string>;
-    /** Segment ID where error occurred (if available) e.g., "M1L0" for a layout, "M1R0" for a route */
-    segmentId?: string;
-    /** Segment type where error occurred (if available) */
-    segmentType?: "layout" | "route" | "parallel" | "loader" | "middleware";
-    /** Loader name (if error occurred in a loader) */
-    loaderName?: string;
-    /** Middleware name/id (if error occurred in middleware) */
-    middlewareId?: string;
-    /** Action ID (if error occurred during server action) e.g., "src/actions.ts#addToCart" */
-    actionId?: string;
-    /** Environment/bindings (platform context) */
-    env?: TEnv;
-    /** Duration from request start to error (milliseconds) */
-    duration?: number;
-    /** Whether this is a partial/navigation request */
-    isPartial?: boolean;
-    /** Whether an error boundary caught the error */
-    handledByBoundary?: boolean;
-    /** Stack trace (if available) */
-    stack?: string;
-    /**
-     * Additional metadata specific to the error phase. For the `cache` phase,
-     * `metadata.category` is a `CacheErrorCategory` (exported from
-     * `@rangojs/router/cache`) identifying the failure kind, e.g. `cache-read`
-     * (transient outage, degraded to a miss) vs `cache-corrupt` (faulty entry
-     * self-healed) vs `cache-invalidate` (a failed background revalidateTag).
-     */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Callback function for error handling
- *
- * Called whenever an error occurs during request handling.
- * The callback is for notification/logging purposes - it cannot
- * modify the error handling flow (use errorBoundary for that).
- *
- * @param context - Comprehensive error context
- *
- * @example
- * ```typescript
- * const onError: OnErrorCallback = (context) => {
- *   // Send to error tracking service
- *   Sentry.captureException(context.error, {
- *     tags: {
- *       phase: context.phase,
- *       route: context.routeKey,
- *     },
- *     extra: {
- *       url: context.url.toString(),
- *       params: context.params,
- *       duration: context.duration,
- *     },
- *   });
- * };
- * ```
- */
-export type OnErrorCallback<TEnv = any> = (context: OnErrorContext<TEnv>) => void | Promise<void>;

package/dist/types.backup/types/global-namespace.d.ts

@@ -1,90 +0,0 @@
-/**
- * Global namespace for module augmentation
- *
- * Users augment these interfaces for type-safe context:
- *
- * @example
- * ```typescript
- * // In env.ts or env.d.ts
- * declare global {
- *   namespace Rango {
- *     interface Env extends AppBindings {}
- *     interface Vars extends AppVariables {}
- *   }
- * }
- *
- * // Now all handlers have type-safe context without imports!
- * // ctx.env.DB, ctx.get("user"), etc.
- * ```
- */
-declare global {
-    namespace Rango {
-        interface Env {
-        }
-        interface Vars {
-        }
-        interface RegisteredRoutes {
-        }
-        interface GeneratedRouteMap {
-        }
-    }
-}
-/**
- * Route map for path-validation surfaces (`href`, `ValidPaths`, `PathResponse`).
- *
- * Resolution order:
- * 1. `RegisteredRoutes` — manual `extends typeof router.routeMap`; richest map,
- *    the only one carrying response-route payload metadata.
- * 2. `GeneratedRouteMap` — auto-wired by `router.named-routes.gen.ts`; path +
- *    search only. Lets `rango generate` alone enable `href()`/`ValidPaths` path
- *    checking without a manual `RegisteredRoutes` declaration.
- * 3. `Record<string, string>` — permissive fallback when nothing is registered.
- *
- * Referencing `GeneratedRouteMap` here is cycle-safe: it is declared in the
- * standalone gen file with no imports, unlike `RegisteredRoutes extends typeof
- * router.routeMap`.
- */
-export type GetRegisteredRoutes = keyof Rango.RegisteredRoutes extends never ? keyof Rango.GeneratedRouteMap extends never ? Record<string, string> : Rango.GeneratedRouteMap : Rango.RegisteredRoutes;
-/**
- * Default route map for reverse() surfaces.
- * Prefers GeneratedRouteMap to avoid router.tsx -> urls.tsx -> types -> router.tsx
- * cycles, but falls back to RegisteredRoutes for manual augmentation and then to
- * a permissive record when no route types are available.
- */
-export type DefaultReverseRouteMap = keyof Rango.GeneratedRouteMap extends never ? keyof Rango.RegisteredRoutes extends never ? Record<string, string> : Rango.RegisteredRoutes : Rango.GeneratedRouteMap;
-/**
- * Default route map for Handler type.
- * Uses GeneratedRouteMap (from gen file) instead of RegisteredRoutes to avoid
- * circular dependencies: router.tsx -> urls.tsx -> handler.tsx -> RegisteredRoutes -> router.tsx.
- * GeneratedRouteMap is declared in a standalone gen file with no imports.
- */
-export type DefaultHandlerRouteMap = keyof Rango.GeneratedRouteMap extends never ? {} : Rango.GeneratedRouteMap;
-/**
- * Default environment type - uses global augmentation if available.
- *
- * Falls back to `unknown` (not `any`) when `Rango.Env` is not augmented, so
- * an app that forgets to register its bindings gets a compile error on
- * `ctx.env.SOMETHING` instead of silently losing all env type-checking. Augment
- * `Rango.Env` to type `ctx.env`.
- */
-export type DefaultEnv = keyof Rango.Env extends never ? unknown : Rango.Env;
-/**
- * Variables type backing the string-key `ctx.get` / `ctx.set` overloads.
- *
- * Uses `Rango.Vars` augmentation when present; otherwise falls back to
- * `Record<string, any>` so an un-augmented app can use string-key vars with
- * zero config -- at the cost of a typo'd key being silently `any`.
- *
- * This `any` fallback is deliberate (see #561) and is an intentional asymmetry
- * with `DefaultEnv` above, which falls back to `unknown`: env bindings are
- * platform-critical and should be registered, so a forgotten binding is made a
- * compile error; vars are ad-hoc and middleware-set, so the zero-config path
- * wins. Augment `Rango.Vars` for type-safe keys.
- */
-export type DefaultVars = keyof Rango.Vars extends never ? Record<string, any> : Rango.Vars;
-/**
- * Default route name type for public `routeName` on contexts.
- * When GeneratedRouteMap is augmented, narrows to the known route names.
- * Otherwise falls back to `string` for untyped usage.
- */
-export type DefaultRouteName = keyof Rango.GeneratedRouteMap extends never ? string : keyof Rango.GeneratedRouteMap & string;