brass-runtime 1.16.0 → 1.17.0

package/docs/frameworks/vanilla.md

@@ -0,0 +1,224 @@
+# Vanilla integration
+
+Use this when an app does not have a framework-level DI or lifecycle system.
+The same shape works for plain browser TypeScript, Node HTTP handlers, CLIs,
+and small services.
+
+## Browser
+
+Browser apps should send telemetry to a same-origin proxy. Do not ship Grafana
+Cloud or collector credentials to the client.
+
+```ts
+// brass.browser.ts
+import { Runtime } from "brass-runtime/core";
+import {
+  defineHttpPolicyPresets,
+  makeDefaultHttpClient,
+} from "brass-runtime/http";
+import {
+  makeObservability,
+  makeOtlpOptions,
+  withHttpObservability,
+} from "brass-runtime/observability";
+
+const policyPresets = defineHttpPolicyPresets({
+  readModel: {
+    lane: "read-model",
+    priority: 3,
+    retry: { maxRetries: 2, baseDelayMs: 100, maxDelayMs: 1_000 },
+  },
+  command: {
+    lane: "command",
+    priority: 1,
+    retry: false,
+  },
+});
+
+export const brass = (() => {
+  const observability = makeObservability({
+    serviceName: "shop-web",
+    resource: { "deployment.environment": "browser" },
+    logs: false,
+    sampling: { ratio: 0.1, respectRemoteSampled: true, forceSampleOnError: true },
+    redaction: {},
+    cardinality: { maxValuesPerLabel: 100 },
+    otlp: makeOtlpOptions({
+      endpoint: "/api/otel",
+      timeoutMs: 10_000,
+      retry: { attempts: 2, initialDelayMs: 100, maxDelayMs: 1_000 },
+      pipeline: { maxQueueSize: 2_000, batchSize: 128, dropPolicy: "drop-oldest" },
+    }),
+    flushIntervalMs: 15_000,
+    autoStart: true,
+  });
+
+  const runtime = new Runtime({
+    env: observability.env,
+    hooks: observability.hooks,
+  });
+
+  const http = makeDefaultHttpClient({
+    baseUrl: "/api",
+    preset: "balanced",
+    timeoutMs: 5_000,
+    policyPresets,
+    middleware: [withHttpObservability(observability)],
+  });
+
+  return {
+    observability,
+    runtime,
+    http,
+    shutdown: async () => {
+      await http.shutdown();
+      await observability.shutdown();
+    },
+  };
+})();
+```
+
+Use it from ordinary browser code:
+
+```ts
+type User = {
+  readonly id: string;
+  readonly name: string;
+};
+
+export async function loadCurrentUser(): Promise<User> {
+  const response = await brass.runtime.toPromise(
+    brass.http.getJson<User>("/users/me", {
+      policy: "readModel",
+      timeoutMs: 2_000,
+    }),
+  );
+
+  return response.body;
+}
+
+window.addEventListener("pagehide", () => {
+  void brass.shutdown();
+});
+```
+
+## Node
+
+On the server, Brass can send directly to a collector because credentials stay
+inside the trusted process.
+
+```ts
+// brass.node.ts
+import { Runtime } from "brass-runtime/core";
+import {
+  defineHttpPolicyPresets,
+  makeDefaultHttpClient,
+} from "brass-runtime/http";
+import {
+  makeObservability,
+  makeOtlpOptions,
+  withHttpObservability,
+} from "brass-runtime/observability";
+
+const policyPresets = defineHttpPolicyPresets({
+  readModel: {
+    lane: "read-model",
+    priority: 3,
+    retry: { maxRetries: 2, baseDelayMs: 100, maxDelayMs: 1_000 },
+  },
+  command: {
+    lane: "command",
+    priority: 1,
+    retry: false,
+  },
+});
+
+export const brass = (() => {
+  const observability = makeObservability({
+    serviceName: process.env.OTEL_SERVICE_NAME ?? "vanilla-node",
+    serviceVersion: process.env.OTEL_SERVICE_VERSION,
+    resource: {
+      "deployment.environment": process.env.NODE_ENV ?? "development",
+    },
+    logs: { minLevel: "info" },
+    sampling: { ratio: 0.25, respectRemoteSampled: true, forceSampleOnError: true },
+    redaction: {},
+    cardinality: { maxValuesPerLabel: 100 },
+    otlp: makeOtlpOptions({
+      endpoint: process.env.GRAFANA_OTLP_ENDPOINT ?? "http://grafana-alloy:4318",
+      headers: process.env.GRAFANA_OTLP_AUTHORIZATION
+        ? { Authorization: process.env.GRAFANA_OTLP_AUTHORIZATION }
+        : undefined,
+      timeoutMs: 10_000,
+      retry: { attempts: 3, initialDelayMs: 100, maxDelayMs: 2_000 },
+      pipeline: {
+        maxQueueSize: 10_000,
+        batchSize: 512,
+        dropPolicy: "drop-oldest",
+        shutdownTimeoutMs: 10_000,
+      },
+    }),
+    flushIntervalMs: 10_000,
+    autoStart: true,
+  });
+
+  const runtime = new Runtime({
+    env: observability.env,
+    hooks: observability.hooks,
+  });
+
+  const http = makeDefaultHttpClient({
+    baseUrl: process.env.API_BASE_URL ?? "https://api.internal",
+    preset: "production",
+    timeoutMs: 5_000,
+    policyPresets,
+    middleware: [withHttpObservability(observability)],
+  });
+
+  return {
+    observability,
+    runtime,
+    http,
+    shutdown: async () => {
+      await http.shutdown();
+      await observability.shutdown();
+    },
+  };
+})();
+```
+
+Use the Node request adapter when you receive `IncomingMessage`-like requests:
+
+```ts
+import { createServer } from "node:http";
+import {
+  makeNodeRequestObservabilityContext,
+} from "brass-runtime/observability";
+import { brass } from "./brass.node";
+
+const server = createServer(async (req, res) => {
+  const ctx = makeNodeRequestObservabilityContext(brass.observability, req, {
+    route: req.url?.startsWith("/users/") ? "/users/:id" : req.url,
+  });
+
+  const response = await ctx.run(
+    ctx.withRequestSpan(
+      brass.http.getJson("/users/42", {
+        policy: "readModel",
+        timeoutMs: 2_000,
+      }),
+    ),
+  );
+
+  res.setHeader("content-type", "application/json");
+  res.end(JSON.stringify(response.body));
+});
+
+process.once("SIGTERM", async () => {
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  await brass.shutdown();
+});
+
+server.listen(process.env.PORT ?? 3000);
+```
+

