Documentation / @agentick/kernel / EventBuffer

Class: EventBuffer<T>

Defined in: kernel/src/event-buffer.ts:100

EventBuffer enables typed, channel-based event streaming.

The event's type property IS the channel. Subscribing to 'delta' means you only receive events where event.type === 'delta'.

Examples

type StreamEvent =
  | { type: 'delta'; value: string }
  | { type: 'complete'; result: any };

const buffer = new EventBuffer<StreamEvent>();

// Subscribe to specific channel - handler gets narrowed type
buffer.on('delta', (event) => {
  console.log(event.value); // TypeScript knows: { type: 'delta', value: string }
});

// Subscribe to all events
buffer.on((event) => {
  console.log(event); // StreamEvent union
});

// Emit - type can be first arg (event.type omitted) or in event object
buffer.emit('delta', { value: 'Hello' });
buffer.emit({ type: 'complete', result: 42 });

buffer.emit('delta', { value: 'first' });
buffer.emit('delta', { value: 'second' });

// Late subscriber gets all past 'delta' events replayed
buffer.onReplay('delta', (e) => console.log(e.value));
// logs: 'first', 'second'

for await (const event of buffer) {
  if (event.type === 'complete') break;
  console.log(event);
}

Type Parameters

T

T extends TypedEvent

Constructors

Constructor

new EventBuffer<T>(): EventBuffer<T>

Returns

EventBuffer<T>

Accessors

closed

Get Signature

get closed(): boolean

Defined in: kernel/src/event-buffer.ts:376

Whether the buffer is closed.

Returns

boolean

---

errorValue

Get Signature

get errorValue(): Error | null

Defined in: kernel/src/event-buffer.ts:381

Error that closed the buffer (if any).

Returns

Error | null

---

length

Get Signature

get length(): number

Defined in: kernel/src/event-buffer.ts:386

Number of buffered events.

Returns

number

---

listenerCount

Get Signature

get listenerCount(): number

Defined in: kernel/src/event-buffer.ts:391

Total number of active subscribers across all channels.

Returns

number

Methods

[asyncIterator]()

[asyncIterator](): AsyncGenerator<T, void, unknown>

Defined in: kernel/src/event-buffer.ts:436

Async iterator that replays all events then waits for new ones.

Multiple iterators can exist simultaneously - each sees all events.

Returns

AsyncGenerator<T, void, unknown>

---

addListener()

Call Signature

addListener<K>(eventType, handler): Unsubscribe

Defined in: kernel/src/event-buffer.ts:484

Alias for on() (EventEmitter compatibility)

Type Parameters

K

K extends string

Parameters

eventType

K

handler

EventHandler<EventMap<T>[K]>

Returns

Unsubscribe

Call Signature

addListener(handler): Unsubscribe

Defined in: kernel/src/event-buffer.ts:488

Alias for on() (EventEmitter compatibility)

Parameters

handler

EventHandler<T>

Returns

Unsubscribe

---

close()

close(): void

Defined in: kernel/src/event-buffer.ts:345

Close the buffer (no more events). Completes all async iterators gracefully.

Returns

void

---

emit()

Call Signature

emit<K>(eventType, event): boolean

Defined in: kernel/src/event-buffer.ts:150

Emit an event (two-param form: type + event without type property).

Type Parameters

K

K extends string

Parameters

eventType

K

event

Omit<EventMap<T>[K], "type">

Returns

boolean

true if there were listeners

Call Signature

emit(eventType, event): boolean

Defined in: kernel/src/event-buffer.ts:156

Emit an event with wildcard (backwards compat with EventEmitter). The event must be a full event object with type property.

Parameters

eventType

"*"

event

T

Returns

boolean

true if there were listeners

Call Signature

emit(event): boolean

Defined in: kernel/src/event-buffer.ts:161

Emit an event (one-param form: full event object with type).

Parameters

event

T

Returns

boolean

true if there were listeners

---

error()

error(err): void

Defined in: kernel/src/event-buffer.ts:360

Close with an error. All waiting iterators will throw this error.

Parameters

err

Error

Returns

void

---

filter()

filter<K>(eventType): AsyncGenerator<EventMap<T>[K], void, unknown>

Defined in: kernel/src/event-buffer.ts:471

Create a filtered async iterator for a specific event type.

Type Parameters

K

K extends string

Parameters

eventType

K

Returns

AsyncGenerator<EventMap<T>[K], void, unknown>

---

getBuffer()

getBuffer(): readonly T[]

Defined in: kernel/src/event-buffer.ts:413

Get all buffered events (readonly).

Returns

readonly T[]

---

getBufferByType()

getBufferByType<K>(eventType): readonly EventMap<T>[K][]

Defined in: kernel/src/event-buffer.ts:418

