effect 4.0.0-beta.74 → 4.0.0-beta.75

package/src/Chunk.ts

@@ -685,8 +685,16 @@ export const get: {
 )
 
 /**
- * Wraps an array into a chunk without copying, so mutating the source array can
- * mutate the chunk.
+ * Wraps an array into a chunk without copying.
+ *
+ * **When to use**
+ *
+ * Use when the input array can be shared with the resulting `Chunk` and avoiding
+ * a copy matters.
+ *
+ * **Gotchas**
+ *
+ * Mutating the source array after wrapping can mutate the resulting `Chunk`.
  *
  * **Example** (Creating chunks without copying arrays)
  *
@@ -709,8 +717,16 @@ export const fromArrayUnsafe = <A>(self: ReadonlyArray<A>): Chunk<A> =>
   self.length === 0 ? empty() : self.length === 1 ? of(self[0]) : makeChunk({ _tag: "IArray", array: self })
 
 /**
- * Wraps a non-empty array into a non-empty chunk without copying, so mutating
- * the source array can mutate the chunk.
+ * Wraps a non-empty array into a non-empty chunk without copying.
+ *
+ * **When to use**
+ *
+ * Use when the input array is already known to be non-empty, can be shared with
+ * the resulting `Chunk`, and avoiding a copy matters.
+ *
+ * **Gotchas**
+ *
+ * Mutating the source array after wrapping can mutate the resulting `Chunk`.
  *
  * **Example** (Creating non-empty chunks without copying arrays)
  *
@@ -732,7 +748,16 @@ export const fromNonEmptyArrayUnsafe = <A>(self: NonEmptyReadonlyArray<A>): NonE
   fromArrayUnsafe(self) as any
 
 /**
- * Gets an element unsafely, will throw on out of bounds
+ * Gets an element at the specified index without returning an `Option`.
+ *
+ * **When to use**
+ *
+ * Use when reading from a `Chunk` at an index known to be in bounds and direct
+ * element access is preferred over handling `Option.none`.
+ *
+ * **Gotchas**
+ *
+ * Throws if the index is out of bounds.
  *
  * **Example** (Accessing elements unsafely)
  *
@@ -753,7 +778,16 @@ export const fromNonEmptyArrayUnsafe = <A>(self: NonEmptyReadonlyArray<A>): NonE
  */
 export const getUnsafe: {
   /**
-   * Gets an element unsafely, will throw on out of bounds
+   * Gets an element at the specified index without returning an `Option`.
+   *
+   * **When to use**
+   *
+   * Use when reading from a `Chunk` at an index known to be in bounds and direct
+   * element access is preferred over handling `Option.none`.
+   *
+   * **Gotchas**
+   *
+   * Throws if the index is out of bounds.
    *
    * **Example** (Accessing elements unsafely)
    *
@@ -774,7 +808,16 @@ export const getUnsafe: {
    */
   (index: number): <A>(self: Chunk<A>) => A
   /**
-   * Gets an element unsafely, will throw on out of bounds
+   * Gets an element at the specified index without returning an `Option`.
+   *
+   * **When to use**
+   *
+   * Use when reading from a `Chunk` at an index known to be in bounds and direct
+   * element access is preferred over handling `Option.none`.
+   *
+   * **Gotchas**
+   *
+   * Throws if the index is out of bounds.
    *
    * **Example** (Accessing elements unsafely)
    *
@@ -828,8 +871,8 @@ export const getUnsafe: {
  *
  * **When to use**
  *
- * Use to add one element after the existing elements and get a non-empty
- * result.
+ * Use to add one element after the existing chunk elements and return a
+ * `NonEmptyChunk`.
  *
  * **Example** (Appending an element)
  *
@@ -858,8 +901,8 @@ export const append: {
    *
    * **When to use**
    *
-   * Use to add one element after the existing elements and get a non-empty
-   * result.
+   * Use to add one element after the existing chunk elements and return a
+   * `NonEmptyChunk`.
    *
    * **Example** (Appending an element)
    *
@@ -888,8 +931,8 @@ export const append: {
    *
    * **When to use**
    *
-   * Use to add one element after the existing elements and get a non-empty
-   * result.
+   * Use to add one element after the existing chunk elements and return a
+   * `NonEmptyChunk`.
    *
    * **Example** (Appending an element)
    *
@@ -2219,7 +2262,7 @@ export const flatten: <S extends Chunk<Chunk<any>>>(self: S) => Chunk.Flatten<S>
  *
  * **When to use**
  *
- * Use to divide a chunk into ordered, non-overlapping batches with at most `n`
+ * Use to divide a chunk into ordered, non-overlapping chunks with at most `n`
  * elements each.
  *
  * **Details**
@@ -2260,7 +2303,7 @@ export const chunksOf: {
    *
    * **When to use**
    *
-   * Use to divide a chunk into ordered, non-overlapping batches with at most `n`
+   * Use to divide a chunk into ordered, non-overlapping chunks with at most `n`
    * elements each.
    *
    * **Details**
@@ -2301,7 +2344,7 @@ export const chunksOf: {
    *
    * **When to use**
    *
-   * Use to divide a chunk into ordered, non-overlapping batches with at most `n`
+   * Use to divide a chunk into ordered, non-overlapping chunks with at most `n`
    * elements each.
    *
    * **Details**
@@ -2509,6 +2552,11 @@ export const head: <A>(self: Chunk<A>) => Option<A> = get(0)
 /**
  * Returns the first element of this chunk.
  *
+ * **When to use**
+ *
+ * Use when you know the chunk is non-empty and need the first element directly
+ * without handling `Option.none`.
+ *
  * **Gotchas**
  *
  * Throws an error if the chunk is empty.
@@ -2576,6 +2624,11 @@ export const last = <A>(self: Chunk<A>): Option<A> => get(self, self.length - 1)
 /**
  * Returns the last element of this chunk.
  *
+ * **When to use**
+ *
+ * Use when you know the chunk is non-empty and need the last element directly
+ * without handling `Option.none`.
+ *
  * **Gotchas**
  *
  * Throws an error if the chunk is empty.

package/src/Clock.ts

@@ -135,12 +135,12 @@ export interface Clock {
 }
 
 /**
- * Context reference for the current Clock service in the environment.
+ * Context reference for the active time service in the environment.
  *
  * **When to use**
  *
- * Use when you need to access or provide the full Clock service rather than a
- * single timestamp accessor.
+ * Use when you need to access or provide the full time service, including sleep
+ * operations, rather than a single timestamp accessor.
  *
  * **Example** (Accessing the Clock service)
  *

package/src/Combiner.ts

@@ -138,9 +138,8 @@ export function make<A>(combine: (self: A, that: A) => A): Combiner<A> {
  *
  * **When to use**
  *
- * 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.
+ * Use when you want the right-hand value to act as the accumulator, or need to
+ * reverse a non-commutative combiner such as string concatenation.
  *
  * **Details**
  *
@@ -243,8 +242,7 @@ export function max<A>(order: Order.Order<A>): Combiner<A> {
  *
  * **When to use**
  *
- * Use when you want "first write wins" semantics while merging values, or
- * when the combining logic should keep the existing value.
+ * Use when you want "first write wins" semantics while merging values.
  *
  * **Details**
  *
@@ -274,8 +272,7 @@ export function first<A>(): Combiner<A> {
  *
  * **When to use**
  *
- * Use when you want "last write wins" semantics while merging values, or
- * when each new value should replace the accumulator.
+ * Use when you want "last write wins" semantics while merging values.
  *
  * **Details**
  *
@@ -306,9 +303,8 @@ export function last<A>(): Combiner<A> {
  *
  * **When to use**
  *
- * 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.
+ * Use when you need a combiner that always returns a fixed value, including
+ * when a generic API requires a combiner but the result is predetermined.
  *
  * **Details**
  *
@@ -340,9 +336,9 @@ export function constant<A>(a: A): Combiner<A> {
  *
  * **When to use**
  *
- * 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.
+ * Use when you need to inject a fixed separator between accumulated values,
+ * such as when building delimited strings, paths, or CSV-like output by
+ * repeated combination.
  *
  * **Details**
  *

package/src/Config.ts

@@ -81,10 +81,10 @@ import * as Option from "./Option.ts"
 import * as Predicate from "./Predicate.ts"
 import * as Rec from "./Record.ts"
 import * as Schema from "./Schema.ts"
-import * as AST from "./SchemaAST.ts"
-import * as Issue from "./SchemaIssue.ts"
-import * as Parser from "./SchemaParser.ts"
-import * as Transformation from "./SchemaTransformation.ts"
+import * as SchemaAST from "./SchemaAST.ts"
+import * as SchemaIssue from "./SchemaIssue.ts"
+import * as SchemaParser from "./SchemaParser.ts"
+import * as SchemaTransformation from "./SchemaTransformation.ts"
 
 const TypeId = "~effect/Config"
 
@@ -93,8 +93,8 @@ const TypeId = "~effect/Config"
  *
  * **When to use**
  *
- * Use when runtime type-checking before calling `.parse()` on an unknown value.
- * - Distinguishing a `Config` from a plain value inside {@link unwrap}.
+ * Use when you need to distinguish a `Config` from an unknown value before
+ * calling `.parse` or {@link unwrap}.
  *
  * **Example** (Type guard)
  *
@@ -115,9 +115,7 @@ export const isConfig = (u: unknown): u is Config<unknown> => Predicate.hasPrope
  *
  * **When to use**
  *
- * 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.
+ * Use when you need to inspect config loading or validation failures.
  *
  * **Details**
  *
@@ -196,7 +194,7 @@ const Proto = {
  * **When to use**
  *
  * Use to build a custom config that cannot be expressed with {@link schema} or
- * convenience constructors, or to compose configs programmatically.
+ * convenience constructors, or compose configs programmatically.
  *
  * **Details**
  *
@@ -238,8 +236,8 @@ export function make<T>(
  *
  * **When to use**
  *
- * Use when post-processing a config value (e.g. trimming, uppercasing, wrapping).
- * - The transformation cannot fail. Use {@link mapOrFail} if it can.
+ * Use when you need to transform a parsed config value with a function that
+ * cannot fail.
  *
  * **Details**
  *
@@ -269,8 +267,8 @@ export const map: {
    *
    * **When to use**
    *
-   * Use when post-processing a config value (e.g. trimming, uppercasing, wrapping).
-   * - The transformation cannot fail. Use {@link mapOrFail} if it can.
+   * Use when you need to transform a parsed config value with a function that
+   * cannot fail.
    *
    * **Details**
    *
@@ -300,8 +298,8 @@ export const map: {
    *
    * **When to use**
    *
-   * Use when post-processing a config value (e.g. trimming, uppercasing, wrapping).
-   * - The transformation cannot fail. Use {@link mapOrFail} if it can.
+   * Use when you need to transform a parsed config value with a function that
+   * cannot fail.
    *
    * **Details**
    *
@@ -335,8 +333,8 @@ export const map: {
  *
  * **When to use**
  *
- * Use to validate or converting a config value where the transformation can
- *   produce a `ConfigError` (e.g. parsing a URL, checking a range).
+ * Use when you need to transform a parsed config value with a function that can
+ * produce a `ConfigError` (e.g. parsing a URL, checking a range).
  *
  * **Details**
  *
@@ -363,8 +361,8 @@ export const mapOrFail: {
    *
    * **When to use**
    *
-   * Use to validate or converting a config value where the transformation can
-   *   produce a `ConfigError` (e.g. parsing a URL, checking a range).
+   * Use when you need to transform a parsed config value with a function that can
+   * produce a `ConfigError` (e.g. parsing a URL, checking a range).
    *
    * **Details**
    *
@@ -391,8 +389,8 @@ export const mapOrFail: {
    *
    * **When to use**
    *
-   * Use to validate or converting a config value where the transformation can
-   *   produce a `ConfigError` (e.g. parsing a URL, checking a range).
+   * Use when you need to transform a parsed config value with a function that can
+   * produce a `ConfigError` (e.g. parsing a URL, checking a range).
    *
    * **Details**
    *
@@ -423,8 +421,8 @@ export const mapOrFail: {
  *
  * **When to use**
  *
- * Use when trying an alternative config source when the primary one errors.
- * - Providing environment-specific overrides.
+ * Use when you need to try an alternative config source after the primary one
+ * fails.
  *
  * **Details**
  *
@@ -455,8 +453,8 @@ export const orElse: {
    *
    * **When to use**
    *
-   * Use when trying an alternative config source when the primary one errors.
-   * - Providing environment-specific overrides.
+   * Use when you need to try an alternative config source after the primary one
+   * fails.
    *
    * **Details**
    *
@@ -487,8 +485,8 @@ export const orElse: {
    *
    * **When to use**
    *
-   * Use when trying an alternative config source when the primary one errors.
-   * - Providing environment-specific overrides.
+   * Use when you need to try an alternative config source after the primary one
+   * fails.
    *
    * **Details**
    *
@@ -523,7 +521,7 @@ export const orElse: {
  *
  * **When to use**
  *
- * Use when grouping related configs into a tuple or named struct.
+ * Use when you need to group related configs into a tuple or named struct.
  *
  * **Details**
  *
@@ -572,7 +570,7 @@ export function all<const Arg extends Iterable<Config<any>> | Record<string, Con
   }
 }
 
-function isMissingDataOnly(issue: Issue.Issue): boolean {
+function isMissingDataOnly(issue: SchemaIssue.Issue): boolean {
   switch (issue._tag) {
     case "MissingKey":
       return true
@@ -603,7 +601,7 @@ function isMissingDataOnly(issue: Issue.Issue): boolean {
  *
  * **When to use**
  *
- * Use when making a config key optional with a sensible default.
+ * Use when you need to make a config key optional with a sensible default.
  *
  * **Details**
  *
@@ -639,7 +637,7 @@ export const withDefault: {
    *
    * **When to use**
    *
-   * Use when making a config key optional with a sensible default.
+   * Use when you need to make a config key optional with a sensible default.
    *
    * **Details**
    *
@@ -675,7 +673,7 @@ export const withDefault: {
    *
    * **When to use**
    *
-   * Use when making a config key optional with a sensible default.
+   * Use when you need to make a config key optional with a sensible default.
    *
    * **Details**
    *
@@ -724,8 +722,7 @@ export const withDefault: {
  *
  * **When to use**
  *
- * Use when a config key may or may not be present and you want to handle both
- *   cases explicitly.
+ * Use when you need to handle a config key that may or may not be present.
  *
  * **Gotchas**
  *
@@ -874,7 +871,7 @@ const dump: (
 })
 
 const recur: (
-  ast: AST.AST,
+  ast: SchemaAST.AST,
   provider: ConfigProvider.ConfigProvider,
   path: Path
 ) => Effect.Effect<Schema.StringTree, Schema.SchemaError | SourceError> = Effect.fnUntraced(
@@ -893,7 +890,7 @@ const recur: (
           const stat = yield* provider.load(path)
           if (stat && stat._tag === "Record") {
             for (const is of ast.indexSignatures) {
-              const matches = Parser._is(is.parameter)
+              const matches = SchemaParser._is(is.parameter)
               for (const key of stat.keys) {
                 if (!Object.hasOwn(out, key) && matches(key)) {
                   const value = yield* recur(is.type, provider, [...path, key])
@@ -938,15 +935,16 @@ const recur: (
  *
  * **When to use**
  *
- * Use when reading structured or validated config (structs, arrays, unions, branded
- *   types, etc.).
- * - All convenience constructors (`string`, `number`, …) delegate to this.
+ * Use when you need to read structured or schema-validated configuration.
  *
  * **Details**
  *
  * The optional `path` sets the root path segment(s) for the config lookup.
  * Pass a single string for a flat key or an array for nested paths.
  *
+ * Convenience constructors such as `string`, `number`, and `boolean` delegate
+ * to this API.
+ *
  * The codec is used to decode the raw `StringTree` produced by the provider
  * into `T`. Schema validation errors are wrapped in `ConfigError`.
  *
@@ -979,8 +977,8 @@ const recur: (
  */
 export function schema<T, E>(codec: Schema.Codec<T, E>, path?: string | ConfigProvider.Path): Config<T> {
   const codecStringTree = Schema.toCodecStringTree(codec)
-  const decodeUnknownEffect = Parser.decodeUnknownEffect(codecStringTree)
-  const codecStringTreeEncoded = AST.toEncoded(codecStringTree.ast)
+  const decodeUnknownEffect = SchemaParser.decodeUnknownEffect(codecStringTree)
+  const codecStringTreeEncoded = SchemaAST.toEncoded(codecStringTree.ast)
   const defaultPath = typeof path === "string" ? [path] : path ?? []
   return make((provider) => {
     const path = provider.prefix ? [...provider.prefix, ...defaultPath] : defaultPath
@@ -988,7 +986,7 @@ export function schema<T, E>(codec: Schema.Codec<T, E>, path?: string | ConfigPr
       Effect.flatMapEager((tree) =>
         decodeUnknownEffect(tree).pipe(
           Effect.mapErrorEager((issue) =>
-            new Schema.SchemaError(path.length > 0 ? new Issue.Pointer(path, issue) : issue)
+            new Schema.SchemaError(path.length > 0 ? new SchemaIssue.Pointer(path, issue) : issue)
           )
         )
       ),
@@ -1008,8 +1006,8 @@ export const FalseValues = Schema.Literals(["false", "no", "off", "0", "n"])
  *
  * **When to use**
  *
- * Use when passing to {@link schema} for custom paths, or use the
- * {@link boolean} convenience constructor.
+ * Use when you need the reusable boolean schema value for `Config.schema` with
+ * custom paths.
  *
  * **Details**
  *
@@ -1024,7 +1022,7 @@ export const FalseValues = Schema.Literals(["false", "no", "off", "0", "n"])
 export const Boolean = Schema.Literals([...TrueValues.literals, ...FalseValues.literals]).pipe(
   Schema.decodeTo(
     Schema.Boolean,
-    Transformation.transform({
+    SchemaTransformation.transform({
       decode: (value) => value === "true" || value === "yes" || value === "on" || value === "1" || value === "y",
       encode: (value) => value ? "true" : "false"
     })
@@ -1036,8 +1034,8 @@ export const Boolean = Schema.Literals([...TrueValues.literals, ...FalseValues.l
  *
  * **When to use**
  *
- * Use when passing to {@link schema} for custom paths, or use the {@link port}
- * convenience constructor.
+ * Use when you need the reusable port schema value for `Config.schema` with
+ * custom paths.
  *
  * @see {@link port} – convenience constructor
  *
@@ -1051,8 +1049,8 @@ export const Port = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 655
  *
  * **When to use**
  *
- * Use when passing to {@link schema} for custom paths, or use the
- * {@link logLevel} convenience constructor.
+ * Use when you need the reusable log-level schema value for `Config.schema`
+ * with custom paths.
  *
  * **Details**
  *
@@ -1115,7 +1113,7 @@ export const Record = <K extends Schema.Record.Key, V extends Schema.Top>(key: K
   const recordString = Schema.String.pipe(
     Schema.decodeTo(
       Schema.Record(Schema.String, Schema.String),
-      Transformation.splitKeyValue(options)
+      SchemaTransformation.splitKeyValue(options)
     ),
     Schema.decodeTo(record)
   )
@@ -1132,8 +1130,8 @@ export const Record = <K extends Schema.Record.Key, V extends Schema.Top>(key: K
  *
  * **When to use**
  *
- * Use when inside {@link orElse} to re-raise a specific error.
- * - Testing error handling paths.
+ * Use when you need to re-raise a specific config error, such as inside
+ * {@link orElse}.
  *
  * @category constructors
  * @since 2.0.0
@@ -1148,8 +1146,8 @@ export function fail(err: SourceError | Schema.SchemaError) {
  *
  * **When to use**
  *
- * Use when providing a hardcoded constant inside {@link orElse}.
- * - Testing.
+ * Use when you need a hardcoded config value, such as inside {@link orElse} or
+ * tests.
  *
  * **Example** (Constant fallback)
  *
@@ -1226,7 +1224,8 @@ export function nonEmptyString(name?: string) {
  *
  * **When to use**
  *
- * Use to read a numeric config value when `NaN` and `Infinity` are acceptable.
+ * Use when you need config input to accept JavaScript's full number domain,
+ * including NaN and infinities, rather than reject non-finite values.
  *
  * **Details**
  *
@@ -1307,7 +1306,7 @@ export function int(name?: string) {
  * @category constructors
  * @since 2.0.0
  */
-export function literal<L extends AST.LiteralValue>(literal: L, name?: string) {
+export function literal<L extends SchemaAST.LiteralValue>(literal: L, name?: string) {
   return schema(Schema.Literal(literal), name)
 }
 
@@ -1335,7 +1334,7 @@ export function literal<L extends AST.LiteralValue>(literal: L, name?: string) {
  * @category constructors
  * @since 4.0.0
  */
-export function literals<const L extends ReadonlyArray<AST.LiteralValue>>(literals: L, name?: string) {
+export function literals<const L extends ReadonlyArray<SchemaAST.LiteralValue>>(literals: L, name?: string) {
   return schema(Schema.Literals(literals), name)
 }
 
@@ -1662,9 +1661,7 @@ export function date(name?: string) {
  *
  * **When to use**
  *
- * Use when grouping related config keys under a common namespace (e.g.
- *   `"database"`, `"redis"`).
- * - Building reusable config fragments that callers nest at different paths.
+ * Use when you need to group related config keys under a common namespace.
  *
  * **Details**
  *
@@ -1717,9 +1714,7 @@ export const nested: {
    *
    * **When to use**
    *
-   * Use when grouping related config keys under a common namespace (e.g.
-   *   `"database"`, `"redis"`).
-   * - Building reusable config fragments that callers nest at different paths.
+   * Use when you need to group related config keys under a common namespace.
    *
    * **Details**
    *
@@ -1772,9 +1767,7 @@ export const nested: {
    *
    * **When to use**
    *
-   * Use when grouping related config keys under a common namespace (e.g.
-   *   `"database"`, `"redis"`).
-   * - Building reusable config fragments that callers nest at different paths.
+   * Use when you need to group related config keys under a common namespace.
    *
    * **Details**
    *