brass-runtime 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Augusto Vivaldelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,361 @@
+# 🛠️ brass-ts — Mini runtime funcional al estilo ZIO en TypeScript
+
+**brass-ts** es un runtime funcional inspirado en **ZIO 2**, escrito en **TypeScript vanilla** y **sin usar Promises ni async/await** como primitiva principal de modelado.
+
+El objetivo del proyecto es explorar cómo construir, desde cero, un sistema de:
+
+- **Efectos puros** (sincrónicos y asincrónicos)
+- **Concurrencia estructurada**
+- **Fibras** (fibers)
+- **Scheduler cooperativo**
+- **Limpieza segura de recursos (acquire / release)**
+- **Scopes estructurados**
+- **Finalizers (a nivel scope y fibra)**
+- **Streams estructurados (ZStream-like) con backpressure**
+
+Todo con un diseño **determinístico**, **pure FP**, y sin depender de `Promise` ni `async/await` para la semántica del modelo.
+
+---
+
+## ✨ Características principales
+
+### 1. `Effect` sincrónico (núcleo funcional)
+
+En `brass-ts`, un efecto puro se modela como:
+
+```ts
+type Exit<E, A> =
+  | { _tag: "Success"; value: A }
+  | { _tag: "Failure"; error: E };
+
+type Effect<R, E, A> = (env: R) => Exit<E, A>;
+```
+
+Con combinadores típicos de un sistema de efectos:
+
+- `map`
+- `flatMap`
+- `mapError`
+- `catchAll`
+- `zip`
+- `foreach`
+- `collectAll`
+- `as`, `asUnit`, `tap`
+
+Este núcleo no usa `Promise` ni `async/await`. Es **100% sincrónico y determinista**.
+
+---
+
+### 2. `Async` — efectos asincrónicos sin Promises
+
+Para modelar operaciones asincrónicas, `brass-ts` define un tipo de datos algebraico:
+
+```ts
+type Async<R, E, A> =
+  | { _tag: "Succeed"; value: A }
+  | { _tag: "Fail"; error: E }
+  | { _tag: "Sync"; thunk: (env: R) => A }
+  | { _tag: "Async"; register: (env: R, cb: (exit: Exit<E, A>) => void) => void }
+  | { _tag: "FlatMap"; first: Async<R, E, any>; andThen: (a: any) => Async<R, E, A> };
+```
+
+Con constructores como:
+
+- `asyncSucceed`
+- `asyncFail`
+- `asyncSync`
+- `asyncTotal`
+- `async` (primitive para integrar APIs callback-based como `setTimeout`, `fs`, etc.)
+- `asyncMap`
+- `asyncFlatMap`
+
+Y un runtime que ejecuta `Async` mediante un **intérprete explícito**, sin usar `Promise`.
+
+---
+
+### 3. Scheduler cooperativo
+
+El sistema usa un **scheduler cooperativo** con una cola de tareas:
+
+```ts
+class Scheduler {
+  schedule(task: () => void): void;
+}
+```
+
+El `Scheduler` controla:
+
+- el orden en que se ejecutan los pasos de cada fibra,
+- la equidad (fairness),
+- posibles políticas de prioridad.
+
+Esto permite testear y razonar sobre la concurrencia sin depender del azar del event loop.
+
+---
+
+### 4. Fibers (fibras)
+
+Cada programa `Async` corre dentro de una **fibra**:
+
+```ts
+type Fiber<E, A> = {
+  id: number;
+  status: () => "Running" | "Done" | "Interrupted";
+  join: (cb: (exit: Exit<E | Interrupted, A>) => void) => void;
+  interrupt: () => void;
+  addFinalizer: (f: (exit: Exit<E | Interrupted, A>) => Async<any, any, any>) => void;
+};
+```
+
+Las fibras proveen:
+
+- concurrencia liviana (miles de fibers),
+- cancelación cooperativa (`interrupt`),
+- `join` para esperar resultados,
+- **finalizers de fibra** (LIFO) que se ejecutan siempre: éxito, fallo o interrupción.
+
+---
+
+### 5. Scopes — Concurrencia estructurada
+
+Un **Scope** modela una unidad de concurrencia estructurada:
+
+```ts
+class Scope<R> {
+  fork<E, A>(eff: Async<R, E, A>, env: R): Fiber<E, A>;
+  subScope(): Scope<R>;
+  addFinalizer(f: (exit: Exit<any, any>) => Async<R, any, any>): void;
+  close(exit?: Exit<any, any>): void;
+  isClosed(): boolean;
+}
+```
+
+Un scope:
+
+- rastrea las fibras hijas,
+- rastrea sub-scopes,
+- mantiene una pila de finalizers (LIFO),
+- al cerrarse:
+    - interrumpe fibras hijas,
+    - cierra sub-scopes,
+    - ejecuta finalizers registrados.
+
+Esto da **concurrencia estructurada** al estilo ZIO:
+si algo vive en un `Scope`, se limpia cuando el scope termina.
+
+---
+
+### 6. Acquire / Release — Resource Safety
+
+Al estilo `ZIO.acquireRelease`, `brass-ts` implementa:
+
+```ts
+acquireRelease(
+  acquire: Async<R, E, A>,
+  release: (res: A, exit: Exit<any, any>) => Async<R, any, any>,
+  scope: Scope<R>
+): Async<R, E, A>;
+```
+
+Semántica:
+
+- `acquire` corre dentro del scope,
+- si tiene éxito, registra un finalizer que hace `release(res, exitFinalDelScope)`,
+- el finalizer se ejecuta:
+    - si el scope cierra con éxito,
+    - si hay error,
+    - si hay interrupción/cancelación.
+
+**Garantiza cleanup de recursos** (archivos, sockets, conexiones, etc.) de forma estructurada.
+
+---
+
+### 7. Structured Concurrency: `race`, `zipPar`, `collectAllPar`
+
+Sobre fibras, scopes y `Async`, se construyen combinadores de **concurrencia estructurada**:
+
+#### `race(left, right, scope)`
+
+- ejecuta `left` y `right` en paralelo dentro de un scope,
+- el primero que termina “gana”,
+- la fibra perdedora se interrumpe,
+- se propaga el resultado del ganador.
+
+#### `zipPar(left, right, scope)`
+
+- ejecuta ambos efectos en paralelo,
+- si alguno falla → se cancela el otro,
+- si ambos tienen éxito → devuelve `[A, B]`.
+
+#### `collectAllPar(effects, scope)`
+
+- ejecuta una lista de efectos en paralelo,
+- si alguno falla → cancela el resto,
+- si todos completan → devuelve la lista de resultados.
+
+Esto replica la semántica de **ZIO 2 structured concurrency**.
+
+---
+
+### 8. ZStream-like — Streams estructurados con backpressure
+
+`brass-ts` incluye una base de **streams estructurados** inspirados en `ZStream`:
+
+```ts
+type Pull<R, E, A> = Async<R, Option<E>, A>;
+
+type ZStream<R, E, A> = {
+  open: (scope: Scope<R>) => Pull<R, E, A>;
+};
+```
+
+Donde:
+
+- `Success(a)` → el stream produjo un valor,
+- `Failure(Some(e))` → error,
+- `Failure(None)` → fin del stream.
+
+Constructores básicos:
+
+- `empty`
+- `streamOf`
+- `fromArray`
+
+Transformaciones:
+
+- `map`
+- `filter`
+- `fromResource` (integra acquire/release con streams)
+
+Consumo:
+
+```ts
+runCollect(stream, env): Async<R, E, A[]>;
+```
+
+El consumo se hace respetando backpressure: cada `pull` produce como mucho un valor,
+y el scope del stream garantiza que todos los recursos/finalizers se limpien al terminar
+(el stream o el consumidor).
+
+---
+
+## 📁 Estructura sugerida del proyecto
+
+Una posible organización de archivos para tu repo de **brass-ts**:
+
+```bash
+src/
+  fibers/    
+  scheduler/    
+  stream/
+  types/
+    
+
+examples/
+  demo.ts
+  fiberFinalizer.ts
+  resourceExample.ts
+```
+
+---
+
+## 🚀 Ejemplo rápido
+
+```ts
+import {
+  asyncTotal,
+  asyncFlatMap,
+  asyncSucceed,
+} from "./asyncEffect";
+import { sleep } from "./std";
+import { Scope } from "./scope";
+import { race } from "./concurrency";
+
+type Env = {};
+
+function task(name: string, ms: number) {
+  return asyncFlatMap(sleep(ms), () =>
+    asyncSucceed(`Terminé ${name}`)
+  );
+}
+
+function main() {
+  const env: Env = {};
+  const scope = new Scope<Env>();
+
+  const fast = task("rápida", 200);
+  const slow = task("lenta", 1000);
+
+  race(fast, slow, scope)(env, exit => {
+    console.log("Resultado race:", exit);
+    scope.close(exit);
+  });
+}
+
+main();
+```
+
+---
+
+## 🧪 Objetivos del proyecto
+
+- Explorar el diseño de runtimes funcionales modernos (tipo ZIO) en TypeScript.
+- Entender y practicar:
+    - Efectos tipados (`R`, `E`, `A`),
+    - Concurrencia estructurada,
+    - Fibras,
+    - Scopes y finalizers,
+    - Streams con recursos seguros y backpressure.
+- Servir como base educativa y potencialmente como **runtime experimental**
+  para proyectos de ejemplo, demos y pruebas de conceptos FP en TS.
+
+---
+
+## 📝 Estado actual
+
+- [x] Núcleo de efectos sincrónicos (`Effect`)
+- [x] Núcleo de efectos asincrónicos (`Async`) sin Promises
+- [x] Scheduler cooperativo
+- [x] Fibers con finalizers
+- [x] Scopes con finalizers (LIFO)
+- [x] Acquire / Release
+- [x] Concurrencia estructurada (`race`, `zipPar`, `collectAllPar`)
+- [x] Streams básicos (`ZStream`-like) con backpressure y scopes
+- [ ] Buffering en streams
+- [ ] Merge / zipPar de streams
+- [ ] Hubs / Broadcast / Multicast
+- [ ] Pipelines (tipo `ZPipeline`)
+- [ ] Channels / Sinks avanzado
+
+---
+
+## 📜 Licencia
+
+Este proyecto está pensado como laboratorio de ideas FP.
+Se recomienda usar licencia MIT:
+
+```text
+MIT License
+Copyright (c) 2025
+```
+
+---
+
+## 🤝 Contribuciones
+
+Ideas de mejora, PRs y discusiones de diseño son más que bienvenidas.
+
+Algunas direcciones interesantes para futuro:
+
+- Integrar fs / net de Node de forma segura vía `Async`,
+- Agregar tests deterministas de concurrencia,
+- Implementar Hubs y Queues al estilo ZIO,
+- Extender ZStream con merges, buffers y pipelines,
+- Explorar integración con TypeScript decorators para “endpoints” basados en efectos.
+
+---
+
+Hecho con ❤️ en TypeScript, para aprender y jugar con runtimes funcionales.
+
+**Nombre del proyecto:** `brass-ts`  
+**Objetivo:** construir un mini ZIO-like runtime en el ecosistema JS/TS, pero manteniendo el control total sobre la semántica de los efectos desde el código de usuario.

