effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/Latch.d.ts

@@ -1,7 +1,7 @@
 /**
  * The `Latch` module provides a reusable synchronization primitive for
  * coordinating fibers. A `Latch` is either open or closed: when it is closed,
- * fibers that use {@link await} or {@link whenOpen} suspend until the latch is
+ * fibers that use {@link _await await} or {@link whenOpen} suspend until the latch is
  * opened or the current waiters are released.
  *
  * **Mental model**
@@ -17,7 +17,7 @@
  *
  * - Create a latch inside `Effect`: {@link make}
  * - Create a latch synchronously: {@link makeUnsafe}
- * - Wait for a signal before continuing: {@link await}
+ * - Wait for a signal before continuing: {@link _await await}
  * - Guard an effect so it runs only after the latch is open: {@link whenOpen}
  * - Let all current and future waiters proceed: {@link open}
  * - Let only the current waiters proceed: {@link release}
@@ -38,6 +38,11 @@ import type * as Effect from "./Effect.ts";
  * A reusable coordination primitive that lets fibers wait until they are
  * released by the latch.
  *
+ * **When to use**
+ *
+ * Use to coordinate fibers that must wait for an explicit open or release
+ * signal before continuing.
+ *
  * **Details**
  *
  * A closed latch causes `await` and `whenOpen` to suspend. `open` opens the
@@ -61,23 +66,70 @@ import type * as Effect from "./Effect.ts";
  * })
  * ```
  *
+ * @see {@link make} for creating a latch inside Effect code
+ * @see {@link open} for releasing current and future waiters
+ * @see {@link release} for releasing only the current waiters
+ *
  * @category models
  * @since 4.0.0
  */
 export interface Latch {
-    /** open the latch, releasing all fibers waiting on it */
+    /**
+     * Opens the latch, releasing all fibers waiting on it.
+     *
+     * **When to use**
+     *
+     * Use to let current and future waiters continue.
+     */
     readonly open: Effect.Effect<boolean>;
-    /** open the latch, releasing all fibers waiting on it */
+    /**
+     * Opens the latch synchronously, releasing all fibers waiting on it.
+     *
+     * **When to use**
+     *
+     * Use when synchronous code must open the latch immediately.
+     */
     openUnsafe(this: Latch): boolean;
-    /** release all fibers waiting on the latch, without opening it */
+    /**
+     * Releases all fibers currently waiting on the latch without opening it.
+     *
+     * **When to use**
+     *
+     * Use to let current waiters continue while future waiters still suspend.
+     */
     readonly release: Effect.Effect<boolean>;
-    /** wait for the latch to be opened */
+    /**
+     * Waits for the latch to be opened or released.
+     *
+     * **When to use**
+     *
+     * Use to suspend until the latch allows the current fiber to continue.
+     */
     readonly await: Effect.Effect<void>;
-    /** close the latch */
+    /**
+     * Closes the latch so future waiters suspend again.
+     *
+     * **When to use**
+     *
+     * Use to re-enable waiting after a latch has been opened.
+     */
     readonly close: Effect.Effect<boolean>;
-    /** close the latch */
+    /**
+     * Closes the latch synchronously so future waiters suspend again.
+     *
+     * **When to use**
+     *
+     * Use when synchronous code must close the latch immediately.
+     */
     closeUnsafe(this: Latch): boolean;
-    /** only run the given effect when the latch is open */
+    /**
+     * Runs the given effect only after the latch allows waiting fibers to
+     * continue.
+     *
+     * **When to use**
+     *
+     * Use to gate an effect behind the latch signal.
+     */
     whenOpen<A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>;
 }
 /**
@@ -85,8 +137,7 @@ export interface Latch {
  *
  * **When to use**
  *
- * Use this only when synchronous allocation is required; otherwise prefer
- * `make`.
+ * Use when synchronous allocation is required outside an Effect workflow.
  *
  * **Details**
  *
@@ -114,6 +165,8 @@ export interface Latch {
  * const program = Effect.all([waiter, opener])
  * ```
  *
+ * @see {@link make} for creating a latch inside Effect code
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -121,6 +174,10 @@ export declare const makeUnsafe: (open?: boolean | undefined) => Latch;
 /**
  * Creates a `Latch` inside `Effect`.
  *
+ * **When to use**
+ *
+ * Use to create a latch for coordinating fibers inside Effect code.
+ *
  * **Details**
  *
  * The latch starts closed by default; pass `true` to create it open.
@@ -149,6 +206,8 @@ export declare const makeUnsafe: (open?: boolean | undefined) => Latch;
  * })
  * ```
  *
+ * @see {@link makeUnsafe} for synchronous allocation outside Effect code
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -156,17 +215,29 @@ export declare const make: (open?: boolean | undefined) => Effect.Effect<Latch>;
 /**
  * Opens the latch and releases fibers waiting on it.
  *
+ * **When to use**
+ *
+ * Use to open a latch and release all fibers that are waiting on it.
+ *
  * **Details**
  *
  * The returned effect succeeds with `true` when this call changed the latch
  * from closed to open, or `false` if it was already open.
  *
+ * @see {@link openUnsafe} for a synchronous variant
+ * @see {@link release} to release waiting fibers without opening the latch
+ *
  * @category combinators
  * @since 4.0.0
  */
 export declare const open: (self: Latch) => Effect.Effect<boolean>;
 /**
- * Synchronously opens the latch and releases fibers waiting on it.
+ * Opens the latch synchronously and releases fibers waiting on it.
+ *
+ * **When to use**
+ *
+ * Use when synchronous code needs to open a latch immediately and release the
+ * fibers waiting on it.
  *
  * **Details**
  *
@@ -174,6 +245,10 @@ export declare const open: (self: Latch) => Effect.Effect<boolean>;
  * `false` if it was already open. This unsafe variant performs the state
  * change immediately instead of returning an `Effect`.
  *
+ * @see {@link open} for the effectful variant
+ * @see {@link release} to release waiting fibers without opening the latch
+ * @see {@link closeUnsafe} for the synchronous inverse operation
+ *
  * @category unsafe
  * @since 4.0.0
  */
@@ -181,12 +256,19 @@ export declare const openUnsafe: (self: Latch) => boolean;
 /**
  * Releases the fibers currently waiting on a closed latch without opening it.
  *
+ * **When to use**
+ *
+ * Use to let the fibers currently waiting on a latch proceed while keeping the
+ * latch closed for future waiters.
+ *
  * **Details**
  *
  * The returned effect succeeds with `true` when release was requested while
  * the latch was closed, or `false` if the latch was already open. Future
  * waiters still suspend until the latch is opened or released again.
  *
+ * @see {@link open} for opening the latch for current and future waiters
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -196,6 +278,25 @@ export {
 /**
  * Waits for the latch to be opened.
  *
+ * **When to use**
+ *
+ * Use to suspend the current fiber until the latch is opened or the current
+ * set of waiters is released.
+ *
+ * **Details**
+ *
+ * Awaiting an already open latch completes immediately. Awaiting a closed
+ * latch suspends until `open` or `release` resumes the waiters.
+ *
+ * **Gotchas**
+ *
+ * `release` can resume current waiters without opening the latch, so later
+ * waiters may still suspend.
+ *
+ * @see {@link open} for opening the latch for current and future waiters
+ * @see {@link release} for resuming current waiters without opening the latch
+ * @see {@link whenOpen} for waiting before running another effect
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -203,25 +304,42 @@ _await as await };
 /**
  * Closes the latch so future `await` and `whenOpen` calls suspend.
  *
+ * **When to use**
+ *
+ * Use to re-enable waiting on a latch after it was opened, so later `await`
+ * and `whenOpen` calls suspend again.
+ *
  * **Details**
  *
  * The returned effect succeeds with `true` when this call changed the latch
  * from open to closed, or `false` if it was already closed.
  *
+ * @see {@link closeUnsafe} for a synchronous variant
+ * @see {@link open} for opening the latch for current and future waiters
+ *
  * @category combinators
  * @since 4.0.0
  */
 export declare const close: (self: Latch) => Effect.Effect<boolean>;
 /**
- * Synchronously closes the latch so future `await` and `whenOpen` calls
+ * Closes the latch synchronously so future `await` and `whenOpen` calls
  * suspend.
  *
+ * **When to use**
+ *
+ * Use to close a latch synchronously when the state change must happen outside
+ * an `Effect`.
+ *
  * **Details**
  *
  * Returns `true` when this call changed the latch from open to closed, or
  * `false` if it was already closed. This unsafe variant performs the state
  * change immediately instead of returning an `Effect`.
  *
+ * @see {@link close} for the effectful variant
+ * @see {@link openUnsafe} to synchronously open the latch and release waiting
+ * fibers
+ *
  * @category unsafe
  * @since 4.0.0
  */
