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

package/src/Logger.ts

@@ -1,85 +1,11 @@
 /**
- * The `Logger` module defines the logging model used by the Effect runtime and
- * provides constructors for formatting, routing, batching, and installing
- * loggers. A `Logger<Message, Output>` receives each runtime log event as an
- * {@link Options} value and transforms it into an output such as a string,
- * structured object, JSON line, console write, file write, or trace span event.
- *
- * **Mental model**
- *
- * - Effect programs emit log events with APIs such as `Effect.log`,
- *   `Effect.logInfo`, `Effect.logWarning`, and `Effect.logError`
- * - Each event contains a message, log level, cause, fiber, and timestamp
- * - Loggers are ordinary values created with {@link make} and installed with
- *   {@link layer}
- * - Multiple loggers can be active at once by providing a layer with several
- *   logger values
- * - Formatter loggers such as {@link formatLogFmt}, {@link formatStructured},
- *   and {@link formatJson} return formatted data without writing it anywhere
- * - Console loggers such as {@link consolePretty}, {@link consoleLogFmt},
- *   {@link consoleStructured}, and {@link consoleJson} write formatted output
- *   to the active Effect console
- *
- * **Log output structure**
- *
- * Built-in formatters include the log level, timestamp, fiber identifier, and
- * logged message. When present, they also include the pretty-printed cause,
- * active log annotations, and active log spans. Structured and JSON loggers keep
- * these fields as machine-readable data, while logfmt and pretty loggers render
- * them as human-readable text.
- *
- * **Common tasks**
- *
- * - Create a custom logger: {@link make}
- * - Transform logger output: {@link map}
- * - Write formatter output to the console: {@link withConsoleLog},
- *   {@link withConsoleError}, {@link withLeveledConsole}
- * - Use built-in console loggers: {@link consolePretty}, {@link consoleLogFmt},
- *   {@link consoleStructured}, {@link consoleJson}
- * - Use built-in formatter loggers: {@link formatSimple}, {@link formatLogFmt},
- *   {@link formatStructured}, {@link formatJson}
- * - Batch logger output before flushing to a sink: {@link batched}
- * - Write string logger output to a file: {@link toFile}
- * - Preserve trace correlation by including {@link tracerLogger}
- * - Install or replace loggers for an effect: {@link layer}
- *
- * **Gotchas**
- *
- * - {@link layer} replaces the current logger set by default; pass
- *   `mergeWithExisting: true` when adding loggers to the existing runtime
- *   loggers
- * - Formatter loggers only produce values; wrap them with console, file, batch,
- *   or custom sink loggers when output should be written somewhere
- * - {@link batched} and {@link toFile} are scoped; keep their scope open while
- *   logs are being emitted so buffered entries can flush reliably
- * - {@link toFile} accepts only loggers that output strings, so pair it with
- *   string formatters such as {@link formatJson} or {@link formatLogFmt}
- * - The default runtime logger set includes {@link tracerLogger}; replacing
- *   loggers without merging may remove automatic log-to-trace-span recording
- *
- * **Quickstart**
- *
- * **Example** (Installing a JSON console logger)
+ * Defines loggers and log-event data for Effect programs.
  *
- * ```ts
- * import { Effect, Logger } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   yield* Effect.logInfo("request started", { method: "GET", path: "/users" })
- *   yield* Effect.logError("request failed", { status: 500 })
- * }).pipe(
- *   Effect.annotateLogs("service", "users-api"),
- *   Effect.withLogSpan("http.request"),
- *   Effect.provide(Logger.layer([Logger.consoleJson]))
- * )
- * ```
- *
- * **See also**
- *
- * - {@link make} for defining custom loggers
- * - {@link layer} for installing loggers
- * - {@link formatJson} and {@link consoleJson} for structured production logs
- * - {@link consolePretty} for readable local logs
+ * A `Logger<Message, Output>` receives each log event as `Options` and turns it
+ * into output such as a formatted string, structured object, console write,
+ * file write, JSON line, or trace span event. This module also includes active
+ * logger references, console routing helpers, built-in formatters, batching,
+ * file logging, and layers for installing loggers.
  *
  * @since 2.0.0
  */

package/src/ManagedRuntime.ts

