effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/Path.ts

@@ -1,4 +1,34 @@
 /**
+ * The `Path` module provides a platform path service for manipulating file
+ * system paths through Effect's environment. It models path operations as a
+ * replaceable service so programs can depend on path behavior without directly
+ * coupling to a particular runtime implementation.
+ *
+ * **Mental model**
+ *
+ * - `Path.Path` is a `Context.Service` tag used to access the current path implementation
+ * - The service offers familiar path operations such as joining, resolving, parsing, and formatting
+ * - Most operations are pure string transformations and follow POSIX-style path semantics
+ * - File URL conversions return `Effect`s because invalid paths or URLs can fail with `BadArgument`
+ * - Custom implementations can be provided with `Layer.succeed` for alternate platforms or tests
+ *
+ * **Common tasks**
+ *
+ * - Combine path segments with `join` or turn segments into an absolute path with `resolve`
+ * - Normalize `.` and `..` segments with `normalize`
+ * - Inspect paths with `basename`, `dirname`, `extname`, and `isAbsolute`
+ * - Convert between structured path parts and strings with `parse` and `format`
+ * - Compute relative paths with `relative`
+ * - Convert between file paths and `file:` URLs with `toFileUrl` and `fromFileUrl`
+ *
+ * **Gotchas**
+ *
+ * - Path strings are not checked against the file system; these operations only manipulate syntax
+ * - `resolve` may consult the host current working directory when no absolute segment is supplied
+ * - `fromFileUrl` only accepts valid `file:` URLs and rejects encoded path separators
+ * - Use the service from the environment when writing portable Effect code instead of importing
+ *   host-specific path APIs directly
+ *
  * @since 4.0.0
  */
 import * as Context from "./Context.ts"
@@ -8,14 +38,21 @@ import * as Layer from "./Layer.ts"
 import { BadArgument } from "./PlatformError.ts"
 
 /**
+ * Runtime type identifier used to mark implementations of the `Path` service.
+ *
  * @since 4.0.0
  */
 export const TypeId = "~effect/platform/Path"
 
 /**
- * @since 4.0.0
- * @category model
- * @example
+ * Service interface for platform-specific path manipulation.
+ *
+ * The service exposes operations for joining, normalizing, parsing,
+ * formatting, and converting file system paths. URL conversion methods return
+ * `Effect`s because invalid file URLs or paths can fail with `BadArgument`.
+ *
+ * **Example** (Using path operations)
+ *
  * ```ts
  * import { Effect, Path } from "effect"
  *
@@ -46,6 +83,9 @@ export const TypeId = "~effect/platform/Path"
  *   })
  * })
  * ```
+ *
+ * @category model
+ * @since 4.0.0
  */
 export interface Path {
   readonly [TypeId]: typeof TypeId
@@ -66,9 +106,10 @@ export interface Path {
 }
 
 /**
- * @since 4.0.0
- * @category namespace
- * @example
+ * Namespace containing types associated with the `Path` service.
+ *
+ * **Example** (Working with parsed paths)
+ *
  * ```ts
  * import { Effect, Path } from "effect"
  *
@@ -91,12 +132,20 @@ export interface Path {
  *   console.log(parsed, exampleParsed)
  * })
  * ```
+ *
+ * @category namespace
+ * @since 4.0.0
  */
 export declare namespace Path {
   /**
-   * @since 4.0.0
-   * @category model
-   * @example
+   * Structured representation of a parsed file system path.
+   *
+   * The fields correspond to the path root, directory, base filename,
+   * extension, and filename without extension, matching the shape consumed by
+   * `Path.format`.
+   *
+   * **Example** (Parsing and formatting paths)
+   *
    * ```ts
    * import { Effect, Path } from "effect"
    *
@@ -123,6 +172,9 @@ export declare namespace Path {
    *   console.log(formatted) // "/home/user/newfile.ts"
    * })
    * ```
+   *
+   * @category model
+   * @since 4.0.0
    */
   export interface Parsed {
     readonly root: string
@@ -134,9 +186,13 @@ export declare namespace Path {
 }
 
 /**
- * @since 4.0.0
- * @category tag
- * @example
+ * Context service tag for accessing the current `Path` implementation.
+ *
+ * Yield this service inside an effect to use path operations supplied by the
+ * environment, or provide a custom implementation with `Layer.succeed`.
+ *
+ * **Example** (Providing a custom Path service)
+ *
  * ```ts
  * import { Effect, Layer, Path } from "effect"
  *
@@ -190,6 +246,9 @@ export declare namespace Path {
  * // Run with custom path implementation
  * const result = Effect.provide(program, customPathLayer)
  * ```
+ *
+ * @category tag
+ * @since 4.0.0
  */
 export const Path: Context.Service<Path, Path> = Context.Service("effect/Path")
 
@@ -786,7 +845,12 @@ const posixImpl = Path.of({
 })
 
 /**
- * @since 4.0.0
+ * Layer that provides the built-in POSIX `Path` implementation.
+ *
+ * Use this layer when an effect requires the `Path` service and should use
+ * forward-slash path semantics.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<Path> = Layer.succeed(Path)(posixImpl)

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> =>