effect 3.5.8 → 3.6.0

package/src/Effect.ts

@@ -3419,7 +3419,7 @@ export const updateService: {
 // -------------------------------------------------------------------------------------
 
 /**
- * The "do simulation" in allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+ * The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
  *
  * Here's how the do simulation works:
  *
@@ -3449,7 +3449,7 @@ export const updateService: {
 export const Do: Effect<{}> = effect.Do
 
 /**
- * The "do simulation" in allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+ * The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
  *
  * Here's how the do simulation works:
  *
@@ -3489,7 +3489,7 @@ export const bind: {
 } = effect.bind
 
 /**
- * The "do simulation" in allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+ * The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
  *
  * Here's how the do simulation works:
  *
@@ -3535,7 +3535,7 @@ const let_: {
 
 export {
   /**
-   * The "do simulation" in allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+   * The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
    *
    * Here's how the do simulation works:
    *
@@ -4029,6 +4029,12 @@ export const tap: {
   ) => [X] extends [Effect<infer _A1, infer E1, infer R1>] ? Effect<A, E | E1, R | R1>
     : [X] extends [PromiseLike<infer _A1>] ? Effect<A, E | Cause.UnknownException, R>
     : Effect<A, E, R>
+  <A, X, E1, R1>(
+    f: (a: NoInfer<A>) => Effect<X, E1, R1>,
+    options: { onlyEffect: true }
+  ): <E, R>(
+    self: Effect<A, E, R>
+  ) => Effect<A, E | E1, R | R1>
   <X>(
     f: NotFunction<X>
   ): <A, E, R>(
@@ -4036,18 +4042,34 @@ export const tap: {
   ) => [X] extends [Effect<infer _A1, infer E1, infer R1>] ? Effect<A, E | E1, R | R1>
     : [X] extends [PromiseLike<infer _A1>] ? Effect<A, E | Cause.UnknownException, R>
     : Effect<A, E, R>
+  <X, E1, R1>(
+    f: Effect<X, E1, R1>,
+    options: { onlyEffect: true }
+  ): <A, E, R>(
+    self: Effect<A, E, R>
+  ) => Effect<A, E | E1, R | R1>
   <A, E, R, X>(
     self: Effect<A, E, R>,
     f: (a: NoInfer<A>) => X
   ): [X] extends [Effect<infer _A1, infer E1, infer R1>] ? Effect<A, E | E1, R | R1>
     : [X] extends [PromiseLike<infer _A1>] ? Effect<A, E | Cause.UnknownException, R>
     : Effect<A, E, R>
+  <A, E, R, X, E1, R1>(
+    self: Effect<A, E, R>,
+    f: (a: NoInfer<A>) => Effect<X, E1, R1>,
+    options: { onlyEffect: true }
+  ): Effect<A, E | E1, R | R1>
   <A, E, R, X>(
     self: Effect<A, E, R>,
     f: NotFunction<X>
   ): [X] extends [Effect<infer _A1, infer E1, infer R1>] ? Effect<A, E | E1, R | R1>
     : [X] extends [PromiseLike<infer _A1>] ? Effect<A, E | Cause.UnknownException, R>
     : Effect<A, E, R>
+  <A, E, R, X, E1, R1>(
+    self: Effect<A, E, R>,
+    f: Effect<X, E1, R1>,
+    options: { onlyEffect: true }
+  ): Effect<A, E | E1, R | R1>
 } = core.tap
 
 /**
@@ -5958,6 +5980,8 @@ export declare namespace Tag {
    * @category models
    */
   export interface ProhibitedType {
+    Service?: `property "Service" is forbidden`
+    Identifier?: `property "Identifier" is forbidden`
     _op?: `property "_op" is forbidden`
     _tag?: `property "_tag" is forbidden`
     of?: `property "of" is forbidden`

package/src/Either.ts

@@ -791,7 +791,7 @@ export const gen: Gen.Gen<EitherTypeLambda, Gen.Adapter<EitherTypeLambda>> = (..
 // -------------------------------------------------------------------------------------
 
 /**
- * The "do simulation" in allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+ * The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
  *
  * Here's how the do simulation works:
  *
@@ -821,7 +821,7 @@ export const gen: Gen.Gen<EitherTypeLambda, Gen.Adapter<EitherTypeLambda>> = (..
 export const Do: Either<{}> = right({})
 
 /**
- * The "do simulation" in allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+ * The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
  *
  * Here's how the do simulation works:
  *
@@ -861,7 +861,7 @@ export const bind: {
 } = doNotation.bind<EitherTypeLambda>(map, flatMap)
 
 /**
- * The "do simulation" in allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+ * The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
  *
  * Here's how the do simulation works:
  *
@@ -907,7 +907,7 @@ const let_: {
 
 export {
   /**
-   * The "do simulation" in allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+   * The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
    *
    * Here's how the do simulation works:
    *

package/src/List.ts

@@ -29,6 +29,7 @@ import * as Equivalence from "./Equivalence.js"
 import { dual, identity, unsafeCoerce } from "./Function.js"
 import * as Hash from "./Hash.js"
 import { format, type Inspectable, NodeInspectSymbol, toJSON } from "./Inspectable.js"
+import type { nonEmpty, NonEmptyIterable } from "./NonEmptyIterable.js"
 import * as Option from "./Option.js"
 import type { Pipeable } from "./Pipeable.js"
 import { pipeArguments } from "./Pipeable.js"
@@ -72,7 +73,7 @@ export interface Nil<out A> extends Iterable<A>, Equal.Equal, Pipeable, Inspecta
  * @since 2.0.0
  * @category models
  */
-export interface Cons<out A> extends Iterable<A>, Equal.Equal, Pipeable, Inspectable {
+export interface Cons<out A> extends NonEmptyIterable<A>, Equal.Equal, Pipeable, Inspectable {
   readonly [TypeId]: TypeId
   readonly _tag: "Cons"
   readonly head: A
@@ -96,7 +97,7 @@ export const getEquivalence = <A>(isEquivalent: Equivalence.Equivalence<A>): Equ
 
 const _equivalence = getEquivalence(Equal.equals)
 
-const ConsProto: Omit<Cons<unknown>, "head" | "tail"> = {
+const ConsProto: Omit<Cons<unknown>, "head" | "tail" | typeof nonEmpty> = {
   [TypeId]: TypeId,
   _tag: "Cons",
   toString(this: Cons<unknown>) {

package/src/Metric.ts

@@ -361,7 +361,7 @@ export const set: {
  * @since 2.0.0
  * @category getters
  */
-export const snapshot: Effect.Effect<ReadonlyArray<MetricPair.MetricPair.Untyped>> = internal.snapshot
+export const snapshot: Effect.Effect<Array<MetricPair.MetricPair.Untyped>> = internal.snapshot
 
 /**
  * Creates a metric that ignores input and produces constant output.

package/src/MetricRegistry.ts

@@ -25,7 +25,7 @@ export type MetricRegistryTypeId = typeof MetricRegistryTypeId
  */
 export interface MetricRegistry {
   readonly [MetricRegistryTypeId]: MetricRegistryTypeId
-  snapshot(): ReadonlyArray<MetricPair.MetricPair.Untyped>
+  snapshot(): Array<MetricPair.MetricPair.Untyped>
   get<Type extends MetricKeyType.MetricKeyType<any, any>>(
     key: MetricKey.MetricKey<Type>
   ): MetricHook.MetricHook<

package/src/Micro.ts

@@ -562,6 +562,7 @@ export const envUnsafeMakeEmpty = (): Env<never> => {
   const refs = Object.create(null)
   refs[currentAbortController.key] = controller
   refs[currentAbortSignal.key] = controller.signal
+  refs[currentScheduler.key] = new MicroSchedulerDefault()
   return envMake(refs)
 }
 
@@ -733,6 +734,79 @@ export const provideServiceEffect: {
   ): Micro<A, E | E2, Exclude<R, I> | R2> => flatMap(acquire, (service) => provideService(self, tag, service))
 )
 
+// ----------------------------------------------------------------------------
+// scheduler
+// ----------------------------------------------------------------------------
+
+/**
+ * @since 3.5.9
+ * @experimental
+ * @category scheduler
+ */
+export interface MicroScheduler {
+  readonly scheduleTask: (task: () => void, priority: number) => void
+  readonly shouldYield: (env: Env<unknown>) => boolean
+  readonly flush: () => void
+}
+
+const setImmediate = "setImmediate" in globalThis ? globalThis.setImmediate : (f: () => void) => setTimeout(f, 0)
+
+/**
+ * @since 3.5.9
+ * @experimental
+ * @category scheduler
+ */
+export class MicroSchedulerDefault implements MicroScheduler {
+  private tasks: Array<() => void> = []
+  private running = false
+
+  /**
+   * @since 3.5.9
+   */
+  scheduleTask(task: () => void, _priority: number) {
+    this.tasks.push(task)
+    if (!this.running) {
+      this.running = true
+      setImmediate(this.afterScheduled)
+    }
+  }
+
+  /**
+   * @since 3.5.9
+   */
+  afterScheduled = () => {
+    this.running = false
+    this.runTasks()
+  }
+
+  /**
+   * @since 3.5.9
+   */
+  runTasks() {
+    const tasks = this.tasks
+    this.tasks = []
+    for (let i = 0, len = tasks.length; i < len; i++) {
+      tasks[i]()
+    }
+  }
+
+  /**
+   * @since 3.5.9
+   */
+  shouldYield(_env: Env<unknown>) {
+    return false
+  }
+
+  /**
+   * @since 3.5.9
+   */
+  flush() {
+    while (this.tasks.length > 0) {
+      this.runTasks()
+    }
+  }
+}
+
 // ========================================================================
 // Env refs
 // ========================================================================
@@ -809,6 +883,16 @@ const currentInterruptible: EnvRef<boolean> = envRefMake(
   () => true
 )
 
+/**
+ * @since 3.4.0
+ * @experimental
+ * @category environment refs
+ */
+export const currentScheduler: EnvRef<MicroScheduler> = envRefMake(
+  "effect/Micro/currentScheduler",
+  () => new MicroSchedulerDefault()
+)
+
 /**
  * If you have a `Micro` that uses `concurrency: "inherit"`, you can use this
  * api to control the concurrency of that `Micro` when it is run.
@@ -879,8 +963,9 @@ const unsafeMakeOptions = <R, A, E>(
     if (microDepthState.depth === 1) {
       microDepthState.maxDepthBeforeYield = envGet(env, currentMaxDepthBeforeYield)
     }
-    if (microDepthState.depth >= microDepthState.maxDepthBeforeYield) {
-      yieldAdd(() => execute(env, onExit))
+    const scheduler = env.refs[currentScheduler.key] as MicroScheduler
+    if (microDepthState.depth >= microDepthState.maxDepthBeforeYield || scheduler.shouldYield(env)) {
+      scheduler.scheduleTask(() => execute(env, onExit), 0)
     } else {
       try {
         run(env, onExit)
@@ -1200,34 +1285,21 @@ export const tryPromise = <A, E>(options: {
     }
   })
 
-const yieldState: {
-  tasks: Array<() => void>
-  working: boolean
-} = globalValue("effect/Micro/yieldState", () => ({
-  tasks: [],
-  working: false
-}))
-
-const yieldRunTasks = () => {
-  const tasks = yieldState.tasks
-  yieldState.tasks = []
-  for (let i = 0, len = tasks.length; i < len; i++) {
-    tasks[i]()
-  }
-}
-
-const setImmediate = "setImmediate" in globalThis ? globalThis.setImmediate : (f: () => void) => setTimeout(f, 0)
-
-const yieldAdd = (task: () => void) => {
-  yieldState.tasks.push(task)
-  if (!yieldState.working) {
-    yieldState.working = true
-    setImmediate(() => {
-      yieldState.working = false
-      yieldRunTasks()
-    })
-  }
-}
+/**
+ * Pause the execution of the current `Micro` effect, and resume it on the next
+ * iteration of the event loop.
+ *
+ * You can specify a priority for the task, which will determine when it is
+ * executed relative to other tasks.
+ *
+ * @since 3.4.0
+ * @experimental
+ * @category constructors
+ */
+export const yieldWithPriority = (priority: number): Micro<void> =>
+  make(function(env, onExit) {
+    envGet(env, currentScheduler).scheduleTask(() => onExit(exitVoid), priority)
+  })
 
 /**
  * Pause the execution of the current `Micro` effect, and resume it on the next
@@ -1237,9 +1309,7 @@ const yieldAdd = (task: () => void) => {
  * @experimental
  * @category constructors
  */
-export const yieldNow: Micro<void> = make(function(_env, onExit) {
-  yieldAdd(() => onExit(exitVoid))
-})
+export const yieldNow: Micro<void> = yieldWithPriority(0)
 
 /**
  * Flush any yielded effects that are waiting to be executed.
@@ -1248,10 +1318,9 @@ export const yieldNow: Micro<void> = make(function(_env, onExit) {
  * @experimental
  * @category constructors
  */
-export const yieldFlush: Micro<void> = sync(function() {
-  while (yieldState.tasks.length > 0) {
-    yieldRunTasks()
-  }
+export const yieldFlush: Micro<void> = make(function(env, onExit) {
+  envGet(env, currentScheduler).flush()
+  onExit(exitVoid)
 })
 
 /**
@@ -3687,11 +3756,11 @@ export const fork = <A, E, R>(self: Micro<A, E, R>): Micro<Handle<A, E>, never,
       map[currentAbortSignal.key] = handle._controller.signal
       return map
     })
-    yieldAdd(() => {
+    envGet(env, currentScheduler).scheduleTask(() => {
       self[runSymbol](nextEnv, (exit) => {
         handle.emit(exit)
       })
-    })
+    }, 0)
     onExit(Either.right(handle))
   })
 
@@ -3714,11 +3783,11 @@ export const forkDaemon = <A, E, R>(self: Micro<A, E, R>): Micro<Handle<A, E>, n
       map[currentAbortSignal.key] = controller.signal
       return map
     })
-    yieldAdd(() => {
+    envGet(env, currentScheduler).scheduleTask(() => {
       self[runSymbol](nextEnv, (exit) => {
         handle.emit(exit)
       })
-    })
+    }, 0)
     onExit(Either.right(handle))
   })
 
@@ -3790,12 +3859,14 @@ export const runFork = <A, E>(
   effect: Micro<A, E>,
   options?: {
     readonly signal?: AbortSignal | undefined
+    readonly scheduler?: MicroScheduler | undefined
   } | undefined
 ): Handle<A, E> => {
   const controller = new AbortController()
   const refs = Object.create(null)
   refs[currentAbortController.key] = controller
   refs[currentAbortSignal.key] = controller.signal
+  refs[currentScheduler.key] = options?.scheduler ?? new MicroSchedulerDefault()
   const env = envMake(refs)
   const handle = new HandleImpl<A, E>(controller.signal, controller)
   effect[runSymbol](envSet(env, currentAbortSignal, handle._controller.signal), (exit) => {
@@ -3826,6 +3897,7 @@ export const runPromiseExit = <A, E>(
   effect: Micro<A, E>,
   options?: {
     readonly signal?: AbortSignal | undefined
+    readonly scheduler?: MicroScheduler | undefined
   } | undefined
 ): Promise<MicroExit<A, E>> =>
   new Promise((resolve, _reject) => {
@@ -3845,6 +3917,7 @@ export const runPromise = <A, E>(
   effect: Micro<A, E>,
   options?: {
     readonly signal?: AbortSignal | undefined
+    readonly scheduler?: MicroScheduler | undefined
   } | undefined
 ): Promise<A> =>
   runPromiseExit(effect, options).then((exit) => {
@@ -3865,10 +3938,9 @@ export const runPromise = <A, E>(
  * @category execution
  */
 export const runSyncExit = <A, E>(effect: Micro<A, E>): MicroExit<A, E> => {
-  const handle = runFork(effect)
-  while (yieldState.tasks.length > 0) {
-    yieldRunTasks()
-  }
+  const scheduler = new MicroSchedulerDefault()
+  const handle = runFork(effect, { scheduler })
+  scheduler.flush()
   const exit = handle.unsafePoll()
   if (exit === null) {
     return exitDie(handle)

package/src/Option.ts

@@ -1196,7 +1196,7 @@ export const exists: {
 // -------------------------------------------------------------------------------------
 
 /**
- * The "do simulation" in allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+ * The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
  *
  * Here's how the do simulation works:
  *
@@ -1244,7 +1244,7 @@ const let_: {
 
 export {
   /**
-   * The "do simulation" in allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+   * The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
    *
    * Here's how the do simulation works:
    *
@@ -1277,7 +1277,7 @@ export {
 }
 
 /**
- * The "do simulation" in allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+ * The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
  *
  * Here's how the do simulation works:
  *
@@ -1319,7 +1319,7 @@ export const bind: {
 } = doNotation.bind<OptionTypeLambda>(map, flatMap)
 
 /**
- * The "do simulation" in allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
+ * The "do simulation" in Effect allows you to write code in a more declarative style, similar to the "do notation" in other programming languages. It provides a way to define variables and perform operations on them using functions like `bind` and `let`.
  *
  * Here's how the do simulation works:
  *

package/src/Predicate.ts

@@ -29,6 +29,45 @@ export interface Refinement<in A, out B extends A> {
   (a: A): a is B
 }
 
+/**
+ * @since 3.6.0
+ * @category type-level
+ */
+export declare namespace Predicate {
+  /**
+   * @since 3.6.0
+   * @category type-level
+   */
+  export type In<T extends Any> = [T] extends [Predicate<infer _A>] ? _A : never
+  /**
+   * @since 3.6.0
+   * @category type-level
+   */
+  export type Any = Predicate<any>
+}
+
+/**
+ * @since 3.6.0
+ * @category type-level
+ */
+export declare namespace Refinement {
+  /**
+   * @since 3.6.0
+   * @category type-level
+   */
+  export type In<T extends Any> = [T] extends [Refinement<infer _A, infer _>] ? _A : never
+  /**
+   * @since 3.6.0
+   * @category type-level
+   */
+  export type Out<T extends Any> = [T] extends [Refinement<infer _, infer _B>] ? _B : never
+  /**
+   * @since 3.6.0
+   * @category type-level
+   */
+  export type Any = Refinement<any, any>
+}
+
 /**
  * Given a `Predicate<A>` returns a `Predicate<B>`
  *
@@ -686,23 +725,44 @@ export const productMany = <A>(
  * Similar to `Promise.all` but operates on `Predicate`s.
  *
  * ```
+ * [Refinement<A, B>, Refinement<C, D>, ...] -> Refinement<[A, C, ...], [B, D, ...]>
  * [Predicate<A>, Predicate<B>, ...] -> Predicate<[A, B, ...]>
+ * [Refinement<A, B>, Predicate<C>, ...] -> Refinement<[A, C, ...], [B, C, ...]>
  * ```
  *
  * @since 2.0.0
  */
-export const tuple = <T extends ReadonlyArray<Predicate<any>>>(
-  ...elements: T
-): Predicate<Readonly<{ [I in keyof T]: [T[I]] extends [Predicate<infer A>] ? A : never }>> => all(elements) as any
+export const tuple: {
+  <T extends ReadonlyArray<Predicate.Any>>(
+    ...elements: T
+  ): [Extract<T[number], Refinement.Any>] extends [never] ? Predicate<{ readonly [I in keyof T]: Predicate.In<T[I]> }>
+    : Refinement<
+      { readonly [I in keyof T]: T[I] extends Refinement.Any ? Refinement.In<T[I]> : Predicate.In<T[I]> },
+      { readonly [I in keyof T]: T[I] extends Refinement.Any ? Refinement.Out<T[I]> : Predicate.In<T[I]> }
+    >
+} = (...elements: ReadonlyArray<Predicate.Any>) => all(elements) as any
 
 /**
+ * ```
+ * { ab: Refinement<A, B>; cd: Refinement<C, D>, ... } -> Refinement<{ ab: A; cd: C; ... }, { ab: B; cd: D; ... }>
+ * { a: Predicate<A, B>; b: Predicate<B>, ... } -> Predicate<{ a: A; b: B; ... }>
+ * { ab: Refinement<A, B>; c: Predicate<C>, ... } -> Refinement<{ ab: A; c: C; ... }, { ab: B; c: С; ... }>
+ * ```
+ *
  * @since 2.0.0
  */
-export const struct = <R extends Record<string, Predicate<any>>>(
-  fields: R
-): Predicate<{ readonly [K in keyof R]: [R[K]] extends [Predicate<infer A>] ? A : never }> => {
+export const struct: {
+  <R extends Record<string, Predicate.Any>>(
+    fields: R
+  ): [Extract<R[keyof R], Refinement.Any>] extends [never] ?
+    Predicate<{ readonly [K in keyof R]: Predicate.In<R[K]> }> :
+    Refinement<
+      { readonly [K in keyof R]: R[K] extends Refinement.Any ? Refinement.In<R[K]> : Predicate.In<R[K]> },
+      { readonly [K in keyof R]: R[K] extends Refinement.Any ? Refinement.Out<R[K]> : Predicate.In<R[K]> }
+    >
+} = (<R extends Record<string, Predicate.Any>>(fields: R) => {
   const keys = Object.keys(fields)
-  return (a) => {
+  return (a: Record<string, unknown>) => {
     for (const key of keys) {
       if (!fields[key](a[key])) {
         return false
@@ -710,7 +770,7 @@ export const struct = <R extends Record<string, Predicate<any>>>(
     }
     return true
   }
-}
+}) as any
 
 /**
  * Negates the result of a given predicate.

package/src/Random.ts

@@ -1,11 +1,14 @@
 /**
  * @since 2.0.0
  */
+import type * as Array from "./Array.js"
+import type * as Cause from "./Cause.js"
 import type * as Chunk from "./Chunk.js"
 import type * as Context from "./Context.js"
 import type * as Effect from "./Effect.js"
 import * as defaultServices from "./internal/defaultServices.js"
 import * as internal from "./internal/random.js"
+import type * as NonEmptyIterable from "./NonEmptyIterable.js"
 
 /**
  * @since 2.0.0
@@ -103,6 +106,27 @@ export const nextIntBetween: (min: number, max: number) => Effect.Effect<number>
  */
 export const shuffle: <A>(elements: Iterable<A>) => Effect.Effect<Chunk.Chunk<A>> = defaultServices.shuffle
 
+/**
+ * Get a random element from an iterable.
+ *
+ * @example
+ * import { Effect, Random } from "effect"
+ *
+ * Effect.gen(function* () {
+ *   const randomItem = yield* Random.choice([1, 2, 3])
+ *   console.log(randomItem)
+ * })
+ *
+ * @since 3.6.0
+ * @category constructors
+ */
+export const choice: <Self extends Iterable<unknown>>(
+  elements: Self
+) => Self extends NonEmptyIterable.NonEmptyIterable<infer A> ? Effect.Effect<A>
+  : Self extends Array.NonEmptyReadonlyArray<infer A> ? Effect.Effect<A>
+  : Self extends Iterable<infer A> ? Effect.Effect<A, Cause.NoSuchElementException>
+  : never = defaultServices.choice
+
 /**
  * Retreives the `Random` service from the context and uses it to run the
  * specified workflow.