effect-cf 0.1.0 → 0.2.0

package/src/WorkflowBinding.ts

@@ -0,0 +1,254 @@
+import { Data, Effect, Option, Schema as S } from "effect";
+
+import * as Binding from "./Binding";
+import type * as RpcDefinition from "./RpcDefinition";
+
+const TypeId = "effect-cf/WorkflowBinding" as const;
+
+export type WorkflowInstanceCreateOptions<Payload> = Omit<
+  globalThis.WorkflowInstanceCreateOptions<Payload>,
+  "params"
+>;
+
+export type WorkflowInstanceCreateBatchOptions<Payload, EncodedPayload = unknown> = ReadonlyArray<
+  { readonly payload: Payload } & WorkflowInstanceCreateOptions<EncodedPayload>
+>;
+
+export interface WorkflowInstanceRestartOptions {
+  readonly from?: {
+    readonly name?: string;
+    readonly count?: number;
+    readonly type?: string;
+  };
+}
+
+export type WorkflowInstanceStatusName = globalThis.InstanceStatus["status"];
+
+export interface WorkflowInstanceStatus<Result> {
+  readonly status: WorkflowInstanceStatusName;
+  readonly output: Option.Option<Result>;
+  readonly error: Option.Option<{
+    readonly name: string;
+    readonly message: string;
+  }>;
+}
+
+export interface WorkflowInstance<Result> {
+  readonly raw: globalThis.WorkflowInstance;
+  readonly id: string;
+  readonly pause: Effect.Effect<void, WorkflowOperationError>;
+  readonly resume: Effect.Effect<void, WorkflowOperationError>;
+  readonly terminate: Effect.Effect<void, WorkflowOperationError>;
+  readonly restart: (
+    options?: WorkflowInstanceRestartOptions,
+  ) => Effect.Effect<void, WorkflowOperationError>;
+  readonly status: Effect.Effect<
+    WorkflowInstanceStatus<Result>,
+    WorkflowOperationError | WorkflowResultDecodeError
+  >;
+  readonly sendEvent: (event: WorkflowInstanceEvent) => Effect.Effect<void, WorkflowOperationError>;
+}
+
+export interface WorkflowInstanceEvent {
+  readonly type: string;
+  readonly payload: unknown;
+}
+
+export interface WorkflowBindingDefinition<
+  Payload extends RpcDefinition.ServiceFreeSchema,
+  Result extends RpcDefinition.ServiceFreeSchema,
+> {
+  /** Binding name as configured in `wrangler.jsonc`. */
+  readonly binding: string;
+  /** Codec used to encode payloads passed to `Workflow.create`. */
+  readonly payload: Payload;
+  /** Codec used to decode completed workflow status output. */
+  readonly result: Result;
+}
+
+declare const WorkflowServiceTypeId: unique symbol;
+
+export interface WorkflowService<
+  Id extends string,
+  Payload extends RpcDefinition.ServiceFreeSchema,
+  Result extends RpcDefinition.ServiceFreeSchema,
+> {
+  readonly [WorkflowServiceTypeId]: {
+    readonly id: Id;
+    readonly payload: S.Schema.Type<Payload>;
+    readonly encodedPayload: S.Codec.Encoded<Payload>;
+    readonly result: S.Schema.Type<Result>;
+    readonly encodedResult: S.Codec.Encoded<Result>;
+  };
+}
+
+export class WorkflowOperationError extends Data.TaggedError("WorkflowOperationError")<{
+  readonly binding: string;
+  readonly operation: string;
+  readonly cause: unknown;
+}> {}
+
+export class WorkflowResultDecodeError extends Data.TaggedError("WorkflowResultDecodeError")<{
+  readonly binding: string;
+  readonly instanceId: string;
+  readonly cause: unknown;
+}> {}
+
+const workflowError = (binding: string, operation: string, cause: unknown) =>
+  new WorkflowOperationError({ binding, operation, cause });
+
+const tryWorkflowPromise = <A>(
+  binding: string,
+  operation: string,
+  evaluate: () => Promise<A>,
+): Effect.Effect<A, WorkflowOperationError> =>
+  Effect.tryPromise({
+    try: evaluate,
+    catch: (cause) => workflowError(binding, operation, cause),
+  });
+
+const isWorkflow = <Payload>(value: unknown): value is globalThis.Workflow<Payload> => {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const resource = value as Record<string, unknown>;
+
+  return (
+    typeof resource.create === "function" &&
+    typeof resource.createBatch === "function" &&
+    typeof resource.get === "function"
+  );
+};
+
+export const make = <
+  Id extends string,
+  Payload extends RpcDefinition.ServiceFreeSchema,
+  Result extends RpcDefinition.ServiceFreeSchema,
+>(
+  id: Id,
+  definition: WorkflowBindingDefinition<Payload, Result>,
+) => Service<WorkflowService<Id, Payload, Result>>()<Id, Payload, Result>(id, definition);
+
+export const Service =
+  <Self>() =>
+  <
+    Id extends string,
+    Payload extends RpcDefinition.ServiceFreeSchema,
+    Result extends RpcDefinition.ServiceFreeSchema,
+  >(
+    id: Id,
+    definition: WorkflowBindingDefinition<Payload, Result>,
+  ) => {
+    type PayloadValue = S.Schema.Type<Payload>;
+    type EncodedPayload = S.Codec.Encoded<Payload>;
+    type ResultValue = S.Schema.Type<Result>;
+
+    const tag = Binding.Service<Self>()(
+      id,
+      definition.binding,
+      (value): value is globalThis.Workflow<EncodedPayload> => isWorkflow<EncodedPayload>(value),
+    );
+
+    const encodePayload = S.encodeEffect(definition.payload);
+    const decodeResult = S.decodeUnknownEffect(definition.result);
+
+    const wrapInstance = (raw: globalThis.WorkflowInstance): WorkflowInstance<ResultValue> => {
+      const operation = <A>(name: string, evaluate: () => Promise<A>) =>
+        tryWorkflowPromise(definition.binding, name, evaluate);
+
+      return {
+        raw,
+        id: raw.id,
+        pause: operation("pause", () => raw.pause()),
+        resume: operation("resume", () => raw.resume()),
+        terminate: operation("terminate", () => raw.terminate()),
+        restart: (options) =>
+          operation("restart", () =>
+            (raw as { restart(options?: WorkflowInstanceRestartOptions): Promise<void> }).restart(
+              options,
+            ),
+          ),
+        status: operation("status", () => raw.status()).pipe(
+          Effect.flatMap((status) =>
+            Effect.gen(function* () {
+              const output =
+                status.output === undefined
+                  ? Option.none<ResultValue>()
+                  : Option.some(
+                      yield* decodeResult(status.output).pipe(
+                        Effect.mapError(
+                          (cause) =>
+                            new WorkflowResultDecodeError({
+                              binding: definition.binding,
+                              instanceId: raw.id,
+                              cause,
+                            }),
+                        ),
+                      ),
+                    );
+
+              return {
+                status: status.status,
+                output,
+                error: status.error === undefined ? Option.none() : Option.some(status.error),
+              };
+            }),
+          ),
+        ),
+        sendEvent: (event) => operation("sendEvent", () => raw.sendEvent(event)),
+      };
+    };
+
+    const create = Effect.fnUntraced(function* (
+      payload: PayloadValue,
+      options?: WorkflowInstanceCreateOptions<EncodedPayload>,
+    ) {
+      const workflow = yield* tag;
+      const encoded = yield* encodePayload(payload);
+      const raw = yield* tryWorkflowPromise(definition.binding, "create", () =>
+        workflow.create({ ...options, params: encoded }),
+      );
+
+      return wrapInstance(raw);
+    });
+
+    const createBatch = Effect.fnUntraced(function* (
+      batch: WorkflowInstanceCreateBatchOptions<PayloadValue, EncodedPayload>,
+    ) {
+      const workflow = yield* tag;
+      const encodedBatch: Array<globalThis.WorkflowInstanceCreateOptions<EncodedPayload>> = [];
+
+      for (const item of batch) {
+        const { payload, ...options } = item;
+
+        encodedBatch.push({
+          ...options,
+          params: yield* encodePayload(payload),
+        });
+      }
+
+      const rawInstances = yield* tryWorkflowPromise(definition.binding, "createBatch", () =>
+        workflow.createBatch(encodedBatch),
+      );
+
+      return rawInstances.map(wrapInstance);
+    });
+
+    const get = Effect.fnUntraced(function* (instanceId: string) {
+      const workflow = yield* tag;
+      const raw = yield* tryWorkflowPromise(definition.binding, "get", () =>
+        workflow.get(instanceId),
+      );
+
+      return wrapInstance(raw);
+    });
+
+    return Object.assign(tag, {
+      [TypeId]: TypeId,
+      binding: definition.binding,
+      create,
+      createBatch,
+      get,
+    });
+  };

