@flink-app/flink 0.14.3 → 2.0.0-alpha.100

package/dist/src/FlinkLog.d.ts

@@ -1,24 +1,88 @@
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error";
+/**
+ * Simple logging utility with proper stdout/stderr separation
+ *
+ * Following Unix/POSIX best practices:
+ * - trace, debug, info → stdout (normal output)
+ * - warn, error → stderr (diagnostic output)
+ *
+ * Benefits:
+ * - Respects flink.config.js logging configuration
+ * - Container orchestration can capture streams separately
+ * - Shell redirection works correctly (command > out.log 2> err.log)
+ * - Log aggregation tools can route differently
+ * - Monitoring systems can alert on stderr only
+ *
+ * @example
+ * ```typescript
+ * import { log } from "@flink-app/flink";
+ *
+ * log.trace("Detailed trace info");
+ * log.debug("Debug information");
+ * log.info("General information");
+ * log.warn("Warning message");
+ * log.error("Error message");
+ * ```
+ *
+ * @example Configure via flink.config.js
+ * ```javascript
+ * module.exports = {
+ *   logging: {
+ *     components: {
+ *       "app": "debug"  // Enable debug for default log
+ *     }
+ *   }
+ * };
+ * ```
+ */
 export declare const log: {
+    /**
+     * Trace logs (stdout)
+     * Use for extremely detailed diagnostic information (most verbose level)
+     */
+    trace: (...args: any[]) => void;
+    /**
+     * Debug logs (stdout)
+     * Use for detailed diagnostic information during development
+     */
     debug: (...args: any[]) => void;
+    /**
+     * Info logs (stdout)
+     * Use for general informational messages about application state
+     */
     info: (...args: any[]) => void;
+    /**
+     * Warning logs (stderr)
+     * Use for potentially harmful situations that aren't errors
+     * Writes to stderr following Unix/POSIX best practices
+     */
     warn: (...args: any[]) => void;
+    /**
+     * Error logs (stderr)
+     * Use for error events that might still allow the app to continue
+     * Writes to stderr following Unix/POSIX best practices
+     */
     error: (...args: any[]) => void;
-    json: (...args: any) => void;
-    bgColorLog: (ticket: "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white", text: string, setting?: {
-        reverse?: boolean | undefined;
-        bold?: boolean | undefined;
-        italic?: boolean | undefined;
-        dim?: boolean | undefined;
-        underscore?: boolean | undefined;
-        strikethrough?: boolean | undefined;
-    }) => void;
-    fontColorLog: (ticket: "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white", text: string, setting?: {
-        reverse?: boolean | undefined;
-        bold?: boolean | undefined;
-        italic?: boolean | undefined;
-        dim?: boolean | undefined;
-        underscore?: boolean | undefined;
-        strikethrough?: boolean | undefined;
-    }) => void;
-    setLevel: (level: "debug" | "info" | "warn" | "error") => void;
+    /**
+     * JSON output (stdout)
+     * Use for structured data output
+     */
+    json: (...args: any[]) => void;
+    /**
+     * Colored background log (stdout)
+     * Use for highlighted messages during development
+     */
+    bgColorLog: (color: string, ...args: any[]) => void;
+    /**
+     * Colored font log (stdout)
+     * Use for colored messages during development
+     */
+    fontColorLog: (color: string, ...args: any[]) => void;
+    /**
+     * Set log level for the default "app" logger
+     *
+     * @deprecated Use flink.config.js or FlinkLogFactory.setComponentLevel("app", level) instead
+     */
+    setLevel: (level: LogLevel) => void;
 };
+export {};

package/dist/src/FlinkLog.js

