effect 4.0.2 → 4.0.3

package/src/socket/Socket.ts

@@ -799,13 +799,18 @@ export interface WebSocketLike {
 }
 
 /**
- * Common options understood by a WebSocket client implementation.
+ * Client options for Node and Bun WebSocket implementations, allowing
+ * handshake headers and subprotocols to be supplied together.
  *
  * @stability unstable
  * @category models
  * @since 4.0.0
  */
 export interface WebSocketClientOptions {
+  /**
+   * Subprotocols to offer in the opening handshake.
+   */
+  readonly protocols?: string | Array<string> | undefined
   /**
    * Headers to include in the opening handshake.
    *
@@ -857,6 +862,7 @@ export class WebSocketConstructor extends Context.Service<
 
 /**
  * Layer that provides `WebSocketConstructor` using `globalThis.WebSocket`.
+ * Rejects client options objects, including those with handshake headers.
  *
  * @stability unstable
  * @category layers
@@ -874,6 +880,8 @@ export const layerWebSocketConstructorGlobal: Layer.Layer<WebSocketConstructor>
 /**
  * Creates a `Socket` backed by a `WebSocketConstructor`, dialing the
  * WebSocket for each reader acquisition.
+ * Optional handshake headers require a Node or Bun constructor; without
+ * headers, protocols are passed directly for browser compatibility.
  *
  * @stability unstable
  * @category constructors
@@ -882,13 +890,21 @@ export const layerWebSocketConstructorGlobal: Layer.Layer<WebSocketConstructor>
 export const makeWebSocket = (url: string | Effect.Effect<string>, options?: {
   readonly openTimeout?: Duration.Input | undefined
   readonly protocols?: string | Array<string> | undefined
+  readonly headers?: Readonly<Record<string, string>> | undefined
   readonly highWaterMark?: number | undefined
 }): Effect.Effect<Socket, never, WebSocketConstructor> =>
   WebSocketConstructor.use((makeWs) =>
     fromWebSocket(
       Effect.acquireRelease(
         (typeof url === "string" ? Effect.succeed(url) : url).pipe(
-          Effect.map((url) => makeWs(url, options?.protocols))
+          Effect.map((url) =>
+            makeWs(
+              url,
+              options?.headers === undefined
+                ? options?.protocols
+                : { protocols: options.protocols, headers: options.headers }
+            )
+          )
         ),
         (ws) => Effect.sync(() => ws.close(1000))
       ),
@@ -1165,6 +1181,7 @@ const defaultHighWaterMark = 64 * 1024
 /**
  * Creates a binary `Channel` backed by a WebSocket URL, requiring a
  * `WebSocketConstructor` service.
+ * Supports subprotocols and, with a Node or Bun constructor, handshake headers.
  *
  * @stability unstable
  * @category constructors
@@ -1175,6 +1192,7 @@ export const makeWebSocketChannel = <IE = never>(
   options?: {
     readonly openTimeout?: Duration.Input | undefined
     readonly protocols?: string | Array<string> | undefined
+    readonly headers?: Readonly<Record<string, string>> | undefined
     readonly highWaterMark?: number | undefined
   }
 ): Channel.Channel<
@@ -1193,6 +1211,7 @@ export const makeWebSocketChannel = <IE = never>(
 /**
  * Layer that provides a `Socket` service backed by a WebSocket URL or URL
  * effect.
+ * Supports subprotocols and, with a Node or Bun constructor, handshake headers.
  *
  * @stability unstable
  * @category layers
@@ -1203,6 +1222,7 @@ export const layerWebSocket: (
   options?: {
     readonly openTimeout?: Duration.Input | undefined
     readonly protocols?: string | Array<string> | undefined
+    readonly headers?: Readonly<Record<string, string>> | undefined
     readonly highWaterMark?: number | undefined
   } | undefined
 ) => Layer.Layer<Socket, never, WebSocketConstructor> = flow(makeWebSocket, Layer.effect(Socket))

package/src/socket/index.ts

@@ -5,6 +5,12 @@
 
 // @barrel: Auto-generated exports. Do not edit manually.
 
+/**
+ * @stability experimental
+ * @since 4.0.0
+ */
+export * as DatagramSocket from "./DatagramSocket.ts"
+
 /**
  * @stability unstable
  * @since 4.0.0

package/src/sql/Migrator.ts

@@ -140,14 +140,21 @@ export const make = <RD = never>({
   PRIMARY KEY (migration_id)
 )`,
       pg: () =>
-        Effect.catch(
-          sql`select ${table}::regclass`,
-          () =>
-            sql`CREATE TABLE ${sql(table)} (
+        Effect.flatMap(
+          migrationsTableExists(sql, table),
+          (exists) =>
+            exists ? Effect.void : Effect.asVoid(sql`CREATE TABLE ${sql(table)} (
   migration_id integer primary key,
   created_at timestamp with time zone not null default now(),
   name text not null
-)`
+)`).pipe(
+              Effect.catch((error) =>
+                Effect.flatMap(
+                  migrationsTableExists(sql, table),
+                  (exists) => exists ? Effect.void : Effect.fail(error)
+                )
+              )
+            )
         ),
       orElse: () =>
         sql`CREATE TABLE IF NOT EXISTS ${sql(table)} (
@@ -328,6 +335,15 @@ export const make = <RD = never>({
     return completed
   })
 
+const migrationsTableExists = (sql: Client.SqlClient, table: string): Effect.Effect<boolean, SqlError> => {
+  // Match query quoting: to_regclass folds unquoted names to lowercase.
+  const quotedTable = sql`${sql(table)}`.compile(true)[0]
+  return Effect.map(
+    sql`SELECT 1 AS found WHERE to_regclass(${quotedTable}) IS NOT NULL`.withoutTransform,
+    (rows) => rows.length > 0
+  )
+}
+
 const migrationOrder = Order.make<ResolvedMigration>(([a], [b]) => Order.Number(a, b))
 
 const isConstraintConflict = (error: SqlError): boolean =>

package/src/sql/SqlClient.ts

@@ -9,7 +9,7 @@
  * @stability unstable
  * @since 4.0.0
  */
-import type * as Cause from "../Cause.ts"
+import * as Cause from "../Cause.ts"
 import { Clock } from "../Clock.ts"
 import * as Context from "../Context.ts"
 import * as Effect from "../Effect.ts"
@@ -280,6 +280,12 @@ export const make = Effect.fnUntraced(function*(options: SqlClient.MakeOptions)
  *
  * **Details**
  *
+ * Both acquirers lease the connection into the current scope and hold the
+ * semaphore until that scope closes, so a statement or stream keeps the
+ * connection until it finishes and another fiber cannot begin a transaction
+ * underneath it. Effects that use the connection directly, such as an export,
+ * have to run inside `Effect.scoped`.
+ *
  * SQLite can keep a transaction open after COMMIT fails, for example on a
  * deferred foreign key violation. `onCommitFailure` rolls it back before the
  * connection is reused. If that ROLLBACK fails, the connection is rejected, and
@@ -300,7 +306,7 @@ export const makeSqliteAcquirers = <C extends Connection.Connection>(options: {
   readonly semaphore: Semaphore.Semaphore
   readonly isTransaction?: ((conn: C) => boolean) | undefined
 }): {
-  readonly acquirer: Effect.Effect<C, SqlError>
+  readonly acquirer: Effect.Effect<C, SqlError, Scope.Scope>
   readonly transactionAcquirer: Effect.Effect<C, SqlError, Scope.Scope>
   readonly onCommitFailure: (conn: Connection.Connection) => Effect.Effect<void, SqlError>
 } => {
@@ -336,15 +342,17 @@ export const makeSqliteAcquirers = <C extends Connection.Connection>(options: {
     })
   })
 
+  const lease = Effect.uninterruptibleMask((restore) =>
+    Effect.flatMap(Effect.scope, (scope) =>
+      restore(semaphore.take(1)).pipe(
+        Effect.andThen(Scope.addFinalizer(scope, semaphore.release(1))),
+        Effect.andThen(available)
+      ))
+  )
+
   return {
-    acquirer: semaphore.withPermits(1)(available),
-    transactionAcquirer: Effect.uninterruptibleMask((restore) =>
-      Effect.flatMap(Effect.scope, (scope) =>
-        restore(semaphore.take(1)).pipe(
-          Effect.andThen(Scope.addFinalizer(scope, semaphore.release(1))),
-          Effect.andThen(available)
-        ))
-    ),
+    acquirer: lease,
+    transactionAcquirer: lease,
     onCommitFailure: (conn) => Effect.tapCause(rollback(conn as C), (cause) => Effect.sync(() => poison(cause)))
   }
 }
