@meadown/logger 1.8.7 → 1.8.9

package/README.md

@@ -2,7 +2,7 @@
 
 # @meadown/logger
 
-A **development-focused logger** for Node.js and TypeScript — built to make your
+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.
@@ -10,7 +10,7 @@ No dependencies. No config. Import it and you're done.
 ## Why this exists
 
 I kept writing the same `console.log` wrapper in every project. Every time.
-Copy, paste, rename. And I still shipped it to production by accident. And I
+Copy, paste, rename. And I still shipped it to production by accident. Unconsciously I
 still spent ten minutes staring at logs trying to figure out which file they
 came from.
 
@@ -19,6 +19,10 @@ At some point I just built the thing I always wanted.
 One import. No config. No dependencies. It shows you exactly where every log
 came from, and it gets out of the way when you ship.
 
+It's not trying to be Winston or Pino. No transports, no log levels, no config files.
+Just a better `console.log` for the hours you spend in development. One that
+tells you where things came from and disappears when you ship.
+
 > The full story — the problem, the research, every design decision, and
 > everything that got cut — is in [`docs/STORY.md`](docs/STORY.md).
 
@@ -26,8 +30,8 @@ came from, and it gets out of the way when you ship.
 
 - **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
+- **Clickable source link** — every log is a clickable link that jumps to the exact file and line it came from
+- **Tap logging** — log any value or promise inline; fetch calls also get timing, status, size, and body
 - **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`
@@ -44,6 +48,9 @@ yarn add @meadown/logger
 
 ## Using it
 
+Set `NODE_ENV=production` and all output is suppressed. Anything else and
+logging is on. No config files, no init call, no options object.
+
 ```ts
 import logger from "@meadown/logger"
 
@@ -60,9 +67,41 @@ logger.error("Something went wrong")
 └── 05-30 04:00:00 PM - (server.ts:42)
 ```
 
+### Recommended: single shared import
+
+Rather than importing directly from `@meadown/logger` in every file, create
+one shared module in your project and re-export from there. This gives you a
+single place to set options like `maxLines` and keeps any future changes to
+one file.
+
+```ts
+// lib/logger.ts
+import logger from "@meadown/logger"
+
+logger.maxLines = 10 // configure once, applies everywhere
+
+export default logger
+```
+
+```ts
+// anywhere else in your project
+import logger from "@/lib/logger"
+```
+
+When re-exporting, use a direct re-export, Not a wrapper function. A wrapper
+breaks the caller location shown in every log line.
+
+```ts
+// GOOD — location stays honest
+export { default as logger } from "@meadown/logger"
+
+// BAD — every log points at this file, not the real caller
+export const logger = (...args) => log(...args)
+```
+
 ## API response logging
 
-Drop `tap` into any `await` chain — you get timing, status, size, and the
+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
@@ -93,25 +132,43 @@ const user = await logger.tap(
 You can immediately see: was it successful? How long did it take? What came
 back? Without opening DevTools.
 
-![API response logging — tap a fetch and see timing, status, size, and body](media/tap-api-demo.png)
+![API response logging: tap a fetch and see timing, status, size, and body](media/tap-api-demo.png)
+
+### Tap any value
+
+`tap` works on anything, not just fetch. Pass in any value or expression and
+get it back exactly as it was. The only thing that happens is a log.
+
+```ts
+// numbers, strings, objects — logged and returned as-is
+logger.tap(port, "port")
+logger.tap(process.env.NODE_ENV, "env")
+logger.tap(config, "loaded config")
+```
 
-Works with plain values too — logs it, returns it, nothing changes:
+```ts
+// async functions — promise flows through, timing logged when it settles
+const user = await logger.tap(getUser(), "getUser")
+const config = await logger.tap(loadConfig(), "loadConfig")
+```
 
 ```ts
