@decohere/scribe 0.0.1-dev.13 → 0.0.1-dev.130

package/es6/src/redact.js

@@ -0,0 +1,57 @@
+import { DefaultCensor, DefaultRedactions } from "./types.js";
+function keysFromPaths(paths) {
+    const keys = new Set();
+    for (const path of paths){
+        const segments = path.split(".").filter((segment)=>segment.length > 0 && segment !== "*");
+        const key = segments.at(-1);
+        if (key != null) {
+            keys.add(key);
+        }
+    }
+    return keys;
+}
+function isPlainObject(value) {
+    if (value == null || typeof value !== "object" || Array.isArray(value) || value instanceof Error) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function object(value, keys, censor = DefaultCensor, copies = new WeakMap()) {
+    if (value == null || typeof value !== "object") {
+        return value;
+    }
+    if (value instanceof Error) {
+        return value;
+    }
+    // A cycle in the input stays a cycle in the copy.
+    const copied = copies.get(value);
+    if (copied !== undefined) {
+        return copied;
+    }
+    if (Array.isArray(value)) {
+        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, copies);
+    }
+    return out;
+}
+function fromOptions(options) {
+    return keysFromPaths(options?.paths ?? DefaultRedactions.paths);
+}
+export const redact = {
+    object,
+    keysFromPaths,
+    fromOptions
+};

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,3 +1 @@
-export { };
-
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi9ob21lL3J1bm5lci93b3JrL2RlY29oZXJlL2RlY29oZXJlL3Byb2plY3RzL3NjcmliZS9zY3JpYmUvc3JjL3Rlc3RpbmcvaW5kZXgudHMiXSwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0IHt9O1xuIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLFdBQVUifQ==
+export * from "./capture.adapter.js";

package/es6/src/types.js

@@ -15,11 +15,21 @@ export const LogLevels = {
     trace: 10
 };
 export const DefaultLogLevel = "info";
+/** Pino's default censor. ConsoleAdapter uses the same placeholder. */ export const DefaultCensor = "[Redacted]";
+/**
+ * Object keys Scribe redacts. Adapters apply this list — Pino via `redact.paths`
+ * (top-level and one nest), ConsoleAdapter via `redact.object`.
+ */ export const DefaultRedactionKeys = [
+    "password",
+    "secret",
+    "token",
+    "otp",
+    "pw",
+    "userconfig"
+];
 export const DefaultRedactions = {
-    paths: [
-        "*.password",
-        "*.secret"
-    ]
+    paths: DefaultRedactionKeys.flatMap((key)=>[
+            key,
+            `*.${key}`
+        ])
 };
-
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi9ob21lL3J1bm5lci93b3JrL2RlY29oZXJlL2RlY29oZXJlL3Byb2plY3RzL3NjcmliZS9zY3JpYmUvc3JjL3R5cGVzLnRzIl0sInNvdXJjZXNDb250ZW50IjpbImNvbnN0IExPR19MRVZFTFMgPSBbXCJmYXRhbFwiLCBcImVycm9yXCIsIFwid2FyblwiLCBcImluZm9cIiwgXCJkZWJ1Z1wiLCBcInRyYWNlXCJdIGFzIGNvbnN0O1xuXG5leHBvcnQgdHlwZSBMb2dMZXZlbCA9IHR5cGVvZiBMT0dfTEVWRUxTO1xuXG5leHBvcnQgdHlwZSBEZWZhdWx0TGV2ZWxzID0gTG9nTGV2ZWxbbnVtYmVyXTtcblxuZXhwb3J0IGNvbnN0IExvZ0xldmVscyA9IHtcblx0ZmF0YWw6IDYwLFxuXHRlcnJvcjogNTAsXG5cdHdhcm46IDQwLFxuXHRpbmZvOiAzMCxcblx0ZGVidWc6IDIwLFxuXHR0cmFjZTogMTAsXG59IHNhdGlzZmllcyBSZWNvcmQ8RGVmYXVsdExldmVscywgbnVtYmVyPjtcblxuZXhwb3J0IGNvbnN0IERlZmF1bHRMb2dMZXZlbDogRGVmYXVsdExldmVscyA9IFwiaW5mb1wiO1xuXG5leHBvcnQgdHlwZSBSZWRhY3Rpb25PcHRpb25zID0ge1xuXHRwYXRoczogc3RyaW5nW107XG59O1xuXG5leHBvcnQgY29uc3QgRGVmYXVsdFJlZGFjdGlvbnM6IFJlZGFjdGlvbk9wdGlvbnMgPSB7IHBhdGhzOiBbXCIqLnBhc3N3b3JkXCIsIFwiKi5zZWNyZXRcIl0gfTtcblxuZXhwb3J0IGludGVyZmFjZSBTY3JpYmVPcHRpb25zPFxuXHRUIGV4dGVuZHMgc3RyaW5nID0gbmV2ZXIsXG5cdEN1c3RvbU9ubHkgZXh0ZW5kcyB0cnVlIHwgZmFsc2UgPSB1bmRlZmluZWQsXG4+IHtcblx0bG9nTGV2ZWw/OiBEZWZhdWx0TGV2ZWxzIHwgc3RyaW5nO1xuXHRjdXN0b21MZXZlbHM/OiB7XG5cdFx0W2xldmVsIGluIFRdOiBudW1iZXI7XG5cdH07XG5cdGN1c3RvbU9ubHk/OiBDdXN0b21Pbmx5O1xuXHRyZWRhY3Rpb25zPzogUmVkYWN0aW9uT3B0aW9ucztcbn1cblxuZXhwb3J0IHR5cGUgTG9nQWRhcHRlck9wdGlvbnMgPSBSZWNvcmQ8c3RyaW5nLCBuZXZlcj47XG4iXSwibmFtZXMiOlsiTE9HX0xFVkVMUyIsIkxvZ0xldmVscyIsImZhdGFsIiwiZXJyb3IiLCJ3YXJuIiwiaW5mbyIsImRlYnVnIiwidHJhY2UiLCJEZWZhdWx0TG9nTGV2ZWwiLCJEZWZhdWx0UmVkYWN0aW9ucyIsInBhdGhzIl0sIm1hcHBpbmdzIjoiQUFBQSxNQUFNQSxhQUFhO0lBQUM7SUFBUztJQUFTO0lBQVE7SUFBUTtJQUFTO0NBQVE7QUFNdkUsT0FBTyxNQUFNQyxZQUFZO0lBQ3hCQyxPQUFPO0lBQ1BDLE9BQU87SUFDUEMsTUFBTTtJQUNOQyxNQUFNO0lBQ05DLE9BQU87SUFDUEMsT0FBTztBQUNSLEVBQTBDO0FBRTFDLE9BQU8sTUFBTUMsa0JBQWlDLE9BQU87QUFNckQsT0FBTyxNQUFNQyxvQkFBc0M7SUFBRUMsT0FBTztRQUFDO1FBQWM7S0FBVztBQUFDLEVBQUUifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/scribe",
-  "version": "0.0.1-dev.13",
+  "version": "0.0.1-dev.130",
   "description": "Structured logging interface with pluggable adapters",
   "keywords": [
     "typescript",
@@ -8,6 +8,15 @@
     "structured-logging",
     "decohere"
   ],
+  "homepage": "https://github.com/typesmiths/decohere/tree/main/projects/scribe/scribe#readme",
+  "bugs": {
+    "url": "https://github.com/typesmiths/decohere/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/typesmiths/decohere.git",
+    "directory": "projects/scribe/scribe"
+  },
   "license": "ISC",
   "author": "Typesmiths",
   "type": "module",
@@ -17,6 +26,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/console.adapter.d.ts

@@ -6,6 +6,7 @@ export declare class ConsoleAdapter extends LogAdapter {
     private configuredLevels;
     private configuredLogLevel;
     private configuredLogLevelValue;
+    private redactionKeys;
     constructor(_options?: ConsoleAdapterOptions);
     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>;

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,7 +1,10 @@
 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";
+export * from "./redact.js";
 export * from "./types.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,14 +1,45 @@
 import type { Logger } from "./logger.type.js";
 import { type ScribeOptions } from "./types.js";
-export interface LoggerAdapter {
+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>;
     flush(cb?: () => void): void;
+    /**
+     * Synchronously stop accepting writes (kill ThreadStream / close fds).
+     * Call before swapping adapters so a dead worker cannot spam on further logs.
+     * Idempotent — safe to call more than once.
+     */
+    retire(): void;
+    /**
+     * Drain buffered output and release unmanaged handles (workers, fds).
+     * Idempotent — safe to call more than once.
+     */
+    stop(): Promise<void>;
 }
 export declare abstract class LogAdapter implements LoggerAdapter {
     abstract configure<T extends string = never, CustomOnly extends true | false = false>(options: ScribeOptions<T, CustomOnly>): any;
     abstract getLogger<T extends string = never, CustomOnly extends true | false = false>(name: string): Logger<T, CustomOnly>;
     flush(cb?: () => void): void;
+    retire(): void;
+    stop(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
     protected getLogLevels(options: ScribeOptions<any, any>): Record<string, number>;
     protected getUniqueLevels(defaultLevels: Record<string, number>, customLevels: Record<string, number>): [string, number][];
 }

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

@@ -1,24 +1,53 @@
+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 declare class scribe {
+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;
     }): Logger<T, CustomOnly>;
     static configure<T extends string = never, CustomOnly extends true | false = false>(configOptions: LoggerFactoryOptions<T, CustomOnly>): (name?: string) => Logger<T, CustomOnly>;
-    static get extend(): scribe;
     static flush(cb?: () => void): void;
+    /** Synchronously stop accepting writes on the active adapter. */
+    static retire(): void;
+    /** Drain the active adapter and release workers / destinations. */
+    static stop(): Promise<void>;
+    /**
+     * 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`, and `child(fields)` to a live handle
+     * that adds `bindings`, so children follow a reconfigure too.
+     */
+    private static createLiveLogger;
     constructor();
     configure<T extends string = never, CustomOnly extends true | false = false>(configOptions: LoggerFactoryOptions<T, CustomOnly>): (name?: string) => Logger<T, CustomOnly>;
+    retire(): void;
+    stop(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
     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

@@ -0,0 +1,10 @@
+import { type RedactionOptions } from "./types.js";
+declare function keysFromPaths(paths: string[]): Set<string>;
+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;
+    keysFromPaths: typeof keysFromPaths;
+    fromOptions: typeof fromOptions;
+};
+export {};

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";

package/types/src/types.d.ts

@@ -13,6 +13,13 @@ export declare const DefaultLogLevel: DefaultLevels;
 export type RedactionOptions = {
     paths: string[];
 };
+/** Pino's default censor. ConsoleAdapter uses the same placeholder. */
+export declare const DefaultCensor = "[Redacted]";
+/**
+ * Object keys Scribe redacts. Adapters apply this list — Pino via `redact.paths`
+ * (top-level and one nest), ConsoleAdapter via `redact.object`.
+ */
+export declare const DefaultRedactionKeys: readonly ["password", "secret", "token", "otp", "pw", "userconfig"];
 export declare const DefaultRedactions: RedactionOptions;
 export interface ScribeOptions<T extends string = never, CustomOnly extends true | false = undefined> {
     logLevel?: DefaultLevels | string;