@webpieces/winston 0.3.307

package/README.md

@@ -0,0 +1,41 @@
+# @webpieces/winston
+
+Node-only [winston](https://github.com/winstonjs/winston) backends for the webpieces
+pluggable logging seam (`LoggerFactory` → `Logger` from `@webpieces/core-util`).
+
+Two factories, both auto-enriching every line with the logged context keys registered in
+`HeaderRegistry`:
+
+- **`WinstonConsoleFactory`** — local dev: colorized single-line pretty output,
+  `[loggerName] [requestId=… tenantId=…] level: message {…extra}`.
+- **`WinstonGcpFactory`** — Cloud Run / GKE: flat JSON to **stdout**, scraped by the logging
+  agent. A level→`severity` map is the only GCP glue (no `@google-cloud` transport);
+  registered context keys land at top-level `jsonPayload.<name>`. This mirrors the
+  tested-in-GCP logger in `onetablet/monorepo-nx1`.
+
+## Usage
+
+```ts
+import { LogManager, HeaderRegistry } from '@webpieces/core-util';
+import { WinstonGcpFactory, WinstonConsoleFactory } from '@webpieces/winston';
+import { RequestContextReader } from '@webpieces/core-context';
+
+const reader = new RequestContextReader();
+const loggerFactory = process.env.K_SERVICE
+    ? new WinstonGcpFactory(reader)
+    : new WinstonConsoleFactory(reader);
+
+// Typically you pass loggerFactory to setupRuntime(new RuntimeSetupOptions(loggerFactory, ...)),
+// which calls HeaderRegistry.configure(...) then LogManager.setFactory(loggerFactory) for you.
+```
+
+The `ContextReader` is a **constructor argument** (the node `RequestContextReader` lives in
+`@webpieces/core-context`) so this package depends only on `@webpieces/core-util` — not on
+any node context package.
+
+## Options
+
+`new WinstonGcpFactory(reader, new WinstonFactoryOptions(level, svcGitHash))`:
+
+- `level` — minimum webpieces level to emit (default `'info'`). `trace` maps to winston `silly`.
+- `svcGitHash` — when set, every line carries `jsonPayload.svcGitHash` (deployment filter).

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@webpieces/winston",
+  "version": "0.3.307",
+  "description": "Node-only winston LoggerFactory backends for webpieces: Console (local pretty) + GCP (Cloud Run stdout JSON), auto-enriched with HeaderRegistry context keys",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "author": "Dean Hiller",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deanhiller/webpieces-ts.git",
+    "directory": "packages/logging/winston"
+  },
+  "keywords": [
+    "webpieces",
+    "winston",
+    "logging",
+    "gcp",
+    "cloud-run"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@webpieces/core-util": "0.3.307",
+    "winston": "3.11.0",
+    "logform": "2.7.0",
+    "safe-stable-stringify": "2.5.0"
+  }
+}

package/src/WinstonConsoleFactory.d.ts

@@ -0,0 +1,15 @@
+import type { ContextReader } from '@webpieces/core-util';
+import { WinstonFactoryBase } from './WinstonFactoryBase';
+import { WinstonFactoryOptions } from './WinstonFactoryOptions';
+/**
+ * WinstonConsoleFactory - the LOCAL developer backend. Colorized single-line
+ * pretty console output with the registered context keys as a bracketed prefix,
+ * for human reading — same enrichment as the GCP backend, different rendering.
+ * Matches the tested onetablet/monorepo-nx1 local logger.
+ *
+ * @param reader the environment's ContextReader (on a node server, a
+ *   `RequestContextReader` from @webpieces/core-context).
+ */
+export declare class WinstonConsoleFactory extends WinstonFactoryBase {
+    constructor(reader: ContextReader, opts?: WinstonFactoryOptions);
+}

package/src/WinstonConsoleFactory.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WinstonConsoleFactory = void 0;
+const winston_1 = require("winston");
+const WinstonFactoryBase_1 = require("./WinstonFactoryBase");
+const WinstonFactoryOptions_1 = require("./WinstonFactoryOptions");
+const format_1 = require("./format");
+/**
+ * WinstonConsoleFactory - the LOCAL developer backend. Colorized single-line
+ * pretty console output with the registered context keys as a bracketed prefix,
+ * for human reading — same enrichment as the GCP backend, different rendering.
+ * Matches the tested onetablet/monorepo-nx1 local logger.
+ *
+ * @param reader the environment's ContextReader (on a node server, a
+ *   `RequestContextReader` from @webpieces/core-context).
+ */
+class WinstonConsoleFactory extends WinstonFactoryBase_1.WinstonFactoryBase {
+    constructor(reader, opts = new WinstonFactoryOptions_1.WinstonFactoryOptions()) {
+        super(winston_1.format.combine((0, format_1.bigIntSafeFormat)(), (0, format_1.injectContextFormat)(reader), (0, format_1.severityFormat)(), winston_1.format.colorize(), (0, format_1.localPrettyFormat)()), opts);
+    }
+}
+exports.WinstonConsoleFactory = WinstonConsoleFactory;
+//# sourceMappingURL=WinstonConsoleFactory.js.map

package/src/WinstonConsoleFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WinstonConsoleFactory.js","sourceRoot":"","sources":["../../../../../packages/logging/winston/src/WinstonConsoleFactory.ts"],"names":[],"mappings":";;;AAAA,qCAAiC;AAEjC,6DAA0D;AAC1D,mEAAgE;AAChE,qCAAoG;AAEpG;;;;;;;;GAQG;AACH,MAAa,qBAAsB,SAAQ,uCAAkB;IACzD,YAAY,MAAqB,EAAE,OAA8B,IAAI,6CAAqB,EAAE;QACxF,KAAK,CACD,gBAAM,CAAC,OAAO,CACV,IAAA,yBAAgB,GAAE,EAClB,IAAA,4BAAmB,EAAC,MAAM,CAAC,EAC3B,IAAA,uBAAc,GAAE,EAChB,gBAAM,CAAC,QAAQ,EAAE,EACjB,IAAA,0BAAiB,GAAE,CACtB,EACD,IAAI,CACP,CAAC;IACN,CAAC;CACJ;AAbD,sDAaC","sourcesContent":["import { format } from 'winston';\nimport type { ContextReader } from '@webpieces/core-util';\nimport { WinstonFactoryBase } from './WinstonFactoryBase';\nimport { WinstonFactoryOptions } from './WinstonFactoryOptions';\nimport { bigIntSafeFormat, injectContextFormat, localPrettyFormat, severityFormat } from './format';\n\n/**\n * WinstonConsoleFactory - the LOCAL developer backend. Colorized single-line\n * pretty console output with the registered context keys as a bracketed prefix,\n * for human reading — same enrichment as the GCP backend, different rendering.\n * Matches the tested onetablet/monorepo-nx1 local logger.\n *\n * @param reader the environment's ContextReader (on a node server, a\n *   `RequestContextReader` from @webpieces/core-context).\n */\nexport class WinstonConsoleFactory extends WinstonFactoryBase {\n    constructor(reader: ContextReader, opts: WinstonFactoryOptions = new WinstonFactoryOptions()) {\n        super(\n            format.combine(\n                bigIntSafeFormat(),\n                injectContextFormat(reader),\n                severityFormat(),\n                format.colorize(),\n                localPrettyFormat(),\n            ),\n            opts,\n        );\n    }\n}\n"]}

