@tahminator/sapling 2.0.3 → 2.0.5-beta.23c37926

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import e, { ErrorRequestHandler, NextFunction, Request, Response, Router } from "express";
+import e, { ErrorRequestHandler, NextFunction, Request, RequestHandler, Response as Response$1, Router } from "express";
 
 //#region src/html/404.d.ts
 /**
@@ -26,7 +26,7 @@ type RouteDefinition = {
 };
 type Class<T> = new (...args: any[]) => T;
 type HttpHeaders = Record<string, string>;
-type ExpressMiddlewareFn = ($1: Request, $2: Response, $3: NextFunction) => void;
+type ExpressMiddlewareFn = ($1: Request, $2: Response$1, $3: NextFunction) => void;
 //#endregion
 //#region src/annotation/controller.d.ts
 declare const _ControllerRegistry: WeakMap<Function, Router | ErrorRequestHandler>;
@@ -230,6 +230,45 @@ declare namespace StandardSchemaV1 {
   type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
 }
 /** The Standard JSON Schema interface. */
+interface StandardJSONSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard JSON Schema properties. */
+  readonly "~standard": StandardJSONSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardJSONSchemaV1 {
+  /** The Standard JSON Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+    /** Methods for generating the input/output JSON Schema. */
+    readonly jsonSchema: StandardJSONSchemaV1.Converter;
+  }
+  /** The Standard JSON Schema converter interface. */
+  interface Converter {
+    /** Converts the input type to JSON Schema. May throw if conversion is not supported. */
+    readonly input: (options: StandardJSONSchemaV1.Options) => Record<string, unknown>;
+    /** Converts the output type to JSON Schema. May throw if conversion is not supported. */
+    readonly output: (options: StandardJSONSchemaV1.Options) => Record<string, unknown>;
+  }
+  /**
+   * The target version of the generated JSON Schema.
+   *
+   * It is *strongly recommended* that implementers support `"draft-2020-12"` and `"draft-07"`, as they are both in wide use. All other targets can be implemented on a best-effort basis. Libraries should throw if they don't support a specified target.
+   *
+   * The `"openapi-3.0"` target is intended as a standardized specifier for OpenAPI 3.0 which is a superset of JSON Schema `"draft-04"`.
+   */
+  type Target = "draft-2020-12" | "draft-07" | "openapi-3.0" | ({} & string);
+  /** The options for the input/output methods. */
+  interface Options {
+    /** Specifies the target version of the generated JSON Schema. Support for all versions is on a best-effort basis. If a given version is not supported, the library should throw. */
+    readonly target: Target;
+    /** Explicit support for additional vendor-specific parameters, if needed. */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+  /** The Standard types interface. */
+  interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {}
+  /** Infers the input type of a Standard. */
+  type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+  /** Infers the output type of a Standard. */
+  type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}
 //#endregion
 //#region src/helper/redirect.d.ts
 /**
@@ -408,6 +447,15 @@ declare class ParserError extends ResponseStatusError {
 }
 //#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.
  */
