@soulcraft/brainy 2.15.0 → 3.0.1

package/dist/utils/structuredLogger.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Enhanced Structured Logging System for Brainy
+ * Provides production-ready logging with structured output, context preservation,
+ * performance tracking, and multiple transport support
+ */
+export declare enum LogLevel {
+    SILENT = -1,
+    FATAL = 0,
+    ERROR = 1,
+    WARN = 2,
+    INFO = 3,
+    DEBUG = 4,
+    TRACE = 5
+}
+export interface LogContext {
+    requestId?: string;
+    userId?: string;
+    operation?: string;
+    entityId?: string;
+    entityType?: string;
+    [key: string]: any;
+}
+export interface LogEntry {
+    timestamp: string;
+    level: string;
+    levelNumeric: number;
+    module: string;
+    message: string;
+    context?: LogContext;
+    data?: any;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+        code?: string;
+    };
+    performance?: {
+        duration?: number;
+        memory?: {
+            used: number;
+            total: number;
+        };
+    };
+    host?: string;
+    pid: number;
+    version?: string;
+}
+export interface LogTransport {
+    name: string;
+    log(entry: LogEntry): void | Promise<void>;
+    flush?(): Promise<void>;
+}
+export interface StructuredLoggerConfig {
+    level: LogLevel;
+    modules?: Record<string, LogLevel>;
+    format: 'json' | 'pretty' | 'simple';
+    transports: LogTransport[];
+    context?: LogContext;
+    includeHost?: boolean;
+    includeMemory?: boolean;
+    bufferSize?: number;
+    flushInterval?: number;
+    version?: string;
+}
+export declare class StructuredLogger {
+    private static instance;
+    private config;
+    private defaultContext;
+    private performanceMarks;
+    private constructor();
+    private loadEnvironmentConfig;
+    static getInstance(): StructuredLogger;
+    configure(config: Partial<StructuredLoggerConfig>): void;
+    setContext(context: LogContext): void;
+    clearContext(): void;
+    withContext(context: LogContext): StructuredLogger;
+    startTimer(label: string): void;
+    endTimer(label: string): number | undefined;
+    private shouldLog;
+    private createLogEntry;
+    private log;
+    fatal(module: string, message: string, contextOrData?: LogContext | any, data?: any): void;
+    error(module: string, message: string, contextOrData?: LogContext | any, data?: any): void;
+    warn(module: string, message: string, contextOrData?: LogContext | any, data?: any): void;
+    info(module: string, message: string, contextOrData?: LogContext | any, data?: any): void;
+    debug(module: string, message: string, contextOrData?: LogContext | any, data?: any): void;
+    trace(module: string, message: string, contextOrData?: LogContext | any, data?: any): void;
+    createModuleLogger(module: string): {
+        fatal: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+        error: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+        warn: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+        info: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+        debug: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+        trace: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+        withContext: (context: LogContext) => {
+            fatal: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+            error: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+            warn: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+            info: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+            debug: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+            trace: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+            withContext: (context: LogContext) => /*elided*/ any;
+            startTimer: (label: string) => void;
+            endTimer: (label: string) => number | undefined;
+        };
+        startTimer: (label: string) => void;
+        endTimer: (label: string) => number | undefined;
+    };
+    flush(): Promise<void>;
+    addTransport(transport: LogTransport): void;
+    removeTransport(name: string): void;
+    child(context: LogContext): StructuredLogger;
+}
+export declare const structuredLogger: StructuredLogger;
+export declare function createModuleLogger(module: string): {
+    fatal: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+    error: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+    warn: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+    info: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+    debug: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+    trace: (message: string, contextOrData?: LogContext | any, data?: any) => void;
+    withContext: (context: LogContext) => /*elided*/ any;
+    startTimer: (label: string) => void;
+    endTimer: (label: string) => number | undefined;
+};
+export declare function setLogContext(context: LogContext): void;
+export declare function withLogContext(context: LogContext): StructuredLogger;
+export declare function createCorrelationId(): string;
+export declare function logPerformance(logger: ReturnType<typeof createModuleLogger>, operation: string, fn: () => any): any;
+export declare class LoggerCompatibilityWrapper {
+    private moduleLogger;
+    constructor(module?: string);
+    error(module: string, message: string, ...args: any[]): void;
+    warn(module: string, message: string, ...args: any[]): void;
+    info(module: string, message: string, ...args: any[]): void;
+    debug(module: string, message: string, ...args: any[]): void;
+    trace(module: string, message: string, ...args: any[]): void;
+    createModuleLogger(module: string): {
+        error: (message: string, ...args: any[]) => void;
+        warn: (message: string, ...args: any[]) => void;
+        info: (message: string, ...args: any[]) => void;
+        debug: (message: string, ...args: any[]) => void;
+        trace: (message: string, ...args: any[]) => void;
+    };
+}
+export type ModuleLogger = ReturnType<typeof createModuleLogger>;

