@rangojs/router 0.4.0 → 0.4.1

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

@@ -1,21 +0,0 @@
-/**
- * Build-time utilities for @rangojs/router
- *
- * Note: Route manifest is automatically generated at runtime on first request.
- * These build-time utilities are only needed for advanced use cases like
- * custom tooling or pre-generating manifests.
- *
- * @example Generate manifest programmatically (for custom tooling)
- * ```typescript
- * import { generateManifest } from "@rangojs/router/build";
- * import { urlpatterns } from "./urls";
- *
- * // Async: generateManifest awaits any async include() providers
- * // (`() => import("./routes")`) so the split groups appear in the manifest.
- * const manifest = await generateManifest(urlpatterns);
- * console.log(manifest.routeManifest); // { home: "/", about: "/about", ... }
- * ```
- */
-export { generateManifest, generateManifestFull, generateManifestCode, type GeneratedManifest, } from "./generate-manifest.js";
-export { writePerModuleRouteTypes, extractRoutesFromSource, generatePerModuleTypesSource, createScanFilter, type ScanFilter, } from "./generate-route-types.js";
-export { hashParams } from "../prerender/param-hash.js";

package/dist/types.backup/build/prefix-tree-utils.d.ts

@@ -1,56 +0,0 @@
-/**
- * Pure prefix-tree walks shared by the build/discovery layer and the runtime
- * trie builder. Kept in `build/` (not `vite/utils`) so runtime code
- * (rsc/manifest-init via build/route-trie) can consume them without importing
- * from the vite layer. `vite/utils/manifest-utils` re-exports them so existing
- * vite-side imports stay unchanged.
- */
-/**
- * Flatten prefix tree leaf nodes into precomputed route entries.
- * Leaf nodes have no children (no nested includes), so their routes can be
- * used directly by evaluateLazyEntry() without running the handler.
- * Non-leaf nodes are skipped because they have nested lazy includes that
- * require the handler to run for discovery.
- *
- * A leaf is also skipped when its staticPrefix collides with an ancestor
- * include node's staticPrefix. That happens when a dynamic param collapses the
- * staticPrefix of nested includes onto the parent's (e.g. `/m/:id/edit` -> sp
- * `/m`): precomputing such a leaf under the collapsed prefix would let the
- * ancestor's lazy entry claim a route it cannot register (the route is behind
- * further nested lazy includes), producing a RouteNotFoundError at request time
- * (issue #506). Those routes are resolved via the handler chain instead.
- */
-export declare function flattenLeafEntries(prefixTree: Record<string, any>, routeManifest: Record<string, string>, result: Array<{
-    staticPrefix: string;
-    routes: Record<string, string>;
-}>): void;
-/**
- * Build the staticPrefix -> routes lookup the runtime shortcut consumes from a
- * flat precomputed-entry array.
- *
- * A staticPrefix owned by MORE THAN ONE leaf include cannot be collapsed to a
- * single routes object: `new Map(entries.map(e => [e.staticPrefix, e.routes]))`
- * is last-wins, so one include's routes are silently dropped and mis-assigned
- * to whichever entry evaluates first. Two distinct includes legitimately share a
- * staticPrefix when a dynamic param collapses their literal prefixes onto the
- * same value (e.g. `include("/shop/:cat", ...)` and a nested
- * `include("/shop/:brand", ...)` both extract "/shop/"). Merging them is also
- * wrong — assigning the merged set to the first matching entry makes findMatch
- * pick the wrong handler for routes belonging to the other include, which then
- * fails its `Store.manifest.has(routeKey)` invariant at render (500 on a valid
- * route, dev/prod identical).
- *
- * So any shared staticPrefix is OMITTED from the shortcut entirely. Those
- * includes fall through to the handler path in evaluateLazyEntry(), which is the
- * ground truth (identical to pre-precomputed behavior). The shortcut is purely an
- * optimization, so dropping a prefix can only cost a handler run, never change a
- * result.
- */
-export declare function buildPrecomputedByPrefix(entries: Array<{
-    staticPrefix: string;
-    routes: Record<string, string>;
-}>): Map<string, Record<string, string>>;
-/**
- * Walk prefix tree to map each route name to its scope's staticPrefix.
- */
-export declare function buildRouteToStaticPrefix(prefixTree: Record<string, any>, result: Record<string, string>): void;

package/dist/types.backup/build/route-trie.d.ts

