effect-orpc 0.2.0 → 0.2.1

package/src/extension/create-node-proxy.ts

@@ -0,0 +1,270 @@
+import {
+  effectInternalsSymbol,
+  getEffectInternals,
+  type EffectExtensionState,
+  type EffectProxyTarget,
+} from "./state";
+
+const unhandledProperty = Symbol("effect-orpc/unhandledProperty");
+
+export type UnhandledProperty = typeof unhandledProperty;
+
+export interface NodeProxyContext<
+  TTarget extends EffectProxyTarget<TSource>,
+  TSource extends object,
+> {
+  methodCache: Map<PropertyKey, unknown>;
+  state: EffectExtensionState;
+  target: TTarget;
+  upstream: TSource;
+}
+
+interface NodeProxyInternalConfig<
+  TTarget extends EffectProxyTarget<TSource>,
+  TSource extends object,
+> {
+  getProperty?: (
+    context: NodeProxyContext<TTarget, TSource>,
+    prop: PropertyKey,
+    receiver: unknown,
+  ) => unknown | UnhandledProperty;
+  getVirtual?: (
+    context: NodeProxyContext<TTarget, TSource>,
+    prop: PropertyKey,
+    receiver: unknown,
+  ) => unknown | UnhandledProperty;
+  virtualDescriptors?: Partial<
+    Record<string | symbol, Pick<PropertyDescriptor, "enumerable">>
+  >;
+  virtualKeys?: readonly (string | symbol)[];
+  wrapResult?: (
+    context: NodeProxyContext<TTarget, TSource>,
+    prop: PropertyKey,
+    result: unknown,
+    receiver: unknown,
+  ) => unknown;
+}
+
+/**
+ * Configures how an Effect-aware node proxy exposes virtual properties and
+ * rewrites returned values while the upstream builder/procedure remains the
+ * source of truth for passthrough behavior.
+ */
+export interface NodeProxyConfig<
+  TTarget extends EffectProxyTarget<TSource>,
+  TSource extends object,
+> extends NodeProxyInternalConfig<TTarget, TSource> {
+  /**
+   * Returns a value for virtual properties such as `~effect` or custom
+   * proxy-backed methods. Return `unhandled()` to fall back to the next step.
+   */
+  getVirtual?: (
+    context: NodeProxyContext<TTarget, TSource>,
+    prop: PropertyKey,
+    receiver: unknown,
+  ) => unknown | UnhandledProperty;
+  /**
+   * Intercepts property access before upstream passthrough. Return
+   * `unhandled()` to delegate to the wrapped upstream node.
+   */
+  getProperty?: (
+    context: NodeProxyContext<TTarget, TSource>,
+    prop: PropertyKey,
+    receiver: unknown,
+  ) => unknown | UnhandledProperty;
+  /**
+   * Declares which virtual keys should appear in reflection APIs like `in`,
+   * `Object.keys`, and descriptor lookup.
+   */
+  virtualKeys?: readonly (string | symbol)[];
+  /**
+   * Controls enumerability for virtual keys exposed through the proxy.
+   */
+  virtualDescriptors?: Partial<
+    Record<string | symbol, Pick<PropertyDescriptor, "enumerable">>
+  >;
+  /**
+   * Rewraps upstream method results when they should stay inside the Effect
+   * extension model.
+   */
+  wrapResult?: (
+    context: NodeProxyContext<TTarget, TSource>,
+    prop: PropertyKey,
+    result: unknown,
+    receiver: unknown,
+  ) => unknown;
+}
+
+function createNodeProxyContext<
+  TTarget extends EffectProxyTarget<TSource>,
+  TSource extends object,
+>(target: TTarget): NodeProxyContext<TTarget, TSource> {
+  const internals = getEffectInternals(target);
+  return {
+    methodCache: internals.methodCache,
+    state: internals.state,
+    target,
+    upstream: internals.upstream as TSource,
+  };
+}
+
+function createBoundMethod<
+  TTarget extends EffectProxyTarget<TSource>,
+  TSource extends object,
+>(
+  context: NodeProxyContext<TTarget, TSource>,
+  prop: PropertyKey,
+  value: (...args: unknown[]) => unknown,
+  config: NodeProxyInternalConfig<TTarget, TSource>,
+  receiver: unknown,
+): (...args: unknown[]) => unknown {
+  const cache = context.methodCache;
+  if (cache.has(prop)) {
+    return cache.get(prop) as (...args: unknown[]) => unknown;
+  }
+
+  const wrapped = (...args: unknown[]) => {
+    const result = Reflect.apply(value, context.upstream, args);
+    return config.wrapResult?.(context, prop, result, receiver) ?? result;
+  };
+
+  cache.set(prop, wrapped);
+  return wrapped;
+}
+
+/**
+ * Creates an Effect-aware proxy around a local shell object.
+ *
+ * @param target The local Effect wrapper instance that already has upstream and
+ * state symbols attached via `attachEffectState`.
+ * @param config The extension hooks that define virtual properties,
+ * interception points, and result rewrapping behavior for the proxy.
+ */
+export function createNodeProxy<
+  TTarget extends EffectProxyTarget<TSource>,
+  TSource extends object,
+>(target: TTarget, config: NodeProxyConfig<TTarget, TSource>): TTarget {
+  const privateKeys = new Set<PropertyKey>([effectInternalsSymbol]);
+  const virtualKeys = new Set(config.virtualKeys ?? []);
+
+  return new Proxy(target, {
+    get(currentTarget, prop, receiver) {
+      if (privateKeys.has(prop)) {
+        return Reflect.get(currentTarget, prop, receiver);
+      }
+
+      const context = createNodeProxyContext<TTarget, TSource>(
+        currentTarget as TTarget,
+      );
+
+      const virtualValue = config.getVirtual?.(context, prop, receiver);
+      if (virtualValue !== undefined && virtualValue !== unhandledProperty) {
+        return virtualValue;
+      }
+
+      const propertyValue = config.getProperty?.(context, prop, receiver);
+      if (propertyValue !== undefined && propertyValue !== unhandledProperty) {
+        return propertyValue;
+      }
+
+      const sourceValue = Reflect.get(context.upstream, prop, context.upstream);
+
+      if (Reflect.has(context.upstream, prop)) {
+        if (typeof sourceValue === "function") {
+          return createBoundMethod(
+            context,
+            prop,
+            sourceValue as (...args: unknown[]) => unknown,
+            config,
+            receiver,
+          );
+        }
+
+        return sourceValue;
+      }
+
+      return Reflect.get(currentTarget, prop, receiver);
+    },
+
+    has(currentTarget, prop) {
+      if (virtualKeys.has(prop)) {
+        return true;
+      }
+
+      const context = createNodeProxyContext<TTarget, TSource>(currentTarget);
+      return (
+        Reflect.has(context.upstream, prop) || Reflect.has(currentTarget, prop)
+      );
+    },
+
+    ownKeys(currentTarget) {
+      const keys = new Set<string | symbol>();
+
+      for (const key of Reflect.ownKeys(currentTarget)) {
+        if (!privateKeys.has(key)) {
+          keys.add(key);
+        }
+      }
+
+      const context = createNodeProxyContext<TTarget, TSource>(
+        currentTarget as TTarget,
+      );
+
+      for (const key of Reflect.ownKeys(context.upstream)) {
+        keys.add(key);
+      }
+
+      for (const key of virtualKeys) {
+        keys.add(key);
+      }
+
+      return [...keys];
+    },
+
+    getOwnPropertyDescriptor(currentTarget, prop) {
+      const context = createNodeProxyContext<TTarget, TSource>(
+        currentTarget as TTarget,
+      );
+
+      if (virtualKeys.has(prop)) {
+        const value = config.getVirtual?.(context, prop, currentTarget);
+        if (value !== undefined && value !== unhandledProperty) {
+          return {
+            configurable: true,
+            enumerable: config.virtualDescriptors?.[prop]?.enumerable ?? false,
+            value,
+            writable: false,
+          };
+        }
+      }
+
+      const descriptor = Reflect.getOwnPropertyDescriptor(
+        context.upstream,
+        prop,
+      );
+
+      if (descriptor === undefined) {
+        return Reflect.getOwnPropertyDescriptor(currentTarget, prop);
+      }
+
+      if ("value" in descriptor && typeof descriptor.value === "function") {
+        return {
+          ...descriptor,
+          value: createBoundMethod(
+            context,
+            prop,
+            descriptor.value as (...args: unknown[]) => unknown,
+            config,
+            currentTarget,
+          ),
+        };
+      }
+
+      return descriptor;
+    },
+  });
+}
+
+export function unhandled(): UnhandledProperty {
+  return unhandledProperty;
+}

