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

package/src/Combiner.ts

@@ -1,62 +1,11 @@
 /**
- * A module for combining two values of the same type into one.
+ * Defines reusable rules for merging two values of the same type.
  *
- * A `Combiner<A>` wraps a single binary function `(self: A, that: A) => A`.
- * It describes *how* two values merge but carries no initial/empty value
- * (for that, see `Reducer` which extends `Combiner` with an
- * `initialValue`).
- *
- * ## Mental model
- *
- * - **Combiner** – an object with a `combine(self, that)` method that returns
- *   a value of the same type.
- * - **Argument order** – `self` is the "left" / accumulator side, `that` is
- *   the "right" / incoming side.
- * - **No identity element** – unlike a monoid, a `Combiner` does not require
- *   a neutral element. Use `Reducer` when you need one.
- * - **Purity** – all combiners produced by this module are pure; they never
- *   mutate their arguments.
- * - **Composability** – combiners can be lifted into `Option`, `Struct`,
- *   `Tuple`, and other container types via helpers in those modules.
- *
- * ## Common tasks
- *
- * - Create a combiner from any binary function → {@link make}
- * - Swap argument order → {@link flip}
- * - Pick the smaller / larger of two values → {@link min} / {@link max}
- * - Always keep the first or last value → {@link first} / {@link last}
- * - Ignore both values and return a fixed result → {@link constant}
- * - Insert a separator between combined values → {@link intercalate}
- *
- * ## Gotchas
- *
- * - `min` and `max` require an `Order<A>`, not a raw comparator. Import from
- *   e.g. `Number.Order` or `String.Order`.
- * - `intercalate` is curried: call it with the separator first, then pass the
- *   base combiner.
- * - A `Reducer` (which adds `initialValue`) is also a valid `Combiner` — you
- *   can pass a `Reducer` anywhere a `Combiner` is expected.
- *
- * ## Quickstart
- *
- * **Example** (combining strings with a separator)
- *
- * ```ts
- * import { Combiner, String } from "effect"
- *
- * const csv = Combiner.intercalate(",")(String.ReducerConcat)
- *
- * console.log(csv.combine("a", "b"))
- * // Output: "a,b"
- *
- * console.log(csv.combine(csv.combine("a", "b"), "c"))
- * // Output: "a,b,c"
- * ```
- *
- * ## See also
- *
- * - {@link make} – the primary constructor
- * - {@link Combiner} – the core interface
+ * A `Combiner<A>` contains one operation, `combine(self, that)`, which returns
+ * the merged value. It does not define an initial value for reducing a
+ * collection; use a `Reducer` when you need that. This module includes the
+ * `Combiner` interface, a constructor for custom combining logic, and common
+ * combiners for choosing or ordering values.
  *
  * @since 4.0.0
  */

package/src/Config.ts

