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

package/dist/src/utils.d.ts

@@ -12,6 +12,31 @@ export declare function getHandlerFiles(appRoot: string): Promise<string[]>;
 export declare function getSchemaFiles(appRoot: string): Promise<string[]>;
 export declare function getCollectionNameForRepo(repoFilename: string): string;
 export declare function getRepoInstanceName(fn: string): string;
+/**
+ * Convert PascalCase or camelCase to kebab-case
+ *
+ * Examples:
+ * - FooBarBaz → foo-bar-baz
+ * - CarAgent → car-agent
+ * - APIAgent → api-agent
+ * - HTMLParser → html-parser
+ * - IOManager → io-manager
+ *
+ * Handles:
+ * - Single uppercase followed by lowercase: CarAgent → car-agent
+ * - Multiple consecutive uppercase: APIAgent → api-agent
+ * - All caps: HTML → html
+ */
+export declare function toKebabCase(str: string): string;
+/**
+ * Convert kebab-case to snake_case
+ *
+ * Examples:
+ * - car-agent → car_agent
+ * - api-agent → api_agent
+ * - html-parser → html_parser
+ */
+export declare function toSnakeCase(str: string): string;
 /**
  * Get http method from props or convention based on file name
  * if it starts with i.e "GetFoo"
@@ -37,3 +62,8 @@ export declare function getDataAtPath(data: any, instancePath: string): any;
  * @param maxDataLength Maximum length of data to show (default 500)
  */
 export declare function formatValidationErrors(errors: any[] | null | undefined, data: any, maxDataLength?: number): string;
+/**
+ * Generate a short random ID for nested conversations
+ * Format: 8 character alphanumeric string (e.g., "a3b7c9d2")
+ */
+export declare function generateShortId(): string;

package/dist/src/utils.js

@@ -47,11 +47,14 @@ exports.getHandlerFiles = getHandlerFiles;
 exports.getSchemaFiles = getSchemaFiles;
 exports.getCollectionNameForRepo = getCollectionNameForRepo;
 exports.getRepoInstanceName = getRepoInstanceName;
+exports.toKebabCase = toKebabCase;
+exports.toSnakeCase = toSnakeCase;
 exports.getHttpMethodFromHandlerName = getHttpMethodFromHandlerName;
 exports.getJsDocComment = getJsDocComment;
 exports.getPathParams = getPathParams;
 exports.getDataAtPath = getDataAtPath;
 exports.formatValidationErrors = formatValidationErrors;
+exports.generateShortId = generateShortId;
 var path_1 = require("path");
 var tiny_glob_1 = __importDefault(require("tiny-glob"));
 var FlinkHttpHandler_1 = require("./FlinkHttpHandler");
@@ -122,6 +125,43 @@ function getRepoInstanceName(fn) {
     var name = fn.split(".ts")[0];
     return name.charAt(0).toLowerCase() + name.substr(1);
 }
