effect-cf 0.6.0 → 0.7.0

package/src/QueueDefinition.ts

@@ -1,5 +1,6 @@
-import { Effect, Schema as S, type Layer, type Scope } from "effect";
+import { Context, Effect, Schema as S, type Layer, type Scope } from "effect";
 
+import * as Binding from "./Binding";
 import type { WorkerEnvironment } from "./Environment";
 import * as QueueEntrypoint from "./Queue";
 import * as QueueBinding from "./QueueBinding";
@@ -19,15 +20,6 @@ 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<
@@ -44,6 +36,44 @@ export interface Options<ROut, Self extends Definition.Any> extends Omit<
   readonly rpc?: never;
 }
 
+export type LayerOptions = {
+  readonly binding: string;
+};
+
+export interface TagClass<
+  Self,
+  Id extends string,
+  Message extends RpcDefinition.ServiceFreeSchema,
+> extends Context.ServiceClass<Self, Id, QueueBinding.QueueBindingClient<Message>> {
+  readonly id: Id;
+  readonly message: Message;
+  readonly make: <ROut, LayerError>(
+    layer: Layer.Layer<ROut, LayerError, ExecutionContext | WorkerContext | WorkerEnvironment>,
+    options: Options<ROut, Definition<Id, Message>>,
+  ) => WorkerEntrypoint.WorkerClass<Record<never, never>, ROut>;
+  readonly layer: (
+    options: LayerOptions,
+  ) => Layer.Layer<
+    Self,
+    Binding.BindingNotFoundError | Binding.BindingValidationError,
+    WorkerEnvironment
+  >;
+  readonly send: (
+    message: S.Schema.Type<Message>,
+    options?: QueueBinding.QueueSendOptions,
+  ) => Effect.Effect<void, QueueBinding.QueueOperationError | S.SchemaError, Self>;
+  readonly sendBatch: (
+    messages: Iterable<QueueBinding.MessageSendRequest<S.Schema.Type<Message>>>,
+    options?: QueueBinding.QueueSendBatchOptions,
+  ) => Effect.Effect<void, QueueBinding.QueueOperationError | S.SchemaError, Self>;
+  readonly metrics: () => Effect.Effect<
+    QueueBinding.QueueMetrics,
+    QueueBinding.QueueOperationError,
+    Self
+  >;
+  readonly unsafeRaw: () => Effect.Effect<globalThis.Queue<S.Codec.Encoded<Message>>, never, Self>;
+}
+
 const makeDefinition = <Id extends string, Message extends RpcDefinition.ServiceFreeSchema>(
   id: Id,
   definition: { readonly message: Message },
@@ -63,49 +93,65 @@ const makeDefinition = <Id extends string, Message extends RpcDefinition.Service
         ...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 make = <Id extends string, Message extends RpcDefinition.ServiceFreeSchema>(
+  id: Id,
+  definition: { readonly message: Message },
+) => Tag<Definition<Id, Message>>()(id, definition);
 
 export const Tag =
-  <_Self>() =>
+  <Self>() =>
   <Id extends string, Message extends RpcDefinition.ServiceFreeSchema>(
     id: Id,
     definition: { readonly message: Message },
   ) => {
     const queueDefinition = makeDefinition(id, definition);
+    const tag = Context.Service<Self, QueueBinding.QueueBindingClient<Message>>()(id);
+
+    const layer = (binding: LayerOptions) =>
+      QueueBinding.layer(tag, {
+        ...binding,
+        message: definition.message,
+      });
+
+    const send = Effect.fnUntraced(function* (
+      message: S.Schema.Type<Message>,
+      options?: QueueBinding.QueueSendOptions,
+    ) {
+      const queue = yield* tag;
+      yield* queue.send(message, options);
+    });
 
-    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;
-    }
+    const sendBatch = Effect.fnUntraced(function* (
+      messages: Iterable<QueueBinding.MessageSendRequest<S.Schema.Type<Message>>>,
+      options?: QueueBinding.QueueSendBatchOptions,
+    ) {
+      const queue = yield* tag;
+      yield* queue.sendBatch(messages, options);
+    });
+
+    const metrics = Effect.fnUntraced(function* () {
+      const queue = yield* tag;
+      return yield* queue.metrics();
+    });
+
+    const unsafeRaw = Effect.fnUntraced(function* () {
+      const queue = yield* tag;
+      return yield* queue.unsafeRaw;
+    });
 
-    return QueueDefinitionClass as (abstract new () => object) & typeof queueDefinition;
+    return Object.assign(tag, {
+      id: queueDefinition.id,
+      message: queueDefinition.message,
+      make: queueDefinition.make,
+      layer,
+      send,
+      sendBatch,
+      metrics,
+      unsafeRaw,
+    }) as TagClass<Self, Id, Message>;
   };
 
 export const Queue = Tag;

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> => {