brass-runtime 1.16.0 → 1.17.0

package/docs/guides/streams.md

@@ -0,0 +1,117 @@
+# Streams & Pipelines
+
+brass-runtime provides ZIO-style streams with automatic fusion for high performance.
+
+## Creating streams
+
+```ts
+import { fromArray, emptyStream, fromPull } from "brass-runtime";
+
+// From an array (optimized: uses FromArray node, no per-element overhead)
+const numbers = fromArray([1, 2, 3, 4, 5]);
+
+// Empty stream
+const empty = emptyStream();
+```
+
+## Pipelines (transformers)
+
+Pipelines are reusable stream transformers:
+
+```ts
+import { mapP, filterP, takeP, dropP, andThen, via } from "brass-runtime";
+
+// Single operators
+const doubled = mapP((x: number) => x * 2);
+const evens = filterP((x: number) => x % 2 === 0);
+const first10 = takeP(10);
+const skipFirst5 = dropP(5);
+
+// Compose pipelines (auto-fused!)
+const pipeline = andThen(
+  andThen(doubled, evens),
+  first10
+);
+
+// Apply to a stream
+const result = await run(collectStream(via(fromArray(data), pipeline)));
+```
+
+## Stream Fusion
+
+When you compose pure operators with `andThen`, brass-runtime automatically fuses them into a single loop — no intermediate fibers, no per-element scheduling overhead.
+
+```ts
+// This pipeline:
+const pipeline = andThen(
+  andThen(mapP(x => x * 2), filterP(x => x > 10)),
+  takeP(100)
+);
+
+// Is executed as a single tight loop equivalent to:
+// for (const x of input) {
+//   const mapped = x * 2;
+//   if (mapped > 10) { output.push(mapped); if (output.length >= 100) break; }
+// }
+```
+
+**Performance:** 10,000 elements through map+filter in **0.25ms** (vs 84ms without fusion).
+
+## Stream Operators
+
+```ts
+import { zip, zipWith, scan, interleave, take, drop, throttle, debounce } from "brass-runtime";
+
+// Zip two streams element-by-element
+const pairs = zip(names, ages); // ["Alice", 30], ["Bob", 25], ...
+
+// Running accumulator
+const runningSum = scan(numbers, 0, (acc, n) => acc + n);
+// 0, 1, 3, 6, 10, 15, ...
+
+// Interleave (alternate elements)
+const mixed = interleave(evens, odds);
+
+// Rate limiting
+const throttled = throttle(events, 1000); // max 1 per second
+const debounced = debounce(keystrokes, 300); // emit after 300ms silence
+```
+
+## Collecting results
+
+```ts
+import { collectStream } from "brass-runtime";
+
+// Collect all elements into an array
+const all = await run(collectStream(stream));
+
+// With pipeline
+const filtered = await run(collectStream(via(stream, pipeline)));
+```
+
+## Queue-based streams
+
+```ts
+import { bounded } from "brass-runtime";
+
+const queue = await run(bounded(100, "backpressure"));
+
+// Producer
+for (const item of items) {
+  await run(queue.offer(item));
+}
+
+// Consumer
+const value = await run(queue.take());
+
+// Batch operations
+const results = await run(queue.offerBatch(items));
+const batch = await run(queue.takeBatch(50));
+```
+
+## Performance tips
+
+1. **Use `andThen` for composition** — triggers automatic fusion
+2. **Use `fromArray` for known data** — uses optimized FromArray node
+3. **Use `via` instead of calling pipeline directly** — enables fusion fast-path
+4. **Batch queue operations** — `offerBatch`/`takeBatch` for bulk work

package/docs/guides/supervisors.md

