debug-fabulous 2.0.43 → 2.0.44

package/README.md

@@ -1,54 +1,132 @@
-# debug-fabulous [![NPM version][npm-image]][npm-url] [![build status][travis-image]][travis-url] [![Test coverage][coveralls-image]][coveralls-url]
+# debug-fabulous
+
+**Lazy-evaluation wrapper for [`debug`](https://github.com/debug-js/debug) — skip string building entirely when logging is disabled.**
+
+[![npm version](https://img.shields.io/npm/v/debug-fabulous.svg)](https://www.npmjs.com/package/debug-fabulous)
+[![npm downloads](https://img.shields.io/npm/dw/debug-fabulous.svg)](https://www.npmjs.com/package/debug-fabulous)
+[![tests](https://github.com/brickhouse-tech/debug-fabulous/actions/workflows/tests.yml/badge.svg)](https://github.com/brickhouse-tech/debug-fabulous/actions/workflows/tests.yml)
+
+## Why?
+
+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.
+
+**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.
+
+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.
 
 ## Install
 
-`npm install --save debug-fabulous`
+```bash
+npm install debug-fabulous
+```
+
+## Quick Start
 
-## Purpose:
+```js
+const debugFab = require('debug-fabulous');
+const debug = debugFab()('my-app');
 
-Wrapper / Extension around [visionmedia's debug](https://github.com/visionmedia/debug) to allow lazy evaluation of debugging via closure handling.
+// Lazy evaluation — the function only runs if 'my-app' is enabled
+debug(() => 'user object: ' + JSON.stringify(largeUserObject));
 
-## Why would I consider using this library?
+// Plain strings still work
+debug('server started on port %d', 3000);
+```
 
-The main utilities added to this library is lazy log level evaluation. This allows whatever logged strings to only be created and evaluated if a log level is active. This can considerably reduce the amount of memory used in logging when you are not using.
+### Spawning Child Debuggers
 
-With this in mind, there are no excuses to not log anything and everything as performance can be kept in check easily (via log levels).
+Create hierarchical namespaces without string juggling:
 
-### Proof
+```js
+const debugFab = require('debug-fabulous');
+const debug = debugFab()('my-app');
 
-For analysis of the performance results are in [perfWith.out](./test/perf/perfWith.out) and [perfWithout.out](./test/perf/perfWithout.out).
+const dbDebug = debug.spawn('db');       // my-app:db
+const queryDebug = dbDebug.spawn('query'); // my-app:db:query
 
-In summary, the tests using this library are using 3 times less memory for the same logging statements (when the log levels are disabled).
+dbDebug('connected');
+queryDebug(() => `SELECT took ${ms}ms, returned ${rows.length} rows`);
+```
 
-## This library essentially wraps two things:
+### Standalone Spawnable
 
-- [lazy-eval](./src/lazy-eval.js): debug closure handling
-- [spawn](./src/spawn.js): spawns off existing namespaces for a sub namespace.
+If you just need hierarchical debuggers without the factory:
 
-## Example:
+```js
+const { spawnable } = require('debug-fabulous');
+const debug = spawnable('my-app');
+
+const child = debug.spawn('worker');  // my-app:worker
+child('processing job %d', jobId);
+```
+
+## TypeScript
+
+debug-fabulous is written in TypeScript and ships type declarations.
+
+```ts
+import debugFab, { spawnable } from 'debug-fabulous';
+
+const debug = debugFab()('my-app');
+
+// Lazy eval with type safety
+debug(() => `processed ${items.length} items`);
+
+// Spawn children
+const child = debug.spawn('worker');
+child('ready');
+
+// Return an array for format strings
+debug(() => ['found %d results in %dms', count, elapsed]);
+```
 
-For usage see the [tests](./test) or the example below.
+## API
+
+### `debugFab(debugApi?)`
+
+Returns a wrapped `debug` factory with lazy evaluation and namespace caching.
+
+- **`debugApi`** *(optional)* — a custom `debug` instance. Defaults to `require('debug')`.
+
+The returned factory has the same API as `debug` (`enable()`, `disable()`, `load()`, `save()`, etc.) plus lazy evaluation support.
+
+### `debug(fn)` — Lazy Evaluation
+
+Pass a function instead of a string. It's only called when the namespace is enabled:
+
+```js
+// Function returns a string
+debug(() => expensiveStringOperation());
+
+// Function returns [formatter, ...args] array
+debug(() => ['user %s performed %d actions', userName, count]);
+```
+
+### `debug.spawn(namespace)`
+
+Creates a child debugger under the current namespace:
+
+```js
+const root = debug('app');       // app
+const db = root.spawn('db');     // app:db
+const cache = db.spawn('cache'); // app:db:cache
+```
+
+### `spawnable(namespace, debugFabFactory?)`
+
+Standalone function that creates a spawnable debugger directly:
 
 ```js
-var debug = require('')();
-// force namespace to be enabled otherwise it assumes process.env.DEBUG is setup
-// debug.save('namespace');
-// debug.enable(debug.load())
-debug = debug('namespace'); // debugger in the namespace
-debug(function() {
-  return 'something to log' + someLargeHarryString;
-});
-debug(() => 'something to log ${someLargeHarryString}');
-debug('small out'); // prints namespace small out
-var childDbg = debug.spawn('child'); // debugger in the namespace:child
-childDbg('small out'); // prints namespace:child small out
-var grandChildDbg = debug.spawn('grandChild'); // debugger in the namespace:child:grandChild
-grandChildDbg('small out'); // prints namespace:child:grandChild small out
-```
-
-[npm-image]: https://img.shields.io/npm/v/debug-fabulous.svg
-[npm-url]: https://www.npmjs.com/package/debug-fabulous
-[travis-image]: https://img.shields.io/travis/nmccready/debug-fabulous.svg
-[travis-url]: https://travis-ci.org/nmccready/debug-fabulous
-[coveralls-image]: https://coveralls.io/repos/github/nmccready/debug-fabulous/badge.svg
-[coveralls-url]: https://coveralls.io/github/nmccready/debug-fabulous?branch=master
+const { spawnable } = require('debug-fabulous');
+const debug = spawnable('app');
+```
+
+## How It Works
+
+1. **Namespace caching** — `Map`-based memoization means repeated `debug('same-ns')` calls return the same instance instantly.
+2. **Singleton no-op** — Disabled namespaces get a shared no-op function instead of allocating per-instance.
+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()`.
+
+## License
+
+[MIT](./LICENSE) — Nicholas McCready and [contributors](https://github.com/brickhouse-tech/debug-fabulous/graphs/contributors).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "debug-fabulous",
-  "version": "2.0.43",
+  "version": "2.0.44",
   "description": "visionmedia debug extensions rolled into one",
   "keywords": [
     "debug",