effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/Pipeable.ts

@@ -1,11 +1,38 @@
 /**
+ * The `Pipeable` module defines the shared interface and implementation helpers
+ * for values that support Effect-style method chaining with `.pipe(...)`.
+ *
+ * A `Pipeable` value can pass itself through a sequence of unary functions from
+ * left to right, so code can be written as `value.pipe(f, g, h)` instead of
+ * deeply nesting calls. This is the method form used by many Effect data types
+ * to compose transformations, validations, and effectful operations while
+ * keeping the original value as the starting point of the pipeline.
+ *
+ * **Common tasks**
+ *
+ * - Type values that expose a `.pipe(...)` method with the {@link Pipeable} interface
+ * - Implement a custom `.pipe(...)` method with {@link pipeArguments}
+ * - Reuse the standard implementation through {@link Prototype}, {@link Class}, or {@link Mixin}
+ *
+ * **Gotchas**
+ *
+ * - Each function receives the result of the previous function, not the original value
+ * - The overloads preserve precise types for long pipelines, but very long chains may be easier to read when split
+ *
  * @since 2.0.0
  */
 
 /**
- * @since 2.0.0
+ * Interface for values that support method-style `pipe` composition.
+ *
+ * Calling `value.pipe(f, g, h)` passes the value through each function from
+ * left to right, returning the final result. Many Effect data types implement
+ * this so operations can be chained without nesting function calls.
+ *
  * @category models
- * @example
+ * @since 2.0.0
+ * **Example** (Chaining operations with pipe)
+ *
  * ```ts
  * import { Effect } from "effect"
  *
@@ -500,22 +527,32 @@ export interface Pipeable {
 }
 
 /**
- * @since 2.0.0
+ * Applies a `pipe` method's variadic arguments to an initial value from left
+ * to right.
+ *
+ * This helper is intended for implementing `Pipeable.pipe` methods that
+ * receive JavaScript's `arguments` object. With no functions it returns the
+ * original value; otherwise it feeds each result into the next function.
+ *
  * @category utilities
- * @example
+ * @since 2.0.0
+ * **Example** (Implementing a pipe method)
+ *
  * ```ts
  * import { Pipeable } from "effect"
  *
- * // pipeArguments is used internally to implement efficient piping
- * function customPipe<A>(self: A, ...fns: Array<(a: any) => any>): unknown {
- *   return Pipeable.pipeArguments(self, arguments as any)
- * }
+ * class NumberBox {
+ *   constructor(readonly value: number) {}
  *
- * // Example usage
- * const add = (x: number) => (y: number) => x + y
- * const multiply = (x: number) => (y: number) => x * y
+ *   pipe(..._fns: ReadonlyArray<(value: number) => number>): number {
+ *     return Pipeable.pipeArguments(this.value, arguments) as number
+ *   }
+ * }
  *
- * const result = customPipe(5, add(2), multiply(3))
+ * const result = new NumberBox(5).pipe(
+ *   (n) => n + 2,
+ *   (n) => n * 3
+ * )
  * console.log(result) // 21
  * ```
  */
