effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/unstable/workflow/Workflow.ts

@@ -15,7 +15,7 @@
  * 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
+ * derived from the workflow tag 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.
@@ -36,8 +36,8 @@ import * as Option from "../../Option.ts"
 import * as Predicate from "../../Predicate.ts"
 import type * as Schedule from "../../Schedule.ts"
 import * as Schema from "../../Schema.ts"
-import * as Issue from "../../SchemaIssue.ts"
-import * as Parser from "../../SchemaParser.ts"
+import * as SchemaIssue from "../../SchemaIssue.ts"
+import * as SchemaParser from "../../SchemaParser.ts"
 import * as Tranformation from "../../SchemaTransformation.ts"
 import * as Scope from "../../Scope.ts"
 import type { ExitEncoded } from "../rpc/RpcMessage.ts"
@@ -55,17 +55,21 @@ const TypeId = "~effect/workflow/Workflow"
  * @since 4.0.0
  */
 export interface Workflow<
-  Name extends string,
+  Tag extends string,
   Payload extends AnyStructSchema,
   Success extends Schema.Top,
   Error extends Schema.Top
 > {
+  new(_: never): {}
+
   readonly [TypeId]: typeof TypeId
-  readonly name: Name
+  readonly _tag: Tag
   readonly payloadSchema: Payload
   readonly successSchema: Success
   readonly errorSchema: Error
   readonly annotations: Context.Context<never>
+  readonly idempotencyKey: (payload: Payload["Type"]) => string
+  readonly suspendedRetrySchedule?: Schedule.Schedule<any, unknown> | undefined
 
   /**
    * Add an annotation to the workflow.
@@ -73,14 +77,14 @@ export interface Workflow<
   annotate<I, S>(
     key: Context.Key<I, S>,
     value: S
-  ): Workflow<Name, Payload, Success, Error>
+  ): Workflow<Tag, Payload, Success, Error>
 
   /**
    * Merge multiple annotations into the workflow.
    */
   annotateMerge<I>(
     annotations: Context.Context<I>
-  ): Workflow<Name, Payload, Success, Error>
+  ): Workflow<Tag, Payload, Success, Error>
 
   /**
    * Execute the workflow with the given payload.
@@ -139,7 +143,7 @@ export interface Workflow<
     | WorkflowEngine
     | Exclude<
       R,
-      WorkflowEngine | WorkflowInstance | Execution<Name> | Scope.Scope
+      WorkflowEngine | WorkflowInstance | Execution<Tag> | Scope.Scope
     >
     | Payload["DecodingServices"]
     | Payload["EncodingServices"]
@@ -178,7 +182,7 @@ export interface Workflow<
     ) => Effect.Effect<
       A,
       E,
-      R | R2 | WorkflowInstance | Execution<Name> | Scope.Scope
+      R | R2 | WorkflowInstance | Execution<Tag> | Scope.Scope
     >
     <A, E, R, R2>(
       effect: Effect.Effect<A, E, R>,
@@ -189,7 +193,7 @@ export interface Workflow<
     ): Effect.Effect<
       A,
       E,
-      R | R2 | WorkflowInstance | Execution<Name> | Scope.Scope
+      R | R2 | WorkflowInstance | Execution<Tag> | Scope.Scope
     >
   }
 }
@@ -206,14 +210,14 @@ export interface AnyStructSchema extends Schema.Top {
 
 /**
  * Type-level marker for services associated with a specific workflow
- * execution name.
+ * execution tag.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Execution<Name extends string> {
+export interface Execution<Tag extends string> {
   readonly _: unique symbol
-  readonly name: Name
+  readonly _tag: Tag
 }
 
 /**
@@ -224,13 +228,17 @@ export interface Execution<Name extends string> {
  * @since 4.0.0
  */
 export interface Any {
+  new(_: never): {}
+
   readonly [TypeId]: typeof TypeId
-  readonly name: string
+  readonly _tag: string
   readonly executionId: (payload: any) => Effect.Effect<string>
   readonly payloadSchema: AnyStructSchema
   readonly successSchema: Schema.Top
   readonly errorSchema: Schema.Top
   readonly annotations: Context.Context<never>
+  readonly idempotencyKey: (payload: any) => string
+  readonly suspendedRetrySchedule?: Schedule.Schedule<any, unknown> | undefined
 }
 
 /**
@@ -317,21 +325,125 @@ const InstanceTag = Context.Service<
   "effect/workflow/WorkflowEngine/WorkflowInstance" satisfies typeof WorkflowInstance.key
 )
 
+const makeExecutionIdFromPayload = (self: AnyWithProps, payload: unknown) =>
+  makeHashDigest(`${self._tag}-${self.idempotencyKey(payload)}`)
+
+const Proto = {
+  [TypeId]: TypeId,
+  annotate(this: AnyWithProps, tag: Context.Key<any, any>, value: any) {
+    return makeProto({
+      _tag: this._tag,
+      payloadSchema: this.payloadSchema,
+      successSchema: this.successSchema,
+      errorSchema: this.errorSchema,
+      annotations: Context.add(this.annotations, tag, value),
+      idempotencyKey: this.idempotencyKey,
+      suspendedRetrySchedule: this.suspendedRetrySchedule
+    })
+  },
+  annotateMerge(this: AnyWithProps, context: Context.Context<any>) {
+    return makeProto({
+      _tag: this._tag,
+      payloadSchema: this.payloadSchema,
+      successSchema: this.successSchema,
+      errorSchema: this.errorSchema,
+      annotations: Context.merge(this.annotations, context),
+      idempotencyKey: this.idempotencyKey,
+      suspendedRetrySchedule: this.suspendedRetrySchedule
+    })
+  },
+  execute<const Discard extends boolean = false>(
+    this: AnyWithProps,
+    fields: any,
+    opts?: { readonly discard?: Discard } | undefined
+  ) {
+    return Effect.suspend(() => {
+      const payload = this.payloadSchema.make(fields)
+      return Effect.flatMap(
+        EngineTag,
+        (engine) =>
+          Effect.flatMap(makeExecutionIdFromPayload(this, payload), (executionId) =>
+            Effect.andThen(
+              Effect.annotateCurrentSpan({ executionId }),
+              engine.execute(this as any, {
+                executionId,
+                payload,
+                discard: opts?.discard,
+                suspendedRetrySchedule: this.suspendedRetrySchedule
+              })
+            ))
+      )
+    }).pipe(
+      Effect.withSpan(
+        `${this._tag}.execute`,
+        {},
+        { captureStackTrace: false }
+      )
+    ) as any
+  },
+  poll(this: Workflow<string, AnyStructSchema, Schema.Top, Schema.Top>, executionId: string) {
+    return Effect.flatMap(EngineTag, (engine) => engine.poll(this, executionId)).pipe(
+      Effect.withSpan(`${this._tag}.poll`, { attributes: { executionId } }, { captureStackTrace: false })
+    )
+  },
+  interrupt(this: AnyWithProps, executionId: string) {
+    return Effect.flatMap(EngineTag, (engine) => engine.interrupt(this, executionId)).pipe(
+      Effect.withSpan(`${this._tag}.interrupt`, { attributes: { executionId } }, { captureStackTrace: false })
+    )
+  },
+  resume(this: Workflow<string, AnyStructSchema, Schema.Top, Schema.Top>, executionId: string) {
+    return Effect.flatMap(EngineTag, (engine) => engine.resume(this, executionId)).pipe(
+      Effect.withSpan(`${this._tag}.resume`, { attributes: { executionId } }, { captureStackTrace: false })
+    )
+  },
+  toLayer(this: Workflow<string, AnyStructSchema, Schema.Top, Schema.Top>, execute: any) {
+    return Layer.effectDiscard(
+      Effect.flatMap(EngineTag, (engine) => engine.register(this, execute))
+    )
+  },
+  executionId(this: AnyWithProps, payload: any) {
+    return Effect.flatMap(
+      Effect.orDie(this.payloadSchema.makeEffect(payload)),
+      (payload) => makeExecutionIdFromPayload(this, payload)
+    )
+  },
+  withCompensation: ((...args: ReadonlyArray<any>) => (withCompensation as any)(...args))
+}
+
+const makeProto = <
+  const Tag extends string,
+  Payload extends AnyStructSchema,
+  Success extends Schema.Top,
+  Error extends Schema.Top
+>(options: {
+  readonly _tag: Tag
+  readonly payloadSchema: Payload
+  readonly successSchema: Success
+  readonly errorSchema: Error
+  readonly annotations: Context.Context<never>
+  readonly idempotencyKey: (payload: Payload["Type"]) => string
+  readonly suspendedRetrySchedule?: Schedule.Schedule<any, unknown> | undefined
+}): Workflow<Tag, Payload, Success, Error> => {
+  function Workflow() {}
+  Object.setPrototypeOf(Workflow, Proto)
+  Object.assign(Workflow, options)
+  return Workflow as any
+}
+
 /**
  * Creates a durable workflow definition with schemas, annotations, and
- * deterministic execution IDs derived from the workflow name and idempotency
+ * deterministic execution IDs derived from the workflow tag and idempotency
  * key.
  *
  * @category constructors
  * @since 4.0.0
  */
 export const make = <
