effect 4.0.0-beta.0 → 4.0.0-beta.10

package/dist/Effect.d.ts

@@ -92,7 +92,7 @@ import type { Scope } from "./Scope.ts";
 import * as ServiceMap from "./ServiceMap.ts";
 import type { AnySpan, ParentSpan, Span, SpanLink, SpanOptions, SpanOptionsNoTrace, TraceOptions, Tracer } from "./Tracer.ts";
 import type { TxRef } from "./TxRef.ts";
-import type { Concurrency, Covariant, EqualsWith, ExcludeReason, ExcludeTag, ExtractReason, ExtractTag, NoInfer, ReasonOf, ReasonTags, Tags, unassigned } from "./Types.ts";
+import type { Concurrency, Covariant, EqualsWith, ExcludeReason, ExcludeTag, ExtractReason, ExtractTag, NoInfer, ReasonOf, ReasonTags, Simplify, Tags, unassigned } from "./Types.ts";
 import type * as Unify from "./Unify.ts";
 declare const TypeId: "~effect/Effect";
 /**
@@ -1352,6 +1352,90 @@ export declare const callback: <A, E = never, R = never>(register: (this: Schedu
  * @category Creating Effects
  */
 export declare const never: Effect<never>;
+/**
+ * An `Effect` containing an empty record `{}`, used as the starting point for
+ * do notation chains.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { pipe } from "effect/Function"
+ *
+ * const program = pipe(
+ *   Effect.Do,
+ *   Effect.bind("x", () => Effect.succeed(2)),
+ *   Effect.bind("y", ({ x }) => Effect.succeed(x + 1)),
+ *   Effect.let("sum", ({ x, y }) => x + y)
+ * )
+ * ```
+ *
+ * @since 4.0.0
+ * @category Do notation
+ */
+export declare const Do: Effect<{}>;
+/**
+ * Gives a name to the success value of an `Effect`, creating a single-key
+ * record used in do notation pipelines.
+ *
+ * @since 4.0.0
+ * @category Do notation
+ */
+export declare const bindTo: {
+    /**
+     * Gives a name to the success value of an `Effect`, creating a single-key
+     * record used in do notation pipelines.
+     *
+     * @since 4.0.0
+     * @category Do notation
+     */
+    <N extends string>(name: N): <A, E, R>(self: Effect<A, E, R>) => Effect<{
+        [K in N]: A;
+    }, E, R>;
+    /**
+     * Gives a name to the success value of an `Effect`, creating a single-key
+     * record used in do notation pipelines.
+     *
+     * @since 4.0.0
+     * @category Do notation
+     */
+    <A, E, R, N extends string>(self: Effect<A, E, R>, name: N): Effect<{
+        [K in N]: A;
+    }, E, R>;
+};
+declare const let_: {
+    <N extends string, A extends Record<string, any>, B>(name: N, f: (a: NoInfer<A>) => B): <E, R>(self: Effect<A, E, R>) => Effect<Simplify<Omit<A, N> & Record<N, B>>, E, R>;
+    <A extends Record<string, any>, E, R, B, N extends string>(self: Effect<A, E, R>, name: N, f: (a: NoInfer<A>) => B): Effect<Simplify<Omit<A, N> & Record<N, B>>, E, R>;
+};
+export { 
+/**
+ * Adds a computed plain value to the do notation record.
+ *
+ * @since 4.0.0
+ * @category Do notation
+ */
+let_ as let };
+/**
+ * Adds an `Effect` value to the do notation record under a given name.
+ *
+ * @since 4.0.0
+ * @category Do notation
+ */
+export declare const bind: {
+    /**
+     * Adds an `Effect` value to the do notation record under a given name.
+     *
+     * @since 4.0.0
+     * @category Do notation
+     */
+    <N extends string, A extends Record<string, any>, B, E2, R2>(name: N, f: (a: NoInfer<A>) => Effect<B, E2, R2>): <E, R>(self: Effect<A, E, R>) => Effect<Simplify<Omit<A, N> & Record<N, B>>, E | E2, R | R2>;
+    /**
+     * Adds an `Effect` value to the do notation record under a given name.
+     *
+     * @since 4.0.0
+     * @category Do notation
+     */
+    <A extends Record<string, any>, E, R, B, E2, R2, N extends string>(self: Effect<A, E, R>, name: N, f: (a: NoInfer<A>) => Effect<B, E2, R2>): Effect<Simplify<Omit<A, N> & Record<N, B>>, E | E2, R | R2>;
+};
 /**
  * Provides a way to write effectful code using generator functions, simplifying
  * control flow and error handling.
@@ -4704,6 +4788,33 @@ export declare const catchIf: {
      */
     <A, E, R, Result extends Filter.ResultOrBool, A2, E2, R2, A3 = never, E3 = Filter.Fail<E, Result>, R3 = never>(self: Effect<A, E, R>, filter: Filter.OrPredicate<NoInfer<E>, Result>, f: (e: Filter.Pass<E, Result>) => Effect<A2, E2, R2>, orElse?: ((e: Filter.Fail<E, Result>) => Effect<A3, E3, R3>) | undefined): Effect<A | A2 | A3, E2 | E3, R | R2 | R3>;
 };
