effect 4.0.1 → 4.0.2

package/src/PubSub.ts

@@ -8,6 +8,7 @@
  * subscribers, message-taking helpers, capacity and shutdown operations, a
  * type guard, and low-level types for custom hub strategies.
  *
+ * @stability stable
  * @since 2.0.0
  */
 import * as Arr from "./Array.ts"
@@ -60,6 +61,7 @@ const TypeId = "~effect/PubSub"
  * actual // => ["Hello", "World"]
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -81,6 +83,7 @@ export interface PubSub<in out A> extends Pipeable {
  * `PubSub`, including atomic implementations, backing subscriptions, replay
  * windows, and delivery strategies.
  *
+ * @stability stable
  * @since 2.0.0
  */
 export declare namespace PubSub {
@@ -162,12 +165,18 @@ export declare namespace PubSub {
     /**
      * Describes how publishers should signal to subscribers that they are
      * waiting for space to become available in the `PubSub`.
+     *
+     * **Details**
+     *
+     * The publisher may have yielded since `publish` checked `ended`, so it
+     * must be checked again before registering or publishing the surplus.
      */
     handleSurplus(
       pubsub: Atomic<A>,
       subscribers: Subscribers<A>,
       elements: Iterable<A>,
-      isShutdown: MutableRef.MutableRef<boolean>
+      isShutdown: MutableRef.MutableRef<boolean>,
+      ended: MutableRef.MutableRef<Option.Option<A>>
     ): Effect.Effect<boolean>
 
     /**
@@ -223,6 +232,7 @@ export declare namespace PubSub {
  * actual // => [true, false, false]
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -259,6 +269,7 @@ const SubscriptionTypeId = "~effect/PubSub/Subscription"
  * actual // => { message: "msg1", messages: ["msg2"], allMessages: ["msg3"] }
  * ```
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -302,6 +313,7 @@ export interface Subscription<out A> extends Pipeable {
  * actual // => true
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -333,6 +345,8 @@ export const make = <A>(
  * them. When the capacity is full, publishers suspend until space is available.
  * Pass an options object to configure both `capacity` and an optional replay
  * buffer for late subscribers.
+ * The capacity must be a positive integer or `Infinity` for unbounded storage.
+ * Invalid capacities cause the effect to die.
  *
  * **Example** (Creating a bounded PubSub)
  *
@@ -359,6 +373,7 @@ export const make = <A>(
  * actual // => [100, 100]
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -379,6 +394,8 @@ export const bounded = <A>(
  *
  * **Details**
  *
+ * The capacity must be a positive integer or `Infinity` for unbounded storage.
+ * Invalid capacities cause the effect to die.
  * For best performance use capacities that are powers of two.
  *
  * **Example** (Dropping messages when full)
@@ -406,6 +423,7 @@ export const bounded = <A>(
  * actual // => { dropped: true, messages: ["msg1", "msg2", "msg3"] }
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -426,6 +444,8 @@ export const dropping = <A>(
  *
  * **Details**
  *
+ * The capacity must be a positive integer or `Infinity` for unbounded storage.
+ * Invalid capacities cause the effect to die.
  * For best performance use capacities that are powers of two.
  *
  * **Example** (Sliding old messages when full)
@@ -452,6 +472,7 @@ export const dropping = <A>(
  * actual // => ["msg2", "msg3", "msg4"]
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -492,6 +513,7 @@ export const sliding = <A>(
  * actual // => ["message-0", "message-1", "message-2"]
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -519,8 +541,9 @@ export const unbounded = <A>(options?: {
  *
  * **Gotchas**
  *
- * The capacity must be greater than zero; invalid capacities throw
- * synchronously before an atomic implementation is created.
+ * The capacity must be a positive integer or `Infinity` for unbounded storage;
+ * invalid capacities throw synchronously before an atomic implementation is
+ * created.
  *
  * @see {@link make} for constructing a `PubSub` from an atomic implementation and delivery strategy
  * @see {@link makeAtomicUnbounded} for an atomic implementation without a bounded capacity
@@ -528,6 +551,7 @@ export const unbounded = <A>(options?: {
  * @see {@link dropping} for the higher-level dropping constructor
  * @see {@link sliding} for the higher-level sliding constructor
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -569,6 +593,7 @@ export const makeAtomicBounded = <A>(
  * @see {@link make} for wrapping an atomic implementation with a delivery strategy
  * @see {@link unbounded} for the high-level effectful constructor for unbounded `PubSub` values
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -599,6 +624,7 @@ export const makeAtomicUnbounded = <A>(options?: {
  * actual // => [100, Number.MAX_SAFE_INTEGER]
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -639,6 +665,7 @@ export const capacity = <A>(self: PubSub<A>): number => self.pubsub.capacity
  * actual // => { initialSize: 0, afterPublish: 2, messages: ["msg1", "msg2"] }
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -671,6 +698,7 @@ export const size = <A>(self: PubSub<A>): Effect.Effect<number> => Effect.sync((
  * actual // => 0
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 4.0.0
  */
@@ -714,6 +742,7 @@ export const sizeUnsafe = <A>(self: PubSub<A>): number => {
  * actual // => { initiallyFull: false, nowFull: true, messages: ["msg1", "msg2"] }
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -748,6 +777,7 @@ export const isFull = <A>(self: PubSub<A>): Effect.Effect<boolean> =>
  * actual // => { initiallyEmpty: true, nowEmpty: false, message: "Hello" }
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -785,6 +815,7 @@ export const isEmpty = <A>(self: PubSub<A>): Effect.Effect<boolean> => Effect.ma
  * actual // => { isShutdown: true, published: false }
  * ```
  *
+ * @stability stable
  * @category lifecycle
  * @since 2.0.0
  */
@@ -855,6 +886,7 @@ export const shutdown = <A>(self: PubSub<A>): Effect.Effect<void> =>
  *
  * @see {@link shutdown} for interrupting subscribers instead of delivering a final message
  *
+ * @stability stable
  * @category lifecycle
  * @since 4.0.0
  */
@@ -916,6 +948,7 @@ export const end: {
    *
    * @see {@link shutdown} for interrupting subscribers instead of delivering a final message
    *
+   * @stability stable
    * @category lifecycle
    * @since 4.0.0
    */
@@ -977,6 +1010,7 @@ export const end: {
    *
    * @see {@link shutdown} for interrupting subscribers instead of delivering a final message
    *
+   * @stability stable
    * @category lifecycle
    * @since 4.0.0
    */
@@ -990,6 +1024,7 @@ export const end: {
  *
  * See {@link end} for the semantics.
  *
+ * @stability stable
  * @category lifecycle
  * @since 4.0.0
  */
@@ -1001,6 +1036,7 @@ export const endUnsafe: {
    *
    * See {@link end} for the semantics.
    *
+   * @stability stable
    * @category lifecycle
    * @since 4.0.0
    */
@@ -1012,6 +1048,7 @@ export const endUnsafe: {
    *
    * See {@link end} for the semantics.
    *
+   * @stability stable
    * @category lifecycle
    * @since 4.0.0
    */
@@ -1065,6 +1102,7 @@ export const endUnsafe: {
  * actual // => [false, true]
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -1095,6 +1133,7 @@ export const isShutdown = <A>(self: PubSub<A>): Effect.Effect<boolean> => Effect
  * actual // => [false, true]
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 4.0.0
  */
@@ -1132,6 +1171,7 @@ export const isShutdownUnsafe = <A>(self: PubSub<A>): boolean => self.shutdownFl
  * actual // => "PubSub has been shutdown!"
  * ```
  *
+ * @stability stable
  * @category lifecycle
  * @since 2.0.0
  */
@@ -1176,6 +1216,7 @@ export const awaitShutdown = <A>(self: PubSub<A>): Effect.Effect<void> => self.s
  *
  * @see {@link publishUnsafe} for a synchronous non-blocking attempt that does not run effectful surplus handling
  *
+ * @stability stable
  * @category publishing
  * @since 2.0.0
  */
@@ -1219,6 +1260,7 @@ export const publish: {
    *
    * @see {@link publishUnsafe} for a synchronous non-blocking attempt that does not run effectful surplus handling
    *
+   * @stability stable
    * @category publishing
    * @since 2.0.0
    */
@@ -1262,6 +1304,7 @@ export const publish: {
    *
    * @see {@link publishUnsafe} for a synchronous non-blocking attempt that does not run effectful surplus handling
    *
+   * @stability stable
    * @category publishing
    * @since 2.0.0
    */
@@ -1281,7 +1324,8 @@ export const publish: {
       self.pubsub,
       self.subscribers,
       [value],
-      self.shutdownFlag
+      self.shutdownFlag,
+      self.ended
     )
   }))
 
@@ -1316,6 +1360,7 @@ export const publish: {
  *
  * @see {@link publish} for effectful publishing that honors the configured surplus strategy
  *
+ * @stability stable
  * @category publishing
  * @since 4.0.0
  */
@@ -1351,6 +1396,7 @@ export const publishUnsafe: {
    *
    * @see {@link publish} for effectful publishing that honors the configured surplus strategy
    *
+   * @stability stable
    * @category publishing
    * @since 4.0.0
    */
@@ -1386,6 +1432,7 @@ export const publishUnsafe: {
    *
    * @see {@link publish} for effectful publishing that honors the configured surplus strategy
    *
+   * @stability stable
    * @category publishing
    * @since 4.0.0
    */
@@ -1431,6 +1478,7 @@ export const publishUnsafe: {
  * actual // => { allPublished: true, firstBatch: ["msg1", "msg2"], result: true, secondBatch: ["msg3", "msg4"] }
  * ```
  *
+ * @stability stable
  * @category publishing
  * @since 2.0.0
  */
@@ -1467,6 +1515,7 @@ export const publishAll: {
    * actual // => { allPublished: true, firstBatch: ["msg1", "msg2"], result: true, secondBatch: ["msg3", "msg4"] }
    * ```
    *
+   * @stability stable
    * @category publishing
    * @since 2.0.0
    */
@@ -1503,6 +1552,7 @@ export const publishAll: {
    * actual // => { allPublished: true, firstBatch: ["msg1", "msg2"], result: true, secondBatch: ["msg3", "msg4"] }
    * ```
    *
+   * @stability stable
    * @category publishing
    * @since 2.0.0
    */
@@ -1521,7 +1571,8 @@ export const publishAll: {
       self.pubsub,
       self.subscribers,
       surplus,
-      self.shutdownFlag
+      self.shutdownFlag,
+      self.ended
     )
   }))
 
@@ -1573,6 +1624,7 @@ export const publishAll: {
  * actual // => [["Hello", "World"], ["Broadcast", "Broadcast"]]
  * ```
  *
+ * @stability stable
  * @category subscriptions
  * @since 2.0.0
  */
@@ -1640,6 +1692,7 @@ const unsubscribe = <A>(self: Subscription<A>): Effect.Effect<void> =>
  * actual // => "Hello"
  * ```
  *
+ * @stability stable
  * @category subscriptions
  * @since 4.0.0
  */
@@ -1688,6 +1741,7 @@ export const take = <A>(self: Subscription<A>): Effect.Effect<A> =>
  * actual // => ["msg1", "msg2", "msg3"]
  * ```
  *
+ * @stability stable
  * @category subscriptions
  * @since 4.0.0
  */
@@ -1714,7 +1768,17 @@ export const takeAll = <A>(self: Subscription<A>): Effect.Effect<Arr.NonEmptyArr
 const pollForItem = <A>(self: Subscription<A>) =>
   Effect.callback<A>((resume) => {
     if (self.shutdownFlag.current) return resume(Effect.interrupt)
-    if (Option.isSome(self.ended.current)) return resume(Effect.succeed(self.ended.current.value))
+    if (Option.isSome(self.ended.current)) {
+      // Messages may have been published after the empty check, before this callback ran.
+      const message = self.pollers.length === 0
+        ? self.subscription.poll()
+        : MutableList.Empty
+      if (message !== MutableList.Empty) {
+        self.strategy.onPubSubEmptySpaceUnsafe(self.pubsub, self.subscribers)
+        return resume(Effect.succeed(message))
+      }
+      return resume(Effect.succeed(self.ended.current.value))
+    }
     const deferred = Deferred.makeUnsafe<A>()
     let set = self.subscribers.get(self.subscription)
     if (!set) {
@@ -1767,6 +1831,7 @@ const pollForItem = <A>(self: Subscription<A>) =>
  * actual // => [["msg1", "msg2", "msg3"], ["msg4", "msg5"], []]
  * ```
  *
+ * @stability stable
  * @category subscriptions
  * @since 4.0.0
  */
@@ -1804,6 +1869,7 @@ export const takeUpTo: {
    * actual // => [["msg1", "msg2", "msg3"], ["msg4", "msg5"], []]
    * ```
    *
+   * @stability stable
    * @category subscriptions
    * @since 4.0.0
    */
@@ -1841,6 +1907,7 @@ export const takeUpTo: {
    * actual // => [["msg1", "msg2", "msg3"], ["msg4", "msg5"], []]
    * ```
    *
+   * @stability stable
    * @category subscriptions
    * @since 4.0.0
    */
@@ -1893,6 +1960,7 @@ export const takeUpTo: {
  * actual // => ["msg1", "msg2", "msg3"]
  * ```
  *
+ * @stability stable
  * @category subscriptions
  * @since 4.0.0
  */
@@ -1927,6 +1995,7 @@ export const takeBetween: {
    * actual // => ["msg1", "msg2", "msg3"]
    * ```
    *
+   * @stability stable
    * @category subscriptions
    * @since 4.0.0
    */
@@ -1961,6 +2030,7 @@ export const takeBetween: {
    * actual // => ["msg1", "msg2", "msg3"]
    * ```
    *
+   * @stability stable
    * @category subscriptions
    * @since 4.0.0
    */
@@ -2047,6 +2117,7 @@ const takeRemainderLoop = <A>(
  *
  * @see {@link remainingUnsafe} for a synchronous check that reports shutdown as `Option.none()`
  *
+ * @stability stable
  * @category getters
  * @since 4.0.0
  */
@@ -2083,6 +2154,7 @@ export const remaining = <A>(self: Subscription<A>): Effect.Effect<number> =>
  *
  * @see {@link remaining} for the effectful variant that interrupts on shutdown
  *
+ * @stability stable
  * @category getters
  * @since 4.0.0
  */
@@ -2970,7 +3042,7 @@ const makePubSubUnsafe = <A>(
 ): PubSub<A> => new PubSubImpl(pubsub, subscribers, scope, shutdownHook, shutdownFlag, strategy, ended)
 
 const ensureCapacity = (capacity: number): void => {
-  if (capacity <= 0) {
+  if (capacity <= 0 || (capacity !== Infinity && !Number.isInteger(capacity))) {
     throw new Error(`Cannot construct PubSub with capacity of ${capacity}`)
   }
 }
@@ -3001,6 +3073,7 @@ const ensureCapacity = (capacity: number): void => {
  * @see {@link DroppingStrategy} for dropping new messages when capacity is full
  * @see {@link SlidingStrategy} for evicting old messages when capacity is full
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -3023,9 +3096,13 @@ export class BackPressureStrategy<in out A> implements PubSub.Strategy<A> {
     pubsub: PubSub.Atomic<A>,
     subscribers: PubSub.Subscribers<A>,
     elements: Iterable<A>,
-    isShutdown: MutableRef.MutableRef<boolean>
+    isShutdown: MutableRef.MutableRef<boolean>,
+    ended: MutableRef.MutableRef<Option.Option<A>>
   ): Effect.Effect<boolean> {
     return Effect.callback<boolean>((resume) => {
+      // The publisher may have yielded since `publish` checked `ended`, and
+      // `end` only rejects publishers that are already registered.
+      if (Option.isSome(ended.current)) return resume(Effect.succeed(false))
       const deferred = Deferred.makeUnsafe<boolean>()
       this.offerUnsafe(elements, deferred)
       this.onPubSubEmptySpaceUnsafe(pubsub, subscribers)
@@ -3142,6 +3219,7 @@ export class BackPressureStrategy<in out A> implements PubSub.Strategy<A> {
  * actual // => { published: [true, true, false], messages: ["msg1", "msg2"] }
  * ```
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -3225,6 +3303,7 @@ export class DroppingStrategy<in out A> implements PubSub.Strategy<A> {
  * actual // => ["msg3", "msg4"]
  * ```
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -3237,9 +3316,11 @@ export class SlidingStrategy<in out A> implements PubSub.Strategy<A> {
     pubsub: PubSub.Atomic<A>,
     subscribers: PubSub.Subscribers<A>,
     elements: Iterable<A>,
-    _isShutdown: MutableRef.MutableRef<boolean>
+    _isShutdown: MutableRef.MutableRef<boolean>,
+    ended: MutableRef.MutableRef<Option.Option<A>>
   ): Effect.Effect<boolean> {
     return Effect.sync(() => {
+      if (Option.isSome(ended.current)) return false
       this.slidingPublishUnsafe(pubsub, elements)
       this.completeSubscribersUnsafe(pubsub, subscribers)
       return true

package/src/Pull.ts

@@ -8,6 +8,7 @@
  * filtering, catching, converting, and matching done signals separately from
  * ordinary failures.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import * as Cause from "./Cause.ts"
@@ -34,6 +35,7 @@ import * as Result from "./Result.ts"
  * consumers can distinguish ordinary failures from end-of-input and carry a
  * leftover value when needed.
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -53,6 +55,7 @@ export interface Pull<out A, out E = never, out Done = void, out R = never>
  * @see {@link Leftover} for extracting the completion leftover type
  * @see {@link Services} for extracting the required services type instead
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -71,6 +74,7 @@ export type Success<P> = P extends Effect<infer _A, infer _E, infer _R> ? _A : n
  * @see {@link Services} for extracting the required services type instead
  * @see {@link ExcludeDone} for excluding `Cause.Done` from an error union
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -90,6 +94,7 @@ export type Error<P> = P extends Effect<infer _A, infer _E, infer _R> ? _E exten
  * @see {@link Error} for extracting the ordinary failure type, excluding `Cause.Done`
  * @see {@link Services} for extracting the required services type instead
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -108,6 +113,7 @@ export type Leftover<P> = P extends Effect<infer _A, infer _E, infer _R> ? _E ex
  * @see {@link Error} for extracting the ordinary failure type
  * @see {@link Leftover} for extracting the completion leftover type
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -124,6 +130,7 @@ export type Services<P> = P extends Effect<infer _A, infer _E, infer _R> ? _R :
  * @see {@link Error} for extracting ordinary failures from a `Pull`
  * @see {@link Leftover} for extracting the completion leftover type
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -151,6 +158,7 @@ export type ExcludeDone<E> = Exclude<E, Cause.Done<any>>
  * @see {@link matchEffect} for handling success, ordinary failure, and done outcomes explicitly
  * @see {@link filterDoneLeftover} for extracting a done leftover from an existing `Cause`
  *
+ * @stability stable
  * @category error handling
  * @since 4.0.0
  */
@@ -177,6 +185,7 @@ export const catchDone: {
    * @see {@link matchEffect} for handling success, ordinary failure, and done outcomes explicitly
    * @see {@link filterDoneLeftover} for extracting a done leftover from an existing `Cause`
    *
+   * @stability stable
    * @category error handling
    * @since 4.0.0
    */
@@ -205,6 +214,7 @@ export const catchDone: {
    * @see {@link matchEffect} for handling success, ordinary failure, and done outcomes explicitly
    * @see {@link filterDoneLeftover} for extracting a done leftover from an existing `Cause`
    *
+   * @stability stable
    * @category error handling
    * @since 4.0.0
    */
@@ -230,6 +240,7 @@ export const catchDone: {
  * @see {@link filterDone} for extracting the `Cause.Done` value from a `Cause`
  * @see {@link filterNoDone} for selecting causes with no done failures
  *
+ * @stability stable
  * @category predicates
  * @since 4.0.0
  */
@@ -247,6 +258,7 @@ export const isDoneCause = <E>(cause: Cause.Cause<E>): boolean => cause.reasons.
  * @see {@link isDoneCause} for checking an entire `Cause` for any done reason
  * @see {@link filterDone} for extracting the `Cause.Done` value from a `Cause`
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -271,6 +283,7 @@ export const isDoneFailure = <E>(
  * done signal. Without a done signal the `Result` fails with the original
  * cause.
  *
+ * @stability stable
  * @category filtering
  * @since 4.0.0
  */
@@ -311,6 +324,7 @@ export const filterDone: <E>(
  * @see {@link filterDoneLeftover} for extracting only the done leftover value
  * @see {@link filterNoDone} for the inverse filter that succeeds only when no done failure is present
  *
+ * @stability stable
  * @category filtering
  * @since 4.0.0
  */
@@ -334,6 +348,7 @@ export const filterDoneVoid: <E extends Cause.Done>(
  * @see {@link filterDone} for the inverse typed done filter
  * @see {@link filterDoneVoid} for done detection when the payload is not needed
  *
+ * @stability stable
  * @category filtering
  * @since 4.0.0
  */
@@ -354,6 +369,7 @@ export const filterNoDone: <E>(
  * Use to extract only the leftover value carried by a `Cause.Done` completion
  * signal.
  *
+ * @stability stable
  * @category filtering
  * @since 4.0.0
  */
@@ -383,6 +399,7 @@ export const filterDoneLeftover: <E>(
  * @see {@link filterDone} for extracting the done signal without converting the cause to an `Exit`
  * @see {@link matchEffect} for handling `Pull` success, failure, and done outcomes directly
  *
+ * @stability stable
  * @category converting
  * @since 4.0.0
  */
@@ -414,6 +431,7 @@ export const doneExitFromCause = <E>(cause: Cause.Cause<E>): Exit.Exit<Cause.Don
  * await Effect.runPromise(result) // => "Stream halted with: stream ended"
  * ```
  *
+ * @stability stable
  * @category pattern matching
  * @since 4.0.0
  */
@@ -441,6 +459,7 @@ export const matchEffect: {
    * await Effect.runPromise(result) // => "Stream halted with: stream ended"
    * ```
    *
+   * @stability stable
    * @category pattern matching
    * @since 4.0.0
    */
@@ -474,6 +493,7 @@ export const matchEffect: {
    * await Effect.runPromise(result) // => "Stream halted with: stream ended"
    * ```
    *
+   * @stability stable
    * @category pattern matching
    * @since 4.0.0
    */