@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/dist/analyze/live-graph.d.ts

@@ -0,0 +1,81 @@
+/**
+ * live-graph — classification from a running dev server's environment
+ * module graphs (the fast path).
+ *
+ * When a dev server runs, the env module graphs are already resident —
+ * classification is a lookup, not a crawl. This module adapts those
+ * graphs to the SAME classification pipeline the cold crawl uses
+ * (classify.ts + chains.ts + poison-scan.ts — design/47's "one
+ * classification module, thin frontends" requirement), so the
+ * dev-server endpoint and the CLI can never disagree about a file.
+ *
+ * Differences from the crawl, both inherent to the live source:
+ *
+ * - The browser (`client`) graph can be non-empty here (a real browser
+ *   has requested modules), so `envs.client` is confirmable.
+ * - Rendering populates graphs lazily — only visited routes' code is
+ *   present, and modules behind unexecuted dynamic imports carry
+ *   `transformResult == null` (the §8 frontier). Those are reported as
+ *   `subtreeUnknown` rather than transformed on demand: a hint must
+ *   never mutate the dev server's graphs as a side effect of asking.
+ *
+ * Design docs: 47-module-environment-tooling.md §8, §"Dev-server
+ * endpoint".
+ */
+import { type Directive } from './classify.ts';
+import type { GraphModuleReport } from './crawl.ts';
+import { type ChainGraph } from './chains.ts';
+/**
+ * Duck-typed node view for liveness checks — the `transformResult`
+ * member ChainModuleNode deliberately omits (§8 detection is a
+ * classification concern, not a chain concern).
+ */
+interface LiveModuleNode {
+    transformResult: unknown;
+}
+import type { ChainModuleNode } from './chains.ts';
+/** Duck-typed module graph — structural supertype of Vite's. */
+export interface LiveGraph extends ChainGraph {
+    getModulesByFile(file: string): Set<ChainModuleNode & LiveModuleNode> | undefined;
+}
+export interface LiveGraphContext {
+    rsc: LiveGraph;
+    ssr: LiveGraph;
+    client: LiveGraph;
+    /** Realpath'd project root. */
+    root: string;
+    appDir: string;
+    pageExtensions?: readonly string[];
+}
+/**
+ * Per-module answer — the crawl's shape, aliased rather than restated
+ * so a field added to one frontend cannot silently miss the other.
+ */
+export type LiveModuleReport = GraphModuleReport;
+/**
+ * Classify one file from the live graphs. `file` must be an absolute
+ * realpath (graph nodes carry realpaths); it is slash-normalized here
+ * to match Vite's node keying.
+ */
+export declare function classifyLiveFile(rawFile: string, ctx: LiveGraphContext, getDirective?: (file: string) => Directive, errors?: LiveGraphError[]): Promise<LiveModuleReport>;
+/** Live-source error entry — the crawl's error vocabulary. */
+export interface LiveGraphError {
+    environment: 'scan';
+    id: string;
+    message: string;
+}
+export interface LiveProjectReport {
+    root: string;
+    modules: LiveModuleReport[];
+    errors: LiveGraphError[];
+}
+/**
+ * Classify every project source file from the live graphs. Files on
+ * disk that no graph reached get the §2 provisional/pending
+ * classification — on a lazily-warmed dev server that includes routes
+ * nobody has visited yet, which is honest: the graphs genuinely have
+ * not confirmed them.
+ */
+export declare function classifyLiveProject(ctx: LiveGraphContext): Promise<LiveProjectReport>;
+export {};
+//# sourceMappingURL=live-graph.d.ts.map

package/dist/analyze/live-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-graph.d.ts","sourceRoot":"","sources":["../../src/analyze/live-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAsB,KAAK,UAAU,EAAoB,MAAM,aAAa,CAAC;AASpF;;;;GAIG;AACH,UAAU,cAAc;IACtB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,gEAAgE;AAChE,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,eAAe,GAAG,cAAc,CAAC,GAAG,SAAS,CAAC;CACnF;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,SAAS,CAAC;IACf,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,SAAS,CAAC;IAClB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AA8BjD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,gBAAgB,EAIrB,YAAY,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAiC,EAIjE,MAAM,CAAC,EAAE,cAAc,EAAE,GACxB,OAAO,CAAC,gBAAgB,CAAC,CAiD3B;AAuBD,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmB3F"}