package/src/WinstonFactoryBase.d.ts

@@ -0,0 +1,16 @@
+import type { Format } from 'logform';
+import type { Logger, LoggerFactory } from '@webpieces/core-util';
+import { WinstonFactoryOptions } from './WinstonFactoryOptions';
+/**
+ * WinstonFactoryBase - shared plumbing for the winston {@link LoggerFactory}
+ * backends. Builds ONE underlying winston logger (a single `Console` transport,
+ * handleExceptions/Rejections on) with the caller-chosen format stack, then hands
+ * out a cached {@link WinstonLogger} per name (each a winston child carrying
+ * `loggerName`). Subclasses differ only in the format stack they pass up.
+ */
+export declare abstract class WinstonFactoryBase implements LoggerFactory {
+    private readonly base;
+    private readonly loggers;
+    protected constructor(finalFormat: Format, opts: WinstonFactoryOptions);
+    getLogger(name: string): Logger;
+}

package/src/WinstonFactoryBase.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WinstonFactoryBase = void 0;
+const winston_1 = require("winston");
+const WinstonLogger_1 = require("./WinstonLogger");
+/**
+ * WinstonFactoryBase - shared plumbing for the winston {@link LoggerFactory}
+ * backends. Builds ONE underlying winston logger (a single `Console` transport,
+ * handleExceptions/Rejections on) with the caller-chosen format stack, then hands
+ * out a cached {@link WinstonLogger} per name (each a winston child carrying
+ * `loggerName`). Subclasses differ only in the format stack they pass up.
+ */
+class WinstonFactoryBase {
+    base;
+    loggers = new Map();
+    constructor(finalFormat, opts) {
+        this.base = (0, winston_1.createLogger)({
+            level: WinstonLogger_1.LEVEL_TO_WINSTON[opts.level],
+            format: finalFormat,
+            defaultMeta: opts.svcGitHash ? { svcGitHash: opts.svcGitHash } : undefined,
+            transports: [new winston_1.transports.Console()],
+            handleExceptions: true,
+            handleRejections: true,
+        });
+    }
+    getLogger(name) {
+        let logger = this.loggers.get(name);
+        if (!logger) {
+            logger = new WinstonLogger_1.WinstonLogger(this.base.child({ loggerName: name }));
+            this.loggers.set(name, logger);
+        }
+        return logger;
+    }
+}
+exports.WinstonFactoryBase = WinstonFactoryBase;
+//# sourceMappingURL=WinstonFactoryBase.js.map

package/src/WinstonFactoryBase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WinstonFactoryBase.js","sourceRoot":"","sources":["../../../../../packages/logging/winston/src/WinstonFactoryBase.ts"],"names":[],"mappings":";;;AAAA,qCAAmD;AAInD,mDAAkE;AAGlE;;;;;;GAMG;AACH,MAAsB,kBAAkB;IACnB,IAAI,CAAc;IAClB,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAErD,YAAsB,WAAmB,EAAE,IAA2B;QAClE,IAAI,CAAC,IAAI,GAAG,IAAA,sBAAY,EAAC;YACrB,KAAK,EAAE,gCAAgB,CAAC,IAAI,CAAC,KAAK,CAAC;YACnC,MAAM,EAAE,WAAW;YACnB,WAAW,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,SAAS;YAC1E,UAAU,EAAE,CAAC,IAAI,oBAAU,CAAC,OAAO,EAAE,CAAC;YACtC,gBAAgB,EAAE,IAAI;YACtB,gBAAgB,EAAE,IAAI;SACzB,CAAC,CAAC;IACP,CAAC;IAED,SAAS,CAAC,IAAY;QAClB,IAAI,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,EAAE,CAAC;YACV,MAAM,GAAG,IAAI,6BAAa,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;YAClE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,MAAM,CAAC;IAClB,CAAC;CACJ;AAvBD,gDAuBC","sourcesContent":["import { createLogger, transports } from 'winston';\nimport type { Logger as WinstonBase } from 'winston';\nimport type { Format } from 'logform';\nimport type { Logger, LoggerFactory } from '@webpieces/core-util';\nimport { LEVEL_TO_WINSTON, WinstonLogger } from './WinstonLogger';\nimport { WinstonFactoryOptions } from './WinstonFactoryOptions';\n\n/**\n * WinstonFactoryBase - shared plumbing for the winston {@link LoggerFactory}\n * backends. Builds ONE underlying winston logger (a single `Console` transport,\n * handleExceptions/Rejections on) with the caller-chosen format stack, then hands\n * out a cached {@link WinstonLogger} per name (each a winston child carrying\n * `loggerName`). Subclasses differ only in the format stack they pass up.\n */\nexport abstract class WinstonFactoryBase implements LoggerFactory {\n    private readonly base: WinstonBase;\n    private readonly loggers = new Map<string, Logger>();\n\n    protected constructor(finalFormat: Format, opts: WinstonFactoryOptions) {\n        this.base = createLogger({\n            level: LEVEL_TO_WINSTON[opts.level],\n            format: finalFormat,\n            defaultMeta: opts.svcGitHash ? { svcGitHash: opts.svcGitHash } : undefined,\n            transports: [new transports.Console()],\n            handleExceptions: true,\n            handleRejections: true,\n        });\n    }\n\n    getLogger(name: string): Logger {\n        let logger = this.loggers.get(name);\n        if (!logger) {\n            logger = new WinstonLogger(this.base.child({ loggerName: name }));\n            this.loggers.set(name, logger);\n        }\n        return logger;\n    }\n}\n"]}