@@ -229,6 +347,11 @@ export declare const closeUnsafe: (self: Latch) => boolean;
 /**
  * Waits on the latch, then runs the provided effect.
  *
+ * **When to use**
+ *
+ * Use to gate another effect so it starts only after the latch is opened or
+ * the current waiters are released.
+ *
  * **Details**
  *
  * If the latch is open, the effect runs immediately. If it is closed, the
@@ -236,6 +359,10 @@ export declare const closeUnsafe: (self: Latch) => boolean;
  * released. The provided effect's success, failure, and requirements are
  * preserved.
  *
+ * @see `await` for waiting without running another effect
+ * @see {@link open} for opening the latch for current and future waiters
+ * @see {@link release} for resuming current waiters without opening the latch
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -243,6 +370,11 @@ export declare const whenOpen: {
     /**
      * Waits on the latch, then runs the provided effect.
      *
+     * **When to use**
+     *
+     * Use to gate another effect so it starts only after the latch is opened or
+     * the current waiters are released.
+     *
      * **Details**
      *
      * If the latch is open, the effect runs immediately. If it is closed, the
@@ -250,6 +382,10 @@ export declare const whenOpen: {
      * released. The provided effect's success, failure, and requirements are
      * preserved.
      *
+     * @see `await` for waiting without running another effect
+     * @see {@link open} for opening the latch for current and future waiters
+     * @see {@link release} for resuming current waiters without opening the latch
+     *
      * @category combinators
      * @since 4.0.0
      */