@@ -1,41 +1,11 @@
 /**
- * The `ManagedRuntime` module provides a way to build a reusable runtime from
- * a `Layer` and use it to run effects that require the services produced by
- * that layer. A `ManagedRuntime<R, ER>` owns the lifecycle of the layer-built
- * resources, caches the resulting `Context<R>`, and exposes runners for
- * integrating Effect programs with JavaScript entry points.
- *
- * **Mental model**
- *
- * - A managed runtime is created from a `Layer` with {@link make}
- * - The layer is built lazily the first time the runtime is used
- * - The built context is cached and reused for subsequent effect executions
- * - Resources acquired by the layer are owned by the runtime's internal scope
- * - Disposing the runtime closes that scope and releases all managed resources
- * - Effects run through the runtime receive the layer's services automatically
- *
- * **Common tasks**
- *
- * - Create a runtime from application services: {@link make}
- * - Run an effect as a `Promise`: {@link ManagedRuntime.runPromise}
- * - Run an effect and keep its `Exit`: {@link ManagedRuntime.runPromiseExit}
- * - Fork an effect into a `Fiber`: {@link ManagedRuntime.runFork}
- * - Bridge callback-style APIs: {@link ManagedRuntime.runCallback}
- * - Run synchronous effects at program boundaries: {@link ManagedRuntime.runSync},
- *   {@link ManagedRuntime.runSyncExit}
- * - Access the cached service context: {@link ManagedRuntime.context}
- * - Release layer resources: {@link ManagedRuntime.dispose},
- *   {@link ManagedRuntime.disposeEffect}
+ * Runs many effects against services built once from a `Layer`.
  *
- * **Gotchas**
- *
- * - Always dispose a managed runtime when it is no longer needed, especially
- *   when the layer acquires resources such as connections, servers, or files
- * - Layer construction errors are included in the error channel of runtime
- *   runners, so `ER` is combined with the effect's own error type
- * - `runSync` can only execute effects without asynchronous boundaries; use
- *   `runPromise` for asynchronous programs
- * - After disposal, the runtime cannot be reused
+ * A `ManagedRuntime` builds the services from a layer, keeps those services
+ * available for repeated effect runs, and releases acquired resources when it
+ * is disposed. This module includes the runtime type, a constructor, a guard,
+ * and runners for connecting Effect programs to JavaScript entry points such as
+ * promises, callbacks, and synchronous code.
  *
  * @since 2.0.0
  */

package/src/Match.ts

@@ -1,46 +1,12 @@
 /**
- * Pattern matching for TypeScript values, predicates, and tagged unions.
- *
- * `Match` turns branching logic into a matcher that is built from ordered
- * cases and finished with an explicit finalizer. Use `Match.type` to define a
- * reusable matcher for a type, or `Match.value` to classify one value
- * immediately. Cases can match literal values, predicates, object patterns,
- * discriminators, tags, or negated patterns.
- *
- * **Mental model**
- *
- * A matcher checks cases in the order they are added and evaluates the handler
- * for the first match. Type matchers produce a function that can be reused with
- * different inputs, while value matchers already contain the input value. As
- * cases are added, the type system tracks which inputs remain unmatched, so
- * `Match.exhaustive` is only available when every remaining case has been
- * handled.
- *
- * **Common tasks**
- *
- * - Use `Match.type<Union>()` when a branch table should be reusable and
- *   exhaustiveness-checked.
- * - Use `Match.value(value)` when a single value should be matched immediately.
- * - Use `Match.tag`, `Match.tags`, or `Match.discriminator` for discriminated
- *   unions and domain objects with tag fields.
- * - Use `Match.orElse`, `Match.option`, or `Match.result` when unmatched input
- *   should be handled explicitly instead of requiring full exhaustiveness.
- *
- * **Example** (Matching a tagged union)
- *
- * ```ts
- * import { Match } from "effect"
- *
- * type Event =
- *   | { readonly _tag: "UserCreated"; readonly id: string }
- *   | { readonly _tag: "UserDeleted"; readonly id: string }
- *
- * const describe = Match.type<Event>().pipe(
- *   Match.tag("UserCreated", (event) => `created ${event.id}`),
- *   Match.tag("UserDeleted", (event) => `deleted ${event.id}`),
- *   Match.exhaustive
- * )
- * ```
+ * Builds pattern matchers for TypeScript values.
+ *
+ * `Match` lets you add ordered cases and then finish them with a result,
+ * fallback, `Option`, or exhaustive check. Use `Match.type` to define a
+ * reusable matcher for a type, or `Match.value` to match one value immediately.
+ * Cases can match literal values, predicates, object shapes, tags, negated
+ * patterns, and common checks such as strings, numbers, records, and class
+ * instances.
  *
  * @since 4.0.0
  */