package/src/WinstonFactoryOptions.d.ts

@@ -0,0 +1,32 @@
+import type { LogLevel } from '@webpieces/core-util';
+/**
+ * WinstonFactoryOptions - tuning for the winston LoggerFactory backends.
+ *
+ * Data-only structure → a class, per CLAUDE.md. All fields optional; a bare
+ * `new WinstonGcpFactory(reader)` uses the defaults (INFO threshold, no git hash).
+ */
+export declare class WinstonFactoryOptions {
+    /**
+     * Minimum webpieces level to emit. Defaults to 'info' (matching the
+     * tested monorepo-nx logger); pass 'trace'/'debug' to see finer lines.
+     */
+    readonly level: LogLevel;
+    /**
+     * The running service's git commit SHA. When set, every line carries
+     * `jsonPayload.svcGitHash=<sha>` (winston defaultMeta) so operators can
+     * filter Cloud Logging by deployment.
+     */
+    readonly svcGitHash?: string | undefined;
+    constructor(
+    /**
+     * Minimum webpieces level to emit. Defaults to 'info' (matching the
+     * tested monorepo-nx logger); pass 'trace'/'debug' to see finer lines.
+     */
+    level?: LogLevel, 
+    /**
+     * The running service's git commit SHA. When set, every line carries
+     * `jsonPayload.svcGitHash=<sha>` (winston defaultMeta) so operators can
+     * filter Cloud Logging by deployment.
+     */
+    svcGitHash?: string | undefined);
+}

package/src/WinstonFactoryOptions.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WinstonFactoryOptions = void 0;
+/**
+ * WinstonFactoryOptions - tuning for the winston LoggerFactory backends.
+ *
+ * Data-only structure → a class, per CLAUDE.md. All fields optional; a bare
+ * `new WinstonGcpFactory(reader)` uses the defaults (INFO threshold, no git hash).
+ */
+class WinstonFactoryOptions {
+    level;
+    svcGitHash;
+    constructor(
+    /**
+     * Minimum webpieces level to emit. Defaults to 'info' (matching the
+     * tested monorepo-nx logger); pass 'trace'/'debug' to see finer lines.
+     */
+    level = 'info', 
+    /**
+     * The running service's git commit SHA. When set, every line carries
+     * `jsonPayload.svcGitHash=<sha>` (winston defaultMeta) so operators can
+     * filter Cloud Logging by deployment.
+     */
+    svcGitHash) {
+        this.level = level;
+        this.svcGitHash = svcGitHash;
+    }
+}
+exports.WinstonFactoryOptions = WinstonFactoryOptions;
+//# sourceMappingURL=WinstonFactoryOptions.js.map

package/src/WinstonFactoryOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WinstonFactoryOptions.js","sourceRoot":"","sources":["../../../../../packages/logging/winston/src/WinstonFactoryOptions.ts"],"names":[],"mappings":";;;AAEA;;;;;GAKG;AACH,MAAa,qBAAqB;IAMV;IAMA;IAXpB;IACI;;;OAGG;IACa,QAAkB,MAAM;IACxC;;;;OAIG;IACa,UAAmB;QANnB,UAAK,GAAL,KAAK,CAAmB;QAMxB,eAAU,GAAV,UAAU,CAAS;IACpC,CAAC;CACP;AAdD,sDAcC","sourcesContent":["import type { LogLevel } from '@webpieces/core-util';\n\n/**\n * WinstonFactoryOptions - tuning for the winston LoggerFactory backends.\n *\n * Data-only structure → a class, per CLAUDE.md. All fields optional; a bare\n * `new WinstonGcpFactory(reader)` uses the defaults (INFO threshold, no git hash).\n */\nexport class WinstonFactoryOptions {\n    constructor(\n        /**\n         * Minimum webpieces level to emit. Defaults to 'info' (matching the\n         * tested monorepo-nx logger); pass 'trace'/'debug' to see finer lines.\n         */\n        public readonly level: LogLevel = 'info',\n        /**\n         * The running service's git commit SHA. When set, every line carries\n         * `jsonPayload.svcGitHash=<sha>` (winston defaultMeta) so operators can\n         * filter Cloud Logging by deployment.\n         */\n        public readonly svcGitHash?: string,\n    ) {}\n}\n"]}

package/src/WinstonGcpFactory.d.ts

@@ -0,0 +1,18 @@
+import type { ContextReader } from '@webpieces/core-util';
+import { WinstonFactoryBase } from './WinstonFactoryBase';
+import { WinstonFactoryOptions } from './WinstonFactoryOptions';
+/**
+ * WinstonGcpFactory - the GCP/Cloud Run backend. Emits flat JSON to stdout; the
+ * Cloud Run / GKE logging agent natively parses it — `severity` + `message` lift
+ * onto the LogEntry and every registered context key lands at top-level
+ * jsonPayload.<name> (requestId, tenantId, …), filterable directly. There is NO
+ * @google-cloud transport — correlation rides the webpieces context. This matches
+ * the tested-in-GCP onetablet/monorepo-nx1 core logger exactly.
+ *
+ * @param reader the environment's ContextReader — on a node server pass
+ *   `new RequestContextReader()` from @webpieces/core-context. Keeping it a
+ *   constructor arg is why this package depends only on @webpieces/core-util.
+ */
+export declare class WinstonGcpFactory extends WinstonFactoryBase {
+    constructor(reader: ContextReader, opts?: WinstonFactoryOptions);
+}

