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

package/src/Effect.ts

@@ -119,6 +119,7 @@ import type {
   NoInfer,
   ReasonOf,
   ReasonTags,
+  Simplify,
   Tags,
   unassigned
 } from "./Types.ts"
@@ -1511,6 +1512,103 @@ export const callback: <A, E = never, R = never>(
  */
 export const never: Effect<never> = internal.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 const Do: Effect<{}> = internal.Do
+
+/**
+ * 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 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>
+} = internal.bindTo
+
+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>
+} = internal.let
+
+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 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>
+} = internal.bind
+
 /**
  * Provides a way to write effectful code using generator functions, simplifying
  * control flow and error handling.
@@ -5124,6 +5222,36 @@ export const catchIf: {
   ): Effect<A | A2 | A3, E2 | E3, R | R2 | R3>
 } = internal.catchIf
 
+/**
+ * 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 const catchNoSuchElement: <A, E, R>(
+  self: Effect<A, E, R>
+) => Effect<Option<A>, Exclude<E, Cause.NoSuchElementError>, R> = internal.catchNoSuchElement
+
 /**
  * Recovers from specific failures based on a predicate.
  *
@@ -7194,7 +7322,7 @@ export 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>
   // -----------------------------------------------------------------------------
   // Delays & timeouts
   // -----------------------------------------------------------------------------
@@ -7245,7 +7373,7 @@ export 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>
 } = internal.timeout
 
 /**
@@ -7347,7 +7475,7 @@ export 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.
@@ -7397,7 +7525,7 @@ export 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>
 } = internal.timeoutOption
 
 /**
@@ -7475,7 +7603,7 @@ export const timeoutOrElse: {
    */
   <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>
@@ -7518,7 +7646,7 @@ export const timeoutOrElse: {
   <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>
@@ -7565,7 +7693,7 @@ export 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`.
@@ -7586,7 +7714,7 @@ export 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>
 } = internal.delay
 
 /**
@@ -7611,7 +7739,7 @@ export const delay: {
  * @since 2.0.0
  * @category Delays & Timeouts
  */
-export const sleep: (duration: Duration.DurationInput) => Effect<void> = internal.sleep
+export const sleep: (duration: Duration.Input) => Effect<void> = internal.sleep
 
 /**
  * Measures the runtime of an effect and returns the duration with its result.
@@ -8014,6 +8142,37 @@ export const filter: {
   // Filtering
   // -----------------------------------------------------------------------------
 
+  /**
+   * 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>>
+  // -----------------------------------------------------------------------------
+  // Filtering
+  // -----------------------------------------------------------------------------
+
   /**
    * Filters elements of an iterable using a predicate, refinement, effectful
    * predicate, or `Filter.FilterEffect`.
@@ -8132,6 +8291,34 @@ export const filter: {
   // Filtering
   // -----------------------------------------------------------------------------
 
+  /**
+   * 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>>
+  // -----------------------------------------------------------------------------
+  // Filtering
+  // -----------------------------------------------------------------------------
+
   /**
    * Filters elements of an iterable using a predicate, refinement, effectful
    * predicate, or `Filter.FilterEffect`.
@@ -12183,7 +12370,7 @@ export 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).
@@ -12250,7 +12437,7 @@ export 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>>
 } = internal.cachedWithTTL
 
 /**
@@ -12392,7 +12579,7 @@ export 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.
@@ -12462,7 +12649,7 @@ export 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>]>
 } = internal.cachedInvalidateWithTTL
 
 // -----------------------------------------------------------------------------
@@ -12688,252 +12875,6 @@ export const interruptibleMask: <A, E, R>(
   ) => Effect<A, E, R>
 ) => Effect<A, E, R> = internal.interruptibleMask
 
-// -----------------------------------------------------------------------------
-// Semaphore
-// -----------------------------------------------------------------------------
-
-/**
- * @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 const makeSemaphoreUnsafe: (permits: number) => Semaphore = internal.makeSemaphoreUnsafe
-
-/**
- * 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 const makeSemaphore: (permits: number) => Effect<Semaphore> = internal.makeSemaphore
-
-// -----------------------------------------------------------------------------
-// Latch
-// -----------------------------------------------------------------------------
-
-/**
- * @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 const makeLatchUnsafe: (open?: boolean | undefined) => Latch = internal.makeLatchUnsafe
-
-/**
- * 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 const makeLatch: (open?: boolean | undefined) => Effect<Latch> = internal.makeLatch
-
 // -----------------------------------------------------------------------------
 // Repetition & Recursion
 // -----------------------------------------------------------------------------
@@ -22062,8 +22003,8 @@ export const trackDuration: {
       return onExit(self, () => {
         const endTime = clock.currentTimeNanosUnsafe()
         const duration = Duration.subtract(
-          Duration.fromDurationInputUnsafe(endTime),
-          Duration.fromDurationInputUnsafe(startTime)
+          Duration.fromInputUnsafe(endTime),
+          Duration.fromInputUnsafe(startTime)
         )
         const input = f === undefined ? duration : internalCall(() => f(duration))
         return Metric.update(metric, input as any)