effect 4.0.2 → 4.0.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "effect",
   "type": "module",
-  "version": "4.0.2",
+  "version": "4.0.4",
   "license": "MIT",
   "description": "The missing standard library for TypeScript, for writing production-grade software.",
   "homepage": "https://effect.website",
@@ -46,6 +46,7 @@
     "./persistence": "./dist/persistence/index.js",
     "./process": "./dist/process/index.js",
     "./reactivity": "./dist/reactivity/index.js",
+    "./graphql": "./dist/graphql/index.js",
     "./rpc": "./dist/rpc/index.js",
     "./schema": "./dist/schema/index.js",
     "./socket": "./dist/socket/index.js",
@@ -74,13 +75,15 @@
     "provenance": true
   },
   "devDependencies": {
-    "@types/node": "^26.6.4",
+    "@types/node": "^26.6.5",
     "ajv": "^8.20.0",
     "ajv-draft-04": "^1.0.0",
     "ast-types": "^0.16.3",
+    "esbuild": "^0.28.2",
     "immer": "^11.1.21",
+    "miniflare": "5.20260925.0-alpha",
     "protobufjs": "^8.8.0",
-    "tinybench": "^6.2.0",
+    "tinybench": "^6.2.1",
     "valibot": "^1.5.0"
   },
   "scripts": {

package/src/Context.ts

@@ -1033,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)
   }
@@ -1986,6 +1986,15 @@ export const pick = <S extends ReadonlyArray<Key<any, any>>>(
   ...services: S
 ) =>
 <Services>(self: Context<Services>): Context<Services & Service.Identifier<S[number]>> => {
+  if (services.length <= 1) {
+    const map = new Map<string, unknown>()
+    if (services.length === 1) {
+      const key = services[0].key
+      const value = lookup(self, key)
+      if (value !== notFound) map.set(key, value)
+    }
+    return makeUnsafe(map)
+  }
   const keep = new Set(services.map((key) => key.key))
   return withFlat(self, (map) =>
     map.forEach((_, key) => {

package/src/Crypto.ts

@@ -66,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]
  * })
@@ -148,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.
@@ -293,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)))
     )

package/src/DateTime.ts

@@ -2108,7 +2108,7 @@ export const isPastUnsafe: (self: DateTime) => boolean = Internal.isPastUnsafe
  *
  * **Details**
  *
- * This always returns the UTC representation, ignoring any time zone information.
+ * This preserves the original instant, regardless of any time zone information.
  *
  * **Example** (Converting DateTime values to UTC Dates)
  *
@@ -2133,7 +2133,9 @@ export const toDateUtc: (self: DateTime) => Date = Internal.toDateUtc
  *
  * **Details**
  *
- * For `DateTime.Zoned`, this adjusts for the time zone before converting.
+ * For `DateTime.Zoned`, this stores the zoned wall-clock time in the returned
+ * `Date`'s UTC fields, rather than preserving the original instant. Use
+ * `toDateUtc` to preserve the instant.
  * For `DateTime.Utc`, this is equivalent to `toDateUtc`.
  *
  * **Example** (Converting DateTime values to Dates)
@@ -2141,13 +2143,14 @@ export const toDateUtc: (self: DateTime) => Date = Internal.toDateUtc
  * ```ts import.meta.vitest
  * import { DateTime } from "effect"
  *
- * const utc = DateTime.makeUnsafe("2024-01-01T12:00:00Z")
- * const zoned = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
+ * const utc = DateTime.makeUnsafe("2024-07-01T12:00:00Z")
+ * const zoned = DateTime.makeZonedUnsafe("2024-07-01T12:00:00Z", {
  *   timeZone: "Europe/London"
  * })
  *
- * DateTime.toDate(utc).toISOString() // => "2024-01-01T12:00:00.000Z"
- * DateTime.toDate(zoned).toISOString() // => "2024-01-01T12:00:00.000Z"
+ * DateTime.toDate(utc).toISOString() // => "2024-07-01T12:00:00.000Z"
+ * DateTime.toDate(zoned).toISOString() // => "2024-07-01T13:00:00.000Z"
+ * DateTime.toDateUtc(zoned).toISOString() // => "2024-07-01T12:00:00.000Z"
  * ```
  *
  * @stability stable

package/src/Duration.ts

@@ -36,11 +36,12 @@ const bigint1e3 = BigInt(1_000)
 const bigint1e6 = BigInt(1_000_000)
 const bigint1e9 = BigInt(1_000_000_000)
 
-const roundTiesAwayFromZero = (input: number): bigint =>
-  BigInt(input < 0 ? Math.ceil(input - 0.5) : Math.floor(input + 0.5))
+const roundTiesAwayFromZero = (input: number): bigint => BigInt(Math.sign(input) * Math.round(Math.abs(input)))
 
 const roundMillisToNanos = (millis: number): bigint => roundTiesAwayFromZero(millis * 1_000_000)
 
