effect-cf 0.5.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 } from "effect";
+import { Context, Data, Effect, type Scope } from "effect";
 
 import * as Binding from "./Binding";
 import * as CloudflareRpc from "./Rpc";
@@ -74,86 +74,177 @@ type ServiceMethodSuccess<Api, Method extends keyof Api> = RpcInvocation.AsyncMe
   Api,
   Method
 >;
+type ServiceMethodCloudflareReturn<
+  Api,
+  Method extends keyof Api,
+> = RpcInvocation.AsyncMethodCloudflareReturn<Api, Method>;
 
-type ServiceCall<Self, Api> = <Method extends ServiceMethodKey<Api>>(
+type ServiceCall<R, Api> = <Method extends ServiceMethodKey<Api>>(
   method: Method,
   ...args: ServiceMethodArgs<Api, Method>
-) => Effect.Effect<ServiceMethodSuccess<Api, Method>, ServiceBindingRpcError, Self>;
+) => Effect.Effect<ServiceMethodSuccess<Api, Method>, ServiceBindingRpcError, R>;
 
-type DefinitionDirectMethods<Self, Definition extends WorkerDefinition.Definition.Any> = {
+type DefinitionDirectMethods<R, Definition extends WorkerDefinition.Definition.Any> = {
   readonly [Method in RpcDefinition.Definition.MethodNames<Definition>]: (
     ...args: RpcDefinition.Method.Args<Definition["methods"][Method]>
   ) => Effect.Effect<
     RpcDefinition.Method.Success<Definition["methods"][Method]>,
     ServiceBindingRpcError,
-    Self
+    R
   >;
 };
 
-type DirectMethods<Self, Definition> = Definition extends WorkerDefinition.Definition.Any
-  ? DefinitionDirectMethods<Self, Definition>
+type DirectMethods<R, Definition> = Definition extends WorkerDefinition.Definition.Any
+  ? DefinitionDirectMethods<R, 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
- * - direct RPC methods when `definition` is provided
- *
- * @example
- * ```ts
- * const Counter = WorkerDefinition.make("Counter", {
- *   increment: WorkerDefinition.method({
- *     args: [Schema.Number],
- *     success: Schema.Number,
- *   }),
- * });
- *
- * const CounterService = Counter.binding("COUNTER", { binding: "COUNTER" });
- *
- * const program = Effect.gen(function* () {
- *   const next = yield* CounterService.increment(1);
- *   return next;
- * });
- * ```
- */
-export const Service =
-  <Self, Api extends object = never>() =>
-  <
-    Id extends string,
-    const Definition extends WorkerDefinition.Definition.Any | undefined = undefined,
-  >(
-    id: Id,
-    definition: ServiceBindingDefinition<Definition>,
-  ) => {
-    type ServiceApi = ApiOrDefinition<Api, Definition>;
+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<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>;
+};
 
-    const tag = Binding.Service<Self>()(
-      id,
-      definition.binding,
-      (value): value is ServiceBindingClient<ServiceApi> =>
-        typeof value === "object" && value !== null && "fetch" in value,
-    );
+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>;
+};
 
