@beignet/core 0.0.52 → 0.0.53

package/src/server/use-case-route.ts

@@ -149,20 +149,143 @@ export type UseCaseRouteInputParts<C extends HttpContractConfig> = {
   body: InferBody<C>;
 };
 
+type SegmentPathParam<Segment extends string> = Segment extends `:${infer Name}`
+  ? Name
+  : Segment extends `[${infer Name}]`
+    ? Name
+    : never;
+
+type PathParamNames<Path extends string> = string extends Path
+  ? never
+  : Path extends `${infer Segment}/${infer Rest}`
+    ? SegmentPathParam<Segment> | PathParamNames<Rest>
+    : SegmentPathParam<Path>;
+
+type EmptyBinderInput = Record<never, never>;
+
+declare const UNMERGEABLE_BINDER_INPUT: unique symbol;
+
+type UnmergeableBinderInput = {
+  readonly [UNMERGEABLE_BINDER_INPUT]: true;
+};
+
+type IsAny<T> = 0 extends 1 & T ? true : false;
+
+type BinderObject<T> =
+  IsAny<T> extends true
+    ? UnmergeableBinderInput
+    : [T] extends [object]
+      ? [Extract<T, readonly unknown[]>] extends [never]
+        ? T
+        : UnmergeableBinderInput
+      : UnmergeableBinderInput;
+
+type MergeBinderObjects<LowerPrecedence, HigherPrecedence> = [
+  BinderObject<LowerPrecedence>,
+] extends [UnmergeableBinderInput]
+  ? UnmergeableBinderInput
+  : [BinderObject<HigherPrecedence>] extends [UnmergeableBinderInput]
+    ? UnmergeableBinderInput
+    : Omit<
+        BinderObject<LowerPrecedence>,
+        keyof BinderObject<HigherPrecedence>
+      > &
+        BinderObject<HigherPrecedence>;
+
+type InferredPathInput<C extends HttpContractConfig> = string extends C["path"]
+  ? UnmergeableBinderInput
+  : [PathParamNames<C["path"]>] extends [never]
+    ? EmptyBinderInput
+    : { [K in PathParamNames<C["path"]>]: string };
+
+type BinderPathInput<C extends HttpContractConfig> =
+  C["pathParams"] extends StandardSchemaV1
+    ? InferOutput<C["pathParams"]>
+    : InferredPathInput<C>;
+
+type BinderQueryInput<C extends HttpContractConfig> =
+  C["query"] extends StandardSchemaV1
+    ? InferOutput<C["query"]>
+    : EmptyBinderInput;
+
+type BinderBodyInput<C extends HttpContractConfig> =
+  C["body"] extends StandardSchemaV1
+    ? InferOutput<C["body"]>
+    : EmptyBinderInput;
+
+type HasPathSchema<C extends HttpContractConfig> =
+  C["pathParams"] extends StandardSchemaV1 ? true : false;
+
+type HasQuerySchema<C extends HttpContractConfig> =
+  C["query"] extends StandardSchemaV1 ? true : false;
+
+type HasBodySchema<C extends HttpContractConfig> =
+  C["body"] extends StandardSchemaV1 ? true : false;
+
+type HasInferredPathInput<C extends HttpContractConfig> =
+  string extends C["path"]
+    ? true
+    : [PathParamNames<C["path"]>] extends [never]
+      ? false
+      : true;
+
+type MergedBinderInput<C extends HttpContractConfig> = MergeBinderObjects<
+  MergeBinderObjects<BinderQueryInput<C>, BinderBodyInput<C>>,
+  BinderPathInput<C>
+>;
+
+/**
+ * Input produced when a binder route omits an explicit `input` mapper.
+ *
+ * A sole declared request schema passes through unchanged when the literal
+ * path has no additional inferred parameters. Every other supported default
+ * binding merges object inputs with path over body over query precedence.
+ */
+type DefaultBinderRouteInput<C extends HttpContractConfig> =
+  HasPathSchema<C> extends true
+    ? HasQuerySchema<C> extends true
+      ? MergedBinderInput<C>
+      : HasBodySchema<C> extends true
+        ? MergedBinderInput<C>
+        : BinderPathInput<C>
+    : HasQuerySchema<C> extends true
+      ? HasBodySchema<C> extends true
+        ? MergedBinderInput<C>
+        : HasInferredPathInput<C> extends true
+          ? MergedBinderInput<C>
+          : BinderQueryInput<C>
+      : HasBodySchema<C> extends true
+        ? HasInferredPathInput<C> extends true
+          ? MergedBinderInput<C>
+          : BinderBodyInput<C>
+        : BinderPathInput<C>;
+
+type UseCaseRouteInputMode = "default" | "mapped";
+
 /**
  * Constraint that checks a use case against the route that binds it.
  *
  * Produces a readable branded mismatch object on the `useCase` property when
- * the use case requires a context the server does not provide, or when its
- * output does not match the contract's declared success response schema.
+ * the use case requires a context the server does not provide, when its
+ * output does not match the contract's declared success response schema, or
+ * when the default binder input does not satisfy the use case input.
  */
-export type UseCaseFitsRoute<Ctx, C extends HttpContractConfig, UC> = [
+export type UseCaseFitsRoute<
   Ctx,
-] extends [UseCaseRouteCtx<UC>]
+  C extends HttpContractConfig,
+  UC,
+  InputMode extends UseCaseRouteInputMode = "default",
+> = [Ctx] extends [UseCaseRouteCtx<UC>]
   ? [UseCaseRouteOutput<UC>] extends [
       SuccessBodyFromKeys<C["responses"], Success2xxKeys<C["responses"]>>,
     ]
