Class HierarchicalEmitter<Events>

Overview

A lightweight event system that allows hierarchical event propagation (similar to DOM event bubbling).

Events triggered on a child (e.g., a Collection) will propagate up to its parent (e.g., the parent Db and its parent DataAPIClient), unless explicitly stopped.

This allows to quickly (and granular-ly) enable listen for events at any level of the hierarchy, and stop propagation at any level if needed.

Event Hierarchy

Events follow a structured hierarchy:

• Collection | Table → Db → Client
• AstraAdmin | DbAdmin → Client

If, for instance, you have two different Collection objects which both point to the same collection, only the one that triggered the event will be notified.

Example

const client = new DataAPIClient({ logging: 'all' });

client.on('commandFailed', (event) => {
  console.error('Some command failed:', event.commandName, event.error);
});

const db = client.db('*ENDPOINT*', { token: '*TOKEN*' });
const collection = db.collection('test_coll');

collection.on('commandFailed', (event) => {
  event.stopPropagation(); // Prevents bubbling up to the client
  console.error('test_coll command failed:', event.commandName, event.error);
});

collection.insertOne({ '$invalid-key': 'value' });
Copy

On errors in listeners

If an error is thrown in a listener, it will be silently ignored and will not stop the propagation of the event.

If you need to handle errors in listeners, you must wrap the listener in a try/catch block yourself.

Remarks

Having a custom implementation avoids a dependency on events for maximum compatibility across environments & module systems.

See

DataAPIClientEventMap