@beespoke/micro-server-logger-winston 0.0.0-stage → 2.0.3

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# @beespoke/micro-server-logger-winston
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Winston logging and CLI table output, usable directly or as the application logger.
+
+Supports Node 24+ and Bun 1.3.14+.
+
+## Install
+
+```sh
+npm install @beespoke/micro-server @beespoke/micro-server-logger-winston
+```
+
+Use `bun add` in place of `npm install` for Bun projects.
+
+## Configure the plugin
+
+```ts
+import { defineConfig } from '@beespoke/micro-server';
+
+export default defineConfig({
+    plugins: ['@beespoke/micro-server-logger-winston'],
+});
+```
+
+## Log messages
+
+```ts
+import { Logger } from '@beespoke/micro-server-logger-winston';
+
+Logger.info('Application ready');
+Logger.warn('Retrying request', { attempt: 2 });
+Logger.error(new Error('Example error'));
+Logger.table([{ name: 'worker', status: 'ready' }]);
+```
+
+The root exports `Logger` as both a named and default export. Methods include `info`, `warn`, `error`, `debug`, and `table`. Plugin registration selects this facade as core's application logger and registers shutdown cleanup. An explicit `logger` in core configuration takes precedence. Only one plugin may provide the application logger.
+
+No plugin options are required; if provided, the options object must be empty. Standalone logging lazily creates its Winston instance; finish with `await Logger.close()`. The current default log level is `info`, so debug messages are filtered by that configuration.
+
+## Start the application
+
+Save the configuration as `micro-server.config.ts` next to your application's `package.json`, then create `index.ts`:
+
+```ts
+import { ApplicationServer } from '@beespoke/micro-server';
+
+await ApplicationServer.bootstrap();
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+    process.once(signal, () => {
+        void ApplicationServer.close().catch(error => {
+            console.error(error);
+            process.exitCode = 1;
+        });
+    });
+}
+```
+
+Run `bun index.ts` or `node --env-file-if-exists=.env index.ts`. Node requires ESM (`"type": "module"` in package.json). When using Bun, load configuration secrets from the application environment or its `.env` file.
+
+## TypeScript and lifecycle
+
+Add this type-only import to an application-owned `plugin-types.d.ts` for configuration autocomplete:
+
+```ts
+import type {} from '@beespoke/micro-server-logger-winston/plugin';
+```
+
+Core validates plugin options before setup and owns cleanup after successful startup or startup failure. Await `ApplicationServer.bootstrap()` before using the configured client, and call `ApplicationServer.close()` during application shutdown. Importing the package does not open a connection. Relative plugin paths resolve from the selected configuration file's directory.
+
+The root export can also be used without HTTP core. In that case, explicitly initialize and close the client. The `/plugin` entry is the integration adapter for `@beespoke/micro-server`.

package/dist/Logger.d.ts

@@ -0,0 +1,13 @@
+import type { PluginContext } from './PluginContext.js';
+/** Static methods also satisfy the core's variadic logger contract. */
+export default class Logger {
+    readonly name = "logger-winston";
+    setup(context: PluginContext): void;
+    static info(...args: unknown[]): void;
+    static error(...args: unknown[]): void;
+    static warn(...args: unknown[]): void;
+    static debug(...args: unknown[]): void;
+    private static write;
+    static table(data: object[]): void;
+    static close(): Promise<void>;
+}

package/dist/PluginContext.d.ts

