effect 4.0.0-beta.70 → 4.0.0-beta.72

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)
@@ -111,11 +111,11 @@ const TypeId = "~effect/Config"
 export const isConfig = (u: unknown): u is Config<unknown> => Predicate.hasProperty(u, TypeId)
 
 /**
- * The error type produced when config loading or validation fails.
+ * Represents the error type produced when config loading or validation fails.
  *
  * **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,9 +195,8 @@ const Proto = {
  *
  * **When to use**
  *
- * - Building a custom config that cannot be expressed with {@link schema} or
- *   the convenience constructors.
- * - Composing configs programmatically.
+ * Use to build a custom config that cannot be expressed with {@link schema} or
+ * convenience constructors, or to compose configs programmatically.
  *
  * **Details**
  *
@@ -234,7 +238,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 +269,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 +300,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 +335,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 +363,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 +391,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**
@@ -415,11 +419,11 @@ export const mapOrFail: {
 })
 
 /**
- * Falls back to another config when parsing fails with a `ConfigError`.
+ * Provides a fallback config when parsing fails with a `ConfigError`.
  *
  * **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**
@@ -447,11 +451,11 @@ export const mapOrFail: {
  */
 export const orElse: {
   /**
-   * Falls back to another config when parsing fails with a `ConfigError`.
+   * Provides a fallback config when parsing fails with a `ConfigError`.
    *
    * **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**
@@ -479,11 +483,11 @@ export const orElse: {
    */
   <A2>(that: (error: ConfigError) => Config<A2>): <A>(self: Config<A>) => Config<A2 | A>
   /**
-   * Falls back to another config when parsing fails with a `ConfigError`.
+   * Provides a fallback config when parsing fails with a `ConfigError`.
    *
    * **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 +523,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 +603,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 +639,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 +675,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 +724,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 +754,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 +773,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 +800,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 +938,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.
  *
@@ -992,12 +1004,12 @@ export const TrueValues = Schema.Literals(["true", "yes", "on", "1", "y"])
 export const FalseValues = Schema.Literals(["false", "no", "off", "0", "n"])
 
 /**
- * A `Schema.Codec` for boolean values encoded as strings.
+ * Schema for boolean values encoded as strings.
  *
  * **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**
  *
@@ -1020,12 +1032,12 @@ export const Boolean = Schema.Literals([...TrueValues.literals, ...FalseValues.l
 )
 
 /**
- * A `Schema.Codec` for port numbers (integers in 1–65535).
+ * Schema for port numbers (integers in 1–65535).
  *
  * **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
  *
@@ -1035,12 +1047,12 @@ export const Boolean = Schema.Literals([...TrueValues.literals, ...FalseValues.l
 export const Port = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65535 }))
 
 /**
- * A `Schema.Codec` for `LogLevel` string literals.
+ * Schema for `LogLevel` string literals.
  *
  * **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**
  *
@@ -1055,12 +1067,12 @@ export const Port = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 655
 export const LogLevel = Schema.Literals(LogLevel_.values)
 
 /**
- * A `Schema.Codec` for key-value record types that can also be parsed from
+ * Schema for key-value record types that can also be parsed from
  * a flat comma-separated string.
  *
  * **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 +1132,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 +1148,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 +1173,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 +1204,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 +1224,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 +1245,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 +1266,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 +1287,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 +1303,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 +1314,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 +1330,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 +1343,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 +1376,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 +1389,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 +1422,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 +1434,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 +1464,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 +1477,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 +1510,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 +1523,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 +1554,8 @@ export function logLevel(name?: string) {
  * // Output: <redacted>
  * ```
  *
+ * @see {@link string} for non-secret string settings
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1495,6 +1566,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 +1614,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 +1626,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 +1662,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 +1717,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 +1772,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.
    *