+/**
+ * Catches `NoSuchElementError` failures and converts them to `Option.none`.
+ *
+ * Success values become `Option.some`, `NoSuchElementError` becomes
+ * `Option.none`, and all other errors are preserved.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option } from "effect"
+ *
+ * const some = Effect.fromNullishOr(1).pipe(Effect.catchNoSuchElement)
+ * const none = Effect.fromNullishOr(null).pipe(Effect.catchNoSuchElement)
+ *
+ * Effect.runPromise(some).then(console.log) // { _id: 'Option', _tag: 'Some', value: 1 }
+ * Effect.runPromise(none).then(console.log) // { _id: 'Option', _tag: 'None' }
+ * ```
+ *
+ * **Previously Known As**
+ *
+ * This API replaces the following from Effect 3.x:
+ *
+ * - `Effect.optionFromOptional`
+ *
+ * @since 2.0.0
+ * @category Error Handling
+ */
+export declare const catchNoSuchElement: <A, E, R>(self: Effect<A, E, R>) => Effect<Option<A>, Exclude<E, Cause.NoSuchElementError>, R>;
 /**
  * Recovers from specific failures based on a predicate.
  *
@@ -6665,7 +6776,7 @@ export declare const timeout: {
      * @since 2.0.0
      * @category Delays & Timeouts
      */
-    (duration: Duration.DurationInput): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E | Cause.TimeoutError, R>;
+    (duration: Duration.Input): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E | Cause.TimeoutError, R>;
     /**
      * Adds a time limit to an effect, triggering a timeout if the effect exceeds
      * the duration.
@@ -6712,7 +6823,7 @@ export declare const timeout: {
      * @since 2.0.0
      * @category Delays & Timeouts
      */
-    <A, E, R>(self: Effect<A, E, R>, duration: Duration.DurationInput): Effect<A, E | Cause.TimeoutError, R>;
+    <A, E, R>(self: Effect<A, E, R>, duration: Duration.Input): Effect<A, E | Cause.TimeoutError, R>;
 };
 /**
  * Handles timeouts by returning an `Option` that represents either the result
@@ -6813,7 +6924,7 @@ export declare const timeoutOption: {
      * @since 3.1.0
      * @category Delays & Timeouts
      */
-    (duration: Duration.DurationInput): <A, E, R>(self: Effect<A, E, R>) => Effect<Option<A>, E, R>;
+    (duration: Duration.Input): <A, E, R>(self: Effect<A, E, R>) => Effect<Option<A>, E, R>;
     /**
      * Handles timeouts by returning an `Option` that represents either the result
      * or a timeout.
@@ -6863,7 +6974,7 @@ export declare const timeoutOption: {
      * @since 3.1.0
      * @category Delays & Timeouts
      */
-    <A, E, R>(self: Effect<A, E, R>, duration: Duration.DurationInput): Effect<Option<A>, E, R>;
+    <A, E, R>(self: Effect<A, E, R>, duration: Duration.Input): Effect<Option<A>, E, R>;
 };
 /**
  * Applies a timeout to an effect, with a fallback effect executed if the timeout is reached.
@@ -6939,7 +7050,7 @@ export declare const timeoutOrElse: {
      * @category Delays & Timeouts
      */
     <A2, E2, R2>(options: {
-        readonly duration: Duration.DurationInput;
+        readonly duration: Duration.Input;
         readonly onTimeout: LazyArg<Effect<A2, E2, R2>>;
     }): <A, E, R>(self: Effect<A, E, R>) => Effect<A | A2, E | E2, R | R2>;
     /**
@@ -6979,7 +7090,7 @@ export declare const timeoutOrElse: {
      * @category Delays & Timeouts
      */
     <A, E, R, A2, E2, R2>(self: Effect<A, E, R>, options: {
-        readonly duration: Duration.DurationInput;
+        readonly duration: Duration.Input;
         readonly onTimeout: LazyArg<Effect<A2, E2, R2>>;
     }): Effect<A | A2, E | E2, R | R2>;
 };
