Bare Events

Common errors

• TypeError: EventEmitter is not a constructor

  cause Attempting to instantiate `EventEmitter` when it was incorrectly imported as a default export in an ES Module context or when destructuring a CommonJS `require` call incorrectly.
  fix For ES Modules: `import { EventEmitter } from 'bare-events';`. For CommonJS: `const EventEmitter = require('bare-events');` (without destructuring if the top-level export is the constructor).

• Unhandled 'error' event. ([Error object details])

  cause An `error` event was emitted by an `EventEmitter` instance, but no listener was registered to handle it. In Node.js, this typically leads to a process crash.
  fix Always register an error handler for any `EventEmitter` that might emit errors: `myEmitter.on('error', (err) => { console.error('Caught an error:', err); });`

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` in an ES Module (ESM) file (e.g., a `.mjs` file or a `.js` file in a package with `"type": "module"` in `package.json`).
  fix Switch to ES Module `import` syntax: `import { EventEmitter } from 'bare-events';`

Warnings

• gotcha Failing to remove event listeners, especially for long-lived emitters or frequently created components, can lead to memory leaks. This is a common pitfall with all event emitter implementations.
  Fix: Always pair `on` or `once` with a corresponding `off` call when the listener is no longer needed. Consider using `AbortController` (via `bare-abort-controller`) to manage listener lifecycles, or ensure components clean up their listeners on unmount/destroy.
• breaking In Node.js, if an `error` event is emitted and no listeners are attached to it, the process will crash. This default behavior can be unexpected for new users.
  Fix: Always add a listener for the `error` event on any `EventEmitter` instance that might emit errors. For example: `myEmitter.on('error', (err) => console.error('Caught:', err));`
• gotcha The `this` context within event listener functions can be inconsistent depending on how the function is defined and called. Traditional `function` declarations will have `this` bound to the `EventEmitter` instance, but arrow functions retain the `this` from their lexical scope.
  Fix: Use arrow functions (`(payload) => { /* ... */ }`) if you want `this` to refer to the surrounding lexical context. If you explicitly need `this` to be the `EventEmitter` instance, use a traditional `function (payload) { /* ... */ }` declaration or manually bind the function (e.g., `listener.bind(myEmitter)`).
• gotcha When migrating from CommonJS `require()` to ES Modules `import`, ensure you use named imports (`import { EventEmitter } from 'bare-events'`) rather than default imports, as `bare-events` does not provide a default export for its main class.
  Fix: Update `import EventEmitter from 'bare-events'` to `import { EventEmitter } from 'bare-events'` in ES Module files. Ensure your build configuration correctly handles module resolution for both CJS and ESM if you have a mixed codebase.

Install

• npm install bare-events npm
• yarn add bare-events yarn
• pnpm add bare-events pnpm

Imports

• EventEmitter
  wrong:

  import EventEmitter from 'bare-events'

  correct:

  import { EventEmitter } from 'bare-events'

  Bare Events uses named exports for its primary `EventEmitter` class, even in ESM contexts. Direct default imports will result in `undefined` or an error.
• EventEmitter

  const EventEmitter = require('bare-events')

  This is the standard CommonJS import pattern, as shown in the package's documentation.
• EventEmitter (type)

  import type { EventEmitter } from 'bare-events'

  When using TypeScript, prefer `import type` for type-only imports to ensure they are stripped from the compiled JavaScript, preventing runtime overhead and potential issues.

Quickstart

This quickstart demonstrates how to create a typed event emitter, subscribe to events with `on` and `once`, emit events with `emit`, and properly clean up listeners using `off`.

import { EventEmitter } from 'bare-events';

interface MyEvents {
  'data': (payload: string) => void;
  'ready': () => void;
  'error': (err: Error) => void;
}

// Create a new EventEmitter instance, typed for better safety
const myEmitter = new EventEmitter<MyEvents>();

// Subscribe to the 'data' event
myEmitter.on('data', (payload: string) => {
  console.log(`Received data: ${payload}`);
});

// Subscribe to the 'ready' event, only once
myEmitter.once('ready', () => {
  console.log('Emitter is ready!');
});

// Emit events
myEmitter.emit('data', 'Hello, world!');
myEmitter.emit('ready');
myEmitter.emit('data', 'Another piece of data!');

// Demonstrate removing a listener
const errorHandler = (err: Error) => console.error('Caught error:', err.message);
myEmitter.on('error', errorHandler);
myEmitter.emit('error', new Error('Something went wrong!'));
myEmitter.off('error', errorHandler); // Remove the specific listener
myEmitter.emit('error', new Error('This error will crash the process if no other listener is present.')); // No listener, will crash in Node.js