package/src/WinstonGcpFactory.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WinstonGcpFactory = void 0;
+const winston_1 = require("winston");
+const WinstonFactoryBase_1 = require("./WinstonFactoryBase");
+const WinstonFactoryOptions_1 = require("./WinstonFactoryOptions");
+const format_1 = require("./format");
+/**
+ * WinstonGcpFactory - the GCP/Cloud Run backend. Emits flat JSON to stdout; the
+ * Cloud Run / GKE logging agent natively parses it — `severity` + `message` lift
+ * onto the LogEntry and every registered context key lands at top-level
+ * jsonPayload.<name> (requestId, tenantId, …), filterable directly. There is NO
+ * @google-cloud transport — correlation rides the webpieces context. This matches
+ * the tested-in-GCP onetablet/monorepo-nx1 core logger exactly.
+ *
+ * @param reader the environment's ContextReader — on a node server pass
+ *   `new RequestContextReader()` from @webpieces/core-context. Keeping it a
+ *   constructor arg is why this package depends only on @webpieces/core-util.
+ */
+class WinstonGcpFactory extends WinstonFactoryBase_1.WinstonFactoryBase {
+    constructor(reader, opts = new WinstonFactoryOptions_1.WinstonFactoryOptions()) {
+        super(winston_1.format.combine((0, format_1.bigIntSafeFormat)(), (0, format_1.injectContextFormat)(reader), (0, format_1.severityFormat)(), winston_1.format.json()), opts);
+    }
+}
+exports.WinstonGcpFactory = WinstonGcpFactory;
+//# sourceMappingURL=WinstonGcpFactory.js.map

package/src/WinstonGcpFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WinstonGcpFactory.js","sourceRoot":"","sources":["../../../../../packages/logging/winston/src/WinstonGcpFactory.ts"],"names":[],"mappings":";;;AAAA,qCAAiC;AAEjC,6DAA0D;AAC1D,mEAAgE;AAChE,qCAAiF;AAEjF;;;;;;;;;;;GAWG;AACH,MAAa,iBAAkB,SAAQ,uCAAkB;IACrD,YAAY,MAAqB,EAAE,OAA8B,IAAI,6CAAqB,EAAE;QACxF,KAAK,CACD,gBAAM,CAAC,OAAO,CACV,IAAA,yBAAgB,GAAE,EAClB,IAAA,4BAAmB,EAAC,MAAM,CAAC,EAC3B,IAAA,uBAAc,GAAE,EAChB,gBAAM,CAAC,IAAI,EAAE,CAChB,EACD,IAAI,CACP,CAAC;IACN,CAAC;CACJ;AAZD,8CAYC","sourcesContent":["import { format } from 'winston';\nimport type { ContextReader } from '@webpieces/core-util';\nimport { WinstonFactoryBase } from './WinstonFactoryBase';\nimport { WinstonFactoryOptions } from './WinstonFactoryOptions';\nimport { bigIntSafeFormat, injectContextFormat, severityFormat } from './format';\n\n/**\n * WinstonGcpFactory - the GCP/Cloud Run backend. Emits flat JSON to stdout; the\n * Cloud Run / GKE logging agent natively parses it — `severity` + `message` lift\n * onto the LogEntry and every registered context key lands at top-level\n * jsonPayload.<name> (requestId, tenantId, …), filterable directly. There is NO\n * @google-cloud transport — correlation rides the webpieces context. This matches\n * the tested-in-GCP onetablet/monorepo-nx1 core logger exactly.\n *\n * @param reader the environment's ContextReader — on a node server pass\n *   `new RequestContextReader()` from @webpieces/core-context. Keeping it a\n *   constructor arg is why this package depends only on @webpieces/core-util.\n */\nexport class WinstonGcpFactory extends WinstonFactoryBase {\n    constructor(reader: ContextReader, opts: WinstonFactoryOptions = new WinstonFactoryOptions()) {\n        super(\n            format.combine(\n                bigIntSafeFormat(),\n                injectContextFormat(reader),\n                severityFormat(),\n                format.json(),\n            ),\n            opts,\n        );\n    }\n}\n"]}

package/src/WinstonLogger.d.ts

@@ -0,0 +1,25 @@
+import type { Logger, LogLevel } from '@webpieces/core-util';
+import type { Logger as WinstonBase } from 'winston';
+/**
+ * webpieces LogLevel → winston level name. webpieces `trace` has no native
+ * winston counterpart, so it maps onto winston `silly` (the finest npm level);
+ * both resolve to GCP severity DEBUG via LEVEL_TO_SEVERITY.
+ */
+export declare const LEVEL_TO_WINSTON: Record<LogLevel, string>;
+/**
+ * WinstonLogger - a webpieces {@link Logger} backed by a winston logger instance
+ * (one per name, created as a winston child carrying `loggerName`). Context
+ * enrichment is done by the shared winston formats (see format.ts), so this
+ * wrapper only maps the 5 webpieces levels and spreads an optional Error into
+ * `errName`/`errMessage`/`errStack` — matching the tested monorepo-nx behaviour.
+ */
+export declare class WinstonLogger implements Logger {
+    private readonly winston;
+    constructor(winston: WinstonBase);
+    trace(message: string, err?: Error): void;
+    debug(message: string, err?: Error): void;
+    info(message: string, err?: Error): void;
+    warn(message: string, err?: Error): void;
+    error(message: string, err?: Error): void;
+    private emit;
+}

package/src/WinstonLogger.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WinstonLogger = exports.LEVEL_TO_WINSTON = void 0;
+/**
+ * webpieces LogLevel → winston level name. webpieces `trace` has no native
+ * winston counterpart, so it maps onto winston `silly` (the finest npm level);
+ * both resolve to GCP severity DEBUG via LEVEL_TO_SEVERITY.
+ */
+exports.LEVEL_TO_WINSTON = {
+    trace: 'silly',
+    debug: 'debug',
+    info: 'info',
+    warn: 'warn',
+    error: 'error',
+};
+/**
+ * WinstonLogger - a webpieces {@link Logger} backed by a winston logger instance
+ * (one per name, created as a winston child carrying `loggerName`). Context
+ * enrichment is done by the shared winston formats (see format.ts), so this
+ * wrapper only maps the 5 webpieces levels and spreads an optional Error into
+ * `errName`/`errMessage`/`errStack` — matching the tested monorepo-nx behaviour.
+ */
+class WinstonLogger {
+    winston;
+    constructor(winston) {
+        this.winston = winston;
+    }
+    trace(message, err) {
+        this.emit('trace', message, err);
+    }
+    debug(message, err) {
+        this.emit('debug', message, err);
+    }
+    info(message, err) {
+        this.emit('info', message, err);
+    }
+    warn(message, err) {
+        this.emit('warn', message, err);
+    }
+    error(message, err) {
+        this.emit('error', message, err);
+    }
+    emit(level, message, err) {
+        const winstonLevel = exports.LEVEL_TO_WINSTON[level];
+        if (err) {
+            this.winston.log(winstonLevel, message, {
+                errName: err.name,
+                errMessage: err.message,
+                errStack: err.stack,
+            });
+        }
+        else {
+            this.winston.log(winstonLevel, message);
+        }
+    }
+}
+exports.WinstonLogger = WinstonLogger;
+//# sourceMappingURL=WinstonLogger.js.map

package/src/WinstonLogger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WinstonLogger.js","sourceRoot":"","sources":["../../../../../packages/logging/winston/src/WinstonLogger.ts"],"names":[],"mappings":";;;AAGA;;;;GAIG;AACU,QAAA,gBAAgB,GAA6B;IACtD,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;CACjB,CAAC;AAEF;;;;;;GAMG;AACH,MAAa,aAAa;IACO;IAA7B,YAA6B,OAAoB;QAApB,YAAO,GAAP,OAAO,CAAa;IAAG,CAAC;IAErD,KAAK,CAAC,OAAe,EAAE,GAAW;QAC9B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,GAAW;QAC9B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IACrC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,GAAW;QAC7B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IACpC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,GAAW;QAC7B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,GAAW;QAC9B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IACrC,CAAC;IAEO,IAAI,CAAC,KAAe,EAAE,OAAe,EAAE,GAAW;QACtD,MAAM,YAAY,GAAG,wBAAgB,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,GAAG,EAAE,CAAC;YACN,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,OAAO,EAAE;gBACpC,OAAO,EAAE,GAAG,CAAC,IAAI;gBACjB,UAAU,EAAE,GAAG,CAAC,OAAO;gBACvB,QAAQ,EAAE,GAAG,CAAC,KAAK;aACtB,CAAC,CAAC;QACP,CAAC;aAAM,CAAC;YACJ,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QAC5C,CAAC;IACL,CAAC;CACJ;AAnCD,sCAmCC","sourcesContent":["import type { Logger, LogLevel } from '@webpieces/core-util';\nimport type { Logger as WinstonBase } from 'winston';\n\n/**\n * webpieces LogLevel → winston level name. webpieces `trace` has no native\n * winston counterpart, so it maps onto winston `silly` (the finest npm level);\n * both resolve to GCP severity DEBUG via LEVEL_TO_SEVERITY.\n */\nexport const LEVEL_TO_WINSTON: Record<LogLevel, string> = {\n    trace: 'silly',\n    debug: 'debug',\n    info: 'info',\n    warn: 'warn',\n    error: 'error',\n};\n\n/**\n * WinstonLogger - a webpieces {@link Logger} backed by a winston logger instance\n * (one per name, created as a winston child carrying `loggerName`). Context\n * enrichment is done by the shared winston formats (see format.ts), so this\n * wrapper only maps the 5 webpieces levels and spreads an optional Error into\n * `errName`/`errMessage`/`errStack` — matching the tested monorepo-nx behaviour.\n */\nexport class WinstonLogger implements Logger {\n    constructor(private readonly winston: WinstonBase) {}\n\n    trace(message: string, err?: Error): void {\n        this.emit('trace', message, err);\n    }\n\n    debug(message: string, err?: Error): void {\n        this.emit('debug', message, err);\n    }\n\n    info(message: string, err?: Error): void {\n        this.emit('info', message, err);\n    }\n\n    warn(message: string, err?: Error): void {\n        this.emit('warn', message, err);\n    }\n\n    error(message: string, err?: Error): void {\n        this.emit('error', message, err);\n    }\n\n    private emit(level: LogLevel, message: string, err?: Error): void {\n        const winstonLevel = LEVEL_TO_WINSTON[level];\n        if (err) {\n            this.winston.log(winstonLevel, message, {\n                errName: err.name,\n                errMessage: err.message,\n                errStack: err.stack,\n            });\n        } else {\n            this.winston.log(winstonLevel, message);\n        }\n    }\n}\n"]}

package/src/format.d.ts

@@ -0,0 +1,36 @@
+import type { Format } from 'logform';
+import type { ContextReader } from '@webpieces/core-util';
+export declare const LEVEL_TO_SEVERITY: Record<string, string>;
+/**
+ * Round-trip the record through safe-stable-stringify so circular references
+ * (HTTP client/response cycles, request/response objects, framework execution
+ * contexts) become "[Circular]" instead of crashing the log emit, and bigints
+ * serialize as strings (JSON.stringify can't, and the bare safe-stringify output
+ * wouldn't round-trip through JSON.parse). Symbol keys winston relies on are
+ * untouched (JSON ignores them), so Object.assign only rewrites string fields.
+ */
+export declare function bigIntSafeFormat(): Format;
+/**
+ * Inject every logged HeaderRegistry context key present in the current context
+ * frame into the record under its `name` (→ top-level jsonPayload.<name> in GCP,
+ * filterable as jsonPayload.requestId, jsonPayload.tenantId, …). Secured keys are
+ * masked by HeaderMethods.buildSecureMapForLogs. Caller-supplied fields on the
+ * record win on conflict. Runs on EVERY winston call, including winston's own
+ * handleExceptions/handleRejections lines that bypass the WinstonLogger wrapper.
+ *
+ * The registry is read LAZILY (first log call) because a LoggerFactory is
+ * constructed by the app BEFORE setupRuntime calls HeaderRegistry.configure.
+ */
+export declare function injectContextFormat(reader: ContextReader): Format;
+/**
+ * Map the winston level onto a top-level `severity` field that the Cloud Logging
+ * agent lifts onto the LogEntry.
+ */
+export declare function severityFormat(): Format;
+/**
+ * Local-only human format: `[loggerName] [requestId=… tenantId=…] level: message { …extra }`.
+ * The registered context keys (already injected by injectContextFormat) render as
+ * a bracketed prefix; anything else the caller attached renders as trailing JSON.
+ * The set of context-key names is read lazily from the registry (first line).
+ */
+export declare function localPrettyFormat(): Format;

