import * as Context from "effect/Context"; import * as Effect from "effect/Effect"; import * as Exit from "effect/Exit"; import * as Layer from "effect/Layer"; import * as Option from "effect/Option"; import * as Schedule from "effect/Schedule"; import type * as Schema from "effect/Schema"; import { type DurableDeferred, type Workflow, WorkflowEngine } from "effect/workflow"; import type { RuntimeContext } from "./RuntimeContext.ts"; declare const ImplementedTypeId: unique symbol; /** * Annotates a workflow with the name an engine stores its runs under, when * that differs from the workflow's own name. An engine that names storage * after the workflow, like Cloudflare's Durable Object engine with one class * per workflow, uses it as given. */ export class StorageName extends Context.Service()( "alchemy/Workflows/StorageName", ) {} /** * Marks a workflow as runnable here: something in the context implements it. * `Workflows.layer` provides it for the workflow it implements, and a remote * engine, like `AWS.Lambda.DurableFunctionEngine`, for the workflows its * hosts run. `Workflows.RunWorkflow` requires it, so running a workflow * nothing implements is a type error. */ export interface Implemented { readonly [ImplementedTypeId]: Name; } /** @internal */ export const Implemented = (name: Name) => Context.Service, true>(`alchemy/Workflows/Implemented/${name}`); /** @internal */ export const implemented = ( names: ReadonlyArray, ): Layer.Layer> => Layer.succeedContext( names.reduce( (context, name) => Context.add(context, Implemented(name), true), Context.empty() as Context.Context>, ), ); type Requirements = L extends Layer.Layer ? R : never; /** A workflow's handler: runs it for a payload, inside a run. */ export type Execute< Payload extends Workflow.AnyStructSchema, Success extends Schema.Top, Error extends Schema.Top, R, > = ( payload: Payload["Type"], executionId: string, ) => Effect.Effect; /** * Implement a workflow. Like `workflow.toLayer(execute)`, it registers the * handler with the engine, and it marks the workflow as implemented, so * `RunWorkflow` can run it. * * Pass the handler, or an Effect that builds it. The Effect runs once, when * the Layer is built, so resolve bindings and services there and use them in * the handler it returns. * * Handlers can call runtime-only APIs, like a bucket's `put` or another * Durable Object's methods. A runtime-only API requires `RuntimeContext`, * which a Worker's or Lambda function's init doesn't have. A handler only * runs inside a run, and every run has one, so this Layer doesn't ask for it. * * ### Implementing a workflow * **Example:** A handler * ```typescript * import * as Workflows from "alchemy/Workflows"; * import * as Effect from "effect/Effect"; * import { Activity } from "effect/workflow"; * * export const GreetLive = Workflows.layer( * Greet, * Effect.fn(function* ({ name }) { * return yield* Activity.make({ * name: "greet", * success: Schema.String, * execute: Effect.succeed(`hello ${name}`), * }); * }), * ); * ``` * * **Example:** A handler that uses a binding * ```typescript * import * as Cloudflare from "@alchemy.run/cloudflare"; * import * as Workflows from "alchemy/Workflows"; * import * as Effect from "effect/Effect"; * import { Activity } from "effect/workflow"; * import { Receipts } from "./Receipts.ts"; * * export const CheckoutLive = Workflows.layer( * Checkout, * Effect.gen(function* () { * const receipts = yield* Cloudflare.R2.WriteBucket(Receipts); * return Effect.fn(function* ({ orderId }) { * yield* Activity.make({ * name: "receipt", * execute: receipts.put(`${orderId}.json`, JSON.stringify({ orderId })).pipe(Effect.orDie), * }); * }); * }), * ); * ``` * * @primitive */ export function layer< Name extends string, Payload extends Workflow.AnyStructSchema, Success extends Schema.Top, Error extends Schema.Top, R, >( workflow: Workflow.Workflow, execute: Execute, ): Layer.Layer< Implemented, never, Exclude>>, RuntimeContext> >; export function layer< Name extends string, Payload extends Workflow.AnyStructSchema, Success extends Schema.Top, Error extends Schema.Top, R, InitE, InitR, >( workflow: Workflow.Workflow, make: Effect.Effect, InitE, InitR>, ): Layer.Layer< Implemented, InitE, // oxlint-disable-next-line typescript/no-redundant-type-constituents -- generic in R; only looks like `never` to the linter InitR | Exclude>>, RuntimeContext> >; export function layer( workflow: Workflow.Workflow, execute: | Execute | Effect.Effect< Execute, unknown, unknown >, ): Layer.Layer { return Effect.isEffect(execute) ? Layer.unwrap(Effect.map(execute, (handler) => layer(workflow, handler))) : Layer.merge( workflow.toLayer(execute as any) as Layer.Layer, implemented([workflow._tag]), ); } type NameOf = W extends Workflow.Workflow ? Name : never; type SuccessOf = W extends Workflow.Workflow ? S["Type"] : never; type ErrorOf = W extends Workflow.Workflow ? E["Type"] : never; type PayloadOf = W extends Workflow.Workflow ? P["~type.make.in"] : never; /** Where a run is. */ export type Status = | { readonly _tag: "NotStarted" } | { readonly _tag: "Running" } | { readonly _tag: "Completed"; readonly result: A } | { readonly _tag: "Failed"; readonly error: E } | { readonly _tag: "Interrupted" } | { readonly _tag: "Died"; readonly defect: unknown }; /** One run of a workflow. */ export interface Run { /** The run's id. Store it to read the run again later, with `get`. */ readonly executionId: string; /** Where the run is now. */ readonly status: Effect.Effect>; /** * Wait for the run to finish: its result, or its failure. A run can take * days, so wait in tests and scripts, not in a request. */ readonly result: Effect.Effect; /** Complete a `DurableDeferred` the run waits on. */ readonly signal: ( deferred: DurableDeferred.DurableDeferred, value: Success["Type"], ) => Effect.Effect; /** Stop the run: it fails where it waits, and its compensations run. */ readonly interrupt: Effect.Effect; } /** Starts and reads runs of one workflow. */ export interface WorkflowClient { /** Start a run, or return the run already started with the same key. Returns at once. */ readonly start: (payload: PayloadOf) => Effect.Effect, ErrorOf>>; /** A run started earlier, by its id. */ readonly get: (executionId: string) => Run, ErrorOf>; } /** How often to check a run while waiting for it. */ const POLL = Schedule.min([Schedule.exponential("100 millis"), Schedule.spaced("5 seconds")]); /** * Start and read runs of a workflow, on whichever engine the runtime * provides. Resolve it once, during init; its methods need nothing else. * * It needs the workflow implemented: by `Workflows.layer` in the same * runtime, or by a host a remote engine routes to. Running a workflow nothing * implements is a type error. * * ### Running a workflow * **Example:** Start a run from a request * ```typescript * import * as Workflows from "alchemy/Workflows"; * import * as Effect from "effect/Effect"; * import * as HttpServerResponse from "effect/http/HttpServerResponse"; * * const app = Effect.gen(function* () { * const greet = yield* Workflows.RunWorkflow(Greet); * return { * fetch: Effect.gen(function* () { * const run = yield* greet.start({ name: "sam" }); * return HttpServerResponse.text(run.executionId); * }), * }; * }); * ``` * * **Example:** Read a run later * ```typescript * const run = greet.get(executionId); * const status = yield* run.status; * yield* run.signal(Approval, "agent-7"); * ``` * * @primitive */ export const RunWorkflow = ( workflow: W, ): Effect.Effect< WorkflowClient, never, WorkflowEngine.WorkflowEngine | Implemented> > => Effect.gen(function* () { const engine = yield* WorkflowEngine.WorkflowEngine; const typed = workflow as unknown as Workflow.Workflow; const run = (executionId: string) => makeRun(engine, typed, executionId) as Run, ErrorOf>; return { start: (payload) => typed .execute(payload, { discard: true }) .pipe( Effect.provideService(WorkflowEngine.WorkflowEngine, engine), Effect.map(run), ) as Effect.Effect, ErrorOf>>, get: run, } satisfies WorkflowClient; }); /** * A handle to one run of a workflow on an engine. * * @internal */ export const makeRun = ( engine: WorkflowEngine.WorkflowEngine["Service"], workflow: Workflow.Workflow, executionId: string, ): Run => { const poll = engine.poll(workflow, executionId); return { executionId, status: Effect.map(poll, (result): Status => { if (Option.isNone(result)) return { _tag: "NotStarted" }; if (result.value._tag === "Suspended") return { _tag: "Running" }; const exit = result.value.exit; if (Exit.isSuccess(exit)) return { _tag: "Completed", result: exit.value }; const failure = exit.cause.reasons.find((reason) => reason._tag === "Fail"); if (failure?._tag === "Fail") return { _tag: "Failed", error: failure.error }; const defect = exit.cause.reasons.find((reason) => reason._tag === "Die"); return defect?._tag === "Die" ? { _tag: "Died", defect: defect.defect } : { _tag: "Interrupted" }; }) as Effect.Effect>, result: poll.pipe( Effect.flatMap((result) => Option.isSome(result) && result.value._tag === "Complete" ? Effect.succeed(result.value.exit) : Effect.fail("running" as const), ), Effect.retry({ schedule: POLL }), Effect.orDie, Effect.flatten, ) as Effect.Effect, signal: (deferred, value) => engine.deferredDone(deferred, { workflowName: workflow._tag, executionId, deferredName: deferred.name, exit: Exit.succeed(value), }) as Effect.Effect, interrupt: engine.interrupt(workflow, executionId), }; };