@@ -1,89 +0,0 @@
-/**
- * Build-time Route Trie Construction
- *
- * Builds a serializable trie from the route manifest for O(path_length)
- * route matching at runtime.
- */
-import type { FullManifest } from "./generate-manifest.js";
-/**
- * A response-type variant folded into a primary leaf's negotiate list. `pa` is
- * the variant's own positional param-name array, carried so the runtime can
- * re-key the matched params under the variant's names when it wins negotiation
- * (the trie match extracts params under the PRIMARY leaf's pa). Omitted when the
- * variant has no params; absent/identical pa means no re-key is needed.
- */
-export interface NegotiateVariant {
-    routeKey: string;
-    responseType: string;
-    pa?: string[];
-}
-export interface TrieLeaf {
-    /** Route name (e.g., "site.l1_500") */
-    n: string;
-    /** Static prefix of the entry (e.g., "/site") */
-    sp: string;
-    /** Constraint validation: paramName -> allowed values */
-    cv?: Record<string, string[]>;
-    /** Ordered param names for this route (positional) */
-    pa?: string[];
-    /** Trailing slash mode */
-    ts?: string;
-    /** Route has pre-rendered data available */
-    pr?: true;
-    /** Passthrough: handler kept in bundle for live fallback on unknown params */
-    pt?: true;
-    /** Response type for non-RSC routes (json, text, image, any) */
-    rt?: string;
-    /** Negotiate variants: response-type routes sharing this path */
-    nv?: NegotiateVariant[];
-    /** RSC-first: RSC route was defined before response-type variants */
-    rf?: true;
-}
-export interface TrieNode {
-    /** Route terminal at this node */
-    r?: TrieLeaf;
-    /** Static segment children */
-    s?: Record<string, TrieNode>;
-    /** Param child: { n: paramName, c: child node } */
-    p?: {
-        n: string;
-        c: TrieNode;
-    };
-    /** Suffix-param children keyed by suffix (e.g., ".html" → { n: "productId", c: ... }) */
-    xp?: Record<string, {
-        n: string;
-        c: TrieNode;
-    }>;
-    /**
-     * Wildcard terminal: leaf + paramName (`pn`). `pn` is "*" for the bare `/*`
-     * form and the param name for a named catch-all (`:name+`/`:name*`). `w1`
-     * marks a one-or-more catch-all (`:name+`): the runtime walker then rejects
-     * the zero-segment/empty-remainder case. Absent `w1` is zero-or-more.
-     */
-    w?: TrieLeaf & {
-        pn: string;
-        w1?: true;
-    };
-}
-/**
- * Build a route trie from build-time manifest data.
- *
- * @param routeManifest - Map of route name to full URL pattern
- * @param routeToStaticPrefix - Map of route name to its entry's staticPrefix
- * @param routeTrailingSlash - Optional map of route name to trailing slash mode
- * @param prerenderRouteNames - Optional set of prerendered route names (sets leaf.pr)
- * @param passthroughRouteNames - Optional set of passthrough route names (sets leaf.pt)
- * @param responseTypeRoutes - Optional map of route name to response type (sets leaf.rt)
- */
-export declare function buildRouteTrie(routeManifest: Record<string, string>, routeToStaticPrefix: Record<string, string>, routeTrailingSlash?: Record<string, string>, prerenderRouteNames?: Set<string>, passthroughRouteNames?: Set<string>, responseTypeRoutes?: Record<string, string>): TrieNode;
-/**
- * Build a per-router trie from a generated manifest. This is the single
- * construction path shared by build/discovery (discover-routers.ts, serialized
- * into the production chunk) and the dev/HMR runtime rebuild
- * (rsc/manifest-init.ts). Keeping one code path is what guarantees the dev
- * runtime trie and the production serialized trie are byte-for-byte identical.
- *
- * Returns null when the manifest has no routes, matching the prior guard at
- * both call sites.
- */
-export declare function buildPerRouterTrie(manifest: FullManifest): TrieNode | null;

package/dist/types.backup/build/route-types/ast-helpers.d.ts

@@ -1,3 +0,0 @@
-import ts from "typescript";
-export declare function getStringValue(node: ts.Node): string | null;
-export declare function extractObjectStringProperties(node: ts.ObjectLiteralExpression): Record<string, string>;

package/dist/types.backup/build/route-types/ast-route-extraction.d.ts

