@meadown/logger 1.8.10 → 1.9.0

package/dist/features/logger-tap/tapAsync/helpers/isThenable.js

@@ -0,0 +1,12 @@
+/*
+ * isThenable.ts
+ * Created by Dewan Mobashirul
+ * Copyright (c) 2026 meadown
+ * All rights reserved
+ */
+/** Whether `value` is thenable (a promise we can await + time). */
+export function isThenable(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.then === "function");
+}

package/dist/features/logger-tap/tapAsync/helpers/response.d.ts

@@ -0,0 +1,21 @@
+export type ResponseLike = {
+    status: number;
+    statusText?: unknown;
+    headers?: {
+        get?: (name: string) => string | null;
+    };
+    clone: () => ResponseLike;
+    text: () => Promise<string>;
+};
+/** Whether the resolved value is a fetch `Response` we can read. */
+export declare function isResponse(value: unknown): value is ResponseLike;
+export declare function formatStatus(res: ResponseLike, useColor: boolean): string;
+/**
+ * Reads a (cloned) response body and returns both the parsed value and the
+ * actual byte size. Size is calculated from the body text — not `Content-Length`,
+ * which is absent on compressed responses — so size is always shown.
+ */
+export declare function readBody(res: ResponseLike): Promise<{
+    data: unknown;
+    size: string;
+}>;

package/dist/features/logger-tap/tapAsync/helpers/response.js

@@ -0,0 +1,57 @@
+/*
+ * response.ts
+ * Created by Dewan Mobashirul
+ * Copyright (c) 2026 meadown
+ * All rights reserved
+ */
+import { formatBytes } from "./format.js";
+import { colorize } from "../../../../domain/colors/color.js";
+/** Whether the resolved value is a fetch `Response` we can read. */
+export function isResponse(value) {
+    const v = value;
+    return (typeof v?.status === "number" &&
+        typeof v.clone === "function" &&
+        typeof v.text === "function");
+}
+/**
+ * Status badge color:
+ * 2xx → green · 3xx → cyan · 4xx → yellow · 5xx → red
+ */
+function statusColor(status) {
+    if (status >= 500)
+        return "red";
+    if (status >= 400)
+        return "yellow";
+    if (status >= 300)
+        return "cyan";
+    return "green";
+}
+export function formatStatus(res, useColor) {
+    const text = typeof res.statusText === "string" && res.statusText
+        ? `${res.status} ${res.statusText}`
+        : `${res.status}`;
+    return useColor ? colorize(text, statusColor(res.status)) : text;
+}
+/**
+ * Reads a (cloned) response body and returns both the parsed value and the
+ * actual byte size. Size is calculated from the body text — not `Content-Length`,
+ * which is absent on compressed responses — so size is always shown.
+ */
+export async function readBody(res) {
+    try {
+        const text = await res.text();
+        const bytes = new TextEncoder().encode(text).length;
+        const size = formatBytes(bytes);
+        if (text === "")
+            return { data: undefined, size };
+        try {
+            return { data: JSON.parse(text), size };
+        }
+        catch {
+            return { data: text, size };
+        }
+    }
+    catch {
+        return { data: undefined, size: "unknown" };
+    }
+}

package/dist/features/logger-tap/tapAsync/index.d.ts

@@ -0,0 +1,2 @@
+export { tapAsync } from "./tapAsync.js";
+export { isThenable } from "./helpers/index.js";

package/dist/features/logger-tap/tapAsync/index.js

@@ -0,0 +1,8 @@
+/*
+ * index.ts
+ * Created by Dewan Mobashirul
+ * Copyright (c) 2026 meadown
+ * All rights reserved
+ */
+export { tapAsync } from "./tapAsync.js";
+export { isThenable } from "./helpers/index.js";

package/dist/{tap → features/logger-tap/tapAsync}/tapAsync.d.ts

