# 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](https://tinyshed.org/tinystore/docs/guides/channels) explains how to use them, and the [Bun and Node](https://tinyshed.org/tinystore/docs/reference/bun/channels), [Python](https://tinyshed.org/tinystore/docs/reference/python/channels) and [Rust](https://tinyshed.org/tinystore/docs/reference/rust/channels) pages list the same API.

## Channel

```go
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

```go
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

```go
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

```go
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

```go
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

```go
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

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

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

## Message

```go
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

```go
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

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

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

### OnError

```go
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

```go
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

```go
func Recursive() SubscribeOption
```

Recursive takes the branches below this one too.

## Subscription

```go
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

```go
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.