effect-orpc 0.1.4 → 0.2.0

package/README.md

@@ -318,6 +318,55 @@ runtime-agnostic.
 If you do not need framework-to-handler fiber propagation, you do not need the
 `/node` entrypoint at all.
 
+## Contract-First Usage
+
+Use `implementEffect(contract, runtime)` when you already have an oRPC contract
+and want to keep contract-first enforcement while adding Effect-native handlers.
+Use `makeEffectORPC(runtime, builder?)` when you want to build procedures
+directly from an oRPC builder.
+
+```ts
+import { Effect, ManagedRuntime } from "effect";
+import { eoc, implementEffect } from "effect-orpc";
+import z from "zod";
+
+class UsersRepo extends Effect.Service<UsersRepo>()("UsersRepo", {
+  accessors: true,
+  sync: () => ({
+    list: (amount: number) =>
+      Array.from({ length: amount }, (_, index) => `user-${index + 1}`),
+  }),
+}) {}
+
+const contract = {
+  users: {
+    list: eoc
+      .input(z.object({ amount: z.number().int().positive() }))
+      .output(z.array(z.string())),
+  },
+};
+
+const runtime = ManagedRuntime.make(UsersRepo.Default);
+const oe = implementEffect(contract, runtime);
+
+export const router = oe.router({
+  users: {
+    list: oe.users.list.effect(function* ({ input }) {
+      return yield* UsersRepo.list(input.amount);
+    }),
+  },
+});
+```
+
+Contract leaves keep the contract-defined input, output, and error surface.
+They add `.effect(...)` alongside existing implementer methods such as
+`.handler(...)` and `.use(...)`, but do not expose contract-changing builder
+methods like `.input(...)` or `.output(...)`.
+
+If your contract declares tagged Effect error classes, prefer `eoc.errors(...)`
+instead of raw `oc.errors(...)` so the error schema and metadata are derived
+directly from the `ORPCTaggedError` class.
+
 ## API Reference
 
 ### `makeEffectORPC(runtime, builder?)`