@@ -1,73 +1,9 @@
 /**
- * Declarative, schema-driven configuration loading. A `Config<T>` describes
- * how to read and validate a value of type `T` from a `ConfigProvider`. Configs
- * can be composed, transformed, and used directly as Effects.
- *
- * ## Mental model
- *
- * - **Config\<T\>** – a recipe for extracting a typed value from a
- *   `ConfigProvider`. Created via convenience constructors or {@link schema}.
- * - **ConfigProvider** – the backing data source (env vars, JSON, `.env`
- *   files). See the `ConfigProvider` module.
- * - **ConfigError** – wraps either a `SourceError` (provider I/O failure) or
- *   a `SchemaError` (validation / decoding failure).
- * - **parse** – instance method on every `Config` that takes a provider and
- *   returns `Effect<T, ConfigError>`.
- * - **Yieldable** – every `Config` can be yielded inside `Effect.gen`. It
- *   automatically resolves the current `ConfigProvider` from the context.
- *
- * ## Common tasks
- *
- * - Read a single env var → {@link string}, {@link number}, {@link boolean},
- *   {@link int}, {@link port}, {@link url}, {@link date}, {@link duration},
- *   {@link logLevel}, {@link redacted}
- * - Read a structured config → {@link schema} with a `Schema.Struct`
- * - Provide a default → {@link withDefault}
- * - Make a config optional → {@link option}
- * - Transform a value → {@link map} / {@link mapOrFail}
- * - Fall back on error → {@link orElse}
- * - Combine multiple configs → {@link all}
- * - Build from a `Schema.Codec` → {@link schema}
- * - Always succeed or fail → {@link succeed} / {@link fail}
- *
- * ## Gotchas
- *
- * - `withDefault` and `option` only apply when the error is caused by
- *   **missing data**. Validation errors (wrong type, out of range) still
- *   propagate.
- * - When yielded in `Effect.gen`, the config resolves using the current
- *   `ConfigProvider` service. To use a specific provider, call `.parse(provider)`
- *   instead.
- * - The `name` parameter on convenience constructors (e.g. `Config.string("HOST")`)
- *   sets the root path segment. Omit it when the config is part of a larger
- *   schema.
- *
- * ## Quickstart
- *
- * **Example** (Reading typed config from environment variables)
- *
- * ```ts
- * import { Config, ConfigProvider, Effect, Schema } from "effect"
- *
- * const AppConfig = Config.schema(
- *   Schema.Struct({
- *     host: Schema.String,
- *     port: Schema.Int
- *   }),
- *   "app"
- * )
- *
- * const provider = ConfigProvider.fromEnv({
- *   env: { app_host: "localhost", app_port: "8080" }
- * })
- *
- * // Effect.runSync(AppConfig.parse(provider))
- * // { host: "localhost", port: 8080 }
- * ```
- *
- * @see {@link schema} – build a Config from any Schema.Codec
- * @see {@link ConfigError} – the error type for config failures
- * @see {@link make} – low-level Config constructor
+ * Descriptions of configuration values that can be read from a
+ * `ConfigProvider`. A `Config<T>` explains which keys to read, how to decode
+ * and validate them, and how to combine defaults, fallbacks, nested paths, and
+ * multiple settings. Configs are also Effects, so they can be yielded in
+ * `Effect.gen` after a provider has been supplied.
  *
  * @since 4.0.0
  */

package/src/ConfigProvider.ts

@@ -1,79 +1,10 @@
 /**
- * Provides the data source layer for the `Config` module. A `ConfigProvider`
- * knows how to load raw configuration nodes from a backing store (environment
- * variables, JSON objects, `.env` files, file trees) and expose them through a
- * uniform `Node` interface that `Config` schemas consume.
- *
- * ## Mental model
- *
- * - **Node** – a discriminated union (`Value | Record | Array`) that describes
- *   what lives at a given path in the configuration tree.
- * - **Path** – an array of string or numeric segments used to address a node
- *   (e.g. `["database", "host"]`).
- * - **ConfigProvider** – an object with a `load(path)` method that resolves a
- *   path to a `Node | undefined`. Providers can be composed and transformed.
- * - **Context.Reference** – `ConfigProvider` is registered as a reference
- *   service that defaults to `fromEnv()`, so it works without explicit
- *   provision.
- * - **SourceError** – the typed error returned when a backing store is
- *   unreadable (I/O failure, permission error, etc.).
- *
- * ## Common tasks
- *
- * - Read from environment variables → {@link fromEnv}
- * - Read from a JSON / plain object → {@link fromUnknown}
- * - Parse a `.env` string → {@link fromDotEnvContents}
- * - Load a `.env` file → {@link fromDotEnv}
- * - Read from a directory tree → {@link fromDir}
- * - Build a custom provider → {@link make}
- * - Fall back to another provider → {@link orElse}
- * - Scope a provider under a prefix → {@link nested}
- * - Convert path segments to `CONSTANT_CASE` → {@link constantCase}
- * - Transform path segments arbitrarily → {@link mapInput}
- * - Install a provider as a Layer → {@link layer} / {@link layerAdd}
- *
- * ## Gotchas
- *
- * - `fromEnv` joins path segments with `_` for lookup **and** splits env var
- *   names on `_` to discover child keys. `DATABASE_HOST=x` is therefore
- *   accessible at both `["DATABASE_HOST"]` and `["DATABASE", "HOST"]`.
- * - Because of `_` splitting, querying a parent path like `["DATABASE"]`
- *   returns a `Record` node with child key `"HOST"`, even if no env var
- *   named `DATABASE` exists.
- * - When using `fromEnv` with schemas that use camelCase keys, pipe the
- *   provider through {@link constantCase} so `databaseHost` resolves to
- *   `DATABASE_HOST`.
- * - `orElse` only falls back when the primary provider returns `undefined`
- *   (path not found). It does **not** catch `SourceError`.
- * - `nested` prepends segments to the path *after* `mapInput` has run, so
- *   the order of composition matters.
- *
- * ## Quickstart
- *
- * **Example** (Reading config from environment variables)
- *
- * ```ts
- * import { Config, ConfigProvider, Effect } from "effect"
- *
- * const provider = ConfigProvider.fromEnv({
- *   env: { APP_PORT: "3000", APP_HOST: "localhost" }
- * })
- *
- * const port = Config.number("port")
- *
- * const program = port.parse(
- *   provider.pipe(
- *     ConfigProvider.nested("app"),
- *     ConfigProvider.constantCase
- *   )
- * )
- *
- * // Effect.runSync(program) // 3000
- * ```
- *
- * @see {@link make} – build a provider from a lookup function
- * @see {@link fromEnv} – the default provider backed by `process.env`
- * @see {@link fromUnknown} – provider backed by a plain JS object
+ * Data sources used by `Config` to load raw configuration values. A
+ * `ConfigProvider` reads paths from places such as environment variables,
+ * JavaScript objects, `.env` contents, or directories, and returns a uniform
+ * `Node` shape that config schemas can decode. The module also includes helpers
+ * for composing providers, changing paths, and installing providers through
+ * layers.
  *
  * @since 4.0.0
  */

package/src/Console.ts

@@ -1,75 +1,11 @@
 /**
- * The `Console` module provides a functional interface for console operations within
- * the Effect ecosystem. It offers type-safe logging, debugging, and console manipulation
- * capabilities with built-in support for testing and environment isolation.
+ * Wraps console operations in Effect.
  *
- * ## Key Features
- *
- * - **Type-safe logging**: All console operations return Effects for composability
- * - **Testable**: Mock console output for testing scenarios
- * - **Service-based**: Integrated with Effect's dependency injection system
- * - **Environment isolation**: Different console implementations per environment
- * - **Rich API**: Support for all standard console methods (log, error, debug, etc.)
- * - **Performance tracking**: Built-in timing and profiling capabilities
- *
- * ## Core Operations
- *
- * - **Basic logging**: `log`, `error`, `warn`, `info`, `debug`
- * - **Assertions**: `assert` for conditional logging
- * - **Grouping**: `group`, `groupCollapsed`, `groupEnd` for organized output
- * - **Timing**: `time`, `timeEnd`, `timeLog` for performance measurement
- * - **Data display**: `table`, `dir`, `dirxml` for structured data visualization
- * - **Utilities**: `clear`, `count`, `countReset`, `trace`
- *
- * **Example** (Logging basic messages)
- *
- * ```ts
- * import { Console, Effect } from "effect"
- *
- * // Basic logging
- * const program = Effect.gen(function*() {
- *   yield* Console.log("Hello, World!")
- *   yield* Console.error("Something went wrong")
- *   yield* Console.warn("This is a warning")
- *   yield* Console.info("Information message")
- * })
- * ```
- *
- * **Example** (Grouping timed logs)
- *
- * ```ts
- * import { Console, Effect } from "effect"
- *
- * // Grouped logging with timing
- * const debugProgram = Console.withGroup(
- *   Effect.gen(function*() {
- *     yield* Console.log("Step 1: Loading...")
- *     yield* Effect.sleep("100 millis")
- *
- *     yield* Console.log("Step 2: Processing...")
- *     yield* Effect.sleep("200 millis")
- *   }),
- *   { label: "Processing Data" }
- * )
- * ```
- *
- * **Example** (Displaying structured data)
- *
- * ```ts
- * import { Console, Effect } from "effect"
- *
- * // Data visualization and debugging
- * const dataProgram = Effect.gen(function*() {
- *   const users = [
- *     { id: 1, name: "Alice", age: 30 },
- *     { id: 2, name: "Bob", age: 25 }
- *   ]
- *
- *   yield* Console.table(users)
- *   yield* Console.dir(users[0], { depth: 2 })
- *   yield* Console.assert(users.length > 0, "Users array should not be empty")
- * })
- * ```
+ * The `Console` service exposes common console methods such as logging,
+ * warnings, errors, groups, counters, tables, and timers. Because console access
+ * goes through a service, programs can use custom console implementations in
+ * tests or other environments. This module also includes scoped helpers that
+ * close console groups or timers automatically.
  *
  * @since 2.0.0
  */