@@ -7024,7 +7135,7 @@ export declare const delay: {
      * @since 2.0.0
      * @category Delays & Timeouts
      */
-    (duration: Duration.DurationInput): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
+    (duration: Duration.Input): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
     /**
      * Returns an effect that is delayed from this effect by the specified
      * `Duration`.
@@ -7045,7 +7156,7 @@ export declare const delay: {
      * @since 2.0.0
      * @category Delays & Timeouts
      */
-    <A, E, R>(self: Effect<A, E, R>, duration: Duration.DurationInput): Effect<A, E, R>;
+    <A, E, R>(self: Effect<A, E, R>, duration: Duration.Input): Effect<A, E, R>;
 };
 /**
  * Returns an effect that suspends for the specified duration. This method is
@@ -7069,7 +7180,7 @@ export declare const delay: {
  * @since 2.0.0
  * @category Delays & Timeouts
  */
-export declare const sleep: (duration: Duration.DurationInput) => Effect<void>;
+export declare const sleep: (duration: Duration.Input) => Effect<void>;
 /**
  * Measures the runtime of an effect and returns the duration with its result.
  *
@@ -7433,6 +7544,32 @@ export declare const filter: {
      * @category Filtering
      */
     <A>(predicate: Predicate.Predicate<NoInfer<A>>): (elements: Iterable<A>) => Effect<Array<A>>;
+    /**
+     * Filters elements of an iterable using a predicate, refinement, effectful
+     * predicate, or `Filter.FilterEffect`.
+     *
+     * @example
+     * ```ts
+     * import { Effect, Filter, Result } from "effect"
+     *
+     * // Sync predicate
+     * const evens = Effect.filter([1, 2, 3, 4], (n) => n % 2 === 0)
+     *
+     * // Effectful predicate
+     * const checked = Effect.filter([1, 2, 3], (n) => Effect.succeed(n > 1))
+     *
+     * // FilterEffect
+     * const mapped = Effect.filter([1, 2, 3, 4], (n) =>
+     *   Effect.succeed(n % 2 === 0 ? Result.succeed(n * 2) : Result.fail(n))
+     * )
+     * ```
+     *
+     * @since 2.0.0
+     * @category Filtering
+     */
+    <A, B, X>(filter: Filter.Filter<NoInfer<A>, B, X>, options?: {
+        readonly concurrency?: Concurrency | undefined;
+    }): (elements: Iterable<A>) => Effect<Array<B>>;
     /**
      * Filters elements of an iterable using a predicate, refinement, effectful
      * predicate, or `Filter.FilterEffect`.
@@ -7533,6 +7670,30 @@ export declare const filter: {
      * @category Filtering
      */
     <A>(elements: Iterable<A>, predicate: Predicate.Predicate<A>): Effect<Array<A>>;
+    /**
+     * Filters elements of an iterable using a predicate, refinement, effectful
+     * predicate, or `Filter.FilterEffect`.
+     *
+     * @example
+     * ```ts
+     * import { Effect, Filter, Result } from "effect"
+     *
+     * // Sync predicate
+     * const evens = Effect.filter([1, 2, 3, 4], (n) => n % 2 === 0)
+     *
+     * // Effectful predicate
+     * const checked = Effect.filter([1, 2, 3], (n) => Effect.succeed(n > 1))
+     *
+     * // FilterEffect
+     * const mapped = Effect.filter([1, 2, 3, 4], (n) =>
+     *   Effect.succeed(n % 2 === 0 ? Result.succeed(n * 2) : Result.fail(n))
+     * )
+     * ```
+     *
+     * @since 2.0.0
+     * @category Filtering
+     */
+    <A, B, X>(elements: Iterable<A>, filter: Filter.Filter<NoInfer<A>, B, X>): Effect<Array<B>>;
     /**
      * Filters elements of an iterable using a predicate, refinement, effectful
      * predicate, or `Filter.FilterEffect`.
@@ -11335,7 +11496,7 @@ export declare const cachedWithTTL: {
      * @since 2.0.0
      * @category Caching
      */
-    (timeToLive: Duration.DurationInput): <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>;
+    (timeToLive: Duration.Input): <A, E, R>(self: Effect<A, E, R>) => Effect<Effect<A, E, R>>;
     /**
      * Returns an effect that caches its result for a specified `Duration`,
      * known as "timeToLive" (TTL).
@@ -11402,7 +11563,7 @@ export declare const cachedWithTTL: {
      * @since 2.0.0
      * @category Caching
      */
