Skip to content

samber/cc-skills-golang / skills/golang-samber-ro

golang-samber-ro

Verified

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 `samber/cc-skills-golang@golang-samber-lo` skill).

FileKindSize
SKILL.mdskill md11.8 KB
evals/evals.jsonconfig17.3 KB
references/operators-guide.mdmarkdown14.6 KB
references/patterns.mdmarkdown8.0 KB
references/plugin-ecosystem.mdmarkdown6.3 KB
references/subjects-guide.mdmarkdown6.3 KB

references/patterns.md

View on GitHub
# Reactive Patterns

Real-world patterns for building production reactive pipelines with samber/ro.

## Table of Contents

- [Pattern 1: Remote Call with Retry and Timeout](#pattern-1-remote-call-with-retry-and-timeout)
- [Pattern 2: Continuous Event Stream (Hot Observable)](#pattern-2-continuous-event-stream-hot-observable)
- [Pattern 3: Fan-In from Multiple Sources](#pattern-3-fan-in-from-multiple-sources)
- [Pattern 4: Dependent Data Combination](#pattern-4-dependent-data-combination)
- [Pattern 5: Running Aggregation with Scan](#pattern-5-running-aggregation-with-scan)
- [Pattern 6: Error Recovery Cascade](#pattern-6-error-recovery-cascade)
- [Pattern 7: File System Watcher](#pattern-7-file-system-watcher)
- [Pattern 8: Graceful Shutdown](#pattern-8-graceful-shutdown)
- [Pattern 9: Event-Driven Pipeline with Logging](#pattern-9-event-driven-pipeline-with-logging)

## Pattern 1: Remote Call with Retry and Timeout

Wrap a remote call (HTTP, gRPC, database) with automatic retry, exponential backoff, timeout, and fallback.

```go
result := ro.Pipe3(
    fetchUser(userID),  // ro.Observable[User] — wraps your remote call
    ro.Timeout[User](5*time.Second),
    ro.RetryWithConfig[User](ro.RetryConfig{
        Max:               3,
        Delay:             500 * time.Millisecond,
        BackoffMultiplier: 2.0,
        MaxDelay:          5 * time.Second,
    }),
    ro.Catch[User](func(err error) ro.Observable[User] {
        log.Printf("remote call failed after retries: %v, using cache", err)
        return getCachedUser(userID)
    }),
)

user, err := ro.Collect(result)
```

**Why ro over plain calls:** declarative retry + timeout + fallback in 10 lines vs manual for-loops with sleep, context, and error tracking.

## Pattern 2: Continuous Event Stream (Hot Observable)

Share a single long-lived connection (WebSocket, SSE, message queue) across multiple consumers.

```go
// Cold observable wrapping any event stream source
eventStream := ro.NewObservable[TickerEvent](func(ctx context.Context, obs ro.Observer[TickerEvent]) error {
    // connect to your stream source (WebSocket, NATS, Kafka, etc.)
    for {
        event, err := streamSource.Read(ctx)
        if err != nil {
            return err
        }
        obs.Next(event)
    }
})

// Share: one connection, multiple consumers
shared := ro.Pipe1(eventStream, ro.Share[TickerEvent]())

// Consumer 1: update UI
shared.Subscribe(ro.OnNext(func(e TickerEvent) {
    updateDashboard(e)
}))

// Consumer 2: record metrics
shared.Subscribe(ro.OnNext(func(e TickerEvent) {
    metrics.RecordTick(e.Symbol, e.Price)
}))

// Consumer 3: alert on threshold
ro.Pipe1(shared, ro.Filter(func(e TickerEvent) bool {
    return e.Price > alertThreshold
})).Subscribe(ro.OnNext(sendAlert))
```

The `rohttp` plugin provides WebSocket and HTTP streaming observables (see [Plugin Ecosystem](./plugin-ecosystem.md)).

## Pattern 3: Fan-In from Multiple Sources

Merge events from multiple independent sources, batch, and process.

```go
combined := ro.Pipe2(
    ro.Merge(
        apiStream,
        pushStream,
        cronScheduleStream,
    ),
    ro.Distinct[Event](),
    ro.BufferWithTimeOrCount[Event](100, 5*time.Second),
    ro.Map(func(batch []Event) ProcessResult {
        return processBatch(batch)
    }),
)
```

**When to use Merge vs Concat vs Zip:**

| Operator | Behavior | Use when |
| --- | --- | --- |
| `Merge` | Interleave: emit from any source as it arrives | Independent streams, order doesn't matter |
| `Concat` | Sequential: finish first source, then start second | Ordered processing, fallback chains |
| `Zip` | Pair: wait for one value from each source | Correlated data (user + settings, request + response) |
| `CombineLatest` | Latest: re-emit combined whenever any source changes | Dependent state (price \* quantity, config + data) |

## Pattern 4: Dependent Data Combination

Combine data from multiple async sources that depend on each other.

```go
// Fetch user and their orders in parallel, combine
profile := ro.Pipe1(
    ro.CombineLatest2(
        fetchUser(userID),
        fetchOrders(userID),
    ),
    ro.Map(func(pair lo.Tuple2[User, []Order]) UserProfile {
        return UserProfile{
            User:   pair.A,
            Orders: pair.B,
        }
    }),
)
```

For independent data where you need exactly one value from each:

```go
// Zip: waits for one value from each, pairs them
configAndData := ro.Zip2(loadConfig(), loadData())
```

## Pattern 5: Running Aggregation with Scan

Maintain running state across stream values — useful for dashboards, analytics, monitoring.

```go
type Stats struct {
    Count int
    Sum   float64
    Avg   float64
    Max   float64
}

statsStream := ro.Pipe2(
    metricsStream,
    ro.Scan(func(acc Stats, v float64) Stats {
        acc.Count++
        acc.Sum += v
        acc.Avg = acc.Sum / float64(acc.Count)
        if v > acc.Max {
            acc.Max = v
        }
        return acc
    }, Stats{}),
    ro.SampleTime[Stats](5*time.Second), // emit stats every 5s
)
```

**Scan vs Reduce:** `Scan` emits every intermediate state (good for live dashboards). `Reduce` emits only the final accumulated value (good for batch summaries).

## Pattern 6: Error Recovery Cascade

Layer multiple error recovery strategies.

```go
resilient := ro.Pipe3(
    primaryDataSource,
    // Strategy 1: retry transient failures
    ro.RetryWithConfig[Data](ro.RetryConfig{
        Max:   2,
        Delay: time.Second,
    }),
    // Strategy 2: fall back to secondary source
    ro.Catch[Data](func(err error) ro.Observable[Data] {
        log.Warn("primary failed, trying secondary", "err", err)
        return secondaryDataSource
    }),
    // Strategy 3: return cached/default value
    ro.OnErrorReturn[Data](cachedDefault),
)
```

**Order matters:** retry first (transient errors), then fallback source (persistent errors), then default value (total failure).

## Pattern 7: File System Watcher

React to file changes with debouncing.

```go
import rofsnotify "github.com/samber/ro/plugins/fsnotify"

watcher := ro.Pipe3(
    rofsnotify.Watch("/etc/app/config/"),
    ro.Filter(func(e fsnotify.Event) bool {
        return e.Op&fsnotify.Write != 0
    }),
    ro.ThrottleTime[fsnotify.Event](2*time.Second), // debounce rapid saves
    ro.Map(func(e fsnotify.Event) Config {
        return reloadConfig(e.Name)
    }),
)

watcher.Subscribe(ro.NewObserver(
    func(cfg Config) { applyConfig(cfg) },
    func(err error) { log.Error("config watch failed", "err", err) },
    func() { log.Info("config watcher stopped") },
))
```

## Pattern 8: Graceful Shutdown

Use context or signal observable to cleanly terminate infinite streams.

```go
import rosignal "github.com/samber/ro/plugins/signal"

// Method 1: OS signal
shutdown := rosignal.Notify(syscall.SIGTERM, syscall.SIGINT)

sub := ro.Pipe1(
    workStream,
    ro.TakeUntil[Work, os.Signal](shutdown),
).Subscribe(ro.NewObserver(
    processWork,
    handleError,
    func() { log.Info("gracefully stopped") },
))

sub.Wait() // blocks until SIGTERM/SIGINT

// Method 2: Context cancellation
ctx, cancel := context.WithCancel(context.Background())

sub := ro.Pipe2(
    workStream,
    ro.ContextReset[Work](ctx),
    ro.ThrowOnContextCancel[Work](),
).Subscribe(worker)

// Later: cancel() triggers clean shutdown
```

## Pattern 9: Event-Driven Pipeline with Logging

Full production pipeline with observability at each stage.

```go
import roslog "github.com/samber/ro/plugins/observability/slog"

pipeline := ro.Pipe5(
    eventSource,
    ro.TapOnSubscribe[Event](func() {
        slog.Info("pipeline started")
    }),
    ro.Filter(func(e Event) bool { return e.Valid() }),
    roslog.TapOnNext[Event](logger, slog.LevelDebug), // log each event
    ro.Map(enrichEvent),
    ro.BufferWithTimeOrCount[EnrichedEvent](50, 10*time.Second),
    ro.MapErr(func(batch []EnrichedEvent) (Result, error) {
        return persistBatch(batch)
    }),
    ro.TapOnError[Result](func(err error) {
        slog.Error("pipeline error", "err", err)
        metrics.IncrCounter("pipeline.errors", 1)
    }),
    ro.RetryWithConfig[Result](ro.RetryConfig{Max: 3, Delay: time.Second}),
)
```
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall