import * as Context from "effect/Context"; import * as Effect from "effect/Effect"; import * as Layer from "effect/Layer"; 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; declare const StorageName_base: Context.ServiceClass; /** * 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 declare class StorageName extends StorageName_base { } /** * 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 declare const Implemented: (name: Name) => Context.Service, true>; /** @internal */ export declare const implemented: (names: ReadonlyArray) => Layer.Layer>; type Requirements = L extends Layer.Layer ? R : never; /** A workflow's handler: runs it for a payload, inside a run. */ export type Execute = (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 declare function layer(workflow: Workflow.Workflow, execute: Execute): Layer.Layer, never, Exclude>>, RuntimeContext>>; export declare function layer(workflow: Workflow.Workflow, make: Effect.Effect, InitE, InitR>): Layer.Layer, InitE, InitR | Exclude>>, RuntimeContext>>; 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>; } /** * 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 declare const RunWorkflow: (workflow: W) => Effect.Effect, never, WorkflowEngine.WorkflowEngine | Implemented>>; /** * A handle to one run of a workflow on an engine. * * @internal */ export declare const makeRun: (engine: WorkflowEngine.WorkflowEngine["Service"], workflow: Workflow.Workflow, executionId: string) => Run; export {}; //# sourceMappingURL=Workflows.d.ts.map