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

package/src/Crypto.ts

@@ -0,0 +1,327 @@
+/**
+ * The `Crypto` module provides a platform-agnostic service for cryptographic
+ * operations. Runtime packages such as `@effect/platform-node`,
+ * `@effect/platform-bun`, and `@effect/platform-browser` provide concrete
+ * implementations backed by the host platform's cryptography APIs.
+ *
+ * Use `Crypto` for cryptographic randomness, UUID generation, random values,
+ * and message digests. The base `Random` service is not cryptographically
+ * secure unless you replace it with a cryptographically secure implementation.
+ *
+ * **Example** (Providing a test Crypto service)
+ *
+ * ```ts
+ * import { Console, Crypto, Effect, Layer } from "effect"
+ *
+ * const TestCrypto = Layer.succeed(
+ *   Crypto.Crypto,
+ *   Crypto.make({
+ *     randomBytes: (size) => new Uint8Array(size),
+ *     digest: (_algorithm, data) => Effect.succeed(data)
+ *   })
+ * )
+ *
+ * const program = Effect.gen(function*() {
+ *   const crypto = yield* Crypto.Crypto
+ *   const id = yield* crypto.randomUUIDv4
+ *   yield* Console.log(`Created id: ${id}`)
+ * })
+ *
+ * Effect.runPromise(Effect.provide(program, TestCrypto))
+ * ```
+ *
+ * **Example** (Generating random bytes)
+ *
+ * ```ts
+ * import { Crypto, Effect, Layer } from "effect"
+ *
+ * const TestCrypto = Layer.succeed(
+ *   Crypto.Crypto,
+ *   Crypto.make({
+ *     randomBytes: (size) => new Uint8Array(size),
+ *     digest: (_algorithm, data) => Effect.succeed(data)
+ *   })
+ * )
+ *
+ * const program = Effect.gen(function*() {
+ *   const crypto = yield* Crypto.Crypto
+ *   return yield* crypto.randomBytes(32)
+ * })
+ *
+ * Effect.runPromise(Effect.provide(program, TestCrypto))
+ * ```
+ *
+ * @since 4.0.0
+ */
+import * as Context from "./Context.ts"
+import * as Effect from "./Effect.ts"
+import * as PlatformError from "./PlatformError.ts"
+
+const TypeId = "~effect/platform/Crypto"
+
+/**
+ * Digest algorithms supported by the platform `Crypto` service.
+ *
+ * SHA-1 is included for interoperability with existing protocols. Do not use
+ * SHA-1 for new security-sensitive designs.
+ *
+ * **Example** (Using a digest algorithm)
+ *
+ * ```ts
+ * import { Crypto } from "effect"
+ *
+ * const algorithm: Crypto.DigestAlgorithm = "SHA-256"
+ * ```
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type DigestAlgorithm = "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512"
+
+/**
+ * Platform-agnostic cryptographic operations.
+ *
+ * `Crypto` implementations must use cryptographically secure platform APIs.
+ * The random generator helpers are derived by the `make` constructor from
+ * the random methods on this service.
+ *
+ * **Example** (Using cryptographic operations)
+ *
+ * ```ts
+ * import { Crypto, Effect, Layer } from "effect"
+ *
+ * const TestCrypto = Layer.succeed(
+ *   Crypto.Crypto,
+ *   Crypto.make({
+ *     randomBytes: (size) => new Uint8Array(size),
+ *     digest: (_algorithm, data) => Effect.succeed(data)
+ *   })
+ * )
+ *
+ * const program = Effect.gen(function*() {
+ *   const crypto = yield* Crypto.Crypto
+ *   const bytes = yield* crypto.randomBytes(16)
+ *   const uuidv4 = yield* crypto.randomUUIDv4
+ *   const uuidv7 = yield* crypto.randomUUIDv7
+ *   const hash = yield* crypto.digest("SHA-256", bytes)
+ *   return { uuidv4, uuidv7, hash }
+ * })
+ *
+ * Effect.runPromise(Effect.provide(program, TestCrypto))
+ * ```
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface Crypto {
+  readonly [TypeId]: typeof TypeId
+
+  /**
+   * Generates a random integer in the range Number.MIN_SAFE_INTEGER to
+   * Number.MAX_SAFE_INTEGER (both inclusive).
+   */
+  nextIntUnsafe(): number
+
+  /**
+   * Generates a random number in the range 0 (inclusive) to 1 (exclusive).
+   */
+  nextDoubleUnsafe(): number
+
+  /**
+   * Generates cryptographically secure random bytes.
+   */
+  randomBytes(size: number): Effect.Effect<Uint8Array, PlatformError.PlatformError>
+
+  /**
+   * Computes a cryptographic digest for the supplied data.
+   */
+  digest(
+    algorithm: DigestAlgorithm,
+    data: Uint8Array
+  ): Effect.Effect<Uint8Array, PlatformError.PlatformError>
+
+  /**
+   * Generates a cryptographically secure random number between 0 (inclusive)
+   * and 1 (exclusive).
+   */
+  readonly random: Effect.Effect<number>
+
+  /**
+   * Generates a cryptographically secure random boolean.
+   */
+  readonly randomBoolean: Effect.Effect<boolean>
+
+  /**
+   * Generates a cryptographically secure random integer between
+   * `Number.MIN_SAFE_INTEGER` and `Number.MAX_SAFE_INTEGER` (both inclusive).
+   */
+  readonly randomInt: Effect.Effect<number>
+
+  /**
+   * Generates a cryptographically secure random number between `min`
+   * (inclusive) and `max` (exclusive).
+   */
+  randomBetween(min: number, max: number): Effect.Effect<number>
+
+  /**
+   * Generates a cryptographically secure random integer between `min` and `max`.
+   *
+   * The lower bound is rounded up with `Math.ceil` and the upper bound is
+   * rounded down with `Math.floor`. By default the range is inclusive; set
+   * `options.halfOpen: true` to exclude the upper bound.
+   */
+  randomIntBetween(min: number, max: number, options?: {
+    readonly halfOpen?: boolean | undefined
+  }): Effect.Effect<number>
+
+  /**
+   * Uses the cryptographically secure random generator to shuffle the supplied
+   * iterable.
+   */
+  randomShuffle<A>(elements: Iterable<A>): Effect.Effect<Array<A>>
+
+  /**
+   * Generates a cryptographically secure UUIDv4 string.
+   */
+  readonly randomUUIDv4: Effect.Effect<string, PlatformError.PlatformError>
+
+  /**
+   * Generates a cryptographically secure UUIDv7 string.
+   */
+  readonly randomUUIDv7: Effect.Effect<string, PlatformError.PlatformError>
+}
+
+/**
+ * The service identifier for the platform `Crypto` service.
+ *
+ * @category services
+ * @since 4.0.0
+ */
+export const Crypto: Context.Service<Crypto, Crypto> = Context.Service("effect/Crypto")
+
+/**
+ * Creates a `Crypto` service from the primitive implementation, deriving the
+ * random generator helpers and UUID generation from those primitives.
+ *
+ * **Example** (Creating a Crypto service)
+ *
+ * ```ts
+ * import { Crypto, Effect, Layer } from "effect"
+ *
+ * const TestCrypto = Layer.succeed(
+ *   Crypto.Crypto,
+ *   Crypto.make({
+ *     randomBytes: (size) => new Uint8Array(size),
+ *     digest: (_algorithm, data) => Effect.succeed(data)
+ *   })
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const make = (
+  impl: {
+    readonly randomBytes: (size: number) => Uint8Array
+    readonly digest: (
+      algorithm: DigestAlgorithm,
+      data: Uint8Array
+    ) => Effect.Effect<Uint8Array, PlatformError.PlatformError>
+  }
+): Crypto => {
+  const randomBytesUnsafe = impl.randomBytes
+
+  const randomBytes: Crypto["randomBytes"] = (size) => Effect.map(validateSize("randomBytes", size), randomBytesUnsafe)
+
+  const nextDoubleUnsafe = (): number => {
+    const bytes = randomBytesUnsafe(7)
+    const value = ((bytes[0] & 0x1f) * 2 ** 48) + (bytes[1] * 2 ** 40) + (bytes[2] * 2 ** 32) +
+      (bytes[3] * 2 ** 24) + (bytes[4] * 2 ** 16) + (bytes[5] * 2 ** 8) + bytes[6]
+    return value / 2 ** 53
+  }
+
+  const nextIntUnsafe = (): number =>
+    Math.floor(nextDoubleUnsafe() * (Number.MAX_SAFE_INTEGER - Number.MIN_SAFE_INTEGER + 1)) + Number.MIN_SAFE_INTEGER
+
+  return Crypto.of({
+    [TypeId]: TypeId,
+    randomBytes,
+    nextDoubleUnsafe,
+    nextIntUnsafe,
+    digest: impl.digest,
+    random: Effect.sync(() => nextDoubleUnsafe()),
+    randomBoolean: Effect.sync(() => nextDoubleUnsafe() > 0.5),
+    randomInt: Effect.sync(() => nextIntUnsafe()),
+    randomBetween: (min, max) => Effect.sync(() => nextDoubleUnsafe() * (max - min) + min),
+    randomIntBetween(min, max, options) {
+      const extra = options?.halfOpen === true ? 0 : 1
+      return Effect.sync(() => {
+        const minInt = Math.ceil(min)
+        const maxInt = Math.floor(max)
+        return Math.floor(nextDoubleUnsafe() * (maxInt - minInt + extra)) + minInt
+      })
+    },
+    randomShuffle: (elements) =>
+      Effect.sync(() => {
+        const buffer = Array.from(elements)
+        for (let i = buffer.length - 1; i >= 1; i = i - 1) {
+          const index = Math.min(i, Math.floor(nextDoubleUnsafe() * (i + 1)))
+          const value = buffer[i]!
+          buffer[i] = buffer[index]!
+          buffer[index] = value
+        }
+        return buffer
+      }),
+    randomUUIDv4: Effect.sync(() => formatUUIDv4(randomBytesUnsafe(16))),
+    randomUUIDv7: Effect.clockWith((clock) =>
+      Effect.succeed(formatUUIDv7(clock.currentTimeMillisUnsafe(), randomBytesUnsafe(16)))
+    )
+  })
+}
+
+const validateSize = (method: string, size: number): Effect.Effect<number, PlatformError.PlatformError> =>
+  Number.isSafeInteger(size) && size >= 0
+    ? Effect.succeed(size)
+    : Effect.fail(PlatformError.badArgument({
+      module: "Crypto",
+      method,
+      description: "size must be a non-negative safe integer"
+    }))
+
+const hex = (byte: number): string => byte.toString(16).padStart(2, "0")
+
+const formatUUID = (bytes: Uint8Array): string => {
+  const segments = [
+    bytes.subarray(0, 4),
+    bytes.subarray(4, 6),
+    bytes.subarray(6, 8),
+    bytes.subarray(8, 10),
+    bytes.subarray(10, 16)
+  ]
+
+  return segments.map((segment) => Array.from(segment, hex).join("")).join("-")
+}
+
+const formatUUIDv4 = (bytes: Uint8Array): string => {
+  bytes[6] = (bytes[6] & 0x0f) | 0x40
+  bytes[8] = (bytes[8] & 0x3f) | 0x80
+
+  return formatUUID(bytes)
+}
+
+const maxUUIDv7Timestamp = 2 ** 48 - 1
+
+const formatUUIDv7 = (timestampMillis: number, bytes: Uint8Array): string => {
+  const timestamp = Math.min(Math.max(0, Math.trunc(timestampMillis)), maxUUIDv7Timestamp)
+
+  bytes[0] = Math.floor(timestamp / 2 ** 40)
+  bytes[1] = Math.floor(timestamp / 2 ** 32) & 0xff
+  bytes[2] = Math.floor(timestamp / 2 ** 24) & 0xff
+  bytes[3] = Math.floor(timestamp / 2 ** 16) & 0xff
+  bytes[4] = Math.floor(timestamp / 2 ** 8) & 0xff
+  bytes[5] = timestamp & 0xff
+  bytes[6] = (bytes[6] & 0x0f) | 0x70
+  bytes[8] = (bytes[8] & 0x3f) | 0x80
+
+  return formatUUID(bytes)
+}

package/src/Data.ts

@@ -229,7 +229,6 @@ type UntaggedChildren<A> = true extends ChildrenAreTagged<A>
  *   values ({@link TaggedEnum.Value})
  * - Full constructor objects ({@link TaggedEnum.Constructor})
  *
- * @category types
  * @since 2.0.0
  */
 export declare namespace TaggedEnum {
@@ -267,6 +266,7 @@ export declare namespace TaggedEnum {
    * @see {@link Kind} — apply concrete types to a `WithGenerics` definition
    * @see {@link taggedEnum} — runtime constructors
    *
+   * @category models
    * @since 2.0.0
    */
   export interface WithGenerics<Count extends number> {
@@ -306,6 +306,7 @@ export declare namespace TaggedEnum {
    *
    * @see {@link WithGenerics} — define the generic shape
    *
+   * @category utility types
    * @since 2.0.0
    */
   export type Kind<
@@ -345,6 +346,7 @@ export declare namespace TaggedEnum {
    *
    * @see {@link Value} — extracts the full variant type (including `_tag`)
    *
+   * @category utility types
    * @since 2.0.0
    */
   export type Args<
@@ -374,6 +376,7 @@ export declare namespace TaggedEnum {
    *
    * @see {@link Args} — extracts fields without `_tag`
    *
+   * @category utility types
    * @since 2.0.0
    */
   export type Value<
@@ -460,6 +463,7 @@ export declare namespace TaggedEnum {
    * The constructor returns the full variant type `A`. If no fields remain
    * after excluding `Tag` keys, the constructor argument type becomes `void`.
    *
+   * @category utility types
    * @since 4.0.0
    */
   export type ConstructorFrom<A, Tag extends keyof A = never> = (
@@ -474,6 +478,7 @@ export declare namespace TaggedEnum {
    *
    * @see {@link Constructor} — the non-generic equivalent
    *
+   * @category models
    * @since 3.2.0
    */
   export interface GenericMatchers<Z extends WithGenerics<number>> {

package/src/DateTime.ts

@@ -114,7 +114,6 @@ export interface Zoned extends DateTime.Proto {
  * Companion namespace containing the public helper types used by `DateTime`
  * constructors, parts APIs, formatting, and date/time arithmetic.
  *
- * @category models
  * @since 3.6.0
  */
 export declare namespace DateTime {
@@ -299,7 +298,6 @@ export type TimeZone = TimeZone.Offset | TimeZone.Named
  * Companion namespace containing the public variant and protocol types for
  * `TimeZone`.
  *
- * @category models
  * @since 3.6.0
  */
 export declare namespace TimeZone {
@@ -610,7 +608,7 @@ export const clamp: {
  * ```
  *
  * @category constructors
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const fromDateUnsafe: (date: Date) => Utc = Internal.fromDateUnsafe
 
@@ -642,7 +640,7 @@ export const fromDateUnsafe: (date: Date) => Utc = Internal.fromDateUnsafe
  * ```
  *
  * @category constructors
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const makeUnsafe: <A extends DateTime.Input>(input: A) => DateTime.PreserveZone<A> = Internal.makeUnsafe
 
@@ -673,7 +671,7 @@ export const makeUnsafe: <A extends DateTime.Input>(input: A) => DateTime.Preser
  * ```
  *
  * @category constructors
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const makeZonedUnsafe: (input: DateTime.Input, options?: {
   readonly timeZone?: number | string | TimeZone | undefined
@@ -830,7 +828,7 @@ export const now: Effect.Effect<Utc> = Internal.now
  * ```
  *
  * @category constructors
- * @since 3.6.0
+ * @since 3.14.0
  */
 export const nowAsDate: Effect.Effect<Date> = Internal.nowAsDate
 
@@ -850,7 +848,7 @@ export const nowAsDate: Effect.Effect<Date> = Internal.nowAsDate
  * ```
  *
  * @category constructors
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const nowUnsafe: LazyArg<Utc> = Internal.nowUnsafe
 
@@ -1059,7 +1057,7 @@ export const setZoneOffset: {
  * ```
  *
  * @category time zones
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const zoneMakeNamedUnsafe: (zoneId: string) => TimeZone.Named = Internal.zoneMakeNamedUnsafe
 
@@ -1288,7 +1286,7 @@ export const setZoneNamed: {
  * ```
  *
  * @category time zones
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const setZoneNamedUnsafe: {
   /**
@@ -1308,7 +1306,7 @@ export const setZoneNamedUnsafe: {
    * ```
    *
    * @category time zones
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (
    zoneId: string,
@@ -1334,7 +1332,7 @@ export const setZoneNamedUnsafe: {
    * ```
    *
    * @category time zones
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (
    self: DateTime,
@@ -1572,7 +1570,7 @@ export const max: {
  * ```
  *
  * @category comparisons
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const isGreaterThan: {
   /**
@@ -1591,7 +1589,7 @@ export const isGreaterThan: {
    * ```
    *
    * @category comparisons
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (that: DateTime): (self: DateTime) => boolean
   /**
@@ -1610,7 +1608,7 @@ export const isGreaterThan: {
    * ```
    *
    * @category comparisons
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (self: DateTime, that: DateTime): boolean
 } = Internal.isGreaterThan
@@ -1633,7 +1631,7 @@ export const isGreaterThan: {
  * ```
  *
  * @category comparisons
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const isGreaterThanOrEqualTo: {
   /**
@@ -1654,7 +1652,7 @@ export const isGreaterThanOrEqualTo: {
    * ```
    *
    * @category comparisons
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (that: DateTime): (self: DateTime) => boolean
   /**
@@ -1675,7 +1673,7 @@ export const isGreaterThanOrEqualTo: {
    * ```
    *
    * @category comparisons
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (self: DateTime, that: DateTime): boolean
 } = Internal.isGreaterThanOrEqualTo
@@ -1696,7 +1694,7 @@ export const isGreaterThanOrEqualTo: {
  * ```
  *
  * @category comparisons
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const isLessThan: {
   /**
@@ -1715,7 +1713,7 @@ export const isLessThan: {
    * ```
    *
    * @category comparisons
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (that: DateTime): (self: DateTime) => boolean
   /**
@@ -1734,7 +1732,7 @@ export const isLessThan: {
    * ```
    *
    * @category comparisons
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (self: DateTime, that: DateTime): boolean
 } = Internal.isLessThan
@@ -1757,7 +1755,7 @@ export const isLessThan: {
  * ```
  *
  * @category comparisons
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const isLessThanOrEqualTo: {
   /**
@@ -1778,7 +1776,7 @@ export const isLessThanOrEqualTo: {
    * ```
    *
    * @category comparisons
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (that: DateTime): (self: DateTime) => boolean
   /**
@@ -1799,7 +1797,7 @@ export const isLessThanOrEqualTo: {
    * ```
    *
    * @category comparisons
-   * @since 3.6.0
+   * @since 4.0.0
    */
   (self: DateTime, that: DateTime): boolean
 } = Internal.isLessThanOrEqualTo
@@ -1903,7 +1901,7 @@ export const isFuture: (self: DateTime) => Effect.Effect<boolean> = Internal.isF
  * ```
  *
  * @category comparisons
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const isFutureUnsafe: (self: DateTime) => boolean = Internal.isFutureUnsafe
 
@@ -1947,7 +1945,7 @@ export const isPast: (self: DateTime) => Effect.Effect<boolean> = Internal.isPas
  * ```
  *
  * @category comparisons
- * @since 3.6.0
+ * @since 4.0.0
  */
 export const isPastUnsafe: (self: DateTime) => boolean = Internal.isPastUnsafe
 
@@ -1973,7 +1971,7 @@ export const isPastUnsafe: (self: DateTime) => boolean = Internal.isPastUnsafe
  * console.log(utcDate.toISOString()) // "2024-01-01T12:00:00.000Z"
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 3.6.0
  */
 export const toDateUtc: (self: DateTime) => Date = Internal.toDateUtc
@@ -1998,7 +1996,7 @@ export const toDateUtc: (self: DateTime) => Date = Internal.toDateUtc
  * console.log(DateTime.toDate(zoned).toISOString())
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 3.6.0
  */
 export const toDate: (self: DateTime) => Date = Internal.toDate
@@ -2022,7 +2020,7 @@ export const toDate: (self: DateTime) => Date = Internal.toDate
  * console.log(offset) // 0 (London is UTC+0 in winter)
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 3.6.0
  */
 export const zonedOffset: (self: Zoned) => number = Internal.zonedOffset
@@ -2045,7 +2043,7 @@ export const zonedOffset: (self: Zoned) => number = Internal.zonedOffset
  * console.log(offsetString) // "+03:00"
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 3.6.0
  */
 export const zonedOffsetIso: (self: Zoned) => string = Internal.zonedOffsetIso
@@ -2066,7 +2064,7 @@ export const zonedOffsetIso: (self: Zoned) => string = Internal.zonedOffsetIso
  * console.log(epochMillis) // 1704067200000
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 3.6.0
  */
 export const toEpochMillis: (self: DateTime) => number = Internal.toEpochMillis
@@ -2090,7 +2088,7 @@ export const toEpochMillis: (self: DateTime) => number = Internal.toEpochMillis
  * )
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 3.6.0
  */
 export const removeTime: (self: DateTime) => Utc = Internal.removeTime