effect-orpc 0.1.4 → 0.2.1

package/src/types/index.ts

@@ -4,12 +4,10 @@ import type {
   ErrorMap,
   ErrorMapItem,
   Meta,
-  Route,
   Schema,
 } from "@orpc/contract";
 import type {
   Builder,
-  BuilderConfig,
   BuilderDef,
   BuilderWithMiddlewares,
   Context,
@@ -22,7 +20,6 @@ import type {
   ProcedureHandlerOptions,
   RouterBuilder,
 } from "@orpc/server";
-import type { Promisable } from "@orpc/shared";
 import type { Effect, ManagedRuntime } from "effect";
 import type { YieldWrap } from "effect/Utils";
 
@@ -33,6 +30,19 @@ import type {
   ORPCTaggedErrorInstance,
 } from "../tagged-error";
 
+type EffectBuilderDefBase<
+  TInputSchema extends AnySchema,
+  TOutputSchema extends AnySchema,
+  TEffectErrorMap extends EffectErrorMap,
+  TMeta extends Meta,
+> = EnhanceRouterOptions<EffectErrorMapToErrorMap<TEffectErrorMap>> &
+  BuilderDef<
+    TInputSchema,
+    TOutputSchema,
+    EffectErrorMapToErrorMap<TEffectErrorMap>,
+    TMeta
+  >;
+
 /**
  * Extended builder definition that includes the Effect ManagedRuntime.
  */
@@ -43,14 +53,12 @@ export interface EffectBuilderDef<
   TMeta extends Meta,
   TRequirementsProvided,
   TRuntimeError,
-> extends EnhanceRouterOptions<EffectErrorMapToErrorMap<TEffectErrorMap>> {
-  inputValidationIndex: number;
-  outputValidationIndex: number;
-  config: BuilderConfig;
-  meta: TMeta;
-  route: Route;
-  inputSchema?: TInputSchema;
-  outputSchema?: TOutputSchema;
+> extends EffectBuilderDefBase<
+  TInputSchema,
+  TOutputSchema,
+  TEffectErrorMap,
+  TMeta
+> {
   runtime: ManagedRuntime.ManagedRuntime<TRequirementsProvided, TRuntimeError>;
   /**
    * Optional span configuration for Effect tracing.
@@ -62,21 +70,6 @@ export interface EffectBuilderDef<
   effectErrorMap: TEffectErrorMap;
 }
 
-export type NonEffectProcedureHandler<
-  TCurrentContext extends Context,
-  TInput,
-  THandlerOutput,
-  TEffectErrorMap extends EffectErrorMap,
-  TMeta extends Meta,
-> = (
-  opt: ProcedureHandlerOptions<
-    TCurrentContext,
-    TInput,
-    EffectErrorConstructorMap<TEffectErrorMap>,
-    TMeta
-  >,
-) => Promisable<THandlerOutput>;
-
 /**
  * Extended procedure definition that includes the Effect ManagedRuntime.
  */
@@ -429,4 +422,7 @@ export type InferBuilderMeta<T> =
                 ? TMeta
                 : Meta;
 
+export type { EffectBuilderSurface } from "./effect-builder-surface";
+export type { EffectDecoratedProcedureSurface } from "./effect-procedure-surface";
+
 export * from "./variants";

package/src/types/variants.ts

@@ -21,6 +21,7 @@ import type {
   MergedCurrentContext,
   MergedInitialContext,
   Middleware,
+  ProcedureHandler,
   Router,
 } from "@orpc/server";
 
@@ -201,12 +202,11 @@ export interface EffectBuilderWithMiddlewares<
    * @see {@link https://orpc.dev/docs/procedure Procedure Docs}
    */
   "handler"<UFuncOutput>(
-    handler: EffectProcedureHandler<
+    handler: ProcedureHandler<
       TCurrentContext,
       unknown,
       UFuncOutput,
-      TEffectErrorMap,
-      TRequirementsProvided,
+      EffectErrorMapToErrorMap<TEffectErrorMap>,
       TMeta
     >,
   ): EffectDecoratedProcedure<
@@ -220,6 +220,13 @@ export interface EffectBuilderWithMiddlewares<
     TRuntimeError
   >;
 
+  /**
+   * Defines the handler of the procedure using an Effect.
+   * The Effect is executed using the ManagedRuntime provided during builder creation.
+   * The effect is automatically wrapped with `Effect.withSpan`.
+   *
+   * @see {@link https://orpc.dev/docs/procedure Procedure Docs}
+   */
   "effect"<UFuncOutput>(
     effectFn: EffectProcedureHandler<
       TCurrentContext,
@@ -240,6 +247,14 @@ export interface EffectBuilderWithMiddlewares<
     TRuntimeError
   >;
 
+  /**
+   * Adds a traceable span to the procedure for telemetry.
+   * The span name is used for Effect tracing via `Effect.withSpan`.
+   * Stack trace is captured at the call site for better error reporting.
+   *
+   * @param spanName - The name of the span for telemetry (e.g., 'users.getUser')
+   * @returns A traced procedure builder
+   */
   "traced"(
     spanName: string,
   ): EffectProcedureBuilderWithInput<
@@ -476,12 +491,11 @@ export interface EffectProcedureBuilder<
    * @see {@link https://orpc.dev/docs/procedure Procedure Docs}
    */
   "handler"<UFuncOutput>(
-    handler: EffectProcedureHandler<
+    handler: ProcedureHandler<
       TCurrentContext,
       unknown,
       UFuncOutput,
-      TEffectErrorMap,
-      TRequirementsProvided,
+      EffectErrorMapToErrorMap<TEffectErrorMap>,
       TMeta
     >,
   ): EffectDecoratedProcedure<
@@ -495,6 +509,13 @@ export interface EffectProcedureBuilder<
     TRuntimeError
   >;
 
+  /**
+   * Defines the handler of the procedure using an Effect.
+   * The Effect is executed using the ManagedRuntime provided during builder creation.
+   * The effect is automatically wrapped with `Effect.withSpan`.
+   *
+   * @see {@link https://orpc.dev/docs/procedure Procedure Docs}
+   */
   "effect"<UFuncOutput>(
     effectFn: EffectProcedureHandler<
       TCurrentContext,
@@ -514,6 +535,27 @@ export interface EffectProcedureBuilder<
     TRequirementsProvided,
     TRuntimeError
   >;
+
+  /**
+   * Adds a traceable span to the procedure for telemetry.
+   * The span name is used for Effect tracing via `Effect.withSpan`.
+   * Stack trace is captured at the call site for better error reporting.
+   *
+   * @param spanName - The name of the span for telemetry (e.g., 'users.getUser')
+   * @returns A traced procedure builder
+   */
+  "traced"(
+    spanName: string,
+  ): EffectProcedureBuilder<
+    TInitialContext,
+    TCurrentContext,
+    TInputSchema,
+    TOutputSchema,
+    TEffectErrorMap,
+    TMeta,
+    TRequirementsProvided,
+    TRuntimeError
+  >;
 }
 
 export interface EffectProcedureBuilderWithInput<
@@ -694,12 +736,11 @@ export interface EffectProcedureBuilderWithInput<
    * @see {@link https://orpc.dev/docs/procedure Procedure Docs}
    */
   "handler"<UFuncOutput>(
-    handler: EffectProcedureHandler<
+    handler: ProcedureHandler<
       TCurrentContext,
       InferSchemaOutput<TInputSchema>,
       UFuncOutput,
-      TEffectErrorMap,
-      TRequirementsProvided,
+      EffectErrorMapToErrorMap<TEffectErrorMap>,
       TMeta
     >,
   ): EffectDecoratedProcedure<
@@ -713,6 +754,13 @@ export interface EffectProcedureBuilderWithInput<
     TRuntimeError
   >;
 
+  /**
+   * Defines the handler of the procedure using an Effect.
+   * The Effect is executed using the ManagedRuntime provided during builder creation.
+   * The effect is automatically wrapped with `Effect.withSpan`.
+   *
+   * @see {@link https://orpc.dev/docs/procedure Procedure Docs}
+   */
   "effect"<UFuncOutput>(
     effectFn: EffectProcedureHandler<
       TCurrentContext,
@@ -733,6 +781,14 @@ export interface EffectProcedureBuilderWithInput<
     TRuntimeError
   >;
 
+  /**
+   * Adds a traceable span to the procedure for telemetry.
+   * The span name is used for Effect tracing via `Effect.withSpan`.
+   * Stack trace is captured at the call site for better error reporting.
+   *
+   * @param spanName - The name of the span for telemetry (e.g., 'users.getUser')
+   * @returns A traced procedure builder
+   */
   "traced"(
     spanName: string,
   ): EffectProcedureBuilderWithInput<
@@ -791,7 +847,7 @@ export interface EffectProcedureBuilderWithOutput<
     TCurrentContext,
     TInputSchema,
     TOutputSchema,
-    TEffectErrorMap,
+    MergedEffectErrorMap<TEffectErrorMap, U>,
     TMeta,
     TRequirementsProvided,
     TRuntimeError
@@ -891,12 +947,11 @@ export interface EffectProcedureBuilderWithOutput<
    * @see {@link https://orpc.dev/docs/procedure Procedure Docs}
    */
   "handler"(
-    handler: EffectProcedureHandler<
+    handler: ProcedureHandler<
       TCurrentContext,
       unknown,
       InferSchemaInput<TOutputSchema>,
-      TEffectErrorMap,
-      TRequirementsProvided,
+      EffectErrorMapToErrorMap<TEffectErrorMap>,
       TMeta
     >,
   ): EffectDecoratedProcedure<
@@ -910,6 +965,13 @@ export interface EffectProcedureBuilderWithOutput<
     TRuntimeError
   >;
 
+  /**
+   * Defines the handler of the procedure using an Effect.
+   * The Effect is executed using the ManagedRuntime provided during builder creation.
+   * The effect is automatically wrapped with `Effect.withSpan`.
+   *
+   * @see {@link https://orpc.dev/docs/procedure Procedure Docs}
+   */
   "effect"(
     effectFn: EffectProcedureHandler<
       TCurrentContext,
@@ -930,6 +992,14 @@ export interface EffectProcedureBuilderWithOutput<
     TRuntimeError
   >;
 
+  /**
+   * Adds a traceable span to the procedure for telemetry.
+   * The span name is used for Effect tracing via `Effect.withSpan`.
+   * Stack trace is captured at the call site for better error reporting.
+   *
+   * @param spanName - The name of the span for telemetry (e.g., 'users.getUser')
+   * @returns A traced procedure builder
+   */
   "traced"(
     spanName: string,
   ): EffectProcedureBuilderWithInput<
@@ -1104,12 +1174,11 @@ export interface EffectProcedureBuilderWithInputOutput<
    * @see {@link https://orpc.dev/docs/procedure Procedure Docs}
    */
   "handler"(
-    handler: EffectProcedureHandler<
+    handler: ProcedureHandler<
       TCurrentContext,
       InferSchemaOutput<TInputSchema>,
       InferSchemaInput<TOutputSchema>,
-      TEffectErrorMap,
-      TRequirementsProvided,
+      EffectErrorMapToErrorMap<TEffectErrorMap>,
       TMeta
     >,
   ): EffectDecoratedProcedure<
@@ -1123,6 +1192,13 @@ export interface EffectProcedureBuilderWithInputOutput<
     TRuntimeError
   >;
 
+  /**
+   * Defines the handler of the procedure using an Effect.
+   * The Effect is executed using the ManagedRuntime provided during builder creation.
+   * The effect is automatically wrapped with `Effect.withSpan`.
+   *
+   * @see {@link https://orpc.dev/docs/procedure Procedure Docs}
+   */
   "effect"(
     effectFn: EffectProcedureHandler<
       TCurrentContext,
@@ -1143,6 +1219,14 @@ export interface EffectProcedureBuilderWithInputOutput<
     TRuntimeError
   >;
 
+  /**
+   * Adds a traceable span to the procedure for telemetry.
+   * The span name is used for Effect tracing via `Effect.withSpan`.
+   * Stack trace is captured at the call site for better error reporting.
+   *
+   * @param spanName - The name of the span for telemetry (e.g., 'users.getUser')
+   * @returns A traced procedure builder
+   */
   "traced"(
     spanName: string,
   ): EffectProcedureBuilderWithInput<