effect-orpc 0.2.1 → 0.3.0

package/src/effect-procedure.ts

@@ -9,14 +9,22 @@ import type {
   ProcedureDef,
 } from "@orpc/server";
 import {
+  Procedure,
   addMiddleware,
   createActionableClient,
   createProcedureClient,
   decorateMiddleware,
-  Procedure,
 } from "@orpc/server";
 import type { MaybeOptionalOptions } from "@orpc/shared";
+import { Layer } from "effect";
 
+import {
+  createEffectOptionalProviderMiddleware,
+  createEffectPipelineMiddleware,
+  createEffectProcedureHandler,
+  createEffectProviderMiddleware,
+  isEffectMiddleware,
+} from "./effect-runtime";
 import { composeSurfaceProxy } from "./extension/compose-surfaces";
 import {
   createNodeProxy,
@@ -30,7 +38,11 @@ import {
 } from "./extension/state";
 import type { EffectErrorMap, MergedEffectErrorMap } from "./tagged-error";
 import { effectErrorMapToErrorMap } from "./tagged-error";
-import type { EffectErrorMapToErrorMap, EffectProcedureDef } from "./types";
+import type {
+  EffectErrorMapToErrorMap,
+  EffectPipelineStep,
+  EffectProcedureDef,
+} from "./types";
 import type { EffectDecoratedProcedureSurface } from "./types/effect-procedure-surface";
 
 type AnyProcedureLike = Procedure<any, any, any, any, any, any>;
@@ -66,6 +78,8 @@ const procedureVirtualDescriptors = {
   callable: { enumerable: false },
   errors: { enumerable: false },
   meta: { enumerable: false },
+  provide: { enumerable: false },
+  provideOptional: { enumerable: false },
   route: { enumerable: false },
   use: { enumerable: false },
 } as const;
@@ -75,6 +89,8 @@ const decoratedProcedureVirtualKeys = [
   ...baseProcedureVirtualKeys,
   "errors",
   "meta",
+  "provide",
+  "provideOptional",
   "route",
   "use",
   "callable",
@@ -101,11 +117,69 @@ function getEffectProcedureDef(
 ): EffectProcedureDef<any, any, any, any, any, any, any, any> {
   return {
     ...context.upstream["~orpc"],
+    effectSteps: context.state.effectSteps,
+    effectHandler: context.state.effectHandler,
     effectErrorMap: context.state.effectErrorMap,
     runtime: context.state.runtime,
   };
 }
 
+function makeEffectProcedureHandler(
+  def: EffectProcedureDef<any, any, any, any, any, any, any, any>,
+) {
+  if (!def.effectHandler) {
+    return def.handler;
+  }
+
+  return createEffectProcedureHandler({
+    defaultCaptureStackTrace: def.effectHandler.defaultCaptureStackTrace,
+    effectErrorMap: def.effectErrorMap,
+    effectFn: def.effectHandler.effectFn,
+    effectSteps: def.effectSteps,
+    runtime: def.runtime,
+    spanConfig: def.effectHandler.spanConfig,
+  });
+}
+
+function withRebuiltEffectHandler(
+  def: EffectProcedureDef<any, any, any, any, any, any, any, any>,
+): EffectProcedureDef<any, any, any, any, any, any, any, any> {
+  return {
+    ...def,
+    handler: makeEffectProcedureHandler(def),
+  };
+}
+
+function appendEffectStep(
+  def: EffectProcedureDef<any, any, any, any, any, any, any, any>,
+  step: EffectPipelineStep,
+): EffectProcedureDef<any, any, any, any, any, any, any, any> {
+  return withRebuiltEffectHandler({
+    ...def,
+    effectSteps: [...(def.effectSteps ?? []), step],
+  });
+}
+
+function flushEffectSteps(
+  def: EffectProcedureDef<any, any, any, any, any, any, any, any>,
+): EffectProcedureDef<any, any, any, any, any, any, any, any> {
+  if (!def.effectSteps?.length) {
+    return def;
+  }
+
+  const middleware = createEffectPipelineMiddleware({
+    effectErrorMap: def.effectErrorMap,
+    runtime: def.runtime,
+    steps: def.effectSteps,
+  });
+
+  return withRebuiltEffectHandler({
+    ...def,
+    effectSteps: undefined,
+    middlewares: addMiddleware(def.middlewares, middleware),
+  });
+}
+
 function createEffectProcedureProxy<
   T extends AnyEffectProcedure | AnyEffectDecoratedProcedure,
 >(
@@ -158,22 +232,113 @@ function createEffectProcedureProxy<
                 route: mergeRoute(getEffectProcedureDef(context).route, route),
               });
           });
+        case "provide":
+          return getOrCreateVirtualMethod(context, prop, () => {
+            return (tagOrLayer: any, provider?: any) => {
+              const def = getEffectProcedureDef(context);
+
+              if (Layer.isLayer(tagOrLayer)) {
+                const step = {
+                  _tag: "provideLayer" as const,
+                  layer: tagOrLayer,
+                };
+
+                if (def.effectHandler) {
+                  return new EffectDecoratedProcedure(
+                    appendEffectStep(def, step),
+                  );
+                }
+
+                return new EffectDecoratedProcedure({
+                  ...def,
+                  middlewares: addMiddleware(
+                    def.middlewares,
+                    createEffectPipelineMiddleware({
+                      effectErrorMap: state.effectErrorMap,
+                      runtime: state.runtime,
+                      steps: [step],
+                    }),
+                  ),
+                });
+              }
+
+              if (def.effectHandler) {
+                return new EffectDecoratedProcedure(
+                  appendEffectStep(def, {
+                    _tag: "provide",
+                    provider,
+                    tag: tagOrLayer,
+                  }),
+                );
+              }
+
+              return new EffectDecoratedProcedure({
+                ...def,
+                middlewares: addMiddleware(
+                  def.middlewares,
+                  createEffectProviderMiddleware({
+                    effectErrorMap: state.effectErrorMap,
+                    provider,
+                    runtime: state.runtime,
+                    tag: tagOrLayer,
+                  }),
+                ),
+              });
+            };
+          });
+        case "provideOptional":
+          return getOrCreateVirtualMethod(context, prop, () => {
+            return (tag: any, provider: any) => {
+              const def = getEffectProcedureDef(context);
+
+              if (def.effectHandler) {
+                return new EffectDecoratedProcedure(
+                  appendEffectStep(def, {
+                    _tag: "provideOptional",
+                    provider,
+                    tag,
+                  }),
+                );
+              }
+
+              return new EffectDecoratedProcedure({
+                ...def,
+                middlewares: addMiddleware(
+                  def.middlewares,
+                  createEffectOptionalProviderMiddleware({
+                    effectErrorMap: state.effectErrorMap,
+                    provider,
+                    runtime: state.runtime,
+                    tag,
+                  }),
+                ),
+              });
+            };
+          });
         case "use":
           return getOrCreateVirtualMethod(context, prop, () => {
             return (
               middleware: AnyMiddleware,
               mapInput?: MapInputMiddleware<any, any>,
             ) => {
+              const def = getEffectProcedureDef(context);
+              if (!mapInput && isEffectMiddleware(middleware)) {
+                return new EffectDecoratedProcedure(
+                  appendEffectStep(def, {
+                    _tag: "middleware",
+                    middleware,
+                  }),
+                );
+              }
+
+              const flushedDef = flushEffectSteps(def);
               const mapped = mapInput
                 ? decorateMiddleware(middleware).mapInput(mapInput)
                 : middleware;
 
               return new EffectDecoratedProcedure({
-                ...getEffectProcedureDef(context),
-                middlewares: addMiddleware(
-                  getEffectProcedureDef(context).middlewares,
-                  mapped,
-                ),
+                ...flushedDef,
+                middlewares: addMiddleware(flushedDef.middlewares, mapped),
               });
             };
           });