Get buffered events of a specific type.

Type Parameters

K

K extends string

Parameters

eventType

K

Returns

readonly EventMap<T>[K][]

---

getListenerCount()

Call Signature

getListenerCount<K>(eventType): number

Defined in: kernel/src/event-buffer.ts:404

Get listener count for a specific event type.

Type Parameters

K

K extends string

Parameters

eventType

K

Returns

number

Call Signature

getListenerCount(): number

Defined in: kernel/src/event-buffer.ts:406

Get wildcard listener count.

Returns

number

---

off()

Call Signature

off<K>(eventType, handler): boolean

Defined in: kernel/src/event-buffer.ts:263

Unsubscribe a handler from a specific event type.

Type Parameters

K

K extends string

Parameters

eventType

K

handler

EventHandler<EventMap<T>[K]>

Returns

boolean

true if handler was found and removed

Call Signature

off(eventType, handler): boolean

Defined in: kernel/src/event-buffer.ts:269

Unsubscribe a wildcard handler. Pass "*" or no event type for wildcard.

Parameters

eventType

"*"

handler

EventHandler<T>

Returns

boolean

true if handler was found and removed

Call Signature

off(handler): boolean

Defined in: kernel/src/event-buffer.ts:270

Unsubscribe a handler from a specific event type.

Parameters

handler

EventHandler<T>

Returns

boolean

true if handler was found and removed

---

on()

Call Signature

on<K>(eventType, handler): Unsubscribe

Defined in: kernel/src/event-buffer.ts:200

Subscribe to events of a specific type. Handler receives the narrowed type for that event.

Type Parameters

K

K extends string

Parameters

eventType

K

handler

EventHandler<EventMap<T>[K]>

Returns

Unsubscribe

Unsubscribe function

Call Signature

on(eventType, handler): Unsubscribe

Defined in: kernel/src/event-buffer.ts:206

Subscribe to all events (wildcard). Pass "*" or no event type for wildcard subscription.

Parameters

eventType

"*"

handler

EventHandler<T>

Returns

Unsubscribe

Unsubscribe function

Call Signature

on(handler): Unsubscribe

Defined in: kernel/src/event-buffer.ts:207

Subscribe to events of a specific type. Handler receives the narrowed type for that event.

Parameters

handler

EventHandler<T>

Returns

Unsubscribe

Unsubscribe function

---

once()

Call Signature

once<K>(eventType, handler): Unsubscribe

Defined in: kernel/src/event-buffer.ts:226

Subscribe for a single event of a specific type.

Type Parameters

K

K extends string

Parameters

eventType

K

handler

EventHandler<EventMap<T>[K]>

Returns

Unsubscribe

Unsubscribe function

Call Signature

once(eventType, handler): Unsubscribe

Defined in: kernel/src/event-buffer.ts:232

Subscribe for a single event (any type). Pass "*" or no event type for wildcard subscription.

Parameters

eventType

"*"

handler

EventHandler<T>

Returns

Unsubscribe

Unsubscribe function

Call Signature

once(handler): Unsubscribe

Defined in: kernel/src/event-buffer.ts:233

Subscribe for a single event of a specific type.

Parameters

handler

EventHandler<T>

Returns

Unsubscribe

Unsubscribe function

---

onReplay()

Call Signature

onReplay<K>(eventType, handler): Unsubscribe

Defined in: kernel/src/event-buffer.ts:288

Subscribe to a specific event type and replay all buffered events of that type.

Type Parameters

K

K extends string

Parameters

eventType

K

handler

EventHandler<EventMap<T>[K]>

Returns

Unsubscribe

Unsubscribe function

Call Signature

onReplay(handler): Unsubscribe

Defined in: kernel/src/event-buffer.ts:293

Subscribe to all events and replay entire buffer.

Parameters

handler

EventHandler<T>

Returns

Unsubscribe

Unsubscribe function

---

push()

push(event): void

Defined in: kernel/src/event-buffer.ts:115

Push an event into the buffer. Notifies subscribers for this event's type and wildcard subscribers.

Parameters

event

T

Returns

void

---

removeListener()

Call Signature

removeListener<K>(eventType, handler): boolean

Defined in: kernel/src/event-buffer.ts:497

Alias for off() (EventEmitter compatibility)

Type Parameters

K

K extends string

Parameters

eventType

K

handler

EventHandler<EventMap<T>[K]>

Returns

boolean

Call Signature

removeListener(handler): boolean

Defined in: kernel/src/event-buffer.ts:498

Alias for off() (EventEmitter compatibility)

Parameters

handler

EventHandler<T>

Returns

boolean

---

toArray()

toArray(): T[]

Defined in: kernel/src/event-buffer.ts:423

Convert buffer to array (copy).

Returns

T[]