tspace-spear
Version:
tspace-spear is a lightweight, high-performance API framework for Node.js that leverages the native HTTP server and supports uWebSockets.js (C++) for maximum speed and efficiency.
316 lines (315 loc) • 11.2 kB
TypeScript
import { Server } from 'http';
import WebSocket from 'ws';
import { FastRouter } from './fast-router';
import { Router } from './router';
import type { T } from '../types';
import { AppRoutes } from '../compiler/pre-routes';
/**
*
* 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 _router;
private readonly _parser;
private _globalPrefix;
private _adapter;
private _cluster?;
private _cors?;
private _swagger;
private _swaggerSpecs;
private _ws;
private _errorHandler;
private _globalMiddlewares;
private _formatResponse;
private _onListeners;
private _fileUploadOptions;
private _generatePreRouteTypes;
constructor({ controllers, middlewares, globalPrefix, logger, cluster, adapter }?: T.Application);
/**
* 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 {FastRouter}
*/
get routers(): FastRouter;
get contract(): AppRoutes;
/**
* The 'usePreRouteTypes' method is used to create pre routes for e2e and swagger
*
* @param {{object}} options options
* @property {string} options.folder
* @property {RegExp} options.name
* @returns {this}
*/
usePreRouteTypes(options: {
folder: string;
name: RegExp;
}): this;
/**
* The 'ws' method is used to creates the WebSocket server.
*
* @callback {Function} WebSocketServer
* @param {WebSocketServer} wss - WebSocketServer
* @returns {this}
*/
ws(handlers: () => T.WebSocketHandler, options?: WebSocket.ServerOptions): this;
/**
* 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: T.ContextHandler): this;
/**
* The 'useGlobalPrefix' method is used to sets a global prefix for all routes in the router.
*
* If `globalPrefix` is `null` or `undefined`, it will default to an empty string,
* meaning no prefix will be applied.
*
* @param {string | null} globalPrefix - The base path prefix to apply to all routes.
* @returns {this} Returns the current instance for method chaining.
*/
useGlobalPrefix(globalPrefix: string | null): this;
/**
* The 'useAdater' method is used to switch between different server implementations,
* such as the native Node.js HTTP server or uWebSockets.js (uWS).
*
* @param {T.AdapterServer} adapter - The adapter instance (e.g., HTTP or uWS).
* @returns {this} Returns the current instance for chaining
*/
useAdater(adapter: T.AdapterServer): this;
/**
* The 'useCluster' method is used cluster run the server
*
* @param {boolean | number} cluster
* @returns {this}
*/
useCluster(cluster?: number | boolean): 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?: T.MethodInput[];
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?: T.MethodInput[];
}): 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 // bytes. default Infinity
* @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} doc
* @returns
*/
useSwagger(doc?: T.Swagger.Doc): 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 'response' method is used to format the response
*
* @param {function} format
* @returns
*/
response(format: (r: unknown, statusCode: number) => Record<string, any> | string): 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: any, ctx: T.Context) => T.Response): this;
/**
* The 'notfound' method is middleware that is specifically designed to handle errors notfound that occur during the processing of requests
*
* @param {function} fn
* @returns
*/
notfound(fn: (ctx: T.Context) => T.Response): 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: T.ContextHandler[]): 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: T.ContextHandler[]): 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: T.ContextHandler[]): 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: T.ContextHandler[]): 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: T.ContextHandler[]): this;
/**
* The 'head' method is used to add the request handler to the router for 'HEAD' 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}
*/
head(path: string, ...handlers: T.ContextHandler[]): this;
/**
* The 'head' method is used to add the request handler to the router for 'HEAD' 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}
*/
options(path: string, ...handlers: T.ContextHandler[]): this;
/**
* The 'all' method is used to add the request handler to the router for 'GET' 'POST' 'PUT' 'PATCH' 'DELETE' 'HEAD' 'OPTIONS' 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: T.ContextHandler[]): this;
private _import;
private _scan;
private _registerControllers;
private _registerMiddlewares;
private _wrapHandlers;
private _wrapResponse;
private _nextError;
private _clusterMode;
private _createServer;
private _createContext;
private _normalizePath;
private _swaggerHandler;
}
export declare class Application extends Spear {
}
export { Spear };
export default Spear;