@@ -1,6 +1,4 @@
-import { type Caller } from "../caller/getCaller.js";
-/** Whether `value` is thenable (a promise we can await + time). */
-export declare function isThenable(value: unknown): value is PromiseLike<unknown>;
+import { type Caller } from "../../../domain/caller/getCaller.js";
 /**
  * The async tap. Fire-and-forget: returns `promise` immediately (unchanged),
  * and logs a rich block once it resolves. For a `Response`, reads the body from

package/dist/features/logger-tap/tapAsync/tapAsync.js

@@ -0,0 +1,92 @@
+/*
+ * tapAsync.ts
+ * Created by Dewan Mobashirul
+ * Copyright (c) 2026 meadown
+ * All rights reserved
+ */
+import { performance } from "node:perf_hooks";
+import { formatDuration, formatBytes, isResponse, readBody, buildBlock, } from "./helpers/index.js";
+import { isTTY } from "../../../domain/terminal/isTTY.js";
+import { writeLog } from "../../../domain/write/index.js";
+import { isLogAllowed } from "../../../config/index.js";
+/**
+ * The async tap. Fire-and-forget: returns `promise` immediately (unchanged),
+ * and logs a rich block once it resolves. For a `Response`, reads the body from
+ * a clone so the caller's original stays consumable. A rejection logs an error
+ * to stderr. `caller` MUST be resolved by `tap` (the user-facing function) so
+ * the logged location points at the user's file.
+ */
+export function tapAsync(promise, label, caller) {
+    if (!isLogAllowed())
+        return;
+    const useColor = isTTY("stdout");
+    const start = performance.now();
+    void promise.then((resolved) => {
+        const ms = Math.round(performance.now() - start);
+        if (isResponse(resolved)) {
+            let clone = null;
+            try {
+                clone = resolved.clone();
+            }
+            catch {
+                clone = null;
+            }
+            if (clone === null) {
+                writeLog({
+                    channel: "log",
+                    tag: "[TAP]",
+                    args: buildBlock(label, ms, resolved, { data: undefined, size: "unknown" }, useColor),
+                    caller,
+                });
+                return;
+            }
+            const cl = resolved.headers?.get?.("content-length");
+            const tooLarge = cl != null && cl !== "" && Number(cl) > 512 * 1024;
+            if (tooLarge) {
+                writeLog({
+                    channel: "log",
+                    tag: "[TAP]",
+                    args: buildBlock(label, ms, resolved, {
+                        data: "(body too large to display)",
+                        size: formatBytes(Number(cl)),
+                    }, useColor),
+                    caller,
+                });
+                return;
+            }
+            void readBody(clone).then((body) => {
+                writeLog({
+                    channel: "log",
+                    tag: "[TAP]",
+                    args: buildBlock(label, ms, resolved, body, useColor),
+                    caller,
+                });
+            });
+            return;
+        }
+        // Non-Response promise — plain value with elapsed time.
+        const elapsed = formatDuration(ms, useColor);
+        writeLog({
+            channel: "log",
+            tag: "[TAP]",
+            args: label === undefined
+                ? [elapsed, resolved]
+                : [`${label} ${elapsed}`, resolved],
+            caller,
+        });
+    }, (err) => {
+        const ms = Math.round(performance.now() - start);
+        const elapsed = formatDuration(ms, useColor);
+        writeLog({
+            channel: "error",
+            tag: "[ERROR]",
+            args: [
+                label === undefined
+                    ? `rejected after ${elapsed}`
+                    : `${label} rejected after ${elapsed}`,
+                err,
+            ],
+            caller,
+        });
+    });
+}

package/dist/features/logger-warn/index.d.ts

@@ -0,0 +1 @@
+export default function logWarn(...args: unknown[]): void;

package/dist/features/logger-warn/index.js

@@ -0,0 +1,15 @@
+/*
+ * index.ts
+ * Created by Dewan Mobashirul
+ * Copyright (c) 2026 meadown
+ * All rights reserved
+ */
+import { isLogAllowed } from "../../config/index.js";
+import getCaller from "../../domain/caller/getCaller.js";
+import { writeLog } from "../../domain/write/writeLog.js";
+export default function logWarn(...args) {
+    if (!isLogAllowed())
+        return;
+    const caller = getCaller();
+    writeLog({ channel: "warn", tag: "[WARN]", args, caller });
+}

package/dist/index.d.ts

@@ -1,32 +1,77 @@
-/** The logger: a callable for info logs, plus `.error`, `.warn`, and `.tap`. */
-export interface LogFN {
+import { type Tap } from "./features/logger-tap/index.js";
+import { type Group } from "./features/logger-group/index.js";
+/** Type of the logger — use this to annotate variables or parameters that accept it. */
+export interface Logger {
+    /** Log at info level — `stdout`, cyan `[INFO]` tag. */
     (...args: unknown[]): void;
+    /** Log at error level — `stderr`, red `[ERROR]` tag. */
     error(...args: unknown[]): void;
+    /** Log at warn level — `stderr`, yellow `[WARN]` tag. */
     warn(...args: unknown[]): void;
     /**
-     * Logs `value` (optionally tagged with `label`) and returns it **unchanged**,
-     * so it drops into any expression: `const u = logger.tap(getUser(), "user")`.
-     * Pass a **promise** (e.g. a `fetch`) and you get the same promise back while
-     * its elapsed time — and the HTTP status if it's a `Response` — is logged in
-     * the background. Silent in production; the value always flows through.
+     * Logs `value` with an optional `label` and gives it straight back unchanged
+     * — so you can drop it into any expression without adding an extra line.
+     *
+     * **Sync value** — logged immediately, returned as-is:
+     * ```ts
+     * const port = logger.tap(3000, "port")       // logs it, port is still 3000
+     * const user = logger.tap(getUser(), "user")  // logs the user object, returns it
+     * ```
+     *
+     * **Promise** — the same promise comes back; timing and HTTP status are logged
+     * in the background once it settles, without blocking your code:
+     * ```ts
+     * const res  = await logger.tap(fetch(url), "GET /users")  // logs status + ms
+     * const data = await logger.tap(loadConfig(), "config")    // logs value + ms
+     * ```
+     *
+     * @param value  Any value or promise — always returned as-is.
+     * @param label  Optional label shown next to the value in the log line.
      */
-    tap<T>(value: T, label?: string): T;
+    tap: Tap;
     /**
-     * How many lines of a multi-line message to show before collapsing the rest
-     * into a `… N more lines` summary. `0` (the default) shows everything.
+     * Log multiple related items as one block under a shared name and single
+     * timestamp. Each item in `logs` renders on its own `├──` branch — any value
+     * is accepted (string, object, function, Promise, …).
+     *
+     * `type` sets the channel and tag color: `"info"` (default), `"warn"`, `"error"`.
+     *
+     * @example
+     * ```ts
+     * logger.group({ name: "Server setup", logs: [`port: ${port}`, `env: ${env}`] })
+     * logger.group({ name: "Validation failed", type: "error", logs: ["email invalid"] })
+     * ```
+     */
+    group: Group;
+    /**
+     * How many lines to show before the rest collapses into a
+     * `… N more lines` summary. `0` (default) shows everything.
+     *
+     * @example
+     * logger.maxLines = 5
      */
     maxLines: number;
 }
 /**
- * Logs to the console, but only outside production. Each line is prefixed with
- * a level tag, a short local timestamp, and a clickable link to the file it was
- * called from; all arguments are then printed as-is.
- * @example
- * logger("Auth", "user logged in")
- * // [INFO] 05-30 04:00:00 PM (server.ts:42) Auth user logged in
+ * A logger built for development — colored tags, a local timestamp, and a
+ * clickable `(file:line)` link on every line so you always know where a
+ * message came from. Works like `console.log`: pass anything and it prints.
+ *
+ * Logs only when `NODE_ENV !== "production"`.
+ *
  * @example
- * logger.maxLines = 5 // long messages collapse to 5 lines; 0 = show all
+ * ```ts
+ * logger("server started", { port: 3000 })
+ * logger.error("db failed", new Error("ECONNREFUSED"))
+ * logger.warn("disk above 80%")
+ * ```
+ *
+ * @example Tap — keep the value flowing, log it on the side
+ * ```ts
+ * const user = logger.tap(await getUser(id), "user")
+ * const res  = await logger.tap(fetch(url), "GET /users")
+ * ```
  */
-declare const logger: LogFN;
+declare const logger: Logger;
 export { logger };
 export default logger;

package/dist/index.js

@@ -1,26 +1,40 @@
 /*
  * index.ts
  * Created by Dewan Mobashirul
- * Copyright (c) 2026 dewan-meadown
+ * Copyright (c) 2026 meadown
  * All rights reserved
  */
-import createLog from "./core/createLog.js";
-import createTap from "./tap/createTap.js";
-import { getVisibleLines, setVisibleLines } from "./core/writeLog/index.js";
+import { getVisibleLines, setVisibleLines, } from "./features/logger-max-lines/index.js";
+import logInfo from "./features/logger/index.js";
+import logWarn from "./features/logger-warn/index.js";
+import logError from "./features/logger-error/index.js";
+import tap from "./features/logger-tap/index.js";
+import group from "./features/logger-group/index.js";
 /**
- * Logs to the console, but only outside production. Each line is prefixed with
- * a level tag, a short local timestamp, and a clickable link to the file it was
- * called from; all arguments are then printed as-is.
+ * A logger built for development — colored tags, a local timestamp, and a
+ * clickable `(file:line)` link on every line so you always know where a
+ * message came from. Works like `console.log`: pass anything and it prints.
+ *
+ * Logs only when `NODE_ENV !== "production"`.
+ *
  * @example
- * logger("Auth", "user logged in")
- * // [INFO] 05-30 04:00:00 PM (server.ts:42) Auth user logged in
- * @example
- * logger.maxLines = 5 // long messages collapse to 5 lines; 0 = show all
+ * ```ts
+ * logger("server started", { port: 3000 })
+ * logger.error("db failed", new Error("ECONNREFUSED"))
+ * logger.warn("disk above 80%")
+ * ```
+ *
+ * @example Tap — keep the value flowing, log it on the side
+ * ```ts
+ * const user = logger.tap(await getUser(id), "user")
+ * const res  = await logger.tap(fetch(url), "GET /users")
+ * ```
  */
-const logger = Object.assign(createLog("log", "[INFO]"), {
-    error: createLog("error", "[ERROR]"),
-    warn: createLog("warn", "[WARN]"),
-    tap: createTap(),
+const logger = Object.assign(logInfo, {
+    error: logError,
+    warn: logWarn,
+    tap,
+    group,
 });
 // `maxLines` is a live getter/setter backed by the shared collapse setting, so
 // setting it once affects info, error, and warn alike.

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+/** The console channels the logger writes to. */
+export type LogChannel = "log" | "error" | "warn";

package/dist/types/index.js

@@ -0,0 +1,7 @@
+/*
+ * index.ts
+ * Created by Dewan Mobashirul
+ * Copyright (c) 2026 meadown
+ * All rights reserved
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meadown/logger",
-  "version": "1.8.10",
+  "version": "1.9.0",
   "description": "A development-focused logger for Node.js and TypeScript — zero dependencies, clickable source links, and API response logging built in.",
   "keywords": [
     "logger",
@@ -53,9 +53,12 @@
     "test": "tsc && node --test \"test/**/*.test.mjs\"",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
-    "demo": "pnpm build && node examples/demo.mjs",
-    "demo:calls": "pnpm build && node examples/call-sites.mjs",
-    "demo:api": "pnpm build && node examples/api.mjs",
+    "demo": "pnpm build && node --experimental-strip-types examples/ts/demo.ts",
+    "demo:calls": "pnpm build && node --experimental-strip-types examples/ts/call-sites.ts",
+    "demo:api": "pnpm build && node --experimental-strip-types examples/ts/api.ts",
+    "demo-mjs": "pnpm build && node examples/mjs/demo.mjs",
+    "demo:calls-mjs": "pnpm build && node examples/mjs/call-sites.mjs",
+    "demo:api-mjs": "pnpm build && node examples/mjs/api.mjs",
     "prepublishOnly": "pnpm run lint && pnpm test && pnpm run build",
     "prepare": "husky",
     "release": "semantic-release"

package/dist/cjs/core/createLog.d.ts

@@ -1,8 +0,0 @@
-import { type LogChannel } from "../constants.js";
-/**
- * Builds a log function bound to a console channel and tag. The returned closure
- * is what the caller invokes directly, so {@link getCaller} resolves the caller's
- * own frame; the resolved caller is then handed to {@link writeLog}, which never
- * touches the stack. Logs only outside production — see {@link isLogAllowed}.
- */
-export default function createLog(channel: LogChannel, tag: string): (...args: unknown[]) => void;

package/dist/cjs/core/createLog.js

@@ -1,29 +0,0 @@
-"use strict";
-/*
- * createLog.ts
- * Created by Dewan Mobashirul
- * Copyright (c) 2026 dewan-meadown
- * All rights reserved
- */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = createLog;
-const getCaller_js_1 = __importDefault(require("../caller/getCaller.js"));
-const index_js_1 = require("./writeLog/index.js");
-const config_js_1 = require("../config.js");
-/**
- * Builds a log function bound to a console channel and tag. The returned closure
- * is what the caller invokes directly, so {@link getCaller} resolves the caller's
- * own frame; the resolved caller is then handed to {@link writeLog}, which never
- * touches the stack. Logs only outside production — see {@link isLogAllowed}.
- */
-function createLog(channel, tag) {
-    return (...args) => {
-        if (!(0, config_js_1.isLogAllowed)())
-            return;
-        const caller = (0, getCaller_js_1.default)();
-        (0, index_js_1.writeLog)({ channel, tag, args, caller });
-    };
-}

package/dist/cjs/core/writeLog/index.js

@@ -1,48 +0,0 @@
-"use strict";
-/*
- * index.ts
- * Created by Dewan Mobashirul
- * Copyright (c) 2026 dewan-meadown
- * All rights reserved
- */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.setVisibleLines = exports.getVisibleLines = void 0;
-exports.writeLog = writeLog;
-const constants_js_1 = require("../../constants.js");
-const getTimeStamp_js_1 = __importDefault(require("../../time/getTimeStamp.js"));
-const color_js_1 = require("../../colors/color.js");
-const isTTY_js_1 = require("../../terminal/isTTY.js");
-const renderMessage_js_1 = require("./renderMessage.js");
-const formatLocation_js_1 = require("./formatLocation.js");
-var visibleLines_js_1 = require("./visibleLines.js");
-Object.defineProperty(exports, "getVisibleLines", { enumerable: true, get: function () { return visibleLines_js_1.getVisibleLines; } });
-Object.defineProperty(exports, "setVisibleLines", { enumerable: true, get: function () { return visibleLines_js_1.setVisibleLines; } });
-/**
- * Renders and writes one log entry. The `caller` is resolved by the *caller* of
- * this function (the log closure or `tap`) and passed in, so this helper never
- * touches the stack — keeping {@link getCaller}'s frame depth correct no matter
- * which user-facing function delegates here.
- */
-function writeLog(opts) {
-    const { channel, tag, args, caller } = opts;
-    const streamName = channel === "log" ? "stdout" : "stderr";
-    // One terminal check drives both color and clickable links — `isTTY` is the
-    // single source of truth (DRY). Off when output is piped/redirected.
-    const useColor = (0, isTTY_js_1.isTTY)(streamName);
-    const paint = (s, c) => useColor ? (0, color_js_1.colorize)(s, c) : s;
-    const location = (0, formatLocation_js_1.formatLocation)(caller, useColor);
-    const tagOut = paint(tag, constants_js_1.TAG_COLOR[channel]);
-    const timeStamp = paint((0, getTimeStamp_js_1.default)(), "teal");
-    const locOut = paint(`(${location})`, "dimTeal");
-    const connector = paint(constants_js_1.BRANCH, "gray");
-    const connectorBottom = paint(constants_js_1.BRANCH_END, "gray");
-    const separator = paint(constants_js_1.SEPARATOR, "gray");
-    // Layout: the tag, the message hanging off a `├──` branch, then the timestamp
-    // and location on a `└──` branch below. Leading `\n` spaces entries apart.
-    const message = (0, renderMessage_js_1.renderMessage)(args, useColor);
-    const meta = `\n${connectorBottom} ${timeStamp} ${separator} ${locOut}`;
-    console[channel](`\n${tagOut}`, `\n${connector}`, message, meta);
-}

package/dist/cjs/tap/createTap.d.ts

@@ -1,18 +0,0 @@
-/** Logs a value and returns it unchanged. Promises route to the timed path. */
-export interface Tap {
-    <T>(value: T, label?: string): T;
-}
-/**
- * Builds `tap` — logs a value and returns it **unchanged**, so it drops into any
- * expression (`const u = logger.tap(getUser(), "user")`). The consumer always
- * gets back exactly what they passed; the only effect is a clean log.
- *
- * - A plain value is logged synchronously and returned.
- * - A **promise** is returned as-is (same object, never awaited or wrapped), and
- *   its elapsed time — plus the HTTP status if it resolves to a `Response` — is
- *   logged in the background (fire-and-forget, non-blocking).
- *
- * The returned closure is what the caller invokes directly, so {@link getCaller}
- * resolves the caller's own frame. Silent in production; the value still flows.
- */
-export default function createTap(): Tap;

package/dist/cjs/tap/createTap.js

@@ -1,51 +0,0 @@
-"use strict";
-/*
- * createTap.ts
- * Created by Dewan Mobashirul
- * Copyright (c) 2026 dewan-meadown
- * All rights reserved
- */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = createTap;
-const getCaller_js_1 = __importDefault(require("../caller/getCaller.js"));
-const index_js_1 = require("../core/writeLog/index.js");
-const config_js_1 = require("../config.js");
-const tapAsync_js_1 = require("./tapAsync.js");
-/**
- * Builds `tap` — logs a value and returns it **unchanged**, so it drops into any
- * expression (`const u = logger.tap(getUser(), "user")`). The consumer always
- * gets back exactly what they passed; the only effect is a clean log.
- *
- * - A plain value is logged synchronously and returned.
- * - A **promise** is returned as-is (same object, never awaited or wrapped), and
- *   its elapsed time — plus the HTTP status if it resolves to a `Response` — is
- *   logged in the background (fire-and-forget, non-blocking).
- *
- * The returned closure is what the caller invokes directly, so {@link getCaller}
- * resolves the caller's own frame. Silent in production; the value still flows.
- */
-function createTap() {
-    const tap = (value, label) => {
-        if (!(0, config_js_1.isLogAllowed)())
-            return value;
-        const caller = (0, getCaller_js_1.default)();
-        if ((0, tapAsync_js_1.isThenable)(value)) {
-            // value is a promise → hand off to the async tap (caller passed in so the
-            // location stays on the user's file, not on this helper).
-            (0, tapAsync_js_1.tapAsync)(value, label, caller);
-        }
-        else {
-            (0, index_js_1.writeLog)({
-                channel: "log",
-                tag: "[TAP]",
-                args: label === undefined ? [value] : [label, value],
-                caller,
-            });
-        }
-        return value;
-    };
-    return tap;
-}