effect 4.0.1 → 4.0.3

package/src/Effectable.ts

@@ -4,6 +4,7 @@
  * domain-specific values, such as service keys or configuration descriptions,
  * be evaluated by Effect and yielded inside `Effect.gen`.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import type * as Effect from "./Effect.ts"
@@ -26,6 +27,7 @@ import { evaluate, makePrimitiveProto } from "./internal/core.ts"
  * @see {@link Class} for a class-based approach to defining custom Effect values
  * @see {@link Mixin} for wrapping an existing class constructor
  *
+ * @stability stable
  * @category prototypes
  * @since 4.0.0
  */
@@ -64,6 +66,7 @@ const Base: new<A, E, R>() => Effect.Effect<A, E, R> = (() => {
  *
  * @see {@link Prototype} for a lower-level primitive approach to creating custom Effect-like values without a class
  * @see {@link Mixin} for wrapping an existing class constructor
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -123,6 +126,7 @@ declare abstract class MixinBase extends Class<any, any, any> {
  *
  * @see {@link Prototype} for a lower-level primitive approach to creating custom Effect-like values without a class
  * @see {@link Class} for a base constructor to extend
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */

package/src/Equal.ts

@@ -7,6 +7,7 @@
  * comparison builders, and helpers for marking objects that should compare only
  * by reference.
  *
+ * @stability stable
  * @since 2.0.0
  */
 import type { Equivalence } from "./Equivalence.ts"
@@ -49,6 +50,7 @@ import { hasProperty } from "./Predicate.ts"
  *
  * @see {@link Equal} — the interface that uses this symbol
  * @see {@link isEqual} — type guard for `Equal` implementors
+ * @stability stable
  * @category symbols
  * @since 2.0.0
  */
@@ -103,6 +105,7 @@ export const symbol = "~effect/Equal"
  * @see {@link symbol} — the property key used by the equality method
  * @see {@link equals} — the main comparison function
  * @see {@link isEqual} — type guard for `Equal` implementors
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -167,6 +170,7 @@ export interface Equal extends Hash.Hash {
  * @see {@link Equal} — the interface for custom equality
  * @see {@link isEqual} — check whether a value implements `Equal`
  * @see {@link asEquivalence} — wrap `equals` as an `Equivalence`
+ * @stability stable
  * @category equality
  * @since 2.0.0
  */
@@ -330,11 +334,13 @@ function compareHashed<A>(
   equivalent: (self: A, that: A) => boolean
 ): boolean {
   const groups = new Map<number, Array<A>>()
+  let remaining = 0
   for (const item of that) {
     const h = hashOf(item)
     const group = groups.get(h)
     if (group) group.push(item)
     else groups.set(h, [item])
+    remaining++
   }
   outer: for (const item of self) {
     const group = groups.get(hashOf(item))
@@ -343,13 +349,14 @@ function compareHashed<A>(
         if (equivalent(item, group[i])) {
           group[i] = group[group.length - 1]
           group.pop()
+          remaining--
           continue outer
         }
       }
     }
     return false
   }
-  return true
+  return remaining === 0
 }
 
 const entryHash = (entry: readonly [unknown, unknown]): number => Hash.hash(entry[0])
@@ -410,6 +417,7 @@ export function makeCompareSet<A>(equivalence: Equivalence<A>) {
  *
  * @see {@link Equal} — the interface being checked
  * @see {@link symbol} — the property key that signals `Equal` support
+ * @stability stable
  * @category guards
  * @since 2.0.0
  */
@@ -438,6 +446,7 @@ export const isEqual = (u: unknown): u is Equal => hasProperty(u, symbol)
  * ```
  *
  * @see {@link equals} — the underlying comparison function
+ * @stability stable
  * @category instances
  * @since 4.0.0
  */
@@ -480,6 +489,7 @@ export const asEquivalence: <A>() => Equivalence<A> = () => equals
  * @see {@link byReferenceUnsafe} — same effect without a proxy (mutates the
  *   original)
  * @see {@link equals} — the comparison function affected by this opt-out
+ * @stability stable
  * @category equality
  * @since 4.0.0
  */
@@ -523,6 +533,7 @@ export const byReference = <T extends object>(obj: T): T => byReferenceUnsafe(ne
  *
  * @see {@link byReference} — safer alternative that creates a proxy
  * @see {@link equals} — the comparison function affected by this opt-out
+ * @stability stable
  * @category unsafe
  * @since 4.0.0
  */

package/src/Equivalence.ts

@@ -7,6 +7,7 @@
  * helpers for tuples, arrays, structs, records, dates, and values compared
  * through a derived field.
  *
+ * @stability stable
  * @since 2.0.0
  */
 import { dual } from "./Function.ts"
@@ -54,6 +55,7 @@ import * as Reducer from "./Reducer.ts"
  *
  * @see {@link make}
  * @see {@link strictEqual}
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -89,6 +91,7 @@ export type Equivalence<in A> = (self: A, that: A) => boolean
  *
  * @see {@link Equivalence}
  * @see {@link TypeLambda}
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -141,6 +144,7 @@ export interface EquivalenceTypeLambda extends TypeLambda {
  *
  * @see {@link strictEqual}
  * @see {@link mapInput}
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -193,6 +197,7 @@ const isStrictEquivalent = (x: unknown, y: unknown) => x === y
  *
  * @see {@link make}
  * @see `Equal` for structural equality
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -214,6 +219,7 @@ export const strictEqual: <A>() => Equivalence<A> = () => isStrictEquivalent
  * Equivalence.String("hello", "world") // => false
  * ```
  *
+ * @stability stable
  * @category instances
  * @since 4.0.0
  */
@@ -236,6 +242,7 @@ export const String: Equivalence<string> = isStrictEquivalent
  * Equivalence.Number(NaN, NaN) // => true
  * ```
  *
+ * @stability stable
  * @category instances
  * @since 4.0.0
  */
@@ -259,6 +266,7 @@ export const Number: Equivalence<number> = make((self, that) =>
  * Equivalence.Boolean(true, false) // => false
  * ```
  *
+ * @stability stable
  * @category instances
  * @since 4.0.0
  */
@@ -280,6 +288,7 @@ export const Boolean: Equivalence<boolean> = isStrictEquivalent
  * Equivalence.BigInt(1n, 2n) // => false
  * ```
  *
+ * @stability stable
  * @category instances
  * @since 4.0.0
  */
@@ -331,6 +340,7 @@ export const BigInt: Equivalence<bigint> = isStrictEquivalent
  *
  * @see {@link combineAll}
  * @see {@link mapInput}
+ * @stability stable
  * @category combining
  * @since 2.0.0
  */
@@ -381,6 +391,7 @@ export const combine: {
    *
    * @see {@link combineAll}
    * @see {@link mapInput}
+   * @stability stable
    * @category combining
    * @since 2.0.0
    */
@@ -431,6 +442,7 @@ export const combine: {
    *
    * @see {@link combineAll}
    * @see {@link mapInput}
+   * @stability stable
    * @category combining
    * @since 2.0.0
    */
@@ -498,6 +510,7 @@ export const combine: {
  *
  * @see {@link combine}
  * @see {@link mapInput}
+ * @stability stable
  * @category combining
  * @since 2.0.0
  */
@@ -568,6 +581,7 @@ export const combineAll = <A>(collection: Iterable<Equivalence<A>>): Equivalence
  *
  * @see {@link combine}
  * @see {@link Struct}
+ * @stability stable
  * @category mapping
  * @since 2.0.0
  */
@@ -629,6 +643,7 @@ export const mapInput: {
    *
    * @see {@link combine}
    * @see {@link Struct}
+   * @stability stable
    * @category mapping
    * @since 2.0.0
    */
@@ -690,6 +705,7 @@ export const mapInput: {
    *
    * @see {@link combine}
    * @see {@link Struct}
+   * @stability stable
    * @category mapping
    * @since 2.0.0
    */
@@ -753,6 +769,7 @@ export const mapInput: {
  * customTupleEq(["Hello", "World", "Test"], ["HELLO", "WORLD", "TEST"]) // => true
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -832,6 +849,7 @@ export {
    *
    * @see {@link Tuple}
    * @see {@link Record}
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -903,6 +921,7 @@ export {
  * @see {@link Record}
  * @see {@link mapInput}
  * @see {@link combine}
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -967,6 +986,7 @@ export function Struct<R extends Record<string, Equivalence<any>>>(
  * numberRecordEq(scores1, scores3) // => false
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1021,6 +1041,7 @@ export function Record<A>(value: Equivalence<A>): Equivalence<Record<PropertyKey
  * @see {@link combine} Combine two equivalences
  * @see {@link combineAll} Combine multiple equivalences
  * @see {@link Reducer} Reducer type for collection operations
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -1077,6 +1098,7 @@ export function makeReducer<A>() {
  * @see {@link Number} for the numeric equivalence applied to each `Date#getTime()` result
  * @see {@link mapInput} for deriving an equivalence by mapping inputs before comparison
  * @see {@link strictEqual} for reference equality when two values must be the same object
+ * @stability stable
  * @category instances
  * @since 2.0.0
  */

package/src/ErrorReporter.ts

@@ -8,6 +8,7 @@
  * layers for installing reporters and symbols for marking errors as ignored or
  * attaching severity and attributes.
  *
+ * @stability unstable
  * @since 4.0.0
  */
 import type * as Cause from "./Cause.ts"
@@ -30,6 +31,7 @@ import type * as Scope from "./Scope.ts"
  *
  * Use to refer to the runtime type identifier type in low-level integrations.
  *
+ * @stability unstable
  * @category type IDs
  * @since 4.0.0
  */
@@ -44,6 +46,7 @@ export type TypeId = "~effect/ErrorReporter"
  * implementations. Most code should create reporters with `make` and register
  * them with `layer`.
  *
+ * @stability unstable
  * @category type IDs
  * @since 4.0.0
  */
@@ -70,6 +73,7 @@ export const TypeId: TypeId = "~effect/ErrorReporter"
  * @see {@link report} for manually reporting a `Cause`
  * @see {@link Effect.withErrorReporting} for reporting failures from an effect
  *
+ * @stability unstable
  * @category services
  * @since 4.0.0
  */
@@ -120,6 +124,7 @@ export interface ErrorReporter {
  * @see {@link layer} for registering reporters in the environment
  * @see {@link report} for manually reporting a `Cause`
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -170,6 +175,7 @@ export const make = (
  * Use when you need to read or replace the current set of error reporters
  * directly.
  *
+ * @stability unstable
  * @category services
  * @since 4.0.0
  */
@@ -228,6 +234,7 @@ export const CurrentErrorReporters: Context.Reference<ReadonlySet<ErrorReporter>
  * @see {@link make} for creating an `ErrorReporter` from a callback
  * @see {@link CurrentErrorReporters} for low-level access to the current reporters
  *
+ * @stability unstable
  * @category layers
  * @since 4.0.0
  */
@@ -284,6 +291,7 @@ export const layer = <
  * output // => "fallback value"
  * ```
  *
+ * @stability unstable
  * @category logging
  * @since 4.0.0
  */
@@ -315,12 +323,31 @@ export const report = <E>(cause: Cause.Cause<E>): Effect.Effect<void> =>
  * @see {@link attributes} for the runtime annotation key that attaches reporter
  * metadata
  *
+ * @stability unstable
  * @category annotations
  * @since 4.0.0
  */
 export interface Reportable {
+  /**
+   * Suppress reports for this error.
+   *
+   * @stability unstable
+   * @since 4.0.0
+   */
   readonly [ignore]?: boolean
+  /**
+   * Override the severity level for this error.
+   *
+   * @stability unstable
+   * @since 4.0.0
+   */
   readonly [severity]?: Severity
+  /**
+   * Attach extra key/value metadata to this error.
+   *
+   * @stability unstable
+   * @since 4.0.0
+   */
   readonly [attributes]?: ReadonlyRecord<string, unknown>
 }
 
@@ -343,6 +370,7 @@ declare global {
  * from being forwarded to reporters. This is useful for expected failures such
  * as HTTP 404 responses.
  *
+ * @stability unstable
  * @category annotations
  * @since 4.0.0
  */
@@ -379,6 +407,7 @@ export type ignore = "~effect/ErrorReporter/ignore"
  * @see {@link Reportable} for the annotation contract recognized on object
  * errors
  *
+ * @stability unstable
  * @category annotations
  * @since 4.0.0
  */
@@ -395,6 +424,7 @@ export const ignore: ignore = "~effect/ErrorReporter/ignore"
  *
  * @see {@link ignore} for the annotation key this predicate reads
  *
+ * @stability unstable
  * @category predicates
  * @since 4.0.0
  */
@@ -414,6 +444,7 @@ export const isIgnored = (u: unknown): boolean =>
  * When set to a valid `LogLevel.Severity`, the reporter callback receives this
  * value as `severity`. Missing or invalid values fall back to `"Info"`.
  *
+ * @stability unstable
  * @category annotations
  * @since 4.0.0
  */
@@ -448,6 +479,7 @@ export type severity = "~effect/ErrorReporter/severity"
  * @see {@link Reportable} for the annotation contract recognized on object
  * errors
  *
+ * @stability unstable
  * @category annotations
  * @since 4.0.0
  */
@@ -465,6 +497,7 @@ export const severity: severity = "~effect/ErrorReporter/severity"
  * @see {@link severity} for the annotation key used to override severity
  * @see {@link Reportable} for the annotation properties recognized on object errors
  *
+ * @stability unstable
  * @category annotations
  * @since 4.0.0
  */
@@ -489,6 +522,7 @@ export const getSeverity = (error: object): Severity => {
  * include contextual information such as user IDs, request IDs, or other
  * domain-specific debugging data.
  *
+ * @stability unstable
  * @category annotations
  * @since 4.0.0
  */
@@ -530,6 +564,7 @@ export type attributes = "~effect/ErrorReporter/attributes"
  * @see {@link Reportable} for the annotation contract recognized on object
  * errors
  *
+ * @stability unstable
  * @category annotations
  * @since 4.0.0
  */
@@ -557,6 +592,7 @@ export const attributes: attributes = "~effect/ErrorReporter/attributes"
  * @see {@link attributes} for the annotation key used to attach metadata
  * @see {@link Reportable} for the annotation properties recognized on object errors
  *
+ * @stability unstable
  * @category annotations
  * @since 4.0.0
  */

package/src/ExecutionPlan.ts

@@ -7,6 +7,7 @@
  * order until the workflow succeeds or the plan is exhausted. This module also
  * supports merging plans and reading metadata for the active step and attempt.
  *
+ * @stability unstable
  * @since 3.16.0
  */
 import type { NonEmptyReadonlyArray } from "./Array.ts"
@@ -20,12 +21,13 @@ import * as Layer from "./Layer.ts"
 import type { Pipeable } from "./Pipeable.ts"
 import { pipeArguments } from "./Pipeable.ts"
 import * as Predicate from "./Predicate.ts"
-import type * as Schedule from "./Schedule.ts"
+import * as Schedule from "./Schedule.ts"
 
 /**
  * String literal type used as the runtime type identifier for `ExecutionPlan`
  * values.
  *
+ * @stability unstable
  * @category type IDs
  * @since 3.16.0
  */
@@ -35,6 +37,7 @@ export type TypeId = "~effect/ExecutionPlan"
  * Runtime type identifier attached to `ExecutionPlan` values and used by
  * `isExecutionPlan`.
  *
+ * @stability unstable
  * @category type IDs
  * @since 3.16.0
  */
@@ -58,6 +61,7 @@ export const TypeId: TypeId = "~effect/ExecutionPlan"
  * @see {@link make} for constructing execution plans that satisfy this guard
  * @see {@link TypeId} for the runtime marker checked by this guard
  *
+ * @stability unstable
  * @category guards
  * @since 3.16.0
  */
@@ -84,6 +88,7 @@ export const isExecutionPlan = (u: unknown): u is ExecutionPlan<any> => Predicat
  * ThePlan.steps.map((step) => step.attempts ?? 1) // => [2, 1]
  * ```
  *
+ * @stability unstable
  * @category models
  * @since 3.16.0
  */
@@ -104,7 +109,9 @@ export interface ExecutionPlan<
     readonly while?:
       | ((input: Config["input"]) => Effect.Effect<boolean, Config["error"], Config["requirements"]>)
       | undefined
-    readonly schedule?: Schedule.Schedule<any, Config["input"], Config["requirements"]> | undefined
+    readonly schedule?:
+      | Schedule.Schedule<any, Config["input"], Config["error"], Config["requirements"]>
+      | undefined
   }>
 
   /**
@@ -129,9 +136,10 @@ export interface ExecutionPlan<
  *
  * `provides` tracks services supplied by plan steps, `input` tracks the error
  * input consumed by schedules and `while` predicates, `error` tracks failures
- * from plan layers or predicates, and `requirements` tracks services needed to
- * build or run the plan.
+ * from plan layers, predicates, or schedules, and `requirements` tracks
+ * services needed to build or run the plan.
  *
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */
@@ -163,6 +171,7 @@ export type ConfigBase = {
  * ThePlan.steps.length // => 2
  * ```
  *
+ * @stability unstable
  * @category constructors
  * @since 3.16.0
  */
@@ -171,14 +180,8 @@ export const make = <const Steps extends NonEmptyReadonlyArray<make.Step>>(
 ): ExecutionPlan<{
   provides: make.StepProvides<Steps>
   input: make.StepInput<Steps>
-  error:
-    | (Steps[number]["provide"] extends Context.Context<infer _P> | Layer.Layer<infer _P, infer E, infer _R> ? E
-      : never)
-    | (Steps[number]["while"] extends (input: infer _I) => Effect.Effect<infer _A, infer _E, infer _R> ? _E : never)
-  requirements:
-    | (Steps[number]["provide"] extends Layer.Layer<infer _A, infer _E, infer R> ? R : never)
-    | (Steps[number]["while"] extends (input: infer _I) => Effect.Effect<infer _A, infer _E, infer R> ? R : never)
-    | (Steps[number]["schedule"] extends Schedule.Schedule<infer _O, infer _I, infer R> ? R : never)
+  error: make.StepError<Steps[number]>
+  requirements: make.StepRequirements<Steps[number]>
 }> =>
   makeProto(steps.map((options, i) => {
     if (options.attempts !== undefined && options.attempts < 1) {
@@ -201,6 +204,7 @@ export const make = <const Steps extends NonEmptyReadonlyArray<make.Step>>(
 /**
  * Namespace containing type helpers used by `ExecutionPlan.make`.
  *
+ * @stability unstable
  * @since 3.16.0
  */
 export declare namespace make {
@@ -220,9 +224,31 @@ export declare namespace make {
     readonly provide: Context.Context<any> | Context.Context<never> | Layer.Any
     readonly attempts?: number | undefined
     readonly while?: ((input: any) => boolean | Effect.Effect<boolean, any, any>) | undefined
-    readonly schedule?: Schedule.Schedule<any, any, any> | undefined
+    readonly schedule?: Schedule.Schedule<any, any, any, any> | undefined
   }
 
+  /**
+   * Computes the errors from a step's layer, predicate, and schedule.
+   *
+   * @category utility types
+   * @since 4.0.0
+   */
+  export type StepError<Step> =
+    | (Step extends { readonly provide: Layer.Layer<infer _A, infer E, infer _R> } ? E : never)
+    | (Step extends { readonly while?: (input: any) => infer Result } ? Effect.Error<Result> : never)
+    | (Step extends { readonly schedule?: infer S } ? Schedule.Error<S> : never)
+
+  /**
+   * Computes the services required by a step's layer, predicate, and schedule.
+   *
+   * @category utility types
+   * @since 4.0.0
+   */
+  export type StepRequirements<Step> =
+    | (Step extends { readonly provide: Layer.Layer<infer _A, infer _E, infer R> } ? R : never)
+    | (Step extends { readonly while?: (input: any) => infer Result } ? Effect.Services<Result> : never)
+    | (Step extends { readonly schedule?: infer S } ? Schedule.Env<S> : never)
+
   /**
    * Computes the intersection of services provided by a list of execution-plan
    * steps.
@@ -265,7 +291,7 @@ export declare namespace make {
       & Out
       & (
         & (Step extends { readonly while: (input: infer I) => infer _ } ? I : unknown)
-        & (Step extends { readonly schedule: Schedule.Schedule<infer _O, infer I, infer _R> } ? I : unknown)
+        & (Step extends { readonly schedule: Schedule.Schedule<infer _O, infer I, infer _E, infer _R> } ? I : unknown)
       )
     > :
     Out
@@ -292,6 +318,17 @@ const Proto: Omit<ExecutionPlan<any>, "steps"> = {
         while: step.while
           ? (input: any) => effect.provideContext(step.while!(input), context)
           : undefined,
+        schedule: step.schedule
+          ? Schedule.fromStep(
+            effect.provideContext(
+              effect.map(
+                Schedule.toStep(step.schedule),
+                (next) => (now: number, input: any) => effect.provideContext(next(now, input), context)
+              ),
+              context
+            )
+          )
+          : undefined,
         provide: Layer.isLayer(step.provide)
           ? Layer.provide(step.provide, Layer.succeedContext(context))
           : step.provide
@@ -331,6 +368,7 @@ const makeProto = <Provides, In, PlanE, PlanR>(
  *
  * @see {@link make} for building a plan from individual steps instead of combining existing plans
  *
+ * @stability unstable
  * @category combining
  * @since 3.16.0
  */
@@ -351,6 +389,7 @@ export const merge = <const Plans extends NonEmptyReadonlyArray<ExecutionPlan<an
  * `attempt` is the current 1-based attempt number, and `stepIndex` is the
  * 0-based index of the plan step currently being evaluated.
  *
+ * @stability unstable
  * @category metadata
  * @since 4.0.0
  */
@@ -368,6 +407,7 @@ export interface Metadata {
  * Use to read the active plan step and attempt while code is running under an
  * execution plan.
  *
+ * @stability unstable
  * @category services
  * @since 4.0.0
  */
@@ -388,6 +428,7 @@ export const CurrentMetadata = Context.Reference<Metadata>("effect/ExecutionPlan
  * 1-based attempt number within the current step, and `stepIndex` is the
  * 0-based index of the step being attempted.
  *
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */
@@ -406,6 +447,7 @@ export interface AttemptStart {
  * A successful attempt completes the plan, so this is always the final event.
  * `duration` is the elapsed time of the attempt.
  *
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */
@@ -427,6 +469,7 @@ export interface AttemptSuccess {
  * afterwards is decided by the step's `attempts`, `while`, and `schedule`; a
  * following `AttemptStart` indicates another attempt was made.
  *
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */
@@ -448,6 +491,7 @@ export interface AttemptFailure<E> {
  * `AttemptSuccess` or `AttemptFailure`. An interrupted attempt emits
  * `AttemptFailure` with the interruption cause.
  *
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */