effect-cf 0.1.0 → 0.3.0

package/src/QueueBinding.ts

@@ -0,0 +1,131 @@
+import { Data, Effect, Schema as S } from "effect";
+
+import * as Binding from "./Binding";
+import type * as RpcDefinition from "./RpcDefinition";
+
+const TypeId = "effect-cf/QueueBinding" as const;
+
+export type QueueSendOptions = globalThis.QueueSendOptions;
+export type QueueSendResponse = globalThis.QueueSendResponse;
+export type QueueSendBatchOptions = globalThis.QueueSendBatchOptions;
+export type QueueSendBatchResponse = globalThis.QueueSendBatchResponse;
+export type QueueMetrics = globalThis.QueueMetrics;
+export type MessageSendRequest<Body> = globalThis.MessageSendRequest<Body>;
+
+export interface QueueBindingDefinition<Message extends RpcDefinition.ServiceFreeSchema> {
+  /** Binding name as configured in `wrangler.jsonc`. */
+  readonly binding: string;
+  /** Codec used to encode messages before sending them to Cloudflare Queues. */
+  readonly message: Message;
+}
+
+declare const QueueServiceTypeId: unique symbol;
+
+/** Nominal service marker for Queue services created with {@link make}. */
+export interface QueueService<Id extends string, Message extends RpcDefinition.ServiceFreeSchema> {
+  readonly [QueueServiceTypeId]: {
+    readonly id: Id;
+    readonly message: S.Schema.Type<Message>;
+    readonly encodedMessage: S.Codec.Encoded<Message>;
+  };
+}
+
+export class QueueOperationError extends Data.TaggedError("QueueOperationError")<{
+  readonly binding: string;
+  readonly operation: string;
+  readonly cause: unknown;
+}> {}
+
+const queueError = (binding: string, operation: string, cause: unknown) =>
+  new QueueOperationError({ binding, operation, cause });
+
+const tryQueuePromise = <A>(
+  binding: string,
+  operation: string,
+  evaluate: () => Promise<A>,
+): Effect.Effect<A, QueueOperationError> =>
+  Effect.tryPromise({
+    try: evaluate,
+    catch: (cause) => queueError(binding, operation, cause),
+  });
+
+const isQueue = <Body>(value: unknown): value is globalThis.Queue<Body> => {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const resource = value as Record<string, unknown>;
+
+  return (
+    typeof resource.send === "function" &&
+    typeof resource.sendBatch === "function" &&
+    typeof resource.metrics === "function"
+  );
+};
+
+/** Creates a typed Queue binding service tag plus Effect helpers. */
+export const make = <Id extends string, Message extends RpcDefinition.ServiceFreeSchema>(
+  id: Id,
+  definition: QueueBindingDefinition<Message>,
+) => Service<QueueService<Id, Message>>()<Id, Message>(id, definition);
+
+/**
+ * Builds an Effect service around a Cloudflare Queue producer binding.
+ */
+export const Service =
+  <Self>() =>
+  <Id extends string, Message extends RpcDefinition.ServiceFreeSchema>(
+    id: Id,
+    definition: QueueBindingDefinition<Message>,
+  ) => {
+    type Body = S.Schema.Type<Message>;
+    type EncodedBody = S.Codec.Encoded<Message>;
+
+    const tag = Binding.Service<Self>()(
+      id,
+      definition.binding,
+      (value): value is globalThis.Queue<EncodedBody> => isQueue<EncodedBody>(value),
+    );
+
+    const encodeMessage = S.encodeEffect(definition.message);
+
+    const send = Effect.fnUntraced(function* (message: Body, options?: QueueSendOptions) {
+      const queue = yield* tag;
+      const encoded = yield* encodeMessage(message);
+
+      return yield* tryQueuePromise(definition.binding, "send", () => queue.send(encoded, options));
+    });
+
+    const sendBatch = Effect.fnUntraced(function* (
+      messages: Iterable<MessageSendRequest<Body>>,
+      options?: QueueSendBatchOptions,
+    ) {
+      const queue = yield* tag;
+      const encodedMessages: Array<MessageSendRequest<EncodedBody>> = [];
+
+      for (const message of messages) {
+        encodedMessages.push({
+          ...message,
+          body: yield* encodeMessage(message.body),
+        });
+      }
+
+      return yield* tryQueuePromise(definition.binding, "sendBatch", () =>
+        queue.sendBatch(encodedMessages, options),
+      );
+    });
+
+    const metrics = Effect.fnUntraced(function* () {
+      const queue = yield* tag;
+
+      return yield* tryQueuePromise(definition.binding, "metrics", () => queue.metrics());
+    });
+
+    return Object.assign(tag, {
+      [TypeId]: TypeId,
+      binding: definition.binding,
+      send,
+      sendBatch,
+      metrics,
+    });
+  };

