@effect/workflow 0.1.0

package/src/Workflow.ts

@@ -0,0 +1,401 @@
+/**
+ * @since 1.0.0
+ */
+import * as Context from "effect/Context"
+import * as Data from "effect/Data"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import * as Layer from "effect/Layer"
+import type { Pipeable } from "effect/Pipeable"
+import * as Predicate from "effect/Predicate"
+import * as PrimaryKey from "effect/PrimaryKey"
+import * as Schedule from "effect/Schedule"
+import * as Schema from "effect/Schema"
+import type * as AST from "effect/SchemaAST"
+import { makeHashDigest } from "./internal/crypto.js"
+import type { WorkflowEngine, WorkflowInstance } from "./WorkflowEngine.js"
+
+/**
+ * @since 1.0.0
+ * @category Symbols
+ */
+export const TypeId: unique symbol = Symbol.for("@effect/workflow/Workflow")
+
+/**
+ * @since 1.0.0
+ * @category Symbols
+ */
+export type TypeId = typeof TypeId
+
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export interface Workflow<
+  Name extends string,
+  Payload extends AnyStructSchema,
+  Success extends Schema.Schema.Any,
+  Error extends Schema.Schema.All
+> {
+  readonly [TypeId]: TypeId
+  readonly name: Name
+  readonly payloadSchema: Payload
+  readonly successSchema: Success
+  readonly errorSchema: Error
+
+  /**
+   * Execute the workflow with the given payload.
+   */
+  readonly execute: <const Discard extends boolean = false>(
+    payload: [keyof Payload["fields"]] extends [never] ? void
+      : Schema.Simplify<Schema.Struct.Constructor<Payload["fields"]>>,
+    options?: {
+      readonly discard?: Discard
+    }
+  ) => Effect.Effect<
+    Discard extends true ? void : Success["Type"],
+    Discard extends true ? never : Error["Type"],
+    WorkflowEngine | Registration<Name> | Payload["Context"] | Success["Context"] | Error["Context"]
+  >
+
+  /**
+   * Interrupt a workflow execution for the given execution ID.
+   */
+  readonly interrupt: (executionId: string) => Effect.Effect<void, never, WorkflowEngine | Registration<Name>>
+
+  /**
+   * Create a layer that registers the workflow and provides an effect to
+   * execute it.
+   */
+  readonly toLayer: <R>(
+    execute: (
+      payload: Payload["Type"],
+      executionId: string
+    ) => Effect.Effect<Success["Type"], Error["Type"], R>
+  ) => Layer.Layer<
+    Registration<Name> | WorkflowEngine,
+    never,
+    | WorkflowEngine
+    | Exclude<R, WorkflowEngine | WorkflowInstance>
+    | Payload["Context"]
+    | Success["Context"]
+    | Error["Context"]
+  >
+
+  /**
+   * For the given payload, compute the deterministic execution ID.
+   */
+  readonly executionId: (
+    payload: Schema.Simplify<Schema.Struct.Constructor<Payload["fields"]>>
+  ) => Effect.Effect<string>
+}
+
+/**
+ * @since 1.0.0
+ */
+export interface AnyStructSchema extends Pipeable {
+  readonly [Schema.TypeId]: any
+  readonly make: any
+  readonly Type: any
+  readonly Encoded: any
+  readonly Context: any
+  readonly ast: AST.AST
+  readonly fields: Schema.Struct.Fields
+  readonly annotations: any
+}
+
+/**
+ * @since 1.0.0
+ * @category constructors
+ */
+export interface AnyTaggedRequestSchema extends AnyStructSchema {
+  readonly _tag: string
+  readonly Type: PrimaryKey.PrimaryKey
+  readonly success: Schema.Schema.Any
+  readonly failure: Schema.Schema.All
+}
+
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export interface Registration<Name extends string> {
+  readonly _: unique symbol
+  readonly name: Name
+}
+
+/**
+ * @since 1.0.0
+ * @category Models
+ */
+export interface Any {
+  readonly [TypeId]: TypeId
+  readonly name: string
+  readonly payloadSchema: AnyStructSchema
+  readonly successSchema: Schema.Schema.Any
+  readonly errorSchema: Schema.Schema.All
+  readonly executionId: (payload: any) => Effect.Effect<string>
+}
+
+const EngineTag = Context.GenericTag<WorkflowEngine, WorkflowEngine["Type"]>(
+  "@effect/workflow/WorkflowEngine" satisfies typeof WorkflowEngine.key
+)
+
+const InstanceTag = Context.GenericTag<WorkflowInstance, WorkflowInstance["Type"]>(
+  "@effect/workflow/WorkflowEngine/WorkflowInstance" satisfies typeof WorkflowInstance.key
+)
+
+/**
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const make = <
+  const Name extends string,
+  Payload extends Schema.Struct.Fields | AnyStructSchema,
+  Success extends Schema.Schema.Any = typeof Schema.Void,
+  Error extends Schema.Schema.All = typeof Schema.Never
+>(
+  options: {
+    readonly name: Name
+    readonly payload: Payload
+    readonly idempotencyKey: (
+      payload: Payload extends Schema.Struct.Fields ? Schema.Struct.Type<Payload> : Payload["Type"]
+    ) => string
+    readonly success?: Success
+    readonly error?: Error
+    readonly suspendedRetrySchedule?: Schedule.Schedule<any, unknown> | undefined
+  }
+): Workflow<Name, Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload, Success, Error> => {
+  const suspendedRetrySchedule = options.suspendedRetrySchedule ?? defaultRetrySchedule
+  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) ? options.payload : Schema.Struct(options.payload as any),
+    successSchema: options.success ?? Schema.Void as any,
+    errorSchema: options.error ?? Schema.Never as any,
+    execute: Effect.fnUntraced(
+      function*(fields: any, opts) {
+        const payload = self.payloadSchema.make(fields)
+        const engine = yield* EngineTag
+        const executionId = yield* makeExecutionId(payload)
+        yield* Effect.annotateCurrentSpan({ executionId })
+        if (opts?.discard) {
+          return yield* engine.execute({
+            workflow: self,
+            executionId,
+            payload,
+            discard: true
+          })
+        }
+        let sleep: Effect.Effect<any> | undefined
+        while (true) {
+          const result = yield* engine.execute({
+            workflow: self,
+            executionId,
+            payload,
+            discard: false
+          })
+          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`))
+          )
+          yield* sleep
+        }
+      },
+      Effect.withSpan(`${options.name}.execute`, { captureStackTrace: false })
+    ),
+    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 }
+        })
+    ),
+    toLayer: (execute) =>
+      Layer.effectContext(Effect.gen(function*() {
+        const context = yield* Effect.context<WorkflowEngine>()
+        const engine = Context.get(context, EngineTag)
+        yield* engine.register(self, (payload, executionId) =>
+          execute(payload, executionId).pipe(
+            Effect.provide(context)
+          ) as any)
+        return EngineTag.context(engine)
+      })) as any,
+    executionId: (payload) => makeExecutionId(self.payloadSchema.make(payload))
+  }
+
+  return self
+}
+
+const defaultRetrySchedule = Schedule.exponential(200, 1.5).pipe(
+  Schedule.union(Schedule.spaced(30000))
+)
+
+/**
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const fromTaggedRequest = <S extends AnyTaggedRequestSchema>(schema: S, options?: {
+  readonly suspendedRetrySchedule?: Schedule.Schedule<any, unknown> | undefined
+}): Workflow<S["_tag"], S, S["success"], S["failure"]> =>
+  make({
+    name: schema._tag,
+    payload: schema as any,
+    success: schema.success,
+    error: schema.failure,
+    idempotencyKey: PrimaryKey.value,
+    suspendedRetrySchedule: options?.suspendedRetrySchedule
+  })
+
+/**
+ * @since 1.0.0
+ * @category Result
+ */
+export const ResultTypeId: unique symbol = Symbol.for("@effect/workflow/Workflow/Result")
+
+/**
+ * @since 1.0.0
+ * @category Result
+ */
+export type ResultTypeId = typeof ResultTypeId
+
+/**
+ * @since 1.0.0
+ * @category Result
+ */
+export const isResult = <A = unknown, E = unknown>(u: unknown): u is Result<A, E> =>
+  Predicate.hasProperty(u, ResultTypeId)
+
+/**
+ * @since 1.0.0
+ * @category Result
+ */
+export type Result<A, E> = Complete<A, E> | Suspended
+
+/**
+ * @since 1.0.0
+ * @category Result
+ */
+export type ResultEncoded<A, E> = CompleteEncoded<A, E> | typeof Suspended.Encoded
+
+/**
+ * @since 1.0.0
+ * @category Result
+ */
+export class Complete<A, E> extends Data.TaggedClass("Complete")<{
+  readonly exit: Exit.Exit<A, E>
+}> {
+  /**
+   * @since 1.0.0
+   */
+  readonly [ResultTypeId]: ResultTypeId = ResultTypeId
+
+  /**
+   * @since 1.0.0
+   */
+  static SchemaFromSelf<Success extends Schema.Schema.Any, Error extends Schema.Schema.All>(_options: {
+    readonly success: Success
+    readonly error: Error
+  }): Schema.Schema<Complete<Success["Type"], Error["Type"]>> {
+    return Schema.declare((u): u is Complete<Success["Type"], Error["Type"]> => isResult(u) && u._tag === "Complete")
+  }
+
+  /**
+   * @since 1.0.0
+   */
+  static SchemaEncoded<Success extends Schema.Schema.Any, Error extends Schema.Schema.All>(options: {
+    readonly success: Success
+    readonly error: Error
+  }) {
+    return Schema.Struct({
+      _tag: Schema.tag("Complete"),
+      exit: Schema.Exit({ success: options.success, failure: options.error, defect: Schema.Defect })
+    })
+  }
+
+  /**
+   * @since 1.0.0
+   */
+  static Schema<Success extends Schema.Schema.Any, Error extends Schema.Schema.All>(options: {
+    readonly success: Success
+    readonly error: Error
+  }): Schema.Schema<
+    Complete<Success["Type"], Error["Type"]>,
+    CompleteEncoded<Success["Encoded"], Error["Encoded"]>
+  > {
+    return Schema.transform(
+      this.SchemaEncoded(options),
+      this.SchemaFromSelf(options),
+      {
+        decode(fromA) {
+          return new Complete({ exit: fromA.exit })
+        },
+        encode(toI) {
+          return toI
+        }
+      }
+    ) as any
+  }
+}
+
+/**
+ * @since 1.0.0
+ * @category Result
+ */
+export interface CompleteEncoded<A, E> {
+  readonly _tag: "Complete"
+  readonly exit: Schema.ExitEncoded<A, E, unknown>
+}
+
+/**
+ * @since 1.0.0
+ * @category Result
+ */
+export class Suspended extends Schema.TaggedClass<Suspended>("@effect/workflow/Workflow/Suspended")("Suspended", {}) {
+  /**
+   * @since 1.0.0
+   */
+  readonly [ResultTypeId]: ResultTypeId = ResultTypeId
+}
+
+/**
+ * @since 1.0.0
+ * @category Result
+ */
+export const Result = <Success extends Schema.Schema.Any, Error extends Schema.Schema.All>(
+  options: {
+    readonly success: Success
+    readonly error: Error
+  }
+): Schema.Schema<
+  Result<Success["Type"], Error["Type"]>,
+  ResultEncoded<Success["Encoded"], Error["Encoded"]>,
+  Success["Context"] | Error["Context"]
+> => Schema.Union(Complete.Schema(options), Suspended)
+
+/**
+ * @since 1.0.0
+ * @category Result
+ */
+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) })
+        }
+      })
+    )
+  )

package/src/WorkflowEngine.ts

@@ -0,0 +1,122 @@
+/**
+ * @since 1.0.0
+ */
+import * as Context from "effect/Context"
+import type * 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"
+import type { DurableClock } from "./DurableClock.js"
+import type * as DurableDeferred from "./DurableDeferred.js"
+import type * as Workflow from "./Workflow.js"
+
+/**
+ * @since 1.0.0
+ * @category Services
+ */
+export class WorkflowEngine extends Context.Tag("@effect/workflow/WorkflowEngine")<
+  WorkflowEngine,
+  {
+    /**
+     * Register a workflow with the engine.
+     */
+    readonly register: (
+      workflow: Workflow.Any,
+      execute: (
+        payload: object,
+        executionId: string
+      ) => Effect.Effect<unknown, unknown, WorkflowInstance | WorkflowEngine>
+    ) => Effect.Effect<void>
+
+    /**
+     * Execute a registered workflow.
+     */
+    readonly execute: <const Discard extends boolean>(
+      options: {
+        readonly workflow: Workflow.Any
+        readonly executionId: string
+        readonly payload: object
+        readonly discard: Discard
+      }
+    ) => Effect.Effect<Discard extends true ? void : Workflow.Result<unknown, unknown>>
+
+    /**
+     * Interrupt a registered workflow.
+     */
+    readonly interrupt: (
+      workflow: Workflow.Any,
+      executionId: string
+    ) => Effect.Effect<void>
+
+    /**
+     * Resume a suspended workflow.
+     */
+    readonly resume: (
+      workflowName: string,
+      executionId: string
+    ) => Effect.Effect<void>
+
+    /**
+     * Execute an activity from a workflow.
+     */
+    readonly activityExecute: (
+      options: {
+        readonly activity: Activity.Any
+        readonly attempt: number
+      }
+    ) => Effect.Effect<Workflow.Result<unknown, unknown>, never, WorkflowInstance>
+
+    /**
+     * Try to retrieve the result of an DurableDeferred
+     */
+    readonly deferredResult: (
+      deferred: DurableDeferred.Any
+    ) => Effect.Effect<Option.Option<Schema.ExitEncoded<unknown, unknown, unknown>>, never, WorkflowInstance>
+
+    /**
+     * Set the result of a DurableDeferred, and then resume any waiting
+     * workflows.
+     */
+    readonly deferredDone: (
+      options: {
+        readonly workflowName: string
+        readonly executionId: string
+        readonly deferred: DurableDeferred.Any
+        readonly exit: Schema.ExitEncoded<unknown, unknown, unknown>
+      }
+    ) => Effect.Effect<void>
+
+    /**
+     * Schedule a wake up for a DurableClock
+     */
+    readonly scheduleClock: (options: {
+      readonly workflow: Workflow.Any
+      readonly executionId: string
+      readonly clock: DurableClock
+    }) => Effect.Effect<void>
+  }
+>() {}
+
+/**
+ * @since 1.0.0
+ * @category Services
+ */
+export class WorkflowInstance extends Context.Tag("@effect/workflow/WorkflowEngine/WorkflowInstance")<
+  WorkflowInstance,
+  {
+    /**
+     * The workflow execution ID.
+     */
+    readonly executionId: string
+
+    /**
+     * The workflow definition.
+     */
+    readonly workflow: Workflow.Any
+
+    /**
+     * Whether the workflow has requested to be suspended.
+     */
+    suspended: boolean
+  }
+>() {}

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @since 1.0.0
+ */
+export * as Activity from "./Activity.js"
+
+/**
+ * @since 1.0.0
+ */
+export * as DurableClock from "./DurableClock.js"
+
+/**
+ * @since 1.0.0
+ */
+export * as DurableDeferred from "./DurableDeferred.js"
+
+/**
+ * @since 1.0.0
+ */
+export * as Workflow from "./Workflow.js"
+
+/**
+ * @since 1.0.0
+ */
+export * as WorkflowEngine from "./WorkflowEngine.js"

package/src/internal/crypto.ts

@@ -0,0 +1,15 @@
+import * as Effect from "effect/Effect"
+
+/** @internal */
+export const makeHashDigest = (original: string) =>
+  Effect.map(
+    Effect.promise(() => crypto.subtle.digest("SHA-256", new TextEncoder().encode(original))),
+    (buffer) => {
+      const data = new Uint8Array(buffer)
+      let hexString = ""
+      for (let i = 0; i < 16; i++) {
+        hexString += data[i].toString(16).padStart(2, "0")
+      }
+      return hexString
+    }
+  )