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

package/dist/Scope.d.ts

@@ -1,15 +1,46 @@
 /**
- * The `Scope` module provides functionality for managing resource lifecycles
- * and cleanup operations in a functional and composable manner.
- *
- * A `Scope` represents a context where resources can be acquired and automatically
- * cleaned up when the scope is closed. This is essential for managing resources
- * like file handles, database connections, or any other resources that need
- * proper cleanup.
- *
- * Scopes support both sequential and parallel finalization strategies:
- * - Sequential: Finalizers run one after another in reverse order of registration
- * - Parallel: Finalizers run concurrently for better performance
+ * The `Scope` module manages resource lifetimes by collecting finalizers and
+ * running them when a scope is closed. It is the low-level mechanism behind
+ * scoped resource acquisition: acquire work registers cleanup with the current
+ * scope, and closing the scope releases those resources with the same `Exit`
+ * that ended the scoped workflow.
+ *
+ * Scopes are useful when code needs explicit control over a lifetime boundary,
+ * for example when building services, sharing a resource across multiple
+ * effects, or wiring lower-level infrastructure. Most application code can use
+ * higher-level scoped APIs, but this module exposes the primitives those APIs
+ * are built from.
+ *
+ * **Mental model**
+ *
+ * - A {@link Scope} is a mutable lifetime boundary that can accept finalizers
+ *   while open and run them when closed
+ * - A {@link Closeable} scope can be closed explicitly with {@link close} or
+ *   automatically around an effect with {@link use}
+ * - Sequential scopes run finalizers one after another in reverse registration
+ *   order; parallel scopes run registered finalizers concurrently
+ * - {@link addFinalizer} registers cleanup that ignores the closing exit, while
+ *   {@link addFinalizerExit} registers cleanup that can inspect it
+ * - {@link fork} creates a child scope whose lifetime is connected to a parent
+ *   scope
+ *
+ * **Common tasks**
+ *
+ * - Create scopes with {@link make} or the lower-level {@link makeUnsafe}
+ * - Provide an existing scope to an effect with {@link provide}
+ * - Register cleanup with {@link addFinalizer} or {@link addFinalizerExit}
+ * - Create child scopes with {@link fork} or {@link forkUnsafe}
+ * - Close scopes with {@link close}, or run and close with {@link use}
+ *
+ * **Gotchas**
+ *
+ * - Closing a scope is itself an `Effect`; finalizers run only when that effect
+ *   is executed
+ * - Adding a finalizer to an already closed scope runs the finalizer
+ *   immediately with the stored exit value
+ * - The unsafe constructors and closing helpers are for low-level integration;
+ *   prefer the effectful APIs when ordinary Effect code can express the
+ *   lifetime
  *
  * @since 2.0.0
  */
@@ -192,7 +223,12 @@ export declare namespace State {
     };
 }
 /**
- * The service tag for `Scope`, used for dependency injection in the Effect system.
+ * Service tag for the active resource lifetime.
+ *
+ * **When to use**
+ *
+ * Use to access the active lifetime when registering finalizers or sharing
+ * resources with the surrounding scope.
  *
  * **Example** (Accessing the scope service)
  *
@@ -266,8 +302,16 @@ export declare const make: (finalizerStrategy?: "sequential" | "parallel") => Ef
  */
 export declare const makeUnsafe: (finalizerStrategy?: "sequential" | "parallel") => Closeable;
 /**
- * Provides a `Scope` to an `Effect`, removing the `Scope` requirement from its context.
- * This allows you to run effects that require a scope by explicitly providing one.
+ * Provides a concrete `Scope` to an effect.
+ *
+ * **When to use**
+ *
+ * Use to run an effect that requires `Scope` with a scope managed by the
+ * caller.
+ *
+ * **Details**
+ *
+ * Providing the scope removes the `Scope` requirement from the effect context.
  *
  * **Example** (Providing a scope)
  *
@@ -293,8 +337,16 @@ export declare const makeUnsafe: (finalizerStrategy?: "sequential" | "parallel")
  */
 export declare const provide: {
     /**
-     * Provides a `Scope` to an `Effect`, removing the `Scope` requirement from its context.
-     * This allows you to run effects that require a scope by explicitly providing one.
+     * Provides a concrete `Scope` to an effect.
+     *
+     * **When to use**
+     *
+     * Use to run an effect that requires `Scope` with a scope managed by the
+     * caller.
+     *
+     * **Details**
+     *
+     * Providing the scope removes the `Scope` requirement from the effect context.
      *
      * **Example** (Providing a scope)
      *
@@ -320,8 +372,16 @@ export declare const provide: {
      */
     (value: Scope): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, Exclude<R, Scope>>;
     /**
-     * Provides a `Scope` to an `Effect`, removing the `Scope` requirement from its context.
-     * This allows you to run effects that require a scope by explicitly providing one.
+     * Provides a concrete `Scope` to an effect.
+     *
+     * **When to use**
+     *
+     * Use to run an effect that requires `Scope` with a scope managed by the
+     * caller.
+     *
+     * **Details**
+     *
+     * Providing the scope removes the `Scope` requirement from the effect context.
      *
      * **Example** (Providing a scope)
      *
@@ -458,7 +518,7 @@ export declare const addFinalizer: (scope: Scope, finalizer: Effect<unknown>) =>
  */
 export declare const fork: (scope: Scope, finalizerStrategy?: "sequential" | "parallel") => Effect<Closeable>;
 /**
- * Synchronously creates a closeable child scope registered with a parent scope.
+ * Creates a closeable child scope synchronously and registers it with a parent scope.
  *
  * **Details**
  *
@@ -490,8 +550,16 @@ export declare const fork: (scope: Scope, finalizerStrategy?: "sequential" | "pa
  */
 export declare const forkUnsafe: (scope: Scope, finalizerStrategy?: "sequential" | "parallel") => Closeable;
 /**
- * Closes a scope, running all registered finalizers in the appropriate order.
- * The exit value is passed to each finalizer.
+ * Closes a scope and runs its registered finalizers.
+ *
+ * **When to use**
+ *
+ * Use to close a scope manually with a specific exit value.
+ *
+ * **Details**
+ *
+ * Finalizers run in the scope's configured order and receive the supplied
+ * `Exit`.
  *
  * **Example** (Running scope finalizers)
  *
@@ -520,14 +588,24 @@ export declare const forkUnsafe: (scope: Scope, finalizerStrategy?: "sequential"
  */
 export declare const close: <A, E>(self: Scope, exit: Exit<A, E>) => Effect<void>;
 /**
- * Unsafely transitions a scope to `Closed` with the provided exit value.
+ * Closes a scope unsafely with the provided exit value.
+ *
+ * **When to use**
+ *
+ * Use when implementing lower-level scope machinery that must transition a
+ * scope to `Closed` immediately and can run the returned finalizer effect when
+ * one is produced.
  *
  * **Details**
  *
  * Returns an effect that runs registered finalizers, or `undefined` when the
- * scope was already closed or no finalizers need to run. Prefer `close` unless
- * you are implementing lower-level scope machinery and can correctly run the
- * returned effect.
+ * scope was already closed or no finalizers need to run.
+ *
+ * **Gotchas**
+ *
+ * Ignoring the returned effect skips registered finalizers.
+ *
+ * @see {@link close} for the usual effectful close operation that always returns an `Effect`
  *
  * @category unsafe
  * @since 4.0.0
@@ -537,12 +615,20 @@ export declare const closeUnsafe: <A, E>(self: Scope, exit_: Exit<A, E>) => Effe
  * Runs an effect with the provided closeable scope in its context and closes
  * that scope when the effect exits.
  *
+ * **When to use**
+ *
+ * Use when you already have a `Closeable` scope and want to run an effect that
+ * requires `Scope` while automatically closing that scope when the effect exits.
+ *
  * **Details**
  *
  * The scope is closed with the same exit value as the effect, so registered
  * finalizers can observe whether the effect succeeded, failed, or was
  * interrupted.
  *
+ * @see `provide` for providing a scope without closing it automatically
+ * @see `Effect.scoped` for creating and closing a fresh scope around a workflow
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -551,12 +637,20 @@ export declare const use: {
      * Runs an effect with the provided closeable scope in its context and closes
      * that scope when the effect exits.
      *
+     * **When to use**
+     *
+     * Use when you already have a `Closeable` scope and want to run an effect that
+     * requires `Scope` while automatically closing that scope when the effect exits.
+     *
      * **Details**
      *
      * The scope is closed with the same exit value as the effect, so registered
      * finalizers can observe whether the effect succeeded, failed, or was
      * interrupted.
      *
+     * @see `provide` for providing a scope without closing it automatically
+     * @see `Effect.scoped` for creating and closing a fresh scope around a workflow
+     *
      * @category combinators
      * @since 2.0.0
      */
@@ -565,12 +659,20 @@ export declare const use: {
      * Runs an effect with the provided closeable scope in its context and closes
      * that scope when the effect exits.
      *
+     * **When to use**
+     *
+     * Use when you already have a `Closeable` scope and want to run an effect that
+     * requires `Scope` while automatically closing that scope when the effect exits.
+     *
      * **Details**
      *
      * The scope is closed with the same exit value as the effect, so registered
      * finalizers can observe whether the effect succeeded, failed, or was
      * interrupted.
      *
+     * @see `provide` for providing a scope without closing it automatically
+     * @see `Effect.scoped` for creating and closing a fresh scope around a workflow
+     *
      * @category combinators
      * @since 2.0.0
      */

package/dist/Scope.d.ts.map

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

package/dist/Scope.js

@@ -1,15 +1,46 @@
 /**
- * The `Scope` module provides functionality for managing resource lifecycles
- * and cleanup operations in a functional and composable manner.
- *
- * A `Scope` represents a context where resources can be acquired and automatically
- * cleaned up when the scope is closed. This is essential for managing resources
- * like file handles, database connections, or any other resources that need
- * proper cleanup.
- *
- * Scopes support both sequential and parallel finalization strategies:
- * - Sequential: Finalizers run one after another in reverse order of registration
- * - Parallel: Finalizers run concurrently for better performance
+ * The `Scope` module manages resource lifetimes by collecting finalizers and
+ * running them when a scope is closed. It is the low-level mechanism behind
+ * scoped resource acquisition: acquire work registers cleanup with the current
+ * scope, and closing the scope releases those resources with the same `Exit`
+ * that ended the scoped workflow.
+ *
+ * Scopes are useful when code needs explicit control over a lifetime boundary,
+ * for example when building services, sharing a resource across multiple
+ * effects, or wiring lower-level infrastructure. Most application code can use
+ * higher-level scoped APIs, but this module exposes the primitives those APIs
+ * are built from.
+ *
+ * **Mental model**
+ *
+ * - A {@link Scope} is a mutable lifetime boundary that can accept finalizers
+ *   while open and run them when closed
+ * - A {@link Closeable} scope can be closed explicitly with {@link close} or
+ *   automatically around an effect with {@link use}
+ * - Sequential scopes run finalizers one after another in reverse registration
+ *   order; parallel scopes run registered finalizers concurrently
+ * - {@link addFinalizer} registers cleanup that ignores the closing exit, while
+ *   {@link addFinalizerExit} registers cleanup that can inspect it
+ * - {@link fork} creates a child scope whose lifetime is connected to a parent
+ *   scope
+ *
+ * **Common tasks**
+ *
+ * - Create scopes with {@link make} or the lower-level {@link makeUnsafe}
+ * - Provide an existing scope to an effect with {@link provide}
+ * - Register cleanup with {@link addFinalizer} or {@link addFinalizerExit}
+ * - Create child scopes with {@link fork} or {@link forkUnsafe}
+ * - Close scopes with {@link close}, or run and close with {@link use}
+ *
+ * **Gotchas**
+ *
+ * - Closing a scope is itself an `Effect`; finalizers run only when that effect
+ *   is executed
+ * - Adding a finalizer to an already closed scope runs the finalizer
+ *   immediately with the stored exit value
+ * - The unsafe constructors and closing helpers are for low-level integration;
+ *   prefer the effectful APIs when ordinary Effect code can express the
+ *   lifetime
  *
  * @since 2.0.0
  */
@@ -17,7 +48,12 @@ import * as effect from "./internal/effect.js";
 const TypeId = effect.ScopeTypeId;
 const CloseableTypeId = effect.ScopeCloseableTypeId;
 /**
- * The service tag for `Scope`, used for dependency injection in the Effect system.
+ * Service tag for the active resource lifetime.
+ *
+ * **When to use**
+ *
+ * Use to access the active lifetime when registering finalizers or sharing
+ * resources with the surrounding scope.
  *
  * **Example** (Accessing the scope service)
  *
@@ -91,8 +127,16 @@ export const make = effect.scopeMake;
  */
 export const makeUnsafe = effect.scopeMakeUnsafe;
 /**
- * Provides a `Scope` to an `Effect`, removing the `Scope` requirement from its context.
- * This allows you to run effects that require a scope by explicitly providing one.
+ * Provides a concrete `Scope` to an effect.
+ *
+ * **When to use**
+ *
+ * Use to run an effect that requires `Scope` with a scope managed by the
+ * caller.
+ *
+ * **Details**
+ *
+ * Providing the scope removes the `Scope` requirement from the effect context.
  *
  * **Example** (Providing a scope)
  *
@@ -228,7 +272,7 @@ export const addFinalizer = effect.scopeAddFinalizer;
  */
 export const fork = effect.scopeFork;
 /**
- * Synchronously creates a closeable child scope registered with a parent scope.
+ * Creates a closeable child scope synchronously and registers it with a parent scope.
  *
  * **Details**
  *
@@ -260,8 +304,16 @@ export const fork = effect.scopeFork;
  */
 export const forkUnsafe = effect.scopeForkUnsafe;
 /**
- * Closes a scope, running all registered finalizers in the appropriate order.
- * The exit value is passed to each finalizer.
+ * Closes a scope and runs its registered finalizers.
+ *
+ * **When to use**
+ *
+ * Use to close a scope manually with a specific exit value.
+ *
+ * **Details**
+ *
+ * Finalizers run in the scope's configured order and receive the supplied
+ * `Exit`.
  *
  * **Example** (Running scope finalizers)
  *
@@ -290,14 +342,24 @@ export const forkUnsafe = effect.scopeForkUnsafe;
  */
 export const close = effect.scopeClose;
 /**
- * Unsafely transitions a scope to `Closed` with the provided exit value.
+ * Closes a scope unsafely with the provided exit value.
+ *
+ * **When to use**
+ *
+ * Use when implementing lower-level scope machinery that must transition a
+ * scope to `Closed` immediately and can run the returned finalizer effect when
+ * one is produced.
  *
  * **Details**
  *
  * Returns an effect that runs registered finalizers, or `undefined` when the
- * scope was already closed or no finalizers need to run. Prefer `close` unless
- * you are implementing lower-level scope machinery and can correctly run the
- * returned effect.
+ * scope was already closed or no finalizers need to run.
+ *
+ * **Gotchas**
+ *
+ * Ignoring the returned effect skips registered finalizers.
+ *
+ * @see {@link close} for the usual effectful close operation that always returns an `Effect`
  *
  * @category unsafe
  * @since 4.0.0
@@ -307,12 +369,20 @@ export const closeUnsafe = effect.scopeCloseUnsafe;
  * Runs an effect with the provided closeable scope in its context and closes
  * that scope when the effect exits.
  *
+ * **When to use**
+ *
+ * Use when you already have a `Closeable` scope and want to run an effect that
+ * requires `Scope` while automatically closing that scope when the effect exits.
+ *
  * **Details**
  *
  * The scope is closed with the same exit value as the effect, so registered
  * finalizers can observe whether the effect succeeded, failed, or was
  * interrupted.
  *
+ * @see `provide` for providing a scope without closing it automatically
+ * @see `Effect.scoped` for creating and closing a fresh scope around a workflow
+ *
  * @category combinators
  * @since 2.0.0
  */

package/dist/Scope.js.map

@@ -1 +1 @@
-{"version":3,"file":"Scope.js","names":["effect","TypeId","ScopeTypeId","CloseableTypeId","ScopeCloseableTypeId","Scope","scopeTag","make","scopeMake","makeUnsafe","scopeMakeUnsafe","provide","provideScope","addFinalizerExit","scopeAddFinalizerExit","addFinalizer","scopeAddFinalizer","fork","scopeFork","forkUnsafe","scopeForkUnsafe","close","scopeClose","closeUnsafe","scopeCloseUnsafe","use","scopeUse"],"sources":["../src/Scope.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;AAmBA,OAAO,KAAKA,MAAM,MAAM,sBAAsB;AAE9C,MAAMC,MAAM,GAAGD,MAAM,CAACE,WAAW;AACjC,MAAMC,eAAe,GAAGH,MAAM,CAACI,oBAAoB;AAiLnD;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,MAAMC,KAAK,GAAkCL,MAAM,CAACM,QAAQ;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAMC,IAAI,GAAyEP,MAAM,CAACQ,SAAS;AAE1G;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,MAAMC,UAAU,GAAiET,MAAM,CAACU,eAAe;AAE9G;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,OAAO,MAAMC,OAAO,GAuDhBX,MAAM,CAACY,YAAY;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,OAAO,MAAMC,gBAAgB,GAC3Bb,MAAM,CAACc,qBAAqB;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,OAAO,MAAMC,YAAY,GAA+Df,MAAM,CAACgB,iBAAiB;AAEhH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,OAAO,MAAMC,IAAI,GAGQjB,MAAM,CAACkB,SAAS;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,OAAO,MAAMC,UAAU,GACrBnB,MAAM,CAACoB,eAAe;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAO,MAAMC,KAAK,GAA0DrB,MAAM,CAACsB,UAAU;AAE7F;;;;;;;;;;;;;AAaA,OAAO,MAAMC,WAAW,GACtBvB,MAAM,CAACwB,gBAAgB;AAEzB;;;;;;;;;;;;;AAaA,OAAO,MAAMC,GAAG,GA6BZzB,MAAM,CAAC0B,QAAQ","ignoreList":[]}
+{"version":3,"file":"Scope.js","names":["effect","TypeId","ScopeTypeId","CloseableTypeId","ScopeCloseableTypeId","Scope","scopeTag","make","scopeMake","makeUnsafe","scopeMakeUnsafe","provide","provideScope","addFinalizerExit","scopeAddFinalizerExit","addFinalizer","scopeAddFinalizer","fork","scopeFork","forkUnsafe","scopeForkUnsafe","close","scopeClose","closeUnsafe","scopeCloseUnsafe","use","scopeUse"],"sources":["../src/Scope.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,OAAO,KAAKA,MAAM,MAAM,sBAAsB;AAE9C,MAAMC,MAAM,GAAGD,MAAM,CAACE,WAAW;AACjC,MAAMC,eAAe,GAAGH,MAAM,CAACI,oBAAoB;AAiLnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,OAAO,MAAMC,KAAK,GAAkCL,MAAM,CAACM,QAAQ;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAMC,IAAI,GAAyEP,MAAM,CAACQ,SAAS;AAE1G;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,MAAMC,UAAU,GAAiET,MAAM,CAACU,eAAe;AAE9G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,OAAO,MAAMC,OAAO,GAuEhBX,MAAM,CAACY,YAAY;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,OAAO,MAAMC,gBAAgB,GAC3Bb,MAAM,CAACc,qBAAqB;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,OAAO,MAAMC,YAAY,GAA+Df,MAAM,CAACgB,iBAAiB;AAEhH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,OAAO,MAAMC,IAAI,GAGQjB,MAAM,CAACkB,SAAS;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,OAAO,MAAMC,UAAU,GACrBnB,MAAM,CAACoB,eAAe;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,OAAO,MAAMC,KAAK,GAA0DrB,MAAM,CAACsB,UAAU;AAE7F;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,MAAMC,WAAW,GACtBvB,MAAM,CAACwB,gBAAgB;AAEzB;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,MAAMC,GAAG,GA6CZzB,MAAM,CAAC0B,QAAQ","ignoreList":[]}