where-log 0.1.1 → 0.2.1
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.
- package/README.md +90 -3
- package/dist/index.cjs +560 -37
- package/dist/index.d.cts +107 -4
- package/dist/index.d.ts +107 -4
- package/dist/index.mjs +544 -37
- package/package.json +5 -2
package/README.md
CHANGED
|
@@ -1,17 +1,17 @@
|
|
|
1
|
-
#
|
|
1
|
+
# where-log
|
|
2
2
|
|
|
3
3
|
Log a value with the caller file and line number.
|
|
4
4
|
|
|
5
5
|
## Install
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
-
npm install
|
|
8
|
+
npm install where-log
|
|
9
9
|
```
|
|
10
10
|
|
|
11
11
|
## Usage
|
|
12
12
|
|
|
13
13
|
```ts
|
|
14
|
-
import { log } from "
|
|
14
|
+
import { log } from "where-log";
|
|
15
15
|
|
|
16
16
|
const user = { id: 1, name: "Shovon" };
|
|
17
17
|
log(user);
|
|
@@ -41,6 +41,49 @@ log("user", user, {
|
|
|
41
41
|
valueLine: `${label}: ${JSON.stringify(value)}`,
|
|
42
42
|
}),
|
|
43
43
|
});
|
|
44
|
+
|
|
45
|
+
log(user, { mode: "fast", includeLocation: false });
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Preset APIs:
|
|
49
|
+
|
|
50
|
+
```ts
|
|
51
|
+
import { createLogger, logDev, logProd } from "where-log";
|
|
52
|
+
|
|
53
|
+
logDev("user", user); // pretty + location
|
|
54
|
+
logProd("user", user); // fast + no location
|
|
55
|
+
|
|
56
|
+
const appLog = createLogger({ redact: ["user.token"], includeLocation: false });
|
|
57
|
+
appLog("request", { user: { token: "secret" } });
|
|
58
|
+
appLog.info("ready", { status: "ok" });
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Level APIs:
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
import { debug, error, info, success, warn } from "where-log";
|
|
65
|
+
|
|
66
|
+
info("user", user);
|
|
67
|
+
success("saved", { id: 1 });
|
|
68
|
+
warn("quota", { remaining: 2 });
|
|
69
|
+
error("request", { status: 500 });
|
|
70
|
+
debug("trace", { step: "auth" });
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Once / Timer / Context APIs:
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
import { once, time, timeEnd, withContext } from "where-log";
|
|
77
|
+
|
|
78
|
+
once("boot:db", "db connected");
|
|
79
|
+
once("boot:db", "db connected again"); // ignored
|
|
80
|
+
|
|
81
|
+
time("fetch-users");
|
|
82
|
+
// ... work
|
|
83
|
+
timeEnd("fetch-users", { total: 42 }, { warnThresholdMs: 200, errorThresholdMs: 800 });
|
|
84
|
+
|
|
85
|
+
const reqLog = withContext({ requestId: "req_123", userId: 7 }, { includeLocation: false });
|
|
86
|
+
reqLog.info("request", { path: "/api/users" });
|
|
44
87
|
```
|
|
45
88
|
|
|
46
89
|
## Notes
|
|
@@ -49,11 +92,55 @@ log("user", user, {
|
|
|
49
92
|
- Browser/Next.js: call-site depends on source maps and bundler/devtools behavior.
|
|
50
93
|
- If stack parsing fails, the package prints `unknown:0` on line 1.
|
|
51
94
|
|
|
95
|
+
## Performance Tuning
|
|
96
|
+
|
|
97
|
+
- `mode: "pretty"` (default): rich formatting via Node inspect.
|
|
98
|
+
- `mode: "fast"`: lower overhead formatting for hot paths.
|
|
99
|
+
- `includeLocation: false`: skips stack capture/parsing.
|
|
100
|
+
- `inspectDepth`: limit inspect depth in pretty mode.
|
|
101
|
+
- `enabled: false`: disables log output quickly.
|
|
102
|
+
|
|
103
|
+
## Safety / Readability
|
|
104
|
+
|
|
105
|
+
- `redact`: mask sensitive values by path, e.g. `["password", "user.token"]`.
|
|
106
|
+
- `maxArrayLength`: trim large arrays and append a summary item.
|
|
107
|
+
- level helpers prepend compact tags by default (`[INFO]`, `[ERROR]`, etc.).
|
|
108
|
+
|
|
109
|
+
## Session Helpers
|
|
110
|
+
|
|
111
|
+
- `once(key, ...)`: log only first occurrence per runtime session.
|
|
112
|
+
- `time(key)` + `timeEnd(key, ...)`: duration logging with optional thresholds.
|
|
113
|
+
- `resetOnce(keys?)` and `resetTimers(keys?)`: clear in-memory runtime state.
|
|
114
|
+
- `withContext(context)`: create logger with injected structured context.
|
|
115
|
+
|
|
52
116
|
## API
|
|
53
117
|
|
|
54
118
|
- `log(value: unknown): void`
|
|
55
119
|
- `log(value: unknown, options?: LogOptions): void`
|
|
56
120
|
- `log(label: string, value: unknown, options?: LogOptions): void`
|
|
121
|
+
- `info(...)`, `success(...)`, `warn(...)`, `error(...)`, `debug(...)`
|
|
122
|
+
- `once(...)`, `time(...)`, `timeEnd(...)`
|
|
123
|
+
- `logDev(...)`: dev preset (`pretty`, `includeLocation: true`, `colors: true`)
|
|
124
|
+
- `logProd(...)`: prod preset (`fast`, `includeLocation: false`, `colors: false`)
|
|
125
|
+
- `createLogger(presetOptions?: LogOptions): LoggerFn`
|
|
126
|
+
- `withContext(context, presetOptions?): LoggerFn`
|
|
127
|
+
- `resetOnce(keys?)`, `resetTimers(keys?)`
|
|
128
|
+
- `LogMode = "pretty" | "fast"`
|
|
129
|
+
- `LogLevel = "info" | "success" | "warn" | "error" | "debug"`
|
|
57
130
|
- `LogOptions`
|
|
131
|
+
- `enabled?: boolean`
|
|
132
|
+
- `mode?: LogMode` (default `"pretty"`)
|
|
133
|
+
- `includeLocation?: boolean` (default `true`)
|
|
134
|
+
- `inspectDepth?: number` (pretty mode only)
|
|
135
|
+
- `maxArrayLength?: number`
|
|
136
|
+
- `redact?: string[]`
|
|
137
|
+
- `level?: LogLevel`
|
|
138
|
+
- `showLevelTag?: boolean`
|
|
139
|
+
- `consoleMethod?: "log" | "info" | "warn" | "error" | "debug"`
|
|
140
|
+
- `context?: Record<string, unknown>`
|
|
141
|
+
- `clockNow?: () => number`
|
|
142
|
+
- `warnThresholdMs?: number`
|
|
143
|
+
- `errorThresholdMs?: number`
|
|
144
|
+
- `includeDurationOnly?: boolean`
|
|
58
145
|
- `colors?: boolean` (Node only, default `true`)
|
|
59
146
|
- `formatter?: (input) => { locationLine: unknown; valueLine: unknown }`
|