effect 4.0.6 → 4.1.0

package/src/Semaphore.ts

@@ -13,10 +13,11 @@
  */
 import type * as Effect from "./Effect.ts"
 import type { Fiber } from "./Fiber.ts"
-import { dual } from "./Function.ts"
+import { dual, identity } from "./Function.ts"
 import * as core from "./internal/core.ts"
 import * as internal from "./internal/effect.ts"
 import type * as Option from "./Option.ts"
+import type * as Scope from "./Scope.ts"
 
 /**
  * A counting semaphore that coordinates concurrent access with permits.
@@ -134,6 +135,24 @@ export interface Semaphore {
    */
   take(this: Semaphore, permits: number): Effect.Effect<number>
 
+  /**
+   * Acquires the specified number of permits for the lifetime of the current
+   * scope, suspending the task if they are not yet available.
+   *
+   * **When to use**
+   *
+   * Use to hold permits until a scope closes, such as while a scoped resource
+   * is leased.
+   *
+   * **Details**
+   *
+   * Waiting can be interrupted unless the caller is uninterruptible. The
+   * permits are taken and their release is added to the scope in one
+   * uninterruptible step, so acquired permits are always returned when the
+   * scope closes.
+   */
+  takeScoped(this: Semaphore, permits: number): Effect.Effect<void, never, Scope.Scope>
+
   /**
    * Acquires the specified number of permits only if they are immediately
    * available.
@@ -214,26 +233,58 @@ export interface Semaphore {
  */
 export const makeUnsafe = (permits: number): Semaphore => new SemaphoreImpl(permits)
 
