effect 4.0.0-beta.103 → 4.0.0-beta.105

package/src/Effect.ts

@@ -15,7 +15,7 @@ import type * as Cause from "./Cause.ts"
 import type { Clock } from "./Clock.ts"
 import * as Context from "./Context.ts"
 import * as Duration from "./Duration.ts"
-import type { ExecutionPlan } from "./ExecutionPlan.ts"
+import type * as ExecutionPlan from "./ExecutionPlan.ts"
 import * as Exit from "./Exit.ts"
 import type { Fiber } from "./Fiber.ts"
 import type * as Filter from "./Filter.ts"
@@ -7790,6 +7790,14 @@ export const ignoreCause: <
  * and retry timing is derived per step (the first attempt uses the remaining
  * attempts schedule; later retries apply the step schedule at least once).
  *
+ * Attempts can be observed from outside the effect by passing
+ * `options.onEvent`, which receives an `ExecutionPlan.Event` before each
+ * attempt and after it settles. The handler is awaited inline before and after
+ * every attempt, so events are strictly ordered; keep it cheap. It cannot
+ * fail, which keeps observation from changing the plan's outcome, and its
+ * requirements are added to the resulting effect. Terminal events run like
+ * finalizers, so they are emitted even when the attempt is interrupted.
+ *
  * **Example** (Retrying with an execution plan)
  *
  * ```ts import.meta.vitest
@@ -7814,6 +7822,36 @@ export const ignoreCause: <
  * Effect.runSync(program) // => "good"
  * ```
  *
+ * **Example** (Observing execution-plan attempts)
+ *
+ * ```ts import.meta.vitest
+ * import { Context, Effect, ExecutionPlan, Layer } from "effect"
+ *
+ * const Endpoint = Context.Service<{ url: string }>("Endpoint")
+ *
+ * const fetchUrl = Effect.gen(function*() {
+ *   const endpoint = yield* Effect.service(Endpoint)
+ *   if (endpoint.url === "bad") {
+ *     return yield* Effect.fail("Unavailable")
+ *   }
+ *   return endpoint.url
+ * })
+ *
+ * const plan = ExecutionPlan.make(
+ *   { provide: Layer.succeed(Endpoint, { url: "bad" }) },
+ *   { provide: Layer.succeed(Endpoint, { url: "good" }) }
+ * )
+ *
+ * const events: Array<string> = []
+ * const program = Effect.withExecutionPlan(fetchUrl, plan, {
+ *   onEvent: (event) => Effect.sync(() => events.push(`${event._tag}:${event.stepIndex}`))
+ * })
+ *
+ * await Effect.runPromise(program) // => "good"
+ *
+ * events // => ["AttemptStart:0", "AttemptFailure:0", "AttemptStart:1", "AttemptSuccess:1"]
+ * ```
+ *
  * @category error handling
  * @since 3.16.0
  */
