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

package/src/FileSystem.ts

@@ -1,39 +1,56 @@
 /**
- * This module provides a comprehensive file system abstraction that supports both synchronous
- * and asynchronous file operations through Effect. It includes utilities for file I/O, directory
- * management, permissions, timestamps, and file watching with proper error handling.
+ * Effect service for reading, writing, inspecting, and watching files.
  *
- * The `FileSystem` interface provides a cross-platform abstraction over file system operations,
- * allowing you to work with files and directories in a functional, composable way. All operations
- * return `Effect` values that can be composed, transformed, and executed safely.
+ * The `FileSystem` service is the portable boundary between Effect programs and
+ * the host file system. Programs depend on the service from `effect/FileSystem`;
+ * platform packages provide concrete layers at the edge. Operations return
+ * `Effect`, `Stream`, or `Sink` values and report failures as `PlatformError`
+ * instead of throwing.
  *
- * **Example** (Working with files and directories)
+ * **Mental model**
  *
- * ```ts
- * import { Console, Effect, FileSystem } from "effect"
+ * `FileSystem` is a capability, not a global singleton. Request it with
+ * `yield* FileSystem.FileSystem` inside an effect, compose file work like any
+ * other effect, and provide a platform or test implementation when the program
+ * is run. Scoped operations such as `open`, `makeTempFileScoped`, and
+ * `makeTempDirectoryScoped` bind resource cleanup to `Scope`.
  *
- * const program = Effect.gen(function*() {
- *   const fs = yield* FileSystem.FileSystem
+ * **Common tasks**
  *
- *   // Create a directory
- *   yield* fs.makeDirectory("./temp", { recursive: true })
+ * - Create, copy, rename, remove, chmod, chown, link, and symlink paths.
+ * - Read and write whole files as bytes or strings.
+ * - Stream large files with `stream` and `sink`, using binary size helpers such
+ *   as `KiB` and `MiB` for chunk sizes and offsets.
+ * - Inspect metadata with `stat`, check accessibility with `access` or
+ *   `exists`, and canonicalize paths with `realPath`.
+ * - Watch files or directories with `watch` when the platform implementation
+ *   supports it.
  *
- *   // Write a file
- *   yield* fs.writeFileString("./temp/hello.txt", "Hello, World!")
+ * **Example** (Write and clean up a temporary file)
  *
- *   // Read the file back
- *   const content = yield* fs.readFileString("./temp/hello.txt")
- *   yield* Console.log("File content:", content)
+ * ```ts
+ * import { Effect, FileSystem } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const fs = yield* FileSystem.FileSystem
  *
- *   // Get file information
- *   const stats = yield* fs.stat("./temp/hello.txt")
- *   yield* Console.log("File size:", stats.size)
+ *   const directory = yield* fs.makeTempDirectoryScoped()
+ *   const path = `${directory}/message.txt`
  *
- *   // Clean up
- *   yield* fs.remove("./temp", { recursive: true })
+ *   yield* fs.writeFileString(path, "hello")
+ *   return yield* fs.readFileString(path)
  * })
  * ```
  *
+ * **Gotchas**
+ *
+ * Paths are interpreted by the provided implementation, so relative paths, case
+ * sensitivity, permissions, links, and watch behavior are platform-dependent.
+ * Size options are normalized to branded bigint byte counts; prefer the `Size`,
+ * `KiB`, `MiB`, and related helpers for offsets, chunk sizes, and truncation
+ * lengths. A program that uses this service still needs a concrete layer, such
+ * as `NodeFileSystem.layer`, before it can access the real file system.
+ *
  * @since 4.0.0
  */
 import * as Arr from "./Array.ts"