package/src/Context.ts

@@ -1,51 +1,12 @@
 /**
- * The `Context` module implements Effect's typed service environment. A
- * `Context<Services>` is an immutable collection of service implementations,
- * keyed by `Context.Service` or `Context.Reference` values. The type parameter
- * records which service identifiers are present so effects can require
- * dependencies without passing every implementation as an argument.
- *
- * **Mental model**
- *
- * - A service key is both a runtime identifier and a typed handle for one
- *   dependency
- * - `Context.Service` creates keys for dependencies that must be provided by
- *   the surrounding context
- * - `Context.Reference` creates keys that have a cached default value when no
- *   explicit implementation is stored
- * - A `Context` value stores implementations, while Effect fibers carry the
- *   active context used to satisfy service requirements
- * - Context operations such as {@link add}, {@link merge}, {@link pick}, and
- *   {@link omit} return new contexts instead of mutating the original one
- *
- * **Common tasks**
- *
- * - Create service keys: {@link Service}, {@link Reference}
- * - Build contexts: {@link empty}, {@link make}, {@link add}, {@link merge}
- * - Read services: {@link get}, {@link getOption}, {@link getOrElse}
- * - Keep or remove selected services: {@link pick}, {@link omit}
- *
- * **Example** (Building and reading a context)
- *
- * ```ts
- * import { Context } from "effect"
- *
- * const Logger = Context.Service<{ log: (message: string) => void }>("Logger")
- *
- * const context = Context.make(Logger, {
- *   log: (message) => console.log(message)
- * })
- *
- * const logger = Context.get(context, Logger)
- * logger.log("started")
- * ```
- *
- * **Gotchas**
- *
- * - The service key string is the runtime identity; reusing the same string for
- *   unrelated services makes them occupy the same slot
- * - `Context.Reference` defaults are used only when no explicit value is stored
- *   for that key
+ * Stores Effect services in typed maps.
+ *
+ * A `Context` holds service implementations under `Context.Service` or
+ * `Context.Reference` keys, and its type records which keys are present.
+ * Effects use contexts as their environment, so services can be provided once
+ * instead of passed through every function call. This module includes helpers
+ * for creating keys, building contexts, adding and reading services, merging
+ * contexts, and selecting or removing services.
  *
  * @since 4.0.0
  */

package/src/Cron.ts

