debug-fabulous 2.0.43 → 2.0.45
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 +119 -37
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,54 +1,136 @@
|
|
|
1
|
-
# debug-fabulous
|
|
1
|
+
# debug-fabulous
|
|
2
|
+
|
|
3
|
+
**Lazy-evaluation wrapper for [`debug`](https://github.com/debug-js/debug) — skip string building entirely when logging is disabled.**
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/debug-fabulous)
|
|
6
|
+
[](https://www.npmjs.com/package/debug-fabulous)
|
|
7
|
+
[](https://github.com/brickhouse-tech/debug-fabulous/actions/workflows/tests.yml)
|
|
8
|
+
|
|
9
|
+
## Why?
|
|
10
|
+
|
|
11
|
+
The `debug` module always evaluates its arguments, even when the namespace is disabled. If you're building expensive strings — JSON serialization, large object inspection, string concatenation — you pay the cost even when nobody's reading the output.
|
|
12
|
+
|
|
13
|
+
**debug-fabulous** wraps `debug` with lazy evaluation. Pass a function instead of a string, and it only runs when the namespace is actually enabled. When logging is off, the call is a no-op — no string allocation, no concatenation, no wasted cycles.
|
|
14
|
+
|
|
15
|
+
This matters at scale. Libraries like [`gulp-sourcemaps`](https://www.npmjs.com/package/gulp-sourcemaps) (700K+ weekly downloads) use debug-fabulous as a transitive dependency for exactly this reason.
|
|
2
16
|
|
|
3
17
|
## Install
|
|
4
18
|
|
|
5
|
-
|
|
19
|
+
```bash
|
|
20
|
+
npm install debug-fabulous
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Quick Start
|
|
24
|
+
|
|
25
|
+
```js
|
|
26
|
+
const debugFab = require('debug-fabulous');
|
|
27
|
+
const debug = debugFab()('my-app');
|
|
28
|
+
|
|
29
|
+
// Lazy evaluation — the function only runs if 'my-app' is enabled
|
|
30
|
+
debug(() => 'user object: ' + JSON.stringify(largeUserObject));
|
|
31
|
+
|
|
32
|
+
// Plain strings still work
|
|
33
|
+
debug('server started on port %d', 3000);
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
### Spawning Child Debuggers
|
|
37
|
+
|
|
38
|
+
Create hierarchical namespaces without string juggling:
|
|
39
|
+
|
|
40
|
+
```js
|
|
41
|
+
const debugFab = require('debug-fabulous');
|
|
42
|
+
const debug = debugFab()('my-app');
|
|
43
|
+
|
|
44
|
+
const dbDebug = debug.spawn('db'); // my-app:db
|
|
45
|
+
const queryDebug = dbDebug.spawn('query'); // my-app:db:query
|
|
6
46
|
|
|
7
|
-
|
|
47
|
+
dbDebug('connected');
|
|
48
|
+
queryDebug(() => `SELECT took ${ms}ms, returned ${rows.length} rows`);
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### Standalone Spawnable
|
|
52
|
+
|
|
53
|
+
If you just need hierarchical debuggers without the factory:
|
|
8
54
|
|
|
9
|
-
|
|
55
|
+
```js
|
|
56
|
+
const { spawnable } = require('debug-fabulous');
|
|
57
|
+
const debug = spawnable('my-app');
|
|
10
58
|
|
|
11
|
-
|
|
59
|
+
const child = debug.spawn('worker'); // my-app:worker
|
|
60
|
+
child('processing job %d', jobId);
|
|
61
|
+
```
|
|
12
62
|
|
|
13
|
-
|
|
63
|
+
## TypeScript
|
|
14
64
|
|
|
15
|
-
|
|
65
|
+
debug-fabulous is written in TypeScript and ships type declarations.
|
|
16
66
|
|
|
17
|
-
|
|
67
|
+
```ts
|
|
68
|
+
import debugFab, { spawnable } from 'debug-fabulous';
|
|
18
69
|
|
|
19
|
-
|
|
70
|
+
const debug = debugFab()('my-app');
|
|
20
71
|
|
|
21
|
-
|
|
72
|
+
// Lazy eval with type safety
|
|
73
|
+
debug(() => `processed ${items.length} items`);
|
|
22
74
|
|
|
23
|
-
|
|
75
|
+
// Spawn children
|
|
76
|
+
const child = debug.spawn('worker');
|
|
77
|
+
child('ready');
|
|
24
78
|
|
|
25
|
-
|
|
26
|
-
|
|
79
|
+
// Return an array for format strings
|
|
80
|
+
debug(() => ['found %d results in %dms', count, elapsed]);
|
|
81
|
+
```
|
|
27
82
|
|
|
28
|
-
##
|
|
83
|
+
## API
|
|
29
84
|
|
|
30
|
-
|
|
85
|
+
### `debugFab(debugApi?)`
|
|
86
|
+
|
|
87
|
+
Returns a wrapped `debug` factory with lazy evaluation and namespace caching.
|
|
88
|
+
|
|
89
|
+
- **`debugApi`** *(optional)* — a custom `debug` instance. Defaults to `require('debug')`.
|
|
90
|
+
|
|
91
|
+
The returned factory has the same API as `debug` (`enable()`, `disable()`, `load()`, `save()`, etc.) plus lazy evaluation support.
|
|
92
|
+
|
|
93
|
+
### `debug(fn)` — Lazy Evaluation
|
|
94
|
+
|
|
95
|
+
Pass a function instead of a string. It's only called when the namespace is enabled:
|
|
96
|
+
|
|
97
|
+
```js
|
|
98
|
+
// Function returns a string
|
|
99
|
+
debug(() => expensiveStringOperation());
|
|
100
|
+
|
|
101
|
+
// Function returns [formatter, ...args] array
|
|
102
|
+
debug(() => ['user %s performed %d actions', userName, count]);
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### `debug.spawn(namespace)`
|
|
106
|
+
|
|
107
|
+
Creates a child debugger under the current namespace:
|
|
31
108
|
|
|
32
109
|
```js
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
110
|
+
const root = debug('app'); // app
|
|
111
|
+
const db = root.spawn('db'); // app:db
|
|
112
|
+
const cache = db.spawn('cache'); // app:db:cache
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### `spawnable(namespace, debugFabFactory?)`
|
|
116
|
+
|
|
117
|
+
Standalone function that creates a spawnable debugger directly:
|
|
118
|
+
|
|
119
|
+
```js
|
|
120
|
+
const { spawnable } = require('debug-fabulous');
|
|
121
|
+
const debug = spawnable('app');
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## How It Works
|
|
125
|
+
|
|
126
|
+
1. **Namespace caching** — `Map`-based memoization means repeated `debug('same-ns')` calls return the same instance instantly.
|
|
127
|
+
2. **Singleton no-op** — Disabled namespaces get a shared no-op function instead of allocating per-instance.
|
|
128
|
+
3. **Lazy closures** — When you pass a function, it's never invoked if the namespace is disabled. No string allocation, no concatenation, no `JSON.stringify()`.
|
|
129
|
+
|
|
130
|
+
## Sponsor
|
|
131
|
+
|
|
132
|
+
If you find this project useful, consider [sponsoring @nmccready](https://github.com/sponsors/nmccready) to support ongoing maintenance and development. ❤️
|
|
133
|
+
|
|
134
|
+
## License
|
|
135
|
+
|
|
136
|
+
[MIT](./LICENSE) — Nicholas McCready and [contributors](https://github.com/brickhouse-tech/debug-fabulous/graphs/contributors).
|