@@ -337,6 +386,52 @@ const effectOs = makeEffectORPC(runtime);
 const effectAuthedOs = makeEffectORPC(runtime, authedBuilder);
 ```
 
+### `implementEffect(contract, runtime)`
+
+Creates an Effect-aware contract implementer.
+
+- `contract` - An oRPC contract router built with `oc`
+- `runtime` - A `ManagedRuntime<R, E>` instance that provides services for Effect procedures
+
+Returns a contract-shaped implementer tree whose leaves support `.effect(...)`.
+
+```ts
+const oe = implementEffect(contract, runtime);
+
+const router = oe.router({
+  users: {
+    list: oe.users.list.effect(function* ({ input }) {
+      return yield* UsersRepo.list(input.amount);
+    }),
+  },
+});
+```
+
+### `eoc`
+
+An Effect-aware wrapper around oRPC's `oc` contract builder.
+
+Use it when you want contract definitions to accept `ORPCTaggedError` classes
+directly in `.errors(...)` without duplicating the error schema.
+
+```ts
+class UserNotFoundError extends ORPCTaggedError("UserNotFoundError", {
+  code: "NOT_FOUND",
+  schema: z.object({ userId: z.string() }),
+}) {}
+
+const contract = {
+  users: {
+    find: eoc
+      .errors({
+        NOT_FOUND: UserNotFoundError,
+      })
+      .input(z.object({ userId: z.string() }))
+      .output(z.object({ userId: z.string() })),
+  },
+};
+```
+
 ### `EffectBuilder`
 
 Wraps an oRPC Builder with Effect support. Available methods:

package/dist/index.js

@@ -2,14 +2,12 @@ import {
   getCurrentFiberRefs
 } from "./chunk-VOWRLWZZ.js";
 
+// src/contract.ts
+import { isContractProcedure as isContractProcedure2 } from "@orpc/contract";
+import { implement } from "@orpc/server";
+
 // src/effect-builder.ts
-import {
-  mergeMeta as mergeMeta2,
-  mergePrefix as mergePrefix2,
-  mergeRoute as mergeRoute2,
-  mergeTags,
-  ORPCError as ORPCError2
-} from "@orpc/contract";
+import { mergeMeta as mergeMeta2, mergePrefix as mergePrefix2, mergeRoute as mergeRoute2, mergeTags } from "@orpc/contract";
 import {
   addMiddleware as addMiddleware2,
   Builder,
@@ -17,7 +15,6 @@ import {
   fallbackConfig,
   lazy as lazy2
 } from "@orpc/server";
-import { Cause as Cause2, Effect, Exit, FiberRefs } from "effect";
 
 // src/effect-enhance-router.ts
 import {
@@ -323,6 +320,86 @@ function enhanceEffectRouter(router, options) {
   return enhanced;
 }
 
+// src/effect-runtime.ts
+import { ORPCError as ORPCError2 } from "@orpc/contract";
+import { Cause as Cause2, Effect, Exit, FiberRefs } from "effect";
+function toORPCErrorFromCause(cause) {
+  return Cause2.match(cause, {
+    onDie(defect) {
+      return new ORPCError2("INTERNAL_SERVER_ERROR", {
+        cause: defect
+      });
+    },
+    onFail(error) {
+      if (isORPCTaggedError(error)) {
+        return error.toORPCError();
+      }
+      if (error instanceof ORPCError2) {
+        return error;
+      }
+      return new ORPCError2("INTERNAL_SERVER_ERROR", {
+        cause: error
+      });
+    },
+    onInterrupt(fiberId) {
+      return new ORPCError2("INTERNAL_SERVER_ERROR", {
+        cause: new Error(`${fiberId} Interrupted`)
+      });
+    },
+    onSequential(left) {
+      return left;
+    },
+    onEmpty: new ORPCError2("INTERNAL_SERVER_ERROR", {
+      cause: new Error("Unknown error")
+    }),
+    onParallel(left) {
+      return left;
+    }
+  });
+}
+function createEffectProcedureHandler(options) {
+  const {
+    runtime,
+    effectErrorMap,
+    effectFn,
+    spanConfig,
+    defaultCaptureStackTrace
+  } = options;
+  return async (opts) => {
+    const effectOpts = {
+      context: opts.context,
+      input: opts.input,
+      path: opts.path,
+      procedure: opts.procedure,
+      signal: opts.signal,
+      lastEventId: opts.lastEventId,
+      errors: createEffectErrorConstructorMap(effectErrorMap)
+    };
+    const spanName = spanConfig?.name ?? opts.path.join(".");
+    const captureStackTrace = spanConfig?.captureStackTrace ?? defaultCaptureStackTrace;
+    const resolver = Effect.fnUntraced(effectFn);
+    const tracedEffect = Effect.withSpan(resolver(effectOpts), spanName, {
+      captureStackTrace
+    });
+    const parentFiberRefs = getCurrentFiberRefs();
+    const effectWithRefs = parentFiberRefs ? Effect.fiberIdWith(
+      (fiberId) => Effect.flatMap(
+        Effect.getFiberRefs,
+        (fiberRefs) => Effect.setFiberRefs(
+          FiberRefs.joinAs(fiberRefs, fiberId, parentFiberRefs)
+        ).pipe(Effect.andThen(tracedEffect))
+      )
+    ) : tracedEffect;
+    const exit = await runtime.runPromiseExit(effectWithRefs, {
+      signal: opts.signal
+    });
+    if (Exit.isFailure(exit)) {
+      throw toORPCErrorFromCause(exit.cause);
+    }
+    return exit.value;
+  };
+}
+
 // src/effect-builder.ts
 function addSpanStackTrace() {
   const ErrorConstructor = Error;
@@ -436,6 +513,14 @@ var EffectBuilder = class _EffectBuilder {
       inputSchema: initialInputSchema
     });
   }
+  /**
+   * Creates a middleware.
+   *
+   * @see {@link https://orpc.dev/docs/middleware Middleware Docs}
+   */
+  middleware(middleware) {
+    return decorateMiddleware2(middleware);
+  }
   /**
    * Adds type-safe custom errors.
    * Supports both traditional oRPC error definitions and ORPCTaggedError classes.
@@ -583,70 +668,13 @@ var EffectBuilder = class _EffectBuilder {
     return new EffectDecoratedProcedure({
       ...this["~effect"],
       handler: async (opts) => {
-        const effectOpts = {
-          context: opts.context,
-          input: opts.input,
-          path: opts.path,
-          procedure: opts.procedure,
-          signal: opts.signal,
-          lastEventId: opts.lastEventId,
-          errors: createEffectErrorConstructorMap(
-            this["~effect"].effectErrorMap
-          )
-        };
-        const spanName = spanConfig?.name ?? opts.path.join(".");
-        const captureStackTrace = spanConfig?.captureStackTrace ?? defaultCaptureStackTrace;
-        const resolver = Effect.fnUntraced(effectFn);
-        const tracedEffect = Effect.withSpan(resolver(effectOpts), spanName, {
-          captureStackTrace
-        });
-        const parentFiberRefs = getCurrentFiberRefs();
-        const effectWithRefs = parentFiberRefs ? Effect.fiberIdWith(
-          (fiberId) => Effect.flatMap(
-            Effect.getFiberRefs,
-            (fiberRefs) => Effect.setFiberRefs(
-              FiberRefs.joinAs(fiberRefs, fiberId, parentFiberRefs)
-            ).pipe(Effect.andThen(tracedEffect))
-          )
-        ) : tracedEffect;
-        const exit = await runtime.runPromiseExit(effectWithRefs, {
-          signal: opts.signal
-        });
-        if (Exit.isFailure(exit)) {
-          throw Cause2.match(exit.cause, {
-            onDie(defect) {
-              return new ORPCError2("INTERNAL_SERVER_ERROR", {
-                cause: defect
-              });
-            },
-            onFail(error) {
-              if (isORPCTaggedError(error)) {
-                return error.toORPCError();
-              }
-              if (error instanceof ORPCError2) {
-                return error;
-              }
-              return new ORPCError2("INTERNAL_SERVER_ERROR", {
-                cause: error
-              });
-            },
-            onInterrupt(fiberId) {
-              return new ORPCError2("INTERNAL_SERVER_ERROR", {
-                cause: new Error(`${fiberId} Interrupted`)
-              });
-            },
-            onSequential(left) {
-              return left;
-            },
-            onEmpty: new ORPCError2("INTERNAL_SERVER_ERROR", {
-              cause: new Error("Unknown error")
-            }),
-            onParallel(left) {
-              return left;
-            }
-          });
-        }
-        return exit.value;
+        return createEffectProcedureHandler({
+          runtime,
+          effectErrorMap: this["~effect"].effectErrorMap,
+          effectFn,
+          spanConfig,
+          defaultCaptureStackTrace
+        })(opts);
       }
     });
   }
@@ -719,6 +747,256 @@ function emptyBuilder() {
     dedupeLeadingMiddlewares: true
   });
 }
+
+// src/eoc.ts
+import { isContractProcedure, oc } from "@orpc/contract";
+var effectContractSymbol = /* @__PURE__ */ Symbol.for(
+  "@orpc/effect/contract"
+);
+function isWrappableContractBuilder(value) {
+  return typeof value === "object" && value !== null && "~orpc" in value;
+}
+function mergeEffectErrorMaps(left, right) {
+  if (!left) {
+    return right;
+  }
+  if (!right) {
+    return left;
+  }
+  return {
+    ...left,
+    ...right
+  };
+}
+function setEffectContractErrorMap(value, effectErrorMap) {
+  if (!effectErrorMap) {
+    return;
+  }
+  Object.defineProperty(value, effectContractSymbol, {
+    value: { errorMap: effectErrorMap },
+    enumerable: false,
+    configurable: true
+  });
+}
+function getEffectContractErrorMap(value) {
+  if (typeof value !== "object" || value === null) {
+    return void 0;
+  }
+  return value[effectContractSymbol]?.errorMap;
+}
+function applyEffectContractErrorMapToRouter(router, source, inheritedEffectErrorMap) {
+  const routerRecord = router;
+  const sourceRecord = source;
+  for (const key of Object.keys(routerRecord)) {
+    const routerValue = routerRecord[key];
+    const sourceValue = sourceRecord && typeof sourceRecord === "object" ? sourceRecord[key] : void 0;
+    if (!routerValue) {
+      continue;
+    }
+    if (isContractProcedure(routerValue)) {
+      const sourceEffectErrorMap = getEffectContractErrorMap(sourceValue);
+      setEffectContractErrorMap(
+        routerValue,
+        mergeEffectErrorMaps(inheritedEffectErrorMap, sourceEffectErrorMap)
+      );
+      continue;
+    }
+    if (typeof routerValue === "object") {
+      applyEffectContractErrorMapToRouter(
+        routerValue,
+        sourceValue,
+        inheritedEffectErrorMap
+      );
+    }
+  }
+}
+function wrapEffectContractBuilder(builder, inheritedEffectErrorMap) {
+  const currentEffectErrorMap = inheritedEffectErrorMap ?? getEffectContractErrorMap(builder);
+  if (typeof builder === "object" && builder !== null) {
+    setEffectContractErrorMap(builder, currentEffectErrorMap);
+  }
+  const proxy = new Proxy(builder, {
+    get(target, prop, receiver) {
+      if (prop === effectContractSymbol) {
+        return currentEffectErrorMap ? { errorMap: currentEffectErrorMap } : void 0;
+      }
+      if (prop === "errors") {
+        return (errors) => {
+          const nextEffectErrorMap = mergeEffectErrorMaps(
+            currentEffectErrorMap,
+            errors
+          );
+          return wrapEffectContractBuilder(
+            Reflect.apply(Reflect.get(target, prop, receiver), target, [
+              effectErrorMapToErrorMap(errors)
+            ]),
+            nextEffectErrorMap
+          );
+        };
+      }
+      if (prop === "router") {
+        return (router) => {
+          const result = Reflect.apply(
+            Reflect.get(target, prop, receiver),
+            target,
+            [router]
+          );
+          applyEffectContractErrorMapToRouter(
+            result,
+            router,
+            currentEffectErrorMap
+          );
+          return result;
+        };
+      }
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value !== "function") {
+        return value;
+      }
+      return (...args) => {
+        const result = Reflect.apply(value, target, args);
+        return isWrappableContractBuilder(result) ? wrapEffectContractBuilder(result, currentEffectErrorMap) : result;
+      };
+    }
+  });
+  setEffectContractErrorMap(proxy, currentEffectErrorMap);
+  return proxy;
+}
+var eoc = wrapEffectContractBuilder(
+  oc,
+  {}
+);
+
+// src/contract.ts
+var CONTRACT_HIDDEN_METHODS = /* @__PURE__ */ new Set([
+  "$config",
+  "$context",
+  "$input",
+  "$meta",
+  "$route",
+  "errors",
+  "input",
+  "lazy",
+  "meta",
+  "middleware",
+  "output",
+  "prefix",
+  "route",
+  "router",
+  "tag"
+]);
+function makeEnhanceOptions(runtime) {
+  return {
+    middlewares: [],
+    errorMap: {},
+    dedupeLeadingMiddlewares: true,
+    runtime
+  };
+}
+function wrapContractNode(contract, target, runtime) {
+  const cache = /* @__PURE__ */ new Map();
+  return new Proxy(target, {
+    get(currentTarget, prop, receiver) {
+      if (cache.has(prop)) {
+        return cache.get(prop);
+      }
+      if (isContractProcedure2(contract)) {
+        if (prop === "effect") {
+          const effect = (effectFn) => {
+            const effectErrorMap = getEffectContractErrorMap(contract) ?? currentTarget["~orpc"].errorMap;
+            return new EffectDecoratedProcedure({
+              ...currentTarget["~orpc"],
+              errorMap: effectErrorMapToErrorMap(effectErrorMap),
+              effectErrorMap,
+              runtime,
+              handler: createEffectProcedureHandler({
+                runtime,
+                effectErrorMap,
+                effectFn,
+                defaultCaptureStackTrace: addSpanStackTrace()
+              })
+            });
+          };
+          cache.set(prop, effect);
+          return effect;
+        }
+        if (prop === "use") {
+          const use = (...args) => wrapContractNode(
+            contract,
+            Reflect.apply(
+              Reflect.get(currentTarget, prop, currentTarget),
+              currentTarget,
+              args
+            ),
+            runtime
+          );
+          cache.set(prop, use);
+          return use;
+        }
+        if (CONTRACT_HIDDEN_METHODS.has(String(prop))) {
+          return void 0;
+        }
+      } else {
+        if (prop === "$context" || prop === "$config" || prop === "use") {
+          const wrappedMethod = (...args) => wrapContractNode(
+            contract,
+            Reflect.apply(
+              Reflect.get(currentTarget, prop, currentTarget),
+              currentTarget,
+              args
+            ),
+            runtime
+          );
+          cache.set(prop, wrappedMethod);
+          return wrappedMethod;
+        }
+        if (prop === "router" || prop === "lazy") {
+          const wrappedMethod = (...args) => enhanceEffectRouter(
+            Reflect.apply(
+              Reflect.get(currentTarget, prop, currentTarget),
+              currentTarget,
+              args
+            ),
+            makeEnhanceOptions(runtime)
+          );
+          cache.set(prop, wrappedMethod);
+          return wrappedMethod;
+        }
+        if (typeof prop === "string" && prop in contract) {
+          const child = wrapContractNode(
+            contract[prop],
+            Reflect.get(currentTarget, prop, receiver),
+            runtime
+          );
+          cache.set(prop, child);
+          return child;
+        }
+      }
+      const value = Reflect.get(currentTarget, prop, receiver);
+      return typeof value === "function" ? value.bind(currentTarget) : value;
+    },
+    has(currentTarget, prop) {
+      if (isContractProcedure2(contract)) {
+        if (prop === "effect") {
+          return true;
+        }
+        if (CONTRACT_HIDDEN_METHODS.has(String(prop))) {
+          return false;
+        }
+      } else if (typeof prop === "string" && prop in contract) {
+        return true;
+      }
+      return Reflect.has(currentTarget, prop);
+    }
+  });
+}
+function implementEffect(contract, runtime) {
+  return wrapContractNode(
+    contract,
+    implement(contract),
+    runtime
+  );
+}
 export {
   EffectBuilder,
   EffectDecoratedProcedure,
@@ -727,6 +1005,8 @@ export {
   addSpanStackTrace,
   createEffectErrorConstructorMap,
   effectErrorMapToErrorMap,
+  eoc,
+  implementEffect,
   isORPCTaggedError,
   isORPCTaggedErrorClass,
   makeEffectORPC,