effect-cf 0.6.0 → 0.8.0

package/src/ServiceBinding.ts

@@ -1,4 +1,4 @@
-import { Data, Effect, type Scope } from "effect";
+import { Context, Data, Effect, type Scope } from "effect";
 
 import * as Binding from "./Binding";
 import * as CloudflareRpc from "./Rpc";
@@ -74,6 +74,10 @@ type ServiceMethodSuccess<Api, Method extends keyof Api> = RpcInvocation.AsyncMe
   Api,
   Method
 >;
+type ServiceMethodCloudflareReturn<
+  Api,
+  Method extends keyof Api,
+> = RpcInvocation.AsyncMethodCloudflareReturn<Api, Method>;
 
 type ServiceCall<R, Api> = <Method extends ServiceMethodKey<Api>>(
   method: Method,
@@ -98,31 +102,274 @@ export type ServiceBindingEffectClient<
   Api extends object,
   Definition extends WorkerDefinition.Definition.Any | undefined = undefined,
 > = DirectMethods<never, Definition> & {
+  /**
+   * Forwards an HTTP request to the bound Worker service.
+   *
+   * Use this when the service binding is acting as an HTTP origin rather than a
+   * Cloudflare RPC target.
+   *
+   * @example
+   * ```ts
+   * import { Effect } from "effect";
+   *
+   * const program = Effect.gen(function* () {
+   *   const api = yield* ApiWorker;
+   *   return yield* api.fetch(new Request("https://internal.example/users"));
+   * });
+   * ```
+   */
   readonly fetch: (
     input: RequestInfo | URL,
     init?: RequestInit,
   ) => Effect.Effect<globalThis.Response, ServiceBindingFetchError>;
+  /**
+   * Invokes a Worker RPC method and returns Cloudflare's raw RPC result.
+   *
+   * This preserves Cloudflare RPC behavior such as promise-like pipelining and
+   * transferable / disposable result objects. It does not resolve the returned
+   * promise-like value and it does not decode definition-backed success schemas.
+   *
+   * Most application code should use {@link call} instead.
+   *
+   * @example
+   * ```ts
+   * import { Effect } from "effect";
+   *
+   * const program = Effect.gen(function* () {
+   *   const counter = yield* CounterService;
+   *
+   *   const result = yield* counter.rpc("increment", 41);
+   *   const value = yield* Effect.promise(() => result);
+   *
+   *   return value;
+   * });
+   * ```
+   */
   readonly rpc: <Method extends ServiceMethodKey<Api>>(
     method: Method,
     ...args: ServiceMethodArgs<Api, Method>
-  ) => Effect.Effect<ServiceMethodSuccess<Api, Method>, ServiceBindingRpcError>;
+  ) => Effect.Effect<ServiceMethodCloudflareReturn<Api, Method>, ServiceBindingRpcError>;
+  /**
+   * Invokes a Worker RPC method, resolves Cloudflare's RPC result, and decodes
+   * the success value when the binding was created from a definition.
+   *
+   * This is the normal choice when application code wants the final typed value.
+   *
+   * @example
+   * ```ts
+   * import { Effect } from "effect";
+   *
+   * const program = Effect.gen(function* () {
+   *   const counter = yield* CounterService;
+   *   const value = yield* counter.call("increment", 41);
+   *
+   *   return value;
+   * });
+   * ```
+   */
   readonly call: <Method extends ServiceMethodKey<Api>>(
     method: Method,
     ...args: ServiceMethodArgs<Api, Method>
   ) => Effect.Effect<ServiceMethodSuccess<Api, Method>, ServiceBindingRpcError>;
+  /**
+   * Invokes a Worker RPC method in the current `Scope`, resolves Cloudflare's RPC
+   * result, decodes definition-backed success values, and disposes the resolved
+   * result when the scope closes if it implements `Symbol.dispose`.
+   *
+   * Use this for RPC methods that return Cloudflare RPC resources or other
+   * disposable objects whose lifetime should be tied to an Effect scope.
+   *
+   * @example
+   * ```ts
+   * import { Effect } from "effect";
+   *
+   * const program = Effect.scoped(
+   *   Effect.gen(function* () {
+   *     const files = yield* FileService;
+   *     const handle = yield* files.scopedCall("open", "report.csv");
+   *
+   *     return yield* handle.read();
+   *   }),
+   * );
+   * ```
+   */
   readonly scopedCall: <Method extends ServiceMethodKey<Api>>(
     method: Method,
     ...args: ServiceMethodArgs<Api, Method>
   ) => Effect.Effect<Awaited<ServiceMethodSuccess<Api, Method>>, unknown, Scope.Scope>;
 };
 
