@tahminator/sapling 2.0.5-beta.23c37926 → 2.0.5-beta.279125eb

package/dist/index.d.mts

@@ -437,100 +437,14 @@ declare class ResponseStatusError extends Error {
 }
 //#endregion
 //#region src/helper/error/parse.d.ts
-type ParserErrorLocation = "reqbody" | "reqparams" | "reqquery";
+type ParserErrorLocation = "reqbody" | "reqparams" | "reqquery" | "resbody";
 /**
- * This error should be thrown when some data cannot be parsed by a given schema.
+ * This error should be thrown when some data cannot be parsed by a given Standard Schema compatible schema.
  */
 declare class ParserError extends ResponseStatusError {
-  constructor(location: ParserErrorLocation, issues: readonly StandardSchemaV1.Issue[], vendor: string);
+  constructor(location: ParserErrorLocation, issues: readonly StandardSchemaV1.Issue[], vendor: string, functionName: string);
   private static formatMessage;
-}
-//#endregion
-//#region src/helper/sapling.d.ts
-type Settings = {
-  serialize: (value: any) => string;
-  deserialize: (value: string) => any;
-  doc: {
-    openApiPath: string;
-    swaggerPath: string;
-  };
-};
-declare const _settings: Settings;
-/**
- * Collection of utility functions which are essential for Sapling to function.
- */
-declare class Sapling {
-  /**
-   * If you would prefer to manually resolve your controllers instead, call resolve
-   * on the controller class.
-   *
-   * @example```ts
-   * import { Sapling } from "@tahminator/sapling";
-   * import TestController from "./path/to/test.controller";
-   *
-   * const app = express();
-   *
-   * const router = Sapling.resolve(TestController);
-   * app.use(router);
-   * ```
-   */
-  static resolve<TClass>(this: void, clazz: Class<TClass>): Router | ErrorRequestHandler;
-  /**
-   * Register this function as a middleware in order to utilize Sapling's `deserialize` function.
-   *
-   * @example```ts
-   * import { Sapling } from "@tahminator/sapling";
-   * import express from "express";
-   *
-   * const app = express();
-   *
-   * app.use(Sapling.json());
-   * ```
-   */
-  static json(this: void): ExpressMiddlewareFn;
-  /**
-   * Register your application with all the necessary middlewares and logics for Sapling to function.
-   *
-   * @example```ts
-   * import { Sapling } from "@tahminator/sapling";
-   * import express from "express";
-   *
-   * const app = express();
-   *
-   * app.registerApp(app);
-   * ```
-   */
-  static registerApp(app: e.Express): void;
-  /**
-   * Serialize a value into a JSON string.
-   *
-   * This function is used in {@link ResponseEntity} to serialize the `body`.
-   *
-   * Use `setSerializeFn` to override underlying implementation.
-   *
-   * @defaultValue `JSON.stringify`
-   */
-  static serialize(this: void, value: any): string;
-  /**
-   * Replace the function used for `serialize`.
-   */
-  static setSerializeFn(this: void, fn: (value: any) => string): void;
-  /**
-   * De-serialize a JSON string back to a JavaScript object.
-   *
-   * This function is used to de-serialize a string into a `body`.
-   *
-   * Use `setDeserializeFn` to override underlying implementation.
-   *
-   * @defaultValue `JSON.parse`
-   */
-  static deserialize<T = any>(this: void, value: string): T;
-  /**
-   * Replace the function used for `deserialize`
-   */
-  static setDeserializeFn(this: void, fn: (value: string) => any): void;
-  static setOpenApiPath(this: void, path: string): void;
-  static setSwaggerPath(this: void, path: string): void;
+  static getPrettyLocationString(location: ParserErrorLocation): "request body" | "request params" | "request query" | "response body";
 }
 //#endregion
 //#region node_modules/.pnpm/openapi-types@12.1.3/node_modules/openapi-types/dist/index.d.ts
@@ -854,115 +768,208 @@ declare namespace OpenAPIV3 {
 }
 //#endregion
 //#region src/helper/openapi.d.ts