-    const fetch = (input: RequestInfo | URL, init?: RequestInit) =>
-      Effect.gen(function* () {
-        const service = yield* tag;
+export const isServiceBindingClient = <Api extends object>(
+  value: unknown,
+): value is ServiceBindingClient<Api> =>
+  typeof value === "object" && value !== null && typeof Reflect.get(value, "fetch") === "function";
 
-        return yield* Effect.tryPromise({
-          try: () => service.fetch(input, init),
-          catch: (cause) => new ServiceBindingFetchError({ binding: definition.binding, cause }),
-        });
+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<ServiceApi>>(
+    const rpc = <Method extends ServiceMethodKey<Api>>(
       method: Method,
-      ...args: ServiceMethodArgs<ServiceApi, Method>
+      ...args: ServiceMethodArgs<Api, Method>
     ) =>
       Effect.gen(function* () {
-        const service = yield* tag;
         const methodName = String(method);
         const encodedArgs =
           definition.definition === undefined
@@ -176,7 +267,7 @@ export const Service =
         return yield* RpcInvocation.invokeRpcMethod(
           service,
           method,
-          encodedArgs as ServiceMethodArgs<ServiceApi, Method>,
+          encodedArgs as ServiceMethodArgs<Api, Method>,
           (cause) =>
             new ServiceBindingRpcError({
               binding: definition.binding,
@@ -186,13 +277,20 @@ export const Service =
         );
       });
 
-    const call = <Method extends ServiceMethodKey<ServiceApi>>(
-      method: Method,
-      ...args: ServiceMethodArgs<ServiceApi, Method>
+    const decodeSuccess = <Method extends ServiceMethodKey<Api>>(
+      methodName: string,
+      value: Awaited<ServiceMethodCloudflareReturn<Api, Method>>,
     ) =>
       Effect.gen(function* () {
-        const methodName = String(method);
-        const value = yield* CloudflareRpc.resolve(yield* rpc(method, ...args)).pipe(
+        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({
@@ -203,15 +301,16 @@ export const Service =
           ),
         );
 
-        if (definition.definition === undefined) {
-          return value as ServiceMethodSuccess<ServiceApi, Method>;
-        }
+        return decoded as ServiceMethodSuccess<Api, Method>;
+      });
 
-        const decoded = yield* RpcDefinition.decodeSuccess(
-          definition.definition,
-          methodName as RpcDefinition.Definition.MethodNames<NonNullable<Definition>>,
-          value,
-        ).pipe(
+    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({
@@ -222,7 +321,115 @@ export const Service =
           ),
         );
 
-        return decoded as ServiceMethodSuccess<ServiceApi, Method>;
+        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
+ * - `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
+ * ```ts
+ * const Counter = WorkerDefinition.make("Counter", {
+ *   increment: WorkerDefinition.method({
+ *     args: [Schema.Number],
+ *     success: Schema.Number,
+ *   }),
+ * });
+ *
+ * const CounterLive = Counter.layer({ binding: "COUNTER" });
+ *
+ * const program = Effect.gen(function* () {
+ *   const counter = yield* Counter;
+ *   const next = yield* counter.increment(1);
+ *   return next;
+ * });
+ * ```
+ */
+export const Service =
+  <Self, Api extends object = never>() =>
+  <
+    Id extends string,
+    const Definition extends WorkerDefinition.Definition.Any | undefined = undefined,
+  >(
+    id: Id,
+    definition: ServiceBindingDefinition<Definition>,
+  ) => {
+    type ServiceApi = ApiOrDefinition<Api, Definition>;
+
+    const tag = Binding.Service<Self>()(
+      id,
+      definition.binding,
+      (value): value is ServiceBindingClient<ServiceApi> => isServiceBindingClient(value),
+      makeClient<ServiceApi, Definition>(definition),
+    );
+
+    const fetch = (input: RequestInfo | URL, init?: RequestInit) =>
+      Effect.gen(function* () {
+        const service = yield* tag;
+        return yield* service.fetch(input, init);
+      });
+
+    const rpc = <Method extends ServiceMethodKey<ServiceApi>>(
+      method: Method,
+      ...args: ServiceMethodArgs<ServiceApi, Method>
+    ) =>
+      Effect.gen(function* () {
+        const service = yield* tag;
+        return yield* service.rpc(method, ...args);
+      });
+
+    const call = <Method extends ServiceMethodKey<ServiceApi>>(
+      method: Method,
+      ...args: ServiceMethodArgs<ServiceApi, Method>
+    ) =>
+      Effect.gen(function* () {
+        const service = yield* tag;
+        return yield* service.call(method, ...args);
       });
 
     const scopedCall = <Method extends ServiceMethodKey<ServiceApi>>(
@@ -230,8 +437,8 @@ export const Service =
       ...args: ServiceMethodArgs<ServiceApi, Method>
     ) =>
       Effect.gen(function* () {
-        const result = yield* rpc(method, ...args);
-        return yield* CloudflareRpc.scoped(result);
+        const service = yield* tag;
+        return yield* service.scopedCall(method, ...args);
       });
 
     const directMethods = makeDirectMethods<Self, ServiceApi, Definition>(
@@ -257,14 +464,14 @@ export const Service =
       };
   };
 
-const makeDirectMethods = <
-  Self,
+export const makeDirectMethods = <
+  R,
   Api,
   Definition extends WorkerDefinition.Definition.Any | undefined,
 >(
   rpcDefinition: Definition | undefined,
-  call: ServiceCall<Self, Api>,
-): DirectMethods<Self, Definition> => {
+  call: ServiceCall<R, Api>,
+): DirectMethods<R, Definition> => {
   const methods = {} as Record<string, unknown>;
 
   if (rpcDefinition !== undefined) {
@@ -274,5 +481,5 @@ const makeDirectMethods = <
     }
   }
 
-  return methods as DirectMethods<Self, Definition>;
+  return methods as DirectMethods<R, Definition>;
 };