effect-orpc 0.3.0 → 0.5.0

package/README.md

@@ -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,26 +56,27 @@ class UserNotFoundError extends ORPCTaggedError("UserNotFoundError", {
   status: 404,
 }) {}
 
-// Create an Effect-aware oRPC builder with your service layer, optionally from
-// another base oRPC builder, and provide tagged errors.
-const effectOs = makeEffectORPC(UsersRepo.Default, 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 } });
+  });
 
-// You can also pass an explicit ManagedRuntime if you need lifecycle control:
+// 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 effectOs = makeEffectORPC(runtime, authedOs).errors({ UserNotFoundError });
-
-// Or start with only the builder and provide the layer later:
-// const effectOs = makeEffectORPC(authedOs)
-//   .provide(UsersRepo.Default)
-//   .errors({ UserNotFoundError });
+// 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();
@@ -103,7 +95,7 @@ The wrapper enforces that Effect procedures only use services provided by `.prov
 
 ```ts
 import { Context, Effect, Layer } from "effect";
-import { makeEffectORPC } from "effect-orpc";
+import { eos } from "effect-orpc";
 
 class ProvidedService extends Context.Tag("ProvidedService")<
   ProvidedService,
@@ -119,16 +111,16 @@ const AppLive = Layer.succeed(ProvidedService, {
   doSomething: () => Effect.succeed("ok"),
 });
 
-const effectOs = makeEffectORPC(AppLive);
+const effectProcedure = eos.provide(AppLive);
 
 // ✅ This compiles - ProvidedService is provided by AppLive
-const works = effectOs.effect(function* () {
+const works = effectProcedure.effect(function* () {
   const service = yield* ProvidedService;
   return yield* service.doSomething();
 });
 
 // ❌ This fails to compile - MissingService is not provided
-const fails = effectOs.effect(function* () {
+const fails = effectProcedure.effect(function* () {
   const service = yield* MissingService; // Type error!
   return yield* service.doSomething();
 });
@@ -145,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
@@ -214,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);
+      }),
   },
 };
 ```
@@ -234,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 }) {
@@ -261,7 +253,7 @@ const TracingLive = NodeSdk.layer(
 
 const AppLive = Layer.mergeAll(UserServiceLive, TracingLive);
 
-const effectOs = makeEffectORPC(AppLive);
+const effectProcedure = eos.provide(AppLive);
 ```
 
 ### Error Stack Traces
@@ -276,14 +268,14 @@ MyCustomError: Something went wrong
 
 ## Effect middleware
 