@@ -1,13 +0,0 @@
-import ts from "typescript";
-/**
- * Extract route definitions from source code by walking the TypeScript AST.
- * Finds path() and path.json(), path.md(), etc. call expressions and extracts
- * the pattern, name, params, and optional search schema from each.
- * Skips unnamed paths (no { name: "..." }).
- */
-export declare function extractRoutesFromSource(code: string, sourceFileArg?: ts.SourceFile): Array<{
-    name: string;
-    pattern: string;
-    params?: Record<string, string>;
-    search?: Record<string, string>;
-}>;

package/dist/types.backup/build/route-types/codegen.d.ts

@@ -1,16 +0,0 @@
-/**
- * Generate a per-module types file from extracted routes.
- * Output has zero imports, preventing circular references.
- */
-export declare function generatePerModuleTypesSource(routes: Array<{
-    name: string;
-    pattern: string;
-    params?: Record<string, string>;
-    search?: Record<string, string>;
-}>): string;
-/**
- * Generates a .ts file that augments Rango.GeneratedRouteMap
- * with route name -> pattern mappings. This enables Handler<"routeName">
- * without circular references since the file has no imports from the app.
- */
-export declare function generateRouteTypesSource(routeManifest: Record<string, string>, searchSchemas?: Record<string, Record<string, string>>): string;

package/dist/types.backup/build/route-types/include-resolution.d.ts

@@ -1,74 +0,0 @@
-import ts from "typescript";
-export type UnresolvableReason = "factory-call" | "dynamic-expression" | "unresolvable-import" | "file-not-found";
-export interface UnresolvableInclude {
-    pathPrefix: string;
-    namePrefix: string | null;
-    reason: UnresolvableReason;
-    sourceFile: string;
-    detail: string;
-}
-/**
- * Per-scan memo shared across the include-resolution recursion. Keys are
- * absolute file paths; values cache the readFileSync result and the
- * ts.SourceFile parsed from the FULL file source. A separate blockSources map
- * caches parses of extracted sub-blocks (urls() call text), keyed by the exact
- * block string, so the two extractors (routes + includes) for the same block
- * share a single parse.
- *
- * The memo is purely a performance accelerator: same input -> same parse, so
- * generated output is identical to the un-memoized path. A fresh memo is
- * created per top-level scan entry, so stale file edits between scans are never
- * served.
- */
-export interface ScanMemo {
-    files: Map<string, string>;
-    blockSourceFiles: Map<string, ts.SourceFile>;
-}
-export declare function createScanMemo(): ScanMemo;
-/**
- * Extract include() calls with diagnostics for unresolvable ones.
- * Returns both resolved includes (identifier second args) and unresolvable
- * includes (factory calls, etc.) with reasons.
- */
-export declare function extractIncludesWithDiagnostics(code: string, sourceFileArg?: ts.SourceFile): {
-    resolved: Array<{
-        pathPrefix: string;
-        variableName?: string;
-        moduleSpecifier?: string;
-        namePrefix: string | null;
-    }>;
-    unresolvable: Array<{
-        pathPrefix: string;
-        namePrefix: string | null;
-        reason: UnresolvableReason;
-        detail: string;
-    }>;
-};
-/**
- * Find the import statement for a local variable name.
- * Returns the import specifier and the exported name from the source module.
- */
-export declare function resolveImportedVariable(code: string, localName: string): {
-    specifier: string;
-    exportedName: string;
-} | null;
-/**
- * Resolve an import specifier relative to the importing file.
- * Strips .js/.mjs/.jsx extensions and tries .ts/.tsx/.js/.jsx candidates.
- */
-export declare function resolveImportPath(importSpec: string, fromFile: string): string | null;
-/**
- * Build route map and search schemas together.
- * Internal helper used by the include resolution path.
- *
- * @param inlineBlock - Optional pre-extracted code block (e.g. from an inline
- *   builder function). When provided, variableName is ignored and the block
- *   is parsed directly for path()/include() calls.
- * @param memo - Per-scan readFileSync/parse memo. A fresh one is created at the
- *   top-level entry and threaded through the recursion so each file is read and
- *   parsed once per scan. Behavior-preserving (same input -> same output).
- */
-export declare function buildCombinedRouteMapWithSearch(filePath: string, variableName?: string, visited?: Set<string>, diagnosticsOut?: UnresolvableInclude[], inlineBlock?: string, memo?: ScanMemo): {
-    routes: Record<string, string>;
-    searchSchemas: Record<string, Record<string, string>>;
-};

