brass-runtime 1.15.0 → 1.16.1

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

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 *")),
+  ),
+);
+```