tspace-spear
Version:
tspace-spear is a lightweight API framework for Node.js that is fast and highly focused on providing the best developer experience. It utilizes the native HTTP server
313 lines (312 loc) • 11 kB
TypeScript
/// <reference types="node" />
import { Server } from 'http';
import findMyWayRouter, { Instance } from 'find-my-way';
import { Router } from './router';
import type { TContext, TNextFunction, TApplication } from '../types';
/**
*
* The 'Spear' class is used to create a server and handle HTTP requests.
*
* @returns {Spear} application
* @example
* new Spear()
* .get('/' , () => 'Hello world!')
* .get('/json' , () => {
* return {
* message : 'Hello world!'
* }
* })
* .listen(3000 , () => console.log('server listening on port : 3000'))
*
*/
declare class Spear {
private readonly _controllers?;
private readonly _middlewares?;
private readonly _globalPrefix;
private readonly _router;
private readonly _parser;
private _cluster?;
private _cors?;
private _swagger;
private _swaggerAdditional;
private _errorHandler;
private _globalMiddlewares;
private _formatResponse;
private _onListeners;
private _fileUploadOptions;
constructor({ controllers, middlewares, globalPrefix, logger, cluster }?: TApplication);
/**
* The get 'instance' method is used to get the instance of Spear.
*
* @returns {this}
*/
get instance(): this;
/**
* The get 'routers' method is used get the all routers.
*
* @returns {Instance<findMyWayRouter.HTTPVersion.V1>}
*/
get routers(): Instance<findMyWayRouter.HTTPVersion.V1>;
/**
* The 'use' method is used to add the middleware into the request pipeline.
*
* @callback {Function} middleware
* @property {Object} ctx - context { req , res , query , params , cookies , files , body}
* @property {Function} next - go to next function
* @returns {this}
*/
use(middleware: (ctx: TContext, next: TNextFunction) => void): this;
/**
* The 'useCluster' method is used cluster run the server
*
* @param {boolean | number} cluster
* @returns {this}
*/
useCluster(cluster?: number): this;
/**
* The 'useLogger' method is used to add the middleware view logger response.
*
* @callback {Function} middleware
* @property {Object} ctx - context { req , res , query , params , cookies , files , body}
* @property {Function} next - go to next function
* @returns {this}
*/
useLogger({ methods, exceptPath }?: {
methods?: ('GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE')[];
exceptPath?: string[] | RegExp;
}): this;
/**
* The 'useBodyParser' method is a middleware used to parse the request body of incoming HTTP requests.
* @param {object?}
* @property {array?} except the body parser with some methods
* @returns {this}
*/
useBodyParser({ except }?: {
except?: ('GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE')[];
}): this;
/**
* The 'useFileUpload' method is a middleware used to handler file uploads. It adds a file upload of incoming HTTP requests.
*
* @param {?Object}
* @property {?number} limits
* @property {?string} tempFileDir
* @property {?Object} removeTempFile
* @property {boolean} removeTempFile.remove
* @property {number} removeTempFile.ms
* @returns
*/
useFileUpload({ limit, tempFileDir, removeTempFile }?: {
limit?: number;
tempFileDir?: string;
removeTempFile?: {
remove: boolean;
ms: number;
};
}): this;
/**
* The 'useCookiesParser' method is a middleware used to parses cookies attached to the client request object.
*
* @returns {this}
*/
useCookiesParser(): this;
/**
* The 'useRouter' method is used to add the router in the request context.
*
* @parms {Function} router
* @property {Function} router - get() , post() , put() , patch() , delete()
* @returns {this}
*/
useRouter(router: Router): this;
/**
* The 'useSwagger' method is a middleware used to create swagger api.
*
* @param {?Object}
* @property {?string} path
* @property {?array} servers
* @property {?object} info
* @property {?array} tags
* @returns
*/
useSwagger({ path, servers, info, tags }?: {
path?: `/${string}`;
servers?: {
url: string;
description?: string;
}[];
tags?: string[];
info?: {
title?: string;
description?: string;
version?: string;
};
}): this;
/**
* The 'listen' method is used to bind and start a server to a particular port and optionally a hostname.
*
* @param {number} port
* @param {function} callback
* @returns
*/
listen(port: number, hostname?: string | ((callback: {
server: Server;
port: number;
}) => void), callback?: (callback: {
server: Server;
port: number;
}) => void): Promise<Server>;
/**
* The 'cors' is used to enable the cors origins on the server.
*
* @params {Object}
* @property {(string | RegExp)[]} origins
* @property {boolean} credentials
* @returns
*/
cors({ origins, credentials }?: {
origins?: (string | RegExp)[];
credentials?: boolean;
}): this;
/**
* The 'enableCors' is used to enable the cors origins on the server.
*
* @params {Object}
* @property {(string | RegExp)[]} origins
* @property {boolean} credentials
* @returns
*/
enableCors({ origins, credentials }?: {
origins?: (string | RegExp)[];
credentials?: boolean;
}): this;
/**
* The 'formatResponse' method is used to format the response
*
* @param {function} format
* @returns
*/
formatResponse(format: (r: unknown, statusCode: number) => any): this;
/**
* The 'response' method is used to format the response
*
* @param {function} format
* @returns
*/
response(format: (r: unknown, statusCode: number) => any): this;
/**
* The 'errorHandler' method is middleware that is specifically designed to handle errors.
*
* that occur during the processing of requests
*
* @param {function} error
* @returns
*/
errorHandler(error: (err: Error, ctx: TContext) => any): this;
/**
* The 'catch' method is middleware that is specifically designed to handle errors.
*
* that occur during the processing of requests
*
* @param {function} error
* @returns
*/
catch(error: (err: Error, ctx: TContext) => any): this;
/**
* The 'notFoundHandler' method is middleware that is specifically designed to handle errors notfound that occur during the processing of requests
*
* @param {function} notfound
* @returns
*/
notFoundHandler(fn: (ctx: TContext) => any): this;
/**
* The 'notfound' method is middleware that is specifically designed to handle errors notfound that occur during the processing of requests
*
* @param {function} notfound
* @returns
*/
notfound(fn: (ctx: TContext) => any): this;
/**
* The 'get' method is used to add the request handler to the router for the 'GET' method.
*
* @param {string} path
* @callback {...Function[]} handlers of the middlewares
* @property {Object} ctx - context { req , res , query , params , cookies , files , body}
* @property {Function} next - go to next function
* @returns {this}
*/
get(path: string, ...handlers: ((ctx: TContext, next: TNextFunction) => any)[]): this;
/**
* The 'post' method is used to add the request handler to the router for the 'POST' method.
*
* @param {string} path
* @callback {...Function[]} handlers of the middlewares
* @property {Object} ctx - context { req , res , query , params , cookies , files , body}
* @property {Function} next - go to next function
* @returns {this}
*/
post(path: string, ...handlers: ((ctx: TContext, next: TNextFunction) => any)[]): this;
/**
* The 'put' method is used to add the request handler to the router for the 'PUT' method.
*
* @param {string} path
* @callback {...Function[]} handlers of the middlewares
* @property {Object} ctx - context { req , res , query , params , cookies , files , body}
* @property {Function} next - go to next function
* @returns {this}
*/
put(path: string, ...handlers: ((ctx: TContext, next: TNextFunction) => any)[]): this;
/**
* The 'patch' method is used to add the request handler to the router for the 'PATCH' method.
*
* @param {string} path
* @callback {...Function[]} handlers of the middlewares
* @property {Object} ctx - context { req , res , query , params , cookies , files , body}
* @property {Function} next - go to next function
* @returns {this}
*/
patch(path: string, ...handlers: ((ctx: TContext, next: TNextFunction) => any)[]): this;
/**
* The 'delete' method is used to add the request handler to the router for the 'DELETE' method.
*
* @param {string} path
* @callback {...Function[]} handlers of the middlewares
* @property {Object} ctx - context { req , res , query , params , cookies , files , body}
* @property {Function} next - go to next function
* @returns {this}
*/
delete(path: string, ...handlers: ((ctx: TContext, next: TNextFunction) => any)[]): this;
/**
* The 'all' method is used to add the request handler to the router for 'GET' 'POST' 'PUT' 'PATCH' 'DELETE' methods.
*
* @param {string} path
* @callback {...Function[]} handlers of the middlewares
* @property {object} ctx - context { req , res , query , params , cookies , files , body}
* @property {function} next - go to next function
* @returns {this}
*/
all(path: string, ...handlers: ((ctx: TContext, next: TNextFunction) => any)[]): this;
/**
* The 'any' method is used to add the request handler to the router for 'GET' 'POST' 'PUT' 'PATCH' 'DELETE' methods.
*
* @param {string} path
* @callback {...Function[]} handlers of the middlewares
* @property {object} ctx - context { req , res , query , params , cookies , files , body}
* @property {function} next - go to next function
* @returns {this}
*/
any(path: string, ...handlers: ((ctx: TContext, next: TNextFunction) => any)[]): this;
private _clusterMode;
private _import;
private _registerControllers;
private _registerMiddlewares;
private _customizeResponse;
private _nextFunction;
private _wrapHandlers;
private _wrapResponse;
private _createServer;
private _normalizePath;
private _swaggerHandler;
}
export declare class Application extends Spear {
}
export { Spear };
export default Spear;