effect 3.9.2 → 3.10.0

package/dist/cjs/internal/version.js

@@ -4,7 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.setCurrentVersion = exports.getCurrentVersion = void 0;
-let moduleVersion = "3.9.2";
+let moduleVersion = "3.10.0";
 const getCurrentVersion = () => moduleVersion;
 exports.getCurrentVersion = getCurrentVersion;
 const setCurrentVersion = version => {

package/dist/cjs/internal/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","names":["moduleVersion","getCurrentVersion","exports","setCurrentVersion","version"],"sources":["../../../src/internal/version.ts"],"sourcesContent":[null],"mappings":";;;;;;AAAA,IAAIA,aAAa,GAAG,OAAO;AAEpB,MAAMC,iBAAiB,GAAGA,CAAA,KAAMD,aAAa;AAAAE,OAAA,CAAAD,iBAAA,GAAAA,iBAAA;AAE7C,MAAME,iBAAiB,GAAIC,OAAe,IAAI;EACnDJ,aAAa,GAAGI,OAAO;AACzB,CAAC;AAAAF,OAAA,CAAAC,iBAAA,GAAAA,iBAAA","ignoreList":[]}
+{"version":3,"file":"version.js","names":["moduleVersion","getCurrentVersion","exports","setCurrentVersion","version"],"sources":["../../../src/internal/version.ts"],"sourcesContent":[null],"mappings":";;;;;;AAAA,IAAIA,aAAa,GAAG,QAAQ;AAErB,MAAMC,iBAAiB,GAAGA,CAAA,KAAMD,aAAa;AAAAE,OAAA,CAAAD,iBAAA,GAAAA,iBAAA;AAE7C,MAAME,iBAAiB,GAAIC,OAAe,IAAI;EACnDJ,aAAa,GAAGI,OAAO;AACzB,CAAC;AAAAF,OAAA,CAAAC,iBAAA,GAAAA,iBAAA","ignoreList":[]}

package/dist/dts/Arbitrary.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @since 3.10.0
+ */
+import * as FastCheck from "./FastCheck.js";
+import type * as Schema from "./Schema.js";
+/**
+ * @category model
+ * @since 3.10.0
+ */
+export interface LazyArbitrary<A> {
+    (fc: typeof FastCheck): FastCheck.Arbitrary<A>;
+}
+/**
+ * @category annotations
+ * @since 3.10.0
+ */
+export interface ArbitraryGenerationContext {
+    readonly depthIdentifier?: string;
+    readonly maxDepth: number;
+}
+/**
+ * @category annotations
+ * @since 3.10.0
+ */
+export type ArbitraryAnnotation<A, TypeParameters extends ReadonlyArray<any> = readonly []> = (...arbitraries: [
+    ...{
+        readonly [K in keyof TypeParameters]: LazyArbitrary<TypeParameters[K]>;
+    },
+    ctx: ArbitraryGenerationContext
+]) => LazyArbitrary<A>;
+/**
+ * Returns a LazyArbitrary for the `A` type of the provided schema.
+ *
+ * @category arbitrary
+ * @since 3.10.0
+ */
+export declare const makeLazy: <A, I, R>(schema: Schema.Schema<A, I, R>) => LazyArbitrary<A>;
+/**
+ * Returns a fast-check Arbitrary for the `A` type of the provided schema.
+ *
+ * @category arbitrary
+ * @since 3.10.0
+ */
+export declare const make: <A, I, R>(schema: Schema.Schema<A, I, R>) => FastCheck.Arbitrary<A>;
+//# sourceMappingURL=Arbitrary.d.ts.map

package/dist/dts/Arbitrary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Arbitrary.d.ts","sourceRoot":"","sources":["../../src/Arbitrary.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAM3C,OAAO,KAAK,KAAK,MAAM,MAAM,aAAa,CAAA;AAG1C;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,CAAC,EAAE,EAAE,OAAO,SAAS,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;CAC/C;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,EAAE,cAAc,SAAS,aAAa,CAAC,GAAG,CAAC,GAAG,SAAS,EAAE,IAAI,CAC5F,GAAG,WAAW,EAAE;IACd,GAAG;QAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,cAAc,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;KAAE;IAC7E,GAAG,EAAE,0BAA0B;CAChC,KACE,aAAa,CAAC,CAAC,CAAC,CAAA;AAErB;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,UAAU,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,aAAa,CAAC,CAAC,CAC7C,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,UAAU,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,SAAS,CAAC,SAAS,CAAC,CAAC,CAAgC,CAAA"}

package/dist/dts/Effect.d.ts

@@ -1390,25 +1390,45 @@ export declare const validateFirst: {
     } | undefined): Effect<B, Array<E>, R>;
 };
 /**
- * Imports an asynchronous side-effect into a pure `Effect` value. The callback
- * function `Effect<A, E, R> => void` **MUST** be called at most once.
+ * Creates an `Effect` from a callback-based asynchronous API.
  *
- * The registration function can optionally return an Effect, which will be
- * executed if the `Fiber` executing this Effect is interrupted.
+ * Useful for integrating Node.js-style callback functions into the Effect system.
  *
- * The registration function can also receive an `AbortSignal` if required for
+ * The `resume` function **MUST** be called at most once.
+ *
+ * The `resume` function can optionally return an `Effect`, which will be
+ * executed if the `Fiber` executing this `Effect` is interrupted.
+ *
+ * The `resume` function can also receive an `AbortSignal` if required for
  * interruption.
  *
  * The `FiberId` of the fiber that may complete the async callback may also be
  * specified. This is called the "blocking fiber" because it suspends the fiber
- * executing the `async` Effect (i.e. semantically blocks the fiber from making
+ * executing the `async` effect (i.e. semantically blocks the fiber from making
  * progress). Specifying this fiber id in cases where it is known will improve
  * diagnostics, but not affect the behavior of the returned effect.
  *
+ * @example
+ * import { Effect } from "effect"
+ * import * as fs from "fs"
+ *
+ * // Wrapping a callback-based API using Effect.async
+ * const readFile = (filename: string) => Effect.async<Buffer, Error>((resume) => {
+ *   fs.readFile(filename, (error, data) => {
+ *     if (error) {
+ *       resume(Effect.fail(error))
+ *     } else {
+ *       resume(Effect.succeed(data))
+ *     }
+ *   });
+ * });
+ *
+ * const program = readFile("todos.txt")
+ *
  * @since 2.0.0
  * @category constructors
  */