+/**
+ * Convert PascalCase or camelCase to kebab-case
+ *
+ * Examples:
+ * - FooBarBaz → foo-bar-baz
+ * - CarAgent → car-agent
+ * - APIAgent → api-agent
+ * - HTMLParser → html-parser
+ * - IOManager → io-manager
+ *
+ * Handles:
+ * - Single uppercase followed by lowercase: CarAgent → car-agent
+ * - Multiple consecutive uppercase: APIAgent → api-agent
+ * - All caps: HTML → html
+ */
+function toKebabCase(str) {
+    return str
+        // Insert hyphen before uppercase letters that follow lowercase letters
+        // CarAgent → Car-Agent
+        .replace(/([a-z])([A-Z])/g, "$1-$2")
+        // Insert hyphen before uppercase letter that follows uppercase and precedes lowercase
+        // APIAgent → API-Agent
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
+        // Convert to lowercase
+        .toLowerCase();
+}
+/**
+ * Convert kebab-case to snake_case
+ *
+ * Examples:
+ * - car-agent → car_agent
+ * - api-agent → api_agent
+ * - html-parser → html_parser
+ */
+function toSnakeCase(str) {
+    return str.replace(/-/g, "_");
+}
 /**
  * Get http method from props or convention based on file name
  * if it starts with i.e "GetFoo"
@@ -236,3 +276,15 @@ function formatValidationErrors(errors, data, maxDataLength) {
     });
     return formatted.join("\n");
 }
+/**
+ * Generate a short random ID for nested conversations
+ * Format: 8 character alphanumeric string (e.g., "a3b7c9d2")
+ */
+function generateShortId() {
+    var chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+    var result = "";
+    for (var i = 0; i < 8; i++) {
+        result += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return result;
+}

package/dist/src/workers/SchemaGeneratorWorker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/workers/SchemaGeneratorWorker.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var worker_threads_1 = require("worker_threads");
+var ts_json_schema_generator_1 = require("ts-json-schema-generator");
+if (!worker_threads_1.parentPort) {
+    throw new Error("This script must be run as a worker thread");
+}
+worker_threads_1.parentPort.on("message", function (input) {
+    try {
+        // Configure schema generator - match the config from TypeScriptCompiler
+        var config = {
+            path: input.schemaFilePath,
+            expose: "export",
+            topRef: false,
+            additionalProperties: false,
+            jsDoc: "basic",
+            sortProps: false,
+            strictTuples: false,
+            minify: false,
+            markdownDescription: false,
+            skipTypeCheck: true,
+            encodeRefs: false,
+            extraTags: [],
+            functions: "fail",
+            discriminatorType: "json-schema",
+            tsconfig: input.tsconfigPath,
+        };
+        // Create TypeScript program and schema generator
+        var program = (0, ts_json_schema_generator_1.createProgram)(config);
+        var parser = (0, ts_json_schema_generator_1.createParser)(program, config);
+        var formatter = (0, ts_json_schema_generator_1.createFormatter)(config);
+        var generator = new ts_json_schema_generator_1.SchemaGenerator(program, parser, formatter, config);
+        // Generate schema for the type
+        var schema = generator.createSchema(input.typeName);
+        // Send result back to main thread
+        worker_threads_1.parentPort.postMessage({
+            typeName: input.typeName,
+            schema: schema,
+        });
+    }
+    catch (error) {
+        // Send error back to main thread
+        worker_threads_1.parentPort.postMessage({
+            typeName: input.typeName,
+            schema: {},
+            error: error.message || String(error),
+        });
+    }
+});

package/dist/src/workers/WorkerPool.d.ts

@@ -0,0 +1,60 @@
+export declare class WorkerPool<TInput, TOutput> {
+    private workerScriptPath;
+    private taskTimeout;
+    private workers;
+    private availableWorkers;
+    private taskQueue;
+    private workerTasks;
+    private poolSize;
+    private initialized;
+    constructor(workerScriptPath: string, poolSize?: number, taskTimeout?: number);
+    /**
+     * Calculate optimal pool size based on CPU count and memory
+     */
+    private calculateOptimalPoolSize;
+    /**
+     * Initialize the worker pool
+     */
+    initialize(): Promise<void>;
+    /**
+     * Execute a task using an available worker
+     */
+    execute(input: TInput): Promise<TOutput>;
+    /**
+     * Assign a task to an available worker
+     */
+    private assignTaskToWorker;
+    /**
+     * Handle message received from worker
+     */
+    private handleWorkerMessage;
+    /**
+     * Handle worker error
+     */
+    private handleWorkerError;
+    /**
+     * Handle worker exit
+     */
+    private handleWorkerExit;
+    /**
+     * Handle task timeout
+     */
+    private handleTaskTimeout;
+    /**
+     * Process next task from queue
+     */
+    private processNextTask;
+    /**
+     * Terminate all workers and clean up
+     */
+    terminate(): Promise<void>;
+    /**
+     * Get pool statistics
+     */
+    getStats(): {
+        poolSize: number;
+        availableWorkers: number;
+        activeTasks: number;
+        queuedTasks: number;
+    };
+}

package/dist/src/workers/WorkerPool.js

@@ -0,0 +1,306 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerPool = void 0;
+var worker_threads_1 = require("worker_threads");
+var os_1 = __importDefault(require("os"));
+var WorkerPool = /** @class */ (function () {
+    function WorkerPool(workerScriptPath, poolSize, taskTimeout) {
+        if (taskTimeout === void 0) { taskTimeout = 30000; }
+        this.workerScriptPath = workerScriptPath;
+        this.taskTimeout = taskTimeout;
+        this.workers = [];
+        this.availableWorkers = [];
+        this.taskQueue = [];
+        this.workerTasks = new Map();
+        this.initialized = false;
+        this.poolSize = poolSize || this.calculateOptimalPoolSize();
+    }
+    /**
+     * Calculate optimal pool size based on CPU count and memory
+     */
+    WorkerPool.prototype.calculateOptimalPoolSize = function () {
+        var cpuCount = os_1.default.cpus().length;
+        var availableMemoryGB = os_1.default.totalmem() / (Math.pow(1024, 3));
+        // Memory constraint: 20MB per worker, use max 30% of RAM
+        var maxByMemory = Math.floor((availableMemoryGB * 0.3) / 0.02);
+        // CPU constraint: Leave 2 cores for main thread + OS
+        var maxByCPU = Math.max(1, cpuCount - 2);
+        // Cap at 8 for diminishing returns
+        return Math.min(8, maxByMemory, maxByCPU);
+    };
+    /**
+     * Initialize the worker pool
+     */
+    WorkerPool.prototype.initialize = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var _loop_1, this_1, i;
+            var _this = this;
+            return __generator(this, function (_a) {
+                if (this.initialized) {
+                    return [2 /*return*/];
+                }
+                _loop_1 = function (i) {
+                    var worker = new worker_threads_1.Worker(this_1.workerScriptPath);
+                    this_1.workers.push(worker);
+                    this_1.availableWorkers.push(worker);
+                    worker.on("message", function (message) {
+                        _this.handleWorkerMessage(worker, message);
+                    });
+                    worker.on("error", function (error) {
+                        _this.handleWorkerError(worker, error);
+                    });
+                    worker.on("exit", function (code) {
+                        _this.handleWorkerExit(worker, code);
+                    });
+                };
+                this_1 = this;
+                for (i = 0; i < this.poolSize; i++) {
+                    _loop_1(i);
+                }
+                this.initialized = true;
+                return [2 /*return*/];
+            });
+        });
+    };
+    /**
+     * Execute a task using an available worker
+     */
+    WorkerPool.prototype.execute = function (input) {
+        return __awaiter(this, void 0, void 0, function () {
+            var _this = this;
+            return __generator(this, function (_a) {
+                if (!this.initialized) {
+                    throw new Error("Worker pool not initialized. Call initialize() first.");
+                }
+                return [2 /*return*/, new Promise(function (resolve, reject) {
+                        var task = { input: input, resolve: resolve, reject: reject };
+                        if (_this.availableWorkers.length > 0) {
+                            _this.assignTaskToWorker(task);
+                        }
+                        else {
+                            _this.taskQueue.push(task);
+                        }
+                    })];
+            });
+        });
+    };
+    /**
+     * Assign a task to an available worker
+     */
+    WorkerPool.prototype.assignTaskToWorker = function (task) {
+        var _this = this;
+        var worker = this.availableWorkers.shift();
+        if (!worker) {
+            this.taskQueue.push(task);
+            return;
+        }
+        this.workerTasks.set(worker, task);
+        // Set timeout for task
+        task.timeout = setTimeout(function () {
+            _this.handleTaskTimeout(worker);
+        }, this.taskTimeout);
+        worker.postMessage(task.input);
+    };
+    /**
+     * Handle message received from worker
+     */
+    WorkerPool.prototype.handleWorkerMessage = function (worker, message) {
+        var task = this.workerTasks.get(worker);
+        if (!task) {
+            return;
+        }
+        // Clear timeout
+        if (task.timeout) {
+            clearTimeout(task.timeout);
+        }
+        // Remove task from active tasks
+        this.workerTasks.delete(worker);
+        // Resolve the task
+        task.resolve(message);
+        // Make worker available again
+        this.availableWorkers.push(worker);
+        // Process next task in queue
+        this.processNextTask();
+    };
+    /**
+     * Handle worker error
+     */
+    WorkerPool.prototype.handleWorkerError = function (worker, error) {
+        var task = this.workerTasks.get(worker);
+        if (task) {
+            // Clear timeout
+            if (task.timeout) {
+                clearTimeout(task.timeout);
+            }
+            // Remove task and reject
+            this.workerTasks.delete(worker);
+            task.reject(error);
+            // Make worker available again (it might still be usable)
+            this.availableWorkers.push(worker);
+            // Process next task
+            this.processNextTask();
+        }
+    };
+    /**
+     * Handle worker exit
+     */
+    WorkerPool.prototype.handleWorkerExit = function (worker, code) {
+        var task = this.workerTasks.get(worker);
+        if (task) {
+            // Clear timeout
+            if (task.timeout) {
+                clearTimeout(task.timeout);
+            }
+            // Remove task and reject
+            this.workerTasks.delete(worker);
+            task.reject(new Error("Worker exited with code ".concat(code)));
+        }
+        // Remove worker from all lists
+        var workerIndex = this.workers.indexOf(worker);
+        if (workerIndex !== -1) {
+            this.workers.splice(workerIndex, 1);
+        }
+        var availableIndex = this.availableWorkers.indexOf(worker);
+        if (availableIndex !== -1) {
+            this.availableWorkers.splice(availableIndex, 1);
+        }
+    };
+    /**
+     * Handle task timeout
+     */
+    WorkerPool.prototype.handleTaskTimeout = function (worker) {
+        var _this = this;
+        var task = this.workerTasks.get(worker);
+        if (!task) {
+            return;
+        }
+        // Remove task and reject
+        this.workerTasks.delete(worker);
+        task.reject(new Error("Task timeout exceeded"));
+        // Terminate the worker and create a new one
+        worker.terminate();
+        // Remove from available workers
+        var availableIndex = this.availableWorkers.indexOf(worker);
+        if (availableIndex !== -1) {
+            this.availableWorkers.splice(availableIndex, 1);
+        }
+        // Create a new worker to replace it
+        var newWorker = new worker_threads_1.Worker(this.workerScriptPath);
+        this.workers.push(newWorker);
+        this.availableWorkers.push(newWorker);
+        newWorker.on("message", function (message) {
+            _this.handleWorkerMessage(newWorker, message);
+        });
+        newWorker.on("error", function (error) {
+            _this.handleWorkerError(newWorker, error);
+        });
+        newWorker.on("exit", function (code) {
+            _this.handleWorkerExit(newWorker, code);
+        });
+        // Process next task
+        this.processNextTask();
+    };
+    /**
+     * Process next task from queue
+     */
+    WorkerPool.prototype.processNextTask = function () {
+        if (this.taskQueue.length > 0 && this.availableWorkers.length > 0) {
+            var task = this.taskQueue.shift();
+            if (task) {
+                this.assignTaskToWorker(task);
+            }
+        }
+    };
+    /**
+     * Terminate all workers and clean up
+     */
+    WorkerPool.prototype.terminate = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var tasks, _i, tasks_1, task, _a, tasks_2, task, _b, _c, task;
+            return __generator(this, function (_d) {
+                switch (_d.label) {
+                    case 0:
+                        tasks = Array.from(this.workerTasks.values());
+                        for (_i = 0, tasks_1 = tasks; _i < tasks_1.length; _i++) {
+                            task = tasks_1[_i];
+                            if (task.timeout) {
+                                clearTimeout(task.timeout);
+                            }
+                        }
+                        // Reject all pending tasks
+                        for (_a = 0, tasks_2 = tasks; _a < tasks_2.length; _a++) {
+                            task = tasks_2[_a];
+                            task.reject(new Error("Worker pool terminated"));
+                        }
+                        for (_b = 0, _c = this.taskQueue; _b < _c.length; _b++) {
+                            task = _c[_b];
+                            task.reject(new Error("Worker pool terminated"));
+                        }
+                        // Terminate all workers
+                        return [4 /*yield*/, Promise.all(this.workers.map(function (worker) { return worker.terminate(); }))];
+                    case 1:
+                        // Terminate all workers
+                        _d.sent();
+                        this.workers = [];
+                        this.availableWorkers = [];
+                        this.taskQueue = [];
+                        this.workerTasks.clear();
+                        this.initialized = false;
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Get pool statistics
+     */
+    WorkerPool.prototype.getStats = function () {
+        return {
+            poolSize: this.poolSize,
+            availableWorkers: this.availableWorkers.length,
+            activeTasks: this.workerTasks.size,
+            queuedTasks: this.taskQueue.length,
+        };
+    };
+    return WorkerPool;
+}());
+exports.WorkerPool = WorkerPool;

package/examples/logging-hierarchical-example.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env tsx
+/**
+ * Example: Java-Style Hierarchical Logging in Flink
+ *
+ * This example demonstrates the hierarchical prefix matching feature
+ * inspired by Java logging frameworks (Log4j, Logback).
+ *
+ * Run with:
+ *   npx tsx packages/flink/examples/logging-hierarchical-example.ts
+ *
+ * Or with environment variables:
+ *   LOG_LEVELS=flink.ai:debug npx tsx packages/flink/examples/logging-hierarchical-example.ts
+ */
+
+import { FlinkLogFactory } from "../src";
+
+console.log("=== Java-Style Hierarchical Logging Example ===\n");
+
+// Configure hierarchical logging (Java-style)
+console.log("📋 Configuration:");
+console.log("  - Global level: warn");
+console.log("  - flink.ai.* → debug (hierarchical prefix)");
+console.log("  - flink.ai.openai → trace (exact match - more specific)\n");
+
+FlinkLogFactory.setGlobalLevel("warn");
+FlinkLogFactory.setHierarchicalLevel("flink.ai", "debug");
+FlinkLogFactory.setComponentLevel("flink.ai.openai", "trace");
+
+// Create loggers (lowercase recommended)
+const openaiLog = FlinkLogFactory.createLogger("flink.ai.openai");
+const anthropicLog = FlinkLogFactory.createLogger("flink.ai.anthropic");
+const claudeLog = FlinkLogFactory.createLogger("flink.ai.claude.v4");
+const dbLog = FlinkLogFactory.createLogger("flink.database.mongodb");
+const cacheLog = FlinkLogFactory.createLogger("flink.cache.redis");
+
+// Test case insensitivity
+const openaiLog2 = FlinkLogFactory.createLogger("Flink.AI.OpenAI");
+console.log("✅ Case insensitivity check:");
+console.log(`   flink.ai.openai === Flink.AI.OpenAI: ${openaiLog === openaiLog2}\n`);
+
+// Display effective levels
+console.log("📊 Effective Log Levels:");
+console.log(`   flink.ai.openai: ${FlinkLogFactory.getEffectiveLevel("flink.ai.openai")} (exact match)`);
+console.log(
+    `   flink.ai.anthropic: ${FlinkLogFactory.getEffectiveLevel("flink.ai.anthropic")} (prefix: flink.ai.)`
+);
+console.log(
+    `   flink.ai.claude.v4: ${FlinkLogFactory.getEffectiveLevel("flink.ai.claude.v4")} (prefix: flink.ai.)`
+);
+console.log(
+    `   flink.database.mongodb: ${
+        FlinkLogFactory.getEffectiveLevel("flink.database.mongodb") || "warn (global)"
+    }`
+);
+console.log(
+    `   flink.cache.redis: ${FlinkLogFactory.getEffectiveLevel("flink.cache.redis") || "warn (global)"}\n`
+);
+
+// Test logging at different levels
+console.log("🔍 Testing Log Output:\n");
+
+console.log("--- flink.ai.openai (level: trace) ---");
+openaiLog.trace("This is a TRACE message (visible)");
+openaiLog.debug("This is a DEBUG message (visible)");
+openaiLog.info("This is an INFO message (visible)");
+openaiLog.warn("This is a WARN message (visible)");
+
+console.log("\n--- flink.ai.anthropic (level: debug via prefix) ---");
+anthropicLog.debug("This is a DEBUG message (visible)");
+anthropicLog.info("This is an INFO message (visible)");
+console.log("[TRACE message would be hidden]\n");
+
+console.log("--- flink.ai.claude.v4 (level: debug via prefix) ---");
+claudeLog.debug("Multi-level prefix matching works!");
+claudeLog.info("Claude v4 logger inherits from flink.ai prefix");
+
+console.log("\n--- flink.database.mongodb (level: warn via global) ---");
+dbLog.warn("This is a WARN message (visible)");
+console.log("[INFO and DEBUG messages would be hidden]\n");
+
+console.log("--- flink.cache.redis (level: warn via global) ---");
+cacheLog.warn("This is a WARN message (visible)");
+console.log("[INFO and DEBUG messages would be hidden]\n");
+
+// Demonstrate wildcard patterns
+console.log("\n=== Wildcard Pattern Example ===\n");
+FlinkLogFactory.setWildcardLevel("flink.database.*", "debug");
+
+const mongoLog = FlinkLogFactory.createLogger("flink.database.mongodb");
+const redisLog = FlinkLogFactory.createLogger("flink.database.redis");
+
+console.log("📋 Configuration:");
+console.log("  - flink.database.* → debug (single-level wildcard)\n");
+
+console.log("📊 Effective Levels:");
+console.log(
+    `   flink.database.mongodb: ${FlinkLogFactory.getEffectiveLevel("flink.database.mongodb")} (wildcard: flink.database.*)`
+);
+console.log(
+    `   flink.database.redis: ${FlinkLogFactory.getEffectiveLevel("flink.database.redis")} (wildcard: flink.database.*)\n`
+);
+
+console.log("--- flink.database.mongodb (level: debug via wildcard) ---");
+mongoLog.debug("MongoDB debug message (now visible)");
+
+console.log("\n--- flink.database.redis (level: debug via wildcard) ---");
+redisLog.debug("Redis debug message (now visible)");
+
+// Demonstrate runtime level changes
+console.log("\n\n=== Runtime Level Changes ===\n");
+console.log("Changing flink.ai.openai from trace → info");
+FlinkLogFactory.setComponentLevel("flink.ai.openai", "info");
+
+console.log("\n--- flink.ai.openai (level: info after change) ---");
+openaiLog.info("This INFO message is visible");
+console.log("[DEBUG and TRACE messages would now be hidden]\n");
+
+// Reset to original
+console.log("Resetting flink.ai.openai back to trace");
+FlinkLogFactory.setComponentLevel("flink.ai.openai", "trace");
+
+console.log("\n✅ Example complete! Try running with different LOG_LEVELS:");
+console.log("   LOG_LEVELS=flink.ai:trace npm run example");
+console.log("   LOG_LEVELS=flink.ai:debug,flink.database:info npm run example");
+console.log("   LOG_LEVELS=flink.ai.*:debug,flink.database.**:warn npm run example");