+export type ServiceBindingStaticClient<
+  R,
+  Api extends object,
+  Definition extends WorkerDefinition.Definition.Any | undefined = undefined,
+> = DirectMethods<R, Definition> & {
+  readonly fetch: (
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ) => Effect.Effect<globalThis.Response, ServiceBindingFetchError, R>;
+  readonly rpc: <Method extends ServiceMethodKey<Api>>(
+    method: Method,
+    ...args: ServiceMethodArgs<Api, Method>
+  ) => Effect.Effect<ServiceMethodCloudflareReturn<Api, Method>, ServiceBindingRpcError, R>;
+  readonly call: <Method extends ServiceMethodKey<Api>>(
+    method: Method,
+    ...args: ServiceMethodArgs<Api, Method>
+  ) => Effect.Effect<ServiceMethodSuccess<Api, Method>, ServiceBindingRpcError, R>;
+  readonly scopedCall: <Method extends ServiceMethodKey<Api>>(
+    method: Method,
+    ...args: ServiceMethodArgs<Api, Method>
+  ) => Effect.Effect<Awaited<ServiceMethodSuccess<Api, Method>>, unknown, Scope.Scope | R>;
+};
+
+export const isServiceBindingClient = <Api extends object>(
+  value: unknown,
+): value is ServiceBindingClient<Api> =>
+  typeof value === "object" && value !== null && typeof Reflect.get(value, "fetch") === "function";
+
+export const makeClient = <
+  Api extends object,
+  const Definition extends WorkerDefinition.Definition.Any | undefined = undefined,
+>(
+  definition: ServiceBindingDefinition<Definition>,
+): ((service: ServiceBindingClient<Api>) => ServiceBindingEffectClient<Api, Definition>) => {
+  return (service: ServiceBindingClient<Api>) => {
+    const fetch = (input: RequestInfo | URL, init?: RequestInit) =>
+      Effect.tryPromise({
+        try: () => service.fetch(input, init),
+        catch: (cause) => new ServiceBindingFetchError({ binding: definition.binding, cause }),
+      });
+
+    const rpc = <Method extends ServiceMethodKey<Api>>(
+      method: Method,
+      ...args: ServiceMethodArgs<Api, Method>
+    ) =>
+      Effect.gen(function* () {
+        const methodName = String(method);
+        const encodedArgs =
+          definition.definition === undefined
+            ? args
+            : yield* RpcDefinition.encodeArgs(
+                definition.definition,
+                methodName as RpcDefinition.Definition.MethodNames<NonNullable<Definition>>,
+                args as never,
+              ).pipe(
+                Effect.mapError(
+                  (cause) =>
+                    new ServiceBindingRpcError({
+                      binding: definition.binding,
+                      method: methodName,
+                      cause,
+                    }),
+                ),
+              );
+
+        return yield* RpcInvocation.invokeRpcMethod(
+          service,
+          method,
+          encodedArgs as ServiceMethodArgs<Api, Method>,
+          (cause) =>
+            new ServiceBindingRpcError({
+              binding: definition.binding,
+              method: methodName,
+              cause,
+            }),
+        );
+      });
+
+    const decodeSuccess = <Method extends ServiceMethodKey<Api>>(
+      methodName: string,
+      value: Awaited<ServiceMethodCloudflareReturn<Api, Method>>,
+    ) =>
+      Effect.gen(function* () {
+        if (definition.definition === undefined) {
+          return value as ServiceMethodSuccess<Api, Method>;
+        }
+
+        const decoded = yield* RpcDefinition.decodeSuccess(
+          definition.definition,
+          methodName as RpcDefinition.Definition.MethodNames<NonNullable<Definition>>,
+          value,
+        ).pipe(
+          Effect.mapError(
+            (cause) =>
+              new ServiceBindingRpcError({
+                binding: definition.binding,
+                method: methodName,
+                cause,
+              }),
+          ),
+        );
+
+        return decoded as ServiceMethodSuccess<Api, Method>;
+      });
+
+    const call = <Method extends ServiceMethodKey<Api>>(
+      method: Method,
+      ...args: ServiceMethodArgs<Api, Method>
+    ) =>
+      Effect.gen(function* () {
+        const methodName = String(method);
+        const value = yield* CloudflareRpc.resolve(yield* rpc(method, ...args)).pipe(
+          Effect.mapError(
+            (cause) =>
+              new ServiceBindingRpcError({
+                binding: definition.binding,
+                method: methodName,
+                cause,
+              }),
+          ),
+        );
+
+        return yield* decodeSuccess<Method>(methodName, value);
+      });
+
+    const scopedCall = <Method extends ServiceMethodKey<Api>>(
+      method: Method,
+      ...args: ServiceMethodArgs<Api, Method>
+    ) =>
+      Effect.gen(function* () {
+        const methodName = String(method);
+        const result = yield* rpc(method, ...args);
+        const value = yield* CloudflareRpc.scoped(result);
+        return yield* decodeSuccess<Method>(methodName, value);
+      });
+
+    const directMethods = makeDirectMethods<never, Api, Definition>(definition.definition, call);
+
+    return Object.assign(directMethods, {
+      fetch,
+      rpc,
+      call,
+      scopedCall,
+    }) as ServiceBindingEffectClient<Api, Definition>;
+  };
+};
+
+export const layer = <
+  Self,
+  Api extends object,
+  const Definition extends WorkerDefinition.Definition.Any | undefined = undefined,
+>(
+  tag: Context.Service<Self, ServiceBindingEffectClient<Api, Definition>>,
+  definition: ServiceBindingDefinition<Definition>,
+) =>
+  Binding.layer(
+    tag,
+    definition.binding,
+    (value): value is ServiceBindingClient<Api> => isServiceBindingClient<Api>(value),
+    makeClient<Api, Definition>(definition),
+  );
+
 /**
  * Creates a typed Effect service for a Worker service binding.
  *
  * Returned value includes:
  * - a Context tag for dependency injection
  * - `fetch(...)` for raw HTTP forwarding
- * - `call(...)` for generic RPC invocation
+ * - `rpc(...)` for raw Cloudflare RPC results
+ * - `call(...)` for resolved and decoded RPC results
+ * - `scopedCall(...)` for scoped and decoded disposable RPC results
  * - direct RPC methods when `definition` is provided
  *
  * @example
@@ -134,10 +381,11 @@ export type ServiceBindingEffectClient<
  *   }),
  * });
  *
- * const CounterService = Counter.binding("COUNTER", { binding: "COUNTER" });
+ * const CounterLive = Counter.layer({ binding: "COUNTER" });
  *
  * const program = Effect.gen(function* () {
- *   const next = yield* CounterService.increment(1);
+ *   const counter = yield* Counter;
+ *   const next = yield* counter.increment(1);
  *   return next;
  * });
  * ```
@@ -153,119 +401,11 @@ export const Service =
   ) => {
     type ServiceApi = ApiOrDefinition<Api, Definition>;
 
-    const makeClient = (
-      service: ServiceBindingClient<ServiceApi>,
-    ): ServiceBindingEffectClient<ServiceApi, Definition> => {
-      const fetch = (input: RequestInfo | URL, init?: RequestInit) =>
-        Effect.tryPromise({
-          try: () => service.fetch(input, init),
-          catch: (cause) => new ServiceBindingFetchError({ binding: definition.binding, cause }),
-        });
-
-      const rpc = <Method extends ServiceMethodKey<ServiceApi>>(
-        method: Method,
-        ...args: ServiceMethodArgs<ServiceApi, Method>
-      ) =>
-        Effect.gen(function* () {
-          const methodName = String(method);
-          const encodedArgs =
-            definition.definition === undefined
-              ? args
-              : yield* RpcDefinition.encodeArgs(
-                  definition.definition,
-                  methodName as RpcDefinition.Definition.MethodNames<NonNullable<Definition>>,
-                  args as never,
-                ).pipe(
-                  Effect.mapError(
-                    (cause) =>
-                      new ServiceBindingRpcError({
-                        binding: definition.binding,
-                        method: methodName,
-                        cause,
-                      }),
-                  ),
-                );
-
-          return yield* RpcInvocation.invokeRpcMethod(
-            service,
-            method,
-            encodedArgs as ServiceMethodArgs<ServiceApi, Method>,
-            (cause) =>
-              new ServiceBindingRpcError({
-                binding: definition.binding,
-                method: methodName,
-                cause,
-              }),
-          );
-        });
-
-      const call = <Method extends ServiceMethodKey<ServiceApi>>(
-        method: Method,
-        ...args: ServiceMethodArgs<ServiceApi, Method>
-      ) =>
-        Effect.gen(function* () {
-          const methodName = String(method);
-          const value = yield* CloudflareRpc.resolve(yield* rpc(method, ...args)).pipe(
-            Effect.mapError(
-              (cause) =>
-                new ServiceBindingRpcError({
-                  binding: definition.binding,
-                  method: methodName,
-                  cause,
-                }),
-            ),
-          );
-
-          if (definition.definition === undefined) {
-            return value as ServiceMethodSuccess<ServiceApi, Method>;
-          }
-
-          const decoded = yield* RpcDefinition.decodeSuccess(
-            definition.definition,
-            methodName as RpcDefinition.Definition.MethodNames<NonNullable<Definition>>,
-            value,
-          ).pipe(
-            Effect.mapError(
-              (cause) =>
-                new ServiceBindingRpcError({
-                  binding: definition.binding,
-                  method: methodName,
-                  cause,
-                }),
-            ),
-          );
-
-          return decoded as ServiceMethodSuccess<ServiceApi, Method>;
-        });
-
-      const scopedCall = <Method extends ServiceMethodKey<ServiceApi>>(
-        method: Method,
-        ...args: ServiceMethodArgs<ServiceApi, Method>
-      ) =>
-        Effect.gen(function* () {
-          const result = yield* rpc(method, ...args);
-          return yield* CloudflareRpc.scoped(result);
-        });
-
-      const directMethods = makeDirectMethods<never, ServiceApi, Definition>(
-        definition.definition,
-        call,
-      );
-
-      return Object.assign(directMethods, {
-        fetch,
-        rpc,
-        call,
-        scopedCall,
-      }) as ServiceBindingEffectClient<ServiceApi, Definition>;
-    };
-
     const tag = Binding.Service<Self>()(
       id,
       definition.binding,
-      (value): value is ServiceBindingClient<ServiceApi> =>
-        typeof value === "object" && value !== null && "fetch" in value,
-      makeClient,
+      (value): value is ServiceBindingClient<ServiceApi> => isServiceBindingClient(value),
+      makeClient<ServiceApi, Definition>(definition),
     );
 
     const fetch = (input: RequestInfo | URL, init?: RequestInit) =>
@@ -324,7 +464,11 @@ export const Service =
       };
   };
 
-const makeDirectMethods = <R, Api, Definition extends WorkerDefinition.Definition.Any | undefined>(
+export const makeDirectMethods = <
+  R,
+  Api,
+  Definition extends WorkerDefinition.Definition.Any | undefined,
+>(
   rpcDefinition: Definition | undefined,
   call: ServiceCall<R, Api>,
 ): DirectMethods<R, Definition> => {

package/src/Worker.ts

@@ -1,10 +1,14 @@
 import { WorkerEntrypoint as CloudflareWorkerEntrypoint } from "cloudflare:workers";
 import { Cause, ConfigProvider, Context, Effect, Layer, ManagedRuntime, type Scope } from "effect";
+import type { Schema as S } from "effect";
 import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
 
+import type * as Binding from "./Binding";
 import { WorkerConfig, WorkerEnvironment, type WorkerEnv } from "./Environment";
 import { fromMessage, fromMessageBatch, type QueueHandler } from "./Queue";
+import type * as Rpc from "./Rpc";
 import type * as RpcDefinition from "./RpcDefinition";
+import type * as ServiceBinding from "./ServiceBinding";
 import * as WorkerDefinition from "./WorkerDefinition";
 import * as Entrypoint from "./internal/Entrypoint";
 import { fromExecutionContext, type RunWaitUntilEffect } from "./internal/WorkerContext";
@@ -282,38 +286,128 @@ export const makeFetchHandler = <ROut, LayerError, Env extends WorkerEnv = Worke
   };
 };
 
-export const Tag = WorkerDefinition.Tag;
+export type ServiceFreeSchema = S.Codec<any, any, never, never>;
 
-export const method = WorkerDefinition.method;
+export interface Method<
+  Args extends ReadonlyArray<ServiceFreeSchema> = ReadonlyArray<ServiceFreeSchema>,
+  Success extends ServiceFreeSchema = ServiceFreeSchema,
+> {
+  readonly args: Args;
+  readonly success: Success;
+}
+
+export namespace Method {
+  export type Any = Method<ReadonlyArray<ServiceFreeSchema>, ServiceFreeSchema>;
+
+  type ArgsFromSchemas<Args extends ReadonlyArray<ServiceFreeSchema>> = Args extends readonly []
+    ? []
+    : Args extends readonly [
+          infer Head extends ServiceFreeSchema,
+          ...infer Tail extends ReadonlyArray<ServiceFreeSchema>,
+        ]
+      ? [S.Schema.Type<Head>, ...ArgsFromSchemas<Tail>]
+      : Array<S.Schema.Type<Args[number]>>;
 
-export const implement = WorkerDefinition.implement;
+  export type Args<Self extends Any> = ArgsFromSchemas<Self["args"]>;
+
+  export type Success<Self extends Any> = S.Schema.Type<Self["success"]>;
+}
 
-export type Definition<
-  Id extends string = string,
-  Methods extends RpcDefinition.Methods = RpcDefinition.Methods,
-> = WorkerDefinition.Definition<Id, Methods>;
+export type Methods = Record<string, Method.Any>;
+
+export type NoReservedMethods<MethodsShape extends Methods> =
+  Extract<keyof MethodsShape, ReservedMethodName> extends never ? MethodsShape : never;
+
+export interface Definition<Id extends string = string, MethodsShape extends Methods = Methods> {
+  readonly id: Id;
+  readonly methods: MethodsShape;
+}
 
 export namespace Definition {
-  export type Any = WorkerDefinition.Definition.Any;
+  export type Any = Definition<string, Methods>;
 }
 
-export type ServerApi<Self extends WorkerDefinition.Definition.Any> =
-  WorkerDefinition.ServerApi<Self>;
+export type ServerApi<Self extends Definition.Any> = {
+  readonly [Key in keyof Self["methods"]]: (
+    ...args: Method.Args<Self["methods"][Key]>
+  ) => Promise<Method.Success<Self["methods"][Key]>>;
+};
+
+export type Api<Self extends Definition.Any> = Rpc.Provider<ServerApi<Self>, ReservedMethodName>;
 
-export type Api<Self extends WorkerDefinition.Definition.Any> = WorkerDefinition.Api<Self>;
+export type Handlers<ROut, Self extends Definition.Any> = {
+  readonly [Key in keyof Self["methods"]]: (
+    ...args: Method.Args<Self["methods"][Key]>
+  ) => WorkerRpcHandler<ROut, Method.Success<Self["methods"][Key]>>;
+};
 
-export type Handlers<
-  ROut,
-  Self extends WorkerDefinition.Definition.Any,
-> = WorkerDefinition.Handlers<ROut, Self>;
+export interface Options<ROut, Self extends Definition.Any> extends Omit<
+  WorkerOptions<ROut, Handlers<ROut, Self>>,
+  "rpc"
+> {
+  readonly rpc: Handlers<ROut, Self>;
+}
 
-export type Options<ROut, Self extends WorkerDefinition.Definition.Any> = WorkerDefinition.Options<
+export type LayerOptions = WorkerDefinition.LayerOptions;
+
+export type TagClass<Self, Id extends string, MethodsShape extends Methods> = Context.ServiceClass<
+  Self,
+  Id,
+  ServiceBinding.ServiceBindingEffectClient<
+    Api<Definition<Id, MethodsShape>>,
+    Definition<Id, MethodsShape>
+  >
+> &
+  ServiceBinding.ServiceBindingStaticClient<
+    Self,
+    Api<Definition<Id, MethodsShape>>,
+    Definition<Id, MethodsShape>
+  > & {
+    readonly id: Id;
+    readonly methods: MethodsShape;
+    readonly make: <ROut, LayerError>(
+      layer: Layer.Layer<ROut, LayerError, ExecutionContext | WorkerContext | WorkerEnvironment>,
+      options: Options<ROut, Definition<Id, MethodsShape>>,
+    ) => WorkerClass<Handlers<ROut, Definition<Id, MethodsShape>>, ROut>;
+    readonly layer: (
+      options: LayerOptions,
+    ) => Layer.Layer<
+      Self,
+      Binding.BindingNotFoundError | Binding.BindingValidationError,
+      WorkerEnvironment
+    >;
+  };
+
+export type TagFactory = <Self>() => <Id extends string, const MethodsShape extends Methods>(
+  id: Id,
+  methods: MethodsShape & NoReservedMethods<MethodsShape>,
+) => TagClass<Self, Id, MethodsShape>;
+
+export const Tag = WorkerDefinition.Tag as unknown as TagFactory;
+
+export const method = WorkerDefinition.method as {
+  <Success extends ServiceFreeSchema>(definition: {
+    readonly success: Success;
+  }): Method<readonly [], Success>;
+  <
+    const Args extends ReadonlyArray<ServiceFreeSchema>,
+    Success extends ServiceFreeSchema,
+  >(definition: {
+    readonly args: Args;
+    readonly success: Success;
+  }): Method<Args, Success>;
+};
+
+export const implement = WorkerDefinition.implement as unknown as <
   ROut,
-  Self
->;
+  const Self extends Definition.Any,
+>(
+  _definition: Self,
+  handlers: Handlers<ROut, Self>,
+) => Handlers<ROut, Self>;
 
 export type HandlerEffect<
   ROut,
-  Self extends WorkerDefinition.Definition.Any,
+  Self extends Definition.Any,
   Key extends keyof Self["methods"],
-> = WorkerDefinition.HandlerEffect<ROut, Self, Key>;
+> = WorkerRpcHandler<ROut, Method.Success<Self["methods"][Key]>>;