package/src/format.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEVEL_TO_SEVERITY = void 0;
+exports.bigIntSafeFormat = bigIntSafeFormat;
+exports.injectContextFormat = injectContextFormat;
+exports.severityFormat = severityFormat;
+exports.localPrettyFormat = localPrettyFormat;
+/**
+ * The winston format layers that turn a raw webpieces log call into a
+ * Cloud-Logging-ready structured record. Ported verbatim (behaviourally) from
+ * the tested-in-GCP logger at
+ * onetablet/monorepo-nx1 libraries/core-context/src/logger/format.ts, with the
+ * one webpieces adaptation: context is read from the webpieces HeaderRegistry +
+ * a ContextReader (rather than a hard-coded PLATFORM_HEADERS enum), so the exact
+ * set of logged fields is whatever the app registered.
+ *
+ * Correlation rides the webpieces magic context (AsyncLocalStorage on the
+ * server, via the ContextReader passed in) — NOT OpenTelemetry / trace-agent, so
+ * nothing here imports a tracing agent.
+ */
+const winston_1 = require("winston");
+const safe_stable_stringify_1 = require("safe-stable-stringify");
+const core_util_1 = require("@webpieces/core-util");
+// winston level → GCP Cloud Logging severity. The Cloud Run / GKE logging agent
+// recognises top-level `severity` in stdout JSON; without this map it falls back
+// to "DEFAULT" which is unfilterable. webpieces `trace` maps onto winston `silly`
+// (see WinstonLogger), so both land at DEBUG severity.
+exports.LEVEL_TO_SEVERITY = {
+    silly: 'DEBUG',
+    verbose: 'DEBUG',
+    debug: 'DEBUG',
+    info: 'INFO',
+    warn: 'WARNING',
+    error: 'ERROR',
+};
+/**
+ * Round-trip the record through safe-stable-stringify so circular references
+ * (HTTP client/response cycles, request/response objects, framework execution
+ * contexts) become "[Circular]" instead of crashing the log emit, and bigints
+ * serialize as strings (JSON.stringify can't, and the bare safe-stringify output
+ * wouldn't round-trip through JSON.parse). Symbol keys winston relies on are
+ * untouched (JSON ignores them), so Object.assign only rewrites string fields.
+ */
+function bigIntSafeFormat() {
+    return (0, winston_1.format)((info) => {
+        return Object.assign(info, JSON.parse(
+        // webpieces-disable no-any-unknown -- safe-stable-stringify's Replacer types the value as unknown
+        (0, safe_stable_stringify_1.stringify)(info, (_key, value) => {
+            if (typeof value === 'bigint') {
+                return value.toString();
+            }
+            return value;
+        })));
+    })();
+}
+/**
+ * Inject every logged HeaderRegistry context key present in the current context
+ * frame into the record under its `name` (→ top-level jsonPayload.<name> in GCP,
+ * filterable as jsonPayload.requestId, jsonPayload.tenantId, …). Secured keys are
+ * masked by HeaderMethods.buildSecureMapForLogs. Caller-supplied fields on the
+ * record win on conflict. Runs on EVERY winston call, including winston's own
+ * handleExceptions/handleRejections lines that bypass the WinstonLogger wrapper.
+ *
+ * The registry is read LAZILY (first log call) because a LoggerFactory is
+ * constructed by the app BEFORE setupRuntime calls HeaderRegistry.configure.
+ */
+function injectContextFormat(reader) {
+    const headerMethods = new core_util_1.HeaderMethods();
+    let loggedKeys;
+    return (0, winston_1.format)((info) => {
+        if (!loggedKeys) {
+            loggedKeys = core_util_1.HeaderRegistry.get().getLoggedKeys();
+        }
+        const logMap = headerMethods.buildSecureMapForLogs(loggedKeys, reader);
+        logMap.forEach((value, name) => {
+            if (info[name] === undefined) {
+                info[name] = value;
+            }
+        });
+        return info;
+    })();
+}
+/**
+ * Map the winston level onto a top-level `severity` field that the Cloud Logging
+ * agent lifts onto the LogEntry.
+ */
+function severityFormat() {
+    return (0, winston_1.format)((info) => {
+        info['severity'] = exports.LEVEL_TO_SEVERITY[info.level] || info.level.toUpperCase();
+        return info;
+    })();
+}
+// Fields that are rendered specially (or not at all) by the local pretty format,
+// so they must not leak into the trailing "extra" JSON blob.
+const LOCAL_STRUCTURAL_KEYS = new Set(['level', 'message', 'severity', 'svcGitHash', 'loggerName']);
+/**
+ * Local-only human format: `[loggerName] [requestId=… tenantId=…] level: message { …extra }`.
+ * The registered context keys (already injected by injectContextFormat) render as
+ * a bracketed prefix; anything else the caller attached renders as trailing JSON.
+ * The set of context-key names is read lazily from the registry (first line).
+ */
+function localPrettyFormat() {
+    let contextNames;
+    return winston_1.format.printf((info) => {
+        if (!contextNames) {
+            contextNames = new Set(core_util_1.HeaderRegistry.get().getLoggedKeys().map((k) => k.name));
+        }
+        const prefixBits = [];
+        for (const name of contextNames) {
+            const value = info[name];
+            if (value != null) {
+                prefixBits.push(`${name}=${String(value)}`);
+            }
+        }
+        const prefix = prefixBits.length ? `[${prefixBits.join(' ')}] ` : '';
+        const loggerName = info['loggerName'] ? `[${String(info['loggerName'])}] ` : '';
+        const rest = {};
+        for (const key of Object.keys(info)) {
+            if (LOCAL_STRUCTURAL_KEYS.has(key) || contextNames.has(key)) {
+                continue;
+            }
+            rest[key] = info[key];
+        }
+        const restStr = Object.keys(rest).length ? ` ${(0, safe_stable_stringify_1.stringify)(rest)}` : '';
+        return `${loggerName}${prefix}${info.level}: ${info.message}${restStr}`;
+    });
+}
+//# sourceMappingURL=format.js.map