-export declare const async: <A, E = never, R = never>(register: (callback: (_: Effect<A, E, R>) => void, signal: AbortSignal) => void | Effect<void, never, R>, blockingOn?: FiberId.FiberId) => Effect<A, E, R>;
+export declare const async: <A, E = never, R = never>(resume: (callback: (_: Effect<A, E, R>) => void, signal: AbortSignal) => void | Effect<void, never, R>, blockingOn?: FiberId.FiberId) => Effect<A, E, R>;
 /**
  * Converts an asynchronous, callback-style API into an `Effect`, which will
  * be executed asynchronously.
@@ -1503,6 +1523,29 @@ export declare const custom: {
  */
 export declare const withFiberRuntime: <A, E = never, R = never>(withRuntime: (fiber: Fiber.RuntimeFiber<A, E>, status: FiberStatus.Running) => Effect<A, E, R>) => Effect<A, E, R>;
 /**
+ * Creates an `Effect` that represents a recoverable error.
+ *
+ * This `Effect` does not succeed but instead fails with the provided error. The
+ * failure can be of any type, and will propagate through the effect pipeline
+ * unless handled.
+ *
+ * Use this function when you want to explicitly signal an error in an `Effect`
+ * computation. The failed effect can later be handled with functions like
+ * {@link catchAll} or {@link catchTag}.
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * // Example of creating a failed effect
+ * const failedEffect = Effect.fail("Something went wrong")
+ *
+ * // Handle the failure
+ * failedEffect.pipe(
+ *   Effect.catchAll((error) => Effect.succeed(`Recovered from: ${error}`)),
+ *   Effect.runPromise
+ * ).then(console.log)
+ * // Output: "Recovered from: Something went wrong"
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -1608,16 +1651,40 @@ export declare const never: Effect<never>;
  */
 export declare const none: <A, E, R>(self: Effect<Option.Option<A>, E, R>) => Effect<void, E | Cause.NoSuchElementException, R>;
 /**
- * Like `tryPromise` but produces a defect in case of errors.
+ * Creates an `Effect` that represents an asynchronous computation guaranteed to succeed.
+ *
+ * The provided function (`thunk`) returns a `Promise` that should never reject.
+ * If the `Promise` does reject, the rejection is treated as a defect.
  *
  * An optional `AbortSignal` can be provided to allow for interruption of the
- * wrapped Promise api.
+ * wrapped `Promise` API.
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * // Creating an effect that resolves after a delay
+ * const delay = (message: string) => Effect.promise(() => new Promise((resolve) => {
+ *   setTimeout(() => resolve(message), 2000)
+ * }))
+ *
+ * const program = delay("Async operation completed successfully!")
  *
  * @since 2.0.0
  * @category constructors
  */
 export declare const promise: <A>(evaluate: (signal: AbortSignal) => PromiseLike<A>) => Effect<A>;
 /**
+ * Creates an `Effect` that succeeds with the provided value.
+ *
+ * Use this function to represent a successful computation that yields a value of type `A`.
+ * The effect does not fail and does not require any environmental context.
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * // Creating an effect that succeeds with the number 42
+ * const success = Effect.succeed(42)
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -1637,15 +1704,49 @@ export declare const succeedNone: Effect<Option.Option<never>>;
  */
 export declare const succeedSome: <A>(value: A) => Effect<Option.Option<A>>;
 /**
+ * Creates an `Effect` that defers the creation of another effect until it is needed.
+ *
+ * Useful for lazy evaluation, handling circular dependencies, or avoiding eager execution in recursive functions.
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * // Handling recursion without stack overflow
+ * const fibonacci = (n: number): Effect.Effect<number> =>
+ *   n < 2
+ *     ? Effect.succeed(1)
+ *     : Effect.zipWith(
+ *         Effect.suspend(() => fibonacci(n - 1)),
+ *         Effect.suspend(() => fibonacci(n - 2)),
+ *         (a, b) => a + b
+ *       )
+ *
+ * console.log(Effect.runSync(fibonacci(10))) // Output: 89
+ *
  * @since 2.0.0
  * @category constructors
  */
 export declare const suspend: <A, E, R>(effect: LazyArg<Effect<A, E, R>>) => Effect<A, E, R>;
 /**
+ * Creates an `Effect` that represents a synchronous side-effectful computation.
+ *
+ * The provided function (`thunk`) should not throw errors; if it does, the error is treated as a defect.
+ * Use `Effect.sync` when you are certain the operation will not fail.
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * // Creating an effect that logs a message
+ * const log = (message: string) => Effect.sync(() => {
+ *   console.log(message) // side effect
+ * })
+ *
+ * const program = log("Hello, World!")
+ *
  * @since 2.0.0
  * @category constructors
  */
