effect 4.0.1 → 4.0.3

package/src/Context.ts

@@ -8,6 +8,7 @@
  * for creating keys, building contexts, adding and reading services, merging
  * contexts, and selecting or removing services.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import type { Effect, EffectIterator } from "./Effect.ts"
@@ -26,6 +27,7 @@ import type * as Types from "./Types.ts"
  * String literal type used as the runtime type identifier for `Context`
  * service keys.
  *
+ * @stability stable
  * @category type IDs
  * @since 4.0.0
  */
@@ -35,6 +37,7 @@ export type ServiceTypeId = "~effect/Context/Service"
  * Runtime type identifier attached to `Context` service keys and used by
  * `isKey` to recognize them.
  *
+ * @stability stable
  * @category type IDs
  * @since 4.0.0
  */
@@ -58,6 +61,7 @@ export const ServiceTypeId: ServiceTypeId = "~effect/Context/Service"
  * @see {@link Service} for creating required service keys
  * @see {@link Reference} for creating service keys with default values
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -92,6 +96,7 @@ export interface Key<out Identifier, out Shape> extends Effect<Shape, never, Ide
  * Context.get(context, Database).query("SELECT 1") // => "Result: SELECT 1"
  * ```
  *
+ * @stability stable
  * @category services
  * @since 4.0.0
  */
@@ -117,6 +122,7 @@ export interface Service<in out Identifier, in out Shape> extends Key<Identifier
  *
  * @see {@link Service} for creating function-style keys or class-style service keys
  *
+ * @stability stable
  * @category services
  * @since 4.0.0
  */
@@ -131,6 +137,7 @@ export interface ServiceClass<in out Self, in out Identifier extends string, in
  * Namespace containing helper types for class-style `Context.Service`
  * declarations.
  *
+ * @stability stable
  * @since 4.0.0
  */
 export declare namespace ServiceClass {
@@ -195,6 +202,7 @@ export declare namespace ServiceClass {
  *
  * @see {@link Reference} for service keys with default values
  *
+ * @stability stable
  * @category services
  * @since 4.0.0
  */
@@ -246,6 +254,7 @@ export const Service: {
    *
    * @see {@link Reference} for service keys with default values
    *
+   * @stability stable
    * @category services
    * @since 4.0.0
    */
@@ -303,6 +312,7 @@ export const Service: {
    *
    * @see {@link Reference} for service keys with default values
    *
+   * @stability stable
    * @category services
    * @since 4.0.0
    */
@@ -369,6 +379,7 @@ export const Service: {
    *
    * @see {@link Reference} for service keys with default values
    *
+   * @stability stable
    * @category services
    * @since 4.0.0
    */
@@ -479,6 +490,7 @@ const ReferenceTypeId = "~effect/Context/Reference" as const
  * messages // => ["default logger"]
  * ```
  *
+ * @stability stable
  * @category services
  * @since 3.11.0
  */