package/dist/analyze/poison-rules.d.ts

@@ -0,0 +1,72 @@
+/**
+ * poison-rules — single source of truth for server-only / client-only
+ * module rules.
+ *
+ * Two tiers with different enforcement policies (design/47 §3):
+ *
+ * 1. **Explicit markers** (`server-only`, `client-only`) — evaluation-time
+ *    poison pills. `plugins/shims.ts` resolves them to virtual modules
+ *    whose body is a top-level `throw` in the wrong environment and a
+ *    silent no-op in the right one. The error fires when the module is
+ *    evaluated, not at resolve time.
+ *
+ * 2. **Inferred rules** (`node:*` imports, timber's ALS modules, browser
+ *    globals) — report-only. They have legitimate false positives
+ *    (`import.meta.env.SSR`-guarded `node:*` use, conditionally-imported
+ *    packages), so erroring the build on them would refuse working apps.
+ *    The `timber graph` reporter surfaces them as hints.
+ *
+ * Both shims.ts and the reporter consume this module so the two surfaces
+ * can never disagree. Promoting inferred rules to build errors is a
+ * policy flip on this list, never a new rule set.
+ *
+ * Design doc: 47-module-environment-tooling.md §3.
+ */
+/** Vite environment names the dev server / build run. */
+export type EnvironmentName = 'rsc' | 'ssr' | 'client';
+export interface ExplicitMarker {
+    /** The bare specifier user code imports (`server-only` / `client-only`). */
+    readonly specifier: string;
+    /** Virtual module ID the specifier resolves to in shims.ts. */
+    readonly virtualId: string;
+    /**
+     * True when evaluating the marker in `env` is a violation (the virtual
+     * module body must throw). `undefined` means "no environment context"
+     * (e.g. a non-environment-aware build) and is treated as a server
+     * environment — matching the historical shims.ts behavior.
+     */
+    readonly violatesIn: (env: EnvironmentName | string | undefined) => boolean;
+    /** Exact runtime error message thrown in the wrong environment. */
+    readonly errorMessage: string;
+    readonly enforcement: 'poison-pill';
+}
+export declare const EXPLICIT_MARKERS: readonly ExplicitMarker[];
+/**
+ * Look up an explicit marker by its import specifier. Throws on an
+ * unknown specifier — callers reference rules that must exist, and a
+ * silent undefined would just defer the failure.
+ */
+export declare function markerFor(specifier: string): ExplicitMarker;
+/**
+ * Generate the virtual module body for an explicit marker in `env`:
+ * a top-level throw in the wrong environment, a no-op otherwise.
+ */
+export declare function poisonPillSource(marker: ExplicitMarker, env: EnvironmentName | string | undefined): string;
+export interface InferredRule {
+    readonly id: string;
+    /** Which exclusivity the signal implies for the containing module. */
+    readonly implies: 'server-only' | 'client-only';
+    readonly enforcement: 'report-only';
+    /** Human-readable description for reporter output. */
+    readonly description: string;
+    /** Import-specifier signal — matches static import sources. */
+    readonly matchesImport?: (specifier: string) => boolean;
+    /**
+     * Identifier signal — global names whose use implies the exclusivity.
+     * Consumers must apply shadow-safe matching (an allowlisted-position
+     * AST check, not a text search).
+     */
+    readonly identifiers?: readonly string[];
+}
+export declare const INFERRED_RULES: readonly InferredRule[];
+//# sourceMappingURL=poison-rules.d.ts.map

package/dist/analyze/poison-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poison-rules.d.ts","sourceRoot":"","sources":["../../src/analyze/poison-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAC;AAIvD,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC;IAC5E,mEAAmE;IACnE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC;CACrC;AAED,eAAO,MAAM,gBAAgB,EAAE,SAAS,cAAc,EAmBrD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAI3D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,GACxC,MAAM,CAKR;AAID,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAAC;IAChD,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC;IACpC,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;IACxD;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAwBD,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EA4BjD,CAAC"}