package/src/Metric.ts

@@ -1,85 +1,12 @@
 /**
- * The `Metric` module provides tools for defining, updating, tagging, and
- * reading application metrics from Effect programs. A `Metric<Input, State>`
- * accepts typed input values and aggregates them into a typed state that can be
- * read directly or exported from a snapshot.
- *
- * **Mental model**
- *
- * - A metric has an identifier, a type, an optional description, optional attributes, and mutable aggregate state
- * - Use counters for cumulative values such as requests, errors, retries, or bytes processed
- * - Use gauges for point-in-time values that can rise or fall, such as active connections or queue size
- * - Use frequencies to count occurrences of discrete string values, such as status codes or action names
- * - Use histograms to bucket numeric observations and inspect count, min, max, and sum
- * - Use summaries to calculate quantiles over a bounded, time-based observation window
- * - Metrics are updated from effects with {@link update} and {@link modify}, and read with {@link value}
- * - Attributes tag metrics with key-value dimensions so the same logical metric can be grouped by service, endpoint, method, or other labels
- * - Snapshots capture the currently registered metrics and their aggregate states for reporting or export
- *
- * **Common tasks**
- *
- * - Create counters: {@link counter}
- * - Create gauges: {@link gauge}
- * - Create frequencies: {@link frequency}
- * - Create histograms: {@link histogram}, {@link linearBoundaries}, {@link exponentialBoundaries}
- * - Create summaries: {@link summary}, {@link summaryWithTimestamp}
- * - Measure effect duration: {@link timer}
- * - Update a metric: {@link update}
- * - Apply relative updates where supported: {@link modify}
- * - Read one metric: {@link value}
- * - Tag a metric: {@link withAttributes}
- * - Transform accepted input values: {@link mapInput}
- * - Record a constant input for repeated events: {@link withConstantInput}
- * - Inspect all registered metrics: {@link snapshot}, {@link dump}
- * - Enable fiber runtime metrics: {@link enableRuntimeMetrics}
- *
- * **Gotchas**
- *
- * - Counter and gauge metrics can use `number` inputs by default or `bigint` inputs with the `bigint` option
- * - Incremental counters ignore negative updates; use non-incremental counters only when decreases are meaningful
- * - {@link update} sets a gauge to an absolute value, while {@link modify} changes it relative to its current value
- * - Histogram buckets are cumulative and depend on the boundaries supplied when the metric is created
- * - Summary quantiles are calculated from the configured sliding window, so old observations expire
- * - Prefer low-cardinality attributes; using unbounded values such as request IDs can create too many metric series
- *
- * **Quickstart**
- *
- * **Example** (Creating and updating metrics)
- *
- * ```ts
- * import { Effect, Metric } from "effect"
- *
- * const requestCount = Metric.counter("http_requests_total", {
- *   description: "Total number of HTTP requests"
- * })
- *
- * const responseTime = Metric.histogram("http_response_time", {
- *   description: "HTTP response time in milliseconds",
- *   boundaries: Metric.linearBoundaries({ start: 0, width: 50, count: 20 })
- * })
- *
- * const handleRequest = Effect.gen(function*() {
- *   yield* Metric.update(
- *     Metric.withAttributes(requestCount, {
- *       endpoint: "/api/users",
- *       method: "GET"
- *     }),
- *     1
- *   )
- *
- *   yield* Metric.update(responseTime, 125)
- *
- *   return yield* Metric.value(requestCount)
- * })
- * ```
- *
- * **See also**
- *
- * - {@link counter} / {@link gauge} / {@link frequency} for common metric types
- * - {@link histogram} / {@link summary} for distribution metrics
- * - {@link update} / {@link modify} / {@link value} for working with metric state
- * - {@link withAttributes} for adding dimensions
- * - {@link snapshot} for exporting all registered metric values
+ * Records and reads measurements from Effect programs.
+ *
+ * A `Metric<Input, State>` accepts typed update values and stores an aggregated
+ * state that can be read directly or included in a snapshot. Metrics are used
+ * for counters, gauges, frequencies, histograms, summaries, and timers. This
+ * module includes metric constructors, update and read helpers, attributes,
+ * histogram boundaries, registry snapshots, text dumps, and controls for
+ * enabling runtime metrics.
  *
  * @since 2.0.0
  */

package/src/MutableHashMap.ts

@@ -1,40 +1,11 @@
 /**
- * `MutableHashMap` is an in-place key-value map with fast lookup, insertion,
- * removal, clearing, and iteration. It combines a native `Map` for ordinary
- * JavaScript keys with hash buckets for keys that implement Effect `Equal` /
- * `Hash`, so callers can mix referential and structural lookup in the same
- * collection.
+ * Stores key/value entries in a mutable hash map.
  *
- * **Mental model**
- *
- * - `MutableHashMap<K, V>` stores entries on a single mutable map instance
- * - {@link set}, {@link remove}, and {@link clear} mutate that instance and
- *   return it for convenient piping
- * - Keys that implement `Equal` / `Hash` are matched structurally through hash
- *   buckets; other keys use JavaScript map semantics
- * - The map is iterable as `[key, value]` pairs and reports size in O(1)
- *
- * **Common tasks**
- *
- * - Create maps: {@link empty}, {@link make}, {@link fromIterable}
- * - Read entries: {@link get}, {@link has}, {@link size}
- * - Mutate entries: {@link set}, {@link modify}, {@link remove}, {@link clear}
- * - Narrow unknown values: {@link isMutableHashMap}
- *
- * **Gotchas**
- *
- * - This data structure is intentionally mutable; share it only when callers
- *   agree on ownership
- * - Mutating a structural key after insertion can make future lookups fail if
- *   its equality or hash changes
- * - Iteration follows the underlying storage order and should not be used as a
- *   sorting guarantee
- *
- * **Performance**
- *
- * - Lookup, insertion, removal, clearing, and size are O(1) on average
- * - Hash collisions can make key lookup and removal O(n)
- * - Iteration is O(n)
+ * `MutableHashMap` updates the same collection in place and supports fast
+ * lookup, insertion, removal, clearing, and iteration. It combines a native
+ * `Map` for ordinary JavaScript keys with hash buckets for keys that implement
+ * Effect `Equal` and `Hash`, so callers can mix reference-based and structural
+ * lookup in the same collection.
  *
  * @since 2.0.0
  */

package/src/MutableHashSet.ts

@@ -1,70 +1,12 @@
 /**
- * `MutableHashSet` is an in-place hash set for storing unique values with fast
- * membership checks, insertion, removal, clearing, and iteration. It is built on
- * {@link MutableHashMap}: each set value is stored as a map key, so uniqueness
+ * Stores unique values in a mutable hash set.
+ *
+ * `MutableHashSet` updates the same collection in place and supports fast
+ * membership checks, insertion, removal, clearing, and iteration. It is built
+ * on `MutableHashMap`: each set value is stored as a map key, so uniqueness
  * follows the same hashing and equality rules as the underlying mutable hash
  * map.
  *
- * **Mental model**
- *
- * - `MutableHashSet<V>` is a mutable collection of unique values of type `V`
- * - {@link add}, {@link remove}, and {@link clear} mutate the same set instance
- * - Duplicate values are ignored according to Effect equality and hashing
- *   semantics
- * - Values that implement `Equal` / `Hash` can be compared structurally;
- *   primitive values and ordinary object references use the underlying hash map
- *   behavior
- * - The set is iterable, so `for...of` and `Array.from(set)` can inspect the
- *   current values
- *
- * **Common tasks**
- *
- * - Create an empty set: {@link empty}
- * - Create from values or an iterable: {@link make}, {@link fromIterable}
- * - Add, remove, and clear values: {@link add}, {@link remove}, {@link clear}
- * - Check membership and size: {@link has}, {@link size}
- * - Narrow unknown values: {@link isMutableHashSet}
- *
- * **Gotchas**
- *
- * - This data structure is intentionally mutable; keep ownership clear if the
- *   same set is shared by multiple callers
- * - Mutating operations return the same set instance for convenient piping
- * - Do not use iteration order as a sorting or presentation guarantee
- * - Use immutable collection modules when callers need persistent snapshots
- *
- * **Performance**
- *
- * - Add, membership checks, and removal are O(1) on average
- * - Hash collisions can make those operations O(n)
- * - Clearing and reading size are O(1)
- * - Iteration is O(n)
- *
- * **Quickstart**
- *
- * **Example** (Tracking unique values)
- *
- * ```ts
- * import { MutableHashSet } from "effect"
- *
- * const set = MutableHashSet.make("alice", "bob", "alice")
- *
- * MutableHashSet.add(set, "carol")
- * MutableHashSet.remove(set, "bob")
- *
- * console.log(MutableHashSet.has(set, "alice"))
- * // Output: true
- *
- * console.log(MutableHashSet.size(set))
- * // Output: 2
- * ```
- *
- * **See also**
- *
- * - {@link MutableHashMap} for the mutable key-value structure underneath
- * - {@link empty}, {@link make}, and {@link fromIterable} for construction
- * - {@link add}, {@link remove}, and {@link has} for core set operations
- *
  * @since 2.0.0
  */
 import { format } from "./Formatter.ts"

