@blixis-io/logging 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Voeten
+
+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

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# `@blixis-io/logging`
 
-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.
+A multi-transport logger, injectable like any other provider. Doesn't depend on `@blixis-io/http` — usable in any app, HTTP or not.
+
+```bash
+npm install @blixis-io/logging @blixis-io/core @blixis-io/di
+```
+
+```ts
+import { createLogger, consoleTransport } from "@blixis-io/logging";
+
+const logger = createLogger({
+  transports: [consoleTransport()],
+});
+
+logger.info("post created", { postId: post.id });
+logger.error("save failed", { error: err, postId: post.id });
+```
+
+Every log entry fans out to every configured transport at once — each with its own independent `minLevel` — instead of one swappable backend. A real app usually wants console *and* an error tracker *and* maybe a Slack ping, simultaneously.
+
+Part of [Blixis Framework](https://github.com/blixis-io/framework) — full docs: [Logging](https://blixis-io.github.io/framework/concepts/logging/) · [API reference](https://blixis-io.github.io/framework/reference/blixis-logging/).

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+import { DynamicModule } from "@blixis-io/core";
+import { InjectionToken } from "@blixis-io/di";
+//#region src/levels.d.ts
+export declare const LOG_LEVELS: readonly ["trace", "debug", "info", "warn", "error", "fatal"];
+type LogLevel = (typeof LOG_LEVELS)[number];
+export declare function levelSeverity(level: LogLevel): number;
+export declare function isLevelEnabled(level: LogLevel, minLevel: LogLevel): boolean;
+//#endregion
+//#region src/types.d.ts
+interface LogRecord {
+  readonly level: LogLevel;
+  readonly message: string;
+  readonly timestamp: string;
+  /**
+   * Structured metadata bound to this entry. An attached `Error` goes under
+   * the `error` key by convention — transports that care (Sentry, etc.)
+   * look for it there rather than a dedicated parameter, so every level
+   * keeps the same `(message, context?)` signature.
+   */
+  readonly context: Readonly<Record<string, unknown>>;
+}
+/**
+ * A log destination. `log()` may be async (a network call to Sentry/Slack/
+ * Logstash); `createLogger()` never awaits it — a slow or failing transport
+ * must never block or crash the caller of `logger.info(...)`.
+ */
+interface Transport {
+  /** Entries below this level are never passed to `log()`. Default: `"trace"` (everything). */
+  minLevel?: LogLevel | undefined;
+  log(record: LogRecord): void | Promise<void>;
+}
+interface Logger {
+  trace(message: string, context?: Record<string, unknown>): void;
+  debug(message: string, context?: Record<string, unknown>): void;
+  info(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>): void;
+  fatal(message: string, context?: Record<string, unknown>): void;
+  /** A logger that merges `context` into every entry's context, on top of this logger's own bound context. */
+  child(context: Record<string, unknown>): Logger;
+}
+//#endregion
+//#region src/logger.d.ts
+interface CreateLoggerOptions {
+  transports: Transport[];
+  /** Floor below which nothing reaches any transport, regardless of each transport's own minLevel. Default: `"trace"`. */
+  minLevel?: LogLevel;
+  /** Bound context merged into every entry; extend per call-site with the second argument, or scope it with `child()`. */
+  context?: Record<string, unknown>;
+}
+/** Builds a `Logger` that fans every entry out to each transport (filtered by that transport's own `minLevel`), never awaiting or letting a transport failure propagate. */
+export declare function createLogger(options: CreateLoggerOptions): Logger;
+//#endregion
+//#region src/module.d.ts
+export declare const LOGGER: InjectionToken<Logger>;
+/**
+ * `LoggerModule.forRoot({ transports: [...] })` builds one `Logger` and
+ * provides it under `LOGGER` for the whole app to `@Inject`. `global: true`
+ * so every module can inject it without also having to import
+ * `LoggerModule` itself — logging is cross-cutting infra, not a feature
+ * dependency.
+ */
+export declare class LoggerModule {
+  static forRoot(options: CreateLoggerOptions): DynamicModule;
+}
+//#endregion
+//#region src/transports/console.d.ts
+interface ConsoleTransportOptions {
+  minLevel?: LogLevel;
+  /** Write each record as one JSON line instead of a human-readable one — friendlier to log aggregators. Default: `false`. */
+  json?: boolean;
+}
+/** The default transport: writes to `console`, routed by level (`fatal` also goes to `console.error`, there's no more-severe console method). */
+export declare function consoleTransport(options?: ConsoleTransportOptions): Transport;
+//#endregion
+export type { ConsoleTransportOptions, CreateLoggerOptions, LogLevel, LogRecord, Logger, Transport };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/levels.ts","../src/types.ts","../src/logger.ts","../src/module.ts","../src/transports/console.ts"],"mappings":";;;qBAAa;KAED,mBAAmB;wBAEf,cAAc,OAAO;wBAIrB,eAAe,OAAO,UAAU,UAAU;;;UCNzC;WACN,OAAO;WACP;WACA;;;;;;;WAOA,SAAS,SAAS;;;;;;;UAQZ;;EAEf,WAAW;EACX,IAAI,QAAQ,mBAAmB;;UAGhB;EACf,MAAM,iBAAiB,UAAU;EACjC,MAAM,iBAAiB,UAAU;EACjC,KAAK,iBAAiB,UAAU;EAChC,KAAK,iBAAiB,UAAU;EAChC,MAAM,iBAAiB,UAAU;EACjC,MAAM,iBAAiB,UAAU;;EAEjC,MAAM,SAAS,0BAA0B;;;;UC/B1B;EACf,YAAY;;EAEZ,WAAW;;EAEX,UAAU;;;wBA0DI,aAAa,SAAS,sBAAsB;;;qBC7D/C,QAAM,eAAA;;;;;;;;qBAUN;SACJ,QAAQ,SAAS,sBAAsB;;;;UCb/B;EACf,WAAW;;EAEX;;;wBAkBc,iBAAiB,UAAS,0BAA+B"}

package/dist/index.js

@@ -0,0 +1,119 @@
+import { Module } from "@blixis-io/core";
+import { InjectionToken } from "@blixis-io/di";
+//#region src/levels.ts
+const LOG_LEVELS = [
+	"trace",
+	"debug",
+	"info",
+	"warn",
+	"error",
+	"fatal"
+];
+function levelSeverity(level) {
+	return LOG_LEVELS.indexOf(level);
+}
+function isLevelEnabled(level, minLevel) {
+	return levelSeverity(level) >= levelSeverity(minLevel);
+}
+//#endregion
+//#region src/logger.ts
+const DEFAULT_MIN_LEVEL = "trace";
+function reportTransportFailure(error) {
+	console.error("[@blixis-io/logging] a transport failed:", error);
+}
+function emit(transports, globalMinLevel, level, message, context) {
+	if (!isLevelEnabled(level, globalMinLevel)) return;
+	const record = {
+		level,
+		message,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		context
+	};
+	for (const transport of transports) {
+		if (!isLevelEnabled(level, transport.minLevel ?? DEFAULT_MIN_LEVEL)) continue;
+		try {
+			const result = transport.log(record);
+			if (result instanceof Promise) result.catch(reportTransportFailure);
+		} catch (error) {
+			reportTransportFailure(error);
+		}
+	}
+}
+function buildLogger(transports, globalMinLevel, boundContext) {
+	const log = (level) => (message, context = {}) => {
+		emit(transports, globalMinLevel, level, message, {
+			...boundContext,
+			...context
+		});
+	};
+	return {
+		trace: log("trace"),
+		debug: log("debug"),
+		info: log("info"),
+		warn: log("warn"),
+		error: log("error"),
+		fatal: log("fatal"),
+		child: (context) => buildLogger(transports, globalMinLevel, {
+			...boundContext,
+			...context
+		})
+	};
+}
+/** Builds a `Logger` that fans every entry out to each transport (filtered by that transport's own `minLevel`), never awaiting or letting a transport failure propagate. */
+function createLogger(options) {
+	return buildLogger(options.transports, options.minLevel ?? DEFAULT_MIN_LEVEL, options.context ?? {});
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.151.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/module.ts
+var _LoggerModule;
+const LOGGER = new InjectionToken("blixis.logger");
+let LoggerModule = _LoggerModule = class LoggerModule {
+	static forRoot(options) {
+		return {
+			module: _LoggerModule,
+			providers: [{
+				provide: LOGGER,
+				useFactory: () => createLogger(options)
+			}],
+			exports: [LOGGER],
+			global: true
+		};
+	}
+};
+LoggerModule = _LoggerModule = __decorate([Module()], LoggerModule);
+//#endregion
+//#region src/transports/console.ts
+const CONSOLE_METHOD = {
+	trace: "log",
+	debug: "debug",
+	info: "info",
+	warn: "warn",
+	error: "error",
+	fatal: "error"
+};
+function formatHuman(record) {
+	const base = `${record.timestamp} ${record.level.toUpperCase()} ${record.message}`;
+	return Object.keys(record.context).length > 0 ? `${base} ${JSON.stringify(record.context)}` : base;
+}
+/** The default transport: writes to `console`, routed by level (`fatal` also goes to `console.error`, there's no more-severe console method). */
+function consoleTransport(options = {}) {
+	return {
+		minLevel: options.minLevel,
+		log(record) {
+			const line = options.json ? JSON.stringify(record) : formatHuman(record);
+			console[CONSOLE_METHOD[record.level]](line);
+		}
+	};
+}
+//#endregion
+export { LOGGER, LOG_LEVELS, LoggerModule, consoleTransport, createLogger, isLevelEnabled, levelSeverity };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/levels.ts","../src/logger.ts","../src/module.ts","../src/transports/console.ts"],"sourcesContent":["export const LOG_LEVELS = [\"trace\", \"debug\", \"info\", \"warn\", \"error\", \"fatal\"] as const;\n\nexport type LogLevel = (typeof LOG_LEVELS)[number];\n\nexport function levelSeverity(level: LogLevel): number {\n  return LOG_LEVELS.indexOf(level);\n}\n\nexport function isLevelEnabled(level: LogLevel, minLevel: LogLevel): boolean {\n  return levelSeverity(level) >= levelSeverity(minLevel);\n}\n","import { isLevelEnabled, type LogLevel } from \"./levels.js\";\nimport type { Logger, LogRecord, Transport } from \"./types.js\";\n\nexport interface CreateLoggerOptions {\n  transports: Transport[];\n  /** Floor below which nothing reaches any transport, regardless of each transport's own minLevel. Default: `\"trace\"`. */\n  minLevel?: LogLevel;\n  /** Bound context merged into every entry; extend per call-site with the second argument, or scope it with `child()`. */\n  context?: Record<string, unknown>;\n}\n\nconst DEFAULT_MIN_LEVEL: LogLevel = \"trace\";\n\nfunction reportTransportFailure(error: unknown): void {\n  // The one place this package uses console directly: a transport failing\n  // must never crash or silently swallow the caller's own logging.\n  console.error(\"[@blixis-io/logging] a transport failed:\", error);\n}\n\nfunction emit(\n  transports: readonly Transport[],\n  globalMinLevel: LogLevel,\n  level: LogLevel,\n  message: string,\n  context: Record<string, unknown>,\n): void {\n  if (!isLevelEnabled(level, globalMinLevel)) {\n    return;\n  }\n\n  const record: LogRecord = { level, message, timestamp: new Date().toISOString(), context };\n\n  for (const transport of transports) {\n    if (!isLevelEnabled(level, transport.minLevel ?? DEFAULT_MIN_LEVEL)) {\n      continue;\n    }\n    try {\n      const result = transport.log(record);\n      if (result instanceof Promise) {\n        result.catch(reportTransportFailure);\n      }\n    } catch (error) {\n      reportTransportFailure(error);\n    }\n  }\n}\n\nfunction buildLogger(transports: readonly Transport[], globalMinLevel: LogLevel, boundContext: Record<string, unknown>): Logger {\n  const log =\n    (level: LogLevel) =>\n    (message: string, context: Record<string, unknown> = {}): void => {\n      emit(transports, globalMinLevel, level, message, { ...boundContext, ...context });\n    };\n\n  return {\n    trace: log(\"trace\"),\n    debug: log(\"debug\"),\n    info: log(\"info\"),\n    warn: log(\"warn\"),\n    error: log(\"error\"),\n    fatal: log(\"fatal\"),\n    child: (context) => buildLogger(transports, globalMinLevel, { ...boundContext, ...context }),\n  };\n}\n\n/** Builds a `Logger` that fans every entry out to each transport (filtered by that transport's own `minLevel`), never awaiting or letting a transport failure propagate. */\nexport function createLogger(options: CreateLoggerOptions): Logger {\n  return buildLogger(options.transports, options.minLevel ?? DEFAULT_MIN_LEVEL, options.context ?? {});\n}\n","import { Module, type DynamicModule } from \"@blixis-io/core\";\nimport { InjectionToken } from \"@blixis-io/di\";\nimport { createLogger, type CreateLoggerOptions } from \"./logger.js\";\nimport type { Logger } from \"./types.js\";\n\nexport const LOGGER = new InjectionToken<Logger>(\"blixis.logger\");\n\n/**\n * `LoggerModule.forRoot({ transports: [...] })` builds one `Logger` and\n * provides it under `LOGGER` for the whole app to `@Inject`. `global: true`\n * so every module can inject it without also having to import\n * `LoggerModule` itself — logging is cross-cutting infra, not a feature\n * dependency.\n */\n@Module()\nexport class LoggerModule {\n  static forRoot(options: CreateLoggerOptions): DynamicModule {\n    return {\n      module: LoggerModule,\n      providers: [{ provide: LOGGER, useFactory: () => createLogger(options) }],\n      exports: [LOGGER],\n      global: true,\n    };\n  }\n}\n","import type { LogLevel } from \"../levels.js\";\nimport type { LogRecord, Transport } from \"../types.js\";\n\nexport interface ConsoleTransportOptions {\n  minLevel?: LogLevel;\n  /** Write each record as one JSON line instead of a human-readable one — friendlier to log aggregators. Default: `false`. */\n  json?: boolean;\n}\n\nconst CONSOLE_METHOD = {\n  trace: \"log\",\n  debug: \"debug\",\n  info: \"info\",\n  warn: \"warn\",\n  error: \"error\",\n  fatal: \"error\",\n} as const satisfies Record<LogLevel, \"log\" | \"debug\" | \"info\" | \"warn\" | \"error\">;\n\nfunction formatHuman(record: LogRecord): string {\n  const base = `${record.timestamp} ${record.level.toUpperCase()} ${record.message}`;\n  return Object.keys(record.context).length > 0 ? `${base} ${JSON.stringify(record.context)}` : base;\n}\n\n/** The default transport: writes to `console`, routed by level (`fatal` also goes to `console.error`, there's no more-severe console method). */\nexport function consoleTransport(options: ConsoleTransportOptions = {}): Transport {\n  return {\n    minLevel: options.minLevel,\n    log(record) {\n      const line = options.json ? JSON.stringify(record) : formatHuman(record);\n      console[CONSOLE_METHOD[record.level]](line);\n    },\n  };\n}\n"],"mappings":";;;AAAA,MAAa,aAAa;CAAC;CAAS;CAAS;CAAQ;CAAQ;CAAS;AAAO;AAI7E,SAAgB,cAAc,OAAyB;CACrD,OAAO,WAAW,QAAQ,KAAK;AACjC;AAEA,SAAgB,eAAe,OAAiB,UAA6B;CAC3E,OAAO,cAAc,KAAK,KAAK,cAAc,QAAQ;AACvD;;;ACCA,MAAM,oBAA8B;AAEpC,SAAS,uBAAuB,OAAsB;CAGpD,QAAQ,MAAM,4CAA4C,KAAK;AACjE;AAEA,SAAS,KACP,YACA,gBACA,OACA,SACA,SACM;CACN,IAAI,CAAC,eAAe,OAAO,cAAc,GACvC;CAGF,MAAM,SAAoB;EAAE;EAAO;EAAS,4BAAW,IAAI,KAAK,EAAA,CAAE,YAAY;EAAG;CAAQ;CAEzF,KAAK,MAAM,aAAa,YAAY;EAClC,IAAI,CAAC,eAAe,OAAO,UAAU,YAAY,iBAAiB,GAChE;EAEF,IAAI;GACF,MAAM,SAAS,UAAU,IAAI,MAAM;GACnC,IAAI,kBAAkB,SACpB,OAAO,MAAM,sBAAsB;EAEvC,SAAS,OAAO;GACd,uBAAuB,KAAK;EAC9B;CACF;AACF;AAEA,SAAS,YAAY,YAAkC,gBAA0B,cAA+C;CAC9H,MAAM,OACH,WACA,SAAiB,UAAmC,CAAC,MAAY;EAChE,KAAK,YAAY,gBAAgB,OAAO,SAAS;GAAE,GAAG;GAAc,GAAG;EAAQ,CAAC;CAClF;CAEF,OAAO;EACL,OAAO,IAAI,OAAO;EAClB,OAAO,IAAI,OAAO;EAClB,MAAM,IAAI,MAAM;EAChB,MAAM,IAAI,MAAM;EAChB,OAAO,IAAI,OAAO;EAClB,OAAO,IAAI,OAAO;EAClB,QAAQ,YAAY,YAAY,YAAY,gBAAgB;GAAE,GAAG;GAAc,GAAG;EAAQ,CAAC;CAC7F;AACF;;AAGA,SAAgB,aAAa,SAAsC;CACjE,OAAO,YAAY,QAAQ,YAAY,QAAQ,YAAY,mBAAmB,QAAQ,WAAW,CAAC,CAAC;AACrG;;;;;;;;;;;;AC/DA,MAAa,SAAS,IAAI,eAAuB,eAAe;AAUzD,IAAM,eAAA,gBAAN,MAAM,aAAa;CACxB,OAAO,QAAQ,SAA6C;EAC1D,OAAO;GACL,QAAA;GACA,WAAW,CAAC;IAAE,SAAS;IAAQ,kBAAkB,aAAa,OAAO;GAAE,CAAC;GACxE,SAAS,CAAC,MAAM;GAChB,QAAQ;EACV;CACF;AACF;AAVC,eAAA,gBAAA,WAAA,CAAA,OAAO,CAAA,GAAA,YAAA;;;ACLR,MAAM,iBAAiB;CACrB,OAAO;CACP,OAAO;CACP,MAAM;CACN,MAAM;CACN,OAAO;CACP,OAAO;AACT;AAEA,SAAS,YAAY,QAA2B;CAC9C,MAAM,OAAO,GAAG,OAAO,UAAU,GAAG,OAAO,MAAM,YAAY,EAAE,GAAG,OAAO;CACzE,OAAO,OAAO,KAAK,OAAO,OAAO,CAAC,CAAC,SAAS,IAAI,GAAG,KAAK,GAAG,KAAK,UAAU,OAAO,OAAO,MAAM;AAChG;;AAGA,SAAgB,iBAAiB,UAAmC,CAAC,GAAc;CACjF,OAAO;EACL,UAAU,QAAQ;EAClB,IAAI,QAAQ;GACV,MAAM,OAAO,QAAQ,OAAO,KAAK,UAAU,MAAM,IAAI,YAAY,MAAM;GACvE,QAAQ,eAAe,OAAO,OAAO,CAAC,IAAI;EAC5C;CACF;AACF"}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@blixis-io/logging",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "A multi-transport logger, injectable like any other provider. Doesn't depend on @blixis-io/http — usable in any app, HTTP or not.",
+  "license": "MIT",
+  "author": "Michael Voeten <michael@voeten.online>",
+  "homepage": "https://blixis-io.github.io/framework/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blixis-io/framework.git",
+    "directory": "packages/logging"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "keywords": [
+    "logging",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "@blixis-io/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@blixis-io/core": "0.1.0",
+    "@blixis-io/di": "0.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "rolldown -c"
+  }
 }