-type OpenAPIConfig = {
+type OpenAPIMetadata = {
   title: string;
   version: string;
   description?: string;
 };
 declare class OpenAPIGenerator {
   private controllers;
-  private config;
-  setConfig(config: OpenAPIConfig): void;
   registerController(controllerClass: Function, prefix: string): void;
+  private get metadata();
   generateSpec(): OpenAPIV3.Document;
   private toJsonSchema;
 }
 declare const openApiGenerator: OpenAPIGenerator;
-declare function _registerControllerClass(controllerClass: Function, prefix: string): void;
-declare function _setOpenApiConfig(config: OpenAPIConfig): void;
-declare function _generateOpenApiSpec(): OpenAPIV3.Document;
+declare function _registerController(controllerClass: Function, prefix: string): void;
+declare function generateOpenApiSpec(): OpenAPIV3.Document;
 //#endregion
-//#region src/annotation/request.d.ts
-type RequestSchemaDefinition = {
-  body?: StandardSchemaV1 & StandardJSONSchemaV1;
-  param?: StandardSchemaV1 & StandardJSONSchemaV1;
-  query?: StandardSchemaV1 & StandardJSONSchemaV1;
+//#region src/helper/sapling.d.ts
+type Settings = {
+  serialize: (value: any) => string;
+  deserialize: (value: string) => any;
+  doc: {
+    openApiPath: string;
+    swaggerPath: string;
+    metadata: OpenAPIMetadata;
+  };
 };
+declare const _settings: Settings;
 /**
- * Apply to a route method to have `request.body` be parsed by `schema`.
- *
- * This annotation will parse `request.body` & then override `request.body`.
- * You can then just simply cast `request.body` for your use
- *
- * @example
- * ```ts
- *  const CREATE_BOOK_REQUEST_BODY_SCHEMA = z.object({
- *    name: z.string(),
- *    description: z.string().optional(),
- *  });
- *
- * ⠀@Controller({ prefix: "/api/book" })
- *  class BookController {
- *   ⠀@RequestBody(CREATE_BOOK_REQUEST_BODY_SCHEMA)
- *   ⠀@POST()
- *    public createBook(request: e.Request) {
- *      const { name, description } = request.body as unknown as z.infer<
- *        typeof CREATE_BOOK_REQUEST_BODY_SCHEMA
- *      >;
- *    }
- *  }
- * ```
+ * Collection of utility functions which are essential for Sapling to function.
  */
+declare class Sapling {
+  /**
+   * If you would prefer to manually resolve your controllers instead, call resolve
+   * on the controller class.
+   *
+   * @example```ts
+   * import { Sapling } from "@tahminator/sapling";
+   * import TestController from "./path/to/test.controller";
+   *
+   * const app = express();
+   *
+   * const router = Sapling.resolve(TestController);
+   * app.use(router);
+   * ```
+   */
+  static resolve<TClass>(this: void, clazz: Class<TClass>): Router | ErrorRequestHandler;
+  /**
+   * Register this function as a middleware in order to utilize Sapling's `deserialize` function.
+   *
+   * @example```ts
+   * import { Sapling } from "@tahminator/sapling";
+   * import express from "express";
+   *
+   * const app = express();
+   *
+   * app.use(Sapling.json());
+   * ```
+   */
+  static json(this: void): ExpressMiddlewareFn;
+  /**
+   * Register your application with all the necessary middlewares and logics for Sapling to function.
+   *
+   * @example```ts
+   * import { Sapling } from "@tahminator/sapling";
+   * import express from "express";
+   *
+   * const app = express();
+   *
+   * app.registerApp(app);
+   * ```
+   */
+  static registerApp(app: e.Express): void;
+  /**
+   * Serialize a value into a JSON string.
+   *
+   * This function is used in {@link ResponseEntity} to serialize the `body`.
+   *
+   * Use `setSerializeFn` to override underlying implementation.
+   *
+   * @defaultValue `JSON.stringify`
+   */
+  static serialize(this: void, value: any): string;
+  /**
+   * Replace the function used for `serialize`.
+   */
+  static setSerializeFn(this: void, fn: (value: any) => string): void;
+  /**
+   * De-serialize a JSON string back to a JavaScript object.
+   *
+   * This function is used to de-serialize a string into a `body`.
+   *
+   * Use `setDeserializeFn` to override underlying implementation.
+   *
+   * @defaultValue `JSON.parse`
+   */
+  static deserialize<T = any>(this: void, value: string): T;
+  /**
+   * Replace the function used for `deserialize`
+   */
+  static setDeserializeFn(this: void, fn: (value: string) => any): void;
+  /**
+   * Modify extra settings
+   */
+  static Extras: {
+    /**
+     * Modify default settings applied to OpenAPI & Swagger
+     */
+    swaggerAndOpenApi: {
+      /**
+       * Set base OpenAPI metadata values.
+       *
+       * @default { title: "API", version: "1.0.0" }
+       */
+      setMetadata(metadata: OpenAPIMetadata): void;
+      /**
+       * change default endpoint that will serve OpenAPI spec.
+       * Swagger will also load this endpoint on load.
+       *
+       * @default `/openapi.json`
+       */
+      setOpenApiPath(this: void, path: string): void;
+      /**
+       * change Swagger endpoint.
+       *
+       * @default `/swagger.html`
+       */
+      setSwaggerPath(this: void, path: string): void;
+    };
+  };
+  /**
+   * This method can be used in a `@MiddlewareClass` to register any libraries
+   * that expect you to register multiple registers at once. An example is `swagger-ui-express`
+   *
+   * @example
+   * ```ts
+   * ⠀@MiddlewareClass()
+   *  class Serve {
+   *    // `swagger.serve` returns multiple Express handlers for all the assets and routes
+   *    // that will be served
+   *    private readonly handlers: RequestHandler[] = swagger.serve;
+   *
+   *   ⠀@Middleware(_settings.doc.swaggerPath)
+   *    handle(request: Request, response: Response, next: NextFunction) {
+   *      return Sapling.chainHandlers(this.handlers, request, response, next);
+   *    }
+   *  }
+   * ```
+   */
+  static chainHandlers(this: void, handlers: RequestHandler[], request: Request, response: Response$1, next: NextFunction, index?: number): void;
+}
+//#endregion
+//#region src/annotation/validator.d.ts
+type ValidatorSchema = {
+  requestBody?: StandardSchemaV1 & StandardJSONSchemaV1;
+  requestParam?: StandardSchemaV1 & StandardJSONSchemaV1;
+  requestQuery?: StandardSchemaV1 & StandardJSONSchemaV1;
+  responseBody?: StandardSchemaV1 & StandardJSONSchemaV1;
+};
+declare function ResponseBody(schema: StandardSchemaV1 & StandardJSONSchemaV1): MethodDecorator;
 declare function RequestBody(schema: StandardSchemaV1 & StandardJSONSchemaV1): MethodDecorator;
-/**
- * Apply to a route method to have `request.param` be parsed by `schema`.
- *
- * This annotation will parse `request.param` & then override `request.param`.
- * You can then just simply cast `request.param` for your use
- *
- * @example
- * ```ts
- *  const GET_BOOK_REQUEST_PARAM_SCHEMA = z.object({
- *    bookId: z.string(),
- *  });
- *
- * ⠀@Controller({ prefix: "/api/book" })
- *  class BookController {
- *   ⠀@RequestParam(GET_BOOK_REQUEST_PARAM_SCHEMA)
- *   ⠀@GET("/:bookId")
- *    public getBook(request: e.Request) {
- *      const { bookId } = request.param as unknown as z.infer<
- *        typeof GET_BOOK_REQUEST_PARAM_SCHEMA
- *      >;
- *    }
- *  }
- * ```
- */
 declare function RequestParam(schema: StandardSchemaV1 & StandardJSONSchemaV1): MethodDecorator;
-/**
- * Apply to a route method to have `request.query` be parsed by `schema`.
- *
- * This annotation will parse `request.query` & then override `request.query`.
- * You can then just simply cast `request.query` for your use
- *
- * @example
- * ```ts
- *  const LIST_BOOKS_REQUEST_QUERY_SCHEMA = z.object({
- *    sort: z.enum(["name", "createdAt"]).optional(),
- *    q: z.string().optional(),
- *  });
- *
- * ⠀@Controller({ prefix: "/api/book" })
- *  class BookController {
- *   ⠀@RequestQuery(LIST_BOOKS_REQUEST_QUERY_SCHEMA)
- *   ⠀@GET()
- *    public listBooks(request: e.Request) {
- *      const { sort, q } = request.query as unknown as z.infer<
- *        typeof LIST_BOOKS_REQUEST_QUERY_SCHEMA
- *      >;
- *    }
- *  }
- * ```
- */
 declare function RequestQuery(schema: StandardSchemaV1 & StandardJSONSchemaV1): MethodDecorator;
-declare function _getRequestSchemas(ctor: Function, fnName: string): RequestSchemaDefinition | undefined;
-declare function _parseOrThrow<TSchema extends StandardSchemaV1>(schema: TSchema, input: unknown, kind: ParserErrorLocation): Promise<StandardSchemaV1.InferOutput<TSchema>>;
+declare function _getOrCreateSchemaDefinition(ctor: Function, fnName: string): ValidatorSchema;
+declare function _parseOrThrow<TSchema extends StandardSchemaV1>(schema: TSchema, input: unknown, location: ParserErrorLocation, fnName: string): Promise<StandardSchemaV1.InferOutput<TSchema>>;
+declare function _saveValidatorSchema(def: ValidatorSchema, key: keyof ValidatorSchema, schema: StandardSchemaV1 & StandardJSONSchemaV1, fnName: string): void;
+declare function _getValidatorSchema(ctor: Function, fnName: string): ValidatorSchema | undefined;
+//#endregion
+//#region src/annotation/schema.d.ts
+type ResponseSchema = {
+  statusCode: HttpStatus;
+  description?: string;
+  schema?: StandardSchemaV1 & StandardJSONSchemaV1;
+};
+type RouteSchemaDefinition = {
+  summary?: string;
+  description?: string;
+  responses?: ResponseSchema[];
+};
+type ControllerSchemaDefinition = {
+  title?: string;
+  description?: string;
+};
+declare function ControllerSchema(options: {
+  title?: string;
+  description?: string;
+}): ClassDecorator;
+declare function RouteSchema(options: {
+  summary?: string;
+  description?: string;
+  responses?: ResponseSchema[];
+}): MethodDecorator;
+declare function _setRouteSchema(ctor: Function, fnName: string, options: RouteSchemaDefinition): void;
+declare function _setControllerSchema(ctor: Function, options: ControllerSchemaDefinition): void;
+declare function _getRouteSchema(ctor: Function, fnName: string): RouteSchemaDefinition | undefined;
+declare function _getControllerSchema(ctor: Function): ControllerSchemaDefinition | undefined;
 //#endregion
 //#region src/middleware/default/error/base.d.ts
 /**
  * This should be registered last in the middleware chain.
  *
  * All exception messages are hidden from the request by default.
+ * If the default is not suitable, you may also easily write your own.
  */
 declare class DefaultBaseErrorMiddleware {
   handle(err: unknown, _request: Request, _response: Response$1, _next: NextFunction): ResponseEntity<{
@@ -971,6 +978,10 @@ declare class DefaultBaseErrorMiddleware {
 }
 //#endregion
 //#region src/middleware/default/error/parse.d.ts
+/**
+ * Default error middleware that handles `ParserError`.
+ * If the default is not suitable, you may also easily write your own.
+ */
 declare class DefaultParserErrorMiddleware {
   handle(err: unknown, _request: Request, _response: Response$1, next: NextFunction): ResponseEntity<{
     message: string;
@@ -978,6 +989,10 @@ declare class DefaultParserErrorMiddleware {
 }
 //#endregion
 //#region src/middleware/default/error/responsestatus.d.ts
+/**
+ * Default error middleware that handles `ResponseStatusError`.
+ * If the default is not suitable, you may also easily write your own.
+ */
 declare class DefaultResponseStatusErrorMiddleware {
   handle(err: unknown, _request: Request, _response: Response$1, next: NextFunction): ResponseEntity<{
     message: string;
@@ -985,23 +1000,87 @@ declare class DefaultResponseStatusErrorMiddleware {
 }
 //#endregion
 //#region src/middleware/default/openapi/index.d.ts
+/**
+ * Enable the serving of the OpenAPI spec autogenerated by Sapling.
+ *
+ * Configure any middleware-specific settings with `Sapling.Extras.swaggerAndOpenApi`
+ *
+ * You must register `DefaultSwaggerMiddleware.Serve` & `DefaultSwaggerMiddleware.Setup` after `DefaultOpenApiMiddleware`
+ *
+ * ```ts
+ *  const middlewares = [
+ *    DefaultOpenApiMiddleware,
+ *    DefaultSwaggerMiddleware.Serve,
+ *    DefaultSwaggerMiddleware.Setup,
+ *  ];
+ *  middlewares.map(Sapling.resolve).forEach((r) => app.use(r));
+ * ```
+ */
 declare class DefaultOpenApiMiddleware {
   handle(_request: Request, _response: Response$1, _next: NextFunction): ResponseEntity<OpenAPIV3.Document<{}>>;
 }
 //#endregion
 //#region src/middleware/default/swagger/index.d.ts
+/**
+ * Enable the serving of the Swagger endpoint used to serve the OpenAPI spec generated by Sapling.
+ *
+ * Configure any middleware-specific settings with `Sapling.Extras.swaggerAndOpenApi`
+ *
+ * You must register `DefaultSwaggerMiddleware.Serve` & `DefaultSwaggerMiddleware.Setup` after `DefaultOpenApiMiddleware`
+ *
+ * ```ts
+ *  const middlewares = [
+ *    DefaultOpenApiMiddleware,
+ *    DefaultSwaggerMiddleware.Serve,
+ *    DefaultSwaggerMiddleware.Setup,
+ *  ];
+ *  middlewares.map(Sapling.resolve).forEach((r) => app.use(r));
+ * ```
+ */
 declare class Serve {
   private readonly handlers;
-  handle(_request: Request, _response: Response$1, _next: NextFunction): RequestHandler[];
+  handle(request: Request, response: Response$1, next: NextFunction): void;
 }
+/**
+ * Enable the serving of the Swagger endpoint used to serve the OpenAPI spec generated by Sapling.
+ *
+ * Configure any middleware-specific settings with `Sapling.Extras.swaggerAndOpenApi`
+ *
+ * You must register `DefaultSwaggerMiddleware.Serve` & `DefaultSwaggerMiddleware.Setup` after `DefaultOpenApiMiddleware`
+ *
+ * ```ts
+ *  const middlewares = [
+ *    DefaultOpenApiMiddleware,
+ *    DefaultSwaggerMiddleware.Serve,
+ *    DefaultSwaggerMiddleware.Setup,
+ *  ];
+ *  middlewares.map(Sapling.resolve).forEach((r) => app.use(r));
+ * ```
+ */
 declare class Setup {
   private readonly handler;
   constructor();
   handle(request: Request, response: Response$1, next: NextFunction): unknown;
 }
+/**
+ * Enable the serving of the Swagger endpoint used to serve the OpenAPI spec generated by Sapling.
+ *
+ * Configure any middleware-specific settings with `Sapling.Extras.swaggerAndOpenApi`
+ *
+ * You must register `DefaultSwaggerMiddleware.Serve` & `DefaultSwaggerMiddleware.Setup` after `DefaultOpenApiMiddleware`
+ *
+ * ```ts
+ *  const middlewares = [
+ *    DefaultOpenApiMiddleware,
+ *    DefaultSwaggerMiddleware.Serve,
+ *    DefaultSwaggerMiddleware.Setup,
+ *  ];
+ *  middlewares.map(Sapling.resolve).forEach((r) => app.use(r));
+ * ```
+ */
 declare const DefaultSwaggerMiddleware: {
   Serve: typeof Serve;
   Setup: typeof Setup;
 };
 //#endregion
-export { Class, Controller, DELETE, DefaultBaseErrorMiddleware, DefaultOpenApiMiddleware, DefaultParserErrorMiddleware, DefaultResponseStatusErrorMiddleware, DefaultSwaggerMiddleware, ExpressMiddlewareFn, ExpressRouterMethodKey, ExpressRouterMethods, GET, HEAD, Html404ErrorPage, HttpHeaders, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, ParserError, ParserErrorLocation, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteDefinition, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _generateOpenApiSpec, _getRequestSchemas, _getRoutes, _parseOrThrow, _registerControllerClass, _resolve, _setOpenApiConfig, _settings, methodResolve, openApiGenerator };
+export { Class, Controller, ControllerSchema, ControllerSchemaDefinition, DELETE, DefaultBaseErrorMiddleware, DefaultOpenApiMiddleware, DefaultParserErrorMiddleware, DefaultResponseStatusErrorMiddleware, DefaultSwaggerMiddleware, ExpressMiddlewareFn, ExpressRouterMethodKey, ExpressRouterMethods, GET, HEAD, Html404ErrorPage, HttpHeaders, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, OpenAPIMetadata, PATCH, POST, PUT, ParserError, ParserErrorLocation, RedirectView, RequestBody, RequestParam, RequestQuery, ResponseBody, ResponseEntity, ResponseEntityBuilder, ResponseSchema, ResponseStatusError, RouteDefinition, RouteSchema, RouteSchemaDefinition, Sapling, ValidatorSchema, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getControllerSchema, _getOrCreateSchemaDefinition, _getRouteSchema, _getRoutes, _getValidatorSchema, _parseOrThrow, _registerController, _resolve, _saveValidatorSchema, _setControllerSchema, _setRouteSchema, _settings, generateOpenApiSpec, methodResolve, openApiGenerator };