Channels API for Bun and Node

Every public class, function and type of the Channels engine in @tinyshed/tinystore, generated from its source. The Channels guide explains how to use them, and the Python, Go and Rust pages list the same API.

#Message

interface Message<T> {
    value: T
    branch: string[]
}

A message as a subscriber receives it: what was published, and the branch it was published under.

#Missed

interface Missed {
    reason: 'behind' | 'reconnect'
    count?: number | undefined
}

Messages a subscriber may have lost: it fell behind its branch's log, and count says how many; or its connection was lost and made again, and how many is unknown.

#SubscribeOptions

interface SubscribeOptions {
    /** take every branch below this one too */
    recursive?: boolean | undefined
    /** told what was missed, in line with the messages; the store's log says it when absent */
    onMissed?: ((missed: Missed) => unknown) | undefined
    /** told what the handler threw, with the message; the store's log says it when absent */
    onError?: ((error: unknown, message: Message<unknown>) => unknown) | undefined
}

#EachOptions

interface EachOptions {
    recursive?: boolean | undefined
    onMissed?: ((missed: Missed) => unknown) | undefined
}

#Channel

class Channel<T> {
    readonly name: string
    readonly branch: readonly string[]
}

A channel of messages of one type, or one of its branches: open it with store.channel(name).

#Channel.under

under(...owners: Key[]): Channel<T>

The branch of owners under this one: whose messages these are.

#Channel.publish

publish(value: T): Promise<void>

Hands value to every subscriber of this branch, and of the branches above it listened to recursive, that listens now. It answers once the store has the message, not once anyone handled it.

#Channel.subscribe

subscribe(handler: (message: Message<T>) => unknown, options?: SubscribeOptions): Promise<Subscription>

Calls handler with each message published from now on, one at a time and in order: it answers once the store has the subscription, so that a message published after it arrives.

const sub = await chat.under(roomId).subscribe(m => show(m.value), { onMissed: () => reload() })
await sub.stop()

#Channel.each

each(options?: EachOptions): AsyncGenerator<Message<T>>

The messages published from now on, as a loop: it listens from its first turn, and break ends it. A throw in the loop's body ends it too.

for await (const m of chat.under(roomId).each()) await save(m.value)

#Subscription

class Subscription {}

A subscription whose handler is called with each message: stop ends it, and the store's close does.

#Subscription.stop

stop(): Promise<void>

No call starts after it, and it answers once the running call ended; called from inside the subscription's own handler, it answers at once.

#Subscription.start

start(handler: (message: Message<unknown>) => unknown, options: SubscribeOptions | undefined): Promise<void>

Registers the subscription, then runs its handler in the background.

#TxChannel

interface TxChannel<T> {
    under(...owners: Key[]): TxChannel<T>
    publish(value: T): Promise<void>
}

A channel inside a transaction: its messages are handed over once the transaction commits.