@rc312/tss-effect-serverfn 0.0.0-stage → 0.2.0

package/src/create-effect-server-fn.ts

@@ -0,0 +1,197 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { createServerFn } from "@tanstack/react-start";
+import type {
+  Fetcher,
+  FunctionMiddlewareWithTypes,
+  Method,
+  Register,
+  ServerFnBuilder,
+  ServerFnCtx,
+  ServerFnOptions,
+  ServerFnStrict,
+  ServerFnStrictOutput,
+} from "@tanstack/react-start";
+import type { ValidateSerializableInput } from "@tanstack/router-core";
+import type { Effect, Schema } from "effect";
+
+import type { ExecutionCapability, RequestServices } from "./execution.ts";
+
+/**
+ * Type-only bridge from an Effect Schema to Start's validator inference.
+ * Clients supply encoded input; handlers receive decoded data. Runtime decoding
+ * is supplied by the compiler bridge, not a Standard Schema adapter.
+ */
+type NativeValidator<Input> = Input extends Schema.Constraint
+  ? StandardSchemaV1<Input["Encoded"], Input["Type"]>
+  : undefined;
+
+type HandlerContext<MethodType, Middlewares, Input> = ServerFnCtx<
+  Register,
+  MethodType,
+  Middlewares,
+  NativeValidator<Input>
+>;
+
+type DecodingServices<Input> = Input extends Schema.Constraint
+  ? Input["DecodingServices"]
+  : never;
+
+type AppendMiddlewares<
+  Current,
+  Next extends NativeMiddlewares,
+> = Current extends readonly unknown[] ? readonly [...Current, ...Next] : Next;
+
+type SerializableOutput<A, Strict extends ServerFnStrict> =
+  ServerFnStrictOutput<Strict> extends false
+    ? A
+    : A extends Response
+      ? A
+      : ValidateSerializableInput<Register, A>;
+
+type NativeBuilder<
+  M extends Method,
+  Strict extends ServerFnStrict,
+> = ServerFnBuilder<Register, M, Strict>;
+
+type NativeMiddlewares = Parameters<
+  NativeBuilder<Method, ServerFnStrict>["middleware"]
+>[0];
+
+/**
+ * Enable handlers only when middleware supplies a runtime and all decoding
+ * services. The returned Effect must also satisfy service and wire-output checks.
+ */
+type Handler<
+  M extends Method,
+  Middlewares,
+  Input,
+  Strict extends ServerFnStrict,
+> =
+  HandlerContext<M, Middlewares, Input>["context"] extends ExecutionCapability<
+    infer Services
+  >
+    ? [Exclude<DecodingServices<Input>, Services | RequestServices>] extends [
+        never,
+      ]
+      ? <A, E>(
+          handler: (
+            context: HandlerContext<M, Middlewares, Input>
+          ) => Effect.Effect<A, E, Services | RequestServices> &
+            Effect.Effect<SerializableOutput<A, Strict>, unknown, unknown>
+        ) => Fetcher<Middlewares, NativeValidator<Input>, A>
+      : never
+    : never;
+
+type SerializableInput<
+  Input extends Schema.Constraint,
+  M extends Method,
+  Strict extends ServerFnStrict,
+> = Strict extends false | { input: false }
+  ? unknown
+  : [M, Input["Encoded"]] extends ["POST", FormData]
+    ? unknown
+    : Schema.ConstraintCodec<
+        unknown,
+        ValidateSerializableInput<Register, Input["Encoded"]>,
+        unknown,
+        unknown
+      >;
+
+/**
+ * Start's server-function builder with raw Effect Schemas and Effect handlers.
+ *
+ * Native method, middleware-context, and serialization inference are preserved.
+ * Configured builders remain callable until a validator is attached, following
+ * Start's builder contract.
+ *
+ * @template M - HTTP method used by the server function.
+ * @template Middlewares - Accumulated native middleware and its context types.
+ * @template Input - The attached Effect Schema, or `undefined` before validation.
+ * @template Strict - Start's input/output serialization-check policy.
+ * @template Callable - Whether this builder can configure another endpoint.
+ */
+export type EffectServerFnBuilder<
+  M extends Method = "GET",
+  Middlewares = undefined,
+  Input = undefined,
+  Strict extends ServerFnStrict = true,
+  Callable extends boolean = true,
+> = Omit<
+  NativeBuilder<M, Strict>,
+  "handler" | "validator" | "middleware" | "~types"
+> & {
+  readonly "~types": FunctionMiddlewareWithTypes<
+    Register,
+    Middlewares,
+    NativeValidator<Input>,
+    undefined,
+    undefined,
+    undefined,
+    undefined
+  >["~types"] & {
+    readonly method: M;
+    readonly strict: Strict;
+    readonly response: undefined;
+  };
+  /**
+   * Return an Effect using decoded data and native middleware context.
+   * The generated client function returns a Promise; remote rejections do not
+   * carry the Effect error channel as a TypeScript rejection type.
+   */
+  readonly handler: Handler<M, Middlewares, Input, Strict>;
+  /** Decode raw input in the handler's application runtime and request Scope. */
+  readonly validator: <NextInput extends Schema.Constraint>(
+    schema: NextInput & SerializableInput<NextInput, M, Strict>
+  ) => EffectServerFnBuilder<M, Middlewares, NextInput, Strict, false>;
+  /** Append native middleware, retaining its inferred context and execution services. */
+  readonly middleware: <const Next extends NativeMiddlewares>(
+    middlewares: Next
+  ) => EffectServerFnBuilder<
+    M,
+    AppendMiddlewares<Middlewares, Next>,
+    Input,
+    Strict,
+    Callable
+  >;
+} & (Callable extends true
+    ? <
+        NextMethod extends Method = M,
+        NextStrict extends ServerFnStrict = Strict,
+      >(
+        options?: ServerFnOptions<NextMethod, NextStrict>
+      ) => EffectServerFnBuilder<NextMethod, Middlewares, Input, NextStrict>
+    : unknown);
+
+/** Factory signature for an Effect-aware native Start server-function builder. */
+export type CreateEffectServerFn = <
+  M extends Method = "GET",
+  Strict extends ServerFnStrict = true,
+>(
+  options?: ServerFnOptions<M, Strict>
+) => EffectServerFnBuilder<M, undefined, undefined, Strict>;
+
+/**
+ * Define a Start server function using an Effect Schema and an Effect handler.
+ *
+ * Requires `effectServerFns()` from `@rc312/tss-effect-serverfn/vite`, installed before
+ * `tanstackStart()`, and execution middleware from `createEffectMiddleware`.
+ * This value retains the native `createServerFn` identity; the plugin adapts
+ * validators and handlers before Start performs extraction and RPC generation.
+ *
+ * @param options - Native Start options, including HTTP method and strictness.
+ * @returns A builder whose completed handler exposes Start's Promise client.
+ *
+ * @example
+ * Using the shared factory configured with execution middleware:
+ * ```ts
+ * import { Effect, Schema } from "effect";
+ * import { createEffectServerFn } from "./effect-server-fn";
+ *
+ * export const greet = createEffectServerFn({ method: "GET" })
+ *   .validator(Schema.Struct({ name: Schema.NonEmptyString }))
+ *   .handler(({ data }) => Effect.succeed(`Hello, ${data.name}!`));
+ * ```
+ */
+export const createEffectServerFn: CreateEffectServerFn =
+  // SAFETY: The compiler lowers raw schemas and Effect callbacks before TanStack consumes them.
+  createServerFn as typeof createServerFn & CreateEffectServerFn;

