@decohere/scribe 0.0.1-dev.119 → 0.0.1-dev.120

package/commonjs/src/console.adapter.js

@@ -28,13 +28,16 @@ class ConsoleAdapter extends _loggeradapter.LogAdapter {
     }
     getLogger(name) {
         const loggerName = name || "default";
-        return this.createConsoleLogger(loggerName);
+        return this.createConsoleLogger(loggerName, {});
     }
-    createConsoleLogger(name) {
+    createConsoleLogger(name, bindings) {
         const allLevels = this.configuredLevels;
         const currentLevel = this.configuredLogLevel;
         const threshold = this.configuredLogLevelValue;
         const redactionKeys = this.redactionKeys;
+        const bound = Object.keys(bindings).length > 0 ? [
+            _redact.redact.object(bindings, redactionKeys)
+        ] : [];
         const baseLogger = {
             get currentLevel () {
                 return currentLevel;
@@ -52,7 +55,10 @@ class ConsoleAdapter extends _loggeradapter.LogAdapter {
                     message = String(msg);
                 }
                 const logLine = `[${timestamp}] ${level.toUpperCase()} [${name}]: ${message}`;
-                const payload = args.map((arg)=>_redact.redact.object(arg, redactionKeys));
+                const payload = [
+                    ...args.map((arg)=>_redact.redact.object(arg, redactionKeys)),
+                    ...bound
+                ];
                 if (payload.length > 0) {
                     console.log(logLine, ...payload);
                 } else {
@@ -61,7 +67,11 @@ class ConsoleAdapter extends _loggeradapter.LogAdapter {
             };
         const noop = ()=>{};
         const logger = Object.assign(baseLogger, {
-            isLevelEnabled: (level)=>(allLevels[level] ?? 0) >= threshold
+            isLevelEnabled: (level)=>(allLevels[level] ?? 0) >= threshold,
+            child: (fields)=>this.createConsoleLogger(name, {
+                    ...bindings,
+                    ...fields
+                })
         });
         for (const [levelName, levelValue] of Object.entries(allLevels)){
             logger[levelName] = levelValue >= threshold ? logFunction(levelName) : noop;

package/commonjs/src/env.js

@@ -39,8 +39,9 @@ const VALID_LEVELS = [
     "trace"
 ];
 function getLogLevelFromEnv() {
+    const env = globalThis.process?.env;
     for (const name of ENV_VAR_NAMES){
-        const value = process.env[name]?.trim().toLowerCase();
+        const value = env?.[name]?.trim().toLowerCase();
         if (value) {
             return value;
         }

package/commonjs/src/index.js

@@ -5,6 +5,8 @@ Object.defineProperty(exports, "__esModule", {
 _export_star(require("./console.adapter.js"), exports);
 _export_star(require("./env.js"), exports);
 _export_star(require("./errors.js"), exports);
+_export_star(require("./log-entry.adapter.js"), exports);
+_export_star(require("./log-entry.js"), exports);
 _export_star(require("./logger.adapter.js"), exports);
 _export_star(require("./logger.factory.js"), exports);
 _export_star(require("./logger.type.js"), exports);

package/commonjs/src/log-entry.adapter.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "LogEntryAdapter", {
+    enumerable: true,
+    get: function() {
+        return LogEntryAdapter;
+    }
+});
+const _logentry = require("./log-entry.js");
+const _loggeradapter = require("./logger.adapter.js");
+const _redact = require("./redact.js");
+const _types = require("./types.js");
+class LogEntryAdapter extends _loggeradapter.LogAdapter {
+    levels = _types.LogLevels;
+    level = _types.DefaultLogLevel;
+    threshold = _types.LogLevels.info;
+    redactionKeys = _redact.redact.fromOptions();
+    configure(scribeOptions) {
+        this.levels = this.getLogLevels(scribeOptions);
+        this.level = scribeOptions.logLevel ?? _types.DefaultLogLevel;
+        this.threshold = this.levels[this.level] ?? _types.LogLevels.info;
+        this.redactionKeys = _redact.redact.fromOptions(scribeOptions.redactions);
+    }
+    getLogger(name) {
+        return this.createLogger(name || "default", {});
+    }
+    createLogger(name, bindings) {
+        const { levels, level: currentLevel, threshold, redactionKeys } = this;
+        const baseLogger = {
+            get currentLevel () {
+                return currentLevel;
+            },
+            get logLevels () {
+                return levels;
+            }
+        };
+        const noop = ()=>{};
+        const methods = {};
+        for (const [level, value] of Object.entries(levels)){
+            methods[level] = value >= threshold ? (...args)=>this.write(_logentry.logEntry.from(level, name, args, {
+                    bindings,
+                    redactionKeys
+                })) : noop;
+        }
+        return Object.assign(baseLogger, methods, {
+            isLevelEnabled: (level)=>(levels[level] ?? 0) >= threshold,
+            child: (fields)=>this.createLogger(name, {
+                    ...bindings,
+                    ...fields
+                })
+        });
+    }
+}

package/commonjs/src/log-entry.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "logEntry", {
+    enumerable: true,
+    get: function() {
+        return logEntry;
+    }
+});
+const _loggeradapter = require("./logger.adapter.js");
+const _redact = require("./redact.js");
+function isFields(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+/** Serialize errors passed as fields (`{ error }`), so they keep their message and stack. */ function serializeErrors(fields) {
+    const out = {};
+    for (const [key, value] of Object.entries(fields)){
+        out[key] = value instanceof Error ? (0, _loggeradapter.serializeError)(value) : value;
+    }
+    return out;
+}
+/**
+ * Builds an entry from a log call's arguments:
+ *
+ * - `log.info("text")`, `log.info(42)` → `msg`
+ * - `log.error(err)` → `msg` is `err.message`, `err` the serialized error
+ * - `log.info({ fields })`, `log.info({ fields }, "text")` → `fields` (a string
+ *   `msg` field becomes the message)
+ * - `log.info("text", { fields })` → `msg` + `fields`
+ * - `log.error("text", err)` → `msg` + `err`
+ * - `log.info("text", value)` → `msg` + `fields.data`; any further arguments go
+ *   in `fields.args`
+ */ function from(level, name, [first, ...rest], { bindings, redactionKeys }) {
+    let msg;
+    let err;
+    let fields = {};
+    if (first instanceof Error) {
+        err = first;
+        msg = first.message;
+    } else if (isFields(first)) {
+        const { msg: fieldMsg, ...others } = first;
+        fields = others;
+        if (typeof fieldMsg === "string") {
+            msg = fieldMsg;
+        } else if (fieldMsg !== undefined) {
+            fields.msg = fieldMsg;
+        }
+        if (typeof rest[0] === "string") {
+            msg = rest.shift();
+        }
+    } else if (first !== undefined) {
+        msg = String(first);
+    }
+    const [second, ...extra] = rest;
+    if (second instanceof Error && err == null) {
+        err = second;
+    } else if (isFields(second)) {
+        fields = {
+            ...fields,
+            ...second
+        };
+    } else if (second !== undefined) {
+        fields.data = second;
+    }
+    if (extra.length > 0) {
+        fields.args = extra;
+    }
+    const allFields = serializeErrors({
+        ...bindings,
+        ...fields
+    });
+    const entry = {
+        level,
+        name,
+        fields: redactionKeys == null ? allFields : _redact.redact.object(allFields, redactionKeys)
+    };
+    if (msg !== undefined) {
+        entry.msg = msg;
+    }
+    if (err != null) {
+        const serialized = (0, _loggeradapter.serializeError)(err);
+        entry.err = redactionKeys == null ? serialized : _redact.redact.object(serialized, redactionKeys);
+    }
+    return entry;
+}
+const logEntry = {
+    from
+};

package/commonjs/src/logger.adapter.js

@@ -9,17 +9,52 @@ function _export(target, all) {
     });
 }
 _export(exports, {
+    get DefaultErrorCauseDepth () {
+        return DefaultErrorCauseDepth;
+    },
     get LogAdapter () {
         return LogAdapter;
     },
     get formatError () {
         return formatError;
+    },
+    get serializeError () {
+        return serializeError;
     }
 });
 const _types = require("./types.js");
 function formatError(err) {
     return err.stack ?? err.message;
 }
+const DefaultErrorCauseDepth = 3;
+function serializeError(err, causeDepth = DefaultErrorCauseDepth) {
+    const out = {
+        name: err.name,
+        message: err.message
+    };
+    if (err.stack != null) {
+        out.stack = err.stack;
+    }
+    for (const [key, value] of Object.entries(err)){
+        if (key === "cause" || key in out) {
+            continue;
+        }
+        if (!(value instanceof Error)) {
+            out[key] = value;
+        } else if (causeDepth > 0) {
+            out[key] = serializeError(value, causeDepth - 1);
+        }
+    }
+    const { cause } = err;
+    if (cause instanceof Error) {
+        if (causeDepth > 0) {
+            out.cause = serializeError(cause, causeDepth - 1);
+        }
+    } else if (cause !== undefined) {
+        out.cause = cause;
+    }
+    return out;
+}
 class LogAdapter {
     flush(cb) {
         cb?.();

package/commonjs/src/logger.factory.js

@@ -11,11 +11,13 @@ Object.defineProperty(exports, "scribe", {
 const _consoleadapter = require("./console.adapter.js");
 const _env = require("./env.js");
 const _errors = require("./errors.js");
+const _logentry = require("./log-entry.js");
 const _types = require("./types.js");
 class scribe {
     loggerProvider;
     /** True after `configure({ adapter })` — the constructor’s ConsoleAdapter is only a fallback. */ adapterConfigured = false;
     defaultAdapterWarned = false;
+    tap;
     static instance = new scribe();
     static logger(name, customLevels) {
         // Apply custom levels once against the active adapter; the live handle
@@ -48,17 +50,39 @@ class scribe {
     /**
 	 * Module-level `const log = scribe.logger(...)` must follow a later
 	 * `scribe.configure()` (CLI / Flux / HotReloadServer). Forward every use to
-	 * the active adapter logger for `name`.
-	 */ static createLiveLogger(name) {
+	 * the active adapter logger for `name`, and `child(fields)` to a live handle
+	 * that adds `bindings`, so children follow a reconfigure too.
+	 */ static createLiveLogger(name, bindings = {}) {
+        const bound = Object.keys(bindings).length > 0;
+        const resolve = ()=>{
+            const root = scribe.instance.getLogger(name);
+            return bound ? root.child(bindings) : root;
+        };
         return new Proxy({}, {
             get (_target, prop) {
-                const underlying = scribe.instance.getLogger(name);
+                if (prop === "child") {
+                    return (fields)=>scribe.createLiveLogger(name, {
+                            ...bindings,
+                            ...fields
+                        });
+                }
+                const underlying = resolve();
                 const value = Reflect.get(underlying, prop, underlying);
-                return typeof value === "function" ? value.bind(underlying) : value;
+                if (typeof value !== "function") {
+                    return value;
+                }
+                const method = value.bind(underlying);
+                const instance = scribe.instance;
+                if (instance.tap == null || typeof prop !== "string" || !Object.hasOwn(underlying.logLevels, prop) || !underlying.isLevelEnabled(prop)) {
+                    return method;
+                }
+                return (...args)=>{
+                    method(...args);
+                    instance.notifyTap(prop, name ?? "default", args, bindings);
+                };
             },
             has (_target, prop) {
-                const underlying = scribe.instance.getLogger(name);
-                return Reflect.has(underlying, prop);
+                return Reflect.has(resolve(), prop);
             }
         });
     }
@@ -69,13 +93,14 @@ class scribe {
         this.loggerProvider.configure(defaultOptions);
     }
     configure(configOptions) {
-        const { adapter, options } = configOptions;
+        const { adapter, options, tap } = configOptions;
         const previous = this.loggerProvider;
         if (previous !== adapter) {
             previous.retire();
         }
         this.loggerProvider = adapter;
         this.adapterConfigured = true;
+        this.tap = tap;
         const defaultsAndOptions = this.mergeDefaults(options);
         adapter.configure(defaultsAndOptions);
         if (previous !== adapter) {
@@ -105,12 +130,29 @@ class scribe {
         this.supportsLevels(customLevels, logger);
         return logger;
     }
+    notifyTap(level, name, args, bindings) {
+        const tap = this.tap;
+        if (tap == null) {
+            return;
+        }
+        try {
+            tap(_logentry.logEntry.from(level, name, args, {
+                bindings
+            }));
+        } catch (err) {
+            // Not swallowed: the logging call returns, the runtime reports the tap's error.
+            queueMicrotask(()=>{
+                throw err;
+            });
+        }
+    }
     warnIfDefaultAdapter() {
         if (this.adapterConfigured || this.defaultAdapterWarned) {
             return;
         }
         this.defaultAdapterWarned = true;
-        process.stderr.write("[scribe] No logger adapter configured; using the default ConsoleAdapter. " + "Configure an adapter at your composition root (for production, prefer " + "@decohere/scribe-pino → JSON on stdout). See " + "https://github.com/typesmiths/decohere/blob/main/projects/scribe/README.md\n");
+        // console.warn, not the stderr stream: the facade runs in browsers and Workers too.
+        console.warn("[scribe] No logger adapter configured; using the default ConsoleAdapter. " + "Configure an adapter at your composition root (for production, prefer " + "@decohere/scribe-pino → JSON on stdout). See " + "https://github.com/typesmiths/decohere/blob/main/projects/scribe/README.md");
     }
     supportsLevels(customLevels, logger) {
         if (!customLevels) {

package/commonjs/src/redact.js

@@ -27,26 +27,33 @@ function isPlainObject(value) {
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
-function object(value, keys, censor = _types.DefaultCensor, seen = new WeakSet()) {
+function object(value, keys, censor = _types.DefaultCensor, copies = new WeakMap()) {
     if (value == null || typeof value !== "object") {
         return value;
     }
     if (value instanceof Error) {
         return value;
     }
-    if (seen.has(value)) {
-        return value;
+    // A cycle in the input stays a cycle in the copy.
+    const copied = copies.get(value);
+    if (copied !== undefined) {
+        return copied;
     }
-    seen.add(value);
     if (Array.isArray(value)) {
-        return value.map((item)=>object(item, keys, censor, seen));
+        const out = [];
+        copies.set(value, out);
+        for (const item of value){
+            out.push(object(item, keys, censor, copies));
+        }
+        return out;
     }
     if (!isPlainObject(value)) {
         return value;
     }
     const out = {};
+    copies.set(value, out);
     for (const [key, nested] of Object.entries(value)){
-        out[key] = keys.has(key) ? censor : object(nested, keys, censor, seen);
+        out[key] = keys.has(key) ? censor : object(nested, keys, censor, copies);
     }
     return out;
 }

package/commonjs/src/testing/capture.adapter.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "CaptureAdapter", {
+    enumerable: true,
+    get: function() {
+        return CaptureAdapter;
+    }
+});
+const _logentryadapter = require("../log-entry.adapter.js");
+class CaptureAdapter extends _logentryadapter.LogEntryAdapter {
+    entries = [];
+    /** Entries at `level`. */ at(level) {
+        return this.entries.filter((entry)=>entry.level === level);
+    }
+    clear() {
+        this.entries.length = 0;
+    }
+    write(entry) {
+        this.entries.push(entry);
+    }
+}

package/commonjs/src/testing/index.js

@@ -2,3 +2,17 @@
 Object.defineProperty(exports, "__esModule", {
     value: true
 });
+_export_star(require("./capture.adapter.js"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}

package/es6/src/console.adapter.js

@@ -18,13 +18,16 @@ export class ConsoleAdapter extends LogAdapter {
     }
     getLogger(name) {
         const loggerName = name || "default";
-        return this.createConsoleLogger(loggerName);
+        return this.createConsoleLogger(loggerName, {});
     }
-    createConsoleLogger(name) {
+    createConsoleLogger(name, bindings) {
         const allLevels = this.configuredLevels;
         const currentLevel = this.configuredLogLevel;
         const threshold = this.configuredLogLevelValue;
         const redactionKeys = this.redactionKeys;
+        const bound = Object.keys(bindings).length > 0 ? [
+            redact.object(bindings, redactionKeys)
+        ] : [];
         const baseLogger = {
             get currentLevel () {
                 return currentLevel;
@@ -42,7 +45,10 @@ export class ConsoleAdapter extends LogAdapter {
                     message = String(msg);
                 }
                 const logLine = `[${timestamp}] ${level.toUpperCase()} [${name}]: ${message}`;
-                const payload = args.map((arg)=>redact.object(arg, redactionKeys));
+                const payload = [
+                    ...args.map((arg)=>redact.object(arg, redactionKeys)),
+                    ...bound
+                ];
                 if (payload.length > 0) {
                     console.log(logLine, ...payload);
                 } else {
@@ -51,7 +57,11 @@ export class ConsoleAdapter extends LogAdapter {
             };
         const noop = ()=>{};
         const logger = Object.assign(baseLogger, {
-            isLevelEnabled: (level)=>(allLevels[level] ?? 0) >= threshold
+            isLevelEnabled: (level)=>(allLevels[level] ?? 0) >= threshold,
+            child: (fields)=>this.createConsoleLogger(name, {
+                    ...bindings,
+                    ...fields
+                })
         });
         for (const [levelName, levelValue] of Object.entries(allLevels)){
             logger[levelName] = levelValue >= threshold ? logFunction(levelName) : noop;

package/es6/src/env.js

@@ -17,10 +17,11 @@ const VALID_LEVELS = [
 /**
  * Reads the log level from environment variables.
  * Checks LOG_LEVEL, SCRIBE_LOG_LEVEL, and LOGGING_LEVEL in order.
- * Returns null if none are set.
+ * Returns null if none are set, or if the runtime has no `process` (browsers).
  */ export function getLogLevelFromEnv() {
+    const env = globalThis.process?.env;
     for (const name of ENV_VAR_NAMES){
-        const value = process.env[name]?.trim().toLowerCase();
+        const value = env?.[name]?.trim().toLowerCase();
         if (value) {
             return value;
         }

package/es6/src/index.js

@@ -1,6 +1,8 @@
 export * from "./console.adapter.js";
 export * from "./env.js";
 export * from "./errors.js";
+export * from "./log-entry.adapter.js";
+export * from "./log-entry.js";
 export * from "./logger.adapter.js";
 export * from "./logger.factory.js";
 export * from "./logger.type.js";

package/es6/src/log-entry.adapter.js

@@ -0,0 +1,49 @@
+import { logEntry } from "./log-entry.js";
+import { LogAdapter } from "./logger.adapter.js";
+import { redact } from "./redact.js";
+import { DefaultLogLevel, LogLevels } from "./types.js";
+/**
+ * Base for adapters that write structured entries. It owns levels, the level
+ * threshold, `child`, and censoring the `redactions` keys; a subclass only
+ * writes each `LogEntry`.
+ */ export class LogEntryAdapter extends LogAdapter {
+    levels = LogLevels;
+    level = DefaultLogLevel;
+    threshold = LogLevels.info;
+    redactionKeys = redact.fromOptions();
+    configure(scribeOptions) {
+        this.levels = this.getLogLevels(scribeOptions);
+        this.level = scribeOptions.logLevel ?? DefaultLogLevel;
+        this.threshold = this.levels[this.level] ?? LogLevels.info;
+        this.redactionKeys = redact.fromOptions(scribeOptions.redactions);
+    }
+    getLogger(name) {
+        return this.createLogger(name || "default", {});
+    }
+    createLogger(name, bindings) {
+        const { levels, level: currentLevel, threshold, redactionKeys } = this;
+        const baseLogger = {
+            get currentLevel () {
+                return currentLevel;
+            },
+            get logLevels () {
+                return levels;
+            }
+        };
+        const noop = ()=>{};
+        const methods = {};
+        for (const [level, value] of Object.entries(levels)){
+            methods[level] = value >= threshold ? (...args)=>this.write(logEntry.from(level, name, args, {
+                    bindings,
+                    redactionKeys
+                })) : noop;
+        }
+        return Object.assign(baseLogger, methods, {
+            isLevelEnabled: (level)=>(levels[level] ?? 0) >= threshold,
+            child: (fields)=>this.createLogger(name, {
+                    ...bindings,
+                    ...fields
+                })
+        });
+    }
+}

package/es6/src/log-entry.js

@@ -0,0 +1,79 @@
+import { serializeError } from "./logger.adapter.js";
+import { redact } from "./redact.js";
+function isFields(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+/** Serialize errors passed as fields (`{ error }`), so they keep their message and stack. */ function serializeErrors(fields) {
+    const out = {};
+    for (const [key, value] of Object.entries(fields)){
+        out[key] = value instanceof Error ? serializeError(value) : value;
+    }
+    return out;
+}
+/**
+ * Builds an entry from a log call's arguments:
+ *
+ * - `log.info("text")`, `log.info(42)` → `msg`
+ * - `log.error(err)` → `msg` is `err.message`, `err` the serialized error
+ * - `log.info({ fields })`, `log.info({ fields }, "text")` → `fields` (a string
+ *   `msg` field becomes the message)
+ * - `log.info("text", { fields })` → `msg` + `fields`
+ * - `log.error("text", err)` → `msg` + `err`
+ * - `log.info("text", value)` → `msg` + `fields.data`; any further arguments go
+ *   in `fields.args`
+ */ function from(level, name, [first, ...rest], { bindings, redactionKeys }) {
+    let msg;
+    let err;
+    let fields = {};
+    if (first instanceof Error) {
+        err = first;
+        msg = first.message;
+    } else if (isFields(first)) {
+        const { msg: fieldMsg, ...others } = first;
+        fields = others;
+        if (typeof fieldMsg === "string") {
+            msg = fieldMsg;
+        } else if (fieldMsg !== undefined) {
+            fields.msg = fieldMsg;
+        }
+        if (typeof rest[0] === "string") {
+            msg = rest.shift();
+        }
+    } else if (first !== undefined) {
+        msg = String(first);
+    }
+    const [second, ...extra] = rest;
+    if (second instanceof Error && err == null) {
+        err = second;
+    } else if (isFields(second)) {
+        fields = {
+            ...fields,
+            ...second
+        };
+    } else if (second !== undefined) {
+        fields.data = second;
+    }
+    if (extra.length > 0) {
+        fields.args = extra;
+    }
+    const allFields = serializeErrors({
+        ...bindings,
+        ...fields
+    });
+    const entry = {
+        level,
+        name,
+        fields: redactionKeys == null ? allFields : redact.object(allFields, redactionKeys)
+    };
+    if (msg !== undefined) {
+        entry.msg = msg;
+    }
+    if (err != null) {
+        const serialized = serializeError(err);
+        entry.err = redactionKeys == null ? serialized : redact.object(serialized, redactionKeys);
+    }
+    return entry;
+}
+export const logEntry = {
+    from
+};

package/es6/src/logger.adapter.js

@@ -2,6 +2,39 @@ import { LogLevels } from "./types.js";
 export function formatError(err) {
     return err.stack ?? err.message;
 }
+/** How many causes deep `serializeError` follows by default. */ export const DefaultErrorCauseDepth = 3;
+/**
+ * Plain-object form of an error for structured logs. An `Error` cause, or an
+ * `Error` in another own property, is serialized the same way, up to
+ * `causeDepth` levels; any other value is kept as it is.
+ */ export function serializeError(err, causeDepth = DefaultErrorCauseDepth) {
+    const out = {
+        name: err.name,
+        message: err.message
+    };
+    if (err.stack != null) {
+        out.stack = err.stack;
+    }
+    for (const [key, value] of Object.entries(err)){
+        if (key === "cause" || key in out) {
+            continue;
+        }
+        if (!(value instanceof Error)) {
+            out[key] = value;
+        } else if (causeDepth > 0) {
+            out[key] = serializeError(value, causeDepth - 1);
+        }
+    }
+    const { cause } = err;
+    if (cause instanceof Error) {
+        if (causeDepth > 0) {
+            out.cause = serializeError(cause, causeDepth - 1);
+        }
+    } else if (cause !== undefined) {
+        out.cause = cause;
+    }
+    return out;
+}
 export class LogAdapter {
     flush(cb) {
         cb?.();

package/es6/src/logger.factory.js

@@ -1,11 +1,13 @@
 import { ConsoleAdapter } from "./console.adapter.js";
 import { resolveLogLevel } from "./env.js";
 import { LoggingConfigurationError } from "./errors.js";
+import { logEntry } from "./log-entry.js";
 import { DefaultLogLevel, DefaultRedactions } from "./types.js";
 export class scribe {
     loggerProvider;
     /** True after `configure({ adapter })` — the constructor’s ConsoleAdapter is only a fallback. */ adapterConfigured = false;
     defaultAdapterWarned = false;
+    tap;
     static instance = new scribe();
     static logger(name, customLevels) {
         // Apply custom levels once against the active adapter; the live handle
@@ -38,17 +40,39 @@ export class scribe {
     /**
 	 * Module-level `const log = scribe.logger(...)` must follow a later
 	 * `scribe.configure()` (CLI / Flux / HotReloadServer). Forward every use to
-	 * the active adapter logger for `name`.
-	 */ static createLiveLogger(name) {
+	 * the active adapter logger for `name`, and `child(fields)` to a live handle
+	 * that adds `bindings`, so children follow a reconfigure too.
+	 */ static createLiveLogger(name, bindings = {}) {
+        const bound = Object.keys(bindings).length > 0;
+        const resolve = ()=>{
+            const root = scribe.instance.getLogger(name);
+            return bound ? root.child(bindings) : root;
+        };
         return new Proxy({}, {
             get (_target, prop) {
-                const underlying = scribe.instance.getLogger(name);
+                if (prop === "child") {
+                    return (fields)=>scribe.createLiveLogger(name, {
+                            ...bindings,
+                            ...fields
+                        });
+                }
+                const underlying = resolve();
                 const value = Reflect.get(underlying, prop, underlying);
-                return typeof value === "function" ? value.bind(underlying) : value;
+                if (typeof value !== "function") {
+                    return value;
+                }
+                const method = value.bind(underlying);
+                const instance = scribe.instance;
+                if (instance.tap == null || typeof prop !== "string" || !Object.hasOwn(underlying.logLevels, prop) || !underlying.isLevelEnabled(prop)) {
+                    return method;
+                }
+                return (...args)=>{
+                    method(...args);
+                    instance.notifyTap(prop, name ?? "default", args, bindings);
+                };
             },
             has (_target, prop) {
-                const underlying = scribe.instance.getLogger(name);
-                return Reflect.has(underlying, prop);
+                return Reflect.has(resolve(), prop);
             }
         });
     }
@@ -59,13 +83,14 @@ export class scribe {
         this.loggerProvider.configure(defaultOptions);
     }
     configure(configOptions) {
-        const { adapter, options } = configOptions;
+        const { adapter, options, tap } = configOptions;
         const previous = this.loggerProvider;
         if (previous !== adapter) {
             previous.retire();
         }
         this.loggerProvider = adapter;
         this.adapterConfigured = true;
+        this.tap = tap;
         const defaultsAndOptions = this.mergeDefaults(options);
         adapter.configure(defaultsAndOptions);
         if (previous !== adapter) {
@@ -95,12 +120,29 @@ export class scribe {
         this.supportsLevels(customLevels, logger);
         return logger;
     }
+    notifyTap(level, name, args, bindings) {
+        const tap = this.tap;
+        if (tap == null) {
+            return;
+        }
+        try {
+            tap(logEntry.from(level, name, args, {
+                bindings
+            }));
+        } catch (err) {
+            // Not swallowed: the logging call returns, the runtime reports the tap's error.
+            queueMicrotask(()=>{
+                throw err;
+            });
+        }
+    }
     warnIfDefaultAdapter() {
         if (this.adapterConfigured || this.defaultAdapterWarned) {
             return;
         }
         this.defaultAdapterWarned = true;
-        process.stderr.write("[scribe] No logger adapter configured; using the default ConsoleAdapter. " + "Configure an adapter at your composition root (for production, prefer " + "@decohere/scribe-pino → JSON on stdout). See " + "https://github.com/typesmiths/decohere/blob/main/projects/scribe/README.md\n");
+        // console.warn, not the stderr stream: the facade runs in browsers and Workers too.
+        console.warn("[scribe] No logger adapter configured; using the default ConsoleAdapter. " + "Configure an adapter at your composition root (for production, prefer " + "@decohere/scribe-pino → JSON on stdout). See " + "https://github.com/typesmiths/decohere/blob/main/projects/scribe/README.md");
     }
     supportsLevels(customLevels, logger) {
         if (!customLevels) {

package/es6/src/redact.js

@@ -17,26 +17,33 @@ function isPlainObject(value) {
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
-function object(value, keys, censor = DefaultCensor, seen = new WeakSet()) {
+function object(value, keys, censor = DefaultCensor, copies = new WeakMap()) {
     if (value == null || typeof value !== "object") {
         return value;
     }
     if (value instanceof Error) {
         return value;
     }
-    if (seen.has(value)) {
-        return value;
+    // A cycle in the input stays a cycle in the copy.
+    const copied = copies.get(value);
+    if (copied !== undefined) {
+        return copied;
     }
-    seen.add(value);
     if (Array.isArray(value)) {
-        return value.map((item)=>object(item, keys, censor, seen));
+        const out = [];
+        copies.set(value, out);
+        for (const item of value){
+            out.push(object(item, keys, censor, copies));
+        }
+        return out;
     }
     if (!isPlainObject(value)) {
         return value;
     }
     const out = {};
+    copies.set(value, out);
     for (const [key, nested] of Object.entries(value)){
-        out[key] = keys.has(key) ? censor : object(nested, keys, censor, seen);
+        out[key] = keys.has(key) ? censor : object(nested, keys, censor, copies);
     }
     return out;
 }

package/es6/src/testing/capture.adapter.js

@@ -0,0 +1,17 @@
+import { LogEntryAdapter } from "../log-entry.adapter.js";
+/**
+ * Test double: keeps every entry that passes the level threshold, prints
+ * nothing. `scribe.configure({ adapter: capture })`, run the code, then assert
+ * on `capture.entries`.
+ */ export class CaptureAdapter extends LogEntryAdapter {
+    entries = [];
+    /** Entries at `level`. */ at(level) {
+        return this.entries.filter((entry)=>entry.level === level);
+    }
+    clear() {
+        this.entries.length = 0;
+    }
+    write(entry) {
+        this.entries.push(entry);
+    }
+}

package/es6/src/testing/index.js

@@ -1 +1 @@
-export { };
+export * from "./capture.adapter.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/scribe",
-  "version": "0.0.1-dev.119",
+  "version": "0.0.1-dev.120",
   "description": "Structured logging interface with pluggable adapters",
   "keywords": [
     "typescript",
@@ -17,6 +17,11 @@
       "types": "./types/src/index.d.ts",
       "import": "./es6/src/index.js",
       "require": "./commonjs/src/index.js"
+    },
+    "./testing": {
+      "types": "./types/src/testing/index.d.ts",
+      "import": "./es6/src/testing/index.js",
+      "require": "./commonjs/src/testing/index.js"
     }
   },
   "scripts": {

package/types/src/env.d.ts

@@ -2,7 +2,7 @@ import type { DefaultLevels } from "./types.js";
 /**
  * Reads the log level from environment variables.
  * Checks LOG_LEVEL, SCRIBE_LOG_LEVEL, and LOGGING_LEVEL in order.
- * Returns null if none are set.
+ * Returns null if none are set, or if the runtime has no `process` (browsers).
  */
 export declare function getLogLevelFromEnv(): string | null;
 /**

package/types/src/index.d.ts

@@ -1,6 +1,8 @@
 export * from "./console.adapter.js";
 export * from "./env.js";
 export * from "./errors.js";
+export * from "./log-entry.adapter.js";
+export * from "./log-entry.js";
 export * from "./logger.adapter.js";
 export * from "./logger.factory.js";
 export * from "./logger.type.js";

package/types/src/log-entry.adapter.d.ts

@@ -0,0 +1,20 @@
+import { type LogEntry } from "./log-entry.js";
+import { LogAdapter } from "./logger.adapter.js";
+import type { Logger } from "./logger.type.js";
+import { type ScribeOptions } from "./types.js";
+/**
+ * Base for adapters that write structured entries. It owns levels, the level
+ * threshold, `child`, and censoring the `redactions` keys; a subclass only
+ * writes each `LogEntry`.
+ */
+export declare abstract class LogEntryAdapter extends LogAdapter {
+    protected levels: Record<string, number>;
+    private level;
+    private threshold;
+    private redactionKeys;
+    configure<T extends string = never, CustomOnly extends true | false = false>(scribeOptions: ScribeOptions<T, CustomOnly>): void;
+    getLogger<T extends string = never, CustomOnly extends true | false = false>(name?: string): Logger<T, CustomOnly>;
+    /** Write one entry that passed the level threshold. */
+    protected abstract write(entry: LogEntry): void;
+    private createLogger;
+}

package/types/src/log-entry.d.ts

@@ -0,0 +1,38 @@
+import { type SerializedError } from "./logger.adapter.js";
+/**
+ * One logged call. Adapters that write structured lines build it with
+ * `logEntry.from`, and taps receive it.
+ */
+export type LogEntry = {
+    level: string;
+    name: string;
+    msg?: string;
+    err?: SerializedError;
+    /** Bound fields (`child`), then the call's own fields. */
+    fields: Record<string, unknown>;
+};
+export type LogEntryOptions = {
+    bindings?: Record<string, unknown>;
+    /**
+     * Keys the adapter censors (`redact.fromOptions`). Redaction is the
+     * adapter's job, so the facade's tap passes none.
+     */
+    redactionKeys?: ReadonlySet<string>;
+};
+/**
+ * Builds an entry from a log call's arguments:
+ *
+ * - `log.info("text")`, `log.info(42)` → `msg`
+ * - `log.error(err)` → `msg` is `err.message`, `err` the serialized error
+ * - `log.info({ fields })`, `log.info({ fields }, "text")` → `fields` (a string
+ *   `msg` field becomes the message)
+ * - `log.info("text", { fields })` → `msg` + `fields`
+ * - `log.error("text", err)` → `msg` + `err`
+ * - `log.info("text", value)` → `msg` + `fields.data`; any further arguments go
+ *   in `fields.args`
+ */
+declare function from(level: string, name: string, [first, ...rest]: readonly unknown[], { bindings, redactionKeys }: LogEntryOptions): LogEntry;
+export declare const logEntry: {
+    from: typeof from;
+};
+export {};

package/types/src/logger.adapter.d.ts

@@ -1,6 +1,22 @@
 import type { Logger } from "./logger.type.js";
 import { type ScribeOptions } from "./types.js";
 export declare function formatError(err: Error): string;
+export type SerializedError = {
+    name: string;
+    message: string;
+    stack?: string;
+    cause?: unknown;
+    /** Own enumerable properties such as `code` or `statusCode`. */
+    [property: string]: unknown;
+};
+/** How many causes deep `serializeError` follows by default. */
+export declare const DefaultErrorCauseDepth = 3;
+/**
+ * Plain-object form of an error for structured logs. An `Error` cause, or an
+ * `Error` in another own property, is serialized the same way, up to
+ * `causeDepth` levels; any other value is kept as it is.
+ */
+export declare function serializeError(err: Error, causeDepth?: number): SerializedError;
 export interface LoggerAdapter extends AsyncDisposable {
     configure<T extends string = never, CustomOnly extends true | false = false>(options: ScribeOptions<T, CustomOnly>): any;
     getLogger<T extends string = never, CustomOnly extends true | false = false>(name: string): Logger<T, CustomOnly>;

package/types/src/logger.factory.d.ts

@@ -1,15 +1,26 @@
+import { type LogEntry } from "./log-entry.js";
 import type { LoggerAdapter } from "./logger.adapter.js";
 import type { Logger } from "./logger.type.js";
 import { type ScribeOptions } from "./types.js";
 type LoggerFactoryOptions<T extends string = never, CustomOnly extends true | false = false> = {
     options?: ScribeOptions<T, CustomOnly>;
     adapter: LoggerAdapter;
+    /**
+     * Called with every entry a `scribe.logger(...)` handle writes (levels the
+     * adapter has enabled). For error reporters such as Sentry. Scribe does not
+     * redact what it hands the tap; the tap, or the service behind it, does.
+     * A tap that throws does not break the call that logged: the error is
+     * rethrown on a microtask, where the runtime reports it as uncaught.
+     */
+    tap?: LogTap;
 };
+export type LogTap = (entry: LogEntry) => void;
 export declare class scribe implements AsyncDisposable {
     private loggerProvider;
     /** True after `configure({ adapter })` — the constructor’s ConsoleAdapter is only a fallback. */
     private adapterConfigured;
     private defaultAdapterWarned;
+    private tap;
     private static instance;
     static logger<T extends string = never, CustomOnly extends true | false = false>(name?: string, customLevels?: {
         [level in T]: number;
@@ -23,7 +34,8 @@ export declare class scribe implements AsyncDisposable {
     /**
      * Module-level `const log = scribe.logger(...)` must follow a later
      * `scribe.configure()` (CLI / Flux / HotReloadServer). Forward every use to
-     * the active adapter logger for `name`.
+     * the active adapter logger for `name`, and `child(fields)` to a live handle
+     * that adds `bindings`, so children follow a reconfigure too.
      */
     private static createLiveLogger;
     constructor();
@@ -34,6 +46,7 @@ export declare class scribe implements AsyncDisposable {
     getLogger<T extends string = never, CustomOnly extends true | false = false>(name?: string, customLevels?: {
         [level in T]: number;
     }): Logger<T, CustomOnly>;
+    private notifyTap;
     private warnIfDefaultAdapter;
     private supportsLevels;
     private mergeDefaults;

package/types/src/logger.type.d.ts

@@ -10,4 +10,9 @@ export type Logger<CustomLevels extends string = never, CustomOnly extends true
     [Property in CustomLevels]: LogFn;
 } & {
     isLevelEnabled(level: string): boolean;
+    /**
+     * A logger with the same name and levels that adds `fields` (a request id, a
+     * job name) to every entry. Children of children merge their fields.
+     */
+    child(fields: Record<string, unknown>): Logger<CustomLevels, CustomOnly>;
 } & BaseLogger;

package/types/src/redact.d.ts

@@ -1,6 +1,6 @@
 import { type RedactionOptions } from "./types.js";
 declare function keysFromPaths(paths: string[]): Set<string>;
-declare function object(value: unknown, keys: ReadonlySet<string>, censor?: string, seen?: WeakSet<object>): unknown;
+declare function object(value: unknown, keys: ReadonlySet<string>, censor?: string, copies?: WeakMap<object, unknown>): unknown;
 declare function fromOptions(options?: RedactionOptions): Set<string>;
 export declare const redact: {
     object: typeof object;

package/types/src/testing/capture.adapter.d.ts

@@ -0,0 +1,14 @@
+import { LogEntryAdapter } from "../log-entry.adapter.js";
+import type { LogEntry } from "../log-entry.js";
+/**
+ * Test double: keeps every entry that passes the level threshold, prints
+ * nothing. `scribe.configure({ adapter: capture })`, run the code, then assert
+ * on `capture.entries`.
+ */
+export declare class CaptureAdapter extends LogEntryAdapter {
+    readonly entries: LogEntry[];
+    /** Entries at `level`. */
+    at(level: string): LogEntry[];
+    clear(): void;
+    protected write(entry: LogEntry): void;
+}

package/types/src/testing/index.d.ts

@@ -1 +1 @@
-export {};
+export * from "./capture.adapter.js";