Type alias DataAPIClientEventMap

Overview

The EventMap of events the DataAPIClient emits, which is an instance of TypedEventEmitter, when events logging is enabled (via logging options throughout the major class hierarchy).

There are quite a few combinations of ways in which event logging may be enabled in the logging configuration, but there are a few most common ways to do so:

• logging: 'all' - This will emit all events, but will also log some of them to the console
• logging: [{ events: 'all', emits: 'event' }] - This will emit all events, without logging any of them to the console
• logging: '<command>' - This will emit only the events for the specified command, but may also log some of them to the console
  • The default behavior for if an event is logged to the console or not varies
  • See below section on event types for more info about default behaviors

When to prefer events

Events can be thought of as a "generic logging interface" for Data API & DevOps operations. Though the DataAPILoggingConfig, you can also enable/disable logging to stdout/stderr, but:

• You're forced to use the console as output
• You can't programmatically interact with the logs/data
• You can't easily filter or format the logs

DataAPIClientEventMap are a more flexible way to interact with the logs, allowing you to basically plug in, or even build, your own logging system around them.

And of course, you're free to use both events and console logging in tandem, if you so choose.

Disclaimer

Note that these emit real commands, not any abstracted commands like "insertMany" or "updateMany", which may be split into multiple of those commands under the hood.

This generally applies to normal command events; no admin command events are abstracted as such.

Event types

There are two major categories of events emitted by the DataAPIClient:

• CommandEventMap - Events related to the execution of a command
  • i.e. Db, Collection, Table operations
• AdminCommandEventMap - Events related to the execution of an admin command
  • i.e. AstraAdmin, DbAdmin operations

Every event may be enabled/disabled individually, independent of one another.

commandStarted (CommandStartedEvent)

Emitted when a command is started, before the initial HTTP request is made.

Default behavior when logging is enabled (through 'all' or 'commandStarted'):

• Emits the event
• Does NOT log to the console

commandSucceeded (CommandSucceededEvent)

Emitted when a command has succeeded (i.e. the status code is 200, and no errors are returned).

Default behavior when logging is enabled (through 'all' or 'commandSucceeded'):

• Emits the event
• Does NOT log to the console

commandFailed (CommandFailedEvent)

Emitted when a command has errored (i.e. the status code is not 200, or errors are returned).

Default behavior when logging is enabled (through 'all' or 'commandFailed'):

• Emits the event
• Logs to stderr

commandWarnings (CommandWarningsEvent)

Emitted when a command has warnings (i.e. when the status.warnings field is present).

Warnings may be present even if the command has succeeded.

Such warnings include updates/deletes without a filter, or using deprecated command aliases.

Default behavior when logging is enabled (through 'all' or 'commandWarnings'):

• Emits the event
• Logs to stderr

adminCommandStarted (AdminCommandStartedEvent)

Emitted when an admin command is started, before the initial HTTP request is made.

Default behavior when logging is enabled (through 'all' or 'adminCommandStarted'):

• Emits the event
• Logs to stdout

adminCommandPolling (AdminCommandPollingEvent)

Emitted when a command is polling in a long-running operation (i.e. AstraAdmin.createDatabase).

NOTE: this is ONLY emitted when using AstraAdmin & AstraDbAdmin methods. Non-Astra-backends do not yet require any command polling.

Frequency of polling depends on the command being run, and whether a custom polling interval was set.

Default behavior when logging is enabled (through 'all' or 'adminCommandPolling'):

• Emits the event
• Logs to stdout

adminCommandSucceeded (AdminCommandSucceededEvent)

Emitted when an admin command has succeeded, after any necessary polling (i.e. when an HTTP 200 is returned).

Default behavior when logging is enabled (through 'all' or 'adminCommandSucceeded'):

• Emits the event
• Logs to stdout

adminCommandFailed (AdminCommandFailedEvent)

Emitted when an admin command has failed (i.e. when an HTTP 4xx/5xx is returned, even if while polling).

Default behavior when logging is enabled (through 'all' or 'adminCommandFailed'):

• Emits the event
• Logs to stderr

adminCommandWarnings (AdminCommandWarningsEvent)

Emitted when an admin command has warnings (i.e. when the status.warnings field is present).

NOTE: this is ONLY emitted when using DataAPIDbAdmin methods. Astra-backends work using the DevOps API, which does not produce any command warnings.

Warnings may be present even if the command has succeeded.

Such warnings include using deprecated command aliases, such as those with "namespace" terminology.

Example

const client = new DataAPIClient('*TOKEN*', {
  logging: [{ events: 'all', emits: 'event' }],
});
const db = client.db('*ENDPOINT*');

client.on('commandStarted', (event) => {
  console.log('Command started:', event);
});

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

client.on('commandSucceeded', (event) => {
  console.log('Command succeeded:', event);
});

// Output:
// 'Command started: <...>'
// 'Command succeeded: <...>'
await db.createCollection('my_collection');
Copy

See

• DataAPILoggingConfig
• CommandEventMap
• AdminCommandEventMap