effect-cf 0.0.1

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "effect-cf",
+  "version": "0.0.1",
+  "description": "Effect-native primitives for Cloudflare Workers and bindings.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danieljvdm/effect-cf.git",
+    "directory": "packages/effect-cf"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "prepublishOnly": "vp run build"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.15.0",
+    "@cloudflare/workers-types": "^4.20260421.1",
+    "@effect/vitest": "catalog:",
+    "effect": "catalog:",
+    "typescript": "^6.0.2",
+    "vite-plus": "0.1.19",
+    "vitest": "catalog:"
+  },
+  "peerDependencies": {
+    "effect": "^4.0.0-beta.57"
+  }
+}

package/src/Binding.ts

@@ -0,0 +1,70 @@
+import { Context, Data, Effect, Layer } from "effect";
+
+import { WorkerEnvironment } from "./Environment";
+import type { WorkerEnv } from "./Environment";
+
+/** Internal type id marker used by binding helper services. */
+export const TypeId = "effect-cf/Binding" as const;
+
+/** Error raised when a configured binding does not exist on `env`. */
+export class BindingNotFoundError extends Data.TaggedError("BindingNotFoundError")<{
+  readonly binding: string;
+}> {}
+
+/** Error raised when a binding exists but does not match the expected shape. */
+export class BindingValidationError extends Data.TaggedError("BindingValidationError")<{
+  readonly binding: string;
+}> {}
+
+const isPropertyTarget = (value: unknown): value is object =>
+  (typeof value === "object" || typeof value === "function") && value !== null;
+
+const getBinding = <Resource>(
+  env: WorkerEnv,
+  binding: string,
+  isResource: (value: unknown) => value is Resource,
+): Effect.Effect<Resource, BindingNotFoundError | BindingValidationError> =>
+  Effect.gen(function* () {
+    if (!isPropertyTarget(env)) {
+      return yield* Effect.fail(new BindingValidationError({ binding }));
+    }
+
+    const resource = Reflect.get(env, binding);
+
+    if (resource === undefined) {
+      return yield* Effect.fail(new BindingNotFoundError({ binding }));
+    }
+
+    if (!isResource(resource)) {
+      return yield* Effect.fail(new BindingValidationError({ binding }));
+    }
+
+    return resource;
+  });
+
+/**
+ * Creates a Context tag + layer for reading and validating a Cloudflare binding.
+ */
+export const Service =
+  <Self>() =>
+  <Id extends string, Resource>(
+    id: Id,
+    binding: string,
+    isResource: (value: unknown) => value is Resource,
+  ) => {
+    const tag = Context.Service<Self, Resource>()(id);
+
+    const layer = Layer.effect(
+      tag,
+      Effect.gen(function* () {
+        const env = yield* WorkerEnvironment;
+        return yield* getBinding(env, binding, isResource);
+      }),
+    );
+
+    return Object.assign(tag, {
+      [TypeId]: TypeId,
+      binding,
+      layer,
+    });
+  };

package/src/DurableObject.ts