package/dist/examples/demo.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = sleep;
+const effect_1 = require("../types/effect");
+const stream_1 = require("../stream/stream");
+const asyncEffect_1 = require("../types/asyncEffect");
+const fiber_1 = require("../fibers/fiber");
+const withScope_1 = require("../scheduler/withScope");
+function main() {
+    const env = {};
+    const fiberA = (0, fiber_1.fork)(task("A", 1000), env);
+    const fiberB = (0, fiber_1.fork)(task("B", 500), env);
+    fiberA.join((exit) => {
+        console.log("Fiber A:", exit);
+    });
+    fiberB.join((exit) => {
+        console.log("Fiber B:", exit);
+    });
+    const eff1 = (0, effect_1.succeed)(10);
+    const eff2 = (0, effect_1.succeed)(20);
+    const sumEff = (0, effect_1.zip)(eff1, eff2);
+    const sumExit = sumEff({});
+    console.log("sumExit:", sumExit);
+    const numsEff = (0, effect_1.foreach)([1, 2, 3], (n) => (0, effect_1.succeed)(n * 2));
+    console.log("foreach:", numsEff({}));
+    const s = (0, stream_1.fromArray)([1, 2, 3, 4]);
+    const sMapped = (0, stream_1.mapStream)(s, (n) => n * 10);
+    const collected = (0, stream_1.collectStream)(sMapped, env);
+    console.log("Stream mapeado:", collected);
+    (0, withScope_1.withScope)(scope => {
+        const f1 = scope.fork(task("A", 1000), env);
+        const f2 = scope.fork(task("B", 1500), env);
+        const f3 = scope.fork(task("C", 2000), env);
+        console.log("Tareas lanzadas dentro del scope");
+        // Si quiero, cancelo todo luego de 1.2s
+        setTimeout(() => {
+            console.log("CANCELANDO TODO EL SCOPE...");
+            scope.close();
+        }, 1200);
+        f1.join(console.log);
+        f2.join(console.log);
+        f3.join(console.log);
+    });
+}
+function sleep(ms) {
+    return (0, asyncEffect_1.async)((_, cb) => {
+        setTimeout(() => {
+            cb({ _tag: "Success", value: undefined });
+        }, ms);
+    });
+}
+function task(name, ms) {
+    return (0, asyncEffect_1.asyncFlatMap)(sleep(ms), () => (0, asyncEffect_1.asyncSucceed)(`Terminé ${name} después de ${ms}ms`));
+}
+main();

