Golang Samber Ro

1---2name: golang-samber-ro3description: "Reactive 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 golang-samber-lo skill)."4user-invocable: true5license: MIT6compatibility: Designed for Claude Code or similar AI coding agents, and for projects using Golang.7metadata:8  author: samber9  version: "1.0.4"10  openclaw:11    emoji: "👁️"12    homepage: https://github.com/samber/cc-skills-golang13    requires:14      bins:15        - go16    install: []17    skill-library-version: "0.3.0"18allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent mcp__context7__resolve-library-id mcp__context7__query-docs AskUserQuestion19---20 21**Persona:** You are a Go engineer who reaches for reactive streams when data flows asynchronously or infinitely. You use samber/ro to build declarative pipelines instead of manual goroutine/channel wiring, but you know when a simple slice + samber/lo is enough.22 23**Thinking mode:** Use `ultrathink` when designing advanced reactive pipelines or choosing between cold/hot observables, subjects, and combining operators. Wrong architecture leads to resource leaks or missed events.24 25# samber/ro — Reactive Streams for Go26 27Go implementation of [ReactiveX](https://reactivex.io/). Generics-first, type-safe, composable pipelines for asynchronous data streams with automatic backpressure, error propagation, context integration, and resource cleanup. 150+ operators, 5 subject types, 40+ plugins.28 29**Official Resources:**30 31- [github.com/samber/ro](https://github.com/samber/ro)32- [ro.samber.dev](https://ro.samber.dev)33- [pkg.go.dev/github.com/samber/ro](https://pkg.go.dev/github.com/samber/ro)34 35This skill is not exhaustive. Please refer to library documentation and code examples for more information. Context7 can help as a discoverability platform.36 37## Why samber/ro (Streams vs Slices)38 39Go channels + goroutines become unwieldy for complex async pipelines: manual channel closures, verbose goroutine lifecycle, error propagation across nested selects, and no composable operators. `samber/ro` solves this with declarative, chainable stream operators.40 41**When to use which tool:**42 43| Scenario | Tool | Why |44| --- | --- | --- |45| Transform a slice (map, filter, reduce) | `samber/lo` | Finite, synchronous, eager — no stream overhead needed |46| Simple goroutine fan-out with error handling | `errgroup` | Standard lib, lightweight, sufficient for bounded concurrency |47| Infinite event stream (WebSocket, tickers, file watcher) | `samber/ro` | Declarative pipeline with backpressure, retry, timeout, combine |48| Real-time data enrichment from multiple async sources | `samber/ro` | CombineLatest/Zip compose dependent streams without manual select |49| Pub/sub with multiple consumers sharing one source | `samber/ro` | Hot observables (Share/Subjects) handle multicast natively |50 51**Key differences: lo vs ro**52 53| Aspect | `samber/lo` | `samber/ro` |54| --- | --- | --- |55| Data | Finite slices | Infinite streams |56| Execution | Synchronous, blocking | Asynchronous, non-blocking |57| Evaluation | Eager (allocates intermediate slices) | Lazy (processes items as they arrive) |58| Timing | Immediate | Time-aware (delay, throttle, interval, timeout) |59| Error model | Return `(T, error)` per call | Error channel propagates through pipeline |60| Use case | Collection transforms | Event-driven, real-time, async pipelines |61 62## Installation63 64```bash65go get github.com/samber/ro66```67 68## Core Concepts69 70Four building blocks:71 721. **Observable** — a data source that emits values over time. Cold by default: each subscriber triggers independent execution from scratch732. **Observer** — a consumer with three callbacks: `onNext(T)`, `onError(error)`, `onComplete()`743. **Operator** — a function that transforms an observable into another observable, chained via `Pipe`754. **Subscription** — the connection between observable and observer. Call `.Wait()` to block or `.Unsubscribe()` to cancel76 77```go78observable := ro.Pipe2(79    ro.RangeWithInterval(0, 5, 1*time.Second),80    ro.Filter(func(x int) bool { return x%2 == 0 }),81    ro.Map(func(x int) string { return fmt.Sprintf("even-%d", x) }),82)83 84observable.Subscribe(ro.NewObserver(85    func(s string) { fmt.Println(s) },      // onNext86    func(err error) { log.Println(err) },    // onError87    func() { fmt.Println("Done!") },         // onComplete88))89// Output: "even-0", "even-2", "even-4", "Done!"90 91// Or collect synchronously:92values, err := ro.Collect(observable)93```94 95## Cold vs Hot Observables96 97**Cold** (default): each `.Subscribe()` starts a new independent execution. Safe and predictable — use by default.98 99**Hot**: multiple subscribers share a single execution. Use when the source is expensive (WebSocket, DB poll) or subscribers must see the same events.100 101| Convert with | Behavior |102| --- | --- |103| `Share()` | Cold → hot with reference counting. Last unsubscribe tears down |104| `ShareReplay(n)` | Same as Share + buffers last N values for late subscribers |105| `Connectable()` | Cold → hot, but waits for explicit `.Connect()` call |106| Subjects | Natively hot — call `.Send()`, `.Error()`, `.Complete()` directly |107 108| Subject | Constructor | Replay behavior |109| --- | --- | --- |110| `PublishSubject` | `NewPublishSubject[T]()` | None — late subscribers miss past events |111| `BehaviorSubject` | `NewBehaviorSubject[T](initial)` | Replays last value to new subscribers |112| `ReplaySubject` | `NewReplaySubject[T](bufferSize)` | Replays last N values |113| `AsyncSubject` | `NewAsyncSubject[T]()` | Emits only last value, only on complete |114| `UnicastSubject` | `NewUnicastSubject[T](bufferSize)` | Single subscriber only |115 116For subject details and hot observable patterns, see [Subjects Guide](./references/subjects-guide.md).117 118## Operator Quick Reference119 120| Category | Key operators | Purpose |121| --- | --- | --- |122| Creation | `Just`, `FromSlice`, `FromChannel`, `Range`, `Interval`, `Defer`, `Future` | Create observables from various sources |123| Transform | `Map`, `MapErr`, `FlatMap`, `Scan`, `Reduce`, `GroupBy` | Transform or accumulate stream values |124| Filter | `Filter`, `Take`, `TakeLast`, `Skip`, `Distinct`, `Find`, `First`, `Last` | Selectively emit values |125| Combine | `Merge`, `Concat`, `Zip2`–`Zip6`, `CombineLatest2`–`CombineLatest5`, `Race` | Merge multiple observables |126| Error | `Catch`, `OnErrorReturn`, `OnErrorResumeNextWith`, `Retry`, `RetryWithConfig` | Recover from errors |127| Timing | `Delay`, `DelayEach`, `Timeout`, `ThrottleTime`, `SampleTime`, `BufferWithTime` | Control emission timing |128| Side effect | `Tap`/`Do`, `TapOnNext`, `TapOnError`, `TapOnComplete` | Observe without altering stream |129| Terminal | `Collect`, `ToSlice`, `ToChannel`, `ToMap` | Consume stream into Go types |130 131Use typed `Pipe2`, `Pipe3` ... `Pipe25` for compile-time type safety across operator chains. The untyped `Pipe` uses `any` and loses type checking.132 133For the complete operator catalog (150+ operators with signatures), see [Operators Guide](./references/operators-guide.md).134 135## Common Mistakes136 137| Mistake | Why it fails | Fix |138| --- | --- | --- |139| Using `ro.OnNext()` without error handler | Errors are silently dropped — bugs hide in production | Use `ro.NewObserver(onNext, onError, onComplete)` with all 3 callbacks |140| Using untyped `Pipe()` instead of `Pipe2`/`Pipe3` | Loses compile-time type safety, errors surface at runtime | Use `Pipe2`, `Pipe3`...`Pipe25` for typed operator chains |141| Forgetting `.Unsubscribe()` on infinite streams | Goroutine leak — the observable runs forever | Use `TakeUntil(signal)`, context cancellation, or explicit `Unsubscribe()` |142| Using `Share()` when cold is sufficient | Unnecessary complexity, harder to reason about lifecycle | Use hot observables only when multiple consumers need the same stream |143| Using `samber/ro` for finite slice transforms | Stream overhead (goroutines, subscriptions) for a synchronous operation | Use `samber/lo` — it's simpler, faster, and purpose-built for slices |144| Not propagating context for cancellation | Streams ignore shutdown signals, causing resource leaks on termination | Chain `ContextWithTimeout` or `ThrowOnContextCancel` in the pipeline |145 146## Best Practices147 1481. **Always handle all three events** — use `NewObserver(onNext, onError, onComplete)`, not just `OnNext`. Unhandled errors cause silent data loss1492. **Use `Collect()` for synchronous consumption** — when the stream is finite and you need `[]T`, `Collect` blocks until complete and returns the slice + error1503. **Prefer typed Pipe functions** — `Pipe2`, `Pipe3`...`Pipe25` catch type mismatches at compile time. Reserve untyped `Pipe` for dynamic operator chains1514. **Bound infinite streams** — use `Take(n)`, `TakeUntil(signal)`, `Timeout(d)`, or context cancellation. Unbounded streams leak goroutines1525. **Use `Tap`/`Do` for observability** — log, trace, or meter emissions without altering the stream. Chain `TapOnError` for error monitoring1536. **Prefer `samber/lo` for simple transforms** — if the data is a finite slice and you need Map/Filter/Reduce, use `lo`. Reach for `ro` when data arrives over time, from multiple sources, or needs retry/timeout/backpressure154 155## Plugin Ecosystem156 15740+ plugins extend ro with domain-specific operators:158 159| Category | Plugins | Import path prefix |160| --- | --- | --- |161| Encoding | JSON, CSV, Base64, Gob | `plugins/encoding/...` |162| Network | HTTP, I/O, FSNotify | `plugins/http`, `plugins/io`, `plugins/fsnotify` |163| Scheduling | Cron, ICS | `plugins/cron`, `plugins/ics` |164| Observability | Zap, Slog, Zerolog, Logrus, Sentry, Oops | `plugins/observability/...`, `plugins/samber/oops` |165| Rate limiting | Native, Ulule | `plugins/ratelimit/...` |166| Data | Bytes, Strings, Sort, Strconv, Regexp, Template | `plugins/bytes`, `plugins/strings`, etc. |167| System | Process, Signal | `plugins/proc`, `plugins/signal` |168 169For the full plugin catalog with import paths and usage examples, see [Plugin Ecosystem](./references/plugin-ecosystem.md).170 171For real-world reactive patterns (retry+timeout, WebSocket fan-out, graceful shutdown, stream combination), see [Patterns](./references/patterns.md).172 173If you encounter a bug or unexpected behavior in samber/ro, open an issue at [github.com/samber/ro/issues](https://github.com/samber/ro/issues).174 175## Cross-References176 177- → See `samber/cc-skills-golang@golang-samber-lo` skill for finite slice transforms (Map, Filter, Reduce, GroupBy) — use lo when data is already in a slice178- → See `samber/cc-skills-golang@golang-samber-mo` skill for monadic types (Option, Result, Either) that compose with ro pipelines179- → See `samber/cc-skills-golang@golang-samber-hot` skill for in-memory caching (also available as an ro plugin)180- → See `samber/cc-skills-golang@golang-concurrency` skill for goroutine/channel patterns when reactive streams are overkill181- → See `samber/cc-skills-golang@golang-observability` skill for monitoring reactive pipelines in production