package/src/QueueDefinition.ts

@@ -0,0 +1,129 @@
+import { Effect, Schema as S, type Layer, type Scope } from "effect";
+
+import type { WorkerEnvironment } from "./Environment";
+import * as QueueEntrypoint from "./Queue";
+import * as QueueBinding from "./QueueBinding";
+import type { ExecutionContext, WorkerContext } from "./Worker";
+import * as WorkerEntrypoint from "./Worker";
+import type * as RpcDefinition from "./RpcDefinition";
+
+export interface Definition<
+  Id extends string = string,
+  Message extends RpcDefinition.ServiceFreeSchema = RpcDefinition.ServiceFreeSchema,
+> {
+  readonly id: Id;
+  readonly message: Message;
+}
+
+export namespace Definition {
+  export type Any = Definition<string, 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> = (
+  batch: QueueEntrypoint.QueueBatch<S.Schema.Type<Self["message"]>>,
+) => Effect.Effect<
+  void,
+  unknown,
+  ExecutionContext | WorkerEntrypoint.WorkerContext | WorkerEnvironment | Scope.Scope | ROut
+>;
+
+export interface Options<ROut, Self extends Definition.Any> extends Omit<
+  WorkerEntrypoint.WorkerOptions<ROut, Record<never, never>>,
+  "queue" | "rpc"
+> {
+  readonly queue: Handler<ROut, Self>;
+  readonly rpc?: never;
+}
+
+const makeDefinition = <Id extends string, Message extends RpcDefinition.ServiceFreeSchema>(
+  id: Id,
+  definition: { readonly message: Message },
+) => {
+  type SelfDefinition = Definition<Id, Message>;
+  const queueDefinition: SelfDefinition = {
+    id,
+    message: definition.message,
+  };
+
+  return Object.assign(queueDefinition, {
+    make: <ROut, LayerError>(
+      layer: Layer.Layer<ROut, LayerError, ExecutionContext | WorkerContext | WorkerEnvironment>,
+      options: Options<ROut, SelfDefinition>,
+    ) =>
+      WorkerEntrypoint.make(layer, {
+        ...options,
+        queue: wrapHandler(queueDefinition, options.queue),
+      }),
+    Binding:
+      <Self>() =>
+      <BindingId extends string>(
+        bindingId: BindingId,
+        binding: Omit<QueueBinding.QueueBindingDefinition<Message>, "message">,
+      ) =>
+        QueueBinding.Service<Self>()<BindingId, Message>(bindingId, {
+          ...binding,
+          message: definition.message,
+        }),
+    binding: <BindingId extends string>(
+      bindingId: BindingId,
+      binding: Omit<QueueBinding.QueueBindingDefinition<Message>, "message">,
+    ) =>
+      QueueBinding.Service<BindingService<BindingId, SelfDefinition>>()<BindingId, Message>(
+        bindingId,
+        {
+          ...binding,
+          message: definition.message,
+        },
+      ),
+  });
+};
+
+export const make = makeDefinition;
+
+export const Tag =
+  <_Self>() =>
+  <Id extends string, Message extends RpcDefinition.ServiceFreeSchema>(
+    id: Id,
+    definition: { readonly message: Message },
+  ) => {
+    const queueDefinition = makeDefinition(id, definition);
+
+    abstract class QueueDefinitionClass {
+      static readonly id = queueDefinition.id;
+      static readonly message = queueDefinition.message;
+      static readonly make = queueDefinition.make;
+      static readonly Binding = queueDefinition.Binding;
+      static readonly binding = queueDefinition.binding;
+    }
+
+    return QueueDefinitionClass as (abstract new () => object) & typeof queueDefinition;
+  };
+
+export const Queue = Tag;
+
+const wrapHandler = <ROut, const Self extends Definition.Any>(
+  definition: Self,
+  handler: Handler<ROut, Self>,
+): QueueEntrypoint.QueueHandler<ROut> => {
+  const decodeBody = S.decodeUnknownEffect(definition.message);
+
+  return (batch) =>
+    Effect.gen(function* () {
+      const decoded = yield* QueueEntrypoint.decodeBatch(batch.raw, decodeBody);
+      yield* handler(decoded);
+    });
+};
+
+export const implement = <ROut, const Self extends Definition.Any>(
+  _definition: Self,
+  handler: Handler<ROut, Self>,
+): Handler<ROut, Self> => handler;

package/src/Worker.ts

@@ -1,20 +1,13 @@
 import { WorkerEntrypoint as CloudflareWorkerEntrypoint } from "cloudflare:workers";
-import {
-  Cause,
-  ConfigProvider,
-  Context,
-  Effect,
-  Exit,
-  Layer,
-  ManagedRuntime,
-  type Scope,
-} from "effect";
+import { Cause, ConfigProvider, Context, Effect, Layer, ManagedRuntime, type Scope } from "effect";
 import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
 
 import { WorkerConfig, WorkerEnvironment, type WorkerEnv } from "./Environment";
+import { fromMessage, fromMessageBatch, type QueueHandler } from "./Queue";
 import type * as RpcDefinition from "./RpcDefinition";
 import * as WorkerDefinition from "./WorkerDefinition";
 import * as Entrypoint from "./internal/Entrypoint";
+import { fromExecutionContext, type RunWaitUntilEffect } from "./internal/WorkerContext";
 
 export class ExecutionContext extends Context.Service<
   ExecutionContext,
@@ -22,6 +15,7 @@ export class ExecutionContext extends Context.Service<
 >()("effect-cf/ExecutionContext") {}
 
 export interface WorkerContextWaitUntilOptions<E, R> {
+  readonly mode?: "observe" | "propagate";
   readonly onFailure?: (cause: Cause.Cause<E>) => Effect.Effect<void, never, R>;
 }
 
@@ -31,6 +25,10 @@ export interface WorkerContextService {
     effect: Effect.Effect<A, E, R>,
     options?: WorkerContextWaitUntilOptions<E, R2>,
   ): Effect.Effect<void, never, R | R2>;
+  waitUntilPropagating<A, E, R, R2 = never>(
+    effect: Effect.Effect<A, E, R>,
+    options?: Omit<WorkerContextWaitUntilOptions<E, R2>, "mode">,
+  ): Effect.Effect<void, never, R | R2>;
   readonly passThroughOnException: Effect.Effect<void>;
 }
 
