@nwire/logger 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# @nwire/logger
+
+> Logger contract — interface every Nwire layer logs against, with Noop + Console defaults.
+
+## What it is
+
+A tiny `Logger` interface (`debug` / `info` / `warn` / `error` + `child(bindings)`) so framework code can log without binding to a specific implementation. Ships a silent `NoopLogger` (test default) and a JSON-line `ConsoleLogger` (dev default). Production wires plug in `@nwire/logger-pino` or any structured adapter that conforms.
+
+## Install
+
+```bash
+pnpm add @nwire/logger
+```
+
+## Standalone use
+
+For developers building a library that wants a structured-logging contract without forcing pino/winston on consumers. Code logs against `Logger`; callers inject whichever adapter they want.
+
+```ts
+import { ConsoleLogger, type Logger } from "@nwire/logger";
+
+class CourseService {
+  constructor(private log: Logger) {}
+  async enrol(studentId: string, courseId: string) {
+    this.log.info({ studentId, courseId }, "enrolling");
+    // …
+  }
+}
+
+const svc = new CourseService(new ConsoleLogger({ level: "info" }));
+```
+
+## Within nwire-app
+
+For developers using this package as part of the Nwire stack. `ctx.logger` is already attached per request with envelope ids (`correlationId`, `causationId`, `tenant`, `userId`) bound. Touch this package directly only when implementing a custom adapter.
+
+```ts
+import { loggerForEnvelope, ConsoleLogger } from "@nwire/logger";
+import { seedEnvelope } from "@nwire/envelope";
+
+const root = new ConsoleLogger({ level: "info" });
+const env = seedEnvelope({ source: "http", tenant: "acme" });
+const log = loggerForEnvelope(root, env);
+log.info({ courseId: "c-1" }, "course requested");
+// → {"level":"info","correlationId":"...","tenant":"acme","courseId":"c-1","msg":"course requested"}
+```
+
+## API
+
+- `Logger` — interface every adapter implements.
+- `NoopLogger` — silent default; use in tests.
+- `ConsoleLogger` — JSON-line stdout; use in dev.
+- `loggerForEnvelope(parent, envelope)` — derives a child logger with envelope ids pre-bound.
+
+## See also
+
+- [Architecture sketch §05 — Foundation tier](../../architecture-sketch.html#packages)
+- Sibling packages: [@nwire/logger-pino](../nwire-logger-pino), [@nwire/envelope](../nwire-envelope)

package/dist/logger-iface.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@nwire/logger` — Logger contract + Noop + Console defaults.
+ *
+ *   Logger interface — debug/info/warn/error + child(bindings)
+ *   NoopLogger — silent default
+ *   ConsoleLogger — JSON-line stdout, dev-friendly
+ *   loggerForEnvelope(parent, envelope) — auto-attaches envelope ids
+ *
+ * Production deployments use a structured adapter like `@nwire/logger-pino`.
+ */
+export { NoopLogger, ConsoleLogger, loggerForEnvelope, type Logger } from "./logger.js";
+//# sourceMappingURL=logger-iface.d.ts.map

package/dist/logger-iface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger-iface.d.ts","sourceRoot":"","sources":["../src/logger-iface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,iBAAiB,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC"}

package/dist/logger-iface.js

@@ -0,0 +1,12 @@
+/**
+ * `@nwire/logger` — Logger contract + Noop + Console defaults.
+ *
+ *   Logger interface — debug/info/warn/error + child(bindings)
+ *   NoopLogger — silent default
+ *   ConsoleLogger — JSON-line stdout, dev-friendly
+ *   loggerForEnvelope(parent, envelope) — auto-attaches envelope ids
+ *
+ * Production deployments use a structured adapter like `@nwire/logger-pino`.
+ */
+export { NoopLogger, ConsoleLogger, loggerForEnvelope } from "./logger.js";
+//# sourceMappingURL=logger-iface.js.map

package/dist/logger-iface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger-iface.js","sourceRoot":"","sources":["../src/logger-iface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,iBAAiB,EAAe,MAAM,UAAU,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Minimal `Logger` contract for the runtime.
+ *
+ * The framework auto-attaches envelope ids (`correlationId`, `causationId`,
+ * `messageId`, `tenant`, `userId`) to every log call so domain code never
+ * threads them manually. The contract is small on purpose — wires plug in
+ * pino, winston, console, or a no-op.
+ *
+ * The runtime calls the logger at well-defined checkpoints (dispatch start,
+ * handler error, retry, DLQ, projection lag) — all from a `ctx.logger` that
+ * already has the envelope baked in.
+ */
+import type { MessageEnvelope } from "@nwire/envelope";
+export interface Logger {
+    debug(message: string, fields?: Record<string, unknown>): void;
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+    /** Return a child logger with additional fields baked in. */
+    child(bindings: Record<string, unknown>): Logger;
+}
+/**
+ * No-op logger. Default in `createApp` so the framework never demands a
+ * logger; production wires pass in a real one.
+ */
+export declare class NoopLogger implements Logger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+    child(): Logger;
+}
+/**
+ * Console logger. Simple JSON-line output for dev. Production should pass a
+ * structured logger (pino) instead.
+ */
+export declare class ConsoleLogger implements Logger {
+    private readonly bindings;
+    constructor(bindings?: Record<string, unknown>);
+    private write;
+    debug(m: string, f?: Record<string, unknown>): void;
+    info(m: string, f?: Record<string, unknown>): void;
+    warn(m: string, f?: Record<string, unknown>): void;
+    error(m: string, f?: Record<string, unknown>): void;
+    child(bindings: Record<string, unknown>): Logger;
+}
+/**
+ * Build a child logger with envelope ids baked in. Used by the runtime to
+ * scope every handler/reaction's logger to its own envelope automatically.
+ */
+export declare function loggerForEnvelope(parent: Logger, envelope: MessageEnvelope): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/D,6DAA6D;IAC7D,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;CAClD;AAED;;;GAGG;AACH,qBAAa,UAAW,YAAW,MAAM;IACvC,KAAK,IAAI,IAAI;IACb,IAAI,IAAI,IAAI;IACZ,IAAI,IAAI,IAAI;IACZ,KAAK,IAAI,IAAI;IACb,KAAK,IAAI,MAAM;CAGhB;AAED;;;GAGG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAEnE,OAAO,CAAC,KAAK;IAYb,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAGnD,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAGlD,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAGlD,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAGnD,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;CAGjD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,MAAM,CAQnF"}

package/dist/logger.js

@@ -0,0 +1,75 @@
+/**
+ * Minimal `Logger` contract for the runtime.
+ *
+ * The framework auto-attaches envelope ids (`correlationId`, `causationId`,
+ * `messageId`, `tenant`, `userId`) to every log call so domain code never
+ * threads them manually. The contract is small on purpose — wires plug in
+ * pino, winston, console, or a no-op.
+ *
+ * The runtime calls the logger at well-defined checkpoints (dispatch start,
+ * handler error, retry, DLQ, projection lag) — all from a `ctx.logger` that
+ * already has the envelope baked in.
+ */
+/**
+ * No-op logger. Default in `createApp` so the framework never demands a
+ * logger; production wires pass in a real one.
+ */
+export class NoopLogger {
+    debug() { }
+    info() { }
+    warn() { }
+    error() { }
+    child() {
+        return this;
+    }
+}
+/**
+ * Console logger. Simple JSON-line output for dev. Production should pass a
+ * structured logger (pino) instead.
+ */
+export class ConsoleLogger {
+    bindings;
+    constructor(bindings = {}) {
+        this.bindings = bindings;
+    }
+    write(level, message, fields) {
+        const line = {
+            level,
+            message,
+            ts: new Date().toISOString(),
+            ...this.bindings,
+            ...(fields ?? {}),
+        };
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify(line));
+    }
+    debug(m, f) {
+        this.write("debug", m, f);
+    }
+    info(m, f) {
+        this.write("info", m, f);
+    }
+    warn(m, f) {
+        this.write("warn", m, f);
+    }
+    error(m, f) {
+        this.write("error", m, f);
+    }
+    child(bindings) {
+        return new ConsoleLogger({ ...this.bindings, ...bindings });
+    }
+}
+/**
+ * Build a child logger with envelope ids baked in. Used by the runtime to
+ * scope every handler/reaction's logger to its own envelope automatically.
+ */
+export function loggerForEnvelope(parent, envelope) {
+    return parent.child({
+        messageId: envelope.messageId,
+        correlationId: envelope.correlationId,
+        causationId: envelope.causationId,
+        ...(envelope.tenant ? { tenant: envelope.tenant } : {}),
+        ...(envelope.userId ? { userId: envelope.userId } : {}),
+    });
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAaH;;;GAGG;AACH,MAAM,OAAO,UAAU;IACrB,KAAK,KAAU,CAAC;IAChB,IAAI,KAAU,CAAC;IACf,IAAI,KAAU,CAAC;IACf,KAAK,KAAU,CAAC;IAChB,KAAK;QACH,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,WAAoC,EAAE;QAAtC,aAAQ,GAAR,QAAQ,CAA8B;IAAG,CAAC;IAE/D,KAAK,CAAC,KAAa,EAAE,OAAe,EAAE,MAAgC;QAC5E,MAAM,IAAI,GAAG;YACX,KAAK;YACL,OAAO;YACP,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC5B,GAAG,IAAI,CAAC,QAAQ;YAChB,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC;SAClB,CAAC;QACF,sCAAsC;QACtC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,CAAS,EAAE,CAA2B;QAC1C,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5B,CAAC;IACD,IAAI,CAAC,CAAS,EAAE,CAA2B;QACzC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,CAAC,CAAS,EAAE,CAA2B;QACzC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3B,CAAC;IACD,KAAK,CAAC,CAAS,EAAE,CAA2B;QAC1C,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5B,CAAC;IACD,KAAK,CAAC,QAAiC;QACrC,OAAO,IAAI,aAAa,CAAC,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;IAC9D,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,QAAyB;IACzE,OAAO,MAAM,CAAC,KAAK,CAAC;QAClB,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,aAAa,EAAE,QAAQ,CAAC,aAAa;QACrC,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxD,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@nwire/logger",
+  "version": "0.7.0",
+  "description": "Nwire — Logger contract + Noop + Console defaults. Production adapters: @nwire/logger-pino, @nwire/logger-winston. Envelope ids auto-attached via loggerForEnvelope.",
+  "keywords": [
+    "log",
+    "logger",
+    "nwire",
+    "observability"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/logger-iface.js",
+  "types": "./dist/logger-iface.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/logger-iface.js",
+      "types": "./dist/logger-iface.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nwire/envelope": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}