Events and Collectors

Collector#

interface Collector<M extends MessageCore = Message>interface Collector<
  M extends MessageCore = Message
>

close(): Effect<void>

result(): Effect<CollectorResult<M>, CollectorFailure>result(): Effect<
  CollectorResult<M>,
  CollectorFailure
>

CollectorOptions#

interface CollectorOptions<
    E = never,
    R = never,
    M extends MessageCore = Message
>
    extends EventBufferOptionsinterface CollectorOptions<
  E = never,
  R = never,
  M extends MessageCore = Message
>
  extends EventBufferOptions

filter optional#

Return true to accept a message, or false to skip it

Omit to accept all messages in the channel, including bots. Runs synchronously in receive order, after channel selection. Do not return a Promise or perform blocking work. Throwing or returning anything except a boolean fails this collector with reason filter. A thrown value is the CollectorError cause. The failure is also reported to the client-level onError with kind filter and the message IDs, or logged at Error. Asynchronous work returned by mistake is neither awaited nor cancelled, and its rejection is discarded. A slow filter blocks other JavaScript work. The collector checks its deadlines again after the filter returns

(message: M) => boolean

guildId optional#

Community that owns this channel, as a positive decimal ID within the unsigned 64-bit range

The caller must supply the correct community, because the SDK does not fetch the channel to verify membership. Its assigned gateway shard must be connected. Recovery of that shard ends collection, while unrelated shards do not. Events with a different supplied guildId are discarded. Missing community context does not prove the channel is private. Omit this option for unknown or private scope. Then the whole gateway must be connected and any shard recovery ends collection

string

idleMs optional#

Stop successfully after this many milliseconds without an accepted message

Omit to disable this deadline. Integer 1 through 2,147,483,647. The interval starts at registration and resets before each accepted message's callback. Rejected messages, duplicate IDs and messages still queued do not reset it. Callback time counts as idle time. The earlier idle or total deadline wins. Equal deadlines produce reason timeout

number

maxBytes optional#

Maximum UTF-8 JSON bytes kept for accepted messages

Positive safe integer, default 4,194,304, not a total memory limit

number

maxMessages optional#

Stop successfully after this many accepted messages and their callbacks

Positive safe integer, default 1

number

onMessage optional#

Run once per accepted message ID, sequentially, after filtering and stored-byte limit checks

Failures and defects while active fail collection with CollectorError handler, whose cause is the original failure or defect. The failure is also reported to the client-level onError with kind collector, the message IDs and the full Cause, or logged at Error. Stop, timeout, idle completion, scope closure, recovery and shutdown interrupt active work and await its finalizers. Uninterruptible work can delay closure. Do not await this collector's completion or client shutdown inside its handler. Already-dispatched effects are not rolled back. Callbacks are never retried

(message: M) => Effect<unknown, E, R>

timeoutMs optional#

Stop successfully after this many milliseconds from registration, regardless of activity

Integer 1 through 2,147,483,647, default 30,000

number

Inherited from EventBufferOptions: maxPendingBytes, maxPendingMessages

EventHandlerOptions#

interface EventHandlerOptions<E = never, R = never, T = unknown>
    extends HandlerOptions<T>interface EventHandlerOptions<
  E = never, R = never, T = unknown
>
  extends HandlerOptions<T>

onError optional#

Receive this subscription's failures instead of the client-level onError, with the original error and its full Cause

(report: FailureReport) => Effect<unknown, E, R>(report: FailureReport)
  => Effect<unknown, E, R>

A failure only queues its report, so the hook never holds a handler slot. One worker with the services available at registration delivers reports one at a time in order, with up to 64 waiting while the hook is busy. Later ones are logged instead, with fields.reportOutcome "queueFull", and counted in diagnostics().counters.reportsDropped. A failed or defective hook is logged together with the original failure and is never retried. Reports already queued when the subscription closes are still delivered. Client shutdown interrupts a running hook and waits at most one second for its cleanup, then logs the interrupted and queued reports at Error with fields.reportOutcome "interrupted" or "subscriptionClosed". A hook that interrupts itself also logs its report with "interrupted", and later reports still reach the hook

partitionReady optional#

Hold the events of a partition key until that key is ready, without using a handler slot

Valid only together with partition, otherwise registration dies with ConfigurationError. Before the first waiting event of a key starts, the SDK calls this hook with the key. The key's events stay in the queue until the hook's Effect completes, while events of other keys keep starting. A held event does not use one of the concurrency slots, but it counts toward maxPendingMessages and maxPendingBytes, so a bot that waits for many keys at once needs a larger maxPendingMessages than the default 256. Held events also count as waiting work for a draining shutdown, so a hook that never completes makes the drain wait until its limit. The hook returns an Effect, which the SDK runs with the services available when the handler is registered. An Effect that completes without waiting marks the key ready at once, and one that waits holds the key until it completes. The SDK remembers that a key is ready only while it has waiting or running events. After the key went idle, its next event calls the hook again, so memory stays bounded by the keys with queued work. Hooks for different keys run at the same time, and every burst of events after an idle period calls the hook again. Keep it a cheap, idempotent check that answers at once when the key is already ready, such as an Effect that succeeds at once. Events without a key share the key "", and the hook receives "". With partition "guild", a direct message has no community, so its key is its channel ID. A hook should treat keys it does not know as ready. A hook that fails or dies reports every waiting event of that key as a failure of that event's handler, as a throwing partition function does, and those handlers do not run. The key is then forgotten, so a later event calls the hook again. The hook is interrupted when the subscription stops, which includes closing it, client shutdown and a draining shutdown that reaches its drain limit

(key: string) => Effect<unknown, E, R>

TypeScript

