Channels API for Go

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

#Channel

type Channel[T any] struct {
	// contains filtered or unexported fields
}

Channel is a channel of messages of one type, or one of its branches.

#OpenChannel

func OpenChannel[T any](store *tinystore.Store, name string) (*Channel[T], error)

OpenChannel opens a channel of messages of T, each written as its JSON.

#Channel.Each

func (c *Channel[T]) Each(ctx context.Context, opts ...SubscribeOption) iter.Seq2[Message[T], error]

Each is the messages published from now on, as a loop: it listens from before its first turn, and leaving the loop, ctx's end or the store's close ends it. A connection lost is subscribed again, and OnMissed told.

#Channel.In

func (c *Channel[T]) In(tx tinystore.InTx) *Channel[T]

In is the channel inside a transaction, the store's or a database's: its messages are handed over once the transaction commits, and never if it rolls back.

#Channel.Publish

func (c *Channel[T]) Publish(ctx context.Context, value T) error

Publish hands value to every subscriber of this branch that listens now, and of those above it that listen recursively. It answers once the store has the message, not once anyone handled it; inside a transaction, once the transaction has it.

#Channel.Subscribe

func (c *Channel[T]) Subscribe(ctx context.Context, handler func(ctx context.Context, m Message[T]) error, opts ...SubscribeOption) (*Subscription, error)

Subscribe calls handler with each message published from now on, one at a time and in order, its ctx ending when the subscription stops. It answers once the store has the subscription, so that a message published after it arrives; what handler returns goes to OnError.

sub, err := messages.Under(roomID).Subscribe(ctx, func(ctx context.Context, m channels.Message[Chat]) error {
	show(m.Value)
	return nil
})

#Channel.Under

func (c *Channel[T]) Under(owners ...any) *Channel[T]

Under is the branch of owners under this one: whose messages these are.

#Message

type Message[T any] struct {
	Value  T
	Branch []string
}

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

#Missed

type Missed struct {
	Reason string
	Count  int
}

Missed is messages a subscriber may have lost: it fell behind its branch's log, Reason "behind" and Count how many; or its connection was lost and made again, Reason "reconnect", how many unknown.

#SubscribeOption

type SubscribeOption interface {
	// contains filtered or unexported methods
}

SubscribeOption is how a subscription listens and what it is told.

#OnError

func OnError[T any](fn func(err error, m Message[T])) SubscribeOption

OnError is given what a handler returned, and the message it failed; without it the store's log says it, once a minute at most.

#OnMissed

func OnMissed(fn func(Missed)) SubscribeOption

OnMissed is told what the subscriber may have missed; without it the store's log says it, once a minute at most.

#Recursive

func Recursive() SubscribeOption

Recursive takes the branches below this one too.

#Subscription

type Subscription struct {
	// contains filtered or unexported fields
}

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

#Subscription.Stop

func (s *Subscription) Stop(ctx context.Context) error

Stop ends the subscription: no call starts after it, and it answers once the running call ended; inside its own handler, at once.