@soulcraft/brainy 2.15.0 → 3.0.1

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;
+    };
+};

package/dist/utils/rateLimiter.js

@@ -0,0 +1,271 @@
+/**
+ * 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
+ */
+/**
+ * Simple in-memory rate limiter
+ */
+export class RateLimiter {
+    constructor(config) {
+        this.config = config;
+        this.requests = new Map();
+        this.cleanupInterval = null;
+        // Start cleanup interval to remove expired entries
+        this.startCleanup();
+    }
+    /**
+     * Check if a request is allowed and update the rate limit
+     */
+    async checkLimit(identifier) {
+        const now = Date.now();
+        if (this.config.distributed && this.config.storage) {
+            return this.checkDistributedLimit(identifier, now);
+        }
+        return this.checkMemoryLimit(identifier, now);
+    }
+    /**
+     * Check rate limit using in-memory storage
+     */
+    checkMemoryLimit(identifier, now) {
+        const entry = this.requests.get(identifier);
+        const resetTime = now + this.config.windowMs;
+        if (!entry || entry.resetTime <= now) {
+            // New window or expired window
+            this.requests.set(identifier, {
+                count: 1,
+                resetTime
+            });
+            return {
+                allowed: true,
+                remaining: this.config.maxRequests - 1,
+                resetTime,
+                limit: this.config.maxRequests
+            };
+        }
+        // Existing window
+        if (entry.count < this.config.maxRequests) {
+            entry.count++;
+            return {
+                allowed: true,
+                remaining: this.config.maxRequests - entry.count,
+                resetTime: entry.resetTime,
+                limit: this.config.maxRequests
+            };
+        }
+        // Rate limit exceeded
+        return {
+            allowed: false,
+            remaining: 0,
+            resetTime: entry.resetTime,
+            limit: this.config.maxRequests
+        };
+    }
+    /**
+     * Check rate limit using distributed storage (S3/R2)
+     */
+    async checkDistributedLimit(identifier, now) {
+        const storage = this.config.storage;
+        const key = `ratelimit_${identifier}`;
+        const resetTime = now + this.config.windowMs;
+        try {
+            // Try to get existing rate limit data from metadata storage
+            const existing = await storage.getMetadata(key);
+            if (!existing || !existing.resetTime ||
+                Number(existing.resetTime) <= now) {
+                // New window or expired window
+                await storage.saveMetadata(key, {
+                    count: 1,
+                    resetTime: resetTime,
+                    identifier
+                });
+                return {
+                    allowed: true,
+                    remaining: this.config.maxRequests - 1,
+                    resetTime,
+                    limit: this.config.maxRequests
+                };
+            }
+            const count = Number(existing.count || 0);
+            if (count < this.config.maxRequests) {
+                // Update count
+                await storage.saveMetadata(key, {
+                    count: count + 1,
+                    resetTime: existing.resetTime,
+                    identifier
+                });
+                return {
+                    allowed: true,
+                    remaining: this.config.maxRequests - count - 1,
+                    resetTime: Number(existing.resetTime),
+                    limit: this.config.maxRequests
+                };
+            }
+            // Rate limit exceeded
+            return {
+                allowed: false,
+                remaining: 0,
+                resetTime: Number(existing.resetTime),
+                limit: this.config.maxRequests
+            };
+        }
+        catch (error) {
+            // On error, fail open (allow the request)
+            console.warn('Rate limiter error, failing open:', error);
+            return {
+                allowed: true,
+                remaining: this.config.maxRequests,
+                resetTime,
+                limit: this.config.maxRequests
+            };
+        }
+    }
+    /**
+     * Reset rate limit for a specific identifier
+     */
+    async reset(identifier) {
+        if (this.config.distributed && this.config.storage) {
+            const key = `ratelimit_${identifier}`;
+            // Reset by setting count to 0 and expired time
+            await this.config.storage.saveMetadata(key, {
+                count: 0,
+                resetTime: 0,
+                identifier
+            });
+        }
+        else {
+            this.requests.delete(identifier);
+        }
+    }
+    /**
+     * Start cleanup interval to remove expired entries
+     */
+    startCleanup() {
+        // Run cleanup every minute
+        this.cleanupInterval = setInterval(() => {
+            const now = Date.now();
+            const expired = [];
+            for (const [key, entry] of this.requests) {
+                if (entry.resetTime <= now) {
+                    expired.push(key);
+                }
+            }
+            for (const key of expired) {
+                this.requests.delete(key);
+            }
+        }, 60000); // 1 minute
+        // Don't keep Node.js process alive just for cleanup
+        if (this.cleanupInterval.unref) {
+            this.cleanupInterval.unref();
+        }
+    }
+    /**
+     * Stop the rate limiter and cleanup
+     */
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        this.requests.clear();
+    }
+}
+/**
+ * Express/Connect middleware for rate limiting
+ */
+export function rateLimitMiddleware(config) {
+    const limiter = new RateLimiter(config);
+    return async (req, res, next) => {
+        // Use IP address as identifier (can be customized)
+        const identifier = req.ip || req.connection?.remoteAddress || 'unknown';
+        const result = await limiter.checkLimit(identifier);
+        // Set rate limit headers
+        res.setHeader('X-RateLimit-Limit', result.limit);
+        res.setHeader('X-RateLimit-Remaining', result.remaining);
+        res.setHeader('X-RateLimit-Reset', result.resetTime);
+        if (!result.allowed) {
+            res.status(429).json({
+                error: config.message || 'Too many requests, please try again later.',
+                retryAfter: Math.ceil((result.resetTime - Date.now()) / 1000)
+            });
+            return;
+        }
+        next();
+    };
+}
+/**
+ * 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 function createRateLimiter(config) {
+    return new RateLimiter(config);
+}
+/**
+ * Preset configurations for common use cases
+ */
+export const RateLimitPresets = {
+    /**
+     * Default API rate limit: 100 requests per 15 minutes
+     */
+    default: {
+        maxRequests: 100,
+        windowMs: 15 * 60 * 1000
+    },
+    /**
+     * Strict rate limit: 10 requests per minute
+     */
+    strict: {
+        maxRequests: 10,
+        windowMs: 60 * 1000
+    },
+    /**
+     * Lenient rate limit: 1000 requests per hour
+     */
+    lenient: {
+        maxRequests: 1000,
+        windowMs: 60 * 60 * 1000
+    },
+    /**
+     * Search endpoint: 30 requests per minute
+     */
+    search: {
+        maxRequests: 30,
+        windowMs: 60 * 1000,
+        message: 'Search rate limit exceeded. Please wait before searching again.'
+    },
+    /**
+     * Write operations: 20 requests per minute
+     */
+    write: {
+        maxRequests: 20,
+        windowMs: 60 * 1000,
+        message: 'Write rate limit exceeded. Please slow down your write operations.'
+    }
+};
+//# sourceMappingURL=rateLimiter.js.map