package/src/MutableList.ts

@@ -1,50 +1,10 @@
 /**
- * The `MutableList` module provides a mutable linked list for accumulating,
- * ordering, inspecting, and draining values with efficient operations at both
- * ends of the list.
- *
- * A `MutableList<A>` stores values in linked buckets of arrays. Appending adds
- * values to the tail, prepending adds values to the head, and taking removes
- * values from the head. Unlike persistent collections, every mutation updates
- * the list object in place: operations such as {@link append}, {@link prepend},
- * {@link take}, {@link takeN}, {@link clear}, {@link filter}, and {@link remove}
- * change the same `MutableList` instance and update its `length`.
- *
- * **Mental model**
- *
- * - `MutableList<A>` is a stateful container with `head`, `tail`, and `length`
- * - Values are consumed from the head with {@link take}, {@link takeN}, or
- *   {@link takeAll}
- * - {@link append} and {@link appendAll} preserve FIFO queue order for normal
- *   producer-consumer use cases
- * - {@link prepend} and {@link prependAll} place values before the current
- *   contents, which is useful for priority work or restoring items to the front
- * - {@link toArray} and {@link toArrayN} copy values without modifying the list
- * - The `head` and `tail` bucket fields are exposed for advanced use, but most
- *   code should treat them as implementation details
- *
- * **Common tasks**
- *
- * - Create an empty list: {@link make}
- * - Add one value: {@link append}, {@link prepend}
- * - Add many values: {@link appendAll}, {@link prependAll}
- * - Drain one value: {@link take}
- * - Drain many values: {@link takeN}, {@link takeAll}
- * - Inspect without draining: {@link toArrayN}, {@link toArray}
- * - Reset the list: {@link clear}
- * - Mutate contents in place: {@link filter}, {@link remove}
- *
- * **Gotchas**
- *
- * - `MutableList` is intentionally mutable; sharing a list means sharing its
- *   changing state
- * - {@link take} returns the {@link Empty} symbol when the list has no value, so
- *   compare with `MutableList.Empty` instead of relying on falsy checks
- * - {@link appendAllUnsafe} and {@link prependAllUnsafe} may reuse the provided
- *   array when `mutable` is `true`; only enable that optimization when callers
- *   will not keep using the array independently
- * - {@link remove} uses JavaScript strict equality semantics, not structural
- *   equality
+ * Mutable lists for collecting ordered values and draining them from the front.
+ * A `MutableList<A>` can append values to the end, prepend values to the
+ * beginning, take one or more values from the front, inspect its contents as an
+ * array, filter values, remove values, and clear itself. All operations update
+ * the same list object in place and keep its `length` field current. Taking
+ * from an empty list returns the `Empty` symbol.
  *
  * @since 4.0.0
  */

package/src/MutableRef.ts

