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

package/src/FiberMap.ts

@@ -608,7 +608,7 @@ export const set: {
 ): Effect.Effect<void> => Effect.sync(() => setUnsafe(self, key, fiber, options)))
 
 /**
- * Retrieve a fiber from the FiberMap.
+ * Retrieves a fiber from the FiberMap synchronously.
  *
  * **Example** (Retrieving a fiber unsafely)
  *
@@ -639,7 +639,7 @@ export const set: {
  */
 export const getUnsafe: {
   /**
-   * Retrieve a fiber from the FiberMap.
+   * Retrieves a fiber from the FiberMap synchronously.
    *
    * **Example** (Retrieving a fiber unsafely)
    *
@@ -670,7 +670,7 @@ export const getUnsafe: {
    */
   <K>(key: K): <A, E>(self: FiberMap<K, A, E>) => Option.Option<Fiber.Fiber<A, E>>
   /**
-   * Retrieve a fiber from the FiberMap.
+   * Retrieves a fiber from the FiberMap synchronously.
    *
    * **Example** (Retrieving a fiber unsafely)
    *
@@ -708,7 +708,7 @@ export const getUnsafe: {
 )
 
 /**
- * Retrieve a fiber from the FiberMap.
+ * Retrieves a fiber from the FiberMap effectfully.
  *
  * **Details**
  *
@@ -743,7 +743,7 @@ export const getUnsafe: {
  */
 export const get: {
   /**
-   * Retrieve a fiber from the FiberMap.
+   * Retrieves a fiber from the FiberMap effectfully.
    *
    * **Details**
    *
@@ -778,7 +778,7 @@ export const get: {
    */
   <K>(key: K): <A, E>(self: FiberMap<K, A, E>) => Effect.Effect<Option.Option<Fiber.Fiber<A, E>>>
   /**
-   * Retrieve a fiber from the FiberMap.
+   * Retrieves a fiber from the FiberMap effectfully.
    *
    * **Details**
    *
@@ -819,7 +819,7 @@ export const get: {
 )
 
 /**
- * Check if a key exists in the FiberMap.
+ * Checks whether a key exists in the FiberMap.
  *
  * **Example** (Checking if a key exists unsafely)
  *
@@ -843,7 +843,7 @@ export const get: {
  */
 export const hasUnsafe: {
   /**
-   * Check if a key exists in the FiberMap.
+   * Checks whether a key exists in the FiberMap.
    *
    * **Example** (Checking if a key exists unsafely)
    *
@@ -867,7 +867,7 @@ export const hasUnsafe: {
    */
   <K>(key: K): <A, E>(self: FiberMap<K, A, E>) => boolean
   /**
-   * Check if a key exists in the FiberMap.
+   * Checks whether a key exists in the FiberMap.
    *
    * **Example** (Checking if a key exists unsafely)
    *
@@ -897,7 +897,7 @@ export const hasUnsafe: {
 )
 
 /**
- * Check if a key exists in the FiberMap.
+ * Checks whether a key exists in the FiberMap.
  * This is the Effect-wrapped version of `hasUnsafe`.
  *
  * **Example** (Checking if a key exists)
@@ -925,7 +925,7 @@ export const hasUnsafe: {
  */
 export const has: {
   /**
-   * Check if a key exists in the FiberMap.
+   * Checks whether a key exists in the FiberMap.
    * This is the Effect-wrapped version of `hasUnsafe`.
    *
    * **Example** (Checking if a key exists)
@@ -953,7 +953,7 @@ export const has: {
    */
   <K>(key: K): <A, E>(self: FiberMap<K, A, E>) => Effect.Effect<boolean>
   /**
-   * Check if a key exists in the FiberMap.
+   * Checks whether a key exists in the FiberMap.
    * This is the Effect-wrapped version of `hasUnsafe`.
    *
    * **Example** (Checking if a key exists)
@@ -986,7 +986,7 @@ export const has: {
 )
 
 /**
- * Remove a fiber from the FiberMap, interrupting it if it exists.
+ * Removes a fiber from the FiberMap, interrupting it if it exists.
  *
  * **Example** (Removing a fiber)
  *
@@ -1014,7 +1014,7 @@ export const has: {
  */
 export const remove: {
   /**
-   * Remove a fiber from the FiberMap, interrupting it if it exists.
+   * Removes a fiber from the FiberMap, interrupting it if it exists.
    *
    * **Example** (Removing a fiber)
    *
@@ -1042,7 +1042,7 @@ export const remove: {
    */
   <K>(key: K): <A, E>(self: FiberMap<K, A, E>) => Effect.Effect<void>
   /**
-   * Remove a fiber from the FiberMap, interrupting it if it exists.
+   * Removes a fiber from the FiberMap, interrupting it if it exists.
    *
    * **Example** (Removing a fiber)
    *
@@ -1071,7 +1071,7 @@ export const remove: {
   <K, A, E>(self: FiberMap<K, A, E>, key: K): Effect.Effect<void>
 } = dual<
   /**
-   * Remove a fiber from the FiberMap, interrupting it if it exists.
+   * Removes a fiber from the FiberMap, interrupting it if it exists.
    *
    * **Example** (Removing a fiber)
    *
@@ -1099,7 +1099,7 @@ export const remove: {
    */
   <K>(key: K) => <A, E>(self: FiberMap<K, A, E>) => Effect.Effect<void>,
   /**
-   * Remove a fiber from the FiberMap, interrupting it if it exists.
+   * Removes a fiber from the FiberMap, interrupting it if it exists.
    *
    * **Example** (Removing a fiber)
    *
@@ -1139,7 +1139,7 @@ export const remove: {
   }))
 
 /**
- * Remove all fibers from the FiberMap, interrupting them.
+ * Removes all fibers from the FiberMap, interrupting them.
  *
  * **Example** (Clearing all fibers)
  *
@@ -1482,7 +1482,7 @@ export const runtimePromise = <K, A, E>(self: FiberMap<K, A, E>): <R = never>()
   )
 
 /**
- * Get the number of fibers currently in the FiberMap.
+ * Gets the number of fibers currently in the FiberMap.
  *
  * **Example** (Checking the map size)
  *
@@ -1539,7 +1539,7 @@ export const join = <K, A, E>(self: FiberMap<K, A, E>): Effect.Effect<void, E> =
   Deferred.await(self.deferred as Deferred.Deferred<void, E>)
 
 /**
- * Wait for the FiberMap to be empty.
+ * Waits for the FiberMap to be empty.
  * This will wait for all currently running fibers to complete.
  *
  * **Example** (Waiting for an empty map)

package/src/FiberSet.ts

@@ -93,7 +93,7 @@ export interface FiberSet<out A = unknown, out E = unknown>
 }
 
 /**
- * Checks if a value is a FiberSet.
+ * Checks whether a value is a FiberSet.
  *
  * **Example** (Checking if a value is a FiberSet)
  *
@@ -417,7 +417,7 @@ export const addUnsafe: {
 })
 
 /**
- * Add a fiber to the FiberSet. When the fiber completes, it will be removed.
+ * Adds a fiber to the FiberSet. When the fiber completes, it will be removed.
  *
  * **Example** (Adding a fiber)
  *
@@ -441,7 +441,7 @@ export const addUnsafe: {
  */
 export const add: {
   /**
-   * Add a fiber to the FiberSet. When the fiber completes, it will be removed.
+   * Adds a fiber to the FiberSet. When the fiber completes, it will be removed.
    *
    * **Example** (Adding a fiber)
    *
@@ -470,7 +470,7 @@ export const add: {
     } | undefined
   ): (self: FiberSet<A, E>) => Effect.Effect<void>
   /**
-   * Add a fiber to the FiberSet. When the fiber completes, it will be removed.
+   * Adds a fiber to the FiberSet. When the fiber completes, it will be removed.
    *
    * **Example** (Adding a fiber)
    *
@@ -511,7 +511,7 @@ export const add: {
 )
 
 /**
- * Interrupt all fibers in the FiberSet and clear the set.
+ * Interrupts all fibers in the `FiberSet` and clears the set.
  *
  * **Example** (Clearing all fibers)
  *
@@ -556,7 +556,7 @@ const constInterruptedFiber = (function() {
 })()
 
 /**
- * Fork an Effect and add the forked fiber to the FiberSet.
+ * Forks an Effect and add the forked fiber to the FiberSet.
  * When the fiber completes, it will be removed from the FiberSet.
  *
  * **Example** (Forking effects into a set)
@@ -584,7 +584,7 @@ const constInterruptedFiber = (function() {
  */
 export const run: {
   /**
-   * Fork an Effect and add the forked fiber to the FiberSet.
+   * Forks an Effect and add the forked fiber to the FiberSet.
    * When the fiber completes, it will be removed from the FiberSet.
    *
    * **Example** (Forking effects into a set)
@@ -620,7 +620,7 @@ export const run: {
     effect: Effect.Effect<XA, XE, R>
   ) => Effect.Effect<Fiber.Fiber<XA, XE>, never, R>
   /**
-   * Fork an Effect and add the forked fiber to the FiberSet.
+   * Forks an Effect and add the forked fiber to the FiberSet.
    * When the fiber completes, it will be removed from the FiberSet.
    *
    * **Example** (Forking effects into a set)
@@ -680,7 +680,7 @@ const runImpl = <A, E, R, XE extends E, XA extends A>(
   })
 
 /**
- * Capture a Runtime and use it to fork Effect's, adding the forked fibers to the FiberSet.
+ * Captures a `Runtime` and uses it to fork effects into the `FiberSet`.
  *
  * **Example** (Capturing a runtime)
  *
@@ -741,7 +741,13 @@ export const runtime: <A, E>(
   )
 
 /**
- * Captures a Runtime and uses it to fork Effects into the `FiberSet`.
+ * Captures a `Runtime` and returns a Promise-based runner that forks effects
+ * into the `FiberSet`.
+ *
+ * **When to use**
+ *
+ * Use when you need to bridge effects to `Promise` values while still tracking
+ * their fibers in a `FiberSet`.
  *
  * **Details**
  *
@@ -767,6 +773,8 @@ export const runtime: <A, E>(
  * })
  * ```
  *
+ * @see {@link runtime} for a runner that returns the forked `Fiber`
+ *
  * @category combinators
  * @since 3.13.0
  */
@@ -802,7 +810,7 @@ export const runtimePromise = <A, E>(self: FiberSet<A, E>): <R = never>() => Eff
   )
 
 /**
- * Get the number of fibers currently in the FiberSet.
+ * Gets the number of fibers currently in the FiberSet.
  *
  * **Example** (Checking the set size)
  *
@@ -829,7 +837,7 @@ export const size = <A, E>(self: FiberSet<A, E>): Effect.Effect<number> =>
   Effect.sync(() => self.state._tag === "Closed" ? 0 : self.state.backing.size)
 
 /**
- * Join all fibers in the FiberSet. If any of the Fiber's in the set terminate with a failure,
+ * Joins all fibers in the FiberSet. If any fiber in the set terminates with a failure,
  * the returned Effect will terminate with the first failure that occurred.
  *
  * **Example** (Joining failing fibers)
@@ -853,7 +861,7 @@ export const join = <A, E>(self: FiberSet<A, E>): Effect.Effect<void, E> =>
   Deferred.await(self.deferred as Deferred.Deferred<void, E>)
 
 /**
- * Wait until the fiber set is empty.
+ * Waits until the fiber set is empty.
  *
  * **Example** (Waiting for an empty set)
  *

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, 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.
  *
- *   // Create a directory
- *   yield* fs.makeDirectory("./temp", { recursive: true })
+ * **Example** (Write and clean up a temporary file)
  *
- *   // Write a file
- *   yield* fs.writeFileString("./temp/hello.txt", "Hello, World!")
+ * ```ts
+ * import { Effect, FileSystem } from "effect"
  *
- *   // Read the file back
- *   const content = yield* fs.readFileString("./temp/hello.txt")
- *   yield* Console.log("File content:", content)
+ * 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"
@@ -96,7 +113,7 @@ export interface FileSystem {
   readonly [TypeId]: typeof TypeId
 
   /**
-   * Check if a file can be accessed.
+   * Checks whether a file can be accessed.
    * You can optionally specify the level of access to check for.
    */
   readonly access: (
@@ -145,7 +162,7 @@ export interface FileSystem {
     gid: number
   ) => Effect.Effect<void, PlatformError>
   /**
-   * Check if a path exists.
+   * Checks whether a path exists.
    */
   readonly exists: (
     path: string
@@ -720,12 +737,16 @@ export type OpenFlag =
   | "ax+"
 
 /**
- * The service identifier for the FileSystem service.
+ * Service tag for platform file-system operations.
+ *
+ * **When to use**
+ *
+ * Use to access or provide operations for files, directories, permissions,
+ * streams, and sinks through the Effect context.
  *
  * **Details**
  *
  * This key is used to provide and access the FileSystem service in the Effect context.
- * Use this to inject file system implementations or access file system operations.
  *
  * **Example** (Accessing and providing FileSystem)
  *
@@ -757,7 +778,7 @@ export type OpenFlag =
  * )
  * ```
  *
- * @category tag
+ * @category tags
  * @since 4.0.0
  */
 export const FileSystem: Context.Service<FileSystem, FileSystem> = Context.Service("effect/platform/FileSystem")
@@ -765,12 +786,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 +1074,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.
  *
- * @category File
+ * **Details**
+ *
+ * This marker is part of the runtime representation of file handles. Prefer
+ * `isFile` when narrowing unknown values.
+ *
+ * @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 type IDs
  * @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 +1271,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 +1297,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 +1318,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