-    <A, E, R>(self: Effect<A, E, R>, timeToLive: Duration.DurationInput): Effect<Effect<A, E, R>>;
+    <A, E, R>(self: Effect<A, E, R>, timeToLive: Duration.Input): Effect<Effect<A, E, R>>;
 };
 /**
  * Caches an effect's result for a specified duration and allows manual
@@ -11543,7 +11704,7 @@ export declare const cachedInvalidateWithTTL: {
      * @since 2.0.0
      * @category Caching
      */
-    (timeToLive: Duration.DurationInput): <A, E, R>(self: Effect<A, E, R>) => Effect<[Effect<A, E, R>, Effect<void>]>;
+    (timeToLive: Duration.Input): <A, E, R>(self: Effect<A, E, R>) => Effect<[Effect<A, E, R>, Effect<void>]>;
     /**
      * Caches an effect's result for a specified duration and allows manual
      * invalidation before expiration.
@@ -11613,7 +11774,7 @@ export declare const cachedInvalidateWithTTL: {
      * @since 2.0.0
      * @category Caching
      */
-    <A, E, R>(self: Effect<A, E, R>, timeToLive: Duration.DurationInput): Effect<[Effect<A, E, R>, Effect<void>]>;
+    <A, E, R>(self: Effect<A, E, R>, timeToLive: Duration.Input): Effect<[Effect<A, E, R>, Effect<void>]>;
 };
 /**
  * Returns an effect that is immediately interrupted.
@@ -11813,232 +11974,6 @@ export declare const uninterruptibleMask: <A, E, R>(f: (restore: <AX, EX, RX>(ef
  * @category Interruption
  */
 export declare const interruptibleMask: <A, E, R>(f: (restore: <AX, EX, RX>(effect: Effect<AX, EX, RX>) => Effect<AX, EX, RX>) => Effect<A, E, R>) => Effect<A, E, R>;
