@effect/workflow 0.1.2 → 0.1.4

package/src/DurableDeferred.ts

@@ -1,6 +1,7 @@
 /**
  * @since 1.0.0
  */
+import type { NonEmptyReadonlyArray } from "effect/Array"
 import type * as Brand from "effect/Brand"
 import type * as Cause from "effect/Cause"
 import * as Context from "effect/Context"
@@ -10,7 +11,7 @@ import * as Exit from "effect/Exit"
 import { dual } from "effect/Function"
 import * as Option from "effect/Option"
 import * as Schema from "effect/Schema"
-import type * as Workflow from "./Workflow.js"
+import * as Workflow from "./Workflow.js"
 import type { WorkflowEngine, WorkflowInstance } from "./WorkflowEngine.js"
 
 /**
@@ -94,7 +95,7 @@ const await_: <Success extends Schema.Schema.Any, Error extends Schema.Schema.Al
 >(self: DurableDeferred<Success, Error>) {
   const engine = yield* EngineTag
   const instance = yield* InstanceTag
-  const oexit = yield* engine.deferredResult(self)
+  const oexit = yield* Workflow.wrapActivityResult(engine.deferredResult(self), Option.isNone)
   if (Option.isNone(oexit)) {
     instance.suspended = true
     return yield* Effect.interrupt
@@ -112,6 +113,106 @@ export {
   await_ as await
 }
 
+/**
+ * @since 1.0.0
+ * @category Combinators
+ */
+export const into: {
+  /**
+   * @since 1.0.0
+   * @category Combinators
+   */
+  <Success extends Schema.Schema.Any, Error extends Schema.Schema.All>(self: DurableDeferred<Success, Error>): <R>(effect: Effect.Effect<Success["Type"], Error["Type"], R>) => Effect.Effect<
+    Success["Type"],
+    Error["Type"],
+    R | WorkflowEngine | WorkflowInstance | Success["Context"] | Error["Context"]
+  >
+  /**
+   * @since 1.0.0
+   * @category Combinators
+   */
+  <Success extends Schema.Schema.Any, Error extends Schema.Schema.All, R>(
+    effect: Effect.Effect<Success["Type"], Error["Type"], R>,
+    self: DurableDeferred<Success, Error>
+  ): Effect.Effect<
+    Success["Type"],
+    Error["Type"],
+    R | WorkflowEngine | WorkflowInstance | Success["Context"] | Error["Context"]
+  >
+} = dual(2, <Success extends Schema.Schema.Any, Error extends Schema.Schema.All, R>(
+  effect: Effect.Effect<Success["Type"], Error["Type"], R>,
+  self: DurableDeferred<Success, Error>
+): Effect.Effect<
+  Success["Type"],
+  Error["Type"],
+  R | WorkflowEngine | WorkflowInstance | Success["Context"] | Error["Context"]
+> =>
+  Effect.contextWithEffect((context: Context.Context<WorkflowEngine | WorkflowInstance>) => {
+    const engine = Context.get(context, EngineTag)
+    const instance = Context.get(context, InstanceTag)
+    return Effect.onExit(
+      effect,
+      Effect.fnUntraced(function*(exit) {
+        if (instance.suspended) return
+        const encodedExit = yield* Effect.orDie(Schema.encode(self.exitSchema)(exit))
+        yield* engine.deferredDone({
+          workflowName: instance.workflow.name,
+          executionId: instance.executionId,
+          deferred: self,
+          exit: encodedExit as any
+        })
+      })
+    )
+  }))
+
+/**
+ * @since 1.0.0
+ * @category Racing
+ */
+export const raceAll = <
+  const Effects extends NonEmptyReadonlyArray<Effect.Effect<any, any, any>>,
+  SI,
+  SR,
+  EI,
+  ER
+>(options: {
+  name: string
+  success: Schema.Schema<
+    Effects[number] extends Effect.Effect<infer S, infer _E, infer _R> ? S : never,
+    SI,
+    SR
+  >
+  error: Schema.Schema<
+    Effects[number] extends Effect.Effect<infer _S, infer E, infer _R> ? E : never,
+    EI,
+    ER
+  >
+  effects: Effects
+}): Effect.Effect<
+  (Effects[number] extends Effect.Effect<infer _A, infer _E, infer _R> ? _A : never),
+  (Effects[number] extends Effect.Effect<infer _A, infer _E, infer _R> ? _E : never),
+  | (Effects[number] extends Effect.Effect<infer _A, infer _R, infer R> ? R : never)
+  | SR
+  | ER
+  | WorkflowEngine
+  | WorkflowInstance
+> => {
+  const deferred = make<any, any>(`raceAll/${options.name}`, {
+    success: options.success,
+    error: options.error
+  })
+  return Effect.gen(function*() {
+    const engine = yield* EngineTag
+    const oexit = yield* Workflow.wrapActivityResult(engine.deferredResult(deferred), Option.isNone)
+    if (Option.isSome(oexit)) {
+      return yield* (Effect.flatten(Effect.orDie(
+        Schema.decodeUnknown(deferred.exitSchema)(oexit.value)
+      )) as Effect.Effect<any, any, any>)
+    }
+    return yield* into(Effect.raceAll(options.effects), deferred)
+  })
+}
+
 /**
  * @since 1.0.0
  * @category Token

package/src/Workflow.ts

@@ -45,6 +45,27 @@ export interface Workflow<
   readonly payloadSchema: Payload
   readonly successSchema: Success
   readonly errorSchema: Error
+  readonly annotations: Context.Context<never>
+
+  /**
+   * Add an annotation to the workflow.
+   */
+  annotate<I, S>(tag: Context.Tag<I, S>, value: S): Workflow<
+    Name,
+    Payload,
+    Success,
+    Error
+  >
+
+  /**
+   * Add the annotations from a Context object to the workflow.
+   */
+  annotateContext<I>(context: Context.Context<I>): Workflow<
+    Name,
+    Payload,
+    Success,
+    Error
+  >
 
   /**
    * Execute the workflow with the given payload.
@@ -166,9 +187,34 @@ export interface Any {
   readonly payloadSchema: AnyStructSchema
   readonly successSchema: Schema.Schema.Any
   readonly errorSchema: Schema.Schema.All
+  readonly annotations: Context.Context<never>
   readonly executionId: (payload: any) => Effect.Effect<string>
 }
 
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export type Registrations<Workflows extends Any> = Workflows extends Workflow<
+  infer _Name,
+  infer _Payload,
+  infer _Success,
+  infer _Error
+> ? Registration<_Name> :
+  never
+
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export type Requirements<Workflows extends Any> = Workflows extends Workflow<
+  infer _Name,
+  infer _Payload,
+  infer _Success,
+  infer _Error
+> ? _Payload["Context"] | _Success["Context"] | _Error["Context"] :
+  never
+
 const EngineTag = Context.GenericTag<WorkflowEngine, WorkflowEngine["Type"]>(
   "@effect/workflow/WorkflowEngine" satisfies typeof WorkflowEngine.key
 )
@@ -196,6 +242,7 @@ export const make = <
     readonly success?: Success
     readonly error?: Error
     readonly suspendedRetrySchedule?: Schedule.Schedule<any, unknown> | undefined
+    readonly annotations?: Context.Context<never>
   }
 ): Workflow<Name, Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload, Success, Error> => {
   const suspendedRetrySchedule = options.suspendedRetrySchedule ?? defaultRetrySchedule
@@ -206,6 +253,19 @@ export const make = <
     payloadSchema: Schema.isSchema(options.payload) ? options.payload : Schema.Struct(options.payload as any),
     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)
+      })
+    },
+    annotateContext(context) {
+      return make({
+        ...options,
+        annotations: Context.merge(self.annotations, context)
+      })
+    },
     execute: Effect.fnUntraced(
       function*(fields: any, opts) {
         const payload = self.payloadSchema.make(fields)
@@ -231,7 +291,6 @@ export const make = <
           if (result._tag === "Complete") {
             return yield* result.exit as Exit.Exit<Success["Type"], Error["Type"]>
           }
-          // @effect-diagnostics effect/floatingEffect:off
           sleep ??= (yield* Schedule.driver(suspendedRetrySchedule)).next(void 0).pipe(
             Effect.catchAll(() => Effect.dieMessage(`${options.name}.execute: suspendedRetrySchedule exhausted`))
           )
@@ -420,18 +479,47 @@ export const Result = <Success extends Schema.Schema.Any, Error extends Schema.S
  */
 export const intoResult = <A, E, R>(
   effect: Effect.Effect<A, E, R>
-): Effect.Effect<Result<A, E>, never, R | WorkflowInstance> =>
-  Effect.uninterruptibleMask((restore) =>
-    Effect.withFiberRuntime((fiber) =>
-      Effect.matchCause(restore(effect), {
-        onSuccess: (value) => new Complete({ exit: Exit.succeed(value) }),
-        onFailure(cause) {
-          const instance = Context.unsafeGet(fiber.currentContext, InstanceTag)
-          return instance.suspended ? new Suspended() : new Complete({ exit: Exit.failCause(cause) })
-        }
-      })
+): Effect.Effect<Result<A, E>, never, Exclude<R, Scope.Scope> | WorkflowInstance> =>
+  Effect.contextWithEffect((context: Context.Context<WorkflowInstance>) => {
+    const instance = Context.get(context, InstanceTag)
+    return Effect.uninterruptibleMask((restore) =>
+      restore(effect).pipe(
+        Effect.scoped,
+        Effect.matchCause({
+          onSuccess: (value) => new Complete({ exit: Exit.succeed(value) }),
+          onFailure: (cause) => instance.suspended ? new Suspended() : new Complete({ exit: Exit.failCause(cause) })
+        })
+      )
     )
-  )
+  })
+
+/**
+ * @since 1.0.0
+ * @category Result
+ */
+export const wrapActivityResult = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  isSuspend: (value: A) => boolean
+): Effect.Effect<A, E, R | WorkflowInstance> =>
+  Effect.contextWithEffect((context: Context.Context<WorkflowInstance>) => {
+    const instance = Context.get(context, InstanceTag)
+    const state = instance.activityState
+    if (instance.suspended) {
+      return state.count > 0 ?
+        state.latch.await.pipe(
+          Effect.andThen(Effect.yieldNow()),
+          Effect.andThen(Effect.interrupt)
+        ) :
+        Effect.interrupt
+    }
+    if (state.count === 0) state.latch.unsafeClose()
+    state.count++
+    return Effect.onExit(effect, (exit) => {
+      state.count--
+      const isSuspended = Exit.isSuccess(exit) && isSuspend(exit.value)
+      return state.count === 0 ? state.latch.open : isSuspended ? state.latch.await : Effect.void
+    })
+  })
 
 /**
  * Add compensation logic to an effect inside a Workflow. The compensation finalizer will be
@@ -481,14 +569,15 @@ export const withCompensation: {
   compensation: (value: A, cause: Cause.Cause<unknown>) => Effect.Effect<void, never, R2>
 ): Effect.Effect<A, E, R | R2 | WorkflowInstance | Scope.Scope> =>
   Effect.uninterruptibleMask((restore) =>
-    Effect.contextWithEffect((context: Context.Context<WorkflowInstance>) => {
-      const instance = Context.get(context, InstanceTag)
-      return Effect.tap(restore(effect), (value) =>
-        Effect.addFinalizer((exit) => {
-          if (Exit.isSuccess(exit) || instance.suspended) {
-            return Effect.void
-          }
-          return compensation(value, exit.cause)
-        }))
-    })
+    Effect.tap(
+      restore(effect),
+      (value) =>
+        Effect.contextWithEffect((context: Context.Context<WorkflowInstance>) =>
+          Effect.addFinalizer((exit) =>
+            Exit.isSuccess(exit) || Context.get(context, InstanceTag).suspended
+              ? Effect.void
+              : compensation(value, exit.cause)
+          )
+        )
+    )
   ))

package/src/WorkflowEngine.ts

@@ -2,7 +2,7 @@
  * @since 1.0.0
  */
 import * as Context from "effect/Context"
