effect 4.0.0-beta.66 → 4.0.0-beta.68

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,21 +5,101 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * @since 1.0.0
+ * Utilities for marking the parts of worker messages that should be transferred
+ * through `postMessage` instead of copied by the structured clone algorithm.
+ *
+ * This module is used with worker message schemas to collect
+ * `globalThis.Transferable` values while encoding a message, so the worker
+ * platform can pass the collected list as the `postMessage` transfer list.
+ * Common cases include sending large `Uint8Array` payloads, `ImageData` pixel
+ * buffers, or `MessagePort` channels without paying for an extra copy.
+ *
+ * Transferable annotations do not make an otherwise unsupported value
+ * structured-cloneable; the encoded message still has to be valid for
+ * `postMessage`. Transferring also moves ownership to the receiver, so buffers
+ * are detached from the sender after the send completes. Be careful when a
+ * typed array view shares a backing buffer with other data, since collecting
+ * that buffer transfers ownership of the whole buffer.
+ *
+ * @since 4.0.0
  */
 export * as Transferable from "./Transferable.ts"
 
 /**
+ * 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
  */
 export * as Worker from "./Worker.ts"
 
 /**
+ * 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
  */
 export * as WorkerError from "./WorkerError.ts"
 
 /**
+ * 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
  */
 export * as WorkerRunner from "./WorkerRunner.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"
 
 /**
+ * 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
- * @category Models
  */
 export interface Activity<
   Success extends Schema.Top = Schema.Void,
@@ -73,8 +97,11 @@ export interface Activity<
 }
 
 /**
+ * Type-erased activity shape for APIs that only need the activity identity,
+ * name, annotations, and encoded execution.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface Any {
   readonly [TypeId]: typeof TypeId
@@ -84,8 +111,11 @@ export interface Any {
 }
 
 /**
+ * Type-erased activity shape that also exposes success and error schemas for
+ * derived workflow APIs.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface AnyWithProps {
   readonly [TypeId]: typeof TypeId
@@ -96,8 +126,11 @@ export interface AnyWithProps {
 }
 
 /**
+ * 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
- * @category Constructors
  */
 export const make = <
   R,
@@ -178,18 +211,27 @@ const retryOnInterrupt = (
   )
 
 /**
+ * Retries an effect with `Effect.retry` while updating `CurrentAttempt` for
+ * each attempt.
+ *
+ * @category error handling
  * @since 4.0.0
- * @category Error handling
  */
 export const retry: {
   /**
+   * Retries an effect with `Effect.retry` while updating `CurrentAttempt` for
+   * each attempt.
+   *
+   * @category error handling
    * @since 4.0.0
-   * @category Error handling
    */
   <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>
   /**
+   * Retries an effect with `Effect.retry` while updating `CurrentAttempt` for
+   * each attempt.
+   *
+   * @category error handling
    * @since 4.0.0
-   * @category Error handling
    */
   <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,

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"
 
 /**
+ * Represents a durable workflow timer with a name, duration, and deferred
+ * completed when the timer wakes.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface DurableClock {
   readonly [TypeId]: typeof TypeId
@@ -23,8 +40,11 @@ export interface DurableClock {
 }
 
 /**
+ * Creates a durable clock definition and its associated deferred wake-up
+ * signal.
+ *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 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: {