@@ -359,6 +367,18 @@ const isNoTransactionError = (error: SqlError): boolean => {
   return /no transaction is active/i.test(message);
 }
 
+/**
+ * A failed COMMIT cleanup leaves the connection in an unsafe state, so both the
+ * COMMIT error and the cleanup error are promoted to defects: typed recovery
+ * must not be able to hide them.
+ */
+const failuresToDefects = <E>(cause: Cause.Cause<E>): Cause.Cause<never> =>
+  Cause.fromReasons(cause.reasons.map((reason) =>
+    Cause.isFailReason(reason)
+      ? Cause.makeDieReason(reason.error).annotate(Cause.reasonAnnotations(reason))
+      : reason
+  ))
+
 /**
  * Builds a transaction wrapper that begins top-level transactions, uses
  * savepoints for nested transactions, commits on success, and rolls back on
@@ -424,15 +444,19 @@ export const makeWithTransaction = <I, S>(options: {
                         )
                       ),
                       (exit) => {
-                        let effect: Effect.Effect<void>
+                        let effect: Effect.Effect<void, SqlError>
                         if (Exit.isSuccess(exit)) {
                           if (id === 0) {
                             span.event("effect.sql.transaction.commit", clock.currentTimeNanosUnsafe())
                             const onCommitFailure = options.onCommitFailure
-                            effect = Effect.orDie(options.commit(conn))
-                            if (onCommitFailure) {
-                              effect = Effect.onError(effect, () => Effect.orDie(onCommitFailure(conn)))
-                            }
+                            effect = onCommitFailure
+                              ? Effect.catchCause(options.commit(conn), (commitCause) =>
+                                Effect.matchCauseEffect(onCommitFailure(conn), {
+                                  onFailure: (cleanupCause) =>
+                                    Effect.failCause(failuresToDefects(Cause.combine(commitCause, cleanupCause))),
+                                  onSuccess: () => Effect.failCause(commitCause)
+                                }))
+                              : options.commit(conn)
                           } else {
                             span.event("effect.sql.transaction.savepoint", clock.currentTimeNanosUnsafe())
                             effect = Effect.void

package/src/testing/TestCrypto.ts

@@ -0,0 +1,94 @@
+/**
+ * Provides a deterministic implementation of the Effect `Crypto` service for
+ * tests.
+ *
+ * Random bytes, numbers, shuffles, UUIDs, and ULIDs are derived from a seeded
+ * pseudo-random generator. Digest operations are delegated to an underlying
+ * platform `Crypto` service.
+ *
+ * @stability unstable
+ * @since 4.0.0
+ */
+import * as Crypto from "../Crypto.ts"
+import * as Effect from "../Effect.ts"
+import * as Layer from "../Layer.ts"
+import * as Random from "../Random.ts"
+
+/**
+ * Creates a deterministic `Crypto` service using a seeded pseudo-random
+ * generator.
+ *
+ * **When to use**
+ *
+ * Use to construct a `Crypto` service whose random operations are reproducible
+ * in tests while preserving the digest implementation of a platform `Crypto`
+ * service.
+ *
+ * **Details**
+ *
+ * The effect requires an existing `Crypto` service and delegates digest
+ * operations to it. Each evaluation starts a new random sequence from `seed`;
+ * every other random operation is derived from that sequence.
+ *
+ * **Gotchas**
+ *
+ * The generated values are deterministic and must not be used for
+ * security-sensitive purposes. The sequence depends on the order in which
+ * random operations are evaluated. UUIDv7 and ULID values also include the
+ * current `Clock` time, which must be controlled separately when their complete
+ * output needs to be reproducible.
+ *
+ * @see {@link layer} for providing the service as a layer
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.0
+ */
+export const make: (
+  seed: string | number
+) => Effect.Effect<Crypto.Crypto, never, Crypto.Crypto> = Effect.fnUntraced(
+  function*(_seed: string | number) {
+    const crypto = yield* Crypto.Crypto
+    const seededRandom = yield* Random.Random
+    return Crypto.make({
+      randomBytes: (size) => {
+        const bytes = new Uint8Array(size)
+        for (let i = 0; i < size; i++) {
+          bytes[i] = Math.floor(seededRandom.nextDoubleUnsafe() * 256)
+        }
+        return bytes
+      },
+      digest: crypto.digest
+    })
+  },
+  (effect, seed) => Random.withSeed(effect, seed)
+)
+
+/**
+ * Creates a layer that provides deterministic `Crypto` random operations from
+ * a seed.
+ *
+ * **When to use**
+ *
+ * Use to provide reproducible random bytes, numbers, shuffles, UUIDs, and ULIDs
+ * to an Effect program under test.
+ *
+ * **Details**
+ *
+ * The layer requires an existing platform `Crypto` service whose digest
+ * implementation is retained. Each layer build starts the random sequence from
+ * `seed`.
+ *
+ * **Gotchas**
+ *
+ * UUIDv7 and ULID values also depend on the current `Clock`. Provide a test
+ * clock when their complete output needs to be reproducible.
+ *
+ * @see {@link make} for constructing the service directly
+ *
+ * @stability unstable
+ * @category layers
+ * @since 4.0.0
+ */
+export const layer = (seed: string | number): Layer.Layer<Crypto.Crypto, never, Crypto.Crypto> =>
+  Layer.effect(Crypto.Crypto, make(seed))

package/src/testing/index.ts

@@ -17,6 +17,12 @@ export * as TestClock from "./TestClock.ts"
  */
 export * as TestConsole from "./TestConsole.ts"
 
+/**
+ * @stability unstable
+ * @since 4.0.0
+ */
+export * as TestCrypto from "./TestCrypto.ts"
+
 /**
  * @stability unstable
  * @since 4.0.0

package/src/workflow/DurableDeferred.ts

@@ -10,7 +10,6 @@
  * @stability unstable
  * @since 4.0.0
  */
-import * as Arr from "../Array.ts"
 import type { NonEmptyReadonlyArray } from "../Array.ts"
 import type * as Brand from "../Brand.ts"
 import * as Cause from "../Cause.ts"
@@ -18,8 +17,9 @@ import * as Context from "../Context.ts"
 import * as Effect from "../Effect.ts"
 import * as Base64Url from "../encoding/Base64Url.ts"
 import * as Exit from "../Exit.ts"
-import * as Filter from "../Filter.ts"
+import * as Fiber from "../Fiber.ts"
 import { dual } from "../Function.ts"
+import * as Latch from "../Latch.ts"
 import * as Option from "../Option.ts"
 import * as Schema from "../Schema.ts"
 import * as SchemaGetter from "../SchemaGetter.ts"
