effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/Queue.ts

@@ -1,55 +1,67 @@
 /**
  * The `Queue` module provides asynchronous queues for communicating between
- * fibers. A `Queue<A, E>` can receive values of type `A`, deliver them to
- * consumers in order, and eventually complete or fail with an error of type
- * `E`.
+ * fibers. A `Queue<A, E>` accepts values of type `A`, hands each value to one
+ * consumer in offer order, and can later complete, fail, interrupt, or shut
+ * down through the queue lifecycle.
  *
  * **Mental model**
  *
- * - A queue is a fiber-aware channel with one write side ({@link Enqueue}) and
- *   one read side ({@link Dequeue})
+ * - A queue is a fiber-aware channel with a write side ({@link Enqueue}) and a
+ *   read side ({@link Dequeue}).
  * - Producers add values with {@link offer} or {@link offerAll}; consumers
  *   remove values with {@link take}, {@link takeN}, {@link takeBetween}, or
- *   {@link takeAll}
+ *   {@link takeAll}.
+ * - Unlike publish-subscribe hubs, consumers compete for values; a successful
+ *   take removes the value from the queue.
  * - Bounded queues use an overflow strategy: {@link bounded} suspends
  *   producers, {@link dropping} rejects new values, and {@link sliding} drops
- *   old values
- * - Queues can be completed with {@link end}, failed with {@link fail} or
- *   {@link failCause}, interrupted with {@link interrupt}, and shut down with
- *   {@link shutdown}
- * - Operations are expressed as `Effect` values so waiting producers and
- *   consumers compose with interruption, scheduling, and structured
- *   concurrency
+ *   old values.
+ * - Operations are `Effect` values, so waiting producers and consumers compose
+ *   with interruption, scheduling, and structured concurrency.
  *
  * **Common tasks**
  *
  * - Create queues: {@link make}, {@link bounded}, {@link dropping},
- *   {@link sliding}, {@link unbounded}
- * - Restrict capabilities: {@link asEnqueue}, {@link asDequeue}
- * - Produce values: {@link offer}, {@link offerAll}
+ *   {@link sliding}, {@link unbounded}.
+ * - Restrict capabilities: {@link asEnqueue}, {@link asDequeue}.
+ * - Produce values: {@link offer}, {@link offerAll}.
  * - Consume values: {@link take}, {@link takeN}, {@link takeBetween},
- *   {@link takeAll}, {@link poll}, {@link peek}
- * - Drain or reset buffered values: {@link collect}, {@link clear}
+ *   {@link takeAll}, {@link poll}, {@link peek}.
+ * - Drain or reset buffered values: {@link collect}, {@link clear}.
  * - Signal lifecycle: {@link end}, {@link fail}, {@link failCause},
- *   {@link interrupt}, {@link shutdown}
- * - Inspect state: {@link size}, {@link isFull}
+ *   {@link interrupt}, {@link shutdown}.
+ * - Inspect state: {@link size}, {@link isFull}.
+ *
+ * **Example** (One producer and one consumer)
+ *
+ * ```ts
+ * import { Effect, Queue } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const queue = yield* Queue.bounded<string>(16)
+ *
+ *   yield* Queue.offer(queue, "work")
+ *
+ *   return yield* Queue.take(queue)
+ * })
+ * ```
  *
  * **Gotchas**
  *
- * - `take` waits when the queue is empty; use {@link poll} when absence should
- *   be represented as `Option.None`
- * - `dropping` and `sliding` queues can lose values by design; use
- *   {@link bounded} when every offered value must be preserved
+ * - {@link take} waits when the queue is empty; use {@link poll} when absence
+ *   should be represented as an empty `Option`.
+ * - {@link dropping} and {@link sliding} queues can lose values by design; use
+ *   {@link bounded} when every offered value must be preserved.
  * - Completion and failure are observed by consumers through the queue's error
- *   channel, so include `Cause.Done` in the error type when using {@link end}
+ *   channel, so include `Cause.Done` in the error type when using {@link end}.
  * - The `Unsafe` variants are synchronous, low-level operations; prefer the
- *   effectful APIs in application code
+ *   effectful APIs in application code.
  *
  * **See also**
  *
- * - {@link Enqueue} for write-only queue handles
- * - {@link Dequeue} for read-only queue handles
- * - {@link Pull} for stream-style completion errors
+ * - {@link Enqueue} for write-only queue handles.
+ * - {@link Dequeue} for read-only queue handles.
+ * - {@link Pull} for stream-style completion errors.
  *
  * @since 3.8.0
  */
@@ -76,6 +88,14 @@ const DequeueTypeId = "~effect/Queue/Dequeue"
 /**
  * Type guard to check if a value is a Queue.
  *
+ * **When to use**
+ *
+ * Use to narrow an unknown value to a full `Queue` before passing it to APIs
+ * that need both offering and taking capabilities.
+ *
+ * @see {@link isEnqueue} for checking values that only need write access
+ * @see {@link isDequeue} for checking values that only need read access
+ *
  * @category guards
  * @since 2.0.0
  */
@@ -86,6 +106,20 @@ export const isQueue = <A = unknown, E = unknown>(
 /**
  * Type guard to check if a value is an Enqueue.
  *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before calling queue operations that require
+ * write-side access.
+ *
+ * **Gotchas**
+ *
+ * A full `Queue` also satisfies this guard because every queue includes the
+ * enqueue side.
+ *
+ * @see {@link isQueue} for checking for a full read-write queue handle
+ * @see {@link isDequeue} for checking for the read side of a queue
+ * @see {@link asEnqueue} for narrowing an existing `Queue` to its write-only interface
+ *
  * @category guards
  * @since 2.0.0
  */
@@ -96,6 +130,16 @@ export const isEnqueue = <A = unknown, E = unknown>(
 /**
  * Type guard to check if a value is a Dequeue.
  *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before passing it to read-side queue
+ * operations.
+ *
+ * @see {@link Dequeue} for the read-side queue handle checked by this guard
+ * @see {@link isQueue} for checking for a full read-write queue handle
+ * @see {@link isEnqueue} for checking for the write side of a queue
+ * @see {@link asDequeue} for narrowing an existing `Queue` to its read-only interface
+ *
  * @category guards
  * @since 2.0.0
  */
@@ -104,7 +148,20 @@ export const isDequeue = <A = unknown, E = unknown>(
 ): u is Dequeue<A, E> => hasProperty(u, DequeueTypeId)
 
 /**
- * Converts a Queue to an Enqueue (write-only interface).
+ * Converts a `Queue` to its write-only `Enqueue` interface.
+ *
+ * **When to use**
+ *
+ * Use to expose only the producer side of a `Queue` to code that should offer
+ * values or signal queue lifecycle.
+ *
+ * **Gotchas**
+ *
+ * This is a type-level capability restriction. It returns the same queue
+ * object, so it does not hide read operations at runtime.
+ *
+ * @see {@link asDequeue} for exposing only the read side of a `Queue`
+ * @see {@link Enqueue} for the write-only queue handle returned by this conversion
  *
  * @category converting
  * @since 4.0.0
@@ -112,7 +169,20 @@ export const isDequeue = <A = unknown, E = unknown>(
 export const asEnqueue = <A, E>(self: Queue<A, E>): Enqueue<A, E> => self
 
 /**
- * Convert a Queue to a Dequeue, allowing only read operations.
+ * Narrows a `Queue` to a `Dequeue`, exposing the consumer side of the queue.
+ *
+ * **When to use**
+ *
+ * Use to pass a queue to code that should consume values while keeping
+ * producer-side operations out of that code's TypeScript type.
+ *
+ * **Gotchas**
+ *
+ * This is a type-level narrowing operation. It returns the same queue object
+ * and does not create a runtime wrapper.
+ *
+ * @see {@link asEnqueue} for narrowing a queue to its producer side
+ * @see {@link Dequeue} for the consumer-side queue handle returned by this function
  *
  * @category converting
  * @since 4.0.0
@@ -483,7 +553,7 @@ export const bounded = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  *
  * **When to use**
  *
- * This strategy prevents producers from being blocked but may result in message loss.
+ * Use when producers should not block and message loss is acceptable.
  * Useful when you want to maintain a rolling window of the most recent messages.
  *
  * **Example** (Creating sliding queues)
@@ -518,7 +588,7 @@ export const sliding = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  *
  * **When to use**
  *
- * This strategy prevents producers from being blocked and preserves existing messages,
+ * Use when producers should not block and existing messages should be preserved,
  * but new messages may be lost when the queue is full.
  *
  * **Example** (Creating dropping queues)
@@ -554,7 +624,7 @@ export const dropping = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  *
  * **When to use**
  *
- * Unlike bounded queues, unbounded queues never apply backpressure - producers
+ * Use when producers should never be blocked; unbounded queues never apply backpressure, so producers
  * can always add messages successfully. This is useful when you want to prioritize
  * producer throughput over memory usage control.
  *
@@ -1551,7 +1621,29 @@ const await_ = <A, E>(self: Dequeue<A, E>): Effect<void, Exclude<E, Done>> =>
 
 export {
   /**
-   * Wait for the queue to be done.
+   * Waits until a queue reaches the `Done` state.
+   *
+   * **When to use**
+   *
+   * Use to suspend a fiber until no further values can be taken from the queue
+   * and its terminal outcome is known.
+   *
+   * **Details**
+   *
+   * The effect succeeds with `void` for normal `Done` completion. Other
+   * terminal causes are preserved, so failures and interruptions complete this
+   * effect with the same terminal outcome.
+   *
+   * **Gotchas**
+   *
+   * A queue can be closing before it is done. `await` resumes at `Done`, not at
+   * the first completion signal, so buffered messages may need to be drained
+   * first.
+   *
+   * @see {@link end} for signaling normal completion while preserving buffered messages for consumers
+   * @see {@link fail} for signaling an error while preserving buffered messages for consumers
+   * @see {@link interrupt} for graceful interruption after buffered messages are drained
+   * @see {@link shutdown} for immediately discarding buffered messages and resuming pending operations
    *
    * @category Completion
    * @since 4.0.0

package/src/Random.ts

@@ -1,15 +1,30 @@
 /**
- * The `Random` module provides a service for generating pseudo-random numbers
- * in Effect programs. It offers a testable and composable way to work with
- * randomness, supporting integers, floating-point numbers, and range-based
- * generation.
- *
- * The default `Random` service is not cryptographically secure. Do not use it
- * for secrets, tokens, UUIDs, session identifiers, or other security-sensitive
- * values. For cryptographically secure random generation, replace the service
- * with a cryptographically secure implementation such as the platform `Crypto`
- * service. `Random.withSeed` also replaces the service, but predictable seeds
- * remain deterministic and must not be treated as cryptographically secure.
+ * Pseudo-random generation through Effect's service context. The module exposes
+ * effectful generators for booleans, doubles, safe integers, bounded numbers,
+ * shuffling, and deterministic seeded runs.
+ *
+ * **Mental model**
+ *
+ * Randomness is read from the current {@link Random} service instead of a
+ * global singleton. That makes random programs reproducible in tests and local
+ * simulations with {@link withSeed}, while still allowing applications to
+ * replace the service at the edge.
+ *
+ * **Common tasks**
+ *
+ * - Draw a floating-point value in `[0, 1)` with {@link next}
+ * - Draw an integer with {@link nextInt} or {@link nextIntBetween}
+ * - Draw a floating-point value in a custom range with {@link nextBetween}
+ * - Randomize an iterable with {@link shuffle}
+ * - Run the same random sequence repeatedly with {@link withSeed}
+ *
+ * **Gotchas**
+ *
+ * - The default service is not suitable for secrets, session identifiers,
+ *   tokens, or other security-sensitive values.
+ * - `withSeed` is deterministic by design. A predictable seed does not make
+ *   generated values cryptographically secure.
+ * - Bounded integer generation rounds bounds before drawing from the range.
  *
  * **Example** (Generating random values)
  *
@@ -18,13 +33,10 @@
  *
  * const program = Effect.gen(function*() {
  *   const randomFloat = yield* Random.next
- *   console.log("Random float:", randomFloat)
- *
  *   const randomInt = yield* Random.nextInt
- *   console.log("Random integer:", randomInt)
- *
  *   const diceRoll = yield* Random.nextIntBetween(1, 6)
- *   console.log("Dice roll:", diceRoll)
+ *
+ *   return { randomFloat, randomInt, diceRoll }
  * })
  * ```
  *
@@ -39,6 +51,11 @@ import * as Predicate from "./Predicate.ts"
 /**
  * Represents a service for generating pseudo-random numbers.
  *
+ * **When to use**
+ *
+ * Use to access or provide the random-number generator service used by Effect
+ * programs.
+ *
  * **Gotchas**
  *
  * The default implementation is based on `Math.random` and is not
@@ -75,6 +92,11 @@ const randomWith = <A>(f: (random: typeof Random["Service"]) => A): Effect.Effec
 /**
  * Generates a random number between 0 (inclusive) and 1 (exclusive).
  *
+ * **When to use**
+ *
+ * Use to generate a pseudo-random floating-point number in the standard
+ * `[0, 1)` range.
+ *
  * **Example** (Generating a random number)
  *
  * ```ts
@@ -94,6 +116,10 @@ export const next: Effect.Effect<number> = randomWith((r) => r.nextDoubleUnsafe(
 /**
  * Generates a random boolean value.
  *
+ * **When to use**
+ *
+ * Use to make a pseudo-random true-or-false choice.
+ *
  * **Example** (Generating a random boolean)
  *
  * ```ts
@@ -114,6 +140,11 @@ export const nextBoolean: Effect.Effect<boolean> = randomWith((r) => r.nextDoubl
  * Generates a random integer between `Number.MIN_SAFE_INTEGER` (inclusive)
  * and `Number.MAX_SAFE_INTEGER` (inclusive).
  *
+ * **When to use**
+ *
+ * Use to generate a pseudo-random safe integer across the full safe-integer
+ * range.
+ *
  * **Example** (Generating a random integer)
  *
  * ```ts
@@ -133,6 +164,10 @@ export const nextInt: Effect.Effect<number> = randomWith((r) => r.nextIntUnsafe(
 /**
  * Generates a random number between `min` (inclusive) and `max` (exclusive).
  *
+ * **When to use**
+ *
+ * Use to generate a pseudo-random floating-point number within a numeric range.
+ *
  * **Example** (Generating a bounded random number)
  *
  * ```ts
@@ -153,6 +188,10 @@ export const nextBetween = (min: number, max: number): Effect.Effect<number> =>
 /**
  * Generates a random integer between `min` and `max`.
  *
+ * **When to use**
+ *
+ * Use to generate a pseudo-random integer within a rounded numeric range.
+ *
  * **Details**
  *
  * The lower bound is rounded up with `Math.ceil` and the upper bound is
@@ -190,6 +229,10 @@ export const nextIntBetween = (min: number, max: number, options?: {
 /**
  * Uses the pseudo-random number generator to shuffle the specified iterable.
  *
+ * **When to use**
+ *
+ * Use to randomly reorder an iterable using the active `Random` service.
+ *
  * **Example** (Shuffling values)
  *
  * ```ts
@@ -219,6 +262,10 @@ export const shuffle = <A>(elements: Iterable<A>): Effect.Effect<Array<A>> =>
 /**
  * Seeds the pseudo-random number generator with the specified value.
  *
+ * **When to use**
+ *
+ * Use to run an effect with a deterministic pseudo-random sequence.
+ *
  * **Details**
  *
  * Using the same seed produces the same random sequence, which is useful for
@@ -255,6 +302,10 @@ export const withSeed: {
   /**
    * Seeds the pseudo-random number generator with the specified value.
    *
+   * **When to use**
+   *
+   * Use to run an effect with a deterministic pseudo-random sequence.
+   *
    * **Details**
    *
    * Using the same seed produces the same random sequence, which is useful for
@@ -291,6 +342,10 @@ export const withSeed: {
   /**
    * Seeds the pseudo-random number generator with the specified value.
    *
+   * **When to use**
+   *
+   * Use to run an effect with a deterministic pseudo-random sequence.
+   *
    * **Details**
    *
    * Using the same seed produces the same random sequence, which is useful for