Client

The call controls startup only, using the client's connection settings. Cancellation or an expected failure before initial readiness waits for shard cleanup and leaves the client Disconnected, so connect can be tried again. An already-connected client not managed by run succeeds without opening another socket. A competing call fails with ClientBusyError without disturbing active work, and closing clients fail with ClientClosedError. After initial readiness, permanent failure of a required shard in a multi-shard plan closes the client. The waitForClose method retains that failure as ShardConnectionError with shardId and failure

After success, the startup signal no longer affects the session. Unexpected SDK or cleanup failures reject with SdkDefect

The listener runs asynchronously, one call at a time per subscriber, awaiting a returned promise. A listener that throws, rejects or returns an Err result goes to the client-level onError as an observer failure, or is logged at Error, and does not close the client. The returned observer's close ends delivery, but cannot cancel listener code already running. A listener that is not a function throws ConfigurationError

Handlers run one at a time by default, except messageCreate handlers and partitioned handlers, which run up to eight at a time as runBot does. A slow messageCreate callback therefore does not stall later messages, but callbacks can finish out of order. Pass concurrency 1 or a partition such as "channel" to keep related messages in order. Without a partition, increasing concurrency keeps receive-order starts but allows out-of-order completion. A partition keeps receive order within each key, while a later event for another key may start first. Each subscription has its own ordering and queue, with no ordering across event types and no exactly-once delivery. Default pending limits are 256 payloads or 4 MiB of full source JSON, not total process memory. A bulk payload counts once, including all its bytes. A full queue drops its oldest waiting events by default, logs a Warn record and counts the drop, and the subscription keeps running. With a partition, it drops from the longest backlog or the arriving event instead, as the overflow option describes. An event larger than maxPendingBytes that has to wait is itself dropped. Choose overflow stop to close only this subscription instead, observable through the returned handle

A failed handler is isolated and not retried. A default API handler fails when it throws, rejects, or returns or resolves an Err result, and a native handler fails when its Effect fails. Its original failure, with the event name, subscription ID and message IDs, goes to this subscription's onError, else the client-level onError, else an Error log record with the full message, stack and cause chain. Observe the subscription's outcome as well as the client's run or waitForClose outcome. Registration misuse, such as an unknown event name, fails with a suggested correction

Each invocation also receives an EventContext with the receiving shard, its session epoch, its receipt, the received frame size and, for an event that changes or removes a cached entity, the previous snapshot of the enabled cache. Event middleware registered with use runs around every handler invocation, including those of subscriptions registered earlier

The handler receives the event payload, a signal requesting cancellation on close or shutdown, and the EventContext. Return or await asynchronous handler work. Other return values are ignored. The SDK cannot stop promises that ignore the signal or manage work the handler did not return. Registration returns the Subscription synchronously. Invalid arguments throw ConfigurationError, and unexpected failures throw SdkDefect. Registration after shutdown began, such as from a handler still running during shutdown, is not misuse: It returns an already-closed Subscription whose handler never runs and whose waitForClose succeeds, and writes a Warn log record with code events.registeredAfterShutdown

The run method requires a Disconnected client with no competing connection work. A rejected or pre-cancelled call does not take over or close the client. Expected connection, busy and closed failures use ConnectError

The returned ResultAsync stays pending while connected or recovering, and one AbortSignal controls the whole lifetime. Cancellation returns CancelledError. Unexpected SDK or cleanup failures reject with SdkDefect, including failures during cancellation cleanup

A failed run is reported with its original error to the client-level onError, else an Error log record with code lifecycle.taskFailed. A repeating task keeps its schedule after a failed run, so a passing problem such as a network error does not end it, and a lasting one is reported at every run

Shutdown cancels the runs that have not started. A draining shutdown, such as a stop requested from runBot, starts no new run and lets runs in progress finish within its drainMs, and then shutdown cancels what is left. One lifecycle.tasksCancelled Info record counts the tasks that shutdown ended with a run waiting or in progress. Tasks are kept in memory only, so a restart forgets them. Scheduling after shutdown began, including during a drain, is refused with ClientClosedError, and invalid options are misuse with ConfigurationError

The task receives a signal that aborts when shutdown cancels its run. Return or await its asynchronous work: A throw, a rejection, or a returned or resolved Err result fails the run. The SDK cannot stop a promise that ignores the signal. Returns the task's handle synchronously. A task that is not a function and invalid options throw ConfigurationError, scheduling after shutdown began throws ClientClosedError, and an option getter that throws causes SdkDefect. A waiting task keeps Node.js running until it ends or closes, or the client shuts down

Handlers and callbacks receive cancellation through their signal, and returned collector callback promises are awaited. Application reporter promises are not awaited. No signal is accepted. Invalid options throw ConfigurationError before shutdown starts. Success is Ok(undefined) after cleanup. Unexpected SDK or cleanup failures reject with SdkDefect, whose reasons keep every interruption and fault value

Returns a subscription synchronously. Call next for each payload and close when finished, or use await using. Invalid arguments throw ConfigurationError, and unexpected failures throw SdkDefect. Registration after shutdown began is not misuse: It returns an already-closed subscription whose next returns Ok(null) and whose waitForClose succeeds, and writes a Warn log record with code events.registeredAfterShutdown

The middleware receives the invocation, a next function returning a promise and the handler's cancellation signal. Registration returns synchronously. The returned registration's close stops applying the middleware to later invocations. A middleware that is not a function throws ConfigurationError, a closing or closed client throws ClientClosedError, and unexpected failures throw SdkDefect

The default timeout is 30,000 ms from registration. A timeout or invalid or throwing filter fails with EventWaitError without input or exception text. Inspect a filter exception inside the filter before rethrowing if needed. Buffer limits match subscribe. Reconnection can miss events and does not reset the deadline. Overflow, invalid configuration and client closure remain distinct failures

Completion or cancellation releases the queue, filter, timer and subscription without shutting down the client. This returns an event, not a registration handle. Use subscribe, a scoped on subscription or a collector to confirm registration before triggering an action

Observation starts when called. Abort returns CancelledError after subscription cleanup. Unexpected SDK or cleanup failures reject with SdkDefect

Unexpected background or cleanup failures reject with SdkDefect