package/src/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../../../../packages/logging/winston/src/format.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The winston format layers that turn a raw webpieces log call into a\n * Cloud-Logging-ready structured record. Ported verbatim (behaviourally) from\n * the tested-in-GCP logger at\n * onetablet/monorepo-nx1 libraries/core-context/src/logger/format.ts, with the\n * one webpieces adaptation: context is read from the webpieces HeaderRegistry +\n * a ContextReader (rather than a hard-coded PLATFORM_HEADERS enum), so the exact\n * set of logged fields is whatever the app registered.\n *\n * Correlation rides the webpieces magic context (AsyncLocalStorage on the\n * server, via the ContextReader passed in) — NOT OpenTelemetry / trace-agent, so\n * nothing here imports a tracing agent.\n */\nimport { format } from 'winston';\nimport type { Format, TransformableInfo } from 'logform';\nimport { stringify as safeStringify } from 'safe-stable-stringify';\nimport { HeaderMethods, HeaderRegistry } from '@webpieces/core-util';\nimport type { ContextKey, ContextReader } from '@webpieces/core-util';\n\n// JSON-shaped value (the widest thing a log field / replacer value can hold),\n// used instead of `any`/`unknown` which the code rules disallow.\ntype JsonValue = string | number | boolean | bigint | object | null | undefined;\n\n// winston level → GCP Cloud Logging severity. The Cloud Run / GKE logging agent\n// recognises top-level `severity` in stdout JSON; without this map it falls back\n// to \"DEFAULT\" which is unfilterable. webpieces `trace` maps onto winston `silly`\n// (see WinstonLogger), so both land at DEBUG severity.\nexport const LEVEL_TO_SEVERITY: Record<string, string> = {\n    silly: 'DEBUG',\n    verbose: 'DEBUG',\n    debug: 'DEBUG',\n    info: 'INFO',\n    warn: 'WARNING',\n    error: 'ERROR',\n};\n\n/**\n * Round-trip the record through safe-stable-stringify so circular references\n * (HTTP client/response cycles, request/response objects, framework execution\n * contexts) become \"[Circular]\" instead of crashing the log emit, and bigints\n * serialize as strings (JSON.stringify can't, and the bare safe-stringify output\n * wouldn't round-trip through JSON.parse). Symbol keys winston relies on are\n * untouched (JSON ignores them), so Object.assign only rewrites string fields.\n */\nexport function bigIntSafeFormat(): Format {\n    return format((info: TransformableInfo) => {\n        return Object.assign(\n            info,\n            JSON.parse(\n                // webpieces-disable no-any-unknown -- safe-stable-stringify's Replacer types the value as unknown\n                safeStringify(info, (_key: string, value: unknown) => {\n                    if (typeof value === 'bigint') {\n                        return value.toString();\n                    }\n                    return value;\n                })!,\n            ),\n        );\n    })();\n}\n\n/**\n * Inject every logged HeaderRegistry context key present in the current context\n * frame into the record under its `name` (→ top-level jsonPayload.<name> in GCP,\n * filterable as jsonPayload.requestId, jsonPayload.tenantId, …). Secured keys are\n * masked by HeaderMethods.buildSecureMapForLogs. Caller-supplied fields on the\n * record win on conflict. Runs on EVERY winston call, including winston's own\n * handleExceptions/handleRejections lines that bypass the WinstonLogger wrapper.\n *\n * The registry is read LAZILY (first log call) because a LoggerFactory is\n * constructed by the app BEFORE setupRuntime calls HeaderRegistry.configure.\n */\nexport function injectContextFormat(reader: ContextReader): Format {\n    const headerMethods = new HeaderMethods();\n    let loggedKeys: ContextKey[] | undefined;\n    return format((info: TransformableInfo) => {\n        if (!loggedKeys) {\n            loggedKeys = HeaderRegistry.get().getLoggedKeys();\n        }\n        const logMap = headerMethods.buildSecureMapForLogs(loggedKeys, reader);\n        logMap.forEach((value: string, name: string) => {\n            if (info[name] === undefined) {\n                info[name] = value;\n            }\n        });\n        return info;\n    })();\n}\n\n/**\n * Map the winston level onto a top-level `severity` field that the Cloud Logging\n * agent lifts onto the LogEntry.\n */\nexport function severityFormat(): Format {\n    return format((info: TransformableInfo) => {\n        info['severity'] = LEVEL_TO_SEVERITY[info.level] || info.level.toUpperCase();\n        return info;\n    })();\n}\n\n// Fields that are rendered specially (or not at all) by the local pretty format,\n// so they must not leak into the trailing \"extra\" JSON blob.\nconst LOCAL_STRUCTURAL_KEYS = new Set<string>(['level', 'message', 'severity', 'svcGitHash', 'loggerName']);\n\n/**\n * Local-only human format: `[loggerName] [requestId=… tenantId=…] level: message { …extra }`.\n * The registered context keys (already injected by injectContextFormat) render as\n * a bracketed prefix; anything else the caller attached renders as trailing JSON.\n * The set of context-key names is read lazily from the registry (first line).\n */\nexport function localPrettyFormat(): Format {\n    let contextNames: Set<string> | undefined;\n    return format.printf((info: TransformableInfo) => {\n        if (!contextNames) {\n            contextNames = new Set(HeaderRegistry.get().getLoggedKeys().map((k: ContextKey) => k.name));\n        }\n        const prefixBits: string[] = [];\n        for (const name of contextNames) {\n            const value = info[name];\n            if (value != null) {\n                prefixBits.push(`${name}=${String(value)}`);\n            }\n        }\n        const prefix = prefixBits.length ? `[${prefixBits.join(' ')}] ` : '';\n        const loggerName = info['loggerName'] ? `[${String(info['loggerName'])}] ` : '';\n\n        const rest: Record<string, JsonValue> = {};\n        for (const key of Object.keys(info)) {\n            if (LOCAL_STRUCTURAL_KEYS.has(key) || contextNames.has(key)) {\n                continue;\n            }\n            rest[key] = info[key] as JsonValue;\n        }\n        const restStr = Object.keys(rest).length ? ` ${safeStringify(rest)}` : '';\n\n        return `${loggerName}${prefix}${info.level}: ${info.message}${restStr}`;\n    });\n}\n"]}

