@beignet/core 0.0.3 → 0.0.4

package/src/server/types.ts

@@ -1,2 +1,2 @@
-export * from "./contract-like";
-export * from "./http";
+export * from "./contract-like.js";
+export * from "./http.js";

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

@@ -0,0 +1,430 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type {
+  HttpContractConfig,
+  InferOutput,
+  Success2xxKeys,
+} from "../contracts/index.js";
+import { inferSoleSuccessStatus } from "../contracts/index.js";
+import type { ContractLike, ResolveContract } from "./contract-like.js";
+import type {
+  AddedCtxFromHooks,
+  Handler,
+  InferBody,
+  InferHeaders,
+  InferPath,
+  InferQuery,
+  RouteHook,
+} from "./http.js";
+
+/**
+ * Structural shape of a finalized use case accepted by the route binder.
+ *
+ * This intentionally mirrors `UseCaseDef` from `@beignet/core/application`
+ * without importing it, so the server runtime stays decoupled from the
+ * application builder at runtime.
+ */
+export type AnyUseCaseLike = {
+  /**
+   * Stable use-case name, used in binder diagnostics.
+   */
+  name: string;
+  /**
+   * Input schema declared with `.input(...)`.
+   */
+  inputSchema: StandardSchemaV1;
+  /**
+   * Output schema declared with `.output(...)`.
+   */
+  outputSchema: StandardSchemaV1;
+  /**
+   * Execute the use case with application context and typed input.
+   */
+  run: (args: never) => Promise<unknown>;
+};
+
+type UseCaseRouteCtx<UC> = UC extends {
+  run: (args: { ctx: infer Ctx; input: infer _Input }) => Promise<infer _Out>;
+}
+  ? Ctx
+  : never;
+
+/**
+ * Input type accepted by a bound use case's `run(...)`.
+ */
+export type UseCaseRouteInput<UC> = UC extends {
+  run: (args: { ctx: infer _Ctx; input: infer Input }) => Promise<infer _Out>;
+}
+  ? Input
+  : never;
+
+type UseCaseRouteOutput<UC> = UC extends {
+  run: (args: { ctx: infer _Ctx; input: infer _Input }) => Promise<infer Out>;
+}
+  ? Out
+  : never;
+
+type ResponseBodyForSchema<S> = S extends null
+  ? // biome-ignore lint/suspicious/noConfusingVoidType: void accepts z.void() use case outputs for null response schemas
+    void | undefined
+  : S extends StandardSchemaV1
+    ? InferOutput<S>
+    : unknown;
+
+type ResponseForStatus<
+  TResponses,
+  TStatus extends number,
+> = TStatus extends keyof TResponses
+  ? TResponses[TStatus]
+  : `${TStatus}` extends keyof TResponses
+    ? TResponses[`${TStatus}`]
+    : never;
+
+type SuccessBodyFromKeys<TResponses, K> = [K] extends [never]
+  ? unknown
+  : K extends number
+    ? ResponseBodyForSchema<ResponseForStatus<TResponses, K>>
+    : unknown;
+
+type UnionToIntersection<T> = (
+  T extends unknown
+    ? (value: T) => void
+    : never
+) extends (value: infer I) => void
+  ? I
+  : never;
+
+type BinderStatusFromKeys<K> = [K] extends [never]
+  ? {
+      /**
+       * Success status for the use case result. Required because the contract
+       * does not declare exactly one 2xx response.
+       */
+      status: number;
+    }
+  : [K] extends [UnionToIntersection<K>]
+    ? {
+        /**
+         * Success status for the use case result. Optional because the
+         * contract declares exactly one 2xx response.
+         */
+        status?: K;
+      }
+    : {
+        /**
+         * Success status for the use case result. Required because the
+         * contract declares multiple 2xx responses.
+         */
+        status: K;
+      };
+
+/**
+ * `status` option for a binder route.
+ *
+ * Optional and typed to the sole declared 2xx status when the contract
+ * declares exactly one, required (typed to the union of declared 2xx
+ * statuses) otherwise.
+ */
+export type BinderStatusOption<C extends HttpContractConfig> =
+  BinderStatusFromKeys<Success2xxKeys<C["responses"]>>;
+
+/**
+ * Parsed request parts passed to a binder route's `input` mapper.
+ */
+export type UseCaseRouteInputParts<C extends HttpContractConfig> = {
+  /**
+   * Parsed path parameters.
+   */
+  path: InferPath<C>;
+  /**
+   * Parsed query parameters.
+   */
+  query: InferQuery<C>;
+  /**
+   * Parsed request headers.
+   */
+  headers: InferHeaders<C>;
+  /**
+   * Parsed request body.
+   */
+  body: InferBody<C>;
+};
+
+/**
+ * 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.
+ */
+export type UseCaseFitsRoute<Ctx, C extends HttpContractConfig, UC> = [
+  Ctx,
+] extends [UseCaseRouteCtx<UC>]
+  ? [UseCaseRouteOutput<UC>] extends [
+      SuccessBodyFromKeys<C["responses"], Success2xxKeys<C["responses"]>>,
+    ]
+    ? unknown
+    : {
+        "~beignetError": "useCase output does not match the contract's success response schema";
+      }
+  : {
+      "~beignetError": "useCase requires a context this server does not provide";
+    };
+
+type UseCaseRouteShape<
+  HandlerCtx,
+  CLike extends ContractLike,
+  C extends HttpContractConfig,
+  UC extends AnyUseCaseLike,
+  Hooks,
+> = {
+  /**
+   * Contract builder or plain contract config for this route.
+   */
+  contract: CLike;
+  /**
+   * 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.
+   *
+   * Defaults to `defaultBinderInput`, which merges query, body, and path
+   * objects (path wins collisions) and never merges headers.
+   */
+  input?: (parts: UseCaseRouteInputParts<C>) => UseCaseRouteInput<UC>;
+  handle?: never;
+} & BinderStatusOption<C>;
+
+/**
+ * Route registration that binds a contract directly to a use case.
+ *
+ * The server synthesizes the handler: it maps parsed request parts to the use
+ * case input, runs the use case, and returns its output as the success
+ * response body. Use a full `handle` route for headers, streaming, native
+ * `Response` values, or multi-status handling.
+ */
+export type UseCaseRouteDef<
+  Ctx,
+  CLike extends ContractLike,
+  UC extends AnyUseCaseLike,
+  Hooks extends readonly RouteHook<Ctx, object>[] = readonly [],
+> = UseCaseRouteShape<
+  Ctx & AddedCtxFromHooks<Hooks>,
+  CLike,
+  ResolveContract<CLike>,
+  UC,
+  Hooks
+>;
+
+/**
+ * Structural check that a use case accepts the context this route provides.
+ *
+ * Enforced through `run` parameter contravariance so it applies even where
+ * contract types are erased, such as `defineRouteGroup<Ctx>({ ... })`.
+ */
+export type UseCaseAcceptsCtx<Ctx> = {
+  run: (args: { ctx: Ctx; input: never }) => Promise<unknown>;
+};
+
+/**
+ * Loosely typed binder route used at collection boundaries where contract and
+ * use case types are erased. The use case's context requirement is still
+ * checked against the server context.
+ */
+export type AnyUseCaseRouteDef<
+  Ctx,
+  CLike extends ContractLike = ContractLike,
+  Hooks extends readonly RouteHook<Ctx, object>[] = readonly RouteHook<
+    Ctx,
+    object
+  >[],
+> = {
+  contract: CLike;
+  hooks?: Hooks;
+  useCase: AnyUseCaseLike & UseCaseAcceptsCtx<Ctx & AddedCtxFromHooks<Hooks>>;
+  // biome-ignore lint/suspicious/noExplicitAny: request part types are erased at collection boundaries
+  input?: (parts: any) => unknown;
+  status?: number;
+  handle?: never;
+};
+
+type HooksOf<E> = E extends { hooks: infer H extends readonly unknown[] }
+  ? H
+  : readonly [];
+
+/**
+ * Per-element binder validation applied where route tuples are inferred, such
+ * as `defineRouteGroup<Ctx>()({ ... })`, so contract/use-case mismatches are
+ * reported on the individual route literal.
+ */
+export type ValidatedRouteInput<Ctx, E> = E extends {
+  contract: infer CL extends ContractLike;
+  useCase: infer UC extends AnyUseCaseLike;
+}
+  ? ResolveContract<CL> extends infer C extends HttpContractConfig
+    ? {
+        contract: CL;
+        hooks?: HooksOf<E>;
+        useCase: UC &
+          UseCaseFitsRoute<Ctx & AddedCtxFromHooks<HooksOf<E>>, C, UC>;
+        input?: (parts: UseCaseRouteInputParts<C>) => UseCaseRouteInput<UC>;
+        handle?: never;
+      } & BinderStatusOption<C>
+    : unknown
+  : unknown;
+
+/**
+ * Element-wise binder validation for a route input list.
+ */
+export type ValidatedRouteInputs<Ctx, R extends readonly unknown[]> = {
+  [K in keyof R]: ValidatedRouteInput<Ctx, R[K]>;
+};
+
+/**
+ * Trusted run key shared with `@beignet/core/application` via the global
+ * symbol registry, so the binder never imports the application builder at
+ * runtime.
+ */
+const USE_CASE_TRUSTED_RUN_KEY: unique symbol = Symbol.for(
+  "beignet.useCase.trustedRun",
+);
+
+type RuntimeUseCase = AnyUseCaseLike & {
+  run: (args: { ctx: unknown; input: unknown }) => Promise<unknown>;
+  [USE_CASE_TRUSTED_RUN_KEY]?: (args: {
+    ctx: unknown;
+    input: unknown;
+  }) => Promise<unknown>;
+};
+
+/**
+ * Loosely typed binder route definition consumed by route registration.
+ */
+export type RuntimeUseCaseRouteDef = {
+  useCase: RuntimeUseCase;
+  input?: (parts: {
+    path: unknown;
+    query: unknown;
+    headers: unknown;
+    body: unknown;
+  }) => unknown;
+  status?: number;
+};
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Default input mapping for binder routes.
+ *
+ * Merges parsed query, body, and path objects into one input object. Path
+ * keys win all collisions, then body keys, then query keys. Headers are never
+ * merged: parsed headers include every raw request header, so merging them
+ * would poison the use case input. Non-object bodies (text, arrays, scalars)
+ * are excluded. Routes that need headers or non-object bodies declare an
+ * explicit `input` mapper.
+ */
+export function defaultBinderInput(parts: {
+  path: unknown;
+  query: unknown;
+  body: unknown;
+}): Record<string, unknown> {
+  return {
+    ...(isPlainObject(parts.query) ? parts.query : {}),
+    ...(isPlainObject(parts.body) ? parts.body : {}),
+    ...(isPlainObject(parts.path) ? parts.path : {}),
+  };
+}
+
+/**
+ * Whether a route definition is a binder route.
+ */
+export function isUseCaseRouteDef(route: {
+  handle?: unknown;
+  useCase?: unknown;
+}): route is RuntimeUseCaseRouteDef {
+  return route.useCase !== undefined && route.useCase !== null;
+}
+
+function computeTrustedInput(
+  contract: HttpContractConfig,
+  def: RuntimeUseCaseRouteDef,
+): boolean {
+  if (def.input) return false;
+
+  const sources = [contract.pathParams, contract.query, contract.body].filter(
+    (schema) => schema !== null && schema !== undefined,
+  );
+  return sources.length === 1 && sources[0] === def.useCase.inputSchema;
+}
+
+function computeResponseExemption(
+  contract: HttpContractConfig,
+  def: RuntimeUseCaseRouteDef,
+  status: number,
+): number | undefined {
+  return contract.responses[status] === def.useCase.outputSchema
+    ? status
+    : undefined;
+}
+
+/**
+ * Synthesize the route handler for a binder route at registration time.
+ *
+ * Resolves the success status, decides whether the validated request parts can
+ * skip the use case's input parse, and computes whether server-side response
+ * validation is redundant for the success status.
+ */
+export function createUseCaseRouteHandler<Ctx, C extends HttpContractConfig>(
+  contract: C,
+  def: RuntimeUseCaseRouteDef,
+): {
+  handler: Handler<Ctx, C>;
+  responseValidationExemptStatus?: number;
+} {
+  const status = def.status ?? inferSoleSuccessStatus(contract);
+  if (status === undefined) {
+    throw new Error(
+      `Route binder for contract "${contract.name}" cannot infer a success ` +
+        `status: the contract declares ${
+          Object.keys(contract.responses).length === 0
+            ? "no responses"
+            : "zero or multiple 2xx responses"
+        }. Declare exactly one 2xx response or pass an explicit status.`,
+    );
+  }
+
+  const mapInput = def.input ?? defaultBinderInput;
+  const trustedRun = computeTrustedInput(contract, def)
+    ? def.useCase[USE_CASE_TRUSTED_RUN_KEY]
+    : undefined;
+  const run = trustedRun ?? def.useCase.run;
+
+  const handler: Handler<Ctx, C> = async ({
+    ctx,
+    path,
+    query,
+    headers,
+    body,
+  }) => ({
+    status,
+    body: await run.call(def.useCase, {
+      ctx,
+      input: mapInput({ path, query, headers, body }),
+    }),
+  });
+
+  return {
+    handler,
+    responseValidationExemptStatus: computeResponseExemption(
+      contract,
+      def,
+      status,
+    ),
+  };
+}

