@bsb/observable-winston 9.0.0

package/README.md

@@ -0,0 +1,62 @@
+# @bsb/observable-winston
+
+Winston observable plugin for BSB - integrate with the popular Winston logging framework.
+
+## Installation
+
+```bash
+npm install @bsb/observable-winston
+```
+
+## Features
+
+- **Winston integration** - Full Winston ecosystem support
+- **Multiple transports** - Console, file, daily-rotate-file
+- **Flexible formatting** - JSON, pretty-print, or simple text
+- **Child loggers** - Per-plugin Winston loggers
+- **Error serialization** - Proper error stack trace handling
+
+## Configuration
+
+```yaml
+plugins:
+  observables:
+    - plugin: "@bsb/observable-winston"
+      enabled: true
+      config:
+        level: "info"
+        transports:
+          console:
+            enabled: true
+            colorize: true
+          file:
+            enabled: false
+            filename: "./logs/application.log"
+            maxsize: 10485760
+            maxFiles: 5
+            tailable: true
+          dailyRotate:
+            enabled: true
+            dirname: "./logs"
+            filename: "application-%DATE%.log"
+            datePattern: "YYYY-MM-DD"
+            maxSize: "20m"
+            maxFiles: "14d"
+            zippedArchive: true
+        format:
+          timestamp: true
+          json: true
+          prettyPrint: false
+```
+
+### Configuration Options
+
+- **level**: Minimum log level ("error", "warn", "info", "debug")
+- **transports.console**: Console output settings
+- **transports.file**: Standard file output
+- **transports.dailyRotate**: Daily rotating files with retention
+- **format**: Timestamp, JSON, and pretty-print options
+
+## License
+
+Dual-licensed under AGPL-3.0-only OR Commercial License.

package/lib/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license for this program.
+ * The commercial license allows you to use the Program in a closed-source manner,
+ * including the right to create derivative works that are not subject to the terms
+ * of the AGPL.
+ *
+ * To obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+export { WinstonConfigSchema, type WinstonConfig, Config, Plugin, } from "./plugins/observable-winston";

package/lib/index.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license for this program.
+ * The commercial license allows you to use the Program in a closed-source manner,
+ * including the right to create derivative works that are not subject to the terms
+ * of the AGPL.
+ *
+ * To obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Plugin = exports.Config = exports.WinstonConfigSchema = void 0;
+var observable_winston_1 = require("./plugins/observable-winston");
+Object.defineProperty(exports, "WinstonConfigSchema", { enumerable: true, get: function () { return observable_winston_1.WinstonConfigSchema; } });
+Object.defineProperty(exports, "Config", { enumerable: true, get: function () { return observable_winston_1.Config; } });
+Object.defineProperty(exports, "Plugin", { enumerable: true, get: function () { return observable_winston_1.Plugin; } });

package/lib/plugins/observable-winston/index.d.ts