package/src/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @webpieces/winston
+ *
+ * Node-only winston {@link LoggerFactory} backends for webpieces. Install one at
+ * startup via `LogManager.setFactory(...)`:
+ *
+ * ```ts
+ * import { WinstonGcpFactory, WinstonConsoleFactory } from '@webpieces/winston';
+ * import { RequestContextReader } from '@webpieces/core-context';
+ *
+ * const reader = new RequestContextReader();
+ * const loggerFactory = process.env.K_SERVICE
+ *   ? new WinstonGcpFactory(reader)      // Cloud Run → stdout JSON
+ *   : new WinstonConsoleFactory(reader); // local → pretty console
+ * // hand to setupRuntime(new RuntimeSetupOptions(loggerFactory, ...))
+ * ```
+ *
+ * Both backends auto-enrich every line with the logged context keys from
+ * HeaderRegistry. This package depends only on @webpieces/core-util (+ winston);
+ * the node RequestContextReader is passed in, not imported.
+ *
+ * @packageDocumentation
+ */
+export { WinstonGcpFactory } from './WinstonGcpFactory';
+export { WinstonConsoleFactory } from './WinstonConsoleFactory';
+export { WinstonFactoryOptions } from './WinstonFactoryOptions';
+export { WinstonLogger, LEVEL_TO_WINSTON } from './WinstonLogger';
+export { LEVEL_TO_SEVERITY, bigIntSafeFormat, injectContextFormat, severityFormat, localPrettyFormat, } from './format';

package/src/index.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localPrettyFormat = exports.severityFormat = exports.injectContextFormat = exports.bigIntSafeFormat = exports.LEVEL_TO_SEVERITY = exports.LEVEL_TO_WINSTON = exports.WinstonLogger = exports.WinstonFactoryOptions = exports.WinstonConsoleFactory = exports.WinstonGcpFactory = void 0;
+/**
+ * @webpieces/winston
+ *
+ * Node-only winston {@link LoggerFactory} backends for webpieces. Install one at
+ * startup via `LogManager.setFactory(...)`:
+ *
+ * ```ts
+ * import { WinstonGcpFactory, WinstonConsoleFactory } from '@webpieces/winston';
+ * import { RequestContextReader } from '@webpieces/core-context';
+ *
+ * const reader = new RequestContextReader();
+ * const loggerFactory = process.env.K_SERVICE
+ *   ? new WinstonGcpFactory(reader)      // Cloud Run → stdout JSON
+ *   : new WinstonConsoleFactory(reader); // local → pretty console
+ * // hand to setupRuntime(new RuntimeSetupOptions(loggerFactory, ...))
+ * ```
+ *
+ * Both backends auto-enrich every line with the logged context keys from
+ * HeaderRegistry. This package depends only on @webpieces/core-util (+ winston);
+ * the node RequestContextReader is passed in, not imported.
+ *
+ * @packageDocumentation
+ */
+var WinstonGcpFactory_1 = require("./WinstonGcpFactory");
+Object.defineProperty(exports, "WinstonGcpFactory", { enumerable: true, get: function () { return WinstonGcpFactory_1.WinstonGcpFactory; } });
+var WinstonConsoleFactory_1 = require("./WinstonConsoleFactory");
+Object.defineProperty(exports, "WinstonConsoleFactory", { enumerable: true, get: function () { return WinstonConsoleFactory_1.WinstonConsoleFactory; } });
+var WinstonFactoryOptions_1 = require("./WinstonFactoryOptions");
+Object.defineProperty(exports, "WinstonFactoryOptions", { enumerable: true, get: function () { return WinstonFactoryOptions_1.WinstonFactoryOptions; } });
+var WinstonLogger_1 = require("./WinstonLogger");
+Object.defineProperty(exports, "WinstonLogger", { enumerable: true, get: function () { return WinstonLogger_1.WinstonLogger; } });
+Object.defineProperty(exports, "LEVEL_TO_WINSTON", { enumerable: true, get: function () { return WinstonLogger_1.LEVEL_TO_WINSTON; } });
+var format_1 = require("./format");
+Object.defineProperty(exports, "LEVEL_TO_SEVERITY", { enumerable: true, get: function () { return format_1.LEVEL_TO_SEVERITY; } });
+Object.defineProperty(exports, "bigIntSafeFormat", { enumerable: true, get: function () { return format_1.bigIntSafeFormat; } });
+Object.defineProperty(exports, "injectContextFormat", { enumerable: true, get: function () { return format_1.injectContextFormat; } });
+Object.defineProperty(exports, "severityFormat", { enumerable: true, get: function () { return format_1.severityFormat; } });
+Object.defineProperty(exports, "localPrettyFormat", { enumerable: true, get: function () { return format_1.localPrettyFormat; } });
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/logging/winston/src/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,yDAAwD;AAA/C,sHAAA,iBAAiB,OAAA;AAC1B,iEAAgE;AAAvD,8HAAA,qBAAqB,OAAA;AAC9B,iEAAgE;AAAvD,8HAAA,qBAAqB,OAAA;AAC9B,iDAAkE;AAAzD,8GAAA,aAAa,OAAA;AAAE,iHAAA,gBAAgB,OAAA;AACxC,mCAMkB;AALd,2GAAA,iBAAiB,OAAA;AACjB,0GAAA,gBAAgB,OAAA;AAChB,6GAAA,mBAAmB,OAAA;AACnB,wGAAA,cAAc,OAAA;AACd,2GAAA,iBAAiB,OAAA","sourcesContent":["/**\n * @webpieces/winston\n *\n * Node-only winston {@link LoggerFactory} backends for webpieces. Install one at\n * startup via `LogManager.setFactory(...)`:\n *\n * ```ts\n * import { WinstonGcpFactory, WinstonConsoleFactory } from '@webpieces/winston';\n * import { RequestContextReader } from '@webpieces/core-context';\n *\n * const reader = new RequestContextReader();\n * const loggerFactory = process.env.K_SERVICE\n *   ? new WinstonGcpFactory(reader)      // Cloud Run → stdout JSON\n *   : new WinstonConsoleFactory(reader); // local → pretty console\n * // hand to setupRuntime(new RuntimeSetupOptions(loggerFactory, ...))\n * ```\n *\n * Both backends auto-enrich every line with the logged context keys from\n * HeaderRegistry. This package depends only on @webpieces/core-util (+ winston);\n * the node RequestContextReader is passed in, not imported.\n *\n * @packageDocumentation\n */\nexport { WinstonGcpFactory } from './WinstonGcpFactory';\nexport { WinstonConsoleFactory } from './WinstonConsoleFactory';\nexport { WinstonFactoryOptions } from './WinstonFactoryOptions';\nexport { WinstonLogger, LEVEL_TO_WINSTON } from './WinstonLogger';\nexport {\n    LEVEL_TO_SEVERITY,\n    bigIntSafeFormat,\n    injectContextFormat,\n    severityFormat,\n    localPrettyFormat,\n} from './format';\n"]}