tspace-spear 1.2.2 → 1.2.4

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
 
@@ -14,8 +16,14 @@ Install with [npm](https://www.npmjs.com/):
 npm install tspace-spear --save
 
 ```
+
+## Documentation
+
+See the [`docs`](https://thanathip41.github.io/tspace-spear) directory for full documentation.
+
 ## Basic Usage
 - [Start Server](#start-server)
+- [Adapter](#adapter)
 - [Cluster](#cluster)
 - [Global Prefix](#global-prefix)
 - [Logger](#logger)
@@ -29,9 +37,10 @@ npm install tspace-spear --save
 - [Cookie](#cookie)
 - [Middleware](#middleware)
 - [Controller](#controller)
+- [Dto](#dto)
 - [Router](#router)
 - [Swagger](#swagger)
-- [WebSocket](#web-socket)
+- [WebSocket](#websocket)
 - [Example CRUD](#example-crud)
 
 ## Start Server
@@ -49,7 +58,37 @@ 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
+Cluster mode allows tspace-spear to run multiple worker processes to fully utilize multi-core CPU performance.
 ```js
 import { Spear } from "tspace-spear";
 new Spear({
@@ -66,6 +105,9 @@ new Spear({
 ```
 
 ## Global Prefix
+Global Prefix allows you to define a base path for all routes in your application.
+
+It helps keep your API structured and consistent (e.g. /api, /v1, /app).
 ```js
 const app = new Spear({
   globalPrefix : '/api' // prefix all routes
@@ -77,6 +119,16 @@ const app = new Spear({
 ```
 
 ## Logger
+The built-in Logger provides request logging for incoming HTTP requests.
+
+It helps you monitor:
+
+Request method
+Request path
+Performance tracking
+Debugging and observability
+
+You can enable a simple logger or configure advanced logging behavior.
 ```js
 const app = new Spear({
   logger :  true
@@ -92,8 +144,17 @@ const app = new Spear({
 ```
 
 ## Format Response
+Provides a consistent response structure system to standardize how responses are handled across your application.
+
+It ensures that:
+
+* All responses are predictable
+* Errors are properly structured
+* Missing routes are handled cleanly
+* Global error catching is supported
 
 ### Notfound
+The NotFound handler is triggered when no route matches the incoming request.
 ```js
 const app = new Spear()
 .get('/' , () => {
@@ -110,6 +171,13 @@ const app = new Spear()
 ```
 
 ### Response
+The response system ensures that all returned values are automatically formatted and sent to the client.
+
+You can return:
+
+* String
+* Object (JSON)
+* Custom response via ctx.res
 ```js
 import { Spear } from "tspace-spear";
 
@@ -151,6 +219,10 @@ const app = new Spear()
 ```
 
 ### Catch
+The Catch handler is used to handle unexpected runtime errors globally.
+
+It acts as a safety layer to prevent server crashes and standardize error responses.
+
 ```js
 import { Spear } from "tspace-spear";
 import { z } from "zod";
@@ -185,7 +257,9 @@ const app = new Spear()
 ```
 
 ## Cors
+CORS (Cross-Origin Resource Sharing) controls which origins are allowed to access your API.
 
+It helps secure your server by restricting or allowing cross-domain requests.
 ```js
 const app = new Spear()
 .cors({
@@ -200,6 +274,9 @@ const app = new Spear()
 ```
 
 ## Body
+Body parsing allows your server to read incoming request payloads (JSON) and access them via ctx.body.
+
+It enables handling requests with structured data.
 ```js
 
 new Spear()
@@ -215,7 +292,14 @@ new Spear()
 ```
 
 ## File Upload
+File upload support allows handling multipart/form-data requests and working with uploaded files via ctx.files.
 
+It provides:
+
+* Temporary file handling
+* File size limits
+* Manual file movement
+* Auto cleanup option
 ```js
 
 import { Spear, type T } from 'tspace-spear';
@@ -252,6 +336,14 @@ new Spear()
 ```
 
 ## Cookie
+Cookie support allows you to read and manage HTTP cookies from incoming requests via ctx.cookies.
+
+It is useful for:
+
+* Session handling
+* Authentication
+* User preferences
+* Stateful requests
 ```js
 
 new Spear()
@@ -265,6 +357,12 @@ new Spear()
 ```
 
 ## Middleware
+Middleware is a function that runs before the controller handler and is used to:
+
+* Intercept requests
+* Modify ctx
+* Validate or block execution
+* Handle authentication / logging / transformations
 ```js
 import { type T } from "tspace-spear"
 // file cat-middleware.ts
@@ -316,6 +414,9 @@ import CatMiddleware from './cat-middleware.ts'
 ```
 
 ## Controller
+A Controller is used to group related routes and define request handlers in a structured way.
+
+It helps organize your application into modules (similar to NestJS / Express routers), while keeping a clean and readable API design.
 ```js
 import { 
   Controller , 
@@ -430,8 +531,131 @@ import CatController from './cat-controller.ts'
 })()
 ```
 
+
+## Dto
+DTO (Data Transfer Object) is used to validate and transform incoming request data before it reaches your controller logic.
+```js
+import { 
+  Controller , 
+  Post,
+  createDtoDecorator
+  type T
+} from 'tspace-spear';
+
+import z from "zod";
+
+const ValidateDtoBody = (keys: string[]) => {
+  return createDtoDecorator((ctx) => {
+    const body = ctx.body ?? {};
+    const issues: Array<{ path: string; message: string }> = [];
+
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+
+        if (body[key] == null) {
+            issues.push({
+                path: key,
+                message: "Missing field",
+            });
+        }
+    }
+
+    if (issues.length > 0) {
+        throw {
+          message : "Validation failed",
+          issues
+        }
+    }
+  });
+}
+
+const ValidateDtoZodBody = (schema: z.ZodTypeAny) => {
+  return createDtoDecorator((ctx) => {
+    const result = schema.parse(ctx.body);
+    ctx.body = result as T.Body;
+  });
+}
+
+const ValidateDtoPromiseBody = (keys: string[]) => {
+  return createDtoDecorator(async (ctx) => {
+      await new Promise(resolve => setTimeout(resolve,500));
+      // check in DB or other async operation
+      throw new Error('Validation failed in promise!');
+  }, (ctx, error) => {
+    // you implement your custom error handling for async validation here
+    return ctx.res.status(400).json({
+      message: error.message || "Validation failed",
+      issues: error.issues || [],
+    });
+  });
+}
+
+const catSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+})
+
+
+// file cat-controller.ts
+@Controller('/cats')
+export class CatController {
+  @Post('/')
+  @ValidateDtoBody(["name", "age"])
+  public async basic(ctx : T.Context) {
+    const body = ctx.body;
+    return {
+      body
+    }
+  }
+
+  @Post('/zod')
+  @ValidateDtoZodBody(catSchema)
+  public async zod(ctx : T.Context) {
+    const body = ctx.body as z.infer<typeof catSchema>;
+    return {
+      body
+    }
+  }
+
+  @Post('/promise')
+  @ValidateDtoPromiseBody(['name', 'age'])
+  public async promise(ctx : T.Context) {
+    const body = ctx.body;
+
+    return {
+      body
+    }
+  }
+}
+
+import { Spear } , { Router, type T } from "tspace-spear";
+
+import CatController from './cat-controller.ts'
+
+(async () => {
+
+  new Spear({
+    controllers: [ CatController ]
+  })
+  .useBodyParser()
+  .listen(3000 , () => console.log(`Server is now listening http://localhost:3000`))
+
+  // localhost:3000/cats  // basic implete
+  // localhost:3000/cats/zod  // zod implete
+  // localhost:3000/cats/promise // promise implete
+
+})()
+```
+
 ## Router
+The Router allows you to organize routes into modular groups, making your application more scalable and maintainable.
 
+It supports:
+
+* Grouped routes
+* Nested route prefixes
+* Reusable router modules
+* Separation of concerns
 ```js
 import { Spear, Router, type T } from "tspace-spear";
 
@@ -475,6 +699,14 @@ app.listen(port , () => console.log(`Server is now listening http://localhost:30
 ```
 
 ## Swagger
+Provides built-in Swagger support to document your API endpoints.
+
+It allows you to:
+
+* Describe request parameters (query, body, params)
+* Generate API documentation
+* Improve developer experience
+* Standardize API contracts
 ```js
 
 // file cat-controller.ts
@@ -542,7 +774,22 @@ class CatController {
         name :  {
           type : 'string',
           example : "xxxxx"
-        }
+        },
+        status :  {
+            type : 'string',
+            example: "active",
+            enum: ['active', 'inactive'],
+            description: "User status (active = enabled, inactive = disabled)",
+            required : true
+        },
+        roles: {
+            type: 'array',
+            items : {
+                type: 'string',
+                example: "roleA",
+                enum: ['roleA', 'roleB']
+            }
+        },
       }
     }
   })
@@ -619,7 +866,7 @@ class CatController {
         file : {
           type : 'array',
           items: {
-            type:"file",
+            type  :"string",
             format:"binary"
           }
         },
@@ -667,44 +914,78 @@ class CatController {
 ```
 
 ## WebSocket
+Provides built-in WebSocket support for real-time communication.
+
+It allows you to:
+
+* Handle client connections
+* Send/receive messages
+* Build chat systems
+* Manage real-time events
 ```js
 import { Spear } from "tspace-spear";
+import fs from 'fs';
+import path from 'path';
 
 new Spear()
-.get('/', () => 'Hello wor1ld!')
-.post('/', ({ req , res , headers , query })=> {  
-  return res.tooManyRequests()
+.get('/',(ctx) => {
+  // you can serve a HTML file for testing WebSocket connection
+  const htmlWs = fs.readFileSync(path.join(path.resolve(), 'public', 'ws.html'), 'utf-8');
+  return ctx.res.html(htmlWs);
 })
 .ws(() => {
+  const clients = new Map<string, any>();
   return {
     connection: (ws) => {
-      ws.send(JSON.stringify({ type: 'welcome', message: 'Welcome to the server!' }));
+      console.log("connected");
     },
+
     message: (ws, msg) => {
       const data = JSON.parse(msg.toString());
 
-      switch (data.type) {
-        case 'chat':
-          console.log('Chat message:', data.text);
-          ws.send(JSON.stringify({ type: 'chat_ack', message: 'Chat received!' }));
-          break;
+      if (data.type === "register") {
+        ws.userId = data.userId;
+        clients.set(data.userId, ws);
+
+        ws.send(JSON.stringify({
+          type: "system",
+          message: `registered as ${data.userId}`
+        }));
+
+        return;
+      }
+
+      if (data.type === "chat") {
+        const targetWs = clients.get(data.to);
+
+        if (!targetWs) {
+          ws.send(JSON.stringify({
+            type: "error",
+            message: "User not online"
+          }));
+          return;
+        }
 
-        case 'ping':
-          console.log('Ping received');
-          ws.send(JSON.stringify({ type: 'pong' }));
-          break;
+        targetWs.send(JSON.stringify({
+          type: "chat",
+          from: ws.userId,
+          text: data.text
+        }));
 
-        default:
-          ws.send(JSON.stringify({ type: 'error', message: 'Unknown message type' }));
+        return;
       }
     },
-    close: (ws, code, reason) => {
-      console.log('Client disconnected');
+
+    close: (ws) => {
+      if (ws.userId) {
+        clients.delete(ws.userId);
+      }
     },
+    
     error: (ws, error) => {
       console.error('WebSocket error:', error);
     }
-  }    
+  };
 })
 .listen(3000 , ({ port , server }) =>  {
     console.log(`server listening on : http://localhost:${port}`)

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

@@ -0,0 +1,153 @@
+export declare const HTTP_STATUS_MESSAGES: {
+    readonly 100: "Continue";
+    readonly 101: "Switching Protocols";
+    readonly 102: "Processing";
+    readonly 200: "OK";
+    readonly 201: "Created";
+    readonly 202: "Accepted";
+    readonly 203: "Non-Authoritative Information";
+    readonly 204: "No Content";
+    readonly 205: "Reset Content";
+    readonly 206: "Partial Content";
+    readonly 207: "Multi-Status";
+    readonly 208: "Already Reported";
+    readonly 226: "IM Used";
+    readonly 300: "Multiple Choices";
+    readonly 301: "Moved Permanently";
+    readonly 302: "Found";
+    readonly 303: "See Other";
+    readonly 304: "Not Modified";
+    readonly 305: "Use Proxy";
+    readonly 306: "(Unused)";
+    readonly 307: "Temporary Redirect";
+    readonly 308: "Permanent Redirect";
+    readonly 400: "Bad Request";
+    readonly 401: "Unauthorized";
+    readonly 402: "Payment Required";
+    readonly 403: "Forbidden";
+    readonly 404: "Not Found";
+    readonly 405: "Method Not Allowed";
+    readonly 406: "Not Acceptable";
+    readonly 407: "Proxy Authentication Required";
+    readonly 408: "Request Timeout";
+    readonly 409: "Conflict";
+    readonly 410: "Gone";
+    readonly 411: "Length Required";
+    readonly 412: "Precondition Failed";
+    readonly 413: "Payload Too Large";
+    readonly 414: "URI Too Long";
+    readonly 415: "Unsupported Media Type";
+    readonly 416: "Range Not Satisfiable";
+    readonly 417: "Expectation Failed";
+    readonly 418: "I'm a teapot";
+    readonly 421: "Misdirected Request";
+    readonly 422: "Unprocessable Entity";
+    readonly 423: "Locked";
+    readonly 424: "Failed Dependency";
+    readonly 425: "Too Early";
+    readonly 426: "Upgrade Required";
+    readonly 428: "Precondition Required";
+    readonly 429: "Too Many Requests";
+    readonly 431: "Request Header Fields Too Large";
+    readonly 451: "Unavailable For Legal Reasons";
+    readonly 500: "Internal Server Error";
+    readonly 501: "Not Implemented";
+    readonly 502: "Bad Gateway";
+    readonly 503: "Service Unavailable";
+    readonly 504: "Gateway Timeout";
+    readonly 505: "HTTP Version Not Supported";
+    readonly 506: "Variant Also Negotiates";
+    readonly 507: "Insufficient Storage";
+    readonly 508: "Loop Detected";
+    readonly 510: "Not Extended";
+    readonly 511: "Network Authentication Required";
+};
+export declare const HEADER_CONTENT_TYPES: {
+    readonly text: {
+        readonly 'Content-Type': "text/plain";
+    };
+    readonly html: {
+        readonly 'Content-Type': "text/html";
+    };
+    readonly css: {
+        readonly 'Content-Type': "text/css";
+    };
+    readonly js: {
+        readonly 'Content-Type': "application/javascript";
+    };
+    readonly json: {
+        readonly 'Content-Type': "application/json";
+    };
+    readonly form: {
+        readonly 'Content-Type': "application/x-www-form-urlencoded";
+    };
+    readonly multipart: {
+        readonly 'Content-Type': "multipart/form-data";
+    };
+    readonly png: {
+        readonly 'Content-Type': "image/png";
+    };
+    readonly jpg: {
+        readonly 'Content-Type': "image/jpeg";
+    };
+    readonly jpeg: {
+        readonly 'Content-Type': "image/jpeg";
+    };
+    readonly gif: {
+        readonly 'Content-Type': "image/gif";
+    };
+    readonly webp: {
+        readonly 'Content-Type': "image/webp";
+    };
+    readonly svg: {
+        readonly 'Content-Type': "image/svg+xml";
+    };
+    readonly ico: {
+        readonly 'Content-Type': "image/x-icon";
+    };
+    readonly pdf: {
+        readonly 'Content-Type': "application/pdf";
+    };
+    readonly zip: {
+        readonly 'Content-Type': "application/zip";
+    };
+    readonly gzip: {
+        readonly 'Content-Type': "application/gzip";
+    };
+    readonly mp4: {
+        readonly 'Content-Type': "video/mp4";
+    };
+    readonly webm: {
+        readonly 'Content-Type': "video/webm";
+    };
+    readonly ogg: {
+        readonly 'Content-Type': "video/ogg";
+    };
+    readonly mp3: {
+        readonly 'Content-Type': "audio/mpeg";
+    };
+    readonly wav: {
+        readonly 'Content-Type': "audio/wav";
+    };
+    readonly aac: {
+        readonly 'Content-Type': "audio/aac";
+    };
+    readonly oga: {
+        readonly 'Content-Type': "audio/ogg";
+    };
+    readonly woff: {
+        readonly 'Content-Type': "font/woff";
+    };
+    readonly woff2: {
+        readonly 'Content-Type': "font/woff2";
+    };
+    readonly ttf: {
+        readonly 'Content-Type': "font/ttf";
+    };
+    readonly otf: {
+        readonly 'Content-Type': "font/otf";
+    };
+    readonly octet: {
+        readonly 'Content-Type': "application/octet-stream";
+    };
+};