package/src/effect-middleware.ts

@@ -0,0 +1,171 @@
+import { createMiddleware, createServerOnlyFn } from "@tanstack/react-start";
+import type { ServerFnMeta } from "@tanstack/react-start";
+import type { ValidateSerializableInput } from "@tanstack/router-core";
+import type { Cause, Duration, Effect, Exit, Schema } from "effect";
+import type { HttpServerRequest } from "effect/http";
+
+import { bootstrapFailure } from "./bootstrap.server.ts";
+import type { ExecutionCapability } from "./execution.ts";
+
+/**
+ * Server-local diagnostics passed to a configured failure reporter after request
+ * cleanup. Causes can contain private input and application details; only the
+ * projected rejection is eligible for transport to the client.
+ */
+export interface FailureReport {
+  /** Original operation Cause, including any request-scope finalizer failures. */
+  readonly cause: Cause.Cause<unknown>;
+  /** The phase active when the operation failed. */
+  readonly phase: "input" | "execution";
+  /** Proposed client rejection: the approved encoded error or trusted fallback. */
+  readonly failure: unknown;
+  /** An additional fault from inspecting or encoding the original failure. */
+  readonly processingCause?: Cause.Cause<unknown> | undefined;
+  /** TanStack's identity and source metadata for the current server function. */
+  readonly serverFnMeta: ServerFnMeta;
+}
+
+/**
+ * Application-owned execution and failure policy resolved for a handler call.
+ *
+ * The adapter owns the request Scope; the application owns the runtime and its
+ * disposal. Encoding and reporting run after request cleanup, with application
+ * services and HTTP request metadata still available.
+ *
+ * @template R - Services supplied by the application's runner.
+ * @template RuntimeError - Failures from acquiring the application's runtime.
+ * @template P - Public rejection record produced by the error encoder.
+ */
+export interface EffectConfiguration<R, RuntimeError, P extends object> {
+  /**
+   * Execute in the application environment and return the complete Exit.
+   * Use `Effect.runPromiseExit` for service-free work or a shared
+   * `ManagedRuntime`'s `runPromiseExit`. Custom runners must honor the supplied
+   * abort signal and await finalization before settling.
+   */
+  readonly runPromiseExit: <A, E>(
+    program: Effect.Effect<A, E, R>,
+    options?: Effect.RunOptions
+  ) => Promise<Exit.Exit<A, E | RuntimeError>>;
+  /**
+   * Approve and encode a single typed business failure for the client.
+   * Undeclared properties are stripped. Unapproved failures, defects, mixed
+   * Causes, and encoding failures use `fallbackFailure` instead.
+   */
+  readonly publicError?: Schema.ConstraintEncoder<
+    // Built-in wire values avoid a recursive Register.config dependency for global middleware.
+    ValidateSerializableInput<unknown, P>,
+    NoInfer<R> | HttpServerRequest.HttpServerRequest
+  >;
+  /**
+   * Replace native `ErrorReporter.report` with an awaited Effect.
+   * Control flow, ordinary invalid input, and pure interruption skip reporting.
+   * Faults or timeouts in this callback leave the business rejection intact and
+   * allow outer framework reporting. Compose native reporting here if desired.
+   */
+  readonly reportFailure?: (
+    report: FailureReport
+  ) => Effect.Effect<
+    void,
+    unknown,
+    NoInfer<R> | HttpServerRequest.HttpServerRequest
+  >;
+  /**
+   * Timeout for the `reportFailure` override only.
+   *
+   * @default "5 seconds"
+   */
+  readonly reportTimeout?: Duration.Input;
+}
+
+/**
+ * Configure the eager safe fallback and lazy application execution policy.
+ *
+ * @template R - Services supplied by the resolved runner.
+ * @template RuntimeError - Failures from acquiring the application's runtime.
+ * @template P - Public rejection record produced by the error encoder.
+ * @template F - Trusted fallback record available before application loading.
+ */
+export interface EffectMiddlewareOptions<
+  R,
+  RuntimeError,
+  P extends object,
+  F extends object,
+> {
+  /**
+   * Trusted, serializable rejection for failures that cannot be exposed.
+   * Keep it independent of lazy application loading and free of private details.
+   * A fresh copy receives server-local diagnostics for each rejection.
+   */
+  readonly fallbackFailure: F & ValidateSerializableInput<unknown, F>;
+  /**
+   * Resolve configuration when the generated handler requests execution.
+   * Native middleware that rejects or replaces the handler does not invoke this
+   * callback. Reuse an application runtime rather than creating one per request.
+   */
+  readonly resolve: () =>
+    | EffectConfiguration<R, RuntimeError, P>
+    | PromiseLike<EffectConfiguration<R, RuntimeError, P>>;
+}
+
+const loadBoundary = createServerOnlyFn(() => import("./boundary.server.ts"));
+
+const makeBootstrapFailure = createServerOnlyFn(bootstrapFailure);
+
+/**
+ * Create native Start middleware that supplies Effect execution to server functions.
+ *
+ * Install one owner before authorization and validation middleware. The Vite
+ * plugin's generated handler uses it to decode input and execute business work
+ * in one request Scope, with cancellation tied to the actual HTTP request.
+ * Cleanup completes before native post-handler middleware resumes.
+ *
+ * @param options - Trusted fallback and lazy application configuration.
+ * @returns Function middleware for a configured `createEffectServerFn` builder
+ * or Start's global function-middleware registration.
+ *
+ * @example
+ * ```ts
+ * import { createServerOnlyFn } from "@tanstack/react-start";
+ * import { Effect } from "effect";
+ * import {
+ *   createEffectMiddleware,
+ *   createEffectServerFn as base,
+ * } from "@rc312/tss-effect-serverfn";
+ *
+ * export const createEffectServerFn = base().middleware([
+ *   createEffectMiddleware({
+ *     fallbackFailure: { code: "INTERNAL", message: "Something went wrong" },
+ *     resolve: createServerOnlyFn(() => ({
+ *       runPromiseExit: Effect.runPromiseExit,
+ *     })),
+ *   }),
+ * ]);
+ * ```
+ */
+export const createEffectMiddleware = <
+  R,
+  RuntimeError,
+  P extends object,
+  F extends object,
+>(
+  options: EffectMiddlewareOptions<R, RuntimeError, P, F>
+) =>
+  createMiddleware({ type: "function" }).server<ExecutionCapability<R>>(
+    async ({ next, context, method, serverFnMeta }) => {
+      let boundary: Awaited<ReturnType<typeof loadBoundary>>;
+
+      try {
+        boundary = await loadBoundary();
+      } catch (error) {
+        throw makeBootstrapFailure<F>(options.fallbackFailure, error);
+      }
+
+      return boundary.execute(
+        options,
+        { method, serverFnMeta },
+        context,
+        (execution) => next({ context: execution })
+      );
+    }
+  );

