obug Lightweight Debugging Utility

Common errors

• TypeError: obug is not a function

  cause Attempting to call the top-level `obug` module as a function (similar to `require('debug')('namespace')`) in an ESM context, or incorrectly importing the default export.
  fix Use the named export `createDebug` explicitly: `import { createDebug } from 'obug'; const debug = createDebug('my-namespace');`

• TypeError: Cannot read properties of undefined (reading 'createDebug')

  cause Incorrectly trying to destructure `createDebug` from a CommonJS `require('obug')` that doesn't expose it this way, or a typo in the named import.
  fix Ensure you are using `import { createDebug } from 'obug';` for ESM, and verify that your environment is properly configured for ESM. If strictly in CJS, you may need a bundler to resolve the ESM module correctly.

• ReferenceError: exports is not defined in ES module scope

  cause Attempting to use CommonJS-specific globals (`exports`, `module.exports`, `require`) within an ES Module file (`.mjs` or `type: "module"` in `package.json`).
  fix Convert your module to use ES Module syntax (`import`/`export`). `obug` is built for ESM, and mixing CJS patterns can lead to errors.

Warnings

• breaking obug v2 introduced a significant rewrite that refactors API imports and usage compared to v1. Direct replacements for `debug`'s default export might not work without modification.
  Fix: Update all import statements to use named exports (e.g., `import { createDebug } from 'obug'`) instead of relying on a default export or a CommonJS-style `require('obug')` that returns a function.
• gotcha obug drops support for older browsers and Node.js versions compared to the original `debug` package, specifically targeting ES2015+ environments.
  Fix: Ensure your project's target environment supports ES2015+ features (e.g., modern browsers, Node.js 14+). If targeting older runtimes, consider using the original `debug` package or transpiling your code.
• gotcha obug is designed with native ES Module (ESM) compatibility in mind. Using CommonJS `require()` in an ESM context or a mixed environment without proper configuration can lead to import issues.
  Fix: Prefer `import ... from 'obug'` syntax. If using CommonJS, ensure your build setup correctly handles ESM imports or configure Node.js with `--experimental-loader esm` (though named imports are still the preferred way).

Install

• npm install obug npm
• yarn add obug yarn
• pnpm add obug pnpm

Imports

• createDebug
  wrong:

  const createDebug = require('obug').createDebug

  correct:

  import { createDebug } from 'obug'

  v2 refactored API imports, use named exports for ESM.
• disable
  wrong:

  const disable = require('obug').disable

  correct:

  import { disable } from 'obug'

  v2 refactored API imports, use named exports for ESM.
• namespaces
  wrong:

  const namespaces = require('obug').namespaces

  correct:

  import { namespaces } from 'obug'

  v2 refactored API imports, use named exports for ESM.

Quickstart

Demonstrates `obug` installation, creating debuggers, enabling/disabling namespaces, and using sub-namespaces.

import { createDebug, disable, enable, enabled, namespaces } from 'obug';

// Enable debug messages for 'my-namespace' and its sub-namespaces
enable('my-namespace*');

// Get the currently enabled namespaces
console.log('Enabled namespaces:', namespaces());

const debug = createDebug('my-namespace', {
  // All options are optional
  useColors: true, // false, true, undefined for auto-detect
  color: 2, // custom color (e.g., ANSI color code)
  // custom formatArgs (Node.js only)
  formatArgs(args) {
    // Example: prepend a timestamp
    args[0] = `[${new Date().toISOString()}] ${args[0]}`;
  },
  formatters: {}, // custom formatters (like debug.formatters)
  // Node.js only options
  inspectOpts: { depth: 4 },
  // custom log function
  log: console.log,
});

// This message will be logged because 'my-namespace' is enabled
debug('This is a debug message for %s', 'my-component');
console.log(
  'Namespace:', debug.namespace, // 'my-namespace'
  'Enabled:', debug.enabled,     // true
  'Using colors:', debug.useColors, // true
);

// Create a sub-namespace, inheriting options from the parent
const sub = debug.extend('sub-namespace');
sub('This is a sub-namespace debug message with an object: %o', { id: 123, status: 'active' });
console.log('Sub-namespace:', sub.namespace); // 'my-namespace:sub-namespace'

// Example of disabling debug messages
disable('my-namespace*');
console.log('Enabled after disable:', enabled('my-namespace')); // Should be false or empty

const debug2 = createDebug('another-namespace');
debug2('This message will NOT appear because its namespace is not enabled.');