Skip to content

Latest commit

 

History

History
285 lines (196 loc) · 4.99 KB

modules.md

File metadata and controls

285 lines (196 loc) · 4.99 KB

📦 Modules — brass-runtime

This document describes the current and planned modules in brass-runtime, how they relate to each other, and how users are expected to navigate them.

The structure intentionally mirrors the mental model of ZIO:

  • a small, principled core
  • optional, layered modules
  • everything expressed in terms of typed effects and structured concurrency

Core modules (foundation)

These modules form the runtime kernel. Everything else builds on top of them.

runtime

Status: ✅ stable

Responsible for executing effects.

Contents:

  • Scheduler — cooperative, deterministic task scheduler
  • task queue, microtask flushing
  • fairness and explicit async boundaries

You almost never interact with this directly as a user.

asyncEffect / types

Status: ✅ stable

The heart of the system.

Key types:

  • Effect<R, E, A>
  • Async<R, E, A>
  • Exit<E, A>

Capabilities:

  • sync + async algebra (no Promises in semantics)
  • map, flatMap, fold, etc.
  • explicit async registration via callbacks

This is the semantic core of brass.

fiber

Status: ✅ stable

Lightweight fibers with structured lifecycle.

Features:

  • Fiber<E, A> abstraction
  • cooperative interruption
  • join, interrupt
  • LIFO finalizers

Fibers are always run under a Scope.

scope

Status: ✅ stable

Structured concurrency and resource safety.

Features:

  • parent / child scopes
  • deterministic cleanup
  • addFinalizer, close
  • used by fibers, streams, HTTP, resources

Scopes ensure:

no leaks, no zombies, no forgotten cleanup

resource

Status: ✅ stable

Resource-safe acquisition.

API:

  • acquireRelease
  • fromResource

Ties resource lifetimes to scopes.

Concurrency combinators

concurrency

Status: ✅ stable

High-level structured concurrency.

Includes:

  • race
  • zipPar
  • collectAllPar
  • fork

Semantics:

  • loser fibers are interrupted
  • errors propagate deterministically
  • scopes are respected

Stream modules (ZStream-like)

stream

Status: 🚧 active

Pull-based, resource-safe streams.

Key ideas:

  • Pull<R, E, A>
  • ZStream<R, E, A>
  • explicit backpressure
  • scope-aware

Includes:

  • constructors (fromArray, fromPull, empty)
  • transformations (map, filter)
  • execution (runCollect, collectStream)

buffer

Status: 🚧 active

Stream buffering with backpressure.

Features:

  • bounded buffers
  • backpressure vs dropping modes
  • deterministic cleanup

This is the foundation for:

  • pipelines
  • async boundaries in streams
  • future hubs

Planned stream modules

Status: ⏳ planned

  • pipeline — ZPipeline-style transformations
  • sink — consumers / reducers
  • hub — broadcast / pub-sub streams
  • channel — low-level streaming algebra

HTTP module

http

Status: ✅ usable / evolving

ZIO-HTTP–inspired client built on brass runtime.

Layers:

  • wire layer: HttpClient = Request => Async<_, HttpError, HttpWireResponse>
  • middleware: request/response transforms
  • DX layer: ergonomic helpers (getJson, postJson, etc.)

Key concepts:

  • fully lazy
  • cancelable via fibers
  • no Promises in core semantics
  • middleware-style composition (withMeta, logging, retries, auth)

Submodules:

  • client.ts — low-level HTTP execution
  • httpClient.ts — DX + helpers
  • withMeta — response enrichment middleware

Example usage:

const http = httpClientBuilder({ baseUrl }).withMeta();

const post = await toPromise(http.getJson<Post>("/posts/1"), {});

Interop modules

promise

Status: ✅ stable

Interop with Promise-based APIs.

Includes:

  • toPromise — await effects externally
  • fromPromiseAbortable
  • tryPromiseAbortable

Important:

Promises are interop only, never a runtime primitive.

Examples module

examples

Status: ✅ maintained

Executable documentation.

Covers:

  • fibers & interruption
  • scopes & finalizers
  • abortable promises
  • streams + buffering
  • HTTP usage

If you’re new: 👉 start here.

How to navigate the project

If you want to…

Understand the runtime

  • asyncEffect
  • scheduler
  • fiber
  • scope

Use effects

  • map, flatMap, fold
  • toPromise (interop only)

Do concurrency

  • race
  • zipPar
  • fork

Work with streams

  • stream
  • buffer

Call HTTP

  • http/client
  • http/httpClient
  • middleware like withMeta

Design philosophy

  • Explicit > implicit
  • Structured > ad-hoc
  • Lazy by default
  • Cancellation is cooperative and visible
  • No hidden async semantics

brass is not trying to be “easy first” — it’s trying to be correct first.

Future directions

  • Public API stabilization
  • Docs site (mdbook / Docusaurus)
  • ZIO-style module layering (Layer-like)
  • Metrics & tracing middleware
  • Typed errors across HTTP + streams

If you want:

  • a diagram of module dependencies
  • a shorter npm-facing version
  • or a ZIO comparison table

say the word.