effect-cf 0.0.1

package/src/WorkerDefinition.ts

@@ -0,0 +1,206 @@
+import { Effect, type Layer } from "effect";
+
+import type { WorkerEnvironment } from "./Environment";
+import * as WorkerEntrypoint from "./Worker";
+import type { WorkerRpcHandler } from "./Worker";
+import * as RpcDefinition from "./RpcDefinition";
+import * as ServiceBinding from "./ServiceBinding";
+
+/**
+ * RPC contract for a Worker service.
+ *
+ * Create with {@link make} and reuse to type both worker implementations and
+ * service bindings in other workers.
+ */
+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 = WorkerEntrypoint.ReservedMethodName;
+
+const reservedMethodNames = new Set<string>([
+  "constructor",
+  "dup",
+  "fetch",
+  "connect",
+  "alarm",
+  "webSocketMessage",
+  "webSocketClose",
+  "webSocketError",
+]);
+
+/**
+ * Promise-based client API derived from a {@link 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 BindingServiceTypeId: unique symbol;
+
+/**
+ * Nominal service marker for a worker binding created with {@link make}.
+ */
+export interface BindingService<Id extends string, Self extends Definition.Any> {
+  readonly [BindingServiceTypeId]: {
+    readonly id: Id;
+    readonly definition: Self;
+  };
+}
+
+/**
+ * Effect handlers for each RPC method in a worker definition.
+ */
+export type Handlers<ROut, Self extends Definition.Any> = {
+  readonly [Key in keyof Self["methods"]]: (
+    ...args: RpcDefinition.Method.Args<Self["methods"][Key]>
+  ) => WorkerRpcHandler<ROut, RpcDefinition.Method.Success<Self["methods"][Key]>>;
+};
+
+type BoundaryHandlers<ROut, Self extends Definition.Any> = {
+  readonly [Key in keyof Self["methods"]]: (
+    ...args: Array<unknown>
+  ) => WorkerRpcHandler<ROut, RpcDefinition.Method.EncodedSuccess<Self["methods"][Key]>>;
+};
+
+/**
+ * Worker constructor options for a specific RPC definition.
+ */
+export interface Options<ROut, Self extends Definition.Any> extends Omit<
+  WorkerEntrypoint.WorkerOptions<ROut, Handlers<ROut, Self>>,
+  "rpc"
+> {
+  readonly rpc: Handlers<ROut, Self>;
+}
+
+/**
+ * Defines a single RPC method schema in a worker definition.
+ */
+export const method = RpcDefinition.method;
+
+/**
+ * Creates a typed worker RPC definition plus helpers for implementation and bindings.
+ *
+ * @example
+ * ```ts
+ * const CounterWorker = WorkerDefinition.make("CounterWorker", {
+ *   increment: WorkerDefinition.method({
+ *     args: [Schema.Number],
+ *     success: Schema.Number,
+ *   }),
+ * });
+ * ```
+ */
+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("Worker", methods, reservedMethodNames);
+  const definition: SelfDefinition = RpcDefinition.make(id, methods);
+
+  return Object.assign(definition, {
+    make: <ROut, LayerError>(
+      layer: Layer.Layer<
+        ROut,
+        LayerError,
+        WorkerEntrypoint.ExecutionContext | WorkerEntrypoint.WorkerContext | WorkerEnvironment
+      >,
+      options: Options<ROut, SelfDefinition>,
+    ) =>
+      WorkerEntrypoint.make(layer, {
+        ...options,
+        rpc: wrapHandlers(definition, options.rpc),
+      }),
+    Binding:
+      <Self>() =>
+      <BindingId extends string>(
+        bindingId: BindingId,
+        binding: Omit<ServiceBinding.ServiceBindingDefinition<SelfDefinition>, "definition">,
+      ) =>
+        ServiceBinding.Service<Self, Api<SelfDefinition>>()<BindingId, SelfDefinition>(bindingId, {
+          ...binding,
+          definition,
+        }),
+    binding: <BindingId extends string>(
+      bindingId: BindingId,
+      binding: Omit<ServiceBinding.ServiceBindingDefinition<SelfDefinition>, "definition">,
+    ) =>
+      ServiceBinding.Service<BindingService<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 WorkerDefinitionClass {
+      static readonly id = definition.id;
+      static readonly methods = definition.methods;
+      static readonly make = definition.make;
+      static readonly Binding = definition.Binding;
+      static readonly binding = definition.binding;
+    }
+
+    return WorkerDefinitionClass as (abstract new () => object) & typeof definition;
+  };
+
+export const Worker = 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 worker RPC handler Effect.
+ */
+export type HandlerEffect<
+  ROut,
+  Self extends Definition.Any,
+  Key extends keyof Self["methods"],
+> = WorkerRpcHandler<ROut, RpcDefinition.Method.Success<Self["methods"][Key]>>;

package/src/index.ts

@@ -0,0 +1,15 @@
+export * as Binding from "./Binding";
+export * as DurableObject from "./DurableObject";
+export * as DurableObjectDefinition from "./DurableObjectDefinition";
+export * as DurableObjectNamespace from "./DurableObjectNamespace";
+export * as DurableObjectRpcWebSocket from "./DurableObjectRpcWebSocket";
+export * as DurableObjectState from "./DurableObjectState";
+export * as DurableObjectWebSocket from "./DurableObjectWebSocket";
+export * as DurableObjectStorage from "./DurableObjectStorage";
+export * as Kv from "./Kv";
+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 { WorkerConfig, WorkerEnvironment, type WorkerEnv } from "./Environment";

package/src/internal/Entrypoint.ts

@@ -0,0 +1,40 @@
+import { Effect, Layer } from "effect";
+
+import * as RpcDefinition from "../RpcDefinition";
+
+type AnyArgs = Array<any>;
+type EntrypointRpcMethod = (...args: AnyArgs) => Effect.Effect<any, any, any>;
+
+export type EntrypointRpc = Record<string, EntrypointRpcMethod>;
+
+export const provideEntrypointServices = <ROut, LayerError, RIn>(
+  layer: Layer.Layer<ROut, LayerError, RIn>,
+  services: Layer.Layer<RIn, never, never>,
+): Layer.Layer<ROut | RIn, LayerError, never> =>
+  layer.pipe(Layer.provideMerge(services)) as Layer.Layer<ROut | RIn, LayerError, never>;
+
+export const defineEntrypointRpcMethods = <Self>(
+  target: string,
+  prototype: object,
+  rpc: EntrypointRpc | undefined,
+  reservedMethodNames: ReadonlySet<string>,
+  run: (self: Self, effect: Effect.Effect<any, any, any>) => Promise<unknown>,
+): void => {
+  const methods = rpc ?? {};
+
+  RpcDefinition.assertNoReservedMethods(target, methods, reservedMethodNames);
+
+  for (const [key, method] of Object.entries(methods)) {
+    Object.defineProperty(prototype, key, {
+      enumerable: true,
+      value(this: Self, ...args: AnyArgs) {
+        return run(
+          this,
+          Effect.suspend(() => method(...args)),
+        );
+      },
+    });
+  }
+};
+
+export const assumeEntrypointClass = <Class>(entrypoint: unknown): Class => entrypoint as Class;

package/src/internal/RpcInvocation.ts

@@ -0,0 +1,73 @@
+import { Effect } from "effect";
+
+import type * as CloudflareRpc from "../Rpc";
+
+type AnyArgs = Array<any>;
+
+export type AsyncMethodKey<Api> = {
+  [Key in keyof Api]-?: Key extends string
+    ? Api[Key] extends (...args: AnyArgs) => Promise<unknown>
+      ? Key
+      : never
+    : never;
+}[keyof Api];
+
+export type AsyncMethodArgs<Api, Method extends keyof Api> = Api[Method] extends (
+  ...args: infer Args
+) => Promise<unknown>
+  ? Args
+  : never;
+
+export type AsyncMethodSuccess<Api, Method extends keyof Api> = Api[Method] extends (
+  ...args: AnyArgs
+) => Promise<infer A>
+  ? A
+  : never;
+
+export type AsyncMethodCloudflareReturn<Api, Method extends keyof Api> = CloudflareRpc.Result<
+  AsyncMethodSuccess<Api, Method>
+>;
+
+const isPropertyTarget = (value: unknown): value is object =>
+  (typeof value === "object" || typeof value === "function") && value !== null;
+
+export const lookupRpcMethod = <Api, Method extends AsyncMethodKey<Api>, Error>(
+  target: unknown,
+  method: Method,
+  makeError: (cause: unknown) => Error,
+): Effect.Effect<
+  (...args: AsyncMethodArgs<Api, Method>) => AsyncMethodCloudflareReturn<Api, Method>,
+  Error
+> =>
+  Effect.try({
+    try: () => {
+      if (!isPropertyTarget(target)) {
+        throw new TypeError(`RPC target is not object-like`);
+      }
+
+      const value = Reflect.get(target, method);
+
+      if (typeof value !== "function") {
+        throw new TypeError(`RPC method "${String(method)}" is not callable`);
+      }
+
+      return ((...args: AsyncMethodArgs<Api, Method>) => Reflect.apply(value, target, args)) as (
+        ...args: AsyncMethodArgs<Api, Method>
+      ) => AsyncMethodCloudflareReturn<Api, Method>;
+    },
+    catch: makeError,
+  });
+
+export const invokeRpcMethod = <Api, Method extends AsyncMethodKey<Api>, Error>(
+  target: unknown,
+  method: Method,
+  args: AsyncMethodArgs<Api, Method>,
+  makeError: (cause: unknown) => Error,
+): Effect.Effect<AsyncMethodCloudflareReturn<Api, Method>, Error> =>
+  Effect.gen(function* () {
+    const fn = yield* lookupRpcMethod<Api, Method, Error>(target, method, makeError);
+    return yield* Effect.try({
+      try: () => fn(...args),
+      catch: makeError,
+    });
+  });