package/dist/analyze/poison-scan.d.ts

@@ -0,0 +1,48 @@
+/**
+ * poison-scan — report-only poisoning detection for `timber graph`.
+ *
+ * Matches a module's static import specifiers against the shared rule
+ * lists in poison-rules.ts (the single source of truth — design/47 §3)
+ * and reports a poisoning only when the implied exclusivity CONFLICTS
+ * with where the module actually runs: a server-only signal in a
+ * client-reachable module, or a client-only signal in a server-reachable
+ * one. A `node:fs` import in a file only the RSC environment loads is
+ * working code, not a finding.
+ *
+ * Scope: import-specifier signals only (explicit markers + the inferred
+ * rules' `matchesImport`). The inferred browser-global identifier rules
+ * need shadow-safe allowlisted-position AST matching and are a separate
+ * ticket — reporting them from a text scan would flag legitimate code.
+ *
+ * Design docs: 47-module-environment-tooling.md §3.
+ */
+import { type ModuleKind } from './classify.ts';
+/** One poisoning finding on a module, in the JSON-contract shape. */
+export interface Poisoning {
+    /** Rule id — an inferred rule's id, or the explicit marker specifier. */
+    rule: string;
+    /** The import specifier that matched. */
+    specifier: string;
+    /** Which exclusivity the signal implies for the containing module. */
+    implies: 'server-only' | 'client-only';
+    /** Human-readable description for reporter output. */
+    description: string;
+}
+/**
+ * Collect every static import/export source and string-literal dynamic
+ * import from a module's original source. Sources that fail to parse
+ * (or are not JS/TS at all) return [] — no specifiers is a safe
+ * default for a report-only scan.
+ */
+export declare function collectImportSpecifiers(code: string, file: string): string[];
+/** Exclusivity signals a module's import specifiers carry. */
+export declare function importSignals(specifiers: string[]): Poisoning[];
+/**
+ * Filter a module's signals down to actual conflicts with its
+ * classification. Environment reach follows the taxonomy: boundary /
+ * client-internal / shared modules run client-side; server / shared /
+ * server-action modules run server-side. Pending (provisional) modules
+ * run nowhere confirmed, so nothing conflicts yet.
+ */
+export declare function poisoningsFor(kind: ModuleKind, pending: boolean, signals: Poisoning[]): Poisoning[];
+//# sourceMappingURL=poison-scan.d.ts.map

package/dist/analyze/poison-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poison-scan.d.ts","sourceRoot":"","sources":["../../src/analyze/poison-scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAE7D,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,OAAO,EAAE,aAAa,GAAG,aAAa,CAAC;IACvC,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;CACrB;AAiBD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAsD5E;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,CAyB/D;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,SAAS,EAAE,GACnB,SAAS,EAAE,CAUb"}

package/dist/analyze/scan.d.ts

@@ -0,0 +1,73 @@
+/**
+ * scan — project source-file disk scan shared by the crawl and the
+ * graph cache.
+ *
+ * One walker, one rule set: the crawl uses it to find files no graph
+ * reached (the provisional/pending set) and to bound graph membership,
+ * and the mtime-keyed graph cache fingerprints exactly the same file
+ * set — the three can never disagree about what "the project" is (a
+ * file the crawl classifies but the fingerprint ignores would make the
+ * cache silently stale).
+ *
+ * Skip rules are deliberately shallow: timber's router excludes only
+ * `_`-prefixed directories, so `app/.well-known/page.tsx` and
+ * `app/dist/page.tsx` are REAL routes — a rule that skipped `dist` or
+ * dot-directories at any depth would hide legitimate route files from
+ * the scan while the module graph still reached them (codex review,
+ * PR #1056). Therefore:
+ *
+ * - `node_modules` is skipped at ANY depth (never project source, and
+ *   graph membership excludes it identically)
+ * - dot-prefixed and build-output directories (`dist`, `coverage`, …)
+ *   are skipped only as the FIRST path segment under the root — that
+ *   is where `.git`, `.timber`, `.wrangler`, and real build outputs
+ *   live; deeper occurrences are walked
+ *
+ * Deliberately vite-free: the cache-hit path of `timber graph` reads
+ * this module without booting (or even importing) Vite.
+ *
+ * Design docs: 47-module-environment-tooling.md §2, §Cold-path policy.
+ */
+/**
+ * Slash-normalize a Windows path — Vite's `normalizePath` for the
+ * vite-free callers (the graph cache-hit path must not import Vite).
+ * Same platform guard as Vite's: posix paths pass through untouched,
+ * so a filename containing a literal backslash is never corrupted.
+ */
+export declare const normalizeSlashes: (path: string) => string;
+/** A scan failure the caller records instead of swallowing. */
+export interface ScanFailure {
+    dir: string;
+    message: string;
+}
+/**
+ * Directories never scanned when they are the first path segment under
+ * the root. `node_modules` is additionally skipped at any depth.
+ */
+export declare const SCAN_IGNORED_DIRS: Set<string>;
+/** Regex form of BUILTIN_EXTENSIONS for file-basename matching. */
+export declare const SOURCE_EXTENSIONS: RegExp;
+/**
+ * Build a regex that matches SOURCE_EXTENSIONS plus any extra
+ * extensions from the user's pageExtensions config. Returns the
+ * builtin regex unchanged when nothing new is added.
+ */
+export declare function buildSourceExtensions(pageExtensions?: readonly string[]): RegExp;
+/**
+ * Whether an absolute, slash-normalized path is one the scanner WOULD
+ * admit — the same segment rules the walker applies, so a
+ * directly-addressed path (`package.json`, `<root>/dist/generated.js`,
+ * `types.d.ts`, a nested node_modules file) is answered exactly the
+ * way the scan-based sweep would answer it: by exclusion. Existence
+ * and is-a-file checks remain the caller's (this is pure path logic).
+ */
+export declare function isScannableSourceFile(file: string, root: string, extensions?: RegExp): boolean;
+/**
+ * Recursively list project source files on disk.
+ *
+ * Unreadable directories are reported through `onFailure`, not thrown
+ * and not swallowed — this walker exists to keep files from silently
+ * vanishing, so a directory it cannot see must be visible too.
+ */
+export declare function scanProjectSourceFiles(dir: string, out: string[], onFailure: (failure: ScanFailure) => void, depth?: number, extensions?: RegExp): Promise<void>;
+//# sourceMappingURL=scan.d.ts.map

package/dist/analyze/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../src/analyze/scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAKH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MACmC,CAAC;AAErF,+DAA+D;AAC/D,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,aAAgE,CAAC;AAS/F,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,QAAwD,CAAC;AAKvF;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAMhF;AAkBD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAQ9F;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EAAE,EACb,SAAS,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,EACzC,KAAK,SAAI,EACT,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAoBf"}

package/dist/cache/cache-api.d.ts

@@ -0,0 +1,48 @@
+import type { CacheOptions } from './index.ts';
+import type { PrebuiltComponentOptions } from '../server/prebuilt-runtime.ts';
+/**
+ * Cache namespace — `cache.data`, `cache.component`, `cache.invalidate`.
+ *
+ * ```ts
+ * import { cache } from '@timber-js/app/cache';
+ *
+ * const getUser = cache.data(
+ *   async (id: string) => db.users.findUnique({ where: { id } }),
+ *   { ttl: 60, tags: (id) => [`user:${id}`] }
+ * );
+ * ```
+ */
+export declare const cache: {
+    /**
+     * Wrap an async function with cross-request caching.
+     *
+     * The configured cache handler (defaults to MemoryCacheHandler, overridable
+     * via timber.config.ts) is re-resolved on every call, so module-scope
+     * wrappers created before `setCacheHandler()` still pick up the configured
+     * handler (TIM-1029).
+     */
+    data<Fn extends (...args: any[]) => Promise<any>>(fn: Fn, opts: CacheOptions<Fn>, stableId?: string): Fn;
+    /**
+     * Invalidate cache entries by tag or key.
+     *
+     * ```ts
+     * cache.invalidate({ tag: 'products' });
+     * cache.invalidate({ key: 'user:abc' });
+     * ```
+     */
+    invalidate(opts: {
+        key?: string;
+        tag?: string;
+    }): Promise<void>;
+    /**
+     * Runtime fallback for `cache.component(...)` callsites the timber-prebuilt
+     * transform does not rewrite — nested/computed/argument-position forms (see
+     * plugins/prebuilt.ts). Only module-scope `const X = cache.component(...)`
+     * declarations are transformed and eligible for prebuilding; everything else
+     * lands here, warns once per component, and renders dynamically. Same
+     * safety-net pattern as the data cache's runtime fnId fallback (TIM-1054):
+     * an untraceable callsite degrades in performance, never in correctness.
+     */
+    component<C extends (props: any) => unknown>(componentFn: C, _options?: PrebuiltComponentOptions): C;
+};
+//# sourceMappingURL=cache-api.d.ts.map

package/dist/cache/cache-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-api.d.ts","sourceRoot":"","sources":["../../src/cache/cache-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAS9E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,KAAK;IAChB;;;;;;;OAOG;IAEH,IAAI,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAC1C,EAAE,QACA,YAAY,CAAC,EAAE,CAAC,aACX,MAAM,GAChB,EAAE;IAIL;;;;;;;OAOG;IACG,UAAU,OAAO;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCrE;;;;;;;;OAQG;IAEH,SAAS,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,eAC5B,CAAC,aACH,wBAAwB,GAClC,CAAC;CAYL,CAAC"}

package/dist/cache/fast-hash.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Fast non-cryptographic hash for cache keys.
+ *
+ * FNV-1a 64-bit produces a well-distributed hash with a collision
+ * probability of ~1 in 5 billion at 77k keys (birthday paradox).
+ * Not suitable for security, but ideal for cache key generation
+ * where we need speed over crypto strength.
+ *
+ * Uses BigInt for 64-bit arithmetic — supported in all modern runtimes
+ * including Cloudflare Workers. No node:crypto dependency.
+ *
+ * Server-side only. The `_rsc` payload cache key deliberately does NOT use
+ * this — the origin compares that value, which makes it a check rather than
+ * a cache key, and FNV is solvable for a chosen digest. See
+ * `shared/rsc-cache-key.ts`.
+ *
+ * See TIM-370.
+ */
+/**
+ * Compute a 64-bit FNV-1a hash of a string, returned as a 16-char hex string.
+ *
+ * 64 bits gives ~5 billion keys before a 50% collision probability
+ * (birthday paradox), making accidental collisions effectively impossible
+ * for cache key use cases.
+ */
+export declare function fnv1aHash(input: string): string;
+//# sourceMappingURL=fast-hash.d.ts.map

package/dist/cache/fast-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fast-hash.d.ts","sourceRoot":"","sources":["../../src/cache/fast-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO/C"}

package/dist/cache/handler-store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Module-level cache handler singleton.
+ *
+ * Lazily initialized to MemoryCacheHandler on first access. The framework
+ * replaces this at boot from timber.config.ts via setCacheHandler().
+ *
+ * This module avoids importing from ./index to prevent circular dependencies.
+ */
+interface CacheHandlerLike {
+    get(key: string): Promise<{
+        value: unknown;
+        stale: boolean;
+    } | null>;
+    set(key: string, value: unknown, opts: {
+        ttl: number;
+        tags: string[];
+    }): Promise<void>;
+    invalidate(opts: {
+        key?: string;
+        tag?: string;
+    }): Promise<void>;
+}
+/** Replace the active cache handler. Called by the framework at boot. */
+export declare function setCacheHandler(h: CacheHandlerLike): void;
+/** Whether the handler was explicitly configured (vs the default in-memory fallback). */
+export declare function isCacheHandlerConfigured(): boolean;
+/**
+ * Get the active cache handler. Creates a default MemoryCacheHandler on
+ * first access if none has been set via setCacheHandler().
+ */
+export declare function getCacheHandler(): CacheHandlerLike;
+export {};
+//# sourceMappingURL=handler-store.d.ts.map