-    ? unknown
+    ? InputMode extends "mapped"
+      ? unknown
+      : [DefaultBinderRouteInput<C>] extends [UseCaseRouteInput<UC>]
+        ? unknown
+        : {
+            "~beignetError": "default binder input does not match the use case input; add an input mapper";
+          }
     : {
         "~beignetError": "useCase output does not match the contract's success response schema";
       }
@@ -185,21 +308,34 @@ type UseCaseRouteShape<
    * Route-scoped hooks that run after group hooks and before the use case.
    */
   hooks?: Hooks;
-  /**
-   * Use case bound directly to the contract.
-   */
-  useCase: UC & UseCaseFitsRoute<HandlerCtx, C, UC>;
-  /**
-   * Map parsed request parts to the use case input.
-   *
-   * A sole declared path, query, or body schema is passed through unchanged
-   * when no additional path, query, or object body values are present.
-   * Otherwise `defaultBinderInput` merges query, body, and path objects (path
-   * wins collisions) and never merges headers.
-   */
-  input?: (parts: UseCaseRouteInputParts<C>) => UseCaseRouteInput<UC>;
   handle?: never;
-} & BinderStatusOption<C>;
+} & (
+  | {
+      /**
+       * Use case bound directly to the contract. The default binder input
+       * must satisfy the use case input type.
+       */
+      useCase: UC & UseCaseFitsRoute<HandlerCtx, C, UC>;
+      input?: never;
+    }
+  | {
+      /**
+       * Use case bound directly to the contract through an explicit input
+       * mapper.
+       */
+      useCase: UC & UseCaseFitsRoute<HandlerCtx, C, UC, "mapped">;
+      /**
+       * Map parsed request parts to the use case input.
+       *
+       * A sole declared path, query, or body schema is passed through
+       * unchanged when no additional path, query, or object body values are
+       * present. Otherwise `defaultBinderInput` merges query, body, and path
+       * objects (path wins collisions) and never merges headers.
+       */
+      input: (parts: UseCaseRouteInputParts<C>) => UseCaseRouteInput<UC>;
+    }
+) &
+  BinderStatusOption<C>;
 
 /**
  * Route registration that binds a contract directly to a use case.
@@ -271,11 +407,25 @@ export type ValidatedRouteInput<Ctx, E> = E extends {
     ? {
         contract: CL;
         hooks?: HooksOf<E>;
-        useCase: UC &
-          UseCaseFitsRoute<Ctx & AddedCtxFromHooks<HooksOf<E>>, C, UC>;
-        input?: (parts: UseCaseRouteInputParts<C>) => UseCaseRouteInput<UC>;
         handle?: never;
-      } & BinderStatusOption<C>
+      } & (
+        | {
+            useCase: UC &
+              UseCaseFitsRoute<Ctx & AddedCtxFromHooks<HooksOf<E>>, C, UC>;
+            input?: never;
+          }
+        | {
+            useCase: UC &
+              UseCaseFitsRoute<
+                Ctx & AddedCtxFromHooks<HooksOf<E>>,
+                C,
+                UC,
+                "mapped"
+              >;
+            input: (parts: UseCaseRouteInputParts<C>) => UseCaseRouteInput<UC>;
+          }
+      ) &
+        BinderStatusOption<C>
     : unknown
   : unknown;
 
@@ -322,6 +472,49 @@ export type RuntimeUseCaseRouteDef = {
   status?: number;
 };
 
+type UseCaseInputValidationFailure = Error & {
+  name: "UseCaseValidationError";
+  phase: "input";
+  useCaseName: string;
+};
+
+function isUseCaseInputValidationFailure(
+  error: unknown,
+  useCaseName: string,
+): error is UseCaseInputValidationFailure {
+  if (!(error instanceof Error)) return false;
+  const candidate = error as Partial<UseCaseInputValidationFailure>;
+  return (
+    candidate.name === "UseCaseValidationError" &&
+    candidate.phase === "input" &&
+    candidate.useCaseName === useCaseName
+  );
+}
+
+/**
+ * Internal framework error raised when a type-erased binder route produces an
+ * input that the bound use case rejects.
+ */
+export class UseCaseRouteInputValidationError extends Error {
+  readonly code = "USE_CASE_INPUT_VALIDATION_ERROR";
+  readonly contractName: string;
+  readonly useCaseName: string;
+
+  constructor(args: {
+    contractName: string;
+    useCaseName: string;
+    cause: UseCaseInputValidationFailure;
+  }) {
+    super(
+      `Default binder input for contract "${args.contractName}" does not satisfy use case "${args.useCaseName}". Add an explicit input mapper.`,
+      { cause: args.cause },
+    );
+    this.name = "UseCaseRouteInputValidationError";
+    this.contractName = args.contractName;
+    this.useCaseName = args.useCaseName;
+  }
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -458,10 +651,24 @@ export function createUseCaseRouteHandler<Ctx, C extends HttpContractConfig>(
         : defaultBinderInput(parts);
     const run = passSingle && trustedRun ? trustedRun : def.useCase.run;
 
-    return {
-      status,
-      body: await run.call(def.useCase, { ctx, input }),
-    };
+    try {
+      return {
+        status,
+        body: await run.call(def.useCase, { ctx, input }),
+      };
+    } catch (error) {
+      if (
+        !def.input &&
+        isUseCaseInputValidationFailure(error, def.useCase.name)
+      ) {
+        throw new UseCaseRouteInputValidationError({
+          contractName: contract.name,
+          useCaseName: def.useCase.name,
+          cause: error,
+        });
+      }
+      throw error;
+    }
   };
 
   return {