@@ -0,0 +1,13 @@
+/** Structural subset of the core context; standalone clients need no HTTP dependency. */
+export interface Logger {
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+export interface PluginContext {
+    readonly logger: Logger;
+    readonly configDir: string;
+    onStart(hook: () => void | Promise<void>): void;
+    onClose(hook: () => void | Promise<void>): void;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { default, default as Logger } from './Logger.js';

package/dist/index.js

@@ -0,0 +1,104 @@
+// src/Logger.ts
+import winston from "winston";
+import Table from "cli-table3";
+var activeLogger;
+var closing;
+function getLogger() {
+  if (!activeLogger) {
+    const { combine, timestamp, errors, splat, printf, colorize } = winston.format;
+    activeLogger = winston.createLogger({
+      level: "info",
+      format: combine(errors({ stack: true }), timestamp(), colorize(), splat(), printf((info) => {
+        const message = typeof info.message === "object" ? JSON.stringify(info.message, null, 3) : info.message;
+        return `[${info.level}]${info.timestamp}: ${message}`;
+      })),
+      transports: [new winston.transports.Console]
+    });
+  }
+  return activeLogger;
+}
+
+class Logger {
+  name = "logger-winston";
+  setup(context) {
+    context.onClose(() => Logger.close());
+  }
+  static info(...args) {
+    Logger.write("info", args);
+  }
+  static error(...args) {
+    Logger.write("error", args);
+  }
+  static warn(...args) {
+    Logger.write("warn", args);
+  }
+  static debug(...args) {
+    Logger.write("debug", args);
+  }
+  static write(level, args) {
+    if (!args.length)
+      return;
+    const [message, ...details] = args;
+    const logger = getLogger();
+    if (message instanceof Error && details.length === 0)
+      logger[level](message);
+    else if (typeof message === "string")
+      logger[level](`${message}${details.length ? " %o".repeat(details.length) : ""}`, ...details);
+    else
+      logger[level]({ message, ...details.length ? { details } : {} });
+  }
+  static table(data) {
+    if (!Array.isArray(data) || data.length === 0) {
+      Logger.info("No data to display in table.");
+      return;
+    }
+    const headers = Object.keys(data[0]);
+    const table = new Table({
+      head: headers,
+      wordWrap: true,
+      wrapOnWordBoundary: false,
+      colWidths: headers.map(() => 30),
+      style: { head: ["green"], border: ["grey"] }
+    });
+    for (const row of data) {
+      table.push(headers.map((header) => {
+        const value = row[header];
+        return typeof value === "object" && value !== null ? JSON.stringify(value) : String(value);
+      }));
+    }
+    Logger.info(`
+` + table.toString());
+  }
+  static async close() {
+    if (closing)
+      return closing;
+    const logger = activeLogger;
+    if (!logger)
+      return;
+    activeLogger = undefined;
+    closing = new Promise((resolve, reject) => {
+      const finish = () => {
+        logger.removeListener("error", fail);
+        logger.close();
+        resolve();
+      };
+      const fail = (error) => {
+        logger.removeListener("finish", finish);
+        logger.close();
+        reject(error);
+      };
+      logger.once("finish", finish);
+      logger.once("error", fail);
+      logger.end();
+    });
+    try {
+      await closing;
+    } finally {
+      closing = undefined;
+    }
+  }
+}
+export {
+  Logger as default,
+  Logger
+};

package/dist/plugin/index.d.ts

@@ -0,0 +1,9 @@
+import type { PluginDefinition } from '@beespoke/micro-server';
+export type WinstonPluginOptions = Record<string, never>;
+declare module '@beespoke/micro-server' {
+    interface PluginOptionsRegistry {
+        '@beespoke/micro-server-logger-winston': WinstonPluginOptions;
+    }
+}
+declare const definition: PluginDefinition<WinstonPluginOptions>;
+export default definition;

package/dist/plugin/index.js

@@ -0,0 +1,22 @@
+// src/plugin/index.ts
+import { Logger } from "../index.js";
+var definition = {
+  name: "@beespoke/micro-server-logger-winston",
+  validate(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options) || Object.keys(options).length)
+      throw new Error("Winston options must be an empty object");
+  },
+  create() {
+    return {
+      name: "logger-winston",
+      applicationLogger: Logger,
+      setup(context) {
+        new Logger().setup(context);
+      }
+    };
+  }
+};
+var plugin_default = definition;
+export {
+  plugin_default as default
+};

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@beespoke/micro-server-logger-winston",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.3",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin/index.d.ts",
+      "import": "./dist/plugin/index.js",
+      "default": "./dist/plugin/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun ../../scripts/build-package.ts"
+  },
+  "dependencies": {
+    "winston": "^3.13.0",
+    "cli-table3": "^0.6.5",
+    "@types/node": "^24.0.0"
+  },
+  "peerDependencies": {
+    "@beespoke/micro-server": "^2.0.3"
+  },
+  "peerDependenciesMeta": {
+    "@beespoke/micro-server": {
+      "optional": true
+    }
+  }
+}