@nicolastoulemont/std 0.7.2 → 0.8.1

package/README.md

@@ -4,18 +4,29 @@
 
 `@nicolastoulemont/std` is a functional TypeScript toolkit for modeling domain data, handling failures explicitly, and composing sync or async workflows.
 It is designed for application code where clear control flow, predictable typing, and dependency-aware orchestration matter.
-The API is small, pipe-friendly, and built around practical primitives you can combine incrementally.
+The API is pipe-friendly, namespace-oriented, and built from small primitives you can combine incrementally.
 
 ## Installation
 
+Install the base package:
+
 ```bash
 pnpm add @nicolastoulemont/std
 ```
 
+Install optional extras used by some modules and examples:
+
+```bash
+pnpm add @nicolastoulemont/std zod multithreading
+```
+
+- `zod` is optional. The ADT examples below use it, but `Adt` accepts any Standard Schema-compatible validator, including `zod`, `valibot`, `arktype`, and similar libraries.
+- `multithreading` is optional. It is only required if you want to use the `Multithread` module.
+
 ## Quick Start
 
 ```ts
-import { Result, Data, pipe } from "@nicolastoulemont/std"
+import { Data, Result, pipe } from "@nicolastoulemont/std"
 
 class InvalidPortError extends Data.TaggedError("InvalidPortError")<{ input: string }> {}
 
@@ -33,7 +44,6 @@ const parsePort = (input: string) =>
 import { Fx, Layer, Provide, Service, pipe } from "@nicolastoulemont/std"
 
 const Config = Service.tag<{ baseUrl: string }>("Config")
-
 const ConfigLive = Layer.ok(Config, { baseUrl: "https://api.example.com" })
 
 const program = Fx.gen(function* () {
@@ -54,12 +64,12 @@ const response = Fx.match(exit, {
 
 ### Result
 
-Result models success/failure with typed errors so transformations stay explicit and composable.
+Result models success and failure with typed errors so transformations stay explicit and composable.
 
 #### Abstract Example
 
 ```ts
-import { Result, Data, pipe } from "@nicolastoulemont/std"
+import { Data, Result, pipe } from "@nicolastoulemont/std"
 
 class NotPositiveIntegerError extends Data.TaggedError("NotPositiveIntegerError")<{ input: string }> {}
 