-  const Name extends string,
+  const Tag extends string,
   Payload extends Schema.Struct.Fields | AnyStructSchema,
   Success extends Schema.Top = Schema.Void,
   Error extends Schema.Top = Schema.Never
->(options: {
-  readonly name: Name
+>(tag: Tag, options: {
   readonly payload: Payload
   readonly idempotencyKey: (
     payload: Payload extends Schema.Struct.Fields ? Schema.Struct.Type<Payload>
@@ -342,105 +454,23 @@ export const make = <
   readonly suspendedRetrySchedule?: Schedule.Schedule<any, unknown> | undefined
   readonly annotations?: Context.Context<never>
 }): Workflow<
-  Name,
+  Tag,
   Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload,
   Success,
   Error
-> => {
-  const makeExecutionId = (payload: any) => makeHashDigest(`${options.name}-${options.idempotencyKey(payload)}`)
-  const self: Workflow<Name, any, Success, Error> = {
-    [TypeId]: TypeId,
-    name: options.name,
-    payloadSchema: Schema.isSchema(options.payload)
+> =>
+  makeProto<Tag, Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload, Success, Error>({
+    _tag: tag,
+    payloadSchema: (Schema.isSchema(options.payload)
       ? options.payload
-      : Schema.Struct(options.payload as any),
+      : Schema.Struct(options.payload as any)) as Payload extends Schema.Struct.Fields ? Schema.Struct<Payload>
+        : Payload,
     successSchema: options.success ?? (Schema.Void as any),
     errorSchema: options.error ?? (Schema.Never as any),
     annotations: options.annotations ?? Context.empty(),
-    annotate(tag, value) {
-      return make({
-        ...options,
-        annotations: Context.add(self.annotations, tag, value)
-      })
-    },
-    annotateMerge(context) {
-      return make({
-        ...options,
-        annotations: Context.merge(self.annotations, context)
-      })
-    },
-    execute: Effect.fnUntraced(
-      function*<const Discard extends boolean = false>(
-        fields: any,
-        opts?: { readonly discard?: Discard } | undefined
-      ) {
-        const payload = self.payloadSchema.make(fields)
-        const engine = yield* EngineTag
-        const executionId = yield* makeExecutionId(payload)
-        yield* Effect.annotateCurrentSpan({ executionId })
-        return yield* engine.execute(self, {
-          executionId,
-          payload,
-          discard: opts?.discard,
-          suspendedRetrySchedule: options.suspendedRetrySchedule
-        })
-      },
-      Effect.withSpan(
-        `${options.name}.execute`,
-        {},
-        { captureStackTrace: false }
-      )
-    ) as any,
-    poll: Effect.fnUntraced(
-      function*(executionId: string) {
-        const engine = yield* EngineTag
-        return yield* engine.poll(self, executionId)
-      },
-      (effect, executionId) =>
-        Effect.withSpan(effect, `${options.name}.poll`, {
-          captureStackTrace: false,
-          attributes: { executionId }
-        })
-    ),
-    interrupt: Effect.fnUntraced(
-      function*(executionId: string) {
-        const engine = yield* EngineTag
-        yield* engine.interrupt(self, executionId)
-      },
-      (effect, executionId) =>
-        Effect.withSpan(effect, `${options.name}.interrupt`, {
-          captureStackTrace: false,
-          attributes: { executionId }
-        })
-    ),
-    resume: Effect.fnUntraced(
-      function*(executionId: string) {
-        const engine = yield* EngineTag
-        yield* engine.resume(self, executionId)
-      },
-      (effect, executionId) =>
-        Effect.withSpan(effect, `${options.name}.resume`, {
-          captureStackTrace: false,
-          attributes: { executionId }
-        })
-    ),
-    toLayer: (execute) =>
-      Layer.effectDiscard(
-        Effect.gen(function*() {
-          const engine = yield* EngineTag
-          return yield* engine.register(self, execute)
-        })
-      ),
-    executionId: (payload) =>
-      Effect.flatMap(
-        Effect.orDie(self.payloadSchema.makeEffect(payload)),
-        makeExecutionId
-      ),
-    withCompensation
-  }
-
-  return self
-}
+    idempotencyKey: options.idempotencyKey as any,
+    suspendedRetrySchedule: options.suspendedRetrySchedule
+  })
 
 const ResultTypeId = "~effect/workflow/Workflow/Result"
 
@@ -539,15 +569,15 @@ export class Complete<A, E> extends Data.TaggedClass("Complete")<{
       [Schema.Exit(options.success, options.error, Schema.Defect)],
       ([exit]) => (input, ast, options) => {
         if (!(isResult(input) && input._tag === "Complete")) {
-          return Effect.fail(new Issue.InvalidType(ast, Option.some(input)))
+          return Effect.fail(new SchemaIssue.InvalidType(ast, Option.some(input)))
         }
         return Effect.mapBothEager(
-          Parser.decodeEffect(exit)(input.exit, options),
+          SchemaParser.decodeEffect(exit)(input.exit, options),
           {
             onSuccess: (exit) => new Complete({ exit }),
             onFailure: (issue) =>
-              new Issue.Composite(ast, Option.some(input), [
-                new Issue.Pointer(["exit"], issue)
+              new SchemaIssue.Composite(ast, Option.some(input), [
+                new SchemaIssue.Pointer(["exit"], issue)
               ])
           }
         )
@@ -794,6 +824,11 @@ export const addFinalizer: <R>(
 /**
  * Adds compensation logic to an effect inside a Workflow.
  *
+ * **When to use**
+ *
+ * Use when a top-level workflow step needs compensating cleanup if the overall
+ * workflow later fails after the step succeeds.
+ *
  * **Details**
  *
  * The compensation finalizer is called if the entire workflow fails, allowing you to perform cleanup or other actions based on the success value and the cause of the workflow failure.
@@ -809,6 +844,11 @@ export const withCompensation: {
   /**
    * Adds compensation logic to an effect inside a Workflow.
    *
+   * **When to use**
+   *
+   * Use when a top-level workflow step needs compensating cleanup if the overall
+   * workflow later fails after the step succeeds.
+   *
    * **Details**
    *
    * The compensation finalizer is called if the entire workflow fails, allowing you to perform cleanup or other actions based on the success value and the cause of the workflow failure.
@@ -828,6 +868,11 @@ export const withCompensation: {
   /**
    * Adds compensation logic to an effect inside a Workflow.
    *
+   * **When to use**
+   *
+   * Use when a top-level workflow step needs compensating cleanup if the overall
+   * workflow later fails after the step succeeds.
+   *
    * **Details**
    *
    * The compensation finalizer is called if the entire workflow fails, allowing you to perform cleanup or other actions based on the success value and the cause of the workflow failure.

package/src/unstable/workflow/WorkflowEngine.ts

@@ -372,8 +372,16 @@ 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.
+ * implementation.
+ *
+ * **When to use**
+ *
+ * Use when wiring a trusted low-level workflow engine implementation into the
+ * typed `WorkflowEngine` service.
+ *
+ * **Gotchas**
+ *
+ * The implementation must correctly persist, resume, and encode workflow state.
  *
  * @category constructors
  * @since 4.0.0
@@ -461,7 +469,7 @@ export const makeUnsafe = (options: Encoded): WorkflowEngine["Service"] =>
         ).pipe(
           Effect.catch(() =>
             Effect.die(
-              `${self.name}.execute: suspendedRetrySchedule exhausted`
+              `${self._tag}.execute: suspendedRetrySchedule exhausted`
             )
           )
         )
@@ -616,7 +624,7 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
         return
       }
 
-      const entry = workflows.get(state.instance.workflow.name)!
+      const entry = workflows.get(state.instance.workflow._tag)!
       const instance = WorkflowInstance.initial(state.instance.workflow, state.instance.executionId)
       instance.interrupted = state.instance.interrupted
       state.instance = instance
@@ -647,16 +655,16 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
 
     const engine = makeUnsafe({
       register: Effect.fnUntraced(function*(workflow, execute) {
-        workflows.set(workflow.name, {
+        workflows.set(workflow._tag, {
           workflow,
           execute,
           scope: yield* Effect.scope
         })
       }),
       execute: Effect.fnUntraced(function*(workflow, options) {
-        const entry = workflows.get(workflow.name)
+        const entry = workflows.get(workflow._tag)
         if (!entry) {
-          return yield* Effect.orDie(Effect.fail(`Workflow ${workflow.name} is not registered`))
+          return yield* Effect.orDie(Effect.fail(`Workflow ${workflow._tag} is not registered`))
         }
 
         let state = executions.get(options.executionId)
@@ -745,7 +753,7 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
         }),
       scheduleClock: (workflow, options) =>
         engine.deferredDone(options.clock.deferred, {
-          workflowName: workflow.name,
+          workflowName: workflow._tag,
           executionId: options.executionId,
           deferredName: options.clock.deferred.name,
           exit: Exit.void

package/src/unstable/workflow/WorkflowProxy.ts

@@ -43,8 +43,7 @@ import type * as Workflow from "./Workflow.ts"
  * import { RpcServer } from "effect/unstable/rpc"
  * import { Workflow, WorkflowProxy, WorkflowProxyServer } from "effect/unstable/workflow"
  *
- * const EmailWorkflow = Workflow.make({
- *   name: "EmailWorkflow",
+ * const EmailWorkflow = Workflow.make("EmailWorkflow", {
  *   payload: {
  *     id: Schema.String,
  *     to: Schema.String
@@ -82,15 +81,15 @@ export const toRpcGroup = <
   for (const workflow_ of workflows) {
     const workflow = workflow_ as Workflow.AnyWithProps
     rpcs.push(
-      Rpc.make(`${prefix}${workflow.name}`, {
+      Rpc.make(`${prefix}${workflow._tag}`, {
         payload: workflow.payloadSchema,
         error: workflow.errorSchema,
         success: workflow.successSchema
       }).annotateMerge(workflow.annotations),
-      Rpc.make(`${prefix}${workflow.name}Discard`, {
+      Rpc.make(`${prefix}${workflow._tag}Discard`, {
         payload: workflow.payloadSchema
       }).annotateMerge(workflow.annotations),
-      Rpc.make(`${prefix}${workflow.name}Resume`, { payload: ResumePayload })
+      Rpc.make(`${prefix}${workflow._tag}Resume`, { payload: ResumePayload })
         .annotateMerge(workflow.annotations)
     )
   }
@@ -125,8 +124,7 @@ export type ConvertRpcs<Workflows extends Workflow.Any, Prefix extends string> =
  * import { HttpApi, HttpApiBuilder } from "effect/unstable/httpapi"
  * import { Workflow, WorkflowProxy, WorkflowProxyServer } from "effect/unstable/workflow"
  *
- * const EmailWorkflow = Workflow.make({
- *   name: "EmailWorkflow",
+ * const EmailWorkflow = Workflow.make("EmailWorkflow", {
  *   payload: {
  *     id: Schema.String,
  *     to: Schema.String
@@ -161,17 +159,17 @@ export const toHttpApiGroup = <const Name extends string, const Workflows extend
   let group = HttpApiGroup.make(name)
   for (const workflow_ of workflows) {
     const workflow = workflow_ as Workflow.AnyWithProps
-    const path = `/${tagToPath(workflow.name)}` as const
+    const path = `/${tagToPath(workflow._tag)}` as const
     group = group.add(
-      HttpApiEndpoint.post(workflow.name, path, {
+      HttpApiEndpoint.post(workflow._tag, path, {
         payload: workflow.payloadSchema,
         success: workflow.successSchema,
         error: workflow.errorSchema
       }).annotateMerge(workflow.annotations),
-      HttpApiEndpoint.post(workflow.name + "Discard", `${path}/discard`, {
+      HttpApiEndpoint.post(workflow._tag + "Discard", `${path}/discard`, {
         payload: workflow.payloadSchema
       }).annotateMerge(workflow.annotations),
-      HttpApiEndpoint.post(workflow.name + "Resume", `${path}/resume`, {
+      HttpApiEndpoint.post(workflow._tag + "Resume", `${path}/resume`, {
         payload: ResumePayload
       }).annotateMerge(workflow.annotations)
     ) as any

package/src/unstable/workflow/WorkflowProxyServer.ts

@@ -67,35 +67,35 @@ export const layerHttpApi = <
         const workflow = workflow_ as Workflow.AnyWithProps
         handlers = handlers
           .handle(
-            workflow.name as any,
+            workflow._tag as any,
             ({ payload }: { payload: any }) =>
               workflow.execute(payload).pipe(
                 Effect.tapDefect(Effect.logError),
                 Effect.annotateLogs({
                   module: "WorkflowProxyServer",
-                  method: workflow.name
+                  method: workflow._tag
                 })
               )
           )
           .handle(
-            workflow.name + "Discard" as any,
+            workflow._tag + "Discard" as any,
             ({ payload }: { payload: any }) =>
               workflow.execute(payload, { discard: true } as any).pipe(
                 Effect.tapDefect(Effect.logError),
                 Effect.annotateLogs({
                   module: "WorkflowProxyServer",
-                  method: workflow.name + "Discard"
+                  method: workflow._tag + "Discard"
                 })
               )
           )
           .handle(
-            workflow.name + "Resume" as any,
+            workflow._tag + "Resume" as any,
             ({ payload }: { payload: any }) =>
               workflow.resume(payload.executionId).pipe(
                 Effect.tapDefect(Effect.logError),
                 Effect.annotateLogs({
                   module: "WorkflowProxyServer",
-                  method: workflow.name + "Resume"
+                  method: workflow._tag + "Resume"
                 })
               )
           )
@@ -127,7 +127,7 @@ export const layerRpcHandlers = <
     const handlers = new Map<string, Rpc.Handler<string>>()
     for (const workflow_ of workflows) {
       const workflow = workflow_ as Workflow.AnyWithProps
-      const tag = `${prefix}${workflow.name}`
+      const tag = `${prefix}${workflow._tag}`
       const tagDiscard = `${tag}Discard`
       const tagResume = `${tag}Resume`
       const key = `effect/rpc/Rpc/${tag}`