@@ -765,12 +782,21 @@ export const FileSystem: Context.Service<FileSystem, FileSystem> = Context.Servi
 /**
  * Creates a FileSystem implementation from a partial implementation.
  *
+ * **When to use**
+ *
+ * Use to build a concrete `FileSystem` service from platform-specific core
+ * operations while deriving the convenience methods that can be implemented
+ * from them.
+ *
  * **Details**
  *
  * This function takes a partial FileSystem implementation and automatically provides
  * default implementations for `exists`, `readFileString`, `stream`, `sink`, and
  * `writeFileString` methods based on the provided core methods.
  *
+ * @see {@link makeNoop} for a testing stub that accepts method overrides without requiring a complete implementation
+ * @see {@link layerNoop} for providing a no-op `FileSystem` as a `Layer` in tests
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -1044,18 +1070,35 @@ export const layerNoop = (fileSystem: Partial<FileSystem>): Layer.Layer<FileSyst
  * Runtime type identifier attached to `FileSystem.File` handles and used by
  * `isFile` to recognize them.
  *
+ * **When to use**
+ *
+ * Use when implementing a custom `FileSystem` file handle that should be
+ * recognized by `isFile`.
+ *
+ * @see {@link File} for the open file handle shape that carries this marker
+ * @see {@link isFile} for the public guard that checks this marker
+ *
  * @category File
  * @since 4.0.0
  */
 export const FileTypeId = "~effect/platform/FileSystem/File"
 
 /**
- * Type guard to check if a value is a File instance.
+ * Returns `true` if a value is a `File` handle by checking for the
+ * `FileTypeId` marker.
+ *
+ * **When to use**
+ *
+ * Use when accepting an unknown value and you need to narrow it to a `File`
+ * before calling file-handle operations.
  *
  * **Details**
  *
- * This function determines whether the provided value is a valid File
- * instance by checking for the presence of the File type identifier.
+ * This is a structural marker check. It does not validate the marker value or
+ * the shape of the file handle.
+ *
+ * @see {@link File} for the file-handle interface narrowed by this guard
+ * @see {@link FileTypeId} for the runtime marker checked by this guard
  *
  * @category File
  * @since 4.0.0
@@ -1224,12 +1267,25 @@ export declare namespace File {
 }
 
 /**
- * Creates a branded file descriptor.
+ * Creates a `File.Descriptor` from a number.
+ *
+ * **When to use**
+ *
+ * Use to brand an operating-system file descriptor number when implementing a
+ * `FileSystem` that returns custom `File` handles.
  *
  * **Details**
  *
- * File descriptors are integer handles that the operating system uses to identify
- * open files. This branded type ensures type safety when working with file descriptors.
+ * `File.Descriptor` is a branded integer handle used by operating systems to
+ * identify open files.
+ *
+ * **Gotchas**
+ *
+ * This constructor is nominal and does not check that the number is an integer
+ * or that it refers to an open file descriptor.
+ *
+ * @see {@link File.Descriptor} for the branded descriptor type produced by this constructor
+ * @see {@link File} for file handles that expose a descriptor through `fd`
  *
  * @category constructors
  * @since 4.0.0
@@ -1237,12 +1293,20 @@ export declare namespace File {
 export const FileDescriptor = Brand.nominal<File.Descriptor>()
 
 /**
- * Specifies the reference point for seeking within a file.
+ * Specifies the reference point for seeking within an open file.
+ *
+ * **When to use**
+ *
+ * Use with `File` handles when positioning the cursor before a read or write
+ * and the offset must be interpreted from either the start of the file or the
+ * current cursor.
  *
  * **Details**
  *
- * - `"start"` - Seek from the beginning of the file
- * - `"current"` - Seek from the current position
+ * - `"start"` seeks from the beginning of the file.
+ * - `"current"` seeks from the current cursor position.
+ *
+ * @see {@link File} for the open file handle API whose `seek` method consumes this mode
  *
  * @category models
  * @since 4.0.0
@@ -1250,7 +1314,19 @@ export const FileDescriptor = Brand.nominal<File.Descriptor>()
 export type SeekMode = "start" | "current"
 
 /**
- * Represents file system events that can be observed when watching files or directories.
+ * Represents file system events emitted when watching files or directories.
+ *
+ * **When to use**
+ *
+ * Use when consuming file system watch streams and pattern matching on `_tag`
+ * to handle created, updated, or removed paths.
+ *
+ * **Details**
+ *
+ * The union covers create, update, and remove events. Each event carries the
+ * reported `path`.
+ *
+ * @see {@link FileSystem} for the service interface whose `watch` operation emits these events
  *
  * @category models
  * @since 4.0.0

package/src/Filter.ts

@@ -328,7 +328,15 @@ export const fromPredicateOption = <A, B>(predicate: (a: A) => Option.Option<B>)
 /**
  * Converts a Filter into a predicate function.
  *
- * @category constructors
+ * **When to use**
+ *
+ * Use to reuse a `Filter` with APIs that accept only boolean predicates when
+ * the pass and fail payloads are not needed.
+ *
+ * @see {@link toOption} for keeping passed values and discarding failure values
+ * @see {@link toResult} for preserving both pass and failure values
+ *
+ * @category converting
  * @since 4.0.0
  */
 export const toPredicate = <A, Pass, Fail>(
@@ -357,6 +365,20 @@ export const string: Filter<unknown, string> = fromPredicate(Predicate.isString)
  * Creates a `Filter` that passes only values strictly equal to the specified
  * value using JavaScript `===` comparison.
  *
+ * **When to use**
+ *
+ * Use when you need a `Filter` that accepts only the exact primitive value or
+ * object reference using JavaScript strict equality in a `Filter` / `Result`
+ * pipeline.
+ *
+ * **Gotchas**
+ *
+ * `NaN` never passes, even when the expected value is `NaN`, and objects pass
+ * only when they are the same reference.
+ *
+ * @see {@link equals} for structural equality when distinct values with equal
+ * contents should pass
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -368,6 +390,16 @@ export const equalsStrict =
  * Creates a `Filter` that passes inputs whose `has(key)` method returns
  * `true` for the specified key.
  *
+ * **When to use**
+ *
+ * Use to keep inputs that expose a `has` method, such as `Set` or `Map`, when
+ * they contain a required key.
+ *
+ * @see {@link fromPredicate} for custom predicate filters or inputs without a
+ * `has` method
+ * @see {@link Predicate.hasProperty} for guarding property presence instead of
+ * calling an input's `has` method
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -378,6 +410,23 @@ export const has =
 /**
  * Creates a filter that only passes instances of the given constructor.
  *
+ * **When to use**
+ *
+ * Use to narrow unknown input to values created by a specific JavaScript
+ * constructor while keeping the result in the `Filter` / `Result` pipeline.
+ *
+ * **Details**
+ *
+ * The filter succeeds when the input satisfies `instanceof constructor`.
+ * Otherwise it fails with the original input.
+ *
+ * **Gotchas**
+ *
+ * This uses JavaScript `instanceof` semantics, including prototype-chain and
+ * realm behavior.
+ *
+ * @see {@link fromPredicate} for custom predicate-based narrowing
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -406,13 +455,44 @@ export const number: Filter<unknown, number> = fromPredicate(Predicate.isNumber)
 /**
  * A predefined filter that only passes through boolean values.
  *
+ * **When to use**
+ *
+ * Use when accepting an unknown input only if it is already a boolean and you
+ * want a `Filter` result rather than a plain predicate result.
+ *
+ * **Details**
+ *
+ * Implemented with `fromPredicate(Predicate.isBoolean)`, so `true` and `false`
+ * succeed and non-booleans fail with the original input.
+ *
+ * @see {@link Predicate.isBoolean} for the underlying guard
+ * @see {@link fromPredicate} for custom predicate-based filters
+ *
  * @category constructors
  * @since 4.0.0
  */
 export const boolean: Filter<unknown, boolean> = fromPredicate(Predicate.isBoolean)
 
 /**
- * A predefined filter that only passes through BigInt values.
+ * A predefined filter that only passes through `bigint` primitive values.
+ *
+ * **When to use**
+ *
+ * Use to keep `bigint` primitive values from unknown input while staying in the
+ * composable `Filter` / `Result` pipeline.
+ *
+ * **Details**
+ *
+ * Implemented with `fromPredicate(Predicate.isBigInt)`, so values where
+ * `typeof input === "bigint"` succeed and all other inputs fail with the
+ * original input.
+ *
+ * **Gotchas**
+ *
+ * This filter does not coerce numbers or strings; `1n` passes while `1` fails.
+ *
+ * @see {@link number} for JavaScript `number` values
+ * @see {@link Predicate.isBigInt} for the underlying guard
  *
  * @category constructors
  * @since 4.0.0
@@ -430,6 +510,25 @@ export const symbol: Filter<unknown, symbol> = fromPredicate(Predicate.isSymbol)
 /**
  * A predefined filter that only passes through Date objects.
  *
+ * **When to use**
+ *
+ * Use when narrowing unknown input to JavaScript `Date` instances with a
+ * reusable `Filter`.
+ *
+ * **Details**
+ *
+ * Implemented with `fromPredicate(Predicate.isDate)`, so passing values return
+ * `Result.succeed(input)` and failing values return `Result.fail(input)`.
+ *
+ * **Gotchas**
+ *
+ * The check uses `instanceof Date`, so invalid `Date` objects still pass; the
+ * filter does not validate the timestamp.
+ *
+ * @see {@link Predicate.isDate} for the underlying guard
+ * @see {@link instanceOf} for constructor-based filtering
+ * @see {@link fromPredicate} for custom date checks
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -438,6 +537,24 @@ export const date: Filter<unknown, Date> = fromPredicate(Predicate.isDate)
 /**
  * Creates a filter that checks if an input is tagged with a specific tag.
  *
+ * **When to use**
+ *
+ * Use to keep only the matching member of a `_tag`-discriminated union while
+ * staying in a composable `Filter` / `Result` pipeline.
+ *
+ * **Details**
+ *
+ * The filter succeeds when `Predicate.isTagged(input, tag)` returns `true`.
+ * Otherwise it fails with the original input.
+ *
+ * **Gotchas**
+ *
+ * This only checks `_tag`; it does not validate the rest of the variant fields.
+ *
+ * @see {@link Predicate.isTagged} for the underlying boolean guard when a
+ * `Filter` result is not needed
+ * @see {@link reason} for extracting a nested reason variant from tagged errors
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -445,6 +562,24 @@ export const tagged: {
   /**
    * Creates a filter that checks if an input is tagged with a specific tag.
    *
+   * **When to use**
+   *
+   * Use to keep only the matching member of a `_tag`-discriminated union while
+   * staying in a composable `Filter` / `Result` pipeline.
+   *
+   * **Details**
+   *
+   * The filter succeeds when `Predicate.isTagged(input, tag)` returns `true`.
+   * Otherwise it fails with the original input.
+   *
+   * **Gotchas**
+   *
+   * This only checks `_tag`; it does not validate the rest of the variant fields.
+   *
+   * @see {@link Predicate.isTagged} for the underlying boolean guard when a
+   * `Filter` result is not needed
+   * @see {@link reason} for extracting a nested reason variant from tagged errors
+   *
    * @category constructors
    * @since 4.0.0
    */
@@ -452,6 +587,24 @@ export const tagged: {
   /**
    * Creates a filter that checks if an input is tagged with a specific tag.
    *
+   * **When to use**
+   *
+   * Use to keep only the matching member of a `_tag`-discriminated union while
+   * staying in a composable `Filter` / `Result` pipeline.
+   *
+   * **Details**
+   *
+   * The filter succeeds when `Predicate.isTagged(input, tag)` returns `true`.
+   * Otherwise it fails with the original input.
+   *
+   * **Gotchas**
+   *
+   * This only checks `_tag`; it does not validate the rest of the variant fields.
+   *
+   * @see {@link Predicate.isTagged} for the underlying boolean guard when a
+   * `Filter` result is not needed
+   * @see {@link reason} for extracting a nested reason variant from tagged errors
+   *
    * @category constructors
    * @since 4.0.0
    */
@@ -459,6 +612,24 @@ export const tagged: {
   /**
    * Creates a filter that checks if an input is tagged with a specific tag.
    *
+   * **When to use**
+   *
+   * Use to keep only the matching member of a `_tag`-discriminated union while
+   * staying in a composable `Filter` / `Result` pipeline.
+   *
+   * **Details**
+   *
+   * The filter succeeds when `Predicate.isTagged(input, tag)` returns `true`.
+   * Otherwise it fails with the original input.
+   *
+   * **Gotchas**
+   *
+   * This only checks `_tag`; it does not validate the rest of the variant fields.
+   *
+   * @see {@link Predicate.isTagged} for the underlying boolean guard when a
+   * `Filter` result is not needed
+   * @see {@link reason} for extracting a nested reason variant from tagged errors
+   *
    * @category constructors
    * @since 4.0.0
    */
@@ -522,6 +693,20 @@ const reasonImpl =
 /**
  * Creates a filter that only passes values equal to the specified value using structural equality.
  *
+ * **When to use**
+ *
+ * Use to accept inputs that are structurally equal to a known expected value
+ * while staying in a composable `Filter` / `Result` pipeline.
+ *
+ * **Details**
+ *
+ * Delegates to `Equal.equals`. On success it returns `Result.succeed(value)`;
+ * on failure it returns `Result.fail(input)`.
+ *
+ * @see {@link equalsStrict} for JavaScript `===` matching instead of structural
+ * equality
+ * @see {@link Equal.equals} for the underlying structural equality semantics
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -562,11 +747,17 @@ export const or: {
 /**
  * Combines two filters and applies a function to their results.
  *
+ * **When to use**
+ *
+ * Use to combine two filters with a custom function to merge their outputs.
+ *
  * **Details**
  *
  * Both filters must succeed (not return `fail`) for the combination to succeed.
  * If both filters pass, their outputs are combined using the provided function.
  *
+ * @see {@link zip} for combining two filters into a tuple
+ *
  * @category combinators
  * @since 4.0.0
  */
@@ -574,11 +765,17 @@ export const zipWith: {
   /**
    * Combines two filters and applies a function to their results.
    *
+   * **When to use**
+   *
+   * Use to combine two filters with a custom function to merge their outputs.
+   *
    * **Details**
    *
    * Both filters must succeed (not return `fail`) for the combination to succeed.
    * If both filters pass, their outputs are combined using the provided function.
    *
+   * @see {@link zip} for combining two filters into a tuple
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -586,11 +783,17 @@ export const zipWith: {
   /**
    * Combines two filters and applies a function to their results.
    *
+   * **When to use**
+   *
+   * Use to combine two filters with a custom function to merge their outputs.
+   *
    * **Details**
    *
    * Both filters must succeed (not return `fail`) for the combination to succeed.
    * If both filters pass, their outputs are combined using the provided function.
    *
+   * @see {@link zip} for combining two filters into a tuple
+   *
    * @category combinators
    * @since 4.0.0
    */
@@ -942,6 +1145,14 @@ export const composePassthrough: {
  * Converts a `Filter` into a function that returns `Some` for passed values
  * and `None` for filtered-out values.
  *
+ * **When to use**
+ *
+ * Use when adapting a `Filter` to `Option`-based code and you only need the
+ * passed value, with filtered-out inputs represented as `None`.
+ *
+ * @see {@link toResult} for keeping the filter failure value
+ * @see {@link toPredicate} for plain boolean pass/fail checks
+ *
  * @category converting
  * @since 4.0.0
  */
@@ -957,6 +1168,14 @@ export const toOption = <A, Pass, Fail>(
  * Converts a `Filter` into a function that returns the underlying
  * `Result.Result` for each input.
  *
+ * **When to use**
+ *
+ * Use to adapt a `Filter` to APIs that expect a plain function returning
+ * `Result`, while preserving both the pass value and the failure value.
+ *
+ * @see {@link toOption} for keeping only passed values
+ * @see {@link toPredicate} for plain boolean pass/fail checks
+ *
  * @category converting
  * @since 4.0.0
  */

package/src/Formatter.ts

@@ -60,7 +60,7 @@ import { getRedacted, redact, symbolRedactable } from "./Redactable.ts"
  *
  * **When to use**
  *
- * Use `Formatter` when you want to type a formatting or rendering function generically, or when you are building a pipeline that accepts pluggable formatters.
+ * Use when you want to type a formatting or rendering function generically, or when you are building a pipeline that accepts pluggable formatters.
  *
  * **Details**
  *
@@ -91,7 +91,7 @@ export interface Formatter<in Value, out Format = string> {
  *
  * **When to use**
  *
- * - Pretty-printing values for debugging, logging, or error messages.
+ * Use to pretty-print values for debugging, logging, or error messages.
  * - You need to handle `BigInt`, `Symbol`, `Set`, `Map`, `Date`, `RegExp`,
  *   or class instances that `JSON.stringify` cannot represent.
  * - You want circular references shown as `"[Circular]"` instead of
@@ -289,7 +289,7 @@ function safeToString(input: any): string {
  *
  * **When to use**
  *
- * - You need valid JSON output (unlike {@link format}).
+ * Use when you need valid JSON output (unlike {@link format}).
  * - The input may contain circular references and you want them silently
  *   omitted rather than throwing a `TypeError`.
  *