effect-orpc 0.2.2 → 0.4.0

package/README.md

@@ -7,7 +7,7 @@ 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
+- **Type-safe service injection** - Add base services with `.provide(layer)` or pass a `Layer` / `ManagedRuntime<R>` directly
 - **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()`.
@@ -30,7 +30,7 @@ Runnable demos live in the repository's `examples/` directory.
 ```ts
 import { os } from "@orpc/server";
 import { Effect, ManagedRuntime } from "effect";
-import { makeEffectORPC, ORPCTaggedError } from "effect-orpc";
+import { eos, makeEffectORPC, ORPCTaggedError } from "effect-orpc";
 
 interface User {
   id: number;
@@ -43,15 +43,6 @@ let users: User[] = [
   { 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 Effect.Service<UsersRepo>()("UsersRepo", {
   accessors: true,
@@ -65,18 +56,27 @@ class UserNotFoundError extends ORPCTaggedError("UserNotFoundError", {
   status: 404,
 }) {}
 
-// Create runtime with your services
-const runtime = ManagedRuntime.make(UsersRepo.Default);
-// Create Effect-aware oRPC builder from an other (optional) base oRPC builder and provide tagged errors
-const effectOs = makeEffectORPC(runtime, authedOs).errors({
-  UserNotFoundError,
-});
+// Create an Effect-aware oRPC builder with your service layer, context, errors,
+// and middleware.
+const effectProcedure = eos
+  .provide(UsersRepo.Default)
+  .errors({ UNAUTHORIZED: { status: 401 }, UserNotFoundError })
+  .$context<{ userId?: number }>()
+  .use(({ context, errors, next }) => {
+    if (context.userId === undefined) throw errors.UNAUTHORIZED();
+    return next({ context: { ...context, userId: context.userId } });
+  });
+
+// Use ManagedRuntime only when scoped resources should be acquired once and
+// released on shutdown, for example a shared cache, database pool, or telemetry SDK:
+// const runtime = ManagedRuntime.make(UsersRepo.Default);
+// const effectProcedure = makeEffectORPC(runtime).errors({ UserNotFoundError });
 
 // Create the router with mixed procedures
 export const router = {
   health: os.handler(() => "ok"),
   users: {
-    me: effectOs.effect(function* ({ context: { userId } }) {
+    me: effectProcedure.effect(function* ({ context: { userId } }) {
       const user = yield* UsersRepo.get(userId);
       if (!user) {
         return yield* new UserNotFoundError();
@@ -91,11 +91,11 @@ 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:
+The wrapper enforces that Effect procedures only use services provided by `.provide(layer)`, request-scoped `.provide(tag, provider)` calls, or an initial `Layer` / `ManagedRuntime`. If you try to use a service that isn't available, you'll get a compile-time error:
 
 ```ts
-import { Context, Effect, Layer, ManagedRuntime } from "effect";
-import { makeEffectORPC } from "effect-orpc";
+import { Context, Effect, Layer } from "effect";
+import { eos } from "effect-orpc";
 
 class ProvidedService extends Context.Tag("ProvidedService")<
   ProvidedService,
@@ -107,22 +107,20 @@ class MissingService extends Context.Tag("MissingService")<
   { doSomething: () => Effect.Effect<string> }
 >() {}
 
-const runtime = ManagedRuntime.make(
-  Layer.succeed(ProvidedService, {
-    doSomething: () => Effect.succeed("ok"),
-  }),
-);
+const AppLive = Layer.succeed(ProvidedService, {
+  doSomething: () => Effect.succeed("ok"),
+});
 
-const effectOs = makeEffectORPC(runtime);
+const effectProcedure = eos.provide(AppLive);
 
-// ✅ This compiles - ProvidedService is in the runtime
-const works = effectOs.effect(function* () {
+// ✅ This compiles - ProvidedService is provided by AppLive
+const works = effectProcedure.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* () {
+// ❌ This fails to compile - MissingService is not provided
+const fails = effectProcedure.effect(function* () {
   const service = yield* MissingService; // Type error!
   return yield* service.doSomething();
 });
@@ -139,7 +137,7 @@ const fails = effectOs.effect(function* () {
 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
+const getUser = effectProcedure
   // Mixed error maps
   .errors({
     // Regular oRPC error
@@ -208,19 +206,19 @@ All Effect procedures are automatically traced with `Effect.withSpan`. By defaul
 const router = {
   users: {
     // Span name: "users.get"
-    get: effectOs.input(z.object({ id: z.string() })).effect(function* ({
+    get: effectProcedure.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);
-    }),
+    create: effectProcedure
+      .input(z.object({ name: z.string() }))
+      .effect(function* ({ input }) {
+        const userService = yield* UserService;
+        return yield* userService.create(input.name);
+      }),
   },
 };
 ```
@@ -228,7 +226,7 @@ const router = {
 Use `.traced()` to override the default span name:
 
 ```ts
-const getUser = effectOs
+const getUser = effectProcedure
   .input(z.object({ id: z.string() }))
   .traced("custom.span.name") // Override the default path-based name
   .effect(function* ({ input }) {
@@ -239,7 +237,7 @@ const getUser = effectOs
 
 ### Enabling OpenTelemetry
 
-To enable tracing, include the OpenTelemetry layer in your runtime:
+To enable tracing, include the OpenTelemetry layer in your application layer:
 
 ```ts
 import { NodeSdk } from "@effect/opentelemetry";
@@ -255,8 +253,7 @@ const TracingLive = NodeSdk.layer(
 
 const AppLive = Layer.mergeAll(UserServiceLive, TracingLive);
 
-const runtime = ManagedRuntime.make(AppLive);
-const effectOs = makeEffectORPC(runtime);
+const effectProcedure = eos.provide(AppLive);
 ```
 
 ### Error Stack Traces
@@ -269,24 +266,136 @@ MyCustomError: Something went wrong
     at users.getById (/app/src/procedures.ts:41:35)
 ```
 
+## Effect middleware
+
+`.use(...)` accepts generator-based Effect middleware in addition to native oRPC
+middleware. Two patterns are supported:
+
+**Gate** — run auth or validation side effects, then let the pipeline continue
+automatically (no need to call `next`):
+
+```ts
+effectProcedure.use(function* () {
+  const user = yield* CurrentUser;
+  yield* requireActiveUser(user);
+});
+```
+
+**Wrap** — call downstream explicitly and return the result. When porting oRPC
+middleware that uses `return next(...)`, use `return yield* next(...)`:
+
+```ts
+effectProcedure.use(function* ({ next }) {
+  const user = yield* CurrentUser;
+  yield* requireActiveUser(user);
+
+  return yield* next({
+    context: { userId: user.id },
+  });
+});
+```
+
+To transform the downstream output, capture `next()` and pass through `output`:
+
+```ts
+effectProcedure.use(function* ({ next }, _input, output) {
+  const result = yield* next();
+  return yield* output(`${result.output}-wrapped`);
+});
+```
+
+Calling `yield* next()` without returning its result still runs the handler once,
+but prefer `return yield* next(...)` so the pipeline receives your middleware
+result explicitly.
+
+### Runtime boundaries and fiber context continuity
+
+`effect-orpc` batches contiguous Effect-native steps into one runtime boundary.
+Effect-native steps are `.provide(...)`, `.provideOptional(...)`, generator
+`.use(function* ...)`, and `.effect(function* ...)`.
+
+```ts
+eos
+  .provide(AppLive)
+  .provide(CurrentUser, ({ context }) => Effect.succeed(context.user))
+  .use(function* ({ next }) {
+    const user = yield* CurrentUser;
+    return yield* next({ context: { userId: user.id } });
+  })
+  .effect(function* ({ context }) {
+    const user = yield* CurrentUser;
+    return `${context.userId}:${user.id}`;
+  });
+```
+
+The example above runs the provider, middleware, and handler inside a single
+Effect execution boundary.
+
+A native oRPC middleware breaks the contiguous Effect pipeline. Pending Effect
+steps are flushed into one generated oRPC middleware before the native middleware:
+
+```ts
+eos
+  .provide(AppLive)
+  .provide(CurrentUser, getCurrentUser) // Effect group #1
+  .use(function* ({ next }) {
+    return yield* next();
+  })
+  .use(({ next }) => next()) // native oRPC middleware; flushes group #1
+  .use(function* ({ next }) {
+    return yield* next();
+  }) // Effect group #2
+  .effect(function* () {
+    return "ok";
+  });
+```
+
+That split still creates multiple runtime boundaries. If the Node bridge is
+installed, however, `effect-orpc` carries the current `FiberRefs` through the
+native oRPC continuation and merges them into the next Effect boundary:
+
+```ts
+import "effect-orpc/node";
+```
+
+Use the side-effect import when you only need continuity across internal
+`effect-orpc` boundaries, such as Effect group #1 → native oRPC middleware →
+Effect group #2.
+
+Procedure-level `.provide*` after a native `.handler(...)` has no Effect handler
+boundary to attach to, so it is installed as an oRPC middleware that runs its
+provider Effect through the configured runtime source:
+
+```ts
+eos
+  .provide(AppLive)
+  .handler(() => "ok") // native oRPC handler
+  .provide(CurrentUser, getCurrentUser); // fallback provider middleware
+```
+
+If you want `.provide*` and Effect middleware to batch with the handler, use
+`.effect(function* ...)` instead of `.handler(...)`.
+
 ## 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.
+The `/node` entrypoint installs a bridge backed by `AsyncLocalStorage`. It has
+two uses:
+
+- `import "effect-orpc/node"` installs the bridge passively. This is enough for
+  `effect-orpc` to propagate `FiberRefs` across its own split runtime boundaries.
+- `withFiberContext(() => next())` actively seeds the bridge from an external
+  Effect scope, such as framework middleware wrapping an oRPC handler.
 
-To preserve request-scoped logs, tracing annotations, and
-other fiber-local state, wrap the framework continuation with `withFiberContext` from
-`effect-orpc/node`.
+Use `withFiberContext` when request-local `FiberRef` state is created outside the
+oRPC pipeline and should be visible inside handlers:
 
 ```ts
 import { Hono } from "hono";
-import { Effect, ManagedRuntime } from "effect";
-import { makeEffectORPC } from "effect-orpc";
+import { Effect } from "effect";
+import { eos } from "effect-orpc";
 import { withFiberContext } from "effect-orpc/node";
 
-const runtime = ManagedRuntime.make(AppLive);
-const effectOs = makeEffectORPC(runtime);
+const effectProcedure = eos.provide(AppLive);
 const app = new Hono();
 
 app.use("*", async (c, next) => {
@@ -302,31 +411,27 @@ app.use("*", async (c, 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.
+Importing `withFiberContext` from `effect-orpc/node` also installs the bridge, so
+you do not need a separate side-effect import.
 
-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.
+When a captured fiber context and the application `Layer` / `ManagedRuntime`
+both provide the same service, `effect-orpc` prioritizes the captured context.
+The application layer is treated as the base layer, while the bridge preserves more specific
+request-scoped values such as request IDs, logging annotations, tracing context,
+or scoped overrides when crossing runtime boundaries.
 
-If you do not need framework-to-handler fiber propagation, you do not need the
-`/node` entrypoint at all.
+The main package stays runtime-agnostic; `/node` is separate because the bridge
+relies on `AsyncLocalStorage` from `node:async_hooks`.
 
 ## 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.
+Use `implementEffect(contract, layerOrRuntime)` when you already have an oRPC
+contract and want to keep contract-first enforcement while adding Effect-native
+handlers. Use `eos.provide(layer)` when you want to build procedures directly
+from the default Effect-aware builder.
 
 ```ts
-import { Effect, ManagedRuntime } from "effect";
+import { Effect } from "effect";
 import { eoc, implementEffect } from "effect-orpc";
 import z from "zod";
 
@@ -346,8 +451,7 @@ const contract = {
   },
 };
 
-const runtime = ManagedRuntime.make(UsersRepo.Default);
-const oe = implementEffect(contract, runtime);
+const oe = implementEffect(contract, UsersRepo.Default);
 
 export const router = oe.router({
   users: {
@@ -369,34 +473,46 @@ directly from the `ORPCTaggedError` class.
 
 ## API Reference
 
-### `makeEffectORPC(runtime, builder?)`
+### `eos`
 
-Creates an Effect-aware procedure builder.
+The default Effect-aware procedure builder. Provide your application services
+with `.provide(layer)`:
 
-- `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`
+```ts
+const effectProcedure = eos.provide(AppLive);
+```
 
-Returns an `EffectBuilder` instance.
+Use `makeEffectORPC(runtime)` when a scoped `Layer` should be acquired once and
+released by your application shutdown path, such as a shared cache, database
+pool, HTTP client, or telemetry SDK:
 
 ```ts
-// With default builder
-const effectOs = makeEffectORPC(runtime);
+const runtime = ManagedRuntime.make(AppLive);
+
+const effectProcedure = makeEffectORPC(runtime);
 
-// With customized builder
-const effectAuthedOs = makeEffectORPC(runtime, authedBuilder);
+// later, during app shutdown
+await runtime.dispose();
+```
+
+`makeEffectORPC(builder)` is also available when you need to wrap an existing
+oRPC builder:
+
+```ts
+const effectAuthedOs = makeEffectORPC(authedBuilder).provide(AppLive);
 ```
 
-### `implementEffect(contract, runtime)`
+### `implementEffect(contract, layerOrRuntime)`
 
 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
+- `layerOrRuntime` - A `Layer<R, E, never>` provided per call, or a user-owned `ManagedRuntime<R, E>` when the application should control acquisition and release (for example, a shared cache, database pool, or telemetry SDK)
 
 Returns a contract-shaped implementer tree whose leaves support `.effect(...)`.
 
 ```ts
-const oe = implementEffect(contract, runtime);
+const oe = implementEffect(contract, AppLive);
 
 const router = oe.router({
   users: {
@@ -436,26 +552,28 @@ const contract = {
 
 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                                |
+| 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                                                      |
+| `.provide(layer)`   | Provide a base Effect layer to downstream Effect middleware and handlers             |
+| `.provide(tag, fn)` | Provide a request-scoped Effect service to downstream Effect middleware and handlers |
+| `.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`
 
@@ -466,6 +584,8 @@ The result of calling `.effect()`. Extends standard oRPC `DecoratedProcedure` wi
 | `.errors(map)`          | Add more custom errors                        |
 | `.meta(meta)`           | Update metadata (merged with existing)        |
 | `.route(route)`         | Update route configuration (merged)           |
+| `.provide(layer)`       | Provide a base Effect layer                   |
+| `.provide(tag, fn)`     | Provide a request-scoped Effect service       |
 | `.use(middleware)`      | Add middleware                                |
 | `.callable(options?)`   | Make procedure directly invocable             |
 | `.actionable(options?)` | Make procedure compatible with server actions |

package/dist/{chunk-VOWRLWZZ.js → chunk-IJP6L2XR.js}

@@ -6,9 +6,13 @@ function installFiberContextBridge(nextBridge) {
 function getCurrentFiberRefs() {
   return bridge?.getCurrentFiberRefs();
 }
+function runWithFiberRefs(fiberRefs, fn) {
+  return bridge?.runWithFiberRefs ? bridge.runWithFiberRefs(fiberRefs, fn) : fn();
+}
 
 export {
   installFiberContextBridge,
-  getCurrentFiberRefs
+  getCurrentFiberRefs,
+  runWithFiberRefs
 };
-//# sourceMappingURL=chunk-VOWRLWZZ.js.map
+//# sourceMappingURL=chunk-IJP6L2XR.js.map

package/dist/chunk-IJP6L2XR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/fiber-context-bridge.ts"],"sourcesContent":["import type { FiberRefs } from \"effect\";\n\nexport interface FiberContextBridge {\n  readonly getCurrentFiberRefs: () => FiberRefs.FiberRefs | undefined;\n  readonly runWithFiberRefs?: <T>(\n    fiberRefs: FiberRefs.FiberRefs,\n    fn: () => Promise<T>,\n  ) => Promise<T>;\n}\n\nlet bridge: FiberContextBridge | undefined;\n\nexport function installFiberContextBridge(\n  nextBridge: FiberContextBridge | undefined,\n): void {\n  bridge = nextBridge;\n}\n\nexport function getCurrentFiberRefs(): FiberRefs.FiberRefs | undefined {\n  return bridge?.getCurrentFiberRefs();\n}\n\nexport function runWithFiberRefs<T>(\n  fiberRefs: FiberRefs.FiberRefs,\n  fn: () => Promise<T>,\n): Promise<T> {\n  return bridge?.runWithFiberRefs\n    ? bridge.runWithFiberRefs(fiberRefs, fn)\n    : fn();\n}\n"],"mappings":";AAUA,IAAI;AAEG,SAAS,0BACd,YACM;AACN,WAAS;AACX;AAEO,SAAS,sBAAuD;AACrE,SAAO,QAAQ,oBAAoB;AACrC;AAEO,SAAS,iBACd,WACA,IACY;AACZ,SAAO,QAAQ,mBACX,OAAO,iBAAiB,WAAW,EAAE,IACrC,GAAG;AACT;","names":[]}