@@ -0,0 +1,159 @@
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license for this program.
+ * The commercial license allows you to use the Program in a closed-source manner,
+ * including the right to create derivative works that are not subject to the terms
+ * of the AGPL.
+ *
+ * To obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import { BSBObservable, BSBObservableConstructor, BSBError } from "@bsb/base";
+import { DTrace, LogMeta } from "@bsb/base";
+import { z } from "zod";
+import "winston-daily-rotate-file";
+/**
+ * Configuration schema for Winston observable
+ */
+export declare const WinstonConfigSchema: z.ZodObject<{
+    level: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        warn: "warn";
+        info: "info";
+        debug: "debug";
+    }>>;
+    transports: z.ZodObject<{
+        console: z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            colorize: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>;
+        file: z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            filename: z.ZodDefault<z.ZodString>;
+            maxsize: z.ZodDefault<z.ZodNumber>;
+            maxFiles: z.ZodDefault<z.ZodNumber>;
+            tailable: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>;
+        dailyRotate: z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            dirname: z.ZodDefault<z.ZodString>;
+            filename: z.ZodDefault<z.ZodString>;
+            datePattern: z.ZodDefault<z.ZodString>;
+            maxSize: z.ZodDefault<z.ZodString>;
+            maxFiles: z.ZodDefault<z.ZodString>;
+            zippedArchive: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    format: z.ZodObject<{
+        timestamp: z.ZodDefault<z.ZodBoolean>;
+        json: z.ZodDefault<z.ZodBoolean>;
+        prettyPrint: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type WinstonConfig = z.infer<typeof WinstonConfigSchema>;
+export declare const Config: import("@bsb/base").BSBPluginConfigClass<z.ZodObject<{
+    level: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        warn: "warn";
+        info: "info";
+        debug: "debug";
+    }>>;
+    transports: z.ZodObject<{
+        console: z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            colorize: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>;
+        file: z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            filename: z.ZodDefault<z.ZodString>;
+            maxsize: z.ZodDefault<z.ZodNumber>;
+            maxFiles: z.ZodDefault<z.ZodNumber>;
+            tailable: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>;
+        dailyRotate: z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            dirname: z.ZodDefault<z.ZodString>;
+            filename: z.ZodDefault<z.ZodString>;
+            datePattern: z.ZodDefault<z.ZodString>;
+            maxSize: z.ZodDefault<z.ZodString>;
+            maxFiles: z.ZodDefault<z.ZodString>;
+            zippedArchive: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    format: z.ZodObject<{
+        timestamp: z.ZodDefault<z.ZodBoolean>;
+        json: z.ZodDefault<z.ZodBoolean>;
+        prettyPrint: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>;
+}, z.core.$strip>>;
+/**
+ * Winston observable plugin - integrate with Winston logger
+ */
+export declare class Plugin extends BSBObservable<InstanceType<typeof Config>> {
+    static Config: import("@bsb/base").BSBPluginConfigClass<z.ZodObject<{
+        level: z.ZodDefault<z.ZodEnum<{
+            error: "error";
+            warn: "warn";
+            info: "info";
+            debug: "debug";
+        }>>;
+        transports: z.ZodObject<{
+            console: z.ZodObject<{
+                enabled: z.ZodDefault<z.ZodBoolean>;
+                colorize: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strip>;
+            file: z.ZodObject<{
+                enabled: z.ZodDefault<z.ZodBoolean>;
+                filename: z.ZodDefault<z.ZodString>;
+                maxsize: z.ZodDefault<z.ZodNumber>;
+                maxFiles: z.ZodDefault<z.ZodNumber>;
+                tailable: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strip>;
+            dailyRotate: z.ZodObject<{
+                enabled: z.ZodDefault<z.ZodBoolean>;
+                dirname: z.ZodDefault<z.ZodString>;
+                filename: z.ZodDefault<z.ZodString>;
+                datePattern: z.ZodDefault<z.ZodString>;
+                maxSize: z.ZodDefault<z.ZodString>;
+                maxFiles: z.ZodDefault<z.ZodString>;
+                zippedArchive: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+        format: z.ZodObject<{
+            timestamp: z.ZodDefault<z.ZodBoolean>;
+            json: z.ZodDefault<z.ZodBoolean>;
+            prettyPrint: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    private logFormatter;
+    private logger;
+    private isDisposed;
+    constructor(config: BSBObservableConstructor<InstanceType<typeof Config>>);
+    init(): Promise<void>;
+    run(): Promise<void>;
+    /**
+     * Send log to Winston
+     */
+    private sendLog;
+    debug(trace: DTrace, pluginName: string, message: string, meta: LogMeta<any>): void;
+    info(trace: DTrace, pluginName: string, message: string, meta: LogMeta<any>): void;
+    warn(trace: DTrace, pluginName: string, message: string, meta: LogMeta<any>): void;
+    error(trace: DTrace, pluginName: string, message: string | BSBError<any>, meta?: LogMeta<any>): void;
+    dispose(): void;
+}

package/lib/plugins/observable-winston/index.js

@@ -0,0 +1,252 @@
+"use strict";
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license for this program.
+ * The commercial license allows you to use the Program in a closed-source manner,
+ * including the right to create derivative works that are not subject to the terms
+ * of the AGPL.
+ *
+ * To obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Plugin = exports.Config = exports.WinstonConfigSchema = void 0;
+const base_1 = require("@bsb/base");
+const zod_1 = require("zod");
+const winston = __importStar(require("winston"));
+require("winston-daily-rotate-file");
+/**
+ * Configuration schema for Winston observable
+ */
+exports.WinstonConfigSchema = zod_1.z.object({
+    level: zod_1.z.enum(["error", "warn", "info", "debug"]).default("info"),
+    transports: zod_1.z.object({
+        console: zod_1.z.object({
+            enabled: zod_1.z.boolean().default(true),
+            colorize: zod_1.z.boolean().default(true),
+        }),
+        file: zod_1.z.object({
+            enabled: zod_1.z.boolean().default(false),
+            filename: zod_1.z.string().default("./logs/application.log"),
+            maxsize: zod_1.z.number().int().default(10485760), // 10MB
+            maxFiles: zod_1.z.number().int().default(5),
+            tailable: zod_1.z.boolean().default(true),
+        }),
+        dailyRotate: zod_1.z.object({
+            enabled: zod_1.z.boolean().default(false),
+            dirname: zod_1.z.string().default("./logs"),
+            filename: zod_1.z.string().default("application-%DATE%.log"),
+            datePattern: zod_1.z.string().default("YYYY-MM-DD"),
+            maxSize: zod_1.z.string().default("20m"),
+            maxFiles: zod_1.z.string().default("14d"),
+            zippedArchive: zod_1.z.boolean().default(true),
+        }),
+    }),
+    format: zod_1.z.object({
+        timestamp: zod_1.z.boolean().default(true),
+        json: zod_1.z.boolean().default(true),
+        prettyPrint: zod_1.z.boolean().default(false),
+    }),
+});
+exports.Config = (0, base_1.createConfigSchema)({
+    name: 'observable-winston',
+    description: 'Winston observable plugin with console, file, and rotation transports',
+    version: '9.0.0',
+    image: './observable-winston.png',
+    tags: ['winston', 'logging', 'observability', 'transports'],
+    documentation: ['./docs/plugin.md'],
+}, exports.WinstonConfigSchema);
+/**
+ * Convert BSB log level to Winston log level
+ */
+function bsbLevelToWinstonLevel(level) {
+    const normalized = level.toLowerCase();
+    switch (normalized) {
+        case "error":
+            return "error";
+        case "warn":
+        case "warning":
+            return "warn";
+        case "info":
+            return "info";
+        case "debug":
+            return "debug";
+        default:
+            return "info";
+    }
+}
+/**
+ * Winston observable plugin - integrate with Winston logger
+ */
+class Plugin extends base_1.BSBObservable {
+    static Config = exports.Config;
+    logFormatter = new base_1.LogFormatter();
+    logger;
+    isDisposed = false;
+    constructor(config) {
+        super(config);
+    }
+    async init() {
+        const transports = [];
+        // Console transport
+        if (this.config.transports.console.enabled) {
+            const consoleFormat = this.config.transports.console.colorize
+                ? winston.format.combine(winston.format.colorize(), winston.format.simple())
+                : winston.format.simple();
+            transports.push(new winston.transports.Console({
+                format: consoleFormat,
+            }));
+        }
+        // File transport
+        if (this.config.transports.file.enabled) {
+            transports.push(new winston.transports.File({
+                filename: this.config.transports.file.filename,
+                maxsize: this.config.transports.file.maxsize,
+                maxFiles: this.config.transports.file.maxFiles,
+                tailable: this.config.transports.file.tailable,
+            }));
+        }
+        // Daily rotate file transport
+        if (this.config.transports.dailyRotate.enabled) {
+            const DailyRotateFile = require("winston-daily-rotate-file");
+            transports.push(new DailyRotateFile({
+                dirname: this.config.transports.dailyRotate.dirname,
+                filename: this.config.transports.dailyRotate.filename,
+                datePattern: this.config.transports.dailyRotate.datePattern,
+                maxSize: this.config.transports.dailyRotate.maxSize,
+                maxFiles: this.config.transports.dailyRotate.maxFiles,
+                zippedArchive: this.config.transports.dailyRotate.zippedArchive,
+            }));
+        }
+        // Build format
+        const formats = [];
+        if (this.config.format.timestamp) {
+            formats.push(winston.format.timestamp());
+        }
+        if (this.config.format.json) {
+            formats.push(winston.format.json());
+        }
+        else if (this.config.format.prettyPrint) {
+            formats.push(winston.format.prettyPrint());
+        }
+        else {
+            formats.push(winston.format.simple());
+        }
+        // Create logger
+        this.logger = winston.createLogger({
+            level: this.config.level,
+            format: winston.format.combine(...formats),
+            transports,
+        });
+    }
+    async run() {
+        // No runtime setup needed
+    }
+    /**
+     * Send log to Winston
+     */
+    sendLog(level, trace, pluginName, message, meta) {
+        if (this.isDisposed) {
+            return;
+        }
+        try {
+            const formattedMessage = this.logFormatter.formatLog(trace, message, meta);
+            const winstonLevel = bsbLevelToWinstonLevel(level);
+            // Build metadata object
+            const metadata = {
+                plugin: pluginName,
+                trace_id: trace.t,
+                span_id: trace.s,
+                level,
+                ...meta,
+            };
+            // Log to Winston
+            this.logger.log(winstonLevel, formattedMessage, metadata);
+        }
+        catch (err) {
+            console.error(`[observable-winston] Send error: ${err.message}`);
+        }
+    }
+    // Logging methods
+    debug(trace, pluginName, message, meta) {
+        if (this.mode === "production") {
+            return;
+        }
+        this.sendLog("debug", trace, pluginName, message, meta);
+    }
+    info(trace, pluginName, message, meta) {
+        this.sendLog("info", trace, pluginName, message, meta);
+    }
+    warn(trace, pluginName, message, meta) {
+        this.sendLog("warn", trace, pluginName, message, meta);
+    }
+    error(trace, pluginName, message, meta) {
+        if (message instanceof base_1.BSBError) {
+            if (message.raw !== null) {
+                this.sendLog("error", message.raw.trace, pluginName, message.raw.message, message.raw.meta);
+            }
+            else {
+                this.sendLog("error", trace, pluginName, message.message);
+            }
+        }
+        else {
+            this.sendLog("error", trace, pluginName, message, meta);
+        }
+    }
+    dispose() {
+        this.isDisposed = true;
+        if (this.logger) {
+            this.logger.close();
+        }
+    }
+}
+exports.Plugin = Plugin;