@viktorbarzin/log 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @viktorbarzin/log
 
-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 JSON-lines logger for the platform's log contract: one object per line on
+stderr with `ts` (Python `isoformat`, `+00:00`), `level`, `logger`, `msg`,
+then the call's extras (which never overwrite those four keys), then `exc`
+for an error. No dependencies; works on Bun and Node.
+
+<!-- typecheck-preamble
+declare const err: unknown;
+-->
+```ts
+import { getLogger, installJsonConsole } from "@viktorbarzin/log";
+
+const log = getLogger("myapp.sync");
+log.info("sync served", { user: "someone", lists: 3 });
+log.exception("sync failed", err, { path: "/api/sync" });
+
+installJsonConsole(); // console.* from the framework becomes JSON lines too (logger "console")
+```
+
+```json
+{"ts":"2026-10-16T04:05:06.789000+00:00","level":"INFO","logger":"myapp.sync","msg":"sync served","user":"someone","lists":3}
+```
+
+## API
+
+| Export | |
+|---|---|
+| `getLogger(name)` | `debug`, `info`, `warning`, `error`, `exception(msg, err, extra?)`, `record(level, msg, extra?, err?)` |
+| `parseLogLevel(raw)` | `WARN` → `WARNING`; unknown or unset → `INFO` |
+| `setLogLevel(level)` | the threshold; starts from `LOG_LEVEL` |
+| `setLogSink(sink)` | send lines elsewhere (tests); returns a restore function |
+| `installJsonConsole(target?)` | route `console.*` through the logger; an `Error` argument goes under `exc`; returns a restore function |
+| `formatRecord`, `pythonIsoTimestamp` | the formatting, exported for tests |
+
+The sink and threshold are one per process (kept on `globalThis`), so a
+server bundled twice still logs through one sink. `LOG_LEVEL` is the only
+environment variable read.

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+export type LogLevel = "DEBUG" | "INFO" | "WARNING" | "ERROR";
+export type LogExtra = Record<string, unknown>;
+export type LogSink = (line: string) => void;
+/** `WARN` means WARNING; anything unknown or unset is INFO. */
+export declare function parseLogLevel(raw: string | undefined): LogLevel;
+/** Python's `datetime.isoformat()` for an aware UTC datetime: `...T04:05:06.789000+00:00`. */
+export declare function pythonIsoTimestamp(date: Date): string;
+/** Send lines somewhere other than stderr (tests). Returns a restore function. */
+export declare function setLogSink(sink: LogSink): () => void;
+export declare function setLogLevel(level: LogLevel): void;
+export declare function formatRecord(level: LogLevel, logger: string, msg: string, extra?: LogExtra, err?: unknown, now?: Date): string;
+export interface Logger {
+    debug(msg: string, extra?: LogExtra): void;
+    info(msg: string, extra?: LogExtra): void;
+    warning(msg: string, extra?: LogExtra): void;
+    error(msg: string, extra?: LogExtra): void;
+    /** ERROR with the error's stack under `exc`, like Python's logger.exception. */
+    exception(msg: string, err: unknown, extra?: LogExtra): void;
+    /** Any level, with an optional error under `exc`. */
+    record(level: LogLevel, msg: string, extra?: LogExtra, err?: unknown): void;
+}
+export declare function getLogger(name: string): Logger;
+/**
+ * Route console.* through the JSON-lines logger (logger "console"), so the
+ * framework's own output (Nitro's error handler, srvx's banner, uncaught
+ * errors) is JSON lines too. An Error argument goes under `exc` with its
+ * stack, as one line. Returns a function that puts the old methods back.
+ */
+export declare function installJsonConsole(target?: Console): () => void;

package/dist/index.js

@@ -0,0 +1,134 @@
+/**
+ * JSON-lines logging, the platform's log contract: one JSON object per line
+ * on stderr with `ts` (Python isoformat, `+00:00`), `level`, `logger`, `msg`,
+ * then the extras passed at the call site, then `exc` for an error. Extras
+ * never overwrite the four standard keys. Loki and the dashboards parse this
+ * shape.
+ *
+ * The sink and threshold are one per process, kept on globalThis: a server
+ * bundled twice (Nitro's entry plus Start's SSR graph) still has one of each.
+ * The initial threshold comes from LOG_LEVEL, the only variable read here.
+ */
+import { format } from "node:util";
+const LEVEL_RANK = {
+    DEBUG: 10,
+    INFO: 20,
+    WARNING: 30,
+    ERROR: 40,
+};
+/** `WARN` means WARNING; anything unknown or unset is INFO. */
+export function parseLogLevel(raw) {
+    const upper = (raw ?? "").trim().toUpperCase();
+    if (upper === "WARN")
+        return "WARNING";
+    return upper in LEVEL_RANK ? upper : "INFO";
+}
+function state() {
+    const store = globalThis;
+    const slot = Symbol.for("@viktorbarzin:log");
+    let found = store[slot];
+    if (found === undefined) {
+        found = {
+            sink: (line) => {
+                process.stderr.write(`${line}\n`);
+            },
+            threshold: LEVEL_RANK[parseLogLevel(process.env.LOG_LEVEL)],
+        };
+        store[slot] = found;
+    }
+    return found;
+}
+/** Python's `datetime.isoformat()` for an aware UTC datetime: `...T04:05:06.789000+00:00`. */
+export function pythonIsoTimestamp(date) {
+    return date.toISOString().replace("Z", "000+00:00");
+}
+/** Send lines somewhere other than stderr (tests). Returns a restore function. */
+export function setLogSink(sink) {
+    const current = state();
+    const previous = current.sink;
+    current.sink = sink;
+    return () => {
+        current.sink = previous;
+    };
+}
+export function setLogLevel(level) {
+    state().threshold = LEVEL_RANK[level];
+}
+function jsonReplacer(_key, value) {
+    // Python's json.dumps(default=str) stringifies what JSON cannot carry.
+    if (typeof value === "bigint")
+        return value.toString();
+    if (value instanceof Error)
+        return String(value);
+    return value;
+}
+function formatError(err) {
+    if (err instanceof Error)
+        return err.stack ?? `${err.name}: ${err.message}`;
+    return String(err);
+}
+export function formatRecord(level, logger, msg, extra, err, now = new Date()) {
+    const payload = {
+        ts: pythonIsoTimestamp(now),
+        level,
+        logger,
+        msg,
+    };
+    if (extra) {
+        for (const [key, value] of Object.entries(extra)) {
+            if (!(key in payload))
+                payload[key] = value;
+        }
+    }
+    if (err !== undefined)
+        payload.exc = formatError(err);
+    return JSON.stringify(payload, jsonReplacer);
+}
+export function getLogger(name) {
+    const emit = (level, msg, extra, err) => {
+        const current = state();
+        if (LEVEL_RANK[level] < current.threshold)
+            return;
+        current.sink(formatRecord(level, name, msg, extra, err));
+    };
+    return {
+        debug: (msg, extra) => emit("DEBUG", msg, extra),
+        info: (msg, extra) => emit("INFO", msg, extra),
+        warning: (msg, extra) => emit("WARNING", msg, extra),
+        error: (msg, extra) => emit("ERROR", msg, extra),
+        exception: (msg, err, extra) => emit("ERROR", msg, extra, err),
+        record: emit,
+    };
+}
+const CONSOLE_LEVELS = {
+    error: "ERROR",
+    warn: "WARNING",
+    log: "INFO",
+    info: "INFO",
+    debug: "DEBUG",
+    trace: "DEBUG",
+};
+/**
+ * Route console.* through the JSON-lines logger (logger "console"), so the
+ * framework's own output (Nitro's error handler, srvx's banner, uncaught
+ * errors) is JSON lines too. An Error argument goes under `exc` with its
+ * stack, as one line. Returns a function that puts the old methods back.
+ */
+export function installJsonConsole(target = console) {
+    const consoleLog = getLogger("console");
+    const methods = target;
+    const saved = new Map();
+    for (const [method, level] of Object.entries(CONSOLE_LEVELS)) {
+        saved.set(method, methods[method]);
+        methods[method] = (...args) => {
+            const err = args.find((arg) => arg instanceof Error);
+            const rest = args.filter((arg) => arg !== err);
+            const msg = rest.length > 0 ? format(...rest) : err ? String(err) : "";
+            consoleLog.record(level, msg, undefined, err);
+        };
+    }
+    return () => {
+        for (const [method, fn] of saved)
+            methods[method] = fn;
+    };
+}

package/package.json

@@ -1,6 +1,36 @@
 {
-  "name": "@viktorbarzin/log",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@viktorbarzin/log",
+	"version": "0.1.0",
+	"description": "JSON-lines logger for the homelab app platform: ts, level, logger, msg, extras, exc.",
+	"license": "MIT",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"sideEffects": false,
+	"engines": {
+		"bun": ">=1.4.3"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ViktorBarzin/app-kit.git",
+		"directory": "packages/log"
+	},
+	"homepage": "https://github.com/ViktorBarzin/app-kit/tree/master/packages/log#readme",
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"build": "tsc -b",
+		"test": "bun test"
+	}
+}