@meadown/logger 1.7.0 → 1.8.0

package/README.md

@@ -1,16 +1,32 @@
 # @meadown/logger
 
-I kept writing `console.log` everywhere, then squinting at my terminal trying to
-remember _which file_ a message came from — and worse, forgetting to pull those logs
-out before shipping. So I made this.
-
-It's basically `console.log` with the rough edges sanded off: every message gets a
-**color-coded** level tag, a timestamp, and the file and line it came from — as a
-**clickable link** you can open straight from your terminal. And it stays quiet in
-production, so you can leave your logs where they are and not worry about them.
+A **development-focused logger** for Node.js and TypeScript — built to make your
+development loop faster and your terminal actually readable.
 
 No dependencies. No config. Import it and you're done.
 
+## Why this exists
+
+I kept writing the same custom log wrapper in every project — the one that
+silences itself in production and shows a timestamp. I kept forgetting to use
+it, shipping stray `console.log` calls, and having no idea which file a log
+message came from. So I built the version I always wanted: zero dependencies,
+automatic production silence, and every line tells you exactly where it came
+from as a clickable link.
+
+> Full story — problem, research, design, build, and what got cut along the
+> way — in [`docs/STORY.md`](docs/STORY.md).
+
+## Features
+
+- **Zero dependencies**
+- **Development-focused** — built for the dev experience, not production ops
+- **Clickable source link** — every log is a clickable link to the exact file it came from
+- **API response logging** — `tap` a fetch and get timing, status, size, and body automatically
+- **Color-coded levels** — `[INFO]` cyan, `[WARN]` yellow, `[ERROR]` red
+- **Tree layout output** — clean, scannable structure in your terminal
+- **Collapsible messages** — cap long output with `logger.maxLines`
+
 ## Install
 
 ```bash
@@ -27,100 +43,114 @@ yarn add @meadown/logger
 import logger from "@meadown/logger"
 
 logger("Hello world")
-logger("Auth", "user logged in") // every argument is printed as-is, like console.log
+logger("Auth", "user logged in")
 
 logger.warn("This is deprecated")
 logger.error("Something went wrong")
 ```
 
-You'll see something like:
-
 ```text
 [INFO]
 ├── Auth user logged in
 └── 05-30 04:00:00 PM - (server.ts:42)
 ```
 
-Each entry is a little tree: the level tag — `[INFO]`, `[WARN]`, or `[ERROR]` — on
-top, your message hanging off a `├──` branch, and a short local timestamp
-(month-day, 12-hour time) plus the source location on the `└──` branch below.
-Entries are spaced apart by a blank line so they're easy to scan in a busy terminal.
-
-### One thing if you re-export it
+## API response logging
 
-A lot of projects like to funnel everything through their own `lib/logger` file.
-That's totally fine here — just pass the logger straight through instead of wrapping
-it in a new function. The file and line are read from the call stack, so an extra
-wrapper makes every log blame _that_ file instead of wherever you actually logged.
+Drop `tap` into any `await` chain — you get timing, status, size, and the
+actual response body. The promise flows through untouched. One line of code.
 
 ```ts
-// GOOD: pass it through — the (file:line) stays honest
-export { default as logger } from "@meadown/logger"
+const user = await logger.tap(
+  fetch("https://api.example.com/users/1"),
+  "GET /users/1"
+)
+// user is the real Response — your code doesn't change at all
+```
 
-// BAD: now every log points at this file, not the real caller
-export const logger = (...args) => log(...args)
+```text
+[TAP]
+├── GET /users/1
+│
+│  response:
+│  ├── time:   65ms
+│  ├── status: 200 OK
+│  └── size:   848 B
+│
+│  body:
+│  ├── id:    1
+│  ├── name:  Leanne Graham
+│  └── email: Sincere@april.biz
+│
+└── 05-30 07:54:26 PM - (api.ts:12)
 ```
 
+You can immediately see: was it successful? How long did it take? What came
+back? Without opening DevTools.
+
+Works with plain values too — logs it, returns it, nothing changes:
+
+```ts
+const port = logger.tap(5000, "port")          // port is still 5000
+const user = logger.tap(await getUser(), "user") // same as without tap
+```
+
+## Clickable source link
+
+That `(server.ts:42)` is a **clickable link** — open it and you land on the exact
+line that wrote the log. Works in VS Code, iTerm2, WezTerm, Kitty, and Windows
+Terminal. Degrades to plain text everywhere else.
+
 ## Color-coded levels
 