-const port = logger.tap(5000, "port") // port is still 5000
-const user = logger.tap(await getUser(), "user") // same as without tap
+// inline — no temp variable needed
+server.listen(logger.tap(port, "port"))
 ```
 
+If it's a promise, `tap` logs elapsed time once it settles. If it resolves
+to a `Response` (any fetch like call), you also get status and size, same
+as the fetch example above.
+
 ## 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.
+That `(server.ts:42)` is a **clickable link**. Click it and your editor opens the file and jumps straight to that line. Works in VS Code, iTerm2, WezTerm, Kitty, and Windows Terminal. Degrades to plain text everywhere else.
 
 ## Color-coded levels
 
-`[INFO]` cyan · `[WARN]` yellow · `[ERROR]` red. Timestamp and location tinted teal.
-Auto-disabled when output is piped — no escape codes in your log files.
+`[INFO]` , `[TAP]` cyan · `[WARN]` yellow · `[ERROR]` red. Timestamp and location tinted teal.
+Auto-disabled when output is piped no escape codes in your log files.
 
 ## Tree layout output
 
@@ -121,7 +178,7 @@ Auto-disabled when output is piped — no escape codes in your log files.
 └── 05-30 04:00:00 PM - (server.ts:42)
 ```
 
-Level tag, message, timestamp, and location — all in a clean tree. Easy to scan,
+Level tag, message, timestamp, and location all in a clean tree. Easy to scan,
 even in a busy terminal.
 
 ## Collapsible messages
@@ -131,34 +188,25 @@ logger.maxLines = 5 // show 5 lines, then "... N more lines"
 logger.maxLines = 0 // default — show everything
 ```
 
-### One thing if you re-export it
-
-```ts
-// GOOD — location stays honest
-export { default as logger } from "@meadown/logger"
-
-// BAD — every log points at this file, not the real caller
-export const logger = (...args) => log(...args)
-```
-
 ## 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.
+You shouldn't have to think about whether your logs will leak into production.
+This package reads `NODE_ENV` and handles it for you. Set it to `production`
+and all output is handled for you. You never have to remember to wrap a log call,
+remove a debug line, or grep the codebase before a release.
 
-| `NODE_ENV`                               | Logs?  |
-| ---------------------------------------- | ------ |
-| not set, `development`, or anything else | shown  |
-| `production`                             | silent |
+| `NODE_ENV`                               | Logs?      |
+| ---------------------------------------- | ---------- |
+| not set, `development`, or anything else | shown      |
+| `production`                             | suppressed |
 
 ## Security
 
 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.
+See [SECURITY.md](https://github.com/meadown/meadown-logger/blob/main/SECURITY.md) for the full security model.
 
 ## License
 
-MIT © meadown
+Architected and developed by [Dewan Mobashirul](https://linkedin.com/in/dewan-meadown)
+
+MIT © [meadown](https://github.com/meadown)

package/dist/cjs/core/writeLog.js

@@ -61,7 +61,7 @@ function renderMessage(args, useColor) {
  */
 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 (0, link_js_1.hyperlink)(caller.label, (0, link_js_1.fileUrl)(caller.file, caller.line));
     return caller.label;
 }
 /**

package/dist/cjs/decorations/link.d.ts

@@ -1,11 +1,9 @@
 /**
- * Builds a valid `file://` URL for a path so terminals can open it on click.
- * Paths already in `file://` form are used as-is. We intentionally do NOT append
- * `:line` — that isn't a valid URI and breaks file openers (e.g. GNOME/`gio`,
- * which would look for a file literally named `foo.ts:42`). The line number
- * stays visible in the link's display text instead.
+ * Builds a `file://` URL for a path so terminals can open it on click.
+ * When `line` is provided, appends `:line` so supporting terminals (VS Code,
+ * iTerm2, WezTerm) jump straight to that line.
  */
