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

package/src/Pipeable.ts

@@ -25,6 +25,10 @@
 /**
  * Interface for values that support method-style `pipe` composition.
  *
+ * **When to use**
+ *
+ * Use to type values that expose an Effect-style `.pipe(...)` method.
+ *
  * **Details**
  *
  * Calling `value.pipe(f, g, h)` passes the value through each function from
@@ -533,6 +537,11 @@ export interface Pipeable {
  * Applies a `pipe` method's variadic arguments to an initial value from left
  * to right.
  *
+ * **When to use**
+ *
+ * Use to implement a custom `.pipe(...)` method from JavaScript's `arguments`
+ * object.
+ *
  * **Details**
  *
  * This helper is intended for implementing `Pipeable.pipe` methods that
@@ -599,10 +608,10 @@ export const pipeArguments = <A>(self: A, args: IArguments): unknown => {
  *
  * **When to use**
  *
- * Classes or object prototypes can reuse this value when they need the
+ * Use when classes or object prototypes can reuse this value when they need the
  * standard pipe implementation backed by `pipeArguments`.
  *
- * @category models
+ * @category prototypes
  * @since 3.15.0
  */
 export const Prototype: Pipeable = {
@@ -612,12 +621,12 @@ export const Prototype: Pipeable = {
 }
 
 /**
- * Base constructor whose instances implement the standard `Pipeable.pipe`
+ * Provides a base constructor whose instances implement the standard `Pipeable.pipe`
  * method.
  *
  * **When to use**
  *
- * Extend or compose this constructor when defining a class that should support
+ * Use when extend or compose this constructor when defining a class that should support
  * Effect-style method chaining through `.pipe(...)`.
  *
  * @category constructors
@@ -632,6 +641,15 @@ export const Class: new() => Pipeable = (function() {
 /**
  * Constructor type for classes whose instances implement `Pipeable`.
  *
+ * **When to use**
+ *
+ * Use as the constructor-side type when a class value should be known to create
+ * instances that support Effect-style method chaining with `.pipe(...)`.
+ *
+ * @see {@link Pipeable} for the instance-side contract
+ * @see {@link Class} for the base constructor
+ * @see {@link Mixin} for wrapping an existing class constructor
+ *
  * @category models
  * @since 3.15.0
  */
@@ -643,11 +661,18 @@ export interface PipeableConstructor {
  * Returns a subclass of the provided class that adds the standard `pipe`
  * method.
  *
+ * **When to use**
+ *
+ * Use to add pipe support to an existing class without extending a base class
+ * or modifying its prototype.
+ *
  * **Details**
  *
  * The original constructor and instance members are preserved, and the added
  * method delegates to `pipeArguments`.
  *
+ * @see {@link Prototype} for a reusable prototype object
+ * @see {@link Class} for a base constructor to extend
  * @category constructors
  * @since 4.0.0
  */

package/src/PlatformError.ts

@@ -38,11 +38,20 @@ const TypeId = "~effect/platform/PlatformError"
 /**
  * Error data for an invalid argument passed to a platform API.
  *
+ * **When to use**
+ *
+ * Use when a platform API rejects caller input before performing the underlying
+ * operation and callers need invalid-argument reason data directly.
+ *
  * **Details**
  *
  * The error records the module and method that rejected the argument, with an
  * optional description and cause. It is usually wrapped in `PlatformError`.
  *
+ * @see {@link badArgument} for creating a wrapped `PlatformError` whose reason is `BadArgument`
+ * @see {@link SystemError} for failures reported by the host platform or operating system
+ * @see {@link PlatformError} for the wrapper used by most platform APIs
+ *
  * @category models
  * @since 4.0.0
  */
@@ -55,6 +64,10 @@ export class BadArgument extends Data.TaggedError("BadArgument")<{
   /**
    * Formats the module, method, and optional description that rejected the argument.
    *
+   * **When to use**
+   *
+   * Use to read the formatted error message for a rejected platform argument.
+   *
    * @since 4.0.0
    */
   override get message(): string {
@@ -65,11 +78,19 @@ export class BadArgument extends Data.TaggedError("BadArgument")<{
 /**
  * Normalized category for failures reported by platform or system operations.
  *
+ * **When to use**
+ *
+ * Use to type or match the normalized `_tag` on `SystemError` values reported
+ * by platform operations.
+ *
  * **Details**
  *
  * The tags group lower-level platform errors into a stable set such as
  * `NotFound`, `PermissionDenied`, `TimedOut`, and `Unknown`.
  *
+ * @see {@link SystemError} for the error data that carries this tag on its `_tag` field
+ * @see {@link systemError} for creating a `PlatformError` from a system failure with one of these tags
+ *
  * @category models
  * @since 4.0.0
  */
@@ -89,12 +110,21 @@ export type SystemErrorTag =
 /**
  * Error data for a platform or system operation failure.
  *
+ * **When to use**
+ *
+ * Use as the reason data for failures reported by a host platform or operating
+ * system when you need a normalized system error tag plus operation details.
+ *
  * **Details**
  *
  * The error records a normalized `_tag`, the module and method that failed,
  * and optional details such as the syscall, path or descriptor, description,
  * and original cause. It is usually wrapped in `PlatformError`.
  *
+ * @see {@link systemError} for creating the usual `PlatformError` wrapper from this reason data
+ * @see {@link BadArgument} for platform API failures caused by rejected caller input before an operation runs
+ * @see {@link SystemErrorTag} for the normalized tag values stored in `_tag`
+ *
  * @category models
  * @since 4.0.0
  */
@@ -110,6 +140,10 @@ export class SystemError extends Data.Error<{
   /**
    * Formats the normalized system error tag with operation and path details.
    *
+   * **When to use**
+   *
+   * Use to read the formatted error message for a normalized system failure.
+   *
    * @since 4.0.0
    */
   override get message(): string {
@@ -123,11 +157,22 @@ export class SystemError extends Data.Error<{
  * Tagged error used by platform APIs to report either invalid arguments or
  * system-level failures.
  *
+ * **When to use**
+ *
+ * Use as the shared error type for platform APIs that expose invalid arguments
+ * and host or operating-system failures through a single `Effect` error
+ * channel.
+ *
  * **Details**
  *
  * The `reason` field contains the underlying `BadArgument` or `SystemError`.
  * When that reason has a cause, the cause is preserved on the wrapper.
  *
+ * @see {@link BadArgument} for invalid inputs rejected before an operation runs
+ * @see {@link SystemError} for failures reported by the host platform or operating system
+ * @see {@link badArgument} for creating this wrapper from rejected caller input
+ * @see {@link systemError} for creating this wrapper from a host or operating-system failure
+ *
  * @category models
  * @since 4.0.0
  */
@@ -145,6 +190,10 @@ export class PlatformError extends Data.TaggedError("PlatformError")<{
   /**
    * Marks this value as a platform error wrapper for runtime guards.
    *
+   * **When to use**
+   *
+   * Use to identify `PlatformError` values through their runtime type marker.
+   *
    * @since 4.0.0
    */
   readonly [TypeId]: typeof TypeId = TypeId
@@ -159,8 +208,8 @@ export class PlatformError extends Data.TaggedError("PlatformError")<{
  *
  * **When to use**
  *
- * Use this helper when adapting an operating-system or platform failure into
- * the normalized platform error model.
+ * Use to adapt an operating-system or platform failure into the normalized
+ * platform error model.
  *
  * @category constructors
  * @since 4.0.0
@@ -180,8 +229,8 @@ export const systemError = (options: {
  *
  * **When to use**
  *
- * Use this helper when a platform API rejects caller input before performing
- * the underlying operation.
+ * Use to report a platform API rejecting caller input before performing the
+ * underlying operation.
  *
  * @category constructors
  * @since 4.0.0

package/src/Pool.ts

@@ -1,31 +1,47 @@
 /**
- * The `Pool` module provides scoped resource pools for sharing expensive or
- * limited resources across fibers. A `Pool<A, E>` manages values of type `A`
- * acquired by an effect that may fail with `E`, automatically releasing all
- * allocated resources when the surrounding `Scope` closes.
+ * Scoped resource pools for sharing expensive or limited resources across
+ * fibers.
+ *
+ * The `Pool` module acquires values with a scoped effect, lets fibers borrow
+ * them with {@link get}, and releases all acquired values when the pool scope
+ * closes. Pools are useful for database connections, clients, buffers, or other
+ * resources where acquisition is expensive and total concurrency must be
+ * bounded.
  *
  * **Mental model**
  *
- * - A pool owns a bounded set of acquired items and hands them out with {@link get}
- * - Each checkout is scoped; leaving the scope returns the item to the pool
- * - `concurrency` controls how many fibers may use the same item at once
- * - `targetUtilization` controls when the pool grows between its minimum and maximum sizes
- * - {@link invalidate} removes a specific item so it can be replaced lazily
+ * - A pool owns resources between its configured minimum and maximum size.
+ * - Each item is acquired in the pool scope and finalized when removed or when
+ *   the pool shuts down.
+ * - {@link get} checks out an item in the caller's scope; leaving that scope
+ *   returns the item to the pool.
+ * - `concurrency` is per item, so a pool with size 4 and concurrency 2 can
+ *   serve up to 8 simultaneous checkouts.
+ * - `targetUtilization` controls when the resize strategy grows or shrinks the pool.
  *
  * **Common tasks**
  *
- * - Create a fixed-size pool with {@link make}
- * - Create an elastic pool with time-to-live reclamation using {@link makeWithTTL}
- * - Implement custom resizing and reclamation behavior with {@link makeWithStrategy}
- * - Borrow resources safely in scoped effects with {@link get}
+ * - Create a fixed-size pool with {@link make}.
+ * - Create an elastic pool that expires idle items with {@link makeWithTTL}.
+ * - Use {@link makeWithStrategy} for custom resize or reclamation behavior.
+ * - Borrow items safely in scoped effects with {@link get}.
+ * - Replace a broken item lazily with {@link invalidate}.
  *
  * **Gotchas**
  *
- * - Pool construction and item checkout require `Scope`; closing the scope shuts
- *   down the pool or returns the borrowed item
- * - Failed acquisitions are represented by the `get` effect failing with the
- *   acquisition error, and retrying `get` can retry acquisition
- * - Resource finalization order during shutdown is unspecified
+ * - Pool construction requires `Scope`; closing that scope shuts down the pool.
+ * - A checked-out item is returned only when the checkout scope closes, so do
+ *   not leak scoped effects that hold pool items indefinitely.
+ * - Acquisition failures fail the {@link get} effect for that checkout; later
+ *   checkouts can try acquisition again.
+ * - Invalidated items are finalized when they are no longer checked out, then
+ *   replacement happens on demand.
+ *
+ * **See also**
+ *
+ * - {@link Pool} for the pool value.
+ * - {@link get} for checked-out access.
+ * - {@link invalidate} for removing a specific item.
  *
  * @since 2.0.0
  */
@@ -53,6 +69,17 @@ const TypeId = "~effect/Pool"
  * associated with the acquisition and release of resources. An attempt to get
  * an item `A` from a pool may fail with an error of type `E`.
  *
+ * **When to use**
+ *
+ * Use when you need to share a bounded set of scoped resources across fibers
+ * while the pool manages acquisition, reuse, and release.
+ *
+ * @see {@link make} for creating a pool with size bounds
+ * @see {@link makeWithTTL} for creating a pool with idle item expiration
+ * @see {@link makeWithStrategy} for creating a pool with a custom strategy
+ * @see {@link get} for acquiring an item from a pool
+ * @see {@link invalidate} for removing a broken item from the pool
+ *
  * @category models
  * @since 2.0.0
  */
@@ -65,11 +92,20 @@ export interface Pool<in out A, in out E = never> extends Pipeable {
 /**
  * Normalized configuration used by a `Pool`.
  *
+ * **When to use**
+ *
+ * Use as the normalized, read-only description of how a pool acquires, sizes,
+ * shares, and resizes its items after construction.
+ *
  * **Details**
  *
  * The config stores the acquire effect, size bounds, per-item concurrency,
  * target utilization, and resizing strategy used by the pool implementation.
  *
+ * @see {@link Pool} for the value exposing this configuration
+ * @see {@link State} for mutable runtime state instead of static configuration
+ * @see {@link Strategy} for the resizing and reclamation contract stored on the config
+ *
  * @category models
  * @since 4.0.0
  */
@@ -85,6 +121,12 @@ export interface Config<A, E> {
 /**
  * Mutable runtime state maintained by a `Pool`.
  *
+ * **When to use**
+ *
+ * Use when you need to inspect or support the runtime state backing a `Pool`,
+ * including its scope, item sets, semaphores, waiters, invalidation tracking,
+ * and shutdown flag.
+ *
  * **Details**
  *
  * This state tracks the pool scope, active and available items, invalidated
@@ -92,6 +134,11 @@ export interface Config<A, E> {
  * inspection and implementation support; user code should prefer the
  * high-level pool operations.
  *
+ * @see {@link Pool} for the pool value exposing this state
+ * @see {@link PoolItem} for the entries stored in the runtime item sets
+ * @see {@link get} for acquiring items through the high-level API
+ * @see {@link invalidate} for invalidating items through the high-level API
+ *
  * @category models
  * @since 4.0.0
  */
@@ -110,12 +157,21 @@ export interface State<A, E> {
 /**
  * Internal record for a value managed by a `Pool`.
  *
+ * **When to use**
+ *
+ * Use when implementing a custom pool `Strategy` that needs to inspect
+ * acquired items, track reference counts, or return reclaimable items to the
+ * pool.
+ *
  * **Details**
  *
  * Each item stores the acquisition `Exit`, its finalizer, the current
  * reference count, and whether automatic reclaiming has been disabled because
  * the item was invalidated.
  *
+ * @see {@link Strategy} for the custom strategy callbacks that receive and return pool items
+ * @see {@link State} for the runtime sets that store active, available, and invalidated pool items
+ *
  * @category models
  * @since 4.0.0
  */
@@ -130,12 +186,19 @@ export interface PoolItem<A, E> {
  * Strategy used by a `Pool` to manage background resizing and item
  * reclamation.
  *
+ * **When to use**
+ *
+ * Use when defining a custom pool lifecycle policy that needs to run background
+ * work, observe acquired items, or choose items for reclamation.
+ *
  * **Details**
  *
  * `run` starts any strategy-specific background work, `onAcquire` is invoked
  * when an item is acquired, and `reclaim` selects an item that can be removed
  * or replaced.
  *
+ * @see {@link makeWithStrategy} for constructing a pool from a custom `Strategy`
+ *
  * @category models
  * @since 4.0.0
  */
@@ -148,6 +211,15 @@ export interface Strategy<A, E> {
 /**
  * Returns `true` if the specified value is a `Pool`, `false` otherwise.
  *
+ * **When to use**
+ *
+ * Use to validate unknown values at runtime boundaries before treating them as
+ * `Pool` values.
+ *
+ * **Details**
+ *
+ * This predicate narrows the input to `Pool<unknown, unknown>`.
+ *
  * @category refinements
  * @since 2.0.0
  */
@@ -156,6 +228,11 @@ export const isPool = (u: unknown): u is Pool<unknown, unknown> => hasProperty(u
 /**
  * Makes a new pool of the specified fixed size.
  *
+ * **When to use**
+ *
+ * Use to create a fixed-size pool when you know the exact number of resources
+ * needed upfront, without growth or shrinkage.
+ *
  * **Details**
  *
  * The pool is returned in a `Scope`, which governs the lifetime of the pool.
@@ -172,6 +249,8 @@ export const isPool = (u: unknown): u is Pool<unknown, unknown> => hasProperty(u
  * A `targetUtilization` of 0.5 will create new pool items when the existing items are
  * 50% utilized.
  *
+ * @see {@link makeWithTTL} for pools with min/max sizes and a TTL-based shrinking policy
+ * @see {@link makeWithStrategy} for pools with a custom resizing and reclamation strategy
  * @category constructors
  * @since 2.0.0
  */
@@ -187,6 +266,11 @@ export const make = <A, E, R>(options: {
  * Creates a scoped pool with minimum and maximum sizes and a time-to-live
  * policy for shrinking unused excess items.
  *
+ * **When to use**
+ *
+ * Use to create an elastic scoped pool that can grow up to a maximum size and
+ * later reclaim unused excess items.
+ *
  * **Details**
  *
  * The returned pool requires `Scope`; when that scope is closed, allocated
@@ -254,11 +338,19 @@ export const makeWithTTL = <A, E, R>(options: {
 /**
  * Creates a scoped pool using a custom resizing and reclamation strategy.
  *
+ * **When to use**
+ *
+ * Use to build a pool whose item lifecycle is controlled by an explicit
+ * `Strategy`, such as custom background resizing, replacement, or reclamation.
+ *
  * **Details**
  *
  * The returned pool requires `Scope`; closing the scope shuts down the pool and
- * releases allocated items. Use this constructor when `make` and `makeWithTTL`
- * do not provide the desired item lifecycle behavior.
+ * releases allocated items.
+ *
+ * @see {@link make} for fixed-size pools without custom resizing or reclamation
+ * @see {@link makeWithTTL} for min/max pools that shrink excess items with a TTL policy
+ * @see {@link Strategy} for the custom strategy contract consumed by this constructor
  *
  * @category constructors
  * @since 4.0.0
@@ -342,9 +434,23 @@ const shutdown = Effect.fnUntraced(function*<A, E>(self: Pool<A, E>) {
 })
 
 /**
- * Retrieves an item from the pool in a scoped effect. Note that if
- * acquisition fails, then the returned effect will fail for that same reason.
- * Retrying a failed acquisition attempt will repeat the acquisition attempt.
+ * Retrieves an item from the pool in a scoped effect.
+ *
+ * **When to use**
+ *
+ * Use to borrow a pooled resource for the lifetime of the current scope so it
+ * is automatically returned when that scope closes.
+ *
+ * **Details**
+ *
+ * The returned effect waits for an available item when the pool is at capacity.
+ * If acquiring a new item fails, the effect fails with the acquisition error.
+ *
+ * **Gotchas**
+ *
+ * Retrying a failed `get` can repeat the acquisition attempt.
+ *
+ * @see {@link invalidate} for removing an unhealthy item from future reuse
  *
  * @category getters
  * @since 2.0.0
@@ -419,27 +525,63 @@ const getPoolItemInner = Effect.fnUntraced(function*<A, E>(
 })
 
 /**
- * Invalidates the specified item. This will cause the pool to eventually
- * reallocate the item, although this reallocation may occur lazily rather
- * than eagerly.
+ * Invalidates the specified item so the pool can remove it and reallocate the
+ * item, lazily if needed.
+ *
+ * **When to use**
+ *
+ * Use to prevent a pooled item from being reused after you determine it is no
+ * longer suitable, such as a stale connection or a resource that failed a
+ * health check.
+ *
+ * **Gotchas**
+ *
+ * The item is matched with strict equality. Passing an equivalent but different
+ * object instance does nothing.
+ *
+ * @see {@link get} for retrieving scoped items from the pool
  *
  * @category combinators
  * @since 2.0.0
  */
 export const invalidate: {
   /**
-   * Invalidates the specified item. This will cause the pool to eventually
-   * reallocate the item, although this reallocation may occur lazily rather
-   * than eagerly.
+   * Invalidates the specified item so the pool can remove it and reallocate the
+   * item, lazily if needed.
+   *
+   * **When to use**
+   *
+   * Use to prevent a pooled item from being reused after you determine it is no
+   * longer suitable, such as a stale connection or a resource that failed a
+   * health check.
+   *
+   * **Gotchas**
+   *
+   * The item is matched with strict equality. Passing an equivalent but different
+   * object instance does nothing.
+   *
+   * @see {@link get} for retrieving scoped items from the pool
    *
    * @category combinators
    * @since 2.0.0
    */
   <A>(item: A): <E>(self: Pool<A, E>) => Effect.Effect<void, never, Scope.Scope>
   /**
-   * Invalidates the specified item. This will cause the pool to eventually
-   * reallocate the item, although this reallocation may occur lazily rather
-   * than eagerly.
+   * Invalidates the specified item so the pool can remove it and reallocate the
+   * item, lazily if needed.
+   *
+   * **When to use**
+   *
+   * Use to prevent a pooled item from being reused after you determine it is no
+   * longer suitable, such as a stale connection or a resource that failed a
+   * health check.
+   *
+   * **Gotchas**
+   *
+   * The item is matched with strict equality. Passing an equivalent but different
+   * object instance does nothing.
+   *
+   * @see {@link get} for retrieving scoped items from the pool
    *
    * @category combinators
    * @since 2.0.0