@@ -7828,6 +7866,14 @@ export const withExecutionPlan: {
    * and retry timing is derived per step (the first attempt uses the remaining
    * attempts schedule; later retries apply the step schedule at least once).
    *
+   * Attempts can be observed from outside the effect by passing
+   * `options.onEvent`, which receives an `ExecutionPlan.Event` before each
+   * attempt and after it settles. The handler is awaited inline before and after
+   * every attempt, so events are strictly ordered; keep it cheap. It cannot
+   * fail, which keeps observation from changing the plan's outcome, and its
+   * requirements are added to the resulting effect. Terminal events run like
+   * finalizers, so they are emitted even when the attempt is interrupted.
+   *
    * **Example** (Retrying with an execution plan)
    *
    * ```ts import.meta.vitest
@@ -7852,14 +7898,47 @@ export const withExecutionPlan: {
    * Effect.runSync(program) // => "good"
    * ```
    *
+   * **Example** (Observing execution-plan attempts)
+   *
+   * ```ts import.meta.vitest
+   * import { Context, Effect, ExecutionPlan, Layer } from "effect"
+   *
+   * const Endpoint = Context.Service<{ url: string }>("Endpoint")
+   *
+   * const fetchUrl = Effect.gen(function*() {
+   *   const endpoint = yield* Effect.service(Endpoint)
+   *   if (endpoint.url === "bad") {
+   *     return yield* Effect.fail("Unavailable")
+   *   }
+   *   return endpoint.url
+   * })
+   *
+   * const plan = ExecutionPlan.make(
+   *   { provide: Layer.succeed(Endpoint, { url: "bad" }) },
+   *   { provide: Layer.succeed(Endpoint, { url: "good" }) }
+   * )
+   *
+   * const events: Array<string> = []
+   * const program = Effect.withExecutionPlan(fetchUrl, plan, {
+   *   onEvent: (event) => Effect.sync(() => events.push(`${event._tag}:${event.stepIndex}`))
+   * })
+   *
+   * await Effect.runPromise(program) // => "good"
+   *
+   * events // => ["AttemptStart:0", "AttemptFailure:0", "AttemptStart:1", "AttemptSuccess:1"]
+   * ```
+   *
    * @category error handling
    * @since 3.16.0
    */
-  <Input, Provides, PlanE, PlanR>(
-    plan: ExecutionPlan<{ provides: Provides; input: Input; error: PlanE; requirements: PlanR }>
+  <Input, Provides, PlanE, PlanR, RX = never>(
+    plan: ExecutionPlan.ExecutionPlan<{ provides: Provides; input: Input; error: PlanE; requirements: PlanR }>,
+    options?: {
+      readonly onEvent?: ((event: ExecutionPlan.Event<Input | PlanE>) => Effect<void, never, RX>) | undefined
+    }
   ): <A, E extends Input, R>(
     effect: Effect<A, E, R>
-  ) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
+  ) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR | RX>
   /**
    * Applies an `ExecutionPlan` to an effect, retrying with step-provided resources
    * until it succeeds or the plan is exhausted.
@@ -7870,6 +7949,14 @@ export const withExecutionPlan: {
    * and retry timing is derived per step (the first attempt uses the remaining
    * attempts schedule; later retries apply the step schedule at least once).
    *
+   * Attempts can be observed from outside the effect by passing
+   * `options.onEvent`, which receives an `ExecutionPlan.Event` before each
+   * attempt and after it settles. The handler is awaited inline before and after
+   * every attempt, so events are strictly ordered; keep it cheap. It cannot
+   * fail, which keeps observation from changing the plan's outcome, and its
+   * requirements are added to the resulting effect. Terminal events run like
+   * finalizers, so they are emitted even when the attempt is interrupted.
+   *
    * **Example** (Retrying with an execution plan)
    *
    * ```ts import.meta.vitest
@@ -7894,13 +7981,46 @@ export const withExecutionPlan: {
    * Effect.runSync(program) // => "good"
    * ```
    *
+   * **Example** (Observing execution-plan attempts)
+   *
+   * ```ts import.meta.vitest
+   * import { Context, Effect, ExecutionPlan, Layer } from "effect"
+   *
+   * const Endpoint = Context.Service<{ url: string }>("Endpoint")
+   *
+   * const fetchUrl = Effect.gen(function*() {
+   *   const endpoint = yield* Effect.service(Endpoint)
+   *   if (endpoint.url === "bad") {
+   *     return yield* Effect.fail("Unavailable")
+   *   }
+   *   return endpoint.url
+   * })
+   *
+   * const plan = ExecutionPlan.make(
+   *   { provide: Layer.succeed(Endpoint, { url: "bad" }) },
+   *   { provide: Layer.succeed(Endpoint, { url: "good" }) }
+   * )
+   *
+   * const events: Array<string> = []
+   * const program = Effect.withExecutionPlan(fetchUrl, plan, {
+   *   onEvent: (event) => Effect.sync(() => events.push(`${event._tag}:${event.stepIndex}`))
+   * })
+   *
+   * await Effect.runPromise(program) // => "good"
+   *
+   * events // => ["AttemptStart:0", "AttemptFailure:0", "AttemptStart:1", "AttemptSuccess:1"]
+   * ```
+   *
    * @category error handling
    * @since 3.16.0
    */
-  <A, E extends Input, R, Provides, Input, PlanE, PlanR>(
+  <A, E extends Input, R, Provides, Input, PlanE, PlanR, RX = never>(
     effect: Effect<A, E, R>,
-    plan: ExecutionPlan<{ provides: Provides; input: Input; error: PlanE; requirements: PlanR }>
-  ): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
+    plan: ExecutionPlan.ExecutionPlan<{ provides: Provides; input: Input; error: PlanE; requirements: PlanR }>,
+    options?: {
+      readonly onEvent?: ((event: ExecutionPlan.Event<E | PlanE>) => Effect<void, never, RX>) | undefined
+    }
+  ): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR | RX>
 } = internalExecutionPlan.withExecutionPlan
 
 /**
@@ -12005,7 +12125,7 @@ export const updateService: {
    * @category providing services
    * @since 2.0.0
    */
