@controller-contract/server 0.3.3 → 0.4.0

package/dist/index-DvVe6qYj.d.mts

@@ -0,0 +1,44 @@
+import { ExitOutput, FailOutput, NextOutput, PassOutput } from "@controller-contract/core";
+//#region src/utils/outputs.d.ts
+declare const outputs: Readonly<{
+  next<T>(data: T, code?: number): NextOutput<T>;
+  pass<T>(data: T, code?: number): PassOutput<T>;
+  fail<const T extends string>(data: FailOutput<T>['data'], code?: number): FailOutput<T>;
+  /**
+   * Used to escape the controller contract state machine, useful for redirects.
+   */
+  exit(): ExitOutput;
+}>;
+//#endregion
+//#region src/utils/root-only.d.ts
+/**
+ * Useful for quickly sending a root level error to the client.
+ */
+declare function rootOnly(message: string): FailOutput<'root'>['data'];
+//#endregion
+//#region src/utils/standard-outputs.d.ts
+/**
+ * Useful for quick http basic responses.
+ */
+declare const StandardOutputs: Readonly<{
+  OK: import("@controller-contract/core").PassOutput<{
+    key: "root";
+    message: string;
+  }[]>;
+  Created: import("@controller-contract/core").PassOutput<{
+    key: "root";
+    message: string;
+  }[]>;
+  Accepted: import("@controller-contract/core").PassOutput<{
+    key: "root";
+    message: string;
+  }[]>;
+  BadRequest: import("@controller-contract/core").FailOutput<"root">;
+  Unauthorized: import("@controller-contract/core").FailOutput<"root">;
+  Forbidden: import("@controller-contract/core").FailOutput<"root">;
+  NotFound: import("@controller-contract/core").FailOutput<"root">;
+  InternalServerError: import("@controller-contract/core").FailOutput<"root">;
+  BadGateway: import("@controller-contract/core").FailOutput<"root">;
+}>;
+//#endregion
+export { rootOnly as n, outputs as r, StandardOutputs as t };

package/dist/index.d.mts

@@ -1,137 +1,214 @@
-import { ControllerContract, ExitOutput, FailOutput, InputChannel, Method, NextOutput, NoInput, Output, ParamsFrom, PassOutput } from "@controller-contract/core";
+import { r as outputs } from "./index-DvVe6qYj.mjs";
+import { ControllerContract, ExitOutput, FailOutput, Method, NoInput, Output, PassOutput, PathParams } from "@controller-contract/core";
 import { StandardSchemaV1 } from "@standard-schema/spec";
