@tahminator/sapling 1.5.27 → 1.5.28

package/dist/index.d.cts

@@ -0,0 +1,421 @@
+import e, { NextFunction, Request, Response, Router } from "express";
+
+//#region src/html/404.d.ts
+/**
+ * Default Express.js 404 error page, as a string.
+ */
+declare const Html404ErrorPage: (error: string) => string;
+//#endregion
+//#region src/types.d.ts
+type ExpressRouterMethodKey = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS" | "HEAD" | "USE";
+type ExpressRouterMethods = Lowercase<ExpressRouterMethodKey>;
+declare const methodResolve: Record<ExpressRouterMethodKey, ExpressRouterMethods>;
+type RouteDefinition = {
+  /**
+   * Express.js HTTP method.
+   */
+  method: ExpressRouterMethodKey;
+  /**
+   * The path to define the route on. Can be a string or RegExp.
+   */
+  path: string | RegExp;
+  /**
+   * The name of the function the `@Route` annotation was applied on.
+   */
+  fnName: string;
+};
+type Class<T> = new (...args: any[]) => T;
+type HttpHeaders = Record<string, string>;
+type ExpressMiddlewareFn = ($1: Request, $2: Response, $3: NextFunction) => void;
+//#endregion
+//#region src/annotation/controller.d.ts
+declare const _ControllerRegistry: WeakMap<Function, Router>;
+type ControllerProps = {
+  /**
+   * Optional URL prefix applied to all routes in the controller. Defaults to "".
+   */
+  prefix?: string;
+  /**
+   * Optional array of dependencies to be injected into the constructor that are `@Injectable`
+   */
+  deps?: Array<Class<any>>;
+} | undefined;
+/**
+ * Registers a class as an HTTP controller and registers its routes.
+ *
+ * @param [prefix] Optional URL prefix applied to all routes in the controller. Defaults to "".
+ * @param [deps] Optional array of dependencies to be injected into the constructor that are `@Injectable`
+ */
+declare function Controller({
+  prefix,
+  deps
+}?: ControllerProps): ClassDecorator;
+//#endregion
+//#region lib/weakmap.d.ts
+/**
+ * WeakMap that is iterable.
+ */
+declare class IterableWeakMap<K extends object, V> {
+  #private;
+  constructor(iterable?: Iterable<[K, V]>);
+  set(key: K, value: V): this;
+  get(key: K): V | undefined;
+  delete(key: K): boolean;
+  [Symbol.iterator](): IterableIterator<[K, V]>;
+  entries(): IterableIterator<[K, V]>;
+  keys(): IterableIterator<K>;
+  values(): IterableIterator<V>;
+  forEach(callback: (value: V, key: K, map: this) => void, thisArg?: any): void;
+}
+//#endregion
+//#region src/annotation/injectable.d.ts
+declare const _InjectableRegistry: WeakMap<Class<any>, any>;
+declare const _InjectableDeps: IterableWeakMap<Class<any>, Class<any>[]>;
+/**
+ * Mark the class as an injectable to be handled by Sapling. The class can now be
+ * be injected into other classes, as well as allow the class to inject other `@Injectable` classes.
+ *
+ * @argument deps - An optional array to define any dependencies that this class may require.
+ */
+declare function Injectable(deps?: Array<Class<any>>): ClassDecorator;
+/**
+ * Resolves and instantiates a class along with all of it's transitive dependencies.
+ *
+ * Uses topological sort (Kahn's algorithm) to ensure that the dependency graph is created
+ * in a correct order.
+ *
+ * When `resolve` is first called (usually during controller registration),
+ * it will compute the dependency graph of all `@Injectable` classes and instantiates
+ * them in the correct order.
+ *
+ * Subsequent calls to dependencies that have already been resolved are cached, so they will
+ * re-use the created singletons instead of re-instantiation.
+ */
+declare function _resolve<T>(ctor: Class<T>): T;
+//#endregion
+//#region src/annotation/route.d.ts
+type OptionalStrOrRegExp = string | RegExp | undefined;
+/**
+ * Custom annotation that will store all routes inside of a map,
+ * which can then be used to initialize all the routes to the router.
+ */
+declare function _Route({
+  method,
+  path
+}: {
+  method: ExpressRouterMethodKey;
+  path: OptionalStrOrRegExp;
+}): MethodDecorator;
+/**
+ * Register GET route on the given path (default "") for the given controller.
+ */
+declare const GET: (path?: OptionalStrOrRegExp) => MethodDecorator;
+/**
+ * Register POST route on the given path (default "") for the given controller.
+ */
+declare const POST: (path?: OptionalStrOrRegExp) => MethodDecorator;
+/**
+ * Register PUT route on the given path (default "") for the given controller.
+ */
+declare const PUT: (path?: OptionalStrOrRegExp) => MethodDecorator;
+/**
+ * Register DELETE route on the given path (default "") for the given controller.
+ */
+declare const DELETE: (path?: OptionalStrOrRegExp) => MethodDecorator;
+/**
+ * Register OPTIONS route on the given path (default "") for the given controller.
+ */
+declare const OPTIONS: (path?: OptionalStrOrRegExp) => MethodDecorator;
+/**
+ * Register PATCH route on the given path (default "") for the given controller.
+ */
+declare const PATCH: (path?: OptionalStrOrRegExp) => MethodDecorator;
+/**
+ * Register HEAD route on the given path (default "") for the given controller.
+ */
+declare const HEAD: (path?: OptionalStrOrRegExp) => MethodDecorator;
+/**
+ * Register a middleware route on the given path (default "") for the given controller.
+ */
+declare const Middleware: (path?: OptionalStrOrRegExp) => MethodDecorator;
+/**
+ * Given a class constructor, fetch all the routes attached.
+ */
+declare function _getRoutes(ctor: Function): readonly RouteDefinition[];
+//#endregion
+//#region src/annotation/middleware.d.ts
+/**
+ * Used to define a middleware-only class.
+ *
+ * __NOTE:__ `@MiddlewareClass` works exactly the same as `@Controller`. As such, you
+ * can still register `@Route` and `@Middleware` methods, though you very well should not
+ * for the sake of semantics.
+ */
+declare function MiddlewareClass(...args: Parameters<typeof Controller>): ClassDecorator;
+//#endregion
+//#region src/helper/redirect.d.ts
+/**
+ * Generic HTTP redirect wrapped modeled after Spring's `RedirectView`.
+ *
+ * You can either return `new RedirectView(url)` or `RedirectView.redirect(url)` inside of a controller method.
+ */
+declare class RedirectView {
+  _url: string;
+  constructor(url: string);
+  getUrl(): string;
+  /**
+   * Instantiate `RedirectView` with the given `url`.
+   */
+  static redirect(url: string): RedirectView;
+}
+//#endregion
+//#region src/helper/response.d.ts
+/**
+ * Generic HTTP response wrapper modeled after Spring's `ResponseEntity`.
+ *
+ * Provides status code, headers, and an optional typed body.
+ * The body is serialized through `Sapling.serialize`.
+ *
+ * @typeParam T - the type of the response body
+ */
+declare class ResponseEntity<T> {
+  private readonly _statusCode;
+  private readonly _headers;
+  private readonly _body;
+  constructor(body: T, headers?: HttpHeaders, statusCode?: number);
+  /**
+   * Create a builder with a 200 status code.
+   *
+   * @example```ts
+   * return ResponseEntity.ok().body({ success: true });
+   * ```
+   */
+  static ok(): ResponseEntityBuilder;
+  /**
+   * Create a builder with a custom status code.
+   *
+   * @example```ts
+   * return ResponseEntity.status(HttpStatus.BAD_REQUEST).body({ success: false });
+   * ```
+   *
+   * @see {@link HttpStatus}
+   */
+  static status(statusCode: number): ResponseEntityBuilder;
+  /**
+   * Return status code.
+   */
+  getStatusCode(): number;
+  /**
+   * Return headers.
+   */
+  getHeaders(): HttpHeaders;
+  /**
+   * Return the response body.
+   */
+  getBody(): T;
+}
+/**
+ * Builder for {@link ResponseEntity}.
+ *
+ * Forces the status code to be set first, then headers and body,
+ * ensuring type safety when constructing the response.
+ */
+declare class ResponseEntityBuilder {
+  private readonly _statusCode;
+  private _headers;
+  constructor(statusCode: number);
+  /**
+   * Set all headers as an object with keys and values.
+   */
+  headers(headers: HttpHeaders): this;
+  /**
+   * Add/override a single key and value to the headers.
+   */
+  setHeader(key: string, value: string): this;
+  /**
+   * Set the response body.
+   */
+  body<T>(body: T): ResponseEntity<T>;
+}
+//#endregion
+//#region src/enum/http.d.ts
+/**
+ * Enum of every valid HTTP status code mapped to a specific enum member.
+ *
+ * @see {@link ResponseEntity}
+ */
+declare enum HttpStatus {
+  CONTINUE = 100,
+  SWITCHING_PROTOCOLS = 101,
+  PROCESSING = 102,
+  EARLY_HINTS = 103,
+  OK = 200,
+  CREATED = 201,
+  ACCEPTED = 202,
+  NON_AUTHORITATIVE_INFORMATION = 203,
+  NO_CONTENT = 204,
+  RESET_CONTENT = 205,
+  PARTIAL_CONTENT = 206,
+  MULTI_STATUS = 207,
+  ALREADY_REPORTED = 208,
+  IM_USED = 226,
+  MULTIPLE_CHOICES = 300,
+  MOVED_PERMANENTLY = 301,
+  FOUND = 302,
+  SEE_OTHER = 303,
+  NOT_MODIFIED = 304,
+  TEMPORARY_REDIRECT = 307,
+  PERMANENT_REDIRECT = 308,
+  BAD_REQUEST = 400,
+  UNAUTHORIZED = 401,
+  PAYMENT_REQUIRED = 402,
+  FORBIDDEN = 403,
+  NOT_FOUND = 404,
+  METHOD_NOT_ALLOWED = 405,
+  NOT_ACCEPTABLE = 406,
+  PROXY_AUTHENTICATION_REQUIRED = 407,
+  REQUEST_TIMEOUT = 408,
+  CONFLICT = 409,
+  GONE = 410,
+  LENGTH_REQUIRED = 411,
+  PRECONDITION_FAILED = 412,
+  PAYLOAD_TOO_LARGE = 413,
+  URI_TOO_LONG = 414,
+  UNSUPPORTED_MEDIA_TYPE = 415,
+  REQUESTED_RANGE_NOT_SATISFIABLE = 416,
+  EXPECTATION_FAILED = 417,
+  I_AM_A_TEAPOT = 418,
+  UNPROCESSABLE_ENTITY = 422,
+  LOCKED = 423,
+  FAILED_DEPENDENCY = 424,
+  TOO_EARLY = 425,
+  UPGRADE_REQUIRED = 426,
+  PRECONDITION_REQUIRED = 428,
+  TOO_MANY_REQUESTS = 429,
+  REQUEST_HEADER_FIELDS_TOO_LARGE = 431,
+  UNAVAILABLE_FOR_LEGAL_REASONS = 451,
+  INTERNAL_SERVER_ERROR = 500,
+  NOT_IMPLEMENTED = 501,
+  BAD_GATEWAY = 502,
+  SERVICE_UNAVAILABLE = 503,
+  GATEWAY_TIMEOUT = 504,
+  HTTP_VERSION_NOT_SUPPORTED = 505,
+  VARIANT_ALSO_NEGOTIATES = 506,
+  INSUFFICIENT_STORAGE = 507,
+  LOOP_DETECTED = 508,
+  BANDWIDTH_LIMIT_EXCEEDED = 509,
+  NOT_EXTENDED = 510,
+  NETWORK_AUTHENTICATION_REQUIRED = 511
+}
+//#endregion
+//#region src/helper/error.d.ts
+/**
+ * Ensure that you define a middleware that can handle this error.
+ *
+ * @see {@link Sapling.loadResponseStatusErrorMiddleware}
+ */
+declare class ResponseStatusError extends Error {
+  readonly status: HttpStatus;
+  constructor(status: HttpStatus, message?: string);
+}
+//#endregion
+//#region src/helper/sapling.d.ts
+/**
+ * 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;
+  /**
+   * 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;
+  /**
+   * Register a middleware that will handle {@link ResponseStatusError}.
+   *
+   * This middleware will chain to the next middleware if it does not catch {@link ResponseStatusError}.
+   * You may still define middleware to handle all other errors in a separate `app.use` call.
+   *
+   * @example
+   * ```ts
+   * import express from "express";
+   * import { Sapling } from "@tahminator/sapling";
+   *
+   * const app = express();
+   *
+   * Sapling.loadResponseStatusErrorMiddleware(app, (err, req, res, next) => {
+   *   // `err` is guaranteed to be of type ResponseStatusError
+   *   res.status(err.status).json({
+   *     success: false,
+   *     message: err.message,
+   *   });
+   * });
+   * ```
+   */
+  static loadResponseStatusErrorMiddleware(this: void, app: e.Express, fn: (err: ResponseStatusError, request: e.Request, response: e.Response, next: e.NextFunction) => void): 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;
+}
+//#endregion
+export { Class, Controller, DELETE, ExpressMiddlewareFn, ExpressRouterMethodKey, ExpressRouterMethods, GET, HEAD, Html404ErrorPage, HttpHeaders, HttpStatus, Injectable, Middleware, MiddlewareClass, OPTIONS, PATCH, POST, PUT, RedirectView, ResponseEntity, ResponseEntityBuilder, ResponseStatusError, RouteDefinition, Sapling, _ControllerRegistry, _InjectableDeps, _InjectableRegistry, _Route, _getRoutes, _resolve, methodResolve };