package/dist/examples/fiberFinalizer.js

@@ -0,0 +1,23 @@
+"use strict";
+// fiberFinalizer.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+const asyncEffect_1 = require("../types/asyncEffect");
+const fiber_1 = require("../fibers/fiber");
+const demo_1 = require("./demo");
+function main() {
+    const env = {};
+    const eff = (0, asyncEffect_1.asyncFlatMap)((0, asyncEffect_1.asyncTotal)(() => console.log("Start")), () => (0, asyncEffect_1.asyncFlatMap)((0, demo_1.sleep)(1000), () => (0, asyncEffect_1.asyncTotal)(() => "done")));
+    const fiber = (0, fiber_1.fork)(eff, env);
+    fiber.addFinalizer(exit => (0, asyncEffect_1.asyncTotal)(() => {
+        console.log("RUNNING FINALIZER → exit =", exit._tag);
+    }));
+    // cancelamos antes de terminar para ver que el finalizer corre
+    setTimeout(() => {
+        console.log("Interrupting fiber...");
+        fiber.interrupt();
+    }, 500);
+    fiber.join((exit) => {
+        console.log("Fiber completed:", exit);
+    });
+}
+main();

package/dist/examples/resourceExample.js

@@ -0,0 +1,41 @@
+"use strict";
+// src/resourceExample.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+const acquireRelease_1 = require("../scheduler/acquireRelease");
+const asyncEffect_1 = require("../types/asyncEffect");
+const withScope_1 = require("../scheduler/withScope");
+function openFile(name) {
+    console.log("OPEN FILE:", name);
+    return {
+        name,
+        closed: false,
+        close() {
+            console.log("CLOSE FILE:", name);
+            this.closed = true;
+        }
+    };
+}
+function main() {
+    (0, withScope_1.withScope)(scope => {
+        const env = {};
+        const program = (0, acquireRelease_1.acquireRelease)((0, asyncEffect_1.asyncTotal)(() => openFile("data.txt")), (file, exit) => (0, asyncEffect_1.asyncTotal)(() => {
+            console.log("Finalizer running due to:", exit._tag);
+            file.close();
+        }), scope);
+        // use the resource
+        scope.fork((0, asyncEffect_1.asyncFlatMap)(program, (fh) => (0, asyncEffect_1.asyncFlatMap)(sleep(1000), () => (0, asyncEffect_1.asyncSucceed)(`Using ${fh.name}`))), env);
+        // cancel whole scope early (to force cleanup)
+        setTimeout(() => {
+            console.log("Cancelling scope manually...");
+            scope.close();
+        }, 500);
+    });
+}
+function sleep(ms) {
+    return (0, asyncEffect_1.async)((_, cb) => {
+        setTimeout(() => {
+            cb({ _tag: "Success", value: undefined });
+        }, ms);
+    });
+}
+main();

