effect-orpc 0.1.4 → 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

@@ -1,3 +1,18 @@
+export { implementEffect } from "./contract";
+export type {
+  EffectImplementer,
+  EffectImplementerInternal,
+  EffectProcedureImplementer,
+} from "./contract";
+export { eoc } from "./eoc";
+export type {
+  EffectContractBuilder,
+  EffectContractProcedureBuilder,
+  EffectContractProcedureBuilderWithInput,
+  EffectContractProcedureBuilderWithInputOutput,
+  EffectContractProcedureBuilderWithOutput,
+  EffectContractRouterBuilder,
+} from "./eoc";
 export {
   addSpanStackTrace,
   EffectBuilder,
@@ -30,6 +45,8 @@ export type {
 export type {
   AnyBuilderLike,
   EffectBuilderDef,
+  EffectBuilderSurface,
+  EffectDecoratedProcedureSurface,
   EffectBuilderWithMiddlewares,
   EffectErrorMapToErrorMap,
   EffectProcedureBuilder,
@@ -40,10 +57,10 @@ export type {
   EffectProcedureHandler,
   EffectRouterBuilder,
   EffectSpanConfig,
-  InferBuilderInitialContext,
   InferBuilderCurrentContext,
-  InferBuilderInputSchema,
-  InferBuilderOutputSchema,
   InferBuilderErrorMap,
+  InferBuilderInitialContext,
+  InferBuilderInputSchema,
   InferBuilderMeta,
+  InferBuilderOutputSchema,
 } from "./types";

package/src/tagged-error.ts

@@ -15,7 +15,6 @@ import type {
   ErrorMapItem,
   InferSchemaOutput,
 } from "@orpc/contract";
-import type { ORPCErrorConstructorMap } from "@orpc/server";
 import type { MaybeOptionalOptions } from "@orpc/shared";
 import { resolveMaybeOptionalOptions } from "@orpc/shared";
 import type { Pipeable } from "effect";
@@ -433,8 +432,29 @@ export type EffectErrorMapToUnion<T extends EffectErrorMap> = {
 /**
  * Constructor map for EffectErrorMap - provides typed error constructors for handlers.
  */
-export type EffectErrorConstructorMap<T extends EffectErrorMap> =
-  ORPCErrorConstructorMap<EffectErrorMapToErrorMap<T>>;
+type EffectErrorConstructor<
+  TCode extends ORPCErrorCode,
+  TItem,
+> = TItem extends AnyORPCTaggedErrorClass
+  ? (...args: ConstructorParameters<TItem>) => InstanceType<TItem>
+  : TItem extends { data?: infer TSchema extends AnySchema }
+    ? (
+        ...rest: MaybeOptionalOptions<
+          Omit<
+            ORPCErrorOptions<InferSchemaOutput<TSchema>>,
+            "defined" | "status"
+          >
+        >
+      ) => ORPCError<TCode, InferSchemaOutput<TSchema>>
+    : (
+        ...rest: MaybeOptionalOptions<
+          Omit<ORPCErrorOptions<unknown>, "defined" | "status">
+        >
+      ) => ORPCError<TCode, unknown>;
+
+export type EffectErrorConstructorMap<T extends EffectErrorMap> = {
+  [K in Extract<keyof T, ORPCErrorCode>]: EffectErrorConstructor<K, T[K]>;
+};
 
 /**
  * Creates an error constructor map from an EffectErrorMap.
@@ -478,7 +498,7 @@ export function createEffectErrorConstructorMap<T extends EffectErrorMap>(
     },
   });
 
-  return proxy as EffectErrorConstructorMap<T>;
+  return proxy as unknown as EffectErrorConstructorMap<T>;
 }
 
 /**