@@ -1,26 +1,178 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.log = void 0;
-var node_color_log_1 = __importDefault(require("node-color-log"));
+var FlinkLogFactory_1 = require("./FlinkLogFactory");
+/**
+ * Lazy-loaded application logger using FlinkLogFactory
+ *
+ * This logger uses the component name "app" and respects all
+ * logging configuration from flink.config.js and environment variables.
+ *
+ * Configured via:
+ * - flink.config.js: components["app"] = "debug"
+ * - Environment: LOG_LEVEL=debug
+ * - Programmatic: FlinkLogFactory.setComponentLevel("app", "debug")
+ */
+var appLogger = null;
+/**
+ * Get or create the app logger (lazy initialization)
+ */
+function getAppLogger() {
+    if (!appLogger) {
+        appLogger = FlinkLogFactory_1.FlinkLogFactory.createLogger("app");
+    }
+    return appLogger;
+}
+/**
+ * Simple logging utility with proper stdout/stderr separation
+ *
+ * Following Unix/POSIX best practices:
+ * - trace, debug, info → stdout (normal output)
+ * - warn, error → stderr (diagnostic output)
+ *
+ * Benefits:
+ * - Respects flink.config.js logging configuration
+ * - Container orchestration can capture streams separately
+ * - Shell redirection works correctly (command > out.log 2> err.log)
+ * - Log aggregation tools can route differently
+ * - Monitoring systems can alert on stderr only
+ *
+ * @example
+ * ```typescript
+ * import { log } from "@flink-app/flink";
+ *
+ * log.trace("Detailed trace info");
+ * log.debug("Debug information");
+ * log.info("General information");
+ * log.warn("Warning message");
+ * log.error("Error message");
+ * ```
+ *
+ * @example Configure via flink.config.js
+ * ```javascript
+ * module.exports = {
+ *   logging: {
+ *     components: {
+ *       "app": "debug"  // Enable debug for default log
+ *     }
+ *   }
+ * };
+ * ```
+ */
 exports.log = {
-    debug: node_color_log_1.default.debug.bind(node_color_log_1.default),
-    info: node_color_log_1.default.info.bind(node_color_log_1.default),
-    warn: node_color_log_1.default.warn.bind(node_color_log_1.default),
-    error: node_color_log_1.default.error.bind(node_color_log_1.default),
+    /**
+     * Trace logs (stdout)
+     * Use for extremely detailed diagnostic information (most verbose level)
+     */
+    trace: function () {
+        var _a;
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        return (_a = getAppLogger()).trace.apply(_a, args);
+    },
+    /**
+     * Debug logs (stdout)
+     * Use for detailed diagnostic information during development
+     */
+    debug: function () {
+        var _a;
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        return (_a = getAppLogger()).debug.apply(_a, args);
+    },
+    /**
+     * Info logs (stdout)
+     * Use for general informational messages about application state
+     */
+    info: function () {
+        var _a;
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        return (_a = getAppLogger()).info.apply(_a, args);
+    },
+    /**
+     * Warning logs (stderr)
+     * Use for potentially harmful situations that aren't errors
+     * Writes to stderr following Unix/POSIX best practices
+     */
+    warn: function () {
+        var _a;
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        return (_a = getAppLogger()).warn.apply(_a, args);
+    },
+    /**
+     * Error logs (stderr)
+     * Use for error events that might still allow the app to continue
+     * Writes to stderr following Unix/POSIX best practices
+     */
+    error: function () {
+        var _a;
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        return (_a = getAppLogger()).error.apply(_a, args);
+    },
+    /**
+     * JSON output (stdout)
+     * Use for structured data output
+     */
     json: function () {
+        var _a;
         var args = [];
         for (var _i = 0; _i < arguments.length; _i++) {
             args[_i] = arguments[_i];
         }
-        for (var _a = 0, args_1 = args; _a < args_1.length; _a++) {
-            var o = args_1[_a];
-            console.log(JSON.stringify(o, null, 2));
+        return (_a = getAppLogger()).json.apply(_a, args);
+    },
+    /**
+     * Colored background log (stdout)
+     * Use for highlighted messages during development
+     */
+    bgColorLog: function (color) {
+        var _a;
+        var args = [];
+        for (var _i = 1; _i < arguments.length; _i++) {
+            args[_i - 1] = arguments[_i];
+        }
+        return (_a = getAppLogger()).bgColorLog.apply(_a, __spreadArray([color], args, false));
+    },
+    /**
+     * Colored font log (stdout)
+     * Use for colored messages during development
+     */
+    fontColorLog: function (color) {
+        var _a;
+        var args = [];
+        for (var _i = 1; _i < arguments.length; _i++) {
+            args[_i - 1] = arguments[_i];
         }
+        return (_a = getAppLogger()).fontColorLog.apply(_a, __spreadArray([color], args, false));
+    },
+    /**
+     * Set log level for the default "app" logger
+     *
+     * @deprecated Use flink.config.js or FlinkLogFactory.setComponentLevel("app", level) instead
+     */
+    setLevel: function (level) {
+        getAppLogger().setLevel(level);
     },
-    bgColorLog: node_color_log_1.default.bgColorLog.bind(node_color_log_1.default),
-    fontColorLog: node_color_log_1.default.fontColorLog.bind(node_color_log_1.default),
-    setLevel: function (level) { return node_color_log_1.default.setLevel.bind(node_color_log_1.default)(level); },
 };

package/dist/src/FlinkLogFactory.d.ts

@@ -0,0 +1,288 @@
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error";
+/**
+ * Component-specific logger with independent log level control
+ */
+export declare class ComponentLogger {
+    private componentName;
+    private componentLevel;
+    private namedLogger;
+    constructor(componentName: string);
+    /**
+     * Set log level for this specific component.
+     * Overrides the global log level.
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Clear component-specific level and fall back to global level
+     */
+    clearLevel(): void;
+    /**
+     * Check if a message should be logged based on component and global levels
+     */
+    private shouldLog;
+    trace(...args: any[]): void;
+    debug(...args: any[]): void;
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+    json(...args: any[]): void;
+    bgColorLog(color: string, ...args: any[]): void;
+    fontColorLog(color: string, ...args: any[]): void;
+}
+/**
+ * Configuration for logging system
+ */
+export interface LoggingConfig {
+    /**
+     * Global log level (default: "info")
+     */
+    global?: LogLevel;
+    /**
+     * Show timestamps in log messages (default: true)
+     */
+    showTimestamps?: boolean;
+    /**
+     * Component-specific log levels with wildcard support
+     *
+     * Supports:
+     * - Exact match: "flink.ai.openai" → matches only "flink.ai.openai"
+     * - Prefix match: "flink.ai." → matches "flink.ai.openai", "flink.ai.anthropic", etc.
+     * - Single-level wildcard: "flink.ai.*" → matches "flink.ai.openai" but NOT "flink.ai.openai.v4"
+     * - Multi-level wildcard: "flink.ai.**" → matches any depth under "flink.ai"
+     *
+     * @example
+     * {
+     *   "flink.ai.openai": "trace",     // exact match
+     *   "flink.ai.*": "debug",          // single-level wildcard
+     *   "flink.database.**": "warn",    // multi-level wildcard
+     *   "flink.handlers.": "info"       // prefix match (trailing dot)
+     * }
+     */
+    components?: Record<string, LogLevel>;
+    /**
+     * @internal
+     * Internal use only - hierarchical configurations parsed from components map
+     */
+    hierarchical?: Array<{
+        prefix: string;
+        level: LogLevel;
+        specificity: number;
+    }>;
+    /**
+     * @internal
+     * Internal use only - wildcard configurations parsed from components map
+     */
+    wildcards?: Array<{
+        pattern: string;
+        level: LogLevel;
+        specificity: number;
+    }>;
+}
+/**
+ * Factory for creating component-specific loggers with hierarchical level control
+ */
+export declare class FlinkLogFactory {
+    private static globalLevel;
+    private static loggers;
+    private static initialized;
+    private static showTimestamps;
+    /**
+     * Store component configurations from environment/config for lazy application
+     */
+    private static componentConfigs;
+    /**
+     * Hierarchical prefix configurations (Java-style)
+     * Sorted by specificity (most specific first) for efficient matching
+     */
+    private static hierarchicalConfigs;
+    /**
+     * Wildcard pattern configurations (optional, advanced)
+     * Sorted by specificity (most specific first) for efficient matching
+     */
+    private static wildcardConfigs;
+    /**
+     * Set the global log level (affects all loggers without component-specific levels)
+     */
+    static setGlobalLevel(level: LogLevel): void;
+    /**
+     * Get the current global log level
+     */
+    static getGlobalLevel(): LogLevel;
+    /**
+     * Get all registered loggers (useful for debugging)
+     */
+    static getLoggers(): Map<string, ComponentLogger>;
+    /**
+     * Enable or disable timestamps in log messages
+     */
+    static setShowTimestamps(show: boolean): void;
+    /**
+     * Check if timestamps are enabled
+     */
+    static getShowTimestamps(): boolean;
+    /**
+     * Clear all component-specific log levels (fall back to global)
+     */
+    static resetComponentLevels(): void;
+    /**
+     * Clear all hierarchical prefix configurations
+     */
+    static resetHierarchicalLevels(): void;
+    /**
+     * Clear all wildcard pattern configurations
+     */
+    static resetWildcardLevels(): void;
+    /**
+     * Set log level for a specific component by name (exact match)
+     */
+    static setComponentLevel(componentName: string, level: LogLevel | null): void;
+    /**
+     * Set hierarchical prefix-based log level (Java-style)
+     * @param prefix Logger name prefix (e.g., "flink.ai" matches all "flink.ai.*")
+     * @param level Log level to apply
+     *
+     * @example
+     * FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+     * // Now all loggers starting with "flink.ai." will use debug level
+     * // This includes the exact match "flink.ai" AND all children "flink.ai.*"
+     */
+    static setHierarchicalLevel(prefix: string, level: LogLevel): void;
+    /**
+     * Set wildcard pattern-based log level (advanced)
+     * @param pattern Wildcard pattern (e.g., "flink.ai.*" or "flink.ai.**")
+     * @param level Log level to apply
+     *
+     * @example
+     * FlinkLogFactory.setWildcardLevel("flink.ai.*", "debug");
+     * // Matches flink.ai.openai but NOT flink.ai.openai.v4
+     *
+     * FlinkLogFactory.setWildcardLevel("flink.ai.**", "trace");
+     * // Matches any depth under flink.ai.
+     */
+    static setWildcardLevel(pattern: string, level: LogLevel): void;
+    /**
+     * Get the effective log level for a component (resolved through hierarchy)
+     * @param componentName Component name to check
+     * @returns Resolved log level or null if only global level applies
+     */
+    static getEffectiveLevel(componentName: string): LogLevel | null;
+    /**
+     * Initialize logging from environment variables and/or configuration file
+     *
+     * Priority (highest to lowest):
+     * 1. Config file (flink.config.js)
+     * 2. Environment variable (LOG_LEVEL=debug)
+     *
+     * @param fileConfig Optional logging configuration from flink.config.js
+     *
+     * @example Environment Variable
+     * ```bash
+     * LOG_LEVEL=debug pnpm run dev
+     * ```
+     *
+     * @example Config File (flink.config.js)
+     * ```javascript
+     * module.exports = {
+     *   logging: {
+     *     global: "info",
+     *     showTimestamps: true,
+     *     components: {
+     *       "flink.ai.openai": "trace",          // exact match
+     *       "flink.ai.*": "debug",               // single-level wildcard
+     *       "flink.database.**": "warn",         // multi-level wildcard
+     *       "flink.handlers.": "info"            // prefix match
+     *     }
+     *   }
+     * };
+     * ```
+     */
+    static configure(fileConfig?: LoggingConfig): void;
+    /**
+     * Parse logging configuration from environment variables
+     * Supports only LOG_LEVEL for global level setting
+     */
+    private static parseEnvironment;
+    /**
+     * Normalize logger name to lowercase (Java-style convention)
+     * @param name Logger name or pattern
+     * @returns Normalized lowercase name
+     */
+    private static normalize;
+    /**
+     * Determine if a name should be treated as a hierarchical prefix
+     * @param name Normalized logger name
+     * @returns True if it should be treated as a prefix
+     */
+    private static shouldTreatAsPrefix;
+    /**
+     * Calculate specificity for prefix matching
+     * More specific prefixes (more segments) have higher specificity
+     * @param prefix Prefix string (may or may not end with dot)
+     * @returns Specificity score (number of segments)
+     */
+    private static calculatePrefixSpecificity;
+    /**
+     * Calculate specificity for wildcard patterns
+     * More specific patterns (more non-wildcard segments) have higher specificity
+     * For same segment count, * (single-level) is more specific than ** (multi-level)
+     * @param pattern Wildcard pattern
+     * @returns Specificity score (base + decimal for wildcard type)
+     */
+    private static calculateWildcardSpecificity;
+    /**
+     * Resolve component log level through hierarchical matching
+     * Order of precedence (highest to lowest):
+     * 1. Exact match
+     * 2. Most specific prefix match
+     * 3. Less specific prefix match
+     * 4. Wildcard pattern match
+     * 5. null (falls back to global level)
+     *
+     * @param componentName Component name to resolve
+     * @returns Resolved log level or null
+     */
+    private static resolveComponentLevel;
+    /**
+     * Simple wildcard matching for logger patterns
+     * Supports:
+     * - * matches single segment (flink.ai.* matches flink.ai.openai)
+     * - ** matches any depth (flink.ai.** matches flink.ai.openai.v4)
+     * - Partial segment match (flink.ai.open* matches flink.ai.openai)
+     *
+     * @param name Logger name to match
+     * @param pattern Wildcard pattern
+     * @returns True if pattern matches
+     */
+    private static matchWildcard;
+    /**
+     * Parse components map and classify entries into exact, prefix, or wildcard matches
+     * @param components Components map from config
+     * @returns Classified configuration
+     */
+    private static parseComponentsMap;
+    /**
+     * Check if a string is a valid log level
+     */
+    private static isValidLogLevel;
+    /**
+     * Create or retrieve a component-specific logger
+     * Automatically applies environment/config settings when logger is created
+     * Supports hierarchical prefix matching (Java-style)
+     *
+     * @param componentName Logger name (lowercase dot notation recommended, e.g., "flink.ai.openai")
+     * @returns ComponentLogger instance
+     *
+     * @example
+     * ```typescript
+     * // Java-style hierarchical naming (recommended)
+     * const log = FlinkLogFactory.createLogger("flink.ai.openai");
+     * const dbLog = FlinkLogFactory.createLogger("flink.database.mongodb");
+     *
+     * // Case insensitive - these create the same logger
+     * const log1 = FlinkLogFactory.createLogger("flink.ai.openai");
+     * const log2 = FlinkLogFactory.createLogger("Flink.AI.OpenAI");  // Same instance
+     * ```
+     */
+    static createLogger(componentName: string): ComponentLogger;
+}
+export {};