@@ -38,60 +36,6 @@ export class WorkerContext extends Context.Service<WorkerContext, WorkerContextS
   "effect-cf/WorkerContext",
 ) {}
 
-type RunWaitUntilEffect = <A, E>(
-  effect: Effect.Effect<A, E, never>,
-) => Promise<Exit.Exit<A, unknown>>;
-
-const fromExecutionContext = (
-  ctx: globalThis.ExecutionContext,
-  runPromiseExit: RunWaitUntilEffect,
-): WorkerContextService => ({
-  raw: ctx,
-  waitUntil: <A, E, R, R2 = never>(
-    effect: Effect.Effect<A, E, R>,
-    options?: WorkerContextWaitUntilOptions<E, R2>,
-  ) =>
-    Effect.context<R | R2>().pipe(
-      Effect.flatMap((context) =>
-        Effect.sync(() => {
-          const observed = Effect.exit(effect).pipe(
-            Effect.flatMap((exit) => {
-              if (Exit.isSuccess(exit)) {
-                return Effect.void;
-              }
-
-              const handleFailure =
-                options?.onFailure?.(exit.cause) ??
-                Effect.logError("WorkerContext.waitUntil failed", Cause.pretty(exit.cause));
-
-              return handleFailure.pipe(
-                Effect.catchCause((handlerCause) =>
-                  Effect.logError(
-                    "WorkerContext.waitUntil failure handler failed",
-                    Cause.pretty(exit.cause),
-                    Cause.pretty(handlerCause),
-                  ),
-                ),
-              );
-            }),
-          );
-
-          ctx.waitUntil(
-            runPromiseExit(Effect.scoped(Effect.provideContext(observed, context))).then((exit) => {
-              if (Exit.isFailure(exit)) {
-                console.error(
-                  "WorkerContext.waitUntil failure handler failed",
-                  Cause.pretty(exit.cause),
-                );
-              }
-            }),
-          );
-        }),
-      ),
-    ),
-  passThroughOnException: Effect.sync(() => ctx.passThroughOnException()),
-});
-
 export class NativeRequest extends Context.Service<NativeRequest, Request>()(
   "effect-cf/NativeRequest",
 ) {}
@@ -103,6 +47,12 @@ export type ReservedMethodName =
   | RpcDefinition.ReservedMethodName
   | "fetch"
   | "connect"
+  | "queue"
+  | "scheduled"
+  | "tail"
+  | "tailStream"
+  | "test"
+  | "trace"
   | "alarm"
   | "webSocketMessage"
   | "webSocketClose"
