Glogg Global Logger

Common errors

• ERR_REQUIRE_ESM: Must use import to load ES Module

  cause Attempting to use `import getLogger from 'glogg';` in an ESM module context or a bundler that strictly enforces ESM.
  fix Change the import statement to `const getLogger = require('glogg');`. Ensure your project's `package.json` does not have `"type": "module"` if you intend to primarily use CommonJS modules without transpilation.

• Unhandled 'error' event (process exit)

  cause A `logger.error()` method was called, but no listener was registered for the 'error' event on that logger instance.
  fix Add an error event listener to your logger instance: `logger.on('error', (msg) => { console.error('Caught glogg error:', msg); /* Handle gracefully */ });`

Warnings

• breaking The minimum Node.js version requirement was updated to `>= 10.13.0`.
  Fix: Ensure your Node.js environment meets or exceeds version 10.13.0. Users on older Node.js versions must remain on glogg v1.x.
• gotcha The Node.js process will crash if an `error` event is emitted by a logger and there are no listeners attached to handle it.
  Fix: Always attach at least one listener to the `error` event using `logger.on('error', handlerFunction)` to prevent process termination. This is standard Node.js `EventEmitter` behavior for 'error' events.
• gotcha Glogg does not filter log levels internally. All calls to `debug`, `info`, `warn`, and `error` will emit their respective events. Filtering based on desired verbosity or environment must be implemented within your event listeners.
  Fix: Implement conditional logic within your `logger.on()` handlers to process or discard messages based on their level or other criteria (e.g., `if (level === 'debug' && process.env.NODE_ENV !== 'development') return;`).
• gotcha Glogg is a CommonJS-only package. Attempting to use ESM `import` syntax will lead to runtime errors (`ERR_REQUIRE_ESM` or 'Cannot use import statement outside a module') in environments that don't transpile or handle CJS interoperability.
  Fix: Use CommonJS `require()` syntax: `const getLogger = require('glogg');`. If you are in an ESM module context, you may need to use a CJS wrapper or consider alternatives that support ESM directly.

Install

• npm install glogg npm
• yarn add glogg yarn
• pnpm add glogg pnpm

Imports

• getLogger
  wrong:

  import getLogger from 'glogg';

  correct:

  const getLogger = require('glogg');

  This package is CommonJS-only. Attempting to use ESM `import` will result in a runtime error like 'ERR_REQUIRE_ESM' or 'Cannot use import statement outside a module'.
• logger.on

  logger.on('event', handler);

  Used to subscribe to log events ('debug', 'info', 'warn', 'error'). Attaching a listener to the 'error' event is critical to prevent the Node.js process from crashing on unhandled errors.
• debug / info / warn / error methods
  wrong:

  import { info } from 'glogg';

  correct:

  const { info, error } = logger;

  These methods (e.g., `logger.debug()`, `logger.info()`) are properties of the logger instance returned by `getLogger()`. They cannot be directly imported from the package. Destructuring them from the logger instance has been supported since v1.0.1.

Quickstart

Demonstrates how to create namespaced loggers, subscribe to different log levels (info, error), and emit various types of messages using `util.format()` style string interpolation and direct object logging. It explicitly highlights the critical error handling requirement to prevent process crashes.

const getLogger = require('glogg');

// Create a logger for a specific namespace
const mainLogger = getLogger('my-app');

// Create another logger for a different module
const dataModuleLogger = getLogger('data-processor');

// Listen for 'info' events from the 'my-app' namespace
mainLogger.on('info', (message) => {
  console.log(`[MainApp Info Listener]: ${message}`);
});

// IMPORTANT: You *must* handle 'error' events, or the process will crash.
mainLogger.on('error', (errMessage) => {
  console.error(`[MainApp Error Handler]: CRITICAL! ${errMessage}`);
  // In a real application, you might exit, log to a different system, etc.
});

// Log various types of messages
mainLogger.debug('This is a verbose debug message at %s.', new Date().toLocaleTimeString());
mainLogger.info('Application started successfully at %s.', new Date().toISOString());
mainLogger.warn('A configuration setting is missing, falling back to default.');
mainLogger.error('Failed to connect to database: Connection refused!');

// Log without string formatting - all arguments are emitted directly
dataModuleLogger.info({ event: 'data_processed', count: 123, status: 'success' });
dataModuleLogger.debug(['debug array', { key: 'value' }]);

// Demonstrates a message from a different logger
dataModuleLogger.warn('Data processing took longer than expected.');

// Output from a listener that applies custom filtering (conceptual)
// For instance, only process warnings from 'data-processor' in a specific way
dataModuleLogger.on('warn', (msg) => {
    if (msg.includes('longer than expected')) {
        console.log(`[Special Data Warn]: Specific issue noted: ${msg}`);
    }
});

// Simulate another error (this would also crash if not handled by mainLogger's handler)
// mainLogger.error('Another critical failure point!');