package/docs/getting-started.md

@@ -0,0 +1,159 @@
+# 🧵 Brass Runtime — Getting Started
+
+`brass-runtime` es un runtime funcional y cooperativo para JavaScript/TypeScript inspirado en modelos como **ZIO**, **Effect** y **structured concurrency**.
+
+Su objetivo es permitir escribir lógica **pura, cancelable y composable**, sin perder la posibilidad de ejecutarla fácilmente desde código imperativo.
+
+---
+
+## 📦 Instalación
+
+```bash
+npm install brass-runtime
+```
+
+
+
+## 🧠 Conceptos clave
+
+### `Async<R, E, A>`
+Un `Async` representa un **cálculo perezoso** que:
+
+- puede requerir un entorno (`R`)
+- puede fallar con un error (`E`)
+- puede producir un valor (`A`)
+- **no se ejecuta automáticamente**
+
+Nada corre hasta que vos lo pedís explícitamente.
+
+---
+
+## 🚀 Ejemplo rápido
+
+```ts
+import { makeHttp } from "brass-runtime/http";
+import { toPromise } from "brass-runtime";
+
+const http = makeHttp({
+  baseUrl: "https://jsonplaceholder.typicode.com",
+});
+
+async function main() {
+  const effect = http.get("/posts/1");
+
+  const result = await toPromise(effect, {});
+  console.log(result.status);
+  console.log(result.bodyText);
+}
+
+main();
+```
+
+---
+
+## 🧩 ¿Por qué `toPromise`?
+
+`toPromise` es el **puente entre el mundo funcional y el mundo imperativo**.
+
+- `Async` es perezoso → no ejecuta nada por sí solo
+- `toPromise` ejecuta el efecto en el runtime
+- devuelve una `Promise` estándar
+
+```ts
+const result = await toPromise(effect, env);
+```
+
+Internamente:
+- crea un *fiber*
+- lo ejecuta en el scheduler
+- espera el resultado
+- lo transforma en `Promise`
+
+---
+
+## ⚙️ Estructura mental del runtime
+
+```
+Async  --->  Fiber  --->  Scheduler  --->  Resultado
+   |            |            |
+   |            |            +-- controla ejecución
+   |            +-- maneja estado y cancelación
+   +-- describe el cómputo
+```
+
+Nada se ejecuta hasta que:
+```ts
+toPromise(effect, env)
+```
+
+---
+
+## 🌐 Ejemplo HTTP completo
+
+```ts
+import { makeHttp } from "brass-runtime/http";
+import { toPromise } from "brass-runtime";
+
+const http = makeHttp({
+  baseUrl: "https://jsonplaceholder.typicode.com",
+});
+
+async function main() {
+  const effect = http.get("/posts/1");
+
+  const result = await toPromise(effect, {});
+  console.log("Status:", result.status);
+  console.log("Body:", result.bodyText);
+}
+
+main();
+```
+
+---
+
+## 🧩 ¿Por qué no usar `fetch` directamente?
+
+Porque `Async` te da:
+
+- Cancelación estructurada
+- Composición funcional
+- Control explícito de ejecución
+- Testing determinístico
+- Integración con fibras y scopes
+
+---
+
+## 🧠 Regla de oro
+
+> **Los efectos no se ejecutan solos.**  
+> Se describen con `Async`, y se ejecutan solo con `toPromise` (o un runner equivalente).
+
+---
+
+## 🧪 Testing
+
+```ts
+import { toPromise } from "brass-runtime";
+
+test("fetch works", async () => {
+  const result = await toPromise(http.get("/posts/1"), {});
+  expect(result.status).toBe(200);
+});
+```
+
+---
+
+## 🧭 Próximos pasos
+
+- Composición (`map`, `flatMap`)
+- Cancelación con `AbortSignal`
+- `race`, `timeout`, `retry`
+- Integración con React / Bun / Workers
+
+
+---
+
+## Next
+
+- Learn how interruption and `Scope` work: [Cancellation & interruption](./cancellation.md)
+- Enable logging/tracing with hooks: [Observability](./observability.md)

package/docs/guides/README.md

@@ -0,0 +1,40 @@
+# brass-runtime Guides
+
+Guides for each feature of brass-runtime, organized by topic.
+
+## Core
+
+- [Getting Started](./getting-started.md) — Install, first effect, basic patterns
+- [Effects & Fibers](./effects-and-fibers.md) — The effect system, fibers, and concurrency
+- [Error Handling](./error-handling.md) — Typed errors, catchTag, recovery patterns
+- [Resource Management](./resource-management.md) — bracket, ensuring, managed resources
+
+## Concurrency
+
+- [Streams & Pipelines](./streams.md) — ZStream, operators, fusion
+- [Queue & Hub](./queue-and-hub.md) — Bounded queues, pub/sub
+- [Semaphore & Rate Limiting](./semaphore.md) — Concurrency control
+- [Circuit Breaker](./circuit-breaker.md) — Failure protection
+- [Supervisors](./supervisors.md) — Restart and escalation policies for child fibers
+
+## Resilience
+
+- [Retry & Backoff](./retry.md) — retry, retryWithBackoff, Schedule
+- [Timeout](./timeout.md) — Effect timeouts with cancellation
+
+## Infrastructure
+
+- [Layers (DI)](./layers.md) — Dependency injection with lifecycle
+- [Ref (Shared State)](./ref.md) — Mutable state across fibers
+- [Scheduler](./scheduler.md) — Task scheduling, lanes, budgets
+- [Worker Pool](./worker-pool.md) — CPU-intensive offloading
+
+## Observability
+
+- [Tracing](./tracing.md) — OpenTelemetry-compatible spans
+- [Metrics](./metrics.md) — Counters, gauges, histograms
+- [Graceful Shutdown](./shutdown.md) — Clean process termination
+
+## Testing
+
+- [Testing Utilities](./testing.md) — TestRuntime, assertions, helpers