@@ -0,0 +1,98 @@
+# Supervisors
+
+Supervisors let a runtime own groups of child fibers with explicit restart and
+escalation policy. Use them for long-lived workers, polling loops, connection
+refreshers, and other background work that should fail in a predictable shape.
+
+```ts
+import { Runtime, fixed, joinSupervised, makeSupervisor } from "brass-runtime";
+
+const runtime = Runtime.make({});
+const supervisor = makeSupervisor(runtime, {
+  strategy: "one-for-one",
+  restart: {
+    mode: "on-failure",
+    maxRestarts: 5,
+    withinMs: 60_000,
+    schedule: fixed(250),
+  },
+});
+
+const worker = supervisor.start({
+  name: "token-refresh",
+  effect: () => refreshTokenLoop(),
+});
+
+await runtime.toPromise(joinSupervised(worker));
+```
+
+## Strategies
+
+- `one-for-one`: restart only the child that failed.
+- `all-for-one`: interrupt and restart siblings when one child fails.
+
+## Restart Policy
+
+`restart` can be `"never"`, `"always"`, `"on-failure"`, or an object:
+
+```ts
+const supervisor = makeSupervisor(runtime, {
+  restart: {
+    mode: "on-failure",
+    maxRestarts: 10,
+    withinMs: 30_000,
+    delayMs: ({ restartCount }) => Math.min(1_000, restartCount * 100),
+  },
+});
+```
+
+For reusable timing behavior, pass a `Schedule`:
+
+```ts
+import { exponential, jitter, makeSupervisor } from "brass-runtime";
+
+const supervisor = makeSupervisor(runtime, {
+  restart: {
+    mode: "on-failure",
+    schedule: jitter(exponential(100, 5_000), { factor: 0.2 }),
+  },
+});
+```
+
+## Escalation
+
+When the restart budget is exhausted, escalation controls what happens next:
+
+- `shutdown` interrupts sibling fibers.
+- `ignore` completes only the failed child and leaves siblings running.
+
+```ts
+const supervisor = makeSupervisor(runtime, {
+  strategy: "all-for-one",
+  restart: { mode: "on-failure", maxRestarts: 3 },
+  escalation: "shutdown",
+});
+```
+
+## Observability
+
+Supervisors emit runtime events through the existing `RuntimeHooks` pipeline:
+
+- `supervisor.child.start`
+- `supervisor.child.end`
+- `supervisor.child.restart`
+- `supervisor.child.escalate`
+- `supervisor.shutdown`
+
+Attach an `EventBus`, metrics sink, structured logger, or observability preset
+the same way you do for fibers/scopes.
+
+## Shutdown
+
+Call `shutdown()` during graceful process termination. It cancels pending
+restart timers, interrupts running children, and completes when current child
+fibers have observed interruption.
+
+```ts
+await runtime.toPromise(supervisor.shutdown());
+```

package/docs/guides/testing.md

@@ -0,0 +1,162 @@
+# Testing Utilities
+
+brass-runtime provides helpers for testing effects deterministically.
+
+## TestRuntime
+
+```ts
+import { makeTestRuntime } from "brass-runtime";
+
+const { runtime, run, runExit, clock, advance, flushAll } = makeTestRuntime();
+
+// run() returns the value (throws on failure)
+const value = await run(myEffect);
+
+// runExit() returns the full Exit (never throws)
+const exit = await runExit(myEffect);
+if (exit._tag === "Success") console.log(exit.value);
+else console.log(exit.cause);
+```
+
+`makeTestRuntime()` uses the TypeScript runtime engine with:
+
+- `TestScheduler`, a deterministic scheduler you can inspect and flush.
+- `TestClock`, a virtual clock used by `sleep`, `timeout`, retry backoff,
+  `delayedEffect`, and `Runtime.delay`.
+- The same fiber interpreter as production TS mode.
+
+The scheduler auto-flushes by default for ergonomic tests. Disable that when
+you need to inspect queued work:
+
+```ts
+import { makeTestRuntime, succeed } from "brass-runtime";
+
+const { runtime, scheduler, flushAll } = makeTestRuntime({}, { autoFlush: false });
+
+const pending = runtime.toPromise(succeed("ok"));
+expect(scheduler.size()).toBe(1);
+
+flushAll();
+await expect(pending).resolves.toBe("ok");
+```
+
+## Virtual Time
+
+```ts
+import { makeTestRuntime, sleep, timeout, neverEffect } from "brass-runtime";
+
+const { run, runExit, clock, advance } = makeTestRuntime();
+
+const sleeping = run(sleep(1_000));
+expect(clock.pendingTimers()).toHaveLength(1);
+
+advance(1_000);
+await sleeping;
+
+const timedOut = runExit(timeout(neverEffect(), 50));
+advance(50);
+expect(await timedOut).toMatchObject({
+  _tag: "Failure",
+  cause: { _tag: "Fail", error: { _tag: "TimeoutError", ms: 50 } },
+});
+```
+
+## Assertion helpers
+
+```ts
+import { assertSucceeds, assertFails, assertFailsWith, assertCompletesWithin } from "brass-runtime";
+
+// Assert success with specific value
+await assertSucceeds(myEffect, 42);
+
+// Assert failure with specific error
+await assertFails(myEffect, "not found");
+
+// Assert failure matching a predicate
+await assertFailsWith(myEffect, (e) => e._tag === "NetworkError");
+
+// Assert effect completes within time limit
+const result = await assertCompletesWithin(myEffect, 100); // max 100ms
+```
+
+## Test effect builders
+
+```ts
+import { flakyEffect, delayedEffect, neverEffect } from "brass-runtime";
+
+// Fails N times, then succeeds (for testing retry)
+const flaky = flakyEffect(3, "success!", "temporary error");
+// Call 1: fails with "temporary error"
+// Call 2: fails with "temporary error"
+// Call 3: fails with "temporary error"
+// Call 4: succeeds with "success!"
+
+// Completes after a delay (for testing timeouts)
+const slow = delayedEffect(500, "done");
+
+// Never completes (for testing interruption)
+const hanging = neverEffect();
+```
+
+## Testing retry logic
+
+```ts
+import { flakyEffect, retryN, makeTestRuntime } from "brass-runtime";
+
+const { run } = makeTestRuntime();
+
+it("retries and eventually succeeds", async () => {
+  const effect = retryN(flakyEffect(2, "ok", "fail"), 3);
+  const result = await run(effect);
+  expect(result).toBe("ok");
+});
+
+it("fails after exhausting retries", async () => {
+  const effect = retryN(flakyEffect(10, "ok", "fail"), 2);
+  const exit = await runExit(effect);
+  expect(exit._tag).toBe("Failure");
+});
+```
+
+## Testing timeouts
+
+```ts
+import { timeout, delayedEffect, neverEffect, makeTestRuntime } from "brass-runtime";
+
+const { run, advance } = makeTestRuntime();
+
+it("succeeds before timeout", async () => {
+  const result = run(timeout(delayedEffect(10, "fast"), 1000));
+  advance(10);
+  await expect(result).resolves.toBe("fast");
+});
+
+it("times out on slow effect", async () => {
+  const result = run(timeout(neverEffect(), 50));
+  advance(50);
+  await expect(result).rejects.toMatchObject({ _tag: "TimeoutError", ms: 50 });
+});
+```
+
+## Testing concurrency
+
+```ts
+import { makeSemaphore, makeTestRuntime, delayedEffect } from "brass-runtime";
+
+const { run } = makeTestRuntime();
+
+it("limits concurrency", async () => {
+  const sem = makeSemaphore(2);
+  let maxConcurrent = 0;
+  let current = 0;
+
+  const task = sem.withPermit(async((_env, cb) => {
+    current++;
+    maxConcurrent = Math.max(maxConcurrent, current);
+    setTimeout(() => { current--; cb({ _tag: "Success", value: undefined }); }, 10);
+  }));
+
+  await Promise.all([run(task), run(task), run(task), run(task)]);
+  expect(maxConcurrent).toBeLessThanOrEqual(2);
+});
+```

