brass-runtime 1.16.0 → 1.17.0

package/docs/guides/layers.md

@@ -0,0 +1,189 @@
+# Layers (Dependency Injection)
+
+Layers describe how to build services, wire dependencies, and release resources.
+They are lazy values: acquisition happens only when a runtime evaluates
+`provideLayer`, `provideLayerContext`, `buildLayer`, or the `Layer.*` aliases.
+
+Layer 2.0 adds three pieces on top of the original API:
+
+- typed `ServiceTag<A>` keys
+- immutable `LayerContext` service maps
+- scoped builds with memoization and idempotent finalizers
+
+## Typed Contexts
+
+Use tags when a layer graph needs more than one service or when a service should
+be retrieved by capability instead of object shape.
+
+```ts
+import { type Async, Layer, Runtime, asyncSucceed, asyncSync } from "brass-runtime";
+
+const finalizer = (run: () => void): Async<unknown, never, void> =>
+  asyncSync(() => run()) as Async<unknown, never, void>;
+
+type Config = { readonly dbUrl: string };
+type Db = { readonly query: (sql: string) => string };
+
+const Config = Layer.tag<Config>("Config");
+const Db = Layer.tag<Db>("Db");
+
+const ConfigLayer = Layer.value(Config, { dbUrl: "postgres://local" });
+
+const DbLayer = Layer.effect(
+  Db,
+  (ctx) => {
+    const config = ctx.unsafeGet(Config);
+    return asyncSucceed({
+      query: (sql) => `${sql} on ${config.dbUrl}`,
+    });
+  },
+  (db) => finalizer(() => {
+    db.query("close");
+  }),
+);
+
+const AppLayer = Layer.compose(ConfigLayer, DbLayer);
+
+const runtime = Runtime.make({});
+const result = await runtime.toPromise(
+  Layer.provideContext(AppLayer, (ctx) =>
+    asyncSucceed(ctx.unsafeGet(Db).query("select 1")),
+  ),
+);
+```
+
+`LayerContext` is immutable. `add` and `merge` return new contexts, and
+right-hand services win when two contexts contain the same tag.
+
+## Plain Services
+
+The original layer API is still supported for simple service shapes.
+
+```ts
+import { layer, layerFrom, composeLayer, provideLayer, asyncSucceed, asyncSync } from "brass-runtime";
+
+type Config = { readonly dbUrl: string };
+type Db = { readonly query: (sql: string) => string };
+
+const ConfigLayer = layer(() => asyncSucceed<Config>({
+  dbUrl: "postgres://local",
+}));
+
+const DbLayer = layerFrom<Config>()(
+  (config) => asyncSucceed<Db>({
+    query: (sql) => `${sql} on ${config.dbUrl}`,
+  }),
+  () => asyncSync(() => {
+    // close the connection pool here
+  }),
+);
+
+const AppLayer = composeLayer(ConfigLayer, DbLayer);
+
+await runtime.toPromise(
+  provideLayer(AppLayer, (db) => asyncSucceed(db.query("select 1"))),
+);
+```
+
+## Merging
+
+`mergeLayer` combines independent layers. Plain object services are merged with
+object spread; `LayerContext` services are merged by tag.
+
+```ts
+import { Layer, mergeLayer, asyncSucceed } from "brass-runtime";
+
+const Db = Layer.tag<{ readonly query: (sql: string) => string }>("Db");
+const Cache = Layer.tag<{ readonly get: (key: string) => string | undefined }>("Cache");
+
+const DbLayer = Layer.effect(Db, () => asyncSucceed({ query: (sql) => sql }));
+const CacheLayer = Layer.effect(Cache, () => asyncSucceed({ get: () => undefined }));
+
+const InfraLayer = mergeLayer(DbLayer, CacheLayer);
+
+await runtime.toPromise(
+  Layer.provideContext(InfraLayer, (ctx) =>
+    asyncSucceed({
+      db: ctx.unsafeGet(Db),
+      cache: ctx.unsafeGet(Cache),
+    }),
+  ),
+);
+```
+
+## Scoped Builds
+
+Use `buildLayer` or `Layer.build` when a caller wants manual lifecycle control.
+The returned scope memoizes shared layer instances during a build, releases in
+reverse acquisition order, and makes `close()` idempotent.
+
+```ts
+import { Layer, asyncSucceed } from "brass-runtime";
+
+const built = await runtime.toPromise(Layer.build(InfraLayer));
+
+try {
+  await runtime.toPromise(
+    built.use((ctx) => asyncSucceed(ctx.unsafeGet(Db).query("select 1"))),
+  );
+} finally {
+  await runtime.toPromise(built.close());
+}
+```
+
+For advanced graph assembly, create an explicit scope:
+
+```ts
+const scope = Layer.scope();
+
+const db = await runtime.toPromise(scope.get(DbLayer));
+const sameDb = await runtime.toPromise(scope.get(DbLayer));
+
+db === sameDb; // true for the same layer object within the same scope
+
+await runtime.toPromise(scope.close());
+```
+
+After a scope is closed, further `scope.get(...)` calls fail.
+
+## Patterns
+
+### Singleton Service
+
+```ts
+const Logger = Layer.tag<Console>("Logger");
+const LoggerLayer = Layer.value(Logger, console);
+```
+
+### Service With Health Check
+
+```ts
+const DbLayer = Layer.effect(
+  Db,
+  () => asyncSync(() => {
+    const pool = createPool();
+    pool.query("select 1");
+    return pool;
+  }),
+  (pool) => asyncSync(() => {
+    pool.close();
+  }),
+);
+```
+
+### Test Doubles
+
+```ts
+const RealDbLayer = Layer.effect(Db, () => asyncSucceed(createPool()));
+
+const MockDbLayer = Layer.value(Db, {
+  query: (sql: string) => `mock:${sql}`,
+});
+
+const result = await runtime.toPromise(
+  Layer.provideContext(
+    process.env.NODE_ENV === "test" ? MockDbLayer : RealDbLayer,
+    (ctx) => asyncSucceed(ctx.unsafeGet(Db).query("select *")),
+  ),
+);
+```

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)
+```