@@ -1,45 +1,9 @@
 /**
- * The `Cron` module provides utilities for representing recurring calendar
- * schedules with cron expressions. A `Cron` value stores allowed seconds,
- * minutes, hours, days of month, months, weekdays, and an optional time zone,
- * then uses those constraints to test dates and find scheduled occurrences.
- *
- * **Mental model**
- *
- * - A cron schedule is a set of allowed values for each time field
- * - Expressions may use five fields (`minute hour day month weekday`) or six
- *   fields (`second minute hour day month weekday`); five-field expressions
- *   default seconds to `0`
- * - Each field supports `*`, comma-separated values, ranges, and step syntax
- * - Month and weekday fields support aliases such as `JAN`, `DEC`, `SUN`, and
- *   `MON`
- * - Empty internal field sets represent an unconstrained field, the same idea
- *   as `*`
- * - When both day-of-month and weekday are constrained, matching uses cron's
- *   inclusive behavior: either field may match
- *
- * **Common tasks**
- *
- * - Build directly from field constraints: {@link make}
- * - Parse expressions safely: {@link parse}
- * - Parse expressions and throw on invalid input: {@link parseUnsafe}
- * - Check whether a date satisfies a schedule: {@link match}
- * - Find adjacent scheduled dates: {@link next}, {@link prev}
- * - Iterate future scheduled dates: {@link sequence}
- * - Compare schedule constraints: {@link equals}, {@link Equivalence}
- * - Detect parse failures: {@link CronParseError}, {@link isCronParseError}
- *
- * **Gotchas**
- *
- * - Weekdays are numbered `0` through `6`, with `0` representing Sunday
- * - Months are numbered `1` through `12`, while JavaScript `Date` months are
- *   zero-based
- * - `*` normalizes to an empty set internally, so inspect schedules with the
- *   public helpers instead of assuming every allowed value is stored
- * - `next` and `prev` search strictly after or before the provided instant
- * - Time-zone-aware schedules account for daylight saving transitions; during
- *   a fall-back transition, repeated local times are emitted once when moving
- *   forward
+ * Utilities for recurring calendar schedules written as cron expressions or
+ * explicit field constraints. A `Cron` value stores allowed seconds, minutes,
+ * hours, days of month, months, weekdays, and an optional time zone. The module
+ * can create or parse schedules, compare them, test whether a date matches, and
+ * find previous or next scheduled occurrences.
  *
  * @since 2.0.0
  */

package/src/Crypto.ts

@@ -1,55 +1,11 @@
 /**
- * The `Crypto` module provides a platform-agnostic service for cryptographic
- * operations. Runtime packages such as `@effect/platform-node`,
- * `@effect/platform-bun`, and `@effect/platform-browser` provide concrete
- * implementations backed by the host platform's cryptography APIs.
+ * Defines a platform-independent service for cryptographic operations.
  *
- * Use `Crypto` for cryptographic randomness, UUID generation, random values,
- * and message digests. The base `Random` service is not cryptographically
- * secure unless you replace it with a cryptographically secure implementation.
- *
- * **Example** (Providing a test Crypto service)
- *
- * ```ts
- * import { Console, Crypto, Effect, Layer } from "effect"
- *
- * const TestCrypto = Layer.succeed(
- *   Crypto.Crypto,
- *   Crypto.make({
- *     randomBytes: (size) => new Uint8Array(size),
- *     digest: (_algorithm, data) => Effect.succeed(data)
- *   })
- * )
- *
- * const program = Effect.gen(function*() {
- *   const crypto = yield* Crypto.Crypto
- *   const id = yield* crypto.randomUUIDv4
- *   yield* Console.log(`Created id: ${id}`)
- * })
- *
- * Effect.runPromise(Effect.provide(program, TestCrypto))
- * ```
- *
- * **Example** (Generating random bytes)
- *
- * ```ts
- * import { Crypto, Effect, Layer } from "effect"
- *
- * const TestCrypto = Layer.succeed(
- *   Crypto.Crypto,
- *   Crypto.make({
- *     randomBytes: (size) => new Uint8Array(size),
- *     digest: (_algorithm, data) => Effect.succeed(data)
- *   })
- * )
- *
- * const program = Effect.gen(function*() {
- *   const crypto = yield* Crypto.Crypto
- *   return yield* crypto.randomBytes(32)
- * })
- *
- * Effect.runPromise(Effect.provide(program, TestCrypto))
- * ```
+ * Runtime packages provide concrete implementations backed by the host
+ * platform's cryptography APIs. This module defines the service interface and a
+ * constructor from random-byte and digest primitives. The service provides
+ * secure random bytes and numbers, UUIDv4 and UUIDv7 generation, shuffling, and
+ * SHA message digests.
  *
  * @since 4.0.0
  */

