effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/unstable/workflow/DurableDeferred.ts

@@ -1,4 +1,24 @@
 /**
+ * Durable deferreds are named workflow wait points whose result is stored by
+ * the workflow engine as an encoded `Exit`. A workflow can `await` one and
+ * suspend until an activity, worker, timer, or external callback completes it
+ * with `done`, `succeed`, `fail`, or `failCause`.
+ *
+ * Use this module to coordinate work that finishes outside the current
+ * workflow turn: durable races, queues that report worker results, timers,
+ * human approvals, webhooks, and other callback-style integrations. Tokens
+ * encode the workflow name, execution ID, and deferred name so completion can
+ * be routed back to the correct workflow execution without keeping an
+ * in-memory handle.
+ *
+ * Deferred names are part of persisted workflow state, so keep them stable
+ * across replays and unique for each logical wait. Completion is persisted as
+ * an `Exit` and decoded through the success and error schemas when awaited
+ * again; changing schemas or reusing a name for a different result type can
+ * make old completions fail to decode or resume the wrong wait. Complete a
+ * deferred once, and use `withActivityAttempt` when an activity retry needs an
+ * attempt-scoped completion name.
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -21,8 +41,11 @@ import type { WorkflowEngine, WorkflowInstance } from "./WorkflowEngine.ts"
 const TypeId = "~effect/workflow/DurableDeferred"
 
 /**
- * @since 4.0.0
+ * Named durable deferred value whose completion is persisted by the workflow
+ * engine and encoded with success and error schemas.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface DurableDeferred<
   Success extends Schema.Top,
@@ -37,8 +60,11 @@ export interface DurableDeferred<
 }
 
 /**
- * @since 4.0.0
+ * Type-erased durable deferred shape for APIs that only need the deferred
+ * identity and name.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface Any {
   readonly [TypeId]: typeof TypeId
@@ -46,8 +72,11 @@ export interface Any {
 }
 
 /**
- * @since 4.0.0
+ * Type-erased durable deferred shape that also exposes success, error, and
+ * exit schemas.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface AnyWithProps {
   readonly [TypeId]: typeof TypeId
@@ -58,8 +87,11 @@ export interface AnyWithProps {
 }
 
 /**
- * @since 4.0.0
+ * Creates a named durable deferred with optional success and error schemas for
+ * persisted completion.
+ *
  * @category Constructors
+ * @since 4.0.0
  */
 export const make = <
   Success extends Schema.Top = Schema.Void,