-The level tag is colored so you can spot what matters at a glance — `[INFO]` in
-cyan, `[WARN]` in yellow, `[ERROR]` in red. The timestamp and source location are
-tinted teal, and the tree branches sit in a quiet gray, so the colored level tag is
-what your eye lands on first.
+`[INFO]` cyan · `[WARN]` yellow · `[ERROR]` red. Timestamp and location tinted teal.
+Auto-disabled when output is piped — no escape codes in your log files.
 
-Colors appear automatically when you're in a terminal. When output is piped to a
-file or another program, everything prints as plain text — no stray color codes in
-your log files. Nothing to configure.
+## Tree layout output
 
-## Click to open the source
+```text
+[INFO]
+├── Auth user logged in
+└── 05-30 04:00:00 PM - (server.ts:42)
+```
 
-That `(server.ts:42)` at the end of every log isn't just text — when you are in a
-terminal, it's a **clickable link** that opens the file the log came from. No more
-hunting for where a message came from, and the line number is right there in the
-label.
+Level tag, message, timestamp, and location — all in a clean tree. Easy to scan,
+even in a busy terminal.
 
-There's nothing to configure. Links show up automatically when output goes to a
-terminal, and when it's piped to a file or another program they quietly drop to
-plain `(server.ts:42)` text — so your log files never get cluttered with escape
-codes.
+## Collapsible messages
 
-## Trimming long messages
+```ts
+logger.maxLines = 5 // show 5 lines, then "... N more lines"
+logger.maxLines = 0 // default — show everything
+```
 
-By default you see everything you log, however long. But if a big object or a
-chatty multi-line message is drowning out your terminal, you can cap how many
-lines each message shows:
+### One thing if you re-export it
 
 ```ts
-import logger from "@meadown/logger"
+// GOOD — location stays honest
+export { default as logger } from "@meadown/logger"
 
-logger.maxLines = 5 // show the first 5 lines, then "... N more lines"
-logger.maxLines = 0 // back to the default — show everything
+// BAD — every log points at this file, not the real caller
+export const logger = (...args) => log(...args)
 ```
 
-It only trims the _message_, never the tag, timestamp, or location, and the setting
-applies to `logger`, `.error`, and `.warn` alike.
+## NODE_ENV
 
-## What about production?
-
-Here's the nice part: you don't have to do anything. Logs show up while you're
-developing and go silent in production. The only thing that flips the switch is your
-`NODE_ENV`:
+This logger reads `NODE_ENV` to decide when to log. By default it logs everywhere
+except `production`. This is a deliberate dev-focused default — a production-grade
+logger with transport, persistence, and log levels is a separate concern and a
+future direction.
 
 | `NODE_ENV`                               | Logs?  |
 | ---------------------------------------- | ------ |
 | not set, `development`, or anything else | shown  |
 | `production`                             | silent |
 
-So leave your logs in the code. Once you ship with `NODE_ENV=production`, they just
-quietly step aside.
-
 ## Security
 