package/dist/utils/structuredLogger.js

@@ -0,0 +1,394 @@
+/**
+ * Enhanced Structured Logging System for Brainy
+ * Provides production-ready logging with structured output, context preservation,
+ * performance tracking, and multiple transport support
+ */
+import { performance } from 'perf_hooks';
+import { hostname } from 'os';
+import { randomUUID } from 'crypto';
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["SILENT"] = -1] = "SILENT";
+    LogLevel[LogLevel["FATAL"] = 0] = "FATAL";
+    LogLevel[LogLevel["ERROR"] = 1] = "ERROR";
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    LogLevel[LogLevel["INFO"] = 3] = "INFO";
+    LogLevel[LogLevel["DEBUG"] = 4] = "DEBUG";
+    LogLevel[LogLevel["TRACE"] = 5] = "TRACE";
+})(LogLevel || (LogLevel = {}));
+class ConsoleTransport {
+    constructor(format = 'json') {
+        this.name = 'console';
+        this.format = format;
+    }
+    log(entry) {
+        const method = this.getConsoleMethod(entry.levelNumeric);
+        if (this.format === 'json') {
+            method(JSON.stringify(entry));
+        }
+        else if (this.format === 'pretty') {
+            const color = this.getColor(entry.levelNumeric);
+            const prefix = `${entry.timestamp} ${color}[${entry.level}]\\x1b[0m [${entry.module}]`;
+            const message = entry.message;
+            if (entry.error) {
+                method(`${prefix} ${message}`, entry.error);
+            }
+            else if (entry.data) {
+                method(`${prefix} ${message}`, entry.data);
+            }
+            else {
+                method(`${prefix} ${message}`);
+            }
+        }
+        else {
+            // Simple format
+            method(`[${entry.level}] ${entry.message}`);
+        }
+    }
+    getConsoleMethod(level) {
+        switch (level) {
+            case LogLevel.FATAL:
+            case LogLevel.ERROR:
+                return console.error;
+            case LogLevel.WARN:
+                return console.warn;
+            case LogLevel.INFO:
+                return console.info;
+            default:
+                return console.log;
+        }
+    }
+    getColor(level) {
+        switch (level) {
+            case LogLevel.FATAL:
+                return '\\x1b[35m'; // Magenta
+            case LogLevel.ERROR:
+                return '\\x1b[31m'; // Red
+            case LogLevel.WARN:
+                return '\\x1b[33m'; // Yellow
+            case LogLevel.INFO:
+                return '\\x1b[36m'; // Cyan
+            case LogLevel.DEBUG:
+                return '\\x1b[32m'; // Green
+            case LogLevel.TRACE:
+                return '\\x1b[90m'; // Gray
+            default:
+                return '\\x1b[0m'; // Reset
+        }
+    }
+}
+class BufferedTransport {
+    constructor(innerTransport, bufferSize = 100, flushInterval = 5000) {
+        this.name = 'buffered';
+        this.buffer = [];
+        this.innerTransport = innerTransport;
+        this.bufferSize = bufferSize;
+        if (flushInterval > 0) {
+            this.flushTimer = setInterval(() => this.flush(), flushInterval);
+        }
+    }
+    log(entry) {
+        this.buffer.push(entry);
+        if (this.buffer.length >= this.bufferSize) {
+            this.flush();
+        }
+    }
+    async flush() {
+        const entries = this.buffer.splice(0);
+        for (const entry of entries) {
+            await this.innerTransport.log(entry);
+        }
+        if (this.innerTransport.flush) {
+            await this.innerTransport.flush();
+        }
+    }
+    destroy() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+        }
+        this.flush();
+    }
+}
+export class StructuredLogger {
+    constructor() {
+        this.defaultContext = {};
+        this.performanceMarks = new Map();
+        const isDevelopment = process.env.NODE_ENV !== 'production';
+        const format = isDevelopment ? 'pretty' : 'json';
+        this.config = {
+            level: isDevelopment ? LogLevel.DEBUG : LogLevel.INFO,
+            format,
+            transports: [new ConsoleTransport(format)],
+            includeHost: !isDevelopment,
+            includeMemory: false,
+            bufferSize: 100,
+            flushInterval: 5000,
+            version: process.env.npm_package_version
+        };
+        // Load from environment
+        this.loadEnvironmentConfig();
+    }
+    loadEnvironmentConfig() {
+        const envLevel = process.env.BRAINY_LOG_LEVEL;
+        if (envLevel) {
+            const level = LogLevel[envLevel.toUpperCase()];
+            if (level !== undefined) {
+                this.config.level = level;
+            }
+        }
+        const envFormat = process.env.BRAINY_LOG_FORMAT;
+        if (envFormat && ['json', 'pretty', 'simple'].includes(envFormat)) {
+            this.config.format = envFormat;
+        }
+        const moduleConfig = process.env.BRAINY_MODULE_LOG_LEVELS;
+        if (moduleConfig) {
+            try {
+                this.config.modules = JSON.parse(moduleConfig);
+            }
+            catch {
+                // Ignore parse errors
+            }
+        }
+    }
+    static getInstance() {
+        if (!StructuredLogger.instance) {
+            StructuredLogger.instance = new StructuredLogger();
+        }
+        return StructuredLogger.instance;
+    }
+    configure(config) {
+        this.config = { ...this.config, ...config };
+    }
+    setContext(context) {
+        this.defaultContext = { ...this.defaultContext, ...context };
+    }
+    clearContext() {
+        this.defaultContext = {};
+    }
+    withContext(context) {
+        const contextualLogger = Object.create(this);
+        contextualLogger.defaultContext = { ...this.defaultContext, ...context };
+        return contextualLogger;
+    }
+    startTimer(label) {
+        this.performanceMarks.set(label, performance.now());
+    }
+    endTimer(label) {
+        const start = this.performanceMarks.get(label);
+        if (start === undefined)
+            return undefined;
+        const duration = performance.now() - start;
+        this.performanceMarks.delete(label);
+        return duration;
+    }
+    shouldLog(level, module) {
+        if (this.config.modules?.[module] !== undefined) {
+            return level <= this.config.modules[module];
+        }
+        return level <= this.config.level;
+    }
+    createLogEntry(level, module, message, context, data, error) {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level: LogLevel[level],
+            levelNumeric: level,
+            module,
+            message,
+            pid: process.pid,
+            version: this.config.version
+        };
+        // Merge contexts
+        const mergedContext = { ...this.defaultContext, ...context };
+        if (Object.keys(mergedContext).length > 0) {
+            entry.context = mergedContext;
+        }
+        if (data !== undefined) {
+            entry.data = data;
+        }
+        if (error) {
+            entry.error = {
+                name: error.name,
+                message: error.message,
+                stack: error.stack,
+                code: error.code
+            };
+        }
+        if (this.config.includeHost) {
+            entry.host = hostname();
+        }
+        if (this.config.includeMemory) {
+            const mem = process.memoryUsage();
+            entry.performance = {
+                memory: {
+                    used: Math.round(mem.heapUsed / 1024 / 1024),
+                    total: Math.round(mem.heapTotal / 1024 / 1024)
+                }
+            };
+        }
+        return entry;
+    }
+    log(level, module, message, contextOrData, data) {
+        if (!this.shouldLog(level, module)) {
+            return;
+        }
+        // Handle overloaded parameters
+        let context;
+        let logData;
+        if (contextOrData && typeof contextOrData === 'object' && !Array.isArray(contextOrData)) {
+            // Check if it looks like a context object
+            const hasContextKeys = ['requestId', 'userId', 'operation', 'entityId', 'entityType']
+                .some(key => key in contextOrData);
+            if (hasContextKeys) {
+                context = contextOrData;
+                logData = data;
+            }
+            else {
+                logData = contextOrData;
+            }
+        }
+        else {
+            logData = contextOrData;
+        }
+        // Extract error if present
+        let error;
+        if (logData instanceof Error) {
+            error = logData;
+            logData = undefined;
+        }
+        else if (logData?.error instanceof Error) {
+            error = logData.error;
+            delete logData.error;
+        }
+        const entry = this.createLogEntry(level, module, message, context, logData, error);
+        // Send to all transports
+        for (const transport of this.config.transports) {
+            try {
+                transport.log(entry);
+            }
+            catch (err) {
+                // Fallback to console.error if transport fails
+                console.error('Logger transport error:', err);
+            }
+        }
+    }
+    fatal(module, message, contextOrData, data) {
+        this.log(LogLevel.FATAL, module, message, contextOrData, data);
+    }
+    error(module, message, contextOrData, data) {
+        this.log(LogLevel.ERROR, module, message, contextOrData, data);
+    }
+    warn(module, message, contextOrData, data) {
+        this.log(LogLevel.WARN, module, message, contextOrData, data);
+    }
+    info(module, message, contextOrData, data) {
+        this.log(LogLevel.INFO, module, message, contextOrData, data);
+    }
+    debug(module, message, contextOrData, data) {
+        this.log(LogLevel.DEBUG, module, message, contextOrData, data);
+    }
+    trace(module, message, contextOrData, data) {
+        this.log(LogLevel.TRACE, module, message, contextOrData, data);
+    }
+    createModuleLogger(module) {
+        const self = this;
+        return {
+            fatal: (message, contextOrData, data) => self.fatal(module, message, contextOrData, data),
+            error: (message, contextOrData, data) => self.error(module, message, contextOrData, data),
+            warn: (message, contextOrData, data) => self.warn(module, message, contextOrData, data),
+            info: (message, contextOrData, data) => self.info(module, message, contextOrData, data),
+            debug: (message, contextOrData, data) => self.debug(module, message, contextOrData, data),
+            trace: (message, contextOrData, data) => self.trace(module, message, contextOrData, data),
+            withContext: (context) => {
+                const contextual = self.withContext(context);
+                return contextual.createModuleLogger(module);
+            },
+            startTimer: (label) => self.startTimer(`${module}:${label}`),
+            endTimer: (label) => self.endTimer(`${module}:${label}`)
+        };
+    }
+    async flush() {
+        const flushPromises = this.config.transports
+            .filter(t => t.flush)
+            .map(t => t.flush());
+        await Promise.all(flushPromises);
+    }
+    addTransport(transport) {
+        this.config.transports.push(transport);
+    }
+    removeTransport(name) {
+        this.config.transports = this.config.transports.filter(t => t.name !== name);
+    }
+    child(context) {
+        return this.withContext(context);
+    }
+}
+// Singleton instance
+export const structuredLogger = StructuredLogger.getInstance();
+// Convenience functions
+export function createModuleLogger(module) {
+    return structuredLogger.createModuleLogger(module);
+}
+export function setLogContext(context) {
+    structuredLogger.setContext(context);
+}
+export function withLogContext(context) {
+    return structuredLogger.withContext(context);
+}
+// Correlation ID middleware helper
+export function createCorrelationId() {
+    return randomUUID();
+}
+// Performance logging helper
+export function logPerformance(logger, operation, fn) {
+    logger.startTimer(operation);
+    try {
+        const result = fn();
+        if (result && typeof result.then === 'function') {
+            return result.finally(() => {
+                const duration = logger.endTimer(operation);
+                logger.debug(`${operation} completed`, { duration });
+            });
+        }
+        const duration = logger.endTimer(operation);
+        logger.debug(`${operation} completed`, { duration });
+        return result;
+    }
+    catch (error) {
+        const duration = logger.endTimer(operation);
+        logger.error(`${operation} failed`, { duration, error });
+        throw error;
+    }
+}
+// Backward compatibility wrapper for existing logger
+export class LoggerCompatibilityWrapper {
+    constructor(module = 'legacy') {
+        this.moduleLogger = createModuleLogger(module);
+    }
+    error(module, message, ...args) {
+        this.moduleLogger.error(message, { module, data: args });
+    }
+    warn(module, message, ...args) {
+        this.moduleLogger.warn(message, { module, data: args });
+    }
+    info(module, message, ...args) {
+        this.moduleLogger.info(message, { module, data: args });
+    }
+    debug(module, message, ...args) {
+        this.moduleLogger.debug(message, { module, data: args });
+    }
+    trace(module, message, ...args) {
+        this.moduleLogger.trace(message, { module, data: args });
+    }
+    createModuleLogger(module) {
+        const logger = createModuleLogger(module);
+        return {
+            error: (message, ...args) => logger.error(message, { data: args }),
+            warn: (message, ...args) => logger.warn(message, { data: args }),
+            info: (message, ...args) => logger.info(message, { data: args }),
+            debug: (message, ...args) => logger.debug(message, { data: args }),
+            trace: (message, ...args) => logger.trace(message, { data: args })
+        };
+    }
+}
+// Types are already exported above, no need to re-export
+//# sourceMappingURL=structuredLogger.js.map

