effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/workers/Worker.ts

@@ -1,4 +1,28 @@
 /**
+ * Client-side worker primitives shared by browser, Node, and Bun platform
+ * packages.
+ *
+ * A `WorkerPlatform` turns a numeric worker id into a long-lived `Worker`
+ * client using a runtime-specific `Spawner`. This module is the low-level
+ * building block used by worker-backed RPC clients and by platform adapters
+ * that need to communicate with dedicated workers, shared workers,
+ * `MessagePort`s, worker threads, or child-process transports while keeping
+ * setup, message handling, and cleanup inside `Effect` scopes.
+ *
+ * The worker protocol separates spawning from message delivery. Calls to
+ * `send` made before the platform reports readiness are buffered and flushed
+ * after `run` receives the ready signal, so a spawned worker must eventually be
+ * run or buffered messages will never leave the client. Message values are
+ * passed through `postMessage`, which means callers are responsible for
+ * encoding payloads into values supported by the selected runtime's structured
+ * clone implementation. Transfer lists can avoid copies for buffers, ports, or
+ * other transferable values, but ownership moves to the worker and invalid
+ * transfer lists surface as `WorkerSendError`s. Incoming messages are handled
+ * by forking each handler invocation into the worker run's `FiberSet`, so
+ * processing is concurrent rather than serialized; use an explicit queue,
+ * semaphore, or protocol-level acknowledgement when ordering or back pressure
+ * matters.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -11,8 +35,11 @@ import * as Scope from "../../Scope.ts"
 import { WorkerError, WorkerSendError } from "./WorkerError.ts"
 
 /**
- * @since 4.0.0
+ * Service that spawns effect `Worker` instances for numeric worker ids using
+ * the configured `Spawner`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export class WorkerPlatform extends Context.Service<WorkerPlatform, {
   readonly spawn: <O = unknown, I = unknown>(
@@ -21,8 +48,12 @@ export class WorkerPlatform extends Context.Service<WorkerPlatform, {
 }>()("effect/workers/Worker/WorkerPlatform") {}
 
 /**
- * @since 4.0.0
+ * Effect-based worker abstraction that can send input messages and run a
+ * long-lived handler for output messages, failing with `WorkerError` or handler
+ * errors.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Worker<O = unknown, I = unknown> {
   readonly send: (
@@ -40,8 +71,12 @@ export interface Worker<O = unknown, I = unknown> {
 }
 
 /**
- * @since 4.0.0
+ * Wraps platform-specific send and run functions into a `Worker`, translating
+ * platform ready/data messages and running the optional `onSpawn` effect when
+ * the worker reports readiness.
+ *
  * @category models
+ * @since 4.0.0
  */
 export const makeUnsafe = (options: {
   readonly send: (
@@ -63,22 +98,30 @@ export const makeUnsafe = (options: {
 })
 
 /**
- * @since 4.0.0
+ * Internal worker platform protocol message: `[0]` signals readiness and
+ * `[1, payload]` carries data.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type PlatformMessage = readonly [ready: 0] | readonly [data: 1, unknown]
 
 /**
- * @since 4.0.0
+ * Phantom identifier for the service that maps worker ids to platform-specific
+ * worker instances.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface Spawner {
   readonly _: unique symbol
 }
 
 /**
- * @since 4.0.0
+ * Context service tag for the worker `SpawnerFn`.
+ *
  * @category tags
+ * @since 4.0.0
  */
 export const Spawner: Context.Service<
   Spawner,
@@ -86,22 +129,31 @@ export const Spawner: Context.Service<
 > = Context.Service("effect/workers/Worker/Spawner")
 
 /**
- * @since 4.0.0
+ * Function that creates or locates a platform-specific worker instance for a
+ * numeric worker id.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface SpawnerFn<W = unknown> {
   (id: number): W
 }
 
 /**
- * @since 4.0.0
+ * Creates a layer that provides a worker `Spawner` service from a `SpawnerFn`.
+ *
  * @category layers
+ * @since 4.0.0
  */
 export const layerSpawner: <W = unknown>(
   spawner: SpawnerFn<W>
 ) => Layer.Layer<Spawner> = Layer.succeed(Spawner)
 
 /**
+ * Creates a `WorkerPlatform` from platform-specific setup and listen hooks,
+ * buffering sent messages until the worker is ready and scoping port cleanup to
+ * the worker run.
+ *
  * @since 4.0.0
  */
 export const makePlatform = <W>() =>

package/src/unstable/workers/WorkerError.ts

@@ -1,4 +1,23 @@
 /**
+ * Typed error definitions for the unstable worker APIs.
+ *
+ * `WorkerError` is the shared error channel for `WorkerPlatform` and
+ * `WorkerRunnerPlatform` implementations. The nested reason identifies where a
+ * platform failure happened: spawning or setting up a worker, sending through
+ * `postMessage`, receiving worker events, or handling a runtime-specific
+ * failure that does not fit the other categories. This is useful when building
+ * worker-backed RPC clients and servers, implementing a platform adapter, or
+ * recovering differently from startup, transport, and worker-exit failures.
+ *
+ * Worker transports cross browser, Node, Bun, and child-process runtimes, so the
+ * original cause is best treated as diagnostic data. Spawn failures can mean the
+ * runner is not actually executing inside a worker context, send failures often
+ * come from structured-clone or transfer-list problems, and receive failures
+ * may be reported as `messageerror`, `error`, or exit events depending on the
+ * runtime. The `WorkerErrorReason` schema supports encoding and decoding the
+ * tagged reasons, but message payloads still need to be valid for the selected
+ * worker protocol and runtime.
+ *
  * @since 4.0.0
  */
 import { hasProperty } from "../../Predicate.ts"
@@ -7,20 +26,26 @@ import * as Schema from "../../Schema.ts"
 const TypeId = "~effect/workers/WorkerError" as const
 
 /**
- * @since 4.0.0
+ * Type-level identifier used to brand `WorkerError` values.
+ *
  * @category Symbols
+ * @since 4.0.0
  */
 export type TypeId = typeof TypeId
 
 /**
- * @since 4.0.0
+ * Returns `true` when a value is a `WorkerError`.
+ *
  * @category Guards
+ * @since 4.0.0
  */
 export const isWorkerError = (u: unknown): u is WorkerError => hasProperty(u, TypeId)
 
 /**
- * @since 4.0.0
+ * Worker error reason for failures while spawning or setting up a worker.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export class WorkerSpawnError extends Schema.ErrorClass<WorkerSpawnError>(
   "effect/workers/WorkerError/WorkerSpawnError"
@@ -31,8 +56,10 @@ export class WorkerSpawnError extends Schema.ErrorClass<WorkerSpawnError>(
 }) {}
 
 /**
- * @since 4.0.0
+ * Worker error reason for failures while sending a message to a worker.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export class WorkerSendError extends Schema.ErrorClass<WorkerSendError>(
   "effect/workers/WorkerError/WorkerSendError"
@@ -43,8 +70,11 @@ export class WorkerSendError extends Schema.ErrorClass<WorkerSendError>(
 }) {}
 
 /**
- * @since 4.0.0
+ * Worker error reason for failures while receiving or handling a message from a
+ * worker.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export class WorkerReceiveError extends Schema.ErrorClass<WorkerReceiveError>(
   "effect/workers/WorkerError/WorkerReceiveError"
@@ -55,8 +85,10 @@ export class WorkerReceiveError extends Schema.ErrorClass<WorkerReceiveError>(
 }) {}
 
 /**
- * @since 4.0.0
+ * Worker error reason for an unclassified worker failure.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export class WorkerUnknownError extends Schema.ErrorClass<WorkerUnknownError>(
   "effect/workers/WorkerError/WorkerUnknownError"
@@ -67,8 +99,10 @@ export class WorkerUnknownError extends Schema.ErrorClass<WorkerUnknownError>(
 }) {}
 
 /**
- * @since 4.0.0
+ * Union of the specific failure reasons that can be wrapped by a `WorkerError`.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export type WorkerErrorReason =
   | WorkerSpawnError
@@ -77,8 +111,10 @@ export type WorkerErrorReason =
   | WorkerUnknownError
 
 /**
- * @since 4.0.0
+ * Schema for decoding and encoding all supported worker error reason variants.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export const WorkerErrorReason: Schema.Union<[
   typeof WorkerSpawnError,
@@ -93,8 +129,11 @@ export const WorkerErrorReason: Schema.Union<[
 ])
 
 /**
- * @since 4.0.0
+ * Error raised by worker APIs, wrapping a specific `WorkerErrorReason` and
+ * exposing its message and cause.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export class WorkerError extends Schema.ErrorClass<WorkerError>(TypeId)({
   _tag: Schema.tag("WorkerError"),
@@ -110,6 +149,8 @@ export class WorkerError extends Schema.ErrorClass<WorkerError>(TypeId)({
     } as any)
   }
   /**
+   * Marks this value as a worker error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId]: TypeId = TypeId

package/src/unstable/workers/WorkerRunner.ts

@@ -1,4 +1,25 @@
 /**
+ * Server-side worker runner primitives shared by the browser, Node, and Bun
+ * platform packages.
+ *
+ * A `WorkerRunnerPlatform` is installed in code that is already running inside
+ * a worker-like runtime. Starting it yields a `WorkerRunner`, which listens for
+ * parent or client requests, identifies each connection with a numeric port id,
+ * and sends responses back through the same transport. The main Effect use case
+ * is `RpcServer.layerProtocolWorkerRunner`, but platform adapters can also use
+ * these types to expose lower-level request handlers for dedicated workers,
+ * shared workers, worker threads, or child-process channels.
+ *
+ * The wire protocol is intentionally small: inbound messages are
+ * `PlatformMessage` values where `[0, payload]` is a request and `[1]` closes a
+ * port. Higher-level protocols are responsible for encoding request and
+ * response payloads before they cross the worker boundary. Values must still be
+ * accepted by the selected runtime's message mechanism, so structured-clone
+ * support, transfer lists, `messageerror` events, and single-port runtimes such
+ * as Node or Bun should be considered when choosing payload schemas and
+ * resource lifetimes. Handler effects run on the runtime captured by `run`, so
+ * services required by the handler must be provided to the running effect.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -7,8 +28,11 @@ import type * as Queue from "../../Queue.ts"
 import type { WorkerError } from "./WorkerError.ts"
 
 /**
- * @since 4.0.0
+ * Platform-neutral worker runner that receives inbound messages by port ID,
+ * sends outbound messages, and optionally exposes disconnect notifications.
+ *
  * @category models
+ * @since 4.0.0
  */
 export interface WorkerRunner<O = unknown, I = unknown> {
   readonly run: <A, E, R>(
@@ -28,14 +52,19 @@ export interface WorkerRunner<O = unknown, I = unknown> {
 }
 
 /**
- * @since 4.0.0
+ * Wire protocol message used by worker platforms: a request carrying input or a
+ * close signal.
+ *
  * @category models
+ * @since 4.0.0
  */
 export type PlatformMessage<I> = readonly [request: 0, I] | readonly [close: 1]
 
 /**
- * @since 4.0.0
+ * Context service that starts a platform-specific `WorkerRunner`.
+ *
  * @category models
+ * @since 4.0.0
  */
 export class WorkerRunnerPlatform extends Context.Service<WorkerRunnerPlatform, {
   readonly start: <O = unknown, I = unknown>() => Effect.Effect<WorkerRunner<O, I>, WorkerError>

package/src/unstable/workers/index.ts

@@ -5,7 +5,7 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * as Transferable from "./Transferable.ts"
 

package/src/unstable/workflow/Activity.ts

@@ -1,4 +1,24 @@
 /**
+ * The `Activity` module defines named, schema-backed effects that run at the
+ * side-effect boundary of a durable workflow. Activities are executed through a
+ * `WorkflowEngine`, encode their success and failure values with the provided
+ * schemas, and can be replayed from persisted results instead of rerunning the
+ * underlying effect.
+ *
+ * Use activities for work that should not be embedded directly in workflow
+ * control flow, such as calling external services, writing to databases,
+ * enqueueing durable jobs, short sleeps delegated by `DurableClock`, or racing
+ * multiple external operations with `raceAll`. Keep activity names and schemas
+ * stable because engines use them, together with the workflow execution and
+ * retry attempt, to identify stored results.
+ *
+ * Activities can be interrupted and retried, and workflow resumes may observe a
+ * completed encoded result or run the activity again depending on what the
+ * engine has persisted. Make external side effects idempotent, use
+ * `idempotencyKey` for stable request keys derived from the workflow execution,
+ * and include the current attempt only when each retry must address a distinct
+ * external operation.
+ *
  * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts"
@@ -19,8 +39,12 @@ import type { WorkflowEngine, WorkflowInstance } from "./WorkflowEngine.ts"
 const TypeId = "~effect/workflow/Activity"
 
 /**
- * @since 4.0.0
+ * Durable workflow activity that behaves as an `Effect` and records its name,
+ * result schemas, annotations, and encoded execution form for the workflow
+ * engine.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface Activity<
   Success extends Schema.Top = Schema.Void,
@@ -73,8 +97,11 @@ export interface Activity<
 }
 
 /**
- * @since 4.0.0
+ * Type-erased activity shape for APIs that only need the activity identity,
+ * name, annotations, and encoded execution.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface Any {
   readonly [TypeId]: typeof TypeId
@@ -84,8 +111,11 @@ export interface Any {
 }
 
 /**
- * @since 4.0.0
+ * Type-erased activity shape that also exposes success and error schemas for
+ * derived workflow APIs.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface AnyWithProps {
   readonly [TypeId]: typeof TypeId
@@ -96,8 +126,11 @@ export interface AnyWithProps {
 }
 
 /**
- * @since 4.0.0
+ * Creates a workflow activity from an effect, using the provided schemas to
+ * encode successes and failures for durable execution.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const make = <
   R,
@@ -178,18 +211,27 @@ const retryOnInterrupt = (
   )
 
 /**
- * @since 4.0.0
+ * Retries an effect with `Effect.retry` while updating `CurrentAttempt` for
+ * each attempt.
+ *
  * @category Error handling
+ * @since 4.0.0
  */
 export const retry: {
   /**
-   * @since 4.0.0
+   * Retries an effect with `Effect.retry` while updating `CurrentAttempt` for
+   * each attempt.
+   *
    * @category Error handling
+   * @since 4.0.0
    */
   <E, O extends Types.NoExcessProperties<Omit<Effect.Retry.Options<E>, "schedule">, O>>(options: O): <A, R>(self: Effect.Effect<A, E, R>) => Effect.Retry.Return<R, E, A, O>
   /**
-   * @since 4.0.0
+   * Retries an effect with `Effect.retry` while updating `CurrentAttempt` for
+   * each attempt.
+   *
    * @category Error handling
+   * @since 4.0.0
    */
   <A, E, R, O extends Types.NoExcessProperties<Omit<Effect.Retry.Options<E>, "schedule">, O>>(self: Effect.Effect<A, E, R>, options: O): Effect.Retry.Return<R, E, A, O>
 } = dual(
@@ -202,8 +244,11 @@ export const retry: {
 )
 
 /**
- * @since 4.0.0
+ * Context reference containing the current activity retry attempt, defaulting
+ * to `1`.
+ *
  * @category Attempts
+ * @since 4.0.0
  */
 export const CurrentAttempt = Context.Reference<number>(
   "effect/workflow/Activity/CurrentAttempt",
@@ -211,8 +256,11 @@ export const CurrentAttempt = Context.Reference<number>(
 )
 
 /**
- * @since 4.0.0
+ * Computes a deterministic activity idempotency key from the current workflow
+ * execution ID, the supplied name, and optionally the current attempt.
+ *
  * @category Idempotency
+ * @since 4.0.0
  */
 export const idempotencyKey: (
   name: string,
@@ -233,8 +281,11 @@ export const idempotencyKey: (
 })
 
 /**
- * @since 4.0.0
+ * Runs a non-empty collection of activities as a durable race and returns the
+ * first completed success or failure using unioned success and error schemas.
+ *
  * @category Racing
+ * @since 4.0.0
  */
 export const raceAll = <const Activities extends NonEmptyReadonlyArray<Any>>(
   name: string,
@@ -256,7 +307,7 @@ export const raceAll = <const Activities extends NonEmptyReadonlyArray<Any>>(
     error: Schema.Union(
       activities.map((activity) => (activity as any).errorSchema)
     ),
-    effects: activities.map((activity) => (activity as any).asEffect()) as any
+    effects: activities.map((activity) => (activity as any)) as any
   }) as any
 
 // -----------------------------------------------------------------------------

package/src/unstable/workflow/DurableClock.ts

@@ -1,4 +1,18 @@
 /**
+ * Durable workflow clocks provide workflow-safe timers and sleep operations.
+ *
+ * Use this module when a workflow needs to pause until a timeout, reminder,
+ * deadline, retry delay, or other scheduled wake-up. Short sleeps can run as
+ * in-memory activities, while longer sleeps are scheduled with the workflow
+ * engine and resumed through a durable deferred signal when the timer fires.
+ *
+ * Because workflows may be replayed, timer names and durations should be
+ * deterministic and stable for a given workflow path. Avoid deriving them from
+ * ambient wall-clock state, and give distinct sleeps distinct names so replayed
+ * executions can be matched with the correct scheduled wake-up. Lower the
+ * in-memory threshold when a delay must be handled by the workflow engine
+ * rather than the current process.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -12,8 +26,11 @@ import type { WorkflowEngine, WorkflowInstance } from "./WorkflowEngine.ts"
 const TypeId = "~effect/workflow/DurableClock"
 
 /**
- * @since 4.0.0
+ * Represents a durable workflow timer with a name, duration, and deferred
+ * completed when the timer wakes.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface DurableClock {
   readonly [TypeId]: typeof TypeId
@@ -23,8 +40,11 @@ export interface DurableClock {
 }
 
 /**
- * @since 4.0.0
+ * Creates a durable clock definition and its associated deferred wake-up
+ * signal.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const make = (options: {
   readonly name: string
@@ -48,8 +68,11 @@ const InstanceTag = Context.Service<
 )
 
 /**
- * @since 1.0.0
+ * Sleeps inside a workflow, using an in-memory activity for durations at or
+ * below the threshold and scheduling a durable clock for longer durations.
+ *
  * @category Sleeping
+ * @since 4.0.0
  */
 export const sleep: (
   options: {