package/src/execution.ts

@@ -0,0 +1,39 @@
+import type { Effect, Scope } from "effect";
+import type { HttpServerRequest } from "effect/http";
+
+/**
+ * Native middleware-context key shared by the compiler bridge and runtime owner.
+ * This server-local capability must never be forwarded through `sendContext`.
+ * @internal
+ */
+export const executionKey = "@rc312/tss-effect-serverfn/execution";
+
+/**
+ * Services supplied by the adapter in addition to the application's services.
+ * The Scope covers decoding and business work. The HTTP request provides
+ * metadata; Start has already consumed the RPC body.
+ * @internal
+ */
+export type RequestServices = Scope.Scope | HttpServerRequest.HttpServerRequest;
+
+/**
+ * Request-local execution contract used by generated handlers.
+ *
+ * Phase notifications occur inside the running Effect immediately before each
+ * stage. Calls to `run` are rejected after the enclosing native middleware ends.
+ *
+ * @template R - Services supplied by the application runtime.
+ * @internal
+ */
+export interface ExecutionCapability<R> {
+  readonly [executionKey]: {
+    /** Run scoped work and await cleanup before resolving or rejecting the Promise. */
+    readonly run: <A, E>(
+      program: Effect.Effect<A, E, R | RequestServices>
+    ) => Promise<A>;
+    /** Classify subsequent failures as input-decoding failures. */
+    readonly beginInput: () => void;
+    /** Classify subsequent failures as handler-execution failures. */
+    readonly beginExecution: () => void;
+  };
+}

