add Random.choice

.changeset/new-garlics-own.md

@@ -0,0 +1,14 @@
+---
+"effect": minor
+---
+
+Add `Random.choice`.
+
+```ts
+import { Random } from "effect"
+
+Effect.gen(function* () {
+  const randomItem = yield* Random.choice([1, 2, 3])
+  console.log(randomItem)
+})
+```

packages/effect/src/Random.ts

@@ -1,6 +1,7 @@
 /**
  * @since 2.0.0
  */
+import type * as Array from "./Array.js"
 import type * as Chunk from "./Chunk.js"
 import type * as Context from "./Context.js"
 import type * as Effect from "./Effect.js"
@@ -103,6 +104,22 @@ 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 a non-empty array.
+ *
+ * @example
+ * import { Random } from "effect"
+ *
+ * Effect.gen(function* () {
+ *   const randomItem = yield* Random.choice([1, 2, 3])
+ *   console.log(randomItem)
+ * })
+ *
+ * @since 2.0.0
+ * @category constructors
+ */
+export const choice: <A>(elements: Array.NonEmptyReadonlyArray<A>) => Effect.Effect<A> = internal.choice
+
 /**
  * Retreives the `Random` service from the context and uses it to run the
  * specified workflow.

packages/effect/src/internal/random.ts

@@ -1,3 +1,4 @@
+import type * as array from "../Array.js"
 import * as Chunk from "../Chunk.js"
 import * as Context from "../Context.js"
 import type * as Effect from "../Effect.js"
@@ -6,6 +7,7 @@ import * as Hash from "../Hash.js"
 import type * as Random from "../Random.js"
 import * as PCGRandom from "../Utils.js"
 import * as core from "./core.js"
+import * as defaultServices from "./defaultServices.js"
 
 /** @internal */
 const RandomSymbolKey = "effect/Random"
@@ -79,6 +81,12 @@ const shuffleWith = <A>(
   )
 }
 
+export const choice = <A>(elements: array.NonEmptyReadonlyArray<A>): Effect.Effect<A> =>
+  core.map(
+    defaultServices.randomWith((random) => random.nextIntBetween(0, elements.length)),
+    (i) => elements[i]
+  )
+
 const swap = <A>(buffer: Array<A>, index1: number, index2: number): Array<A> => {
   const tmp = buffer[index1]!
   buffer[index1] = buffer[index2]!

packages/effect/test/Random.test.ts

@@ -1,12 +1,12 @@
 import { Array, Chunk, Data, Effect, Random } from "effect"
-import * as it from "effect/test/utils/extend"
+import { expect, it } from "effect/test/utils/extend"
 import { assert, describe } from "vitest"
 
 describe("Random", () => {
   it.effect("shuffle", () =>
-    Effect.gen(function*($) {
+    Effect.gen(function*() {
       const start = Array.range(0, 100)
-      const end = yield* $(Random.shuffle(start))
+      const end = yield* Random.shuffle(start)
       assert.isTrue(Chunk.every(end, (n) => n !== undefined))
       assert.deepStrictEqual(start.sort(), Array.fromIterable(end).sort())
     }).pipe(Effect.repeatN(100)))
@@ -25,4 +25,10 @@ describe("Random", () => {
       assert.strictEqual(n2, n3)
       assert.notStrictEqual(n0, n2)
     }))
+
+  it.live("choice", () =>
+    Effect.gen(function*() {
+      expect(yield* Random.choice([1])).toEqual(1)
+      expect(yield* Random.choice([1, 2, 3])).oneOf([1, 2, 3])
+    }))
 })