effect 4.0.0-beta.67 → 4.0.0-beta.69

package/src/unstable/workflow/DurableDeferred.ts

@@ -44,7 +44,7 @@ const TypeId = "~effect/workflow/DurableDeferred"
  * Named durable deferred value whose completion is persisted by the workflow
  * engine and encoded with success and error schemas.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface DurableDeferred<
@@ -63,7 +63,7 @@ export interface DurableDeferred<
  * Type-erased durable deferred shape for APIs that only need the deferred
  * identity and name.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface Any {
@@ -75,7 +75,7 @@ export interface Any {
  * Type-erased durable deferred shape that also exposes success, error, and
  * exit schemas.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface AnyWithProps {
@@ -90,7 +90,7 @@ export interface AnyWithProps {
  * Creates a named durable deferred with optional success and error schemas for
  * persisted completion.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const make = <
@@ -168,7 +168,7 @@ const await_: <Success extends Schema.Top, Error extends Schema.Top>(
 
 export {
   /**
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   await_ as await
@@ -178,7 +178,7 @@ export {
  * Runs an effect and records its exit into the durable deferred, resuming
  * workflows that are waiting on that deferred.
  *
- * @category Combinators
+ * @category combinators
  * @since 4.0.0
  */
 export const into: {
@@ -186,7 +186,7 @@ export const into: {
    * Runs an effect and records its exit into the durable deferred, resuming
    * workflows that are waiting on that deferred.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(self: DurableDeferred<Success, Error>): <R>(
@@ -204,7 +204,7 @@ export const into: {
    * Runs an effect and records its exit into the durable deferred, resuming
    * workflows that are waiting on that deferred.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top, R>(
@@ -313,6 +313,7 @@ export const raceAll = <
 /**
  * Runtime brand identifier for durable deferred tokens.
  *
+ * @category type IDs
  * @since 4.0.0
  */
 export const TokenTypeId = "~effect/workflow/DurableDeferred/Token"
@@ -320,6 +321,7 @@ export const TokenTypeId = "~effect/workflow/DurableDeferred/Token"
 /**
  * Type-level brand identifier for `Token` values.
  *
+ * @category type IDs
  * @since 4.0.0
  */
 export type TokenTypeId = typeof TokenTypeId
@@ -549,7 +551,7 @@ export const tokenFromPayload: {
  * Completes the durable deferred identified by a token with the supplied exit,
  * encoding the result through the deferred schemas.
  *
- * @category Combinators
+ * @category combinators
  * @since 4.0.0
  */
 export const done: {
@@ -557,7 +559,7 @@ export const done: {
    * Completes the durable deferred identified by a token with the supplied exit,
    * encoding the result through the deferred schemas.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
@@ -576,7 +578,7 @@ export const done: {
    * Completes the durable deferred identified by a token with the supplied exit,
    * encoding the result through the deferred schemas.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
@@ -617,7 +619,7 @@ export const done: {
  * Completes the durable deferred identified by a token with a successful
  * value.
  *
- * @category Combinators
+ * @category combinators
  * @since 4.0.0
  */
 export const succeed: {
@@ -625,7 +627,7 @@ export const succeed: {
    * Completes the durable deferred identified by a token with a successful
    * value.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
@@ -640,7 +642,7 @@ export const succeed: {
    * Completes the durable deferred identified by a token with a successful
    * value.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
@@ -668,14 +670,14 @@ export const succeed: {
 /**
  * Completes the durable deferred identified by a token with a typed failure.
  *
- * @category Combinators
+ * @category combinators
  * @since 4.0.0
  */
 export const fail: {
   /**
    * Completes the durable deferred identified by a token with a typed failure.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
@@ -689,7 +691,7 @@ export const fail: {
   /**
    * Completes the durable deferred identified by a token with a typed failure.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
@@ -717,14 +719,14 @@ export const fail: {
 /**
  * Completes the durable deferred identified by a token with a failure cause.
  *
- * @category Combinators
+ * @category combinators
  * @since 4.0.0
  */
 export const failCause: {
   /**
    * Completes the durable deferred identified by a token with a failure cause.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(
@@ -738,7 +740,7 @@ export const failCause: {
   /**
    * Completes the durable deferred identified by a token with a failure cause.
    *
-   * @category Combinators
+   * @category combinators
    * @since 4.0.0
    */
   <Success extends Schema.Top, Error extends Schema.Top>(

package/src/unstable/workflow/DurableQueue.ts

@@ -30,7 +30,7 @@ import type { WorkflowEngine, WorkflowInstance } from "./WorkflowEngine.ts"
 /**
  * Type-level identifier used to recognize `DurableQueue` values.
  *
- * @category Type IDs
+ * @category type IDs
  * @since 4.0.0
  */
 export type TypeId = "~effect/workflow/DurableQueue"
@@ -38,7 +38,7 @@ export type TypeId = "~effect/workflow/DurableQueue"
 /**
  * Runtime identifier attached to `DurableQueue` values.
  *
- * @category Type IDs
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId: TypeId = "~effect/workflow/DurableQueue"
@@ -47,7 +47,7 @@ export const TypeId: TypeId = "~effect/workflow/DurableQueue"
  * Durable workflow queue definition containing a payload schema, idempotency
  * key, and deferred used to await worker results.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface DurableQueue<
@@ -66,9 +66,11 @@ export interface DurableQueue<
  * A `DurableQueue` wraps a `PersistedQueue`, providing a way to wait for items
  * to finish processing using a `DurableDeferred`.
  *
+ * **Example** (Defining a durable queue with workers)
+ *
  * ```ts
- * import { DurableQueue, Workflow } from "effect/unstable/workflow"
  * import { Effect, Schema } from "effect"
+ * import { DurableQueue, Workflow } from "effect/unstable/workflow"
  *
  * // Define a DurableQueue that can be used to derive workers and offer items for
  * // processing.
@@ -115,7 +117,7 @@ export interface DurableQueue<
  * )
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const make = <

package/src/unstable/workflow/Workflow.ts

@@ -51,7 +51,7 @@ const TypeId = "~effect/workflow/Workflow"
  * plus operations for execution, polling, interruption, resumption, and
  * registration.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface Workflow<
@@ -194,6 +194,7 @@ 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 {
@@ -204,7 +205,7 @@ export interface AnyStructSchema extends Schema.Top {
  * Type-level marker for services associated with a specific workflow
  * execution name.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface Execution<Name extends string> {
@@ -216,7 +217,7 @@ 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
+ * @category models
  * @since 4.0.0
  */
 export interface Any {
@@ -233,7 +234,7 @@ export interface Any {
  * Type-erased workflow shape that also exposes executable operations needed by
  * workflow proxy and engine helpers.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export interface AnyWithProps extends Any {
@@ -252,7 +253,7 @@ export interface AnyWithProps extends Any {
 /**
  * Extracts the payload schema from a `Workflow`.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export type PayloadSchema<W> = W extends Workflow<
@@ -267,7 +268,7 @@ export type PayloadSchema<W> = W extends Workflow<
  * Computes the schema services required by clients that execute or poll
  * workflows.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export type RequirementsClient<Workflows extends Any> = Workflows extends Workflow<
@@ -285,7 +286,7 @@ export type RequirementsClient<Workflows extends Any> = Workflows extends Workfl
  * Computes the schema services required by handlers that decode workflow
  * payloads and encode workflow results.
  *
- * @category Models
+ * @category models
  * @since 4.0.0
  */
 export type RequirementsHandler<Workflows extends Any> = Workflows extends Workflow<
@@ -318,7 +319,7 @@ const InstanceTag = Context.Service<
  * deterministic execution IDs derived from the workflow name and idempotency
  * key.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const make = <
@@ -485,6 +486,7 @@ 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<
@@ -867,7 +869,7 @@ export const suspend = (instance: WorkflowInstance["Service"]): Effect.Effect<ne
  *
  * By default, this is set to `true`, meaning that defects will be captured.
  *
- * @category Annotations
+ * @category annotations
  * @since 4.0.0
  */
 export const CaptureDefects = Context.Reference<boolean>(
@@ -883,7 +885,7 @@ export const CaptureDefects = Context.Reference<boolean>(
  * The suspended execution can later be resumed with the workflow's `resume`
  * method, for example `MyWorkflow.resume(executionId)`.
  *
- * @category Annotations
+ * @category annotations
  * @since 4.0.0
  */
 export const SuspendOnFailure = Context.Reference<boolean>(

package/src/unstable/workflow/WorkflowEngine.ts

@@ -43,7 +43,7 @@ import * as Workflow from "./Workflow.ts"
  * executing workflows and coordinating activities, durable deferreds,
  * interrupts, resumes, and clocks.
  *
- * @category Services
+ * @category services
  * @since 4.0.0
  */
 export class WorkflowEngine extends Context.Service<
@@ -224,7 +224,7 @@ export class WorkflowEngine extends Context.Service<
  * definition, long-lived scope, suspension state, interruption state, and
  * activity coordination state.
  *
- * @category Services
+ * @category services
  * @since 4.0.0
  */
 export class WorkflowInstance extends Context.Service<
@@ -365,7 +365,7 @@ export interface Encoded {
  * implementation. This is unsafe because the implementation must correctly
  * persist, resume, and encode workflow state.
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const makeUnsafe = (options: Encoded): WorkflowEngine["Service"] =>
@@ -415,22 +415,18 @@ export const makeUnsafe = (options: Encoded): WorkflowEngine["Service"] =>
           return options.interrupt(self, executionId)
         })
       }
+      const run = options.execute(self, {
+        executionId,
+        payload: payload as object,
+        discard: opts.discard ?? false,
+        parent: Option.getOrUndefined(parentInstance)
+      }) as Effect.Effect<Workflow.Result<Success["Type"], Error["Type"]>>
 
       if (opts.discard) {
-        yield* options.execute(self, {
-          executionId,
-          payload: payload as object,
-          discard: true
-        })
+        yield* run
         return executionId
       }
 
-      const run = options.execute(self, {
-        executionId,
-        payload: payload as object,
-        discard: false,
-        parent: Option.getOrUndefined(parentInstance)
-      })
       if (Option.isSome(parentInstance)) {
         const wrapped = yield* Workflow.wrapActivityResult(
           run,
@@ -559,7 +555,7 @@ 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
+ * @category layers
  * @since 4.0.0
  */
 export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEngine)(

package/src/unstable/workflow/WorkflowProxy.ts

@@ -36,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",
@@ -67,7 +65,7 @@ import type * as Workflow from "./Workflow.ts"
  * )
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const toRpcGroup = <
@@ -103,6 +101,7 @@ 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<
@@ -119,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",
@@ -154,7 +151,7 @@ export type ConvertRpcs<Workflows extends Workflow.Any, Prefix extends string> =
  * )
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const toHttpApiGroup = <const Name extends string, const Workflows extends NonEmptyReadonlyArray<Workflow.Any>>(
@@ -192,6 +189,7 @@ const tagToPath = (tag: string): string =>
  * 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

@@ -41,7 +41,7 @@ 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
+ * @category layers
  * @since 4.0.0
  */
 export const layerHttpApi = <
@@ -108,7 +108,7 @@ export const layerHttpApi = <
  * Creates RPC handlers for the supplied workflows, wiring execute, discard,
  * and resume RPCs to workflow operations.
  *
- * @category Layers
+ * @category layers
  * @since 4.0.0
  */
 export const layerRpcHandlers = <
@@ -156,6 +156,7 @@ 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<