+const fromNanosNumber = (nanos: number): Duration => make(Number.isFinite(nanos) ? roundTiesAwayFromZero(nanos) : nanos)
+
 const parseNanos = (input: string, scale: bigint): bigint => {
   const decimalIndex = input.indexOf(".")
   if (decimalIndex === -1) return BigInt(input) * scale
@@ -51,9 +52,13 @@ const parseNanos = (input: string, scale: bigint): bigint => {
   const scaled = (
     BigInt(input.slice(isNegative ? 1 : 0, decimalIndex)) * fractionalScale + BigInt(fractional)
   ) * scale
-  const rounded = scaled / fractionalScale +
-    (scaled % fractionalScale * bigint2 >= fractionalScale ? bigint1 : bigint0)
-  return isNegative ? -rounded : rounded
+  return divideTiesAwayFromZero(isNegative ? -scaled : scaled, fractionalScale)
+}
+
+const divideTiesAwayFromZero = (numerator: bigint, denominator: bigint): bigint => {
+  const absolute = numerator < bigint0 ? -numerator : numerator
+  const rounded = absolute / denominator + (absolute % denominator * bigint2 >= denominator ? bigint1 : bigint0)
+  return numerator < bigint0 ? -rounded : rounded
 }
 
 const nanosToHrTime = (nanos: bigint): [seconds: number, nanos: number] => {
@@ -307,7 +312,7 @@ export const fromInputUnsafe = (input: Input): Duration => {
         if (input[0] === Infinity || input[1] === Infinity) {
           return infinity
         }
-        return make(roundTiesAwayFromZero(input[0] * 1_000_000_000 + input[1]))
+        return fromNanosNumber(input[0] * 1_000_000_000 + input[1])
       }
       const obj = input as DurationObject
       let millis = 0
@@ -319,9 +324,7 @@ export const fromInputUnsafe = (input: Input): Duration => {
       if (obj.seconds) millis += obj.seconds * 1_000
       if (obj.milliseconds) millis += obj.milliseconds
       if (!obj.microseconds && !obj.nanoseconds) return make(millis)
-      return make(roundTiesAwayFromZero(
-        millis * 1_000_000 + (obj.microseconds ?? 0) * 1_000 + (obj.nanoseconds ?? 0)
-      ))
+      return fromNanosNumber(millis * 1_000_000 + (obj.microseconds ?? 0) * 1_000 + (obj.nanoseconds ?? 0))
     }
   }
   return invalid(input)
@@ -1794,8 +1797,8 @@ export const divideUnsafe: {
  *
  * **Details**
  *
- * For nanosecond-backed durations, the multiplier must be convertible to a
- * `bigint`; fractional or non-finite multipliers can throw. Infinite
+ * Fractional multipliers on nanosecond-backed durations round the result to
+ * the nearest nanosecond, with ties rounding away from zero. Infinite
  * durations return positive infinity, negative infinity, or zero depending on
  * the multiplier sign.
  *
@@ -1817,8 +1820,8 @@ export const times: {
    *
    * **Details**
    *
-   * For nanosecond-backed durations, the multiplier must be convertible to a
-   * `bigint`; fractional or non-finite multipliers can throw. Infinite
+   * Fractional multipliers on nanosecond-backed durations round the result to
+   * the nearest nanosecond, with ties rounding away from zero. Infinite
    * durations return positive infinity, negative infinity, or zero depending on
    * the multiplier sign.
    *
@@ -1840,8 +1843,8 @@ export const times: {
    *
    * **Details**
    *
-   * For nanosecond-backed durations, the multiplier must be convertible to a
-   * `bigint`; fractional or non-finite multipliers can throw. Infinite
+   * Fractional multipliers on nanosecond-backed durations round the result to
+   * the nearest nanosecond, with ties rounding away from zero. Infinite
    * durations return positive infinity, negative infinity, or zero depending on
    * the multiplier sign.
    *
@@ -1863,7 +1866,24 @@ export const times: {
   (self: Duration, times: number): Duration =>
     match(self, {
       onMillis: (millis) => make(millis * times),
-      onNanos: (nanos) => make(nanos * BigInt(times)),
+      onNanos: (nanos) => {
+        if (Number.isInteger(times)) return make(nanos * BigInt(times))
+        const nanosNumber = Number(nanos)
+        const scaled = nanosNumber * times
+        if (
+          !Number.isFinite(times) ||
+          (Number.isSafeInteger(nanosNumber) && Math.abs(scaled) <= Number.MAX_SAFE_INTEGER)
+        ) {
+          return fromNanosNumber(scaled)
+        }
+        let numerator = times
+        let denominator = bigint1
+        while (!Number.isInteger(numerator)) {
+          numerator *= 2
+          denominator *= bigint2
+        }
+        return make(divideTiesAwayFromZero(nanos * BigInt(numerator), denominator))
+      },
       onInfinity: () => times > 0 ? infinity : times < 0 ? negativeInfinity : zero,
       onNegativeInfinity: () => times > 0 ? negativeInfinity : times < 0 ? infinity : zero
     })

package/src/FileSystem.ts

@@ -220,12 +220,17 @@ export interface FileSystem {
    * **Details**
    *
    * The file handle will be automatically closed when the scope is closed.
+   *
+   * `noFollow` rejects symlinks at the final path component, not in parent
+   * directories. Node and Bun support it on POSIX; unsupported platforms,
+   * including Windows and Deno, fail with `BadArgument`.
    */
   readonly open: (
     path: string,
     options?: {
       readonly flag?: OpenFlag | undefined
       readonly mode?: number | undefined
+      readonly noFollow?: boolean | undefined
     }
   ) => Effect.Effect<File, PlatformError, Scope>
   /**
@@ -827,6 +832,10 @@ export const isFile = (u: unknown): u is File => hasProperty(u, FileTypeId)
  * cursor. Outside append mode, `truncate` clamps a cursor past the new length
  * to that length.
  *
+ * Positional reads leave the cursor unchanged and may run concurrently on
+ * one handle. Cursor operations (`seek`, reads without a position, and writes)
+ * must not run concurrently with each other.
+ *
  * **Example** (Working with file handles)
  *
  * ```ts import.meta.vitest
@@ -877,8 +886,20 @@ export interface File {
    */
   readonly seek: (offset: bigint, from: SeekMode) => Effect.Effect<bigint, PlatformError>
   readonly sync: Effect.Effect<void, PlatformError>
-  readonly read: (buffer: Uint8Array) => Effect.Effect<number, PlatformError>
-  readonly readAlloc: (size: number) => Effect.Effect<Option.Option<Uint8Array>, PlatformError>
+  /**
+   * Reads into `buffer`, returning the byte count or `0` at EOF. Advances the
+   * cursor unless `options.position` is set (see `File.ReadOptions`).
+   */
+  readonly read: (buffer: Uint8Array, options?: File.ReadOptions) => Effect.Effect<number, PlatformError>
+  /**
+   * Reads up to `size` bytes into a new buffer, returning `Option.none()` at
+   * EOF. Advances the cursor unless `options.position` is set (see
+   * `File.ReadOptions`).
+   */
+  readonly readAlloc: (
+    size: number,
+    options?: File.ReadOptions
+  ) => Effect.Effect<Option.Option<Uint8Array>, PlatformError>
   readonly truncate: (length?: number) => Effect.Effect<void, PlatformError>
   readonly write: (buffer: Uint8Array) => Effect.Effect<number, PlatformError>
   readonly writeAll: (buffer: Uint8Array) => Effect.Effect<void, PlatformError>
@@ -892,6 +913,31 @@ export interface File {
  * @since 4.0.0
  */
 export declare namespace File {
+  /**
+   * Options for `File.read` and `File.readAlloc`.
+   *
+   * **Details**
+   *
+   * `position` is a byte offset from the start of the file. It leaves the
+   * cursor unchanged, fails with `BadArgument` if negative, and reads nothing
+   * at or past EOF.
+   *
+   * **Example** (Reading a byte range without moving the cursor)
+   *
+   * ```ts import.meta.vitest
+   * import type { FileSystem } from "effect"
+   *
+   * const options: FileSystem.File.ReadOptions = { position: BigInt(1024) }
+   * options.position // => 1024n
+   * ```
+   *
+   * @category models
+   * @since 4.1.0
+   */
+  export interface ReadOptions {
+    readonly position?: bigint | undefined
+  }
+
   /**
    * Enumeration of possible file system entry types.
    *

package/src/RequestResolver.ts

@@ -311,16 +311,10 @@ export const makeGrouped = <A extends Request.Any, K>(options: {
   })
 
 const hashGroupKey = <A, K>(get: (entry: Request.Entry<A>) => K) => {
-  const groupKeys = MutableHashMap.empty<K, K>()
-  return (entry: Request.Entry<A>): unknown => {
-    const key = get(entry)
-    const okey = MutableHashMap.get(groupKeys, key)
-    if (okey._tag === "Some") {
-      return okey.value
-    }
-    MutableHashMap.set(groupKeys, key, key)
-    return key
-  }
+  // Pending batches match equal keys, so they share one batch.
+  const batchKey = (entry: Request.Entry<A>): unknown => get(entry)
+  internal.equalBatchKeys.add(batchKey)
+  return batchKey
 }
 
 /**

package/src/Scheduler.ts

@@ -160,6 +160,15 @@ class PriorityBuckets {
  * operation counts to decide when fibers should yield, and is the default
  * scheduler implementation.
  *
+ * **Gotchas**
+ *
+ * On Cloudflare Workers, request-owned scheduler timers can be discarded,
+ * leaving shared fibers suspended. Use `new MixedScheduler("sync")` for the
+ * whole application; see `HttpRouter.toWebHandler` for a recipe.
+ * Sync mode does not yield to the event loop: CPU-heavy work delays other
+ * requests, and I/O-polling loops can exhaust the CPU limit. It does not fix
+ * request-owned timers (such as `Effect.sleep`) or request-bound async contexts.
+ *
  * @stability stable
  * @category models
  * @since 2.0.0