@@ -510,6 +522,7 @@ export interface Reference<in out Shape> extends Service<never, Shape> {
  * Database.key // => "Database"
  * ```
  *
+ * @stability stable
  * @since 2.0.0
  */
 export declare namespace Service {
@@ -611,6 +624,7 @@ const TypeId = "~effect/Context" as const
  * Context.get(context, Database).query("SELECT 1") // => "Result: SELECT 1"
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -726,6 +740,7 @@ const lookup = (self: Context<any>, key: string): unknown => {
  * context.mapUnsafe.size // => 1
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -798,6 +813,7 @@ export const hasSameCache = <Services, Services2>(
  * @see {@link isKey} for checking service keys
  * @see {@link isReference} for checking references with defaults
  *
+ * @stability stable
  * @category guards
  * @since 2.0.0
  */
@@ -813,6 +829,7 @@ export const isContext = (u: unknown): u is Context<never> => hasProperty(u, Typ
  * Context.isKey(Context.Service("Service")) // => true
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -834,6 +851,7 @@ export const isKey = (u: unknown): u is Key<any, any> => hasProperty(u, ServiceT
  * Context.isReference(Context.Service("Key")) // => false
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 3.11.0
  */
@@ -849,6 +867,7 @@ export const isReference = <I, S>(u: Key<I, S>): u is Reference<S> => !!(u as Re
  * Context.empty().mapUnsafe.size // => 0
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -870,6 +889,7 @@ const emptyContext = makeUnsafe(new Map())
  * Context.get(context, Port).PORT // => 8080
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -911,6 +931,7 @@ export const make = <I, S>(
  *
  * @see {@link addOrOmit} for adding or removing a service from an `Option`
  *
+ * @stability stable
  * @category combining
  * @since 2.0.0
  */
@@ -948,6 +969,7 @@ export const add: {
    *
    * @see {@link addOrOmit} for adding or removing a service from an `Option`
    *
+   * @stability stable
    * @category combining
    * @since 2.0.0
    */
@@ -985,6 +1007,7 @@ export const add: {
    *
    * @see {@link addOrOmit} for adding or removing a service from an `Option`
    *
+   * @stability stable
    * @category combining
    * @since 2.0.0
    */
@@ -998,6 +1021,7 @@ export const add: {
 /**
  * Adds a service by key to a given `Context` using a string key.
  *
+ * @stability stable
  * @category combining
  * @since 4.0.0
  */
@@ -1009,9 +1033,9 @@ export const addUnsafe = <Services, I, S>(
   const impl = self as ContextImpl<Services>
   const cacheRoot = cacheKeys.has(key) ? undefined : impl.cacheRoot
   if (impl.depth >= MaxDepth) {
-    // Rebase the overlay chain into a flat map, keeping the cacheRoot so a
-    // rebase on an ordinary key does not invalidate fiber caches
-    const map = new Map(impl.mapUnsafe)
+    // Avoid mapUnsafe: it would flatten the parent before copying.
+    const map = new Map(impl._flat ?? impl.base)
+    if (!impl._flat) applyOverlays(map, impl.overlay)
     map.set(key, service)
     return makeImpl(cacheRoot, map, undefined, 0)
   }
@@ -1056,6 +1080,7 @@ export const addUnsafe = <Services, I, S>(
  *
  * @see {@link add} for always storing a service value
  *
+ * @stability stable
  * @category combining
  * @since 4.0.0
  */
@@ -1092,6 +1117,7 @@ export const addOrOmit: {
    *
    * @see {@link add} for always storing a service value
    *
+   * @stability stable
    * @category combining
    * @since 4.0.0
    */
@@ -1128,6 +1154,7 @@ export const addOrOmit: {
    *
    * @see {@link add} for always storing a service value
    *
+   * @stability stable
    * @category combining
    * @since 4.0.0
    */
@@ -1189,6 +1216,7 @@ export const addOrOmit: {
  *
  * @see {@link getOption} for returning `Option.none` when a non-reference key is missing
  *
+ * @stability stable
  * @category getters
  * @since 3.7.0
  */
@@ -1237,6 +1265,7 @@ export const getOrElse: {
    *
    * @see {@link getOption} for returning `Option.none` when a non-reference key is missing
    *
+   * @stability stable
    * @category getters
    * @since 3.7.0
    */
@@ -1285,6 +1314,7 @@ export const getOrElse: {
    *
    * @see {@link getOption} for returning `Option.none` when a non-reference key is missing
    *
+   * @stability stable
    * @category getters
    * @since 3.7.0
    */
@@ -1311,6 +1341,7 @@ export const getOrElse: {
  *
  * @see {@link getOption} for a reference-aware optional lookup
  *
+ * @stability stable
  * @category getters
  * @since 4.0.0
  */
@@ -1331,6 +1362,7 @@ export const getOrUndefined: {
    *
    * @see {@link getOption} for a reference-aware optional lookup
    *
+   * @stability stable
    * @category getters
    * @since 4.0.0
    */
@@ -1351,6 +1383,7 @@ export const getOrUndefined: {
    *
    * @see {@link getOption} for a reference-aware optional lookup
    *
+   * @stability stable
    * @category getters
    * @since 4.0.0
    */
@@ -1398,6 +1431,7 @@ export const getOrUndefinedUnsafe = <A, Services = never>(self: Context<Services
  * @see {@link get} for type-checked service access
  * @see {@link getOption} for optional service access
  *
+ * @stability stable
  * @category unsafe
  * @since 4.0.0
  */
@@ -1434,6 +1468,7 @@ export const getUnsafe: {
    * @see {@link get} for type-checked service access
    * @see {@link getOption} for optional service access
    *
+   * @stability stable
    * @category unsafe
    * @since 4.0.0
    */
@@ -1470,6 +1505,7 @@ export const getUnsafe: {
    * @see {@link get} for type-checked service access
    * @see {@link getOption} for optional service access
    *
+   * @stability stable
    * @category unsafe
    * @since 4.0.0
    */
@@ -1513,6 +1549,7 @@ export const getUnsafe: {
  * @see {@link getOption} for optional service access
  * @see {@link getOrElse} for fallback values
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -1544,6 +1581,7 @@ export const get: {
    * @see {@link getOption} for optional service access
    * @see {@link getOrElse} for fallback values
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -1575,6 +1613,7 @@ export const get: {
    * @see {@link getOption} for optional service access
    * @see {@link getOrElse} for fallback values
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -1606,6 +1645,7 @@ export const get: {
    * @see {@link getOption} for optional service access
    * @see {@link getOrElse} for fallback values
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -1663,6 +1703,7 @@ const serviceNotFoundError = (service: Key<any, any>) => {
  *
  * @see {@link getOrElse} for returning a fallback value directly
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -1697,6 +1738,7 @@ export const getOption: {
    *
    * @see {@link getOrElse} for returning a fallback value directly
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -1731,6 +1773,7 @@ export const getOption: {
    *
    * @see {@link getOrElse} for returning a fallback value directly
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -1772,6 +1815,7 @@ export const getOption: {
  *
  * @see {@link mergeAll} for merging more than two contexts at once
  *
+ * @stability stable
  * @category combining
  * @since 2.0.0
  */
@@ -1807,6 +1851,7 @@ export const merge: {
    *
    * @see {@link mergeAll} for merging more than two contexts at once
    *
+   * @stability stable
    * @category combining
    * @since 2.0.0
    */
@@ -1842,6 +1887,7 @@ export const merge: {
    *
    * @see {@link mergeAll} for merging more than two contexts at once
    *
+   * @stability stable
    * @category combining
    * @since 2.0.0
    */
@@ -1888,6 +1934,7 @@ export const merge: {
  *
  * @see {@link merge} for merging two contexts
  *
+ * @stability stable
  * @category combining
  * @since 3.12.0
  */
@@ -1931,6 +1978,7 @@ export const mergeAll = <T extends Array<unknown>>(
  *
  * @see {@link omit} for removing selected services
  *
+ * @stability stable
  * @category filtering
  * @since 2.0.0
  */
@@ -1973,6 +2021,7 @@ export const pick = <S extends ReadonlyArray<Key<any, any>>>(
  *
  * @see {@link pick} for keeping selected services
  *
+ * @stability stable
  * @category filtering
  * @since 2.0.0
  */
@@ -2029,6 +2078,7 @@ export const omit = <S extends ReadonlyArray<Key<any, any>>>(
  *
  * @see {@link Service} for required services without default values
  *
+ * @stability stable
  * @category services
  * @since 3.11.0
  */

package/src/Cron.ts

@@ -5,6 +5,7 @@
  * can create or parse schedules, compare them, test whether a date matches, and
  * find previous or next scheduled occurrences.
  *
+ * @stability stable
  * @since 2.0.0
  */
 import * as Arr from "./Array.ts"
@@ -13,7 +14,7 @@ import type * as DateTime from "./DateTime.ts"
 import * as Equal from "./Equal.ts"
 import * as Equ from "./Equivalence.ts"
 import { format as formatValue } from "./Formatter.ts"
-import { constVoid, dual, pipe } from "./Function.ts"
+import { constFalse, constVoid, dual, pipe } from "./Function.ts"
 import * as Hash from "./Hash.ts"
 import { type Inspectable, NodeInspectSymbol } from "./Inspectable.ts"
 import * as dateTime from "./internal/dateTime.ts"
@@ -65,6 +66,7 @@ const TypeId = "~effect/Cron"
  * @see {@link match} for testing a date against a schedule
  * @see {@link next} for finding the next scheduled occurrence
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -201,6 +203,7 @@ const CronProto = {
  * @see {@link make} for constructing a `Cron` value directly
  * @see {@link parse} for constructing a `Cron` value from a string
  *
+ * @stability stable
  * @category guards
  * @since 2.0.0
  */
@@ -288,6 +291,7 @@ export const isCron = (u: unknown): u is Cron => hasProperty(u, TypeId)
  *
  * @see {@link parse} for building a schedule from a cron expression string
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -465,6 +469,7 @@ const CronParseErrorTypeId = "~effect/Cron/CronParseError"
  * @see {@link parse} for the parser that returns this error in `Result.fail`
  * @see {@link isCronParseError} for narrowing unknown values to this error type
  *
+ * @stability stable
  * @category errors
  * @since 4.0.0
  */
@@ -501,6 +506,7 @@ export class CronParseError extends Data.TaggedError("CronParseError")<{
  * @see {@link CronParseError} for the parse error type
  * @see {@link parse} for producing `CronParseError` values on invalid input
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -539,6 +545,7 @@ export const isCronParseError = (u: unknown): u is CronParseError => hasProperty
  * @see {@link parseUnsafe} for throwing on invalid cron expressions
  * @see {@link make} for constructing a schedule from explicit field constraints
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -607,6 +614,7 @@ export const parse = (cron: string, tz?: DateTime.TimeZone | string): Result.Res
  * Cron.match(cronWithTz, "2024-01-01T14:00:00Z") // => true
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -637,6 +645,7 @@ export const parseUnsafe = (cron: string, tz?: DateTime.TimeZone | string): Cron
  * Cron.format(cron, { includeSeconds: true }) // => "0 23 0-20/2 * * 0"
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 4.0.0
  */
@@ -708,6 +717,7 @@ const formatSegment = (values: ReadonlySet<number>): string => {
  * @see {@link next} for finding the next matching date/time
  * @see {@link prev} for finding the previous matching date/time
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -783,6 +793,7 @@ const daysInMonth = (date: Date): number =>
  * @see {@link prev} for finding the previous scheduled occurrence
  * @see {@link sequence} for iterating future scheduled occurrences
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -809,6 +820,7 @@ export const next = (cron: Cron, now?: DateTime.DateTime.Input): Date => {
  *
  * @see {@link next} for finding the next scheduled occurrence
  *
+ * @stability stable
  * @category getters
  * @since 3.20.0
  */
@@ -845,6 +857,14 @@ const stepCron = (cron: Cron, now: DateTime.DateTime.Input | undefined, directio
     }
   }
 
+  // Repeated wall times resolve to their first occurrence, so when the search
+  // starts in the second occurrence, matches inside that fold are in the past.
+  const isBeforeStart = reverse || utc ? constFalse : (current: Date) =>
+    dateTime.makeZonedUnsafe(current, {
+      timeZone: zoned.zone,
+      adjustForTimeZone: true
+    }).epochMilliseconds <= zoned.epochMilliseconds
+
   const result = dateTime.mutate(zoned, (current) => {
     current.setUTCSeconds(current.getUTCSeconds() + tick, 0)
 
@@ -988,6 +1008,12 @@ const stepCron = (cron: Cron, now: DateTime.DateTime.Input | undefined, directio
         }
       }
 
+      if (isBeforeStart(current)) {
+        current.setUTCSeconds(current.getUTCSeconds() + 1)
+        i = -1 // skipped fold candidates do not count against the search budget
+        continue
+      }
+
       return
     }
 
@@ -1033,6 +1059,7 @@ const stepCron = (cron: Cron, now: DateTime.DateTime.Input | undefined, directio
  *
  * @see {@link next} for computing one next occurrence
  *
+ * @stability stable
  * @category sequencing
  * @since 2.0.0
  */
@@ -1082,6 +1109,7 @@ export const sequence = function*(cron: Cron, now?: DateTime.DateTime.Input): It
  *
  * @see {@link equals} for directly comparing two `Cron` values
  *
+ * @stability stable
  * @category instances
  * @since 2.0.0
  */
@@ -1141,6 +1169,7 @@ const restrictionsEquals = (self: ReadonlySet<number>, that: ReadonlySet<number>
  *
  * @see {@link Equivalence} for the reusable equivalence instance
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -1186,6 +1215,7 @@ export const equals: {
    *
    * @see {@link Equivalence} for the reusable equivalence instance
    *
+   * @stability stable
    * @category predicates
    * @since 2.0.0
    */
@@ -1231,6 +1261,7 @@ export const equals: {
    *
    * @see {@link Equivalence} for the reusable equivalence instance
    *
+   * @stability stable
    * @category predicates
    * @since 2.0.0
    */

package/src/Crypto.ts

@@ -7,6 +7,7 @@
  * secure random bytes and numbers, UUIDv4 and UUIDv7 generation, shuffling, and
  * SHA message digests.
  *
+ * @stability unstable
  * @since 4.0.0
  */
 import * as Context from "./Context.ts"
@@ -34,6 +35,7 @@ const TypeId = "~effect/Crypto"
  * const algorithm: Crypto.DigestAlgorithm = "SHA-256"
  * ```
  *
+ * @stability unstable
  * @category models
  * @since 4.0.0
  */
@@ -64,7 +66,7 @@ export type DigestAlgorithm = "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512"
  * const program = Effect.gen(function*() {
  *   const crypto = yield* Crypto.Crypto
  *   const bytes = yield* crypto.randomBytes(16)
- *   const uuidv4 = yield* crypto.randomUUIDv4
+ *   const uuidv4 = yield* crypto.randomUUIDv4()
  *   const hash = yield* crypto.digest("SHA-256", bytes)
  *   return [bytes.length, uuidv4.length, hash.length]
  * })
@@ -72,6 +74,7 @@ export type DigestAlgorithm = "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512"
  * await Effect.runPromise(Effect.provide(program, TestCrypto)) // => [16, 36, 16]
  * ```
  *
+ * @stability unstable
  * @category services
  * @since 4.0.0
  */
@@ -145,14 +148,42 @@ export interface Crypto {
   randomShuffle<A>(elements: Iterable<A>): Effect.Effect<Array<A>>
 
   /**
-   * Generates a cryptographically secure UUIDv4 string.
+   * Generates a cryptographically secure UUIDv4.
+   *
+   * **Details**
+   *
+   * The default `"hex"` format returns a lowercase, hyphenated UUID string
+   * (36 characters), not a bare hexadecimal string. The `"bytes"` format
+   * returns the 16 UUID bytes, including the version and variant bits.
    */
-  readonly randomUUIDv4: Effect.Effect<string, PlatformError.PlatformError>
+  randomUUIDv4(options?: {
+    readonly format?: "hex" | undefined
+  }): Effect.Effect<string, PlatformError.PlatformError>
+  randomUUIDv4<Format extends "hex" | "bytes">(options: {
+    readonly format: Format
+  }): Effect.Effect<Format extends "bytes" ? Uint8Array : string, PlatformError.PlatformError>
+  randomUUIDv4(options?: {
+    readonly format?: "hex" | "bytes" | undefined
+  }): Effect.Effect<string | Uint8Array, PlatformError.PlatformError>
 
   /**
-   * Generates a cryptographically secure UUIDv7 string.
+   * Generates a cryptographically secure UUIDv7 using the `Clock` timestamp.
+   *
+   * **Details**
+   *
+   * The default `"hex"` format returns a lowercase, hyphenated UUID string
+   * (36 characters), not a bare hexadecimal string. The `"bytes"` format
+   * returns the 16 UUID bytes, including the timestamp, version and variant bits.
    */
-  readonly randomUUIDv7: Effect.Effect<string, PlatformError.PlatformError>
+  randomUUIDv7(options?: {
+    readonly format?: "hex" | undefined
+  }): Effect.Effect<string, PlatformError.PlatformError>
+  randomUUIDv7<Format extends "hex" | "bytes">(options: {
+    readonly format: Format
+  }): Effect.Effect<Format extends "bytes" ? Uint8Array : string, PlatformError.PlatformError>
+  randomUUIDv7(options?: {
+    readonly format?: "hex" | "bytes" | undefined
+  }): Effect.Effect<string | Uint8Array, PlatformError.PlatformError>
 
   /**
    * Generates a cryptographically secure ULID string.
@@ -185,6 +216,7 @@ export interface Crypto {
  *
  * @see {@link make} for constructing a Crypto service from primitive operations
  *
+ * @stability unstable
  * @category services
  * @since 4.0.0
  */
@@ -224,6 +256,7 @@ export const Crypto: Context.Service<Crypto, Crypto> = Context.Service("effect/C
  * await Effect.runPromise(testCrypto.randomBytes(4)) // => new Uint8Array([0, 0, 0, 0])
  * ```
  *
+ * @stability unstable
  * @category constructors
  * @since 4.0.0
  */
@@ -288,10 +321,16 @@ export const make = (
         }
         return buffer
       }),