package/src/WorkflowDefinition.ts

@@ -0,0 +1,167 @@
+import { Effect, Schema as S, type Layer } from "effect";
+
+import type { WorkerEnvironment } from "./Environment";
+import type { ExecutionContext, WorkerContext } from "./Worker";
+import type * as RpcDefinition from "./RpcDefinition";
+import * as WorkflowBinding from "./WorkflowBinding";
+import * as WorkflowEntrypoint from "./Workflow";
+
+export interface Definition<
+  Id extends string = string,
+  Payload extends RpcDefinition.ServiceFreeSchema = RpcDefinition.ServiceFreeSchema,
+  Result extends RpcDefinition.ServiceFreeSchema = RpcDefinition.ServiceFreeSchema,
+> {
+  readonly id: Id;
+  readonly payload: Payload;
+  readonly result: Result;
+}
+
+export namespace Definition {
+  export type Any = Definition<
+    string,
+    RpcDefinition.ServiceFreeSchema,
+    RpcDefinition.ServiceFreeSchema
+  >;
+}
+
+declare const BindingServiceTypeId: unique symbol;
+
+export interface BindingService<Id extends string, Self extends Definition.Any> {
+  readonly [BindingServiceTypeId]: {
+    readonly id: Id;
+    readonly definition: Self;
+  };
+}
+
+export type Handler<ROut, Self extends Definition.Any> = (
+  payload: S.Schema.Type<Self["payload"]>,
+) => Effect.Effect<
+  S.Schema.Type<Self["result"]>,
+  unknown,
+  WorkflowEntrypoint.WorkflowRunContext<ROut>
+>;
+
+export interface Options<ROut, Self extends Definition.Any> {
+  readonly run: Handler<ROut, Self>;
+}
+
+const makeDefinition = <
+  Id extends string,
+  Payload extends RpcDefinition.ServiceFreeSchema,
+  Result extends RpcDefinition.ServiceFreeSchema,
+>(
+  id: Id,
+  definition: {
+    readonly payload: Payload;
+    readonly result: Result;
+  },
+) => {
+  type SelfDefinition = Definition<Id, Payload, Result>;
+  const workflowDefinition: SelfDefinition = {
+    id,
+    payload: definition.payload,
+    result: definition.result,
+  };
+
+  return Object.assign(workflowDefinition, {
+    make: <ROut, LayerError>(
+      layer: Layer.Layer<ROut, LayerError, ExecutionContext | WorkerContext | WorkerEnvironment>,
+      options: Options<ROut, SelfDefinition>,
+    ) =>
+      WorkflowEntrypoint.make(layer, {
+        run: wrapHandler(workflowDefinition, options.run),
+      }),
+    Binding:
+      <Self>() =>
+      <BindingId extends string>(
+        bindingId: BindingId,
+        binding: Omit<
+          WorkflowBinding.WorkflowBindingDefinition<Payload, Result>,
+          "payload" | "result"
+        >,
+      ) =>
+        WorkflowBinding.Service<Self>()<BindingId, Payload, Result>(bindingId, {
+          ...binding,
+          payload: definition.payload,
+          result: definition.result,
+        }),
+    binding: <BindingId extends string>(
+      bindingId: BindingId,
+      binding: Omit<
+        WorkflowBinding.WorkflowBindingDefinition<Payload, Result>,
+        "payload" | "result"
+      >,
+    ) =>
+      WorkflowBinding.Service<BindingService<BindingId, SelfDefinition>>()<
+        BindingId,
+        Payload,
+        Result
+      >(bindingId, {
+        ...binding,
+        payload: definition.payload,
+        result: definition.result,
+      }),
+  });
+};
+
+export const make = makeDefinition;
+
+export const Tag =
+  <_Self>() =>
+  <
+    Id extends string,
+    Payload extends RpcDefinition.ServiceFreeSchema,
+    Result extends RpcDefinition.ServiceFreeSchema,
+  >(
+    id: Id,
+    definition: {
+      readonly payload: Payload;
+      readonly result: Result;
+    },
+  ) => {
+    const workflowDefinition = makeDefinition(id, definition);
+
+    abstract class WorkflowDefinitionClass {
+      static readonly id = workflowDefinition.id;
+      static readonly payload = workflowDefinition.payload;
+      static readonly result = workflowDefinition.result;
+      static readonly make = workflowDefinition.make;
+      static readonly Binding = workflowDefinition.Binding;
+      static readonly binding = workflowDefinition.binding;
+    }
+
+    return WorkflowDefinitionClass as (abstract new () => object) & typeof workflowDefinition;
+  };
+
+export const Workflow = Tag;
+
+const wrapHandler = <ROut, const Self extends Definition.Any>(
+  definition: Self,
+  handler: Handler<ROut, Self>,
+): WorkflowEntrypoint.WorkflowHandler<
+  ROut,
+  S.Codec.Encoded<Self["payload"]>,
+  S.Codec.Encoded<Self["result"]>
+> => {
+  const decodePayload = S.decodeUnknownEffect(definition.payload);
+  const encodeResult = S.encodeEffect(definition.result);
+
+  return (payload) =>
+    Effect.gen(function* () {
+      const decodedPayload = yield* decodePayload(payload);
+      const event = yield* WorkflowEntrypoint.WorkflowEvent;
+      const decodedEvent = {
+        ...event,
+        payload: decodedPayload,
+      } as WorkflowEntrypoint.WorkflowEventService<S.Schema.Type<Self["payload"]>>;
+      const result = yield* handler(decodedPayload as S.Schema.Type<Self["payload"]>).pipe(
+        Effect.provideService(WorkflowEntrypoint.WorkflowEvent, decodedEvent),
+      );
+      return yield* encodeResult(result as S.Schema.Type<Self["result"]>);
+    });
+};
+
+export const implement = <ROut, const Self extends Definition.Any>(
+  _definition: Self,
+  handler: Handler<ROut, Self>,
+): Handler<ROut, Self> => handler;

