@meadown/logger 1.7.0 → 1.8.0

package/dist/cjs/tap/createTap.js

@@ -0,0 +1,51 @@
+"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 writeLog_js_1 = require("../core/writeLog.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, writeLog_js_1.writeLog)({
+                channel: "log",
+                tag: "[TAP]",
+                args: label === undefined ? [value] : [label, value],
+                caller,
+            });
+        }
+        return value;
+    };
+    return tap;
+}

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

@@ -0,0 +1,11 @@
+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>;
+/**
+ * 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 declare function tapAsync(promise: PromiseLike<unknown>, label: string | undefined, caller: Caller): void;

package/dist/cjs/tap/tapAsync.js

@@ -0,0 +1,207 @@
+"use strict";
+/*
+ * tapAsync.ts
+ * Created by Dewan Mobashirul
+ * Copyright (c) 2026 dewan-meadown
+ * All rights reserved
+ *
+ * The async side of `tap`: times a promise and logs a rich response block when
+ * it resolves to a `Response` — status color, slow-request highlighting, size,
+ * and the actual body — all fire-and-forget so the caller never waits.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isThenable = isThenable;
+exports.tapAsync = tapAsync;
+const node_perf_hooks_1 = require("node:perf_hooks");
+const node_util_1 = require("node:util");
+const writeLog_js_1 = require("../core/writeLog.js");
+const color_js_1 = require("../colors/color.js");
+const isTTY_js_1 = require("../terminal/isTTY.js");
+/** Whether `value` is thenable (a promise we can await + time). */
+function isThenable(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.then === "function");
+}
+/** Whether the resolved value is a fetch `Response` we can read. */
+function isResponse(value) {
+    const v = value;
+    return (typeof v?.status === "number" &&
+        typeof v.clone === "function" &&
+        typeof v.text === "function");
+}
+/** `65ms` (green) · `1.2s` (yellow) · `5.8s` (red). */
+function formatDuration(ms, useColor) {
+    const text = ms >= 1000 ? `${(ms / 1000).toFixed(2)}s` : `${ms}ms`;
+    if (!useColor)
+        return text;
+    if (ms >= 3000)
+        return (0, color_js_1.colorize)(text, "red");
+    if (ms >= 1000)
+        return (0, color_js_1.colorize)(text, "yellow");
+    return (0, color_js_1.colorize)(text, "green");
+}
+/** `848 B` / `1.84 KB` / `2.10 MB`. */
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(2)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+/**
+ * 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";
+}
+function formatStatus(res, useColor) {
+    const text = typeof res.statusText === "string" && res.statusText
+        ? `${res.status} ${res.statusText}`
+        : `${res.status}`;
+    return useColor ? (0, color_js_1.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.
+ */
+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" };
+    }
+}
+/**
+ * Renders the nested tree block the user asked for:
+ *
+ *   GET /users/1
+ *   │
+ *   │  response:
+ *   │  ├── time:   65ms
+ *   │  ├── status: 200 OK
+ *   │  └── size:   848 B
+ *   │
+ *   │  body:
+ *   │  ├── id:    1
+ *   │  └── name:  Leanne Graham
+ */
+function buildBlock(label, ms, res, body, useColor) {
+    const pipe = useColor ? (0, color_js_1.colorize)("│", "gray") : "│";
+    const branch = useColor ? (0, color_js_1.colorize)("├──", "gray") : "├──";
+    const last = useColor ? (0, color_js_1.colorize)("└──", "gray") : "└──";
+    const indent = `${pipe}  `;
+    const statusLine = `${indent}${branch} status: ${formatStatus(res, useColor)}`;
+    const timeLine = `${indent}${branch} time:   ${formatDuration(ms, useColor)}`;
+    const sizeLine = `${indent}${last} size:   ${body.size}`;
+    const responseBlock = [
+        `${pipe}`,
+        `${indent}response:`,
+        timeLine,
+        statusLine,
+        sizeLine,
+    ].join("\n");
+    if (body.data === undefined) {
+        const head = label === undefined ? "" : `${label}\n`;
+        return [`${head}${responseBlock}`];
+    }
+    // Render the body using util.formatWithOptions so objects/arrays look like
+    // console.log output — colors, proper nesting, no JSON.stringify quirkiness.
+    const bodyText = (0, node_util_1.formatWithOptions)({ colors: useColor }, body.data);
+    const bodyLines = bodyText.split("\n");
+    const lastIdx = bodyLines.length - 1;
+    const bodyBlock = bodyLines
+        .map((line, i) => `${indent}${i === lastIdx ? last : branch} ${line}`)
+        .join("\n");
+    const full = [
+        `${pipe}`,
+        `${indent}response:`,
+        timeLine,
+        statusLine,
+        sizeLine,
+        `${pipe}`,
+        `${indent}body:`,
+        bodyBlock,
+    ].join("\n");
+    const head = label === undefined ? "" : `${label}\n`;
+    return [`${head}${full}`];
+}
+/**
+ * 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.
+ */
+function tapAsync(promise, label, caller) {
+    const useColor = (0, isTTY_js_1.isTTY)("stdout");
+    const start = node_perf_hooks_1.performance.now();
+    void promise.then((resolved) => {
+        const ms = Math.round(node_perf_hooks_1.performance.now() - start);
+        if (isResponse(resolved)) {
+            let clone = null;
+            try {
+                clone = resolved.clone();
+            }
+            catch {
+                clone = null;
+            }
+            if (clone === null) {
+                (0, writeLog_js_1.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) {
+                (0, writeLog_js_1.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) => {
+                (0, writeLog_js_1.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);
+        (0, writeLog_js_1.writeLog)({
+            channel: "log", tag: "[TAP]",
+            args: label === undefined ? [elapsed, resolved] : [`${label} ${elapsed}`, resolved],
+            caller,
+        });
+    }, (err) => {
+        const ms = Math.round(node_perf_hooks_1.performance.now() - start);
+        const elapsed = formatDuration(ms, useColor);
+        (0, writeLog_js_1.writeLog)({
+            channel: "error", tag: "[TAP]",
+            args: [label === undefined ? `rejected after ${elapsed}` : `${label} rejected after ${elapsed}`, err],
+            caller,
+        });
+    });
+}

package/dist/cjs/terminal/isTTY.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether the given stream is an interactive terminal — the single source of
+ * truth for "should we emit terminal escapes (colors, clickable links)?". No env
+ * vars, no config. When output is piped or redirected this is `false`, so escape
+ * codes never end up in files or logs.
+ */
+export declare function isTTY(streamName: "stdout" | "stderr"): boolean;

package/dist/cjs/terminal/isTTY.js

@@ -0,0 +1,21 @@
+"use strict";
+/*
+ * isTTY.ts
+ * Created by Dewan Mobashirul
+ * Copyright (c) 2026 dewan-meadown
+ * All rights reserved
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTTY = isTTY;
+/**
+ * Whether the given stream is an interactive terminal — the single source of
+ * truth for "should we emit terminal escapes (colors, clickable links)?". No env
+ * vars, no config. When output is piped or redirected this is `false`, so escape
+ * codes never end up in files or logs.
+ */
+function isTTY(streamName) {
+    if (typeof process === "undefined")
+        return false;
+    const stream = streamName === "stdout" ? process.stdout : process.stderr;
+    return Boolean(stream?.isTTY);
+}

package/dist/colors/color.d.ts

@@ -0,0 +1,20 @@
+/** ANSI SGR codes for the colors/styles the logger uses. */
+declare const CODES: {
+    readonly red: "38;2;239;68;68";
+    readonly yellow: 33;
+    readonly green: 32;
+    readonly cyan: "38;5;37";
+    readonly gray: 90;
+    readonly teal: "38;5;30";
+    readonly dimTeal: "38;5;23";
+    readonly bold: 1;
+};
+/** The named colors/styles {@link colorize} understands. */
+export type Color = keyof typeof CODES;
+/**
+ * Wraps `text` in the ANSI escape codes for `color`, resetting afterwards.
+ * Pure string work — deciding *whether* to colorize is the caller's job (see
+ * `isTTY`), kept separate so it can be checked once per entry.
+ */
+export declare function colorize(text: string, color: Color): string;
+export {};

package/dist/colors/color.js

@@ -0,0 +1,26 @@
+/*
+ * color.ts
+ * Created by Dewan Mobashirul
+ * Copyright (c) 2026 dewan-meadown
+ * All rights reserved
+ */
+/** ANSI SGR codes for the colors/styles the logger uses. */
+const CODES = {
+    red: "38;2;239;68;68", // truecolor #ef4444
+    yellow: 33,
+    green: 32,
+    cyan: "38;5;37", // 256-color deep cyan (#00afaf)
+    gray: 90, // bright black — renders as light gray
+    teal: "38;5;30", // 256-color teal (#008787)
+    dimTeal: "38;5;23", // 256-color darker teal (#005f5f)
+    bold: 1,
+};
+const RESET = "\x1b[0m";
+/**
+ * Wraps `text` in the ANSI escape codes for `color`, resetting afterwards.
+ * Pure string work — deciding *whether* to colorize is the caller's job (see
+ * `isTTY`), kept separate so it can be checked once per entry.
+ */
+export function colorize(text, color) {
+    return `\x1b[${CODES[color]}m${text}${RESET}`;
+}

package/dist/config.d.ts

@@ -4,4 +4,3 @@
  * in your runtime to silence logs.
  */
 export declare function isLogAllowed(): boolean;
-//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -14,4 +14,3 @@ export function isLogAllowed() {
     // edge) where it may be undefined; default to logging when it's absent.
     return typeof process === "undefined" || process.env.NODE_ENV !== "production";
 }
-//# sourceMappingURL=config.js.map

package/dist/constants.d.ts

@@ -0,0 +1,14 @@
+import { type Color } from "./colors/color.js";
+/** The console channels the logger writes to. */
+export type LogChannel = "log" | "error" | "warn";
+/** The tag color per channel: info/tap → cyan, warn → yellow, error → red. */
+export declare const TAG_COLOR: Record<LogChannel, Color>;
+/** Glyphs that draw each entry's little tree. */
+export declare const BRANCH = "\u251C\u2500\u2500";
+export declare const BRANCH_END = "\u2514\u2500\u2500";
+export declare const SEPARATOR = "-";
+/** Hang-indent for message continuation lines, so they align under the message
+ * text (the `├── ` branch is 4 columns wide). */
+export declare const MESSAGE_INDENT = "|\t";
+/** Default for the collapse setting: 0 = show every line. */
+export declare const DEFAULT_MAX_LINES = 0;

package/dist/constants.js

@@ -0,0 +1,24 @@
+/*
+ * constants.ts
+ * Created by Dewan Mobashirul
+ * Copyright (c) 2026 dewan-meadown
+ * All rights reserved
+ *
+ * Single home for the logger's layout/behavior constants, so the values that
+ * shape an entry live in one place instead of as magic literals across modules.
+ */
+/** The tag color per channel: info/tap → cyan, warn → yellow, error → red. */
+export const TAG_COLOR = {
+    log: "cyan",
+    warn: "yellow",
+    error: "red",
+};
+/** Glyphs that draw each entry's little tree. */
+export const BRANCH = "├──"; // the message branch
+export const BRANCH_END = "└──"; // the last (metadata) branch
+export const SEPARATOR = "-"; // between the timestamp and the location
+/** Hang-indent for message continuation lines, so they align under the message
+ * text (the `├── ` branch is 4 columns wide). */
+export const MESSAGE_INDENT = "|\t";
+/** Default for the collapse setting: 0 = show every line. */
+export const DEFAULT_MAX_LINES = 0;

package/dist/core/createLog.d.ts

@@ -0,0 +1,8 @@
+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/core/createLog.js

@@ -0,0 +1,23 @@
+/*
+ * createLog.ts
+ * Created by Dewan Mobashirul
+ * Copyright (c) 2026 dewan-meadown
+ * All rights reserved
+ */
+import getCaller from "../caller/getCaller.js";
+import { writeLog } from "./writeLog.js";
+import { isLogAllowed } from "../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}.
+ */
+export default function createLog(channel, tag) {
+    return (...args) => {
+        if (!isLogAllowed())
+            return;
+        const caller = getCaller();
+        writeLog({ channel, tag, args, caller });
+    };
+}

package/dist/core/writeLog.d.ts

@@ -0,0 +1,18 @@
+import { type LogChannel } from "../constants.js";
+import { type Caller } from "../caller/getCaller.js";
+/** How many lines a long message shows before collapsing (0 = all). */
+export declare function getVisibleLines(): number;
+/** Set how many lines a long message shows before collapsing (0 = all). */
+export declare function setVisibleLines(value: number): void;
+/**
+ * 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.
+ */
+export declare function writeLog(opts: {
+    channel: LogChannel;
+    tag: string;
+    args: unknown[];
+    caller: Caller;
+}): void;

package/dist/core/writeLog.js

@@ -0,0 +1,87 @@
+/*
+ * writeLog.ts
+ * Created by Dewan Mobashirul
+ * Copyright (c) 2026 dewan-meadown
+ * All rights reserved
+ */
+import { formatWithOptions } from "node:util";
+import { TAG_COLOR, BRANCH, BRANCH_END, SEPARATOR, MESSAGE_INDENT, DEFAULT_MAX_LINES, } from "../constants.js";
+import getTimeStamp from "../time/getTimeStamp.js";
+import { fileUrl, hyperlink } from "../decorations/link.js";
+import { colorize } from "../colors/color.js";
+import { isTTY } from "../terminal/isTTY.js";
+/** Max message lines to show before collapsing the rest; 0 (default) shows all. */
+let visibleLines = DEFAULT_MAX_LINES;
+/** How many lines a long message shows before collapsing (0 = all). */
+export function getVisibleLines() {
+    return visibleLines;
+}
+/** Set how many lines a long message shows before collapsing (0 = all). */
+export function setVisibleLines(value) {
+    visibleLines = Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+/**
+ * Collapses a long multi-line message to {@link visibleLines} lines, replacing
+ * the rest with a dimmed `… N more lines` summary. When `visibleLines` is 0
+ * (the default) nothing is collapsed — the full message is shown.
+ */
+function collapse(text, useColor) {
+    if (visibleLines < 1)
+        return text;
+    const lines = text.split("\n");
+    if (lines.length <= visibleLines)
+        return text;
+    const hidden = lines.length - visibleLines;
+    const summary = `${MESSAGE_INDENT}... ${hidden} more line${hidden === 1 ? "" : "s"}`;
+    const visible = lines.slice(0, visibleLines);
+    visible.push(useColor ? colorize(summary, "gray") : summary);
+    return visible.join("\n");
+}
+/**
+ * Renders the args into a single message string exactly as console would —
+ * objects/errors via util.inspect, `%s`/`%d` format specifiers, and colors when
+ * on a terminal — then hang-indents every continuation line so multi-line
+ * output stays left-aligned under the branch, and collapses very long output.
+ */
+function renderMessage(args, useColor) {
+    const text = formatWithOptions({ colors: useColor }, ...args);
+    return collapse(text.replace(/\n/g, `\n${colorize(MESSAGE_INDENT, "gray")}`), useColor);
+}
+/**
+ * Renders a caller as a `(file:line)` location — a clickable OSC-8 link on a
+ * supporting terminal, plain text otherwise. Pure (no stack access).
+ */
+function formatLocation(caller, interactive) {
+    if (caller.file !== null && caller.line !== null && interactive)
+        return hyperlink(caller.label, fileUrl(caller.file));
+    return caller.label;
+}
+/**
+ * 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.
+ */
+export 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 = isTTY(streamName);
+    const location = formatLocation(caller, useColor);
+    // Colors (terminal only): tag by level, timestamp teal, location dim teal,
+    // branch and separator gray.
+    const tagOut = useColor ? colorize(tag, TAG_COLOR[channel]) : tag;
+    const timeStamp = useColor ? colorize(getTimeStamp(), "teal") : getTimeStamp();
+    const locOut = useColor
+        ? colorize(`(${location})`, "dimTeal")
+        : `(${location})`;
+    const connector = useColor ? colorize(BRANCH, "gray") : BRANCH;
+    const connectorBottom = useColor ? colorize(BRANCH_END, "gray") : BRANCH_END;
+    const separator = useColor ? colorize(SEPARATOR, "gray") : SEPARATOR;
+    // 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 = renderMessage(args, useColor);
+    const meta = `\n${connectorBottom} ${timeStamp} ${separator} ${locOut}`;
+    console[channel](`\n${tagOut}`, `\n${connector}`, message, meta);
+}

package/dist/{utils → decorations}/link.d.ts

@@ -12,11 +12,3 @@ export declare function fileUrl(file: string): string;
  * simply show `text`.
  */
 export declare function hyperlink(text: string, url: string): string;
-/**
- * Whether to emit OSC-8 hyperlinks for the given stream. Driven solely by the
- * stream being an interactive terminal (`isTTY`) — no env vars, no config. When
- * output is piped or redirected, links are skipped so escapes never end up in
- * files or logs. Terminals that don't understand OSC-8 just show the plain text.
- */
-export declare function supportsHyperlinks(streamName: "stdout" | "stderr"): boolean;
-//# sourceMappingURL=link.d.ts.map

package/dist/{utils → decorations}/link.js

@@ -25,16 +25,3 @@ export function hyperlink(text, url) {
     const BEL = "\x07";
     return `${OSC}${url}${BEL}${text}${OSC}${BEL}`;
 }
-/**
- * Whether to emit OSC-8 hyperlinks for the given stream. Driven solely by the
- * stream being an interactive terminal (`isTTY`) — no env vars, no config. When
- * output is piped or redirected, links are skipped so escapes never end up in
- * files or logs. Terminals that don't understand OSC-8 just show the plain text.
- */
-export function supportsHyperlinks(streamName) {
-    if (typeof process === "undefined")
-        return false;
-    const stream = streamName === "stdout" ? process.stdout : process.stderr;
-    return Boolean(stream?.isTTY);
-}
-//# sourceMappingURL=link.js.map

package/dist/index.d.ts

@@ -1,8 +1,16 @@
-/** The logger: a callable for info logs, plus `.error` and `.warn` variants. */
+/** The logger: a callable for info logs, plus `.error`, `.warn`, and `.tap`. */
 export interface LogFN {
     (...args: unknown[]): void;
     error(...args: unknown[]): void;
     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.
+     */
+    tap<T>(value: T, label?: string): T;
     /**
      * 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.
@@ -22,4 +30,3 @@ export interface LogFN {
 declare const logger: LogFN;
 export { logger };
 export default logger;
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -4,7 +4,9 @@
  * Copyright (c) 2026 dewan-meadown
  * All rights reserved
  */
-import { createLog, getVisibleLines, setVisibleLines } from "./utils/index.js";
+import createLog from "./core/createLog.js";
+import createTap from "./tap/createTap.js";
+import { getVisibleLines, setVisibleLines } from "./core/writeLog.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
@@ -18,6 +20,7 @@ import { createLog, getVisibleLines, setVisibleLines } from "./utils/index.js";
 const logger = Object.assign(createLog("log", "[INFO]"), {
     error: createLog("error", "[ERROR]"),
     warn: createLog("warn", "[WARN]"),
+    tap: createTap(),
 });
 // `maxLines` is a live getter/setter backed by the shared collapse setting, so
 // setting it once affects info, error, and warn alike.
@@ -29,4 +32,3 @@ Object.defineProperty(logger, "maxLines", {
 });
 export { logger };
 export default logger;
-//# sourceMappingURL=index.js.map

package/dist/tap/createTap.d.ts

@@ -0,0 +1,18 @@
+/** 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;