tspace-spear 1.2.9 → 1.3.0

package/dist/lib/core/server/index.js

@@ -43,6 +43,10 @@ const response_1 = require("./response");
 const compiler_1 = require("../compiler");
 const uWS_1 = require("./uWS");
 const net_2 = require("./net");
+const http_2 = require("./http");
+const metadata_1 = require("../metadata");
+const EMPTY = Object.freeze(Object.create(null));
+const EMPTY_ARRAY = Object.freeze([]);
 /**
  *
  * The 'Spear' class is used to create a server and handle HTTP requests.
@@ -64,7 +68,12 @@ class Spear {
     _middlewares;
     _router = new fast_router_1.FastRouter();
     _parser = new parser_factory_1.ParserFactory();
-    _globalPrefix = '';
+    _globalPrefix = {
+        path: '',
+        options: {
+            exclude: []
+        }
+    };
     _adapter = { kind: 'http', server: http_1.default };
     _cluster;
     _cors;
@@ -110,7 +119,7 @@ class Spear {
         if (cluster)
             this.useCluster(cluster);
         if (adapter)
-            this.useAdater(adapter);
+            this.useAdapter(adapter);
         if (globalPrefix)
             this.useGlobalPrefix(globalPrefix);
         // Ensure controllers is NOT an array and has the required shape
@@ -190,24 +199,55 @@ class Spear {
     /**
      * 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.
+     * This prefix will be prepended to every route path in the application.
+     * If `path` is `null`, `undefined`, or an empty string, no global prefix
+     * will be applied.
+     *
+     * @param {string} path - The global route prefix.
+     *
+     * @param {Object} [options] - Additional configuration options.
+     * @param {Array<{ path: string; method?: TMethod | TMethod[] }>} [options.exclude]
+     * Routes to exclude from the global prefix.
+     *
+     * @returns {this} Returns the current router instance for chaining.
      *
-     * @param {string | null} globalPrefix - The base path prefix to apply to all routes.
-     * @returns {this} Returns the current instance for method chaining.
+     * @example
+     * import Spear from "tspace-spear";
+     * const app = new Spear()
+     *
+     * app.useGlobalPrefix('/api');
+     *
+     * @example
+     * app.useGlobalPrefix('/api', {
+     *   exclude: [
+     *     { path: '/health' },
+     *     { path: '/auth/login', method: 'POST' }
+     *   ]
+     * });
      */
