Lazy-evaluation wrapper for debug — skip string building entirely when logging is disabled.
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 (700K+ weekly downloads) use debug-fabulous as a transitive dependency for exactly this reason.
Install
npm install debug-fabulous
Quick Start
const debugFab = require('debug-fabulous');const debug = debugFab()('my-app');// Lazy evaluation — the function only runs if 'my-app' is enableddebug(() => 'user object: ' + JSON.stringify(largeUserObject));// Plain strings still workdebug('server started on port %d', 3000);
Spawning Child Debuggers
Create hierarchical namespaces without string juggling:
debug-fabulous is written in TypeScript and ships type declarations.
import debugFab, { spawnable } from 'debug-fabulous';const debug = debugFab()('my-app');// Lazy eval with type safetydebug(() => `processed ${items.length} items`);// Spawn childrenconst child = debug.spawn('worker');child('ready');// Return an array for format stringsdebug(() => ['found %d results in %dms', count, elapsed]);
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:
// Function returns a stringdebug(() => expensiveStringOperation());// Function returns [formatter, ...args] arraydebug(() => ['user %s performed %d actions', userName, count]);
debug.spawn(namespace)
Creates a child debugger under the current namespace:
Namespace caching — Map-based memoization means repeated debug('same-ns') calls return the same instance instantly.
Singleton no-op — Disabled namespaces get a shared no-op function instead of allocating per-instance.
Lazy closures — When you pass a function, it's never invoked if the namespace is disabled. No string allocation, no concatenation, no JSON.stringify().
Sponsor
If you find this project useful, consider sponsoring @nmccready to support ongoing maintenance and development. ❤️