effect 4.0.0-beta.77 → 4.0.0-beta.79

package/src/SchemaRepresentation.ts

@@ -1,88 +1,14 @@
 /**
- * Serializable intermediate representation (IR) of Effect Schema types.
- *
- * `SchemaRepresentation` sits between the internal `SchemaAST` and external
- * formats (JSON Schema, generated TypeScript code, serialized JSON). A
- * {@link Representation} is a discriminated union describing the *shape* of a
- * schema — its types, checks, annotations, and references — in a form that
- * can be round-tripped through JSON and used for code generation.
- *
- * ## Mental model
- *
- * - **Representation**: A tagged union (`_tag`) of all supported schema shapes:
- *   primitives, literals, objects, arrays, unions, declarations, references,
- *   and suspensions.
- * - **Document**: A single {@link Representation} paired with a map of named
- *   {@link References} (analogous to JSON Schema `$defs`).
- * - **MultiDocument**: Like `Document` but holds one or more representations
- *   sharing the same references.
- * - **Check / Filter / FilterGroup**: Validation constraints (min length,
- *   pattern, integer, etc.) attached to types that support them.
- * - **Meta types**: Typed metadata for checks on each category — e.g.
- *   {@link StringMeta}, {@link NumberMeta}, {@link ArraysMeta}.
- * - **Reviver**: A callback used by {@link toSchema} and {@link toCodeDocument}
- *   to handle `Declaration` nodes (custom types like `Option`, `Date`, etc.).
- * - **Code / CodeDocument**: Output of {@link toCodeDocument} — TypeScript
- *   source strings for runtime schemas and their type-level counterparts.
- *
- * ## Common tasks
- *
- * - Convert a Schema AST to a Document → {@link fromAST}
- * - Convert multiple ASTs to a MultiDocument → {@link fromASTs}
- * - Reconstruct a runtime Schema from a Document → {@link toSchema}
- * - Convert a Document to JSON Schema → {@link toJsonSchemaDocument}
- * - Convert a MultiDocument to JSON Schema → {@link toJsonSchemaMultiDocument}
- * - Parse a JSON Schema document into a Document → {@link fromJsonSchemaDocument}
- * - Parse a JSON Schema multi-document → {@link fromJsonSchemaMultiDocument}
- * - Generate TypeScript code from a MultiDocument → {@link toCodeDocument}
- * - Serialize/deserialize a Document as JSON → {@link DocumentFromJson}
- * - Serialize/deserialize a MultiDocument as JSON → {@link MultiDocumentFromJson}
- * - Wrap a Document as a MultiDocument → {@link toMultiDocument}
- *
- * ## Gotchas
- *
- * - `Declaration` nodes require a {@link Reviver} to reconstruct complex types
- *   (e.g. `Option`, `Date`). Without one, `toSchema` falls back to the
- *   declaration's `encodedSchema`. Use {@link toSchemaDefaultReviver} for
- *   built-in Effect types.
- * - `Reference` nodes are resolved against the `references` map in the
- *   `Document`. An unresolvable `$ref` throws at runtime.
- * - `Suspend` wraps a single `thunk` representation; it is used for recursive
- *   schemas. Circular references are handled by lazy resolution in
- *   {@link toSchema}.
- * - The `$`-prefixed exports (e.g. {@link $Representation}, {@link $Document})
- *   are Schema codecs for the representation types themselves — use them to
- *   validate or encode/decode representation data, not application data.
- *
- * ## Quickstart
- *
- * **Example** (Round-trip through JSON)
- *
- * ```ts
- * import { Schema, SchemaRepresentation } from "effect"
- *
- * const Person = Schema.Struct({
- *   name: Schema.String,
- *   age: Schema.Int
- * })
- *
- * // Schema AST → Document
- * const doc = SchemaRepresentation.fromAST(Person.ast)
- *
- * // Document → JSON Schema
- * const jsonSchema = SchemaRepresentation.toJsonSchemaDocument(doc)
- *
- * // Document → runtime Schema
- * const reconstructed = SchemaRepresentation.toSchema(doc)
- * ```
- *
- * ## See also
- *
- * - {@link Representation} — the core tagged union
- * - {@link Document} — single-schema container
- * - {@link fromAST} — entry point from Schema AST
- * - {@link toSchema} — reconstruct a runtime Schema
- * - {@link toCodeDocument} — generate TypeScript code
+ * Plain data structures for describing schemas in a serializable form. A
+ * `Representation` is not the original `Schema` object; it is a JSON-friendly
+ * description of the schema's types, fields, unions, checks, annotations, and
+ * references.
+ *
+ * This module defines the representation node types, document types, and
+ * codecs used to validate those documents. It can build representation
+ * documents from schema ASTs, turn representation documents back into schemas,
+ * convert them to and from JSON Schema documents, and generate TypeScript code
+ * artifacts for schema definitions.
  *
  * @since 4.0.0
  */

package/src/SchemaTransformation.ts

@@ -1,86 +1,13 @@
 /**
- * Bidirectional transformations for the Effect Schema system.
- *
- * A `Transformation` pairs a decode `Getter` and an encode `Getter` into a
- * single bidirectional value, used by `Schema.decodeTo`, `Schema.encodeTo`,
- * `Schema.decode`, `Schema.encode`, and `Schema.link` to define how values
- * are converted between encoded and decoded representations. A `Middleware`
- * is the effect-level equivalent — it wraps the entire parsing `Effect`
- * pipeline rather than individual values.
- *
- * ## Mental model
- *
- * - **Transformation**: A pair of `Getter`s (decode + encode) that convert
- *   individual values bidirectionally. `T` is the decoded (Type) side, `E` is
- *   the encoded side. `RD`/`RE` are required Effect services.
- * - **Middleware**: Like `Transformation`, but each direction receives the full
- *   parsing `Effect` and can intercept, retry, or modify the pipeline.
- * - **Getter**: A single-direction transform `Option<E> → Effect<Option<T>, Issue, R>`
- *   (see `SchemaGetter`).
- * - **flip()**: Swaps decode and encode, turning a `Transformation<T, E>` into
- *   `Transformation<E, T>`.
- * - **compose()**: Chains two transformations left-to-right on the decode side
- *   and right-to-left on the encode side.
- * - **passthrough**: The identity transformation — no conversion in either
- *   direction.
- *
- * ## Common tasks
- *
- * - Convert values purely (sync, infallible) → {@link transform}
- * - Convert values with possible failure → {@link transformOrFail}
- * - Handle optional/missing keys → {@link transformOptional}
- * - Build from existing Getters → {@link make}
- * - No-op identity transformation → {@link passthrough}
- * - Subtype/supertype coercion → {@link passthroughSupertype}, {@link passthroughSubtype}
- * - Trim/case strings → {@link trim}, {@link toLowerCase}, {@link toUpperCase}, {@link capitalize}, {@link uncapitalize}, {@link snakeToCamel}
- * - Parse key-value strings → {@link splitKeyValue}
- * - Coerce string ↔ number/bigint → {@link numberFromString}, {@link bigintFromString}
- * - Coerce string ↔ Date/Duration → {@link dateFromString}, {@link durationFromString}
- * - Decode durations → {@link durationFromNanos}, {@link durationFromMillis}
- * - Wrap nullable/optional as Option → {@link optionFromNullOr}, {@link optionFromOptionalKey}, {@link optionFromOptional}
- * - Parse URLs → {@link urlFromString}
- * - Base64 ↔ Uint8Array → {@link uint8ArrayFromBase64String}
- * - Base64 ↔ string → {@link stringFromBase64String}
- * - URI component ↔ string → {@link stringFromUriComponent}
- * - JSON string ↔ unknown → {@link fromJsonString}
- * - FormData/URLSearchParams ↔ unknown → {@link fromFormData}, {@link fromURLSearchParams}
- * - Check if a value is a Transformation → {@link isTransformation}
- *
- * ## Gotchas
- *
- * - `Transformation` operates on individual values; `Middleware` wraps the
- *   entire parsing Effect. Choose accordingly.
- * - `passthrough` requires `T === E` by default. Use `{ strict: false }` to
- *   bypass, or use {@link passthroughSupertype} / {@link passthroughSubtype}.
- * - String transformations like `trim`, `toLowerCase`, and `toUpperCase` use
- *   `passthrough` on the encode side — they are lossy and do not round-trip.
- * - `durationFromNanos` encode can fail if the Duration cannot be represented
- *   as a `bigint`.
- *
- * ## Quickstart
- *
- * **Example** (Defining a custom transformation with Schema.decodeTo)
+ * Builds two-way conversions used by schemas.
  *
- * ```ts
- * import { Schema, SchemaTransformation } from "effect"
- *
- * const CentsFromDollars = Schema.Number.pipe(
- *   Schema.decodeTo(
- *     Schema.Number,
- *     SchemaTransformation.transform({
- *       decode: (dollars) => dollars * 100,
- *       encode: (cents) => cents / 100
- *     })
- *   )
- * )
- * ```
- *
- * ## See also
- *
- * - {@link Transformation} — the core bidirectional transformation class
- * - {@link Middleware} — effect-pipeline-level transformation
- * - {@link transform} — most common constructor
- * - {@link passthrough} — identity transformation
+ * A `Transformation<T, E>` describes how to decode an encoded value into a
+ * decoded value and how to encode it back again. Schema APIs use
+ * transformations to connect two representations, such as a string and a
+ * number, a JSON value and a richer TypeScript value, or a form field and an
+ * application value. This module includes transformation and middleware types,
+ * constructors for pure or effectful conversions, and common conversions used
+ * by the Schema module.
  *
  * @since 4.0.0
  */
@@ -1112,7 +1039,7 @@ const encodeJsonError = (
 ): JsonError => {
   const encoded: JsonError = {
     name: input.name,
-    message: input.message
+    message: typeof input.message === "string" ? input.message : ""
   }
   if (options?.includeStack && typeof input.stack === "string") {
     encoded.stack = input.stack

package/src/SchemaUtils.ts

@@ -1,37 +1,9 @@
 /**
- * Focused schema helpers for patterns that are useful but too specialized for
- * the main `Schema` module. This module currently covers the case where a
- * native JavaScript or TypeScript class should decode from a plain struct and
- * still remain an instance of that class after decoding.
- *
- * **Mental model**
- *
- * - {@link getNativeClassSchema} starts from a constructor and a struct schema
- *   for the encoded shape.
- * - Decoding validates the struct, then calls the constructor with the decoded
- *   fields as one object.
- * - Encoding treats the instance as the encoded object, so instance properties
- *   must line up with the struct fields.
- * - The resulting schema preserves class identity through `Schema.instanceOf`
- *   while retaining a plain-object representation for encoded data.
- *
- * **Common tasks**
- *
- * - Add schema support to an existing native class without rewriting it as a
- *   `Schema.Class`.
- * - Decode structured data into a `Data.Error` subclass or another class whose
- *   constructor accepts a props object.
- * - Encode class instances back to the struct shape expected at API, storage,
- *   or transport boundaries.
- *
- * **Gotchas**
- *
- * - Constructors that expect positional arguments are not compatible unless
- *   they also accept the decoded props object.
- * - Private fields or computed getters are not enough for encoding; the
- *   instance must expose properties compatible with the provided struct schema.
- * - Prefer `Schema.Class` or `Schema.ErrorClass` when you control the class
- *   definition and do not need to adapt an existing constructor.
+ * Small helpers for schema patterns that are too specialized for the main
+ * `Schema` module. The current helper builds a schema for an existing class:
+ * the encoded input is checked with a struct schema, decoding calls the class
+ * constructor with the decoded properties, and the final value remains an
+ * instance of that class.
  *
  * @since 4.0.0
  */

package/src/Scope.ts

@@ -1,46 +1,11 @@
 /**
- * The `Scope` module manages resource lifetimes by collecting finalizers and
- * running them when a scope is closed. It is the low-level mechanism behind
- * scoped resource acquisition: acquire work registers cleanup with the current
- * scope, and closing the scope releases those resources with the same `Exit`
- * that ended the scoped workflow.
- *
- * Scopes are useful when code needs explicit control over a lifetime boundary,
- * for example when building services, sharing a resource across multiple
- * effects, or wiring lower-level infrastructure. Most application code can use
- * higher-level scoped APIs, but this module exposes the primitives those APIs
- * are built from.
- *
- * **Mental model**
- *
- * - A {@link Scope} is a mutable lifetime boundary that can accept finalizers
- *   while open and run them when closed
- * - A {@link Closeable} scope can be closed explicitly with {@link close} or
- *   automatically around an effect with {@link use}
- * - Sequential scopes run finalizers one after another in reverse registration
- *   order; parallel scopes run registered finalizers concurrently
- * - {@link addFinalizer} registers cleanup that ignores the closing exit, while
- *   {@link addFinalizerExit} registers cleanup that can inspect it
- * - {@link fork} creates a child scope whose lifetime is connected to a parent
- *   scope
- *
- * **Common tasks**
- *
- * - Create scopes with {@link make} or the lower-level {@link makeUnsafe}
- * - Provide an existing scope to an effect with {@link provide}
- * - Register cleanup with {@link addFinalizer} or {@link addFinalizerExit}
- * - Create child scopes with {@link fork} or {@link forkUnsafe}
- * - Close scopes with {@link close}, or run and close with {@link use}
+ * Controls how long resources stay open.
  *
- * **Gotchas**
- *
- * - Closing a scope is itself an `Effect`; finalizers run only when that effect
- *   is executed
- * - Adding a finalizer to an already closed scope runs the finalizer
- *   immediately with the stored exit value
- * - The unsafe constructors and closing helpers are for low-level integration;
- *   prefer the effectful APIs when ordinary Effect code can express the
- *   lifetime
+ * A scope is a lifetime boundary. Code can register cleanup effects on it, and
+ * closing the scope runs those cleanups with the `Exit` value that ended the
+ * work. Most application code uses higher-level APIs such as `Effect.scoped`
+ * and `Layer`, while this module is useful when code needs to create, provide,
+ * fork, close, or inspect scopes directly.
  *
  * @since 2.0.0
  */

package/src/ScopedCache.ts

@@ -1,27 +1,12 @@
 /**
- * The `ScopedCache` module provides a cache for values that acquire scoped
- * resources during lookup. Each cached entry owns a `Scope`, so resources
- * created while computing a value stay alive for as long as that entry remains
- * cached and are released when the entry is removed.
- *
- * A `ScopedCache` is itself created inside a scope. Calls to {@link get} run the
- * lookup effect on cache misses, share the same in-flight lookup among
- * concurrent callers for the same key, and store the resulting exit according
- * to a time-to-live policy. Entries can be inserted manually with {@link set},
- * refreshed with {@link refresh}, inspected without triggering lookup with
- * {@link getOption}, and removed with {@link invalidate} or
- * {@link invalidateAll}. Capacity limits evict the oldest entries.
- *
- * **Lifecycle notes**
- *
- * - Entry scopes are closed when entries expire, are invalidated, are evicted,
- *   are replaced, or when the cache's owning scope closes
- * - Successful and failed lookup exits are both cached according to the
- *   configured TTL
- * - Expired entries may remain counted by {@link size} until a cache operation
- *   observes and removes them
- * - Once the owning scope closes, the cache is closed and lookup-style
- *   operations interrupt instead of acquiring new values
+ * Caches values that need scoped resource management.
+ *
+ * Each cached entry owns its own `Scope`, so resources opened while creating a
+ * value stay alive while that entry is cached and are released when the entry is
+ * removed. A `ScopedCache` also belongs to an outer scope, which closes all
+ * remaining entries when the cache is closed. Lookups for the same missing key
+ * share one in-progress effect, and entries can expire, be refreshed, be
+ * invalidated, or be evicted by capacity limits.
  *
  * @since 4.0.0
  */

package/src/ScopedRef.ts

@@ -1,23 +1,11 @@
 /**
- * The `ScopedRef` module provides a mutable reference for values that are tied
- * to scoped resources. Each value stored in a `ScopedRef` is acquired within its
- * own `Scope`, and replacing the value safely releases the resources associated
- * with the previous value.
+ * Stores a current value together with the scope that owns it.
  *
- * Use `ScopedRef` when an application needs to keep a current resource-backed
- * value, such as a live client, connection, subscription, or cached handle, and
- * later swap it for a newly acquired value without leaking the old resources.
- * Reads are simple, while updates are synchronized and resource-safe.
- *
- * **Gotchas**
- *
- * - A `ScopedRef` must itself be created and used within a `Scope`; when that
- *   scope closes, the currently stored value is finalized.
- * - Use {@link fromAcquire} or {@link set} for resourceful values so acquisition
- *   and finalization are tracked correctly.
- * - Use {@link make} only for values that do not acquire resources.
- * - Updating a `ScopedRef` waits for the replacement acquisition and old
- *   finalization to complete before returning.
+ * A `ScopedRef<A>` is useful for resource-backed values such as clients,
+ * connections, subscriptions, or handles. Replacing the value acquires the
+ * replacement in a new scope and releases the resources owned by the previous
+ * value. Reads can be effectful or synchronous, and updates are synchronized so
+ * only one replacement happens at a time.
  *
  * @since 2.0.0
  */

package/src/Semaphore.ts

@@ -1,34 +1,12 @@
 /**
- * The `Semaphore` module provides counting semaphores for limiting concurrent
- * access to shared resources. A semaphore owns a pool of permits; effects take
- * permits before running protected work and return them when the work exits.
- *
- * **Mental model**
- *
- * - The permit count is the maximum amount of guarded work that can run at once
- * - {@link withPermit} and {@link withPermits} acquire permits around one
- *   effect and release them on success, failure, or interruption
- * - {@link take} and {@link release} expose the lower-level protocol when
- *   acquisition and release cannot be scoped to one effect
- * - {@link resize} changes future availability while preserving permits that
- *   are already taken
- *
- * **Common tasks**
- *
- * - Create a semaphore: {@link make}, {@link makeUnsafe}
- * - Guard one effect: {@link withPermit}, {@link withPermits}
- * - Run only when permits are immediately available:
- *   {@link withPermitsIfAvailable}
- * - Manage permits manually: {@link take}, {@link release}, {@link releaseAll}
- * - Change capacity: {@link resize}
- *
- * **Gotchas**
- *
- * - Pending acquisitions wait until enough permits are available
- * - {@link withPermitsIfAvailable} never waits; it returns `Option.none` when
- *   the requested permits are not available immediately
- * - Manual {@link take} / {@link release} usage must keep permit counts
- *   balanced; prefer scoped helpers when possible
+ * Limits how many effects can use a shared resource at the same time.
+ *
+ * A `Semaphore` owns a number of permits. Work can run only after acquiring the
+ * permits it needs, and those permits are returned when the work finishes. This
+ * module includes constructors, automatic wrappers that acquire and release
+ * permits around an effect, manual permit operations, a non-waiting variant for
+ * work that should only run immediately, and resizing support for an existing
+ * semaphore.
  *
  * @since 4.0.0
  */

package/src/Sink.ts

@@ -1,34 +1,11 @@
 /**
- * The `Sink` module provides composable consumers for `Stream` values. A
- * `Sink<A, In, L, E, R>` pulls input elements of type `In`, may require
- * services `R`, may fail with `E`, and eventually produces a result `A` plus
- * any leftover input `L` that was read but not consumed.
+ * Consumes values from a `Stream` and produces one final result.
  *
- * **Mental model**
- *
- * - A sink is the terminal consumer used by `Stream.run`
- * - Sinks can consume zero, one, many, or all input elements before finishing
- * - Leftovers allow one sink to stop early without losing already-pulled input
- * - Sink composition preserves typed errors and service requirements
- * - Most sinks are built from `Channel` internally, but users compose them with
- *   the higher-level APIs in this module
- *
- * **Common tasks**
- *
- * - Create simple sinks: {@link succeed}, {@link fail}, {@link fromEffect}
- * - Fold input: {@link fold}
- * - Collect values: {@link collect}
- * - Count or drain input: {@link count}, {@link drain}
- * - Transform results: {@link map}, {@link mapEffect}, {@link as}
- * - Adapt input before consumption: {@link mapInput}, {@link mapInputEffect}
- *
- * **Gotchas**
- *
- * - A sink can finish before the stream is exhausted; check leftover-aware
- *   combinators when composing parsers or protocol decoders
- * - `In` is contravariant, so a sink that accepts broader input can be used
- *   where narrower input is expected
- * - Resource and service requirements are tracked in the `R` type parameter
+ * A `Sink` may read no input, a fixed amount of input, or keep reading until a
+ * condition is met. If it reads more than it needs, it can return leftovers so
+ * the stream can continue from those values. Sinks are used to collect, fold,
+ * search, count, or otherwise reduce streamed input, and they can be composed
+ * when a stream needs more than one consuming step.
  *
  * @since 2.0.0
  */

package/src/Stdio.ts

@@ -1,32 +1,13 @@
 /**
- * Service contract for process standard input, output, error output, and
- * command-line arguments.
- *
- * `Stdio` lets command-line programs depend on standard I/O through the Effect
+ * Service contract for command-line arguments and standard input, output, and
+ * error output. It lets programs depend on standard I/O through the Effect
  * environment instead of reading from or writing to global process handles
- * directly. The service exposes arguments as an `Effect`, stdout and stderr as
- * `Sink`s that accept strings or bytes, and stdin as a byte `Stream`.
- *
- * **Mental model**
- *
- * Application code describes what it needs from standard I/O, and a runtime
- * layer supplies the concrete streams. Platform packages provide real process
- * implementations, while tests can use `Stdio.layerTest` to replace only the
- * fields that matter for a scenario and keep the rest inert.
- *
- * **Common tasks**
- *
- * - Read command-line arguments from the service's `args` effect.
- * - Write text or bytes by running values into the service's `stdout()` or
- *   `stderr()` sinks.
- * - Consume `stdin` as a stream of `Uint8Array` chunks.
- * - Build deterministic tests with `Stdio.layerTest`.
- *
- * **Gotchas**
+ * directly.
  *
- * Standard I/O is a platform capability. Reads and writes can fail with
- * `PlatformError`, so handle failures in the Effect error channel instead of
- * assuming the process streams are always available.
+ * The service exposes arguments as an `Effect`, stdout and stderr as `Sink`s
+ * that accept strings or bytes, and stdin as a byte `Stream`. This module also
+ * provides a constructor for service values and a small test layer with
+ * overridable defaults.
  *
  * @since 4.0.0
  */

package/src/Stream.ts

@@ -1,83 +1,12 @@
 /**
- * The `Stream` module describes effectful sequences that may emit many values
- * over time. A `Stream<A, E, R>` can produce zero or more `A` values, fail with
- * an `E`, and require services from `R`; the Effect runtime handles
- * backpressure, interruption, scopes, and finalizers while the stream is being
- * consumed.
- *
- * Streams are useful for files, sockets, queues, subscriptions, paginated APIs,
- * background jobs, and any workflow where values should be processed
- * incrementally instead of loaded into memory all at once.
- *
- * **Mental model**
- *
- * - A stream is a lazy description; it does not run until consumed with
- *   {@link run}, {@link runCollect}, {@link runForEach}, or another `run*`
- *   function.
- * - Pulling drives evaluation. Operators request values from upstream, and the
- *   runtime propagates demand instead of pushing unbounded data downstream.
- * - Values are batched internally as chunks for throughput, while user-facing
- *   combinators still work with individual elements unless they mention chunks.
- * - `A` is the element type, `E` is the failure type, and `R` is the required
- *   service context.
- * - Composition mirrors `Effect`: use `pipe`, {@link map}, {@link flatMap},
- *   error handling, resource operators, and service provisioning.
- *
- * **Common tasks**
- *
- * - Create streams from values, effects, and collections with {@link make},
- *   {@link fromEffect}, {@link fromIterable}, and {@link fromQueue}.
- * - Transform or select values with {@link map}, {@link mapEffect},
- *   {@link flatMap}, {@link filter}, and {@link filterMap}.
- * - Combine streams with {@link concat}, {@link merge}, {@link zip},
- *   {@link race}, and {@link interleave}.
- * - Control size and timing with {@link take}, {@link drop}, {@link debounce},
- *   {@link throttle}, {@link grouped}, and {@link groupedWithin}.
- * - Handle failures with {@link catchCause}, {@link catchIf},
- *   {@link mapError}, {@link retry}, and {@link withExecutionPlan}.
- * - Connect to other protocols with {@link fromReadableStream},
- *   {@link toReadableStream}, {@link fromAsyncIterable}, {@link toQueue}, and
- *   {@link runIntoQueue}.
- * - Consume streams with {@link runCollect}, {@link runForEach},
- *   {@link runFold}, {@link runDrain}, or a {@link Sink.Sink}.
- *
- * **Quickstart**
- *
- * **Example** (Transforming and collecting values)
- *
- * ```ts
- * import { Effect, Stream } from "effect"
- *
- * const program = Stream.make(1, 2, 3).pipe(
- *   Stream.map((n) => n * 2),
- *   Stream.runCollect
- * )
- *
- * Effect.runPromise(program).then(console.log)
- * // [2, 4, 6]
- * ```
- *
- * **Gotchas**
- *
- * - A stream is not a collection. Constructors and operators build a
- *   description; effects run each time the stream is consumed.
- * - {@link runCollect} stores every emitted value in memory. Prefer
- *   {@link runForEach}, {@link runFold}, or a streaming sink for large or
- *   infinite streams.
- * - Operators such as {@link merge}, {@link race}, {@link broadcast}, and
- *   {@link share} introduce concurrency, so interruption and finalizer timing
- *   can matter.
- * - Reusing the same stream value does not share execution by itself. Use
- *   {@link share}, {@link broadcast}, queues, or external state when multiple
- *   consumers must observe one running producer.
- *
- * **See also**
- *
- * - {@link Effect.Effect} for single-result effectful programs.
- * - {@link Sink.Sink} for reusable stream consumers.
- * - {@link Channel.Channel} for the lower-level primitive behind streams.
- * - {@link Queue.Queue} and {@link PubSub.PubSub} for coordinating producers
- *   and consumers.
+ * Describes effectful sources that emit values over time.
+ *
+ * A `Stream<A, E, R>` can emit many `A` values, fail with `E`, and require
+ * services `R` while it is being consumed. Streams are useful for data that is
+ * pulled in steps, such as values from collections, queues, pubsubs, schedules,
+ * callbacks, async iterables, or platform streams. The APIs here cover the full
+ * stream lifecycle: create a stream, transform or combine it, control buffering
+ * and timing, handle failures, and finally consume it.
  *
  * @since 2.0.0
  */