@@ -481,37 +529,479 @@ declare class Sapling {
    * 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;
+}
+//#endregion
+//#region node_modules/.pnpm/openapi-types@12.1.3/node_modules/openapi-types/dist/index.d.ts
+declare namespace OpenAPIV3 {
+  interface Document<T extends {} = {}> {
+    openapi: string;
+    info: InfoObject;
+    servers?: ServerObject[];
+    paths: PathsObject<T>;
+    components?: ComponentsObject;
+    security?: SecurityRequirementObject[];
+    tags?: TagObject[];
+    externalDocs?: ExternalDocumentationObject;
+    'x-express-openapi-additional-middleware'?: (((request: any, response: any, next: any) => Promise<void>) | ((request: any, response: any, next: any) => void))[];
+    'x-express-openapi-validation-strict'?: boolean;
+  }
+  interface InfoObject {
+    title: string;
+    description?: string;
+    termsOfService?: string;
+    contact?: ContactObject;
+    license?: LicenseObject;
+    version: string;
+  }
+  interface ContactObject {
+    name?: string;
+    url?: string;
+    email?: string;
+  }
+  interface LicenseObject {
+    name: string;
+    url?: string;
+  }
+  interface ServerObject {
+    url: string;
+    description?: string;
+    variables?: {
+      [variable: string]: ServerVariableObject;
+    };
+  }
+  interface ServerVariableObject {
+    enum?: string[];
+    default: string;
+    description?: string;
+  }
+  interface PathsObject<T extends {} = {}, P extends {} = {}> {
+    [pattern: string]: (PathItemObject<T> & P) | undefined;
+  }
+  enum HttpMethods {
+    GET = "get",
+    PUT = "put",
+    POST = "post",
+    DELETE = "delete",
+    OPTIONS = "options",
+    HEAD = "head",
+    PATCH = "patch",
+    TRACE = "trace"
+  }
+  type PathItemObject<T extends {} = {}> = {
+    $ref?: string;
+    summary?: string;
+    description?: string;
+    servers?: ServerObject[];
+    parameters?: (ReferenceObject | ParameterObject)[];
+  } & { [method in HttpMethods]?: OperationObject<T> };
+  type OperationObject<T extends {} = {}> = {
+    tags?: string[];
+    summary?: string;
+    description?: string;
+    externalDocs?: ExternalDocumentationObject;
+    operationId?: string;
+    parameters?: (ReferenceObject | ParameterObject)[];
+    requestBody?: ReferenceObject | RequestBodyObject;
+    responses: ResponsesObject;
+    callbacks?: {
+      [callback: string]: ReferenceObject | CallbackObject;
+    };
+    deprecated?: boolean;
+    security?: SecurityRequirementObject[];
+    servers?: ServerObject[];
+  } & T;
+  interface ExternalDocumentationObject {
+    description?: string;
+    url: string;
+  }
+  interface ParameterObject extends ParameterBaseObject {
+    name: string;
+    in: string;
+  }
+  interface HeaderObject extends ParameterBaseObject {}
+  interface ParameterBaseObject {
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    allowEmptyValue?: boolean;
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+    schema?: ReferenceObject | SchemaObject;
+    example?: any;
+    examples?: {
+      [media: string]: ReferenceObject | ExampleObject;
+    };
+    content?: {
+      [media: string]: MediaTypeObject;
+    };
+  }
+  type NonArraySchemaObjectType = 'boolean' | 'object' | 'number' | 'string' | 'integer';
+  type ArraySchemaObjectType = 'array';
+  type SchemaObject = ArraySchemaObject | NonArraySchemaObject;
+  interface ArraySchemaObject extends BaseSchemaObject {
+    type: ArraySchemaObjectType;
+    items: ReferenceObject | SchemaObject;
+  }
+  interface NonArraySchemaObject extends BaseSchemaObject {
+    type?: NonArraySchemaObjectType;
+  }
+  interface BaseSchemaObject {
+    title?: string;
+    description?: string;
+    format?: string;
+    default?: any;
+    multipleOf?: number;
+    maximum?: number;
+    exclusiveMaximum?: boolean;
+    minimum?: number;
+    exclusiveMinimum?: boolean;
+    maxLength?: number;
+    minLength?: number;
+    pattern?: string;
+    additionalProperties?: boolean | ReferenceObject | SchemaObject;
+    maxItems?: number;
+    minItems?: number;
+    uniqueItems?: boolean;
+    maxProperties?: number;
+    minProperties?: number;
+    required?: string[];
+    enum?: any[];
+    properties?: {
+      [name: string]: ReferenceObject | SchemaObject;
+    };
+    allOf?: (ReferenceObject | SchemaObject)[];
+    oneOf?: (ReferenceObject | SchemaObject)[];
+    anyOf?: (ReferenceObject | SchemaObject)[];
+    not?: ReferenceObject | SchemaObject;
+    nullable?: boolean;
+    discriminator?: DiscriminatorObject;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    xml?: XMLObject;
+    externalDocs?: ExternalDocumentationObject;
+    example?: any;
+    deprecated?: boolean;
+  }
+  interface DiscriminatorObject {
+    propertyName: string;
+    mapping?: {
+      [value: string]: string;
+    };
+  }
+  interface XMLObject {
+    name?: string;
+    namespace?: string;
+    prefix?: string;
+    attribute?: boolean;
+    wrapped?: boolean;
+  }
+  interface ReferenceObject {
+    $ref: string;
+  }
+  interface ExampleObject {
+    summary?: string;
+    description?: string;
+    value?: any;
+    externalValue?: string;
+  }
+  interface MediaTypeObject {
+    schema?: ReferenceObject | SchemaObject;
+    example?: any;
+    examples?: {
+      [media: string]: ReferenceObject | ExampleObject;
+    };
+    encoding?: {
+      [media: string]: EncodingObject;
+    };
+  }
+  interface EncodingObject {
+    contentType?: string;
+    headers?: {
+      [header: string]: ReferenceObject | HeaderObject;
+    };
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+  }
+  interface RequestBodyObject {
+    description?: string;
+    content: {
+      [media: string]: MediaTypeObject;
+    };
+    required?: boolean;
+  }
+  interface ResponsesObject {
+    [code: string]: ReferenceObject | ResponseObject;
+  }
+  interface ResponseObject {
+    description: string;
+    headers?: {
+      [header: string]: ReferenceObject | HeaderObject;
+    };
+    content?: {
+      [media: string]: MediaTypeObject;
+    };
+    links?: {
+      [link: string]: ReferenceObject | LinkObject;
+    };
+  }
+  interface LinkObject {
+    operationRef?: string;
+    operationId?: string;
+    parameters?: {
+      [parameter: string]: any;
+    };
+    requestBody?: any;
+    description?: string;
+    server?: ServerObject;
+  }
+  interface CallbackObject {
+    [url: string]: PathItemObject;
+  }
+  interface SecurityRequirementObject {
+    [name: string]: string[];
+  }
+  interface ComponentsObject {
+    schemas?: {
+      [key: string]: ReferenceObject | SchemaObject;
+    };
+    responses?: {
+      [key: string]: ReferenceObject | ResponseObject;
+    };
+    parameters?: {
+      [key: string]: ReferenceObject | ParameterObject;
+    };
+    examples?: {
+      [key: string]: ReferenceObject | ExampleObject;
+    };
+    requestBodies?: {
+      [key: string]: ReferenceObject | RequestBodyObject;
+    };
+    headers?: {
+      [key: string]: ReferenceObject | HeaderObject;
+    };
+    securitySchemes?: {
+      [key: string]: ReferenceObject | SecuritySchemeObject;
+    };
+    links?: {
+      [key: string]: ReferenceObject | LinkObject;
+    };
+    callbacks?: {
+      [key: string]: ReferenceObject | CallbackObject;
+    };
+  }
+  type SecuritySchemeObject = HttpSecurityScheme | ApiKeySecurityScheme | OAuth2SecurityScheme | OpenIdSecurityScheme;
+  interface HttpSecurityScheme {
+    type: 'http';
+    description?: string;
+    scheme: string;
+    bearerFormat?: string;
+  }
+  interface ApiKeySecurityScheme {
+    type: 'apiKey';
+    description?: string;
+    name: string;
+    in: string;
+  }
+  interface OAuth2SecurityScheme {
+    type: 'oauth2';
+    description?: string;
+    flows: {
+      implicit?: {
+        authorizationUrl: string;
+        refreshUrl?: string;
+        scopes: {
+          [scope: string]: string;
+        };
+      };
+      password?: {
+        tokenUrl: string;
+        refreshUrl?: string;
+        scopes: {
+          [scope: string]: string;
+        };
+      };
+      clientCredentials?: {
+        tokenUrl: string;
+        refreshUrl?: string;
+        scopes: {
+          [scope: string]: string;
+        };
+      };
+      authorizationCode?: {
+        authorizationUrl: string;
+        tokenUrl: string;
+        refreshUrl?: string;
+        scopes: {
+          [scope: string]: string;
+        };
+      };
+    };
+  }
+  interface OpenIdSecurityScheme {
+    type: 'openIdConnect';
+    description?: string;
+    openIdConnectUrl: string;
+  }
+  interface TagObject {
+    name: string;
+    description?: string;
+    externalDocs?: ExternalDocumentationObject;
+  }
+}
+//#endregion
+//#region src/helper/openapi.d.ts
+type OpenAPIConfig = {
+  title: string;
+  version: string;
+  description?: string;
+};
+declare class OpenAPIGenerator {
+  private controllers;
+  private config;
+  setConfig(config: OpenAPIConfig): void;
+  registerController(controllerClass: Function, prefix: string): void;
+  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;
 //#endregion
 //#region src/annotation/request.d.ts
 type RequestSchemaDefinition = {
-  body?: StandardSchemaV1;
-  param?: StandardSchemaV1;
-  query?: StandardSchemaV1;
+  body?: StandardSchemaV1 & StandardJSONSchemaV1;
+  param?: StandardSchemaV1 & StandardJSONSchemaV1;
+  query?: StandardSchemaV1 & StandardJSONSchemaV1;
 };
-declare function RequestBody(schema: StandardSchemaV1): MethodDecorator;
-declare function RequestParam(schema: StandardSchemaV1): MethodDecorator;
-declare function RequestQuery(schema: StandardSchemaV1): MethodDecorator;
+/**
+ * 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
+ *      >;
+ *    }
+ *  }
+ * ```
+ */
+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>>;
 //#endregion
-//#region src/middleware/default/base.d.ts
+//#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.
  */
 declare class DefaultBaseErrorMiddleware {
-  handle(err: unknown, _request: Request, _response: Response, _next: NextFunction): ResponseEntity<{
+  handle(err: unknown, _request: Request, _response: Response$1, _next: NextFunction): ResponseEntity<{
     message: string;
   }>;
 }
 //#endregion
-//#region src/middleware/default/responsestatus.d.ts
+//#region src/middleware/default/error/parse.d.ts
+declare class DefaultParserErrorMiddleware {
+  handle(err: unknown, _request: Request, _response: Response$1, next: NextFunction): ResponseEntity<{
+    message: string;
+  }> | undefined;
+}
+//#endregion
+//#region src/middleware/default/error/responsestatus.d.ts
 declare class DefaultResponseStatusErrorMiddleware {
-  handle(err: unknown, _request: Request, _response: Response, next: NextFunction): ResponseEntity<{
+  handle(err: unknown, _request: Request, _response: Response$1, next: NextFunction): ResponseEntity<{
     message: string;
   }> | undefined;
 }
 //#endregion
-export { Class, Controller, DELETE, DefaultBaseErrorMiddleware, DefaultResponseStatusErrorMiddleware, 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, _getRequestSchemas, _getRoutes, _parseOrThrow, _resolve, methodResolve };
+//#region src/middleware/default/openapi/index.d.ts
+declare class DefaultOpenApiMiddleware {
+  handle(_request: Request, _response: Response$1, _next: NextFunction): ResponseEntity<OpenAPIV3.Document<{}>>;
+}
+//#endregion
+//#region src/middleware/default/swagger/index.d.ts
+declare class Serve {
+  private readonly handlers;
+  handle(_request: Request, _response: Response$1, _next: NextFunction): RequestHandler[];
+}
+declare class Setup {
+  private readonly handler;
+  constructor();
+  handle(request: Request, response: Response$1, next: NextFunction): unknown;
+}
+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 };