tspace-spear 1.2.1 → 1.2.3

package/README.md

@@ -3,8 +3,10 @@
 [![NPM version](https://img.shields.io/npm/v/tspace-spear.svg)](https://www.npmjs.com)
 [![NPM downloads](https://img.shields.io/npm/dm/tspace-spear.svg)](https://www.npmjs.com)
 
-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.
+tspace-spear is a lightweight and high-performance API framework for Node.js, 
+built on the native HTTP server with optional support for uWebSockets.js (C++) to achieve maximum speed and efficiency. 
+
+It is designed with a strong focus on delivering an excellent developer experience.
 
 ## Install
 
@@ -16,6 +18,7 @@ npm install tspace-spear --save
 ```
 ## Basic Usage
 - [Start Server](#start-server)
+- [Adapter](#adapter)
 - [Cluster](#cluster)
 - [Global Prefix](#global-prefix)
 - [Logger](#logger)
@@ -31,7 +34,7 @@ npm install tspace-spear --save
 - [Controller](#controller)
 - [Router](#router)
 - [Swagger](#swagger)
-- [WebSocket](#web-socket)
+- [WebSocket](#websocket)
 - [Example CRUD](#example-crud)
 
 ## Start Server
@@ -49,6 +52,35 @@ new Spear()
 
 ```
 
+## Adapter
+tspace-spear supports multiple server adapters, 
+including the native Node.js HTTP server and uWebSockets.js for high performance.
+
+⚠️ Requirements for uWebSockets.js
+Node.js 18 or higher is required
+Installation is done via GitHub (no official npm release)
+
+```js
+import { Spear } from "tspace-spear";
+import uWS from "uWebSockets.js";
+
+// Install via package.json
+// "dependencies": {
+//   "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.45.0"
+// }
+
+new Spear({ adapter: uWS })
+.get("/", () => "Hello world!")
+.get("/json", () => {
+  return {
+    message: "Hello world!",
+  };
+})
+.listen(3000, () =>
+  console.log("uWS server is running at http://localhost:3000")
+);
+```
+
 ## Cluster
 ```js
 import { Spear } from "tspace-spear";
@@ -619,7 +651,7 @@ class CatController {
         file : {
           type : 'array',
           items: {
-            type:"file",
+            type  :"string",
             format:"binary"
           }
         },

package/dist/lib/core/decorators/context.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Extract specific fields from `ctx.body`.
+ *
+ * This decorator filters the request body and keeps only the
+ * specified keys. The filtered result replaces `ctx.body`
+ * before the controller method is executed.
+ *
+ * @example
+ * ```ts
+ * @Body('email', 'password')
+ * async login(ctx: T.Context) {
+ *   // ctx.body = { email: "...", password: "..." }
+ * }
+ * ```
+ *
+ * @param {...string} bodyParms - Body field names to extract.
+ * @returns {MethodDecorator}
+ */
+export declare const Body: (...bodyParms: string[]) => Function;
+/**
+ * Extract specific uploaded files from `ctx.files`.
+ *
+ * Filters uploaded files and keeps only the specified
+ * file field names before executing the controller method.
+ *
+ * @example
+ * ```ts
+ * \@Files('avatar', 'resume')
+ * async upload(ctx: T.Context) {
+ *   // ctx.files = { avatar: File, resume: File }
+ * }
+ * ```
+ *
+ * @param {...string} filesParms - File field names to extract.
+ * @returns {MethodDecorator}
+ */
+export declare const Files: (...filesParms: string[]) => Function;
+/**
+ * Extract specific route parameters from `ctx.params`.
+ *
+ * Filters route parameters and keeps only the specified
+ * parameter names.
+ *
+ * @example
+ * ```ts
+ * \@Params('id')
+ * async getUser(ctx: T.Context) {
+ *   // ctx.params = { id: "123" }
+ * }
+ * ```
+ *
+ * @param {...string} paramsData - Route parameter names to extract.
+ * @returns {MethodDecorator}
+ */
+export declare const Params: (...paramsData: string[]) => Function;
+/**
+ * Extract specific query parameters from `ctx.query`.
+ *
+ * Filters query parameters and keeps only the specified
+ * query keys.
+ *
+ * @example
+ * ```ts
+ * \@Query('page', 'limit')
+ * async listUsers(ctx: T.Context) {
+ *   // ctx.query = { page: "1", limit: "10" }
+ * }
+ * ```
+ *
+ * @param {...string} queryParms - Query parameter names to extract.
+ * @returns {MethodDecorator}
+ */
+export declare const Query: (...queryParms: string[]) => Function;
+/**
+ * Extract specific cookies from `ctx.cookies`.
+ *
+ * Filters cookies and keeps only the specified cookie keys
+ * before executing the controller method.
+ *
+ * @example
+ * ```ts
+ * \@Cookies('token')
+ * async profile(ctx: T.Context) {
+ *   // ctx.cookies = { token: "..." }
+ * }
+ * ```
+ *
+ * @param {...string} cookiesParms - Cookie names to extract.
+ * @returns {MethodDecorator}
+ */
+export declare const Cookies: (...cookiesParms: string[]) => Function;

package/dist/lib/core/decorators/controller.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Declares a class as a controller and assigns a base route path.
+ *
+ * The provided path will be used as the **base URL prefix**
+ * for all routes defined inside the controller. The path must
+ * start with `/`.
+ *
+ * This decorator stores the controller path using
+ * `Reflect.defineMetadata` under the key `"controllers"`.
+ * The framework can later read this metadata to register
+ * routes automatically.
+ *
+ * @example
+ * ```ts
+ * \@Controller('/users')
+ * class UserController {
+ *
+ *   async list(ctx: T.Context) {
+ *     return [{ id: 1, name: "John" }];
+ *   }
+ *
+ * }
+ * ```
+ *
+ * If a route handler defines `/profile`, the final route becomes:
+ *
+ * ```
+ * /users/profile
+ * ```
+ *
+ * @param {`/${string}`} path - Base route path for the controller.
+ * @returns {ClassDecorator}
+ */
+export declare const Controller: (path: `/${string}`) => ClassDecorator;

package/dist/lib/core/decorators/headers.d.ts

@@ -0,0 +1,31 @@
+import { OutgoingHttpHeaders } from 'http';
+/**
+ * Sets the HTTP response headers and status code before the controller method executes.
+ *
+ * This decorator calls `res.writeHead()` on the underlying Node.js response object,
+ * allowing you to define the response **status code** and **headers** in advance.
+ *
+ * @example
+ * ```ts
+ * class UserController {
+ *
+ *   \@WriteHeader(200, { "Content-Type": "application/json" })
+ *   async profile(ctx: T.Context) {
+ *     return { id: 1, name: "John" };
+ *   }
+ *
+ * }
+ * ```
+ *
+ * Example response:
+ *
+ * ```
+ * HTTP/1.1 200 OK
+ * Content-Type: application/json
+ * ```
+ *
+ * @param {number} statusCode - HTTP status code to send with the response.
+ * @param {OutgoingHttpHeaders} contentType - Response headers to set.
+ * @returns {Function}
+ */
+export declare const WriteHeader: (statusCode: number, contentType: OutgoingHttpHeaders) => Function;

package/dist/lib/core/decorators/index.d.ts

@@ -0,0 +1,9 @@
+import 'reflect-metadata';
+export * from './methods';
+export * from './headers';
+export * from './middleware';
+export * from './controller';
+export * from './headers';
+export * from './statusCode';
+export * from './context';
+export * from './swagger';

package/dist/lib/core/decorators/methods.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Maps a controller method to an HTTP GET route.
+ *
+ * @example
+ * ```ts
+ * \@Get('/users')
+ * async list(ctx: T.Context) {
+ *   return [{ id: 1, name: "John" }];
+ * }
+ * ```
+ */
+export declare const Get: (path: `/${string}`) => (target: any, propertyKey: any) => void;
+/**
+ * Maps a controller method to an HTTP POST route.
+ *
+ * @example
+ * ```ts
+ * \@Post('/users')
+ * async create(ctx: T.Context) {
+ *   return { success: true };
+ * }
+ * ```
+ */
+export declare const Post: (path: `/${string}`) => (target: any, propertyKey: any) => void;
+/**
+ * Maps a controller method to an HTTP PUT route.
+ *
+ * Used for replacing a resource.
+ *
+ * @example
+ * ```ts
+ * \@Put('/users/:id')
+ * async update(ctx: T.Context) {}
+ * ```
+ */
+export declare const Put: (path: `/${string}`) => (target: any, propertyKey: any) => void;
+/**
+ * Maps a controller method to an HTTP PATCH route.
+ *
+ * Used for partially updating a resource.
+ *
+ * @example
+ * ```ts
+ * \@Patch('/users/:id')
+ * async patch(ctx: T.Context) {}
+ * ```
+ */
+export declare const Patch: (path: `/${string}`) => (target: any, propertyKey: any) => void;
+/**
+ * Maps a controller method to an HTTP DELETE route.
+ *
+ * @example
+ * ```ts
+ * \@Delete('/users/:id')
+ * async remove(ctx: T.Context) {}
+ * ```
+ */
+export declare const Delete: (path: `/${string}`) => (target: any, propertyKey: any) => void;
+/**
+ * Maps a controller method to an HTTP HEAD route.
+ *
+ * HEAD responses contain only headers and no response body.
+ *
+ * @example
+ * ```ts
+ * \@Head('/health')
+ * async health(ctx: T.Context) {}
+ * ```
+ */
+export declare const Head: (path: `/${string}`) => (target: any, propertyKey: any) => void;
+/**
+ * Maps a controller method to an HTTP OPTIONS route.
+ *
+ * Typically used for CORS preflight requests.
+ *
+ * @example
+ * ```ts
+ * \@Options('/users')
+ * async options(ctx: T.Context) {}
+ * ```
+ */
+export declare const Options: (path: `/${string}`) => (target: any, propertyKey: any) => void;

package/dist/lib/core/decorators/middleware.d.ts

@@ -0,0 +1,39 @@
+import { T } from '../types';
+/**
+ * Attaches a middleware function to a controller method.
+ *
+ * The middleware will be executed **before the route handler**.
+ * If the middleware calls `next(err)`, the error will be forwarded
+ * to the framework's error handler. Otherwise, the original
+ * controller method will be executed.
+ *
+ * This decorator also stores middleware metadata using `Reflect.defineMetadata`
+ * so the framework can discover and execute it during the request lifecycle.
+ *
+ * @example
+ * ```ts
+ * class UserController {
+ *
+ *   \@Middleware(authMiddleware)
+ *   async profile(ctx: T.Context) {
+ *     return { user: ctx.user };
+ *   }
+ *
+ * }
+ * ```
+ *
+ * Example middleware:
+ *
+ * ```ts
+ * const authMiddleware: T.RequestFunction = (ctx, next) => {
+ *   if (!ctx.user) {
+ *     return next(new Error("Unauthorized"));
+ *   }
+ *   next();
+ * };
+ * ```
+ *
+ * @param {T.RequestFunction} middleware - Middleware function to execute before the route handler.
+ * @returns {MethodDecorator}
+ */
+export declare const Middleware: (middleware: T.RequestFunction) => Function;

package/dist/lib/core/decorators/middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../../../src/lib/core/decorators/middleware.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACI,MAAM,UAAU,GAAG,CAAC,UAA6B,EAAY,EAAE;IAEpE,OAAO,CAAC,MAAW,EAAE,GAAW,EAAE,UAA8B,EAAE,EAAE;QAClE,MAAM,cAAc,GAAG,UAAU,CAAC,KAAK,CAAC;QAExC,UAAU,CAAC,KAAK,GAAG,UAAU,GAAc,EAAE,IAAoB;YAC/D,IAAI;gBAEF,OAAO,CAAC,cAAc,CAAC,aAAa,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;gBAE1D,OAAO,UAAU,CAAC,GAAG,EAAE,CAAC,GAAS,EAAE,EAAE;oBACnC,IAAI,GAAG,IAAI,IAAI,EAAE;wBACf,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;qBAClB;oBAED,OAAO,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;gBAC9C,CAAC,CAAC,CAAC;aAEJ;YAAC,OAAO,KAAU,EAAE;gBACnB,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;aACpB;QACH,CAAC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC,CAAC;AAvBW,QAAA,UAAU,cAuBrB"}
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../../../src/lib/core/decorators/middleware.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACI,MAAM,UAAU,GAAG,CAAC,UAA6B,EAAY,EAAE;IAEpE,OAAO,CAAC,MAAW,EAAE,GAAW,EAAE,UAA8B,EAAE,EAAE;QAClE,MAAM,cAAc,GAAG,UAAU,CAAC,KAAK,CAAC;QAExC,UAAU,CAAC,KAAK,GAAG,UAAU,GAAc,EAAE,IAAoB;YAC/D,IAAI,CAAC;gBAEH,OAAO,CAAC,cAAc,CAAC,aAAa,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;gBAE1D,OAAO,UAAU,CAAC,GAAG,EAAE,CAAC,GAAS,EAAE,EAAE;oBACnC,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;wBAChB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;oBACnB,CAAC;oBAED,OAAO,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;gBAC9C,CAAC,CAAC,CAAC;YAEL,CAAC;YAAC,OAAO,KAAU,EAAE,CAAC;gBACpB,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC;QACH,CAAC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC,CAAC;AAvBW,QAAA,UAAU,cAuBrB"}

package/dist/lib/core/decorators/statusCode.d.ts

@@ -0,0 +1,26 @@
+import { type T } from '../types';
+/**
+ * Sets the HTTP response status code before executing the controller method.
+ *
+ * The provided status code will be automatically clamped between **100** and **599**
+ * to ensure a valid HTTP status range. It also sets the default
+ * `Content-Type` header to `application/json`.
+ *
+ * @example
+ * ```ts
+ * class UserController {
+ *   \@StatusCode(201)
+ *   async create(ctx: T.Context) {
+ *     return { success: true };
+ *   }
+ * }
+ * ```
+ *
+ * In this example the response will be sent with:
+ * - Status: **201 Created**
+ * - Header: `Content-Type: application/json`
+ *
+ * @param {T.StatusCode} statusCode - HTTP status code to send with the response.
+ * @returns {MethodDecorator}
+ */
+export declare const StatusCode: (statusCode: T.StatusCode) => Function;

package/dist/lib/core/decorators/swagger.d.ts

@@ -0,0 +1,36 @@
+import { type T } from "../types";
+/**
+ * Attaches Swagger/OpenAPI specification metadata to a controller method.
+ *
+ * This decorator stores route documentation using `Reflect.defineMetadata`
+ * so the framework can later collect it and generate **Swagger / OpenAPI**
+ * documentation automatically.
+ *
+ * The metadata is stored on the controller constructor under the key `"swaggers"`.
+ * Each decorated method contributes a Swagger specification object.
+ *
+ * @example
+ * ```ts
+ * class UserController {
+ *
+ *   \@Swagger({
+ *     summary: "Get user profile",
+ *     description: "Returns the authenticated user's profile",
+ *     tags: ["Users"],
+ *     responses: {
+ *       200: {
+ *         description: "Successful response"
+ *       }
+ *     }
+ *   })
+ *   async profile(ctx: T.Context) {
+ *     return { id: 1, name: "John" };
+ *   }
+ *
+ * }
+ * ```
+ *
+ * @param {T.Swagger.Spec} data - Swagger/OpenAPI specification for the route.
+ * @returns {MethodDecorator}
+ */
+export declare const Swagger: (data: T.Swagger.Spec) => (target: any, propertyKey: any) => void;