brass-runtime 1.16.0 → 1.16.1

package/docs/guides/metrics.md

@@ -0,0 +1,101 @@
+# Metrics
+
+Lightweight metrics collection with counters, gauges, and histograms.
+
+## Setup
+
+```ts
+import { makeMetrics } from "brass-runtime";
+
+const metrics = makeMetrics();
+```
+
+## Counters
+
+Monotonically increasing values (requests, errors, events):
+
+```ts
+const requestCount = metrics.counter("http_requests_total", { method: "GET" });
+requestCount.increment();
+requestCount.increment(5); // increment by 5
+
+console.log(requestCount.value()); // 6
+```
+
+## Gauges
+
+Values that go up and down (connections, queue depth):
+
+```ts
+const activeConns = metrics.gauge("active_connections");
+activeConns.set(10);
+activeConns.increment();   // 11
+activeConns.decrement(3);  // 8
+
+console.log(activeConns.value()); // 8
+```
+
+## Histograms
+
+Distribution of values (latency, sizes):
+
+```ts
+const latency = metrics.histogram("request_duration_ms", [1, 5, 10, 25, 50, 100, 250, 500, 1000]);
+
+latency.observe(42.5);
+latency.observe(3.2);
+latency.observe(150);
+
+// Get percentiles
+console.log(latency.percentile(50));  // p50
+console.log(latency.percentile(95));  // p95
+console.log(latency.percentile(99));  // p99
+
+// Get bucket distribution
+const buckets = latency.buckets();
+// { boundaries: [...], counts: [...], sum: 195.7, count: 3, min: 3.2, max: 150 }
+```
+
+## Snapshot (export all metrics)
+
+```ts
+const snapshot = metrics.snapshot();
+// {
+//   counters: [{ name: "http_requests_total", labels: { method: "GET" }, value: 6 }],
+//   gauges: [{ name: "active_connections", labels: {}, value: 8 }],
+//   histograms: [{ name: "request_duration_ms", labels: {}, buckets: {...} }],
+// }
+
+// Export to Prometheus format, CloudWatch, etc.
+```
+
+## With effects
+
+```ts
+const requestCounter = metrics.counter("requests");
+const latencyHist = metrics.histogram("latency_ms");
+
+const instrumented = <R, E, A>(name: string, effect: Async<R, E, A>): Async<R, E, A> => {
+  const start = performance.now();
+  requestCounter.increment();
+  
+  return asyncFold(
+    effect,
+    (error) => {
+      latencyHist.observe(performance.now() - start);
+      metrics.counter("errors", { operation: name }).increment();
+      return asyncFail(error);
+    },
+    (value) => {
+      latencyHist.observe(performance.now() - start);
+      return asyncSucceed(value);
+    }
+  );
+};
+```
+
+## Reset (for testing)
+
+```ts
+metrics.reset(); // clears all counters, gauges, histograms
+```

package/docs/guides/resource-management.md

@@ -0,0 +1,141 @@
+# Resource Management
+
+brass-runtime guarantees resource cleanup even when effects fail or fibers are interrupted.
+
+## bracket — Acquire/Use/Release
+
+The fundamental pattern for safe resource management:
+
+```ts
+import { bracket } from "brass-runtime";
+
+const result = await run(
+  bracket(
+    // Acquire: open the resource
+    openDatabaseConnection(),
+    
+    // Use: work with the resource
+    (conn) => conn.query("SELECT * FROM users"),
+    
+    // Release: always runs, even on failure/interruption
+    (conn, exit) => conn.close()
+  )
+);
+```
+
+**Guarantees:**
+- If `acquire` fails, `release` is never called
+- If `use` fails or is interrupted, `release` still runs
+- Errors in `release` are swallowed (the `use` result propagates)
+
+## ensuring — Attach a finalizer
+
+```ts
+import { ensuring } from "brass-runtime";
+
+const result = await run(
+  ensuring(
+    doWork(),
+    (exit) => {
+      // Always runs after doWork completes
+      if (exit._tag === "Success") logSuccess(exit.value);
+      else logFailure(exit.cause);
+      return unit();
+    }
+  )
+);
+```
+
+## managed — Reusable resource descriptors
+
+Define a resource once, use it many times:
+
+```ts
+import { managed, useManaged } from "brass-runtime";
+
+// Define the resource (acquire + release)
+const dbPool = managed(
+  asyncSucceed(createPool({ max: 10 })),
+  (pool) => { pool.close(); return unit(); }
+);
+
+// Use it — each call acquires a fresh instance
+const users = await run(useManaged(dbPool, (pool) => pool.query("SELECT *")));
+const orders = await run(useManaged(dbPool, (pool) => pool.query("SELECT *")));
+```
+
+## Resource — Composable scoped resources
+
+`Resource` is the higher-level acquire/use/release descriptor. It composes with
+`map`, `flatMap`, `zip`, and `Resource.all`, and releases nested resources in
+reverse acquisition order.
+
+```ts
+import { Resource, makeResource, useResource } from "brass-runtime";
+
+const db = makeResource(
+  openDatabasePool(),
+  (pool, _exit) => pool.close()
+);
+
+const cache = makeResource(
+  openCacheClient(),
+  (client, _exit) => client.disconnect()
+);
+
+const services = Resource.all([db, cache] as const);
+
+const users = await run(
+  useResource(services, ([pool, client]) =>
+    loadUsers(pool, client)
+  )
+);
+```
+
+`Resource.fromManaged(managedValue)` bridges older `managed` descriptors into
+the composable API.
+
+## managedAll — Compose multiple resources
+
+Acquire in order, release in reverse (LIFO):
+
+```ts
+import { managedAll, useManaged } from "brass-runtime";
+
+const dbPool = managed(createPool(), (p) => p.close());
+const cache = managed(createRedis(), (r) => r.disconnect());
+const storage = managed(createS3Client(), (s) => s.destroy());
+
+// All three acquired in order, released in reverse
+const resources = managedAll([dbPool, cache, storage]);
+
+const result = await run(
+  useManaged(resources, ([db, redis, s3]) => {
+    // Use all three services
+    return processData(db, redis, s3);
+  })
+);
+// s3 released first, then redis, then db
+```
+
+## With Semaphore (connection limiting)
+
+```ts
+import { makeSemaphore, bracket } from "brass-runtime";
+
+const poolSem = makeSemaphore(10); // max 10 connections
+
+const withConnection = (work: (conn: Connection) => Async<any, any, any>) =>
+  poolSem.withPermit(
+    bracket(
+      openConnection(),
+      work,
+      (conn) => conn.close()
+    )
+  );
+
+// At most 10 concurrent connections
+await Promise.all(
+  userIds.map(id => run(withConnection(conn => conn.query(id))))
+);
+```