-It's a tiny, zero-dependency package with no file, network, or dynamic-code access.
-See [SECURITY.md](https://www.npmjs.com/package/@meadown/logger?activeTab=code)
-for the security model and how to report a vulnerability. One thing to know: like
-`console.log`, log arguments are written to the terminal as-is and are not
-sanitized — don't log untrusted data to a terminal you trust.
+Zero dependencies, no file or network access, nothing persisted.
+See [SECURITY.md](https://github.com/meadown/meadown-logger/blob/main/SECURITY.md)
+for the full security model.
 
 ## License
 

package/SECURITY.md

@@ -23,14 +23,37 @@ Only the latest published `@meadown/logger` release receives security fixes.
   packages, so there is no third-party supply-chain surface to inherit.
 - **No I/O or dynamic execution.** It does not read or write files, open network
   connections, spawn processes, or use `eval`/`Function`. It only writes to the
-  console and reads `process.env.NODE_ENV` (to stay quiet in production).
+  console and reads `process.env.NODE_ENV` (to stay quiet in production). (The
+  `examples/` directory is not part of the published package and may make real
+  network calls when you run it.)
 - **Nothing is persisted.** Log output is never written to disk, so the logger
   cannot leak logged data to a temp file or similar.
 
-## Trust boundary: log arguments are output, not input
+## What the logger does with your values
 
-Like `console.log` itself, this logger passes the arguments you give it through
-to the terminal as output. **It does not sanitize them.**
+Nothing beyond showing them to you. This matters most for `tap`, which is built to
+log values like API responses that often carry tokens, sessions, or personal data.
+The logger does **not**:
+
+- **store or persist** any value — no files, no database, no caching, no buffering;
+  nothing is kept after the log call returns;
+- **send anything over the network** — there is no networking code and no
+  dependencies, so there is nothing that could "phone home";
+- **read, copy, or forward** tokens, cookies, session IDs, or credentials, and it
+  does not hijack or inspect sessions;
+- **mutate** what you pass — `tap` returns the exact same reference, unchanged.
+
+`logger.tap(await login(), "auth")` writes the response to your terminal and hands
+it straight back. The value never leaves your process — the only "exposure" is the
+text printed to your own console (see the trust boundary below).
+
+## Trust boundary: logged values are output, not input
+
+Like `console.log` itself, this logger passes whatever you give it through to the
+terminal as output, via every entry point — `logger(...)`, `.error(...)`,
+`.warn(...)`, and `.tap(value, label?)`. **It does not sanitize them.** (`tap`
+returns the value untouched and renders it for display; it never inspects or
+alters it.)
 
 If you log **untrusted data** (user input, third-party API responses, etc.) that
 contains terminal control or escape sequences (ANSI `\x1b[…`, OSC-8 hyperlinks,
@@ -39,6 +62,9 @@ e.g. overwrite previously printed text or spoof a clickable link. This is an
 inherent property of writing untrusted text to a terminal, not specific to this
 package.
 
+This is worth keeping in mind for `tap`, whose headline use is logging fetched
+API responses — exactly the kind of third-party data to treat as untrusted.
+
 Guidance:
 
 - Treat log output as you would any other untrusted text rendered in a terminal.

package/dist/{utils → caller}/getCaller.js

@@ -32,4 +32,3 @@ export default function getCaller() {
         return UNKNOWN;
     return { label: `${base}:${line}`, file, line };
 }
-//# sourceMappingURL=getCaller.js.map

package/dist/{utils → cjs/caller}/getCaller.d.ts

@@ -14,4 +14,3 @@ export interface Caller {
  * (e.g. minified, eval, or native code).
  */
 export default function getCaller(): Caller;
-//# sourceMappingURL=getCaller.d.ts.map

package/dist/cjs/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/cjs/colors/color.js

@@ -0,0 +1,29 @@
+"use strict";
+/*
+ * color.ts
+ * Created by Dewan Mobashirul
+ * Copyright (c) 2026 dewan-meadown
+ * All rights reserved
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.colorize = colorize;
+/** 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.
+ */
+function colorize(text, color) {
+    return `\x1b[${CODES[color]}m${text}${RESET}`;
+}

package/dist/cjs/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/cjs/constants.js

@@ -0,0 +1,27 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_LINES = exports.MESSAGE_INDENT = exports.SEPARATOR = exports.BRANCH_END = exports.BRANCH = exports.TAG_COLOR = void 0;
+/** The tag color per channel: info/tap → cyan, warn → yellow, error → red. */
+exports.TAG_COLOR = {
+    log: "cyan",
+    warn: "yellow",
+    error: "red",
+};
+/** Glyphs that draw each entry's little tree. */
+exports.BRANCH = "├──"; // the message branch
+exports.BRANCH_END = "└──"; // the last (metadata) branch
+exports.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). */
+exports.MESSAGE_INDENT = "|\t";
+/** Default for the collapse setting: 0 = show every line. */
+exports.DEFAULT_MAX_LINES = 0;

package/dist/cjs/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/cjs/core/createLog.js

@@ -0,0 +1,29 @@
+"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 writeLog_js_1 = require("./writeLog.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, writeLog_js_1.writeLog)({ channel, tag, args, caller });
+    };
+}

package/dist/cjs/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/cjs/core/writeLog.js

