@sockethub/logger 1.0.0-alpha.12 → 1.0.0-alpha.13

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+import winston from "winston";
+export type Logger = winston.Logger;
+export interface LoggerOptions {
+    level?: string;
+    fileLevel?: string;
+    file?: string;
+}
+/**
+ * Initialize the logger system with global configuration.
+ *
+ * Called once at server bootstrap with config settings. All subsequent
+ * createLogger() calls will use these settings as defaults unless explicitly
+ * overridden.
+ *
+ * @param options - Global logger configuration
+ *
+ * @example
+ * ```typescript
+ * // In server bootstrap
+ * initLogger({
+ *   level: config.get("logging:level"),
+ *   fileLevel: config.get("logging:fileLevel"),
+ *   file: config.get("logging:file"),
+ * });
+ * ```
+ */
+export declare function initLogger(options: LoggerOptions): void;
+/**
+ * Set the logger context for this process.
+ *
+ * All subsequent createLogger() calls will prepend this context to their namespace.
+ * This is typically set once at process startup to identify the process (e.g., "sockethub"
+ * for the main server, or "sockethub:platform:irc:abc123" for a platform child process).
+ *
+ * @param context - The context string to prepend to all logger namespaces in this process
+ *
+ * @example
+ * ```typescript
+ * // In main server process
+ * setLoggerContext('sockethub');
+ * const log = createLogger('server:listener');
+ * // Output namespace: "sockethub:server:listener"
+ *
+ * // In platform child process
+ * setLoggerContext('sockethub:platform:irc:abc123');
+ * const log = createLogger('main');
+ * // Output namespace: "sockethub:platform:irc:abc123:main"
+ * ```
+ */
+export declare function setLoggerContext(context: string): void;
+/**
+ * Get the current logger context for this process.
+ *
+ * @returns The current logger context string, or empty string if not set
+ *
+ * @example
+ * ```typescript
+ * const context = getLoggerContext();
+ * if (context.includes(':platform:')) {
+ *   // We're in a platform child process
+ * }
+ * ```
+ */
+export declare function getLoggerContext(): string;
+/**
+ * Reset the logger context.
+ *
+ * Primarily used for testing to reset state between test cases.
+ *
+ * @example
+ * ```typescript
+ * afterEach(() => {
+ *   resetLoggerContext();
+ * });
+ * ```
+ */
+export declare function resetLoggerContext(): void;
+/**
+ * Creates a Winston logger instance with console and optional file transports.
+ *
+ * Configuration priority (highest to lowest):
+ * 1. Explicit options parameter
+ * 2. Global config (set via initLogger)
+ * 3. Environment variables (LOG_LEVEL, LOG_FILE_LEVEL, LOG_FILE)
+ * 4. Defaults (info for console, debug for file)
+ *
+ * Log levels: error, warn, info, debug
+ *
+ * NODE_ENV=production disables console timestamps (for systemd)
+ *
+ * @param namespace - Logger namespace (e.g., "sockethub:data-layer:queue:...")
+ * @param options - Optional logger configuration overrides
+ * @returns Winston logger instance
+ *
+ * @example
+ * ```typescript
+ * // Uses global config if initLogger() was called
+ * const log = createLogger("sockethub:data-layer:queue:irc-123");
+ *
+ * // Override for specific use case (e.g., early bootstrap logging)
+ * const earlyLog = createLogger("sockethub:bootstrap", { level: "info" });
+ * ```
+ */
+export declare function createLogger(namespace: string, options?: LoggerOptions): Logger;
+/**
+ * Get the namespace from a logger instance.
+ *
+ * Extracts the full namespace (including context) that was set when the logger was created.
+ * Useful for reusing the namespace in other systems like Redis connection names.
+ *
+ * @param logger - Logger instance created by createLogger()
+ * @returns The full namespace string, or empty string if not found
+ *
+ * @example
+ * ```typescript
+ * const log = createLogger('data-layer:queue');
+ * const namespace = getLoggerNamespace(log);
+ * // Returns: "sockethub:data-layer:queue" (if context is "sockethub")
+ *
+ * // Use for Redis connection name
+ * redisConfig.connectionName = namespace;
+ * ```
+ */
+export declare function getLoggerNamespace(logger: Logger): string;
+/**
+ * Reset logger state. Used primarily for testing.
+ * @internal
+ */
+export declare function resetLoggerForTesting(): void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sockethub/logger",
   "description": "Winston-based logger for Sockethub packages",