package/dist/types.backup/build/route-types/param-extraction.d.ts

@@ -1,13 +0,0 @@
-/**
- * Extract typed params from a route pattern string.
- * Matches `:paramName` and `:paramName?` (optional).
- * Custom regex constraints like `:id(\d+)` are ignored for type purposes.
- */
-export declare function extractParamsFromPattern(pattern: string): Record<string, string> | undefined;
-/**
- * Format a single route entry for codegen output.
- * Routes without search remain plain strings (params are extracted from
- * the pattern at the type level by ExtractParams).
- * Routes with search become objects with path and search fields.
- */
-export declare function formatRouteEntry(key: string, pattern: string, _params?: Record<string, string>, search?: Record<string, string>): string;

package/dist/types.backup/build/route-types/per-module-writer.d.ts

@@ -1,18 +0,0 @@
-import type { ScanFilter } from "./scan-filter.js";
-/**
- * Generate per-module route type files by statically parsing url module source.
- * Scans for files containing `urls(` and writes a sibling `.gen.ts` with the
- * extracted route name/pattern pairs. Only writes when content has changed.
- */
-export declare function writePerModuleRouteTypes(root: string, filter?: ScanFilter): void;
-/**
- * Find all variable names assigned to urls() calls in source code.
- * e.g. `export const patterns = urls(...)` -> ["patterns"]
- */
-export declare function findUrlsVariableNames(code: string): string[];
-/**
- * Generate per-module route types for a single url module file.
- * Follows include() calls recursively to produce the full route tree.
- * No-ops if the file doesn't contain `urls(` or has no named routes.
- */
-export declare function writePerModuleRouteTypesForFile(filePath: string): void;

package/dist/types.backup/build/route-types/router-processing.d.ts

@@ -1,82 +0,0 @@
-import type { ScanFilter } from "./scan-filter.js";
-import { type UnresolvableInclude } from "./include-resolution.js";
-export declare function findNestedRouterConflict(routerFiles: string[]): {
-    ancestor: string;
-    nested: string;
-} | null;
-export declare function formatNestedRouterConflictError(conflict: {
-    ancestor: string;
-    nested: string;
-}, prefix?: string): string;
-/**
- * Result of extracting URL patterns from a router file.
- * - "variable": a named variable reference (e.g., `.routes(patterns)` or `urls: patterns`)
- * - "inline": an inline builder function (e.g., `.routes(({ path }) => [...])` or `urls: ({ path }) => [...]`)
- */
-export type UrlsExtractionResult = {
-    kind: "variable";
-    name: string;
-} | {
-    kind: "inline";
-    block: string;
-};
-/**
- * Extract the url patterns from a router file using AST.
- * Detects four patterns:
- *   1. createRouter(...).routes(variableName)
- *   2. createRouter({ urls: variableName, ... })
- *   3. createRouter(...).routes(({ path, ... }) => [...])
- *   4. createRouter({ urls: ({ path, ... }) => [...], ... })
- * Returns either a variable name or an inline code block.
- */
-export declare function extractUrlsFromRouter(code: string): UrlsExtractionResult | null;
-/**
- * Extract the `basename` string literal from createRouter({ basename: "..." }).
- * Returns the basename value or undefined if not present.
- */
-export declare function extractBasenameFromRouter(code: string): string | undefined;
-export declare function genFileTsPath(sourceFile: string): string;
-export declare function resolveSearchSchemas(publicRouteNames: string[], runtimeSchemas: Record<string, Record<string, string>> | undefined, sourceFile: string): Record<string, Record<string, string>> | undefined;
-/**
- * Resolve routes and search schemas from a router source file by following the
- * variable passed to `.routes(...)` or `urls: ...` in createRouter options,
- * or by parsing an inline builder function directly.
- */
-export declare function buildCombinedRouteMapForRouterFile(routerFilePath: string): {
-    routes: Record<string, string>;
-    searchSchemas: Record<string, Record<string, string>>;
-};
-/**
- * Walk the full include tree starting from a router file and detect
- * all includes that the static parser cannot resolve.
- * Returns an array of diagnostics; empty means fully resolvable.
- */
-export declare function detectUnresolvableIncludes(routerFilePath: string): UnresolvableInclude[];
-/**
- * Walk the include tree for a standalone urls() module file and detect
- * all unresolvable includes. Mirrors detectUnresolvableIncludes() but
- * operates on urls() variable declarations instead of going through
- * createRouter().
- */
-export declare function detectUnresolvableIncludesForUrlsFile(filePath: string): UnresolvableInclude[];
-/**
- * Scan for files containing createRouter() and return their paths.
- * Call once at startup; the result can be reused on subsequent watcher triggers.
- */
-export declare function findRouterFiles(root: string, filter?: ScanFilter): string[];
-/**
- * Scan for files containing createHostRouter() and return their paths. Unlike
- * findRouterFiles, this does NOT stop at the first router-root directory -- a host
- * entry typically sits above the sub-app router roots, so the whole tree is scanned.
- */
-export declare function findHostRouterFiles(root: string, filter?: ScanFilter): string[];
-/**
- * Write named-routes.gen.ts files from static source parsing.
- * Dev-only: provides initial .gen.ts files for IDE types before runtime
- * discovery runs. Must NOT be called during production builds -- runtime
- * discovery in buildStart produces the definitive file.
- */
-export declare function writeCombinedRouteTypes(root: string, knownRouterFiles?: string[], opts?: {
-    preserveIfLarger?: boolean;
-    onWrite?: (outPath: string, content: string) => void;
-}): void;