package/src/extension/state.ts

@@ -0,0 +1,108 @@
+import type { ManagedRuntime } from "effect";
+
+import type { EffectErrorMap } from "../tagged-error";
+import type { EffectSpanConfig } from "../types";
+
+export interface EffectExtensionState<
+  TRequirementsProvided = any,
+  TRuntimeError = any,
+> {
+  /**
+   * Extended error map that supports both traditional oRPC errors and ORPCTaggedError classes.
+   * @see {@link EffectErrorMap}
+   */
+  effectErrorMap: EffectErrorMap;
+  /**
+   * The Effect ManagedRuntime that provides services for Effect procedures.
+   * @see {@link ManagedRuntime.ManagedRuntime}
+   */
+  runtime: ManagedRuntime.ManagedRuntime<TRequirementsProvided, TRuntimeError>;
+  /**
+   * Configuration for Effect span tracing.
+   * @see {@link EffectSpanConfig}
+   */
+  spanConfig?: EffectSpanConfig;
+}
+
+export interface EffectInternals<TUpstream extends object = object> {
+  upstream: TUpstream;
+  state: EffectExtensionState;
+  methodCache: Map<PropertyKey, unknown>;
+}
+
+export const effectInternalsSymbol = Symbol("effect-orpc/internals");
+
+export interface EffectProxyTarget<TUpstream extends object = object> {
+  [effectInternalsSymbol]: EffectInternals<TUpstream>;
+}
+
+export function attachEffectState<
+  TTarget extends object,
+  TUpstream extends object,
+>(
+  target: TTarget,
+  upstream: TUpstream,
+  state: EffectExtensionState,
+): asserts target is TTarget & EffectProxyTarget<TUpstream> {
+  Object.defineProperties(target, {
+    [effectInternalsSymbol]: {
+      configurable: true,
+      value: {
+        methodCache: new Map<PropertyKey, unknown>(),
+        state,
+        upstream,
+      } satisfies EffectInternals<TUpstream>,
+    },
+  });
+}
+
+export function getEffectInternals<TUpstream extends object>(
+  target: EffectProxyTarget<TUpstream>,
+): EffectInternals<TUpstream> {
+  return target[effectInternalsSymbol];
+}
+
+export function getEffectUpstream<TUpstream extends object>(
+  target: EffectProxyTarget<TUpstream>,
+): TUpstream {
+  return getEffectInternals(target).upstream;
+}
+
+export function getEffectState(
+  target: EffectProxyTarget,
+): EffectExtensionState {
+  return getEffectInternals(target).state;
+}
+
+export function getEffectMethodCache(
+  target: EffectProxyTarget,
+): Map<PropertyKey, unknown> {
+  return getEffectInternals(target).methodCache;
+}
+
+export function hasEffectState(value: unknown): value is EffectProxyTarget {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    effectInternalsSymbol in (value as object)
+  );
+}
+
+export function assertEffectState<TUpstream extends object>(
+  value: object,
+): asserts value is EffectProxyTarget<TUpstream> {
+  if (!hasEffectState(value)) {
+    throw new Error("Expected effect state to be attached");
+  }
+}
+
+export function getEffectErrorMap(value: {
+  "~effect"?: { effectErrorMap: EffectErrorMap };
+  "~orpc": { errorMap: EffectErrorMap };
+}): EffectErrorMap {
+  return value["~effect"]?.effectErrorMap ?? value["~orpc"].errorMap;
+}
+
+export function unwrapEffectUpstream<T extends object>(value: T): T {
+  return hasEffectState(value) ? (getEffectUpstream(value) as T) : value;
+}

