effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/Combiner.ts

@@ -3,7 +3,7 @@
  *
  * 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 {@link Reducer} which extends `Combiner` with an
+ * (for that, see `Reducer` which extends `Combiner` with an
  * `initialValue`).
  *
  * ## Mental model
@@ -13,7 +13,7 @@
  * - **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 {@link Reducer} when you need one.
+ *   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`,
@@ -70,7 +70,7 @@ import type * as Order from "./Order.ts"
  *
  * **When to use**
  *
- * Use `Combiner` when you need to describe how two values of the same type
+ * Use when you need to describe how two values of the same type
  * merge, pass a reusable combining strategy to library functions like
  * `Struct.makeCombiner` or `Option.makeCombinerFailFast`, or define the
  * combining step for a `Reducer`.
@@ -93,6 +93,10 @@ import type * as Order from "./Order.ts"
 export interface Combiner<A> {
   /**
    * Combines two values into a new value.
+   *
+   * **When to use**
+   *
+   * Use to merge two values according to this combining strategy.
    */
   readonly combine: (self: A, that: A) => A
 }
@@ -102,7 +106,7 @@ export interface Combiner<A> {
  *
  * **When to use**
  *
- * Use this when you have a custom combining operation that is not covered by
+ * Use when you have a custom combining operation that is not covered by
  * the built-in constructors (`min`, `max`, `first`, `last`, `constant`).
  *
  * **Details**
@@ -134,7 +138,7 @@ export function make<A>(combine: (self: A, that: A) => A): Combiner<A> {
  *
  * **When to use**
  *
- * Use this when the "right" value should act as the accumulator side, or when
+ * Use when the "right" value should act as the accumulator side, or when
  * you want to reverse the natural direction of a non-commutative combiner such
  * as string concatenation.
  *
@@ -168,7 +172,7 @@ export function flip<A>(combiner: Combiner<A>): Combiner<A> {
  *
  * **When to use**
  *
- * Use this when you want to accumulate the minimum value across a collection or
+ * Use when you want to accumulate the minimum value across a collection or
  * build a `Reducer` that tracks the running minimum.
  *
  * **Details**
@@ -204,7 +208,7 @@ export function min<A>(order: Order.Order<A>): Combiner<A> {
  *
  * **When to use**
  *
- * Use this when you want to accumulate the maximum value across a collection or
+ * Use when you want to accumulate the maximum value across a collection or
  * build a `Reducer` that tracks the running maximum.
  *
  * **Details**
@@ -239,7 +243,7 @@ export function max<A>(order: Order.Order<A>): Combiner<A> {
  *
  * **When to use**
  *
- * Use this when you want "first write wins" semantics while merging values, or
+ * Use when you want "first write wins" semantics while merging values, or
  * when the combining logic should keep the existing value.
  *
  * **Details**
@@ -271,7 +275,7 @@ export function first<A>(): Combiner<A> {
  *
  * **When to use**
  *
- * Use this when you want "last write wins" semantics while merging values, or
+ * Use when you want "last write wins" semantics while merging values, or
  * when each new value should replace the accumulator.
  *
  * **Details**
@@ -304,7 +308,7 @@ export function last<A>(): Combiner<A> {
  *
  * **When to use**
  *
- * Use this when a combiner should produce a fixed result regardless of input,
+ * Use when a combiner should produce a fixed result regardless of input,
  * or when a generic API needs a combiner but the combined value is
  * predetermined.
  *
@@ -339,7 +343,7 @@ export function constant<A>(a: A): Combiner<A> {
  *
  * **When to use**
  *
- * Use this when you are building delimited strings (CSV, paths, etc.) by
+ * Use when you are building delimited strings (CSV, paths, etc.) by
  * repeated combination, or when you need to inject a fixed separator between
  * accumulated values.
  *

package/src/Config.ts

@@ -93,7 +93,7 @@ const TypeId = "~effect/Config"
  *
  * **When to use**
  *
- * - Runtime type-checking before calling `.parse()` on an unknown value.
+ * Use when runtime type-checking before calling `.parse()` on an unknown value.
  * - Distinguishing a `Config` from a plain value inside {@link unwrap}.
  *
  * **Example** (Type guard)
@@ -115,7 +115,7 @@ export const isConfig = (u: unknown): u is Config<unknown> => Predicate.hasPrope
  *
  * **When to use**
  *
- * - Match on `error.cause._tag` to distinguish source failures from
+ * Use when match on `error.cause._tag` to distinguish source failures from
  *   validation failures.
  * - Pass to {@link fail} to create a Config that always errors.
  *
@@ -150,6 +150,11 @@ export class ConfigError {
 /**
  * A recipe for extracting a typed value `T` from a `ConfigProvider`.
  *
+ * **When to use**
+ *
+ * Use to describe typed configuration that can be parsed from a provider or
+ * yielded inside `Effect.gen`.
+ *
  * **Details**
  *
  * Key members:
@@ -190,7 +195,7 @@ const Proto = {
  *
  * **When to use**
  *
- * - Building a custom config that cannot be expressed with {@link schema} or
+ * Use to build a custom config that cannot be expressed with {@link schema} or
  *   the convenience constructors.
  * - Composing configs programmatically.
  *
@@ -234,7 +239,7 @@ export function make<T>(
  *
  * **When to use**
  *
- * - Post-processing a config value (e.g. trimming, uppercasing, wrapping).
+ * Use when post-processing a config value (e.g. trimming, uppercasing, wrapping).
  * - The transformation cannot fail. Use {@link mapOrFail} if it can.
  *
  * **Details**
@@ -265,7 +270,7 @@ export const map: {
    *
    * **When to use**
    *
-   * - Post-processing a config value (e.g. trimming, uppercasing, wrapping).
+   * Use when post-processing a config value (e.g. trimming, uppercasing, wrapping).
    * - The transformation cannot fail. Use {@link mapOrFail} if it can.
    *
    * **Details**
@@ -296,7 +301,7 @@ export const map: {
    *
    * **When to use**
    *
-   * - Post-processing a config value (e.g. trimming, uppercasing, wrapping).
+   * Use when post-processing a config value (e.g. trimming, uppercasing, wrapping).
    * - The transformation cannot fail. Use {@link mapOrFail} if it can.
    *
    * **Details**
@@ -331,7 +336,7 @@ export const map: {
  *
  * **When to use**
  *
- * - Validating or converting a config value where the transformation can
+ * Use to validate or converting a config value where the transformation can
  *   produce a `ConfigError` (e.g. parsing a URL, checking a range).
  *
  * **Details**
@@ -359,7 +364,7 @@ export const mapOrFail: {
    *
    * **When to use**
    *
-   * - Validating or converting a config value where the transformation can
+   * Use to validate or converting a config value where the transformation can
    *   produce a `ConfigError` (e.g. parsing a URL, checking a range).
    *
    * **Details**
@@ -387,7 +392,7 @@ export const mapOrFail: {
    *
    * **When to use**
    *
-   * - Validating or converting a config value where the transformation can
+   * Use to validate or converting a config value where the transformation can
    *   produce a `ConfigError` (e.g. parsing a URL, checking a range).
    *
    * **Details**
@@ -419,7 +424,7 @@ export const mapOrFail: {
  *
  * **When to use**
  *
- * - Trying an alternative config source when the primary one errors.
+ * Use when trying an alternative config source when the primary one errors.
  * - Providing environment-specific overrides.
  *
  * **Details**
@@ -451,7 +456,7 @@ export const orElse: {
    *
    * **When to use**
    *
-   * - Trying an alternative config source when the primary one errors.
+   * Use when trying an alternative config source when the primary one errors.
    * - Providing environment-specific overrides.
    *
    * **Details**
@@ -483,7 +488,7 @@ export const orElse: {
    *
    * **When to use**
    *
-   * - Trying an alternative config source when the primary one errors.
+   * Use when trying an alternative config source when the primary one errors.
    * - Providing environment-specific overrides.
    *
    * **Details**
@@ -519,7 +524,7 @@ export const orElse: {
  *
  * **When to use**
  *
- * - Grouping related configs into a tuple or named struct.
+ * Use when grouping related configs into a tuple or named struct.
  *
  * **Details**
  *
@@ -599,7 +604,7 @@ function isMissingDataOnly(issue: Issue.Issue): boolean {
  *
  * **When to use**
  *
- * - Making a config key optional with a sensible default.
+ * Use when making a config key optional with a sensible default.
  *
  * **Details**
  *
@@ -635,7 +640,7 @@ export const withDefault: {
    *
    * **When to use**
    *
-   * - Making a config key optional with a sensible default.
+   * Use when making a config key optional with a sensible default.
    *
    * **Details**
    *
@@ -671,7 +676,7 @@ export const withDefault: {
    *
    * **When to use**
    *
-   * - Making a config key optional with a sensible default.
+   * Use when making a config key optional with a sensible default.
    *
    * **Details**
    *
@@ -720,7 +725,7 @@ export const withDefault: {
  *
  * **When to use**
  *
- * - A config key may or may not be present and you want to handle both
+ * Use when a config key may or may not be present and you want to handle both
  *   cases explicitly.
  *
  * **Gotchas**
@@ -750,6 +755,14 @@ export const option = <A>(self: Config<A>): Config<Option.Option<A>> =>
 /**
  * Extracts the successfully parsed value type from a `Config`.
  *
+ * **When to use**
+ *
+ * Use to derive the parsed value type from an existing `Config` value when
+ * declaring reusable config-driven types.
+ *
+ * @see {@link Config} for the config type whose parsed value is extracted
+ * @see {@link Effect.Success} for extracting the success type from any `Effect`
+ *
  * @category utility types
  * @since 2.5.0
  */
@@ -761,7 +774,7 @@ export type Success<T> = [T] extends [Config<infer A>] ? A : never
  *
  * **When to use**
  *
- * - Typing the input of {@link unwrap} so callers can pass either a `Config`
+ * Use when typing the input of {@link unwrap} so callers can pass either a `Config`
  *   or a record of `Config`s.
  *
  * **Details**
@@ -788,7 +801,7 @@ type IsPlainObject<A> = [A] extends [Record<string, any>]
  *
  * **When to use**
  *
- * - Accepting config from callers who may pass either a single `Config` or a
+ * Use when accepting config from callers who may pass either a single `Config` or a
  *   record of individual `Config`s.
  *
  * **Details**
@@ -926,7 +939,7 @@ const recur: (
  *
  * **When to use**
  *
- * - Reading structured or validated config (structs, arrays, unions, branded
+ * Use when reading structured or validated config (structs, arrays, unions, branded
  *   types, etc.).
  * - All convenience constructors (`string`, `number`, …) delegate to this.
  *
@@ -996,8 +1009,8 @@ export const FalseValues = Schema.Literals(["false", "no", "off", "0", "n"])
  *
  * **When to use**
  *
- * - Pass to {@link schema} for custom paths, or use the {@link boolean}
- *   convenience constructor.
+ * Use when passing to {@link schema} for custom paths, or use the
+ * {@link boolean} convenience constructor.
  *
  * **Details**
  *
@@ -1024,8 +1037,8 @@ export const Boolean = Schema.Literals([...TrueValues.literals, ...FalseValues.l
  *
  * **When to use**
  *
- * - Pass to {@link schema} for custom paths, or use the {@link port}
- *   convenience constructor.
+ * Use when passing to {@link schema} for custom paths, or use the {@link port}
+ * convenience constructor.
  *
  * @see {@link port} – convenience constructor
  *
@@ -1039,8 +1052,8 @@ export const Port = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 655
  *
  * **When to use**
  *
- * - Pass to {@link schema} for custom paths, or use the {@link logLevel}
- *   convenience constructor.
+ * Use when passing to {@link schema} for custom paths, or use the
+ * {@link logLevel} convenience constructor.
  *
  * **Details**
  *
@@ -1060,7 +1073,7 @@ export const LogLevel = Schema.Literals(LogLevel_.values)
  *
  * **When to use**
  *
- * - Reading key-value maps from a single env var (e.g. OpenTelemetry
+ * Use when reading key-value maps from a single env var (e.g. OpenTelemetry
  *   resource attributes).
  *
  * **Details**
@@ -1120,7 +1133,7 @@ export const Record = <K extends Schema.Record.Key, V extends Schema.Top>(key: K
  *
  * **When to use**
  *
- * - Inside {@link orElse} to re-raise a specific error.
+ * Use when inside {@link orElse} to re-raise a specific error.
  * - Testing error handling paths.
  *
  * @category constructors
@@ -1136,7 +1149,7 @@ export function fail(err: SourceError | Schema.SchemaError) {
  *
  * **When to use**
  *
- * - Providing a hardcoded constant inside {@link orElse}.
+ * Use when providing a hardcoded constant inside {@link orElse}.
  * - Testing.
  *
  * **Example** (Constant fallback)
@@ -1161,7 +1174,7 @@ export function succeed<T>(value: T) {
  *
  * **When to use**
  *
- * - Reading a single string env var or config key.
+ * Use when reading a single string env var or config key.
  *
  * **Details**
  *
@@ -1192,11 +1205,15 @@ export function string(name?: string) {
  * Creates a config for a non-empty string value. Fails if the value is an
  * empty string.
  *
+ * **When to use**
+ *
+ * Use to read a string config value that must contain at least one character.
+ *
  * **Details**
  *
  * Shortcut for `Config.schema(Schema.NonEmptyString, name)`.
  *
- * @see {@link string} – allows empty strings
+ * @see {@link string} for allowing empty strings
  *
  * @category constructors
  * @since 3.7.0
@@ -1208,12 +1225,16 @@ export function nonEmptyString(name?: string) {
 /**
  * Creates a config for a numeric value (including `NaN`, `Infinity`).
  *
+ * **When to use**
+ *
+ * Use to read a numeric config value when `NaN` and `Infinity` are acceptable.
+ *
  * **Details**
  *
  * Shortcut for `Config.schema(Schema.Number, name)`.
  *
- * @see {@link finite} – rejects `NaN` and `Infinity`
- * @see {@link int} – only integers
+ * @see {@link finite} for rejecting `NaN` and `Infinity`
+ * @see {@link int} for accepting only integers
  *
  * @category constructors
  * @since 2.0.0
@@ -1225,12 +1246,16 @@ export function number(name?: string) {
 /**
  * Creates a config for a finite number (rejects `NaN` and `Infinity`).
  *
+ * **When to use**
+ *
+ * Use to read a numeric config value that must be finite.
+ *
  * **Details**
  *
  * Shortcut for `Config.schema(Schema.Finite, name)`.
  *
- * @see {@link number} – allows `NaN` and `Infinity`
- * @see {@link int} – only integers
+ * @see {@link number} for accepting `NaN` and `Infinity`
+ * @see {@link int} for accepting only integers
  *
  * @category constructors
  * @since 4.0.0
@@ -1242,12 +1267,16 @@ export function finite(name?: string) {
 /**
  * Creates a config for an integer value. Rejects floats.
  *
+ * **When to use**
+ *
+ * Use to read a numeric config value that must be an integer.
+ *
  * **Details**
  *
  * Shortcut for `Config.schema(Schema.Int, name)`.
  *
- * @see {@link number} – allows any number
- * @see {@link port} – integers in 1–65535
+ * @see {@link number} for accepting any number
+ * @see {@link port} for accepting only integers in `1` through `65535`
  *
  * @category constructors
  * @since 4.0.0
@@ -1259,6 +1288,10 @@ export function int(name?: string) {
 /**
  * Creates a config that only accepts a specific literal value.
  *
+ * **When to use**
+ *
+ * Use to restrict a config to a single, specific literal value.
+ *
  * **Details**
  *
  * Shortcut for `Config.schema(Schema.Literal(literal), name)`.
@@ -1271,6 +1304,7 @@ export function int(name?: string) {
  * const env = Config.literal("production", "ENV")
  * ```
  *
+ * @see {@link literals} – accepts multiple literal values
  * @category constructors
  * @since 2.0.0
  */
@@ -1281,6 +1315,10 @@ export function literal<L extends AST.LiteralValue>(literal: L, name?: string) {
 /**
  * Creates a config that only accepts one of the specified literal values.
  *
+ * **When to use**
+ *
+ * Use to restrict a config to a fixed set of allowed literal values.
+ *
  * **Details**
  *
  * Shortcut for `Config.schema(Schema.Literals(literals), name)`.
@@ -1293,6 +1331,8 @@ export function literal<L extends AST.LiteralValue>(literal: L, name?: string) {
  * const env = Config.literals(["development", "production"], "ENV")
  * ```
  *
+ * @see {@link literal} for accepting one specific literal value
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -1304,6 +1344,10 @@ export function literals<const L extends ReadonlyArray<AST.LiteralValue>>(litera
  * Creates a config for a boolean value parsed from common string
  * representations.
  *
+ * **When to use**
+ *
+ * Use to read boolean flags from string-like config sources.
+ *
  * **Details**
  *
  * Shortcut for `Config.schema(Config.Boolean, name)`.
@@ -1333,6 +1377,8 @@ export function literals<const L extends ReadonlyArray<AST.LiteralValue>>(litera
  * // Output: true
  * ```
  *
+ * @see {@link Boolean} for the underlying boolean codec
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1344,6 +1390,10 @@ export function boolean(name?: string) {
  * Creates a config for a `Duration` value parsed from a human-readable
  * string.
  *
+ * **When to use**
+ *
+ * Use to read time duration settings such as timeouts, intervals, or TTLs.
+ *
  * **Details**
  *
  * Shortcut for `Config.schema(Schema.DurationFromString, name)`.
@@ -1373,6 +1423,8 @@ export function boolean(name?: string) {
  * // Output: Duration { _tag: "millis", value: 10000 }
  * ```
  *
+ * @see {@link schema} for decoding configuration values with a custom codec
+ *
  * @category constructors
  * @since 2.5.0
  */
@@ -1383,6 +1435,10 @@ export function duration(name?: string) {
 /**
  * Creates a config for a port number (integer in 1–65535).
  *
+ * **When to use**
+ *
+ * Use to read network port settings that must be valid port numbers.
+ *
  * **Details**
  *
  * Shortcut for `Config.schema(Config.Port, name)`.
@@ -1409,6 +1465,9 @@ export function duration(name?: string) {
  * // Output: 8080
  * ```
  *
+ * @see {@link int} for integer config values outside the port range
+ * @see {@link Port} for the underlying port codec
+ *
  * @category constructors
  * @since 3.16.0
  */
@@ -1419,6 +1478,10 @@ export function port(name?: string) {
 /**
  * Creates a config for a log level string.
  *
+ * **When to use**
+ *
+ * Use to read Effect log-level settings from configuration.
+ *
  * **Details**
  *
  * Shortcut for `Config.schema(Config.LogLevel, name)`.
@@ -1448,6 +1511,8 @@ export function port(name?: string) {
  * // Output: "Info"
  * ```
  *
+ * @see {@link LogLevel} for the underlying log-level codec
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1459,6 +1524,11 @@ export function logLevel(name?: string) {
  * Creates a config for a redacted string value. The parsed result is wrapped
  * in a `Redacted` container that hides the value from logs and `toString`.
  *
+ * **When to use**
+ *
+ * Use to read secret string settings that should not be exposed in logs or
+ * string output.
+ *
  * **Details**
  *
  * Shortcut for `Config.schema(Schema.Redacted(Schema.String), name)`.
@@ -1485,6 +1555,8 @@ export function logLevel(name?: string) {
  * // Output: <redacted>
  * ```
  *
+ * @see {@link string} for non-secret string settings
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1495,6 +1567,14 @@ export function redacted(name?: string) {
 /**
  * Creates a config for a `URL` value parsed from a string.
  *
+ * **When to use**
+ *
+ * Use to read configuration values that must be valid URL strings.
+ *
+ * **Details**
+ *
+ * This is a shortcut for `Config.schema(Schema.URL, name)`.
+ *
  * **Gotchas**
  *
  * Fails if the string cannot be parsed by the `URL` constructor.
@@ -1535,6 +1615,8 @@ export function redacted(name?: string) {
  * // }
  * ```
  *
+ * @see {@link schema} for decoding configuration values with a custom codec
+ *
  * @category constructors
  * @since 3.11.0
  */
@@ -1545,6 +1627,10 @@ export function url(name?: string) {
 /**
  * Creates a config for a `Date` value parsed from a string.
  *
+ * **When to use**
+ *
+ * Use to read date settings that must parse to valid `Date` values.
+ *
  * **Details**
  *
  * Shortcut for `Config.schema(Schema.DateValid, name)`.
@@ -1577,7 +1663,7 @@ export function date(name?: string) {
  *
  * **When to use**
  *
- * - Grouping related config keys under a common namespace (e.g.
+ * Use when grouping related config keys under a common namespace (e.g.
  *   `"database"`, `"redis"`).
  * - Building reusable config fragments that callers nest at different paths.
  *
@@ -1632,7 +1718,7 @@ export const nested: {
    *
    * **When to use**
    *
-   * - Grouping related config keys under a common namespace (e.g.
+   * Use when grouping related config keys under a common namespace (e.g.
    *   `"database"`, `"redis"`).
    * - Building reusable config fragments that callers nest at different paths.
    *
@@ -1687,7 +1773,7 @@ export const nested: {
    *
    * **When to use**
    *
-   * - Grouping related config keys under a common namespace (e.g.
+   * Use when grouping related config keys under a common namespace (e.g.
    *   `"database"`, `"redis"`).
    * - Building reusable config fragments that callers nest at different paths.
    *