effect 4.0.1 → 4.0.3

package/src/FiberMap.ts

@@ -7,6 +7,7 @@
  * interrupt background work by a stable key while keeping all fibers tied to
  * one scope.
  *
+ * @stability stable
  * @since 2.0.0
  */
 import * as Cause from "./Cause.ts"
@@ -54,6 +55,7 @@ const TypeId = "~effect/FiberMap"
  * actual // => 2
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -92,6 +94,7 @@ export interface FiberMap<in out K, out A = unknown, out E = unknown>
  * actual // => [true, false, false]
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 2.0.0
  */
@@ -156,6 +159,7 @@ const makeUnsafe = <K, A = unknown, E = unknown>(
  * actual // => 2
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -208,6 +212,7 @@ export const make = <K, A = unknown, E = unknown>(): Effect.Effect<FiberMap<K, A
  * actual // => ["Hello", "World"]
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -265,6 +270,7 @@ export const makeRuntime = <R, K, E = unknown, A = unknown>(): Effect.Effect<
  * actual // => ["Hello", "World"]
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 3.13.0
  */
@@ -331,6 +337,7 @@ const isInternalInterruption = Filter.toPredicate(Filter.compose(
  * actual // => "Hello"
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -374,6 +381,7 @@ export const setUnsafe: {
    * actual // => "Hello"
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -424,6 +432,7 @@ export const setUnsafe: {
    * actual // => "Hello"
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -521,6 +530,7 @@ export const setUnsafe: {
  * actual // => "Hello"
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -560,6 +570,7 @@ export const set: {
    * actual // => "Hello"
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -606,6 +617,7 @@ export const set: {
    * actual // => "Hello"
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -660,6 +672,7 @@ export const set: {
  * actual // => Option.some("Hello")
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -696,6 +709,7 @@ export const getUnsafe: {
    * actual // => Option.some("Hello")
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -732,6 +746,7 @@ export const getUnsafe: {
    * actual // => Option.some("Hello")
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -774,6 +789,7 @@ export const getUnsafe: {
  * actual // => Option.some("Hello")
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -809,6 +825,7 @@ export const get: {
    * actual // => Option.some("Hello")
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -844,6 +861,7 @@ export const get: {
    * actual // => Option.some("Hello")
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -876,6 +894,7 @@ export const get: {
  * actual // => [true, false]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -902,6 +921,7 @@ export const hasUnsafe: {
    * actual // => [true, false]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -928,6 +948,7 @@ export const hasUnsafe: {
    * actual // => [true, false]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -961,6 +982,7 @@ export const hasUnsafe: {
  * actual // => [true, false]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -988,6 +1010,7 @@ export const has: {
    * actual // => [true, false]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -1015,6 +1038,7 @@ export const has: {
    * actual // => [true, false]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -1051,6 +1075,7 @@ export const has: {
  * actual // => [2, 1]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -1082,6 +1107,7 @@ export const remove: {
    * actual // => [2, 1]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -1113,6 +1139,7 @@ export const remove: {
    * actual // => [2, 1]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -1145,6 +1172,7 @@ export const remove: {
    * actual // => [2, 1]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -1176,6 +1204,7 @@ export const remove: {
    * actual // => [2, 1]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -1220,6 +1249,7 @@ export const remove: {
  * actual // => [3, 0]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -1273,6 +1303,7 @@ const constInterruptedFiber = (function() {
  * actual // => ["Hello", "World", 0]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -1309,6 +1340,7 @@ export const run: {
    * actual // => ["Hello", "World", 0]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -1355,6 +1387,7 @@ export const run: {
    * actual // => ["Hello", "World", 0]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -1440,6 +1473,7 @@ const runImpl = <K, A, E, R, XE extends E, XA extends A>(
  * actual // => [0, 0]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -1517,6 +1551,7 @@ export const runtime: <K, A, E>(
  * actual // => ["Hello", "World"]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 3.13.0
  */
@@ -1580,6 +1615,7 @@ export const runtimePromise = <K, A, E>(self: FiberMap<K, A, E>): <R = never>()
  * actual // => [0, 2]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -1613,6 +1649,7 @@ export const size = <K, A, E>(self: FiberMap<K, A, E>): Effect.Effect<number> =>
  * actual // => Exit.fail("error")
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -1644,6 +1681,7 @@ export const join = <K, A, E>(self: FiberMap<K, A, E>): Effect.Effect<void, E> =
  * actual // => 0
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 3.13.0
  */

package/src/FiberSet.ts

@@ -6,6 +6,7 @@
  * closes. This module includes scoped runtime constructors plus helpers for
  * adding, clearing, running, counting, joining, and waiting for managed fibers.
  *
+ * @stability stable
  * @since 2.0.0
  */
 import * as Cause from "./Cause.ts"
@@ -50,6 +51,7 @@ const TypeId = "~effect/FiberSet"
  * actual // => 0
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -84,6 +86,7 @@ export interface FiberSet<out A = unknown, out E = unknown>
  * actual // => [true, false]
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 2.0.0
  */
@@ -148,6 +151,7 @@ const makeUnsafe = <A, E>(
  * actual // => 2
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -193,6 +197,7 @@ export const make = <A = unknown, E = unknown>(): Effect.Effect<FiberSet<A, E>,
  * actual // => ["hello", "world"]
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -243,6 +248,7 @@ export const makeRuntime = <R = never, A = unknown, E = unknown>(): Effect.Effec
  * actual // => ["hello", "world"]
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 3.13.0
  */
@@ -300,6 +306,7 @@ const isInternalInterruption = Filter.toPredicate(Filter.compose(
  * actual // => 1
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -339,6 +346,7 @@ export const addUnsafe: {
    * actual // => 1
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -383,6 +391,7 @@ export const addUnsafe: {
    * actual // => 1
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -448,6 +457,7 @@ export const addUnsafe: {
  * actual // => 1
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -475,6 +485,7 @@ export const add: {
    * actual // => 1
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -507,6 +518,7 @@ export const add: {
    * actual // => 1
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -555,6 +567,7 @@ export const add: {
  * actual // => [2, 0]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -601,6 +614,7 @@ const constInterruptedFiber = (function() {
  * actual // => ["hello", "world"]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -630,6 +644,7 @@ export const run: {
    * actual // => ["hello", "world"]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -667,6 +682,7 @@ export const run: {
    * actual // => ["hello", "world"]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -738,6 +754,7 @@ const runImpl = <A, E, R, XE extends E, XA extends A>(
  * actual // => 0
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -808,6 +825,7 @@ export const runtime: <A, E>(
  *
  * @see {@link runtime} for a runner that returns the forked `Fiber`
  *
+ * @stability stable
  * @category combinators
  * @since 3.13.0
  */
@@ -866,6 +884,7 @@ export const runtimePromise = <A, E>(self: FiberSet<A, E>): <R = never>() => Eff
  * actual // => [0, 2]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -893,6 +912,7 @@ export const size = <A, E>(self: FiberSet<A, E>): Effect.Effect<number> =>
  * actual // => Exit.fail("error")
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -923,6 +943,7 @@ export const join = <A, E>(self: FiberSet<A, E>): Effect.Effect<void, E> =>
  * actual // => 0
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 3.13.0
  */

package/src/FileSystem.ts

@@ -8,6 +8,7 @@
  * `PlatformError`. The module also includes file handles, open flags, watch
  * events, and the watch backend service.
  *
+ * @stability unstable
  * @since 4.0.0
  */
 import * as Arr from "./Array.ts"
@@ -72,6 +73,7 @@ const TypeId = "~effect/FileSystem"
  * result.content // => "{\"env\": \"development\"}"
  * ```
  *
+ * @stability unstable
  * @category services
  * @since 4.0.0
  */
@@ -218,12 +220,17 @@ export interface FileSystem {
    * **Details**
    *
    * The file handle will be automatically closed when the scope is closed.
+   *
+   * `noFollow` rejects symlinks at the final path component, not in parent
+   * directories. Node and Bun support it on POSIX; unsupported platforms,
+   * including Windows and Deno, fail with `BadArgument`.
    */
   readonly open: (
     path: string,
     options?: {
       readonly flag?: OpenFlag | undefined
       readonly mode?: number | undefined
+      readonly noFollow?: boolean | undefined
     }
   ) => Effect.Effect<File, PlatformError, Scope>
   /**
@@ -411,6 +418,7 @@ export interface FileSystem {
  * flags // => ["r", "w", "a", "r+"]
  * ```
  *
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */
@@ -464,6 +472,7 @@ export type OpenFlag =
  * Effect.runSync(withCustomFs) // => "contents"
  * ```
  *
+ * @stability unstable
  * @category services
  * @since 4.0.0
  */
@@ -487,6 +496,7 @@ export const FileSystem: Context.Service<FileSystem, FileSystem> = Context.Servi
  * @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
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -630,6 +640,7 @@ const notFound = (method: string, path: string) =>
  * Effect.runSync(testProgram) // => "{\"test\": true}"
  * ```
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -759,6 +770,7 @@ export const makeNoop = (fileSystem: Partial<FileSystem>): FileSystem =>
  * Effect.runSync(testProgram) // => "mocked content"
  * ```
  *
+ * @stability unstable
  * @category layers
  * @since 4.0.0
  */
@@ -777,6 +789,7 @@ export const layerNoop = (fileSystem: Partial<FileSystem>): Layer.Layer<FileSyst
  * @see {@link File} for the open file handle shape that carries this marker
  * @see {@link isFile} for the public guard that checks this marker
  *
+ * @stability unstable
  * @category type IDs
  * @since 4.0.0
  */
@@ -799,6 +812,7 @@ export const FileTypeId = "~effect/FileSystem/File"
  * @see {@link File} for the file-handle interface narrowed by this guard
  * @see {@link FileTypeId} for the runtime marker checked by this guard
  *
+ * @stability unstable
  * @category guards
  * @since 4.0.0
  */
@@ -818,6 +832,10 @@ export const isFile = (u: unknown): u is File => hasProperty(u, FileTypeId)
  * cursor. Outside append mode, `truncate` clamps a cursor past the new length
  * to that length.
  *
+ * Positional reads leave the cursor unchanged and may run concurrently on
+ * one handle. Cursor operations (`seek`, reads without a position, and writes)
+ * must not run concurrently with each other.
+ *
  * **Example** (Working with file handles)
  *
  * ```ts import.meta.vitest
@@ -853,6 +871,7 @@ export const isFile = (u: unknown): u is File => hasProperty(u, FileTypeId)
  * result.buffer // => [1, 2, 3, 4, 5]
  * ```
  *
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */
@@ -867,8 +886,20 @@ export interface File {
    */
   readonly seek: (offset: bigint, from: SeekMode) => Effect.Effect<bigint, PlatformError>
   readonly sync: Effect.Effect<void, PlatformError>
-  readonly read: (buffer: Uint8Array) => Effect.Effect<number, PlatformError>
-  readonly readAlloc: (size: number) => Effect.Effect<Option.Option<Uint8Array>, PlatformError>
+  /**
+   * Reads into `buffer`, returning the byte count or `0` at EOF. Advances the
+   * cursor unless `options.position` is set (see `File.ReadOptions`).
+   */
+  readonly read: (buffer: Uint8Array, options?: File.ReadOptions) => Effect.Effect<number, PlatformError>
+  /**
+   * Reads up to `size` bytes into a new buffer, returning `Option.none()` at
+   * EOF. Advances the cursor unless `options.position` is set (see
+   * `File.ReadOptions`).
+   */
+  readonly readAlloc: (
+    size: number,
+    options?: File.ReadOptions
+  ) => Effect.Effect<Option.Option<Uint8Array>, PlatformError>
   readonly truncate: (length?: number) => Effect.Effect<void, PlatformError>
   readonly write: (buffer: Uint8Array) => Effect.Effect<number, PlatformError>
   readonly writeAll: (buffer: Uint8Array) => Effect.Effect<void, PlatformError>
@@ -878,9 +909,35 @@ export interface File {
  * Namespace containing types associated with open file handles, including file
  * descriptors, entry kinds, and stat information.
  *
+ * @stability unstable
  * @since 4.0.0
  */
 export declare namespace File {
+  /**
+   * Options for `File.read` and `File.readAlloc`.
+   *
+   * **Details**
+   *
+   * `position` is a byte offset from the start of the file. It leaves the
+   * cursor unchanged, fails with `BadArgument` if negative, and reads nothing
+   * at or past EOF.
+   *
+   * **Example** (Reading a byte range without moving the cursor)
+   *
+   * ```ts import.meta.vitest
+   * import type { FileSystem } from "effect"
+   *
+   * const options: FileSystem.File.ReadOptions = { position: BigInt(1024) }
+   * options.position // => 1024n
+   * ```
+   *
+   * @category models
+   * @since 4.1.0
+   */
+  export interface ReadOptions {
+    readonly position?: bigint | undefined
+  }
+
   /**
    * Enumeration of possible file system entry types.
    *
@@ -986,6 +1043,7 @@ export declare namespace File {
  *
  * @see {@link File} for the open file handle API whose `seek` method consumes this mode
  *
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */
@@ -994,6 +1052,7 @@ export type SeekMode = "start" | "current"
 /**
  * Options for watching files or directories.
  *
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */
@@ -1019,6 +1078,7 @@ export interface WatchOptions {
  *
  * @see {@link FileSystem} for the service interface whose `watch` operation emits these events
  *
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */
@@ -1027,6 +1087,7 @@ export type WatchEvent = WatchEvent.Create | WatchEvent.Update | WatchEvent.Remo
 /**
  * Namespace containing the concrete event shapes emitted by `FileSystem.watch`.
  *
+ * @stability unstable
  * @since 4.0.0
  */
 export declare namespace WatchEvent {
@@ -1116,6 +1177,7 @@ export declare namespace WatchEvent {
  * Effect.runSync(withCustomBackend) // => true
  * ```
  *
+ * @stability unstable
  * @category services
  * @since 4.0.0
  */