package/dist/fibers/fiber.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fork = fork;
+exports.unsafeRunAsync = unsafeRunAsync;
+const scheduler_1 = require("../scheduler/scheduler");
+let nextId = 1;
+class RuntimeFiber {
+    constructor(effect, env, scheduler) {
+        this.scheduler = scheduler;
+        this.statusValue = "Running";
+        this.interrupted = false;
+        this.result = null;
+        this.joiners = [];
+        this.stack = [];
+        this.fiberFinalizers = [];
+        this.id = nextId++;
+        this.current = effect;
+        this.env = env;
+    }
+    addFinalizer(f) {
+        this.fiberFinalizers.push(f);
+    }
+    status() {
+        return this.statusValue;
+    }
+    join(cb) {
+        if (this.result != null) {
+            cb(this.result);
+        }
+        else {
+            this.joiners.push(cb);
+        }
+    }
+    interrupt() {
+        this.interrupted = true;
+        // cancelación cooperativa: el código async puede chequear flags externos
+    }
+    runFiberFinalizers(exit) {
+        while (this.fiberFinalizers.length > 0) {
+            const fin = this.fiberFinalizers.pop();
+            fin(exit); // fire-and-forget (igual que ZIO)
+        }
+    }
+    /** Programa un paso de la fibra en el scheduler */
+    schedule() {
+        this.scheduler.schedule(() => this.step());
+    }
+    notify(exit) {
+        if (this.result != null)
+            return;
+        // ejecutar finalizers de fibra
+        this.runFiberFinalizers(exit);
+        // marcar estado final
+        this.statusValue = this.interrupted ? "Interrupted" : "Done";
+        this.result = exit;
+        // notificar joiners
+        for (const j of this.joiners)
+            j(exit);
+        this.joiners.length = 0;
+    }
+    onSuccess(value) {
+        const cont = this.stack.pop();
+        if (!cont) {
+            // terminamos con éxito
+            this.notify({ _tag: "Success", value });
+            return;
+        }
+        this.current = cont(value);
+        this.schedule(); // siguiente paso
+    }
+    onFailure(error) {
+        this.notify({ _tag: "Failure", error });
+    }
+    /** Un *paso* de evaluación de la fibra */
+    step() {
+        if (this.result != null)
+            return; // ya terminó
+        const current = this.current;
+        switch (current._tag) {
+            case "Succeed":
+                this.onSuccess(current.value);
+                return;
+            case "Fail":
+                this.onFailure(current.error);
+                return;
+            case "Sync":
+                try {
+                    const v = current.thunk(this.env);
+                    this.onSuccess(v);
+                }
+                catch (e) {
+                    this.onFailure(e);
+                }
+                return;
+            case "FlatMap":
+                this.stack.push(current.andThen);
+                this.current = current.first;
+                this.schedule(); // reducimos el first en otro paso
+                return;
+            case "Async":
+                current.register(this.env, (exit) => {
+                    if (this.interrupted && exit._tag === "Success") {
+                        this.onFailure({ _tag: "Interrupted" });
+                    }
+                    else if (exit._tag === "Success") {
+                        this.onSuccess(exit.value);
+                    }
+                    else {
+                        this.onFailure(exit.error);
+                    }
+                });
+                return;
+        }
+    }
+}
+// API pública: fork + helper unsafeRunAsync
+function fork(effect, env, scheduler = scheduler_1.globalScheduler) {
+    const fiber = new RuntimeFiber(effect, env, scheduler);
+    fiber.schedule(); // arrancamos la primera reducción
+    return fiber;
+}
+// “correr” un Async como antes, pero apoyado en fibras + scheduler
+function unsafeRunAsync(effect, env, cb) {
+    const fiber = fork(effect, env);
+    fiber.join(cb);
+}

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types/effect"), exports);
+__exportStar(require("./types/asyncEffect"), exports);
+__exportStar(require("./stream/stream"), exports);
+__exportStar(require("./types/option"), exports);
+__exportStar(require("./types/effect"), exports);
+__exportStar(require("./scheduler/withScope"), exports);
+__exportStar(require("./scheduler/acquireRelease"), exports);
+__exportStar(require("./scheduler/scheduler"), exports);
+__exportStar(require("./types/cancel"), exports);
+__exportStar(require("./scheduler/scope"), exports);

