effect 4.0.0 → 4.0.2

package/src/Clock.ts

@@ -5,6 +5,7 @@
  * accessed through a service, tests can replace the clock with a controlled
  * implementation.
  *
+ * @stability stable
  * @since 2.0.0
  */
 import type * as Context from "./Context.ts"
@@ -45,6 +46,7 @@ import * as effect from "./internal/effect.ts"
  * await Effect.runPromise(Effect.provideService(clockOperations, Clock.Clock, testClock)) // => [1_000, 1_000_000_000n]
  * ```
  *
+ * @stability stable
  * @category services
  * @since 2.0.0
  */
@@ -183,6 +185,7 @@ export interface Clock {
  * @see {@link currentTimeMillis} for reading the current time in milliseconds
  * @see {@link currentTimeNanos} for reading the current time in nanoseconds
  *
+ * @stability stable
  * @category services
  * @since 2.0.0
  */
@@ -219,6 +222,7 @@ export const Clock: Context.Reference<Clock> = effect.ClockRef
  * @see {@link Clock} for the service reference
  * @see {@link currentTimeMillis} for convenience accessor that returns milliseconds
  * @see {@link currentTimeNanos} for convenience accessor that returns nanoseconds
+ * @stability stable
  * @category accessors
  * @since 2.0.0
  */
@@ -259,6 +263,7 @@ export const clockWith: <A, E, R>(f: (clock: Clock) => Effect<A, E, R>) => Effec
  * @see {@link monotonicTimeNanos} for measuring elapsed time
  * @see {@link clockWith} for accessing the full Clock service
  *
+ * @stability stable
  * @category accessors
  * @since 2.0.0
  */
@@ -299,6 +304,7 @@ export const currentTimeMillis: Effect<number> = effect.currentTimeMillis
  *
  * @see {@link monotonicTimeNanos} for measuring elapsed time
  *
+ * @stability stable
  * @category accessors
  * @since 2.0.0
  */
@@ -320,6 +326,7 @@ export const currentTimeNanos: Effect<bigint> = effect.currentTimeNanos
  *
  * @see {@link currentTimeNanos} for Unix wall-clock timestamps
  *
+ * @stability stable
  * @category accessors
  * @since 4.0.0
  */

package/src/Combiner.ts

@@ -7,6 +7,7 @@
  * `Combiner` interface, a constructor for custom combining logic, and common
  * combiners for choosing or ordering values.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import type * as Order from "./Order.ts"
@@ -35,6 +36,7 @@ import type * as Order from "./Order.ts"
  * ```
  *
  * @see {@link make} – create a `Combiner` from a function
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -73,6 +75,7 @@ export interface Combiner<A> {
  * ```
  *
  * @see {@link Combiner} – the interface this creates
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -104,6 +107,7 @@ export function make<A>(combine: (self: A, that: A) => A): Combiner<A> {
  * ```
  *
  * @see {@link make}
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -137,6 +141,7 @@ export function flip<A>(combiner: Combiner<A>): Combiner<A> {
  * ```
  *
  * @see {@link max}
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -170,6 +175,7 @@ export function min<A>(order: Order.Order<A>): Combiner<A> {
  * ```
  *
  * @see {@link min}
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -199,6 +205,7 @@ export function max<A>(order: Order.Order<A>): Combiner<A> {
  * ```
  *
  * @see {@link last}
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -228,6 +235,7 @@ export function first<A>(): Combiner<A> {
  * ```
  *
  * @see {@link first}
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -260,6 +268,7 @@ export function last<A>(): Combiner<A> {
  *
  * @see {@link first}
  * @see {@link last}
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -294,6 +303,7 @@ export function constant<A>(a: A): Combiner<A> {
  * ```
  *
  * @see {@link make}
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */

package/src/Config.ts

@@ -5,8 +5,10 @@
  * multiple settings. Configs are also Effects, so they can be yielded in
  * `Effect.gen` after a provider has been supplied.
  *
+ * @stability stable
  * @since 4.0.0
  */
+import * as Cause from "./Cause.ts"
 import type { Path, SourceError } from "./ConfigProvider.ts"
 import * as ConfigProvider from "./ConfigProvider.ts"
 import * as Effect from "./Effect.ts"
@@ -44,6 +46,7 @@ const TypeId = "~effect/Config"
  * Config.isConfig("not a config") // => false
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 2.0.0
  */
@@ -66,6 +69,7 @@ export const isConfig = (u: unknown): u is Config<unknown> => Predicate.hasPrope
  * @see {@link orElse} – recover from a ConfigError
  * @see {@link withDefault} – provide a fallback when relevant input is absent
  *
+ * @stability stable
  * @category errors
  * @since 4.0.0
  */
@@ -102,6 +106,7 @@ export class ConfigError {
  *
  * @see {@link schema} – the main way to create a Config
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -177,6 +182,7 @@ const evaluateAt = <T>(
  *
  * @see {@link mapEffect} – when the transformation can fail
  *
+ * @stability stable
  * @category mapping
  * @since 2.0.0
  */
@@ -204,6 +210,7 @@ export const map: {
    *
    * @see {@link mapEffect} – when the transformation can fail
    *
+   * @stability stable
    * @category mapping
    * @since 2.0.0
    */
@@ -231,6 +238,7 @@ export const map: {
    *
    * @see {@link mapEffect} – when the transformation can fail
    *
+   * @stability stable
    * @category mapping
    * @since 2.0.0
    */
@@ -296,6 +304,7 @@ export const map: {
  * )
  * ```
  *
+ * @stability stable
  * @category mapping
  * @since 4.0.0
  */
@@ -357,6 +366,7 @@ export const flatMap: {
    * )
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 4.0.0
    */
@@ -418,6 +428,7 @@ export const flatMap: {
    * )
    * ```
    *
+   * @stability stable
    * @category mapping
    * @since 4.0.0
    */
@@ -456,6 +467,7 @@ export const flatMap: {
  *
  * @see {@link map} – when the transformation cannot fail
  *
+ * @stability stable
  * @category mapping
  * @since 2.0.0
  */
@@ -482,6 +494,7 @@ export const mapEffect: {
    *
    * @see {@link map} – when the transformation cannot fail
    *
+   * @stability stable
    * @category mapping
    * @since 2.0.0
    */
@@ -508,6 +521,7 @@ export const mapEffect: {
    *
    * @see {@link map} – when the transformation cannot fail
    *
+   * @stability stable
    * @category mapping
    * @since 2.0.0
    */
@@ -542,7 +556,8 @@ export const mapEffect: {
  *
  * The fallback's result replaces the original failure. If the fallback is
  * absent, an outer {@link withDefault} or {@link option} can recover it. If the
- * fallback fails, only its error propagates.
+ * fallback fails, only its error propagates. Defects and interruptions never
+ * reach the fallback; they propagate unchanged.
  *
  * **Example** (Trying another port before using a default)
  *
@@ -562,6 +577,7 @@ export const mapEffect: {
  *
  * @see {@link withDefault} – fallback only on semantic absence
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -584,7 +600,8 @@ export const orElse: {
    *
    * The fallback's result replaces the original failure. If the fallback is
    * absent, an outer {@link withDefault} or {@link option} can recover it. If the
-   * fallback fails, only its error propagates.
+   * fallback fails, only its error propagates. Defects and interruptions never
+   * reach the fallback; they propagate unchanged.
    *
    * **Example** (Trying another port before using a default)
    *
@@ -604,6 +621,7 @@ export const orElse: {
    *
    * @see {@link withDefault} – fallback only on semantic absence
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -626,7 +644,8 @@ export const orElse: {
    *
    * The fallback's result replaces the original failure. If the fallback is
    * absent, an outer {@link withDefault} or {@link option} can recover it. If the
-   * fallback fails, only its error propagates.
+   * fallback fails, only its error propagates. Defects and interruptions never
+   * reach the fallback; they propagate unchanged.
    *
    * **Example** (Trying another port before using a default)
    *
@@ -646,6 +665,7 @@ export const orElse: {
    *
    * @see {@link withDefault} – fallback only on semantic absence
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -669,7 +689,8 @@ export const orElse: {
    *
    * The fallback's result replaces the original failure. If the fallback is
    * absent, an outer {@link withDefault} or {@link option} can recover it. If the
-   * fallback fails, only its error propagates.
+   * fallback fails, only its error propagates. Defects and interruptions never
+   * reach the fallback; they propagate unchanged.
    *
    * **Example** (Trying another port before using a default)
    *
@@ -689,12 +710,19 @@ export const orElse: {
    *
    * @see {@link withDefault} – fallback only on semantic absence
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
   A | A2>((provider, pathPrefix) =>
-    Effect.matchEffect(evaluateAt(self, provider, pathPrefix), {
-      onFailure: (error) => evaluateAt(that(error), provider, pathPrefix),
+    Effect.matchCauseEffect(evaluateAt(self, provider, pathPrefix), {
+      // Only plain failures reach the fallback; defects and interruptions propagate unchanged.
+      onFailure: (cause) => {
+        const error = Cause.findErrorOption(cause)
+        return Option.isSome(error) && cause.reasons.every(Cause.isFailReason)
+          ? evaluateAt(that(error.value), provider, pathPrefix)
+          : Effect.failCause(cause)
+      },
       onSuccess: (resolution): Effect.Effect<Resolution<A | A2>, ConfigError> =>
         Result.isFailure(resolution)
           ? evaluateAt(that(resolution.failure), provider, pathPrefix)
@@ -742,6 +770,7 @@ export const orElse: {
  * await Effect.runPromise(dbConfig.parse(missingPort)) // => { host: "localhost", port: 5432 }
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -807,6 +836,7 @@ export function all<const Arg extends Iterable<Config<any>> | Record<string, Con
  * @see {@link option} – returns `Option` instead of a default value
  * @see {@link orElse} – catches all errors, not just absent input
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -843,6 +873,7 @@ export const withDefault: {
    * @see {@link option} – returns `Option` instead of a default value
    * @see {@link orElse} – catches all errors, not just absent input
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -879,6 +910,7 @@ export const withDefault: {
    * @see {@link option} – returns `Option` instead of a default value
    * @see {@link orElse} – catches all errors, not just absent input
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -916,6 +948,7 @@ export const withDefault: {
    * @see {@link option} – returns `Option` instead of a default value
    * @see {@link orElse} – catches all errors, not just absent input
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -957,6 +990,7 @@ export const withDefault: {
  *
  * @see {@link withDefault} – provide a concrete fallback value instead
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -974,6 +1008,7 @@ export const option = <A>(self: Config<A>): Config<Option.Option<A>> =>
  * @see {@link Config} for the config type whose parsed value is extracted
  * @see {@link Effect.Success} for extracting the success type from any `Effect`
  *
+ * @stability stable
  * @category utility types
  * @since 2.5.0
  */
@@ -994,6 +1029,7 @@ export type Success<T> = [T] extends [Config<infer A>] ? A : never
  *
  * @see {@link unwrap} – construct a `Config` from a `Wrap<T>`
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -1039,6 +1075,7 @@ type IsPlainObject<A> = [A] extends [Record<string, any>]
  *
  * @see {@link Wrap} – the utility type accepted by this function
  *
+ * @stability stable
  * @category converting
  * @since 2.0.0
  */
@@ -1062,12 +1099,22 @@ const isSourceError = (u: unknown): u is ConfigProvider.SourceError => Predicate
 
 const cursorToString = (): string => "<configuration>"
 
+// Rewrites each reason of a failure individually, so unrelated defects and
+// interruptions survive the conversion.
+const mapReasons =
+  <E, E2>(f: (reason: Cause.Reason<E>) => Cause.Reason<E2>) =>
+  <A, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E2, R> =>
+    Effect.catchCause(self, (cause) => Effect.failCause(Cause.fromReasons(cause.reasons.map(f))))
+
 const loadCursor: (
   provider: ConfigProvider.ConfigProvider,
   path: Path
 ) => Effect.Effect<ConfigCursor> = (provider, path) =>
   provider.load(path).pipe(
-    Effect.orDie,
+    // Source errors travel as defects so they bypass schema issue recovery; `schema` converts them back.
+    mapReasons<SourceError, never>((reason) =>
+      Cause.isFailReason(reason) ? Cause.makeDieReason(reason.error).annotate(Cause.reasonAnnotations(reason)) : reason
+    ),
     Effect.mapEager((node) => ({ provider, path, node, toString: cursorToString }))
   )
 
@@ -1260,6 +1307,7 @@ const toConfigCursorAST = memoize((root: SchemaAST.AST): SchemaAST.AST => {
  * @see {@link String} / {@link Number} / {@link Boolean} – shortcuts for
  *   single-value configs
  *
+ * @stability stable
  * @category schemas
  * @since 4.0.0
  */
@@ -1286,7 +1334,11 @@ export function schema<T>(codec: Schema.ConstraintCodec<T, unknown>, path?: stri
           })
         )
       ),
-      Effect.catchDefect((defect) => isSourceError(defect) ? Effect.fail(new ConfigError(defect)) : Effect.die(defect))
+      mapReasons((reason) =>
+        Cause.isDieReason(reason) && isSourceError(reason.defect)
+          ? Cause.makeFailReason(new ConfigError(reason.defect)).annotate(Cause.reasonAnnotations(reason))
+          : reason
+      )
     )
   })
 }
@@ -1318,6 +1370,7 @@ const isPath = (u: unknown): u is string | Path => Predicate.isString(u) || glob
  * Use when you need to re-raise a specific config error, such as inside
  * {@link orElse}.
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -1346,6 +1399,7 @@ export function fail(err: SourceError | Schema.SchemaError): Config<never> {
  * Effect.runSync(host.parse(provider)) // => "localhost"
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -1378,6 +1432,7 @@ export function succeed<T>(value: T) {
  * @see {@link NonEmptyString} – rejects empty strings
  * @see {@link schema} – for more complex types
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -1399,6 +1454,7 @@ export function String(name?: string) {
  *
  * @see {@link String} for allowing empty strings
  *
+ * @stability stable
  * @category constructors
  * @since 3.7.0
  */
@@ -1421,6 +1477,7 @@ export function NonEmptyString(name?: string) {
  * @see {@link Finite} for rejecting `NaN` and `Infinity`
  * @see {@link Int} for accepting only integers
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -1442,6 +1499,7 @@ export function Number(name?: string) {
  * @see {@link Number} for accepting `NaN` and `Infinity`
  * @see {@link Int} for accepting only integers
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -1463,6 +1521,7 @@ export function Finite(name?: string) {
  * @see {@link Number} for accepting any number
  * @see {@link Port} for accepting only integers in `1` through `65535`
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -1492,6 +1551,7 @@ export function Int(name?: string) {
  * ```
  *
  * @see {@link Literals} – accepts multiple literal values
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -1522,6 +1582,7 @@ export function Literal<L extends SchemaAST.LiteralValue>(literal: L, name?: str
  *
  * @see {@link Literal} for accepting one specific literal value
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -1555,6 +1616,7 @@ export function Literals<const L extends ReadonlyArray<SchemaAST.LiteralValue>>(
  * ```
  *
  * @see {@link Record} for key-value input from structural records or separated strings.
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -1622,6 +1684,7 @@ export function Array<V extends Schema.ConstraintCodec<unknown, unknown>>(
  * ```
  *
  * @see {@link Array} for array input from structural arrays or separated strings.
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -1697,6 +1760,7 @@ export function Record<
  * ) // => true
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -1739,6 +1803,7 @@ export function Boolean(name?: string) {
  *
  * @see {@link schema} for decoding configuration values with a custom codec
  *
+ * @stability stable
  * @category constructors
  * @since 2.5.0
  */
@@ -1754,6 +1819,7 @@ export function Duration(name?: string) {
  * Decimal symbols such as `kB` use powers of 1,000, while binary symbols such
  * as `KiB` use powers of 1,024.
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -1792,6 +1858,7 @@ export function ByteSize(name?: string) {
  *
  * @see {@link Int} for integer config values outside the port range
  *
+ * @stability stable
  * @category constructors
  * @since 3.16.0
  */
@@ -1829,6 +1896,7 @@ export function Port(name?: string) {
  * ) // => "Info"
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -1869,6 +1937,7 @@ export function LogLevel(name?: string) {
  *
  * @see {@link String} for non-secret string settings
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -1911,6 +1980,7 @@ export function Redacted(name?: string) {
  *
  * @see {@link schema} for decoding configuration values with a custom codec
  *
+ * @stability stable
  * @category constructors
  * @since 3.11.0
  */
@@ -1944,6 +2014,7 @@ export function URL(name?: string) {
  * Effect.runSync(createdAt.parse(provider)).toISOString() // => "2024-01-15T00:00:00.000Z"
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -1999,6 +2070,7 @@ export function Date(name?: string) {
  * @see {@link all} – combine multiple configs into a struct
  * @see {@link schema} – read structured config from a schema
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -2051,6 +2123,7 @@ export const nested: {
    * @see {@link all} – combine multiple configs into a struct
    * @see {@link schema} – read structured config from a schema
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -2103,6 +2176,7 @@ export const nested: {
    * @see {@link all} – combine multiple configs into a struct
    * @see {@link schema} – read structured config from a schema
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */