network-ai 5.10.2 → 5.11.0

package/dist/esm/lib/blackboard-backend.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * Pluggable Backend API for Named Blackboards
+ *
+ * Defines the `BlackboardBackend` interface that abstracts the storage layer
+ * used by `SharedBlackboard`. Two built-in implementations are provided:
+ *
+ *  - `FileBackend`   — persisted to disk via LockedBlackboard (default)
+ *  - `MemoryBackend` — pure in-memory, no disk writes (testing / ephemeral boards)
+ *
+ * Custom backends (Redis, CRDT, cloud storage, etc.) can be implemented by
+ * satisfying the `BlackboardBackend` interface and passing the instance to
+ * `orchestrator.getBlackboard(name, { backend: myBackend })`.
+ *
+ * @module BlackboardBackend
+ * @version 1.0.0
+ * @license MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryBackend = exports.FileBackend = void 0;
+const locked_blackboard_1 = require("./locked-blackboard");
+// ============================================================================
+// FILE BACKEND (default — wraps LockedBlackboard)
+// ============================================================================
+/**
+ * File-backed persistent storage using `LockedBlackboard`.
+ *
+ * All writes are atomic and file-locked. Data survives process restarts.
+ * This is the default backend used when no `backend` option is provided to
+ * `orchestrator.getBlackboard()`.
+ *
+ * @example
+ * ```typescript
+ * const board = orchestrator.getBlackboard('reports', {
+ *   backend: new FileBackend('./data/reports'),
+ * });
+ * ```
+ */
+class FileBackend {
+    lb;
+    constructor(basePath) {
+        this.lb = new locked_blackboard_1.LockedBlackboard(basePath);
+    }
+    read(key) {
+        return this.lb.read(key);
+    }
+    write(key, value, sourceAgent, ttl) {
+        return this.lb.write(key, value, sourceAgent, ttl);
+    }
+    delete(key) {
+        return this.lb.delete(key);
+    }
+    listKeys() {
+        return this.lb.listKeys();
+    }
+    getSnapshot() {
+        return this.lb.getSnapshot();
+    }
+}
+exports.FileBackend = FileBackend;
+// ============================================================================
+// MEMORY BACKEND (pure in-memory, no disk)
+// ============================================================================
+/**
+ * Pure in-memory backend — data lives only for the lifetime of the process.
+ *
+ * Ideal for:
+ * - Unit testing (no temp directories, instant, isolated)
+ * - Short-lived ephemeral boards
+ * - Read-heavy caches that don't need persistence
+ *
+ * Thread-safety note: Node.js is single-threaded; no locking is needed for
+ * in-process use. For multi-process scenarios use `FileBackend` or a
+ * distributed backend (Redis, etc.).
+ *
+ * @example
+ * ```typescript
+ * const board = orchestrator.getBlackboard('ephemeral', {
+ *   backend: new MemoryBackend(),
+ * });
+ * ```
+ */
+class MemoryBackend {
+    store = new Map();
+    isExpired(entry) {
+        if (!entry.ttl)
+            return false;
+        return Date.now() > new Date(entry.timestamp).getTime() + entry.ttl * 1000;
+    }
+    read(key) {
+        const entry = this.store.get(key);
+        if (!entry || this.isExpired(entry))
+            return null;
+        return entry;
+    }
+    write(key, value, sourceAgent, ttl) {
+        const existing = this.store.get(key);
+        const version = existing ? existing.version + 1 : 1;
+        const entry = {
+            key,
+            value,
+            source_agent: sourceAgent,
+            timestamp: new Date().toISOString(),
+            ttl: ttl ?? null,
+            version,
+        };
+        this.store.set(key, entry);
+        return entry;
+    }
+    delete(key) {
+        return this.store.delete(key);
+    }
+    listKeys() {
+        return Array.from(this.store.entries())
+            .filter(([, entry]) => !this.isExpired(entry))
+            .map(([key]) => key);
+    }
+    getSnapshot() {
+        const result = {};
+        for (const [key, entry] of this.store.entries()) {
+            if (!this.isExpired(entry)) {
+                result[key] = entry;
+            }
+        }
+        return result;
+    }
+    /**
+     * Clear all entries. Useful for test teardown.
+     */
+    clear() {
+        this.store.clear();
+    }
+    /**
+     * Returns the current entry count (including expired entries not yet evicted).
+     */
+    size() {
+        return this.store.size;
+    }
+}
+exports.MemoryBackend = MemoryBackend;
+//# sourceMappingURL=blackboard-backend.js.map

package/dist/esm/lib/blackboard-backend.js.map

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