-    useGlobalPrefix(globalPrefix) {
-        this._globalPrefix = globalPrefix == null ? '' : globalPrefix.replace(/^\/+|\/+$/g, '');
+    useGlobalPrefix(path, options) {
+        this._globalPrefix.path = path == null
+            ? ''
+            : path.replace(/^\/+|\/+$/g, '');
+        this._globalPrefix.options.exclude = (options?.exclude ?? []).map(route => {
+            const method = route.methods == null || route.methods === '*'
+                ? '*'
+                : route.methods.map(m => m.toUpperCase());
+            return {
+                path: route.path.replace(/^\/+|\/+$/g, ''),
+                method
+            };
+        });
         return this;
     }
     /**
-     * The 'useAdater' method is used to switch between different server implementations,
+     * The 'useAdapter' 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) {
+    useAdapter(adapter) {
         if (adapter === http_1.default) {
             this._adapter = { kind: 'http', server: adapter };
         }
@@ -218,7 +258,7 @@ class Spear {
             //@ts-ignore
             this._adapter = { kind: 'uWS', server: adapter };
         }
-        this._parser.useAdater(this._adapter);
+        this._parser.useAdapter(this._adapter);
         return this;
     }
     /**
@@ -267,6 +307,7 @@ class Spear {
                 return next();
             }
             const startTime = process.hrtime();
+            //@ts-ignore
             (0, on_finished_1.default)(res, () => {
                 console.log([
                     `[\x1b[1m\x1b[34mINFO\x1b[0m]`,
@@ -382,7 +423,7 @@ class Spear {
     useRouter(router) {
         const routes = router.routes;
         for (const { path, method, handlers } of routes) {
-            this[method](this._normalizePath(this._globalPrefix, path), ...handlers);
+            this[method](this._normalizePath(this._resolveGlobalPrefix({ path, method }), path), ...handlers);
         }
         return this;
     }
@@ -417,7 +458,7 @@ class Spear {
         }
         const server = await this._createServer();
         if (this._generatePreRouteTypes) {
-            await new compiler_1.Compiler().generateRoutes(this._globalPrefix, this._generatePreRouteTypes);
+            await new compiler_1.Compiler().generateRoutes(this._globalPrefix.path, this._generatePreRouteTypes);
         }
         if (this._cluster != null &&
             this._cluster || typeof this._cluster === 'number') {
@@ -542,7 +583,7 @@ class Spear {
      */
     get(path, ...handlers) {
         this._onListeners.push(() => {
-            return this._router.get(this._normalizePath(this._globalPrefix, path), this._wrapHandlers(...this._globalMiddlewares, ...handlers));
+            return this._router.get(this._normalizePath(this._resolveGlobalPrefix({ path, method: 'get' }), path), this._wrapHandlers(...this._globalMiddlewares, ...handlers));
         });
         return this;
     }
@@ -557,7 +598,7 @@ class Spear {
      */
     post(path, ...handlers) {
         this._onListeners.push(() => {
-            return this._router.post(this._normalizePath(this._globalPrefix, path), this._wrapHandlers(...this._globalMiddlewares, ...handlers));
+            return this._router.post(this._normalizePath(this._resolveGlobalPrefix({ path, method: 'post' }), path), this._wrapHandlers(...this._globalMiddlewares, ...handlers));
         });
         return this;
     }
@@ -572,7 +613,7 @@ class Spear {
      */
     put(path, ...handlers) {
         this._onListeners.push(() => {
-            return this._router.put(this._normalizePath(this._globalPrefix, path), this._wrapHandlers(...this._globalMiddlewares, ...handlers));
+            return this._router.put(this._normalizePath(this._resolveGlobalPrefix({ path, method: 'put' }), path), this._wrapHandlers(...this._globalMiddlewares, ...handlers));
         });
         return this;
     }
@@ -587,7 +628,7 @@ class Spear {
      */
     patch(path, ...handlers) {
         this._onListeners.push(() => {
-            return this._router.patch(this._normalizePath(this._globalPrefix, path), this._wrapHandlers(...this._globalMiddlewares, ...handlers));
+            return this._router.patch(this._normalizePath(this._resolveGlobalPrefix({ path, method: 'patch' }), path), this._wrapHandlers(...this._globalMiddlewares, ...handlers));
         });
         return this;
     }
@@ -602,7 +643,7 @@ class Spear {
      */
     delete(path, ...handlers) {
         this._onListeners.push(() => {
-            return this._router.delete(this._normalizePath(this._globalPrefix, path), this._wrapHandlers(...this._globalMiddlewares, ...handlers));
+            return this._router.delete(this._normalizePath(this._resolveGlobalPrefix({ path, method: 'delete' }), path), this._wrapHandlers(...this._globalMiddlewares, ...handlers));
         });
         return this;
     }
@@ -617,7 +658,7 @@ class Spear {
      */
     head(path, ...handlers) {
         this._onListeners.push(() => {
-            return this._router.head(this._normalizePath(this._globalPrefix, path), this._wrapHandlers(...this._globalMiddlewares, ...handlers));
+            return this._router.head(this._normalizePath(this._resolveGlobalPrefix({ path, method: 'head' }), path), this._wrapHandlers(...this._globalMiddlewares, ...handlers));
         });
         return this;
     }
@@ -632,7 +673,7 @@ class Spear {
      */
     options(path, ...handlers) {
         this._onListeners.push(() => {
-            return this._router.options(this._normalizePath(this._globalPrefix, path), this._wrapHandlers(...this._globalMiddlewares, ...handlers));
+            return this._router.options(this._normalizePath(this._resolveGlobalPrefix({ path, method: 'options' }), path), this._wrapHandlers(...this._globalMiddlewares, ...handlers));
         });
         return this;
     }
@@ -647,7 +688,7 @@ class Spear {
      */
     all(path, ...handlers) {
         this._onListeners.push(() => {
-            return this._router.all(this._normalizePath(this._globalPrefix, path), this._wrapHandlers(...this._globalMiddlewares, ...handlers));
+            return this._router.all(this._normalizePath(this._resolveGlobalPrefix({ path, method: 'all' }), path), this._wrapHandlers(...this._globalMiddlewares, ...handlers));
         });
         return this;
     }
@@ -717,52 +758,130 @@ class Spear {
                     console.log(`\x1b[31m[ControllerLoader ERROR]\x1b[0m \x1b[36m${file}\x1b[0m must export a controller class`);
                     continue;
                 }
-                const controllerInstance = new controller();
-                const prefixPath = Reflect.getMetadata("controllers", controller) ?? '';
-                const routers = Reflect.getMetadata("routers", controller) ?? [];
-                const swaggers = Reflect.getMetadata("swaggers", controller) ?? [];
-                if (prefixPath == null)
-                    continue;
+                const controllerInstance = this._createController(controller);
+                const prefixPath = Reflect.getMetadata(metadata_1.CONTROLLER_METADATA, controller) ?? '';
+                const routers = Reflect.getMetadata(metadata_1.ROUTE_METADATA, controller) ?? [];
+                const swaggers = Reflect.getMetadata(metadata_1.SWAGGER_METADATA, controller) ?? [];
+                const middlewares = Reflect.getMetadata(metadata_1.MIDDLEWARE_METADATA, controller) ?? [];
                 for (const { method, path, handler } of Array.from(routers)) {
                     const find = Array.from(swaggers).find(s => s.handler === handler);
                     if (find != null) {
+                        const globalPrefix = this._resolveGlobalPrefix({
+                            path: this._normalizePath(prefixPath, path),
+                            method
+                        });
                         this._swaggerSpecs = [
                             ...this._swaggerSpecs,
                             {
                                 ...find,
-                                path: this._normalizePath(this._globalPrefix, prefixPath, path),
+                                path: this._normalizePath(globalPrefix, prefixPath, path),
                                 method
                             }
                         ];
                     }
-                    this[method](this._normalizePath(this._globalPrefix, prefixPath, path), controllerInstance[String(handler)].bind(controllerInstance));
+                    this[method](this._normalizePath(prefixPath, path), ...this._normalizeMiddlewares(middlewares), controllerInstance[String(handler)].bind(controllerInstance));
                 }
             }
             return;
         }
         for (const controller of this._controllers) {
-            const controllerInstance = new controller();
-            const prefixPath = Reflect.getMetadata("controllers", controller) ?? '';
-            const routers = Reflect.getMetadata("routers", controller) ?? [];
-            const swaggers = Reflect.getMetadata("swaggers", controller) ?? [];
-            if (prefixPath == null)
-                continue;
+            const controllerInstance = this._createController(controller);
+            const prefixPath = Reflect.getMetadata(metadata_1.CONTROLLER_METADATA, controller) ?? '';
+            const routers = Reflect.getMetadata(metadata_1.ROUTE_METADATA, controller) ?? [];
+            const swaggers = Reflect.getMetadata(metadata_1.SWAGGER_METADATA, controller) ?? [];
+            const middlewares = Reflect.getMetadata(metadata_1.MIDDLEWARE_METADATA, controller) ?? [];
             for (const { method, path, handler } of Array.from(routers)) {
                 const find = Array.from(swaggers).find(s => s.handler === handler);
                 if (find != null) {
+                    const globalPrefix = this._resolveGlobalPrefix({
+                        path: this._normalizePath(prefixPath, path),
+                        method
+                    });
                     this._swaggerSpecs = [
                         ...this._swaggerSpecs,
                         {
                             ...find,
-                            path: this._normalizePath(this._globalPrefix, prefixPath, path),
+                            path: this._normalizePath(globalPrefix, prefixPath, path),
                             method
                         }
                     ];
                 }
-                this[method](this._normalizePath(this._globalPrefix, prefixPath, path), controllerInstance[String(handler)].bind(controllerInstance));
+                this[method](this._normalizePath(prefixPath, path), ...this._normalizeMiddlewares(middlewares), controllerInstance[String(handler)].bind(controllerInstance));
             }
         }
     }
+    _createController(ControllerClass) {
+        const services = Reflect.getMetadata(metadata_1.SERVICE_METADATA, ControllerClass) ?? [];
+        const constructorTypes = Reflect.getMetadata(metadata_1.PARAMTYPES_METADATA, ControllerClass) ?? [];
+        if (!constructorTypes.length) {
+            return new ControllerClass();
+        }
+        if (!services.length) {
+            throw new Error(`\x1b[31m[ServiceLoader ERROR]\x1b[0m \x1b[36m${ControllerClass.name}\x1b[0m requires dependencies but no @Service() decorator was found`);
+        }
+        const serviceMap = new Map();
+        for (const ServiceClass of services) {
+            if (typeof ServiceClass !== 'function') {
+                throw new Error(`\x1b[31m[ServiceLoader ERROR]\x1b[0m Invalid service in @Service() of ${ControllerClass.name}`);
+            }
+            serviceMap.set(ServiceClass, new ServiceClass());
+        }
+        const injections = [];
+        const available = services.length
+            ? services
+                .map((s) => s.name)
+            : 'None';
+        for (const DependencyClass of constructorTypes) {
+            const service = serviceMap.get(DependencyClass);
+            if (!service) {
+                throw new Error([
+                    '\x1b[31m[ServiceLoader ERROR]\x1b[0m',
+                    '',
+                    `\x1b[36mController\x1b[0m : ${ControllerClass.name}`,
+                    `\x1b[36mDependency\x1b[0m : ${DependencyClass.name}`,
+                    `\x1b[36mAvailable \x1b[0m : ${available.join(', ')}`,
+                    '',
+                    '\x1b[33mHint\x1b[0m',
+                    '@Service([',
+                    `    ${available.join(',\n    ')},`,
+                    `    ${DependencyClass.name}`,
+                    '])',
+                    '',
+                    `Register '${DependencyClass.name}' in @Service()`
+                ].join('\n'));
+            }
+            injections.push(service);
+        }
+        return new ControllerClass(...injections);
+    }
+    _normalizeMiddlewares = (mids) => {
+        const result = [];
+        const visit = (item) => {
+            if (Array.isArray(item)) {
+                item.forEach(visit);
+                return;
+            }
+            if (!item)
+                return;
+            if (typeof item === "function") {
+                const proto = item.prototype;
+                if (proto && proto !== Object.prototype) {
+                    const instance = new item();
+                    Object.getOwnPropertyNames(proto)
+                        .filter(name => name !== "constructor")
+                        .forEach(name => {
+                        if (typeof instance[name] === "function") {
+                            result.push(instance[name].bind(instance));
+                        }
+                    });
+                    return;
+                }
+                result.push(item);
+            }
+        };
+        mids.forEach(visit);
+        return result;
+    };
     async _registerMiddlewares() {
         if (this._middlewares == null)
             return;
@@ -853,13 +972,15 @@ class Spear {
                     return;
                 }
                 if (typeof result === 'string') {
-                    ctx.res.send(result);
+                    ctx.res.end(result);
                     return;
                 }
                 ctx.res.json(result);
                 return;
             })
-                .catch(err => next(err));
+                .catch(err => {
+                return next(err);
+            });
         };
     }
     _nextError(ctx) {
@@ -867,20 +988,28 @@ class Spear {
         return (err) => {
             if (ctx.res.writableEnded)
                 return;
+            let statusCode = typeof err?.statusCode === 'number' &&
+                Number.isFinite(err.statusCode)
+                ? err.statusCode
+                : 500;
             const errorMessage = err?.message || NEXT_MESSAGE;
             if (this._errorHandler != null) {
                 return this._errorHandler(err, ctx);
             }
             if (!ctx.res.headersSent) {
-                ctx.res.writeHead(500, const_1.HEADER_CONTENT_TYPES['json']);
+                ctx.res.writeHead(statusCode, const_1.HEADER_CONTENT_TYPES['json']);
+            }
+            else {
+                statusCode = ctx.res.statusCode;
             }
             if (this._formatResponse != null) {
                 ctx.res.end(JSON.stringify(this._formatResponse({
                     message: errorMessage
-                }, ctx.res.statusCode)));
+                }, statusCode)));
                 return;
             }
             ctx.res.end(JSON.stringify({
+                statusCode: statusCode,
                 message: errorMessage
             }));
             return;
@@ -992,33 +1121,37 @@ class Spear {
             }
             return server;
         }