package/dist/cache/handler-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-store.d.ts","sourceRoot":"","sources":["../../src/cache/handler-store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,UAAU,gBAAgB;IACxB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACrE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAMD,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAGzD;AAED,yFAAyF;AACzF,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,gBAAgB,CAOlD"}

package/dist/cache/index.d.ts

@@ -6,6 +6,7 @@ export interface CacheHandler {
     set(key: string, value: unknown, opts: {
         ttl: number;
         tags: string[];
+        generation?: number;
     }): Promise<void>;
     invalidate(opts: {
         key?: string;
@@ -17,14 +18,31 @@ export interface CacheOptions<Fn extends (...args: any[]) => any> {
     key?: (...args: Parameters<Fn>) => string;
     staleWhileRevalidate?: boolean;
     tags?: string[] | ((...args: Parameters<Fn>) => string[]);
+    /** Timeout (ms) for singleflight-coalesced calls. Prevents hung fn() from
+     *  permanently blocking all future callers for the same cache key. See TIM-518. */
+    timeoutMs?: number;
 }
 export interface MemoryCacheHandlerOptions {
     /** Maximum number of entries. Oldest accessed entries are evicted first. Default: 1000. */
+    maxEntries?: number;
+    /**
+     * @deprecated Use `maxEntries` instead. Will be removed in a future release.
+     * Alias for `maxEntries` — maximum number of entries (not bytes).
+     */
     maxSize?: number;
+    /** Maximum total byte budget for all cached values. Oldest entries are evicted when exceeded. Default: no limit. */
+    maxBytes?: number;
+    /** Maximum byte size for a single cache entry. Entries exceeding this are silently dropped. Default: no limit. */
+    maxEntryBytes?: number;
 }
 export declare class MemoryCacheHandler implements CacheHandler {
     private store;
-    private maxSize;
+    private generations;
+    private maxEntries;
+    private maxBytes;
+    private maxEntryBytes;
+    private currentBytes;
+    private readonly _trackBytes;
     constructor(opts?: MemoryCacheHandlerOptions);
     get(key: string): Promise<{
         value: unknown;
@@ -33,6 +51,7 @@ export declare class MemoryCacheHandler implements CacheHandler {
     set(key: string, value: unknown, opts: {
         ttl: number;
         tags: string[];
+        generation?: number;
     }): Promise<void>;
     invalidate(opts: {
         key?: string;
@@ -40,13 +59,17 @@ export declare class MemoryCacheHandler implements CacheHandler {
     }): Promise<void>;
     /** Number of entries currently in the cache. */
     get size(): number;
+    /** Estimated total byte size of all cached values. Only tracked when maxBytes or maxEntryBytes is configured; returns 0 otherwise. */
+    get bytes(): number;
+    /** Evict the oldest entry (front of Map). */
+    private evictOldest;
 }
-export { RedisCacheHandler } from './redis-handler';
-export type { RedisClient } from './redis-handler';
-export { createCache } from './timber-cache';
-export { registerCachedFunction } from './register-cached-function';
-export type { RegisterCachedFunctionOptions } from './register-cached-function';
-export { stableStringify } from './stable-stringify';
-export { createSingleflight } from './singleflight';
-export type { Singleflight } from './singleflight';
+export { RedisCacheHandler } from './redis-handler.ts';
+export type { RedisClient, RedisWriteOp } from './redis-handler.ts';
+export { cache } from './cache-api.ts';
+export { setCacheHandler, getCacheHandler } from './handler-store.ts';
+export { setDefaultSingleflightTimeout } from './timber-cache.ts';
+export { estimateByteSize } from './sizeof.ts';
+export { TagAwareCacheHandler } from './tag-aware-handler.ts';
+export type { CacheStore } from './store.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACrE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAGD,MAAM,WAAW,YAAY,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC;IAC1C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,yBAAyB;IACxC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,kBAAmB,YAAW,YAAY;IACrD,OAAO,CAAC,KAAK,CAA4E;IACzF,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,CAAC,EAAE,yBAAyB;IAItC,GAAG,CAAC,GAAG,EAAE,MAAM;;;;IAYf,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE;IAuBtE,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;IAarD,gDAAgD;IAChD,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,YAAY,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"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"}