-  "version": "1.0.0-alpha.12",
+  "version": "1.0.0-alpha.13",
   "type": "module",
   "private": false,
   "author": "Nick Jennings <nick@silverbucket.net>",
@@ -12,17 +12,16 @@
   "main": "dist/index.js",
   "exports": {
     ".": {
-      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     }
   },
   "files": [
-    "src/",
     "dist/"
   ],
   "engines": {
-    "bun": ">=1.2"
+    "node": ">=20"
   },
   "keywords": [
     "sockethub",
@@ -47,5 +46,6 @@
   "devDependencies": {
     "@types/bun": "latest"
   },
-  "gitHead": "f039dab3c3f67cbbf204476fc397532e973f82a8"
+  "gitHead": "864733e5b34449ef39542eceb4ff11aa308081bc",
+  "types": "./dist/index.d.ts"
 }

package/src/index.test.ts

@@ -1,324 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
-import {
-    type Logger,
-    type LoggerOptions,
-    createLogger,
-    getLoggerContext,
-    getLoggerNamespace,
-    initLogger,
-    resetLoggerContext,
-    resetLoggerForTesting,
-    setLoggerContext,
-} from "./index.js";
-
-describe("Logger Package", () => {
-    beforeEach(() => {
-        resetLoggerForTesting();
-        delete process.env.LOG_LEVEL;
-        delete process.env.LOG_FILE_LEVEL;
-        delete process.env.LOG_FILE;
-    });
-
-    afterEach(() => {
-        resetLoggerForTesting();
-    });
-
-    describe("createLogger", () => {
-        it("creates a logger with namespace", () => {
-            const log = createLogger("test:namespace");
-            expect(log).toBeDefined();
-            expect(log.info).toBeFunction();
-            expect(log.warn).toBeFunction();
-            expect(log.error).toBeFunction();
-            expect(log.debug).toBeFunction();
-        });
-
-        it("uses default level info when no config provided", () => {
-            const log = createLogger("test:namespace");
-            expect(log).toBeDefined();
-            // Winston loggers have transports array
-            expect(log.transports).toBeArray();
-            expect(log.transports.length).toBeGreaterThan(0);
-        });
-
-        it("respects explicit options over defaults", () => {
-            const log = createLogger("test:namespace", { level: "error" });
-            expect(log).toBeDefined();
-            const consoleTransport = log.transports[0];
-            expect(consoleTransport.level).toBe("error");
-        });
-
-        it("respects environment variables when no global config", () => {
-            process.env.LOG_LEVEL = "warn";
-            const log = createLogger("test:namespace");
-            const consoleTransport = log.transports[0];
-            expect(consoleTransport.level).toBe("warn");
-        });
-
-        it("creates file transport when file path provided", () => {
-            const log = createLogger("test:namespace", {
-                file: "/tmp/test.log",
-            });
-            expect(log.transports.length).toBe(2); // console + file
-        });
-
-        it("does not create file transport when file is empty string", () => {
-            const log = createLogger("test:namespace", { file: "" });
-            expect(log.transports.length).toBe(1); // console only
-        });
-    });
-
-    describe("getLoggerNamespace", () => {
-        it("returns namespace from logger instance", () => {
-            const log = createLogger("test:namespace");
-            const namespace = getLoggerNamespace(log);
-            expect(namespace).toBe("test:namespace");
-        });
-
-        it("returns namespace with context when set", () => {
-            setLoggerContext("myapp");
-            const log = createLogger("test:namespace");
-            const namespace = getLoggerNamespace(log);
-            expect(namespace).toBe("myapp:test:namespace");
-        });
-
-        it("returns empty string for logger without namespace", () => {
-            const log = createLogger("");
-            const namespace = getLoggerNamespace(log);
-            expect(namespace).toBe("");
-        });
-    });
-
-    describe("initLogger", () => {
-        it("sets global config for subsequent createLogger calls", () => {
-            initLogger({
-                level: "debug",
-                fileLevel: "info",
-                file: "/tmp/global.log",
-            });
-
-            const log = createLogger("test:namespace");
-            expect(log.transports.length).toBe(2); // console + file
-            const consoleTransport = log.transports[0];
-            expect(consoleTransport.level).toBe("debug");
-        });
-
-        it("allows explicit options to override global config", () => {
-            initLogger({ level: "info" });
-
-            const log = createLogger("test:namespace", { level: "error" });
-            const consoleTransport = log.transports[0];
-            expect(consoleTransport.level).toBe("error");
-        });
-
-        it("global config takes precedence over ENV vars", () => {
-            process.env.LOG_LEVEL = "warn";
-            initLogger({ level: "debug" });
-
-            const log = createLogger("test:namespace");
-            const consoleTransport = log.transports[0];
-            expect(consoleTransport.level).toBe("debug");
-        });
-    });
-
-    describe("configuration priority", () => {
-        it("follows priority: explicit > global > env > default", () => {
-            // Set up all sources
-            process.env.LOG_LEVEL = "warn";
-            initLogger({ level: "info" });
-
-            // Explicit wins
-            const log1 = createLogger("test:1", { level: "error" });
-            expect(log1.transports[0].level).toBe("error");
-
-            // Global wins over env
-            const log2 = createLogger("test:2");
-            expect(log2.transports[0].level).toBe("info");
-        });
-
-        it("falls back to env when no global config", () => {
-            process.env.LOG_LEVEL = "warn";
-            const log = createLogger("test:namespace");
-            expect(log.transports[0].level).toBe("warn");
-        });
-
-        it("falls back to default when no config at all", () => {
-            const log = createLogger("test:namespace");
-            expect(log.transports[0].level).toBe("info");
-        });
-    });
-
-    describe("edge cases", () => {
-        it("handles createLogger before initLogger", () => {
-            // This happens during early bootstrap
-            const earlyLog = createLogger("bootstrap", { level: "info" });
-            expect(earlyLog).toBeDefined();
-
-            // Later, initLogger is called
-            initLogger({ level: "debug" });
-
-            // New loggers get global config
-            const laterLog = createLogger("later");
-            expect(laterLog.transports[0].level).toBe("debug");
-
-            // But early logger keeps its config
-            expect(earlyLog.transports[0].level).toBe("info");
-        });
-
-        it("handles file: undefined vs file: empty string", () => {
-            initLogger({ file: "/tmp/test.log" });
-
-            // Explicit empty string disables file
-            const log1 = createLogger("test:1", { file: "" });
-            expect(log1.transports.length).toBe(1);
-
-            // No explicit option uses global
-            const log2 = createLogger("test:2");
-            expect(log2.transports.length).toBe(2);
-        });
-
-        it("serializes circular metadata with [Circular] marker in log output", () => {
-            const previousNodeEnv = process.env.NODE_ENV;
-            process.env.NODE_ENV = "production";
-
-            try {
-                const log = createLogger("test:namespace");
-                const circular: { self?: unknown } = {};
-                circular.self = circular;
-
-                const consoleTransport = log.transports[0] as {
-                    format: {
-                        transform: (
-                            info: Record<string, unknown>,
-                            opts?: unknown,
-                        ) => Record<PropertyKey, unknown>;
-                        options?: unknown;
-                    };
-                };
-
-                const transformed = consoleTransport.format.transform(
-                    {
-                        level: "info",
-                        [Symbol.for("level")]: "info",
-                        message: "circular metadata test",
-                        namespace: "test:namespace",
-                        circular,
-                    },
-                    consoleTransport.format.options,
-                );
-                const output = String(
-                    transformed[Symbol.for("message")] ?? "",
-                ).replace(/\u001b\[[0-9;]*m/g, "");
-
-                expect(output).toContain("circular metadata test");
-                expect(output).toContain("\"[Circular]\"");
-            } finally {
-                process.env.NODE_ENV = previousNodeEnv;
-            }
-        });
-
-        it("serializes Error metadata with name/message/stack in log output", () => {
-            const previousNodeEnv = process.env.NODE_ENV;
-            process.env.NODE_ENV = "production";
-
-            try {
-                const log = createLogger("test:namespace");
-                const consoleTransport = log.transports[0] as {
-                    format: {
-                        transform: (
-                            info: Record<string, unknown>,
-                            opts?: unknown,
-                        ) => Record<PropertyKey, unknown>;
-                        options?: unknown;
-                    };
-                };
-
-                const transformed = consoleTransport.format.transform(
-                    {
-                        level: "error",
-                        [Symbol.for("level")]: "error",
-                        message: "error metadata test",
-                        namespace: "test:namespace",
-                        err: new Error("boom"),
-                    },
-                    consoleTransport.format.options,
-                );
-                const output = String(
-                    transformed[Symbol.for("message")] ?? "",
-                ).replace(/\u001b\[[0-9;]*m/g, "");
-
-                expect(output).toContain("error metadata test");
-                expect(output).toContain("\"name\":\"Error\"");
-                expect(output).toContain("\"message\":\"boom\"");
-                expect(output).toContain("\"stack\"");
-            } finally {
-                process.env.NODE_ENV = previousNodeEnv;
-            }
-        });
-    });
-
-    describe("logger context", () => {
-        it("createLogger without context uses namespace as-is", () => {
-            const log = createLogger("test:namespace");
-            expect(log.defaultMeta.namespace).toBe("test:namespace");
-        });
-
-        it("createLogger with context prepends context to namespace", () => {
-            setLoggerContext("myapp");
-            const log = createLogger("test:namespace");
-            expect(log.defaultMeta.namespace).toBe("myapp:test:namespace");
-        });
-
-        it("getLoggerContext returns empty string by default", () => {
-            expect(getLoggerContext()).toBe("");
-        });
-
-        it("getLoggerContext returns the set context", () => {
-            setLoggerContext("myapp:process");
-            expect(getLoggerContext()).toBe("myapp:process");
-        });
-
-        it("resetLoggerContext clears the context", () => {
-            setLoggerContext("myapp");
-            expect(getLoggerContext()).toBe("myapp");
-
-            resetLoggerContext();
-            expect(getLoggerContext()).toBe("");
-
-            const log = createLogger("test");
-            expect(log.defaultMeta.namespace).toBe("test");
-        });
-
-        it("context works with nested namespaces", () => {
-            setLoggerContext("sockethub:platform:irc:abc123");
-            const log = createLogger("data-layer:worker");
-            expect(log.defaultMeta.namespace).toBe(
-                "sockethub:platform:irc:abc123:data-layer:worker",
-            );
-        });
-
-        it("context is process-wide, affects all subsequent loggers", () => {
-            setLoggerContext("process-context");
-
-            const log1 = createLogger("module1");
-            const log2 = createLogger("module2");
-            const log3 = createLogger("module3");
-
-            expect(log1.defaultMeta.namespace).toBe("process-context:module1");
-            expect(log2.defaultMeta.namespace).toBe("process-context:module2");
-            expect(log3.defaultMeta.namespace).toBe("process-context:module3");
-        });
-
-        it("resetLoggerForTesting also resets context", () => {
-            setLoggerContext("myapp");
-            initLogger({ level: "debug" });
-
-            resetLoggerForTesting();
-
-            expect(getLoggerContext()).toBe("");
-            const log = createLogger("test");
-            expect(log.defaultMeta.namespace).toBe("test");
-            expect(log.transports[0].level).toBe("info"); // back to default
-        });
-    });
-});

package/src/index.ts

@@ -1,300 +0,0 @@
-import winston from "winston";
-
-export type Logger = winston.Logger;
-
-export interface LoggerOptions {
-    level?: string;
-    fileLevel?: string;
-    file?: string;
-}
-
-// Global configuration state (set once at bootstrap via initLogger)
-let globalConfig: LoggerOptions | null = null;
-let hasLoggedInit = false;
-
-// Process-wide logger context (set once at process startup)
-let loggerContext = "";
-let loggerNamespaceStore = new WeakMap<Logger, string>();
-
-// Keep log formatting resilient when metadata contains errors, bigints, or cycles.
-function safeStringify(value: unknown): string {
-    try {
-        const parents: object[] = [];
-        return JSON.stringify(value, function (_key, innerValue) {
-            if (innerValue instanceof Error) {
-                return {
-                    name: innerValue.name,
-                    message: innerValue.message,
-                    stack: innerValue.stack,
-                };
-            }
-            if (typeof innerValue === "bigint") {
-                return innerValue.toString();
-            }
-            if (typeof innerValue === "object" && innerValue !== null) {
-                // Only treat values on the current traversal path as circular.
-                // Shared references in sibling branches should serialize normally.
-                const parent = this as unknown;
-                while (
-                    parents.length > 0 &&
-                    parents[parents.length - 1] !== parent
-                ) {
-                    parents.pop();
-                }
-                if (parents.includes(innerValue)) {
-                    return "[Circular]";
-                }
-                parents.push(innerValue);
-            }
-            return innerValue;
-        });
-    } catch {
-        return '"[Unserializable]"';
-    }
-}
-
-/**
- * Initialize the logger system with global configuration.
- *
- * Called once at server bootstrap with config settings. All subsequent
- * createLogger() calls will use these settings as defaults unless explicitly
- * overridden.
- *
- * @param options - Global logger configuration
- *
- * @example
- * ```typescript
- * // In server bootstrap
- * initLogger({
- *   level: config.get("logging:level"),
- *   fileLevel: config.get("logging:fileLevel"),
- *   file: config.get("logging:file"),
- * });
- * ```
- */
-export function initLogger(options: LoggerOptions): void {
-    globalConfig = options;
-
-    if (!hasLoggedInit) {
-        hasLoggedInit = true;
-        const initLog = createLogger("sockethub:logger");
-        initLog.debug("logger system initialized");
-        if (options.file) {
-            initLog.info(`log file path: ${options.file}`);
-            initLog.info(`file log level: ${options.fileLevel || "debug"}`);
-        }
-        initLog.info(`console log level: ${options.level || "info"}`);
-    }
-}
-
-/**
- * Set the logger context for this process.
- *
- * All subsequent createLogger() calls will prepend this context to their namespace.
- * This is typically set once at process startup to identify the process (e.g., "sockethub"
- * for the main server, or "sockethub:platform:irc:abc123" for a platform child process).
- *
- * @param context - The context string to prepend to all logger namespaces in this process
- *
- * @example
- * ```typescript
- * // In main server process
- * setLoggerContext('sockethub');
- * const log = createLogger('server:listener');
- * // Output namespace: "sockethub:server:listener"
- *
- * // In platform child process
- * setLoggerContext('sockethub:platform:irc:abc123');
- * const log = createLogger('main');
- * // Output namespace: "sockethub:platform:irc:abc123:main"
- * ```
- */
-export function setLoggerContext(context: string): void {
-    loggerContext = context;
-}
-
-/**
- * Get the current logger context for this process.
- *
- * @returns The current logger context string, or empty string if not set
- *
- * @example
- * ```typescript
- * const context = getLoggerContext();
- * if (context.includes(':platform:')) {
- *   // We're in a platform child process
- * }
- * ```
- */
-export function getLoggerContext(): string {
-    return loggerContext;
-}
-
-/**
- * Reset the logger context.
- *
- * Primarily used for testing to reset state between test cases.
- *
- * @example
- * ```typescript
- * afterEach(() => {
- *   resetLoggerContext();
- * });
- * ```
- */
-export function resetLoggerContext(): void {
-    loggerContext = "";
-}
-
-/**
- * Creates a Winston logger instance with console and optional file transports.
- *
- * Configuration priority (highest to lowest):
- * 1. Explicit options parameter
- * 2. Global config (set via initLogger)
- * 3. Environment variables (LOG_LEVEL, LOG_FILE_LEVEL, LOG_FILE)
- * 4. Defaults (info for console, debug for file)
- *
- * Log levels: error, warn, info, debug
- *
- * NODE_ENV=production disables console timestamps (for systemd)
- *
- * @param namespace - Logger namespace (e.g., "sockethub:data-layer:queue:...")
- * @param options - Optional logger configuration overrides
- * @returns Winston logger instance
- *
- * @example
- * ```typescript
- * // Uses global config if initLogger() was called
- * const log = createLogger("sockethub:data-layer:queue:irc-123");
- *
- * // Override for specific use case (e.g., early bootstrap logging)
- * const earlyLog = createLogger("sockethub:bootstrap", { level: "info" });
- * ```
- */
-export function createLogger(
-    namespace: string,
-    options: LoggerOptions = {},
-): Logger {
-    // Prepend logger context if set
-    const fullNamespace = loggerContext
-        ? `${loggerContext}:${namespace}`
-        : namespace;
-
-    // Priority: explicit options > global config > ENV > defaults
-    const cfg: LoggerOptions = {
-        level:
-            options.level ??
-            globalConfig?.level ??
-            process.env.LOG_LEVEL ??
-            "info",
-        fileLevel:
-            options.fileLevel ??
-            globalConfig?.fileLevel ??
-            process.env.LOG_FILE_LEVEL ??
-            "debug",
-        file:
-            options.file !== undefined
-                ? options.file
-                : globalConfig?.file !== undefined
-                  ? globalConfig.file
-                  : (process.env.LOG_FILE ?? ""),
-    };
-
-    const isProduction = process.env.NODE_ENV === "production";
-
-    const consoleFormat = isProduction
-        ? winston.format.combine(
-              winston.format.colorize(),
-              winston.format.printf(
-                  ({ level, message, namespace, ...meta }) => {
-                      const ns = namespace ? `${namespace} ` : "";
-                      const metaStr =
-                          Object.keys(meta).length > 0
-                              ? ` ${safeStringify(meta)}`
-                              : "";
-                      return `${level}: ${ns}${message}${metaStr}`;
-                  },
-              ),
-          )
-        : winston.format.combine(
-              winston.format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" }),
-              winston.format.colorize(),
-              winston.format.printf(
-                  ({ level, message, timestamp, namespace, ...meta }) => {
-                      const ns = namespace ? `${namespace} ` : "";
-                      const metaStr =
-                          Object.keys(meta).length > 0
-                              ? ` ${safeStringify(meta)}`
-                              : "";
-                      return `${timestamp} ${level}: ${ns}${message}${metaStr}`;
-                  },
-              ),
-          );
-
-    const transports: winston.transport[] = [
-        new winston.transports.Console({
-            level: cfg.level,
-            format: consoleFormat,
-        }),
-    ];
-
-    if (cfg.file) {
-        transports.push(
-            new winston.transports.File({
-                level: cfg.fileLevel,
-                filename: cfg.file,
-                format: winston.format.combine(
-                    winston.format.timestamp(),
-                    winston.format.json(),
-                ),
-            }),
-        );
-    }
-
-    const logger = winston.createLogger({
-        level: "debug", // Set to lowest level, let transports filter
-        defaultMeta: { namespace: fullNamespace },
-        transports,
-    });
-    loggerNamespaceStore.set(logger, fullNamespace);
-    return logger;
-}
-
-/**
- * Get the namespace from a logger instance.
- *
- * Extracts the full namespace (including context) that was set when the logger was created.
- * Useful for reusing the namespace in other systems like Redis connection names.
- *
- * @param logger - Logger instance created by createLogger()
- * @returns The full namespace string, or empty string if not found
- *
- * @example
- * ```typescript
- * const log = createLogger('data-layer:queue');
- * const namespace = getLoggerNamespace(log);
- * // Returns: "sockethub:data-layer:queue" (if context is "sockethub")
- *
- * // Use for Redis connection name
- * redisConfig.connectionName = namespace;
- * ```
- */
-export function getLoggerNamespace(logger: Logger): string {
-    return (
-        loggerNamespaceStore.get(logger) ??
-        (logger.defaultMeta as { namespace?: string })?.namespace ??
-        ""
-    );
-}
-
-/**
- * Reset logger state. Used primarily for testing.
- * @internal
- */
-export function resetLoggerForTesting(): void {
-    globalConfig = null;
-    hasLoggedInit = false;
-    loggerContext = "";
-    loggerNamespaceStore = new WeakMap<Logger, string>();
-}