-export declare function fileUrl(file: string): string;
+export declare function fileUrl(file: string, line?: number): string;
 /**
  * Wraps `text` in an OSC-8 terminal hyperlink pointing at `url`. Terminals that
  * support OSC-8 render `text` as a clickable link; others ignore the escape and

package/dist/cjs/decorations/link.js

@@ -10,14 +10,13 @@ exports.fileUrl = fileUrl;
 exports.hyperlink = hyperlink;
 const node_url_1 = require("node:url");
 /**
- * Builds a valid `file://` URL for a path so terminals can open it on click.
- * Paths already in `file://` form are used as-is. We intentionally do NOT append
- * `:line` — that isn't a valid URI and breaks file openers (e.g. GNOME/`gio`,
- * which would look for a file literally named `foo.ts:42`). The line number
- * stays visible in the link's display text instead.
+ * Builds a `file://` URL for a path so terminals can open it on click.
+ * When `line` is provided, appends `:line` so supporting terminals (VS Code,
+ * iTerm2, WezTerm) jump straight to that line.
  */
-function fileUrl(file) {
-    return file.startsWith("file://") ? file : (0, node_url_1.pathToFileURL)(file).href;
+function fileUrl(file, line) {
+    const base = file.startsWith("file://") ? file : (0, node_url_1.pathToFileURL)(file).href;
+    return line != null ? `${base}:${line}` : base;
 }
 /**
  * Wraps `text` in an OSC-8 terminal hyperlink pointing at `url`. Terminals that

package/dist/core/writeLog.js

@@ -53,7 +53,7 @@ function renderMessage(args, useColor) {
  */
 function formatLocation(caller, interactive) {
     if (caller.file !== null && caller.line !== null && interactive)
-        return hyperlink(caller.label, fileUrl(caller.file));
+        return hyperlink(caller.label, fileUrl(caller.file, caller.line));
     return caller.label;
 }
 /**

package/dist/decorations/link.d.ts

@@ -1,11 +1,9 @@
 /**
- * Builds a valid `file://` URL for a path so terminals can open it on click.
- * Paths already in `file://` form are used as-is. We intentionally do NOT append
- * `:line` — that isn't a valid URI and breaks file openers (e.g. GNOME/`gio`,
- * which would look for a file literally named `foo.ts:42`). The line number
- * stays visible in the link's display text instead.
+ * Builds a `file://` URL for a path so terminals can open it on click.
+ * When `line` is provided, appends `:line` so supporting terminals (VS Code,
+ * iTerm2, WezTerm) jump straight to that line.
  */
-export declare function fileUrl(file: string): string;
+export declare function fileUrl(file: string, line?: number): string;
 /**
  * Wraps `text` in an OSC-8 terminal hyperlink pointing at `url`. Terminals that
  * support OSC-8 render `text` as a clickable link; others ignore the escape and

package/dist/decorations/link.js

@@ -6,14 +6,13 @@
  */
 import { pathToFileURL } from "node:url";
 /**
- * Builds a valid `file://` URL for a path so terminals can open it on click.
- * Paths already in `file://` form are used as-is. We intentionally do NOT append
- * `:line` — that isn't a valid URI and breaks file openers (e.g. GNOME/`gio`,
- * which would look for a file literally named `foo.ts:42`). The line number
- * stays visible in the link's display text instead.
+ * Builds a `file://` URL for a path so terminals can open it on click.
+ * When `line` is provided, appends `:line` so supporting terminals (VS Code,
+ * iTerm2, WezTerm) jump straight to that line.
  */
-export function fileUrl(file) {
-    return file.startsWith("file://") ? file : pathToFileURL(file).href;
+export function fileUrl(file, line) {
+    const base = file.startsWith("file://") ? file : pathToFileURL(file).href;
+    return line != null ? `${base}:${line}` : base;
 }
 /**
  * Wraps `text` in an OSC-8 terminal hyperlink pointing at `url`. Terminals that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meadown/logger",
-  "version": "1.8.7",
+  "version": "1.8.9",
   "description": "A development-focused logger for Node.js and TypeScript — zero dependencies, clickable source links, and API response logging built in.",
   "keywords": [
     "logger",