Abstract Protected constructorInternal Should not be instantiated directly.
Internal _propagationReadonly extraAny extra information that may be useful for debugging.
Readonly nameThe name of the event (e.g., 'CommandStarted', 'CommandFailed').
Protected Abstract Internal permitsPoor man's sealed class. Ensures you can't extend this class without first updating DataAPIClientEventMap.
Imagine that:
BaseClientEvent is a Java sealed classDataAPIClientEvent is Java's permit keyword.An implementing class would do something like this:
export class CommandWarningsEvent extends BaseClientEvent {
declare permit: this;
}
If you forget to add declare permit: this, or this is not assignable to DataAPIClientEvent, TypeScript will throw an error.
Readonly requestA unique identifier for the request that triggered this event.
It helps correlate multiple events occurring within the same request lifecycle.
High-level operations, such as collection.insertMany(...), may generate multiple requests internally. Each of these requests will have its own unique requestId.
As an example, a CommandStarted event may be emitted when a command is started, and a CommandSucceeded event may be emitted when the command has succeeded. Both of these events will have the same requestId.
If logged to a file (e.g. winston with a file transport and json format), you could then filter all events with the same requestId to see the entire lifecycle of a single command.
// Set up event listeners on the collection
collection.on('commandStarted', (e) => {
console.log(`Command started with requestId: ${e.requestId}`);
});
collection.on('commandSucceeded', (e) => {
console.log(`Command succeeded with requestId: ${e.requestId}`);
});
// Logs:
// - Command started with requestId: dac0d3ba-79e8-4886-87b9-20237c507eba
// - Command succeeded with requestId: dac0d3ba-79e8-4886-87b9-20237c507eba
await collection.insertOne({ name: 'Alice' });
// Logs:
// - Command started with requestId: 1fe46a92-8187-4eaa-a3c2-80a964b68eba
// - Command succeeded with requestId: 1fe46a92-8187-4eaa-a3c2-80a964b68eba
await collection.insertOne({ name: 'Bob' });
Readonly timestampThe timestamp of when the event was created.
Static Private _defaultStatic Protected formatFormats the event into a human-readable string, as it would be logged to stdout/stderr (if enabled).
See EventFormatter & BaseClientEvent.setDefaultFormatter for more information about custom formatting.
Optional custom formatter function.
The formatted event string.
Converts the event to a verbose JSON format, as it would be logged to stdout:verbose/stderr:verbose (if enabled).
Useful for debugging. The output is pretty-printed JSON with newlines, so perhaps not ideal for structured logging though.
A JSON string with full event details.
Abstract getAbstract getStops the event from bubbling up to the parent listener (e.g. Collection → Db → DataAPIClient) and prevents any further listeners from being called.
db.on('commandStarted', (e) => {
console.log('Command started (db listener)');
});
collection.on('commandStarted', (e) => {
console.log('Command started (collection listener #1)');
e.stopImmediatePropagation();
});
collection.on('commandStarted', (e) => {
console.log('Command started (collection listener #2)');
});
// Logs:
// - Command started (collection listener #1)
collection.insertOne({ name: 'Alice' });
stopPropagation
Stops the event from bubbling up to the parent listener (e.g. Collection → Db → DataAPIClient).
client.on('commandStarted', (e) => {
console.log('Command started (client listener)');
});
db.on('commandStarted', (e) => {
console.log('Command started (db listener)');
e.stopPropagation();
});
collection.on('commandStarted', (e) => {
console.log('Command started (collection listener)');
});
// Logs:
// - Command started (collection listener)
// - Command started (db) listener
collection.insertOne({ name: 'Alice' });
stopImmediatePropagation
Static setSets the default formatter for all events.
Useful especially if you want to change the format of events as they're logged to stdout/stderr (see LoggingOutputs).
See EventFormatter for much more info.
This method sets a static property on the class, so it will affect all instances of BaseClientEvent, regardless of the class. Be careful when using this method in a shared environment.
A function that transforms an event into a log string.
BaseClientEvent.setDefaultFormatter((event, msg) => `[${event.name}] ${msg}`);
Overview
The base class of all events that may be emitted/logged by some HierarchicalEmitter (e.g. a
DataAPIClient,DbAdmin,Collection, etc.)Using events over direct logging allows for more flexibility in how the events are handled, such as:
Each event is associated with a unique
requestId, which can be used to track a specific request across multiple event emissions.See DataAPIClientEventMap & LoggingConfig for much more info.