@@ -136,20 +168,26 @@ const await_: <Success extends Schema.Top, Error extends Schema.Top>(
 
 export {
   /**
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   await_ as await
 }
 
 /**
- * @since 4.0.0
+ * Runs an effect and records its exit into the durable deferred, resuming
+ * workflows that are waiting on that deferred.
+ *
  * @category Combinators
+ * @since 4.0.0
  */
 export const into: {
   /**
-   * @since 4.0.0
+   * Runs an effect and records its exit into the durable deferred, resuming
+   * workflows that are waiting on that deferred.
+   *
    * @category Combinators
+   * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(self: DurableDeferred<Success, Error>): <R>(
     effect: Effect.Effect<Success["Type"], Error["Type"], R>
@@ -163,8 +201,11 @@ export const into: {
     | Error["DecodingServices"]
   >
   /**
-   * @since 4.0.0
+   * Runs an effect and records its exit into the durable deferred, resuming
+   * workflows that are waiting on that deferred.
+   *
    * @category Combinators
+   * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top, R>(
     effect: Effect.Effect<Success["Type"], Error["Type"], R>,
@@ -226,8 +267,11 @@ export const into: {
 )
 
 /**
- * @since 4.0.0
+ * Runs effects as a durable race, returning a previously persisted result when
+ * present or completing a named deferred with the first result.
+ *
  * @category Racing
+ * @since 4.0.0
  */
 export const raceAll = <
   const Effects extends NonEmptyReadonlyArray<Effect.Effect<any, any, any>>,
@@ -267,30 +311,42 @@ export const raceAll = <
 }
 
 /**
+ * Runtime brand identifier for durable deferred tokens.
+ *
  * @since 4.0.0
  */
 export const TokenTypeId = "~effect/workflow/DurableDeferred/Token"
 
 /**
+ * Type-level brand identifier for `Token` values.
+ *
  * @since 4.0.0
  */
 export type TokenTypeId = typeof TokenTypeId
 
 /**
- * @since 4.0.0
+ * Branded string token identifying a durable deferred for a workflow
+ * execution.
+ *
  * @category Token
+ * @since 4.0.0
  */
 export type Token = Brand.Branded<string, TokenTypeId>
 
 /**
- * @since 4.0.0
+ * Schema for branded durable deferred tokens.
+ *
  * @category Token
+ * @since 4.0.0
  */
 export const Token: Schema.brand<Schema.String, TokenTypeId> = Schema.String.pipe(Schema.brand(TokenTypeId))
 
 /**
- * @since 4.0.0
+ * Decoded representation of a durable deferred token containing the workflow
+ * name, execution ID, and deferred name.
+ *
  * @category Token
+ * @since 4.0.0
  */
 export class TokenParsed extends Schema.Class<TokenParsed>(
   "effect/workflow/DurableDeferred/TokenParsed"
@@ -300,6 +356,8 @@ export class TokenParsed extends Schema.Class<TokenParsed>(
   deferredName: Schema.String
 }) {
   /**
+   * Encodes the parsed workflow, execution, and deferred names back into a token.
+   *
    * @since 4.0.0
    */
   get asToken(): Token {
@@ -309,6 +367,8 @@ export class TokenParsed extends Schema.Class<TokenParsed>(
   }
 
   /**
+   * Schema for decoding and encoding durable deferred tokens as strings.
+   *
    * @since 4.0.0
    */
   static readonly FromString = Schema.String.pipe(
@@ -342,19 +402,26 @@ export class TokenParsed extends Schema.Class<TokenParsed>(
   )
 
   /**
+   * Decodes a durable deferred token string into its parsed components.
+   *
    * @since 4.0.0
    */
   static readonly fromString = Schema.decodeSync(TokenParsed.FromString)
 
   /**
+   * Encodes parsed durable deferred token components into a token string.
+   *
    * @since 4.0.0
    */
   static readonly encode = Schema.encodeSync(TokenParsed.FromString)
 }
 
 /**
- * @since 4.0.0
+ * Creates a token for a durable deferred using the current workflow instance's
+ * workflow name and execution ID.
+ *
  * @category Token
+ * @since 4.0.0
  */
 export const token: <Success extends Schema.Top, Error extends Schema.Top>(
   self: DurableDeferred<Success, Error>
@@ -368,13 +435,19 @@ export const token: <Success extends Schema.Top, Error extends Schema.Top>(
 )
 
 /**
- * @since 4.0.0
+ * Creates a durable deferred token from an explicit workflow, execution ID,
+ * and deferred name.
+ *
  * @category Token
+ * @since 4.0.0
  */
 export const tokenFromExecutionId: {
   /**
-   * @since 4.0.0
+   * Creates a durable deferred token from an explicit workflow, execution ID,
+   * and deferred name.
+   *
    * @category Token
+   * @since 4.0.0
    */
   (
     options: {
@@ -385,8 +458,11 @@ export const tokenFromExecutionId: {
     self: DurableDeferred<Success, Error>
   ) => Token
   /**
-   * @since 4.0.0
+   * Creates a durable deferred token from an explicit workflow, execution ID,
+   * and deferred name.
+   *
    * @category Token
+   * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
     self: DurableDeferred<Success, Error>,
@@ -409,13 +485,19 @@ export const tokenFromExecutionId: {
 )
 
 /**
- * @since 4.0.0
+ * Creates a durable deferred token by deriving the workflow execution ID from
+ * the supplied workflow payload.
+ *
  * @category Token
+ * @since 4.0.0
  */
 export const tokenFromPayload: {
   /**
-   * @since 4.0.0
+   * Creates a durable deferred token by deriving the workflow execution ID from
+   * the supplied workflow payload.
+   *
    * @category Token
+   * @since 4.0.0
    */
   <W extends Workflow.Any>(
     options: {
@@ -426,8 +508,11 @@ export const tokenFromPayload: {
     self: DurableDeferred<Success, Error>
   ) => Effect.Effect<Token>
   /**
-   * @since 4.0.0
+   * Creates a durable deferred token by deriving the workflow execution ID from
+   * the supplied workflow payload.
+   *
    * @category Token
+   * @since 4.0.0
    */
   <
     Success extends Schema.Top,
@@ -461,13 +546,19 @@ export const tokenFromPayload: {
 )
 
 /**
- * @since 4.0.0
+ * Completes the durable deferred identified by a token with the supplied exit,
+ * encoding the result through the deferred schemas.
+ *
  * @category Combinators
+ * @since 4.0.0
  */
 export const done: {
   /**
-   * @since 4.0.0
+   * Completes the durable deferred identified by a token with the supplied exit,
+   * encoding the result through the deferred schemas.
+   *
    * @category Combinators
+   * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
     options: {
@@ -482,8 +573,11 @@ export const done: {
     WorkflowEngine | Success["EncodingServices"] | Error["EncodingServices"]
   >
   /**
-   * @since 4.0.0
+   * Completes the durable deferred identified by a token with the supplied exit,
+   * encoding the result through the deferred schemas.
+   *
    * @category Combinators
+   * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
     self: DurableDeferred<Success, Error>,
@@ -520,13 +614,19 @@ export const done: {
 )
 
 /**
- * @since 4.0.0
+ * Completes the durable deferred identified by a token with a successful
+ * value.
+ *
  * @category Combinators
+ * @since 4.0.0
  */
 export const succeed: {
   /**
-   * @since 4.0.0
+   * Completes the durable deferred identified by a token with a successful
+   * value.
+   *
    * @category Combinators
+   * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
     options: {
@@ -537,8 +637,11 @@ export const succeed: {
     self: DurableDeferred<Success, Error>
   ) => Effect.Effect<void, never, WorkflowEngine | Success["EncodingServices"]>
   /**
-   * @since 4.0.0
+   * Completes the durable deferred identified by a token with a successful
+   * value.
+   *
    * @category Combinators
+   * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
     self: DurableDeferred<Success, Error>,
@@ -563,13 +666,17 @@ export const succeed: {
 )
 
 /**
- * @since 4.0.0
+ * Completes the durable deferred identified by a token with a typed failure.
+ *
  * @category Combinators
+ * @since 4.0.0
  */
 export const fail: {
   /**
-   * @since 4.0.0
+   * Completes the durable deferred identified by a token with a typed failure.
+   *
    * @category Combinators
+   * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
     options: {
@@ -580,8 +687,10 @@ export const fail: {
     self: DurableDeferred<Success, Error>
   ) => Effect.Effect<void, never, WorkflowEngine | Error["EncodingServices"]>
   /**
-   * @since 4.0.0
+   * Completes the durable deferred identified by a token with a typed failure.
+   *
    * @category Combinators
+   * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
     self: DurableDeferred<Success, Error>,
@@ -606,13 +715,17 @@ export const fail: {
 )
 
 /**
- * @since 4.0.0
+ * Completes the durable deferred identified by a token with a failure cause.
+ *
  * @category Combinators
+ * @since 4.0.0
  */
 export const failCause: {
   /**
-   * @since 4.0.0
+   * Completes the durable deferred identified by a token with a failure cause.
+   *
    * @category Combinators
+   * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
     options: {
@@ -623,8 +736,10 @@ export const failCause: {
     self: DurableDeferred<Success, Error>
   ) => Effect.Effect<void, never, WorkflowEngine | Error["EncodingServices"]>
   /**
-   * @since 4.0.0
+   * Completes the durable deferred identified by a token with a failure cause.
+   *
    * @category Combinators
+   * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
     self: DurableDeferred<Success, Error>,

package/src/unstable/workflow/DurableQueue.ts

@@ -1,4 +1,20 @@
 /**
+ * Durable queues bridge workflow executions with persisted background workers.
+ * A workflow calls `process` to enqueue a schema-encoded payload in a named
+ * `PersistedQueue`, attach a durable deferred token, and suspend until a worker
+ * records the handler's `Exit` back through that deferred.
+ *
+ * Use this module for workflow steps that should be delegated to independent
+ * workers: long-running side effects, rate-limited or concurrency-limited
+ * integrations, fan-out jobs, API calls, and other work that must survive
+ * workflow suspension, process restarts, or handoff to another service.
+ *
+ * Queue names, payload schemas, result schemas, and idempotency keys become
+ * persisted coordination state. Keep them deterministic and stable across
+ * deployments; changing them is a persistence migration. Delivery follows the
+ * underlying `PersistedQueue` semantics, so handlers should be idempotent and
+ * prepared for retries, duplicate observations, and worker restarts.
+ *
  * @since 4.0.0
  */
 import * as Effect from "../../Effect.ts"
@@ -12,20 +28,27 @@ import * as DurableDeferred from "./DurableDeferred.ts"
 import type { WorkflowEngine, WorkflowInstance } from "./WorkflowEngine.ts"
 
 /**
- * @since 4.0.0
+ * Type-level identifier used to recognize `DurableQueue` values.
+ *
  * @category Type IDs
+ * @since 4.0.0
  */
 export type TypeId = "~effect/workflow/DurableQueue"
 
 /**
- * @since 4.0.0
+ * Runtime identifier attached to `DurableQueue` values.
+ *
  * @category Type IDs
+ * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/workflow/DurableQueue"
 
 /**
- * @since 4.0.0
+ * Durable workflow queue definition containing a payload schema, idempotency
+ * key, and deferred used to await worker results.
+ *
  * @category Models
+ * @since 4.0.0
  */
 export interface DurableQueue<
   Payload extends Schema.Top,
@@ -92,8 +115,8 @@ export interface DurableQueue<
  * )
  * ```
  *
- * @since 4.0.0
  * @category Constructors
+ * @since 4.0.0
  */
 export const make = <
   Payload extends Schema.Top | Schema.Struct.Fields,
@@ -153,8 +176,8 @@ const getQueueSchema = <Payload extends Schema.Top>(
 /**
  * Add an item to the queue and wait for a worker to process it.
  *
- * @since 4.0.0
  * @category Processing
+ * @since 4.0.0
  */
 export const process: <
   Payload extends Schema.Top,
@@ -229,8 +252,8 @@ const defaultRetrySchedule = Schedule.exponential(500, 1.5).pipe(
 /**
  * Create a worker effect that processes items from the durable queue.
  *
- * @since 4.0.0
  * @category Worker
+ * @since 4.0.0
  */
 export const makeWorker: <
   Payload extends Schema.Top,
@@ -316,8 +339,8 @@ export const makeWorker: <
 /**
  * Create a layer that runs workers for the durable queue.
  *
- * @since 4.0.0
  * @category Worker
+ * @since 4.0.0
  */
 export const worker: <
   Payload extends Schema.Top,