@@ -113,6 +63,12 @@ const reservedMethodNames = new Set<string>([
   "dup",
   "fetch",
   "connect",
+  "queue",
+  "scheduled",
+  "tail",
+  "tailStream",
+  "test",
+  "trace",
   "alarm",
   "webSocketMessage",
   "webSocketClose",
@@ -169,6 +125,7 @@ export type RpcHandlers<ROut, Api> = {
 
 export interface WorkerOptions<ROut, Rpc extends WorkerRpc<ROut>> {
   readonly fetch?: Effect.Effect<WorkerFetchSuccess, unknown, WorkerFetchContext<ROut>>;
+  readonly queue?: QueueHandler<ROut>;
   readonly rpc?: Rpc;
 }
 
@@ -181,6 +138,7 @@ export type WorkerClass<Rpc extends WorkerRpc<ROut>, ROut> = new (
   env: WorkerEnv,
 ) => CloudflareWorkerEntrypoint<WorkerEnv> & {
   fetch(request: Request): Promise<Response>;
+  queue(batch: globalThis.MessageBatch): Promise<void>;
 } & WorkerRpcShape<Rpc, ROut>;
 
 export interface FetchHandler<Env extends WorkerEnv = WorkerEnv> {
@@ -211,10 +169,29 @@ const renderFetchSuccess = <E, R>(
         ),
   );
 
-export const make = <ROut, LayerError, const Rpc extends WorkerRpc<ROut> = Record<never, never>>(
+const isWorkerOptions = <ROut, Rpc extends WorkerRpc<ROut>>(
+  options: WorkerOptions<ROut, Rpc> | WorkerHandler<ROut>,
+): options is WorkerOptions<ROut, Rpc> =>
+  typeof options === "object" &&
+  options !== null &&
+  ("fetch" in options || "queue" in options || "rpc" in options);
+
+export function make<ROut, LayerError>(
+  layer: Layer.Layer<ROut, LayerError, ExecutionContext | WorkerContext | WorkerEnvironment>,
+  fetch: WorkerHandler<ROut>,
+): WorkerClass<Record<never, never>, ROut>;
+export function make<ROut, LayerError, const Rpc extends WorkerRpc<ROut> = Record<never, never>>(
   layer: Layer.Layer<ROut, LayerError, ExecutionContext | WorkerContext | WorkerEnvironment>,
   options: WorkerOptions<ROut, Rpc>,
-): WorkerClass<Rpc, ROut> => {
+): WorkerClass<Rpc, ROut>;
+export function make<ROut, LayerError, const Rpc extends WorkerRpc<ROut> = Record<never, never>>(
+  layer: Layer.Layer<ROut, LayerError, ExecutionContext | WorkerContext | WorkerEnvironment>,
+  optionsOrFetch: WorkerOptions<ROut, Rpc> | WorkerHandler<ROut>,
+): WorkerClass<Rpc, ROut> {
+  const options = isWorkerOptions(optionsOrFetch)
+    ? optionsOrFetch
+    : ({ fetch: optionsOrFetch } as WorkerOptions<ROut, Rpc>);
+
   class EffectWorker extends CloudflareWorkerEntrypoint<WorkerEnv> {
     readonly runtime: ManagedRuntime.ManagedRuntime<RuntimeContext<ROut>, LayerError>;
 
@@ -222,7 +199,7 @@ export const make = <ROut, LayerError, const Rpc extends WorkerRpc<ROut> = Recor
       super(ctx, env);
 
       let runWaitUntilEffect: RunWaitUntilEffect = () =>
-        Promise.resolve(Exit.die(new Error("WorkerContext runtime is not initialized")));
+        Promise.reject(new Error("WorkerContext runtime is not initialized"));
 
       const services = Layer.mergeAll(
         Layer.succeed(ExecutionContext, ctx),
@@ -269,6 +246,18 @@ export const make = <ROut, LayerError, const Rpc extends WorkerRpc<ROut> = Recor
         >,
       );
     }
+
+    queue(batch: globalThis.MessageBatch): Promise<void> {
+      const queueHandler = options.queue;
+
+      if (queueHandler === undefined) {
+        return Promise.resolve();
+      }
+
+      const messages = batch.messages.map((message) => fromMessage(message, message.body));
+
+      return this[RunSymbol](queueHandler(fromMessageBatch(batch, messages)));
+    }
   }
 
   Entrypoint.defineEntrypointRpcMethods<EffectWorker>(
@@ -280,7 +269,7 @@ export const make = <ROut, LayerError, const Rpc extends WorkerRpc<ROut> = Recor
   );
 
   return Entrypoint.assumeEntrypointClass<WorkerClass<Rpc, ROut>>(EffectWorker);
-};
+}
 
 export const makeFetchHandler = <ROut, LayerError, Env extends WorkerEnv = WorkerEnv>(
   layer: Layer.Layer<ROut, LayerError, ExecutionContext | WorkerContext | WorkerEnvironment>,

package/src/WorkerDefinition.ts

@@ -28,6 +28,12 @@ const reservedMethodNames = new Set<string>([
   "dup",
   "fetch",
   "connect",
+  "queue",
+  "scheduled",
+  "tail",
+  "tailStream",
+  "test",
+  "trace",
   "alarm",
   "webSocketMessage",
   "webSocketClose",