-const waitForPermits = <A, E, R>(
+interface Waiter {
+  readonly permits: number
+  resume: ((effect: Effect.Effect<void>) => void) | undefined
+}
+
+// The first queued request that fits in the free permits. Larger requests
+// ahead of it keep their place but are overtaken, as documented on `take`.
+const firstAvailableWaiter = (self: SemaphoreImpl): Waiter | undefined => {
+  for (const waiter of self.waiters) {
+    if (waiter.permits <= self.free) return waiter
+  }
+}
+
+const takePermits = <A, E, R>(
   self: SemaphoreImpl,
   n: number,
-  effect: Effect.Effect<A, E, R>
+  onAcquire: () => Effect.Effect<A, E, R>,
+  restore: <AX, EX, RX>(effect: Effect.Effect<AX, EX, RX>) => Effect.Effect<AX, EX, RX> = identity
 ): Effect.Effect<A, E, R> =>
-  internal.callback((resume) => {
-    if (self.free >= n) return resume(effect)
-    const observer = () => {
-      if (self.free < n) return
-      self.waiters.delete(observer)
-      resume(effect)
+  core.withFiber((fiber) => {
+    if (self.free >= n && firstAvailableWaiter(self) === undefined) {
+      self.taken += n
+      return onAcquire()
+    }
+    // A wake does not reserve permits: the waiter keeps its queue entry until
+    // it acquires or is interrupted, and re-checks eligibility when it runs.
+    const waiter: Waiter = { permits: n, resume: undefined }
+    const remove = () => {
+      if (self.waiters.delete(waiter)) self.releaseUnsafe(fiber, 0)
+      return undefined
     }
-    self.waiters.add(observer)
-    return internal.sync(() => {
-      self.waiters.delete(observer)
+    self.waiters.add(waiter)
+    internal.onExitUnsafe(fiber, remove)
+    const wait = restore(internal.callback<void>((resume) => {
+      // The fiber may have yielded since the last check, missing a wake.
+      if (firstAvailableWaiter(self) === waiter) {
+        resume(internal.void)
+      } else {
+        waiter.resume = resume
+      }
+    }))
+    const loop: Effect.Effect<A, E, R> = internal.flatMap(wait, () => {
+      if (firstAvailableWaiter(self) !== waiter) return loop
+      self.taken += n
+      remove()
+      return onAcquire()
     })
+    return loop
   })
 
 class SemaphoreImpl implements Semaphore {
-  public waiters = new Set<() => void>()
+  public waiters = new Set<Waiter>()
   public taken = 0
   public permits: number
 
@@ -246,14 +297,16 @@ class SemaphoreImpl implements Semaphore {
   }
 
   take(n: number): Effect.Effect<number> {
-    const take: Effect.Effect<number> = internal.suspend(() => {
-      if (this.free < n) {
-        return waitForPermits(this, n, take)
-      }
-      this.taken += n
-      return internal.succeed(n)
-    })
-    return take
+    return takePermits(this, n, () => internal.succeed(n))
+  }
+
+  takeScoped(n: number): Effect.Effect<void, never, Scope.Scope> {
+    return internal.uninterruptibleMask((restore) =>
+      internal.flatMap(
+        internal.scope,
+        (scope) => takePermits(this, n, () => internal.scopeAddFinalizer(scope, this.release(n)), restore)
+      )
+    )
   }
 
   takeIfAvailable(n: number): Effect.Effect<boolean> {
@@ -268,9 +321,17 @@ class SemaphoreImpl implements Semaphore {
     this.taken -= n
     if (this.waiters.size > 0) {
       fiber.currentDispatcher.scheduleTask(() => {
-        for (const observer of this.waiters) {
-          if (this.free <= 0) break
-          observer()
+        // Wake every queued request that fits in the free permits. Waiters
+        // that were already woken still count against the budget, since they
+        // keep their place until they acquire. Resumed fibers run inline and
+        // can add or remove waiters, so iterate over a snapshot.
+        let remaining = this.free
+        for (const waiter of Array.from(this.waiters)) {
+          if (!this.waiters.has(waiter) || waiter.permits > remaining) continue
+          remaining -= waiter.permits
+          const resume = waiter.resume
+          waiter.resume = undefined
+          resume?.(internal.void)
         }
       }, 0)
     }
@@ -296,24 +357,18 @@ class SemaphoreImpl implements Semaphore {
 
   withPermits(n: number) {
     return <A, E, R>(self: Effect.Effect<A, E, R>) =>
-      internal.uninterruptibleMask((restore) => {
-        const acquire: Effect.Effect<A, E, R> = internal.suspend(() => {
-          if (this.free < n) {
-            const wait = waitForPermits(this, n, internal.void)
-            return internal.flatMap(restore(wait), () => acquire)
-          }
-          this.taken += n
-          return internal.onExitPrimitive(
-            restore(self),
-            () => {
+      internal.uninterruptibleMask((restore) =>
+        takePermits(
+          this,
+          n,
+          () =>
+            internal.onExitPrimitive(restore(self), () => {
               this.releaseUnsafe(internal.getCurrentFiber()!, n)
               return undefined
-            },
-            true
-          )
-        })
-        return acquire
-      })
+            }, true),
+          restore
+        )
+      )
   }
 
   readonly withPermit = this.withPermits(1)
@@ -720,6 +775,119 @@ export const take: {
   (self: Semaphore, permits: number): Effect.Effect<number>
 } = dual(2, (self: Semaphore, permits: number) => self.take(permits))
 
+/**
+ * Acquires the specified number of permits until the current scope closes.
+ *
+ * **When to use**
+ *
+ * Use when permits should be held for the lifetime of a scope, such as while a
+ * scoped resource is leased.
+ *
+ * **Details**
+ *
+ * The effect waits until enough permits are available. The wait can be
+ * interrupted unless the caller is uninterruptible. The permits are taken and
+ * their release is added to the scope in one uninterruptible step, so acquired
+ * permits are always returned when the scope closes.
+ *
+ * **Example** (Holding a permit for a scope)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Semaphore } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const semaphore = yield* Semaphore.make(1)
+ *   yield* Effect.scoped(Semaphore.takeScoped(semaphore, 1))
+ *   return yield* Semaphore.takeIfAvailable(semaphore, 1)
+ * })
+ *
+ * Effect.runSync(program) // => true
+ * ```
+ *
+ * @see {@link take} for acquiring permits that are released manually
+ * @see {@link withPermits} for holding permits while one effect runs
+ *
+ * @stability stable
+ * @category combinators
+ * @since 4.0.7
+ */
+export const takeScoped: {
+  /**
+   * Acquires the specified number of permits until the current scope closes.
+   *
+   * **When to use**
+   *
+   * Use when permits should be held for the lifetime of a scope, such as while a
+   * scoped resource is leased.
+   *
+   * **Details**
+   *
+   * The effect waits until enough permits are available. The wait can be
+   * interrupted unless the caller is uninterruptible. The permits are taken and
+   * their release is added to the scope in one uninterruptible step, so acquired
+   * permits are always returned when the scope closes.
+   *
+   * **Example** (Holding a permit for a scope)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect, Semaphore } from "effect"
+   *
+   * const program = Effect.gen(function*() {
+   *   const semaphore = yield* Semaphore.make(1)
+   *   yield* Effect.scoped(Semaphore.takeScoped(semaphore, 1))
+   *   return yield* Semaphore.takeIfAvailable(semaphore, 1)
+   * })
+   *
+   * Effect.runSync(program) // => true
+   * ```
+   *
+   * @see {@link take} for acquiring permits that are released manually
+   * @see {@link withPermits} for holding permits while one effect runs
+   *
+   * @stability stable
+   * @category combinators
+   * @since 4.0.7
+   */
+  (permits: number): (self: Semaphore) => Effect.Effect<void, never, Scope.Scope>
+  /**
+   * Acquires the specified number of permits until the current scope closes.
+   *
+   * **When to use**
+   *
+   * Use when permits should be held for the lifetime of a scope, such as while a
+   * scoped resource is leased.
+   *
+   * **Details**
+   *
+   * The effect waits until enough permits are available. The wait can be
+   * interrupted unless the caller is uninterruptible. The permits are taken and
+   * their release is added to the scope in one uninterruptible step, so acquired
+   * permits are always returned when the scope closes.
+   *
+   * **Example** (Holding a permit for a scope)
+   *
+   * ```ts import.meta.vitest
+   * import { Effect, Semaphore } from "effect"
+   *
+   * const program = Effect.gen(function*() {
+   *   const semaphore = yield* Semaphore.make(1)
+   *   yield* Effect.scoped(Semaphore.takeScoped(semaphore, 1))
+   *   return yield* Semaphore.takeIfAvailable(semaphore, 1)
+   * })
+   *
+   * Effect.runSync(program) // => true
+   * ```
+   *
+   * @see {@link take} for acquiring permits that are released manually
+   * @see {@link withPermits} for holding permits while one effect runs
+   *
+   * @stability stable
+   * @category combinators
+   * @since 4.0.7
+   */
+  (self: Semaphore, permits: number): Effect.Effect<void, never, Scope.Scope>
+} = dual(2, (self: Semaphore, permits: number) => self.takeScoped(permits))
+
 /**
  * Acquires the specified number of permits only if they are immediately
  * available.

package/src/Sink.ts

@@ -2687,7 +2687,12 @@ export const catchCause: {
 ): Sink<A | A2, In, L, E2, R | R2> =>
   transformEffect(
     self,
-    Effect.catchCause((cause) => Effect.map(f(cause), (a2) => [a2 as A | A2] as const))
+    Effect.catchCause((cause) =>
+      // Upstream failures are not sink errors, so they bypass the handler.
+      Channel.hasUpstreamFailure(cause)
+        ? Effect.failCause(cause as Cause.Cause<never>)
+        : Effect.map(f(cause), (a2) => [a2 as A | A2] as const)
+    )
   ))
 
 const catch_: {
@@ -2774,7 +2779,15 @@ export const onExit: {
 ): Sink<A, In, L, E | E2, R | R2> =>
   transformEffect(
     self,
-    Effect.onExit((exit) => f(Exit.map(exit, ([a]) => a)))
+    Effect.onExit((exit) =>
+      // Upstream failures stop the sink like an interruption; they are not
+      // sink errors.
+      f(
+        Exit.isFailure(exit) && Channel.hasUpstreamFailure(exit.cause)
+          ? Exit.interrupt()
+          : Exit.map(exit, ([a]) => a)
+      )
+    )
   ))
 
 /**

package/src/Stream.ts

@@ -7295,17 +7295,12 @@ export const peel: {
   ): Effect.fn.Return<[A2, Stream<A, E, never>], E | E2, Scope.Scope | R | R2> {
     let cause: Cause.Cause<E | Cause.Done<void>> | undefined = undefined
     const originalPull = yield* Channel.toPull(self.channel)
-    const pull: Pull.Pull<
-      Arr.NonEmptyReadonlyArray<A>,
-      E
-    > = Effect.catchCause(originalPull, (cause_) => {
+    const pull = Effect.catchCause(originalPull, (cause_) => {
       cause = cause_
       return Effect.failCause(cause_)
     })
 
-    const [result, leftover] = yield* Effect.scopedWith((scope) =>
-      sink.transform(pull as Pull.Pull<Arr.NonEmptyReadonlyArray<A>>, scope)
-    )
+    const [result, leftover] = yield* Effect.scopedWith((scope) => runSink(sink, pull, scope))
     let stream: Stream<A, E> = cause ? empty : fromPull(Effect.succeed(originalPull))
     if (leftover) {
       stream = concat(fromArray(leftover), stream)
@@ -10252,6 +10247,9 @@ export const orDie = <A, E, R>(self: Stream<A, E, R>): Stream<A, never, R> => fr
  *
  * The `log` option controls whether the failure is logged before the stream
  * terminates.
+ * Set `log: "Unhandled"` to read `References.UnhandledLogLevel` when the
+ * failure occurs; `undefined` disables logging. Minimum log level filtering
+ * still applies.
  *
  * **Gotchas**
  *
@@ -10300,12 +10298,12 @@ export const orDie = <A, E, R>(self: Stream<A, E, R>): Stream<A, never, R> => fr
  */
 export const ignore: <
   Arg extends Stream<any, any, any> | {
-    readonly log?: boolean | Severity | undefined
+    readonly log?: boolean | Severity | "Unhandled" | undefined
   } | undefined
 >(
   selfOrOptions: Arg,
   options?: {
-    readonly log?: boolean | Severity | undefined
+    readonly log?: boolean | Severity | "Unhandled" | undefined
   } | undefined
 ) => [Arg] extends [Stream<infer A, infer _E, infer R>] ? Stream<A, never, R>
   : <A, E, R>(self: Stream<A, E, R>) => Stream<A, never, R> = dual(
@@ -10313,7 +10311,7 @@ export const ignore: <
     <A, E, R>(
       self: Stream<A, E, R>,
       options?: {
-        readonly log?: boolean | Severity | undefined
+        readonly log?: boolean | Severity | "Unhandled" | undefined
       } | undefined
     ): Stream<A, never, R> => fromChannel(Channel.ignore(self.channel, options))
   )
@@ -10326,6 +10324,12 @@ export const ignore: <
  * Use when you need to silently suppress a stream's entire failure cause,
  * including both typed errors and defects, rather than propagate it downstream.
  *
+ * **Details**
+ *
+ * Set `log: "Unhandled"` to read `References.UnhandledLogLevel` when the
+ * failure occurs; `undefined` disables logging. Minimum log level filtering
+ * still applies.
+ *
  * **Example** (Ignoring stream failure causes)
  *
  * ```ts import.meta.vitest
@@ -10350,19 +10354,19 @@ export const ignore: <
  */
 export const ignoreCause: <
   Arg extends Stream<any, any, any> | {
-    readonly log?: boolean | Severity | undefined
+    readonly log?: boolean | Severity | "Unhandled" | undefined
   } | undefined
 >(
   streamOrOptions: Arg,
   options?: {
-    readonly log?: boolean | Severity | undefined
+    readonly log?: boolean | Severity | "Unhandled" | undefined
   } | undefined
 ) => [Arg] extends [Stream<infer A, infer _E, infer R>] ? Stream<A, never, R>
   : <A, E, R>(self: Stream<A, E, R>) => Stream<A, never, R> = dual(
     (args) => isStream(args[0]),
     <A, E, R>(
       self: Stream<A, E, R>,
-      options?: { readonly log?: boolean | Severity | undefined } | undefined
+      options?: { readonly log?: boolean | Severity | "Unhandled" | undefined } | undefined
     ): Stream<A, never, R> => fromChannel(Channel.ignoreCause(self.channel, options))
   )
 
@@ -11098,7 +11102,7 @@ export const takeRight: {
     const count = Count.normalize(n)
     if (count === 0) return empty
     return mapAccumArray(self, MutableList.make<A>, (list, arr) => {
-      MutableList.appendAll(list, arr)
+      MutableList.appendAllUnsafe(list, arr)
       if (list.length > count) {
         MutableList.takeNVoid(list, list.length - count)
       }
@@ -12528,10 +12532,10 @@ export const rechunk: {
       let chunk = Arr.empty<A>() as Arr.NonEmptyArray<A>
       let index = 0
       let current: Arr.NonEmptyReadonlyArray<A> | undefined
-      let done = false
+      let cause: Cause.Cause<E | Cause.Done> | undefined
 
       return Effect.suspend(function loop(): Pull.Pull<Arr.NonEmptyReadonlyArray<A>, E, void, R> {
-        if (done) return Cause.done()
+        if (cause) return Effect.failCause(cause)
         else if (current === undefined) {
           return Effect.flatMap(pull, (arr) => {
             if (chunk.length === 0 && arr.length === target) {
@@ -12558,10 +12562,10 @@ export const rechunk: {
         current = undefined
         return loop()
       }).pipe(
-        Pull.catchDone(() => {
-          if (chunk.length === 0) return Cause.done()
+        Effect.catchCause((cause_) => {
+          if (chunk.length === 0) return Effect.failCause(cause_)
           const result = chunk
-          done = true
+          cause = cause_
           chunk = [] as any
           return Effect.succeed(result)
         })
@@ -15122,7 +15126,12 @@ const groupByImpl = <A, E, R, K, V, E2, R2>(
         body: constant(Effect.flatMap(pull, (arr) => f(arr, queues, queueMap))),
         step: constVoid
       }).pipe(
-        Effect.catchCause((cause) => Queue.failCause(out, cause)),
+        Effect.catchCause((cause) => {
+          for (const [, queue] of queueMap) {
+            Queue.endUnsafe(queue)
+          }
+          return Queue.failCause(out, cause)
+        }),
         Effect.forkIn(scope)
       )
 
@@ -15659,7 +15668,7 @@ export const aggregateWithin: {
         return buffer.state.exit as Exit.Exit<never, Cause.Done<void> | E>
       }
       hasInput.closeUnsafe()
-      const pull = emit(Effect.suspend(() => sink.transform(sinkUpstream as any, scope)))
+      const pull = emit(Effect.suspend(() => runSink(sink, sinkUpstream, scope)))
       return buffer.state._tag === "Open" ? Effect.raceFirst(pull, stepToBuffer) : pull
     })
   }))))
@@ -19327,11 +19336,28 @@ export const run: {
 ): Effect.Effect<A2, E | E2, R | R2> =>
   Effect.scopedWith((scope) =>
     Channel.toPullScoped(self.channel, scope).pipe(
-      Effect.flatMap((upstream) => sink.transform(upstream as any, scope)),
+      Effect.flatMap((upstream) => runSink(sink, upstream, scope)),
       Effect.map(([a]) => a)
     )
   ))
 
+/**
+ * Runs `sink` against `upstream`. Upstream failures bypass the sink's error
+ * handlers and are restored once the sink has exited.
+ */
+const runSink = <A, E, R, A2, L, E2, R2>(
+  sink: Sink.Sink<A2, A, L, E2, R2>,
+  upstream: Pull.Pull<Arr.NonEmptyReadonlyArray<A>, E, void, R>,
+  scope: Scope.Scope
+): Effect.Effect<Sink.End<A2, L>, E | E2, R | R2> =>
+  Channel.restoreUpstreamFailure<Sink.End<A2, L>, E | E2, R2>(
+    // The upstream pull runs in this fiber, which already provides `R`.
+    sink.transform(
+      Channel.upstreamFailureToDefect(upstream) as Pull.Pull<Arr.NonEmptyReadonlyArray<A>, never, void>,
+      scope
+    )
+  )
+
 /**
  * Runs the stream and collects all elements into an array.
  *

package/src/String.ts

@@ -1860,6 +1860,9 @@ export const constantCase: (self: string) => string = noCase({
  * Unlike {@link constantCase}, digit-letter boundaries are not split. For
  * example, `"api-v2 xml"` becomes `"API_V2_XML"`.
  *
+ * `configCase` is not idempotent: `"field2value"` becomes `"FIELD2VALUE"`, and
+ * applying it again gives `"FIELD2_VALUE"`.
+ *
  * @see {@link constantCase} for standard uppercase underscore-separated output
  * @stability stable
  * @category transforming

package/src/Terminal.ts

@@ -42,6 +42,12 @@ export interface Terminal {
    */
 
   readonly rows: Effect.Effect<number>
+  /**
+   * Subscribes to terminal size changes. The queue starts with the current
+   * dimensions, receives each resize until the scope closes, and keeps only the
+   * latest size.
+   */
+  readonly size: Effect.Effect<Queue.Dequeue<Size, Cause.Done>, never, Scope.Scope>
   /**
    * Reads input events from the default standard input.
    */
@@ -56,6 +62,18 @@ export interface Terminal {
   readonly display: (text: string) => Effect.Effect<void, PlatformError>
 }
 
+/**
+ * Terminal dimensions measured in character cells.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Size {
+  readonly columns: number
+  readonly rows: number
+}
+
 /**
  * Keyboard key metadata for terminal input, including the key name and
  * modifier state.
@@ -183,7 +201,7 @@ export const Terminal: Context.Service<Terminal, Terminal> = Context.Service("ef
  *
  * **Details**
  *
- * The implementation object supplies `columns`, `rows`, `readInput`,
+ * The implementation object supplies `columns`, `rows`, `size`, `readInput`,
  * `readLine`, and `display`; `make` attaches the `Terminal` service marker so
  * the result can be provided through the `Terminal` context service.
  *

package/src/Tracer.ts

@@ -326,6 +326,15 @@ export type SpanKind = "internal" | "server" | "client" | "producer" | "consumer
  * annotations, attributes, links, sampling and kind information, lifecycle
  * status, and methods to end the span or add attributes, events, and links.
  *
+ * **Details**
+ *
+ * Once a span has `Ended` status, implementations should ignore further calls
+ * to `end`, `attribute`, `event`, and `addLinks`, following the OpenTelemetry
+ * tracing specification. An ended span can still be read and used as a parent.
+ * The built-in span implementations follow this rule, and Effect does not
+ * record logs or `annotateCurrentSpan` attributes on an ended span, such as
+ * when a fiber outlives the span it was forked in.
+ *
  * **Example** (Working with spans)
  *
  * ```ts import.meta.vitest
@@ -684,7 +693,8 @@ export const nativeTracer: Tracer = make({
  * identifiers, the attribute map, and the event list are created lazily on
  * first access, so spans that are never inspected allocate as little as
  * possible. Attributes, events, links, and status are mutated through `Span`
- * methods.
+ * methods. Once the span has ended, those methods do nothing, so a second `end`
+ * keeps the original end time and exit.
  *
  * @see {@link Span} for the interface implemented by native spans
  *
@@ -748,6 +758,7 @@ export class NativeSpan implements Span {
   }
 
   end(endTime: bigint, exit: Exit.Exit<unknown, unknown>): void {
+    if (this.status._tag === "Ended") return
     this.status = {
       _tag: "Ended",
       endTime,
@@ -757,14 +768,17 @@ export class NativeSpan implements Span {
   }
 
   attribute(key: string, value: unknown): void {
+    if (this.status._tag === "Ended") return
     this.attributes.set(key, value)
   }
 
   event(name: string, startTime: bigint, attributes?: Record<string, unknown>): void {
+    if (this.status._tag === "Ended") return
     this.events.push([name, startTime, attributes ?? {}])
   }
 
   addLinks(links: ReadonlyArray<SpanLink>): void {
+    if (this.status._tag === "Ended") return
     // oxlint-disable-next-line no-restricted-syntax
     this.links.push(...links)
   }