@deployanyway/doggo-log 0.4.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.0.0
+
+- Fetch the Context: async request scopes and redaction.
+- Typed API, CLI integration, runnable codebase example and meaningful workflow tests.
+- Stable contracts and migration guidance; original humor stays around accurate facts.
+
 ## 0.4.0
 
 48 original lines: eight per log level. Default `barkMode: 'classic'` preserves the existing first-line commentary. Opt into `barkMode: 'rotate'` for variation without repeats until that level's eight lines have been emitted. A seed selects a repeatable starting point by prefix and level; omitted seed starts with the first line. Filtering and quiet mode do not consume rotation. Each child logger owns its own sequence.

package/MIGRATION.md

@@ -9,3 +9,9 @@ Install 0.3.0 with npm. Seeds and exact humorous wording are version-specific. D
 48 original commentary lines across six levels; opt-in seeded rotation; independent child sequences, no advancement on filtering or failed writes; barkLines catalog API and CLI controls. Classic commentary remains default.
 
 Existing defaults and entry points remain available. The new commentary rotation is opt-in; classic first-line commentary remains the default.
+
+## 0.4.0 to stable 1.0.0
+
+Intentional v1 changes: credential context keys redact by default, and text logs include nonempty context. Use redact:false only when you deliberately need the prior raw-context output. Existing levels, methods, JSON shape, formatting, child loggers, classic barks and opt-in rotation remain. New Node context subpath supports ESM and CommonJS; the core entry remains browser-adaptable.
+
+See README for exact contracts, bounds and failure behavior.

package/README.md

@@ -1,5 +1,43 @@
 # doggo-log
 
+## Fetch the Context: async request scopes and redaction (1.0.0)
+
+The Node-only @deployanyway/doggo-log/context entry exports createRequestLogger(options). Use one logger per service and run(context, callback, ...args) per request. AsyncLocalStorage carries the copied scalar context through awaited work; concurrent requests remain isolated. Child loggers share the active scope, and nested scopes restore the outer context when they finish.
+
+```js
+import { createRequestLogger } from "@deployanyway/doggo-log/context";
+const log = createRequestLogger({ json: true, context: { service: "api" } });
+const db = log.child("database");
+await log.run(
+  { requestId: "request-42", authorization: "private-header" },
+  async () => {
+    await Promise.resolve();
+    db.info("Query finished"); // requestId follows the work; authorization is redacted
+  },
+);
+log.dispose(); // only after all work has completed
+```
+
+run preserves callback return values/promises/errors. Scoped fields override static context, nested fields merge, and getContext() returns a fresh raw scope copy (do not expose it publicly). Outside scopes only static context remains. dispose disables tracking and prevents future run calls. Do not dispose an active service per request. Async boundaries that lose Node context, worker threads and external processes require explicit handoff; scopes do not cross them automatically. Reference: [Node asynchronous context documentation](https://nodejs.org/api/async_context.html).
+
+Redaction runs before writer callbacks and returned JSON/text. Default credential context keys are password, passwd, token, accessToken, refreshToken, authorization, cookie, secret and apiKey, case-insensitive with hyphens/underscores normalized. Configure redact: {keys: ['private'], values: ['literal-secret'], replacement: '[REDACTED]'}. keys replaces the default key list; values replaces exact literals in formatted messages, prefixes and string context values, longest first. redact: false explicitly disables it. Text logs now include supplied context, so request IDs are useful outside JSON too.
+
+Redaction is scoped: context fields must be scalar; it does not inspect arbitrary objects formatted in message arguments, discover unknown secrets, decode transformed tokens or scrub another writer's output. Avoid logging credentials in arbitrary message objects. Protect context keys and configure known literal values where needed. Filtering skips providers/writers; failed writes preserve bark rotation.
+
+```sh
+doggo-log info 'Request complete' --context '{"requestId":"42","authorization":"private"}' --json
+doggo-log info 'token=demo-only' --redact-values '["demo-only"]' --json
+node node_modules/@deployanyway/doggo-log/examples/fetch-context.mjs
+```
+
+--redact-keys accepts comma-separated context keys; --redact-values accepts a JSON string array. The runnable Node example makes two concurrent loopback HTTP requests and demonstrates isolated redacted logs. Browser demos can preview formatting/context redaction; AsyncLocalStorage itself runs in Node, not a browser shim.
+
+## Stable v1 contract
+
+Node 22.13+ or Node 24. MIT licensed. CLI flags, structured fields, ESM/CommonJS exports and declarations are covered by tests and installed-package checks. Existing 0.4 APIs remain available except the explicitly documented doggo-log redaction/text-context changes. Future incompatible public API changes require a major release; callers should consume structured fields rather than parse jokes. Exact humorous wording and seeded catalog choices are version-specific. No telemetry, external API keys or network service is needed for core use.
+
+Run npm test, npm run lint, npm run format:check, npm run coverage, npm run test:types and npm run verify:package from a source checkout. Runnable examples are shipped under examples/. The root demo is https://deployanyway.github.io/.
+
 ## Commentary that stays useful (0.4.0)
 
 48 original lines: eight per log level. Default `barkMode: 'classic'` preserves the existing first-line commentary. Opt into `barkMode: 'rotate'` for variation without repeats until that level's eight lines have been emitted. A seed selects a repeatable starting point by prefix and level; omitted seed starts with the first line. Filtering and quiet mode do not consume rotation. Each child logger owns its own sequence.

package/context.d.cts

@@ -0,0 +1,14 @@
+import type { DogLogger, DogOptions, LogContext } from "./index.js";
+export type RequestLogger = DogLogger & {
+  run<T, A extends unknown[]>(
+    context: LogContext,
+    callback: (...args: A) => T,
+    ...args: A
+  ): T;
+  /** Returns a fresh copy of the current raw scope; do not expose it as a public response. */
+  getContext(): LogContext;
+  dispose(): void;
+};
+export function createRequestLogger(
+  options?: Omit<DogOptions, "contextProvider">,
+): RequestLogger;

package/context.d.ts

@@ -0,0 +1,14 @@
+import type { DogLogger, DogOptions, LogContext } from "./index.js";
+export type RequestLogger = DogLogger & {
+  run<T, A extends unknown[]>(
+    context: LogContext,
+    callback: (...args: A) => T,
+    ...args: A
+  ): T;
+  /** Returns a fresh copy of the current raw scope; do not expose it as a public response. */
+  getContext(): LogContext;
+  dispose(): void;
+};
+export function createRequestLogger(
+  options?: Omit<DogOptions, "contextProvider">,
+): RequestLogger;

package/dist/context.cjs

@@ -0,0 +1,340 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/context.js
+var context_exports = {};
+__export(context_exports, {
+  createRequestLogger: () => createRequestLogger
+});
+module.exports = __toCommonJS(context_exports);
+var import_node_async_hooks = require("node:async_hooks");
+
+// src/index.js
+var import_node_util = require("node:util");
+
+// src/levels.js
+var levels = {
+  debug: { rank: 10, emoji: "\u{1F50D}", color: 90 },
+  log: { rank: 20, emoji: "\u{1F436}", color: 37 },
+  info: { rank: 20, emoji: "\u{1F436}", color: 36 },
+  success: { rank: 20, emoji: "\u{1F43E}", color: 32 },
+  warn: { rank: 30, emoji: "\u{1F9B4}", color: 33 },
+  error: { rank: 40, emoji: "\u{1F6A8}", color: 31 }
+};
+
+// src/commentary.js
+var lines = {
+  debug: [
+    "Sniffing for clues.",
+    "Follow the trace, not the squirrel.",
+    "One breakpoint. Two ears. Maximum attention.",
+    "The missing value has left a scent trail.",
+    "Logging the evidence before chasing the theory.",
+    "The stack trace is our walking route.",
+    "Small reproduction, big detective energy.",
+    "Dallas found a clue. Benji would like to inspect the keyboard."
+  ],
+  log: [
+    "Filed under things I sniffed.",
+    "Fetch complete. Filing the interesting bit.",
+    "Another breadcrumb for future-us.",
+    "This line has been approved by the tail department.",
+    "A small update with excellent ears.",
+    "Evidence delivered without chewing it.",
+    "Keeping a trail through the code forest.",
+    "Benji brought the log. Dallas brought enthusiasm."
+  ],
+  info: [
+    "Good to know. Good dog to tell you.",
+    "A useful update, delivered at husky speed.",
+    "The facts have arrived wearing sensible paws.",
+    "Worth knowing before the next zoomie.",
+    "No alarm. Just a well-timed nose boop.",
+    "Status fetched. Tail at a responsible speed.",
+    "A little context saves a lot of barking.",
+    "Dallas and Benji have entered the observability business."
+  ],
+  success: [
+    "Treat budget approved.",
+    "Good result. Better evidence. Best dog.",
+    "The check passed. Save some applause for monitoring.",
+    "One fewer problem between us and the walk.",
+    "Tail deployment successful.",
+    "The happy path has receipts today.",
+    "Achievement unlocked: boring, repeatable success.",
+    "Dallas celebrates. Benji is already planning the victory lap."
+  ],
+  warn: [
+    "Suspicious squirrel detected.",
+    "Ears up. This deserves a closer look.",
+    "Something smells odd; inspect before retrying.",
+    "A warning is a breadcrumb, not a dare.",
+    "The tail slowed down for a reason.",
+    "Check the evidence before this becomes an incident.",
+    "Potential trouble has arrived with muddy paws.",
+    "Benji heard something. Dallas recommends checking the logs."
+  ],
+  error: [
+    "The dog has fetched the incident report.",
+    "Read the first failure before chasing the pack.",
+    "The red light is evidence, not a personality review.",
+    "Pause the zoomies. Find the cause and the rollback.",
+    "This needs a fix, not louder barking.",
+    "Capture the reproduction while the scent is fresh.",
+    "The operation failed. The team still gets kindness.",
+    "Dallas and Benji are standing by with emotional support."
+  ]
+};
+function barkLines(level) {
+  if (typeof level !== "string" || !Object.hasOwn(lines, level))
+    throw new RangeError("Choose debug, log, info, success, warn or error.");
+  return [...lines[level]];
+}
+function commentaryIndex(seed, salt, length) {
+  if (seed === void 0) return 0;
+  let hash = 2166136261;
+  for (const char of salt + ":" + typeof seed + ":" + seed) {
+    hash ^= char.codePointAt(0);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash % length;
+}
+
+// src/redaction.js
+var defaultKeys = [
+  "password",
+  "passwd",
+  "token",
+  "accessToken",
+  "refreshToken",
+  "authorization",
+  "cookie",
+  "secret",
+  "apiKey"
+];
+var normalize = (key) => key.toLowerCase().replaceAll(/[-_]/g, "");
+function copyContext(context) {
+  if (!context || typeof context !== "object" || Array.isArray(context))
+    throw new TypeError("context must be an object of scalar fields.");
+  for (const value of Object.values(context))
+    if (!(value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)))
+      throw new TypeError(
+        "Context values must be strings, finite numbers, booleans or null."
+      );
+  return { ...context };
+}
+function createRedactor(options) {
+  if (options === false)
+    return { text: (value) => value, context: copyContext };
+  if (options === void 0) options = {};
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw new TypeError("redact must be false or an options object.");
+  const keys = options.keys ?? defaultKeys, values = options.values ?? [], replacement = options.replacement ?? "[REDACTED]";
+  for (const [name, list] of [
+    ["keys", keys],
+    ["values", values]
+  ])
+    if (!Array.isArray(list) || list.length > 100 || !list.every((value) => typeof value === "string" && value.length > 0))
+      throw new TypeError(
+        `Redaction ${name} must contain at most 100 nonempty strings.`
+      );
+  if (typeof replacement !== "string")
+    throw new TypeError("Redaction replacement must be a string.");
+  const protectedKeys = new Set(keys.map(normalize));
+  const literals = [...new Set(values)].sort((a, b) => b.length - a.length);
+  const text = (value) => literals.reduce(
+    (output, secret) => output.split(secret).join(replacement),
+    value
+  );
+  return {
+    text,
+    context: (context) => Object.fromEntries(
+      Object.entries(copyContext(context)).map(([key, value]) => [
+        key,
+        protectedKeys.has(normalize(key)) ? replacement : typeof value === "string" ? text(value) : value
+      ])
+    )
+  };
+}
+
+// src/index.js
+function createDogLogger(options = {}) {
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw new TypeError("Options must be an object.");
+  const config = {
+    emoji: true,
+    bark: false,
+    barkMode: "classic",
+    seed: void 0,
+    color: false,
+    timestamp: false,
+    json: false,
+    quiet: false,
+    prefix: "",
+    level: "info",
+    context: {},
+    contextProvider: () => ({}),
+    write: (line, level) => level === "warn" || level === "error" ? console.error(line) : console.log(line),
+    clock: () => /* @__PURE__ */ new Date(),
+    ...options
+  };
+  for (const key of ["emoji", "color", "timestamp", "json", "quiet", "bark"]) {
+    if (typeof config[key] !== "boolean")
+      throw new TypeError(`${key} must be a boolean.`);
+  }
+  if (typeof config.prefix !== "string")
+    throw new TypeError("prefix must be a string.");
+  if (!config.context || typeof config.context !== "object" || Array.isArray(config.context))
+    throw new TypeError("context must be an object of scalar fields.");
+  for (const value of Object.values(config.context))
+    if (!(value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)))
+      throw new TypeError(
+        "Context values must be strings, finite numbers, booleans or null."
+      );
+  config.context = copyContext(config.context);
+  if (typeof config.contextProvider !== "function")
+    throw new TypeError("contextProvider must be a function.");
+  const redactor = createRedactor(config.redact);
+  if (config.redact !== false)
+    config.redact = {
+      ...config.redact,
+      ...config.redact?.keys ? { keys: [...config.redact.keys] } : {},
+      ...config.redact?.values ? { values: [...config.redact.values] } : {}
+    };
+  if (typeof config.level !== "string" || !Object.hasOwn(levels, config.level))
+    throw new RangeError(
+      `level must be one of: ${Object.keys(levels).join(", ")}.`
+    );
+  if (typeof config.write !== "function" || typeof config.clock !== "function")
+    throw new TypeError("write and clock must be functions.");
+  if (!["classic", "rotate"].includes(config.barkMode))
+    throw new RangeError("barkMode must be classic or rotate.");
+  if (config.seed !== void 0 && typeof config.seed !== "string" && !(typeof config.seed === "number" && Number.isFinite(config.seed)))
+    throw new TypeError("seed must be a string or finite number.");
+  const counters = {};
+  const logger = Object.fromEntries(
+    Object.entries(levels).map(([level, style]) => [
+      level,
+      (...args) => {
+        if (config.quiet || style.rank < levels[config.level].rank)
+          return void 0;
+        const message = redactor.text((0, import_node_util.format)(...args));
+        const context = redactor.context({
+          ...config.context,
+          ...copyContext(config.contextProvider())
+        });
+        const pool = config.bark ? barkLines(level) : void 0;
+        const index = config.barkMode === "rotate" ? (commentaryIndex(
+          config.seed,
+          config.prefix + ":" + level,
+          pool?.length ?? 1
+        ) + (counters[level] ?? 0)) % (pool?.length ?? 1) : 0;
+        const commentary = pool?.[index];
+        let timestamp;
+        if (config.timestamp) {
+          const date = config.clock();
+          if (!(date instanceof Date) || !Number.isFinite(date.getTime()))
+            throw new TypeError("clock must return a valid Date.");
+          timestamp = date.toISOString();
+        }
+        let line;
+        if (config.json) {
+          line = JSON.stringify({
+            level,
+            message,
+            ...Object.keys(context).length ? { context } : {},
+            ...commentary ? { commentary } : {},
+            ...config.prefix ? { prefix: redactor.text(config.prefix) } : {},
+            ...timestamp ? { timestamp } : {}
+          });
+        } else {
+          line = [
+            timestamp,
+            redactor.text(config.prefix),
+            config.emoji ? style.emoji : void 0,
+            level.toUpperCase().padEnd(7),
+            message,
+            Object.keys(context).length ? JSON.stringify(context) : void 0,
+            commentary
+          ].filter((part) => part !== void 0 && part !== "").join(" ");
+          if (config.color) line = `\x1B[${style.color}m${line}\x1B[0m`;
+        }
+        config.write(line, level);
+        if (config.bark)
+          counters[level] = ((counters[level] ?? 0) + 1) % pool.length;
+        return line;
+      }
+    ])
+  );
+  logger.child = (prefix, context = {}) => {
+    if (!context || typeof context !== "object" || Array.isArray(context))
+      throw new TypeError("context must be an object.");
+    if (typeof prefix !== "string" || !prefix.trim())
+      throw new TypeError("Child prefix must be a nonempty string.");
+    return createDogLogger({
+      ...config,
+      context: { ...config.context, ...context },
+      prefix: [config.prefix, prefix.trim()].filter(Boolean).join(":")
+    });
+  };
+  logger.withContext = (context) => {
+    if (!context || typeof context !== "object" || Array.isArray(context))
+      throw new TypeError("context must be an object.");
+    return createDogLogger({
+      ...config,
+      context: { ...config.context, ...context }
+    });
+  };
+  return logger;
+}
+var doglog = createDogLogger();
+
+// src/context.js
+function createRequestLogger(options = {}) {
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw new TypeError("Options must be an object.");
+  if (Object.hasOwn(options, "contextProvider"))
+    throw new TypeError("createRequestLogger owns its context provider.");
+  const storage = new import_node_async_hooks.AsyncLocalStorage();
+  let disposed = false;
+  const logger = createDogLogger({
+    ...options,
+    contextProvider: () => storage.getStore() ?? {}
+  });
+  logger.run = (context, callback, ...args) => {
+    if (disposed) throw new Error("Request logger has been disposed.");
+    if (typeof callback !== "function")
+      throw new TypeError("Request callback must be a function.");
+    const scope = Object.freeze({
+      ...storage.getStore(),
+      ...copyContext(context)
+    });
+    return storage.run(scope, callback, ...args);
+  };
+  logger.getContext = () => ({ ...storage.getStore() });
+  logger.dispose = () => {
+    storage.disable();
+    disposed = true;
+  };
+  return logger;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createRequestLogger
+});

package/dist/index.cjs

@@ -115,6 +115,63 @@ function commentaryIndex(seed, salt, length) {
   return hash % length;
 }
 
+// src/redaction.js
+var defaultKeys = [
+  "password",
+  "passwd",
+  "token",
+  "accessToken",
+  "refreshToken",
+  "authorization",
+  "cookie",
+  "secret",
+  "apiKey"
+];
+var normalize = (key) => key.toLowerCase().replaceAll(/[-_]/g, "");
+function copyContext(context) {
+  if (!context || typeof context !== "object" || Array.isArray(context))
+    throw new TypeError("context must be an object of scalar fields.");
+  for (const value of Object.values(context))
+    if (!(value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)))
+      throw new TypeError(
+        "Context values must be strings, finite numbers, booleans or null."
+      );
+  return { ...context };
+}
+function createRedactor(options) {
+  if (options === false)
+    return { text: (value) => value, context: copyContext };
+  if (options === void 0) options = {};
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw new TypeError("redact must be false or an options object.");
+  const keys = options.keys ?? defaultKeys, values = options.values ?? [], replacement = options.replacement ?? "[REDACTED]";
+  for (const [name, list] of [
+    ["keys", keys],
+    ["values", values]
+  ])
+    if (!Array.isArray(list) || list.length > 100 || !list.every((value) => typeof value === "string" && value.length > 0))
+      throw new TypeError(
+        `Redaction ${name} must contain at most 100 nonempty strings.`
+      );
+  if (typeof replacement !== "string")
+    throw new TypeError("Redaction replacement must be a string.");
+  const protectedKeys = new Set(keys.map(normalize));
+  const literals = [...new Set(values)].sort((a, b) => b.length - a.length);
+  const text = (value) => literals.reduce(
+    (output, secret) => output.split(secret).join(replacement),
+    value
+  );
+  return {
+    text,
+    context: (context) => Object.fromEntries(
+      Object.entries(copyContext(context)).map(([key, value]) => [
+        key,
+        protectedKeys.has(normalize(key)) ? replacement : typeof value === "string" ? text(value) : value
+      ])
+    )
+  };
+}
+
 // src/index.js
 function createDogLogger(options = {}) {
   if (!options || typeof options !== "object" || Array.isArray(options))
@@ -131,6 +188,7 @@ function createDogLogger(options = {}) {
     prefix: "",
     level: "info",
     context: {},
+    contextProvider: () => ({}),
     write: (line, level) => level === "warn" || level === "error" ? console.error(line) : console.log(line),
     clock: () => /* @__PURE__ */ new Date(),
     ...options
@@ -148,7 +206,16 @@ function createDogLogger(options = {}) {
       throw new TypeError(
         "Context values must be strings, finite numbers, booleans or null."
       );
-  config.context = { ...config.context };
+  config.context = copyContext(config.context);
+  if (typeof config.contextProvider !== "function")
+    throw new TypeError("contextProvider must be a function.");
+  const redactor = createRedactor(config.redact);
+  if (config.redact !== false)
+    config.redact = {
+      ...config.redact,
+      ...config.redact?.keys ? { keys: [...config.redact.keys] } : {},
+      ...config.redact?.values ? { values: [...config.redact.values] } : {}
+    };
   if (typeof config.level !== "string" || !Object.hasOwn(levels, config.level))
     throw new RangeError(
       `level must be one of: ${Object.keys(levels).join(", ")}.`
@@ -166,7 +233,11 @@ function createDogLogger(options = {}) {
       (...args) => {
         if (config.quiet || style.rank < levels[config.level].rank)
           return void 0;
-        const message = (0, import_node_util.format)(...args);
+        const message = redactor.text((0, import_node_util.format)(...args));
+        const context = redactor.context({
+          ...config.context,
+          ...copyContext(config.contextProvider())
+        });
         const pool = config.bark ? barkLines(level) : void 0;
         const index = config.barkMode === "rotate" ? (commentaryIndex(
           config.seed,
@@ -186,18 +257,19 @@ function createDogLogger(options = {}) {
           line = JSON.stringify({
             level,
             message,
-            ...Object.keys(config.context).length ? { context: { ...config.context } } : {},
+            ...Object.keys(context).length ? { context } : {},
             ...commentary ? { commentary } : {},
-            ...config.prefix ? { prefix: config.prefix } : {},
+            ...config.prefix ? { prefix: redactor.text(config.prefix) } : {},
             ...timestamp ? { timestamp } : {}
           });
         } else {
           line = [
             timestamp,
-            config.prefix,
+            redactor.text(config.prefix),
             config.emoji ? style.emoji : void 0,
             level.toUpperCase().padEnd(7),
             message,
+            Object.keys(context).length ? JSON.stringify(context) : void 0,
             commentary
           ].filter((part) => part !== void 0 && part !== "").join(" ");
           if (config.color) line = `\x1B[${style.color}m${line}\x1B[0m`;

package/examples/basic.js

@@ -0,0 +1,7 @@
+import { doglog, createDogLogger } from "@deployanyway/doggo-log";
+
+doglog.info("Server started");
+doglog.success("Tests passed");
+doglog.warn("API is getting slow");
+doglog.error("Database connection failed");
+createDogLogger({ json: true, prefix: "demo" }).info("Ready");

package/examples/fetch-context.mjs

@@ -0,0 +1,55 @@
+import { createServer, get } from "node:http";
+import { setImmediate as tick } from "node:timers/promises";
+import { createRequestLogger } from "@deployanyway/doggo-log/context";
+const log = createRequestLogger({
+    json: true,
+    context: { service: "demo-api" },
+  }),
+  db = log.child("database");
+let nextId = 0;
+const server = createServer((request, response) => {
+  void log.run(
+    {
+      requestId: String(++nextId),
+      authorization: request.headers.authorization ?? null,
+    },
+    async () => {
+      try {
+        log.info("Request started");
+        await tick();
+        db.info("Query complete");
+        response.end(JSON.stringify({ requestId: log.getContext().requestId }));
+      } catch (error) {
+        log.error(error.message);
+        response.statusCode = 500;
+        response.end("Failed");
+      }
+    },
+  );
+});
+await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+const port = server.address().port;
+try {
+  const request = () =>
+    new Promise((resolve, reject) => {
+      get(
+        {
+          hostname: "127.0.0.1",
+          port,
+          headers: { authorization: "demo-only-secret" },
+        },
+        (response) => {
+          response.resume();
+          response.on("end", () =>
+            response.statusCode === 200
+              ? resolve()
+              : reject(new Error("HTTP failed")),
+          );
+        },
+      ).on("error", reject);
+    });
+  await Promise.all([request(), request()]);
+} finally {
+  await new Promise((resolve) => server.close(resolve));
+  log.dispose();
+}

package/index.d.cts

@@ -1,6 +1,9 @@
 export type Level = "debug" | "log" | "info" | "success" | "warn" | "error";
 export type LogContext = Record<string, string | number | boolean | null>;
 export interface DogOptions {
+  /** Defaults to common credential context keys. Literal values also redact formatted messages. */
+  redact?: false | { keys?: string[]; values?: string[]; replacement?: string };
+  contextProvider?: () => LogContext;
   emoji?: boolean;
   bark?: boolean;
   barkMode?: "classic" | "rotate";

package/index.d.ts

@@ -1,6 +1,9 @@
 export type Level = "debug" | "log" | "info" | "success" | "warn" | "error";
 export type LogContext = Record<string, string | number | boolean | null>;
 export interface DogOptions {
+  /** Defaults to common credential context keys. Literal values also redact formatted messages. */
+  redact?: false | { keys?: string[]; values?: string[]; replacement?: string };
+  contextProvider?: () => LogContext;
   emoji?: boolean;
   bark?: boolean;
   barkMode?: "classic" | "rotate";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deployanyway/doggo-log",
-  "version": "0.4.0",
-  "description": "A tiny Node.js console logger with JSON output, log levels, and dog emojis. Good logs. Very good logs.",
+  "version": "1.0.0",
+  "description": "Node.js logs with async request context, JSON, levels and configurable redaction. Good logs. Very good logs. Fewer lost request IDs.",
   "type": "module",
   "exports": {
     ".": {
@@ -13,6 +13,16 @@
         "types": "./index.d.cts",
         "default": "./dist/index.cjs"
       }
+    },
+    "./context": {
+      "import": {
+        "types": "./context.d.ts",
+        "default": "./src/context.js"
+      },
+      "require": {
+        "types": "./context.d.cts",
+        "default": "./dist/context.cjs"
+      }
     }
   },
   "bin": {
@@ -27,7 +37,10 @@
     "dist",
     "index.d.ts",
     "index.d.cts",
-    "MIGRATION.md"
+    "MIGRATION.md",
+    "context.d.ts",
+    "context.d.cts",
+    "examples"
   ],
   "engines": {
     "node": ">=22.13"
@@ -76,7 +89,10 @@
     "dog",
     "typescript",
     "humor",
-    "deployanyway"
+    "deployanyway",
+    "async-local-storage",
+    "request-id",
+    "redaction"
   ],
   "main": "./dist/index.cjs",
   "types": "./index.d.ts",

package/src/cli.js

@@ -15,6 +15,8 @@ try {
       json: { type: "boolean" },
       stdin: { type: "boolean" },
       context: { type: "string" },
+      "redact-keys": { type: "string" },
+      "redact-values": { type: "string" },
       "no-color": { type: "boolean" },
       bark: { type: "boolean" },
       "bark-mode": { type: "string" },
@@ -29,7 +31,7 @@ try {
   });
   if (values.help) {
     console.log(
-      "Usage: doggo-log <method> <message> [options]\n\nMethods: log, info, success, warn, error, debug. --stdin reads a bounded message; arguments win. --context accepts JSON scalar fields for JSON logs; --no-color and NO_COLOR disable ANSI.\nOptions:\n  --bark         Add useful dog commentary\n  --bark-mode classic|rotate  Classic line or varied commentary\n  --seed text    Repeatable rotation starting point\n  --json         Emit JSON\n  --timestamp    Include an ISO timestamp\n  --no-emoji     Disable emojis\n  --color        Enable ANSI colors\n  --prefix text  Add a prefix\n  --level name   Minimum level (CLI default: debug)\n  --quiet        Suppress output\n  -h, --help     Show help\n  -v, --version  Show version\n\nExit codes: 0 success; 2 invalid arguments. Logging an error exits 0.",
+      "Usage: doggo-log <method> <message> [options]\n\nMethods: log, info, success, warn, error, debug. Credential context keys redact by default. --redact-keys accepts comma-separated keys; --redact-values accepts a JSON string array. Async request scopes use the Node /context API. --stdin reads a bounded message; arguments win. --context accepts JSON scalar fields for JSON logs; --no-color and NO_COLOR disable ANSI.\nOptions:\n  --bark         Add useful dog commentary\n  --bark-mode classic|rotate  Classic line or varied commentary\n  --seed text    Repeatable rotation starting point\n  --json         Emit JSON\n  --timestamp    Include an ISO timestamp\n  --no-emoji     Disable emojis\n  --color        Enable ANSI colors\n  --prefix text  Add a prefix\n  --level name   Minimum level (CLI default: debug)\n  --quiet        Suppress output\n  -h, --help     Show help\n  -v, --version  Show version\n\nExit codes: 0 success; 2 invalid arguments. Logging an error exits 0.",
     );
   } else if (values.version) {
     console.log(
@@ -56,6 +58,14 @@ try {
         !Object.hasOwn(process.env, "NO_COLOR") &&
         (values.color ?? false),
       context: values.context === undefined ? {} : JSON.parse(values.context),
+      redact: {
+        ...(values["redact-keys"] !== undefined
+          ? { keys: values["redact-keys"].split(",") }
+          : {}),
+        ...(values["redact-values"] !== undefined
+          ? { values: JSON.parse(values["redact-values"]) }
+          : {}),
+      },
       timestamp: values.timestamp ?? false,
       json: values.json ?? false,
       quiet: values.quiet ?? false,

package/src/context.js

@@ -0,0 +1,33 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createDogLogger } from "./index.js";
+import { copyContext } from "./redaction.js";
+
+/** A Node logger with isolated async request scopes. Dispose only after work completes. */
+export function createRequestLogger(options = {}) {
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw new TypeError("Options must be an object.");
+  if (Object.hasOwn(options, "contextProvider"))
+    throw new TypeError("createRequestLogger owns its context provider.");
+  const storage = new AsyncLocalStorage();
+  let disposed = false;
+  const logger = createDogLogger({
+    ...options,
+    contextProvider: () => storage.getStore() ?? {},
+  });
+  logger.run = (context, callback, ...args) => {
+    if (disposed) throw new Error("Request logger has been disposed.");
+    if (typeof callback !== "function")
+      throw new TypeError("Request callback must be a function.");
+    const scope = Object.freeze({
+      ...storage.getStore(),
+      ...copyContext(context),
+    });
+    return storage.run(scope, callback, ...args);
+  };
+  logger.getContext = () => ({ ...storage.getStore() });
+  logger.dispose = () => {
+    storage.disable();
+    disposed = true;
+  };
+  return logger;
+}

package/src/index.js

@@ -1,6 +1,7 @@
 import { format } from "node:util";
 import { levels } from "./levels.js";
 import { barkLines, commentaryIndex } from "./commentary.js";
+import { copyContext, createRedactor } from "./redaction.js";
 export { barkLines };
 
 /**
@@ -22,6 +23,7 @@ export function createDogLogger(options = {}) {
     prefix: "",
     level: "info",
     context: {},
+    contextProvider: () => ({}),
     write: (line, level) =>
       level === "warn" || level === "error"
         ? console.error(line)
@@ -51,7 +53,16 @@ export function createDogLogger(options = {}) {
       throw new TypeError(
         "Context values must be strings, finite numbers, booleans or null.",
       );
-  config.context = { ...config.context };
+  config.context = copyContext(config.context);
+  if (typeof config.contextProvider !== "function")
+    throw new TypeError("contextProvider must be a function.");
+  const redactor = createRedactor(config.redact);
+  if (config.redact !== false)
+    config.redact = {
+      ...config.redact,
+      ...(config.redact?.keys ? { keys: [...config.redact.keys] } : {}),
+      ...(config.redact?.values ? { values: [...config.redact.values] } : {}),
+    };
   if (typeof config.level !== "string" || !Object.hasOwn(levels, config.level))
     throw new RangeError(
       `level must be one of: ${Object.keys(levels).join(", ")}.`,
@@ -73,7 +84,11 @@ export function createDogLogger(options = {}) {
       (...args) => {
         if (config.quiet || style.rank < levels[config.level].rank)
           return undefined;
-        const message = format(...args);
+        const message = redactor.text(format(...args));
+        const context = redactor.context({
+          ...config.context,
+          ...copyContext(config.contextProvider()),
+        });
         const pool = config.bark ? barkLines(level) : undefined;
         const index =
           config.barkMode === "rotate"
@@ -98,20 +113,19 @@ export function createDogLogger(options = {}) {
           line = JSON.stringify({
             level,
             message,
-            ...(Object.keys(config.context).length
-              ? { context: { ...config.context } }
-              : {}),
+            ...(Object.keys(context).length ? { context } : {}),
             ...(commentary ? { commentary } : {}),
-            ...(config.prefix ? { prefix: config.prefix } : {}),
+            ...(config.prefix ? { prefix: redactor.text(config.prefix) } : {}),
             ...(timestamp ? { timestamp } : {}),
           });
         } else {
           line = [
             timestamp,
-            config.prefix,
+            redactor.text(config.prefix),
             config.emoji ? style.emoji : undefined,
             level.toUpperCase().padEnd(7),
             message,
+            Object.keys(context).length ? JSON.stringify(context) : undefined,
             commentary,
           ]
             .filter((part) => part !== undefined && part !== "")

package/src/redaction.js

@@ -0,0 +1,73 @@
+const defaultKeys = [
+  "password",
+  "passwd",
+  "token",
+  "accessToken",
+  "refreshToken",
+  "authorization",
+  "cookie",
+  "secret",
+  "apiKey",
+];
+const normalize = (key) => key.toLowerCase().replaceAll(/[-_]/g, "");
+export function copyContext(context) {
+  if (!context || typeof context !== "object" || Array.isArray(context))
+    throw new TypeError("context must be an object of scalar fields.");
+  for (const value of Object.values(context))
+    if (!(
+      value === null ||
+      typeof value === "string" ||
+      typeof value === "boolean" ||
+      (typeof value === "number" && Number.isFinite(value))
+    ))
+      throw new TypeError(
+        "Context values must be strings, finite numbers, booleans or null.",
+      );
+  return { ...context };
+}
+export function createRedactor(options) {
+  if (options === false)
+    return { text: (value) => value, context: copyContext };
+  if (options === undefined) options = {};
+  if (!options || typeof options !== "object" || Array.isArray(options))
+    throw new TypeError("redact must be false or an options object.");
+  const keys = options.keys ?? defaultKeys,
+    values = options.values ?? [],
+    replacement = options.replacement ?? "[REDACTED]";
+  for (const [name, list] of [
+    ["keys", keys],
+    ["values", values],
+  ])
+    if (
+      !Array.isArray(list) ||
+      list.length > 100 ||
+      !list.every((value) => typeof value === "string" && value.length > 0)
+    )
+      throw new TypeError(
+        `Redaction ${name} must contain at most 100 nonempty strings.`,
+      );
+  if (typeof replacement !== "string")
+    throw new TypeError("Redaction replacement must be a string.");
+  const protectedKeys = new Set(keys.map(normalize));
+  // Longest first prevents a short secret from exposing a suffix of a longer one.
+  const literals = [...new Set(values)].sort((a, b) => b.length - a.length);
+  const text = (value) =>
+    literals.reduce(
+      (output, secret) => output.split(secret).join(replacement),
+      value,
+    );
+  return {
+    text,
+    context: (context) =>
+      Object.fromEntries(
+        Object.entries(copyContext(context)).map(([key, value]) => [
+          key,
+          protectedKeys.has(normalize(key))
+            ? replacement
+            : typeof value === "string"
+              ? text(value)
+              : value,
+        ]),
+      ),
+  };
+}