-  <I, A>(service: Context.Key<I, A>, f: (value: A) => A): <XA, E, R>(self: Effect<XA, E, R>) => Effect<XA, E, R | I>
+  <I, A>(service: Context.Key<I, A>, f: (value: A) => NoInfer<A>): <XA, E, R>(self: Effect<XA, E, R>) => Effect<XA, E, R | I>
   /**
    * Runs an effect with a service implementation transformed by the provided
    * function.
@@ -12041,7 +12161,11 @@ export const updateService: {
    * @category providing services
    * @since 2.0.0
    */
-  <XA, E, R, I, A>(self: Effect<XA, E, R>, service: Context.Key<I, A>, f: (value: A) => A): Effect<XA, E, R | I>
+  <XA, E, R, I, A>(
+    self: Effect<XA, E, R>,
+    service: Context.Key<I, A>,
+    f: (value: A) => NoInfer<A>
+  ): Effect<XA, E, R | I>
 } = internal.updateService
 
 /**
@@ -12105,7 +12229,7 @@ export const updateService: {
  */
 export const updateServiceScoped: <I, A>(
   service: Context.Key<I, A>,
-  f: (value: A) => A,
+  f: (value: A) => NoInfer<A>,
   options?: {
     readonly reset?: ((original: A, updated: A, current: A) => A) | undefined
   } | undefined
@@ -12513,7 +12637,7 @@ export const provideServiceEffect: {
    * @category providing services
    * @since 2.0.0
    */
-  <I, S, E2, R2>(service: Context.Key<I, S>, acquire: Effect<S, E2, R2>): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E | E2, Exclude<R, I> | R2>
+  <I, S, E2, R2>(service: Context.Key<I, S>, acquire: Effect<NoInfer<S>, E2, R2>): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E | E2, Exclude<R, I> | R2>
   /**
    * Provides one service to an effect using an effectful acquisition.
    *
@@ -12572,7 +12696,7 @@ export const provideServiceEffect: {
   <A, E, R, I, S, E2, R2>(
     self: Effect<A, E, R>,
     service: Context.Key<I, S>,
-    acquire: Effect<S, E2, R2>
+    acquire: Effect<NoInfer<S>, E2, R2>
   ): Effect<A, E | E2, Exclude<R, I> | R2>
 } = internal.provideServiceEffect
 
@@ -15378,7 +15502,7 @@ export const schedule: {
    * @category repetition
    * @since 2.0.0
    */
-  <Output, Error, Env>(schedule: Schedule<Output, unknown, Error, Env>): <A, E, R>(self: Effect<A, E, R>) => Effect<Output, E, R | Env>
+  <Output, Error, Env>(schedule: Schedule<Output, unknown, Error, Env>): <A, E, R>(self: Effect<A, E, R>) => Effect<Output, E | Error, R | Env>
   /**
    * Runs an effect repeatedly according to a schedule and returns the schedule's
    * final output.
@@ -15419,11 +15543,11 @@ export const schedule: {
    * @category repetition
    * @since 2.0.0
    */
-  <A, E, R, Output, Error, Env>(self: Effect<A, E, R>, schedule: Schedule<Output, unknown, Error, Env>): Effect<Output, E, R | Env>
+  <A, E, R, Output, Error, Env>(self: Effect<A, E, R>, schedule: Schedule<Output, unknown, Error, Env>): Effect<Output, E | Error, R | Env>
 } = dual(2, <A, E, R, Output, Error, Env>(
   self: Effect<A, E, R>,
   schedule: Schedule<Output, unknown, Error, Env>
-): Effect<Output, E, R | Env> => scheduleFrom(self, undefined, schedule))
+): Effect<Output, E | Error, R | Env> => scheduleFrom(self, undefined, schedule))
 
 /**
  * Runs an effect repeatedly according to a schedule that is initialized with a
@@ -15502,7 +15626,7 @@ export const scheduleFrom: {
    * @category repetition
    * @since 2.0.0
    */
-  <Input, Output, Error, Env>(initial: Input, schedule: Schedule<Output, Input, Error, Env>): <E, R>(self: Effect<Input, E, R>) => Effect<Output, E, R | Env>
+  <Input, Output, Error, Env>(initial: Input, schedule: Schedule<Output, Input, Error, Env>): <E, R>(self: Effect<Input, E, R>) => Effect<Output, E | Error, R | Env>
   /**
    * Runs an effect repeatedly according to a schedule that is initialized with a
    * specific schedule input.
@@ -15545,7 +15669,7 @@ export const scheduleFrom: {
     self: Effect<Input, E, R>,
     initial: Input,
     schedule: Schedule<Output, Input, Error, Env>
-  ): Effect<Output, E, R | Env>
+  ): Effect<Output, E | Error, R | Env>
 } = internalSchedule.scheduleFrom
 
 // -----------------------------------------------------------------------------

package/src/Equal.ts

@@ -360,10 +360,14 @@ function compareRecords(
 /** @internal */
 export function makeCompareMap<K, V>(keyEquivalence: Equivalence<K>, valueEquivalence: Equivalence<V>) {
   return function compareMaps(self: Iterable<[K, V]>, that: Iterable<[K, V]>): boolean {
+    const thatEntries = Array.from(that)
     for (const [selfKey, selfValue] of self) {
       let found = false
-      for (const [thatKey, thatValue] of that) {
+      for (let i = 0; i < thatEntries.length; i++) {
+        const [thatKey, thatValue] = thatEntries[i]
         if (keyEquivalence(selfKey, thatKey) && valueEquivalence(selfValue, thatValue)) {
+          thatEntries[i] = thatEntries[thatEntries.length - 1]
+          thatEntries.pop()
           found = true
           break
         }
@@ -382,10 +386,14 @@ const compareMaps = makeCompareMap(compareBoth, compareBoth)
 /** @internal */
 export function makeCompareSet<A>(equivalence: Equivalence<A>) {
   return function compareSets(self: Iterable<A>, that: Iterable<A>): boolean {
+    const thatValues = Array.from(that)
     for (const selfValue of self) {
       let found = false
-      for (const thatValue of that) {
+      for (let i = 0; i < thatValues.length; i++) {
+        const thatValue = thatValues[i]
         if (equivalence(selfValue, thatValue)) {
+          thatValues[i] = thatValues[thatValues.length - 1]
+          thatValues.pop()
           found = true
           break
         }

package/src/ExecutionPlan.ts

@@ -10,7 +10,9 @@
  * @since 3.16.0
  */
 import type { NonEmptyReadonlyArray } from "./Array.ts"
+import type * as Cause from "./Cause.ts"
 import * as Context from "./Context.ts"
+import type * as Duration from "./Duration.ts"
 import type * as Effect from "./Effect.ts"
 import { constant } from "./Function.ts"
 import * as effect from "./internal/effect.ts"
@@ -179,7 +181,7 @@ export const make = <const Steps extends NonEmptyReadonlyArray<make.Step>>(
     | (Steps[number]["schedule"] extends Schedule.Schedule<infer _O, infer _I, infer R> ? R : never)
 }> =>
   makeProto(steps.map((options, i) => {
-    if (options.attempts && options.attempts < 1) {
+    if (options.attempts !== undefined && options.attempts < 1) {
       throw new Error(`ExecutionPlan.make: step[${i}].attempts must be greater than 0`)
     }
     return {
@@ -372,3 +374,78 @@ export const CurrentMetadata = Context.Reference<Metadata>("effect/ExecutionPlan
     stepIndex: 0
   })
 })
+
+/**
+ * Lifecycle event emitted before an execution-plan attempt runs.
+ *
+ * **Details**
+ *
+ * `attempt` is the cumulative 1-based attempt number across all steps and
+ * matches `CurrentMetadata.attempt` for the same attempt. `stepAttempt` is the
+ * 1-based attempt number within the current step, and `stepIndex` is the
+ * 0-based index of the step being attempted.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface AttemptStart {
+  readonly _tag: "AttemptStart"
+  readonly attempt: number
+  readonly stepAttempt: number
+  readonly stepIndex: number
+}
+
+/**
+ * Lifecycle event emitted when an execution-plan attempt succeeds.
+ *
+ * **Details**
+ *
+ * A successful attempt completes the plan, so this is always the final event.
+ * `duration` is the elapsed time of the attempt.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface AttemptSuccess {
+  readonly _tag: "AttemptSuccess"
+  readonly attempt: number
+  readonly stepAttempt: number
+  readonly stepIndex: number
+  readonly duration: Duration.Duration
+}
+
+/**
+ * Lifecycle event emitted when an execution-plan attempt fails.
+ *
+ * **Details**
+ *
+ * `cause` holds the full failure cause, so defects and interruption are
+ * reported as well as expected errors. Whether the plan retries or fails over
+ * afterwards is decided by the step's `attempts`, `while`, and `schedule`; a
+ * following `AttemptStart` indicates another attempt was made.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface AttemptFailure<E> {
+  readonly _tag: "AttemptFailure"
+  readonly attempt: number
+  readonly stepAttempt: number
+  readonly stepIndex: number
+  readonly duration: Duration.Duration
+  readonly cause: Cause.Cause<E>
+}
+
+/**
+ * Union of the lifecycle events emitted while an execution plan runs.
+ *
+ * **Details**
+ *
+ * Every `AttemptStart` is followed by exactly one terminal event, either
+ * `AttemptSuccess` or `AttemptFailure`. An interrupted attempt emits
+ * `AttemptFailure` with the interruption cause.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type Event<E> = AttemptStart | AttemptSuccess | AttemptFailure<E>

package/src/FiberSet.ts

@@ -100,7 +100,7 @@ const Proto = {
   ...PipeInspectableProto,
   toJSON(this: FiberSet<unknown, unknown>) {
     return {
-      _id: "FiberMap",
+      _id: "FiberSet",
       state: this.state
     }
   }

package/src/FileSystem.ts

@@ -1010,7 +1010,7 @@ export const isFile = (u: unknown): u is File => hasProperty(u, FileTypeId)
  * const file: FileSystem.File = {
  *   [FileSystem.FileTypeId]: FileSystem.FileTypeId,
  *   stat: Effect.succeed({ size: FileSystem.Size(5) } as FileSystem.File.Info),
- *   seek: () => Effect.void,
+ *   seek: () => Effect.succeed(FileSystem.Size(0)),
  *   sync: Effect.void,
  *   read: (buffer) => Effect.sync(() => {
  *     buffer.set([1, 2, 3, 4, 5])
@@ -1040,7 +1040,7 @@ export const isFile = (u: unknown): u is File => hasProperty(u, FileTypeId)
 export interface File {
   readonly [FileTypeId]: typeof FileTypeId
   readonly stat: Effect.Effect<File.Info, PlatformError>
-  readonly seek: (offset: SizeInput, from: SeekMode) => Effect.Effect<void>
+  readonly seek: (offset: SizeInput, from: SeekMode) => Effect.Effect<Size>
   readonly sync: Effect.Effect<void, PlatformError>
   readonly read: (buffer: Uint8Array) => Effect.Effect<Size, PlatformError>
   readonly readAlloc: (size: SizeInput) => Effect.Effect<Option.Option<Uint8Array>, PlatformError>

package/src/Function.ts

@@ -1493,11 +1493,12 @@ export const SK = <A, B>(_: A, b: B): B => b
  * **Details**
  *
  * Each memoized wrapper owns a private `WeakMap` keyed by object identity.
- * Cached `undefined` results are still returned because the cache is checked
- * with `WeakMap.has`.
  *
  * **Gotchas**
  *
+ * `undefined` is reserved to represent a cache miss and is therefore not
+ * supported as a return value.
+ *
  * Structurally equal objects do not share cache entries. If the same object is
  * mutated after its first call, later calls still return the cached result for
  * that reference.
@@ -1505,12 +1506,11 @@ export const SK = <A, B>(_: A, b: B): B => b
  * @category caching
  * @since 4.0.0
  */
-export function memoize<A extends object, O>(f: (a: A) => O): (ast: A) => O {
+export function memoize<A extends object, O extends {} | null>(f: (a: A) => O): (ast: A) => O {
   const cache = new WeakMap<object, O>()
   return (a) => {
-    if (cache.has(a)) {
-      return cache.get(a)!
-    }
+    const cached = cache.get(a)
+    if (cached !== undefined) return cached
     const result = f(a)
     cache.set(a, result)
     return result

package/src/Iterable.ts

@@ -3276,19 +3276,20 @@ export const flatten = <A>(self: Iterable<Iterable<A>>): Iterable<A> => ({
     const outerIterator = self[Symbol.iterator]()
     let innerIterator: Iterator<A> | undefined
     function next() {
-      if (innerIterator === undefined) {
-        const next = outerIterator.next()
-        if (next.done) {
-          return next
+      while (true) {
+        if (innerIterator === undefined) {
+          const next = outerIterator.next()
+          if (next.done) {
+            return next
+          }
+          innerIterator = next.value[Symbol.iterator]()
+        }
+        const result = innerIterator.next()
+        if (!result.done) {
+          return result
         }
-        innerIterator = next.value[Symbol.iterator]()
-      }
-      const result = innerIterator.next()
-      if (result.done) {
         innerIterator = undefined
-        return next()
       }
-      return result
     }
     return { next }
   }

package/src/Layer.ts

@@ -447,11 +447,13 @@ class MemoMapImpl implements MemoMap {
     scope: Scope.Scope,
     build: (memoMap: MemoMap, scope: Scope.Scope) => Effect<Context.Context<ROut>, E, RIn>
   ): Effect<Context.Context<ROut>, E, RIn> {
-    const existing = this.get(layer, scope)
-    if (existing) {
-      return existing
-    }
-    return memoMapBuild(this, layer, scope, build)
+    return internalEffect.suspend(() => {
+      const existing = this.get(layer, scope)
+      if (existing) {
+        return existing
+      }
+      return memoMapBuild(this, layer, scope, build)
+    })
   }
 }