samber/cc-skills-golang / skills/golang-samber-ro
golang-samber-ro
VerifiedReactive streams and event-driven programming in Golang using samber/ro — ReactiveX implementation with 150+ type-safe operators, cold/hot observables, 5 subject types (Publish, Behavior, Replay, Async, Unicast), declarative pipelines via Pipe, 40+ plugins (HTTP, cron, fsnotify, JSON, logging), automatic backpressure, error propagation, and Go context integration. Apply when using or adopting samber/ro, when the codebase imports github.com/samber/ro, or when building asynchronous event-driven pipelines, real-time data processing, streams, or reactive architectures in Go. Not for finite slice transforms (→ See `samber/cc-skills-golang@golang-samber-lo` skill).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.8 KB |
| evals/evals.json | config | 17.3 KB |
| references/operators-guide.md | markdown | 14.6 KB |
| references/patterns.md | markdown | 8.0 KB |
| references/plugin-ecosystem.md | markdown | 6.3 KB |
| references/subjects-guide.md | markdown | 6.3 KB |
references/operators-guide.md
View on GitHub# Operators Guide
samber/ro provides 150+ operators organized by category. All operators are generic functions that take and return `Observable[T]`, designed for chaining via `Pipe`.
## Table of Contents
- [Pipeline Construction](#pipeline-construction)
- [Creation Operators](#creation-operators)
- [Transformation Operators](#transformation-operators)
- [Filtering Operators](#filtering-operators)
- [Combining Operators](#combining-operators)
- [Math and Aggregation](#math-and-aggregation)
- [Error Handling](#error-handling)
- [Timing and Buffering](#timing-and-buffering)
- [Side Effects (Tap / Do)](#side-effects-tap--do)
- [Connectable and Sharing](#connectable-and-sharing)
- [Context Operators](#context-operators)
- [Conditional Operators](#conditional-operators)
- [Terminal Operators](#terminal-operators)
- [Observer and Subscription](#observer-and-subscription)
- [Scheduling](#scheduling)
- [Concurrency Modes](#concurrency-modes)
## Pipeline Construction
```go
// Typed pipes (Pipe1 through Pipe25) — compile-time type safety
result := ro.Pipe2(source, op1, op2)
result := ro.Pipe3(source, op1, op2, op3)
// Untyped pipe — uses any, loses type checking
result := ro.Pipe(source, op1, op2, op3)
// Reusable operator composition (curried)
transform := ro.PipeOp2(op1, op2) // returns func(Observable[A]) Observable[C]
result := transform(source)
// Synchronous collection
values, err := ro.Collect(observable)
```
## Creation Operators
Create observables from various sources. Typically the first argument to `Pipe`.
| Operator | Signature | Purpose |
| --- | --- | --- |
| `Just` | `Just[T](values ...T) Observable[T]` | Emit specific values then complete |
| `Of` | `Of[T](values ...T) Observable[T]` | Alias for Just |
| `FromSlice` | `FromSlice[T](items []T) Observable[T]` | Create from existing slice |
| `FromChannel` | `FromChannel[T](ch <-chan T) Observable[T]` | Wrap Go channel as observable |
| `Range` | `Range(start, end int) Observable[int]` | Emit integer sequence |
| `RangeWithStep` | `RangeWithStep(start, end, step int) Observable[int]` | Integer sequence with custom step |
| `RangeWithInterval` | `RangeWithInterval(start, end int, d time.Duration) Observable[int]` | Integers with delay between each |
| `RangeWithStepAndInterval` | `RangeWithStepAndInterval(start, end, step int, d time.Duration) Observable[int]` | Step + interval combined |
| `Interval` | `Interval(d time.Duration) Observable[int64]` | Emit sequential integers at intervals (infinite) |
| `IntervalWithInitial` | `IntervalWithInitial(initial, d time.Duration) Observable[int64]` | Interval with initial delay |
| `Timer` | `Timer(d time.Duration) Observable[int64]` | Single emission after delay |
| `Repeat` | `Repeat[T](item T, count int64) Observable[T]` | Repeat item N times |
| `RepeatWithInterval` | `RepeatWithInterval[T](item T, count int64, d time.Duration) Observable[T]` | Repeat with delay |
| `Defer` | `Defer[T](factory func() Observable[T]) Observable[T]` | Lazily create observable on subscription |
| `Future` | `Future[T](factory func() (T, error)) Observable[T]` | Single async value from function |
| `Start` | `Start(cb func() (any, error)) Observable[any]` | Execute callback and emit result |
| `Empty` | `Empty[T]() Observable[T]` | Complete immediately, no values |
| `Never` | `Never[T]() Observable[T]` | Never emit or complete |
| `Throw` | `Throw[T](err error) Observable[T]` | Immediately error |
```go
// Custom observable with direct control
obs := ro.NewObservable[int](func(ctx context.Context, observer ro.Observer[int]) error {
observer.Next(1)
observer.Next(2)
observer.Complete()
return nil
})
```
## Transformation Operators
Transform each value in the stream.
| Operator | Purpose |
| --- | --- |
| `Map[T, R](fn func(T) R)` | Transform each value T -> R |
| `MapI[T, R](fn func(T, int64) R)` | Map with index |
| `MapErr[T, R](fn func(T) (R, error))` | Map that can fail — error propagates |
| `MapWithContext[T, R](fn func(ctx, T) (ctx, R))` | Map with context access |
| `MapTo[T, R](output R)` | Replace all values with a constant |
| `FlatMap[T, R](fn func(T) Observable[R])` | Map each value to observable, flatten results |
| `MergeMap[T, R](fn func(T) Observable[R])` | Alias for FlatMap |
| `Scan[T, R](fn func(R, T) R, seed R)` | Running accumulation, emit each intermediate |
| `Reduce[T, R](fn func(R, T) R, seed R)` | Accumulate, emit only final result |
| `GroupBy[T, K](fn func(T) K)` | Partition into grouped observables by key |
| `Cast[T, U]()` | Type cast values |
| `Flatten[T]()` | Flatten `Observable[[]T]` to `Observable[T]` |
| `Materialize[T]()` | Wrap values in `Notification[T]` (next/error/complete) |
| `Dematerialize[T]()` | Unwrap `Notification[T]` back to values |
| `Timestamp[T]()` | Emit `TimestampValue[T]` with emission time |
| `TimeInterval[T]()` | Emit `IntervalValue[T]` with time since last emission |
```go
// FlatMap: for each user ID, fetch their orders (returns observable)
orders := ro.Pipe2(
userIDs,
ro.FlatMap(func(id int) ro.Observable[Order] {
return fetchOrders(id)
}),
ro.Filter(func(o Order) bool { return o.Status == "paid" }),
)
// Scan: running sum
ro.Pipe1(
ro.Just(1, 2, 3, 4, 5),
ro.Scan(func(acc, x int) int { return acc + x }, 0),
)
// Emits: 1, 3, 6, 10, 15
```
## Filtering Operators
Selectively emit values from the stream.
| Operator | Purpose |
| --- | --- |
| `Filter[T](fn func(T) bool)` | Emit only values matching predicate |
| `FilterI[T](fn func(T, int64) bool)` | Filter with index |
| `FilterWithContext[T](fn func(ctx, T) (ctx, bool))` | Filter with context access |
| `Distinct[T comparable]()` | Emit only unique values |
| `DistinctBy[T, K](fn func(T) K)` | Unique by key function |
| `Take[T](n int64)` | Emit first N values then complete |
| `TakeLast[T](n int)` | Emit last N values |
| `TakeWhile[T](fn func(T) bool)` | Emit while predicate true, then complete |
| `TakeUntil[T, S](signal Observable[S])` | Emit until signal observable emits |
| `Skip[T](n int64)` | Skip first N values |
| `SkipLast[T](n int)` | Skip last N values |
| `SkipWhile[T](fn func(T) bool)` | Skip while predicate true |
| `SkipUntil[T, S](signal Observable[S])` | Skip until signal emits |
| `Head[T]()` | First item only |
| `Tail[T]()` | All items except first |
| `ElementAt[T](n int)` | Item at specific index |
| `ElementAtOrDefault[T](n int64, fallback T)` | Item at index or default |
| `Find[T](fn func(T) bool)` | First value matching predicate |
| `First[T](fn func(T) bool)` | First matching value (alias-like) |
| `Last[T](fn func(T) bool)` | Last matching value |
| `Contains[T](fn func(T) bool)` | Emit bool: whether any value matches |
All filtering operators have `I` (indexed), `WithContext`, and `IWithContext` variants.
## Combining Operators
Merge multiple observables into one.
| Operator | Purpose |
| --- | --- |
| `Merge[T](sources ...Observable[T])` | Interleave emissions from all sources |
| `MergeWith[T](obs ...Observable[T])` | Chainable merge |
| `MergeAll[T]()` | Flatten `Observable[Observable[T]]` by merging |
| `Concat[T](obs ...Observable[T])` | Sequential: complete first, then start second |
| `ConcatWith[T](obs ...Observable[T])` | Chainable concat |
| `ConcatAll[T]()` | Flatten by concatenating sequentially |
| `Zip2[A, B](a, b)` | Pair values from 2 sources into `lo.Tuple2` |
| `Zip3` ... `Zip6` | Zip 3-6 sources into corresponding `lo.Tuple` |
| `ZipWith[A, B](obsB)` | Chainable zip |
| `CombineLatest2[A, B](a, b)` | Emit combined latest when either source emits |
| `CombineLatest3` ... `CombineLatest5` | Combine 3-5 sources |
| `CombineLatestWith[A, B](obsB)` | Chainable combine-latest |
| `Race[T](sources ...Observable[T])` | Emit from whichever source emits first |
| `Amb[T](sources ...)` | Alias for Race |
| `StartWith[T](prefixes ...T)` | Prepend values before source emissions |
| `EndWith[T](suffixes ...T)` | Append values after source completes |
```go
// Zip: pair user with their settings
ro.Zip2(userStream, settingsStream)
// Emits: lo.Tuple2[User, Settings]
// CombineLatest: re-emit whenever either changes
ro.CombineLatest2(priceStream, quantityStream)
// Emits latest (price, quantity) pair each time either updates
```
## Math and Aggregation
| Operator | Purpose |
| --- | --- |
| `Count[T]()` | Count of emitted values |
| `Sum[T Numeric]()` | Sum of all values |
| `Average[T Numeric]()` | Average as float64 |
| `Max[T Numeric]()` | Maximum value |
| `Min[T Numeric]()` | Minimum value |
| `Abs()` | Absolute value (float64) |
| `Ceil()` / `Floor()` / `Round()` / `Trunc()` | Rounding (float64) |
| `CeilWithPrecision(n)` / `FloorWithPrecision(n)` | Rounding with decimal places |
| `Clamp[T](lower, upper)` | Constrain values to range |
## Error Handling
| Operator | Purpose |
| --- | --- |
| `Catch[T](fn func(error) Observable[T])` | Catch error, switch to recovery observable |
| `OnErrorReturn[T](value T)` | Replace error with fallback value |
| `OnErrorResumeNextWith[T](obs ...Observable[T])` | Continue with fallback observables on error |
| `Retry[T]()` | Retry indefinitely on error |
| `RetryWithConfig[T](cfg RetryConfig)` | Retry with max attempts, delay, backoff |
| `ThrowIfEmpty[T](fn func() error)` | Error if stream completes empty |
```go
// RetryConfig for exponential backoff
ro.RetryWithConfig[Response](ro.RetryConfig{
Max: 3,
Delay: time.Second,
BackoffMultiplier: 2.0,
MaxDelay: 10 * time.Second,
})
```
## Timing and Buffering
| Operator | Purpose |
| --- | --- |
| `Delay[T](d time.Duration)` | Delay entire stream |
| `DelayEach[T](d time.Duration)` | Delay between each emission |
| `Timeout[T](d time.Duration)` | Error if no emission within duration |
| `ThrottleTime[T](d time.Duration)` | Ignore values within duration of last |
| `ThrottleWhen[T, t](tick Observable[t])` | Throttle by signal |
| `SampleTime[T](d time.Duration)` | Emit latest value at intervals |
| `SampleWhen[T, t](tick Observable[t])` | Sample by signal |
| `BufferWithCount[T](n int)` | Collect N items, emit as `[]T` |
| `BufferWithTime[T](d time.Duration)` | Collect within time window |
| `BufferWithTimeOrCount[T](n, d)` | Buffer with either condition |
| `BufferWhen[T, B](boundary Observable[B])` | Buffer until signal |
| `WindowWhen[T, B](boundary Observable[B])` | Window as nested observables |
| `Pairwise[T]()` | Emit consecutive pairs |
## Side Effects (Tap / Do)
Execute code without changing the stream. `Do` is an alias for `Tap`.
| Operator | Purpose |
| ------------------------------------- | --------------------------- |
| `Tap[T](onNext, onError, onComplete)` | Side effect on all events |
| `TapOnNext[T](fn func(T))` | Side effect on values |
| `TapOnError[T](fn func(error))` | Side effect on errors |
| `TapOnComplete[T](fn func())` | Side effect on completion |
| `TapOnSubscribe[T](fn func())` | Side effect on subscription |
| `TapOnFinalize[T](fn func())` | Side effect on teardown |
All have `WithContext` variants. `Do`, `DoOnNext`, `DoOnError`, `DoOnComplete`, `DoOnSubscribe`, `DoOnFinalize` are aliases.
## Connectable and Sharing
| Operator | Purpose |
| --- | --- |
| `Share[T]()` | Cold -> hot with reference counting |
| `ShareWithConfig[T](cfg ShareConfig[T])` | Share with reset options |
| `ShareReplay[T](bufferSize int)` | Share + replay last N values to late subscribers |
| `ShareReplayWithConfig[T](n, cfg)` | ShareReplay with reset options |
| `Serialize[T]()` | Queue emissions to ensure serial delivery |
```go
// ShareConfig controls lifecycle reset
ro.ShareConfig[T]{
ResetOnComplete: true, // re-subscribe on complete
ResetOnError: true, // re-subscribe on error
ResetOnReferenceCount: true, // re-subscribe when count drops to 0
}
```
## Context Operators
| Operator | Purpose |
| ---------------------------------------- | ------------------------------- |
| `ContextReset[T](ctx context.Context)` | Replace pipeline context |
| `ContextWithValue[T](key, value any)` | Add value to context |
| `ContextWithTimeout[T](d time.Duration)` | Add timeout |
| `ContextWithDeadline[T](t time.Time)` | Add deadline |
| `ContextMap[T](fn func(ctx) ctx)` | Transform context |
| `ThrowOnContextCancel[T]()` | Error when context is cancelled |
## Conditional Operators
| Operator | Purpose |
| --- | --- |
| `All[T](fn func(T) bool)` | Emit bool: whether all values match |
| `DefaultIfEmpty[T](value T)` | Emit default if source completes empty |
| `ThrowIfEmpty[T](fn func() error)` | Error if empty |
| `Iif[T](pred func() bool, a, b Observable[T])` | Choose between two observables |
| `While[T](cond func() bool)` | Repeat while condition true |
| `DoWhile[T](cond func() bool)` | Execute at least once, repeat while true |
| `SequenceEqual[T](obsB Observable[T])` | Emit bool: whether two streams match |
## Terminal Operators
| Operator | Purpose |
| --- | --- |
| `Collect[T](obs Observable[T]) ([]T, error)` | Block, return all values as slice |
| `CollectWithContext[T](ctx, obs) ([]T, ctx, error)` | Collect with context |
| `ToSlice[T]()` | Operator: emit `[]T` on complete |
| `ToChannel[T](size int)` | Convert to `<-chan Notification[T]` |
| `ToMap[T, K, V](fn func(T) (K, V))` | Collect into map |
## Observer and Subscription
```go
// Full observer (recommended)
observer := ro.NewObserver[T](onNext, onError, onComplete)
// Context-aware observer
observer := ro.NewObserverWithContext[T](onNext, onError, onComplete)
// Convenience shortcuts
observer := ro.OnNext[T](func(v T) { ... })
observer := ro.PrintObserver[T]() // debug: prints all events
observer := ro.NoopObserver[T]() // discard all events
// Subscription lifecycle
sub := observable.Subscribe(observer)
sub.Wait() // block until complete or error
sub.Unsubscribe() // cancel and cleanup
sub.IsActive() // check if still running
sub.GetError() // get terminal error
```
## Scheduling
| Operator | Purpose |
| -------------------------------- | ---------------------------------------- |
| `SubscribeOn[T](bufferSize int)` | Run subscription on async scheduler |
| `ObserveOn[T](bufferSize int)` | Deliver notifications on async scheduler |
## Concurrency Modes
```go
// Safe (default): synchronized emissions
ro.NewObservable[T](fn)
ro.NewSafeObservable[T](fn)
// Unsafe: no synchronization, caller must guarantee single-goroutine access
ro.NewUnsafeObservable[T](fn)
// Eventually safe: allows brief unsynchronized period, then synchronizes
ro.NewEventuallySafeObservable[T](fn)
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |