effect-orpc 1.0.0-effect-v4.2 → 1.0.0-effect-v4.4

package/README.md

@@ -0,0 +1,495 @@
+# effect-orpc
+
+A type-safe integration between [oRPC](https://orpc.dev/) and [Effect](https://effect.website/), enabling Effect-native procedures with full service injection support, OpenTelemetry tracing support and typesafe Effect errors support.
+
+Inspired by [effect-trpc](https://github.com/mikearnaldi/effect-trpc).
+
+## Features
+
+- **Effect-native procedures** - Write oRPC procedures using generators with `yield*` syntax
+- **Type-safe service injection** - Use `ManagedRuntime<R>` to provide services to procedures with compile-time safety
+- **Tagged errors** - Create Effect-native error classes with `ORPCTaggedError` that integrate with oRPC's error handling
+- **Full oRPC compatibility** - Mix Effect procedures with standard oRPC procedures in the same router
+- **Telemetry support with automatic tracing** - Procedures are automatically traced with OpenTelemetry-compatible spans. Customize span names with `.traced()`.
+- **Builder pattern preserved** - oRPC builder methods (`.errors()`, `.meta()`, `.route()`, `.input()`, `.output()`, `.use()`) work seamlessly
+
+## Installation
+
+```bash
+npm install effect-orpc
+# or
+pnpm add effect-orpc
+# or
+bun add effect-orpc
+```
+
+Runnable demos live in the repository's `examples/` directory.
+
+## Demo
+
+```ts
+import { os } from "@orpc/server";
+import { Effect, Layer, ManagedRuntime, Context } from "effect";
+import { makeEffectORPC, ORPCTaggedError } from "effect-orpc";
+
+interface User {
+  id: number;
+  name: string;
+}
+
+let users: User[] = [
+  { id: 1, name: "John Doe" },
+  { id: 2, name: "Jane Doe" },
+  { id: 3, name: "James Dane" },
+];
+
+// Authenticated os with initial context & errors set
+const authedOs = os
+  .errors({ UNAUTHORIZED: { status: 401 } })
+  .$context<{ userId?: number }>()
+  .use(({ context, errors, next }) => {
+    if (context.userId === undefined) throw errors.UNAUTHORIZED();
+    return next({ context: { ...context, userId: context.userId } });
+  });
+
+// Define your services
+class UsersRepo extends Context.Service<
+  UsersRepo,
+  {
+    readonly get: (id: number) => User | undefined;
+  }
+>()("UsersRepo") {
+  static readonly layer = Layer.succeed(this, {
+    get: (id: number) => users.find((u) => u.id === id),
+  });
+}
+
+// Special yieldable oRPC error class
+class UserNotFoundError extends ORPCTaggedError("UserNotFoundError", {
+  status: 404,
+}) {}
+
+// Create runtime with your services
+const runtime = ManagedRuntime.make(UsersRepo.layer);
+// Create Effect-aware oRPC builder from an other (optional) base oRPC builder and provide tagged errors
+const effectOs = makeEffectORPC(runtime, authedOs).errors({
+  UserNotFoundError,
+});
+
+// Create the router with mixed procedures
+export const router = {
+  health: os.handler(() => "ok"),
+  users: {
+    me: effectOs.effect(function* ({ context: { userId } }) {
+      const usersRepo = yield* UsersRepo;
+      const user = usersRepo.get(userId);
+      if (!user) {
+        return yield* new UserNotFoundError();
+      }
+      return user;
+    }),
+  },
+};
+
+export type Router = typeof router;
+```
+
+## Type Safety
+
+The wrapper enforces that Effect procedures only use services provided by the `ManagedRuntime`. If you try to use a service that isn't in the runtime, you'll get a compile-time error:
+
+```ts
+import { Effect, Layer, ManagedRuntime, Context } from "effect";
+import { makeEffectORPC } from "effect-orpc";
+
+class ProvidedService extends Context.Service<
+  ProvidedService,
+  {
+    readonly doSomething: () => Effect.Effect<string>;
+  }
+>()("ProvidedService") {}
+
+class MissingService extends Context.Service<
+  MissingService,
+  {
+    readonly doSomething: () => Effect.Effect<string>;
+  }
+>()("MissingService") {}
+
+const runtime = ManagedRuntime.make(
+  Layer.succeed(ProvidedService, {
+    doSomething: () => Effect.succeed("ok"),
+  }),
+);
+
+const effectOs = makeEffectORPC(runtime);
+
+// ✅ This compiles - ProvidedService is in the runtime
+const works = effectOs.effect(function* () {
+  const service = yield* ProvidedService;
+  return yield* service.doSomething();
+});
+
+// ❌ This fails to compile - MissingService is not in the runtime
+const fails = effectOs.effect(function* () {
+  const service = yield* MissingService; // Type error!
+  return yield* service.doSomething();
+});
+```
+
+## Error Handling
+
+`ORPCTaggedError` lets you create Effect-native error classes that integrate seamlessly with oRPC. These errors:
+
+- Can be yielded in Effect generators (`yield* new MyError()` or `yield* Effect.fail(errors.MyError)`)
+- Can be used in Effect builder's `.errors()` maps for type-safe error handling alongside regular oRPC errors
+- Automatically convert to ORPCError when thrown
+
+Make sure the tagged error class is passed to the effect `.errors()` to be able to yield the error class directly and make the client recognize it as defined.
+
+```ts
+const getUser = effectOs
+  // Mixed error maps
+  .errors({
+    // Regular oRPC error
+    NOT_FOUND: {
+      message: "User not found",
+      data: z.object({ id: z.string() }),
+    },
+    // Effect oRPC tagged error
+    UserNotFoundError,
+    // Note: The key of an oRPC error is not used as the error code
+    // So the following will only change the key of the error when accessing it
+    // from the errors object passed to the handler, but not the actual error code itself.
+    // To change the error's code, please see the next section on creating tagged errors.
+    USER_NOT_FOUND: UserNotFoundError,
+    // ^^^ same code as the `UserNotFoundError` error key, defined at the class level
+  })
+  .effect(function* ({ input, errors }) {
+    const user = yield* UsersRepo.findById(input.id);
+    if (!user) {
+      return yield* new UserNotFoundError();
+      // or return `yield* Effect.fail(errors.USER_NOT_FOUND())`
+    }
+    return user;
+  });
+```
+
+### Creating Tagged Errors
+
+```ts
+import { ORPCTaggedError } from "effect-orpc";
+
+// Basic tagged error - code defaults to 'USER_NOT_FOUND' (CONSTANT_CASE of tag)
+class UserNotFound extends ORPCTaggedError("UserNotFound") {}
+
+// With explicit code
+class NotFound extends ORPCTaggedError("NotFound", { code: "NOT_FOUND" }) {}
+
+// With default options (code defaults to 'VALIDATION_ERROR') (CONSTANT_CASE of tag)
+class ValidationError extends ORPCTaggedError("ValidationError", {
+  status: 400,
+  message: "Validation failed",
+}) {}
+
+// With all options
+class ForbiddenError extends ORPCTaggedError("ForbiddenError", {
+  code: "FORBIDDEN",
+  status: 403,
+  message: "Access denied",
+  schema: z.object({
+    reason: z.string(),
+  }),
+}) {}
+
+// With typed data using Standard Schema
+class UserNotFoundWithData extends ORPCTaggedError("UserNotFoundWithData", {
+  schema: z.object({ userId: z.string() }),
+}) {}
+```
+
+## Traceable Spans
+
+All Effect procedures are automatically traced with `Effect.withSpan`. By default, the span name is the procedure path (e.g., `users.getUser`):
+
+```ts
+// Router structure determines span names automatically
+const router = {
+  users: {
+    // Span name: "users.get"
+    get: effectOs.input(z.object({ id: z.string() })).effect(function* ({
+      input,
+    }) {
+      const userService = yield* UserService;
+      return yield* userService.findById(input.id);
+    }),
+    // Span name: "users.create"
+    create: effectOs.input(z.object({ name: z.string() })).effect(function* ({
+      input,
+    }) {
+      const userService = yield* UserService;
+      return yield* userService.create(input.name);
+    }),
+  },
+};
+```
+
+Use `.traced()` to override the default span name:
+
+```ts
+const getUser = effectOs
+  .input(z.object({ id: z.string() }))
+  .traced("custom.span.name") // Override the default path-based name
+  .effect(function* ({ input }) {
+    const userService = yield* UserService;
+    return yield* userService.findById(input.id);
+  });
+```
+
+### Enabling OpenTelemetry
+
+To enable tracing, include the OpenTelemetry layer in your runtime:
+
+```ts
+import { NodeSdk } from "@effect/opentelemetry";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
+
+const TracingLive = NodeSdk.layer(
+  Effect.sync(() => ({
+    resource: { serviceName: "my-service" },
+    spanProcessor: [new SimpleSpanProcessor(new OTLPTraceExporter())],
+  })),
+);
+
+const AppLive = Layer.mergeAll(UserServiceLive, TracingLive);
+
+const runtime = ManagedRuntime.make(AppLive);
+const effectOs = makeEffectORPC(runtime);
+```
+
+### Error Stack Traces
+
+When an Effect procedure fails, the span includes a properly formatted stack trace pointing to the definition site:
+
+```
+MyCustomError: Something went wrong
+    at <anonymous> (/app/src/procedures.ts:42:28)
+    at users.getById (/app/src/procedures.ts:41:35)
+```
+
+## Request-Scoped Fiber Context
+
+If you run `effect-orpc` inside a framework such as Hono, the handler executes
+through the runtime boundary and will not automatically inherit request-local
+`FiberRef` state from outer middleware.
+
+To preserve request-scoped logs, tracing annotations, and
+other fiber-local state, wrap the framework continuation with `withFiberContext` from
+`effect-orpc/node`.
+
+```ts
+import { Hono } from "hono";
+import { Effect, ManagedRuntime } from "effect";
+import { makeEffectORPC } from "effect-orpc";
+import { withFiberContext } from "effect-orpc/node";
+
+const runtime = ManagedRuntime.make(AppLive);
+const effectOs = makeEffectORPC(runtime);
+const app = new Hono();
+
+app.use("*", async (c, next) => {
+  await Effect.runPromise(
+    Effect.gen(function* () {
+      yield* Effect.annotateLogsScoped({
+        requestId: c.get("requestId"),
+      });
+
+      yield* withFiberContext(() => next());
+    }),
+  );
+});
+```
+
+When a captured fiber context and the `ManagedRuntime` both provide the same
+service, `effect-orpc` prioritizes the captured context. The runtime is treated
+as the application-wide base layer, while `withFiberContext` preserves the
+more specific request-scoped values from outer middleware. This prevents
+request-local references such as request IDs, logging annotations, tracing
+context, or scoped overrides from being replaced by runtime defaults when the
+handler crosses the runtime boundary.
+
+The reason for the separate `/node` entrypoint is that `withFiberContext` relies
+on Node/Bun's `AsyncLocalStorage` from `node:async_hooks` to carry Effect
+`FiberRef` state across framework async boundaries. The main package stays
+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?)`
+
+Creates an Effect-aware procedure builder.
+
+- `runtime` - A `ManagedRuntime<R, E>` instance that provides services for Effect procedures
+- `builder` (optional) - An oRPC Builder instance to wrap. Defaults to `os` from `@orpc/server`
+
+Returns an `EffectBuilder` instance.
+
+```ts
+// With default builder
+const effectOs = makeEffectORPC(runtime);
+
+// With customized builder
+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:
+
+| Method              | Description                                                                     |
+| ------------------- | ------------------------------------------------------------------------------- |
+| `.$config(config)`  | Set or override the builder config                                              |
+| `.$context<U>()`    | Set or override the initial context type                                        |
+| `.$meta(meta)`      | Set or override the initial metadata                                            |
+| `.$route(route)`    | Set or override the initial route configuration                                 |
+| `.$input(schema)`   | Set or override the initial input schema                                        |
+| `.errors(map)`      | Add type-safe custom errors                                                     |
+| `.meta(meta)`       | Set procedure metadata (merged with existing)                                   |
+| `.route(route)`     | Configure OpenAPI route (merged with existing)                                  |
+| `.input(schema)`    | Define input validation schema                                                  |
+| `.output(schema)`   | Define output validation schema                                                 |
+| `.use(middleware)`  | Add middleware                                                                  |
+| `.traced(name)`     | Add a traceable span for telemetry (optional, defaults to the procedure's path) |
+| `.handler(handler)` | Define a non-Effect handler (standard oRPC handler)                             |
+| `.effect(handler)`  | Define the Effect handler                                                       |
+| `.prefix(prefix)`   | Prefix all procedures in the router (for OpenAPI)                               |
+| `.tag(...tags)`     | Add tags to all procedures in the router (for OpenAPI)                          |
+| `.router(router)`   | Apply all options to a router                                                   |
+| `.lazy(loader)`     | Create and apply options to a lazy-loaded router                                |
+
+### `EffectDecoratedProcedure`
+
+The result of calling `.effect()`. Extends standard oRPC `DecoratedProcedure` with Effect type preservation.
+
+| Method                  | Description                                   |
+| ----------------------- | --------------------------------------------- |
+| `.errors(map)`          | Add more custom errors                        |
+| `.meta(meta)`           | Update metadata (merged with existing)        |
+| `.route(route)`         | Update route configuration (merged)           |
+| `.use(middleware)`      | Add middleware                                |
+| `.callable(options?)`   | Make procedure directly invocable             |
+| `.actionable(options?)` | Make procedure compatible with server actions |
+
+### `ORPCTaggedError(tag, options?)`
+
+Factory function to create Effect-native tagged error classes.
+
+The options is an optional object containing:
+
+- `schema?` - Optional Standard Schema for the error's data payload (e.g., `z.object({ userId: z.string() })`)
+- `code?` - Optional ORPCErrorCode, defaults to CONSTANT_CASE of the tag (e.g., `UserNotFoundError` → `USER_NOT_FOUND_ERROR`).
+- `status?` - Sets the default status of the error
+- `message` - Sets the default message of the error
+
+## License
+
+MIT

package/dist/{chunk-E5YLLTJI.js → chunk-I5EWBI42.js}

@@ -11,4 +11,4 @@ export {
   installServiceContextBridge,
   getCurrentServices
 };
-//# sourceMappingURL=chunk-E5YLLTJI.js.map
+//# sourceMappingURL=chunk-I5EWBI42.js.map

package/dist/chunk-I5EWBI42.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/service-context-bridge.ts"],"sourcesContent":["import type { Context } from \"effect\";\n\nexport interface ServiceContextBridge {\n  readonly getCurrentServices: () => Context.Context<any> | undefined;\n}\n\nlet bridge: ServiceContextBridge | undefined;\n\nexport function installServiceContextBridge(\n  nextBridge: ServiceContextBridge | undefined,\n): void {\n  bridge = nextBridge;\n}\n\nexport function getCurrentServices(): Context.Context<any> | undefined {\n  return bridge?.getCurrentServices();\n}\n"],"mappings":";AAMA,IAAI;AAEG,SAAS,4BACd,YACM;AACN,WAAS;AACX;AAEO,SAAS,qBAAuD;AACrE,SAAO,QAAQ,mBAAmB;AACpC;","names":[]}