package/dist/scheduler/acquireRelease.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acquireRelease = acquireRelease;
+const asyncEffect_1 = require("../types/asyncEffect");
+/**
+ * acquireRelease:
+ *   acquire: Async<R, E, A>
+ *   release: (A, Exit) => Async<R, never, void>
+ */
+function acquireRelease(acquire, release, scope) {
+    return (0, asyncEffect_1.asyncFlatMap)(acquire, (resource) => {
+        // registrar finalizer
+        scope.addFinalizer((exit) => release(resource, exit));
+        return (0, asyncEffect_1.asyncSucceed)(resource);
+    });
+}

package/dist/scheduler/scheduler.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.globalScheduler = exports.Scheduler = void 0;
+class Scheduler {
+    constructor() {
+        this.queue = [];
+        this.flushing = false;
+    }
+    schedule(task) {
+        this.queue.push(task);
+        if (!this.flushing) {
+            this.flush();
+        }
+    }
+    flush() {
+        this.flushing = true;
+        // Versión simple: drena todo de una
+        while (this.queue.length > 0) {
+            const t = this.queue.shift();
+            t();
+        }
+        this.flushing = false;
+    }
+}
+exports.Scheduler = Scheduler;
+// Un scheduler global para todo el runtime
+exports.globalScheduler = new Scheduler();

package/dist/scheduler/scope.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Scope = void 0;
+// src/scope.ts
+const fiber_1 = require("../fibers/fiber");
+let nextScopeId = 1;
+class Scope {
+    constructor() {
+        this.closed = false;
+        this.children = new Set();
+        this.subScopes = new Set();
+        this.finalizers = [];
+        this.id = nextScopeId++;
+    }
+    /** registra un finalizer (LIFO) */
+    addFinalizer(f) {
+        if (this.closed) {
+            throw new Error("Trying to add finalizer to closed scope");
+        }
+        this.finalizers.push(f);
+    }
+    /** crea un sub scope */
+    subScope() {
+        if (this.closed)
+            throw new Error("Scope closed");
+        const s = new Scope();
+        this.subScopes.add(s);
+        return s;
+    }
+    /** fork en este scope */
+    fork(eff, env) {
+        if (this.closed)
+            throw new Error("Scope closed");
+        const f = (0, fiber_1.fork)(eff, env);
+        this.children.add(f);
+        f.join(() => {
+            this.children.delete(f);
+        });
+        return f;
+    }
+    /** Cierre estructurado */
+    close(exit = { _tag: "Success", value: undefined }) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        // 1) cancelar hijos
+        for (const f of this.children) {
+            f.interrupt();
+        }
+        // 2) cerrar sub scopes
+        for (const s of this.subScopes) {
+            s.close(exit);
+        }
+        // 3) ejecutar finalizers en orden LIFO
+        while (this.finalizers.length > 0) {
+            const fin = this.finalizers.pop();
+            fin(exit); // se ejecuta como Async, pero no esperamos
+        }
+        this.children.clear();
+        this.subScopes.clear();
+    }
+    isClosed() {
+        return this.closed;
+    }
+}
+exports.Scope = Scope;

package/dist/scheduler/withScope.js

@@ -0,0 +1,19 @@
+"use strict";
+// src/withScope.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withScope = withScope;
+const scope_1 = require("./scope");
+/**
+ * Ejecuta una función dentro de un scope estructurado.
+ * Al final (éxito o error), se cierra el scope garantizando cleanup.
+ */
+function withScope(body) {
+    const scope = new scope_1.Scope();
+    try {
+        const result = body(scope);
+        return result;
+    }
+    finally {
+        scope.close(); // cleanup garantizado
+    }
+}

package/dist/stream/stream.js