import { Effect } from "effect"
import type { Client } from "@neontechspace/fluxerly/effect"
export function afterServerSetup(client: Client, setups: Map<string, Effect.Effect<void>>) {
    // A server whose setup is unknown, such as a direct message channel, is ready at once
    return client.on("messageCreate", (message) => Effect.sync(() => void message.content), {
        partition: "guild",
        partitionReady: (key) => setups.get(key) ?? Effect.void,
    })
}

Inherited from HandlerOptions: concurrency, maxPendingBytes, maxPendingMessages, overflow, partition

EventWaitOptions#

interface EventWaitOptions<
    K extends EventName,
    M extends MessageCore = Message
>
    extends EventBufferOptionsinterface EventWaitOptions<
  K extends EventName,
  M extends MessageCore = Message
>
  extends EventBufferOptions

filter optional#

Return true to complete with this event, false to keep waiting

Omit to accept the first event. Runs synchronously and can run while the gateway receives events. Keep it short, since deadlines cannot preempt blocking JavaScript. A throw or non-boolean return fails with EventWaitError reason filter. A thrown value is the error's cause. Do not return a Promise. Mistaken asynchronous work is neither awaited nor cancelled, and its rejection is discarded

(event: EventMap<M>[K]) => boolean

timeoutMs optional#

Total milliseconds to wait from registration, an integer from 1 through 2,147,483,647, default 30,000

Expiry fails with EventWaitError reason timeout, rather than returning an empty event

number

Inherited from EventBufferOptions: maxPendingBytes, maxPendingMessages

MiddlewareRegistration#

interface MiddlewareRegistration

close(): Effect<void>

ReactionCollector#

interface ReactionCollector

close(): Effect<void>

result(): Effect<ReactionCollectorResult, CollectorFailure>result(): Effect<
  ReactionCollectorResult,
  CollectorFailure
>

ReactionCollectorOptions#

interface ReactionCollectorOptions<E = never, R = never>
    extends EventBufferOptionsinterface ReactionCollectorOptions<
  E = never, R = never
>
  extends EventBufferOptions

emoji optional#

Collect only this emoji, or omit to accept any emoji

Use any ReactionEmojiInput, including Unicode, custom markup and parsed or received emoji. The SDK normalizes and copies it at registration. Unicode text must match exactly, including skin tone and variation selectors. Custom emoji match by ID even after renaming. A custom input still needs a valid name. Invalid input fails registration with ConfigurationError field emoji, without a request. Matching runs before filter and onReaction, but after the event enters the queue, so other emoji can still fill the pending queue

ReactionEmojiInput

filter optional#

Return true to accept an addition, or false to skip it

Runs after target and optional emoji matching. With both emoji and filter supplied, both must match. Omission accepts every addition passing the emoji selector. Runs synchronously in receive order, then batch order. A throw or non-boolean return fails only this collector with reason filter, and is reported to the client-level onError with kind filter and the message IDs, or logged at Error. Do not return a Promise. Mistaken asynchronous work is not awaited or cancelled, and its rejection is discarded. Slow code blocks JavaScript. Deadlines are checked after the filter returns

(reaction: MessageReaction) => boolean

guildId optional#

Community that owns the target channel, as a positive decimal ID within the unsigned 64-bit range

The caller must supply the correct community, because no channel lookup verifies it. Its assigned gateway shard must be connected. Recovery of that shard ends collection, while unrelated shard recovery does not. Events with a different supplied guildId are discarded. Missing community context does not prove private scope. Omit for private or unknown scope, requiring a connected whole gateway and ending collection on any shard recovery

string

idleMs optional#

Stop successfully after this many milliseconds without an accepted addition

Omit to disable. Integer 1 through 2,147,483,647. Starts at registration and resets before each accepted addition's callback. Excluded emoji, rejected additions and unprocessed queue or batch entries do not reset it. Callback time counts as idle time. Repeated pairs reset the interval when accepted. The earlier idle or total deadline wins, with timeout winning ties

number

maxBytes optional#

Maximum UTF-8 JSON bytes kept for accepted MessageReaction values

Positive safe integer, default 4,194,304, not a total memory limit

number

maxReactions optional#

Stop successfully after this many accepted additions and their callbacks

Repeated pairs count, positive safe integer, default 1

number

onReaction optional#

Run once per accepted addition, sequentially, before continuing collection

Failures and defects while active fail collection with CollectorError handler, whose cause is the original failure or defect. The failure is also reported to the client-level onError with kind collector, the message IDs and the full Cause, or logged at Error. Stop, timeout, idle completion, scope closure, recovery and shutdown interrupt active work and await its finalizers. Uninterruptible work can delay closure. Do not await this collector's completion inside its handler. Already-dispatched effects are not rolled back. Callbacks are never retried

(reaction: MessageReaction) => Effect<unknown, E, R>(reaction: MessageReaction)
  => Effect<unknown, E, R>

timeoutMs optional#

Stop successfully after this many milliseconds from registration

Activity does not extend it, integer 1 through 2,147,483,647, default 30,000

number

Inherited from EventBufferOptions: maxPendingBytes, maxPendingMessages

Subscription#

interface Subscription

id#

Identifier of this subscription, such as messageCreate#3, used in failure reports and log records

string

close(): Effect<void>

waitForClose(): Effect<void, EventOverflowError>waitForClose(): Effect<
  void, EventOverflowError
>

EventMiddleware#

type EventMiddleware<
    M extends MessageCore = Message,
    E = never,
    R = never
> = (invocation: EventInvocation<M>, next: Effect.Effect<void>)
    => Effect.Effect<unknown, E, R>type EventMiddleware<
  M extends MessageCore = Message,
  E = never,
  R = never
> = (
  invocation: EventInvocation<M>,
  next: Effect.Effect<void>
) => Effect.Effect<unknown, E, R>