package/src/Data.ts

@@ -1,77 +1,10 @@
 /**
- * Immutable data constructors with discriminated-union support.
- *
- * The `Data` module provides base classes and factory functions for creating
- * immutable value types with a `_tag` field for discriminated unions.
- * It is the recommended way to define domain models, error types, and
- * lightweight ADTs in Effect applications.
- *
- * ## Mental model
- *
- * - **`Class`** — base class for plain immutable data. Extend it with a type
- *   parameter to declare the fields. Instances are `Pipeable`.
- * - **`TaggedClass`** — like `Class` but automatically adds a `readonly _tag`
- *   string literal field. Useful for single-variant types or ad-hoc tagged
- *   values.
- * - **`TaggedEnum`** (type) + **`taggedEnum`** (value) — define a multi-variant
- *   discriminated union from a simple record. `taggedEnum()` returns per-variant
- *   constructors plus `$is` / `$match` helpers.
- * - **`Error`** — like `Class` but extends `Cause.YieldableError`, so instances
- *   can be yielded inside `Effect.gen` to fail the effect.
- * - **`TaggedError`** — like `TaggedClass` but extends `Cause.YieldableError`.
- *   Works with `Effect.catchTag` for tag-based error recovery.
- *
- * ## Common tasks
- *
- * - Define a simple value class → {@link Class}
- * - Define a value class with a `_tag` → {@link TaggedClass}
- * - Define a discriminated union with constructors → {@link TaggedEnum} + {@link taggedEnum}
- * - Define a yieldable error → {@link Error}
- * - Define a yieldable tagged error → {@link TaggedError}
- * - Type-guard a tagged value → `$is` from {@link taggedEnum}
- * - Pattern-match on a tagged union → `$match` from {@link taggedEnum}
- *
- * ## Gotchas
- *
- * - Variant records passed to `TaggedEnum` must **not** contain a `_tag` key;
- *   the `_tag` is added automatically from the record key.
- * - When a class has no fields, the constructor argument is optional (`void`).
- * - `taggedEnum()` creates **plain objects**, not class instances. If you need
- *   class-based variants, use `TaggedClass` or `TaggedError` instead.
- * - `TaggedEnum.WithGenerics` supports up to 4 generic type parameters.
- * - `$is(tag)` only checks the `_tag` field, not the full structure. It is safe
- *   when the tag value is globally unique across your application and the value
- *   was produced by your constructors. For untrusted input, validate with
- *   the `Schema` module before using `$is`.
- *
- * ## Quickstart
- *
- * **Example** (tagged union with pattern matching)
+ * Defines helpers for small immutable data models.
  *
- * ```ts
- * import { Data } from "effect"
- *
- * type Shape = Data.TaggedEnum<{
- *   Circle: { readonly radius: number }
- *   Rect: { readonly width: number; readonly height: number }
- * }>
- * const { Circle, Rect, $match } = Data.taggedEnum<Shape>()
- *
- * const area = $match({
- *   Circle: ({ radius }) => Math.PI * radius ** 2,
- *   Rect: ({ width, height }) => width * height
- * })
- *
- * console.log(area(Circle({ radius: 5 })))
- * // 78.53981633974483
- * console.log(area(Rect({ width: 3, height: 4 })))
- * // 12
- * ```
- *
- * @see {@link Class} — plain immutable data class
- * @see {@link TaggedEnum} — discriminated union type
- * @see {@link taggedEnum} — discriminated union constructors
- * @see {@link TaggedError} — yieldable tagged error class
+ * This module helps create plain classes, tagged classes, tagged unions, and
+ * typed errors with readonly fields. Tagged values carry a `_tag` field, which
+ * makes them easy to narrow with pattern matching or simple checks. These
+ * helpers are commonly used for domain values and errors in Effect programs.
  *
  * @since 2.0.0
  */