package/docs/guides/retry.md

@@ -0,0 +1,215 @@
+# Retry & Backoff
+
+brass-runtime provides multiple retry strategies, from simple to composable.
+
+## Quick retry (no delay)
+
+```ts
+import { retryN } from "brass-runtime";
+
+// Retry up to 3 times with no delay
+const result = await run(retryN(fetchData(), 3));
+```
+
+## Exponential backoff with jitter
+
+```ts
+import { retryWithBackoff } from "brass-runtime";
+
+const result = await run(retryWithBackoff(callApi(), {
+  maxRetries: 5,
+  baseDelayMs: 100,     // first retry: random 0-100ms
+  maxDelayMs: 10_000,   // cap at 10s
+  maxElapsedMs: 60_000, // total budget: 60s
+  shouldRetry: (error) => error._tag !== "NotFound", // don't retry 404s
+}));
+```
+
+## Full control with retry()
+
+```ts
+import { retry } from "brass-runtime";
+
+const result = await run(retry(effect, {
+  maxRetries: 10,
+  baseDelayMs: 50,
+  maxDelayMs: 5000,
+  maxElapsedMs: 30_000,
+  jitter: "full",  // or "none" for deterministic delays
+  shouldRetry: (error, attempt) => {
+    if (error._tag === "RateLimit") return true;
+    if (attempt > 5) return false;
+    return true;
+  },
+}));
+```
+
+## Schedule 2.0
+
+For advanced use cases, use `Schedule` values. Schedules are declarative,
+stateful only when driven, and runtime-clock aware when used by
+`retryWithSchedule`, `repeatWithSchedule`, HTTP retry, supervisors, and server
+shutdown polling.
+
+```ts
+import { exponential, intersect, maxElapsed, recurs, retryWithSchedule } from "brass-runtime";
+
+// Retry 5 times with exponential backoff, but stop after 30s total
+const policy = maxElapsed(
+  intersect(recurs(5), exponential(100, 5000)),
+  30_000,
+);
+
+const result = await run(retryWithSchedule(effect, policy));
+```
+
+### ScheduleDriver
+
+Use a driver when you want to manually step a schedule, inspect state, reset it,
+or emit observability events.
+
+```ts
+import { Schedule } from "brass-runtime";
+
+const policy = Schedule.named(
+  "api.retry",
+  Schedule.jitter(Schedule.exponential(100, 5_000), { factor: 0.2 }),
+);
+
+const driver = Schedule.driver(policy, {
+  onDecision: (event) => {
+    console.log(event.name, event.attempt, event.decision.delayMs);
+  },
+});
+
+const next = driver.next({ status: 503 });
+
+if (next.continue) {
+  console.log(`wait ${next.delayMs}ms before trying again`);
+}
+
+driver.snapshot();
+driver.reset();
+```
+
+### Schedule combinators
+
+```ts
+import {
+  Schedule,
+  andThen,
+  elapsed,
+  exponential,
+  fibonacci,
+  fixed,
+  forever,
+  jitter,
+  jittered,
+  linear,
+  maxDelay,
+  maxElapsed,
+  never,
+  once,
+  recurs,
+  spaced,
+  take,
+  tapDecision,
+  untilInput,
+  untilOutput,
+  windowed,
+  whileOutput,
+} from "brass-runtime";
+
+// Fixed delay between retries
+const fixed5s = fixed(5000);
+
+// Alias for fixed delay
+const every5s = spaced(5000);
+
+// One-shot / forever / never policies
+const oneRetry = once();
+const always = forever();
+const stop = never();
+
+// Exponential: 100ms, 200ms, 400ms, 800ms... capped at 10s
+const expo = exponential(100, 10_000);
+
+// Linear: 100ms, 200ms, 300ms... capped at 10s
+const lin = linear(100, 10_000);
+
+// Fibonacci: 100ms, 100ms, 200ms, 300ms, 500ms... capped at 10s
+const fib = fibonacci(100, 10_000);
+
+// Full jitter: random in [0, exponential_delay]
+const fullJitter = jittered(100, 10_000);
+
+// Jitter any schedule by +/-20%
+const softJitter = jitter(expo, { factor: 0.2 });
+
+// Stop after N attempts
+const limited = take(expo, 5);
+
+// Cap delay or total elapsed runtime-clock budget
+const cappedDelay = maxDelay(expo, 2_000);
+const budgeted = maxElapsed(expo, 30_000);
+const elapsedOnly = elapsed(30_000);
+
+// Reset schedule state when the burst window expires
+const rolling = windowed(recurs(3), 60_000);
+
+// Stop based on inputs or outputs
+const untilReady = untilInput<{ status: string }>((input) => input.status === "ready");
+const whileSmall = whileOutput(linear(10), (attempt) => attempt < 5);
+const untilAttempt5 = untilOutput(linear(10), (attempt) => attempt >= 5);
+
+// Attach observability without changing retry semantics
+const observed = tapDecision(Schedule.named("db.retry", expo), (event) => {
+  console.log(event.name, event.attempt, event.decision.delayMs);
+});
+
+// First use fast retries, then switch to slow
+const staged = andThen(take(fixed(100), 3), exponential(1000, 30_000));
+```
+
+Schedules also plug into HTTP retry middleware, so retry, polling, and
+supervisor restarts can share the same timing model:
+
+```ts
+import { Schedule, exponential, jitter } from "brass-runtime";
+import { withRetry } from "brass-runtime/http";
+
+const retry = withRetry({
+  maxRetries: 5,
+  baseDelayMs: 100,
+  maxDelayMs: 5_000,
+  schedule: Schedule.named(
+    "users-api.retry",
+    jitter(exponential(100, 5_000), { factor: 0.2 }),
+  ),
+  onScheduleDecision: (event) => {
+    console.log(event.name, event.attempt, event.decision.delayMs);
+  },
+});
+```
+
+### Repeat (not just retry)
+
+```ts
+import { repeatWithSchedule, fixed } from "brass-runtime";
+
+// Poll every 5 seconds
+const poller = repeatWithSchedule(checkStatus(), fixed(5000));
+```
+
+## With Circuit Breaker
+
+```ts
+import { makeCircuitBreaker, retryWithBackoff } from "brass-runtime";
+
+const breaker = makeCircuitBreaker({ failureThreshold: 5 });
+
+const resilient = retryWithBackoff(
+  breaker.protect(callService()),
+  { maxRetries: 3, shouldRetry: (e) => e._tag !== "CircuitBreakerOpen" }
+);
+```