package/dist/utils/textEncoding.js

@@ -26,7 +26,8 @@ export async function applyTensorFlowPatch() {
                 return globalThis;
             if (typeof global !== 'undefined')
                 return global;
-            return {};
+            throw new Error('Cannot apply TextEncoder/TextDecoder patches: No global object found. ' +
+                'This environment does not have globalThis or global defined.');
         })();
         // Make sure TextEncoder and TextDecoder are available globally
         if (!globalObj.TextEncoder) {

package/dist/utils/typeValidation.d.ts

@@ -23,3 +23,37 @@ export interface ValidationStats {
 }
 export declare function getValidationStats(): ValidationStats;
 export declare function resetValidationStats(): void;
+export declare class ValidationError extends Error {
+    readonly parameter: string;
+    readonly value: any;
+    readonly constraint: string;
+    constructor(parameter: string, value: any, constraint: string);
+}
+/**
+ * Validate required ID parameter
+ * Standard validation for all ID-based operations
+ */
+export declare function validateId(id: unknown, paramName?: string): string;
+/**
+ * Validate search query input
+ * Handles string queries, vectors, and objects for search operations
+ */
+export declare function validateSearchQuery(query: unknown, paramName?: string): any;
+/**
+ * Validate data input for addNoun/updateNoun operations
+ * Handles vectors, objects, strings, and validates structure
+ */
+export declare function validateDataInput(data: unknown, paramName?: string, allowNull?: boolean): any;
+/**
+ * Validate search options
+ * Comprehensive validation for search API options
+ */
+export declare function validateSearchOptions(options: unknown, paramName?: string): any;
+/**
+ * Validate ID arrays (for bulk operations)
+ */
+export declare function validateIdArray(ids: unknown, paramName?: string): string[];
+/**
+ * Track validation stats for monitoring
+ */
+export declare function recordValidation(success: boolean): void;