effect 4.0.1 → 4.0.2

package/src/TxRef.ts

@@ -9,6 +9,7 @@
  * core operations for reading, setting, updating, and modifying a transactional
  * value while returning a separate result.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import * as Effect from "./Effect.ts"
@@ -55,6 +56,7 @@ const TypeId = "~effect/TxRef"
  * await Effect.runPromise(program) // => 1
  * ```
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -95,6 +97,7 @@ export interface TxRef<in out A> extends Pipeable {
  * await Effect.runPromise(program) // => [42, "Bob"]
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -122,6 +125,7 @@ export const make = <A>(initial: A) => Effect.sync(() => makeUnsafe(initial))
  * config.value // => { timeout: 5000, retries: 3 }
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -169,6 +173,7 @@ const journalEntry = <A>(state: Effect.Transaction["Service"], self: TxRef<A>) =
  * await Effect.runPromise(program) // => [0, 1]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -198,6 +203,7 @@ export const modify: {
    * await Effect.runPromise(program) // => [0, 1]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -227,6 +233,7 @@ export const modify: {
    * await Effect.runPromise(program) // => [0, 1]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -274,6 +281,7 @@ export const modify: {
  * await Effect.runPromise(program) // => 20
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -304,6 +312,7 @@ export const update: {
    * await Effect.runPromise(program) // => 20
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -334,6 +343,7 @@ export const update: {
    * await Effect.runPromise(program) // => 20
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -369,6 +379,7 @@ export const update: {
  * await Effect.runPromise(program) // => 42
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -404,6 +415,7 @@ export const get = <A>(self: TxRef<A>): Effect.Effect<A> =>
  * await Effect.runPromise(program) // => 100
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -434,6 +446,7 @@ export const set: {
    * await Effect.runPromise(program) // => 100
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -464,6 +477,7 @@ export const set: {
    * await Effect.runPromise(program) // => 100
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */

package/src/TxSemaphore.ts

@@ -7,6 +7,7 @@
  * creating semaphores, checking capacity and availability, acquiring or
  * releasing permits, and running effects while permits are held.
  *
+ * @stability stable
  * @since 4.0.0
  */
 
@@ -61,6 +62,7 @@ const TypeId = "~effect/TxSemaphore"
  * @see {@link withPermit} for automatically acquiring and releasing one permit
  * @see {@link acquire} for manually acquiring one permit transactionally
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -122,6 +124,7 @@ const makeTxSemaphore = (permitsRef: TxRef.TxRef<number>, capacity: number): TxS
  * @see {@link available} for reading the current available permit count
  * @see {@link capacity} for reading the fixed total permit count
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -167,6 +170,7 @@ export const make = (permits: number): Effect.Effect<TxSemaphore> =>
  *
  * @see {@link capacity} for reading the fixed total permit count
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -200,6 +204,7 @@ export const available = (self: TxSemaphore): Effect.Effect<number> => TxRef.get
  *
  * @see {@link available} for reading the current available permit count
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -236,6 +241,7 @@ export const capacity = (self: TxSemaphore): Effect.Effect<number> => Effect.suc
  * @see {@link release} for returning one permit
  * @see {@link withPermit} for automatic acquire and release around an effect
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -286,6 +292,7 @@ export const acquire = (self: TxSemaphore): Effect.Effect<void> =>
  * @see {@link releaseN} for returning multiple permits
  * @see {@link withPermits} for automatic acquire and release around an effect
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -328,6 +335,7 @@ export const acquireN: {
    * @see {@link releaseN} for returning multiple permits
    * @see {@link withPermits} for automatic acquire and release around an effect
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -370,6 +378,7 @@ export const acquireN: {
    * @see {@link releaseN} for returning multiple permits
    * @see {@link withPermits} for automatic acquire and release around an effect
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -418,6 +427,7 @@ export const acquireN: {
  * @see {@link acquire} for waiting until one permit is available
  * @see {@link tryAcquireN} for attempting to acquire multiple permits without blocking
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -461,6 +471,7 @@ export const tryAcquire = (self: TxSemaphore): Effect.Effect<boolean> =>
  * @see {@link acquireN} for waiting until all requested permits are available
  * @see {@link tryAcquire} for attempting to acquire one permit without blocking
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -497,6 +508,7 @@ export const tryAcquireN: {
    * @see {@link acquireN} for waiting until all requested permits are available
    * @see {@link tryAcquire} for attempting to acquire one permit without blocking
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -533,6 +545,7 @@ export const tryAcquireN: {
    * @see {@link acquireN} for waiting until all requested permits are available
    * @see {@link tryAcquire} for attempting to acquire one permit without blocking
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -586,6 +599,7 @@ export const tryAcquireN: {
  * @see {@link acquire} for manually acquiring one permit
  * @see {@link releaseN} for returning multiple permits
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -631,6 +645,7 @@ export const release = (self: TxSemaphore): Effect.Effect<void> =>
  * @see {@link acquireN} for manually acquiring multiple permits
  * @see {@link release} for returning one permit
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -674,6 +689,7 @@ export const releaseN: {
    * @see {@link acquireN} for manually acquiring multiple permits
    * @see {@link release} for returning one permit
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -717,6 +733,7 @@ export const releaseN: {
    * @see {@link acquireN} for manually acquiring multiple permits
    * @see {@link release} for returning one permit
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -731,6 +748,20 @@ export const releaseN: {
   })
 })
 
+/**
+ * Runs `effect` between `acquire` and `release`. Acquisition and `effect`
+ * inherit the caller's interruptibility, while the handoff from a successful
+ * acquisition to the release finalizer stays protected.
+ */
+const withAcquired = <A, E, R>(
+  acquire: Effect.Effect<void>,
+  effect: Effect.Effect<A, E, R>,
+  release: Effect.Effect<void>
+): Effect.Effect<A, E, R> =>
+  Effect.uninterruptibleMask((restore) =>
+    Effect.flatMap(restore(acquire), () => Effect.ensuring(restore(effect), release))
+  )
+
 /**
  * Executes an effect with a single permit from the semaphore. The permit is
  * automatically acquired before execution and released afterwards, even if the
@@ -778,6 +809,7 @@ export const releaseN: {
  * @see {@link withPermitScoped} for acquiring one permit for the current scope
  * @see {@link acquire} for manual single-permit acquisition
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -829,6 +861,7 @@ export const withPermit: {
    * @see {@link withPermitScoped} for acquiring one permit for the current scope
    * @see {@link acquire} for manual single-permit acquisition
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -880,26 +913,15 @@ export const withPermit: {
    * @see {@link withPermitScoped} for acquiring one permit for the current scope
    * @see {@link acquire} for manual single-permit acquisition
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
   <A, E, R>(self: TxSemaphore, effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
 } = ((...args: Array<any>) => {
-  if (args.length === 1) {
-    const [self] = args
-    return (effect: Effect.Effect<any, any, any>) =>
-      Effect.acquireUseRelease(
-        acquire(self),
-        () => effect,
-        () => release(self)
-      )
-  }
-  const [self, effect] = args
-  return Effect.acquireUseRelease(
-    acquire(self),
-    () => effect,
-    () => release(self)
-  )
+  const [self] = args
+  const run = <A, E, R>(effect: Effect.Effect<A, E, R>) => withAcquired(acquire(self), effect, release(self))
+  return args.length === 1 ? run : run(args[1])
 }) as any
 
 /**
@@ -952,6 +974,7 @@ export const withPermit: {
  * @see {@link withPermit} for automatically acquiring and releasing one permit
  * @see {@link acquireN} for manual multi-permit acquisition
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -1006,6 +1029,7 @@ export const withPermits: {
    * @see {@link withPermit} for automatically acquiring and releasing one permit
    * @see {@link acquireN} for manual multi-permit acquisition
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -1060,26 +1084,15 @@ export const withPermits: {
    * @see {@link withPermit} for automatically acquiring and releasing one permit
    * @see {@link acquireN} for manual multi-permit acquisition
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
   <A, E, R>(self: TxSemaphore, n: number, effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
 } = ((...args: Array<any>) => {
-  if (args.length === 2) {
-    const [self, n] = args
-    return (effect: Effect.Effect<any, any, any>) =>
-      Effect.acquireUseRelease(
-        acquireN(self, n),
-        () => effect,
-        () => releaseN(self, n)
-      )
-  }
-  const [self, n, effect] = args
-  return Effect.acquireUseRelease(
-    acquireN(self, n),
-    () => effect,
-    () => releaseN(self, n)
-  )
+  const [self, n] = args
+  const run = <A, E, R>(effect: Effect.Effect<A, E, R>) => withAcquired(acquireN(self, n), effect, releaseN(self, n))
+  return args.length === 2 ? run : run(args[2])
 }) as any
 
 /**
@@ -1130,13 +1143,15 @@ export const withPermits: {
  * @see {@link withPermit} for acquiring one permit around a single effect
  * @see {@link acquire} for manual single-permit acquisition
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
 export const withPermitScoped = (self: TxSemaphore): Effect.Effect<void, never, Scope.Scope> =>
   Effect.acquireRelease(
     acquire(self),
-    () => release(self)
+    () => release(self),
+    { interruptible: true }
   )
 
 /**
@@ -1171,6 +1186,7 @@ export const withPermitScoped = (self: TxSemaphore): Effect.Effect<void, never,
  *
  * @see {@link make} for creating a `TxSemaphore`
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */

package/src/TxSubscriptionRef.ts

@@ -7,6 +7,7 @@
  * updates. This module includes constructors, reads, writes, update and modify
  * helpers, transactional-queue subscriptions, stream subscriptions, and a guard.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import * as Effect from "./Effect.ts"
@@ -61,6 +62,7 @@ const TypeId = "~effect/TxSubscriptionRef"
  * @see {@link changes} for subscribing through a transactional queue
  * @see {@link changesStream} for subscribing through a `Stream`
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -114,6 +116,7 @@ const TxSubscriptionRefProto: Omit<TxSubscriptionRef<any>, typeof TypeId | "ref"
  *
  * @see {@link changes} for subscribing to the created reference
  *
+ * @stability stable
  * @category constructors
  * @since 3.10.0
  */
@@ -155,6 +158,7 @@ export const make = <A>(value: A): Effect.Effect<TxSubscriptionRef<A>> =>
  *
  * @see {@link changes} for reading the current value and subsequent updates
  *
+ * @stability stable
  * @category getters
  * @since 3.10.0
  */
@@ -190,6 +194,7 @@ export const get = <A>(self: TxSubscriptionRef<A>): Effect.Effect<A> => TxRef.ge
  * @see {@link update} for deriving the next value without a separate return value
  * @see {@link set} for replacing the value directly
  *
+ * @stability stable
  * @category mutations
  * @since 3.10.0
  */
@@ -224,6 +229,7 @@ export const modify: {
    * @see {@link update} for deriving the next value without a separate return value
    * @see {@link set} for replacing the value directly
    *
+   * @stability stable
    * @category mutations
    * @since 3.10.0
    */
@@ -258,6 +264,7 @@ export const modify: {
    * @see {@link update} for deriving the next value without a separate return value
    * @see {@link set} for replacing the value directly
    *
+   * @stability stable
    * @category mutations
    * @since 3.10.0
    */
@@ -305,6 +312,7 @@ export const modify: {
  * @see {@link update} for deriving the new value from the current value
  * @see {@link getAndSet} for setting while returning the previous value
  *
+ * @stability stable
  * @category mutations
  * @since 3.10.0
  */
@@ -334,6 +342,7 @@ export const set: {
    * @see {@link update} for deriving the new value from the current value
    * @see {@link getAndSet} for setting while returning the previous value
    *
+   * @stability stable
    * @category mutations
    * @since 3.10.0
    */
@@ -363,6 +372,7 @@ export const set: {
    * @see {@link update} for deriving the new value from the current value
    * @see {@link getAndSet} for setting while returning the previous value
    *
+   * @stability stable
    * @category mutations
    * @since 3.10.0
    */
@@ -398,6 +408,7 @@ export const set: {
  * @see {@link set} for replacing the value directly
  * @see {@link updateAndGet} for returning the new value after the update
  *
+ * @stability stable
  * @category mutations
  * @since 3.10.0
  */
@@ -428,6 +439,7 @@ export const update: {
    * @see {@link set} for replacing the value directly
    * @see {@link updateAndGet} for returning the new value after the update
    *
+   * @stability stable
    * @category mutations
    * @since 3.10.0
    */
@@ -458,6 +470,7 @@ export const update: {
    * @see {@link set} for replacing the value directly
    * @see {@link updateAndGet} for returning the new value after the update
    *
+   * @stability stable
    * @category mutations
    * @since 3.10.0
    */
@@ -494,6 +507,7 @@ export const update: {
  * @see {@link set} for setting without returning the previous value
  * @see {@link getAndUpdate} for deriving the new value from the previous value
  *
+ * @stability stable
  * @category mutations
  * @since 3.10.0
  */
@@ -524,6 +538,7 @@ export const getAndSet: {
    * @see {@link set} for setting without returning the previous value
    * @see {@link getAndUpdate} for deriving the new value from the previous value
    *
+   * @stability stable
    * @category mutations
    * @since 3.10.0
    */
@@ -554,6 +569,7 @@ export const getAndSet: {
    * @see {@link set} for setting without returning the previous value
    * @see {@link getAndUpdate} for deriving the new value from the previous value
    *
+   * @stability stable
    * @category mutations
    * @since 3.10.0
    */
@@ -589,6 +605,7 @@ export const getAndSet: {
  * @see {@link update} for updating without returning the previous value
  * @see {@link updateAndGet} for returning the new value instead
  *
+ * @stability stable
  * @category mutations
  * @since 3.10.0
  */
@@ -619,6 +636,7 @@ export const getAndUpdate: {
    * @see {@link update} for updating without returning the previous value
    * @see {@link updateAndGet} for returning the new value instead
    *
+   * @stability stable
    * @category mutations
    * @since 3.10.0
    */
@@ -649,6 +667,7 @@ export const getAndUpdate: {
    * @see {@link update} for updating without returning the previous value
    * @see {@link updateAndGet} for returning the new value instead
    *
+   * @stability stable
    * @category mutations
    * @since 3.10.0
    */
@@ -684,6 +703,7 @@ export const getAndUpdate: {
  * @see {@link update} for updating without returning the new value
  * @see {@link getAndUpdate} for returning the previous value instead
  *
+ * @stability stable
  * @category mutations
  * @since 3.10.0
  */
@@ -713,6 +733,7 @@ export const updateAndGet: {
    * @see {@link update} for updating without returning the new value
    * @see {@link getAndUpdate} for returning the previous value instead
    *
+   * @stability stable
    * @category mutations
    * @since 3.10.0
    */
@@ -742,6 +763,7 @@ export const updateAndGet: {
    * @see {@link update} for updating without returning the new value
    * @see {@link getAndUpdate} for returning the previous value instead
    *
+   * @stability stable
    * @category mutations
    * @since 3.10.0
    */
@@ -793,6 +815,7 @@ export const updateAndGet: {
  *
  * @see {@link changesStream} for subscribing through a `Stream`
  *
+ * @stability unstable
  * @category subscriptions
  * @since 3.10.0
  */
@@ -840,6 +863,7 @@ export const changes = <A>(
  *
  * @see {@link changes} for subscribing through a transactional queue
  *
+ * @stability stable
  * @category subscriptions
  * @since 3.10.0
  */
@@ -873,6 +897,7 @@ export const changesStream = <A>(self: TxSubscriptionRef<A>): Stream.Stream<A, n
  *
  * @see {@link make} for creating a `TxSubscriptionRef`
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */