@blokjs/runner 0.2.0

package/dist/cache/NodeResultCache.d.ts

@@ -0,0 +1,286 @@
+/**
+ * Node Result Caching for Blok Runner
+ *
+ * Provides intelligent caching of node execution results to avoid redundant
+ * computation. Supports LRU eviction, TTL-based expiry, tag-based invalidation,
+ * and pluggable cache providers.
+ *
+ * Uses only Node.js built-ins (node:crypto for hashing).
+ */
+/**
+ * A pluggable cache storage backend. Implementations must be safe for
+ * concurrent async access (no overlapping mutations on the same key).
+ */
+export interface CacheProvider {
+    /** Human-readable name of the provider (e.g. "in-memory", "redis"). */
+    readonly name: string;
+    /** Retrieve a cached entry, or `null` if the key is absent / expired. */
+    get<T>(key: string): Promise<CacheEntry<T> | null>;
+    /** Store a value under `key` with optional TTL, tags, and priority. */
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    /** Remove a single key. Returns `true` if the key existed. */
+    delete(key: string): Promise<boolean>;
+    /** Remove *all* entries from the cache. */
+    clear(): Promise<void>;
+    /** Check existence without bumping LRU order. */
+    has(key: string): Promise<boolean>;
+    /** Return a snapshot of hit/miss statistics. */
+    getStats(): CacheStats;
+}
+/** A single cached value together with its metadata. */
+export interface CacheEntry<T> {
+    /** The cached value. */
+    value: T;
+    /** The cache key under which this entry is stored. */
+    key: string;
+    /** Unix-epoch ms when the entry was written. */
+    createdAt: number;
+    /** Unix-epoch ms when the entry will be considered expired. */
+    expiresAt: number;
+    /** Number of times this entry has been read from cache. */
+    hits: number;
+    /** Approximate size in bytes (derived from JSON.stringify length). */
+    size: number;
+}
+/** Options accepted by {@link CacheProvider.set}. */
+export interface CacheSetOptions {
+    /** Time-to-live in milliseconds. Defaults to 60 000 (60 s). */
+    ttlMs?: number;
+    /** Arbitrary string tags for bulk invalidation via {@link InMemoryCache.invalidateByTag}. */
+    tags?: string[];
+    /** Eviction priority. Higher values are evicted later. Default: 0. */
+    priority?: number;
+}
+/** Aggregate cache performance statistics. */
+export interface CacheStats {
+    /** Total cache hits. */
+    hits: number;
+    /** Total cache misses. */
+    misses: number;
+    /** Current number of entries in the cache. */
+    size: number;
+    /** Maximum number of entries allowed. */
+    maxSize: number;
+    /** Hit rate as a ratio (0-1). Returns 0 when no requests have been made. */
+    hitRate: number;
+    /** Number of entries evicted (LRU or TTL). */
+    evictions: number;
+    /** Total number of `set` calls. */
+    totalSets: number;
+    /** Approximate memory consumed by cached values, in bytes. */
+    memoryUsageBytes: number;
+}
+/** Configuration for {@link InMemoryCache}. */
+export interface InMemoryCacheConfig {
+    /** Maximum number of entries before LRU eviction kicks in. Default: 500. */
+    maxSize?: number;
+    /** Default TTL in milliseconds when none is provided on `set`. Default: 60 000. */
+    defaultTTLMs?: number;
+    /** Maximum aggregate byte size of cached values. Default: 50 MB. */
+    maxMemoryBytes?: number;
+    /** Optional callback invoked whenever an entry is evicted. */
+    onEvict?: (key: string, reason: "lru" | "ttl" | "memory" | "manual") => void;
+}
+/**
+ * LRU cache with TTL-based expiry, tag-based invalidation, and memory limits.
+ *
+ * Internally backed by a `Map` whose insertion order is used for LRU tracking.
+ * Every `get` promotes the accessed key to the most-recently-used position.
+ *
+ * Expired entries are cleaned up lazily on access and periodically via a
+ * background sweep timer (every 60 s).  The timer is `unref`-ed so it does
+ * not prevent the Node.js process from exiting.
+ */
+export declare class InMemoryCache implements CacheProvider {
+    readonly name = "in-memory";
+    private readonly store;
+    private readonly maxSize;
+    private readonly defaultTTLMs;
+    private readonly maxMemoryBytes;
+    private readonly onEvict?;
+    private _hits;
+    private _misses;
+    private _evictions;
+    private _totalSets;
+    private _memoryUsageBytes;
+    private sweepTimer;
+    constructor(config?: InMemoryCacheConfig);
+    /** @inheritdoc */
+    get<T>(key: string): Promise<CacheEntry<T> | null>;
+    /** @inheritdoc */
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    /** @inheritdoc */
+    delete(key: string): Promise<boolean>;
+    /** @inheritdoc */
+    clear(): Promise<void>;
+    /** @inheritdoc */
+    has(key: string): Promise<boolean>;
+    /** @inheritdoc */
+    getStats(): CacheStats;
+    /**
+     * Remove all entries that carry the given tag.
+     *
+     * @param tag - Tag string to match against.
+     * @returns Number of entries removed.
+     */
+    invalidateByTag(tag: string): number;
+    /**
+     * Stop the periodic sweep timer and release resources.
+     * Call this when the cache is no longer needed.
+     */
+    destroy(): void;
+    /**
+     * Evict a single key from the cache.
+     *
+     * @returns `true` if the key existed and was removed.
+     */
+    private evict;
+    /**
+     * Evict the least-recently-used entries until `store.size <= maxSize`.
+     * Entries with higher priority are skipped in favour of lower-priority ones.
+     */
+    private enforceSizeLimit;
+    /**
+     * Evict entries until `_memoryUsageBytes <= maxMemoryBytes`.
+     */
+    private enforceMemoryLimit;
+    /**
+     * Sweep all expired entries.  Called periodically by the background timer.
+     */
+    private sweep;
+    private startPeriodicSweep;
+    private stopPeriodicSweep;
+}
+/** Strategy used by {@link NodeResultCache} to derive cache keys. */
+export type CacheKeyStrategy = "input-hash" | "node-input" | "custom";
+/** Custom key generation function. */
+export type CustomKeyFn = (nodeName: string, input: unknown) => string;
+/** The value returned by {@link NodeResultCache.wrapExecution}. */
+export interface CacheResult<O> {
+    /** The execution output (from cache or freshly computed). */
+    data: O;
+    /** `true` when the result was served from cache. */
+    cached: boolean;
+    /** The cache key used for this lookup. */
+    key: string;
+    /** Milliseconds remaining before this entry expires (only when `cached` is true). */
+    ttlRemainingMs?: number;
+}
+/** Configuration for {@link NodeResultCache}. */
+export interface NodeResultCacheConfig {
+    /** The cache provider to use. Defaults to a new {@link InMemoryCache}. */
+    provider?: CacheProvider;
+    /** Whether caching is enabled. Default: `true`. */
+    enabled?: boolean;
+    /** Strategy for generating cache keys. Default: `"node-input"`. */
+    keyStrategy?: CacheKeyStrategy;
+    /** Required when `keyStrategy` is `"custom"`. */
+    customKeyFn?: CustomKeyFn;
+}
+/**
+ * Singleton orchestrator that wraps node executions with transparent caching.
+ *
+ * Typical usage:
+ *
+ * ```ts
+ * const cache = NodeResultCache.getInstance();
+ *
+ * const result = await cache.wrapExecution("myNode", input, async () => {
+ *   return expensiveComputation(input);
+ * });
+ *
+ * console.log(result.cached); // true on subsequent identical calls
+ * ```
+ *
+ * The singleton is configured once via {@link NodeResultCache.configure}.
+ * Subsequent calls to `getInstance()` return the already-configured instance.
+ */
+export declare class NodeResultCache {
+    private static instance;
+    private readonly provider;
+    private readonly enabled;
+    private readonly keyStrategy;
+    private readonly customKeyFn?;
+    /**
+     * In-flight promise map for deduplicating concurrent executions of the
+     * same cache key.  Prevents the "thundering herd" problem where N
+     * concurrent callers all compute the same expensive result.
+     */
+    private readonly inflight;
+    private constructor();
+    /**
+     * Return the singleton instance, creating one with defaults if necessary.
+     */
+    static getInstance(): NodeResultCache;
+    /**
+     * Create (or replace) the singleton with the given configuration.
+     *
+     * @returns The newly configured singleton instance.
+     */
+    static configure(config: NodeResultCacheConfig): NodeResultCache;
+    /**
+     * Tear down the singleton, releasing any resources held by the provider.
+     */
+    static resetInstance(): void;
+    /**
+     * Wrap an async execution with caching.
+     *
+     * If a cached result exists for the derived key it is returned immediately.
+     * Otherwise `execute` is invoked and its result is stored before being
+     * returned.
+     *
+     * Concurrent calls with the same key will share a single in-flight
+     * execution (request coalescing).
+     *
+     * @param nodeName - Logical name of the node being executed.
+     * @param input    - The input payload used to derive the cache key.
+     * @param execute  - Factory that produces the result when no cache hit.
+     * @param options  - Optional TTL, tags, and priority for the cache entry.
+     * @returns A {@link CacheResult} indicating whether the result was cached.
+     */
+    wrapExecution<I, O>(nodeName: string, input: I, execute: () => Promise<O>, options?: CacheSetOptions): Promise<CacheResult<O>>;
+    /**
+     * Invalidate all cache entries whose key starts with the node-specific
+     * prefix.  This is only fully effective with the default `"node-input"`
+     * strategy and the built-in {@link InMemoryCache} provider.
+     *
+     * For external providers, consider using tag-based invalidation instead.
+     *
+     * @param nodeName - Name of the node whose results should be purged.
+     */
+    invalidateNode(nodeName: string): Promise<void>;
+    /**
+     * Invalidate all entries matching *any* of the supplied tags.
+     *
+     * This is a convenience wrapper around {@link InMemoryCache.invalidateByTag}
+     * when the built-in provider is used.
+     *
+     * @param tags - Array of tag strings.
+     */
+    invalidateByTags(tags: string[]): Promise<void>;
+    /**
+     * Pre-populate the cache for a set of known inputs.
+     *
+     * This is useful during application startup to "warm" the cache and
+     * ensure that the first real request for each input is served from cache.
+     *
+     * @param nodeName - Name of the node.
+     * @param inputs   - Array of inputs to pre-compute.
+     * @param execute  - Factory that computes the result for a given input.
+     * @param options  - Optional cache-set options applied to every entry.
+     */
+    warmup<I, O>(nodeName: string, inputs: I[], execute: (input: I) => Promise<O>, options?: CacheSetOptions): Promise<void>;
+    /**
+     * Return the underlying provider's statistics snapshot.
+     */
+    getStats(): CacheStats;
+    /**
+     * Return the underlying cache provider instance.
+     */
+    getProvider(): CacheProvider;
+    /**
+     * Derive a cache key from the node name and input based on the configured
+     * {@link CacheKeyStrategy}.
+     */
+    private buildKey;
+}