-        const server = http_1.default.createServer((req, res) => {
-            if (cors)
-                cors(req, res);
-            return lookup(req, res);
-        });
-        if (this._ws?.handler) {
-            this._ws.server = new ws_1.default.Server({ server, ...this._ws.options });
-            this._ws.server.on('connection', (ws) => {
-                if (this._ws.handler?.connection) {
-                    this._ws.handler.connection(ws);
-                }
-                ws.on('message', (data) => {
-                    this._ws.handler?.message?.(ws, data);
-                });
-                ws.on('close', (code, reason) => {
-                    if (this._ws.handler?.close) {
-                        this._ws.handler?.close(ws, code, reason);
-                    }
-                });
-                ws.on('error', (err) => {
-                    if (this._ws.handler?.error) {
-                        this._ws.handler.error(ws, err);
+        if (adapter.kind === 'http') {
+            const server = http_1.default.createServer((httpReq, httpRes) => {
+                const { req, res } = (0, http_2.httpAdaptRequestResponse)(httpReq, httpRes);
+                if (cors)
+                    cors(req, res);
+                return lookup(req, res);
+            });
+            if (this._ws?.handler) {
+                this._ws.server = new ws_1.default.Server({ server, ...this._ws.options });
+                this._ws.server.on('connection', (ws) => {
+                    if (this._ws.handler?.connection) {
+                        this._ws.handler.connection(ws);
                     }
+                    ws.on('message', (data) => {
+                        this._ws.handler?.message?.(ws, data);
+                    });
+                    ws.on('close', (code, reason) => {
+                        if (this._ws.handler?.close) {
+                            this._ws.handler?.close(ws, code, reason);
+                        }
+                    });
+                    ws.on('error', (err) => {
+                        if (this._ws.handler?.error) {
+                            this._ws.handler.error(ws, err);
+                        }
+                    });
                 });
-            });
+            }
+            return server;
         }
-        return server;
+        throw new Error(`Unsupported adapter`);
     }
     _createContext({ req, res, ps }) {
         const request = req;
@@ -1047,7 +1180,7 @@ class Spear {
         }
         else {
             const addr = req.socket?.remoteAddress;
-            ips = addr ? [addr] : [];
+            ips = addr ? [addr] : EMPTY_ARRAY;
         }
         const ip = (ips.length ? ips[0] : null);
         request.params = params;
@@ -1057,25 +1190,37 @@ class Spear {
         return {
             req: request,
             res: response,
-            headers: headers || Object.create(null),
-            params: params || Object.create(null),
+            headers: headers ?? EMPTY,
+            params: params ?? EMPTY,
             query,
-            body: body || Object.create(null),
-            files: files || Object.create(null),
-            cookies: cookies || Object.create(null),
+            body: body ?? EMPTY,
+            files: files ?? EMPTY,
+            cookies: cookies ?? EMPTY,
             ip,
             ips
         };
     }
     _normalizePath(...paths) {
         const path = paths
+            .filter(Boolean)
             .join('/')
             .replace(/\/+/g, '/')
             .replace(/\/+$/, '');
-        const normalizedPath = path.startsWith('/') ? path : `/${path}`;
-        return /\/api\/api/.test(normalizedPath)
-            ? normalizedPath.replace(/\/api\/api\//, "/api/")
-            : normalizedPath;
+        let normalizedPath = path.startsWith('/')
+            ? path
+            : `/${path}`;
+        const globalPrefix = this._globalPrefix.path
+            .replace(/^\/+|\/+$/g, '');
+        if (globalPrefix) {
+            const duplicatedPrefix = `/${globalPrefix}/${globalPrefix}/`;
+            normalizedPath =
+                normalizedPath.replace(duplicatedPrefix, `/${globalPrefix}/`);
+            if (normalizedPath ===
+                `/${globalPrefix}/${globalPrefix}`) {
+                normalizedPath = `/${globalPrefix}`;
+            }
+        }
+        return normalizedPath || '/';
     }
     async _swaggerHandler() {
         const routes = this.routers
@@ -1102,6 +1247,38 @@ class Spear {
         });
         return;
     }
+    _resolveGlobalPrefix({ path, method }) {
+        const globalPrefix = this._globalPrefix.path;
+        if (!globalPrefix) {
+            return '';
+        }
+        if (path === '*') {
+            return `/${globalPrefix}`;
+        }
+        const cleanPath = path.replace(/^\/+|\/+$/g, '');
+        const upperMethod = method.toUpperCase();
+        const exclude = this._globalPrefix.options.exclude;
+        const isExcluded = exclude.some(route => {
+            const methods = route.method ?? '*';
+            if (methods !== '*' &&
+                !methods.includes(upperMethod)) {
+                return false;
+            }
+            const routePath = route.path.replace(/^\/+|\/+$/g, '');
+            if (routePath === cleanPath) {
+                return true;
+            }
+            if (routePath.endsWith('/*')) {
+                const basePath = routePath.slice(0, -2);
+                return (cleanPath === basePath ||
+                    cleanPath.startsWith(basePath + '/'));
+            }
+            return false;
+        });
+        return isExcluded
+            ? ''
+            : `/${globalPrefix}`;
+    }
 }
 exports.Spear = Spear;
 class Application extends Spear {