@@ -180,6 +180,20 @@ export {
  * Runs an effect and records its exit into the durable deferred, resuming
  * workflows that are waiting on that deferred.
  *
+ * **Details**
+ *
+ * The effect and the write of its exit count as one in-flight activity of the
+ * workflow, so concurrent branches parked on durable waits do not suspend the
+ * run until the exit is recorded. This applies even when the effect itself is
+ * not an activity. If the effect parks on a durable wait, the run suspends
+ * once the other in-flight activities finish, and nothing is recorded.
+ *
+ * **Gotchas**
+ *
+ * A long-running effect keeps the run active instead of letting a parked
+ * sibling suspend it. Completing a deferred the run is waiting on still
+ * interrupts and replays the run.
+ *
  * @stability unstable
  * @category combinators
  * @since 4.0.0
@@ -189,6 +203,20 @@ export const into: {
    * Runs an effect and records its exit into the durable deferred, resuming
    * workflows that are waiting on that deferred.
    *
+   * **Details**
+   *
+   * The effect and the write of its exit count as one in-flight activity of the
+   * workflow, so concurrent branches parked on durable waits do not suspend the
+   * run until the exit is recorded. This applies even when the effect itself is
+   * not an activity. If the effect parks on a durable wait, the run suspends
+   * once the other in-flight activities finish, and nothing is recorded.
+   *
+   * **Gotchas**
+   *
+   * A long-running effect keeps the run active instead of letting a parked
+   * sibling suspend it. Completing a deferred the run is waiting on still
+   * interrupts and replays the run.
+   *
    * @stability unstable
    * @category combinators
    * @since 4.0.0
@@ -210,6 +238,20 @@ export const into: {
    * Runs an effect and records its exit into the durable deferred, resuming
    * workflows that are waiting on that deferred.
    *
+   * **Details**
+   *
+   * The effect and the write of its exit count as one in-flight activity of the
+   * workflow, so concurrent branches parked on durable waits do not suspend the
+   * run until the exit is recorded. This applies even when the effect itself is
+   * not an activity. If the effect parks on a durable wait, the run suspends
+   * once the other in-flight activities finish, and nothing is recorded.
+   *
+   * **Gotchas**
+   *
+   * A long-running effect keeps the run active instead of letting a parked
+   * sibling suspend it. Completing a deferred the run is waiting on still
+   * interrupts and replays the run.
+   *
    * @stability unstable
    * @category combinators
    * @since 4.0.0
@@ -243,43 +285,86 @@ export const into: {
     | Error["DecodingServices"]
     | Success["EncodingServices"]
     | Error["EncodingServices"]
-  > =>
-    Effect.contextWith(
-      (context: Context.Context<WorkflowEngine | WorkflowInstance>) => {
-        const engine = Context.get(context, EngineTag)
-        const parentInstance = Context.get(context, InstanceTag)
-        const instance = { ...parentInstance }
-        return Effect.onExit(
-          Effect.provideService(effect, InstanceTag, instance),
-          Effect.fnUntraced(function*(exit) {
-            if (Exit.isFailure(exit)) {
-              const [interrupts, reasons] = Arr.partition(
-                exit.cause.reasons,
-                Filter.fromPredicate(Cause.isInterruptReason)
-              )
-              if (interrupts.length === exit.cause.reasons.length) {
-                // An interrupt-only exit is never a result: the effect was
-                // suspended, preempted or interrupted, so record nothing.
-                if (instance.suspended) {
-                  parentInstance.suspended = true
-                }
-                return
-              } else if (interrupts.length > 0) {
-                exit = Exit.failCause(Cause.fromReasons(reasons))
-              }
-            }
-            yield* engine.deferredDone(self, {
-              workflowName: instance.workflow._tag,
-              executionId: instance.executionId,
-              deferredName: self.name,
-              exit
-            })
-          })
-        )
-      }
-    )
+  > => recordHeld(effect, self, false)
 )
 
+/**
+ * Records `exit` into `self`. An interrupt-only exit is never a result: the
+ * effect was suspended, preempted or interrupted, so nothing is recorded.
+ * Interrupts mixed into a failure are dropped from the recorded cause.
+ */
+const recordExit = (
+  engine: WorkflowEngine["Service"],
+  instance: WorkflowInstance["Service"],
+  self: DurableDeferred<any, any>,
+  exit: Exit.Exit<any, any>
+) => {
+  if (Exit.isFailure(exit)) {
+    if (Cause.hasInterruptsOnly(exit.cause)) return Effect.void
+    if (Cause.hasInterrupts(exit.cause)) {
+      exit = Exit.failCause(Cause.fromReasons(
+        exit.cause.reasons.filter((reason) => !Cause.isInterruptReason(reason))
+      ))
+    }
+  }
+  return engine.deferredDone(self, {
+    workflowName: instance.workflow._tag,
+    executionId: instance.executionId,
+    deferredName: self.name,
+    exit
+  })
+}
+
+/**
+ * Runs `effect` as one activity of the enclosing workflow and records its exit
+ * into `self`, returning a previously recorded exit instead when `checkCache`
+ * is set. The hold spans the lookup, `effect` and the write, so a parked
+ * sibling cannot suspend the run before the continuation starts.
+ */
+const recordHeld = Effect.fnUntraced(function*<A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  self: DurableDeferred<any, any>,
+  checkCache: boolean
+): Effect.fn.Return<A, E, R | WorkflowEngine | WorkflowInstance> {
+  const engine = yield* EngineTag
+  const instance = yield* InstanceTag
+  const exit = yield* Workflow.wrapActivityResult(
+    Effect.gen(function*() {
+      if (checkCache) {
+        const cached = yield* engine.deferredResult(self)
+        if (Option.isSome(cached)) return cached
+      }
+      // `effect` counts on its own activity state, so a durable await inside
+      // it waits for its own siblings and not for the hold above. The copy
+      // starts unsuspended: a parked arm of an enclosing race leaves that
+      // copy marked suspended while only interrupting its own fiber.
+      const local: WorkflowInstance["Service"] = {
+        ...instance,
+        suspended: false,
+        activityState: { count: 0, latch: Latch.makeUnsafe() }
+      }
+      // A parked `effect` interrupts the fiber it runs on. The child fiber
+      // keeps that from skipping the suspension handling below.
+      const fiber = yield* effect.pipe(
+        Effect.provideService(InstanceTag, local),
+        Effect.onExit((exit) => recordExit(engine, instance, self, exit)),
+        Effect.forkChild({ startImmediately: true })
+      )
+      const exit = yield* Effect.onInterrupt(Fiber.await(fiber), () => Fiber.interrupt(fiber))
+      return local.suspended && Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause)
+        ? Option.none()
+        : Option.some(exit)
+    }),
+    // Every branch of `effect` parked: release the hold and let the enclosing
+    // activities finish before suspending. External preemption does not wait.
+    Option.isNone
+  )
+  if (Option.isNone(exit)) {
+    return yield* Workflow.suspend(instance)
+  }
+  return yield* exit.value
+})
+
 /**
  * Runs effects as a durable race, returning a previously persisted result when
  * present or completing a named deferred with the first result.
@@ -312,17 +397,7 @@ export const raceAll = <
     success: options.success,
     error: options.error
   })
-  return Effect.gen(function*() {
-    const engine = yield* EngineTag
-    const exit = yield* engine.deferredResult(deferred)
-    if (Option.isSome(exit)) {
-      return yield* exit.value
-    }
-    return yield* into(
-      Effect.raceAll(options.effects),
-      deferred
-    )
-  })
+  return recordHeld(Effect.raceAll(options.effects), deferred, true)
 }
 
 /**

package/src/workflow/WorkflowEngine.ts

@@ -826,7 +826,8 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
           Workflow.intoResult,
           Effect.provideService(WorkflowInstance, activityInstance),
           Effect.onExit((exit) => {
-            state.exit = exit
+            // A preempted activity must run again on the next replay.
+            state.exit = Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause) ? undefined : exit
             return Effect.void
           })
         )