package/docs/guides/circuit-breaker.md

@@ -0,0 +1,89 @@
+# Circuit Breaker
+
+Protect against cascading failures when downstream services are unhealthy.
+
+## How it works
+
+```
+CLOSED → (failures exceed threshold) → OPEN → (timeout expires) → HALF-OPEN
+  ↑                                                                    |
+  └──────────── (probe succeeds) ──────────────────────────────────────┘
+                                        (probe fails) → back to OPEN
+```
+
+## Basic usage
+
+```ts
+import { makeCircuitBreaker } from "brass-runtime";
+
+const breaker = makeCircuitBreaker({
+  failureThreshold: 5,     // open after 5 consecutive failures
+  resetTimeoutMs: 30_000,  // try again after 30 seconds
+});
+
+// Protect any effect
+const result = await run(breaker.protect(callPaymentService()));
+```
+
+## Configuration
+
+```ts
+const breaker = makeCircuitBreaker({
+  failureThreshold: 3,      // trips after 3 failures
+  resetTimeoutMs: 10_000,   // 10s cooldown
+  successThreshold: 2,      // need 2 successes in half-open to close
+  
+  // Only count certain errors as failures
+  isFailure: (error) => {
+    if (error._tag === "NotFound") return false;  // 404 is not a failure
+    if (error._tag === "BadRequest") return false; // client error, not service
+    return true; // everything else counts
+  },
+  
+  // Observe state transitions
+  onStateChange: (from, to) => {
+    metrics.counter("circuit_breaker_transitions", { from, to }).increment();
+  },
+});
+```
+
+## With retry
+
+```ts
+import { makeCircuitBreaker, retryWithBackoff } from "brass-runtime";
+
+const breaker = makeCircuitBreaker({ failureThreshold: 5 });
+
+// Retry, but stop if circuit opens
+const resilient = retryWithBackoff(
+  breaker.protect(callService()),
+  {
+    maxRetries: 3,
+    shouldRetry: (error) => {
+      // Don't retry if circuit is open — it'll just fail fast anyway
+      if (error._tag === "CircuitBreakerOpen") return false;
+      return true;
+    },
+  }
+);
+```
+
+## Monitoring
+
+```ts
+const stats = breaker.stats();
+// {
+//   state: "closed",
+//   failures: 2,
+//   successes: 0,
+//   totalRequests: 150,
+//   totalFailures: 5,
+//   totalSuccesses: 143,
+//   totalRejected: 2,
+//   lastFailureTime: 1699000000000,
+//   lastSuccessTime: 1699000001000,
+// }
+
+// Manual reset (e.g., after deploying a fix)
+breaker.reset();
+```

package/docs/guides/error-handling.md

@@ -0,0 +1,91 @@
+# Error Handling
+
+brass-runtime provides typed error handling with discriminated unions, enabling exhaustive pattern matching and type-safe recovery.
+
+## Tagged Errors
+
+Define errors as discriminated unions:
+
+```ts
+type AppError =
+  | { _tag: "NetworkError"; url: string; status: number }
+  | { _tag: "TimeoutError"; ms: number }
+  | { _tag: "NotFound"; id: string };
+```
+
+## catchTag — Handle specific errors
+
+```ts
+import { catchTag } from "brass-runtime";
+
+const result = catchTag(
+  fetchUser(id),          // Async<R, AppError, User>
+  "NotFound",             // catch only NotFound
+  (e) => asyncSucceed(defaultUser)  // e is narrowed to { _tag: "NotFound"; id: string }
+);
+// Result type: Async<R, NetworkError | TimeoutError, User>
+// NotFound is removed from the error type!
+```
+
+## catchTags — Handle multiple errors at once
+
+```ts
+import { catchTags } from "brass-runtime";
+
+const result = catchTags(fetchUser(id), {
+  NotFound: (e) => asyncSucceed(defaultUser),
+  TimeoutError: (e) => retryWithBackoff(fetchUser(id)),
+});
+// Only NetworkError remains in the error channel
+```
+
+## tagError — Wrap untyped errors
+
+```ts
+import { tagError } from "brass-runtime";
+
+// Wrap a fetch error with a tag
+const typed = tagError(
+  rawFetch(url),
+  "NetworkError",
+  (e) => ({ url, message: String(e) })
+);
+// Error type: { _tag: "NetworkError"; url: string; message: string }
+```
+
+## orElse — Fallback on any error
+
+```ts
+import { orElse } from "brass-runtime";
+
+const result = orElse(
+  primaryDataSource(),
+  (error) => fallbackDataSource()
+);
+```
+
+## mapError — Transform errors
+
+```ts
+import { mapError } from "brass-runtime";
+
+const wrapped = mapError(
+  effect,
+  (e) => ({ _tag: "ServiceError" as const, cause: e })
+);
+```
+
+## Combining with retry
+
+```ts
+import { catchTag, retryWithBackoff } from "brass-runtime";
+
+const resilient = catchTag(
+  retryWithBackoff(fetchData(), {
+    maxRetries: 3,
+    shouldRetry: (e) => e._tag === "NetworkError",
+  }),
+  "TimeoutError",
+  () => asyncSucceed(cachedData)
+);
+```