-import type * as Effect from "effect/Effect"
+import * as Effect from "effect/Effect"
 import type * as Option from "effect/Option"
 import type * as Schema from "effect/Schema"
 import type * as Activity from "./Activity.js"
@@ -48,14 +48,6 @@ export class WorkflowEngine extends Context.Tag("@effect/workflow/WorkflowEngine
       executionId: string
     ) => Effect.Effect<void>
 
-    /**
-     * Resume a suspended workflow.
-     */
-    readonly resume: (
-      workflowName: string,
-      executionId: string
-    ) => Effect.Effect<void>
-
     /**
      * Execute an activity from a workflow.
      */
@@ -118,5 +110,22 @@ export class WorkflowInstance extends Context.Tag("@effect/workflow/WorkflowEngi
      * Whether the workflow has requested to be suspended.
      */
     suspended: boolean
+
+    readonly activityState: {
+      count: number
+      readonly latch: Effect.Latch
+    }
   }
->() {}
+>() {
+  static initial(workflow: Workflow.Any, executionId: string): WorkflowInstance["Type"] {
+    return WorkflowInstance.of({
+      executionId,
+      workflow,
+      suspended: false,
+      activityState: {
+        count: 0,
+        latch: Effect.unsafeMakeLatch()
+      }
+    })
+  }
+}

