@deployanyway/doggo-log 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.0 — 2026-10-08
+
+- Useful structured API/CLI additions described in README.
+- TypeScript declarations, CommonJS entry, coverage gates and installed archive checks.
+- Linux Node 22/24 plus Windows/macOS Node 24 CI.
+
 ## 0.2.0 — 2026-10-08
 
 - Scoped logs, optional barks: Use `logger.child("database")` to create an independent logger with a nested prefix. Enable `{ bark: true }` or CLI `--bark` for dog commentary. JSON preserves the original message and adds a separate `commentary` field. Filtering still suppresses output.

package/MIGRATION.md

@@ -0,0 +1,5 @@
+# 0.3.0 migration
+
+Node 22.13+ is required. Existing core APIs remain available; TypeScript declarations and CommonJS exports are new. The CLI now lives in src/cli.js behind the same executable path. Input/stdout behavior for new options is documented in README.
+
+Install 0.3.0 with npm. Seeds and exact humorous wording are version-specific. Do not treat jokes or heuristic scores as production evidence.

package/README.md

@@ -1,5 +1,7 @@
 # doggo-log
 
+> **Version 0.3.0:** install from npm with Node 22.13+ or Node 24. See MIGRATION.md for changes from 0.2.0.
+
 [![npm version](https://img.shields.io/npm/v/%40deployanyway%2Fdoggo-log)](https://www.npmjs.com/package/@deployanyway/doggo-log)
 [![CI](https://github.com/DeployAnyway/doggo-log/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/DeployAnyway/doggo-log/actions/workflows/ci.yml)
 
@@ -159,3 +161,42 @@ createDogLogger({ bark: true, prefix: "api" })
   .child("database")
   .success("Migration complete");
 ```
+
+## Give your dog a request ID
+
+```js
+import { createDogLogger } from "@deployanyway/doggo-log";
+const log = createDogLogger({ json: true, context: { service: "api" } });
+const requestLog = log.child("request", { requestId: "abc" });
+requestLog.info("Fetching the evidence.");
+log.withContext({ retry: 1 }).warn("Suspicious squirrel detected.");
+```
+
+JSON records carry a separate context object. Fields must be strings, finite numbers, booleans or null. Configuration is copied; children override fields without mutating parents. Context is intentionally omitted from plain output. Nested data is rejected rather than producing circular or ambiguous logs. Do not log secrets; this is not a redaction framework.
+
+```sh
+echo "Build passed" | node bin/cli.js success --stdin --bark
+node bin/cli.js info "Request accepted" --json --context '{"requestId":"abc"}'
+```
+
+--stdin explicitly reads UTF-8 input up to 256 KiB; message arguments win. Warn/error go to stderr, other methods to stdout. Logging error still exits 0; malformed configuration exits 2. --no-color and NO_COLOR win over --color. PowerShell quoting differs from POSIX shells; use a simple JSON file or the API when shell quoting becomes the least funny part.
+
+## Run from source
+
+```sh
+git clone --branch main https://github.com/DeployAnyway/doggo-log.git
+cd doggo-log
+npm ci
+npm run build
+node bin/cli.js --help
+```
+
+## Candidate quality standard
+
+Version 0.3 provides useful declaration types, ESM/CommonJS exports, installed-archive checks, and coverage gates (90% statements/lines/functions, 85% branches). CI covers Linux Node 22/24 and Windows/macOS Node 24. Node 22.13+ is required. No runtime dependencies, telemetry or network requests.
+
+From a source checkout: npm ci, npm run build, npm run coverage, npm run test:types, npm run verify:package. Pack verification installs a temporary local archive and checks module entries, types, executable and offline npm exec.
+
+[Contribution guide](CONTRIBUTING.md) · [Conduct](CODE_OF_CONDUCT.md) · [Security](SECURITY.md) · [Roadmap](ROADMAP.md) · [Migration](MIGRATION.md).
+
+**Tools for developers who probably know better.** Software nobody requested, built with questionable priorities, and shipped with absolute confidence!

package/bin/cli.js

@@ -1,53 +1,2 @@
 #!/usr/bin/env node
-import { parseArgs } from "node:util";
-import { readFileSync } from "node:fs";
-import { URL } from "node:url";
-import { createDogLogger } from "../src/index.js";
-import { levels } from "../src/levels.js";
-
-try {
-  const { values, positionals } = parseArgs({
-    allowPositionals: true,
-    options: {
-      help: { type: "boolean", short: "h" },
-      version: { type: "boolean", short: "v" },
-      json: { type: "boolean" },
-      bark: { type: "boolean" },
-      timestamp: { type: "boolean" },
-      quiet: { type: "boolean" },
-      color: { type: "boolean" },
-      "no-emoji": { type: "boolean" },
-      prefix: { type: "string" },
-      level: { type: "string", default: "debug" },
-    },
-  });
-  if (values.help) {
-    console.log(
-      "Usage: doggo-log <method> <message> [options]\n\nMethods: log, info, success, warn, error, debug\nOptions:\n  --bark         Add useful dog commentary\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(
-      JSON.parse(
-        readFileSync(new URL("../package.json", import.meta.url), "utf8"),
-      ).version,
-    );
-  } else {
-    const [method, ...message] = positionals;
-    if (!Object.hasOwn(levels, method ?? "") || !message.join(" ").trim())
-      throw new TypeError("Provide a valid method and nonempty message.");
-    const logger = createDogLogger({
-      emoji: !values["no-emoji"],
-      bark: values.bark ?? false,
-      color: values.color ?? false,
-      timestamp: values.timestamp ?? false,
-      json: values.json ?? false,
-      quiet: values.quiet ?? false,
-      prefix: values.prefix ?? "",
-      level: values.level,
-    });
-    logger[method](message.join(" "));
-  }
-} catch (error) {
-  console.error(`doggo-log: ${error.message}\nRun with --help for usage.`);
-  process.exitCode = 2;
-}
+import "../src/cli.js";

package/dist/index.cjs

@@ -0,0 +1,152 @@
+"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/index.js
+var index_exports = {};
+__export(index_exports, {
+  createDogLogger: () => createDogLogger,
+  doglog: () => doglog
+});
+module.exports = __toCommonJS(index_exports);
+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/index.js
+var barks = {
+  debug: "Sniffing for clues.",
+  log: "Filed under things I sniffed.",
+  info: "Good to know. Good dog to tell you.",
+  success: "Treat budget approved.",
+  warn: "Suspicious squirrel detected.",
+  error: "The dog has fetched the incident report."
+};
+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,
+    color: false,
+    timestamp: false,
+    json: false,
+    quiet: false,
+    prefix: "",
+    level: "info",
+    context: {},
+    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 = { ...config.context };
+  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.");
+  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 = (0, import_node_util.format)(...args);
+        const commentary = config.bark ? barks[level] : void 0;
+        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(config.context).length ? { context: { ...config.context } } : {},
+            ...commentary ? { commentary } : {},
+            ...config.prefix ? { prefix: config.prefix } : {},
+            ...timestamp ? { timestamp } : {}
+          });
+        } else {
+          line = [
+            timestamp,
+            config.prefix,
+            config.emoji ? style.emoji : void 0,
+            level.toUpperCase().padEnd(7),
+            message,
+            commentary
+          ].filter((part) => part !== void 0 && part !== "").join(" ");
+          if (config.color) line = `\x1B[${style.color}m${line}\x1B[0m`;
+        }
+        config.write(line, level);
+        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();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createDogLogger,
+  doglog
+});

package/index.d.cts

@@ -0,0 +1,22 @@
+export type Level = "debug" | "log" | "info" | "success" | "warn" | "error";
+export type LogContext = Record<string, string | number | boolean | null>;
+export interface DogOptions {
+  emoji?: boolean;
+  bark?: boolean;
+  color?: boolean;
+  timestamp?: boolean;
+  json?: boolean;
+  quiet?: boolean;
+  prefix?: string;
+  level?: Level;
+  context?: LogContext;
+  write?: (line: string, level: Level) => void;
+  clock?: () => Date;
+}
+export type LogMethod = (...args: unknown[]) => string | undefined;
+export type DogLogger = Record<Level, LogMethod> & {
+  child(prefix: string, context?: LogContext): DogLogger;
+  withContext(context: LogContext): DogLogger;
+};
+export function createDogLogger(options?: DogOptions): DogLogger;
+export const doglog: DogLogger;

package/index.d.ts

@@ -0,0 +1,22 @@
+export type Level = "debug" | "log" | "info" | "success" | "warn" | "error";
+export type LogContext = Record<string, string | number | boolean | null>;
+export interface DogOptions {
+  emoji?: boolean;
+  bark?: boolean;
+  color?: boolean;
+  timestamp?: boolean;
+  json?: boolean;
+  quiet?: boolean;
+  prefix?: string;
+  level?: Level;
+  context?: LogContext;
+  write?: (line: string, level: Level) => void;
+  clock?: () => Date;
+}
+export type LogMethod = (...args: unknown[]) => string | undefined;
+export type DogLogger = Record<Level, LogMethod> & {
+  child(prefix: string, context?: LogContext): DogLogger;
+  withContext(context: LogContext): DogLogger;
+};
+export function createDogLogger(options?: DogOptions): DogLogger;
+export const doglog: DogLogger;

package/package.json

@@ -1,9 +1,20 @@
 {
   "name": "@deployanyway/doggo-log",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A tiny Node.js console logger with JSON output, log levels, and dog emojis. Good logs. Very good logs.",
   "type": "module",
-  "exports": "./src/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./src/index.js"
+      },
+      "require": {
+        "types": "./index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
   "bin": {
     "doggo-log": "./bin/cli.js"
   },
@@ -12,16 +23,26 @@
     "bin",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "dist",
+    "index.d.ts",
+    "index.d.cts",
+    "MIGRATION.md"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.13"
   },
   "scripts": {
-    "test": "node --test",
+    "test": "node --test test/*.test.js",
     "lint": "eslint .",
     "format": "prettier --write .",
-    "format:check": "prettier --check ."
+    "format:check": "prettier --check .",
+    "build": "node scripts/build.mjs",
+    "pretest": "npm run build",
+    "prepack": "npm run build",
+    "coverage": "c8 --all --include=src/**/*.js --reporter=text --reporter=json-summary --reporter=lcov --check-coverage --lines=90 --statements=90 --functions=90 --branches=85 node --test test/*.test.js",
+    "test:types": "tsc -p tsconfig.json",
+    "verify:package": "node scripts/verify-package.mjs"
   },
   "repository": {
     "type": "git",
@@ -35,8 +56,12 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/node": "^26.6.4",
+    "c8": "^12.0.0",
+    "esbuild": "^0.28.2",
     "eslint": "^10.12.0",
-    "prettier": "^3.6.2"
+    "prettier": "^3.6.2",
+    "typescript": "^7.0.2"
   },
   "keywords": [
     "nodejs",
@@ -48,6 +73,12 @@
     "console",
     "json",
     "log-levels",
-    "dog"
-  ]
+    "dog",
+    "typescript",
+    "humor",
+    "deployanyway"
+  ],
+  "main": "./dist/index.cjs",
+  "types": "./index.d.ts",
+  "homepage": "https://deployanyway.github.io/"
 }

package/src/cli.js

@@ -0,0 +1,66 @@
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { URL } from "node:url";
+import { createDogLogger } from "./index.js";
+import { levels } from "./levels.js";
+
+import { readStdin } from "./input.js";
+
+try {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+      json: { type: "boolean" },
+      stdin: { type: "boolean" },
+      context: { type: "string" },
+      "no-color": { type: "boolean" },
+      bark: { type: "boolean" },
+      timestamp: { type: "boolean" },
+      quiet: { type: "boolean" },
+      color: { type: "boolean" },
+      "no-emoji": { type: "boolean" },
+      prefix: { type: "string" },
+      level: { type: "string", default: "debug" },
+    },
+  });
+  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  --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(
+      JSON.parse(
+        readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+      ).version,
+    );
+  } else {
+    const [method, ...message] = positionals;
+    const text = message.length
+      ? message.join(" ")
+      : values.stdin
+        ? await readStdin()
+        : "";
+    if (!Object.hasOwn(levels, method ?? "") || !text.trim())
+      throw new TypeError("Provide a valid method and nonempty message.");
+    const logger = createDogLogger({
+      emoji: !values["no-emoji"],
+      bark: values.bark ?? false,
+      color:
+        !values["no-color"] &&
+        !Object.hasOwn(process.env, "NO_COLOR") &&
+        (values.color ?? false),
+      context: values.context === undefined ? {} : JSON.parse(values.context),
+      timestamp: values.timestamp ?? false,
+      json: values.json ?? false,
+      quiet: values.quiet ?? false,
+      prefix: values.prefix ?? "",
+      level: values.level,
+    });
+    logger[method](text);
+  }
+} catch (error) {
+  console.error(`doggo-log: ${error.message}\nRun with --help for usage.`);
+  process.exitCode = 2;
+}

package/src/index.js

@@ -25,6 +25,7 @@ export function createDogLogger(options = {}) {
     quiet: false,
     prefix: "",
     level: "info",
+    context: {},
     write: (line, level) =>
       level === "warn" || level === "error"
         ? console.error(line)
@@ -38,6 +39,23 @@ export function createDogLogger(options = {}) {
   }
   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 = { ...config.context };
   if (typeof config.level !== "string" || !Object.hasOwn(levels, config.level))
     throw new RangeError(
       `level must be one of: ${Object.keys(levels).join(", ")}.`,
@@ -64,6 +82,9 @@ export function createDogLogger(options = {}) {
           line = JSON.stringify({
             level,
             message,
+            ...(Object.keys(config.context).length
+              ? { context: { ...config.context } }
+              : {}),
             ...(commentary ? { commentary } : {}),
             ...(config.prefix ? { prefix: config.prefix } : {}),
             ...(timestamp ? { timestamp } : {}),
@@ -86,14 +107,25 @@ export function createDogLogger(options = {}) {
       },
     ]),
   );
-  logger.child = (prefix) => {
+  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;
 }
 

package/src/input.js

@@ -0,0 +1,15 @@
+/** Read bounded UTF-8 stdin without swallowing upstream failures. */
+export async function readStdin(stream = process.stdin) {
+  if (stream.isTTY) throw new TypeError("Pipe or redirect input.");
+  let size = 0;
+  const chunks = [];
+  for await (const chunk of stream) {
+    const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+    size += buffer.length;
+    if (size > 262144) throw new RangeError("stdin exceeds 256 KiB.");
+    chunks.push(buffer);
+  }
+  const text = Buffer.concat(chunks).toString("utf8").trim();
+  if (!text) throw new TypeError("Provide nonempty input.");
+  return text;
+}