@@ -264,6 +429,9 @@ export class EffectProcedure<
   EffectErrorMapToErrorMap<TEffectErrorMap>,
   TMeta
 > {
+  /**
+   * This property holds the defined options and the effect-specific properties.
+   */
   declare "~effect": EffectProcedureDef<
     TInitialContext,
     TCurrentContext,
@@ -274,6 +442,9 @@ export class EffectProcedure<
     TRequirementsProvided,
     TRuntimeError
   >;
+  /**
+   * This property holds the defined options.
+   */
   declare "~orpc": ProcedureDef<
     TInitialContext,
     TCurrentContext,
@@ -296,8 +467,11 @@ export class EffectProcedure<
     >,
     procedure?: AnyProcedureLike,
   ) {
-    super(def);
-    attachEffectState(this, procedure ?? new Procedure(def), {
+    const { effectSteps, effectHandler, ...procedureDef } = def;
+    super(procedureDef);
+    attachEffectState(this, procedure ?? new Procedure(procedureDef), {
+      effectSteps,
+      effectHandler,
       effectErrorMap: def.effectErrorMap,
       runtime: def.runtime,
     });
@@ -346,6 +520,12 @@ export class EffectDecoratedProcedure<
       TRuntimeError
     >
 {
+  /**
+   * Adds type-safe custom errors.
+   * Supports both traditional oRPC error definitions and ORPCTaggedError classes.
+   *
+   * @see {@link https://orpc.dev/docs/error-handling#type%E2%80%90safe-error-handling Type-Safe Error Handling Docs}
+   */
   declare errors: EffectDecoratedProcedureSurface<
     TInitialContext,
     TCurrentContext,
@@ -356,6 +536,12 @@ export class EffectDecoratedProcedure<
     TRequirementsProvided,
     TRuntimeError
   >["errors"];
+  /**
+   * Sets or updates the metadata.
+   * The provided metadata is spared-merged with any existing metadata.
+   *
+   * @see {@link https://orpc.dev/docs/metadata Metadata Docs}
+   */
   declare meta: EffectDecoratedProcedureSurface<
     TInitialContext,
     TCurrentContext,
@@ -366,6 +552,14 @@ export class EffectDecoratedProcedure<
     TRequirementsProvided,
     TRuntimeError
   >["meta"];
+  /**
+   * Sets or updates the route definition.
+   * The provided route is spared-merged with any existing route.
+   * This option is typically relevant when integrating with OpenAPI.
+   *
+   * @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}
+   */
   declare route: EffectDecoratedProcedureSurface<
     TInitialContext,
     TCurrentContext,
@@ -376,6 +570,40 @@ export class EffectDecoratedProcedure<
     TRequirementsProvided,
     TRuntimeError
   >["route"];
+  /**
+   * Provides a request-scoped Effect service to downstream procedures.
+   */
+  declare provide: EffectDecoratedProcedureSurface<
+    TInitialContext,
+    TCurrentContext,
+    TInputSchema,
+    TOutputSchema,
+    TEffectErrorMap,
+    TMeta,
+    TRequirementsProvided,
+    TRuntimeError
+  >["provide"];
+  /**
+   * Optionally provides a request-scoped Effect service to downstream procedures.
+   */
+  declare provideOptional: EffectDecoratedProcedureSurface<
+    TInitialContext,
+    TCurrentContext,
+    TInputSchema,
+    TOutputSchema,
+    TEffectErrorMap,
+    TMeta,
+    TRequirementsProvided,
+    TRuntimeError
+  >["provideOptional"];
+  /**
+   * Uses a middleware to modify the context or improve the pipeline.
+   *
+   * @info Supports both normal middleware and inline middleware implementations.
+   * @info Pass second argument to map the input.
+   * @note The current context must be satisfy middleware dependent-context
+   * @see {@link https://orpc.dev/docs/middleware Middleware Docs}
+   */
   declare use: EffectDecoratedProcedureSurface<
     TInitialContext,
     TCurrentContext,
@@ -386,6 +614,11 @@ export class EffectDecoratedProcedure<
     TRequirementsProvided,
     TRuntimeError
   >["use"];
+  /**
+   * Make this procedure callable (works like a function while still being a procedure).
+   *
+   * @see {@link https://orpc.dev/docs/client/server-side Server-side Client Docs}
+   */
   declare callable: EffectDecoratedProcedureSurface<
     TInitialContext,
     TCurrentContext,
@@ -396,6 +629,11 @@ export class EffectDecoratedProcedure<
     TRequirementsProvided,
     TRuntimeError
   >["callable"];
+  /**
+   * Make this procedure compatible with server action.
+   *
+   * @see {@link https://orpc.dev/docs/server-action Server Action Docs}
+   */
   declare actionable: EffectDecoratedProcedureSurface<
     TInitialContext,
     TCurrentContext,