-//#region src/classes/controller-contract-controller/controller-contract-controller.d.ts
-type ControllerContractController<TMethod extends Method, TPath extends string, TParamsInput, TQueryInput, TBodyInput, TOuput extends Output, TRouter> = (() => TRouter) & {
-  '~cc'?: TMethod | TPath | TParamsInput | TQueryInput | TBodyInput | TOuput;
+//#region src/types/controller.d.ts
+type Controller<TMethod extends Method, TPath extends string, TParamsInput, TQueryInput, TBodyInput, TOutput extends Output, TFrameworkRouter> = (() => TFrameworkRouter) & {
+  '~cc'?: TMethod | TPath | TParamsInput | TQueryInput | TBodyInput | TOutput;
 };
 //#endregion
-//#region src/interfaces/ControllerContractSpec.d.ts
-interface NullaryControllerContractSpec<TFrameworkContext, TInject> {
-  readonly type: 'nullary';
-  readonly injectable: TInject;
-  readonly method: Method;
-  readonly path: string;
-  readonly outputFn: OutputFn<TFrameworkContext, string, Output>;
+//#region src/types/combine-routes-fn.d.ts
+type CombineRoutesFn<TFrameworkRouter> = <TRoutes extends Record<any, Controller<any, any, any, any, any, any, TFrameworkRouter>>>(routes: TRoutes) => TFrameworkRouter;
+//#endregion
+//#region src/interfaces/controller-blueprint.d.ts
+/**
+ * The true shapes aren't needed at this level. We only need a broad description.
+ */
+interface ControllerBlueprintSchemas<TParams, TQuery, TBody> {
+  params: StandardSchemaV1<any, TParams> | null;
+  query: StandardSchemaV1<any, TQuery> | null;
+  body: StandardSchemaV1<any, TBody> | null;
 }
-interface SanitizedControllerContractSpec<TFrameworkContext, TInject> {
-  readonly type: 'sanitized';
-  readonly injectable: TInject;
+type OutputFnBlueprint<TFrameworkContext> = (context: Prettify<TFrameworkContext & {
+  inputs: {
+    params: any;
+    query: any;
+    body: any;
+  };
+  outputs: OutputFnOutputs;
+}>) => Promise<PassOutput<any> | FailOutput<any> | ExitOutput>;
+interface ControllerBlueprint<TFrameworkContext, TFrameworkInjectable> {
+  readonly injectable: TFrameworkInjectable;
   readonly method: Method;
   readonly path: string;
-  readonly channel: InputChannel;
-  readonly schema: StandardSchemaV1;
-  readonly outputFn: SanitizedOutputFn<TFrameworkContext, string, unknown, Output>;
+  readonly schemas: ControllerBlueprintSchemas<unknown, unknown, unknown>;
+  readonly outputFn: OutputFnBlueprint<TFrameworkContext>;
 }
-type ControllerContractSpec<TFrameworkContext, TInject> = NullaryControllerContractSpec<TFrameworkContext, TInject> | SanitizedControllerContractSpec<TFrameworkContext, TInject>;
 //#endregion
-//#region src/utils/outputs.d.ts
-declare namespace outputs {
-  function next<T>(data: T, code?: number): NextOutput<T>;
-  function pass<T>(data: T, code?: number): PassOutput<T>;
-  function fail<const T extends string>(data: FailOutput<T>['data'], code?: number): FailOutput<T>;
+//#region src/types/create-route-fn.d.ts
+type CreateRouteFn<TFrameworkContext, TFrameworkInjectable, TFrameworkRouter> = (blueprint: ControllerBlueprint<TFrameworkContext, TFrameworkInjectable>) => TFrameworkRouter;
+//#endregion
+//#region src/types/fail-output-from.d.ts
+/**
+ * The fail output a validated input can produce. Skipped inputs are `NoInput` and produce none.
+ */
+type FailOutputFrom<T> = [T] extends [NoInput] ? never : FailOutput<Extract<keyof T, string>>;
+//#endregion
+//#region src/types/infer-controller-contract.d.ts
+type InferControllerContract<T> = T extends Controller<infer M, infer P, any, infer Q, infer B, infer O, any> ? ControllerContract<M, P, PathParams<P>, Q, B, O> : never;
+//#endregion
+//#region src/classes/controller-router.d.ts
+declare class ControllerRouter<TFrameworkRouter, TRoutes extends Record<any, Controller<any, any, any, any, any, any, TFrameworkRouter>>> {
+  private readonly combineRoutes;
+  private readonly routes;
+  constructor(combineRoutes: CombineRoutesFn<TFrameworkRouter>, routes: TRoutes);
   /**
-   * Used to escape the controller contract state machine, useful for redirects.
+   * @example
+   * const usersRouter = controllerRouterFactory.createControllerRouter({ getUser, createUser });
+   *
+   * const app = express();
+   * app.use(express.json());
+   * app.use(usersRouter.toRouter());
+   * app.listen(3000);
    */
-  function exit(): ExitOutput;
+  toRouter(): TFrameworkRouter;
+}
+//#endregion
+//#region src/types/map-to-controller-contract.d.ts
+type MapToControllerContract<TRoutes> = { [TRouteName in Extract<keyof TRoutes, string> as Capitalize<TRouteName>]: InferControllerContract<TRoutes[TRouteName]>; };
+//#endregion
+//#region src/types/infer-controller-contracts-from-router.d.ts
+type InferControllerContractsFromRouter<T> = T extends ControllerRouter<any, infer TRoutes> ? MapToControllerContract<TRoutes> : never;
+//#endregion
+//#region src/interfaces/endable.d.ts
+interface Endable<TParams, TQuery, TBody> {
+  getSchemas(): ControllerBlueprintSchemas<TParams, TQuery, TBody>;
+}
+//#endregion
+//#region src/classes/controller-builder/input-builder/steps/after-body-step.d.ts
+declare class AfterBodyStep<TParams, TQuery, TBody> implements Endable<TParams, TQuery, TBody> {
+  private readonly paramsSchema;
+  private readonly querySchema;
+  private readonly bodySchema;
+  constructor(paramsSchema: StandardSchemaV1<any, TParams> | null, querySchema: StandardSchemaV1<any, TQuery> | null, bodySchema: StandardSchemaV1<any, TBody>);
+  getSchemas(): ControllerBlueprintSchemas<TParams, TQuery, TBody>;
+}
+//#endregion
+//#region src/classes/controller-builder/input-builder/steps/after-query-step.d.ts
+declare class AfterQueryStep<TParams, TQuery> implements Endable<TParams, TQuery, NoInput> {
+  private readonly paramsSchema;
+  private readonly querySchema;
+  constructor(paramsSchema: StandardSchemaV1<any, TParams> | null, querySchema: StandardSchemaV1<any, TQuery>);
+  body<TBody>(schema: StandardSchemaV1<any, TBody>): AfterBodyStep<TParams, TQuery, TBody>;
+  getSchemas(): ControllerBlueprintSchemas<TParams, TQuery, NoInput>;
+}
+//#endregion
+//#region src/classes/controller-builder/input-builder/steps/after-params-step.d.ts
+declare class AfterParamsStep<TParams> implements Endable<TParams, NoInput, NoInput> {
+  private readonly paramsSchema;
+  constructor(paramsSchema: StandardSchemaV1<any, TParams>);
+  query<TQuery>(schema: StandardSchemaV1<any, TQuery>): AfterQueryStep<TParams, TQuery>;
+  body<TBody>(schema: StandardSchemaV1<any, TBody>): AfterBodyStep<TParams, NoInput, TBody>;
+  getSchemas(): ControllerBlueprintSchemas<TParams, NoInput, NoInput>;
 }
-declare function rootOnly(message: string): FailOutput<'root'>['data'];
-declare const StandardOutputs: Readonly<{
-  OK: PassOutput<{
-    key: "root";
-    message: string;
-  }[]>;
-  Created: PassOutput<{
-    key: "root";
-    message: string;
-  }[]>;
-  Accepted: PassOutput<{
-    key: "root";
-    message: string;
-  }[]>;
-  BadRequest: FailOutput<"root">;
-  Unauthorized: FailOutput<"root">;
-  Forbidden: FailOutput<"root">;
-  NotFound: FailOutput<"root">;
-  InternalServerError: FailOutput<"root">;
-  BadGateway: FailOutput<"root">;
-}>;
-//#endregion
-//#region src/types/index.d.ts
-type BuilderIntegratorFn<TFrameworkContext, TFrameworkInject, TFrameworkRouter> = (spec: ControllerContractSpec<TFrameworkContext, TFrameworkInject>) => TFrameworkRouter;
-type RouterIntegratorFn<TRouter> = <TRoutes extends Record<any, ControllerContractController<any, any, any, any, any, any, TRouter>>>(routes: TRoutes) => TRouter;
+//#endregion
+//#region src/classes/controller-builder/input-builder/input-builder.d.ts
+declare class InputBuilder {
+  params<TParams>(schema: StandardSchemaV1<any, TParams>): AfterParamsStep<TParams>;
+  query<TQuery>(schema: StandardSchemaV1<any, TQuery>): AfterQueryStep<NoInput, TQuery>;
+  body<TBody>(schema: StandardSchemaV1<any, TBody>): AfterBodyStep<NoInput, NoInput, TBody>;
+}
+//#endregion
+//#region src/types/input-builder-fn.d.ts
+type InputBuilderFn<TParams, TQuery, TBody> = (inputBuilder: InputBuilder) => Endable<TParams, TQuery, TBody>;
+//#endregion
+//#region src/types/prettify.d.ts
 type Prettify<T> = { [K in keyof T]: T[K]; } & {};
-type OutputFn<TFrameworkContext, TPath extends string, TOutput> = (context: Prettify<TFrameworkContext & {
-  params: ParamsFrom<TPath>;
-  outputs: typeof outputs;
+//#endregion
+//#region src/types/output-fn-outputs.d.ts
+type OutputFnOutputs = Prettify<Omit<typeof outputs, 'next'>>;
+//#endregion
+//#region src/types/output-fn.d.ts
+type OutputFn<TFrameworkContext, TParams, TQuery, TBody, TOutput extends PassOutput<any> | FailOutput<any> | ExitOutput> = (context: Prettify<TFrameworkContext & {
+  inputs: {
+    params: TParams;
+    query: TQuery;
+    body: TBody;
+  };
+  outputs: OutputFnOutputs;
 }>) => Promise<TOutput>;
-type SanitizedOutputFn<TFrameworkContext, TPath extends string, TInput, TOutput> = OutputFn<TFrameworkContext & {
-  input: TInput;
-}, TPath, TOutput>;
-type InferControllerContract<T> = T extends ControllerContractController<infer M, infer P, any, infer Q, infer B, infer O, any> ? ControllerContract<M, P, ParamsFrom<P>, Q, B, O> : never;
-type MapToControllerContract<TRoutes> = { [TRouteName in Extract<keyof TRoutes, string> as Capitalize<TRouteName>]: InferControllerContract<TRoutes[TRouteName]>; };
 //#endregion
-//#region src/classes/controller-contract-controller-builder/builder-steps/post-input-step.d.ts
-declare class PostInputStep<TFrameworkContext, TFrameworkInject, TRouter, const TMethod extends Method, const TPath extends string, const TChannel extends InputChannel, TInput, TOutputFromInput extends Output> {
+//#region src/types/resolved-params.d.ts
+/**
+ * Falls back to the raw path params when no params schema was given.
+ */
+type ResolvedParams<TParams, TPath extends string> = [TParams] extends [NoInput] ? PathParams<TPath> : TParams;
+//#endregion
+//#region src/classes/controller-builder/steps/output-step.d.ts
+declare class OutputStep<TFrameworkContext, TFrameworkInjectable, TFrameworkRouter, const TMethod extends Method, const TPath extends string, TParams, TQuery, TBody> {
   private readonly injectable;
-  private readonly integrator;
+  private readonly createRoute;
   private readonly method;
   private readonly path;
-  private readonly channel;
-  private readonly schema;
-  constructor(injectable: TFrameworkInject, integrator: BuilderIntegratorFn<TFrameworkContext, TFrameworkInject, TRouter>, method: TMethod, path: TPath, channel: TChannel, schema: StandardSchemaV1<TInput>);
-  output<TOutput extends Output>(outputFn: SanitizedOutputFn<TFrameworkContext, TPath, TInput, TOutput>): ControllerContractController<TMethod, TPath, ParamsFrom<TPath>, TChannel extends 'query' ? TInput : NoInput, TChannel extends 'body' ? TInput : NoInput, TOutputFromInput | TOutput, TRouter>;
+  private readonly schemas;
+  constructor(injectable: TFrameworkInjectable, createRoute: CreateRouteFn<TFrameworkContext, TFrameworkInjectable, TFrameworkRouter>, method: TMethod, path: TPath, schemas: ControllerBlueprintSchemas<TParams, TQuery, TBody>);
+  output<TOutput extends PassOutput<any> | FailOutput<any> | ExitOutput>(outputFn: OutputFn<TFrameworkContext, Prettify<ResolvedParams<TParams, TPath>>, TQuery, TBody, TOutput>): Controller<TMethod, TPath, Prettify<PathParams<TPath>>, TQuery, TBody, FailOutputFrom<TParams> | FailOutputFrom<TQuery> | FailOutputFrom<TBody> | TOutput, TFrameworkRouter>;
 }
 //#endregion
-//#region src/classes/controller-contract-controller-builder/builder-steps/post-endpoint-step.d.ts
-declare class PostEndpointStep<TFrameworkContext, TFrameworkInject, TRouter, const TMethod extends Method, const TPath extends string> {
+//#region src/classes/controller-builder/steps/input-step.d.ts
+declare class InputStep<TFrameworkContext, TFrameworkInjectable, TFrameworkRouter, const TMethod extends Method, const TPath extends string> {
   private readonly injectable;
-  private readonly integrator;
+  private readonly createRoute;
   private readonly method;
   private readonly path;
-  constructor(injectable: TFrameworkInject, integrator: BuilderIntegratorFn<TFrameworkContext, TFrameworkInject, TRouter>, method: TMethod, path: TPath);
-  input<const TChannel extends InputChannel, TInput>(channel: TChannel, schema: StandardSchemaV1<TInput>): PostInputStep<TFrameworkContext, TFrameworkInject, TRouter, TMethod, TPath, TChannel, TInput, FailOutput<Extract<keyof TInput, string>>>;
-  output<TOutput extends Output>(outputFn: OutputFn<TFrameworkContext, TPath, TOutput>): ControllerContractController<TMethod, TPath, ParamsFrom<TPath>, NoInput, NoInput, TOutput, TRouter>;
+  constructor(injectable: TFrameworkInjectable, createRoute: CreateRouteFn<TFrameworkContext, TFrameworkInjectable, TFrameworkRouter>, method: TMethod, path: TPath);
+  input<TParams, TQuery, TBody>(inputBuilderFn: InputBuilderFn<TParams, TQuery, TBody>): OutputStep<TFrameworkContext, TFrameworkInjectable, TFrameworkRouter, TMethod, TPath, TParams, TQuery, TBody>;
+  output<TOutput extends PassOutput<any> | FailOutput<any> | ExitOutput>(outputFn: OutputFn<TFrameworkContext, Prettify<PathParams<TPath>>, NoInput, NoInput, TOutput>): Controller<TMethod, TPath, Prettify<PathParams<TPath>>, NoInput, NoInput, TOutput, TFrameworkRouter>;
 }
 //#endregion
-//#region src/classes/controller-contract-controller-builder/builder-steps/post-inject-step.d.ts
-declare class PostInjectStep<TFrameworkContext, TFrameworkInject, TRouter> {
+//#region src/classes/controller-builder/steps/endpoint-step.d.ts
+declare class EndpointStep<TFrameworkContext, TFrameworkInjectable, TFrameworkRouter> {
   private readonly injectable;
-  private readonly integrator;
-  constructor(injectable: TFrameworkInject, integrator: BuilderIntegratorFn<TFrameworkContext, TFrameworkInject, TRouter>);
-  endpoint<const TMethod extends Method, const TPath extends string>(method: TMethod, path: TPath): PostEndpointStep<TFrameworkContext, TFrameworkInject, TRouter, TMethod, TPath>;
+  private readonly createRoute;
+  constructor(injectable: TFrameworkInjectable, createRoute: CreateRouteFn<TFrameworkContext, TFrameworkInjectable, TFrameworkRouter>);
+  endpoint<const TMethod extends Method, const TPath extends string>(method: TMethod, path: TPath): InputStep<TFrameworkContext, TFrameworkInjectable, TFrameworkRouter, TMethod, TPath>;
 }
 //#endregion
-//#region src/classes/controller-contract-controller-builder/controller-contract-controller-builder.d.ts
-declare class ControllerContractControllerBuilder<TFrameworkContext, TFrameworkInject, TFrameworkRouter> {
-  private readonly injectableDefaultValue;
-  private readonly integrator;
-  constructor(injectableDefaultValue: TFrameworkInject, integrator: BuilderIntegratorFn<TFrameworkContext, TFrameworkInject, TFrameworkRouter>);
-  inject(injectable: TFrameworkInject): PostInjectStep<TFrameworkContext, TFrameworkInject, TFrameworkRouter>;
-  endpoint<const TMethod extends Method, const TPath extends string>(method: TMethod, path: TPath): PostEndpointStep<TFrameworkContext, TFrameworkInject, TFrameworkRouter, TMethod, TPath>;
+//#region src/classes/controller-builder/controller-builder.d.ts
+declare class ControllerBuilder<TFrameworkContext, TFrameworkInjectable, TFrameworkRouter> {
+  private readonly defaultInjectable;
+  private readonly createRoute;
+  constructor(defaultInjectable: TFrameworkInjectable, createRoute: CreateRouteFn<TFrameworkContext, TFrameworkInjectable, TFrameworkRouter>);
+  inject(injectable: TFrameworkInjectable): EndpointStep<TFrameworkContext, TFrameworkInjectable, TFrameworkRouter>;
+  endpoint<const TMethod extends Method, const TPath extends string>(method: TMethod, path: TPath): InputStep<TFrameworkContext, TFrameworkInjectable, TFrameworkRouter, TMethod, TPath>;
 }
 //#endregion
-//#region src/classes/controller-contract-controller-router/controller-contract-controller-router.d.ts
-declare class ControllerContractControllerRouter<TRouter, TRoutes extends Record<any, ControllerContractController<any, any, any, any, any, any, TRouter>>> {
-  private readonly integrator;
-  private readonly routes;
-  constructor(integrator: RouterIntegratorFn<TRouter>, routes: TRoutes);
-  getIntegratedRouter(): TRouter;
-}
-//#endregion
-//#region src/classes/controller-contract-controller-router/controller-contract-controller-router-factory.d.ts
-declare class ControllerContractControllerRouterFactory<TRouter> {
-  private readonly integrator;
-  constructor(integrator: RouterIntegratorFn<TRouter>);
-  createControllerContractControllerRouter<TRoutes extends Record<any, ControllerContractController<any, any, any, any, any, any, TRouter>>>(routes: TRoutes): ControllerContractControllerRouter<TRouter, TRoutes>;
+//#region src/classes/controller-router-factory.d.ts
+type ControllerRouterRecord<TFrameworkRouter> = Record<string, Controller<any, any, any, any, any, any, TFrameworkRouter>>;
+declare class ControllerRouterFactory<TFrameworkRouter> {
+  private readonly combineRoutes;
+  constructor(combineRoutes: CombineRoutesFn<TFrameworkRouter>);
+  /**
+   * @example
+   * const getUser = builder
+   *   .endpoint('get', '/api/users/:id')
+   *   .output(async ({ inputs, outputs }) => outputs.pass({ id: inputs.params.id }));
+   *
+   * const createUser = builder
+   *   .endpoint('post', '/api/users')
+   *   .input((s) => s.body(z.object({ name: z.string() })))
+   *   .output(async ({ inputs, outputs }) => outputs.pass({ name: inputs.body.name }, 201));
+   *
+   * const usersRouter = controllerRouterFactory.createControllerRouter({ getUser, createUser });
+   */
+  createControllerRouter<TRoutes extends ControllerRouterRecord<TFrameworkRouter>>(routes: TRoutes): ControllerRouter<TFrameworkRouter, TRoutes>;
 }
 //#endregion
-//#region src/classes/framework-integration-factory.d.ts
-declare class FrameworkIntegrationFactory<TFrameworkContext, TFrameworkInject, TFrameworkRouter> {
-  createControllerContractControllerBuilder(injectableDefaultValue: TFrameworkInject, integrator: BuilderIntegratorFn<TFrameworkContext, TFrameworkInject, TFrameworkRouter>): ControllerContractControllerBuilder<TFrameworkContext, TFrameworkInject, TFrameworkRouter>;
-  createControllerContractControllerRouterFactory(integrator: RouterIntegratorFn<TFrameworkRouter>): ControllerContractControllerRouterFactory<TFrameworkRouter>;
+//#region src/classes/framework-setup.d.ts
+/**
+ * @example
+ * const setup = new FrameworkSetup<Request, RequestHandler[], Router>();
+ */
+declare class FrameworkSetup<TFrameworkContext, TFrameworkInjectable, TFrameworkRouter> {
+  /**
+   * @example
+   * const builder = setup.createControllerBuilder([], (blueprint) => { ... });
+   */
+  createControllerBuilder(defaultInjectable: TFrameworkInjectable, createRoute: CreateRouteFn<TFrameworkContext, TFrameworkInjectable, TFrameworkRouter>): ControllerBuilder<TFrameworkContext, TFrameworkInjectable, TFrameworkRouter>;
+  /**
+   * @example
+   * const routerFactory = setup.createControllerRouterFactory((routes) => { ... });
+   */
+  createControllerRouterFactory(combineRoutes: CombineRoutesFn<TFrameworkRouter>): ControllerRouterFactory<TFrameworkRouter>;
 }
 //#endregion
-//#region src/types/infer-controller-contracts-from-router.d.ts
-type InferControllerContractsFromRouter<T> = T extends ControllerContractControllerRouter<any, infer TRoutes> ? MapToControllerContract<TRoutes> : never;
-//#endregion
-export { FrameworkIntegrationFactory, InferControllerContractsFromRouter, StandardOutputs, outputs, rootOnly };
+export { FrameworkSetup, InferControllerContractsFromRouter };