@@ -552,6 +589,11 @@ export const pipeArguments = <A>(self: A, args: IArguments): unknown => {
 }
 
 /**
+ * Reusable prototype that implements `Pipeable.pipe`.
+ *
+ * Classes or object prototypes can reuse this value when they need the
+ * standard pipe implementation backed by `pipeArguments`.
+ *
  * @since 4.0.0
  */
 export const Prototype: Pipeable = {
@@ -561,8 +603,14 @@ export const Prototype: Pipeable = {
 }
 
 /**
- * @since 4.0.0
+ * Base constructor whose instances implement the standard `Pipeable.pipe`
+ * method.
+ *
+ * Extend or compose this constructor when defining a class that should support
+ * Effect-style method chaining through `.pipe(...)`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const Class: new() => Pipeable = (function() {
   function PipeableBase() {}
@@ -571,22 +619,29 @@ export const Class: new() => Pipeable = (function() {
 })()
 
 /**
- * @since 4.0.0
+ * Constructor type for classes whose instances implement `Pipeable`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface PipeableConstructor {
   new(...args: ReadonlyArray<any>): Pipeable
 }
 
 /**
- * @since 4.0.0
+ * Returns a subclass of the provided class that adds the standard `pipe`
+ * method.
+ *
+ * The original constructor and instance members are preserved, and the added
+ * method delegates to `pipeArguments`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const Mixin = <TBase extends new(...args: ReadonlyArray<any>) => any>(
   klass: TBase
-): TBase & PipeableConstructor =>
-  (class extends klass {
-    pipe() {
-      return pipeArguments(this, arguments)
-    }
-  })
+): TBase & PipeableConstructor => (class extends klass {
+  pipe() {
+    return pipeArguments(this, arguments)
+  }
+})

package/src/PlatformError.ts

@@ -1,4 +1,34 @@
 /**
+ * The `PlatformError` module defines the normalized error model used by
+ * platform APIs when adapting host operations into Effect programs. It gives
+ * callers a stable `PlatformError` wrapper whose `reason` is either a
+ * `BadArgument`, for invalid inputs rejected before an operation runs, or a
+ * `SystemError`, for failures reported by the host platform or operating
+ * system.
+ *
+ * Use this module when implementing or consuming platform services such as
+ * file systems, terminal access, sockets, or other environment-specific APIs.
+ * `SystemError` intentionally groups many low-level failures into a small set
+ * of portable tags like `NotFound`, `PermissionDenied`, and `TimedOut`, while
+ * still preserving operation details such as the module, method, syscall, path
+ * or descriptor, description, and original cause when available.
+ *
+ * **Common tasks**
+ *
+ * - Create platform failures from system operations with {@link systemError}
+ * - Report rejected caller input with {@link badArgument}
+ * - Inspect the underlying reason via {@link PlatformError.reason}
+ * - Match normalized system failures with {@link SystemErrorTag}
+ *
+ * **Gotchas**
+ *
+ * - `PlatformError` is a wrapper; inspect `reason` to distinguish
+ *   `BadArgument` from `SystemError`
+ * - `SystemErrorTag` values are normalized categories, not necessarily raw
+ *   platform error codes
+ * - The original cause is preserved when provided, but portable handling
+ *   should rely on the normalized fields
+ *
  * @since 4.0.0
  */
 import * as Data from "./Data.ts"
@@ -6,8 +36,13 @@ import * as Data from "./Data.ts"
 const TypeId = "~effect/platform/PlatformError"
 
 /**
- * @since 4.0.0
+ * Error data for an invalid argument passed to a platform API.
+ *
+ * The error records the module and method that rejected the argument, with an
+ * optional description and cause. It is usually wrapped in `PlatformError`.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export class BadArgument extends Data.TaggedError("BadArgument")<{
   module: string
@@ -16,6 +51,8 @@ export class BadArgument extends Data.TaggedError("BadArgument")<{
   cause?: unknown
 }> {
   /**
+   * Formats the module, method, and optional description that rejected the argument.
+   *
    * @since 4.0.0
    */
   override get message(): string {
@@ -24,8 +61,13 @@ export class BadArgument extends Data.TaggedError("BadArgument")<{
 }
 
 /**
- * @since 4.0.0
+ * Normalized category for failures reported by platform or system operations.
+ *
+ * The tags group lower-level platform errors into a stable set such as
+ * `NotFound`, `PermissionDenied`, `TimedOut`, and `Unknown`.
+ *
  * @category Model
+ * @since 4.0.0
  */
 export type SystemErrorTag =
   | "AlreadyExists"
@@ -41,8 +83,14 @@ export type SystemErrorTag =
   | "WriteZero"
 
 /**
- * @since 4.0.0
+ * Error data for a platform or system operation failure.
+ *
+ * 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`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export class SystemError extends Data.Error<{
   _tag: SystemErrorTag
@@ -54,6 +102,8 @@ export class SystemError extends Data.Error<{
   cause?: unknown
 }> {
   /**
+   * Formats the normalized system error tag with operation and path details.
+   *
    * @since 4.0.0
    */
   override get message(): string {
@@ -64,8 +114,14 @@ export class SystemError extends Data.Error<{
 }
 
 /**
- * @since 4.0.0
+ * Tagged error used by platform APIs to report either invalid arguments or
+ * system-level failures.
+ *
+ * The `reason` field contains the underlying `BadArgument` or `SystemError`.
+ * When that reason has a cause, the cause is preserved on the wrapper.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export class PlatformError extends Data.TaggedError("PlatformError")<{
   reason: BadArgument | SystemError
@@ -79,6 +135,8 @@ export class PlatformError extends Data.TaggedError("PlatformError")<{
   }
 
   /**
+   * Marks this value as a platform error wrapper for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId]: typeof TypeId = TypeId
@@ -89,8 +147,13 @@ export class PlatformError extends Data.TaggedError("PlatformError")<{
 }
 
 /**
- * @since 4.0.0
+ * Creates a `PlatformError` whose reason is a `SystemError`.
+ *
+ * Use this helper when adapting an operating-system or platform failure into
+ * the normalized platform error model.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const systemError = (options: {
   readonly _tag: SystemErrorTag
@@ -103,8 +166,13 @@ export const systemError = (options: {
 }): PlatformError => new PlatformError(new SystemError(options))
 
 /**
- * @since 4.0.0
+ * Creates a `PlatformError` whose reason is a `BadArgument`.
+ *
+ * Use this helper when a platform API rejects caller input before performing
+ * the underlying operation.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const badArgument = (options: {
   readonly module: string

package/src/Pool.ts

@@ -1,4 +1,32 @@
 /**
+ * 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.
+ *
+ * **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
+ *
+ * **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}
+ *
+ * **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
+ *
  * @since 2.0.0
  */
 import type * as Cause from "./Cause.ts"
@@ -25,8 +53,8 @@ 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`.
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Pool<in out A, in out E = never> extends Pipeable {
   readonly [TypeId]: typeof TypeId
@@ -35,8 +63,15 @@ export interface Pool<in out A, in out E = never> extends Pipeable {
 }
 
 /**
- * @since 4.0.0
+ * Normalized configuration used by a `Pool`.
+ *
+ * **Details**
+ *
+ * The config stores the acquire effect, size bounds, per-item concurrency,
+ * target utilization, and resizing strategy used by the pool implementation.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Config<A, E> {
   readonly acquire: Effect.Effect<A, E, Scope.Scope>
@@ -48,8 +83,17 @@ export interface Config<A, E> {
 }
 
 /**
- * @since 4.0.0
+ * Mutable runtime state maintained by a `Pool`.
+ *
+ * **Details**
+ *
+ * This state tracks the pool scope, active and available items, invalidated
+ * items, semaphores, waiters, and shutdown status. It is exposed for
+ * inspection and implementation support; user code should prefer the
+ * high-level pool operations.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface State<A, E> {
   readonly scope: Scope.Scope
@@ -64,8 +108,16 @@ export interface State<A, E> {
 }
 
 /**
- * @since 4.0.0
+ * Internal record for a value managed by a `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.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface PoolItem<A, E> {
   readonly exit: Exit.Exit<A, E>
@@ -75,8 +127,17 @@ export interface PoolItem<A, E> {
 }
 
 /**
- * @since 4.0.0
+ * Strategy used by a `Pool` to manage background resizing and item
+ * 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.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Strategy<A, E> {
   readonly run: (pool: Pool<A, E>) => Effect.Effect<void>
@@ -87,8 +148,8 @@ export interface Strategy<A, E> {
 /**
  * Returns `true` if the specified value is a `Pool`, `false` otherwise.
  *
- * @since 2.0.0
  * @category refinements
+ * @since 2.0.0
  */
 export const isPool = (u: unknown): u is Pool<unknown, unknown> => hasProperty(u, TypeId)
 
@@ -108,8 +169,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.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = <A, E, R>(options: {
   readonly acquire: Effect.Effect<A, E, R>
@@ -120,28 +181,22 @@ export const make = <A, E, R>(options: {
   makeWithStrategy({ ...options, min: options.size, max: options.size, strategy: strategyNoop() })
 
 /**
- * Makes a new pool with the specified minimum and maximum sizes and time to
- * live before a pool whose excess items are not being used will be shrunk
- * down to the minimum size. The pool is returned in a `Scope`, which governs
- * the lifetime of the pool. When the pool is shutdown because the `Scope` is
- * used, the individual items allocated by the pool will be released in some
- * unspecified order.
- *
- * By setting the `concurrency` parameter, you can control the level of concurrent
- * access per pool item. By default, the number of permits is set to `1`.
+ * Creates a scoped pool with minimum and maximum sizes and a time-to-live
+ * policy for shrinking unused excess items.
  *
- * `targetUtilization` determines when to create new pool items. It is a value
- * between 0 and 1, where 1 means only create new pool items when all the existing
- * items are fully utilized.
+ * **Details**
  *
- * A `targetUtilization` of 0.5 will create new pool items when the existing items are
- * 50% utilized.
+ * The returned pool requires `Scope`; when that scope is closed, allocated
+ * items are released in an unspecified order. `concurrency` controls how many
+ * fibers may use each pool item at once and defaults to `1`.
  *
- * The `timeToLiveStrategy` determines how items are invalidated. If set to
- * "creation", then items are invalidated based on their creation time. If set
- * to "usage", then items are invalidated based on pool usage.
+ * `targetUtilization` controls when new items are created and is clamped by the
+ * pool implementation. A value of `1` waits until existing items are fully
+ * utilized before creating more items.
  *
- * By default, the `timeToLiveStrategy` is set to "usage".
+ * `timeToLiveStrategy` controls when excess items expire: `"creation"` measures
+ * from item creation, while `"usage"` measures from pool usage. The default is
+ * `"usage"`.
  *
  * ```ts skip-type-checking
  * import { Duration, Effect, Pool } from "effect"
@@ -163,8 +218,8 @@ export const make = <A, E, R>(options: {
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const makeWithTTL = <A, E, R>(options: {
   readonly acquire: Effect.Effect<A, E, R>
@@ -183,8 +238,16 @@ export const makeWithTTL = <A, E, R>(options: {
   )
 
 /**
- * @since 4.0.0
+ * Creates a scoped pool using a custom resizing and reclamation strategy.
+ *
+ * **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.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeWithStrategy = <A, E, R>(options: {
   readonly acquire: Effect.Effect<A, E, R>
@@ -269,8 +332,8 @@ const shutdown = Effect.fnUntraced(function*<A, E>(self: Pool<A, E>) {
  * acquisition fails, then the returned effect will fail for that same reason.
  * Retrying a failed acquisition attempt will repeat the acquisition attempt.
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const get = <A, E>(self: Pool<A, E>): Effect.Effect<A, E, Scope.Scope> =>
   Effect.suspend(() => {
@@ -346,8 +409,8 @@ const getPoolItemInner = Effect.fnUntraced(function*<A, E>(
  * reallocate the item, although this reallocation may occur lazily rather
  * than eagerly.
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const invalidate: {
   /**
@@ -355,8 +418,8 @@ export const invalidate: {
    * reallocate the item, although this reallocation may occur lazily rather
    * than eagerly.
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <A>(item: A): <E>(self: Pool<A, E>) => Effect.Effect<void, never, Scope.Scope>
   /**
@@ -364,8 +427,8 @@ export const invalidate: {
    * reallocate the item, although this reallocation may occur lazily rather
    * than eagerly.
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <A, E>(self: Pool<A, E>, item: A): Effect.Effect<void, never, Scope.Scope>
 } = dual(2, <A, E>(self: Pool<A, E>, item: A): Effect.Effect<void, never, Scope.Scope> =>

package/src/Predicate.ts

@@ -161,8 +161,8 @@ export interface Refinement<in A, out B extends A> {
  *
  * See also: {@link Predicate}, {@link Refinement}
  *
- * @since 3.6.0
  * @category type-level
+ * @since 3.6.0
  */
 export declare namespace Predicate {
   /**
@@ -187,8 +187,8 @@ export declare namespace Predicate {
    *
    * See also: {@link Predicate.Any}, {@link Refinement.In}
    *
-   * @since 3.6.0
    * @category type-level
+   * @since 3.6.0
    */
   export type In<T extends Any> = [T] extends [Predicate<infer _A>] ? _A : never
 
@@ -211,8 +211,8 @@ export declare namespace Predicate {
    *
    * See also: {@link Predicate.In}
    *
-   * @since 3.6.0
    * @category type-level
+   * @since 3.6.0
    */
   export type Any = Predicate<any>
 }
@@ -240,8 +240,8 @@ export declare namespace Predicate {
  *
  * See also: {@link Refinement}, {@link Predicate}
  *
- * @since 3.6.0
  * @category type-level
+ * @since 3.6.0
  */
 export declare namespace Refinement {
   /**
@@ -265,8 +265,8 @@ export declare namespace Refinement {
    *
    * See also: {@link Refinement.Out}, {@link Predicate.In}
    *
-   * @since 3.6.0
    * @category type-level
+   * @since 3.6.0
    */
 
   export type In<T extends Any> = [T] extends [Refinement<infer _A, infer _>] ? _A : never
@@ -292,8 +292,8 @@ export declare namespace Refinement {
    *
    * See also: {@link Refinement.In}
    *
-   * @since 3.6.0
    * @category type-level
+   * @since 3.6.0
    */
   export type Out<T extends Any> = [T] extends [Refinement<infer _, infer _B>] ? _B : never
 
@@ -316,8 +316,8 @@ export declare namespace Refinement {
    *
    * See also: {@link Refinement.In}, {@link Refinement.Out}
    *
-   * @since 3.6.0
    * @category type-level
+   * @since 3.6.0
    */
   export type Any = Refinement<any, any>
 }
@@ -1161,14 +1161,11 @@ export function isObjectOrArray(input: unknown): input is { [x: PropertyKey]: un
 }
 
 /**
- * Checks whether a value is a plain object (not an array, not `null`).
+ * Checks whether a value is a non-null object value that is not an array.
  *
- * When to use:
- * - You need to accept objects but exclude arrays.
- *
- * Behavior:
- * - Pure; does not mutate input.
- * - Uses `typeof input === "object" && input !== null && !Array.isArray(input)`.
+ * This is a structural runtime check using `typeof input === "object"`, so it
+ * also accepts object instances such as `Date`, `Map`, class instances, and
+ * typed arrays. It excludes `null` and arrays.
  *
  * **Example** (Guard object)
  *
@@ -1189,14 +1186,12 @@ export function isObject(input: unknown): input is { [x: PropertyKey]: unknown }
 }
 
 /**
- * Checks whether a value is a readonly object.
- *
- * When to use:
- * - You need a guard for object-like values and do not care about mutability.
+ * Checks whether a value is a non-null, non-array object and narrows it to a
+ * readonly indexable object type.
  *
- * Behavior:
- * - Pure; does not mutate input.
- * - Delegates to {@link isObject}.
+ * Readonly-ness is a TypeScript type-level view; it is not observable at
+ * runtime. This delegates to `isObject`, so class instances and built-in object
+ * instances are accepted.
  *
  * **Example** (Readonly object)
  *

package/src/PrimaryKey.ts

@@ -25,7 +25,8 @@ export const symbol = "~effect/interfaces/PrimaryKey"
  * Objects implementing this interface must provide a method that returns
  * a unique string identifier.
  *
- * @example
+ * **Example** (Implementing a primary key)
+ *
  * ```ts
  * import { PrimaryKey } from "effect"
  *
@@ -49,6 +50,11 @@ export interface PrimaryKey {
 }
 
 /**
+ * Checks whether a value implements the `PrimaryKey` protocol.
+ *
+ * This is a structural guard for the `PrimaryKey.symbol` property. It does not
+ * call the method or verify that it returns a string.
+ *
  * @category models
  * @since 2.0.0
  */
@@ -57,7 +63,8 @@ export const isPrimaryKey = (u: unknown): u is PrimaryKey => hasProperty(u, symb
 /**
  * Extracts the string value from a `PrimaryKey`.
  *
- * @example
+ * **Example** (Reading primary key values)
+ *
  * ```ts
  * import { PrimaryKey } from "effect"
  *