@@ -0,0 +1,95 @@
+"use strict";
+/*
+ * writeLog.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.getVisibleLines = getVisibleLines;
+exports.setVisibleLines = setVisibleLines;
+exports.writeLog = writeLog;
+const node_util_1 = require("node:util");
+const constants_js_1 = require("../constants.js");
+const getTimeStamp_js_1 = __importDefault(require("../time/getTimeStamp.js"));
+const link_js_1 = require("../decorations/link.js");
+const color_js_1 = require("../colors/color.js");
+const isTTY_js_1 = require("../terminal/isTTY.js");
+/** Max message lines to show before collapsing the rest; 0 (default) shows all. */
+let visibleLines = constants_js_1.DEFAULT_MAX_LINES;
+/** How many lines a long message shows before collapsing (0 = all). */
+function getVisibleLines() {
+    return visibleLines;
+}
+/** Set how many lines a long message shows before collapsing (0 = all). */
+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 = `${constants_js_1.MESSAGE_INDENT}... ${hidden} more line${hidden === 1 ? "" : "s"}`;
+    const visible = lines.slice(0, visibleLines);
+    visible.push(useColor ? (0, color_js_1.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 = (0, node_util_1.formatWithOptions)({ colors: useColor }, ...args);
+    return collapse(text.replace(/\n/g, `\n${(0, color_js_1.colorize)(constants_js_1.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 (0, link_js_1.hyperlink)(caller.label, (0, link_js_1.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.
+ */
+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 location = formatLocation(caller, useColor);
+    // Colors (terminal only): tag by level, timestamp teal, location dim teal,
+    // branch and separator gray.
+    const tagOut = useColor ? (0, color_js_1.colorize)(tag, constants_js_1.TAG_COLOR[channel]) : tag;
+    const timeStamp = useColor ? (0, color_js_1.colorize)((0, getTimeStamp_js_1.default)(), "teal") : (0, getTimeStamp_js_1.default)();
+    const locOut = useColor
+        ? (0, color_js_1.colorize)(`(${location})`, "dimTeal")
+        : `(${location})`;
+    const connector = useColor ? (0, color_js_1.colorize)(constants_js_1.BRANCH, "gray") : constants_js_1.BRANCH;
+    const connectorBottom = useColor ? (0, color_js_1.colorize)(constants_js_1.BRANCH_END, "gray") : constants_js_1.BRANCH_END;
+    const separator = useColor ? (0, color_js_1.colorize)(constants_js_1.SEPARATOR, "gray") : constants_js_1.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/cjs/{utils → decorations}/link.d.ts

@@ -12,10 +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;

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

@@ -8,7 +8,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fileUrl = fileUrl;
 exports.hyperlink = hyperlink;
-exports.supportsHyperlinks = supportsHyperlinks;
 const node_url_1 = require("node:url");
 /**
  * Builds a valid `file://` URL for a path so terminals can open it on click.
@@ -30,15 +29,3 @@ 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.
- */
-function supportsHyperlinks(streamName) {
-    if (typeof process === "undefined")
-        return false;
-    const stream = streamName === "stdout" ? process.stdout : process.stderr;
-    return Boolean(stream?.isTTY);
-}

package/dist/cjs/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.

package/dist/cjs/index.js

@@ -5,9 +5,14 @@
  * 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.logger = void 0;
-const index_js_1 = require("./utils/index.js");
+const createLog_js_1 = __importDefault(require("./core/createLog.js"));
+const createTap_js_1 = __importDefault(require("./tap/createTap.js"));
+const writeLog_js_1 = require("./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,16 +23,17 @@ const index_js_1 = require("./utils/index.js");
  * @example
  * logger.maxLines = 5 // long messages collapse to 5 lines; 0 = show all
  */
-const logger = Object.assign((0, index_js_1.createLog)("log", "[INFO]"), {
-    error: (0, index_js_1.createLog)("error", "[ERROR]"),
-    warn: (0, index_js_1.createLog)("warn", "[WARN]"),
+const logger = Object.assign((0, createLog_js_1.default)("log", "[INFO]"), {
+    error: (0, createLog_js_1.default)("error", "[ERROR]"),
+    warn: (0, createLog_js_1.default)("warn", "[WARN]"),
+    tap: (0, createTap_js_1.default)(),
 });
 exports.logger = logger;
 // `maxLines` is a live getter/setter backed by the shared collapse setting, so
 // setting it once affects info, error, and warn alike.
 Object.defineProperty(logger, "maxLines", {
-    get: index_js_1.getVisibleLines,
-    set: index_js_1.setVisibleLines,
+    get: writeLog_js_1.getVisibleLines,
+    set: writeLog_js_1.setVisibleLines,
     enumerable: true,
     configurable: true,
 });

package/dist/cjs/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;