package/docs/guides/semaphore.md

@@ -0,0 +1,66 @@
+# Semaphore & Rate Limiting
+
+Control concurrency with counting semaphores.
+
+## Basic usage
+
+```ts
+import { makeSemaphore } from "brass-runtime";
+
+// Allow at most 5 concurrent operations
+const sem = makeSemaphore(5);
+
+// Automatic acquire/release
+const result = await run(sem.withPermit(callExternalApi()));
+```
+
+## Rate limiting API calls
+
+```ts
+const apiLimiter = makeSemaphore(10); // max 10 concurrent requests
+
+async function fetchAll(urls: string[]) {
+  return Promise.all(
+    urls.map(url => run(apiLimiter.withPermit(fetch(url))))
+  );
+}
+```
+
+## Database connection limiting
+
+```ts
+const connPool = makeSemaphore(20); // max 20 DB connections
+
+const query = (sql: string) =>
+  connPool.withPermit(
+    bracket(
+      openConnection(),
+      (conn) => conn.execute(sql),
+      (conn) => conn.release()
+    )
+  );
+```
+
+## Manual acquire/release
+
+```ts
+const sem = makeSemaphore(1); // mutex
+
+await run(sem.acquire());
+try {
+  // Critical section — only one fiber at a time
+  await doExclusiveWork();
+} finally {
+  sem.release();
+}
+```
+
+## Monitoring
+
+```ts
+const sem = makeSemaphore(10);
+
+console.log(sem.available()); // permits left (0-10)
+console.log(sem.waiting());   // fibers waiting for a permit
+console.log(sem.capacity);    // total permits (10)
+```

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