effect-orpc 0.3.0 → 0.5.0

package/src/tests/effect-callback-shapes.test.ts

@@ -0,0 +1,410 @@
+import { oc } from "@orpc/contract";
+import { call, createRouterClient } from "@orpc/server";
+import type { Context as ORPCContext } from "@orpc/server";
+import { Context, Effect, Layer, ManagedRuntime, Option, Tracer } from "effect";
+import { describe, expect, it } from "vitest";
+import z from "zod";
+
+import { implementEffect } from "../contract";
+import { eos, makeEffectORPC } from "../effect-builder";
+import type { EffectOrORPCMiddleware } from "../types";
+
+type TestMiddleware<
+  TOutContext extends ORPCContext = { readonly value: string },
+> = EffectOrORPCMiddleware<
+  ORPCContext | Record<never, never>,
+  TOutContext,
+  unknown,
+  unknown,
+  Record<never, never>,
+  never,
+  Record<never, never>
+>;
+
+type TestMiddlewareOptions = Parameters<TestMiddleware>[0];
+type SpanMiddlewareOptions = Parameters<
+  TestMiddleware<Record<never, never>>
+>[0];
+
+type MiddlewareShape = {
+  readonly name: string;
+  readonly middleware: TestMiddleware;
+  readonly expected: string;
+};
+
+function effectHandlerShapes() {
+  return [
+    {
+      name: "function*",
+      handler: function* ({ input }: { input: number }) {
+        const increment = yield* Effect.succeed(1);
+        return input + increment;
+      },
+    },
+    {
+      name: "named Effect.fn",
+      handler: Effect.fn("test.effect.named")(function* ({
+        input,
+      }: {
+        input: number;
+      }) {
+        const increment = yield* Effect.succeed(1);
+        return input + increment;
+      }),
+    },
+    {
+      name: "anonymous Effect.fn",
+      handler: Effect.fn(function* ({ input }: { input: number }) {
+        const increment = yield* Effect.succeed(1);
+        return input + increment;
+      }),
+    },
+    {
+      name: "Effect.gen-returning function",
+      handler: ({ input }: { input: number }) =>
+        Effect.gen(function* () {
+          const increment = yield* Effect.succeed(1);
+          return input + increment;
+        }),
+    },
+  ] as const;
+}
+
+function providerShapes(suffix: string) {
+  return [
+    {
+      name: "function*",
+      provider: function* ({ context }: { context: { value: string } }) {
+        yield* Effect.void;
+        return { value: `${context.value}:${suffix}:generator` };
+      },
+    },
+    {
+      name: "named Effect.fn",
+      provider: Effect.fn("test.provider.named")(function* ({
+        context,
+      }: {
+        context: { value: string };
+      }) {
+        yield* Effect.void;
+        return { value: `${context.value}:${suffix}:named` };
+      }),
+    },
+    {
+      name: "anonymous Effect.fn",
+      provider: Effect.fn(function* ({
+        context,
+      }: {
+        context: { value: string };
+      }) {
+        yield* Effect.void;
+        return { value: `${context.value}:${suffix}:anonymous` };
+      }),
+    },
+    {
+      name: "Effect.gen-returning function",
+      provider: ({ context }: { context: { value: string } }) =>
+        Effect.gen(function* () {
+          yield* Effect.void;
+          return { value: `${context.value}:${suffix}:effect-gen` };
+        }),
+    },
+  ] as const;
+}
+
+function optionalProviderShapes(suffix: string) {
+  return [
+    {
+      name: "function*",
+      provider: function* ({ context }: { context: { value?: string } }) {
+        yield* Effect.void;
+        return Option.map(Option.fromNullable(context.value), (value) => ({
+          value: `${value}:${suffix}:generator`,
+        }));
+      },
+    },
+    {
+      name: "named Effect.fn",
+      provider: Effect.fn("test.optional-provider.named")(function* ({
+        context,
+      }: {
+        context: { value?: string };
+      }) {
+        yield* Effect.void;
+        return Option.map(Option.fromNullable(context.value), (value) => ({
+          value: `${value}:${suffix}:named`,
+        }));
+      }),
+    },
+    {
+      name: "anonymous Effect.fn",
+      provider: Effect.fn(function* ({
+        context,
+      }: {
+        context: { value?: string };
+      }) {
+        yield* Effect.void;
+        return Option.map(Option.fromNullable(context.value), (value) => ({
+          value: `${value}:${suffix}:anonymous`,
+        }));
+      }),
+    },
+    {
+      name: "Effect.gen-returning function",
+      provider: ({ context }: { context: { value?: string } }) =>
+        Effect.gen(function* () {
+          yield* Effect.void;
+          return Option.map(Option.fromNullable(context.value), (value) => ({
+            value: `${value}:${suffix}:effect-gen`,
+          }));
+        }),
+    },
+  ] as const;
+}
+
+function middlewareShapes(): ReadonlyArray<MiddlewareShape> {
+  return [
+    {
+      name: "native guard-only function",
+      middleware: () => {},
+      expected: "handler",
+    },
+    {
+      name: "native next-returning function",
+      middleware: ({ next }) => next({ context: { value: "native-next" } }),
+      expected: "native-next",
+    },
+    {
+      name: "function*",
+      middleware: function* ({ next }: TestMiddlewareOptions) {
+        yield* Effect.void;
+        return yield* next({ context: { value: "generator" } });
+      },
+      expected: "generator",
+    },
+    {
+      name: "named Effect.fn",
+      middleware: Effect.fn("test.middleware.named")(function* ({
+        next,
+      }: TestMiddlewareOptions) {
+        yield* Effect.void;
+        return yield* next({ context: { value: "named" } });
+      }),
+      expected: "named",
+    },
+    {
+      name: "anonymous Effect.fn",
+      middleware: Effect.fn(function* ({ next }: TestMiddlewareOptions) {
+        yield* Effect.void;
+        return yield* next({ context: { value: "anonymous" } });
+      }),
+      expected: "anonymous",
+    },
+    {
+      name: "Effect.gen-returning function",
+      middleware: ({ next }) =>
+        Effect.gen(function* () {
+          yield* Effect.void;
+          return yield* next({ context: { value: "effect-gen" } });
+        }),
+      expected: "effect-gen",
+    },
+    {
+      name: "Effect.gen-returning guard-only function",
+      middleware: () =>
+        Effect.gen(function* () {
+          yield* Effect.void;
+        }),
+      expected: "handler",
+    },
+  ];
+}
+
+describe("Effect callback shapes", () => {
+  for (const { name, handler } of effectHandlerShapes()) {
+    it(`.effect supports ${name}`, async () => {
+      const procedure = eos.input(z.number()).effect(handler);
+
+      await expect(call(procedure, 41)).resolves.toBe(42);
+    });
+  }
+
+  it("contract implementer .effect supports Effect-returning handlers", async () => {
+    const contract = {
+      increment: oc.input(z.number()).output(z.number()),
+    };
+    const implementer = implementEffect(contract, Layer.empty);
+
+    const named = implementer.increment.effect(
+      Effect.fn("test.contract.effect")(function* ({ input }) {
+        const increment = yield* Effect.succeed(1);
+        return input + increment;
+      }),
+    );
+
+    await expect(call(named, 41)).resolves.toBe(42);
+  });
+
+  for (const { name, provider } of providerShapes("provide")) {
+    it(`.provide supports ${name}`, async () => {
+      class RequestValue extends Context.Tag(`RequestValue:${name}`)<
+        RequestValue,
+        { readonly value: string }
+      >() {}
+
+      const procedure = eos
+        .$context<{ value: string }>()
+        .provide(RequestValue, provider)
+        .effect(function* () {
+          const service = yield* RequestValue;
+          return service.value;
+        });
+
+      await expect(
+        call(procedure, undefined, { context: { value: "request" } }),
+      ).resolves.toContain("request:provide");
+    });
+  }
+
+  for (const { name, provider } of optionalProviderShapes("optional")) {
+    it(`.provideOptional supports ${name}`, async () => {
+      class RequestValue extends Context.Tag(`OptionalRequestValue:${name}`)<
+        RequestValue,
+        { readonly value: string }
+      >() {}
+
+      const procedure = eos
+        .$context<{ value?: string }>()
+        .provideOptional(RequestValue, provider)
+        .effect(function* () {
+          return yield* Effect.serviceOption(RequestValue);
+        });
+
+      await expect(
+        call(procedure, undefined, { context: { value: "request" } }),
+      ).resolves.toSatisfy(
+        (option: Option.Option<{ readonly value: string }>) =>
+          Option.isSome(option) &&
+          option.value.value.includes("request:optional"),
+      );
+      await expect(
+        call(procedure, undefined, { context: {} }),
+      ).resolves.toEqual(Option.none());
+    });
+  }
+
+  for (const { name, middleware, expected } of middlewareShapes()) {
+    it(`.use supports ${name}`, async () => {
+      const procedure = eos.use(middleware).effect(function* ({ context }) {
+        return "value" in context ? context.value : "handler";
+      });
+
+      await expect(call(procedure, undefined)).resolves.toBe(expected);
+    });
+  }
+
+  for (const { name, middleware, expected } of middlewareShapes().filter(
+    ({ name }) => !name.startsWith("native"),
+  )) {
+    it(`.middleware supports ${name}`, async () => {
+      const reusable = eos.middleware(middleware);
+      const procedure = eos.use(reusable).effect(function* ({ context }) {
+        return "value" in context ? context.value : "handler";
+      });
+
+      await expect(call(procedure, undefined)).resolves.toBe(expected);
+    });
+  }
+
+  it("Effect handlers keep their own spans inside routed procedure spans", async () => {
+    const spans: Array<{
+      readonly name: string;
+      readonly parentName: string | undefined;
+    }> = [];
+    const spanNamesById = new Map<string, string>();
+    const tracer = Tracer.make({
+      context: (f) => f(),
+      span(name, parent, context, links, startTime, kind) {
+        const spanId = `span-${spans.length + 1}`;
+        spans.push({
+          name,
+          parentName: Option.match(parent, {
+            onNone: () => undefined,
+            onSome: (span) => spanNamesById.get(span.spanId),
+          }),
+        });
+        spanNamesById.set(spanId, name);
+        const attributes = new Map<string, unknown>();
+
+        return {
+          _tag: "Span" as const,
+          name,
+          spanId,
+          traceId: "trace",
+          parent,
+          context,
+          status: { _tag: "Started" as const, startTime },
+          attributes,
+          links,
+          sampled: true,
+          kind,
+          end() {},
+          attribute(key: string, value: unknown) {
+            attributes.set(key, value);
+          },
+          event() {},
+          addLinks() {},
+        };
+      },
+    });
+    const tracedRuntime = ManagedRuntime.make(Layer.setTracer(tracer));
+    const effectFnProcedure = makeEffectORPC(tracedRuntime)
+      .use(
+        Effect.fn("custom.middleware.span")(function* ({
+          next,
+        }: SpanMiddlewareOptions) {
+          return yield* next();
+        }),
+      )
+      .effect(
+        Effect.fn("custom.handler.span")(function* () {
+          return "ok";
+        }),
+      );
+    const withSpanProcedure = makeEffectORPC(tracedRuntime).effect(() =>
+      Effect.succeed("ok").pipe(Effect.withSpan("custom.with-span.handler")),
+    );
+    const client = createRouterClient({
+      users: {
+        effectFn: effectFnProcedure,
+        withSpan: withSpanProcedure,
+      },
+    });
+
+    try {
+      await expect(client.users.effectFn(undefined)).resolves.toBe("ok");
+      await expect(client.users.withSpan(undefined)).resolves.toBe("ok");
+      expect(spans).toContainEqual({
+        name: "users.effectFn",
+        parentName: undefined,
+      });
+      expect(spans).toContainEqual({
+        name: "custom.handler.span",
+        parentName: "users.effectFn",
+      });
+      expect(spans).toContainEqual({
+        name: "users.withSpan",
+        parentName: undefined,
+      });
+      expect(spans).toContainEqual({
+        name: "custom.with-span.handler",
+        parentName: "users.withSpan",
+      });
+      expect(
+        spans.filter(({ name }) => name === "custom.middleware.span"),
+      ).toHaveLength(1);
+    } finally {
+      await tracedRuntime.dispose();
+    }
+  });
+});

