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

package/src/unstable/workflow/Workflow.ts

@@ -1,4 +1,25 @@
 /**
+ * The `Workflow` module defines typed durable workflow descriptions and the
+ * helpers used to execute them through a `WorkflowEngine`. A workflow combines
+ * a stable name, a struct payload schema, success and error schemas, and an
+ * idempotency key so callers can derive deterministic execution IDs, execute or
+ * discard runs, poll results, interrupt or resume suspended executions, and
+ * register handlers with `toLayer`.
+ *
+ * Workflows are intended for long-running business processes that coordinate
+ * activities, durable deferreds, durable clocks, retries, and compensation.
+ * Keep external side effects at activity boundaries so engine implementations
+ * can safely persist, suspend, and resume execution state. Running activities
+ * can delay workflow suspension until they finish or suspend, and compensation
+ * registered with `withCompensation` only applies to top-level workflow
+ * effects, not nested activities.
+ *
+ * When exposing workflows through `WorkflowProxy`, remember that proxy APIs are
+ * derived from the workflow name and schemas. Discard execution returns the
+ * `executionId` instead of the workflow result, resume requires the persisted
+ * `executionId`, and idempotency keys must remain stable for the same logical
+ * request.
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -26,8 +47,12 @@ import type { WorkflowEngine, WorkflowInstance } from "./WorkflowEngine.ts"
 const TypeId = "~effect/workflow/Workflow"
 
 /**
+ * Durable workflow definition with typed payload, success, and error schemas
+ * plus operations for execution, polling, interruption, resumption, and
+ * registration.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface Workflow<
   Name extends string,
@@ -167,6 +192,9 @@ export interface Workflow<
 }
 
 /**
+ * Schema constraint for workflow payload schemas that expose struct fields.
+ *
+ * @category schemas
  * @since 4.0.0
  */
 export interface AnyStructSchema extends Schema.Top {
@@ -174,8 +202,11 @@ export interface AnyStructSchema extends Schema.Top {
 }
 
 /**
+ * Type-level marker for services associated with a specific workflow
+ * execution name.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface Execution<Name extends string> {
   readonly _: unique symbol
@@ -183,8 +214,11 @@ export interface Execution<Name extends string> {
 }
 
 /**
+ * Type-erased workflow shape for APIs that operate on workflows without
+ * preserving their specific payload, success, or error types.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface Any {
   readonly [TypeId]: typeof TypeId
@@ -197,8 +231,11 @@ export interface Any {
 }
 
 /**
+ * Type-erased workflow shape that also exposes executable operations needed by
+ * workflow proxy and engine helpers.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export interface AnyWithProps extends Any {
   readonly payloadSchema: AnyStructSchema
@@ -214,8 +251,10 @@ export interface AnyWithProps extends Any {
 }
 
 /**
+ * Extracts the payload schema from a `Workflow`.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type PayloadSchema<W> = W extends Workflow<
   infer _Name,
@@ -226,8 +265,11 @@ export type PayloadSchema<W> = W extends Workflow<
   : never
 
 /**
+ * Computes the schema services required by clients that execute or poll
+ * workflows.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type RequirementsClient<Workflows extends Any> = Workflows extends Workflow<
   infer _Name,
@@ -241,8 +283,11 @@ export type RequirementsClient<Workflows extends Any> = Workflows extends Workfl
   : never
 
 /**
+ * Computes the schema services required by handlers that decode workflow
+ * payloads and encode workflow results.
+ *
+ * @category models
  * @since 4.0.0
- * @category Models
  */
 export type RequirementsHandler<Workflows extends Any> = Workflows extends Workflow<
   infer _Name,
@@ -270,8 +315,12 @@ const InstanceTag = Context.Service<
 )
 
 /**
+ * Creates a durable workflow definition with schemas, annotations, and
+ * deterministic execution IDs derived from the workflow name and idempotency
+ * key.
+ *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const make = <
   const Name extends string,
@@ -393,30 +442,40 @@ export const make = <
 const ResultTypeId = "~effect/workflow/Workflow/Result"
 
 /**
- * @since 4.0.0
+ * Returns `true` when a value is a workflow `Result`.
+ *
  * @category Result
+ * @since 4.0.0
  */
 export const isResult = <A = unknown, E = unknown>(
   u: unknown
 ): u is Result<A, E> => Predicate.hasProperty(u, ResultTypeId)
 
 /**
- * @since 4.0.0
+ * Result of a workflow execution, either a completed exit or a suspended
+ * workflow state.
+ *
  * @category Result
+ * @since 4.0.0
  */
 export type Result<A, E> = Complete<A, E> | Suspended
 
 /**
- * @since 4.0.0
+ * Encoded representation of a workflow `Result`.
+ *
  * @category Result
+ * @since 4.0.0
  */
 export type ResultEncoded<A, E> =
   | CompleteEncoded<A, E>
   | typeof Suspended.Encoded
 
 /**
- * @since 4.0.0
+ * Encoded representation of a completed workflow result containing an encoded
+ * `Exit`.
+ *
  * @category Result
+ * @since 4.0.0
  */
 export interface CompleteEncoded<A, E> {
   readonly _tag: "Complete"
@@ -424,6 +483,10 @@ export interface CompleteEncoded<A, E> {
 }
 
 /**
+ * Schema constructor for `Complete` workflow results using the supplied
+ * success and error schemas.
+ *
+ * @category schemas
  * @since 4.0.0
  */
 export interface CompleteSchema<
@@ -441,18 +504,25 @@ export interface CompleteSchema<
 }
 
 /**
- * @since 4.0.0
+ * Workflow result representing a completed execution with its success or
+ * failure `Exit`.
+ *
  * @category Result
+ * @since 4.0.0
  */
 export class Complete<A, E> extends Data.TaggedClass("Complete")<{
   readonly exit: Exit.Exit<A, E>
 }> {
   /**
+   * Marks this value as a workflow result for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ResultTypeId] = ResultTypeId
 
   /**
+   * Builds the schema for completed workflow results from success and error schemas.
+   *
    * @since 4.0.0
    */
   static Schema<Success extends Schema.Top, Error extends Schema.Top>(options: {
@@ -506,8 +576,11 @@ export class Complete<A, E> extends Data.TaggedClass("Complete")<{
 }
 
 /**
- * @since 4.0.0
+ * Workflow result representing a suspended execution, optionally carrying the
+ * cause that triggered suspension.
+ *
  * @category Result
+ * @since 4.0.0
  */
 export class Suspended extends Schema.Class<Suspended>(
   "effect/workflow/Workflow/Suspended"
@@ -516,14 +589,19 @@ export class Suspended extends Schema.Class<Suspended>(
   cause: Schema.optional(Schema.Cause(Schema.Never, Schema.Defect))
 }) {
   /**
+   * Marks this value as a workflow result for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [ResultTypeId] = ResultTypeId
 }
 
 /**
- * @since 4.0.0
+ * Creates a schema for workflow results using the supplied success and error
+ * schemas.
+ *
  * @category Result
+ * @since 4.0.0
  */
 export const Result = <
   Success extends Schema.Top,
@@ -536,8 +614,10 @@ export const Result = <
 const AnyOrVoid = Schema.Union([Schema.Any, Schema.Void])
 
 /**
- * @since 4.0.0
+ * Codec for encoded workflow results with generic success and error payloads.
+ *
  * @category Result
+ * @since 4.0.0
  */
 export const ResultEncoded: Schema.Codec<ResultEncoded<any, any>> = Schema.toEncoded(
   Schema.toCodecJson(
@@ -549,8 +629,12 @@ export const ResultEncoded: Schema.Codec<ResultEncoded<any, any>> = Schema.toEnc
 ) as any
 
 /**
- * @since 4.0.0
+ * Runs an effect as a workflow execution and converts its outcome into a
+ * `Result`, handling suspension, defect capture, interruption, and workflow
+ * scope finalization.
+ *
  * @category Result
+ * @since 4.0.0
  */
 export const intoResult = <A, E, R>(
   effect: Effect.Effect<A, E, R>
@@ -609,8 +693,11 @@ export const intoResult = <A, E, R>(
   })
 
 /**
- * @since 4.0.0
+ * Wraps an activity-like effect so workflow suspension waits for currently
+ * running activities to finish or suspend.
+ *
  * @category Result
+ * @since 4.0.0
  */
 export const wrapActivityResult = <A, E, R>(
   effect: Effect.Effect<A, E, R>,
@@ -661,8 +748,8 @@ const waitForZero = Effect.fnUntraced(function*(instance: WorkflowInstance["Serv
  * The workflow scope is only closed when the workflow execution fully
  * completes.
  *
- * @since 1.0.0
  * @category Scope
+ * @since 4.0.0
  */
 export const scope: Effect.Effect<
   Scope.Scope,
@@ -679,8 +766,8 @@ export const scope: Effect.Effect<
  * The workflow scope is only closed when the workflow execution fully
  * completes.
  *
- * @since 1.0.0
  * @category Scope
+ * @since 4.0.0
  */
 export const provideScope = <A, E, R>(
   effect: Effect.Effect<A, E, R>
@@ -688,8 +775,11 @@ export const provideScope = <A, E, R>(
   Effect.flatMap(scope, (scope) => Scope.provide(effect, scope))
 
 /**
- * @since 1.0.0
+ * Adds an exit finalizer to the current workflow scope, preserving the
+ * services available when the finalizer is registered.
+ *
  * @category Scope
+ * @since 4.0.0
  */
 export const addFinalizer: <R>(
   f: (exit: Exit.Exit<unknown, unknown>) => Effect.Effect<void, never, R>
@@ -713,8 +803,8 @@ export const addFinalizer: <R>(
  * NOTE: Compensation will not work for nested activities. Compensation
  * finalizers are only registered for top-level effects in the workflow.
  *
- * @since 1.0.0
  * @category Compensation
+ * @since 4.0.0
  */
 export const withCompensation: {
   /**
@@ -725,8 +815,8 @@ export const withCompensation: {
    * NOTE: Compensation will not work for nested activities. Compensation
    * finalizers are only registered for top-level effects in the workflow.
    *
-   * @since 1.0.0
    * @category Compensation
+   * @since 4.0.0
    */
   <A, R2>(
     compensation: (value: A, cause: Cause.Cause<unknown>) => Effect.Effect<void, never, R2>
@@ -741,8 +831,8 @@ export const withCompensation: {
    * NOTE: Compensation will not work for nested activities. Compensation
    * finalizers are only registered for top-level effects in the workflow.
    *
-   * @since 1.0.0
    * @category Compensation
+   * @since 4.0.0
    */
   <A, E, R, R2>(
     effect: Effect.Effect<A, E, R>,
@@ -760,8 +850,11 @@ export const withCompensation: {
   ))
 
 /**
- * @since 4.0.0
+ * Marks a workflow instance as suspended and interrupts the current fiber to
+ * stop execution until it is resumed.
+ *
  * @category Result
+ * @since 4.0.0
  */
 export const suspend = (instance: WorkflowInstance["Service"]): Effect.Effect<never> =>
   Effect.interruptible(Effect.callback<never>(() => {
@@ -776,8 +869,8 @@ export const suspend = (instance: WorkflowInstance["Service"]): Effect.Effect<ne
  *
  * By default, this is set to `true`, meaning that defects will be captured.
  *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const CaptureDefects = Context.Reference<boolean>(
   "effect/workflow/Workflow/CaptureDefects",
@@ -787,14 +880,13 @@ export const CaptureDefects = Context.Reference<boolean>(
 )
 
 /**
- * If you set this annotation to `true` for a workflow, it will suspend if it
- * encounters any kind of error.
+ * Annotation that causes a workflow to suspend when it encounters any error.
  *
- * You can then manually resume the workflow later with
- * `Workflow.resume(executionId)`.
+ * The suspended execution can later be resumed with the workflow's `resume`
+ * method, for example `MyWorkflow.resume(executionId)`.
  *
+ * @category annotations
  * @since 4.0.0
- * @category Annotations
  */
 export const SuspendOnFailure = Context.Reference<boolean>(
   "effect/workflow/Workflow/SuspendOnFailure",

package/src/unstable/workflow/WorkflowEngine.ts

@@ -1,4 +1,24 @@
 /**
+ * Workflow engine service definitions and the default in-memory engine used to
+ * run durable workflows.
+ *
+ * This module is the runtime boundary for `Workflow` values. It registers
+ * workflow handlers, starts or polls executions by stable execution ID, links
+ * child workflow interruption to parents, and coordinates activities, durable
+ * deferred values, and durable clocks. Library users usually depend on the
+ * typed `WorkflowEngine` service, while persistence backends implement the
+ * lower-level `Encoded` contract and pass it to `makeUnsafe`.
+ *
+ * Durable execution requires engine implementations to make retries and resumes
+ * idempotent. Reusing an execution ID should observe the existing execution
+ * instead of starting duplicate work, suspended executions are retried according
+ * to `suspendedRetrySchedule`, and concurrent deferred completions or clock
+ * wake-ups must be serialized by the backend. Use `interrupt` when
+ * compensation and child workflow cleanup matter; `interruptUnsafe` can stop
+ * work more directly but may bypass those guarantees. The provided
+ * `layerMemory` is useful for tests and local development, but it keeps state
+ * in process memory and does not provide production durability.
+ *
  * @since 4.0.0
  */
 import type * as Cause from "../../Cause.ts"
@@ -19,8 +39,12 @@ import type * as DurableDeferred from "./DurableDeferred.ts"
 import * as Workflow from "./Workflow.ts"
 
 /**
+ * Service interface for workflow runtimes, responsible for registering and
+ * executing workflows and coordinating activities, durable deferreds,
+ * interrupts, resumes, and clocks.
+ *
+ * @category services
  * @since 4.0.0
- * @category Services
  */
 export class WorkflowEngine extends Context.Service<
   WorkflowEngine,
@@ -196,8 +220,12 @@ export class WorkflowEngine extends Context.Service<
 >()("effect/workflow/WorkflowEngine") {}
 
 /**
+ * Per-execution workflow service containing the execution ID, workflow
+ * definition, long-lived scope, suspension state, interruption state, and
+ * activity coordination state.
+ *
+ * @category services
  * @since 4.0.0
- * @category Services
  */
 export class WorkflowInstance extends Context.Service<
   WorkflowInstance,
@@ -261,8 +289,11 @@ export class WorkflowInstance extends Context.Service<
 }
 
 /**
- * @since 4.0.0
+ * Low-level workflow engine contract that works with encoded payloads and
+ * results before `makeUnsafe` adds typed schema decoding and encoding.
+ *
  * @category Encoded
+ * @since 4.0.0
  */
 export interface Encoded {
   readonly register: (
@@ -330,8 +361,12 @@ export interface Encoded {
 }
 
 /**
+ * Builds a typed `WorkflowEngine` service from a low-level encoded
+ * implementation. This is unsafe because the implementation must correctly
+ * persist, resume, and encode workflow state.
+ *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const makeUnsafe = (options: Encoded): WorkflowEngine["Service"] =>
   WorkflowEngine.of({
@@ -524,8 +559,8 @@ const defaultRetrySchedule = Schedule.exponential(200, 1.5).pipe(
  * and local development, but is not suitable for production use as it does not
  * provide durability guarantees.
  *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEngine)(
   Effect.gen(function*() {

package/src/unstable/workflow/WorkflowProxy.ts

@@ -1,4 +1,28 @@
 /**
+ * The `WorkflowProxy` module derives transport contracts from durable
+ * `Workflow` definitions.
+ *
+ * Use it when workflows should be invoked through RPC or HTTP instead of by
+ * importing the workflow implementation directly. `toRpcGroup` creates the
+ * `RpcGroup` that RPC clients and servers share, while `toHttpApiGroup` creates
+ * the `HttpApiGroup` that can be mounted in an HTTP API. Each workflow expands
+ * into execute, discard, and resume operations so external callers can start a
+ * workflow, start it through the discard path, or resume a suspended execution
+ * by `executionId`.
+ *
+ * The generated names and schemas come from the workflow definitions, so keep
+ * workflow names stable and pass the same workflow list to the matching
+ * `WorkflowProxyServer` layer. RPC proxies may be prefixed, but the same prefix
+ * must be used by the server handlers. HTTP endpoint paths are derived from the
+ * lower-cased workflow name. Preserve workflow arrays as const tuples when you
+ * want the generated RPC and HTTP API types to retain each workflow's literal
+ * name, payload, success, and error types.
+ *
+ * Discard and resume are control operations rather than ordinary workflow
+ * result reads. The discard proxy does not expose the normal success or error
+ * schemas, and resume expects the persisted `executionId`; it cannot recreate
+ * that boundary value from the original payload.
+ *
  * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts"
@@ -12,14 +36,12 @@ import type * as Workflow from "./Workflow.ts"
 /**
  * Derives an `RpcGroup` from a list of workflows.
  *
+ * **Example** (Deriving RPC endpoints from workflows)
+ *
  * ```ts
  * import { Layer, Schema } from "effect"
  * import { RpcServer } from "effect/unstable/rpc"
- * import {
- *   Workflow,
- *   WorkflowProxy,
- *   WorkflowProxyServer
- * } from "effect/unstable/workflow"
+ * import { Workflow, WorkflowProxy, WorkflowProxyServer } from "effect/unstable/workflow"
  *
  * const EmailWorkflow = Workflow.make({
  *   name: "EmailWorkflow",
@@ -43,8 +65,8 @@ import type * as Workflow from "./Workflow.ts"
  * )
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const toRpcGroup = <
   const Workflows extends NonEmptyReadonlyArray<Workflow.Any>,
@@ -76,6 +98,10 @@ export const toRpcGroup = <
 }
 
 /**
+ * Maps each workflow to the RPC definitions generated for execute, discard,
+ * and resume operations.
+ *
+ * @category converting
  * @since 4.0.0
  */
 export type ConvertRpcs<Workflows extends Workflow.Any, Prefix extends string> = Workflows extends Workflow.Workflow<
@@ -92,14 +118,12 @@ export type ConvertRpcs<Workflows extends Workflow.Any, Prefix extends string> =
 /**
  * Derives an `HttpApiGroup` from a list of workflows.
  *
+ * **Example** (Deriving HTTP API endpoints from workflows)
+ *
  * ```ts
  * import { Layer, Schema } from "effect"
  * import { HttpApi, HttpApiBuilder } from "effect/unstable/httpapi"
- * import {
- *   Workflow,
- *   WorkflowProxy,
- *   WorkflowProxyServer
- * } from "effect/unstable/workflow"
+ * import { Workflow, WorkflowProxy, WorkflowProxyServer } from "effect/unstable/workflow"
  *
  * const EmailWorkflow = Workflow.make({
  *   name: "EmailWorkflow",
@@ -127,8 +151,8 @@ export type ConvertRpcs<Workflows extends Workflow.Any, Prefix extends string> =
  * )
  * ```
  *
+ * @category constructors
  * @since 4.0.0
- * @category Constructors
  */
 export const toHttpApiGroup = <const Name extends string, const Workflows extends NonEmptyReadonlyArray<Workflow.Any>>(
   name: Name,
@@ -162,6 +186,10 @@ const tagToPath = (tag: string): string =>
     .toLowerCase()
 
 /**
+ * Maps each workflow to the HTTP API endpoints generated for execute,
+ * discard, and resume operations.
+ *
+ * @category converting
  * @since 4.0.0
  */
 export type ConvertHttpApi<Workflows extends Workflow.Any> = Workflows extends Workflow.Workflow<

package/src/unstable/workflow/WorkflowProxyServer.ts

@@ -1,4 +1,29 @@
 /**
+ * The `WorkflowProxyServer` module provides server-side layers for exposing
+ * workflows through the proxy APIs generated by `WorkflowProxy`. It connects
+ * HTTP API endpoints or RPC handlers to the supplied workflow definitions,
+ * routing execute, discard, and resume requests to the corresponding workflow
+ * operation while keeping the `WorkflowEngine` and workflow implementation
+ * services on the server side.
+ *
+ * **Common tasks**
+ *
+ * - Serve a workflow proxy over an HTTP API group with {@link layerHttpApi}
+ * - Serve the RPC group produced by `WorkflowProxy.toRpcGroup` with
+ *   {@link layerRpcHandlers}
+ * - Expose durable workflow starts and explicit resume operations to clients
+ *   without exposing the workflow implementation itself
+ *
+ * **Gotchas**
+ *
+ * - The workflows passed to these layers must match the group produced by
+ *   `WorkflowProxy`; RPC prefixes must be the same on both sides
+ * - Discard handlers use the workflow discard execution path, so callers should
+ *   not rely on receiving the normal workflow success or error value
+ * - Resume handlers expect a payload with the persisted `executionId`; clients
+ *   must preserve that boundary value because it is not recomputed from the
+ *   original workflow payload
+ *
  * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts"
@@ -13,8 +38,11 @@ import type * as Workflow from "./Workflow.ts"
 import type { WorkflowEngine } from "./WorkflowEngine.ts"
 
 /**
+ * Creates handlers for a workflow HTTP API group, wiring execute, discard, and
+ * resume endpoints to the supplied workflows.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layerHttpApi = <
   ApiId extends string,
@@ -77,8 +105,11 @@ export const layerHttpApi = <
   )
 
 /**
+ * Creates RPC handlers for the supplied workflows, wiring execute, discard,
+ * and resume RPCs to workflow operations.
+ *
+ * @category layers
  * @since 4.0.0
- * @category Layers
  */
 export const layerRpcHandlers = <
   const Workflows extends NonEmptyReadonlyArray<Workflow.Any>,
@@ -91,7 +122,7 @@ export const layerRpcHandlers = <
   WorkflowEngine | Workflow.RequirementsHandler<Workflows[number]>
 > =>
   Layer.effectContext(Effect.gen(function*() {
-    const services = yield* Effect.context<never>()
+    const context = yield* Effect.context<never>()
     const prefix = options?.prefix ?? ""
     const handlers = new Map<string, Rpc.Handler<string>>()
     for (const workflow_ of workflows) {
@@ -103,17 +134,17 @@ export const layerRpcHandlers = <
       const keyDiscard = `${key}Discard`
       const keyResume = `${key}Resume`
       handlers.set(key, {
-        services,
+        context,
         tag,
         handler: (payload: any) => workflow.execute(payload) as any
       } as any)
       handlers.set(keyDiscard, {
-        services,
+        context,
         tag: tagDiscard,
         handler: (payload: any) => workflow.execute(payload, { discard: true } as any) as any
       } as any)
       handlers.set(keyResume, {
-        services,
+        context,
         tag: tagResume,
         handler: (payload: any) => workflow.resume(payload.executionId) as any
       } as any)
@@ -122,6 +153,10 @@ export const layerRpcHandlers = <
   }))
 
 /**
+ * Union of RPC handler services required to serve the generated workflow
+ * execute, discard, and resume RPCs.
+ *
+ * @category services
  * @since 4.0.0
  */
 export type RpcHandlers<Workflows extends Workflow.Any, Prefix extends string> = Workflows extends Workflow.Workflow<