package/src/failure.server.ts

@@ -0,0 +1,257 @@
+/* oxlint-disable anti-slop/no-unknown-parameters -- This boundary classifies arbitrary thrown values; parsing them first would lose native control flow and error identity. */
+import { setResponseStatus } from "@tanstack/react-start/server";
+import { isNotFound, isRedirect } from "@tanstack/router-core";
+import {
+  Cause,
+  Effect,
+  ErrorReporter,
+  Exit,
+  Option,
+  Predicate,
+  Schema,
+} from "effect";
+import type { HttpServerRequest } from "effect/http";
+
+import type {
+  EffectConfiguration,
+  FailureReport,
+} from "./effect-middleware.ts";
+import {
+  getServerFnFailureDisposition,
+  ownFailure,
+} from "./provenance.server.ts";
+
+const isControlFlow = (value: unknown) =>
+  value instanceof Response || isRedirect(value) || isNotFound(value);
+
+/**
+ * Extract a typed failure only when it is the Cause's sole reason.
+ * Mixed Causes, defects, and interruption cannot qualify as a public business
+ * error. `Some(undefined)` still represents a real typed failure.
+ */
+const getSingleFailure = <E>(cause: Cause.Cause<E>): Option.Option<E> => {
+  const reason = cause.reasons.length === 1 ? cause.reasons[0] : undefined;
+
+  return reason && Cause.isFailReason(reason)
+    ? Option.some(reason.error)
+    : Option.none();
+};
+
+const isOwnedFailure = (value: unknown) =>
+  getServerFnFailureDisposition(value) !== undefined;
+
+const suppressInterruption = <E>(cause: Cause.Cause<E>) => {
+  const rejection = Cause.squash(cause);
+
+  return Predicate.isObject(rejection)
+    ? ownFailure(rejection, "suppress", cause)
+    : rejection;
+};
+
+/**
+ * Reject a configuration or runtime failure without invoking application policy.
+ * Runtime faults are never approved by the business-error schema, even when
+ * they resemble a public error or native redirect.
+ *
+ * @param fallback - Trusted rejection record to copy for an unexpected failure.
+ * @param cause - Original failure retained in the server-local registry.
+ * @throws {unknown} The squashed interruption, or a fresh fallback with native reporting ownership.
+ * @internal
+ */
+export const rejectRuntimeFailure = <F extends object, E>(
+  fallback: F,
+  cause: Cause.Cause<E>
+): never => {
+  if (Cause.hasInterruptsOnly(cause)) {
+    throw suppressInterruption(cause);
+  }
+
+  throw ownFailure({ ...fallback }, "native", cause);
+};
+
+/**
+ * Handle a rejection escaping the native middleware chain.
+ * Recognized control flow and already-owned rejections retain their identity.
+ * Other values, including objects whose inspection throws, receive the trusted
+ * fallback without loading the application runtime.
+ *
+ * @param fallback - Trusted rejection record for unrecognized failures.
+ * @param error - Value thrown by native middleware or the generated handler.
+ * @throws {unknown} The recognized rejection or a registered fallback record.
+ * @internal
+ */
+export const rejectMiddlewareFailure = <F extends object>(
+  fallback: F,
+  error: unknown
+): never => {
+  let passthrough = false;
+
+  try {
+    passthrough = isControlFlow(error) || isOwnedFailure(error);
+  } catch {
+    // Inspection faults remain private.
+  }
+
+  if (passthrough) {
+    throw error;
+  }
+
+  return rejectRuntimeFailure(fallback, Cause.fail(error));
+};
+
+/**
+ * Await the selected reporter and determine who owns further reporting.
+ * An explicit override replaces native reporting and its ignore policy. The
+ * override is interruptible and timeout-bounded even during masked rejection
+ * processing. Reporter failures leave ownership with the outer framework.
+ *
+ * @returns An Effect yielding `boundary` after handling, `suppress` for a native
+ * ignore annotation, or `native` when outer framework reporting is still needed.
+ */
+const reportFailure = Effect.fnUntraced(function* reportFailure<
+  R,
+  RuntimeError,
+  P extends object,
+>(
+  report: FailureReport,
+  configuration: EffectConfiguration<R, RuntimeError, P>,
+  ignoredByNativeReporter: boolean
+): Effect.fn.Return<
+  "native" | "boundary" | "suppress",
+  never,
+  R | HttpServerRequest.HttpServerRequest
+> {
+  const { reportFailure: override, reportTimeout } = configuration;
+
+  if (override) {
+    const reportingExit = yield* Effect.exit(
+      Effect.suspend(() => override(report)).pipe(
+        Effect.interruptible,
+        Effect.timeout(reportTimeout ?? "5 seconds")
+      )
+    );
+
+    return Exit.isSuccess(reportingExit) ? "boundary" : "native";
+  }
+
+  const reporters = yield* ErrorReporter.CurrentErrorReporters;
+  const reportingExit = yield* Effect.exit(ErrorReporter.report(report.cause));
+
+  if (ignoredByNativeReporter) {
+    return "suppress";
+  }
+
+  return Exit.isSuccess(reportingExit) && reporters.size > 0
+    ? "boundary"
+    : "native";
+});
+
+/**
+ * Project a completed operation's Cause into a client rejection and report it.
+ *
+ * Pure interruption and native control flow pass through without reporting.
+ * Ordinary decoder failures become `INVALID_INPUT` with HTTP 400. Only a single
+ * execution failure can be approved by the public-error encoder; other failures
+ * use the trusted fallback. Diagnostics stay attached by server-local identity.
+ *
+ * The caller must close the operation Scope before running this Effect and
+ * contain any defect in projection itself. Encoder/reporter services come from
+ * the application runtime and HTTP request, not the closed operation Scope.
+ *
+ * @returns An Effect yielding the rejection value for the Promise boundary to
+ * throw. The original Cause is preserved separately from the client payload.
+ * @internal
+ */
+export const projectFailure = Effect.fnUntraced(function* projectFailure<
+  R,
+  RuntimeError,
+  P extends object,
+  F extends object,
+>(
+  cause: Cause.Cause<unknown>,
+  phase: FailureReport["phase"],
+  configuration: EffectConfiguration<R, RuntimeError, P>,
+  fallback: F,
+  serverFnMeta: FailureReport["serverFnMeta"]
+) {
+  if (Cause.hasInterruptsOnly(cause)) {
+    return suppressInterruption(cause);
+  }
+
+  let failure: FailureReport["failure"] = { ...fallback };
+  let processingCause: Cause.Cause<unknown> | undefined;
+
+  const inspectionExit = yield* Effect.exit(
+    Effect.sync(() => {
+      const single = getSingleFailure(cause);
+
+      return Option.isSome(single)
+        ? {
+            ignored: ErrorReporter.isIgnored(single.value),
+            invalidInput:
+              phase === "input" && Schema.isSchemaError(single.value),
+            passthrough:
+              isControlFlow(single.value) || isOwnedFailure(single.value),
+            value: single.value,
+          }
+        : undefined;
+    })
+  );
+
+  if (Exit.isFailure(inspectionExit)) {
+    processingCause = inspectionExit.cause;
+  } else if (inspectionExit.value) {
+    const single = inspectionExit.value;
+
+    if (single.passthrough) {
+      return single.value;
+    }
+
+    if (single.invalidInput) {
+      yield* Effect.sync(() => setResponseStatus(400));
+
+      return ownFailure(
+        { code: "INVALID_INPUT", message: "Invalid input" },
+        "suppress",
+        cause
+      );
+    }
+
+    const { publicError } = configuration;
+
+    if (phase === "execution" && publicError) {
+      const encodingExit = yield* Effect.exit(
+        Effect.suspend(() =>
+          Schema.encodeUnknownEffect(publicError, {
+            onExcessProperty: "ignore",
+          })(single.value)
+        )
+      );
+
+      if (Exit.isSuccess(encodingExit)) {
+        failure = encodingExit.value;
+      } else {
+        processingCause = encodingExit.cause;
+      }
+    }
+  }
+
+  const report: FailureReport = {
+    cause,
+    failure,
+    phase,
+    processingCause,
+    serverFnMeta,
+  };
+
+  const ignored =
+    Exit.isSuccess(inspectionExit) && inspectionExit.value?.ignored === true;
+
+  const disposition = yield* reportFailure(report, configuration, ignored);
+
+  if (Predicate.isObject(failure)) {
+    return ownFailure({ ...failure }, disposition, cause);
+  }
+
+  return ownFailure({ ...fallback }, "native", cause);
+});

package/src/index.ts

@@ -0,0 +1,12 @@
+export {
+  type CreateEffectServerFn,
+  createEffectServerFn,
+  type EffectServerFnBuilder,
+} from "./create-effect-server-fn.ts";
+
+export {
+  type EffectConfiguration,
+  type EffectMiddlewareOptions,
+  createEffectMiddleware,
+  type FailureReport,
+} from "./effect-middleware.ts";