package/src/tests/effect-error-map.test.ts

@@ -1,9 +1,9 @@
 import { fallbackORPCErrorMessage, ORPCError } from "@orpc/client";
-import { Effect, Layer, ManagedRuntime } from "effect";
+import { Effect } from "effect";
 import { describe, expect, expectTypeOf, it } from "vitest";
 import { z } from "zod";
 
-import { makeEffectORPC } from "../effect-builder";
+import { eos } from "../effect-builder";
 import type {
   EffectErrorMap,
   EffectErrorMapToUnion,
@@ -192,11 +192,10 @@ describe("effectErrorMapToErrorMap", () => {
 });
 
 describe("effectBuilder with EffectErrorMap", () => {
-  const runtime = ManagedRuntime.make(Layer.empty);
-  const effectOs = makeEffectORPC(runtime);
+  const effectProcedure = eos;
 
   it("should support errors() with traditional format", () => {
-    const builder = effectOs.errors({
+    const builder = effectProcedure.errors({
       BAD_REQUEST: { status: 400, message: "Bad request" },
     });
 
@@ -206,7 +205,7 @@ describe("effectBuilder with EffectErrorMap", () => {
   });
 
   it("should support errors() with tagged error classes", () => {
-    const builder = effectOs.errors({
+    const builder = effectProcedure.errors({
       USER_NOT_FOUND_ERROR: UserNotFoundError,
       FORBIDDEN: PermissionDenied,
     });
@@ -218,7 +217,7 @@ describe("effectBuilder with EffectErrorMap", () => {
   });
 
   it("should support mixed error format", () => {
-    const builder = effectOs.errors({
+    const builder = effectProcedure.errors({
       BAD_REQUEST: { status: 400 },
       USER_NOT_FOUND_ERROR: UserNotFoundError,
     });
@@ -232,7 +231,7 @@ describe("effectBuilder with EffectErrorMap", () => {
   });
 
   it("should merge errors correctly", () => {
-    const builder = effectOs
+    const builder = effectProcedure
       .errors({ BAD_REQUEST: { status: 400 } })
       .errors({ USER_NOT_FOUND_ERROR: UserNotFoundError })
       .errors({ FORBIDDEN: PermissionDenied });
@@ -245,7 +244,7 @@ describe("effectBuilder with EffectErrorMap", () => {
   });
 
   it("should create procedure with effect handler", async () => {
-    const procedure = effectOs
+    const procedure = effectProcedure
       .errors({
         USER_NOT_FOUND_ERROR: UserNotFoundError,
         BAD_REQUEST: { status: 400 },
@@ -267,7 +266,7 @@ describe("effectBuilder with EffectErrorMap", () => {
   });
 
   it("should allow throwing tagged errors in effect handler", async () => {
-    const procedure = effectOs
+    const procedure = effectProcedure
       .errors({
         USER_NOT_FOUND_ERROR: UserNotFoundError,
       })
@@ -309,11 +308,10 @@ describe("effectBuilder with EffectErrorMap", () => {
 });
 
 describe("effectDecoratedProcedure.errors()", () => {
-  const runtime = ManagedRuntime.make(Layer.empty);
-  const effectOs = makeEffectORPC(runtime);
+  const effectProcedure = eos;
 
   it("should support adding errors to procedure", () => {
-    const procedure = effectOs
+    const procedure = effectProcedure
       .input(z.object({ id: z.string() }))
       .effect(function* ({ input }) {
         return { id: input.id };
@@ -326,7 +324,7 @@ describe("effectDecoratedProcedure.errors()", () => {
   });
 
   it("should merge errors on procedure", () => {
-    const procedure = effectOs
+    const procedure = effectProcedure
       .errors({ BAD_REQUEST: { status: 400 } })
       .input(z.object({ id: z.string() }))
       .effect(function* ({ input }) {

package/src/tests/effect-procedure.test.ts

@@ -4,6 +4,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import z from "zod";
 
 import { EffectDecoratedProcedure } from "../effect-procedure";
+import { makeEffectRuntimeRunner } from "../runtime-source";
 import {
   baseErrorMap,
   baseMeta,
@@ -25,6 +26,7 @@ vi.mock("@orpc/server", async (importOriginal) => {
 });
 
 const runtime = ManagedRuntime.make(Layer.empty);
+const runner = makeEffectRuntimeRunner(runtime);
 
 const handler = vi.fn();
 const middleware = vi.fn();
@@ -40,6 +42,7 @@ const def = {
   meta: baseMeta,
   route: baseRoute,
   handler,
+  runner,
   runtime,
 };
 
@@ -80,7 +83,7 @@ describe("effectDecoratedProcedure", () => {
     });
 
     // Preserves runtime
-    expect(applied["~effect"].runtime).toBe(runtime);
+    expect(applied["~effect"].runner.runtime).toBe(runtime);
   });
 
   it(".meta", () => {
@@ -96,7 +99,7 @@ describe("effectDecoratedProcedure", () => {
     });
 
     // Preserves runtime
-    expect(applied["~effect"].runtime).toBe(runtime);
+    expect(applied["~effect"].runner.runtime).toBe(runtime);
   });
 
   it(".route", () => {
@@ -112,24 +115,63 @@ describe("effectDecoratedProcedure", () => {
     });
 
     // Preserves runtime
-    expect(applied["~effect"].runtime).toBe(runtime);
+    expect(applied["~effect"].runner.runtime).toBe(runtime);
   });
 
   describe(".use", () => {
-    it("without map input", () => {
-      const mid = vi.fn();
+    it("without map input", async () => {
+      const mid = vi.fn(({ next }) =>
+        next({ context: { fromMiddleware: true } }),
+      );
 
       const applied = decorated.use(mid);
       expect(applied).not.toBe(decorated);
       expect(applied).toBeInstanceOf(EffectDecoratedProcedure);
 
-      expect(applied["~effect"]).toEqual({
-        ...def,
-        middlewares: [...def.middlewares, mid],
+      expect(applied["~effect"].middlewares).toHaveLength(
+        def.middlewares.length + 1,
+      );
+      expect(applied["~effect"].middlewares[0]).toBe(def.middlewares[0]);
+
+      const wrapped = applied["~effect"].middlewares[1]!;
+      let nextCalls = 0;
+      let nextOptions: unknown;
+      const next = <TContext extends Record<PropertyKey, unknown>>(options?: {
+        context?: TContext;
+      }) => {
+        nextCalls++;
+        nextOptions = options;
+        return Promise.resolve({
+          output: "ok",
+          context: options?.context ?? ({} as TContext),
+        });
+      };
+      await expect(
+        wrapped(
+          {
+            context: {},
+            errors: {},
+            path: [],
+            procedure: applied,
+            signal: undefined,
+            lastEventId: undefined,
+            next,
+          },
+          "input",
+          vi.fn(),
+        ),
+      ).resolves.toEqual({
+        output: "ok",
+        context: { fromMiddleware: true },
+      });
+      expect(mid).toHaveBeenCalledOnce();
+      expect(nextCalls).toBe(1);
+      expect(nextOptions).toEqual({
+        context: { fromMiddleware: true },
       });
 
       // Preserves runtime
-      expect(applied["~effect"].runtime).toBe(runtime);
+      expect(applied["~effect"].runner.runtime).toBe(runtime);
     });
 
     it("with map input", () => {
@@ -146,7 +188,7 @@ describe("effectDecoratedProcedure", () => {
       });
 
       // Preserves runtime
-      expect(applied["~effect"].runtime).toBe(runtime);
+      expect(applied["~effect"].runner.runtime).toBe(runtime);
     });
   });
 
@@ -207,7 +249,7 @@ describe("effectDecoratedProcedure chaining", () => {
       .route({ path: "/custom" });
 
     expect(applied).toBeInstanceOf(EffectDecoratedProcedure);
-    expect(applied["~effect"].runtime).toBe(runtime);
+    expect(applied["~effect"].runner.runtime).toBe(runtime);
     expect(applied["~effect"].errorMap).toHaveProperty("CUSTOM");
   });
 });

package/src/tests/parity-shared.ts

@@ -1,4 +1,4 @@
-import { Layer, ManagedRuntime } from "effect";
+import { Layer } from "effect";
 
 import { eoc } from "../index";
 import {
@@ -12,7 +12,7 @@ import {
 export type InitialContext = { db: string };
 export type CurrentContext = InitialContext & { auth: boolean };
 
-export const runtime = ManagedRuntime.make(Layer.empty);
+export const runtime = Layer.empty;
 
 export const typedContract = {
   ping: eoc

package/src/types/effect-builder-surface.ts

@@ -474,7 +474,7 @@ export interface EffectBuilderSurface<
   >;
   /**
    * Defines the handler of the procedure using an Effect.
-   * The Effect is executed using the ManagedRuntime provided during builder creation.
+   * The Effect is executed using the configured Effect runtime source.
    * The effect is automatically wrapped with `Effect.withSpan`.
    *
    * @see {@link https://orpc.dev/docs/procedure Procedure Docs}