package/docs/guides/tracing.md

@@ -0,0 +1,71 @@
+# Tracing
+
+OpenTelemetry-compatible span generation for effects.
+
+## Setup
+
+```ts
+import { makeTracer } from "brass-runtime";
+
+const tracer = makeTracer({
+  serviceName: "my-api",
+  sampleRate: 1.0, // sample everything (use 0.1 for 10% in production)
+  onSpanEnd: (span) => {
+    // Export to your backend (Jaeger, Zipkin, etc.)
+    console.log(`[${span.status}] ${span.name}: ${span.endTime! - span.startTime}ms`);
+  },
+});
+```
+
+## Wrapping effects in spans
+
+```ts
+// Wrap any effect in a span
+const result = await run(
+  tracer.span("fetchUser", fetchUser(userId), { userId })
+);
+
+// Nested spans
+const result = await run(
+  tracer.span("handleRequest", asyncFlatMap(
+    tracer.span("validateInput", validate(input)),
+    (valid) => tracer.span("processData", process(valid))
+  ))
+);
+```
+
+## Attributes
+
+```ts
+tracer.span("db.query", dbQuery(sql), {
+  "db.system": "postgresql",
+  "db.statement": sql,
+  "db.name": "users",
+});
+```
+
+## Inspecting spans (testing)
+
+```ts
+const tracer = makeTracer({ serviceName: "test" });
+
+await run(tracer.span("myOp", asyncSucceed(42)));
+
+const spans = tracer.spans();
+expect(spans[0].name).toBe("myOp");
+expect(spans[0].status).toBe("ok");
+expect(spans[0].endTime! - spans[0].startTime).toBeLessThan(10);
+
+tracer.clear(); // reset for next test
+```
+
+## Error spans
+
+```ts
+await run(tracer.span("failingOp", asyncFail("oops"))).catch(() => {});
+
+const span = tracer.spans()[0];
+expect(span.status).toBe("error");
+expect(span.events[0].name).toBe("error");
+expect(span.events[0].attributes!["error.message"]).toBe("oops");
+```