@@ -1,34 +1,11 @@
 /**
- * The `MutableRef` module provides a small synchronous container for mutable
- * state. A `MutableRef<A>` stores one current value of type `A`, exposes that
- * value through `.current`, and offers pipeable helpers for reading, replacing,
- * and transforming the value in place.
- *
- * **Mental model**
- *
- * - `MutableRef<A>` is a stable reference whose `.current` field may change over time
- * - Reads and writes are synchronous and return immediately
- * - `set`, `update`, `increment`, `decrement`, and `toggle` mutate the same reference in place
- * - `getAnd*` helpers return the previous value, while `*AndGet` helpers return the new value
- * - `compareAndSet` updates only when the current value is equal to the expected value using `Equal.equals`
- * - A `MutableRef` is useful for local mutable state, but it does not make updates transactional or effectful
- *
- * **Common tasks**
- *
- * - Create a reference: {@link make}
- * - Read the current value: {@link get} or `.current`
- * - Replace the current value: {@link set}, {@link setAndGet}, {@link getAndSet}
- * - Transform the current value: {@link update}, {@link updateAndGet}, {@link getAndUpdate}
- * - Coordinate conditional replacement: {@link compareAndSet}
- * - Work with counters: {@link increment}, {@link decrement}, {@link incrementAndGet}, {@link decrementAndGet}
- * - Work with boolean flags: {@link toggle}
- *
- * **Gotchas**
- *
- * - All updates are imperative mutations; aliases to the same `MutableRef` observe the same changing value
- * - Updating object or array values does not clone them unless the update function creates a new value
- * - `compareAndSet` compares with Effect equality semantics, not only JavaScript reference equality
- * - For state that must participate in `Effect` workflows, interruption, or fiber coordination, prefer higher-level Effect data types
+ * Stores synchronous mutable state in a small reference object.
+ *
+ * A `MutableRef<A>` stores one current value and exposes it through `.current`.
+ * Unlike `Ref`, its operations are synchronous and update the same object in
+ * place. This module includes pipeable helpers for reading, setting, comparing,
+ * and updating the value, plus numeric increment/decrement helpers and a
+ * boolean toggle helper.
  *
  * @since 2.0.0
  */

package/src/Newtype.ts

@@ -1,65 +1,12 @@
 /**
- * Lightweight wrapper types that prevent accidental mixing of structurally
- * identical values (e.g. `UserId` vs `OrderId`, both `string` at runtime).
- *
- * **Mental model**
- *
- * - **Newtype** — a compile-time wrapper around a **carrier** type (the
- *   underlying primitive or object). At runtime the value is unchanged; the
- *   tag exists only in the type system.
- * - **Key** — a unique string literal that distinguishes one newtype from
- *   another (e.g. `"Label"`, `"UserId"`).
- * - **Carrier** — the underlying type the newtype wraps (e.g. `string`,
- *   `number`).
- * - **Iso** — a lossless two-way conversion between a newtype and its carrier,
- *   created with {@link makeIso}. Use `iso.set(carrier)` to wrap and
- *   `iso.get(newtype)` to unwrap.
- *
- * **Common tasks**
- *
- * - Define a newtype → declare an `interface` extending
- *   `Newtype.Newtype<Key, Carrier>`
- * - Wrap / unwrap values → {@link makeIso} (returns an `Optic.Iso`)
- * - Unwrap only → {@link value}
- * - Lift an `Equivalence` → {@link makeEquivalence}
- * - Lift an `Order` → {@link makeOrder}
- * - Lift a `Combiner` → {@link makeCombiner}
- * - Lift a `Reducer` → {@link makeReducer}
- *
- * **Gotchas**
- *
- * - Newtypes are **purely compile-time**. There is zero runtime overhead;
- *   `value` and `makeIso` use identity casts.
- * - Two newtypes sharing the same key string will be assignable to each other.
- *   Choose unique key strings.
- * - A newtype value is **not** assignable to its carrier type without
- *   explicitly unwrapping via {@link value} or an iso.
- *
- * **Quickstart**
- *
- * **Example** (defining and using a newtype)
- *
- * ```ts
- * import { Newtype } from "effect"
- *
- * // 1. Define a newtype
- * interface Label extends Newtype.Newtype<"Label", string> {}
- *
- * // 2. Create an iso for wrapping/unwrapping
- * const labelIso = Newtype.makeIso<Label>()
- *
- * // 3. Wrap a raw string
- * const myLabel: Label = labelIso.set("hello")
- *
- * // 4. Unwrap back to string
- * const raw: string = labelIso.get(myLabel) // "hello"
- * ```
- *
- * **See also**
- *
- * - {@link Newtype} (the tagged interface)
- * - {@link makeIso} (wrap and unwrap)
- * - {@link value} (unwrap only)
+ * Creates compile-time-only wrappers around existing value types.
+ *
+ * A newtype lets TypeScript distinguish values with the same runtime shape, such
+ * as two different ids that are both strings. The tag exists only in the type
+ * system, so wrapping does not allocate a runtime object. This module includes
+ * the base `Newtype` interface, wrapping and unwrapping helpers, optics, and
+ * helpers for reusing carrier instances such as `Equivalence`, `Order`,
+ * `Combiner`, and `Reducer`.
  *
  * @since 4.0.0
  */