@@ -78,7 +88,7 @@ const parsePositiveInt = (input: string) => {
 #### Real-World Example
 
 ```ts
-import { Result, Data, pipe } from "@nicolastoulemont/std"
+import { Data, Result, pipe } from "@nicolastoulemont/std"
 
 class ValidationError extends Data.TaggedError("ValidationError")<{ message: string }> {}
 class ConflictError extends Data.TaggedError("ConflictError")<{ message: string }> {}
@@ -97,7 +107,7 @@ const signup = (email: string) => pipe(validateEmail(email), Result.flatMap(crea
 
 ### Option
 
-Option models optional presence/absence when missing data is expected and not an error condition.
+Option models optional presence and absence when missing data is expected and not an error condition.
 
 #### Abstract Example
 
@@ -136,7 +146,7 @@ const readPagination = (query: URLSearchParams) => ({
 
 ### Either
 
-Either models two valid branches where both sides are meaningful outcomes rather than success versus failure.
+Either models two meaningful branches where both sides are valid outcomes rather than success versus failure.
 
 #### Abstract Example
 
@@ -172,228 +182,188 @@ const responseMeta = (id: string) =>
   )
 ```
 
-### Fx
+### Brand
 
-Fx models generator-based effects with typed dependencies and short-circuiting typed failures.
+Brand adds nominal typing to primitives and other values without changing their runtime representation.
+Use `Brand.make` when the source is already trusted, and `Brand.refine` when you want a validated branded value wrapped in `Result`.
 
 #### Abstract Example
 
 ```ts
-import { Fx, Layer, Provide, Service, pipe } from "@nicolastoulemont/std"
+import { Brand } from "@nicolastoulemont/std"
 
-const Clock = Service.tag<{ now: () => number }>("Clock")
-const ClockLive = Layer.ok(Clock, { now: () => Date.now() })
+type Port = Brand.Branded<number, "Port">
 
-const program = Fx.gen(function* () {
-  const clock = yield* Clock
-  return clock.now()
-})
+const toPort = Brand.refine<Port>((value) => Number.isInteger(value) && value > 0 && value <= 65_535, "Invalid port")
 
-const exit = Fx.run(pipe(program, Provide.layer(ClockLive)))
-
-const timestamp = Fx.match(exit, {
-  Ok: (ok) => ok.value,
-  Err: () => 0,
-  Defect: () => 0,
-})
+const parsed = toPort(3000)
 ```
 
 #### Real-World Example
 
 ```ts
-import { Fx, Layer, Result, Data, Provide, Service, pipe } from "@nicolastoulemont/std"
+import { Brand, Result, pipe } from "@nicolastoulemont/std"
 
-const Api = Service.tag<{ postOrder: (input: { sku: string; qty: number }) => Promise<{ orderId: string }> }>("Api")
-const ApiLive = Layer.ok(Api, {
-  postOrder: async () => ({ orderId: "ord_42" }),
-})
+type Email = Brand.Branded<string, "Email">
 
-class InvalidQuantityError extends Data.TaggedError("InvalidQuantityError")<{ qty: number }> {}
+const toEmail = Brand.refine<Email>(
+  (value) => value.includes("@"),
+  (value) => `Invalid email: ${value}`,
+)
 
-const submitOrder = Fx.gen(function* (payload: { sku?: string; qty: number }) {
-  const api = yield* Api
-  const sku = yield* Fx.option(payload.sku)
-  const validQty = yield* Result.filter(
-    Result.ok(payload.qty),
-    (qty) => qty > 0,
-    (qty) => new InvalidQuantityError({ qty }),
+const register = (input: { email: string }) =>
+  pipe(
+    Result.ok(input.email),
+    Result.flatMap(toEmail),
+    Result.map((email) => ({ email })),
   )
-  return yield* Fx.try(() => api.postOrder({ sku, qty: validQty }))
-})
-
-const exit = Fx.run(pipe(submitOrder({ sku: "book-1", qty: 2 }), Provide.layer(ApiLive)))
-
-const httpResponse = Fx.match(exit, {
-  Ok: (ok) => ({ status: 201, body: ok.value }),
-  Err: (err) => ({ status: 400, body: String(err.error) }),
-  Defect: () => ({ status: 500, body: "Unexpected defect" }),
-})
 ```
 
-#### Retry Example
+### Predicate
 
-```ts
-import { Fx, Result, Schedule } from "@nicolastoulemont/std"
+Predicate provides small composable boolean predicates and refinements for filtering, narrowing, and request validation.
 
-let attempts = 0
-
-const flaky = Fx.gen(function* () {
-  attempts += 1
-  if (attempts < 3) {
-    return yield* Result.err("temporary" as const)
-  }
-  return "ok"
-})
-
-const exit = Fx.run(Fx.retry(flaky, Schedule.recurs(5)))
-```
-
-#### Nested Retry with Dependencies
+#### Abstract Example
 
 ```ts
-import { Fx, Layer, Result, Schedule, pipe, Provide, Service } from "@nicolastoulemont/std"
-
-type ConfigService = { baseUrl: string }
-const Config = Service.tag<ConfigService>("Config")
-const ConfigLive = Layer.ok(Config, { baseUrl: "https://api.example.com" })
+import { Predicate } from "@nicolastoulemont/std"
 
-let attempts = 0
-
-const inner = Fx.retry(
-  Fx.gen(function* () {
-    const config = yield* Config
-    attempts += 1
-    if (attempts < 2) {
-      return yield* Result.err("temporary" as const)
-    }
-    return config.baseUrl
-  }),
-  Schedule.recurs(2),
+const isPositiveEven = Predicate.and<number>(
+  (n) => n > 0,
+  (n) => n % 2 === 0,
 )
 
-const program = Fx.gen(function* () {
-  const baseUrl = yield* inner
-  return `ready:${baseUrl}`
-})
-
-const exit = Fx.run(pipe(program, Provide.layer(ConfigLive)))
+const ok = isPositiveEven(4)
 ```
 
-#### Concurrent Traversal with Fx.forEach
+#### Real-World Example
 
 ```ts
-import { Fx } from "@nicolastoulemont/std"
+import { Predicate } from "@nicolastoulemont/std"
 
-const loadUsers = Fx.forEach(
-  ["u1", "u2", "u3"],
-  (id) =>
-    Fx.gen(async function* () {
-      const response = await fetch(`/api/users/${id}`)
-      return yield* Fx.try(() => response.json())
-    }),
-  { concurrency: 2 },
-)
-
-const exit = await Fx.run(loadUsers)
-```
-
-### Queue
+type SearchInput = {
+  q: string
+  limit: number
+}
 
-Queue provides a standalone FIFO task queue with configurable concurrency, backpressure (bounded mode), and lifecycle controls.
+const hasQuery = (input: SearchInput) => input.q.trim().length > 0
+const hasSafeLimit = (input: SearchInput) => input.limit > 0 && input.limit <= 100
 
-#### Abstract Example
+const isSearchInput = Predicate.and<SearchInput>(hasQuery, hasSafeLimit)
 
-```ts
-import { Queue } from "@nicolastoulemont/std"
+const canSearch = isSearchInput({ q: "books", limit: 20 })
+```
 
-const queue = Queue.make({ concurrency: 2 })
+### Schema
 
-const first = queue.enqueue(() => 1)
-const second = queue.enqueue(async () => 2)
+Schema wraps Standard Schema-compatible validators for two production use cases:
+boundary parsing and sync-only refinement.
 
-await queue.awaitIdle()
-await queue.shutdown({ mode: "drain" })
-```
+Use `Schema.parse` at I/O boundaries when a broad external type hides smaller implicit subtypes.
+Use `Schema.refine` for in-memory narrowing when the schema validates only part of a broader value and you want to preserve the rest of the original shape.
+Use `Schema.is` when the narrowed type should exactly match the schema output.
+Use `Schema.Refine<Base, typeof schema>` for a reusable preserved-shape narrowed type, and `Schema.Infer<typeof schema>` for the exact schema output type.
+Only use `Schema.refine` with sync schemas that prove properties already present on the original value. Transforms, defaults, and coercions should continue to use `Schema.parse`.
 
-#### Real-World Example
+#### Boundary Parsing Example
 
 ```ts
-import { Queue } from "@nicolastoulemont/std"
+import { Result, Schema } from "@nicolastoulemont/std"
+import { z } from "zod"
 
-const imageQueue = Queue.bounded(100, { concurrency: 4 })
+type Ticket = {
+  channel: "chat" | "email"
+  chatId?: string | null
+  metadata?: {
+    conversationId?: string | null
+  } | null
+}
 
-const tasks = imageUrls.map((url) =>
-  imageQueue.enqueue(async ({ signal }) => {
-    const response = await fetch(url, { signal })
-    return response.arrayBuffer()
+type ChatTicket = {
+  channel: "chat"
+  chatId: string
+  metadata: {
+    conversationId: string
+  }
+}
+
+const ChatTicketSchema: Schema.SyncRefinementSchema<Ticket, ChatTicket> = z.object({
+  channel: z.literal("chat"),
+  chatId: z.string(),
+  metadata: z.object({
+    conversationId: z.string(),
   }),
-)
+})
 
-const buffers = await Promise.all(tasks)
-await imageQueue.shutdown({ mode: "drain" })
-```
+const parseChatTicket = Schema.parse(ChatTicketSchema)
 
-### Multithread
+const result = parseChatTicket({
+  channel: "chat",
+  chatId: "chat_123",
+  metadata: { conversationId: "conv_123" },
+})
 
-Multithread runs self-contained callbacks in worker threads using a Result-first API while remaining yieldable in `Fx.gen`.
+if (Result.isOk(result)) {
+  result.value.metadata.conversationId
+}
+```
 
-#### Abstract Example
+#### In-Memory Refinement Example
 
 ```ts
-import { Multithread } from "@nicolastoulemont/std"
-
-const op = Multithread.run((input: string, ctx) => {
-  ctx.throwIfCancelled()
-  return input.toUpperCase()
-}, "hello")
+import { Schema } from "@nicolastoulemont/std"
+import { z } from "zod"
 
-const result = await op.result()
-```
+type PersistedTicket = {
+  id: string
+  channel: "chat" | "email"
+  chatId?: string | null
+  metadata?: {
+    conversationId?: string | null
+  } | null
+}
 
-#### Real-World Example
+type ChatTicketFields = {
+  channel: "chat"
+  chatId: string
+}
 
-```ts
-import { Fx, Multithread } from "@nicolastoulemont/std"
+const ChatTicketSchema: Schema.SyncSchema<PersistedTicket, ChatTicketFields> = z.object({
+  channel: z.literal("chat"),
+  chatId: z.string(),
+})
 
-const program = Fx.gen(async function* () {
-  const records = yield* Multithread.map(
-    ['{"id":"1","email":"a@example.com"}', '{"id":"2","email":"b@example.com"}'],
-    (line, _index, ctx) => {
-      ctx.throwIfCancelled()
-      try {
-        return JSON.parse(line) as { id: string; email: string }
-      } catch {
-        return { _tag: "Err" as const, error: { _tag: "ParseError" as const, line } }
-      }
-    },
-    { parallelism: 4 },
-  )
+type ChatTicket = Schema.Refine<PersistedTicket, typeof ChatTicketSchema>
 
-  const preferred = yield* Multithread.firstSuccess([Multithread.run(() => "cache"), Multithread.run(() => "database")])
+const isChatTicket = Schema.refine(ChatTicketSchema)
 
-  return { records, preferred }
-})
+declare const ticket: PersistedTicket
 
-const exit = await Fx.run(program)
+if (isChatTicket(ticket)) {
+  ticket.id
+  ticket.chatId.toUpperCase()
+}
 ```
 
-Multithread cancellation is cooperative. `abort()` always cancels logically, and worker code can stop early by calling `ctx.throwIfCancelled()`.
+Use `Schema.is` instead when the narrowed type should be the schema output itself rather than `Base & Output<typeof schema>`.
 
 ### Adt
 
-Adt provides schema-backed tagged variants so you can model domain state with exhaustive pattern matching.
+Adt builds tagged unions backed by any Standard Schema-compatible validator.
+The examples below use `zod`, but the same API works with `valibot`, `arktype`, and other libraries that implement the Standard Schema contract.
 
 #### Abstract Example
 
 ```ts
-import { Adt, type AdtInfer } from "@nicolastoulemont/std"
+import { Adt } from "@nicolastoulemont/std"
 import { z } from "zod"
 
 const Shape = Adt.union("Shape", {
   Circle: z.object({ radius: z.number() }),
   Square: z.object({ side: z.number() }),
 })
-type Shape = AdtInfer<typeof Shape>
+
+type Shape = Adt.Infer<typeof Shape>
 
 const describeShape = (shape: Shape) =>
   Adt.match(shape, {
@@ -405,7 +375,7 @@ const describeShape = (shape: Shape) =>
 #### Real-World Example
 
 ```ts
-import { Adt, type AdtInfer } from "@nicolastoulemont/std"
+import { Adt } from "@nicolastoulemont/std"
 import { z } from "zod"
 
 const OrderState = Adt.union("OrderState", {
@@ -413,7 +383,8 @@ const OrderState = Adt.union("OrderState", {
   Confirmed: z.object({ id: z.string(), paymentId: z.string() }),
   Shipped: z.object({ id: z.string(), trackingId: z.string() }),
 })
-type OrderState = AdtInfer<typeof OrderState>
+
+type OrderState = Adt.Infer<typeof OrderState>
 
 const badgeLabel = (state: OrderState) =>
   Adt.match(state, {
@@ -425,7 +396,8 @@ const badgeLabel = (state: OrderState) =>
 
 ### Data
 
-Data creates immutable structural value objects (`Data.struct`, `Data.tuple`, `Data.array`, `Data.tagged`) with stable equality and hashing semantics.
+Data creates immutable structural value objects with stable equality and hashing semantics.
+Use it when you want value semantics for tuples, arrays, tagged records, or custom error types.
 
 #### Abstract Example
 
@@ -454,6 +426,7 @@ if (previous.equals(next)) {
 ### Order
 
 Order provides composable comparators and immutable sorting helpers.
+Use `Order.string` for deterministic lexicographic ordering and `Order.collator(...)` when locale rules or numeric string sorting matter.
 
 #### Abstract Example
 
@@ -484,6 +457,8 @@ const sorted = Order.sort(
 ```ts
 import { Order } from "@nicolastoulemont/std"
 
+const collator = new Intl.Collator("en", { numeric: true })
+
 type Product = {
   id: string
   category: string
@@ -491,7 +466,7 @@ type Product = {
   rating: number
 }
 
-const byCategory = Order.by(Order.string, (product: Product) => product.category)
+const byCategory = Order.by(Order.collator(collator), (product: Product) => product.category)
 const byPrice = Order.by(Order.number, (product: Product) => product.price)
 const byRatingDesc = Order.reverse(Order.by(Order.number, (product: Product) => product.rating))
 
@@ -506,14 +481,444 @@ const products: Product[] = [
 const sorted = sortProducts(products)
 ```
 
+### Context
+
+Context is the typed immutable service map used by `Fx`, `Layer`, and `Provide`.
+Use it directly when you want to assemble dependencies without building a layer first.
+
+#### Abstract Example
+
+```ts
+import { Context, Service, pipe } from "@nicolastoulemont/std"
+
+const Logger = Service.tag<{ log: (message: string) => void }>("Logger")
+const Clock = Service.tag<{ now: () => number }>("Clock")
+
+const ctx = pipe(Context.make(Logger, { log: () => undefined }), Context.add(Clock, { now: () => 123 }))
+
+const now = Context.get(ctx, Clock).now()
+```
+
+#### Real-World Example
+
+```ts
+import { Context, Service, pipe } from "@nicolastoulemont/std"
+
+const Config = Service.tag<{ apiBaseUrl: string }>("Config")
+const Request = Service.tag<{ id: string }>("Request")
+
+const base = Context.make(Config, { apiBaseUrl: "https://api.example.com" })
+const requestCtx = pipe(base, Context.add(Request, { id: "req_123" }))
+
+const requestId = Context.get(requestCtx, Request).id
+```
+
+### Service
+
+Service defines typed dependency tags that can be yielded inside `Fx.gen`.
+Use `Service.tag(...)` for interface-only tags and `Service.Service<...>()("...")` when you want a class-style service tag.
+
+#### Abstract Example
+
+```ts
+import { Fx, Provide, Service } from "@nicolastoulemont/std"
+
+const Clock = Service.tag<{ now: () => number }>("Clock")
+
+const program = Fx.gen(function* () {
+  return (yield* Clock).now()
+})
+
+const exit = Fx.run(Provide.service(Clock, { now: () => 123 })(program))
+```
+
+#### Real-World Example
+
+```ts
+import { Fx, Provide, Service } from "@nicolastoulemont/std"
+
+const Logger = Service.Service<{ info: (message: string) => void }>()("Logger")
+
+const program = Fx.gen(function* () {
+  const logger = yield* Logger
+  logger.info("starting request")
+  return "ok"
+})
+
+const exit = Fx.run(
+  Provide.service(Logger, {
+    info: (message) => console.log(message),
+  })(program),
+)
+```
+
+### Layer
+
+Layer builds services, composes service graphs, and models dependency construction separately from program execution.
+Use it when the service itself has dependencies, can fail, or needs scoped cleanup.
+
+#### Abstract Example
+
+```ts
+import { Fx, Layer, Provide, Service } from "@nicolastoulemont/std"
+
+const Port = Service.tag<number>("Port")
+const PortLive = Layer.ok(Port, 3000)
+
+const program = Fx.gen(function* () {
+  return yield* Port
+})
+
+const exit = Fx.run(Provide.layer(PortLive)(program))
+```
+
+#### Real-World Example
+
+```ts
+import { Fx, Layer, Provide, Service } from "@nicolastoulemont/std"
+
+const Config = Service.tag<{ baseUrl: string }>("Config")
+const Client = Service.tag<{ get: (path: string) => string }>("Client")
+
+const ConfigLive = Layer.ok(Config, { baseUrl: "https://api.example.com" })
+
+const ClientLive = Layer.fx(Client)(
+  Fx.gen(function* () {
+    const config = yield* Config
+    return {
+      get: (path: string) => `${config.baseUrl}${path}`,
+    }
+  }),
+)
+
+const Live = Layer.provide(ConfigLive)(ClientLive)
+
+const program = Fx.gen(function* () {
+  return (yield* Client).get("/users")
+})
+
+const exit = Fx.run(Provide.layer(Live)(program))
+```
+
+### Provide
+
+Provide resolves `Fx` requirements using a service, a context, or a fully-built layer.
+It is the last step that turns a dependency-requiring effect into a runnable one.
+
+#### Abstract Example
+
+```ts
+import { Fx, Provide, Service } from "@nicolastoulemont/std"
+
+const Port = Service.tag<number>("Port")
+
+const readPort = Fx.gen(function* () {
+  return yield* Port
+})
+
+const exit = Fx.run(Provide.service(Port, 3000)(readPort))
+```
+
+#### Real-World Example
+
+```ts
+import { Context, Fx, Provide, Service, pipe } from "@nicolastoulemont/std"
+
+const Config = Service.tag<{ baseUrl: string }>("Config")
+const Logger = Service.tag<{ info: (message: string) => void }>("Logger")
+
+const ctx = pipe(
+  Context.make(Config, { baseUrl: "https://api.example.com" }),
+  Context.add(Logger, { info: (message) => console.log(message) }),
+)
+
+const program = Fx.gen(function* () {
+  const config = yield* Config
+  const logger = yield* Logger
+  logger.info(`Calling ${config.baseUrl}`)
+  return config.baseUrl
+})
+
+const exit = Fx.run(Provide.context(ctx)(program))
+```
+
+### Fx
+
+Fx models generator-based effects with typed dependencies, typed failures, and sync or async execution.
+It is the center of the effectful part of the library, and it composes naturally with `Result`, `Option`, `Layer`, `Provide`, and `Service`.
+
+#### Abstract Example
+
+```ts
+import { Fx, Layer, Provide, Service, pipe } from "@nicolastoulemont/std"
+
+const Clock = Service.tag<{ now: () => number }>("Clock")
+const ClockLive = Layer.ok(Clock, { now: () => Date.now() })
+
+const program = Fx.gen(function* () {
+  const clock = yield* Clock
+  return clock.now()
+})
+
+const exit = Fx.run(pipe(program, Provide.layer(ClockLive)))
+
+const timestamp = Fx.match(exit, {
+  Ok: (ok) => ok.value,
+  Err: () => 0,
+  Defect: () => 0,
+})
+```
+
+#### Real-World Example
+
+```ts
+import { Data, Fx, Layer, Provide, Result, Service, pipe } from "@nicolastoulemont/std"
+
+const Api = Service.tag<{ postOrder: (input: { sku: string; qty: number }) => Promise<{ orderId: string }> }>("Api")
+
+const ApiLive = Layer.ok(Api, {
+  postOrder: async () => ({ orderId: "ord_42" }),
+})
+
+class InvalidQuantityError extends Data.TaggedError("InvalidQuantityError")<{ qty: number }> {}
+
+const submitOrder = Fx.gen(function* (payload: { sku?: string; qty: number }) {
+  const api = yield* Api
+  const sku = yield* Fx.option(payload.sku)
+  const validQty = yield* Result.filter(
+    Result.ok(payload.qty),
+    (qty) => qty > 0,
+    (qty) => new InvalidQuantityError({ qty }),
+  )
+  return yield* Fx.try(() => api.postOrder({ sku, qty: validQty }))
+})
+
+const exit = Fx.run(pipe(submitOrder({ sku: "book-1", qty: 2 }), Provide.layer(ApiLive)))
+```
+
+### Duration
+
+Duration provides fixed-size, millisecond-backed values for retries, timeouts, and config-style inputs.
+
+#### Abstract Example
+
+```ts
+import { Duration, Result } from "@nicolastoulemont/std"
+
+const timeout = Duration.seconds(30)
+
+const parsed = Duration.parse("5 minutes")
+
+const timeoutMs = Result.match(parsed, {
+  Ok: Duration.toMillis,
+  Err: (error) => error._tag,
+})
+```
+
+#### Real-World Example
+
+```ts
+import { Duration, Schedule } from "@nicolastoulemont/std"
+
+const retry = Schedule.fixed({
+  times: 3,
+  delayMs: Duration.seconds(1),
+})
+
+const backoff = Schedule.exponential({
+  times: 5,
+  baseDelayMs: "0.5 seconds",
+  maxDelayMs: "10 seconds",
+})
+```
+
+### Schedule
+
+Schedule describes retry policies for `Fx.retry`.
+Use `recurs` for immediate retries, `fixed` for constant delays, and `exponential` for backoff.
+
+#### Abstract Example
+
+```ts
+import { Schedule } from "@nicolastoulemont/std"
+
+const schedule = Schedule.recurs(2)
+const delay = schedule.delayForAttempt(1)
+```
+
+#### Real-World Example
+
+```ts
+import { Duration, Fx, Result, Schedule } from "@nicolastoulemont/std"
+
+let attempts = 0
+
+const flaky = Fx.gen(function* () {
+  attempts += 1
+  if (attempts < 3) {
+    return yield* Result.err("temporary" as const)
+  }
+  return "ok"
+})
+
+const exit = await Fx.run(
+  Fx.retry(
+    flaky,
+    Schedule.exponential({
+      times: 5,
+      baseDelayMs: Duration.millis(100),
+      maxDelayMs: "1 seconds",
+    }),
+  ),
+)
+```
+
+### Scope
+
+Scope manages finalizers and nested resource lifecycles.
+It is mostly used by `Layer.scoped` and `Provide.layer`, but you can use it directly when you want explicit cleanup semantics.
+
+#### Abstract Example
+
+```ts
+import { Fx, Result, Scope } from "@nicolastoulemont/std"
+
+let released = false
+
+const scope = Scope.make()
+
+Fx.run(
+  scope.addFinalizer(() =>
+    Fx.gen(function* () {
+      released = true
+    }),
+  ),
+)
+
+Fx.run(scope.close(Result.ok(undefined)))
+```
+
+#### Real-World Example
+
+```ts
+import { Fx, Result, Scope } from "@nicolastoulemont/std"
+
+const events: string[] = []
+
+const root = Scope.make()
+const child = root.fork()
+
+Fx.run(
+  root.addFinalizer(() =>
+    Fx.gen(function* () {
+      events.push("root")
+    }),
+  ),
+)
+
+Fx.run(
+  child.addFinalizer(() =>
+    Fx.gen(function* () {
+      events.push("child")
+    }),
+  ),
+)
+
+Fx.run(root.close(Result.ok(undefined)))
+```
+
+### Queue
+
+Queue provides a standalone FIFO task queue with configurable concurrency, backpressure, and lifecycle controls.
+Use it when you want bounded async work without adopting the full `Fx` model.
+
+#### Abstract Example
+
+```ts
+import { Queue } from "@nicolastoulemont/std"
+
+const queue = Queue.make({ concurrency: 2 })
+
+const first = queue.enqueue(() => 1)
+const second = queue.enqueue(async () => 2)
+
+await queue.awaitIdle()
+await queue.shutdown({ mode: "drain" })
+```
+
+#### Real-World Example
+
+```ts
+import { Queue } from "@nicolastoulemont/std"
+
+const imageQueue = Queue.bounded(100, { concurrency: 4 })
+
+const tasks = imageUrls.map((url) =>
+  imageQueue.enqueue(async ({ signal }) => {
+    const response = await fetch(url, { signal })
+    return response.arrayBuffer()
+  }),
+)
+
+const buffers = await Promise.all(tasks)
+await imageQueue.shutdown({ mode: "drain" })
+```
+
+### Multithread
+
+Multithread runs self-contained callbacks in worker threads using a Result-first API while remaining yieldable in `Fx.gen`.
+It requires the optional `multithreading` dependency at runtime.
+
+#### Abstract Example
+
+```ts
+import { Multithread } from "@nicolastoulemont/std"
+
+const op = Multithread.run((input: string, ctx) => {
+  ctx.throwIfCancelled()
+  return input.toUpperCase()
+}, "hello")
+
+const result = await op.result()
+```
+
+#### Real-World Example
+
+```ts
+import { Fx, Multithread } from "@nicolastoulemont/std"
+
+const program = Fx.gen(async function* () {
+  const records = yield* Multithread.map(
+    ['{"id":"1","email":"a@example.com"}', '{"id":"2","email":"b@example.com"}'],
+    (line, _index, ctx) => {
+      ctx.throwIfCancelled()
+      try {
+        return JSON.parse(line) as { id: string; email: string }
+      } catch {
+        return { _tag: "Err" as const, error: { _tag: "ParseError" as const, line } }
+      }
+    },
+    { parallelism: 4 },
+  )
+
+  const preferred = yield* Multithread.firstSuccess([Multithread.run(() => "cache"), Multithread.run(() => "database")])
+
+  return { records, preferred }
+})
+
+const exit = await Fx.run(program)
+```
+
+Multithread cancellation is cooperative. `abort()` always cancels logically, and worker code can stop early by calling `ctx.throwIfCancelled()`.
+
 ### pipe / flow
 
-pipe and flow compose sync/async transformations into readable, type-inferred data pipelines.
+`pipe` and `flow` compose sync or async transformations into readable, type-inferred data pipelines.
 
 #### Abstract Example
 
 ```ts
-import { pipe, flow } from "@nicolastoulemont/std"
+import { flow, pipe } from "@nicolastoulemont/std"
 
 const toLabel = flow(
   (n: number) => n * 2,
@@ -521,7 +926,7 @@ const toLabel = flow(
   (s) => `value:${s}`,
 )
 
-const result = pipe(10, (n) => n + 1, toLabel) // "value:22"
+const result = pipe(10, (n) => n + 1, toLabel)
 ```
 
 #### Real-World Example