@soulcraft/brainy 3.8.3 → 3.9.0

package/dist/utils/mutex.js

@@ -0,0 +1,221 @@
+/**
+ * Universal Mutex Implementation for Thread-Safe Operations
+ * Provides consistent locking across all storage adapters
+ * Critical for preventing race conditions in count operations
+ */
+/**
+ * In-memory mutex for single-process scenarios
+ * Used by MemoryStorage and as fallback for other adapters
+ */
+export class InMemoryMutex {
+    constructor() {
+        this.locks = new Map();
+    }
+    async acquire(key, timeout = 30000) {
+        if (!this.locks.has(key)) {
+            this.locks.set(key, { queue: [], locked: false });
+        }
+        const lock = this.locks.get(key);
+        if (!lock.locked) {
+            lock.locked = true;
+            return () => this.release(key);
+        }
+        // Wait in queue
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                const index = lock.queue.indexOf(resolver);
+                if (index !== -1) {
+                    lock.queue.splice(index, 1);
+                }
+                reject(new Error(`Mutex timeout for key: ${key}`));
+            }, timeout);
+            const resolver = () => {
+                clearTimeout(timer);
+                lock.locked = true;
+                resolve(() => this.release(key));
+            };
+            lock.queue.push(resolver);
+        });
+    }
+    release(key) {
+        const lock = this.locks.get(key);
+        if (!lock)
+            return;
+        if (lock.queue.length > 0) {
+            const next = lock.queue.shift();
+            next();
+        }
+        else {
+            lock.locked = false;
+            // Clean up if no waiters
+            if (lock.queue.length === 0) {
+                this.locks.delete(key);
+            }
+        }
+    }
+    async runExclusive(key, fn, timeout) {
+        const release = await this.acquire(key, timeout);
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    }
+    isLocked(key) {
+        return this.locks.get(key)?.locked || false;
+    }
+}
+/**
+ * File-based mutex for multi-process scenarios (Node.js)
+ * Uses atomic file operations to prevent TOCTOU races
+ */
+export class FileMutex {
+    constructor(lockDir) {
+        this.processLocks = new Map();
+        this.lockTimers = new Map();
+        this.lockDir = lockDir;
+        // Lazy load Node.js modules
+        if (typeof window === 'undefined') {
+            this.fs = require('fs');
+            this.path = require('path');
+        }
+    }
+    async acquire(key, timeout = 30000) {
+        if (!this.fs || !this.path) {
+            throw new Error('FileMutex is only available in Node.js environments');
+        }
+        const lockFile = this.path.join(this.lockDir, `${key}.lock`);
+        const lockId = `${Date.now()}_${Math.random()}_${process.pid}`;
+        const startTime = Date.now();
+        // Ensure lock directory exists
+        await this.fs.promises.mkdir(this.lockDir, { recursive: true });
+        while (Date.now() - startTime < timeout) {
+            try {
+                // Atomic lock creation using 'wx' flag
+                await this.fs.promises.writeFile(lockFile, JSON.stringify({
+                    lockId,
+                    pid: process.pid,
+                    timestamp: Date.now(),
+                    expiresAt: Date.now() + timeout
+                }), { flag: 'wx' } // Write exclusive - fails if exists
+                );
+                // Successfully acquired lock
+                const release = () => this.release(key, lockFile, lockId);
+                this.processLocks.set(key, release);
+                // Auto-release on timeout
+                const timer = setTimeout(() => {
+                    release();
+                }, timeout);
+                this.lockTimers.set(key, timer);
+                return release;
+            }
+            catch (error) {
+                if (error.code === 'EEXIST') {
+                    // Lock exists - check if expired
+                    try {
+                        const data = await this.fs.promises.readFile(lockFile, 'utf-8');
+                        const lock = JSON.parse(data);
+                        if (lock.expiresAt < Date.now()) {
+                            // Expired - try to remove
+                            try {
+                                await this.fs.promises.unlink(lockFile);
+                                continue; // Retry acquisition
+                            }
+                            catch (unlinkError) {
+                                if (unlinkError.code !== 'ENOENT') {
+                                    // Someone else removed it, continue
+                                    continue;
+                                }
+                            }
+                        }
+                    }
+                    catch {
+                        // Can't read lock file, assume it's valid
+                    }
+                    // Wait before retry
+                    await new Promise(resolve => setTimeout(resolve, 50));
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        throw new Error(`Failed to acquire mutex for key: ${key} after ${timeout}ms`);
+    }
+    async release(key, lockFile, lockId) {
+        // Clear timer
+        const timer = this.lockTimers.get(key);
+        if (timer) {
+            clearTimeout(timer);
+            this.lockTimers.delete(key);
+        }
+        // Remove from process locks
+        this.processLocks.delete(key);
+        try {
+            // Verify we own the lock before releasing
+            const data = await this.fs.promises.readFile(lockFile, 'utf-8');
+            const lock = JSON.parse(data);
+            if (lock.lockId === lockId) {
+                await this.fs.promises.unlink(lockFile);
+            }
+        }
+        catch {
+            // Lock already released or doesn't exist
+        }
+    }
+    async runExclusive(key, fn, timeout) {
+        const release = await this.acquire(key, timeout);
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    }
+    isLocked(key) {
+        return this.processLocks.has(key);
+    }
+    /**
+     * Clean up all locks held by this process
+     */
+    async cleanup() {
+        // Clear all timers
+        for (const timer of this.lockTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.lockTimers.clear();
+        // Release all locks
+        const releases = Array.from(this.processLocks.values());
+        await Promise.all(releases.map(release => release()));
+        this.processLocks.clear();
+    }
+}
+/**
+ * Factory to create appropriate mutex for the environment
+ */
+export function createMutex(options) {
+    const type = options?.type || (typeof window === 'undefined' ? 'file' : 'memory');
+    if (type === 'file' && typeof window === 'undefined') {
+        const lockDir = options?.lockDir || '.brainy/locks';
+        return new FileMutex(lockDir);
+    }
+    return new InMemoryMutex();
+}
+// Global mutex instance for count operations
+let globalMutex = null;
+export function getGlobalMutex() {
+    if (!globalMutex) {
+        globalMutex = createMutex();
+    }
+    return globalMutex;
+}
+/**
+ * Cleanup function for graceful shutdown
+ */
+export async function cleanupMutexes() {
+    if (globalMutex && 'cleanup' in globalMutex) {
+        await globalMutex.cleanup();
+    }
+}
+//# sourceMappingURL=mutex.js.map

package/dist/utils/paramValidation.js

@@ -130,11 +130,24 @@ export function validateFindParams(params) {
 export function validateAddParams(params) {
     // Universal truth: must have data or vector
     if (!params.data && !params.vector) {
-        throw new Error('must provide either data or vector');
+        throw new Error(`Invalid add() parameters: Missing required field 'data'\n` +
+            `\nReceived: ${JSON.stringify({
+                type: params.type,
+                hasMetadata: !!params.metadata,
+                hasId: !!params.id
+            }, null, 2)}\n` +
+            `\nExpected one of:\n` +
+            `  { data: 'text to store', type?: 'note', metadata?: {...} }\n` +
+            `  { vector: [0.1, 0.2, ...], type?: 'embedding', metadata?: {...} }\n` +
+            `\nExamples:\n` +
+            `  await brain.add({ data: 'Machine learning is AI', type: 'concept' })\n` +
+            `  await brain.add({ data: { title: 'Doc', content: '...' }, type: 'document' })`);
     }
     // Validate noun type
     if (!Object.values(NounType).includes(params.type)) {
-        throw new Error(`invalid NounType: ${params.type}`);
+        throw new Error(`Invalid NounType: '${params.type}'\n` +
+            `\nValid types: ${Object.values(NounType).join(', ')}\n` +
+            `\nExample: await brain.add({ data: 'text', type: NounType.Note })`);
     }
     // Validate vector dimensions if provided
     if (params.vector) {
@@ -182,8 +195,11 @@ export function validateRelateParams(params) {
     if (params.from === params.to) {
         throw new Error('cannot create self-referential relationship');
     }
-    // Validate verb type
-    if (!Object.values(VerbType).includes(params.type)) {
+    // Validate verb type - default to RelatedTo if not specified
+    if (params.type === undefined) {
+        params.type = VerbType.RelatedTo;
+    }
+    else if (!Object.values(VerbType).includes(params.type)) {
         throw new Error(`invalid VerbType: ${params.type}`);
     }
     // Universal truth: weight must be 0-1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "3.8.3",
+  "version": "3.9.0",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",