@enterstellar-ai/cache 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,433 @@
+import { ComponentIntent, CompilationResult, ComponentContract } from '@enterstellar-ai/types';
+
+/**
+ * @module @enterstellar-ai/cache/types
+ * @description Cache-local type definitions.
+ *
+ * This file declares the `RenderCache` interface (the public API surface),
+ * `RenderCacheConfig` (factory configuration), `CachedRender` (cached entry
+ * shape), `CacheStats` (observability), and warmup-related types.
+ *
+ * **Naming:** Interface for the object with methods (`RenderCache`), types for
+ * data shapes (`CachedRender`, `CacheStats`, etc.) — per Design Choice T1.
+ *
+ * **L15 compliance:** Zero framework imports. This module is platform-agnostic.
+ *
+ * @see Implementation Bible §4.6
+ * @see Design Choices CA1–CA7
+ */
+
+/**
+ * Configuration for `createRenderCache()`.
+ *
+ * @see Implementation Bible §4.6
+ * @see Design Choice CA2 — cache `CompilationResult` only.
+ */
+type RenderCacheConfig = {
+    /**
+     * Cache eviction strategy.
+     * Currently only LRU is supported — future strategies may include LFU.
+     */
+    readonly strategy: 'lru';
+    /**
+     * Maximum number of entries in the cache.
+     * When exceeded, the least-recently-used entry is evicted.
+     *
+     * @default 1000
+     * @see Design Choice CA3 — global cache, no zone partitioning.
+     */
+    readonly maxEntries: number;
+    /**
+     * Time-to-live for cached entries, in seconds.
+     * Entries older than TTL are lazily evicted on next `get()`.
+     *
+     * @default 3600
+     * @see Design Choice CA4 — TTL expiry is one of four invalidation triggers.
+     */
+    readonly ttl: number;
+    /**
+     * Optional callback invoked whenever an entry is invalidated or evicted.
+     * Useful for DevTools Cache Dashboard integration.
+     *
+     * @param key - The cache key that was invalidated.
+     * @param reason - The reason for invalidation.
+     */
+    readonly onEvict?: (key: string, reason: EvictionReason) => void;
+};
+/**
+ * Reason an entry was evicted from the cache.
+ *
+ * - `'expired'` — TTL exceeded (lazy eviction on `get()`).
+ * - `'capacity'` — LRU eviction due to `maxEntries` limit.
+ * - `'manual'` — Explicitly invalidated via `invalidate()` or `invalidateAll()`.
+ * - `'component-update'` — Registry component update/unregister (CA5).
+ */
+type EvictionReason = 'expired' | 'capacity' | 'manual' | 'component-update';
+/**
+ * A cached render entry — the value stored in the cache.
+ *
+ * Contains the compiled intent and its compilation result (per CA2 — only
+ * `CompilationResult` is cached, NOT rendered React trees).
+ *
+ * @see Design Choice CA2 — `CompilationResult` only, not rendered React tree.
+ */
+type CachedRender = {
+    /** The original compiled intent that produced this result. */
+    readonly compiledIntent: ComponentIntent;
+    /** The compilation result from the compiler pipeline. */
+    readonly compilationResult: CompilationResult;
+    /** Timestamp (ms since epoch) when this entry was cached. */
+    readonly cachedAt: number;
+    /** Timestamp (ms since epoch) when this entry expires. */
+    readonly expiresAt: number;
+};
+/**
+ * Cache performance statistics.
+ *
+ * Exposed via `renderCache.getStats()` for DevTools Cache Dashboard.
+ * Stats are cumulative since last `invalidateAll()` call.
+ */
+type CacheStats = {
+    /** Total number of cache hits since last reset. */
+    readonly hits: number;
+    /** Total number of cache misses since last reset. */
+    readonly misses: number;
+    /** Current number of entries in the cache. */
+    readonly entries: number;
+    /**
+     * Cache hit rate as a ratio (0.0–1.0).
+     * Calculated as `hits / (hits + misses)`. Returns `0` if no lookups yet.
+     */
+    readonly hitRate: number;
+};
+/**
+ * A warmup entry describing a zone + intent pair to pre-compile and cache.
+ *
+ * @see Design Choice CA6 — warmup from static config + historical traces.
+ * @see Design Choice CA7 — async warmup, never blocking.
+ */
+type WarmupEntry = {
+    /** Zone name for the cache key context. */
+    readonly zone: string;
+    /** The component intent to pre-compile and cache. */
+    readonly intent: ComponentIntent;
+};
+/**
+ * Compile function signature for warmup.
+ *
+ * The consumer wires this to `compiler.compile()`. The cache does NOT
+ * import `@enterstellar-ai/compiler` directly — dependency injection keeps the
+ * cache testable and avoids circular dependencies.
+ *
+ * @param intent - The `ComponentIntent` to compile.
+ * @returns The `CompilationResult` from the compiler pipeline.
+ */
+type CompileFn = (intent: ComponentIntent) => Promise<CompilationResult>;
+/**
+ * The Enterstellar Render Cache — makes GenUI feel instant.
+ *
+ * A global (non-zone-partitioned, per CA3) LRU cache that stores
+ * `CompilationResult` entries keyed by `intentHash + componentName` (per CA1).
+ * Cached entries bypass re-compilation for identical intents, dramatically
+ * reducing latency for repeated queries.
+ *
+ * **Factory:** Created via `createRenderCache(config)`. Returns a plain object
+ * with closures — no class instance, no prototype chain (per R1 pattern).
+ *
+ * **Invalidation triggers (CA4):**
+ * - Registry component update/unregister
+ * - Design token change (via `invalidateAll()`)
+ * - TTL expiry (lazy on `get()`)
+ * - Manual `invalidate()` / `invalidateAll()`
+ *
+ * @see Implementation Bible §4.6
+ * @see Design Choices CA1–CA7
+ *
+ * @example
+ * ```ts
+ * import { createRenderCache, buildCacheKey } from '@enterstellar-ai/cache';
+ *
+ * const cache = createRenderCache({ maxEntries: 500, ttl: 1800 });
+ * const key = buildCacheKey(intentHash, componentName);
+ *
+ * // Store
+ * cache.set(key, { compiledIntent, compilationResult, cachedAt, expiresAt });
+ *
+ * // Retrieve
+ * const cached = cache.get(key); // CachedRender | undefined
+ *
+ * // Stats
+ * cache.getStats(); // { hits, misses, entries, hitRate }
+ * ```
+ */
+interface RenderCache {
+    /**
+     * Retrieves a cached render entry by key.
+     *
+     * Returns `undefined` if the key is not found or the entry has expired.
+     * Expired entries are lazily evicted on access.
+     * A successful lookup counts as a cache hit; a miss (including expiry)
+     * counts as a cache miss.
+     *
+     * @param key - Cache key (from `buildCacheKey()`).
+     * @returns The cached render entry, or `undefined` if not found/expired.
+     */
+    get(key: string): CachedRender | undefined;
+    /**
+     * Stores a render entry in the cache.
+     *
+     * If the cache is at capacity (`maxEntries`), the least-recently-used
+     * entry is evicted before insertion.
+     *
+     * @param key - Cache key (from `buildCacheKey()`).
+     * @param render - The `CachedRender` entry to store.
+     */
+    set(key: string, render: CachedRender): void;
+    /**
+     * Invalidates (removes) a single entry by exact key.
+     *
+     * @param key - Cache key to remove.
+     * @returns `true` if an entry was removed, `false` if the key was not found.
+     */
+    invalidate(key: string): boolean;
+    /**
+     * Invalidates all cache entries for a specific component name.
+     *
+     * Iterates all entries and evicts those whose `compilationResult` resolved
+     * to the given component name. Returns the count of evicted entries.
+     *
+     * @param componentName - PascalCase component name.
+     * @returns The number of entries evicted.
+     *
+     * @see Design Choice CA5 — evict ALL entries for a changed component.
+     */
+    invalidateByComponent(componentName: string): number;
+    /**
+     * Clears the entire cache and resets all stats counters.
+     *
+     * @see Design Choice CA4 — manual clear is one of four invalidation triggers.
+     */
+    invalidateAll(): void;
+    /**
+     * Returns a snapshot of cache performance statistics.
+     *
+     * Stats are cumulative since the last `invalidateAll()` call.
+     *
+     * @returns A `CacheStats` object with hits, misses, entries, and hitRate.
+     */
+    getStats(): CacheStats;
+    /**
+     * Pre-warms the cache with common intents.
+     *
+     * Compiles each intent via the provided `compile` function and stores
+     * the result. Failures are logged and skipped — warmup never throws.
+     *
+     * Should be called after app startup using `requestIdleCallback` or
+     * `setTimeout(0)` as a fallback (per CA7 — never blocking).
+     *
+     * @param entries - Array of `{ zone, intent }` pairs to pre-compile.
+     * @param compile - Compile function (typically `compiler.compile()`).
+     *
+     * @see Design Choice CA6 — warmup from static config + historical traces.
+     * @see Design Choice CA7 — async warmup, never blocking.
+     */
+    warmup(entries: readonly WarmupEntry[], compile: CompileFn): Promise<void>;
+    /**
+     * Current number of entries in the cache.
+     */
+    readonly size: number;
+}
+
+/**
+ * @module @enterstellar-ai/cache/create-render-cache
+ * @description Factory function for creating an Enterstellar Render Cache.
+ *
+ * Returns a plain object with closures (per R1 — no class instance, no
+ * prototype chain). The cache uses an internal LRU data structure for O(1)
+ * get/set/eviction, with lazy TTL expiry on `get()`.
+ *
+ * **Configuration defaults:**
+ * - `strategy: 'lru'`
+ * - `maxEntries: 1000`
+ * - `ttl: 3600` (1 hour in seconds)
+ *
+ * **L15 compliance:** Zero framework imports. Pure TypeScript.
+ *
+ * @see Implementation Bible §4.6
+ * @see Design Choices CA1–CA7
+ */
+
+/**
+ * Creates an Enterstellar Render Cache for compiled intents.
+ *
+ * The cache stores `CompilationResult` entries (per CA2 — NOT rendered React
+ * trees) in a global LRU (per CA3 — no zone partitioning). Cache keys are
+ * `intentHash + componentName` (per CA1 — NOT prop hashes).
+ *
+ * Configuration is validated with Zod at creation time (fail-fast). Invalid
+ * config throws `EnterstellarError` with code `ENS-3001`.
+ *
+ * @param config - Optional partial configuration. Unspecified fields use defaults.
+ * @returns A `RenderCache` instance (plain object with closures per R1).
+ * @throws {EnterstellarError} If the configuration is invalid (`ENS-3001`).
+ *
+ * @see Implementation Bible §4.6
+ * @see Design Choice CA1 — cache key = intentHash + componentName.
+ * @see Design Choice CA2 — cache `CompilationResult` only.
+ * @see Design Choice CA3 — global cache, no zone partitioning.
+ *
+ * @example
+ * ```ts
+ * import { createRenderCache, buildCacheKey } from '@enterstellar-ai/cache';
+ *
+ * const cache = createRenderCache({ maxEntries: 500, ttl: 1800 });
+ * const key = buildCacheKey(intentHash, 'PatientVitals');
+ *
+ * cache.set(key, {
+ *   compiledIntent: intent,
+ *   compilationResult: result,
+ *   cachedAt: Date.now(),
+ *   expiresAt: Date.now() + 1800 * 1000,
+ * });
+ *
+ * const cached = cache.get(key); // CachedRender | undefined
+ * ```
+ */
+declare function createRenderCache(config?: Partial<RenderCacheConfig>): RenderCache;
+
+/**
+ * @module @enterstellar-ai/cache/cache-key
+ * @description Cache key construction utility.
+ *
+ * Builds deterministic cache keys from an intent hash and resolved component
+ * name. The key format follows Design Choice CA1: the cache key is based on
+ * the *decision* (which component for which intent), NOT on prop variations.
+ *
+ * **Rationale (CA1):** Hashing props misses the cache if the LLM changes a
+ * trivial field (timestamp, request ID). The decision to use `PatientVitals`
+ * for "show patient vitals" is stable regardless of prop variations.
+ *
+ * **L15 compliance:** Zero framework imports. Pure TypeScript.
+ *
+ * @see Design Choice CA1 — intent hash + resolved component name.
+ */
+/**
+ * Builds a deterministic cache key from an intent hash and component name.
+ *
+ * The intent hash is typically a SHA-256 of the raw intent string (produced
+ * by `@enterstellar-ai/telemetry`). The component name is the PascalCase name of the
+ * resolved component from the registry.
+ *
+ * @param intentHash - Hash of the raw intent string (e.g., SHA-256 hex).
+ * @param componentName - PascalCase name of the resolved component.
+ * @returns A deterministic cache key string.
+ *
+ * @see Design Choice CA1 — key = intentHash + componentName, NOT props.
+ *
+ * @example
+ * ```ts
+ * import { buildCacheKey } from '@enterstellar-ai/cache';
+ *
+ * const key = buildCacheKey(
+ *   'a1b2c3d4e5f6...', // SHA-256 of "show patient vitals"
+ *   'PatientVitals',
+ * );
+ * // => "a1b2c3d4e5f6...::PatientVitals"
+ * ```
+ */
+declare function buildCacheKey(intentHash: string, componentName: string): string;
+
+/**
+ * @module @enterstellar-ai/cache/with-registry-invalidation
+ * @description Wires registry events to cache invalidation.
+ *
+ * Higher-order function that subscribes to `EnterstellarRegistry` events (`update`,
+ * `unregister`) and automatically calls `cache.invalidateByComponent()` for
+ * the affected component. New component registrations (`register` events)
+ * do NOT trigger invalidation — new components don't affect existing cache
+ * entries.
+ *
+ * **Dependency model:** `EnterstellarRegistry` is imported as a **type-only** import.
+ * The registry instance is injected at runtime by the consumer. There is NO
+ * hard dependency on `@enterstellar-ai/registry` in `package.json`. This avoids
+ * circular dependencies and keeps the cache self-contained.
+ *
+ * **L15 compliance:** Zero framework imports. Pure TypeScript.
+ *
+ * @see Design Choice CA4 — registry update is one of four invalidation triggers.
+ * @see Design Choice CA5 — evict ALL entries for a changed component.
+ */
+
+/**
+ * Minimal interface required from an `EnterstellarRegistry` for cache invalidation.
+ *
+ * This avoids importing the full `EnterstellarRegistry` type from `@enterstellar-ai/registry`,
+ * keeping `@enterstellar-ai/cache` decoupled. Any object that satisfies this interface
+ * (including the real `EnterstellarRegistry`) can be used.
+ *
+ * @see Design Choice R18 — registry emits `register`, `unregister`, `update` events.
+ */
+interface CacheInvalidationSource {
+    /**
+     * Subscribes to a registry event.
+     *
+     * @param event - The event type to listen for.
+     * @param handler - Callback receiving the affected contract.
+     * @returns An unsubscribe function.
+     */
+    on(event: 'register' | 'unregister' | 'update', handler: (contract: ComponentContract) => void): () => void;
+}
+/**
+ * Result of wiring registry invalidation to a cache.
+ * Contains the cache (unchanged) and a dispose function for cleanup.
+ */
+type RegistryInvalidationBinding = {
+    /** The same `RenderCache` instance passed in (for chaining convenience). */
+    readonly cache: RenderCache;
+    /**
+     * Unsubscribes all registry event listeners.
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    readonly dispose: () => void;
+};
+/**
+ * Wires registry events to cache invalidation.
+ *
+ * Subscribes to `update` and `unregister` events on the provided registry
+ * (or any object implementing `CacheInvalidationSource`). When a component
+ * is updated or removed, all cache entries for that component are evicted
+ * (per CA5 — evict ALL entries for the changed component).
+ *
+ * The `register` event is intentionally ignored — new component registrations
+ * do not invalidate existing cache entries.
+ *
+ * Returns a `dispose()` function that unsubscribes all listeners. This should
+ * be called during app teardown or when the cache is no longer needed.
+ *
+ * @param cache - The `RenderCache` to wire invalidation to.
+ * @param registry - An `EnterstellarRegistry` (or compatible `CacheInvalidationSource`).
+ * @returns A `RegistryInvalidationBinding` with the cache and a dispose function.
+ *
+ * @see Design Choice CA4 — registry update triggers cache invalidation.
+ * @see Design Choice CA5 — ALL entries for a changed component are evicted.
+ *
+ * @example
+ * ```ts
+ * import { createRenderCache, withRegistryInvalidation } from '@enterstellar-ai/cache';
+ * import { createRegistry } from '@enterstellar-ai/registry';
+ *
+ * const cache = createRenderCache();
+ * const registry = createRegistry({ components: [...] });
+ *
+ * const { dispose } = withRegistryInvalidation(cache, registry);
+ *
+ * // When a component is updated in the registry, the cache auto-evicts
+ * // all entries for that component.
+ *
+ * // Cleanup on app teardown:
+ * dispose();
+ * ```
+ */
+declare function withRegistryInvalidation(cache: RenderCache, registry: CacheInvalidationSource): RegistryInvalidationBinding;
+
+export { type CacheInvalidationSource, type CacheStats, type CachedRender, type CompileFn, type EvictionReason, type RegistryInvalidationBinding, type RenderCache, type RenderCacheConfig, type WarmupEntry, buildCacheKey, createRenderCache, withRegistryInvalidation };