@@ -0,0 +1,106 @@
+"use strict";
+// ----- ADT de Stream -----
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flattenStream = exports.concatStream = exports.emitStream = exports.emptyStream = void 0;
+exports.uncons = uncons;
+exports.mapStream = mapStream;
+exports.fromArray = fromArray;
+exports.collectStream = collectStream;
+const effect_js_1 = require("../types/effect.js");
+const option_js_1 = require("../types/option.js");
+// ----- Constructores helpers -----
+const emptyStream = () => ({
+    _tag: "Empty",
+});
+exports.emptyStream = emptyStream;
+const emitStream = (value) => ({
+    _tag: "Emit",
+    value,
+});
+exports.emitStream = emitStream;
+const concatStream = (left, right) => ({
+    _tag: "Concat",
+    left,
+    right,
+});
+exports.concatStream = concatStream;
+const flattenStream = (stream) => ({
+    _tag: "Flatten",
+    stream,
+});
+exports.flattenStream = flattenStream;
+// ----- uncons: ZIO[R, Option[E], (A, ZStream)] -----
+function uncons(self) {
+    switch (self._tag) {
+        case "Empty":
+            // fin de stream => Failure(None)
+            return (0, effect_js_1.fail)(option_js_1.none);
+        case "Emit":
+            // value.mapError(Some(_)).map(a => (a, Empty))
+            return (0, effect_js_1.map)((0, effect_js_1.mapError)(self.value, (e) => (0, option_js_1.some)(e)), (a) => [a, (0, exports.emptyStream)()]);
+        case "Concat":
+            // left.uncons.map(...).orElseOptional(right.uncons)
+            return (0, effect_js_1.orElseOptional)((0, effect_js_1.map)(uncons(self.left), ([a, tail]) => [
+                a,
+                (0, exports.concatStream)(tail, self.right),
+            ]), () => uncons(self.right));
+        case "Flatten":
+            // stream.uncons.flatMap { case (head, tail) =>
+            //   head.uncons
+            //     .map { case (a, as) => (a, as ++ Flatten(tail)) }
+            //     .orElseOptional(Flatten(tail).uncons)
+            // }
+            return (0, effect_js_1.flatMap)(uncons(self.stream), ([head, tail]) => (0, effect_js_1.orElseOptional)((0, effect_js_1.map)(uncons(head), ([a, as]) => [
+                a,
+                (0, exports.concatStream)(as, (0, exports.flattenStream)(tail)),
+            ]), () => uncons((0, exports.flattenStream)(tail))));
+    }
+}
+// ---------- combinadores extra opcionales ----------
+function mapStream(self, f) {
+    switch (self._tag) {
+        case "Empty":
+            return (0, exports.emptyStream)();
+        case "Emit":
+            return (0, exports.emitStream)((0, effect_js_1.map)(self.value, f));
+        case "Concat":
+            return (0, exports.concatStream)(mapStream(self.left, f), mapStream(self.right, f));
+        case "Flatten": {
+            const mappedOuter = mapStream(self.stream, (inner) => mapStream(inner, f));
+            return (0, exports.flattenStream)(mappedOuter);
+        }
+    }
+}
+// Stream finito desde un array
+function fromArray(values) {
+    let s = (0, exports.emptyStream)();
+    for (let i = values.length - 1; i >= 0; i--) {
+        const head = (0, exports.emitStream)((0, effect_js_1.succeed)(values[i]));
+        s = (0, exports.concatStream)(head, s);
+    }
+    return s;
+}
+// Consumidor síncrono del stream
+function collectStream(stream, env) {
+    const result = [];
+    let current = stream;
+    while (true) {
+        const exit = uncons(current)(env);
+        if (exit._tag === "Failure") {
+            const optErr = exit.error;
+            if (optErr._tag === "None") {
+                // fin del stream
+                return result;
+            }
+            else {
+                // error real
+                throw optErr.value;
+            }
+        }
+        else {
+            const [head, tail] = exit.value;
+            result.push(head);
+            current = tail;
+        }
+    }
+}

package/dist/stream/structuredConcurrency.js

@@ -0,0 +1,132 @@
+"use strict";
+// src/structuredConcurrency.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.race = race;
+exports.zipPar = zipPar;
+exports.collectAllPar = collectAllPar;
+const asyncEffect_1 = require("../types/asyncEffect");
+/**
+ * race(A, B):
+ *   - corre A y B en paralelo
+ *   - el primero que termine gana
+ *   - el otro es cancelado
+ */
+function race(left, right, parentScope) {
+    return (0, asyncEffect_1.async)((env, cb) => {
+        // cada carrera tiene su propio scope interno
+        const scope = parentScope.subScope();
+        let done = false;
+        const onResult = (exit) => {
+            if (done)
+                return;
+            done = true;
+            // cerrar todo (esto cancela la otra fibra)
+            scope.close(exit);
+            cb(exit);
+        };
+        const fiberLeft = scope.fork(left, env);
+        const fiberRight = scope.fork(right, env);
+        fiberLeft.join(onResult);
+        fiberRight.join(onResult);
+    });
+}
+/**
+ * zipPar(A, B):
+ *   - corre A y B en paralelo
+ *   - si ambas terminan bien → éxito con (A, B)
+ *   - si una falla → cancelar todo y devolver fallo
+ */
+function zipPar(left, right, parentScope) {
+    return (0, asyncEffect_1.async)((env, cb) => {
+        const scope = parentScope.subScope();
+        let leftExit = null;
+        let rightExit = null;
+        let done = false;
+        const checkDone = () => {
+            // si todavía no tenemos ambos resultados, no hacemos nada
+            if (!leftExit || !rightExit || done)
+                return;
+            done = true;
+            if (leftExit._tag === "Success" && rightExit._tag === "Success") {
+                // ambos ok
+                scope.close({ _tag: "Success", value: undefined });
+                cb({
+                    _tag: "Success",
+                    value: [leftExit.value, rightExit.value],
+                });
+                return;
+            }
+            // algún error, cancelar todo
+            let cause;
+            if (leftExit._tag === "Failure") {
+                cause = leftExit.error;
+            }
+            else if (rightExit._tag === "Failure") {
+                cause = rightExit.error;
+            }
+            else {
+                // Esto es lógicamente imposible, pero lo ponemos
+                // para mantener feliz a TypeScript.
+                throw new Error("zipPar: unreachable state (no Failure exit)");
+            }
+            const errExit = {
+                _tag: "Failure",
+                error: cause,
+            };
+            scope.close(errExit);
+            cb(errExit);
+        };
+        const f1 = scope.fork(left, env);
+        const f2 = scope.fork(right, env);
+        f1.join((exit) => {
+            leftExit = exit;
+            checkDone();
+        });
+        f2.join((exit) => {
+            rightExit = exit;
+            checkDone();
+        });
+    });
+}
+/**
+ * collectAllPar:
+ *   - corre todos en paralelo
+ *   - si uno falla → cancela todos
+ *   - si todos terminan bien → devuelve array de resultados
+ */
+function collectAllPar(effects, parentScope) {
+    return (0, asyncEffect_1.async)((env, cb) => {
+        const scope = parentScope.subScope();
+        const results = new Array(effects.length);
+        let completed = 0;
+        let done = false;
+        effects.forEach((eff, i) => {
+            const f = scope.fork(eff, env);
+            f.join((exit) => {
+                if (done)
+                    return;
+                if (exit._tag === "Failure") {
+                    done = true;
+                    const errExit = {
+                        _tag: "Failure",
+                        error: exit.error,
+                    };
+                    scope.close(errExit);
+                    cb(errExit);
+                    return;
+                }
+                results[i] = exit.value;
+                completed++;
+                if (completed === effects.length) {
+                    done = true;
+                    const successExit = {
+                        _tag: "Success",
+                        value: results,
+                    };
+                    scope.close({ _tag: "Success", value: undefined });
+                    cb(successExit);
+                }
+            });
+        });
+    });
+}