-    randomUUIDv4: Effect.sync(() => Uuid.v4String(randomBytesUnsafe(16))),
-    randomUUIDv7: Effect.clockWith((clock) =>
-      Effect.succeed(Uuid.v7String(clock.currentTimeMillisUnsafe(), randomBytesUnsafe(16)))
-    ),
+    randomUUIDv4: ((options?: { readonly format?: "hex" | "bytes" | undefined }) =>
+      Effect.sync(() => {
+        const bytes = Uuid.v4Bytes(randomBytesUnsafe(16))
+        return options?.format === "bytes" ? bytes : Uuid.stringify(bytes)
+      })) as Crypto["randomUUIDv4"],
+    randomUUIDv7: ((options?: { readonly format?: "hex" | "bytes" | undefined }) =>
+      Effect.clockWith((clock) => {
+        const bytes = Uuid.v7Bytes(clock.currentTimeMillisUnsafe(), randomBytesUnsafe(16))
+        return Effect.succeed(options?.format === "bytes" ? bytes : Uuid.stringify(bytes))
+      })) as Crypto["randomUUIDv7"],
     randomULID: Effect.clockWith((clock) =>
       Effect.succeed(Ulid.ulidString(clock.currentTimeMillisUnsafe(), randomBytesUnsafe(10)))
     )