beam

type Beam[T any] interface {
	// Sub subscribes to the value stream. The onValue callback is called immediately
	// with the current value (in the same goroutine), and again on every update.
	//
	// The subscription continues until:
	//   - The context is canceled
	//   - The onValue function returns true (indicating done)
	//
	// Returns true if the subscription was successfully established;
	// false means the context was already canceled.
	Sub(ctx context.Context, onValue func(context.Context, T) bool) bool

	// XSub is an extended version of Sub that provides additional control.
	// It behaves the same as Sub, but also:
	//   - Accepts an onCancel callback, invoked when the subscription ends due to context cancellation
	//   - Returns a Cancel function for manual subscription termination
	//
	// Returns the Cancel function and a boolean indicating whether the subscription was established.
	XSub(ctx context.Context, onValue func(context.Context, T) bool, onCancel func()) (context.CancelFunc, bool)

	// ReadAndSub returns the current value and then subscribes to future updates.
	// The onValue function is invoked on every subsequent update.
	//
	// Returns the initial value and a boolean:
	//   - If true, the value is valid and subscription was established
	//   - If false, the context was canceled and the returned value is undefined
	ReadAndSub(ctx context.Context, onValue func(context.Context, T) bool) (T, bool)

	// ReadAndSubExt behaves like ReadAndSub with extended control options.
	// It provides the same functionality as ReadAndSub, but also:
	//   - Accepts an onCancel callback for handling cancellation events
	//   - Returns a Cancel function for manual termination
	//
	// Returns the initial value, Cancel function, and success boolean.
	// If the boolean is false, the value is undefined and no subscription was established.
	XReadAndSub(ctx context.Context, onValue func(context.Context, T) bool, onCancel func()) (T, context.CancelFunc, bool)

	// Read returns the current value of the Beam without establishing a subscription.
	//
	// Returns the current value and a boolean:
	//   - If true, the value is valid
	//   - If false, the context was canceled and the value is undefined
	Read(ctx context.Context) (T, bool)

	// AddWatcher attaches a Watcher for full lifecycle control over subscription events.
	// Watchers receive separate callbacks for initialization, updates, and cancellation,
	// allowing for more sophisticated subscription management.
	//
	// Returns a Cancel function and a boolean indicating whether the watcher was added.
	AddWatcher(ctx context.Context, w Watcher[T]) (context.CancelFunc, bool)
	// contains filtered or unexported methods
}

type SourceBeam[T any] interface {
	Beam[T]

	// Update sets a new value and propagates it to all subscribers and derived beams.
	// The update is applied only if it passes the source's distinct function and provided
	// context is valid
	//
	Update(context.Context, T)

	// XUpdate performs an update and returns a channel that signals when the update
	// has been fully propagated to all subscribers. This allows coordination of
	// dependent operations that must wait for the update to complete.
	//
	// The returned channel receives nil on successful propagation or an error if
	// provided context is invalid or instance ended before propagation finished.
	//
	// Wait on the channel only in contexts where blocking is allowed (hooks, goroutines).
	//
	// Returns the completion channel
	XUpdate(context.Context, T) <-chan error

	Mutate(context.Context, func(T) T)

	// XMutate performs a mutation and returns a channel that signals when the mutation
	// has been fully propagated to all subscribers. This allows coordination of
	// dependent operations that must wait for the mutation to complete.
	//
	// The returned channel receives nil on successful propagation or an error if
	// provided context is invalid or instance ended before propagation finished.
	// Wait on the channel only in contexts where blocking is allowed (hooks, goroutines).
	//
	// Returns the completion channel
	XMutate(context.Context, func(T) T) <-chan error

	// Latest returns the most recently set or mutated value without requiring a context.
	// This provides direct access to the current state and is not affected by
	// context cancellation and doors tree state, unlike Read.
	//
	// WARNING: Latest() does not participate in render cycle consistency guarantees.
	// Use Read() to ensure consistent values across the component tree.
	Latest() T

	// DisableSkipping makes data propagation continue even if a new value
	// is issued. Useful, if you use beam as a communication channel
	// and want all data to be delivered to subscribers.
	DisableSkipping()
}

type Watcher[T any] interface {
	// Cancel is called when the watcher is terminated due to context cancellation.
	Cancel()

	// Init is called with the initial value. The seq parameter represents the sequence number
	// of the update. Called in the same goroutine where the watcher was added.
	//
	// Return true (done) to stop receiving updates after this call.
	Init(ctx context.Context, value *T, seq uint) bool

	// Update is called for each subsequent update to the value.
	// The seq parameter increments with each update.
	//
	// Return true (done) to stop receiving further updates.
	Update(ctx context.Context, value *T, seq uint) bool
}