package/src/index.ts

@@ -8,9 +8,15 @@ export * as DurableObjectState from "./DurableObjectState";
 export * as DurableObjectWebSocket from "./DurableObjectWebSocket";
 export * as DurableObjectStorage from "./DurableObjectStorage";
 export * as Kv from "./Kv";
+export * as Queue from "./Queue";
+export * as QueueBinding from "./QueueBinding";
+export * as QueueDefinition from "./QueueDefinition";
 export * as Rpc from "./Rpc";
 export * as RpcDefinition from "./RpcDefinition";
 export * as ServiceBinding from "./ServiceBinding";
 export * as Worker from "./Worker";
 export * as WorkerDefinition from "./WorkerDefinition";
+export * as Workflow from "./Workflow";
+export * as WorkflowBinding from "./WorkflowBinding";
+export * as WorkflowDefinition from "./WorkflowDefinition";
 export { WorkerConfig, WorkerEnvironment, type WorkerEnv } from "./Environment";

package/src/internal/WorkerContext.ts

@@ -0,0 +1,83 @@
+import { Cause, Effect, Exit } from "effect";
+
+import type { WorkerContextService, WorkerContextWaitUntilOptions } from "../Worker";
+
+export type RunWaitUntilEffect = <A, E>(
+  effect: Effect.Effect<A, E, never>,
+) => Promise<Exit.Exit<A, unknown>>;
+
+const causeError = <E>(cause: Cause.Cause<E>) => new Error(Cause.pretty(cause));
+
+const failureHandler = <E, R>(
+  cause: Cause.Cause<E>,
+  options: WorkerContextWaitUntilOptions<E, R> | undefined,
+) =>
+  (
+    options?.onFailure?.(cause) ??
+    Effect.logError("WorkerContext.waitUntil failed", Cause.pretty(cause))
+  ).pipe(
+    Effect.catchCause((handlerCause) =>
+      Effect.logError(
+        "WorkerContext.waitUntil failure handler failed",
+        Cause.pretty(cause),
+        Cause.pretty(handlerCause),
+      ),
+    ),
+  );
+
+export const fromExecutionContext = (
+  ctx: globalThis.ExecutionContext,
+  runPromiseExit: RunWaitUntilEffect,
+): WorkerContextService => {
+  const schedule = <A, E, R, R2 = never>(
+    effect: Effect.Effect<A, E, R>,
+    options: WorkerContextWaitUntilOptions<E, R2> | undefined,
+    mode: "observe" | "propagate",
+  ) =>
+    Effect.context<R | R2>().pipe(
+      Effect.flatMap((context) =>
+        Effect.sync(() => {
+          const runHandler = (cause: Cause.Cause<E>) =>
+            runPromiseExit(
+              Effect.scoped(Effect.provideContext(failureHandler(cause, options), context)),
+            ).then((exit) => {
+              if (Exit.isFailure(exit)) {
+                console.error(
+                  "WorkerContext.waitUntil failure handler failed",
+                  Cause.pretty(exit.cause),
+                );
+              }
+            });
+
+          ctx.waitUntil(
+            runPromiseExit(Effect.scoped(Effect.provideContext(effect, context))).then(
+              async (exit) => {
+                if (Exit.isSuccess(exit)) {
+                  return;
+                }
+
+                await runHandler(exit.cause as Cause.Cause<E>);
+
+                if (mode === "propagate") {
+                  throw causeError(exit.cause as Cause.Cause<E>);
+                }
+              },
+            ),
+          );
+        }),
+      ),
+    );
+
+  return {
+    raw: ctx,
+    waitUntil: <A, E, R, R2 = never>(
+      effect: Effect.Effect<A, E, R>,
+      options?: WorkerContextWaitUntilOptions<E, R2>,
+    ) => schedule(effect, options, options?.mode ?? "observe"),
+    waitUntilPropagating: <A, E, R, R2 = never>(
+      effect: Effect.Effect<A, E, R>,
+      options?: Omit<WorkerContextWaitUntilOptions<E, R2>, "mode">,
+    ) => schedule(effect, options, "propagate"),
+    passThroughOnException: Effect.sync(() => ctx.passThroughOnException()),
+  };
+};