-`.use(...)` accepts generator-based Effect middleware in addition to native oRPC
-middleware. Two patterns are supported:
+`.use(...)` accepts generator-based and Effect-returning 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
-effectOs.use(function* () {
+effectProcedure.use(function* () {
   const user = yield* CurrentUser;
   yield* requireActiveUser(user);
 });
@@ -293,7 +285,7 @@ effectOs.use(function* () {
 middleware that uses `return next(...)`, use `return yield* next(...)`:
 
 ```ts
-effectOs.use(function* ({ next }) {
+effectProcedure.use(function* ({ next }) {
   const user = yield* CurrentUser;
   yield* requireActiveUser(user);
 
@@ -306,25 +298,45 @@ effectOs.use(function* ({ next }) {
 To transform the downstream output, capture `next()` and pass through `output`:
 
 ```ts
-effectOs.use(function* ({ next }, _input, output) {
+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.
+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.
+
+Effect-returning middleware is also supported, including `Effect.fn(...)` and
+`() => Effect.gen(...)`:
+
+```ts
+effectProcedure.use(
+  Effect.fn("middleware.auth")(function* ({ next }) {
+    const user = yield* CurrentUser;
+    return yield* next({ context: { userId: user.id } });
+  }),
+);
+```
+
+Request-scoped providers support the same generator or Effect-returning style:
+
+```ts
+effectProcedure.provide(CurrentUser, function* ({ context }) {
+  yield* Effect.logDebug("resolving current user");
+  return context.user;
+});
+```
 
 ### 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* ...)`.
+`effect-orpc` batches contiguous Effect-native steps into one runtime boundary. Effect-native steps are `.provide(...)`, `.provideOptional(...)`, generator `.use(function* ...)`, and `.effect(function* ...)`. Effect-returning handlers, providers, and middleware are supported too; named `Effect.fn(...)` callbacks keep their own spans rather than being wrapped as generators.
 
 ```ts
-makeEffectORPC(AppLive)
-  .provide(CurrentUser, ({ context }) => Effect.succeed(context.user))
+eos
+  .provide(AppLive)
+  .provide(CurrentUser, function* ({ context }) {
+    return context.user;
+  })
   .use(function* ({ next }) {
     const user = yield* CurrentUser;
     return yield* next({ context: { userId: user.id } });
@@ -335,14 +347,13 @@ makeEffectORPC(AppLive)
   });
 ```
 
-The example above runs the provider, middleware, and handler inside a single
-internal `runtime.runPromiseExit(...)` call.
+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:
+A native oRPC middleware breaks the contiguous Effect pipeline. Pending Effect steps are flushed into one generated oRPC middleware before the native middleware:
 
 ```ts
-makeEffectORPC(AppLive)
+eos
+  .provide(AppLive)
   .provide(CurrentUser, getCurrentUser) // Effect group #1
   .use(function* ({ next }) {
     return yield* next();
@@ -356,51 +367,41 @@ makeEffectORPC(AppLive)
   });
 ```
 
-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:
+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.
+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 runtime:
+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
-makeEffectORPC(AppLive)
+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(...)`.
+If you want `.provide*` and Effect middleware to batch with the handler, use `.effect(function* ...)` instead of `.handler(...)`.
 
 ## Request-Scoped Fiber Context
 
-The `/node` entrypoint installs a bridge backed by `AsyncLocalStorage`. It has
-two uses:
+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.
+- `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.
 
-Use `withFiberContext` when request-local `FiberRef` state is created outside the
-oRPC pipeline and should be visible inside handlers:
+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 } from "effect";
-import { makeEffectORPC } from "effect-orpc";
+import { eos } from "effect-orpc";
 import { withFiberContext } from "effect-orpc/node";
 
-const effectOs = makeEffectORPC(AppLive);
+const effectProcedure = eos.provide(AppLive);
 const app = new Hono();
 
 app.use("*", async (c, next) => {
@@ -416,24 +417,16 @@ app.use("*", async (c, next) => {
 });
 ```
 
-Importing `withFiberContext` from `effect-orpc/node` also installs the bridge, so
-you do not need a separate side-effect import.
+Importing `withFiberContext` from `effect-orpc/node` also installs the bridge, so you do not need a separate side-effect import.
 
-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.
+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.
 
-The main package stays runtime-agnostic; `/node` is separate because the bridge
-relies on `AsyncLocalStorage` from `node:async_hooks`.
+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, layerOrRuntime)` when you already have an oRPC
-contract and want to keep contract-first enforcement while adding Effect-native
-handlers. Use `makeEffectORPC(layerOrRuntime, 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 } from "effect";
@@ -467,40 +460,35 @@ export const router = oe.router({
 });
 ```
 
-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(...)`.
+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.
+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(layerOrRuntime, builder?)`
+### `eos`
 
-Creates an Effect-aware procedure builder. The recommended default is to pass
-your application `Layer` up front.
+The default Effect-aware procedure builder. Provide your application services with `.provide(layer)`:
 
-Returns an `EffectBuilder` instance.
+```ts
+const effectProcedure = eos.provide(AppLive);
+```
+
+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(AppLive);
+const runtime = ManagedRuntime.make(AppLive);
+
+const effectProcedure = makeEffectORPC(runtime);
 
-// With customized builder
-const effectAuthedOs = makeEffectORPC(AppLive, authedBuilder);
+// later, during app shutdown
+await runtime.dispose();
 ```
 
-You can also start from a builder and provide the layer later, or pass a
-`ManagedRuntime` when you need explicit runtime lifecycle control:
+`makeEffectORPC(builder)` is also available when you need to wrap an existing oRPC builder:
 
 ```ts
-const effectOsWithProvidedLayer = makeEffectORPC().provide(AppLive);
-const effectAuthedOsWithProvidedLayer =
-  makeEffectORPC(authedBuilder).provide(AppLive);
-const effectOsFromRuntime = makeEffectORPC(runtime);
+const effectAuthedOs = makeEffectORPC(authedBuilder).provide(AppLive);
 ```
 
 ### `implementEffect(contract, layerOrRuntime)`
@@ -508,7 +496,7 @@ const effectOsFromRuntime = makeEffectORPC(runtime);
 Creates an Effect-aware contract implementer.
 
 - `contract` - An oRPC contract router built with `oc`
-- `layerOrRuntime` - A `Layer<R, E, never>` or `ManagedRuntime<R, E>` 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(...)`.
 
@@ -528,8 +516,7 @@ const router = oe.router({
 
 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.
+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", {
@@ -553,43 +540,43 @@ 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                                                      |
-| `.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                                     |
+| 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, provider)` | 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`
 
 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)           |
-| `.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 |
+| Method                    | Description                                   |
+| ------------------------- | --------------------------------------------- |
+| `.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, provider)` | Provide a request-scoped Effect service       |
+| `.use(middleware)`        | Add middleware                                |
+| `.callable(options?)`     | Make procedure directly invocable             |
+| `.actionable(options?)`   | Make procedure compatible with server actions |
 
 ### `ORPCTaggedError(tag, options?)`