effect-orpc 0.2.0 → 0.2.2

package/src/effect-builder.ts

@@ -2,55 +2,32 @@ import type {
   AnySchema,
   ContractRouter,
   ErrorMap,
-  HTTPPath,
-  InferSchemaOutput,
   Meta,
-  Route,
   Schema,
 } from "@orpc/contract";
-import { mergeMeta, mergePrefix, mergeRoute, mergeTags } from "@orpc/contract";
-import type {
-  AnyMiddleware,
-  BuilderConfig,
-  BuilderDef,
-  Context,
-  DecoratedMiddleware,
-  Lazy,
-  MapInputMiddleware,
-  MergedCurrentContext,
-  MergedInitialContext,
-  Middleware,
-  ProcedureHandler,
-  Router,
-} from "@orpc/server";
-import {
-  addMiddleware,
-  Builder,
-  decorateMiddleware,
-  fallbackConfig,
-  lazy,
-} from "@orpc/server";
-import type { IntersectPick } from "@orpc/shared";
+import type { Context, Router } from "@orpc/server";
+import { Builder, fallbackConfig, lazy } from "@orpc/server";
 import type { ManagedRuntime } from "effect";
 
 import { enhanceEffectRouter } from "./effect-enhance-router";
 import { EffectDecoratedProcedure } from "./effect-procedure";
 import { createEffectProcedureHandler } from "./effect-runtime";
-import type {
-  EffectErrorConstructorMap,
-  EffectErrorMap,
-  MergedEffectErrorMap,
-} from "./tagged-error";
+import {
+  createNodeProxy,
+  unhandled,
+  type NodeProxyContext,
+} from "./extension/create-node-proxy";
+import {
+  attachEffectState,
+  getEffectErrorMap,
+  unwrapEffectUpstream,
+  type EffectProxyTarget,
+} from "./extension/state";
+import type { EffectErrorMap, MergedEffectErrorMap } from "./tagged-error";
 import { effectErrorMapToErrorMap } from "./tagged-error";
 import type {
   AnyBuilderLike,
   EffectBuilderDef,
-  EffectErrorMapToErrorMap,
-  EffectProcedureBuilderWithInput,
-  EffectProcedureBuilderWithOutput,
-  EffectProcedureHandler,
-  EffectRouterBuilder,
-  EnhancedEffectRouter,
   InferBuilderCurrentContext,
   InferBuilderErrorMap,
   InferBuilderInitialContext,
@@ -58,12 +35,215 @@ import type {
   InferBuilderMeta,
   InferBuilderOutputSchema,
 } from "./types";
+import type { EffectBuilderSurface } from "./types/effect-builder-surface";
+
+const builderVirtualDescriptors = {
+  "~effect": { enumerable: true },
+  effect: { enumerable: false },
+  errors: { enumerable: false },
+  handler: { enumerable: false },
+  lazy: { enumerable: false },
+  router: { enumerable: false },
+  traced: { enumerable: false },
+} as const;
+
+const builderVirtualKeys = [
+  "~effect",
+  "errors",
+  "effect",
+  "traced",
+  "handler",
+  "router",
+  "lazy",
+] as const;
+
+type EffectBuilderTarget = EffectBuilder<
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any
+> &
+  EffectProxyTarget<AnyBuilderLike>;
+
+function isBuilderLike(value: unknown): value is AnyBuilderLike {
+  return typeof value === "object" && value !== null && "~orpc" in value;
+}
+
+function getOrCreateVirtualMethod<T>(
+  context: NodeProxyContext<EffectBuilderTarget, AnyBuilderLike>,
+  prop: PropertyKey,
+  factory: () => T,
+): T {
+  const cache = context.methodCache;
+  if (cache.has(prop)) {
+    return cache.get(prop) as T;
+  }
+
+  const value = factory();
+  cache.set(prop, value);
+  return value;
+}
+
+function getEffectBuilderDef(
+  context: NodeProxyContext<EffectBuilderTarget, AnyBuilderLike>,
+): EffectBuilderDef<any, any, any, any, any, any> {
+  return {
+    ...context.upstream["~orpc"],
+    effectErrorMap: context.state.effectErrorMap,
+    runtime: context.state.runtime,
+    spanConfig: context.state.spanConfig,
+  };
+}
+
+function wrapBuilderLike(
+  builder: AnyBuilderLike,
+  state: NodeProxyContext<EffectBuilderTarget, AnyBuilderLike>["state"],
+): EffectBuilder<any, any, any, any, any, any, any, any> {
+  return new EffectBuilder(
+    {
+      ...builder["~orpc"],
+      effectErrorMap: state.effectErrorMap,
+      runtime: state.runtime,
+      spanConfig: state.spanConfig,
+    },
+    unwrapEffectUpstream(builder),
+  );
+}
+
+function createEffectBuilderProxy(
+  target: EffectBuilderTarget,
+): EffectBuilderTarget {
+  return createNodeProxy<EffectBuilderTarget, AnyBuilderLike>(target, {
+    getVirtual(context, prop) {
+      const effectDef = getEffectBuilderDef(context);
+      if (prop === "~effect") {
+        return getEffectBuilderDef(context);
+      }
+
+      const { upstream: source, state } = context;
+
+      switch (prop) {
+        case "errors":
+          return getOrCreateVirtualMethod(context, prop, () => {
+            return <U extends EffectErrorMap>(errors: U) => {
+              const nextEffectErrorMap: MergedEffectErrorMap<
+                typeof state.effectErrorMap,
+                U
+              > = {
+                ...state.effectErrorMap,
+                ...errors,
+              };
+              const nextBuilder: AnyBuilderLike = Reflect.apply(
+                Reflect.get(source, "errors", source),
+                source,
+                [effectErrorMapToErrorMap(errors)],
+              );
+
+              return wrapBuilderLike(nextBuilder, {
+                ...state,
+                effectErrorMap: nextEffectErrorMap,
+              });
+            };
+          });
+        case "effect":
+          return getOrCreateVirtualMethod(context, prop, () => {
+            return (
+              effectFn: Parameters<
+                EffectBuilderSurface<
+                  any,
+                  any,
+                  any,
+                  any,
+                  any,
+                  any,
+                  any,
+                  any
+                >["effect"]
+              >[0],
+            ) => {
+              const defaultCaptureStackTrace = addSpanStackTrace();
+              return new EffectDecoratedProcedure({
+                ...effectDef,
+                handler: async (opts) => {
+                  return createEffectProcedureHandler({
+                    defaultCaptureStackTrace,
+                    effectErrorMap: state.effectErrorMap,
+                    effectFn,
+                    runtime: state.runtime,
+                    spanConfig: state.spanConfig,
+                  })(opts as any);
+                },
+              });
+            };
+          });
+        case "traced":
+          return getOrCreateVirtualMethod(context, prop, () => {
+            return (spanName: string) =>
+              wrapBuilderLike(source, {
+                ...state,
+                spanConfig: {
+                  captureStackTrace: addSpanStackTrace(),
+                  name: spanName,
+                },
+              });
+          });
+        case "handler":
+          return getOrCreateVirtualMethod(context, prop, () => {
+            return (
+              handler: Parameters<
+                EffectBuilderSurface<
+                  any,
+                  any,
+                  any,
+                  any,
+                  any,
+                  any,
+                  any,
+                  any
+                >["handler"]
+              >[0],
+            ) =>
+              new EffectDecoratedProcedure({
+                ...effectDef,
+                handler,
+              });
+          });
+        case "router":
+          return getOrCreateVirtualMethod(context, prop, () => {
+            return (router: Router<ContractRouter<any>, any>) =>
+              enhanceEffectRouter(router, effectDef) as any;
+          });
+        case "lazy":
+          return getOrCreateVirtualMethod(context, prop, () => {
+            return (
+              loader: () => Promise<{
+                default: Router<ContractRouter<any>, any>;
+              }>,
+            ) => enhanceEffectRouter(lazy(loader), effectDef) as any;
+          });
+        default:
+          return unhandled();
+      }
+    },
+    virtualDescriptors: builderVirtualDescriptors,
+    virtualKeys: builderVirtualKeys,
+    wrapResult(context, _prop, result) {
+      if (!isBuilderLike(result)) {
+        return result;
+      }
+
+      return wrapBuilderLike(result, context.state);
+    },
+  });
+}
 
 /**
  * Captures the stack trace at the call site for better error reporting in spans.
  * This is called at procedure definition time to capture where the procedure was defined.
- *
- * @returns A function that lazily extracts the relevant stack frame
  */
 export function addSpanStackTrace(): () => string | undefined {
   const ErrorConstructor = Error as typeof Error & {
@@ -102,49 +282,23 @@ export class EffectBuilder<
   TMeta extends Meta,
   TRequirementsProvided,
   TRuntimeError,
+> implements EffectBuilderSurface<
+  TInitialContext,
+  TCurrentContext,
+  TInputSchema,
+  TOutputSchema,
+  TEffectErrorMap,
+  TMeta,
+  TRequirementsProvided,
+  TRuntimeError
 > {
-  /**
-   * This property holds the defined options and the effect-specific properties.
-   */
-  declare "~effect": EffectBuilderDef<
-    TInputSchema,
-    TOutputSchema,
-    TEffectErrorMap,
-    TMeta,
-    TRequirementsProvided,
-    TRuntimeError
-  >;
-  declare "~orpc": BuilderDef<
-    TInputSchema,
-    TOutputSchema,
-    EffectErrorMapToErrorMap<TEffectErrorMap>,
-    TMeta
-  >;
-
-  constructor(
-    def: EffectBuilderDef<
-      TInputSchema,
-      TOutputSchema,
-      TEffectErrorMap,
-      TMeta,
-      TRequirementsProvided,
-      TRuntimeError
-    >,
-  ) {
-    const { runtime, spanConfig, effectErrorMap, ...orpcDef } = def;
-    this["~orpc"] = orpcDef;
-    this["~effect"] = { runtime, spanConfig, effectErrorMap, ...orpcDef };
-  }
-
   /**
    * Sets or overrides the config.
    *
    * @see {@link https://orpc.dev/docs/client/server-side#middlewares-order Middlewares Order Docs}
    * @see {@link https://orpc.dev/docs/best-practices/dedupe-middleware#configuration Dedupe Middleware Docs}
    */
-  $config(
-    config: BuilderConfig,
-  ): EffectBuilder<
+  declare $config: EffectBuilderSurface<
     TInitialContext,
     TCurrentContext,
     TInputSchema,
@@ -153,100 +307,37 @@ export class EffectBuilder<
     TMeta,
     TRequirementsProvided,
     TRuntimeError
-  > {
-    const inputValidationCount =
-      this["~effect"].inputValidationIndex -
-      fallbackConfig(
-        "initialInputValidationIndex",
-        this["~effect"].config.initialInputValidationIndex,
-      );
-    const outputValidationCount =
-      this["~effect"].outputValidationIndex -
-      fallbackConfig(
-        "initialOutputValidationIndex",
-        this["~effect"].config.initialOutputValidationIndex,
-      );
-
-    return new EffectBuilder({
-      ...this["~effect"],
-      config,
-      dedupeLeadingMiddlewares: fallbackConfig(
-        "dedupeLeadingMiddlewares",
-        config.dedupeLeadingMiddlewares,
-      ),
-      inputValidationIndex:
-        fallbackConfig(
-          "initialInputValidationIndex",
-          config.initialInputValidationIndex,
-        ) + inputValidationCount,
-      outputValidationIndex:
-        fallbackConfig(
-          "initialOutputValidationIndex",
-          config.initialOutputValidationIndex,
-        ) + outputValidationCount,
-    });
-  }
-
+  >["$config"];
   /**
    * Set or override the initial context.
    *
    * @see {@link https://orpc.dev/docs/context Context Docs}
    */
-  $context<U extends Context>(): EffectBuilder<
-    U & Record<never, never>,
-    U,
+  declare $context: EffectBuilderSurface<
+    TInitialContext,
+    TCurrentContext,
     TInputSchema,
     TOutputSchema,
     TEffectErrorMap,
     TMeta,
     TRequirementsProvided,
     TRuntimeError
-  > {
-    /**
-     * We need `& Record<never, never>` to deal with `has no properties in common with type` error
-     */
-
-    return new EffectBuilder({
-      ...this["~effect"],
-      middlewares: [],
-      inputValidationIndex: fallbackConfig(
-        "initialInputValidationIndex",
-        this["~effect"].config.initialInputValidationIndex,
-      ),
-      outputValidationIndex: fallbackConfig(
-        "initialOutputValidationIndex",
-        this["~effect"].config.initialOutputValidationIndex,
-      ),
-    });
-  }
-
+  >["$context"];
   /**
    * Sets or overrides the initial meta.
    *
    * @see {@link https://orpc.dev/docs/metadata Metadata Docs}
    */
-  $meta<U extends Meta>(
-    initialMeta: U,
-  ): EffectBuilder<
+  declare $meta: EffectBuilderSurface<
     TInitialContext,
     TCurrentContext,
     TInputSchema,
     TOutputSchema,
     TEffectErrorMap,
-    U & Record<never, never>,
+    TMeta,
     TRequirementsProvided,
     TRuntimeError
-  > {
-    /**
-     * We need `& Record<never, never>` to deal with `has no properties in common with type` error
-     */
-
-    return new EffectBuilder({
-      ...this["~effect"],
-      meta: initialMeta,
-    });
-  }
-
+  >["$meta"];
   /**
    * Sets or overrides the initial route.
    * This option is typically relevant when integrating with OpenAPI.
@@ -254,9 +345,7 @@ export class EffectBuilder<
    * @see {@link https://orpc.dev/docs/openapi/routing OpenAPI Routing Docs}
    * @see {@link https://orpc.dev/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
    */
-  $route(
-    initialRoute: Route,
-  ): EffectBuilder<
+  declare $route: EffectBuilderSurface<
     TInitialContext,
     TCurrentContext,
     TInputSchema,
@@ -265,65 +354,61 @@ export class EffectBuilder<
     TMeta,
     TRequirementsProvided,
     TRuntimeError
-  > {
-    return new EffectBuilder({
-      ...this["~effect"],
-      route: initialRoute,
-    });
-  }
-
+  >["$route"];
   /**
    * Sets or overrides the initial input schema.
    *
    * @see {@link https://orpc.dev/docs/procedure#initial-configuration Initial Procedure Configuration Docs}
    */
-  $input<U extends AnySchema>(
-    initialInputSchema?: U,
-  ): EffectBuilder<
+  declare $input: EffectBuilderSurface<
     TInitialContext,
     TCurrentContext,
-    U,
+    TInputSchema,
     TOutputSchema,
     TEffectErrorMap,
     TMeta,
     TRequirementsProvided,
     TRuntimeError
-  > {
-    return new EffectBuilder({
-      ...this["~effect"],
-      inputSchema: initialInputSchema,
-    });
-  }
-
+  >["$input"];
+  /**
+   * This property holds the defined options and the effect-specific properties.
+   */
+  declare "~effect": EffectBuilderDef<
+    TInputSchema,
+    TOutputSchema,
+    TEffectErrorMap,
+    TMeta,
+    TRequirementsProvided,
+    TRuntimeError
+  >;
+  /**
+   * This property holds the defined options.
+   */
+  declare "~orpc": EffectBuilderSurface<
+    TInitialContext,
+    TCurrentContext,
+    TInputSchema,
+    TOutputSchema,
+    TEffectErrorMap,
+    TMeta,
+    TRequirementsProvided,
+    TRuntimeError
+  >["~orpc"];
   /**
    * Creates a middleware.
    *
    * @see {@link https://orpc.dev/docs/middleware Middleware Docs}
    */
-  middleware<
-    UOutContext extends IntersectPick<TCurrentContext, UOutContext>,
-    TInput,
-    TOutput = any,
-  >(
-    middleware: Middleware<
-      TInitialContext,
-      UOutContext,
-      TInput,
-      TOutput,
-      EffectErrorConstructorMap<TEffectErrorMap>,
-      TMeta
-    >,
-  ): DecoratedMiddleware<
+  declare middleware: EffectBuilderSurface<
     TInitialContext,
-    UOutContext,
-    TInput,
-    TOutput,
-    any,
-    TMeta
-  > {
-    return decorateMiddleware(middleware);
-  }
-
+    TCurrentContext,
+    TInputSchema,
+    TOutputSchema,
+    TEffectErrorMap,
+    TMeta,
+    TRequirementsProvided,
+    TRuntimeError
+  >["middleware"];
   /**
    * Adds type-safe custom errors.
    * Supports both traditional oRPC error definitions and ORPCTaggedError classes.
@@ -345,29 +430,16 @@ export class EffectBuilder<
    *
    * @see {@link https://orpc.dev/docs/error-handling#type%E2%80%90safe-error-handling Type-Safe Error Handling Docs}
    */
-  errors<U extends EffectErrorMap>(
-    errors: U,
-  ): EffectBuilder<
+  declare errors: EffectBuilderSurface<
     TInitialContext,
     TCurrentContext,
     TInputSchema,
     TOutputSchema,
-    MergedEffectErrorMap<TEffectErrorMap, U>,
+    TEffectErrorMap,
     TMeta,
     TRequirementsProvided,
     TRuntimeError
-  > {
-    const newEffectErrorMap: MergedEffectErrorMap<TEffectErrorMap, U> = {
-      ...this["~effect"].effectErrorMap,
-      ...errors,
-    };
-    return new EffectBuilder({
-      ...this["~effect"],
-      errorMap: effectErrorMapToErrorMap(newEffectErrorMap),
-      effectErrorMap: newEffectErrorMap,
-    });
-  }
-
+  >["errors"];
   /**
    * Uses a middleware to modify the context or improve the pipeline.
    *
@@ -375,52 +447,23 @@ export class EffectBuilder<
    * @note The current context must be satisfy middleware dependent-context
    * @see {@link https://orpc.dev/docs/middleware Middleware Docs}
    */
-  use<
-    UOutContext extends IntersectPick<TCurrentContext, UOutContext>,
-    UInContext extends Context = TCurrentContext,
-  >(
-    middleware: Middleware<
-      UInContext | TCurrentContext,
-      UOutContext,
-      InferSchemaOutput<TInputSchema>,
-      unknown,
-      EffectErrorConstructorMap<TEffectErrorMap>,
-      TMeta
-    >,
-  ): EffectBuilder<
-    MergedInitialContext<TInitialContext, UInContext, TCurrentContext>,
-    MergedCurrentContext<TCurrentContext, UOutContext>,
+  declare use: EffectBuilderSurface<
+    TInitialContext,
+    TCurrentContext,
     TInputSchema,
     TOutputSchema,
     TEffectErrorMap,
     TMeta,
     TRequirementsProvided,
     TRuntimeError
-  >;
-
-  use(
-    middleware: AnyMiddleware,
-    mapInput?: MapInputMiddleware<any, any>,
-  ): EffectBuilder<any, any, any, any, any, any, any, any> {
-    const mapped = mapInput
-      ? decorateMiddleware(middleware).mapInput(mapInput)
-      : middleware;
-
-    return new EffectBuilder({
-      ...this["~effect"],
-      middlewares: addMiddleware(this["~effect"].middlewares, mapped),
-    });
-  }
-
+  >["use"];
   /**
    * Sets or updates the metadata.
    * The provided metadata is spared-merged with any existing metadata.
    *
    * @see {@link https://orpc.dev/docs/metadata Metadata Docs}
    */
-  meta(
-    meta: TMeta,
-  ): EffectBuilder<
+  declare meta: EffectBuilderSurface<
     TInitialContext,
     TCurrentContext,
     TInputSchema,
@@ -429,13 +472,7 @@ export class EffectBuilder<
     TMeta,
     TRequirementsProvided,
     TRuntimeError
-  > {
-    return new EffectBuilder({
-      ...this["~effect"],
-      meta: mergeMeta(this["~effect"].meta, meta),
-    });
-  }
-
+  >["meta"];
   /**
    * Sets or updates the route definition.
    * The provided route is spared-merged with any existing route.
@@ -444,9 +481,7 @@ export class EffectBuilder<
    * @see {@link https://orpc.dev/docs/openapi/routing OpenAPI Routing Docs}
    * @see {@link https://orpc.dev/docs/openapi/input-output-structure OpenAPI Input/Output Structure Docs}
    */
-  route(
-    route: Route,
-  ): EffectBuilder<
+  declare route: EffectBuilderSurface<
     TInitialContext,
     TCurrentContext,
     TInputSchema,
@@ -455,76 +490,37 @@ export class EffectBuilder<
     TMeta,
     TRequirementsProvided,
     TRuntimeError
-  > {
-    return new EffectBuilder({
-      ...this["~effect"],
-      route: mergeRoute(this["~effect"].route, route),
-    });
-  }
-
+  >["route"];
   /**
    * Defines the input validation schema.
    *
    * @see {@link https://orpc.dev/docs/procedure#input-output-validation Input Validation Docs}
    */
-  input<USchema extends AnySchema>(
-    schema: USchema,
-  ): EffectProcedureBuilderWithInput<
+  declare input: EffectBuilderSurface<
     TInitialContext,
     TCurrentContext,
-    USchema,
+    TInputSchema,
     TOutputSchema,
     TEffectErrorMap,
     TMeta,
     TRequirementsProvided,
     TRuntimeError
-  > {
-    return new EffectBuilder({
-      ...this["~effect"],
-      inputSchema: schema,
-      inputValidationIndex:
-        fallbackConfig(
-          "initialInputValidationIndex",
-          this["~effect"].config.initialInputValidationIndex,
-        ) + this["~effect"].middlewares.length,
-      // we cast to any because EffectProcedureBuilderWithInput is expecting
-      // use() input type to be defined, and EffectBuilder types its use() input
-      // to unknown to allow any middleware to be passed
-      // ---
-      // note: the original implentation of the builder also uses any for the same reason
-    }) as any;
-  }
-
+  >["input"];
   /**
    * Defines the output validation schema.
    *
    * @see {@link https://orpc.dev/docs/procedure#input-output-validation Output Validation Docs}
    */
-  output<USchema extends AnySchema>(
-    schema: USchema,
-  ): EffectProcedureBuilderWithOutput<
+  declare output: EffectBuilderSurface<
     TInitialContext,
     TCurrentContext,
     TInputSchema,
-    USchema,
+    TOutputSchema,
     TEffectErrorMap,
     TMeta,
     TRequirementsProvided,
     TRuntimeError
-  > {
-    // We cast to any because EffectProcedureBuilderWithOutput narrows
-    // handler/effect output typing based on the declared output schema.
-    return new EffectBuilder({
-      ...this["~effect"],
-      outputSchema: schema,
-      outputValidationIndex:
-        fallbackConfig(
-          "initialOutputValidationIndex",
-          this["~effect"].config.initialOutputValidationIndex,
-        ) + this["~effect"].middlewares.length,
-    }) as any;
-  }
-
+  >["output"];
   /**
    * Adds a traceable span to the procedure for telemetry.
    * The span name is used for Effect tracing via `Effect.withSpan`.
@@ -544,9 +540,7 @@ export class EffectBuilder<
    *   })
    * ```
    */
-  traced(
-    spanName: string,
-  ): EffectBuilder<
+  declare traced: EffectBuilderSurface<
     TInitialContext,
     TCurrentContext,
     TInputSchema,
@@ -555,40 +549,22 @@ export class EffectBuilder<
     TMeta,
     TRequirementsProvided,
     TRuntimeError
-  > {
-    return new EffectBuilder({
-      ...this["~effect"],
-      spanConfig: {
-        name: spanName,
-        captureStackTrace: addSpanStackTrace(),
-      },
-    });
-  }
-
-  handler<UFuncOutput>(
-    handler: ProcedureHandler<
-      TCurrentContext,
-      InferSchemaOutput<TInputSchema>,
-      UFuncOutput,
-      EffectErrorMapToErrorMap<TEffectErrorMap>,
-      TMeta
-    >,
-  ): EffectDecoratedProcedure<
+  >["traced"];
+  /**
+   * Defines the handler of the procedure using a standard async/sync function.
+   *
+   * @see {@link https://orpc.dev/docs/procedure Procedure Docs}
+   */
+  declare handler: EffectBuilderSurface<
     TInitialContext,
     TCurrentContext,
     TInputSchema,
-    Schema<UFuncOutput, UFuncOutput>,
+    TOutputSchema,
     TEffectErrorMap,
     TMeta,
     TRequirementsProvided,
     TRuntimeError
-  > {
-    return new EffectDecoratedProcedure({
-      ...this["~effect"],
-      handler,
-    });
-  }
-
+  >["handler"];
   /**
    * Defines the handler of the procedure using an Effect.
    * The Effect is executed using the ManagedRuntime provided during builder creation.
@@ -596,42 +572,16 @@ export class EffectBuilder<
    *
    * @see {@link https://orpc.dev/docs/procedure Procedure Docs}
    */
-  effect<UFuncOutput>(
-    effectFn: EffectProcedureHandler<
-      TCurrentContext,
-      TInputSchema,
-      UFuncOutput,
-      TEffectErrorMap,
-      TRequirementsProvided,
-      TMeta
-    >,
-  ): EffectDecoratedProcedure<
+  declare effect: EffectBuilderSurface<
     TInitialContext,
     TCurrentContext,
     TInputSchema,
-    Schema<UFuncOutput, UFuncOutput>,
+    TOutputSchema,
     TEffectErrorMap,
     TMeta,
     TRequirementsProvided,
     TRuntimeError
-  > {
-    const { runtime, spanConfig } = this["~effect"];
-    // Capture stack trace at definition time for default tracing
-    const defaultCaptureStackTrace = addSpanStackTrace();
-    return new EffectDecoratedProcedure({
-      ...this["~effect"],
-      handler: async (opts) => {
-        return createEffectProcedureHandler({
-          runtime,
-          effectErrorMap: this["~effect"].effectErrorMap,
-          effectFn,
-          spanConfig,
-          defaultCaptureStackTrace,
-        })(opts as any);
-      },
-    });
-  }
-
+  >["effect"];
   /**
    * Prefixes all procedures in the router.
    * The provided prefix is post-appended to any existing router prefix.
@@ -640,85 +590,90 @@ export class EffectBuilder<
    *
    * @see {@link https://orpc.dev/docs/openapi/routing#route-prefixes OpenAPI Route Prefixes Docs}
    */
-  prefix(
-    prefix: HTTPPath,
-  ): EffectRouterBuilder<
+  declare prefix: EffectBuilderSurface<
     TInitialContext,
     TCurrentContext,
+    TInputSchema,
+    TOutputSchema,
     TEffectErrorMap,
     TMeta,
     TRequirementsProvided,
     TRuntimeError
-  > {
-    return new EffectBuilder({
-      ...this["~effect"],
-      prefix: mergePrefix(this["~effect"].prefix, prefix),
-    }) as any;
-  }
-
+  >["prefix"];
   /**
    * Adds tags to all procedures in the router.
    * This helpful when you want to group procedures together in the OpenAPI specification.
    *
    * @see {@link https://orpc.dev/docs/openapi/openapi-specification#operation-metadata OpenAPI Operation Metadata Docs}
    */
-  tag(
-    ...tags: string[]
-  ): EffectRouterBuilder<
+  declare tag: EffectBuilderSurface<
     TInitialContext,
     TCurrentContext,
+    TInputSchema,
+    TOutputSchema,
     TEffectErrorMap,
     TMeta,
     TRequirementsProvided,
     TRuntimeError
-  > {
-    return new EffectBuilder({
-      ...this["~effect"],
-      tags: mergeTags(this["~effect"].tags, tags),
-    }) as any;
-  }
-
+  >["tag"];
   /**
    * Applies all of the previously defined options to the specified router.
    *
    * @see {@link https://orpc.dev/docs/router#extending-router Extending Router Docs}
    */
-  router<U extends Router<ContractRouter<TMeta>, TCurrentContext>>(
-    router: U,
-  ): EnhancedEffectRouter<
-    U,
+  declare router: EffectBuilderSurface<
     TInitialContext,
     TCurrentContext,
-    TEffectErrorMap
-  > {
-    return enhanceEffectRouter(router, {
-      ...this["~effect"],
-    }) as any; // Type instantiation is excessively deep and possibly infinite
-  }
-
+    TInputSchema,
+    TOutputSchema,
+    TEffectErrorMap,
+    TMeta,
+    TRequirementsProvided,
+    TRuntimeError
+  >["router"];
   /**
    * Create a lazy router
    * And applies all of the previously defined options to the specified router.
    *
    * @see {@link https://orpc.dev/docs/router#extending-router Extending Router Docs}
    */
-  lazy<U extends Router<ContractRouter<TMeta>, TCurrentContext>>(
-    loader: () => Promise<{ default: U }>,
-  ): EnhancedEffectRouter<
-    Lazy<U>,
+  declare lazy: EffectBuilderSurface<
     TInitialContext,
     TCurrentContext,
-    TEffectErrorMap
-  > {
-    return enhanceEffectRouter(lazy(loader), {
-      ...this["~effect"],
-    }) as any; // Type instantiation is excessively deep and possibly infinite
+    TInputSchema,
+    TOutputSchema,
+    TEffectErrorMap,
+    TMeta,
+    TRequirementsProvided,
+    TRuntimeError
+  >["lazy"];
+
+  constructor(
+    def: EffectBuilderDef<
+      TInputSchema,
+      TOutputSchema,
+      TEffectErrorMap,
+      TMeta,
+      TRequirementsProvided,
+      TRuntimeError
+    >,
+    builder?: AnyBuilderLike,
+  ) {
+    const { runtime, spanConfig, effectErrorMap, ...orpcDef } = def;
+
+    attachEffectState(this, builder ?? new Builder(orpcDef), {
+      effectErrorMap,
+      runtime,
+      spanConfig,
+    });
+
+    return createEffectBuilderProxy(this);
   }
 }
 
 /**
  * Creates an Effect-aware procedure builder with the specified ManagedRuntime.
- * Uses the default `os` builder from `@orpc/server`.
+ * Uses the default builder shape from `@orpc/server`.
  *
  * @param runtime - The ManagedRuntime that provides services for Effect procedures
  * @returns An EffectBuilder instance for creating Effect-native procedures
@@ -819,23 +774,27 @@ export function makeEffectORPC<TRequirementsProvided, TRuntimeError>(
   TRuntimeError
 > {
   const resolvedBuilder = builder ?? emptyBuilder();
-  return new EffectBuilder({
-    ...resolvedBuilder["~orpc"],
-    errorMap: effectErrorMapToErrorMap(resolvedBuilder["~orpc"].errorMap),
-    effectErrorMap: resolvedBuilder["~orpc"].errorMap,
-    runtime,
-  });
+  const effectErrorMap = getEffectErrorMap(resolvedBuilder);
+  return new EffectBuilder(
+    {
+      ...resolvedBuilder["~orpc"],
+      effectErrorMap: effectErrorMap,
+      errorMap: effectErrorMapToErrorMap(effectErrorMap),
+      runtime,
+    },
+    unwrapEffectUpstream(resolvedBuilder),
+  );
 }
 
 function emptyBuilder(): AnyBuilderLike {
   return new Builder({
     config: {},
-    route: {},
-    meta: {},
+    dedupeLeadingMiddlewares: true,
     errorMap: {},
     inputValidationIndex: fallbackConfig("initialInputValidationIndex"),
-    outputValidationIndex: fallbackConfig("initialOutputValidationIndex"),
+    meta: {},
     middlewares: [],
-    dedupeLeadingMiddlewares: true,
+    outputValidationIndex: fallbackConfig("initialOutputValidationIndex"),
+    route: {},
   });
 }