-export declare const sync: <A>(evaluate: LazyArg<A>) => Effect<A>;
+export declare const sync: <A>(thunk: LazyArg<A>) => Effect<A>;
 declare const _void: Effect<void>;
 export { 
 /**
@@ -2147,12 +2248,19 @@ declare const try_: {
         readonly try: LazyArg<A>;
         readonly catch: (error: unknown) => E;
     }): Effect<A, E>;
-    <A>(evaluate: LazyArg<A>): Effect<A, Cause.UnknownException>;
+    <A>(thunk: LazyArg<A>): Effect<A, Cause.UnknownException>;
 };
 export { 
 /**
- * Imports a synchronous side-effect into a pure `Effect` value, translating any
- * thrown exceptions into typed failed effects creating with `Effect.fail`.
+ * Creates an `Effect` that represents a synchronous computation that might fail.
+ *
+ * If the function (`thunk`) throws an error, it is caught and the effect fails with an `UnknownException`.
+ *
+ * **Overload with custom error handling:**
+ *
+ * Creates an `Effect` that represents a synchronous computation that might fail, with custom error mapping.
+ *
+ * If the `try` function throws an error, the `catch` function maps it to an error of type `E`.
  *
  * @since 2.0.0
  * @category error handling
@@ -2198,7 +2306,7 @@ export declare const tryMap: {
  * via the `catch` function.
  *
  * An optional `AbortSignal` can be provided to allow for interruption of the
- * wrapped Promise api.
+ * wrapped `Promise` API.
  *
  * @since 2.0.0
  * @category error handling
@@ -2210,7 +2318,7 @@ export declare const tryMapPromise: {
      * via the `catch` function.
      *
      * An optional `AbortSignal` can be provided to allow for interruption of the
-     * wrapped Promise api.
+     * wrapped `Promise` API.
      *
      * @since 2.0.0
      * @category error handling
@@ -2225,7 +2333,7 @@ export declare const tryMapPromise: {
      * via the `catch` function.
      *
      * An optional `AbortSignal` can be provided to allow for interruption of the
-     * wrapped Promise api.
+     * wrapped `Promise` API.
      *
      * @since 2.0.0
      * @category error handling
@@ -2236,22 +2344,52 @@ export declare const tryMapPromise: {
     }): Effect<B, E | E1, R>;
 };
 /**
- * Create an `Effect` that when executed will construct `promise` and wait for
- * its result, errors will produce failure as `unknown`.
+ * Creates an `Effect` that represents an asynchronous computation that might fail.
+ *
+ * If the `Promise` returned by `evaluate` rejects, the error is caught and the effect fails with an `UnknownException`.
  *
  * An optional `AbortSignal` can be provided to allow for interruption of the
- * wrapped Promise api.
+ * wrapped `Promise` API.
+ *
+ * **Overload with custom error handling:**
+ *
+ * Creates an `Effect` that represents an asynchronous computation that might fail, with custom error mapping.
+ *
+ * If the `Promise` rejects, the `catch` function maps the error to an error of type `E`.
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * // Fetching data from an API that may fail
+ * const getTodo = (id: number) => Effect.tryPromise(() =>
+ *   fetch(`https://jsonplaceholder.typicode.com/todos/${id}`)
+ * )
  *
  * @since 2.0.0
  * @category error handling
  */
 export declare const tryPromise: {
     /**
-     * Create an `Effect` that when executed will construct `promise` and wait for
-     * its result, errors will produce failure as `unknown`.
+     * Creates an `Effect` that represents an asynchronous computation that might fail.
+     *
+     * If the `Promise` returned by `evaluate` rejects, the error is caught and the effect fails with an `UnknownException`.
      *
      * An optional `AbortSignal` can be provided to allow for interruption of the
-     * wrapped Promise api.
+     * wrapped `Promise` API.
+     *
+     * **Overload with custom error handling:**
+     *
+     * Creates an `Effect` that represents an asynchronous computation that might fail, with custom error mapping.
+     *
+     * If the `Promise` rejects, the `catch` function maps the error to an error of type `E`.
+     *
+     * @example
+     * import { Effect } from "effect"
+     *
+     * // Fetching data from an API that may fail
+     * const getTodo = (id: number) => Effect.tryPromise(() =>
+     *   fetch(`https://jsonplaceholder.typicode.com/todos/${id}`)
+     * )
      *
      * @since 2.0.0
      * @category error handling
@@ -2261,16 +2399,31 @@ export declare const tryPromise: {
         readonly catch: (error: unknown) => E;
     }): Effect<A, E>;
     /**
-     * Create an `Effect` that when executed will construct `promise` and wait for
-     * its result, errors will produce failure as `unknown`.
+     * Creates an `Effect` that represents an asynchronous computation that might fail.
+     *
+     * If the `Promise` returned by `evaluate` rejects, the error is caught and the effect fails with an `UnknownException`.
      *
      * An optional `AbortSignal` can be provided to allow for interruption of the
-     * wrapped Promise api.
+     * wrapped `Promise` API.
+     *
+     * **Overload with custom error handling:**
+     *
+     * Creates an `Effect` that represents an asynchronous computation that might fail, with custom error mapping.
+     *
+     * If the `Promise` rejects, the `catch` function maps the error to an error of type `E`.
+     *
+     * @example
+     * import { Effect } from "effect"
+     *
+     * // Fetching data from an API that may fail
+     * const getTodo = (id: number) => Effect.tryPromise(() =>
+     *   fetch(`https://jsonplaceholder.typicode.com/todos/${id}`)
+     * )
      *
      * @since 2.0.0
      * @category error handling
      */
-    <A>(try_: (signal: AbortSignal) => PromiseLike<A>): Effect<A, Cause.UnknownException>;
+    <A>(evaluate: (signal: AbortSignal) => PromiseLike<A>): Effect<A, Cause.UnknownException>;
 };
 /**
  * The inverse operation `sandbox(effect)`
@@ -7840,6 +7993,28 @@ export declare const unsafeMakeLatch: (open?: boolean | undefined) => Latch;
  */
 export declare const makeLatch: (open?: boolean | undefined) => Effect<Latch, never, never>;
 /**
+ * Executes an effect and returns a `RuntimeFiber` that represents the running computation.
+ *
+ * Use `runFork` when you want to start an effect without blocking the current execution flow.
+ * It returns a fiber that you can observe, interrupt, or join as needed.
+ *
+ * @example
+ * import { Effect, Console, Schedule, Fiber } from "effect"
+ *
+ * // Define an effect that repeats a message every 200 milliseconds
+ * const program = Effect.repeat(
+ *   Console.log("running..."),
+ *   Schedule.spaced("200 millis")
+ * )
+ *
+ * // Start the effect without blocking
+ * const fiber = Effect.runFork(program)
+ *
+ * // Interrupt the fiber after 500 milliseconds
+ * setTimeout(() => {
+ *   Effect.runFork(Fiber.interrupt(fiber))
+ * }, 500)
+ *
  * @since 2.0.0
  * @category execution
  */
@@ -7850,8 +8025,21 @@ export declare const runFork: <A, E>(effect: Effect<A, E>, options?: Runtime.Run
  */
 export declare const runCallback: <A, E>(effect: Effect<A, E>, options?: Runtime.RunCallbackOptions<A, E> | undefined) => Runtime.Cancel<A, E>;
 /**
- * Runs an `Effect` workflow, returning a `Promise` which resolves with the
- * result of the workflow or rejects with an error.
+ * Executes an effect and returns a `Promise` that resolves with the result.
+ *
+ * Use `runPromise` when working with asynchronous effects and you need to integrate with code that uses Promises.
+ * If the effect fails, the returned Promise will be rejected with the error.
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * // Execute an effect and handle the result with a Promise
+ * Effect.runPromise(Effect.succeed(1)).then(console.log) // Output: 1
+ *
+ * // Execute a failing effect and handle the rejection
+ * Effect.runPromise(Effect.fail("my error")).catch((error) => {
+ *   console.error("Effect failed with error:", error)
+ * })
  *
  * @since 2.0.0
  * @category execution
@@ -7860,8 +8048,35 @@ export declare const runPromise: <A, E>(effect: Effect<A, E, never>, options?: {
     readonly signal?: AbortSignal;
 } | undefined) => Promise<A>;
 /**
- * Runs an `Effect` workflow, returning a `Promise` which resolves with the
- * `Exit` value of the workflow.
+ * Executes an effect and returns a `Promise` that resolves with an `Exit` describing the result.
+ *
+ * Use `runPromiseExit` when you need detailed information about the outcome of the effect, including success or failure,
+ * and you want to work with Promises.
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * // Execute a successful effect and get the Exit result as a Promise
+ * Effect.runPromiseExit(Effect.succeed(1)).then(console.log)
+ * // Output:
+ * // {
+ * //   _id: "Exit",
+ * //   _tag: "Success",
+ * //   value: 1
+ * // }
+ *
+ * // Execute a failing effect and get the Exit result as a Promise
+ * Effect.runPromiseExit(Effect.fail("my error")).then(console.log)
+ * // Output:
+ * // {
+ * //   _id: "Exit",
+ * //   _tag: "Failure",
+ * //   cause: {
+ * //     _id: "Cause",
+ * //     _tag: "Fail",
+ * //     failure: "my error"
+ * //   }
+ * // }
  *
  * @since 2.0.0
  * @category execution
@@ -7870,11 +8085,64 @@ export declare const runPromiseExit: <A, E>(effect: Effect<A, E, never>, options
     readonly signal?: AbortSignal;
 } | undefined) => Promise<Exit.Exit<A, E>>;
 /**
+ * Executes an effect synchronously and returns its result.
+ *
+ * Use `runSync` when you are certain that the effect is purely synchronous and will not perform any asynchronous operations.
+ * If the effect fails or contains asynchronous tasks, it will throw an error.
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * // Define a synchronous effect
+ * const program = Effect.sync(() => {
+ *   console.log("Hello, World!")
+ *   return 1
+ * })
+ *
+ * // Execute the effect synchronously
+ * const result = Effect.runSync(program)
+ * // Output: Hello, World!
+ *
+ * console.log(result)
+ * // Output: 1
+ *
  * @since 2.0.0
  * @category execution
  */
 export declare const runSync: <A, E>(effect: Effect<A, E>) => A;
 /**
+ * Executes an effect synchronously and returns an `Exit` describing the result.
+ *
+ * Use `runSyncExit` when you need detailed information about the outcome of the effect,
+ * including whether it succeeded or failed, without throwing exceptions.
+ *
+ * @example
+ * import { Effect } from "effect"
+ *
+ * // Execute a successful effect and get the Exit result
+ * const result1 = Effect.runSyncExit(Effect.succeed(1))
+ * console.log(result1)
+ * // Output:
+ * // {
+ * //   _id: "Exit",
+ * //   _tag: "Success",
+ * //   value: 1
+ * // }
+ *
+ * // Execute a failing effect and get the Exit result
+ * const result2 = Effect.runSyncExit(Effect.fail("my error"))
+ * console.log(result2)
+ * // Output:
+ * // {
+ * //   _id: "Exit",
+ * //   _tag: "Failure",
+ * //   cause: {
+ * //     _id: "Cause",
+ * //     _tag: "Fail",
+ * //     failure: "my error"
+ * //   }
+ * // }
+ *
  * @since 2.0.0
  * @category execution
  */