@@ -257,6 +393,11 @@ export declare const whenOpen: {
     /**
      * Waits on the latch, then runs the provided effect.
      *
+     * **When to use**
+     *
+     * Use to gate another effect so it starts only after the latch is opened or
+     * the current waiters are released.
+     *
      * **Details**
      *
      * If the latch is open, the effect runs immediately. If it is closed, the
@@ -264,6 +405,10 @@ export declare const whenOpen: {
      * released. The provided effect's success, failure, and requirements are
      * preserved.
      *
+     * @see `await` for waiting without running another effect
+     * @see {@link open} for opening the latch for current and future waiters
+     * @see {@link release} for resuming current waiters without opening the latch
+     *
      * @category combinators
      * @since 4.0.0
      */

package/dist/Latch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Latch.d.ts","sourceRoot":"","sources":["../src/Latch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Latch.d.ts","sourceRoot":"","sources":["../src/Latch.ts"],"names":[],"mappings":"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"}

package/dist/Latch.js

@@ -4,8 +4,7 @@ import * as internal from "./internal/effect.js";
  *
  * **When to use**
  *
- * Use this only when synchronous allocation is required; otherwise prefer
- * `make`.
+ * Use when synchronous allocation is required outside an Effect workflow.
  *
  * **Details**
  *
@@ -33,6 +32,8 @@ import * as internal from "./internal/effect.js";
  * const program = Effect.all([waiter, opener])
  * ```
  *
+ * @see {@link make} for creating a latch inside Effect code
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -40,6 +41,10 @@ export const makeUnsafe = internal.makeLatchUnsafe;
 /**
  * Creates a `Latch` inside `Effect`.
  *
+ * **When to use**
+ *
+ * Use to create a latch for coordinating fibers inside Effect code.
+ *
  * **Details**
  *
  * The latch starts closed by default; pass `true` to create it open.
@@ -68,6 +73,8 @@ export const makeUnsafe = internal.makeLatchUnsafe;
  * })
  * ```
  *
+ * @see {@link makeUnsafe} for synchronous allocation outside Effect code
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -75,17 +82,29 @@ export const make = internal.makeLatch;
 /**
  * Opens the latch and releases fibers waiting on it.
  *
+ * **When to use**
+ *
+ * Use to open a latch and release all fibers that are waiting on it.
+ *
  * **Details**
  *
  * The returned effect succeeds with `true` when this call changed the latch
  * from closed to open, or `false` if it was already open.
  *
+ * @see {@link openUnsafe} for a synchronous variant
+ * @see {@link release} to release waiting fibers without opening the latch
+ *
  * @category combinators
  * @since 4.0.0
  */
 export const open = self => self.open;
 /**
- * Synchronously opens the latch and releases fibers waiting on it.
+ * Opens the latch synchronously and releases fibers waiting on it.
+ *
+ * **When to use**
+ *
+ * Use when synchronous code needs to open a latch immediately and release the
+ * fibers waiting on it.
  *
  * **Details**
  *
@@ -93,6 +112,10 @@ export const open = self => self.open;
  * `false` if it was already open. This unsafe variant performs the state
  * change immediately instead of returning an `Effect`.
  *
+ * @see {@link open} for the effectful variant
+ * @see {@link release} to release waiting fibers without opening the latch
+ * @see {@link closeUnsafe} for the synchronous inverse operation
+ *
  * @category unsafe
  * @since 4.0.0
  */
@@ -100,12 +123,19 @@ export const openUnsafe = self => self.openUnsafe();
 /**
  * Releases the fibers currently waiting on a closed latch without opening it.
  *
+ * **When to use**
+ *
+ * Use to let the fibers currently waiting on a latch proceed while keeping the
+ * latch closed for future waiters.
+ *
  * **Details**
  *
  * The returned effect succeeds with `true` when release was requested while
  * the latch was closed, or `false` if the latch was already open. Future
  * waiters still suspend until the latch is opened or released again.
  *
+ * @see {@link open} for opening the latch for current and future waiters
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -115,6 +145,25 @@ export {
 /**
  * Waits for the latch to be opened.
  *
+ * **When to use**
+ *
+ * Use to suspend the current fiber until the latch is opened or the current
+ * set of waiters is released.
+ *
+ * **Details**
+ *
+ * Awaiting an already open latch completes immediately. Awaiting a closed
+ * latch suspends until `open` or `release` resumes the waiters.
+ *
+ * **Gotchas**
+ *
+ * `release` can resume current waiters without opening the latch, so later
+ * waiters may still suspend.
+ *
+ * @see {@link open} for opening the latch for current and future waiters
+ * @see {@link release} for resuming current waiters without opening the latch
+ * @see {@link whenOpen} for waiting before running another effect
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -122,25 +171,42 @@ _await as await };
 /**
  * Closes the latch so future `await` and `whenOpen` calls suspend.
  *
+ * **When to use**
+ *
+ * Use to re-enable waiting on a latch after it was opened, so later `await`
+ * and `whenOpen` calls suspend again.
+ *
  * **Details**
  *
  * The returned effect succeeds with `true` when this call changed the latch
  * from open to closed, or `false` if it was already closed.
  *
+ * @see {@link closeUnsafe} for a synchronous variant
+ * @see {@link open} for opening the latch for current and future waiters
+ *
  * @category combinators
  * @since 4.0.0
  */
 export const close = self => self.close;
 /**
- * Synchronously closes the latch so future `await` and `whenOpen` calls
+ * Closes the latch synchronously so future `await` and `whenOpen` calls
  * suspend.
  *
+ * **When to use**
+ *
+ * Use to close a latch synchronously when the state change must happen outside
+ * an `Effect`.
+ *
  * **Details**
  *
  * Returns `true` when this call changed the latch from open to closed, or
  * `false` if it was already closed. This unsafe variant performs the state
  * change immediately instead of returning an `Effect`.
  *
+ * @see {@link close} for the effectful variant
+ * @see {@link openUnsafe} to synchronously open the latch and release waiting
+ * fibers
+ *
  * @category unsafe
  * @since 4.0.0
  */
@@ -148,6 +214,11 @@ export const closeUnsafe = self => self.closeUnsafe();
 /**
  * Waits on the latch, then runs the provided effect.
  *
+ * **When to use**
+ *
+ * Use to gate another effect so it starts only after the latch is opened or
+ * the current waiters are released.
+ *
  * **Details**
  *
  * If the latch is open, the effect runs immediately. If it is closed, the
@@ -155,6 +226,10 @@ export const closeUnsafe = self => self.closeUnsafe();
  * released. The provided effect's success, failure, and requirements are
  * preserved.
  *
+ * @see `await` for waiting without running another effect
+ * @see {@link open} for opening the latch for current and future waiters
+ * @see {@link release} for resuming current waiters without opening the latch
+ *
  * @category combinators
  * @since 4.0.0
  */

package/dist/Latch.js.map

@@ -1 +1 @@
-{"version":3,"file":"Latch.js","names":["internal","makeUnsafe","makeLatchUnsafe","make","makeLatch","open","self","openUnsafe","release","_await","await","close","closeUnsafe","whenOpen","args","length","effect"],"sources":["../src/Latch.ts"],"sourcesContent":[null],"mappings":"AAoCA,OAAO,KAAKA,QAAQ,MAAM,sBAAsB;AAiDhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,OAAO,MAAMC,UAAU,GAA0CD,QAAQ,CAACE,eAAe;AAEzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,OAAO,MAAMC,IAAI,GAAyDH,QAAQ,CAACI,SAAS;AAE5F;;;;;;;;;;;AAWA,OAAO,MAAMC,IAAI,GAAIC,IAAW,IAA6BA,IAAI,CAACD,IAAI;AAEtE;;;;;;;;;;;;AAYA,OAAO,MAAME,UAAU,GAAID,IAAW,IAAcA,IAAI,CAACC,UAAU,EAAE;AAErE;;;;;;;;;;;;AAYA,OAAO,MAAMC,OAAO,GAAIF,IAAW,IAA6BA,IAAI,CAACE,OAAO;AAE5E,MAAMC,MAAM,GAAIH,IAAW,IAA0BA,IAAI,CAACI,KAAK;AAE/D;AACE;;;;;;AAMAD,MAAM,IAAIC,KAAK;AAGjB;;;;;;;;;;;AAWA,OAAO,MAAMC,KAAK,GAAIL,IAAW,IAA6BA,IAAI,CAACK,KAAK;AAExE;;;;;;;;;;;;;AAaA,OAAO,MAAMC,WAAW,GAAIN,IAAW,IAAcA,IAAI,CAACM,WAAW,EAAE;AAEvE;;;;;;;;;;;;;AAaA,OAAO,MAAMC,QAAQ,GA6BhBA,CAAC,GAAGC,IAAgB,KAAI;EAC3B,IAAIA,IAAI,CAACC,MAAM,KAAK,CAAC,EAAE;IACrB,MAAM,CAACT,IAAI,CAAC,GAAGQ,IAAI;IACnB,OAAQE,MAAoC,IAAKV,IAAI,CAACO,QAAQ,CAACG,MAAM,CAAC;EACxE;EACA,MAAM,CAACV,IAAI,EAAEU,MAAM,CAAC,GAAGF,IAAI;EAC3B,OAAOR,IAAI,CAACO,QAAQ,CAACG,MAAM,CAAC;AAC9B,CAAS","ignoreList":[]}
+{"version":3,"file":"Latch.js","names":["internal","makeUnsafe","makeLatchUnsafe","make","makeLatch","open","self","openUnsafe","release","_await","await","close","closeUnsafe","whenOpen","args","length","effect"],"sources":["../src/Latch.ts"],"sourcesContent":[null],"mappings":"AAoCA,OAAO,KAAKA,QAAQ,MAAM,sBAAsB;AA2GhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,OAAO,MAAMC,UAAU,GAA0CD,QAAQ,CAACE,eAAe;AAEzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,OAAO,MAAMC,IAAI,GAAyDH,QAAQ,CAACI,SAAS;AAE5F;;;;;;;;;;;;;;;;;;AAkBA,OAAO,MAAMC,IAAI,GAAIC,IAAW,IAA6BA,IAAI,CAACD,IAAI;AAEtE;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,MAAME,UAAU,GAAID,IAAW,IAAcA,IAAI,CAACC,UAAU,EAAE;AAErE;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,MAAMC,OAAO,GAAIF,IAAW,IAA6BA,IAAI,CAACE,OAAO;AAE5E,MAAMC,MAAM,GAAIH,IAAW,IAA0BA,IAAI,CAACI,KAAK;AAE/D;AACE;;;;;;;;;;;;;;;;;;;;;;;;;AAyBAD,MAAM,IAAIC,KAAK;AAGjB;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,MAAMC,KAAK,GAAIL,IAAW,IAA6BA,IAAI,CAACK,KAAK;AAExE;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAMC,WAAW,GAAIN,IAAW,IAAcA,IAAI,CAACM,WAAW,EAAE;AAEvE;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAMC,QAAQ,GA+ChBA,CAAC,GAAGC,IAAgB,KAAI;EAC3B,IAAIA,IAAI,CAACC,MAAM,KAAK,CAAC,EAAE;IACrB,MAAM,CAACT,IAAI,CAAC,GAAGQ,IAAI;IACnB,OAAQE,MAAoC,IAAKV,IAAI,CAACO,QAAQ,CAACG,MAAM,CAAC;EACxE;EACA,MAAM,CAACV,IAAI,EAAEU,MAAM,CAAC,GAAGF,IAAI;EAC3B,OAAOR,IAAI,CAACO,QAAQ,CAACG,MAAM,CAAC;AAC9B,CAAS","ignoreList":[]}