package/dist/types.backup/build/route-types/scan-filter.d.ts

@@ -1,17 +0,0 @@
-/** Default exclude patterns for route type scanning. */
-export declare const DEFAULT_EXCLUDE_PATTERNS: string[];
-export type ScanFilter = (absolutePath: string) => boolean;
-/**
- * Compile include/exclude glob patterns into a single predicate.
- * Paths are made root-relative before matching.
- * Returns undefined when no filtering is needed (no include, default exclude).
- */
-export declare function createScanFilter(root: string, opts: {
-    include?: string[];
-    exclude?: string[];
-}): ScanFilter | undefined;
-/**
- * Recursively find .ts/.tsx files under a directory, skipping node_modules
- * and .gen. files.
- */
-export declare function findTsFiles(dir: string, filter?: ScanFilter): string[];

package/dist/types.backup/build/route-types/source-scan.d.ts

@@ -1,13 +0,0 @@
-/**
- * Index of the first match of `pattern` that occurs in code (not in a comment
- * or string), or -1. `pattern` MUST be a global (`/g`) regex. Single native
- * regex sweep with early-exit; O(1) extra memory.
- */
-export declare function firstCodeMatchIndex(code: string, pattern: RegExp): number;
-/**
- * Byte offsets of every match of `pattern` that occurs in code (not in a
- * comment or string). `pattern` MUST be a global (`/g`) regex. Each offset is
- * the match start — the same byte offset a raw `pattern.exec` reports. O(n)
- * time, O(#matches) memory.
- */
-export declare function codeMatchIndices(code: string, pattern: RegExp): number[];

package/dist/types.backup/build/runtime-discovery.d.ts

@@ -1,24 +0,0 @@
-export interface RuntimeDiscoveryOptions {
-    /** Project root directory (where package.json / node_modules live). */
-    root: string;
-    /** Path to vite.config.ts. Auto-detected from root if omitted. */
-    configFile?: string;
-    /** Absolute path to the router entry file. */
-    entry: string;
-    /** Override resolve.alias (skips loading from vite config when provided). */
-    resolveAlias?: Record<string, string>;
-}
-/**
- * Standalone Vite-based route discovery for the CLI.
- * Creates a temporary Vite server with the RSC plugin, imports the entry via
- * the module runner, reads the RouterRegistry, generates manifests, and writes
- * named-routes.gen.ts files.
- *
- * This mirrors the logic in the Vite plugin's discoverRouters() + writeRouteTypesFiles()
- * but without coupling to plugin closure state.
- */
-export declare function discoverAndWriteRouteTypes(opts: RuntimeDiscoveryOptions): Promise<{
-    routerCount: number;
-    routeCount: number;
-    outputFiles: string[];
-}>;

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

@@ -1,21 +0,0 @@
-/**
- * Background Task Runner
- *
- * Unified helper for scheduling async work via waitUntil.
- * When waitUntil is unavailable, falls back to blocking or skipping.
- */
-interface WaitUntilHost {
-    waitUntil?: (fn: () => Promise<void>) => void;
-}
-/**
- * Schedule an async task in the background via waitUntil.
- *
- * @param host - Object with optional waitUntil (request context or similar)
- * @param task - Async function to execute
- * @param blockWhenNoWaitUntil - If true, awaits the task when waitUntil is
- *   unavailable (e.g., Node.js dev server). If false (default), the task
- *   is silently skipped when waitUntil is unavailable.
- * @returns A promise when blocking fallback is used, void otherwise.
- */
-export declare function runBackground(host: WaitUntilHost | null | undefined, task: () => Promise<void>, blockWhenNoWaitUntil?: boolean): Promise<void> | void;
-export {};

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

@@ -1,71 +0,0 @@
-/**
- * Cache error reporting.
- *
- * Caches are best-effort: a read failure degrades to a miss (render fresh) and a
- * write failure degrades to a no-op - they MUST NOT throw up and fail the
- * request. But the failure must still be LOUD: it is logged to the console (so
- * it is visible even in a background waitUntil task or when no hook is wired)
- * AND routed through the router's onError callback (via the request context's
- * deduped _reportBackgroundError) so consumers can observe cache degradation in
- * their own telemetry.
- *
- * The one deliberate exception is the invalidation WRITE verb (updateTag ->
- * store.invalidateTags): a failed durable marker write is rejected so an awaited
- * updateTag() surfaces it (read-your-own-writes honesty). That is not a data
- * read/write and does not go through this helper's swallow-and-degrade path.
- */
-/**
- * Minimal shape of a request context for error reporting. Passed explicitly by
- * background tasks (waitUntil) where the ALS context is already gone, so the
- * error can still reach the router's onError. Structural to avoid importing the
- * full RequestContext type (request-context.ts imports CacheErrorCategory from
- * here - a mutual type-only reference).
- */
-export interface CacheErrorReporter {
-    _reportBackgroundError?: (error: unknown, category: CacheErrorCategory) => void;
-}
-export type CacheErrorCategory = 
-/** A read failed (transient infra: KV/Cache API error). Degrade to a miss. */
-"cache-read"
-/** A write failed. Degrade to a no-op (entry simply not cached). */
- | "cache-write"
-/** A delete/eviction failed. Best-effort. */
- | "cache-delete"
-/**
- * A STORED entry could not be parsed/deserialized (partial KV read, truncated
- * Cache API body, malformed envelope/RSC payload). The entry is faulty and is
- * evicted so subsequent reads do not keep failing on it. Distinct from
- * cache-read so consumers can tell corruption from a transient outage.
- */
- | "cache-corrupt"
-/** A tag-invalidation side effect failed (e.g. the eager CDN purge hook). */
- | "cache-invalidate"
-/**
- * A background stale-while-revalidate refresh failed (the `"use cache"`
- * read-through path). The stale value was already served; the refresh that
- * would have replaced it errored.
- */
- | "stale-revalidation";
-/**
- * Report a non-fatal cache error loudly without failing the request: always logs
- * (label + error) and, when a request context is available, routes the error
- * through the router's onError callback. Never throws.
- *
- * `ctx` is for callers running in a detached background task (waitUntil), where
- * the ALS request context is already gone (so `_getRequestContext()` is null):
- * they capture the context up front and pass it here so onError still fires.
- * Foreground callers omit it and fall back to the ALS context.
- */
-export declare function reportCacheError(error: unknown, category: CacheErrorCategory, label: string, ctx?: CacheErrorReporter): void;
-/**
- * Run a best-effort async cache task (typically scheduled via waitUntil), catching
- * any rejection and routing it through reportCacheError so background cache work
- * (non-blocking L1 writes, KV persistence, L1 promotion) reports failures via
- * onError instead of throwing or silently swallowing. Never rejects.
- *
- * Pass `ctx` when the task runs detached (the ALS context is gone) and the
- * failure should still reach onError; omit it to fall back to the ALS context.
- *
- * @example this.waitUntil(() => reportingAsync(() => cache.put(req, res), "cache-write", "[CFCacheStore] L1 write"))
- */
-export declare function reportingAsync(task: () => Promise<unknown>, category: CacheErrorCategory, label: string, ctx?: CacheErrorReporter): Promise<void>;

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

