effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/Cron.ts

@@ -1,4 +1,46 @@
 /**
+ * The `Cron` module provides utilities for representing recurring calendar
+ * schedules with cron expressions. A `Cron` value stores allowed seconds,
+ * minutes, hours, days of month, months, weekdays, and an optional time zone,
+ * then uses those constraints to test dates and find scheduled occurrences.
+ *
+ * **Mental model**
+ *
+ * - A cron schedule is a set of allowed values for each time field
+ * - Expressions may use five fields (`minute hour day month weekday`) or six
+ *   fields (`second minute hour day month weekday`); five-field expressions
+ *   default seconds to `0`
+ * - Each field supports `*`, comma-separated values, ranges, and step syntax
+ * - Month and weekday fields support aliases such as `JAN`, `DEC`, `SUN`, and
+ *   `MON`
+ * - Empty internal field sets represent an unconstrained field, the same idea
+ *   as `*`
+ * - When both day-of-month and weekday are constrained, matching uses cron's
+ *   inclusive behavior: either field may match
+ *
+ * **Common tasks**
+ *
+ * - Build directly from field constraints: {@link make}
+ * - Parse expressions safely: {@link parse}
+ * - Parse expressions and throw on invalid input: {@link parseUnsafe}
+ * - Check whether a date satisfies a schedule: {@link match}
+ * - Find adjacent scheduled dates: {@link next}, {@link prev}
+ * - Iterate future scheduled dates: {@link sequence}
+ * - Compare schedule constraints: {@link equals}, {@link Equivalence}
+ * - Detect parse failures: {@link CronParseError}, {@link isCronParseError}
+ *
+ * **Gotchas**
+ *
+ * - Weekdays are numbered `0` through `6`, with `0` representing Sunday
+ * - Months are numbered `1` through `12`, while JavaScript `Date` months are
+ *   zero-based
+ * - `*` normalizes to an empty set internally, so inspect schedules with the
+ *   public helpers instead of assuming every allowed value is stored
+ * - `next` and `prev` search strictly after or before the provided instant
+ * - Time-zone-aware schedules account for daylight saving transitions; during
+ *   a fall-back transition, repeated local times are emitted once when moving
+ *   forward
+ *
  * @since 2.0.0
  */
 import * as Arr from "./Array.ts"
@@ -28,7 +70,8 @@ const TypeId = "~effect/time/Cron"
  * seconds, minutes, hours, days, months, and weekdays constraints.
  * It also supports timezone-aware scheduling.
  *
- * @example
+ * **Example** (Creating a cron schedule)
+ *
  * ```ts
  * import { Cron } from "effect"
  *
@@ -78,8 +121,8 @@ const TypeId = "~effect/time/Cron"
  * console.log(matches) // true if it's 9 AM on a weekday
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Cron extends Pipeable, Equal.Equal, Inspectable {
   readonly [TypeId]: typeof TypeId
@@ -190,7 +233,8 @@ const CronProto = {
  * value is a valid Cron instance by checking for the presence of the
  * Cron type identifier.
  *
- * @example
+ * **Example** (Checking cron values)
+ *
  * ```ts
  * import { Cron } from "effect"
  *
@@ -207,8 +251,8 @@ const CronProto = {
  * console.log(Cron.isCron("not a cron")) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export const isCron = (u: unknown): u is Cron => hasProperty(u, TypeId)
 
@@ -219,7 +263,8 @@ export const isCron = (u: unknown): u is Cron => hasProperty(u, TypeId)
  * days, months, and weekdays the schedule should match. Empty arrays mean
  * "match all" for that time unit.
  *
- * @example
+ * **Example** (Creating schedules from constraints)
+ *
  * ```ts
  * import { Cron } from "effect"
  *
@@ -306,8 +351,8 @@ export const isCron = (u: unknown): u is Cron => hasProperty(u, TypeId)
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = (values: {
   readonly seconds?: Iterable<number> | undefined
@@ -415,7 +460,8 @@ const CronParseErrorTypeId = "~effect/time/Cron/CronParseError"
  * the parsing process, including the error message and optionally the
  * input that caused the error.
  *
- * @example
+ * **Example** (Handling cron parse failures)
+ *
  * ```ts
  * import { Cron, Result } from "effect"
  *
@@ -427,8 +473,8 @@ const CronParseErrorTypeId = "~effect/time/Cron/CronParseError"
  * }
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export class CronParseError extends Data.TaggedError("CronParseError")<{
   readonly message: string
@@ -444,7 +490,8 @@ export class CronParseError extends Data.TaggedError("CronParseError")<{
  * value is a CronParseError by checking for the presence of the
  * CronParseError type identifier.
  *
- * @example
+ * **Example** (Checking cron parse errors)
+ *
  * ```ts
  * import { Cron, Result } from "effect"
  *
@@ -458,17 +505,22 @@ export class CronParseError extends Data.TaggedError("CronParseError")<{
  * console.log(Cron.isCronParseError("not an error")) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isCronParseError = (u: unknown): u is CronParseError => hasProperty(u, CronParseErrorTypeId)
 
 /**
- * Parses a cron expression into a `Cron` instance.
+ * Parses a cron expression into a `Cron` instance, returning a `Result` instead
+ * of throwing.
+ *
+ * The expression may contain five fields, where seconds default to `0`, or six
+ * fields including seconds. Fields support `*`, comma-separated values, ranges,
+ * steps, and month or weekday aliases. Invalid expressions fail with
+ * `CronParseError`.
  *
- * @param cron - The cron expression to parse.
+ * **Example** (Parsing cron expressions)
  *
- * @example
  * ```ts
  * import { Cron, Result } from "effect"
  * import * as assert from "node:assert"
@@ -487,8 +539,8 @@ export const isCronParseError = (u: unknown): u is CronParseError => hasProperty
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const parse = (cron: string, tz?: DateTime.TimeZone | string): Result.Result<Cron, CronParseError> => {
   const segments = cron.split(" ").filter(String.isNonEmpty)
@@ -526,7 +578,8 @@ export const parse = (cron: string, tz?: DateTime.TimeZone | string): Result.Res
  * when you're confident the input is valid and want to avoid handling
  * the Result type.
  *
- * @example
+ * **Example** (Parsing cron expressions unsafely)
+ *
  * ```ts
  * import { Cron } from "effect"
  *
@@ -540,19 +593,21 @@ export const parse = (cron: string, tz?: DateTime.TimeZone | string): Result.Res
  * // const invalid = Cron.parseUnsafe("invalid expression")
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const parseUnsafe = (cron: string, tz?: DateTime.TimeZone | string): Cron => Result.getOrThrow(parse(cron, tz))
 
 /**
- * Checks if a given date/time falls within an active Cron time window.
+ * Returns `true` when a date/time matches a `Cron` schedule.
  *
- * This function determines whether a specific date and time matches
- * the cron schedule, taking into account all time constraints and
- * the optional timezone.
+ * Seconds, minutes, hours, months, and the optional timezone are checked
+ * directly. For day constraints, an empty `days` or `weekdays` set means that
+ * field matches every value; when both sets are non-empty, a date matches if
+ * either the day-of-month or weekday matches.
+ *
+ * **Example** (Matching dates against a schedule)
  *
- * @example
  * ```ts
  * import { Cron, Result } from "effect"
  *
@@ -569,8 +624,8 @@ export const parseUnsafe = (cron: string, tz?: DateTime.TimeZone | string): Cron
  * console.log(matches3) // false - wrong day
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const match = (cron: Cron, date: DateTime.DateTime.Input): boolean => {
   const parts = dateTime.makeZonedUnsafe(date, {
@@ -618,7 +673,8 @@ const daysInMonth = (date: Date): number =>
  * should trigger, starting from the specified date (or current time if
  * not provided).
  *
- * @example
+ * **Example** (Finding the next occurrence)
+ *
  * ```ts
  * import { Cron, Result } from "effect"
  *
@@ -634,8 +690,8 @@ const daysInMonth = (date: Date): number =>
  * console.log(nextFromNow) // Next occurrence from now
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const next = (cron: Cron, now?: DateTime.DateTime.Input): Date => {
   return stepCron(cron, now, "next")
@@ -644,8 +700,8 @@ export const next = (cron: Cron, now?: DateTime.DateTime.Input): Date => {
 /**
  * Returns the previous scheduled date/time for the given Cron instance.
  *
- * @since 4.0.0
  * @category utils
+ * @since 3.20.0
  */
 export const prev = (cron: Cron, now?: DateTime.DateTime.Input): Date => {
   return stepCron(cron, now, "prev")
@@ -812,7 +868,8 @@ const stepCron = (cron: Cron, now: DateTime.DateTime.Input | undefined, directio
  * of dates when the cron schedule should trigger, starting from the
  * specified date.
  *
- * @example
+ * **Example** (Iterating scheduled occurrences)
+ *
  * ```ts
  * import { Cron, Result } from "effect"
  *
@@ -826,8 +883,8 @@ const stepCron = (cron: Cron, now: DateTime.DateTime.Input | undefined, directio
  * // [Mon Jan 02 2023 09:00:00, Tue Jan 03 2023 09:00:00, ...]
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const sequence = function*(cron: Cron, now?: DateTime.DateTime.Input): IterableIterator<Date> {
   while (true) {
@@ -836,13 +893,14 @@ export const sequence = function*(cron: Cron, now?: DateTime.DateTime.Input): It
 }
 
 /**
- * An Equivalence instance for comparing Cron schedules.
+ * An `Equivalence` instance for comparing the field restrictions of two `Cron`
+ * schedules.
+ *
+ * This comparison checks seconds, minutes, hours, days, months, and weekdays.
+ * It does not compare the optional timezone.
  *
- * This equivalence compares two Cron instances by checking if their
- * time constraints (seconds, minutes, hours, days, months, weekdays)
- * are equivalent, regardless of the internal order.
+ * **Example** (Comparing schedules with equivalence)
  *
- * @example
  * ```ts
  * import { Cron } from "effect"
  *
@@ -865,8 +923,8 @@ export const sequence = function*(cron: Cron, now?: DateTime.DateTime.Input): It
  * console.log(Cron.Equivalence(cron1, cron2)) // true
  * ```
  *
- * @since 2.0.0
  * @category instances
+ * @since 2.0.0
  */
 export const Equivalence: Equ.Equivalence<Cron> = Equ.make((self, that) =>
   restrictionsEquals(self.seconds, that.seconds) &&
@@ -882,12 +940,13 @@ const restrictionsEquals = (self: ReadonlySet<number>, that: ReadonlySet<number>
   restrictionsArrayEquals(Arr.fromIterable(self), Arr.fromIterable(that))
 
 /**
- * Checks if two Cron instances are equal.
+ * Checks whether two `Cron` instances have the same field restrictions.
+ *
+ * The comparison checks seconds, minutes, hours, days, months, and weekdays.
+ * It does not compare the optional timezone.
  *
- * This function compares two Cron instances to determine if they represent
- * the same schedule by checking all their time constraints for equality.
+ * **Example** (Checking schedule equality)
  *
- * @example
  * ```ts
  * import { Cron } from "effect"
  *
@@ -911,17 +970,18 @@ const restrictionsEquals = (self: ReadonlySet<number>, that: ReadonlySet<number>
  * console.log(Cron.equals(cron1)(cron2)) // true (curried form)
  * ```
  *
- * @since 2.0.0
  * @category predicates
+ * @since 2.0.0
  */
 export const equals: {
   /**
-   * Checks if two Cron instances are equal.
+   * Checks whether two `Cron` instances have the same field restrictions.
+   *
+   * The comparison checks seconds, minutes, hours, days, months, and weekdays.
+   * It does not compare the optional timezone.
    *
-   * This function compares two Cron instances to determine if they represent
-   * the same schedule by checking all their time constraints for equality.
+   * **Example** (Checking schedule equality)
    *
-   * @example
    * ```ts
    * import { Cron } from "effect"
    *
@@ -945,17 +1005,18 @@ export const equals: {
    * console.log(Cron.equals(cron1)(cron2)) // true (curried form)
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 2.0.0
    */
   (that: Cron): (self: Cron) => boolean
   /**
-   * Checks if two Cron instances are equal.
+   * Checks whether two `Cron` instances have the same field restrictions.
+   *
+   * The comparison checks seconds, minutes, hours, days, months, and weekdays.
+   * It does not compare the optional timezone.
    *
-   * This function compares two Cron instances to determine if they represent
-   * the same schedule by checking all their time constraints for equality.
+   * **Example** (Checking schedule equality)
    *
-   * @example
    * ```ts
    * import { Cron } from "effect"
    *
@@ -979,8 +1040,8 @@ export const equals: {
    * console.log(Cron.equals(cron1)(cron2)) // true (curried form)
    * ```
    *
-   * @since 2.0.0
    * @category predicates
+   * @since 2.0.0
    */
   (self: Cron, that: Cron): boolean
 } = dual(2, (self: Cron, that: Cron): boolean => Equivalence(self, that))

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)
+}