package/src/server-only.ts

@@ -0,0 +1,7 @@
+/**
+ * Static Beignet lint marker for modules that must stay out of client bundles.
+ *
+ * Host frameworks may provide their own runtime-only enforcement. This marker
+ * is intentionally a no-op so Beignet can enforce intent through `beignet lint`.
+ */
+export const beignetServerOnly = true;

package/src/tasks/index.ts

@@ -0,0 +1,275 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+/**
+ * Any Standard Schema compatible validator.
+ */
+export type StandardSchema = StandardSchemaV1<unknown, unknown>;
+
+/**
+ * Value or promise of that value.
+ */
+export type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Infer the parsed output type from a Standard Schema.
+ */
+export type InferSchemaOutput<T extends StandardSchemaV1> =
+  StandardSchemaV1.InferOutput<T>;
+
+/**
+ * Operational task definition created by `defineTask(...)`.
+ */
+export interface TaskDef<
+  Name extends string = string,
+  Input extends StandardSchema = StandardSchema,
+  Ctx = unknown,
+  Output = unknown,
+> {
+  /**
+   * Discriminator for task definitions.
+   */
+  readonly kind: "task";
+  /**
+   * Stable task name used by CLIs and operational runners.
+   */
+  readonly name: Name;
+  /**
+   * Standard Schema input validator.
+   */
+  readonly input: Input;
+  /**
+   * Optional human-readable description for docs and tooling.
+   */
+  readonly description?: string;
+  /**
+   * Handle a parsed task input.
+   */
+  handle(
+    args: TaskHandleArgs<TaskDef<Name, Input, Ctx, Output>, Ctx>,
+  ): MaybePromise<Output>;
+}
+
+/**
+ * Infer the parsed input type for an operational task.
+ */
+export type InferTaskInput<T extends TaskDef> =
+  T["input"] extends StandardSchemaV1<unknown, infer Output> ? Output : never;
+
+/**
+ * Infer the result type for an operational task.
+ */
+export type InferTaskOutput<T extends TaskDef> =
+  T extends TaskDef<string, StandardSchema, unknown, infer Output>
+    ? Awaited<Output>
+    : never;
+
+/**
+ * Arguments passed to a task handler.
+ */
+export interface TaskHandleArgs<T extends TaskDef, Ctx> {
+  /**
+   * Task definition being handled.
+   */
+  task: T;
+  /**
+   * Parsed task input.
+   */
+  input: InferTaskInput<T>;
+  /**
+   * Handler context.
+   */
+  ctx: Ctx;
+}
+
+/**
+ * Options for `defineTask(...)`.
+ */
+export interface DefineTaskOptions<
+  Name extends string,
+  Input extends StandardSchema,
+  Ctx,
+  Output,
+> {
+  /**
+   * Standard Schema input validator.
+   */
+  input: Input;
+  /**
+   * Optional human-readable description for docs and tooling.
+   */
+  description?: string;
+  /**
+   * Handle a parsed task input.
+   */
+  handle(
+    args: TaskHandleArgs<TaskDef<Name, Input, Ctx, Output>, Ctx>,
+  ): MaybePromise<Output>;
+}
+
+/**
+ * Options for one task run.
+ */
+export interface RunTaskOptions<Ctx> {
+  /**
+   * Raw task input. It is parsed with the task's Standard Schema before the
+   * handler runs.
+   */
+  input: unknown;
+  /**
+   * Handler context.
+   */
+  ctx: Ctx;
+}
+
+/**
+ * Context-bound operational task helper factory.
+ */
+export interface Tasks<Ctx> {
+  /**
+   * Define a task with the bound context type.
+   */
+  defineTask<
+    Name extends string,
+    Input extends StandardSchema,
+    Output = unknown,
+  >(
+    name: Name,
+    options: DefineTaskOptions<Name, Input, Ctx, Output>,
+  ): TaskDef<Name, Input, Ctx, Output>;
+}
+
+/**
+ * Error thrown when task input validation fails.
+ */
+export class TaskValidationError extends Error {
+  /**
+   * Raw Standard Schema validation issues.
+   */
+  readonly issues: readonly StandardSchemaV1.Issue[];
+
+  constructor(args: {
+    name: string;
+    issues: readonly StandardSchemaV1.Issue[];
+  }) {
+    super(
+      `Task "${args.name}" input validation failed: ${formatIssues(args.issues)}`,
+    );
+    this.name = "TaskValidationError";
+    this.issues = args.issues;
+  }
+}
+
+function formatPath(path: StandardSchemaV1.Issue["path"]): string {
+  if (!path || path.length === 0) return "";
+
+  return path
+    .map((segment) => {
+      if (typeof segment === "number") return `[${segment}]`;
+      const key = String(segment);
+      return /^[A-Za-z_$][\w$]*$/.test(key)
+        ? `.${key}`
+        : `[${JSON.stringify(key)}]`;
+    })
+    .join("")
+    .replace(/^\./, "");
+}
+
+function formatIssues(issues: readonly StandardSchemaV1.Issue[]): string {
+  return issues
+    .map((issue) => {
+      const path = formatPath(issue.path);
+      return path ? `${path}: ${issue.message}` : issue.message;
+    })
+    .join("; ");
+}
+
+async function parseInput<Schema extends StandardSchemaV1>(
+  schema: Schema,
+  input: unknown,
+  options: { name: string },
+): Promise<InferSchemaOutput<Schema>> {
+  const result = await schema["~standard"].validate(input);
+
+  if (result.issues?.length) {
+    throw new TaskValidationError({
+      name: options.name,
+      issues: result.issues,
+    });
+  }
+
+  return (result as { value: InferSchemaOutput<Schema> }).value;
+}
+
+function defineTaskImpl<
+  Name extends string,
+  Input extends StandardSchema,
+  Ctx = unknown,
+  Output = unknown,
+>(
+  name: Name,
+  options: DefineTaskOptions<Name, Input, Ctx, Output>,
+): TaskDef<Name, Input, Ctx, Output> {
+  return {
+    kind: "task",
+    name,
+    input: options.input,
+    description: options.description,
+    handle: options.handle as TaskDef<Name, Input, Ctx, Output>["handle"],
+  };
+}
+
+/**
+ * Validate and parse a task input with the task's Standard Schema.
+ */
+export async function parseTaskInput<T extends TaskDef>(
+  task: T,
+  input: unknown,
+): Promise<InferTaskInput<T>> {
+  return (await parseInput(task.input, input, {
+    name: task.name,
+  })) as InferTaskInput<T>;
+}
+
+/**
+ * Parse input and run an operational task.
+ */
+export async function runTask<
+  T extends TaskDef<string, StandardSchema, Ctx>,
+  Ctx,
+>(task: T, options: RunTaskOptions<Ctx>): Promise<InferTaskOutput<T>> {
+  const parsed = await parseTaskInput(task, options.input);
+  return (await task.handle({
+    task,
+    input: parsed,
+    ctx: options.ctx,
+  })) as InferTaskOutput<T>;
+}
+
+/**
+ * Define a task registry while preserving tuple inference.
+ */
+export function defineTasks<const Defs extends readonly TaskDef[]>(
+  tasks: Defs,
+): Defs {
+  return tasks;
+}
+
+/**
+ * Create task helper methods bound to an application context type.
+ *
+ * Call it once in `lib/tasks.ts`:
+ *
+ * ```ts
+ * export const { defineTask } = createTasks<AppContext>();
+ * ```
+ */
+export function createTasks<Ctx>(): Tasks<Ctx> {
+  return {
+    defineTask<Name extends string, Input extends StandardSchema, Output>(
+      name: Name,
+      options: DefineTaskOptions<Name, Input, Ctx, Output>,
+    ) {
+      return defineTaskImpl<Name, Input, Ctx, Output>(name, options);
+    },
+  };
+}