@blokjs/runner 0.2.0

package/dist/cache/NodeResultCache.js

@@ -0,0 +1,499 @@
+/**
+ * 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).
+ */
+import { createHash } from "node:crypto";
+/**
+ * Estimate the byte-size of an arbitrary value by serialising it to JSON.
+ * Falls back to 0 for values that cannot be serialised.
+ */
+function estimateSize(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value), "utf-8");
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Produce a deterministic SHA-256 hex digest for a cache key string.
+ */
+function sha256(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+const DEFAULT_MAX_SIZE = 500;
+const DEFAULT_TTL_MS = 60_000;
+const DEFAULT_MAX_MEMORY_BYTES = 50 * 1024 * 1024; // 50 MB
+const SWEEP_INTERVAL_MS = 60_000; // 60 s
+/**
+ * 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 class InMemoryCache {
+    name = "in-memory";
+    store = new Map();
+    maxSize;
+    defaultTTLMs;
+    maxMemoryBytes;
+    onEvict;
+    _hits = 0;
+    _misses = 0;
+    _evictions = 0;
+    _totalSets = 0;
+    _memoryUsageBytes = 0;
+    sweepTimer = null;
+    constructor(config = {}) {
+        this.maxSize = config.maxSize ?? DEFAULT_MAX_SIZE;
+        this.defaultTTLMs = config.defaultTTLMs ?? DEFAULT_TTL_MS;
+        this.maxMemoryBytes = config.maxMemoryBytes ?? DEFAULT_MAX_MEMORY_BYTES;
+        this.onEvict = config.onEvict;
+        this.startPeriodicSweep();
+    }
+    // -- CacheProvider implementation ----------------------------------------
+    /** @inheritdoc */
+    async get(key) {
+        const internal = this.store.get(key);
+        if (!internal) {
+            this._misses++;
+            return null;
+        }
+        // Lazy TTL check
+        if (Date.now() >= internal.entry.expiresAt) {
+            this.evict(key, "ttl");
+            this._misses++;
+            return null;
+        }
+        // Promote to most-recently-used (re-insert at the end of the Map)
+        this.store.delete(key);
+        internal.entry.hits++;
+        this.store.set(key, internal);
+        this._hits++;
+        return { ...internal.entry };
+    }
+    /** @inheritdoc */
+    async set(key, value, options) {
+        this._totalSets++;
+        const ttlMs = options?.ttlMs ?? this.defaultTTLMs;
+        const tags = options?.tags ?? [];
+        const priority = options?.priority ?? 0;
+        const size = estimateSize(value);
+        const now = Date.now();
+        // If the key already exists, remove it first so the new entry goes to
+        // the end of the Map (most-recently-used position).
+        const existing = this.store.get(key);
+        if (existing) {
+            this._memoryUsageBytes -= existing.entry.size;
+            this.store.delete(key);
+        }
+        const entry = {
+            value,
+            key,
+            createdAt: now,
+            expiresAt: now + ttlMs,
+            hits: 0,
+            size,
+        };
+        const internal = { entry, tags, priority };
+        this.store.set(key, internal);
+        this._memoryUsageBytes += size;
+        // Enforce memory limit
+        this.enforceMemoryLimit();
+        // Enforce max-size limit via LRU eviction
+        this.enforceSizeLimit();
+    }
+    /** @inheritdoc */
+    async delete(key) {
+        return this.evict(key, "manual");
+    }
+    /** @inheritdoc */
+    async clear() {
+        this.store.clear();
+        this._memoryUsageBytes = 0;
+    }
+    /** @inheritdoc */
+    async has(key) {
+        const internal = this.store.get(key);
+        if (!internal)
+            return false;
+        if (Date.now() >= internal.entry.expiresAt) {
+            this.evict(key, "ttl");
+            return false;
+        }
+        return true;
+    }
+    /** @inheritdoc */
+    getStats() {
+        const total = this._hits + this._misses;
+        return {
+            hits: this._hits,
+            misses: this._misses,
+            size: this.store.size,
+            maxSize: this.maxSize,
+            hitRate: total === 0 ? 0 : this._hits / total,
+            evictions: this._evictions,
+            totalSets: this._totalSets,
+            memoryUsageBytes: this._memoryUsageBytes,
+        };
+    }
+    // -- Extended API --------------------------------------------------------
+    /**
+     * Remove all entries that carry the given tag.
+     *
+     * @param tag - Tag string to match against.
+     * @returns Number of entries removed.
+     */
+    invalidateByTag(tag) {
+        let count = 0;
+        const entries = Array.from(this.store.entries());
+        for (const [key, internal] of entries) {
+            if (internal.tags.includes(tag)) {
+                this.evict(key, "manual");
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Stop the periodic sweep timer and release resources.
+     * Call this when the cache is no longer needed.
+     */
+    destroy() {
+        this.stopPeriodicSweep();
+        this.store.clear();
+        this._memoryUsageBytes = 0;
+    }
+    // -- Private helpers -----------------------------------------------------
+    /**
+     * Evict a single key from the cache.
+     *
+     * @returns `true` if the key existed and was removed.
+     */
+    evict(key, reason) {
+        const internal = this.store.get(key);
+        if (!internal)
+            return false;
+        this.store.delete(key);
+        this._memoryUsageBytes -= internal.entry.size;
+        this._evictions++;
+        if (this.onEvict) {
+            try {
+                this.onEvict(key, reason);
+            }
+            catch {
+                // Eviction callbacks must not throw into the hot path.
+            }
+        }
+        return true;
+    }
+    /**
+     * Evict the least-recently-used entries until `store.size <= maxSize`.
+     * Entries with higher priority are skipped in favour of lower-priority ones.
+     */
+    enforceSizeLimit() {
+        while (this.store.size > this.maxSize) {
+            // Find the entry with the lowest priority among the oldest entries
+            let lowestKey = null;
+            let lowestPriority = Number.POSITIVE_INFINITY;
+            const entries = Array.from(this.store.entries());
+            for (const [key, internal] of entries) {
+                if (internal.priority < lowestPriority) {
+                    lowestPriority = internal.priority;
+                    lowestKey = key;
+                }
+                // Only inspect the oldest quarter (those at the front of the Map)
+                // to keep eviction fast while still respecting priority.
+                if (lowestKey !== null && lowestPriority === 0)
+                    break;
+            }
+            if (lowestKey !== null) {
+                this.evict(lowestKey, "lru");
+            }
+            else {
+                // Safety valve: evict the first (oldest) key.
+                const keys = Array.from(this.store.keys());
+                if (keys.length > 0) {
+                    this.evict(keys[0], "lru");
+                }
+            }
+        }
+    }
+    /**
+     * Evict entries until `_memoryUsageBytes <= maxMemoryBytes`.
+     */
+    enforceMemoryLimit() {
+        while (this._memoryUsageBytes > this.maxMemoryBytes && this.store.size > 0) {
+            const keys = Array.from(this.store.keys());
+            if (keys.length === 0)
+                break;
+            this.evict(keys[0], "memory");
+        }
+    }
+    /**
+     * Sweep all expired entries.  Called periodically by the background timer.
+     */
+    sweep() {
+        const now = Date.now();
+        const entries = Array.from(this.store.entries());
+        for (const [key, internal] of entries) {
+            if (now >= internal.entry.expiresAt) {
+                this.evict(key, "ttl");
+            }
+        }
+    }
+    startPeriodicSweep() {
+        this.sweepTimer = setInterval(() => this.sweep(), SWEEP_INTERVAL_MS);
+        if (this.sweepTimer.unref) {
+            this.sweepTimer.unref();
+        }
+    }
+    stopPeriodicSweep() {
+        if (this.sweepTimer) {
+            clearInterval(this.sweepTimer);
+            this.sweepTimer = null;
+        }
+    }
+}
+/**
+ * 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 class NodeResultCache {
+    static instance = null;
+    provider;
+    enabled;
+    keyStrategy;
+    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.
+     */
+    inflight = new Map();
+    constructor(config = {}) {
+        this.provider = config.provider ?? new InMemoryCache();
+        this.enabled = config.enabled ?? true;
+        this.keyStrategy = config.keyStrategy ?? "node-input";
+        this.customKeyFn = config.customKeyFn;
+        if (this.keyStrategy === "custom" && typeof this.customKeyFn !== "function") {
+            throw new Error('NodeResultCache: "custom" key strategy requires a customKeyFn to be provided.');
+        }
+    }
+    // -- Singleton API -------------------------------------------------------
+    /**
+     * Return the singleton instance, creating one with defaults if necessary.
+     */
+    static getInstance() {
+        if (!NodeResultCache.instance) {
+            NodeResultCache.instance = new NodeResultCache();
+        }
+        return NodeResultCache.instance;
+    }
+    /**
+     * Create (or replace) the singleton with the given configuration.
+     *
+     * @returns The newly configured singleton instance.
+     */
+    static configure(config) {
+        // If an existing instance has a destroyable provider, clean it up.
+        if (NodeResultCache.instance) {
+            const oldProvider = NodeResultCache.instance.provider;
+            if (oldProvider instanceof InMemoryCache) {
+                oldProvider.destroy();
+            }
+        }
+        NodeResultCache.instance = new NodeResultCache(config);
+        return NodeResultCache.instance;
+    }
+    /**
+     * Tear down the singleton, releasing any resources held by the provider.
+     */
+    static resetInstance() {
+        if (NodeResultCache.instance) {
+            const provider = NodeResultCache.instance.provider;
+            if (provider instanceof InMemoryCache) {
+                provider.destroy();
+            }
+            NodeResultCache.instance = null;
+        }
+    }
+    // -- Public API ----------------------------------------------------------
+    /**
+     * 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.
+     */
+    async wrapExecution(nodeName, input, execute, options) {
+        const key = this.buildKey(nodeName, input);
+        // Bypass cache entirely when disabled.
+        if (!this.enabled) {
+            const data = await execute();
+            return { data, cached: false, key };
+        }
+        // 1. Check for a cached entry.
+        const cached = await this.provider.get(key);
+        if (cached) {
+            return {
+                data: cached.value,
+                cached: true,
+                key,
+                ttlRemainingMs: Math.max(0, cached.expiresAt - Date.now()),
+            };
+        }
+        // 2. Deduplicate concurrent executions for the same key.
+        const existing = this.inflight.get(key);
+        if (existing) {
+            const data = (await existing);
+            // By this point the first caller will have stored the result.
+            const entry = await this.provider.get(key);
+            return {
+                data,
+                cached: entry !== null,
+                key,
+                ttlRemainingMs: entry ? Math.max(0, entry.expiresAt - Date.now()) : undefined,
+            };
+        }
+        // 3. Execute and cache.
+        const promise = execute();
+        this.inflight.set(key, promise);
+        try {
+            const data = await promise;
+            await this.provider.set(key, data, options);
+            return { data, cached: false, key };
+        }
+        finally {
+            this.inflight.delete(key);
+        }
+    }
+    /**
+     * 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.
+     */
+    async invalidateNode(nodeName) {
+        if (this.provider instanceof InMemoryCache) {
+            const prefix = `node:${nodeName}:`;
+            const store = this.provider.store;
+            const keysToDelete = [];
+            const allKeys = Array.from(store.keys());
+            for (const key of allKeys) {
+                if (key.startsWith(prefix)) {
+                    keysToDelete.push(key);
+                }
+            }
+            for (const key of keysToDelete) {
+                await this.provider.delete(key);
+            }
+        }
+        else {
+            // For external providers: best-effort tag invalidation.
+            await this.invalidateByTags([`node:${nodeName}`]);
+        }
+    }
+    /**
+     * 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.
+     */
+    async invalidateByTags(tags) {
+        if (this.provider instanceof InMemoryCache) {
+            for (const tag of tags) {
+                this.provider.invalidateByTag(tag);
+            }
+        }
+        // External providers would need their own tag invalidation mechanism.
+    }
+    /**
+     * 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.
+     */
+    async warmup(nodeName, inputs, execute, options) {
+        await Promise.all(inputs.map(async (input) => {
+            const key = this.buildKey(nodeName, input);
+            const exists = await this.provider.has(key);
+            if (!exists) {
+                const result = await execute(input);
+                await this.provider.set(key, result, options);
+            }
+        }));
+    }
+    /**
+     * Return the underlying provider's statistics snapshot.
+     */
+    getStats() {
+        return this.provider.getStats();
+    }
+    /**
+     * Return the underlying cache provider instance.
+     */
+    getProvider() {
+        return this.provider;
+    }
+    // -- Private helpers -----------------------------------------------------
+    /**
+     * Derive a cache key from the node name and input based on the configured
+     * {@link CacheKeyStrategy}.
+     */
+    buildKey(nodeName, input) {
+        switch (this.keyStrategy) {
+            case "input-hash":
+                return sha256(JSON.stringify(input));
+            case "node-input":
+                return `node:${nodeName}:${sha256(nodeName + JSON.stringify(input))}`;
+            case "custom":
+                return this.customKeyFn(nodeName, input);
+            default:
+                return `node:${nodeName}:${sha256(nodeName + JSON.stringify(input))}`;
+        }
+    }
+}
+//# sourceMappingURL=NodeResultCache.js.map

package/dist/cache/NodeResultCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeResultCache.js","sourceRoot":"","sources":["../../src/cache/NodeResultCache.ts"],"names":[],"mappings":"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"}

package/dist/cache/index.d.ts

@@ -0,0 +1 @@
+export { InMemoryCache, NodeResultCache, type CacheProvider, type CacheEntry, type CacheSetOptions, type CacheStats, type InMemoryCacheConfig, type CacheKeyStrategy, type CustomKeyFn, type CacheResult, type NodeResultCacheConfig, } from "./NodeResultCache";

package/dist/cache/index.js

@@ -0,0 +1,2 @@
+export { InMemoryCache, NodeResultCache, } from "./NodeResultCache";
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,aAAa,EACb,eAAe,GAUf,MAAM,mBAAmB,CAAC"}

package/dist/cost/CostEstimator.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Cost Estimator for Blok Workflows
+ *
+ * Estimates execution costs per node and workflow based on
+ * runtime type, cloud provider pricing, and optional profiling data.
+ *
+ * @example
+ * ```typescript
+ * const estimator = new CostEstimator({ provider: "aws", executionsPerMonth: 100000 });
+ * const estimate = estimator.estimateWorkflow(workflowDef);
+ * console.log(estimator.toTable());
+ * ```
+ */
+import type { NodeProfile } from "../monitoring/PerformanceProfiler";
+import type { WorkflowDef } from "../visualization/WorkflowVisualizer";
+import { type CloudProvider, type RuntimeCostCategory, type RuntimeCostModel } from "./pricing";
+export interface NodeCostEstimate {
+    nodeName: string;
+    stepName: string;
+    runtime: string;
+    category: RuntimeCostCategory;
+    estimatedDurationMs: number;
+    estimatedMemoryMb: number;
+    costPerExecution: number;
+    monthlyCost: number;
+}
+export interface WorkflowCostEstimate {
+    workflowName: string;
+    nodes: NodeCostEstimate[];
+    costPerExecution: number;
+    monthlyCost: number;
+    executionsPerMonth: number;
+    provider: CloudProvider;
+}
+export interface CostEstimatorConfig {
+    provider?: CloudProvider;
+    executionsPerMonth?: number;
+    customPricing?: Partial<Record<RuntimeCostCategory, Partial<RuntimeCostModel>>>;
+}
+export declare class CostEstimator {
+    private config;
+    private estimates;
+    constructor(config?: CostEstimatorConfig);
+    estimateWorkflow(workflow: WorkflowDef, profiles?: NodeProfile[]): WorkflowCostEstimate;
+    estimateNode(nodeName: string, stepName: string, stepType: string, runtime: string, avgDurationMs?: number, avgMemoryMb?: number): NodeCostEstimate;
+    getEstimates(): WorkflowCostEstimate[];
+    toTable(): string;
+    toJson(): string;
+    reset(): void;
+    private walkSteps;
+    private getCostModel;
+    private inferRuntime;
+    private fmtUsd;
+    private fmtNum;
+    private truncate;
+    private padColumns;
+}