package/docs/guides/getting-started.md

@@ -0,0 +1,107 @@
+# Getting Started
+
+## Install
+
+```bash
+npm install brass-runtime
+```
+
+## Your first effect
+
+```ts
+import { Runtime, asyncSucceed, asyncFlatMap, asyncFail } from "brass-runtime";
+
+// Create a runtime
+const runtime = Runtime.make({});
+
+// Effects are values — they describe what to do, not how
+const greet = asyncSucceed("Hello, brass!");
+
+// Run the effect
+const result = await runtime.toPromise(greet);
+console.log(result); // "Hello, brass!"
+```
+
+## Composing effects
+
+```ts
+import { asyncSucceed, asyncFlatMap, asyncFail, asyncFold } from "brass-runtime";
+
+// Chain effects with flatMap
+const program = asyncFlatMap(
+  asyncSucceed(21),
+  (n) => asyncSucceed(n * 2)
+);
+// Result: 42
+
+// Handle errors
+const safe = asyncFold(
+  asyncFail("oops"),
+  (error) => asyncSucceed(`recovered from: ${error}`),
+  (value) => asyncSucceed(value)
+);
+```
+
+## Async operations
+
+```ts
+import { async } from "brass-runtime";
+
+// Wrap any callback-based API
+const fetchData = async((_env, cb) => {
+  const controller = new AbortController();
+  
+  fetch("https://api.example.com/data", { signal: controller.signal })
+    .then(res => res.json())
+    .then(data => cb({ _tag: "Success", value: data }))
+    .catch(err => cb({ _tag: "Failure", cause: { _tag: "Fail", error: err } }));
+
+  // Return a canceler
+  return () => controller.abort();
+});
+```
+
+## Concurrency with fibers
+
+```ts
+import { Runtime, asyncSucceed, asyncFlatMap } from "brass-runtime";
+
+const runtime = Runtime.make({});
+
+// Fork runs an effect in a new fiber (lightweight thread)
+const fiber = runtime.fork(longRunningEffect);
+
+// Join waits for the fiber to complete
+fiber.join((exit) => {
+  if (exit._tag === "Success") console.log(exit.value);
+  else console.log("Failed:", exit.cause);
+});
+
+// Interrupt cancels a fiber
+fiber.interrupt();
+```
+
+## Streams
+
+```ts
+import { fromArray, collectStream, via, mapP, filterP, andThen } from "brass-runtime";
+
+// Create a stream from an array
+const numbers = fromArray([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+
+// Build a pipeline (auto-fused for performance)
+const pipeline = andThen(
+  mapP((x: number) => x * 2),
+  filterP((x: number) => x > 10)
+);
+
+// Apply and collect
+const result = await runtime.toPromise(collectStream(via(numbers, pipeline)));
+// [12, 14, 16, 18, 20]
+```
+
+## What's next?
+
+- [Effects & Fibers](./effects-and-fibers.md) — Deep dive into the effect system
+- [Error Handling](./error-handling.md) — Typed errors and recovery
+- [Streams & Pipelines](./streams.md) — Stream processing with fusion