effect 4.0.0-beta.71 → 4.0.0-beta.72

package/src/unstable/workflow/DurableClock.ts

@@ -80,10 +80,10 @@ const InstanceTag = Context.Service<
 )
 
 /**
- * Sleeps inside a workflow, using an in-memory activity for durations at or
+ * Waits 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
+ * @category sleeping
  * @since 4.0.0
  */
 export const sleep: (

package/src/unstable/workflow/DurableDeferred.ts

@@ -168,7 +168,7 @@ const await_: <Success extends Schema.Top, Error extends Schema.Top>(
 
 export {
   /**
-   * Awaits the durable deferred, suspending the current workflow when no
+   * Waits for the durable deferred, suspending the current workflow when no
    * persisted completion is available.
    *
    * @category combinators
@@ -333,7 +333,7 @@ export type TokenTypeId = typeof TokenTypeId
  * Branded string token identifying a durable deferred for a workflow
  * execution.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export type Token = Brand.Branded<string, TokenTypeId>
@@ -341,16 +341,16 @@ export type Token = Brand.Branded<string, TokenTypeId>
 /**
  * Schema for branded durable deferred tokens.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export const Token: Schema.brand<Schema.String, TokenTypeId> = Schema.String.pipe(Schema.brand(TokenTypeId))
 
 /**
- * Decoded representation of a durable deferred token containing the workflow
+ * Schema for a decoded durable deferred token containing the workflow
  * name, execution ID, and deferred name.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export class TokenParsed extends Schema.Class<TokenParsed>(
@@ -425,7 +425,7 @@ export class TokenParsed extends Schema.Class<TokenParsed>(
  * Creates a token for a durable deferred using the current workflow instance's
  * workflow name and execution ID.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export const token: <Success extends Schema.Top, Error extends Schema.Top>(
@@ -443,7 +443,7 @@ export const token: <Success extends Schema.Top, Error extends Schema.Top>(
  * Creates a durable deferred token from an explicit workflow, execution ID,
  * and deferred name.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export const tokenFromExecutionId: {
@@ -451,7 +451,7 @@ export const tokenFromExecutionId: {
    * Creates a durable deferred token from an explicit workflow, execution ID,
    * and deferred name.
    *
-   * @category Token
+   * @category token
    * @since 4.0.0
    */
   (
@@ -466,7 +466,7 @@ export const tokenFromExecutionId: {
    * Creates a durable deferred token from an explicit workflow, execution ID,
    * and deferred name.
    *
-   * @category Token
+   * @category token
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
@@ -493,7 +493,7 @@ export const tokenFromExecutionId: {
  * Creates a durable deferred token by deriving the workflow execution ID from
  * the supplied workflow payload.
  *
- * @category Token
+ * @category token
  * @since 4.0.0
  */
 export const tokenFromPayload: {
@@ -501,7 +501,7 @@ export const tokenFromPayload: {
    * Creates a durable deferred token by deriving the workflow execution ID from
    * the supplied workflow payload.
    *
-   * @category Token
+   * @category token
    * @since 4.0.0
    */
   <W extends Workflow.Any>(
@@ -516,7 +516,7 @@ export const tokenFromPayload: {
    * Creates a durable deferred token by deriving the workflow execution ID from
    * the supplied workflow payload.
    *
-   * @category Token
+   * @category token
    * @since 4.0.0
    */
   <

package/src/unstable/workflow/DurableQueue.ts

@@ -81,8 +81,8 @@ export interface DurableQueue<
 }
 
 /**
- * A `DurableQueue` wraps a `PersistedQueue`, providing a way to wait for items
- * to finish processing using a `DurableDeferred`.
+ * Creates a `DurableQueue` that waits for persisted items to finish processing
+ * using a `DurableDeferred`.
  *
  * **Example** (Defining a durable queue with workers)
  *
@@ -194,7 +194,7 @@ const getQueueSchema = <Payload extends Schema.Top>(
 }
 
 /**
- * Add an item to the queue and wait for a worker to process it.
+ * Adds an item to the queue and wait for a worker to process it.
  *
  * @category Processing
  * @since 4.0.0

package/src/unstable/workflow/Workflow.ts

@@ -447,7 +447,7 @@ const ResultTypeId = "~effect/workflow/Workflow/Result"
 /**
  * Returns `true` when a value is a workflow `Result`.
  *
- * @category Result
+ * @category results
  * @since 4.0.0
  */
 export const isResult = <A = unknown, E = unknown>(
@@ -458,7 +458,7 @@ export const isResult = <A = unknown, E = unknown>(
  * Result of a workflow execution, either a completed exit or a suspended
  * workflow state.
  *
- * @category Result
+ * @category results
  * @since 4.0.0
  */
 export type Result<A, E> = Complete<A, E> | Suspended
@@ -466,7 +466,7 @@ export type Result<A, E> = Complete<A, E> | Suspended
 /**
  * Encoded representation of a workflow `Result`.
  *
- * @category Result
+ * @category results
  * @since 4.0.0
  */
 export type ResultEncoded<A, E> =
@@ -477,7 +477,7 @@ export type ResultEncoded<A, E> =
  * Encoded representation of a completed workflow result containing an encoded
  * `Exit`.
  *
- * @category Result
+ * @category results
  * @since 4.0.0
  */
 export interface CompleteEncoded<A, E> {
@@ -507,10 +507,9 @@ export interface CompleteSchema<
 }
 
 /**
- * Workflow result representing a completed execution with its success or
- * failure `Exit`.
+ * Represents a completed workflow execution with its success or failure `Exit`.
  *
- * @category Result
+ * @category results
  * @since 4.0.0
  */
 export class Complete<A, E> extends Data.TaggedClass("Complete")<{
@@ -579,10 +578,10 @@ export class Complete<A, E> extends Data.TaggedClass("Complete")<{
 }
 
 /**
- * Workflow result representing a suspended execution, optionally carrying the
- * cause that triggered suspension.
+ * Represents a suspended workflow execution, optionally carrying the cause that
+ * triggered suspension.
  *
- * @category Result
+ * @category results
  * @since 4.0.0
  */
 export class Suspended extends Schema.Class<Suspended>(
@@ -603,7 +602,7 @@ export class Suspended extends Schema.Class<Suspended>(
  * Creates a schema for workflow results using the supplied success and error
  * schemas.
  *
- * @category Result
+ * @category results
  * @since 4.0.0
  */
 export const Result = <
@@ -617,9 +616,9 @@ export const Result = <
 const AnyOrVoid = Schema.Union([Schema.Any, Schema.Void])
 
 /**
- * Codec for encoded workflow results with generic success and error payloads.
+ * Schema for encoded workflow results with generic success and error payloads.
  *
- * @category Result
+ * @category results
  * @since 4.0.0
  */
 export const ResultEncoded: Schema.Codec<ResultEncoded<any, any>> = Schema.toEncoded(
@@ -636,7 +635,7 @@ export const ResultEncoded: Schema.Codec<ResultEncoded<any, any>> = Schema.toEnc
  * `Result`, handling suspension, defect capture, interruption, and workflow
  * scope finalization.
  *
- * @category Result
+ * @category results
  * @since 4.0.0
  */
 export const intoResult = <A, E, R>(
@@ -699,7 +698,7 @@ export const intoResult = <A, E, R>(
  * Wraps an activity-like effect so workflow suspension waits for currently
  * running activities to finish or suspend.
  *
- * @category Result
+ * @category results
  * @since 4.0.0
  */
 export const wrapActivityResult = <A, E, R>(
@@ -748,7 +747,7 @@ const waitForZero = Effect.fnUntraced(function*(instance: WorkflowInstance["Serv
 /**
  * Accesses the workflow scope, which is only closed when the workflow execution fully completes.
  *
- * @category Scope
+ * @category resource management
  * @since 4.0.0
  */
 export const scope: Effect.Effect<
@@ -763,7 +762,7 @@ export const scope: Effect.Effect<
 /**
  * Provides the workflow scope to the given effect, and closes the scope only when the workflow execution fully completes.
  *
- * @category Scope
+ * @category resource management
  * @since 4.0.0
  */
 export const provideScope = <A, E, R>(
@@ -775,7 +774,7 @@ export const provideScope = <A, E, R>(
  * Adds an exit finalizer to the current workflow scope, preserving the
  * services available when the finalizer is registered.
  *
- * @category Scope
+ * @category resource management
  * @since 4.0.0
  */
 export const addFinalizer: <R>(
@@ -793,7 +792,7 @@ export const addFinalizer: <R>(
 })
 
 /**
- * Add compensation logic to an effect inside a Workflow.
+ * Adds compensation logic to an effect inside a Workflow.
  *
  * **Details**
  *
@@ -808,7 +807,7 @@ export const addFinalizer: <R>(
  */
 export const withCompensation: {
   /**
-   * Add compensation logic to an effect inside a Workflow.
+   * Adds compensation logic to an effect inside a Workflow.
    *
    * **Details**
    *
@@ -827,7 +826,7 @@ export const withCompensation: {
     effect: Effect.Effect<A, E, R>
   ) => Effect.Effect<A, E, R | R2 | WorkflowInstance | Scope.Scope>
   /**
-   * Add compensation logic to an effect inside a Workflow.
+   * Adds compensation logic to an effect inside a Workflow.
    *
    * **Details**
    *
@@ -859,7 +858,7 @@ export const withCompensation: {
  * Marks a workflow instance as suspended and interrupts the current fiber to
  * stop execution until it is resumed.
  *
- * @category Result
+ * @category results
  * @since 4.0.0
  */
 export const suspend = (instance: WorkflowInstance["Service"]): Effect.Effect<never> =>
@@ -887,7 +886,7 @@ export const CaptureDefects = Context.Reference<boolean>(
 )
 
 /**
- * Causes a workflow to suspend when it encounters any error.
+ * Marks a workflow to suspend when it encounters any error.
  *
  * **Details**
  *

package/src/unstable/workflow/WorkflowEngine.ts

@@ -39,7 +39,7 @@ import type * as DurableDeferred from "./DurableDeferred.ts"
 import * as Workflow from "./Workflow.ts"
 
 /**
- * Service interface for workflow runtimes, responsible for registering and
+ * Service that represents workflow runtimes, responsible for registering and
  * executing workflows and coordinating activities, durable deferreds,
  * interrupts, resumes, and clocks.
  *
@@ -136,7 +136,7 @@ export class WorkflowEngine extends Context.Service<
     ) => Effect.Effect<void>
 
     /**
-     * Unsafely interrupt a registered workflow, potentially ignoring
+     * Interrupts a registered workflow unsafely, potentially ignoring
      * compensation finalizers and orphaning child workflows.
      */
     readonly interruptUnsafe: (
@@ -220,9 +220,19 @@ 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.
+ * Service that contains workflow runtime state for one execution.
+ *
+ * **When to use**
+ *
+ * Use to read or update workflow execution, suspension, interruption,
+ * lifetime, failure, and activity coordination state inside workflow engine
+ * internals.
+ *
+ * **Details**
+ *
+ * The service stores the execution ID, workflow definition, long-lived scope,
+ * suspension and interruption flags, the stored failure cause, and activity
+ * coordination state for a single workflow run.
  *
  * @category services
  * @since 4.0.0
@@ -551,9 +561,17 @@ const defaultRetrySchedule = Schedule.exponential(200, 1.5).pipe(
 )
 
 /**
- * A in-memory implementation of the WorkflowEngine. This is useful for testing
- * and local development, but is not suitable for production use as it does not
- * provide durability guarantees.
+ * Layer that provides an in-memory `WorkflowEngine`.
+ *
+ * **When to use**
+ *
+ * Use to run tests and local development workflows where durability is not
+ * needed.
+ *
+ * **Gotchas**
+ *
+ * This layer keeps state only in memory and is not suitable for production
+ * workflows that require durability.
  *
  * @category layers
  * @since 4.0.0