@soulcraft/brainy 3.0.0 → 3.1.0

package/dist/utils/nodeVersionCheck.js

@@ -0,0 +1,65 @@
+/**
+ * Node.js Version Compatibility Check
+ *
+ * Brainy requires Node.js 22.x LTS for maximum stability with ONNX Runtime.
+ * This prevents V8 HandleScope locking issues in worker threads.
+ */
+/**
+ * Check if the current Node.js version is supported
+ */
+export function checkNodeVersion() {
+    const nodeVersion = process.version;
+    const majorVersion = parseInt(nodeVersion.split('.')[0].substring(1));
+    const versionInfo = {
+        current: nodeVersion,
+        major: majorVersion,
+        isSupported: majorVersion === 22,
+        recommendation: 'Node.js 22.x LTS'
+    };
+    return versionInfo;
+}
+/**
+ * Enforce Node.js version requirement with helpful error messaging
+ */
+export function enforceNodeVersion() {
+    const versionInfo = checkNodeVersion();
+    if (!versionInfo.isSupported) {
+        const errorMessage = [
+            '🚨 BRAINY COMPATIBILITY ERROR',
+            '━'.repeat(50),
+            `❌ Current Node.js: ${versionInfo.current}`,
+            `✅ Required: ${versionInfo.recommendation}`,
+            '',
+            '💡 Quick Fix:',
+            '  nvm install 22 && nvm use 22',
+            '  npm install',
+            '',
+            '📖 Why Node.js 22?',
+            '  • Maximum ONNX Runtime stability',
+            '  • Prevents V8 threading crashes',
+            '  • Optimal zero-config performance',
+            '',
+            '🔗 More info: https://github.com/soulcraftlabs/brainy#node-version',
+            '━'.repeat(50)
+        ].join('\n');
+        throw new Error(errorMessage);
+    }
+}
+/**
+ * Soft warning for version issues (non-blocking)
+ */
+export function warnNodeVersion() {
+    const versionInfo = checkNodeVersion();
+    if (!versionInfo.isSupported) {
+        console.warn([
+            '⚠️  BRAINY VERSION WARNING',
+            `   Current: ${versionInfo.current}`,
+            `   Recommended: ${versionInfo.recommendation}`,
+            '   Consider upgrading for best stability',
+            ''
+        ].join('\n'));
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=nodeVersionCheck.js.map

package/dist/utils/paramValidation.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Zero-Config Parameter Validation
+ *
+ * Self-configuring validation that adapts to system capabilities
+ * Only enforces universal truths, learns everything else
+ */
+import { FindParams, AddParams, UpdateParams, RelateParams } from '../types/brainy.types.js';
+/**
+ * Universal validations - things that are always invalid
+ * These are mathematical/logical truths, not configuration
+ */
+export declare function validateFindParams(params: FindParams): void;
+/**
+ * Validate add parameters
+ */
+export declare function validateAddParams(params: AddParams): void;
+/**
+ * Validate update parameters
+ */
+export declare function validateUpdateParams(params: UpdateParams): void;
+/**
+ * Validate relate parameters
+ */
+export declare function validateRelateParams(params: RelateParams): void;
+/**
+ * Get current validation configuration
+ * Useful for debugging and monitoring
+ */
+export declare function getValidationConfig(): {
+    maxLimit: number;
+    maxQueryLength: number;
+    maxVectorDimensions: number;
+    systemMemory: number;
+    availableMemory: number;
+};
+/**
+ * Record query performance for auto-tuning
+ */
+export declare function recordQueryPerformance(duration: number, resultCount: number): void;

package/dist/utils/paramValidation.js

@@ -0,0 +1,192 @@
+/**
+ * Zero-Config Parameter Validation
+ *
+ * Self-configuring validation that adapts to system capabilities
+ * Only enforces universal truths, learns everything else
+ */
+import { NounType, VerbType } from '../types/graphTypes.js';
+import * as os from 'os';
+/**
+ * Auto-configured limits based on system resources
+ * These adapt to available memory and observed performance
+ */
+class ValidationConfig {
+    constructor() {
+        // Performance observations
+        this.avgQueryTime = 0;
+        this.queryCount = 0;
+        // Auto-configure based on system resources
+        const totalMemory = os.totalmem();
+        const availableMemory = os.freemem();
+        // Scale limits based on available memory
+        // 1GB = 10K limit, 8GB = 80K limit, etc.
+        this.maxLimit = Math.min(100000, // Absolute max for safety
+        Math.floor(availableMemory / (1024 * 1024 * 100)) * 1000);
+        // Query length scales with memory too
+        this.maxQueryLength = Math.min(50000, Math.floor(availableMemory / (1024 * 1024 * 10)) * 1000);
+        // Vector dimensions (standard for all-MiniLM-L6-v2)
+        this.maxVectorDimensions = 384;
+    }
+    static getInstance() {
+        if (!ValidationConfig.instance) {
+            ValidationConfig.instance = new ValidationConfig();
+        }
+        return ValidationConfig.instance;
+    }
+    /**
+     * Learn from actual usage to adjust limits
+     */
+    recordQuery(duration, resultCount) {
+        this.queryCount++;
+        this.avgQueryTime = (this.avgQueryTime * (this.queryCount - 1) + duration) / this.queryCount;
+        // If queries are consistently fast with large results, increase limits
+        if (this.avgQueryTime < 100 && resultCount > this.maxLimit * 0.8) {
+            this.maxLimit = Math.min(this.maxLimit * 1.5, 100000);
+        }
+        // If queries are slow, reduce limits
+        if (this.avgQueryTime > 1000) {
+            this.maxLimit = Math.max(this.maxLimit * 0.8, 1000);
+        }
+    }
+}
+/**
+ * Universal validations - things that are always invalid
+ * These are mathematical/logical truths, not configuration
+ */
+export function validateFindParams(params) {
+    const config = ValidationConfig.getInstance();
+    // Universal truth: negative pagination never makes sense
+    if (params.limit !== undefined) {
+        if (params.limit < 0) {
+            throw new Error('limit must be non-negative');
+        }
+        if (params.limit > config.maxLimit) {
+            throw new Error(`limit exceeds auto-configured maximum of ${config.maxLimit} (based on available memory)`);
+        }
+    }
+    if (params.offset !== undefined && params.offset < 0) {
+        throw new Error('offset must be non-negative');
+    }
+    // Universal truth: probability/similarity must be 0-1
+    if (params.near?.threshold !== undefined) {
+        const t = params.near.threshold;
+        if (t < 0 || t > 1) {
+            throw new Error('threshold must be between 0 and 1');
+        }
+    }
+    // Universal truth: can't specify both query and vector (they're alternatives)
+    if (params.query !== undefined && params.vector !== undefined) {
+        throw new Error('cannot specify both query and vector - they are mutually exclusive');
+    }
+    // Universal truth: can't use both cursor and offset pagination
+    if (params.cursor !== undefined && params.offset !== undefined) {
+        throw new Error('cannot use both cursor and offset pagination simultaneously');
+    }
+    // Auto-limit query length based on memory
+    if (params.query && params.query.length > config.maxQueryLength) {
+        throw new Error(`query exceeds auto-configured maximum length of ${config.maxQueryLength} characters`);
+    }
+    // Validate vector dimensions if provided
+    if (params.vector && params.vector.length !== config.maxVectorDimensions) {
+        throw new Error(`vector must have exactly ${config.maxVectorDimensions} dimensions`);
+    }
+    // Validate enum types if specified
+    if (params.type) {
+        const types = Array.isArray(params.type) ? params.type : [params.type];
+        for (const type of types) {
+            if (!Object.values(NounType).includes(type)) {
+                throw new Error(`invalid NounType: ${type}`);
+            }
+        }
+    }
+}
+/**
+ * Validate add parameters
+ */
+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');
+    }
+    // Validate noun type
+    if (!Object.values(NounType).includes(params.type)) {
+        throw new Error(`invalid NounType: ${params.type}`);
+    }
+    // Validate vector dimensions if provided
+    if (params.vector) {
+        const config = ValidationConfig.getInstance();
+        if (params.vector.length !== config.maxVectorDimensions) {
+            throw new Error(`vector must have exactly ${config.maxVectorDimensions} dimensions`);
+        }
+    }
+}
+/**
+ * Validate update parameters
+ */
+export function validateUpdateParams(params) {
+    // Universal truth: must have an ID
+    if (!params.id) {
+        throw new Error('id is required for update');
+    }
+    // Universal truth: must update something
+    if (!params.data && !params.metadata && !params.type && !params.vector) {
+        throw new Error('must specify at least one field to update');
+    }
+    // Validate type if changing
+    if (params.type && !Object.values(NounType).includes(params.type)) {
+        throw new Error(`invalid NounType: ${params.type}`);
+    }
+    // Validate vector dimensions if provided
+    if (params.vector) {
+        const config = ValidationConfig.getInstance();
+        if (params.vector.length !== config.maxVectorDimensions) {
+            throw new Error(`vector must have exactly ${config.maxVectorDimensions} dimensions`);
+        }
+    }
+}
+/**
+ * Validate relate parameters
+ */
+export function validateRelateParams(params) {
+    // Universal truths
+    if (!params.from) {
+        throw new Error('from entity ID is required');
+    }
+    if (!params.to) {
+        throw new Error('to entity ID is required');
+    }
+    if (params.from === params.to) {
+        throw new Error('cannot create self-referential relationship');
+    }
+    // Validate verb type
+    if (!Object.values(VerbType).includes(params.type)) {
+        throw new Error(`invalid VerbType: ${params.type}`);
+    }
+    // Universal truth: weight must be 0-1
+    if (params.weight !== undefined) {
+        if (params.weight < 0 || params.weight > 1) {
+            throw new Error('weight must be between 0 and 1');
+        }
+    }
+}
+/**
+ * Get current validation configuration
+ * Useful for debugging and monitoring
+ */
+export function getValidationConfig() {
+    const config = ValidationConfig.getInstance();
+    return {
+        maxLimit: config.maxLimit,
+        maxQueryLength: config.maxQueryLength,
+        maxVectorDimensions: config.maxVectorDimensions,
+        systemMemory: os.totalmem(),
+        availableMemory: os.freemem()
+    };
+}
+/**
+ * Record query performance for auto-tuning
+ */
+export function recordQueryPerformance(duration, resultCount) {
+    ValidationConfig.getInstance().recordQuery(duration, resultCount);
+}
+//# sourceMappingURL=paramValidation.js.map

package/dist/utils/rateLimiter.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Rate Limiter for Brainy API
+ *
+ * Provides rate limiting without external dependencies like Redis.
+ * - Uses in-memory storage for single instances
+ * - Can use S3/R2 for distributed rate limiting
+ *
+ * @module rateLimiter
+ */
+import { BaseStorageAdapter } from '../storage/adapters/baseStorageAdapter.js';
+export interface RateLimitConfig {
+    /**
+     * Maximum number of requests allowed
+     */
+    maxRequests: number;
+    /**
+     * Time window in milliseconds
+     */
+    windowMs: number;
+    /**
+     * Optional message to return when rate limit is exceeded
+     */
+    message?: string;
+    /**
+     * Whether to use distributed storage (S3/R2) for rate limiting
+     */
+    distributed?: boolean;
+    /**
+     * Storage adapter for distributed rate limiting
+     */
+    storage?: BaseStorageAdapter;
+    /**
+     * Key prefix for distributed storage
+     */
+    keyPrefix?: string;
+}
+export interface RateLimitResult {
+    /**
+     * Whether the request is allowed
+     */
+    allowed: boolean;
+    /**
+     * Number of requests remaining in the current window
+     */
+    remaining: number;
+    /**
+     * Time when the rate limit window resets (Unix timestamp)
+     */
+    resetTime: number;
+    /**
+     * Total limit for the window
+     */
+    limit: number;
+}
+/**
+ * Simple in-memory rate limiter
+ */
+export declare class RateLimiter {
+    private config;
+    private requests;
+    private cleanupInterval;
+    constructor(config: RateLimitConfig);
+    /**
+     * Check if a request is allowed and update the rate limit
+     */
+    checkLimit(identifier: string): Promise<RateLimitResult>;
+    /**
+     * Check rate limit using in-memory storage
+     */
+    private checkMemoryLimit;
+    /**
+     * Check rate limit using distributed storage (S3/R2)
+     */
+    private checkDistributedLimit;
+    /**
+     * Reset rate limit for a specific identifier
+     */
+    reset(identifier: string): Promise<void>;
+    /**
+     * Start cleanup interval to remove expired entries
+     */
+    private startCleanup;
+    /**
+     * Stop the rate limiter and cleanup
+     */
+    destroy(): void;
+}
+/**
+ * Express/Connect middleware for rate limiting
+ */
+export declare function rateLimitMiddleware(config: RateLimitConfig): (req: any, res: any, next: any) => Promise<void>;
+/**
+ * Create a rate limiter for use with Brainy
+ *
+ * @example
+ * ```typescript
+ * // For single instance (in-memory)
+ * const limiter = createRateLimiter({
+ *   maxRequests: 100,
+ *   windowMs: 15 * 60 * 1000 // 15 minutes
+ * })
+ *
+ * // For distributed (using S3/R2)
+ * const limiter = createRateLimiter({
+ *   maxRequests: 100,
+ *   windowMs: 15 * 60 * 1000,
+ *   distributed: true,
+ *   storage: myS3Adapter
+ * })
+ *
+ * // Check rate limit
+ * const result = await limiter.checkLimit('user-123')
+ * if (!result.allowed) {
+ *   throw new Error('Rate limit exceeded')
+ * }
+ * ```
+ */
+export declare function createRateLimiter(config: RateLimitConfig): RateLimiter;
+/**
+ * Preset configurations for common use cases
+ */
+export declare const RateLimitPresets: {
+    /**
+     * Default API rate limit: 100 requests per 15 minutes
+     */
+    default: {
+        maxRequests: number;
+        windowMs: number;
+    };
+    /**
+     * Strict rate limit: 10 requests per minute
+     */
+    strict: {
+        maxRequests: number;
+        windowMs: number;
+    };
+    /**
+     * Lenient rate limit: 1000 requests per hour
+     */
+    lenient: {
+        maxRequests: number;
+        windowMs: number;
+    };
+    /**
+     * Search endpoint: 30 requests per minute
+     */
+    search: {
+        maxRequests: number;
+        windowMs: number;
+        message: string;
+    };
+    /**
+     * Write operations: 20 requests per minute
+     */
+    write: {
+        maxRequests: number;
+        windowMs: number;
+        message: string;
+    };
+};