effect 4.0.0-beta.67 → 4.0.0-beta.68

package/src/Queue.ts

@@ -76,8 +76,8 @@ const DequeueTypeId = "~effect/Queue/Dequeue"
 /**
  * Type guard to check if a value is a Queue.
  *
- * @category Guards
- * @since 3.8.0
+ * @category guards
+ * @since 2.0.0
  */
 export const isQueue = <A = unknown, E = unknown>(
   u: unknown
@@ -86,8 +86,8 @@ export const isQueue = <A = unknown, E = unknown>(
 /**
  * Type guard to check if a value is an Enqueue.
  *
- * @category Guards
- * @since 4.0.0
+ * @category guards
+ * @since 2.0.0
  */
 export const isEnqueue = <A = unknown, E = unknown>(
   u: unknown
@@ -96,8 +96,8 @@ export const isEnqueue = <A = unknown, E = unknown>(
 /**
  * Type guard to check if a value is a Dequeue.
  *
- * @category Guards
- * @since 4.0.0
+ * @category guards
+ * @since 2.0.0
  */
 export const isDequeue = <A = unknown, E = unknown>(
   u: unknown
@@ -106,7 +106,7 @@ export const isDequeue = <A = unknown, E = unknown>(
 /**
  * Converts a Queue to an Enqueue (write-only interface).
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const asEnqueue = <A, E>(self: Queue<A, E>): Enqueue<A, E> => self
@@ -114,7 +114,7 @@ export const asEnqueue = <A, E>(self: Queue<A, E>): Enqueue<A, E> => self
 /**
  * Convert a Queue to a Dequeue, allowing only read operations.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const asDequeue: <A, E>(self: Queue<A, E>) => Dequeue<A, E> = identity
@@ -143,8 +143,8 @@ export const asDequeue: <A, E>(self: Queue<A, E>) => Dequeue<A, E> = identity
  * })
  * ```
  *
- * @category Models
- * @since 4.0.0
+ * @category models
+ * @since 2.0.0
  */
 export interface Enqueue<in A, in E = never> extends Inspectable {
   readonly [EnqueueTypeId]: Enqueue.Variance<A, E>
@@ -160,8 +160,7 @@ export interface Enqueue<in A, in E = never> extends Inspectable {
  * Companion namespace containing type-level metadata for the `Enqueue`
  * write-only queue interface.
  *
- * @category Models
- * @since 4.0.0
+ * @since 2.0.0
  */
 export declare namespace Enqueue {
   /**
@@ -171,7 +170,7 @@ export declare namespace Enqueue {
    * type `E`, because values and failures flow into the queue through this
    * handle.
    *
-   * @category Models
+   * @category models
    * @since 4.0.0
    */
   export interface Variance<A, E> {
@@ -206,8 +205,8 @@ export declare namespace Enqueue {
  * })
  * ```
  *
- * @category Models
- * @since 3.8.0
+ * @category models
+ * @since 2.0.0
  */
 export interface Dequeue<out A, out E = never> extends Inspectable {
   readonly [DequeueTypeId]: Dequeue.Variance<A, E>
@@ -223,8 +222,7 @@ export interface Dequeue<out A, out E = never> extends Inspectable {
  * Companion namespace containing type-level metadata for the `Dequeue`
  * read-only queue interface.
  *
- * @category Models
- * @since 4.0.0
+ * @since 2.0.0
  */
 export declare namespace Dequeue {
   /**
@@ -233,8 +231,8 @@ export declare namespace Dequeue {
    * `Dequeue` is covariant in both the taken value type `A` and failure type
    * `E`, because values and failures are observed through this handle.
    *
-   * @category Models
-   * @since 3.8.0
+   * @category models
+   * @since 4.0.0
    */
   export interface Variance<A, E> {
     _A: Types.Covariant<A>
@@ -247,12 +245,6 @@ export declare namespace Dequeue {
  *
  * It also supports signaling that it is done or failed.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Mailbox`
- *
  * **Example** (Offering and taking queue values)
  *
  * ```ts
@@ -275,8 +267,8 @@ export declare namespace Dequeue {
  * })
  * ```
  *
- * @category Models
- * @since 3.8.0
+ * @category models
+ * @since 2.0.0
  */
 export interface Queue<in out A, in out E = never> extends Enqueue<A, E>, Dequeue<A, E> {
   readonly [TypeId]: Queue.Variance<A, E>
@@ -286,8 +278,7 @@ export interface Queue<in out A, in out E = never> extends Enqueue<A, E>, Dequeu
  * Companion namespace containing type-level metadata and low-level state types
  * for `Queue`.
  *
- * @category Models
- * @since 3.8.0
+ * @since 2.0.0
  */
 export declare namespace Queue {
   /**
@@ -296,8 +287,8 @@ export declare namespace Queue {
    * A full `Queue` is invariant in both `A` and `E` because the same handle can
    * both produce and consume values and failures.
    *
-   * @category Models
-   * @since 3.8.0
+   * @category models
+   * @since 4.0.0
    */
   export interface Variance<A, E> {
     _A: Types.Invariant<A>
@@ -312,7 +303,7 @@ export declare namespace Queue {
    * This is low-level metadata exposed by the queue model; most users should
    * inspect queues through the public operations.
    *
-   * @category Models
+   * @category models
    * @since 4.0.0
    */
   export type State<A, E> =
@@ -341,7 +332,7 @@ export declare namespace Queue {
    * remaining messages, plus a resume callback that completes the suspended
    * offer when the queue can accept more input.
    *
-   * @category Models
+   * @category models
    * @since 4.0.0
    */
   export type OfferEntry<A> =
@@ -384,14 +375,6 @@ const QueueProto = {
  * `"sliding"` to control what happens when the queue is full. The returned
  * queue can be offered to, taken from, failed, ended, interrupted, or shut down.
  *
- * **Previously Known As**
- *
- * This API replaces the following from Effect 3.x:
- *
- * - `Mailbox.make`
- *
- * @category Constructors
- * @since 3.8.0
  * **Example** (Creating queues)
  *
  * ```ts
@@ -420,6 +403,9 @@ const QueueProto = {
  *   console.log(failed) // true
  * })
  * ```
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const make = <A, E = never>(
   options?: {
@@ -466,7 +452,7 @@ export const make = <A, E = never>(
  * })
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 2.0.0
  */
 export const bounded = <A, E = never>(capacity: number): Effect<Queue<A, E>> => make({ capacity })
@@ -499,7 +485,7 @@ export const bounded = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  * })
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 2.0.0
  */
 export const sliding = <A, E = never>(capacity: number): Effect<Queue<A, E>> => make({ capacity, strategy: "sliding" })
@@ -533,7 +519,7 @@ export const sliding = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  * })
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 2.0.0
  */
 export const dropping = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
@@ -569,7 +555,7 @@ export const dropping = <A, E = never>(capacity: number): Effect<Queue<A, E>> =>
  * })
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 2.0.0
  */
 export const unbounded = <A, E = never>(): Effect<Queue<A, E>> => make()
@@ -601,7 +587,7 @@ export const unbounded = <A, E = never>(): Effect<Queue<A, E>> => make()
  * ```
  *
  * @category Offering
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const offer = <A, E>(self: Enqueue<A, E>, message: Types.NoInfer<A>): Effect<boolean> =>
   internalEffect.suspend(() => {
@@ -701,7 +687,7 @@ export const offerUnsafe = <A, E>(self: Enqueue<A, E>, message: Types.NoInfer<A>
  * ```
  *
  * @category Offering
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const offerAll = <A, E>(self: Enqueue<A, E>, messages: Iterable<A>): Effect<Array<A>> =>
   internalEffect.suspend(() => {
@@ -899,8 +885,7 @@ export const failCause: {
  * **Example** (Failing queues with a cause synchronously)
  *
  * ```ts
- * import { Effect, Cause } from "effect"
- * import { Queue } from "effect"
+ * import { Cause, Effect, Queue } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const queue = yield* Queue.bounded<number, string>(10)
@@ -1086,7 +1071,7 @@ export const interrupt = <A, E>(self: Enqueue<A, E>): Effect<boolean> =>
  * ```
  *
  * @category Completion
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const shutdown = <A, E>(self: Enqueue<A, E>): Effect<boolean> =>
   internalEffect.sync(() => {
@@ -1185,7 +1170,7 @@ export const clear = <A, E>(self: Dequeue<A, E>): Effect<Array<A>, Pull.ExcludeD
  * ```
  *
  * @category Taking
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const takeAll = <A, E>(self: Dequeue<A, E>): Effect<Arr.NonEmptyArray<A>, E> =>
   takeBetween(self, 1, Number.POSITIVE_INFINITY) as any
@@ -1271,7 +1256,7 @@ export const collect = <A, E>(self: Dequeue<A, E | Done>): Effect<Array<A>, Pull
  * ```
  *
  * @category Taking
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const takeN = <A, E>(
   self: Dequeue<A, E>,
@@ -1313,7 +1298,7 @@ export const takeN = <A, E>(
  * ```
  *
  * @category Taking
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const takeBetween = <A, E>(
   self: Dequeue<A, E>,
@@ -1361,7 +1346,7 @@ export const takeBetween = <A, E>(
  * ```
  *
  * @category Taking
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const take = <A, E>(self: Dequeue<A, E>): Effect<A, E> =>
   internalEffect.suspend(
@@ -1399,7 +1384,7 @@ export const take = <A, E>(self: Dequeue<A, E>): Effect<A, E> =>
  * ```
  *
  * @category Taking
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const poll = <A, E>(self: Dequeue<A, E>): Effect<Option.Option<A>> =>
   internalEffect.suspend(() => {
@@ -1566,7 +1551,7 @@ export {
  * ```
  *
  * @category Size
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const size = <A, E>(self: Dequeue<A, E>): Effect<number> => internalEffect.sync(() => sizeUnsafe(self))
 
@@ -1591,7 +1576,7 @@ export const size = <A, E>(self: Dequeue<A, E>): Effect<number> => internalEffec
  * ```
  *
  * @category Size
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const isFull = <A, E>(self: Dequeue<A, E>): Effect<boolean> => internalEffect.sync(() => isFullUnsafe(self))
 
@@ -1695,7 +1680,7 @@ export const isFullUnsafe = <A, E>(self: Dequeue<A, E>): boolean => sizeUnsafe(s
  * ```
  *
  * @category Completion
- * @since 3.8.0
+ * @since 4.0.0
  */
 export const into: {
   /**
@@ -1730,7 +1715,7 @@ export const into: {
    * ```
    *
    * @category Completion
-   * @since 3.8.0
+   * @since 4.0.0
    */
   <A, E>(self: Enqueue<A, E | Done>): <AX, EX extends E, RX>(
     effect: Effect<AX, EX, RX>
@@ -1767,7 +1752,7 @@ export const into: {
    * ```
    *
    * @category Completion
-   * @since 3.8.0
+   * @since 4.0.0
    */
   <AX, E, EX extends E, RX, A>(effect: Effect<AX, EX, RX>, self: Enqueue<A, E | Done>): Effect<boolean, never, RX>
 } = dual(

package/src/Random.ts

@@ -1,7 +1,15 @@
 /**
- * The Random module provides a service for generating 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 `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.
  *
  * **Example** (Generating random values)
  *
@@ -29,7 +37,11 @@ import * as random from "./internal/random.ts"
 import * as Predicate from "./Predicate.ts"
 
 /**
- * Represents a service for generating random numbers.
+ * Represents a service for generating pseudo-random numbers.
+ *
+ * The default implementation is based on `Math.random` and is not
+ * cryptographically secure. Replace the service with a cryptographically secure
+ * implementation before using these generators for security-sensitive values.
  *
  * **Example** (Accessing the random service)
  *
@@ -40,17 +52,15 @@ import * as Predicate from "./Predicate.ts"
  *   const float = yield* Random.next
  *   const integer = yield* Random.nextInt
  *   const inRange = yield* Random.nextIntBetween(1, 100)
- *   const uuid = yield* Random.nextUUIDv4
  *
  *   console.log("Float:", float)
  *   console.log("Integer:", integer)
  *   console.log("In range:", inRange)
- *   console.log("UUID:", uuid)
  * })
  * ```
  *
  * @category Random Number Generators
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const Random: Context.Reference<{
   nextIntUnsafe(): number
@@ -61,7 +71,7 @@ const randomWith = <A>(f: (random: typeof Random["Service"]) => A): Effect.Effec
   Effect.withFiber((fiber) => Effect.succeed(f(fiber.getRef(Random))))
 
 /**
- * Generates a random number between 0 (inclusive) and 1 (inclusive).
+ * Generates a random number between 0 (inclusive) and 1 (exclusive).
  *
  * **Example** (Generating a random number)
  *
@@ -75,7 +85,7 @@ const randomWith = <A>(f: (random: typeof Random["Service"]) => A): Effect.Effec
  * ```
  *
  * @category Random Number Generators
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const next: Effect.Effect<number> = randomWith((r) => r.nextDoubleUnsafe())
 
@@ -94,7 +104,7 @@ export const next: Effect.Effect<number> = randomWith((r) => r.nextDoubleUnsafe(
  * ```
  *
  * @category Random Number Generators
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const nextBoolean: Effect.Effect<boolean> = randomWith((r) => r.nextDoubleUnsafe() > 0.5)
 
@@ -114,12 +124,12 @@ export const nextBoolean: Effect.Effect<boolean> = randomWith((r) => r.nextDoubl
  * ```
  *
  * @category Random Number Generators
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const nextInt: Effect.Effect<number> = randomWith((r) => r.nextIntUnsafe())
 
 /**
- * Generates a random number between `min` (inclusive) and `max` (inclusive).
+ * Generates a random number between `min` (inclusive) and `max` (exclusive).
  *
  * **Example** (Generating a bounded random number)
  *
@@ -160,7 +170,7 @@ export const nextBetween = (min: number, max: number): Effect.Effect<number> =>
  * ```
  *
  * @category Random Number Generators
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const nextIntBetween = (min: number, max: number, options?: {
   readonly halfOpen?: boolean
@@ -188,7 +198,7 @@ export const nextIntBetween = (min: number, max: number, options?: {
  * ```
  *
  * @category Random Number Generators
- * @since 4.0.0
+ * @since 2.0.0
  */
 export const shuffle = <A>(elements: Iterable<A>): Effect.Effect<Array<A>> =>
   randomWith((r) => {
@@ -203,51 +213,7 @@ export const shuffle = <A>(elements: Iterable<A>): Effect.Effect<Array<A>> =>
   })
 
 /**
- * Generates a random UUID (v4) string.
- *
- * **Example** (Generating a UUID)
- *
- * ```ts
- * import { Effect, Random } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const uuid = yield* Random.nextUUIDv4
- *   console.log("UUID:", uuid)
- * })
- * ```
- *
- * @category Random Number Generators
- * @since 4.0.0
- */
-export const nextUUIDv4: Effect.Effect<string> = randomWith((r) => {
-  // Generate 16 random bytes (128 bits) for UUID
-  const bytes: Array<number> = []
-  for (let i = 0; i < 16; i++) {
-    // Get unsigned byte [0, 255] from nextInt (signed 32-bit)
-    bytes.push((r.nextIntUnsafe() >>> 0) & 0xFF)
-  }
-
-  // Set version to 4 (bits 12-15 of time_hi_and_version)
-  bytes[6] = (bytes[6] & 0x0F) | 0x40
-
-  // Set variant to RFC 4122 (bits 6-7 of clock_seq_hi_and_reserved)
-  bytes[8] = (bytes[8] & 0x3F) | 0x80
-
-  // Format as UUID string: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
-  const hex = (n: number) => n.toString(16).padStart(2, "0")
-
-  return [
-    bytes.slice(0, 4).map(hex).join(""),
-    bytes.slice(4, 6).map(hex).join(""),
-    bytes.slice(6, 8).map(hex).join(""),
-    bytes.slice(8, 10).map(hex).join(""),
-    bytes.slice(10, 16).map(hex).join("")
-  ].join("-")
-})
-
-/**
- * Runs an effect with a pseudorandom number generator initialized from the
- * specified seed.
+ * Seeds the pseudo-random number generator with the specified value.
  *
  * Using the same seed produces the same random sequence, which is useful for
  * tests and reproducible simulations. Use an unpredictable seed when uniqueness
@@ -278,8 +244,7 @@ export const nextUUIDv4: Effect.Effect<string> = randomWith((r) => {
  */
 export const withSeed: {
   /**
-   * Runs an effect with a pseudorandom number generator initialized from the
-   * specified seed.
+   * Seeds the pseudo-random number generator with the specified value.
    *
    * Using the same seed produces the same random sequence, which is useful for
    * tests and reproducible simulations. Use an unpredictable seed when uniqueness
@@ -310,8 +275,7 @@ export const withSeed: {
    */
   (seed: string | number): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
   /**
-   * Runs an effect with a pseudorandom number generator initialized from the
-   * specified seed.
+   * Seeds the pseudo-random number generator with the specified value.
    *
    * Using the same seed produces the same random sequence, which is useful for
    * tests and reproducible simulations. Use an unpredictable seed when uniqueness
@@ -550,7 +514,7 @@ function ISAAC_CSPRNG(userSeed?: string | number) {
   }
 
   /**
-   * Returns a signed, random integer in the range [-2^31, 2^31].
+   * Returns a signed, random integer in the range [-2^31, 2^31).
    */
   function nextInt32(): number {
     if (!generation--) {
@@ -561,15 +525,8 @@ function ISAAC_CSPRNG(userSeed?: string | number) {
   }
 
   function nextIntUnsafe(): number {
-    // Get 32 bits (unsigned)
-    const low = nextInt32() >>> 0 // [0, 2^32-1]
-
-    // Get 21 more bits for a total of 53
-    const high = nextInt32() & 0x1FFFFF // [0, 2^21-1]
-
-    // Combine: high bits * 2^32 + low bits, then shift to signed range
-    // This gives [0, 2^53-1], subtract 2^52 to center around 0
-    return (high * 0x100000000) + low - 0x10000000000000
+    return Math.floor(nextDoubleUnsafe() * (Number.MAX_SAFE_INTEGER - Number.MIN_SAFE_INTEGER + 1)) +
+      Number.MIN_SAFE_INTEGER
   }
 
   /**
@@ -582,7 +539,7 @@ function ISAAC_CSPRNG(userSeed?: string | number) {
     // 53-bit integer
     const combined = hi * 4294967296 + lo
 
-    return combined / 9007199254740991 // [0, 1)
+    return combined / 0x20000000000000 // [0, 1)
   }
 
   return { nextIntUnsafe, nextDoubleUnsafe }

package/src/RcMap.ts

@@ -83,7 +83,7 @@ export interface RcMap<in out K, in out A, in out E = never> extends Pipeable {
 /**
  * Represents the internal state of an RcMap, which can be either Open (active)
  * or Closed (shutdown and no longer accepting operations).
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export type State<K, A, E> = State.Open<K, A, E> | State.Closed
@@ -97,7 +97,7 @@ export declare namespace State {
   /**
    * Represents the open/active state of an RcMap, containing the actual
    * resource map that stores entries.
-   * @category Models
+   * @category models
    * @since 4.0.0
    */
   export interface Open<K, A, E> {
@@ -108,7 +108,7 @@ export declare namespace State {
   /**
    * Represents the closed state of an RcMap, indicating that the map has been
    * shut down and will no longer accept new operations.
-   * @category Models
+   * @category models
    * @since 4.0.0
    */
   export interface Closed {
@@ -118,7 +118,7 @@ export declare namespace State {
   /**
    * Represents an individual entry in the RcMap, containing the resource's
    * metadata including reference count, expiration time, and lifecycle management.
-   * @category Models
+   * @category models
    * @since 4.0.0
    */
   export interface Entry<A, E> {
@@ -544,7 +544,7 @@ const release = <K, A, E>(self: RcMap<K, A, E>, key: K, entry: State.Entry<A, E>
  * ```
  *
  * @category combinators
- * @since 3.5.0
+ * @since 3.8.0
  */
 export const keys = <K, A, E>(self: RcMap<K, A, E>): Effect.Effect<Iterable<K>> => {
   return Effect.suspend(() =>
@@ -583,7 +583,7 @@ export const keys = <K, A, E>(self: RcMap<K, A, E>): Effect.Effect<Iterable<K>>
  * ```
  *
  * @category combinators
- * @since 3.5.0
+ * @since 3.13.0
  */
 export const invalidate: {
   /**
@@ -617,7 +617,7 @@ export const invalidate: {
    * ```
    *
    * @category combinators
-   * @since 3.5.0
+   * @since 3.13.0
    */
   <K>(key: K): <A, E>(self: RcMap<K, A, E>) => Effect.Effect<void>
   /**
@@ -651,7 +651,7 @@ export const invalidate: {
    * ```
    *
    * @category combinators
-   * @since 3.5.0
+   * @since 3.13.0
    */
   <K, A, E>(self: RcMap<K, A, E>, key: K): Effect.Effect<void>
 } = dual(
@@ -749,7 +749,7 @@ export const has: {
  * ```
  *
  * @category combinators
- * @since 3.5.0
+ * @since 3.13.0
  */
 export const touch: {
   /**
@@ -785,7 +785,7 @@ export const touch: {
    * ```
    *
    * @category combinators
-   * @since 3.5.0
+   * @since 3.13.0
    */
   <K>(key: K): <A, E>(self: RcMap<K, A, E>) => Effect.Effect<void>
   /**
@@ -821,7 +821,7 @@ export const touch: {
    * ```
    *
    * @category combinators
-   * @since 3.5.0
+   * @since 3.13.0
    */
   <K, A, E>(self: RcMap<K, A, E>, key: K): Effect.Effect<void>
 } = dual(

package/src/RcRef.ts

@@ -79,7 +79,6 @@ export interface RcRef<out A, out E = never> extends Pipeable {
  * type MyVariance = RcRef.RcRef.Variance<string, Error>
  * ```
  *
- * @category models
  * @since 3.5.0
  */
 export declare namespace RcRef {