package/src/index.ts

@@ -45,6 +45,8 @@ export type {
 export type {
   AnyBuilderLike,
   EffectBuilderDef,
+  EffectBuilderSurface,
+  EffectDecoratedProcedureSurface,
   EffectBuilderWithMiddlewares,
   EffectErrorMapToErrorMap,
   EffectProcedureBuilder,

package/src/tests/effect-builder.proxy.test.ts

@@ -0,0 +1,253 @@
+import { isLazy, isProcedure, os, unlazy } from "@orpc/server";
+import { Layer, ManagedRuntime } from "effect";
+import { describe, expect, it } from "vitest";
+import z from "zod";
+
+import { EffectBuilder, makeEffectORPC } from "../effect-builder";
+import { EffectDecoratedProcedure } from "../effect-procedure";
+import { ORPCTaggedError } from "../tagged-error";
+const runtime = ManagedRuntime.make(Layer.empty);
+
+function makeCustomBuilder(meta: Record<string, unknown> = {}): {
+  "~orpc": (typeof os)["~orpc"];
+  customBuilderLike(label: string): any;
+  customValue(): unknown;
+} {
+  return {
+    "~orpc": {
+      ...os["~orpc"],
+      meta,
+    },
+    customBuilderLike(this: any, label: string) {
+      return makeCustomBuilder({
+        ...(this["~orpc"].meta as Record<string, unknown>),
+        label,
+      });
+    },
+    customValue(this: any) {
+      return this["~orpc"].meta;
+    },
+  };
+}
+
+describe("effectBuilder proxy compatibility", () => {
+  it("preserves instanceof and virtual reflection surface", () => {
+    const builder = makeEffectORPC(runtime);
+
+    expect(builder).toBeInstanceOf(EffectBuilder);
+    expect("~orpc" in builder).toBe(true);
+    expect("~effect" in builder).toBe(true);
+    expect("errors" in builder).toBe(true);
+    expect("effect" in builder).toBe(true);
+    expect("traced" in builder).toBe(true);
+    expect("handler" in builder).toBe(true);
+    expect("router" in builder).toBe(true);
+    expect("lazy" in builder).toBe(true);
+    expect("middleware" in builder).toBe(true);
+
+    expect(Object.keys(builder)).toEqual(
+      expect.arrayContaining(["~effect", "~orpc"]),
+    );
+    expect(Reflect.ownKeys(builder)).toEqual(
+      expect.arrayContaining([
+        "~effect",
+        "~orpc",
+        "errors",
+        "effect",
+        "traced",
+        "handler",
+        "router",
+        "lazy",
+      ]),
+    );
+
+    expect(Object.prototype.hasOwnProperty.call(builder, "~orpc")).toBe(true);
+    expect(Object.prototype.hasOwnProperty.call(builder, "~effect")).toBe(true);
+    expect(Object.prototype.hasOwnProperty.call(builder, "effect")).toBe(true);
+
+    const orpcDescriptor = Object.getOwnPropertyDescriptor(builder, "~orpc");
+    expect(orpcDescriptor?.enumerable).toBe(true);
+    expect(orpcDescriptor?.value).toBe(builder["~orpc"]);
+
+    const effectDescriptor = Object.getOwnPropertyDescriptor(
+      builder,
+      "~effect",
+    );
+    expect(effectDescriptor?.enumerable).toBe(true);
+    expect(effectDescriptor?.value).toStrictEqual(builder["~effect"]);
+
+    const methodDescriptor = Object.getOwnPropertyDescriptor(builder, "effect");
+    expect(methodDescriptor?.enumerable).toBe(false);
+    expect(methodDescriptor?.value).toBeTypeOf("function");
+  });
+
+  it("keeps extracted forwarded and intercepted methods callable", () => {
+    const builder = makeEffectORPC(runtime).$meta({ mode: "dev" });
+
+    const meta = builder.meta;
+    const prefixed = builder.prefix;
+    const effect = builder.effect;
+
+    const withMeta = meta({ log: true } as any);
+    const withPrefix = prefixed("/api");
+    const procedure = effect(function* () {
+      return "ok";
+    });
+
+    expect(withMeta).toBeInstanceOf(EffectBuilder);
+    expect(withMeta["~effect"].meta).toEqual({ mode: "dev", log: true });
+    expect(withPrefix).toBeInstanceOf(EffectBuilder);
+    expect((withPrefix as any)["~effect"].prefix).toBe("/api");
+    expect(procedure).toBeInstanceOf(EffectDecoratedProcedure);
+  });
+
+  it("preserves wrapped chaining across forwarded and intercepted methods", () => {
+    const routedBuilder = makeEffectORPC(runtime).prefix("/api").tag("users");
+    const builder = makeEffectORPC(runtime)
+      .$meta({ scope: "users" })
+      .errors({ BAD_REQUEST: { message: "bad request" } })
+      .traced("users.list")
+      .input(z.object({ id: z.string() }))
+      .output(z.object({ id: z.string() }));
+
+    expect(routedBuilder).toBeInstanceOf(EffectBuilder);
+    expect((routedBuilder as any)["~effect"].prefix).toBe("/api");
+    expect((routedBuilder as any)["~effect"].tags).toEqual(["users"]);
+    expect(builder).toBeInstanceOf(EffectBuilder);
+    expect(builder["~effect"].meta).toEqual({ scope: "users" });
+    expect(builder["~effect"].spanConfig?.name).toBe("users.list");
+
+    const procedure = builder.handler(
+      ({ input }: { input: { id: string } }) => input,
+    );
+    expect(procedure).toBeInstanceOf(EffectDecoratedProcedure);
+    expect(procedure["~effect"].runtime).toBe(runtime);
+  });
+
+  it("preserves tagged class support in errors()", () => {
+    class UserNotFoundError extends ORPCTaggedError("UserNotFoundError", {
+      code: "NOT_FOUND",
+      schema: z.object({ userId: z.string() }),
+    }) {}
+
+    const builder = makeEffectORPC(runtime).errors({
+      UserNotFoundError,
+    });
+
+    expect(builder["~effect"].effectErrorMap.UserNotFoundError).toBe(
+      UserNotFoundError,
+    );
+    expect(builder["~orpc"].errorMap).toHaveProperty("NOT_FOUND");
+  });
+
+  it("keeps handler, effect, router, and lazy return behavior unchanged", async () => {
+    const builder = makeEffectORPC(runtime);
+    const procedure = builder.effect(function* () {
+      return { output: "pong" };
+    });
+
+    const handled = builder.handler(() => "handled");
+    const effected = builder.effect(function* () {
+      return "effected";
+    });
+    const routed = builder.prefix("/v1").router({ ping: procedure });
+    const lazied = builder.lazy(async () => ({ default: { ping: procedure } }));
+
+    expect(handled).toBeInstanceOf(EffectDecoratedProcedure);
+    expect(effected).toBeInstanceOf(EffectDecoratedProcedure);
+    expect(routed.ping["~effect"].runtime).toBe(runtime);
+    expect(isLazy(lazied)).toBe(true);
+
+    const { default: resolved } = await unlazy(lazied as any);
+    expect(resolved.ping["~effect"].runtime).toBe(runtime);
+  });
+
+  it("preserves decorated procedure proxy reflection and extracted methods", () => {
+    const procedure = makeEffectORPC(runtime)
+      .route({ path: "/users" })
+      .handler(({ input }) => input);
+
+    expect(procedure).toBeInstanceOf(EffectDecoratedProcedure);
+    expect("~orpc" in procedure).toBe(true);
+    expect("~effect" in procedure).toBe(true);
+    expect("errors" in procedure).toBe(true);
+    expect("meta" in procedure).toBe(true);
+    expect("route" in procedure).toBe(true);
+    expect("use" in procedure).toBe(true);
+    expect("callable" in procedure).toBe(true);
+    expect("actionable" in procedure).toBe(true);
+
+    expect(Reflect.ownKeys(procedure)).toEqual(
+      expect.arrayContaining([
+        "~orpc",
+        "~effect",
+        "errors",
+        "meta",
+        "route",
+        "use",
+        "callable",
+        "actionable",
+      ]),
+    );
+
+    const meta = procedure.meta;
+    const route = procedure.route;
+    const errors = procedure.errors;
+
+    expect(meta({ scope: "users" } as any)["~effect"].meta).toEqual({
+      scope: "users",
+    });
+    expect(route({ method: "GET" })["~effect"].route).toEqual({
+      method: "GET",
+      path: "/users",
+    });
+    const withError = errors({ BAD_REQUEST: { message: "bad request" } });
+    expect(withError["~orpc"].errorMap.BAD_REQUEST.message).toBe("bad request");
+  });
+
+  it("keeps callable procedure clients executable while exposing the procedure surface", async () => {
+    const procedure = makeEffectORPC(runtime).handler(({ input }) => ({
+      echoed: input,
+    }));
+
+    const callable = procedure.callable();
+
+    await expect(callable("hello")).resolves.toEqual({ echoed: "hello" });
+    expect(callable).toSatisfy(isProcedure);
+    expect(callable["~effect"].runtime).toBe(runtime);
+    expect(callable.route({ path: "/echo" })).toBeInstanceOf(
+      EffectDecoratedProcedure,
+    );
+  });
+
+  it("applies builder route and middleware enhancements to routed procedures", () => {
+    const builder = makeEffectORPC(runtime);
+    const middleware = builder.middleware(({ next }) => next({}));
+    const procedure = builder.route({ path: "/ping" }).handler(() => "pong");
+
+    const routed = builder.use(middleware).prefix("/api").router({ procedure });
+
+    expect(routed.procedure["~orpc"].route.path).toBe("/api/ping");
+    expect(routed.procedure["~effect"].route.path).toBe("/api/ping");
+    expect(routed.procedure["~orpc"].middlewares).toHaveLength(
+      procedure["~orpc"].middlewares.length + 1,
+    );
+    expect(routed.procedure["~effect"].middlewares).toHaveLength(
+      procedure["~effect"].middlewares.length + 1,
+    );
+  });
+
+  it("rewraps unknown builder-like methods and passes through non-builder results", () => {
+    const builder = makeEffectORPC(runtime, makeCustomBuilder() as any) as any;
+
+    const customBuilderLike = builder.customBuilderLike;
+    const customValue = builder.customValue;
+
+    const next = customBuilderLike("proxy");
+
+    expect(next).toBeInstanceOf(EffectBuilder);
+    expect(next["~effect"].meta).toEqual({ label: "proxy" });
+    expect(customValue()).toEqual({});
+    expect(next.customValue()).toEqual({ label: "proxy" });
+  });
+});

package/src/tests/parity.effect-builder.test.ts

@@ -1,5 +1,6 @@
 import type { ContractProcedure, Schema } from "@orpc/contract";
 import type {
+  Builder,
   DecoratedMiddleware,
   Middleware,
   MiddlewareOutputFn,
@@ -51,6 +52,22 @@ const withOutput = procedureBuilder.output(outputSchema);
 const withInputOutput = withInput.output(outputSchema);
 
 describe("parity: @orpc/server builder.test-d.ts", () => {
+  it("exposes every upstream builder key", () => {
+    type MissingEffectBuilderKeys = Exclude<
+      keyof Builder<
+        InitialContext,
+        CurrentContext,
+        typeof inputSchema,
+        typeof outputSchema,
+        typeof baseErrorMap,
+        BaseMeta
+      >,
+      keyof typeof typedBuilder
+    >;
+
+    expectTypeOf<MissingEffectBuilderKeys>().toEqualTypeOf<never>();
+  });
+
   it("is a contract procedure", () => {
     expectTypeOf<
       AssertExtends<