effect 4.0.4 → 4.0.5

package/src/Array.ts

@@ -521,8 +521,10 @@ export const fromOption: <A>(self: Option.Option<A>) => Array<A> = Option.toArra
  *
  * **Details**
  *
- * `onNonEmpty` receives a `NonEmptyReadonlyArray`. Supports both data-first and
- * data-last usage.
+ * `onNonEmpty` receives a `NonEmptyArray` for mutable arrays and a
+ * `NonEmptyReadonlyArray` otherwise. Data-last calls default to the readonly
+ * callback, so the returned function still accepts `ReadonlyArray`. Supports
+ * both data-first and data-last usage.
  *
  * **Example** (Branching on emptiness)
  *
@@ -555,8 +557,10 @@ export const match: {
    *
    * **Details**
    *
-   * `onNonEmpty` receives a `NonEmptyReadonlyArray`. Supports both data-first and
-   * data-last usage.
+   * `onNonEmpty` receives a `NonEmptyArray` for mutable arrays and a
+   * `NonEmptyReadonlyArray` otherwise. Data-last calls default to the readonly
+   * callback, so the returned function still accepts `ReadonlyArray`. Supports
+   * both data-first and data-last usage.
    *
    * **Example** (Branching on emptiness)
    *
@@ -594,8 +598,93 @@ export const match: {
    *
    * **Details**
    *
-   * `onNonEmpty` receives a `NonEmptyReadonlyArray`. Supports both data-first and
-   * data-last usage.
+   * `onNonEmpty` receives a `NonEmptyArray` for mutable arrays and a
+   * `NonEmptyReadonlyArray` otherwise. Data-last calls default to the readonly
+   * callback, so the returned function still accepts `ReadonlyArray`. Supports
+   * both data-first and data-last usage.
+   *
+   * **Example** (Branching on emptiness)
+   *
+   * ```ts import.meta.vitest
+   * import { Array } from "effect"
+   *
+   * const describe = Array.match({
+   *   onEmpty: () => "empty",
+   *   onNonEmpty: ([head, ...tail]) => `head: ${head}, tail: ${tail.length}`
+   * })
+   *
+   * describe([]) // => "empty"
+   * describe([1, 2, 3]) // => "head: 1, tail: 2"
+   * ```
+   *
+   * @see {@link matchLeft} — destructures into head + tail
+   * @see {@link matchRight} — destructures into init + last
+   *
+   * @stability stable
+   * @category pattern matching
+   * @since 2.0.0
+   */
+  <B, A, C = B>(
+    options: {
+      readonly onEmpty: LazyArg<B>
+      readonly onNonEmpty: (self: NonEmptyArray<A>) => C
+    }
+  ): (self: Array<A>) => B | C
+  /**
+   * Pattern-matches on an array, handling empty and non-empty cases separately.
+   *
+   * **When to use**
+   *
+   * Use when you need to branch on whether an array is empty.
+   *
+   * **Details**
+   *
+   * `onNonEmpty` receives a `NonEmptyArray` for mutable arrays and a
+   * `NonEmptyReadonlyArray` otherwise. Data-last calls default to the readonly
+   * callback, so the returned function still accepts `ReadonlyArray`. Supports
+   * both data-first and data-last usage.
+   *
+   * **Example** (Branching on emptiness)
+   *
+   * ```ts import.meta.vitest
+   * import { Array } from "effect"
+   *
+   * const describe = Array.match({
+   *   onEmpty: () => "empty",
+   *   onNonEmpty: ([head, ...tail]) => `head: ${head}, tail: ${tail.length}`
+   * })
+   *
+   * describe([]) // => "empty"
+   * describe([1, 2, 3]) // => "head: 1, tail: 2"
+   * ```
+   *
+   * @see {@link matchLeft} — destructures into head + tail
+   * @see {@link matchRight} — destructures into init + last
+   *
+   * @stability stable
+   * @category pattern matching
+   * @since 2.0.0
+   */
+  <A, B, C = B>(
+    self: Array<A>,
+    options: {
+      readonly onEmpty: LazyArg<B>
+      readonly onNonEmpty: (self: NonEmptyArray<A>) => C
+    }
+  ): B | C
+  /**
+   * Pattern-matches on an array, handling empty and non-empty cases separately.
+   *
+   * **When to use**
+   *
+   * Use when you need to branch on whether an array is empty.
+   *
+   * **Details**
+   *
+   * `onNonEmpty` receives a `NonEmptyArray` for mutable arrays and a
+   * `NonEmptyReadonlyArray` otherwise. Data-last calls default to the readonly
+   * callback, so the returned function still accepts `ReadonlyArray`. Supports
+   * both data-first and data-last usage.
    *
    * **Example** (Branching on emptiness)
    *

package/src/Channel.ts

@@ -1984,7 +1984,9 @@ const readableStreamToPullUnsafe = <A, E, E2 = never>(options: {
  * Each yielded value is emitted as an output element. The iterator's return
  * value becomes the channel's done value. Thrown or rejected iterator errors
  * are converted with `onError`. If the channel scope closes early and the
- * iterator has a `return` method, that method is called.
+ * iterator has a `return` method, that method is called. It is awaited unless
+ * a `next()` call is still pending, in which case its result is ignored and an
+ * async generator may not run its cleanup until that pull settles.
  *
  * @stability stable
  * @category constructors
@@ -1996,12 +1998,28 @@ export const fromAsyncIterable = <A, D, E>(
 ): Channel<A, E, D> =>
   fromTransform(Effect.fnUntraced(function*(_, scope) {
     const iter = iterable[Symbol.asyncIterator]()
+    let pulling = false
     if (iter.return) {
-      yield* Scope.addFinalizer(scope, Effect.promise(() => iter.return!()))
+      // `return()` may not settle until a pending `next()` does, so only
+      // await it when the iterator is idle.
+      yield* Scope.addFinalizer(
+        scope,
+        Effect.suspend(() =>
+          pulling
+            ? Effect.sync(() => void iter.return!().catch(constVoid))
+            : Effect.promise(() => iter.return!())
+        )
+      )
     }
     return Effect.flatMap(
       Effect.tryPromise({
-        try: () => iter.next(),
+        try: () => {
+          const promise = iter.next()
+          pulling = true
+          return promise.finally(() => {
+            pulling = false
+          })
+        },
         catch: onError
       }),
       (result) => result.done ? Cause.done(result.value) : Effect.succeed(result.value)
@@ -2017,6 +2035,9 @@ export const fromAsyncIterable = <A, D, E>(
  * The iterator's return value becomes the channel's done value. Thrown or
  * rejected iterator errors are converted with `onError`. If the channel scope
  * closes early and the iterator has a `return` method, that method is called.
+ * It is awaited unless a `next()` call is still pending, in which case its
+ * result is ignored and an async generator may not run its cleanup until that
+ * pull settles.
  *
  * @stability stable
  * @category constructors

package/src/ConfigProvider.ts

@@ -1380,56 +1380,52 @@ function dotEnvExpand(parsed: Record<string, string>): Record<string, string> {
 
   for (const configKey of Object.keys(parsed)) {
     // resolve escape sequences
-    newParsed[configKey] = interpolate(parsed[configKey], parsed).replace(/\\\$/g, "$")
+    newParsed[configKey] = interpolate(parsed[configKey], parsed, new Set([configKey])).replace(/\\\$/g, "$")
   }
 
   return newParsed
 }
 
-function interpolate(envValue: string, parsed: Record<string, string>): string {
-  // find the last unescaped dollar sign in the
-  // value so that we can evaluate it
-  const lastUnescapedDollarSignIndex = searchLast(envValue, /(?!(?<=\\))\$/g)
-
-  // If we couldn't match any unescaped dollar sign
-  // let's return the string as is
-  if (lastUnescapedDollarSignIndex === -1) return envValue
-
-  // This is the right-most group of variables in the string
-  const rightMostGroup = envValue.slice(lastUnescapedDollarSignIndex)
-
-  /**
-   * This finds the inner most variable/group divided
-   * by variable name and default value (if present)
-   * (
-   *   (?!(?<=\\))\$        // only match dollar signs that are not escaped
-   *   {?                   // optional opening curly brace
-   *     ([\w]+)            // match the variable name
-   *     (?::-([^}\\]*))?   // match an optional default value
-   *   }?                   // optional closing curly brace
-   * )
-   */
-  const matchGroup = /((?!(?<=\\))\${?([\w]+)(?::-([^}\\]*))?}?)/
-  const match = rightMostGroup.match(matchGroup)
-
-  if (match !== null) {
-    const [_, group, variableName, defaultValue] = match
-    const value = Object.hasOwn(parsed, variableName) && parsed[variableName] !== ""
-      ? parsed[variableName]
-      : defaultValue ?? ""
-
-    return interpolate(
-      envValue.replace(group, () => value),
-      parsed
-    )
+function interpolate(
+  envValue: string,
+  parsed: Record<string, string>,
+  seen: ReadonlySet<string>
+): string {
+  const reference = /(?<!\\)\${?(\w+)/g
+  let result = ""
+  let cursor = 0
+  let match: RegExpExecArray | null
+  while ((match = reference.exec(envValue)) != null) {
+    const [, name] = match
+    let end = reference.lastIndex
+    let defaultValue = ""
+    if (envValue.startsWith(":-", end)) {
+      end += 2
+      const start = end
+      let depth = 0
+      // Match default braces in the source, not in substituted values.
+      for (; end < envValue.length; end++) {
+        if (envValue.startsWith("${", end)) {
+          depth++
+          end++
+        } else if (envValue[end] === "}") {
+          if (depth === 0) break
+          depth--
+        }
+      }
+      defaultValue = envValue.slice(start, end)
+    }
+    if (envValue[end] === "}") end++
+
+    // References already being expanded resolve as unset.
+    const expanded = Object.hasOwn(parsed, name) && !seen.has(name)
+      ? interpolate(parsed[name], parsed, new Set([...seen, name]))
+      : ""
+    result += envValue.slice(cursor, match.index) + (expanded || interpolate(defaultValue, parsed, seen))
+    cursor = end
+    reference.lastIndex = end
   }
-
-  return envValue
-}
-
-function searchLast(str: string, rgx: RegExp): number {
-  const matches = Array.from(str.matchAll(rgx))
-  return matches.length > 0 ? matches.slice(-1)[0].index : -1
+  return result + envValue.slice(cursor)
 }
 
 /**

package/src/Duration.ts

@@ -38,7 +38,8 @@ const bigint1e9 = BigInt(1_000_000_000)
 
 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 roundMillisToNanos = (millis: number): bigint =>
+  Number.isInteger(millis) ? BigInt(millis) * bigint1e6 : roundTiesAwayFromZero(millis * 1_000_000)
 
 const fromNanosNumber = (nanos: number): Duration => make(Number.isFinite(nanos) ? roundTiesAwayFromZero(nanos) : nanos)
 
@@ -365,10 +366,8 @@ const DurationProto: Omit<Duration, "value"> = {
     // Hash equal finite durations using the same canonical nanoseconds
     // representation used by `equals`.
     switch (this.value._tag) {
-      case "Millis": {
-        const nanos = this.value.millis * 1_000_000
-        return Number.isFinite(nanos) ? Hash.hash(roundTiesAwayFromZero(nanos)) : Hash.number(this.value.millis)
-      }
+      case "Millis":
+        return Hash.hash(roundMillisToNanos(this.value.millis))
       case "Nanos":
         return Hash.hash(this.value.nanos)
       default:

package/src/Effect.ts

@@ -20,7 +20,7 @@ import type * as ExecutionPlan from "./ExecutionPlan.ts"
 import * as Exit from "./Exit.ts"
 import type { Fiber } from "./Fiber.ts"
 import type * as Filter from "./Filter.ts"
-import { constant, dual, type LazyArg } from "./Function.ts"
+import { dual, type LazyArg } from "./Function.ts"
 import type { TypeLambda } from "./HKT.ts"
 import type { Inspectable } from "./Inspectable.ts"
 import * as core from "./internal/core.ts"
@@ -25245,50 +25245,113 @@ export const trackDuration: {
 // Transactions
 // -----------------------------------------------------------------------------
 
+/**
+ * Why the current transaction attempt started after a previous attempt did not commit.
+ *
+ * **Details**
+ *
+ * `"retry"` means the previous attempt called {@link txRetry}. `"conflict"`
+ * means an accessed `TxRef` changed before commit. The first attempt has no
+ * retry reason.
+ *
+ * @stability stable
+ * @category models
+ * @since 4.0.0
+ */
+export type TransactionRetryReason = "retry" | "conflict"
+
+/**
+ * Journal and attempt metadata for an Effect transaction.
+ *
+ * **When to use**
+ *
+ * Use to type the value provided by {@link Transaction}.
+ *
+ * **Details**
+ *
+ * `attempt` starts at `1` and counts each run of the outermost transaction body.
+ * `retryReason` is `"retry"` after {@link txRetry} and `"conflict"` after an
+ * accessed `TxRef` changes before commit; it is unset on the first attempt.
+ * `start`, `now`, `elapsed`, and `elapsedSincePrevious` are millisecond
+ * timestamps and durations for the current attempt, matching {@link Schedule}
+ * metadata. Each journal entry stores the observed version and value of a
+ * `TxRef`. `written` is true when this transaction has updated that ref.
+ *
+ * @see {@link Transaction} for the context service that provides this metadata
+ * @see {@link TransactionRetryReason} for the retry-reason tags recorded on later attempts
+ *
+ * @stability stable
+ * @category models
+ * @since 4.0.0
+ */
+export interface TransactionMeta {
+  readonly journal: ReadonlyMap<
+    TxRef<any>,
+    {
+      readonly version: number
+      readonly value: any
+      readonly written: boolean
+    }
+  >
+  readonly attempt: number
+  readonly retryReason: TransactionRetryReason | undefined
+  readonly start: number
+  readonly now: number
+  readonly elapsed: number
+  readonly elapsedSincePrevious: number
+}
+
+/** @internal */
+export interface TransactionMetaInner {
+  retry: boolean
+  journal: Map<
+    TxRef<any>,
+    {
+      readonly version: number
+      value: any
+      written: boolean
+    }
+  >
+  attempt: number
+  retryReason: TransactionRetryReason | undefined
+  start: number
+  now: number
+  elapsed: number
+  elapsedSincePrevious: number
+}
+
 /**
  * Service that holds the current transaction state.
  *
  * **Details**
  *
- * It includes a journal that stores non-committed changes to `TxRef` values and
- * a retry flag that records whether the transaction should be retried.
+ * Nested {@link tx} calls reuse this same service instance. Yield it inside a
+ * transaction body to read {@link TransactionMeta} fields such as `attempt`
+ * and `retryReason`.
  *
- * **Example** (Building transactions)
+ * **Example** (Reading transaction metadata)
  *
  * ```ts import.meta.vitest
  * import { Effect } from "effect"
  *
- * // Transaction class for software transactional memory operations
- * const txEffect = Effect.gen(function*() {
+ * const program = Effect.tx(Effect.gen(function*() {
  *   const tx = yield* Effect.Transaction
- *   // Use transaction for coordinated state changes
- *   return "Transaction complete"
- * })
+ *   return [tx.attempt, tx.retryReason, tx.elapsed, tx.elapsedSincePrevious]
+ * }))
  *
- * const runnable = Effect.provideService(txEffect, Effect.Transaction, {
- *   retry: false,
- *   journal: new Map()
- * })
- * Effect.runSync(runnable) // => "Transaction complete"
+ * Effect.runSync(program) // => [1, undefined, 0, 0]
  * ```
  *
+ * @see {@link tx} for the outermost transaction boundary that creates this service
+ * @see {@link TransactionMeta} for the journal and attempt metadata
+ *
  * @stability stable
  * @category transactions
  * @since 4.0.0
  */
 export class Transaction extends Context.Service<
   Transaction,
-  {
-    retry: boolean
-    readonly journal: Map<
-      TxRef<any>,
-      {
-        readonly version: number
-        value: any
-        written: boolean
-      }
-    >
-  }
+  TransactionMeta
 >()("effect/Effect/Transaction") {}
 
 /**
@@ -25342,52 +25405,75 @@ export const tx = <A, E, R>(
   effect: Effect<A, E, R>
 ): Effect<A, E, Exclude<R, Transaction>> =>
   withFiber((fiber) => {
-    let state = Context.getOrUndefined(fiber.context, Transaction)
+    const state = Context.getOrUndefined(fiber.context, Transaction)
     if (state && !completedTransactions.has(state)) {
       return effect as Effect<A, E, Exclude<R, Transaction>>
     }
+    const clock = fiber.getRef(internal.ClockRef)
+    const now = clock.currentTimeMillisUnsafe()
     // Create transaction state only at the outermost boundary
-    state = { journal: new Map(), retry: false }
+    const mutable: TransactionMetaInner = {
+      journal: new Map(),
+      retry: false,
+      attempt: 1,
+      retryReason: undefined,
+      start: now,
+      now,
+      elapsed: 0,
+      elapsedSincePrevious: 0
+    }
     let result: Exit.Exit<A, E> | undefined
-    return uninterruptibleMask((restore) =>
-      flatMap(
+    return uninterruptibleMask((restore) => {
+      const run = restore(effect).pipe(
+        provideService(Transaction, mutable),
+        tapCause((cause) => {
+          if (!mutable.retry) return void_
+          // txRetry interrupts the body; any other reason in the cause is a real failure.
+          // Roll back now so the step below fails instead of waiting or rerunning.
+          if (!internal.hasInterruptsOnly(cause)) return sync(() => clearTransaction(mutable))
+          return restore(awaitPendingTransaction(mutable))
+        }),
+        exit
+      )
+      return flatMap(
         whileLoop({
           while: () => !result,
-          body: constant(
-            restore(effect).pipe(
-              provideService(Transaction, state),
-              tapCause((cause) => {
-                if (!state.retry) return void_
-                // txRetry interrupts the body; any other reason in the cause is a real failure.
-                // Roll back now so the step below fails instead of waiting or rerunning.
-                if (!internal.hasInterruptsOnly(cause)) return sync(() => clearTransaction(state))
-                return restore(awaitPendingTransaction(state))
-              }),
-              exit
-            )
-          ),
+          body: () => {
+            if (mutable.attempt > 1) {
+              stampTransaction(mutable, clock.currentTimeMillisUnsafe())
+            }
+            return run
+          },
           step(exit: Exit.Exit<A, E>) {
-            if (state.retry || !isTransactionConsistent(state)) {
-              return clearTransaction(state)
+            if (mutable.retry || !isTransactionConsistent(mutable)) {
+              mutable.attempt++
+              mutable.retryReason = mutable.retry ? "retry" : "conflict"
+              return clearTransaction(mutable)
             }
             if (Exit.isSuccess(exit)) {
-              commitTransaction(fiber, state)
+              commitTransaction(fiber, mutable)
             }
-            clearTransaction(state)
-            completedTransactions.add(state)
+            clearTransaction(mutable)
+            completedTransactions.add(mutable)
             result = exit
           }
         }),
         () => result!
       )
-    )
+    })
   })
 
 // Child fibers inherit the boundary's state, so mark it completed once the
 // boundary finishes and let later `tx` calls start a fresh boundary.
 const completedTransactions = new WeakSet<Transaction["Service"]>()
 
-const isTransactionConsistent = (state: Transaction["Service"]) => {
+const stampTransaction = (state: TransactionMetaInner, now: number) => {
+  state.elapsedSincePrevious = now - state.now
+  state.now = now
+  state.elapsed = now - state.start
+}
+
+const isTransactionConsistent = (state: TransactionMeta) => {
   for (const [ref, { version }] of state.journal) {
     if (ref.version !== version) {
       return false
@@ -25396,7 +25482,7 @@ const isTransactionConsistent = (state: Transaction["Service"]) => {
   return true
 }
 
-const awaitPendingTransaction = (state: Transaction["Service"]) =>
+const awaitPendingTransaction = (state: TransactionMeta) =>
   callback<void>((resume) => {
     // Validate the read set and register the waiter in one synchronous step.
     // A commit that landed after the reads has already signalled its waiters
@@ -25421,7 +25507,7 @@ const awaitPendingTransaction = (state: Transaction["Service"]) =>
     return sync(clearPending)
   })
 
-function commitTransaction(fiber: Fiber<unknown, unknown>, state: Transaction["Service"]) {
+function commitTransaction(fiber: Fiber<unknown, unknown>, state: TransactionMeta) {
   for (const [ref, { value, written }] of state.journal) {
     if (!written) continue
     if (!Object.is(value, ref.value)) {
@@ -25435,7 +25521,7 @@ function commitTransaction(fiber: Fiber<unknown, unknown>, state: Transaction["S
   }
 }
 
-function clearTransaction(state: Transaction["Service"]) {
+function clearTransaction(state: TransactionMetaInner) {
   state.retry = false
   state.journal.clear()
 }
@@ -25480,7 +25566,8 @@ function clearTransaction(state: Transaction["Service"]) {
 export const txRetry: Effect<never, never, Transaction> = flatMap(
   Transaction,
   (state) => {
-    state.retry = true
+    const mutable = state as TransactionMetaInner
+    mutable.retry = true
     return interrupt
   }
 )

package/src/FileSystem.ts

@@ -968,9 +968,17 @@ export declare namespace File {
    * permissions, and size information. This structure is returned by file
    * stat operations.
    *
-   * Node and Bun preserve `size` and `blksize` exactly. Optional `number`
-   * metadata is `Option.none()` when absent or outside the safe integer range.
-   * Unsafe `dev` or `mode` values fail the stat operation with `BadArgument`.
+   * `dev`, `ino`, `rdev`, `nlink`, and `blocks` are `bigint` values, so
+   * 64-bit device identifiers, inode numbers, and counts are not limited to
+   * the safe integer range. `mode`, `uid`, and `gid` are 32-bit values and
+   * remain `number`. Optional metadata is `Option.none()` only when the
+   * platform does not report it.
+   *
+   * Node and Bun report all fields exactly, with `dev`, `ino`, `rdev`, and
+   * `nlink` interpreted as unsigned 64-bit integers. Unsafe `mode` values fail
+   * the stat operation with `BadArgument`. Deno reports these fields as
+   * `number`, so on Deno values above `Number.MAX_SAFE_INTEGER` are already
+   * rounded before they are converted to `bigint`.
    *
    * **Example** (Inspecting file information)
    *
@@ -982,7 +990,7 @@ export declare namespace File {
    *   mtime: Option.none(),
    *   atime: Option.none(),
    *   birthtime: Option.none(),
-   *   dev: 1,
+   *   dev: 1n,
    *   ino: Option.none(),
    *   mode: 0o644,
    *   nlink: Option.none(),
@@ -1014,16 +1022,16 @@ export declare namespace File {
     readonly mtime: Option.Option<Date>
     readonly atime: Option.Option<Date>
     readonly birthtime: Option.Option<Date>
-    readonly dev: number
-    readonly ino: Option.Option<number>
+    readonly dev: bigint
+    readonly ino: Option.Option<bigint>
     readonly mode: number
-    readonly nlink: Option.Option<number>
+    readonly nlink: Option.Option<bigint>
     readonly uid: Option.Option<number>
     readonly gid: Option.Option<number>
-    readonly rdev: Option.Option<number>
+    readonly rdev: Option.Option<bigint>
     readonly size: ByteSize.ByteSize
     readonly blksize: Option.Option<ByteSize.ByteSize>
-    readonly blocks: Option.Option<number>
+    readonly blocks: Option.Option<bigint>
   }
 }
 
@@ -1061,6 +1069,12 @@ export interface WatchOptions {
    * When `true`, changes in subdirectories are also reported.
    */
   readonly recursive?: boolean | undefined
+  /**
+   * Called once the underlying watcher is installed and can buffer events.
+   * Stream construction alone does not install a watcher. Custom watch
+   * backends must also call this callback after installation, when supplied.
+   */
+  readonly onReady?: (() => void) | undefined
 }
 
 /**