package/dist/utils/statistics.d.ts

@@ -1,17 +1,17 @@
 /**
  * Utility functions for retrieving statistics from Brainy
  */
-import { BrainyData } from '../brainyData.js';
+import { Brainy } from '../brainy.js';
 /**
- * Get statistics about the current state of a BrainyData instance
+ * Get statistics about the current state of a Brainy instance
  * This function provides access to statistics at the root level of the library
  *
- * @param instance A BrainyData instance to get statistics from
+ * @param instance A Brainy instance to get statistics from
  * @param options Additional options for retrieving statistics
  * @returns Object containing counts of nouns, verbs, metadata entries, and HNSW index size
  * @throws Error if the instance is not provided or if statistics retrieval fails
  */
-export declare function getStatistics(instance: BrainyData, options?: {
+export declare function getStatistics(instance: Brainy, options?: {
     service?: string | string[];
 }): Promise<{
     nounCount: number;

package/dist/utils/statistics.js

@@ -2,17 +2,17 @@
  * Utility functions for retrieving statistics from Brainy
  */
 /**
- * Get statistics about the current state of a BrainyData instance
+ * Get statistics about the current state of a Brainy instance
  * This function provides access to statistics at the root level of the library
  *
- * @param instance A BrainyData instance to get statistics from
+ * @param instance A Brainy instance to get statistics from
  * @param options Additional options for retrieving statistics
  * @returns Object containing counts of nouns, verbs, metadata entries, and HNSW index size
  * @throws Error if the instance is not provided or if statistics retrieval fails
  */
 export async function getStatistics(instance, options = {}) {
     if (!instance) {
-        throw new Error('BrainyData instance must be provided to getStatistics');
+        throw new Error('Brainy instance must be provided to getStatistics');
     }
     try {
         return await instance.getStatistics(options);