smart-logging 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +64 -38
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # smart-logging
2
2
 
3
- Zero-setup console interception for Node.js. Install it, import it once at startup, and every `console.log`, `console.error`, etc. automatically routes through [Pino](https://github.com/pinojs/pino) with pretty output, timestamps, and file/line metadata. No manual logger wiring required.
3
+ **Import it once. All your `console.*` logs become async-aware, pretty Pino logs with timestamps and file names—no other changes needed.**
4
4
 
5
- Optional tag helpers (`addTag`, `clearTags`) let you stamp logs with request IDs or any metadata you need.
5
+ Ideal when you just want to install a logger and let it handle every `console.log` in the project automatically.
6
6
 
7
7
  ## Install
8
8
 
@@ -14,70 +14,96 @@ yarn add smart-logging
14
14
  pnpm add smart-logging
15
15
  ```
16
16
 
17
- ## Usage
17
+ ## Why smart-logging?
18
18
 
19
- ### ESM
19
+ | Before (plain `console.log`) | After (`smart-logging`) |
20
+ |---------------------------------------------------------------|----------------------------------------------------------------------------------------|
21
+ | Synchronous console writes can block during heavy logging | Console calls are deferred, keeping the event loop responsive |
22
+ | No timestamp, file, or line information | Every message includes ISO timestamp plus the originating file and line |
23
+ | Hard to trace errors—stack traces get lost in noisy output | Pretty Pino formatting preserves stacks and structures them cleanly |
24
+ | Integrating a logger means rewriting every `console.*` call | Import once; all existing `console.*` calls are patched automatically |
25
+ | Adding request/user metadata requires manual plumbing | `addTag` lets you annotate logs with any key/value scope (requestId, userId, etc.) |
26
+ | Existing projects without logging need major refactors | Drop in the package, import it in the root file, and you’re done |
27
+
28
+ ## 1. Enable automatic logging
29
+
30
+ Do this **once** in the entry file of your app (the place where everything starts). After this, every file can keep using plain `console.log`, `console.error`, etc.—they are all patched automatically.
31
+
32
+ ### ESM entry (e.g. `index.mjs`, `app.js` in `"type": "module"`)
20
33
 
21
34
  ```javascript
22
35
  import 'smart-logging';
23
- // Optional helpers
24
- import { addTag, clearTags } from 'smart-logging';
25
36
 
26
- addTag({ requestId: 'req-123' });
27
- console.log('This will include the requestId, timestamp, and file info');
28
- clearTags();
37
+ console.log('Server booting'); // timestamp + file:line
38
+ console.error(new Error('Oops')); // pretty stack trace
39
+ ```
40
+
41
+ Output:
42
+
43
+ ```
44
+ 2025-11-08 19:03:12.345 src/server.js:4 - Server booting
45
+ 2025-11-08 19:03:12.352 src/server.js:5 - Oops
46
+ Error: Oops
47
+ at ...
29
48
  ```
30
49
 
31
- ### CommonJS
50
+ ### CommonJS entry (e.g. `index.js` without `"type": "module"`)
32
51
 
33
52
  ```javascript
34
53
  require('smart-logging');
35
- const { addTag, clearTags } = require('smart-logging');
36
54
 
37
- addTag({ userId: 'user-42' });
38
- console.error(new Error('Oops!'));
39
- clearTags();
55
+ console.info('Ready to roll');
56
+ console.warn('Using CommonJS');
40
57
  ```
41
58
 
42
- That single import is all you need—every built-in console method is monkey-patched once so your app logs are structured and pretty everywhere.
59
+ Output:
43
60
 
44
- ## Features
61
+ ```
62
+ 2025-11-08 19:05:01.410 src/index.js:4 - Ready to roll
63
+ 2025-11-08 19:05:01.411 src/index.js:5 - Using CommonJS
64
+ ```
45
65
 
46
- - Automatic console interception (`log`, `info`, `warn`, `error`, `debug`)
47
- - Pretty printed output (via `pino-pretty`) with timestamps and file:line
48
- - Async context support using `AsyncLocalStorage`
49
- - `addTag(metadata)` to attach request IDs, user IDs, feature flags, etc.
50
- - `clearTags()` to reset metadata when a request ends
51
- - Works with both ESM `import` and CommonJS `require`
66
+ > Format: `[time] file:line - message`
52
67
 
53
- ## Tags / Metadata
68
+ That’s it. No manual logger instances, no extra function calls. Any module that uses `console` automatically inherits the new behaviour.
54
69
 
55
- Use `addTag` to merge metadata into the current async context. Values must be strings, numbers, booleans, or `null`; anything else throws.
70
+ ## 2. Optional tags (request IDs, users, feature flags…)
71
+
72
+ If you want to attach metadata to every log within a request, call `addTag`. You can use any key name (`requestId`, `userId`, `featureFlag`, `ip`, etc.). Values must be strings, numbers, booleans, or `null`—functions, objects, or arrays are rejected to keep logs safe and predictable.
56
73
 
57
74
  ```javascript
58
- addTag({ requestId: 'req-9000', plan: 'enterprise' });
59
- console.info('Handling billing webhook');
75
+ import 'smart-logging';
76
+ import { addTag, clearTags } from 'smart-logging';
77
+
78
+ addTag({ requestId: 'req-123', userId: 'user-99' });
79
+ console.log('Started processing');
60
80
 
61
- addTag({ featureFlag: 'beta-mode' }); // merges into existing tags
62
- console.warn('Customer enabled beta mode');
81
+ addTag({ featureFlag: 'beta-payments' }); // merges with existing tags
82
+ console.warn('Customer in beta flow');
63
83
 
64
- clearTags(); // resets the context for the next request
84
+ clearTags(); // reset when the request finishes
65
85
  ```
66
86
 
67
- Tags are appended to each log line as `key: value`, making it easy to grep or pipe into log aggregators.
87
+ Logs emitted inside that async call chain will include `requestId`, `userId`, and `featureFlag` automatically:
68
88
 
69
- ## Error Handling
89
+ ```
90
+ 2025-11-08 19:03:45.112 requestId: req-123 userId: user-99 featureFlag: beta-payments api/orders.js:27 - Customer in beta flow
91
+ ```
70
92
 
71
- Unhandled errors retain their stack trace and are sent through Pino with context attached. The package also registers listeners for:
93
+ ## What smart-logging does for you
72
94
 
73
- - `uncaughtException`
74
- - `unhandledRejection`
75
- - `SIGINT` (Ctrl+C)
76
- - `process exit`
95
+ - 🪄 Monkey-patches `console.log`, `info`, `warn`, `error`, and `debug`
96
+ - 🕒 Adds ISO timestamps and prettified output via `pino-pretty`
97
+ - 📁 Prints the relative file name and line number that produced the log
98
+ - 🧵 Uses `AsyncLocalStorage` to carry tags across async boundaries
99
+ - 🚨 Hooks `uncaughtException`, `unhandledRejection`, `SIGINT`, and process exit to log cleanly
100
+ - 🧰 Works in both ESM and CommonJS projects out of the box
77
101
 
78
- ## Contributing
102
+ ## Troubleshooting
79
103
 
80
- PRs and issues are welcome! If you’d like to extend the logger or add integrations, open a discussion first so we can align on direction.
104
+ - **Publishing:** bump the version before each `npm publish`.
105
+ - **Tags not showing:** ensure `addTag` runs before the first log in the async path.
106
+ - **Want custom formatting?** Fork and tweak `support/core/logger-core.cjs`.
81
107
 
82
108
  ## License
83
109
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "smart-logging",
3
- "version": "1.0.1",
3
+ "version": "1.0.2",
4
4
  "description": "",
5
5
  "main": "./index.cjs",
6
6
  "type": "module",