package/dist/types/asyncEffect.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.async = exports.asyncTotal = exports.asyncSync = exports.asyncFail = exports.asyncSucceed = void 0;
+exports.asyncMap = asyncMap;
+exports.asyncFlatMap = asyncFlatMap;
+exports.fromPromise = fromPromise;
+exports.tryPromiseAbortable = tryPromiseAbortable;
+exports.fromPromiseAbortable = fromPromiseAbortable;
+const asyncSucceed = (value) => ({
+    _tag: "Succeed",
+    value,
+});
+exports.asyncSucceed = asyncSucceed;
+const asyncFail = (error) => ({
+    _tag: "Fail",
+    error,
+});
+exports.asyncFail = asyncFail;
+const asyncSync = (thunk) => ({
+    _tag: "Sync",
+    thunk,
+});
+exports.asyncSync = asyncSync;
+const asyncTotal = (thunk) => (0, exports.asyncSync)(() => thunk());
+exports.asyncTotal = asyncTotal;
+const async = (register) => ({
+    _tag: "Async",
+    register,
+});
+exports.async = async;
+function asyncMap(fa, f) {
+    return asyncFlatMap(fa, (a) => (0, exports.asyncSucceed)(f(a)));
+}
+function asyncFlatMap(fa, f) {
+    return {
+        _tag: "FlatMap",
+        first: fa,
+        andThen: f,
+    };
+}
+function fromPromise(thunk, onError) {
+    return (0, exports.async)((env, cb) => {
+        thunk(env)
+            .then((value) => cb({ _tag: "Success", value }))
+            .catch((err) => cb({ _tag: "Failure", error: onError(err) }));
+    });
+}
+//TODO: Esto lo hago porque me interesa saber el nombre explicito de lo que falla, no solo que falle sino mas bien un detalle
+const isAbortError = (e) => typeof e === "object" &&
+    e !== null &&
+    "name" in e &&
+    e.name === "AbortError";
+function tryPromiseAbortable(thunk) {
+    return fromPromiseAbortable(thunk, (e) => isAbortError(e)
+        ? { _tag: "Abort" }
+        : { _tag: "PromiseRejected", reason: e });
+}
+function fromPromiseAbortable(thunk, onError) {
+    return (0, exports.async)((env, cb) => {
+        const ac = new AbortController();
+        let done = false;
+        const safeCb = (exit) => {
+            if (done)
+                return;
+            done = true;
+            cb(exit);
+        };
+        try {
+            const p = thunk(env, ac.signal);
+            p.then((value) => safeCb({ _tag: "Success", value }))
+                .catch((err) => safeCb({ _tag: "Failure", error: onError(err) }));
+        }
+        catch (e) {
+            safeCb({ _tag: "Failure", error: onError(e) });
+        }
+        return () => {
+            done = true;
+            ac.abort();
+        };
+    });
+}

package/dist/types/cancel.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeCancelToken = makeCancelToken;
+exports.linkAbortController = linkAbortController;
+/** Implementación simple de CancelToken */
+function makeCancelToken() {
+    let cancelled = false;
+    const listeners = new Set();
+    const cancel = () => {
+        if (cancelled)
+            return;
+        cancelled = true;
+        // ejecuta y limpia
+        for (const f of listeners) {
+            try {
+                f();
+            }
+            catch { /* opcional: log */ }
+        }
+        listeners.clear();
+    };
+    return {
+        isCancelled: () => cancelled,
+        onCancel: (f) => {
+            if (cancelled) {
+                // si ya está cancelado, ejecuta inmediatamente
+                try {
+                    f();
+                }
+                catch { /* opcional */ }
+                return () => { };
+            }
+            listeners.add(f);
+            return () => { listeners.delete(f); };
+        },
+        cancel,
+    };
+}
+/**
+ * Helper: conecta un AbortController a un CancelToken.
+ * Devuelve una función para desenganchar (unsubscribe).
+ */
+function linkAbortController(token, ac) {
+    return token.onCancel(() => ac.abort());
+}