package/src/DateTime.ts

@@ -1,52 +1,12 @@
 /**
- * The `DateTime` module provides immutable data types and utilities for working
- * with instants, UTC date-times, zoned date-times, and time zones. A
- * `DateTime` is always an absolute point in time, represented internally by
- * epoch milliseconds, and may also carry a `TimeZone` for zone-aware calendar
- * parts and formatting.
- *
- * **Mental model**
- *
- * - `DateTime` is a discriminated union: `Utc | Zoned`
- * - `Utc` stores an absolute instant without an associated time zone
- * - `Zoned` stores the same kind of absolute instant plus a `TimeZone`
- * - Time zones can be fixed offsets or named IANA zones such as `"Europe/Rome"`
- * - Comparison and ordering use the instant, so two values in different zones
- *   can still be equivalent
- * - Calendar parts and formatted output depend on whether you ask for UTC parts
- *   or zone-adjusted parts
- *
- * **Common tasks**
- *
- * - Construct values: {@link make}, {@link makeUnsafe}, {@link makeZoned}, {@link makeZonedUnsafe}
- * - Get the current instant: {@link now}, {@link nowInCurrentZone}
- * - Create time zones: {@link zoneMakeOffset}, {@link zoneMakeNamed}, {@link zoneFromString}
- * - Attach or change zones: {@link setZone}, {@link setZoneNamed}, {@link setZoneCurrent}, {@link toUtc}
- * - Convert to platform values or parts: {@link toDate}, {@link toDateUtc}, {@link toEpochMillis}, {@link toParts}, {@link toPartsUtc}
- * - Compare and bound values: {@link Equivalence}, {@link Order}, {@link distance}, {@link min}, {@link max}, {@link clamp}, {@link between}
- * - Transform values: {@link add}, {@link subtract}, {@link startOf}, {@link endOf}, {@link nearest}, {@link setParts}, {@link mutate}
- * - Format values: {@link format}, {@link formatUtc}, {@link formatLocal}, {@link formatIntl}, {@link formatIso}, {@link formatIsoZoned}
- * - Provide an application time zone: {@link CurrentTimeZone}, {@link withCurrentZone}, {@link layerCurrentZone}
- *
- * **Gotchas**
- *
- * - `make` and `makeZoned` return `Option`; unsafe constructors throw on invalid
- *   input
- * - `DateTime` equality is instant-based, not display-time-based
- * - `setZone` changes the zone used for local parts and formatting without
- *   changing the represented instant
- * - Use `adjustForTimeZone` with {@link makeZoned} when input parts should be
- *   interpreted as wall-clock time in the target zone
- * - Daylight-saving gaps and repeated local times are resolved with
- *   `Disambiguation`
- * - Prefer the Clock-backed {@link now} and `CurrentTimeZone` services in
- *   Effect workflows; unsafe helpers read from the host environment directly
- *
- * **See also**
- *
- * - {@link DateTime} for the UTC/zoned data model
- * - {@link TimeZone} for offset and named time-zone values
- * - {@link Disambiguation} for daylight-saving ambiguity handling
+ * Works with absolute instants, UTC date-times, zoned date-times, and time
+ * zones.
+ *
+ * A `DateTime` always represents an absolute point in time with epoch
+ * milliseconds. It may also carry a `TimeZone` for calendar parts, formatting,
+ * and zone-aware transformations. This module includes constructors, time-zone
+ * helpers, comparisons, date arithmetic, current-time effects, and formatting
+ * functions.
  *
  * @since 3.6.0
  */