package/src/WorkflowProxy.ts

@@ -0,0 +1,178 @@
+/**
+ * @since 1.0.0
+ */
+import * as HttpApiEndpoint from "@effect/platform/HttpApiEndpoint"
+import * as HttpApiGroup from "@effect/platform/HttpApiGroup"
+import * as Rpc from "@effect/rpc/Rpc"
+import * as RpcGroup from "@effect/rpc/RpcGroup"
+import type { NonEmptyReadonlyArray } from "effect/Array"
+import type * as Workflow from "./Workflow.js"
+
+/**
+ * Derives an `RpcGroup` from a list of workflows.
+ *
+ * ```ts
+ * import { RpcServer } from "@effect/rpc"
+ * import { Workflow, WorkflowProxy, WorkflowProxyServer } from "@effect/workflow"
+ * import { Layer, Schema } from "effect"
+ *
+ * const EmailWorkflow = Workflow.make({
+ *   name: "EmailWorkflow",
+ *   payload: {
+ *     id: Schema.String,
+ *     to: Schema.String
+ *   },
+ *   idempotencyKey: ({ id }) => id
+ * })
+ *
+ * const myWorkflows = [EmailWorkflow] as const
+ *
+ * // Use WorkflowProxy.toRpcGroup to create a `RpcGroup` from the
+ * // workflows
+ * class MyRpcs extends WorkflowProxy.toRpcGroup(myWorkflows) {}
+ *
+ * // Use WorkflowProxyServer.layerRpcHandlers to create a layer that implements
+ * // the rpc handlers
+ * const ApiLayer = RpcServer.layer(MyRpcs).pipe(
+ *   Layer.provide(WorkflowProxyServer.layerRpcHandlers(myWorkflows))
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const toRpcGroup = <
+  const Workflows extends NonEmptyReadonlyArray<Workflow.Any>,
+  const Prefix extends string = ""
+>(
+  workflows: Workflows,
+  options?: {
+    readonly prefix?: Prefix | undefined
+  }
+): RpcGroup.RpcGroup<ConvertRpcs<Workflows[number], Prefix>> => {
+  const prefix = options?.prefix ?? ""
+  const rpcs: Array<Rpc.Any> = []
+  for (const workflow of workflows) {
+    rpcs.push(
+      Rpc.make(`${prefix}${workflow.name}`, {
+        payload: workflow.payloadSchema,
+        error: workflow.errorSchema,
+        success: workflow.successSchema
+      }).annotateContext(workflow.annotations),
+      Rpc.make(`${prefix}${workflow.name}Discard`, {
+        payload: workflow.payloadSchema
+      }).annotateContext(workflow.annotations)
+    )
+  }
+  return RpcGroup.make(...rpcs) as any
+}
+
+/**
+ * @since 1.0.0
+ */
+export type ConvertRpcs<Workflows extends Workflow.Any, Prefix extends string> = Workflows extends Workflow.Workflow<
+  infer _Name,
+  infer _Payload,
+  infer _Success,
+  infer _Error
+> ?
+    | Rpc.Rpc<`${Prefix}${_Name}`, _Payload, _Success, _Error>
+    | Rpc.Rpc<`${Prefix}${_Name}Discard`, _Payload>
+  : never
+
+/**
+ * Derives an `HttpApiGroup` from a list of workflows.
+ *
+ * ```ts
+ * import { HttpApi, HttpApiBuilder } from "@effect/platform"
+ * import { Workflow, WorkflowProxy, WorkflowProxyServer } from "@effect/workflow"
+ * import { Layer, Schema } from "effect"
+ *
+ * const EmailWorkflow = Workflow.make({
+ *   name: "EmailWorkflow",
+ *   payload: {
+ *     id: Schema.String,
+ *     to: Schema.String
+ *   },
+ *   idempotencyKey: ({ id }) => id
+ * })
+ *
+ * const myWorkflows = [EmailWorkflow] as const
+ *
+ * // Use WorkflowProxy.toHttpApiGroup to create a `HttpApiGroup` from the
+ * // workflows
+ * class MyApi extends HttpApi.make("api")
+ *   .add(WorkflowProxy.toHttpApiGroup("workflows", myWorkflows))
+ * {}
+ *
+ * // Use WorkflowProxyServer.layerHttpApi to create a layer that implements the
+ * // workflows HttpApiGroup
+ * const ApiLayer = HttpApiBuilder.api(MyApi).pipe(
+ *   Layer.provide(WorkflowProxyServer.layerHttpApi(MyApi, "workflows", myWorkflows))
+ * )
+ * ```
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const toHttpApiGroup = <const Name extends string, const Workflows extends NonEmptyReadonlyArray<Workflow.Any>>(
+  name: Name,
+  workflows: Workflows
+): HttpApiGroup.HttpApiGroup<Name, ConvertHttpApi<Workflows[number]>> => {
+  let group = HttpApiGroup.make(name)
+  for (const workflow of workflows) {
+    const path = `/${tagToPath(workflow.name)}` as const
+    group = group.add(
+      HttpApiEndpoint.post(workflow.name, path)
+        .setPayload(workflow.payloadSchema)
+        .addSuccess(workflow.successSchema)
+        .addError(workflow.errorSchema as any)
+        .annotateContext(workflow.annotations)
+    ).add(
+      HttpApiEndpoint.post(workflow.name + "Discard", `${path}/discard`)
+        .setPayload(workflow.payloadSchema)
+        .annotateContext(workflow.annotations)
+    ) as any
+  }
+  return group as any
+}
+
+const tagToPath = (tag: string): string =>
+  tag
+    .replace(/[^a-zA-Z0-9]+/g, "-") // Replace non-alphanumeric characters with hyphen
+    .replace(/([a-z])([A-Z])/g, "$1-$2") // Insert hyphen before uppercase letters
+    .toLowerCase()
+
+/**
+ * @since 1.0.0
+ */
+export type ConvertHttpApi<Workflows extends Workflow.Any> = Workflows extends Workflow.Workflow<
+  infer _Name,
+  infer _Payload,
+  infer _Success,
+  infer _Error
+> ?
+    | HttpApiEndpoint.HttpApiEndpoint<
+      _Name,
+      "POST",
+      never,
+      never,
+      _Payload["Type"],
+      never,
+      _Success["Type"],
+      _Error["Type"],
+      _Payload["Context"] | _Success["Context"],
+      _Error["Context"]
+    >
+    | HttpApiEndpoint.HttpApiEndpoint<
+      `${_Name}Discard`,
+      "POST",
+      never,
+      never,
+      _Payload["Type"],
+      never,
+      void,
+      never,
+      _Payload["Context"]
+    > :
+  never

package/src/WorkflowProxyServer.ts

@@ -0,0 +1,103 @@
+/**
+ * @since 1.0.0
+ */
+import type * as HttpApi from "@effect/platform/HttpApi"
+import * as HttpApiBuilder from "@effect/platform/HttpApiBuilder"
+import type { ApiGroup, HttpApiGroup } from "@effect/platform/HttpApiGroup"
+import type * as Rpc from "@effect/rpc/Rpc"
+import type { NonEmptyReadonlyArray } from "effect/Array"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import type * as Workflow from "./Workflow.js"
+import type { WorkflowEngine } from "./WorkflowEngine.js"
+
+/**
+ * @since 1.0.0
+ * @category Layers
+ */
+export const layerHttpApi = <
+  ApiId extends string,
+  Groups extends HttpApiGroup.Any,
+  ApiE,
+  ApiR,
+  Name extends HttpApiGroup.Name<Groups>,
+  const Workflows extends NonEmptyReadonlyArray<Workflow.Any>
+>(
+  api: HttpApi.HttpApi<ApiId, Groups, ApiE, ApiR>,
+  name: Name,
+  workflows: Workflows
+): Layer.Layer<
+  ApiGroup<ApiId, Name>,
+  never,
+  WorkflowEngine | Workflow.Registrations<Workflows[number]> | Workflow.Requirements<Workflows[number]>
+> =>
+  HttpApiBuilder.group(
+    api,
+    name,
+    Effect.fnUntraced(function*(handlers_) {
+      let handlers = handlers_ as any
+      for (const workflow_ of workflows) {
+        const workflow = workflow_ as Workflow.Workflow<string, any, any, any>
+        handlers = handlers
+          .handle(
+            workflow.name as any,
+            ({ payload }: { payload: any }) => workflow.execute(payload)
+          )
+          .handle(
+            workflow.name + "Discard" as any,
+            ({ payload }: { payload: any }) => workflow.execute(payload, { discard: true } as any)
+          )
+      }
+      return handlers as HttpApiBuilder.Handlers<never, never, never>
+    })
+  )
+
+/**
+ * @since 1.0.0
+ * @category Layers
+ */
+export const layerRpcHandlers = <
+  const Workflows extends NonEmptyReadonlyArray<Workflow.Any>,
+  const Prefix extends string = ""
+>(workflows: Workflows, options?: {
+  readonly prefix?: Prefix
+}): Layer.Layer<
+  RpcHandlers<Workflows[number], Prefix>,
+  never,
+  WorkflowEngine | Workflow.Registrations<Workflows[number]> | Workflow.Requirements<Workflows[number]>
+> =>
+  Layer.effectContext(Effect.gen(function*() {
+    const context = yield* Effect.context<never>()
+    const prefix = options?.prefix ?? ""
+    const handlers = new Map<string, Rpc.Handler<string>>()
+    for (const workflow_ of workflows) {
+      const workflow = workflow_ as Workflow.Workflow<string, any, any, any>
+      const tag = `${prefix}${workflow.name}`
+      const tagDiscard = `${tag}Discard`
+      const key = `@effect/rpc/Rpc/${tag}`
+      const keyDiscard = `${key}Discard`
+      handlers.set(key, {
+        context,
+        tag,
+        handler: (payload: any) => workflow.execute(payload) as any
+      } as any)
+      handlers.set(keyDiscard, {
+        context,
+        tag: tagDiscard,
+        handler: (payload: any) => workflow.execute(payload, { discard: true } as any) as any
+      } as any)
+    }
+    return Context.unsafeMake(handlers)
+  }))
+
+/**
+ * @since 1.0.0
+ */
+export type RpcHandlers<Workflows extends Workflow.Any, Prefix extends string> = Workflows extends Workflow.Workflow<
+  infer _Name,
+  infer _Payload,
+  infer _Success,
+  infer _Error
+> ? Rpc.Handler<`${Prefix}${_Name}`> | Rpc.Handler<`${Prefix}${_Name}Discard`>
+  : never

package/src/index.ts

@@ -22,3 +22,13 @@ export * as Workflow from "./Workflow.js"
  * @since 1.0.0
  */
 export * as WorkflowEngine from "./WorkflowEngine.js"
+
+/**
+ * @since 1.0.0
+ */
+export * as WorkflowProxy from "./WorkflowProxy.js"
+
+/**
+ * @since 1.0.0
+ */
+export * as WorkflowProxyServer from "./WorkflowProxyServer.js"