@tahminator/sapling 2.0.5-beta.0b3bd061 → 2.0.5-beta.1843d6fa

package/dist/index.d.mts

@@ -439,99 +439,12 @@ declare class ResponseStatusError extends Error {
 //#region src/helper/error/parse.d.ts
 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 chainHandlers(this: void, handlers: RequestHandler[], request: Request, response: Response$1, next: NextFunction, index?: number): 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
@@ -855,23 +768,162 @@ declare namespace OpenAPIV3 {
 }
 //#endregion
 //#region src/helper/openapi.d.ts
-type OpenAPIConfig = {
+type OpenAPIMetadata = {
   title: string;
   version: string;
   description?: string;
 };
 declare class OpenAPIGenerator {
+  private OPENAPI_VERSION;
   private controllers;
-  private config;
-  setConfig(config: OpenAPIConfig): void;
   registerController(controllerClass: Function, prefix: string): void;
+  /**
+   * visible for testing
+   */
+  _clearControllers(): 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 _registerController(controllerClass: Function, prefix: string): void;
 declare function generateOpenApiSpec(): OpenAPIV3.Document;
+declare function _clearOpenApiRegistry(): void;
+//#endregion
+//#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;
+/**
+ * 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 = {
@@ -885,9 +937,9 @@ declare function RequestBody(schema: StandardSchemaV1 & StandardJSONSchemaV1): M
 declare function RequestParam(schema: StandardSchemaV1 & StandardJSONSchemaV1): MethodDecorator;
 declare function RequestQuery(schema: StandardSchemaV1 & StandardJSONSchemaV1): MethodDecorator;
 declare function _getOrCreateSchemaDefinition(ctor: Function, fnName: string): ValidatorSchema;
-declare function _parseOrThrow<TSchema extends StandardSchemaV1>(schema: TSchema, input: unknown, kind: ParserErrorLocation): Promise<StandardSchemaV1.InferOutput<TSchema>>;
+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;
-declare function _setOnce(def: ValidatorSchema, key: keyof ValidatorSchema, schema: StandardSchemaV1 & StandardJSONSchemaV1, fnName: string): void;
 //#endregion
 //#region src/annotation/schema.d.ts
 type ResponseSchema = {
@@ -923,6 +975,7 @@ declare function _getControllerSchema(ctor: Function): ControllerSchemaDefinitio
  * 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<{
@@ -931,6 +984,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;
@@ -938,6 +995,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;
@@ -945,23 +1006,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): 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, ControllerSchema, ControllerSchemaDefinition, 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, ResponseBody, ResponseEntity, ResponseEntityBuilder, ResponseSchema, ResponseStatusError, RouteDefinition, RouteSchema, RouteSchemaDefinition, Sapling, ValidatorSchema, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getControllerSchema, _getOrCreateSchemaDefinition, _getRouteSchema, _getRoutes, _getValidatorSchema, _parseOrThrow, _registerControllerClass, _resolve, _setControllerSchema, _setOnce, _setRouteSchema, _settings, generateOpenApiSpec, methodResolve, openApiGenerator, setOpenApiConfig };
+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, _clearOpenApiRegistry, _getControllerSchema, _getOrCreateSchemaDefinition, _getRouteSchema, _getRoutes, _getValidatorSchema, _parseOrThrow, _registerController, _resolve, _saveValidatorSchema, _setControllerSchema, _setRouteSchema, _settings, generateOpenApiSpec, methodResolve, openApiGenerator };