# debug-fabulous

> visionmedia debug extensions rolled into one

Latest version **2.0.109** (published 2026-09-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install debug-fabulous
pnpm add debug-fabulous
yarn add debug-fabulous
bun add debug-fabulous
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 2.0.109 |
| Published | 2026-09-23 |
| First published | 2016-10-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >= 20 |
| Dependencies | 1 |
| Unpacked size | 12 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 6 |
| Author | Nicholas McCready |
| Maintainers | nmccready |
| Keywords | debug, lazy, lazy-eval |

## Links

- npm: https://www.npmjs.com/package/debug-fabulous
- Repository: https://github.com/brickhouse-tech/debug-fabulous
- Homepage: https://github.com/brickhouse-tech/debug-fabulous#readme
- Issues: https://github.com/brickhouse-tech/debug-fabulous/issues
- npm.io page: https://npm.io/package/debug-fabulous

## Dependencies (1)

- [debug](https://npm.io/package/debug.md) 4.4.3

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 2.0.109 (latest) — 2026-09-23
- 2.0.108 — 2026-09-22
- 2.0.107 — 2026-09-17
- 2.0.106 — 2026-09-15
- 2.0.105 — 2026-09-14
- 2.0.104 — 2026-09-09
- 2.0.103 — 2026-09-09
- 2.0.102 — 2026-09-08
- 2.0.100 — 2026-09-02
- 2.0.99 — 2026-09-01
- 2.0.98 — 2026-08-26
- 2.0.97 — 2026-08-20
- 2.0.96 — 2026-08-19
- 2.0.95 — 2026-08-18
- 2.0.94 — 2026-08-17
- … 96 more at https://npm.io/package/debug-fabulous/versions

## README

# 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

```bash
npm install debug-fabulous
```

## Quick Start

```js
const debugFab = require('debug-fabulous');
const debug = debugFab()('my-app');

// Lazy evaluation — the function only runs if 'my-app' is enabled
debug(() => 'user object: ' + JSON.stringify(largeUserObject));

// Plain strings still work
debug('server started on port %d', 3000);
```

### Spawning Child Debuggers

Create hierarchical namespaces without string juggling:

```js
const debugFab = require('debug-fabulous');
const debug = debugFab()('my-app');

const dbDebug = debug.spawn('db');       // my-app:db
const queryDebug = dbDebug.spawn('query'); // my-app:db:query

dbDebug('connected');
queryDebug(() => `SELECT took ${ms}ms, returned ${rows.length} rows`);
```

### Standalone Spawnable

If you just need hierarchical debuggers without the factory:

```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]);
```

## 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
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()`.

## Sponsor

If you find this project useful, consider [sponsoring @nmccready](https://github.com/sponsors/nmccready) to support ongoing maintenance and development. ❤️

## License

[MIT](./LICENSE) — Nicholas McCready and [contributors](https://github.com/brickhouse-tech/debug-fabulous/graphs/contributors).

---
_Source: https://npm.io/package/debug-fabulous · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._