@meadown/logger 1.8.10 → 1.9.0

package/dist/cjs/tap/tapAsync.js

@@ -1,192 +0,0 @@
-"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 index_js_1 = require("../core/writeLog/index.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 >= 2000)
-        return (0, color_js_1.colorize)(text, "red");
-    if (ms >= 500)
-        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 paint = (s, c) => useColor ? (0, color_js_1.colorize)(s, c) : s;
-    const pipe = paint("│", "gray");
-    const branch = paint("├──", "gray");
-    const last = paint("└──", "gray");
-    const indent = `${pipe}  `;
-    const timeLine = `${indent}${branch} time:   ${formatDuration(ms, useColor)}`;
-    const statusLine = `${indent}${branch} status: ${formatStatus(res, useColor)}`;
-    const sizeLine = `${indent}${last} size:   ${body.size}`;
-    const responseLines = [`${pipe}`, `${indent}response:`, timeLine, statusLine, sizeLine];
-    const head = label === undefined ? "" : `${label}\n`;
-    if (body.data === undefined) {
-        return [`${head}${responseLines.join("\n")}`];
-    }
-    // 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 = [...responseLines, `${pipe}`, `${indent}body:`, bodyBlock].join("\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, index_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, index_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, index_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, index_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, index_js_1.writeLog)({
-            channel: "error", tag: "[TAP]",
-            args: [label === undefined ? `rejected after ${elapsed}` : `${label} rejected after ${elapsed}`, err],
-            caller,
-        });
-    });
-}

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

@@ -1,23 +0,0 @@
-/*
- * createLog.ts
- * Created by Dewan Mobashirul
- * Copyright (c) 2026 dewan-meadown
- * All rights reserved
- */
-import getCaller from "../caller/getCaller.js";
-import { writeLog } from "./writeLog/index.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/index.js

@@ -1,39 +0,0 @@
-/*
- * index.ts
- * Created by Dewan Mobashirul
- * Copyright (c) 2026 dewan-meadown
- * All rights reserved
- */
-import { TAG_COLOR, BRANCH, BRANCH_END, SEPARATOR, } from "../../constants.js";
-import getTimeStamp from "../../time/getTimeStamp.js";
-import { colorize } from "../../colors/color.js";
-import { isTTY } from "../../terminal/isTTY.js";
-import { renderMessage } from "./renderMessage.js";
-import { formatLocation } from "./formatLocation.js";
-export { getVisibleLines, setVisibleLines } from "./visibleLines.js";
-/**
- * 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 paint = (s, c) => useColor ? colorize(s, c) : s;
-    const location = formatLocation(caller, useColor);
-    const tagOut = paint(tag, TAG_COLOR[channel]);
-    const timeStamp = paint(getTimeStamp(), "teal");
-    const locOut = paint(`(${location})`, "dimTeal");
-    const connector = paint(BRANCH, "gray");
-    const connectorBottom = paint(BRANCH_END, "gray");
-    const separator = paint(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 = renderMessage(args, useColor);
-    const meta = `\n${connectorBottom} ${timeStamp} ${separator} ${locOut}`;
-    console[channel](`\n${tagOut}`, `\n${connector}`, message, meta);
-}

package/dist/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/tap/createTap.js

@@ -1,45 +0,0 @@
-/*
- * createTap.ts
- * Created by Dewan Mobashirul
- * Copyright (c) 2026 dewan-meadown
- * All rights reserved
- */
-import getCaller from "../caller/getCaller.js";
-import { writeLog } from "../core/writeLog/index.js";
-import { isLogAllowed } from "../config.js";
-import { isThenable, tapAsync } from "./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.
- */
-export default function createTap() {
-    const tap = (value, label) => {
-        if (!isLogAllowed())
-            return value;
-        const caller = getCaller();
-        if (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).
-            tapAsync(value, label, caller);
-        }
-        else {
-            writeLog({
-                channel: "log",
-                tag: "[TAP]",
-                args: label === undefined ? [value] : [label, value],
-                caller,
-            });
-        }
-        return value;
-    };
-    return tap;
-}

package/dist/tap/tapAsync.js

@@ -1,188 +0,0 @@
-/*
- * 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.
- */
-import { performance } from "node:perf_hooks";
-import { formatWithOptions } from "node:util";
-import { writeLog } from "../core/writeLog/index.js";
-import { colorize } from "../colors/color.js";
-import { isTTY } from "../terminal/isTTY.js";
-/** Whether `value` is thenable (a promise we can await + time). */
-export 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 >= 2000)
-        return colorize(text, "red");
-    if (ms >= 500)
-        return colorize(text, "yellow");
-    return 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 ? 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 paint = (s, c) => useColor ? colorize(s, c) : s;
-    const pipe = paint("│", "gray");
-    const branch = paint("├──", "gray");
-    const last = paint("└──", "gray");
-    const indent = `${pipe}  `;
-    const timeLine = `${indent}${branch} time:   ${formatDuration(ms, useColor)}`;
-    const statusLine = `${indent}${branch} status: ${formatStatus(res, useColor)}`;
-    const sizeLine = `${indent}${last} size:   ${body.size}`;
-    const responseLines = [`${pipe}`, `${indent}response:`, timeLine, statusLine, sizeLine];
-    const head = label === undefined ? "" : `${label}\n`;
-    if (body.data === undefined) {
-        return [`${head}${responseLines.join("\n")}`];
-    }
-    // Render the body using util.formatWithOptions so objects/arrays look like
-    // console.log output — colors, proper nesting, no JSON.stringify quirkiness.
-    const bodyText = 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 = [...responseLines, `${pipe}`, `${indent}body:`, bodyBlock].join("\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.
- */
-export function tapAsync(promise, label, caller) {
-    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: "[TAP]",
-            args: [label === undefined ? `rejected after ${elapsed}` : `${label} rejected after ${elapsed}`, err],
-            caller,
-        });
-    });
-}