@@ -1,35 +0,0 @@
-/**
- * Shared Cache Key Utilities
- *
- * Deterministic normalization of search params and route params
- * for cache key generation. Used by cache-runtime, cache-scope,
- * document-cache, and loader-cache.
- */
-/**
- * Build a sorted, deterministic query string from URLSearchParams,
- * excluding the router's reserved params (see isReservedSearchParam).
- *
- * Returns empty string when no user-facing params exist.
- */
-export declare function sortedSearchString(searchParams: URLSearchParams): string;
-/**
- * Build a sorted, deterministic string from route params.
- *
- * Returns empty string when params is empty or undefined.
- */
-export declare function sortedRouteParams(params: Record<string, string> | undefined): string;
-/**
- * Host-namespaced cache key base: `${host}${pathname}[:params][?search]`.
- *
- * The ONE composition of the host-namespacing rule, shared by the segment tier
- * (cache-scope.ts) and the document tier (document-cache.ts) so the rule cannot
- * drift between them. Host prefixing matters because VercelCacheStore /
- * MemorySegmentCacheStore key by the raw string (only CFCacheStore adds host
- * internally) -- on a single function serving multiple domains an
- * un-namespaced key bleeds tenant A's cached response to tenant B.
- *
- * Output is BYTE-STABLE by contract: changing the composition silently
- * invalidates every persisted cache entry on upgrade. Callers append their own
- * tier-specific suffixes (`:rsc`/`:html`, segment hash) after this base.
- */
-export declare function cacheKeyBase(host: string, pathname: string, searchParams?: URLSearchParams, params?: Record<string, string>): string;

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

@@ -1,59 +0,0 @@
-/**
- * Shared Cache Policy Utilities
- *
- * Resolution cascades for TTL, SWR, cache key, and cache store.
- * Consolidates the multi-tier resolution pattern:
- *   explicit option → store defaults → fallback constant
- */
-import type { CacheDefaults, SegmentCacheStore } from "./types.js";
-import type { RequestContext } from "../server/request-context.js";
-/**
- * Default TTL for route-level cache() DSL and loader cache.
- * Applied when neither the cache options nor the store defaults specify a TTL.
- */
-export declare const DEFAULT_ROUTE_TTL = 60;
-/**
- * Default TTL for function-level "use cache" (setItem).
- * Applied when neither the item options nor the store defaults specify a TTL.
- */
-export declare const DEFAULT_FUNCTION_TTL = 900;
-/**
- * A finite, non-negative seconds value? A NaN/Infinity ttl/swr (from a bad
- * cache() option or store defaults) flows into computeExpiration ->
- * staleAt/expiresAt = NaN, where every `now > NaN` is false so the entry never
- * evicts and is served fresh forever; a negative value makes every read a miss.
- * Shared with cache-scope.ts (the segment getters) so every cache path validates
- * the same way. profile-registry.ts uses the same predicate but fails fast at
- * config time; the resolvers here degrade because they run on the live path.
- */
-export declare function isFiniteNonNegativeSeconds(value: number): boolean;
-/**
- * Resolve effective TTL from the 3-tier cascade:
- * explicit → store defaults → fallback. A non-finite/negative resolved value
- * degrades to the fallback (loader cache and "use cache" setItem both resolve
- * ttl here, so this is where those paths are guarded; the segment cache is
- * guarded in cache-scope.ts).
- */
-export declare function resolveTtl(explicit: number | undefined, defaults: CacheDefaults | undefined, fallback: number): number;
-/**
- * Resolve effective SWR window from the 2-tier cascade:
- * explicit → store defaults.
- * Returns 0 when unset (no SWR window) or when the resolved value is
- * non-finite/negative (degrade rather than feed bad math into expiry).
- */
-export declare function resolveSwrWindow(explicit: number | undefined, defaults: CacheDefaults | undefined): number;
-/**
- * Compute staleAt and expiresAt timestamps from TTL and SWR window.
- *
- * - staleAt: when the entry becomes stale (TTL boundary)
- * - expiresAt: when the entry should be evicted (TTL + SWR)
- *
- * When swrWindow is 0, staleAt === expiresAt (no SWR).
- */
-export declare function computeExpiration(ttlSeconds: number, swrSeconds?: number): {
-    staleAt: number;
-    expiresAt: number;
-};
-export declare function resolveCacheKey(keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined, store: SegmentCacheStore | null, defaultKey: string, _label: string): Promise<string>;
-export declare function resolveTagsOption<TEnv>(tags: string[] | ((ctx: RequestContext<TEnv>) => string[]) | undefined, ctx: RequestContext<TEnv> | undefined, label: string): string[] | undefined;
-export declare function resolveCacheStore(explicitStore: SegmentCacheStore | undefined): SegmentCacheStore | null;