effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/SchemaUtils.ts

@@ -1,19 +1,37 @@
 /**
- * The `SchemaUtils` module contains focused helpers for schema patterns that
- * are useful but too specialized for the core `Schema` API surface.
+ * Focused schema helpers for patterns that are useful but too specialized for
+ * the main `Schema` module. This module currently covers the case where a
+ * native JavaScript or TypeScript class should decode from a plain struct and
+ * still remain an instance of that class after decoding.
  *
- * Use this module when you need to describe a native class with a schema while
- * keeping a plain struct as its encoded representation. This is especially
- * useful for classes such as `Data.Error` subclasses that should decode from
- * structured data, encode back to that data, and still preserve class identity
- * for instance checks and schema optics.
+ * **Mental model**
+ *
+ * - {@link getNativeClassSchema} starts from a constructor and a struct schema
+ *   for the encoded shape.
+ * - Decoding validates the struct, then calls the constructor with the decoded
+ *   fields as one object.
+ * - Encoding treats the instance as the encoded object, so instance properties
+ *   must line up with the struct fields.
+ * - The resulting schema preserves class identity through `Schema.instanceOf`
+ *   while retaining a plain-object representation for encoded data.
+ *
+ * **Common tasks**
+ *
+ * - Add schema support to an existing native class without rewriting it as a
+ *   `Schema.Class`.
+ * - Decode structured data into a `Data.Error` subclass or another class whose
+ *   constructor accepts a props object.
+ * - Encode class instances back to the struct shape expected at API, storage,
+ *   or transport boundaries.
  *
  * **Gotchas**
  *
- * - The constructor is called with the decoded struct fields as a single
- *   argument, so the class constructor must accept that shape.
- * - Encoding uses the instance itself as the encoded shape, so the instance
- *   should expose properties compatible with the provided struct schema.
+ * - Constructors that expect positional arguments are not compatible unless
+ *   they also accept the decoded props object.
+ * - Private fields or computed getters are not enough for encoding; the
+ *   instance must expose properties compatible with the provided struct schema.
+ * - Prefer `Schema.Class` or `Schema.ErrorClass` when you control the class
+ *   definition and do not need to adapt an existing constructor.
  *
  * @since 4.0.0
  */
@@ -25,12 +43,21 @@ import * as Transformation from "./SchemaTransformation.ts"
  * Builds an experimental schema for instances of a native class using a struct
  * schema as the encoded representation.
  *
+ * **When to use**
+ *
+ * Use when you need a schema for an existing native class while keeping a
+ * `Struct` schema as its encoded representation.
+ *
  * **Details**
  *
  * Decoding constructs `new constructor(props)` from the encoded fields.
  * Encoding uses the instance as the encoded shape, so the class should expose
  * properties compatible with the provided encoding schema.
  *
+ * @see {@link Schema.instanceOf} for validating existing class instances without a struct encoding
+ * @see {@link Schema.Class} for defining schema-backed classes directly
+ * @see {@link Schema.ErrorClass} for defining schema-backed error classes
+ *
  * @category schemas
  * @since 4.0.0
  */

package/src/Scope.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
  */
@@ -542,12 +573,22 @@ export const close: <A, E>(self: Scope, exit: Exit<A, E>) => Effect<void> = effe
 /**
  * Unsafely transitions a scope to `Closed` 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
@@ -559,12 +600,20 @@ export const closeUnsafe: <A, E>(self: Scope, exit_: Exit<A, E>) => Effect<void,
  * 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 {@link 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
  */
@@ -573,12 +622,20 @@ export 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 {@link 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
    */
@@ -587,12 +644,20 @@ export 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 {@link 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
    */