@@ -0,0 +1,220 @@
+import { DurableObject as CloudflareDurableObject } from "cloudflare:workers";
+import { Effect, Layer, ManagedRuntime, type Scope } from "effect";
+
+import { NativeRequest } from "./Worker";
+import { WorkerEnvironment, type WorkerEnv } from "./Environment";
+import { DurableObjectState, fromDurableObjectState } from "./DurableObjectState";
+import * as DurableObjectDefinition from "./DurableObjectDefinition";
+import * as Entrypoint from "./internal/Entrypoint";
+
+const reservedMethodNames = new Set<string>([
+  "constructor",
+  "dup",
+  "fetch",
+  "alarm",
+  "webSocketMessage",
+  "webSocketClose",
+  "webSocketError",
+]);
+
+type RuntimeContext<ROut> = DurableObjectState | WorkerEnvironment | ROut;
+
+type HandlerContext<ROut> = RuntimeContext<ROut> | Scope.Scope;
+
+type FetchContext<ROut> = HandlerContext<ROut> | NativeRequest;
+
+const RunSymbol = Symbol.for("effect-cf/DurableObject/run");
+
+/**
+ * Effect type for Durable Object lifecycle and RPC handlers.
+ */
+export type DurableObjectHandler<ROut, A = unknown> = Effect.Effect<
+  A,
+  unknown,
+  HandlerContext<ROut>
+>;
+
+/**
+ * Shape of Durable Object RPC handlers passed to {@link make}.
+ */
+export type DurableObjectRpc<ROut> = Record<
+  string,
+  (...args: Array<any>) => DurableObjectHandler<ROut>
+>;
+
+export type DurableObjectRpcShape<Rpc extends DurableObjectRpc<ROut>, ROut> = {
+  readonly [Key in keyof Rpc]: Rpc[Key] extends (
+    ...args: infer Args
+  ) => Effect.Effect<infer A, unknown, HandlerContext<ROut>>
+    ? (...args: Args) => Promise<A>
+    : never;
+};
+
+export type RpcHandlers<ROut, Api> = {
+  readonly [Key in keyof Api as Key extends keyof CloudflareDurableObject<WorkerEnv>
+    ? never
+    : Key extends string
+      ? [Api[Key]] extends [never]
+        ? never
+        : Api[Key] extends (...args: Array<any>) => Promise<unknown>
+          ? Key
+          : never
+      : never]: Api[Key] extends (...args: infer Args) => Promise<infer A>
+    ? (...args: Args) => DurableObjectHandler<ROut, A>
+    : never;
+};
+
+/**
+ * Options for creating a Durable Object class backed by Effect handlers.
+ */
+export interface DurableObjectOptions<ROut, Rpc extends DurableObjectRpc<ROut>> {
+  /** Optional RPC methods exposed as Durable Object instance methods. */
+  readonly rpc?: Rpc;
+  /** Optional fetch handler for HTTP/WebSocket requests. */
+  readonly fetch?: Effect.Effect<Response, unknown, FetchContext<ROut>>;
+  readonly alarm?: (
+    alarmInfo?: globalThis.AlarmInvocationInfo,
+  ) => Effect.Effect<void, unknown, HandlerContext<ROut>>;
+  readonly webSocketMessage?: (
+    socket: WebSocket,
+    message: string | ArrayBuffer,
+  ) => Effect.Effect<void, unknown, HandlerContext<ROut>>;
+  readonly webSocketClose?: (
+    socket: WebSocket,
+    code: number,
+    reason: string,
+    wasClean: boolean,
+  ) => Effect.Effect<void, unknown, HandlerContext<ROut>>;
+  readonly webSocketError?: (
+    socket: WebSocket,
+    error: unknown,
+  ) => Effect.Effect<void, unknown, HandlerContext<ROut>>;
+}
+
+/**
+ * Cloudflare `DurableObject` constructor produced by {@link make}.
+ */
+export type DurableObjectClass<Rpc extends DurableObjectRpc<ROut>, ROut> = new (
+  state: globalThis.DurableObjectState,
+  env: WorkerEnv,
+) => CloudflareDurableObject<WorkerEnv> & DurableObjectRpcShape<Rpc, ROut>;
+
+/**
+ * Creates a Durable Object class backed by a single managed Effect runtime.
+ */
+export const make = <
+  ROut,
+  LayerError,
+  const Rpc extends DurableObjectRpc<ROut> = Record<never, never>,
+>(
+  layer: Layer.Layer<ROut, LayerError, DurableObjectState | WorkerEnvironment>,
+  options: DurableObjectOptions<ROut, Rpc> = {},
+): DurableObjectClass<Rpc, ROut> => {
+  class EffectDurableObject extends CloudflareDurableObject<WorkerEnv> {
+    readonly runtime: ManagedRuntime.ManagedRuntime<RuntimeContext<ROut>, LayerError>;
+
+    constructor(state: globalThis.DurableObjectState, env: WorkerEnv) {
+      super(state, env);
+
+      const services = Layer.mergeAll(
+        Layer.succeed(DurableObjectState, fromDurableObjectState(state)),
+        Layer.succeed(WorkerEnvironment, env),
+      );
+
+      const runtimeLayer = Entrypoint.provideEntrypointServices(layer, services);
+
+      this.runtime = ManagedRuntime.make(runtimeLayer);
+    }
+
+    [RunSymbol]<A, E>(effect: Effect.Effect<A, E, HandlerContext<ROut>>): Promise<A> {
+      return this.runtime.runPromise(Effect.scoped(effect));
+    }
+
+    fetch(request: Request): Promise<Response> {
+      const fetchHandler = options.fetch;
+
+      if (fetchHandler === undefined) {
+        return Promise.resolve(new Response("Not Found", { status: 404 }));
+      }
+
+      return this[RunSymbol](Effect.provideService(fetchHandler, NativeRequest, request));
+    }
+
+    alarm(alarmInfo?: globalThis.AlarmInvocationInfo): Promise<void> | void {
+      if (options.alarm !== undefined) {
+        return this[RunSymbol](options.alarm(alarmInfo));
+      }
+    }
+
+    webSocketMessage(socket: WebSocket, message: string | ArrayBuffer): Promise<void> | void {
+      if (options.webSocketMessage !== undefined) {
+        return this[RunSymbol](options.webSocketMessage(socket, message));
+      }
+    }
+
+    webSocketClose(
+      socket: WebSocket,
+      code: number,
+      reason: string,
+      wasClean: boolean,
+    ): Promise<void> | void {
+      if (options.webSocketClose !== undefined) {
+        return this[RunSymbol](options.webSocketClose(socket, code, reason, wasClean));
+      }
+    }
+
+    webSocketError(socket: WebSocket, error: unknown): Promise<void> | void {
+      if (options.webSocketError !== undefined) {
+        return this[RunSymbol](options.webSocketError(socket, error));
+      }
+    }
+  }
+
+  Entrypoint.defineEntrypointRpcMethods<EffectDurableObject>(
+    "Durable Object",
+    EffectDurableObject.prototype,
+    options.rpc,
+    reservedMethodNames,
+    (self, effect) => self[RunSymbol](effect),
+  );
+
+  return Entrypoint.assumeEntrypointClass<DurableObjectClass<Rpc, ROut>>(EffectDurableObject);
+};
+
+export const Tag = DurableObjectDefinition.Tag;
+
+export const method = DurableObjectDefinition.method;
+
+export const implement = DurableObjectDefinition.implement;
+
+export type Definition<
+  Id extends string = string,
+  Methods extends DurableObjectDefinition.Definition.Any["methods"] =
+    DurableObjectDefinition.Definition.Any["methods"],
+> = DurableObjectDefinition.Definition<Id, Methods>;
+
+export namespace Definition {
+  export type Any = DurableObjectDefinition.Definition.Any;
+}
+
+export type ServerApi<Self extends DurableObjectDefinition.Definition.Any> =
+  DurableObjectDefinition.ServerApi<Self>;
+
+export type Api<Self extends DurableObjectDefinition.Definition.Any> =
+  DurableObjectDefinition.Api<Self>;
+
+export type Handlers<
+  ROut,
+  Self extends DurableObjectDefinition.Definition.Any,
+> = DurableObjectDefinition.Handlers<ROut, Self>;
+
+export type Options<
+  ROut,
+  Self extends DurableObjectDefinition.Definition.Any,
+> = DurableObjectDefinition.Options<ROut, Self>;
+
+export type HandlerEffect<
+  ROut,
+  Self extends DurableObjectDefinition.Definition.Any,
+  Key extends keyof Self["methods"],
+> = DurableObjectDefinition.HandlerEffect<ROut, Self, Key>;