-/**
- * @category Semaphore
- * @since 2.0.0
- * @example
- * ```ts
- * import { Effect } from "effect"
- *
- * // Create and use a semaphore for controlling concurrent access
- * const program = Effect.gen(function*() {
- *   const semaphore = yield* Effect.makeSemaphore(2)
- *
- *   return yield* semaphore.withPermits(1)(
- *     Effect.succeed("Resource accessed")
- *   )
- * })
- * ```
- */
-export interface Semaphore {
-    /**
-     * Adjusts the number of permits available in the semaphore.
-     */
-    resize(permits: number): Effect<void>;
-    /**
-     * Runs an effect with the given number of permits and releases the permits
-     * when the effect completes.
-     *
-     * **Details**
-     *
-     * This function acquires the specified number of permits before executing
-     * the provided effect. Once the effect finishes, the permits are released.
-     * If insufficient permits are available, the function will wait until they
-     * are released by other tasks.
-     */
-    withPermits(permits: number): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
-    /**
-     * Runs an effect with the given number of permits and releases the permits
-     * when the effect completes.
-     *
-     * **Details**
-     *
-     * This function acquires the specified number of permits before executing
-     * the provided effect. Once the effect finishes, the permits are released.
-     * If insufficient permits are available, the function will wait until they
-     * are released by other tasks.
-     */
-    withPermit<A, E, R>(self: Effect<A, E, R>): Effect<A, E, R>;
-    /**
-     * Runs an effect only if the specified number of permits are immediately
-     * available.
-     *
-     * **Details**
-     *
-     * This function attempts to acquire the specified number of permits. If they
-     * are available, it runs the effect and releases the permits after the effect
-     * completes. If permits are not available, the effect does not execute, and
-     * the result is `Option.none`.
-     */
-    withPermitsIfAvailable(permits: number): <A, E, R>(self: Effect<A, E, R>) => Effect<Option<A>, E, R>;
-    /**
-     * Acquires the specified number of permits and returns the resulting
-     * available permits, suspending the task if they are not yet available.
-     * Concurrent pending `take` calls are processed in a first-in, first-out manner.
-     */
-    take(permits: number): Effect<number>;
-    /**
-     * Releases the specified number of permits and returns the resulting
-     * available permits.
-     */
-    release(permits: number): Effect<number>;
-    /**
-     * Releases all permits held by this semaphore and returns the resulting available permits.
-     */
-    releaseAll: Effect<number>;
-}
-/**
- * Unsafely creates a new Semaphore.
- *
- * @example
- * ```ts
- * import { Effect } from "effect"
- *
- * const semaphore = Effect.makeSemaphoreUnsafe(3)
- *
- * const task = (id: number) =>
- *   semaphore.withPermits(1)(
- *     Effect.gen(function*() {
- *       yield* Effect.log(`Task ${id} started`)
- *       yield* Effect.sleep("1 second")
- *       yield* Effect.log(`Task ${id} completed`)
- *     })
- *   )
- *
- * // Only 3 tasks can run concurrently
- * const program = Effect.all([
- *   task(1),
- *   task(2),
- *   task(3),
- *   task(4),
- *   task(5)
- * ], { concurrency: "unbounded" })
- * ```
- *
- * @since 2.0.0
- * @category Semaphore
- */
-export declare const makeSemaphoreUnsafe: (permits: number) => Semaphore;
-/**
- * Creates a new Semaphore.
- *
- * @example
- * ```ts
- * import { Effect } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const semaphore = yield* Effect.makeSemaphore(2)
- *
- *   const task = (id: number) =>
- *     semaphore.withPermits(1)(
- *       Effect.gen(function*() {
- *         yield* Effect.log(`Task ${id} acquired permit`)
- *         yield* Effect.sleep("1 second")
- *         yield* Effect.log(`Task ${id} releasing permit`)
- *       })
- *     )
- *
- *   // Run 4 tasks, but only 2 can run concurrently
- *   yield* Effect.all([task(1), task(2), task(3), task(4)])
- * })
- * ```
- *
- * @since 2.0.0
- * @category Semaphore
- */
-export declare const makeSemaphore: (permits: number) => Effect<Semaphore>;
-/**
- * @category Latch
- * @since 3.8.0
- * @example
- * ```ts
- * import { Effect } from "effect"
- *
- * // Create and use a latch for coordination between fibers
- * const program = Effect.gen(function*() {
- *   const latch = yield* Effect.makeLatch()
- *
- *   // Wait for the latch to be opened
- *   yield* latch.await
- *
- *   return "Latch was opened!"
- * })
- * ```
- */
-export interface Latch {
-    /** open the latch, releasing all fibers waiting on it */
-    readonly open: Effect<boolean>;
-    /** open the latch, releasing all fibers waiting on it */
-    readonly openUnsafe: () => boolean;
-    /** release all fibers waiting on the latch, without opening it */
-    readonly release: Effect<boolean>;
-    /** wait for the latch to be opened */
-    readonly await: Effect<void>;
-    /** close the latch */
-    readonly close: Effect<boolean>;
-    /** close the latch */
-    readonly closeUnsafe: () => boolean;
-    /** only run the given effect when the latch is open */
-    readonly whenOpen: <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
-}
-/**
- * Creates a new Latch.
- *
- * @example
- * ```ts
- * import { Effect } from "effect"
- *
- * const latch = Effect.makeLatchUnsafe(false)
- *
- * const waiter = Effect.gen(function*() {
- *   yield* Effect.log("Waiting for latch to open...")
- *   yield* latch.await
- *   yield* Effect.log("Latch opened! Continuing...")
- * })
- *
- * const opener = Effect.gen(function*() {
- *   yield* Effect.sleep("2 seconds")
- *   yield* Effect.log("Opening latch...")
- *   yield* latch.open
- * })
- *
- * const program = Effect.all([waiter, opener])
- * ```
- *
- * @category Latch
- * @since 3.8.0
- */
-export declare const makeLatchUnsafe: (open?: boolean | undefined) => Latch;
-/**
- * Creates a new Latch.
- *
- * @example
- * ```ts
- * import { Effect } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const latch = yield* Effect.makeLatch(false)
- *
- *   const waiter = Effect.gen(function*() {
- *     yield* Effect.log("Waiting for latch to open...")
- *     yield* latch.await
- *     yield* Effect.log("Latch opened! Continuing...")
- *   })
- *
- *   const opener = Effect.gen(function*() {
- *     yield* Effect.sleep("2 seconds")
- *     yield* Effect.log("Opening latch...")
- *     yield* latch.open
- *   })
- *
- *   yield* Effect.all([waiter, opener])
- * })
- * ```
- *
- * @category Latch
- * @since 3.8.0
- */
-export declare const makeLatch: (open?: boolean | undefined) => Effect<Latch>;
 /**
  * @since 2.0.0
  * @category Repetition / Recursion