package/dist/types/effect.js

@@ -0,0 +1,130 @@
+"use strict";
+// src/effect.ts
+// Resultado de ejecutar un efecto
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromThunk = exports.sync = exports.fail = exports.succeed = void 0;
+exports.map = map;
+exports.flatMap = flatMap;
+exports.mapError = mapError;
+exports.catchAll = catchAll;
+exports.orElseOptional = orElseOptional;
+exports.zip = zip;
+exports.tap = tap;
+exports.as = as;
+exports.asUnit = asUnit;
+exports.foreach = foreach;
+exports.collectAll = collectAll;
+// ---------- Constructores básicos ----------
+const succeed = (value) => (_) => ({ _tag: "Success", value });
+exports.succeed = succeed;
+const fail = (error) => () => ({ _tag: "Failure", error });
+exports.fail = fail;
+const sync = (thunk) => (env) => {
+    try {
+        return { _tag: "Success", value: thunk(env) };
+    }
+    catch (e) {
+        return { _tag: "Failure", error: e };
+    }
+};
+exports.sync = sync;
+const fromThunk = (thunk) => (0, exports.sync)(() => thunk());
+exports.fromThunk = fromThunk;
+// ---------- Combinadores de valor ----------
+function map(eff, f) {
+    return (env) => {
+        const exit = eff(env);
+        if (exit._tag === "Success") {
+            return { _tag: "Success", value: f(exit.value) };
+        }
+        return exit;
+    };
+}
+function flatMap(eff, f) {
+    return (env) => {
+        const exit1 = eff(env);
+        if (exit1._tag === "Failure") {
+            return exit1;
+        }
+        return f(exit1.value)(env);
+    };
+}
+function mapError(eff, f) {
+    return (env) => {
+        const exit = eff(env);
+        if (exit._tag === "Failure") {
+            return { _tag: "Failure", error: f(exit.error) };
+        }
+        return exit;
+    };
+}
+function catchAll(eff, handler) {
+    return (env) => {
+        const exit = eff(env);
+        if (exit._tag === "Failure") {
+            return handler(exit.error)(env);
+        }
+        return exit;
+    };
+}
+/**
+ * Versión estilo ZIO.orElseOptional:
+ * eff: Effect<R, Option<E>, A>
+ * - Failure(Some(e))  => se propaga
+ * - Failure(None)     => se ejecuta `that`
+ */
+function orElseOptional(eff, that) {
+    return (env) => {
+        const exit1 = eff(env);
+        if (exit1._tag === "Success")
+            return exit1;
+        const opt = exit1.error;
+        if (opt._tag === "Some")
+            return exit1; // error real
+        return that()(env); // None => probamos alternativa
+    };
+}
+// ---------- Más combinadores ----------
+function zip(fa, fb) {
+    return (env) => {
+        const ea = fa(env);
+        if (ea._tag === "Failure")
+            return ea;
+        const eb = fb(env);
+        if (eb._tag === "Failure")
+            return eb;
+        return { _tag: "Success", value: [ea.value, eb.value] };
+    };
+}
+function tap(eff, f) {
+    return (env) => {
+        const ea = eff(env);
+        if (ea._tag === "Failure")
+            return ea;
+        const eb = f(ea.value)(env);
+        if (eb._tag === "Failure")
+            return eb;
+        return ea;
+    };
+}
+function as(eff, value) {
+    return map(eff, () => value);
+}
+function asUnit(eff) {
+    return as(eff, undefined);
+}
+function foreach(items, f) {
+    return (env) => {
+        const out = [];
+        for (const a of items) {
+            const exit = f(a)(env);
+            if (exit._tag === "Failure")
+                return exit;
+            out.push(exit.value);
+        }
+        return { _tag: "Success", value: out };
+    };
+}
+function collectAll(effects) {
+    return foreach(effects, (e) => e);
+}

package/dist/types/option.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.some = exports.none = void 0;
+exports.none = { _tag: "None" };
+const some = (value) => ({ _tag: "Some", value });
+exports.some = some;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "brass-runtime",
+  "version": "1.0.0",
+  "description": "Effect runtime utilities for TypeScript",
+  "license": "ISC",
+  "author": "",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "ts-node-dev src/examples/demo.ts",
+    "build": "tsc",
+    "test": "node -e \"console.log('no tests yet')\"",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.0",
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/git": "^10.0.0",
+    "@semantic-release/github": "^11.0.0",
+    "@semantic-release/npm": "^13.1.3",
+    "@semantic-release/release-notes-generator": "^14.0.0",
+    "semantic-release": "^25.0.2",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.9.3"
+  }
+}