package/src/DurableObjectDefinition.ts

@@ -0,0 +1,214 @@
+import { Effect, type Layer } from "effect";
+
+import * as DurableObjectEntrypoint from "./DurableObject";
+import type { DurableObjectHandler } from "./DurableObject";
+import * as DurableObjectNamespace from "./DurableObjectNamespace";
+import type { DurableObjectState } from "./DurableObjectState";
+import * as RpcDefinition from "./RpcDefinition";
+import type { WorkerEnvironment } from "./Environment";
+
+/**
+ * RPC contract for a Durable Object class.
+ */
+export type Definition<
+  Id extends string = string,
+  Methods extends RpcDefinition.Methods = RpcDefinition.Methods,
+> = RpcDefinition.Definition<Id, Methods>;
+
+export namespace Definition {
+  export type Any = RpcDefinition.Definition.Any;
+}
+
+export type ReservedMethodName =
+  | RpcDefinition.ReservedMethodName
+  | "fetch"
+  | "alarm"
+  | "webSocketMessage"
+  | "webSocketClose"
+  | "webSocketError";
+
+const reservedMethodNames = new Set<string>([
+  "constructor",
+  "dup",
+  "fetch",
+  "alarm",
+  "webSocketMessage",
+  "webSocketClose",
+  "webSocketError",
+]);
+
+/**
+ * Promise-based client API derived from a Durable Object definition.
+ */
+export type ServerApi<Self extends Definition.Any> = RpcDefinition.Definition.ServerApi<Self>;
+
+export type Api<Self extends Definition.Any> = RpcDefinition.Definition.Api<
+  Self,
+  ReservedMethodName
+>;
+
+declare const NamespaceServiceTypeId: unique symbol;
+
+/**
+ * Nominal service marker for a Durable Object namespace binding.
+ */
+export interface NamespaceService<Id extends string, Self extends Definition.Any> {
+  readonly [NamespaceServiceTypeId]: {
+    readonly id: Id;
+    readonly definition: Self;
+  };
+}
+
+/**
+ * Effect handlers for each RPC method in a Durable Object definition.
+ */
+export type Handlers<ROut, Self extends Definition.Any> = {
+  readonly [Key in keyof Self["methods"]]: (
+    ...args: RpcDefinition.Method.Args<Self["methods"][Key]>
+  ) => DurableObjectHandler<ROut, RpcDefinition.Method.Success<Self["methods"][Key]>>;
+};
+
+type BoundaryHandlers<ROut, Self extends Definition.Any> = {
+  readonly [Key in keyof Self["methods"]]: (
+    ...args: Array<unknown>
+  ) => DurableObjectHandler<ROut, RpcDefinition.Method.EncodedSuccess<Self["methods"][Key]>>;
+};
+
+/**
+ * Durable Object constructor options for a specific RPC definition.
+ */
+export interface Options<ROut, Self extends Definition.Any> extends Omit<
+  DurableObjectEntrypoint.DurableObjectOptions<ROut, Handlers<ROut, Self>>,
+  "rpc"
+> {
+  readonly rpc: Handlers<ROut, Self>;
+}
+
+/**
+ * Defines a single RPC method schema in a Durable Object definition.
+ */
+export const method = RpcDefinition.method;
+
+/**
+ * Creates a Durable Object RPC definition plus implementation/binding helpers.
+ *
+ * @example
+ * ```ts
+ * const ChatRoom = DurableObjectDefinition.make("ChatRoom", {
+ *   postMessage: DurableObjectDefinition.method({
+ *     args: [Schema.String],
+ *     success: Schema.Void,
+ *   }),
+ * });
+ * ```
+ */
+const makeDefinition = <Id extends string, const MethodsShape extends RpcDefinition.Methods>(
+  id: Id,
+  methods: MethodsShape & RpcDefinition.NoReservedMethods<MethodsShape, ReservedMethodName>,
+) => {
+  type SelfDefinition = Definition<Id, MethodsShape>;
+  RpcDefinition.assertNoReservedMethods("Durable Object", methods, reservedMethodNames);
+  const definition: SelfDefinition = RpcDefinition.make(id, methods);
+
+  return Object.assign(definition, {
+    make: <ROut, LayerError>(
+      layer: Layer.Layer<ROut, LayerError, DurableObjectState | WorkerEnvironment>,
+      options: Options<ROut, SelfDefinition>,
+    ) =>
+      DurableObjectEntrypoint.make(layer, {
+        ...options,
+        rpc: wrapHandlers(definition, options.rpc),
+      }),
+    Namespace:
+      <Self>() =>
+      <BindingId extends string>(
+        bindingId: BindingId,
+        binding: Omit<
+          DurableObjectNamespace.DurableObjectNamespaceBindingDefinition<SelfDefinition>,
+          "definition"
+        >,
+      ) =>
+        DurableObjectNamespace.Service<Self, Api<SelfDefinition>>()<BindingId, SelfDefinition>(
+          bindingId,
+          {
+            ...binding,
+            definition,
+          },
+        ),
+    namespace: <BindingId extends string>(
+      bindingId: BindingId,
+      binding: Omit<
+        DurableObjectNamespace.DurableObjectNamespaceBindingDefinition<SelfDefinition>,
+        "definition"
+      >,
+    ) =>
+      DurableObjectNamespace.Service<
+        NamespaceService<BindingId, SelfDefinition>,
+        Api<SelfDefinition>
+      >()<BindingId, SelfDefinition>(bindingId, {
+        ...binding,
+        definition,
+      }),
+  });
+};
+
+export const make = makeDefinition;
+
+export const Tag =
+  <_Self>() =>
+  <Id extends string, const MethodsShape extends RpcDefinition.Methods>(
+    id: Id,
+    methods: MethodsShape & RpcDefinition.NoReservedMethods<MethodsShape, ReservedMethodName>,
+  ) => {
+    const definition = makeDefinition<Id, MethodsShape>(id, methods);
+
+    abstract class DurableObjectDefinitionClass {
+      static readonly id = definition.id;
+      static readonly methods = definition.methods;
+      static readonly make = definition.make;
+      static readonly Namespace = definition.Namespace;
+      static readonly namespace = definition.namespace;
+    }
+
+    return DurableObjectDefinitionClass as (abstract new () => object) & typeof definition;
+  };
+
+export const DurableObject = Tag;
+
+const wrapHandlers = <ROut, const Self extends Definition.Any>(
+  definition: Self,
+  handlers: Handlers<ROut, Self>,
+): BoundaryHandlers<ROut, Self> => {
+  const wrapped = {} as Record<string, unknown>;
+
+  for (const key of Object.keys(definition.methods) as Array<
+    RpcDefinition.Definition.MethodNames<Self>
+  >) {
+    const handler = handlers[key];
+    wrapped[key] = (...args: Array<unknown>) =>
+      Effect.gen(function* () {
+        const decodedArgs = yield* RpcDefinition.decodeArgs(definition, key, args);
+        const value = yield* handler(...decodedArgs);
+        return yield* RpcDefinition.encodeSuccess(definition, key, value);
+      });
+  }
+
+  return wrapped as BoundaryHandlers<ROut, Self>;
+};
+
+/**
+ * Helper for implementing handlers with the exact method shape of a definition.
+ */
+export const implement = <ROut, const Self extends Definition.Any>(
+  _definition: Self,
+  handlers: Handlers<ROut, Self>,
+): Handlers<ROut, Self> => handlers;
+
+/**
+ * Convenience alias for a single Durable Object RPC handler Effect.
+ */
+export type HandlerEffect<
+  ROut,
+  Self extends Definition.Any,
+  Key extends keyof Self["methods"],
+> = DurableObjectHandler<ROut, RpcDefinition.Method.Success<Self["methods"][Key]>>;