tspace-spear 1.2.5 → 1.2.6-beta.1

package/README.md

@@ -3,10 +3,23 @@
 [![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 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. 
+**tspace-spear** is a lightweight, 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.
+It is designed with a strong focus on developer experience and provides end-to-end (E2E) type safety and testing support across the full request lifecycle, from request input to response output (see [E2E](#e2e)).
+
+---
+
+## Features
+
+- ⚡ High-performance core built on native Node.js HTTP
+- 🚀 Optional uWebSockets.js support via adapter for ultra-low latency and maximum throughput
+- 🧠 End-to-end (E2E) type safety across request → response lifecycle
+- 🧪 Built-in testing support for E2E validation
+- 🧩 Simple and intuitive developer experience
+- 🔌 Flexible architecture for plugins and extensions
+- 📘 Auto-generated Swagger documentation via `app.useSwagger()` (zero manual configuration required)
+
+---
 
 ## Install
 
@@ -41,6 +54,7 @@ See the [`docs`](https://thanathip41.github.io/tspace-spear) directory for full
 - [Router](#router)
 - [Swagger](#swagger)
 - [WebSocket](#websocket)
+- [E2E](#e2e)
 - [Example CRUD](#example-crud)
 
 ## Start Server
@@ -508,8 +522,12 @@ import CatController from './cat-controller.ts'
     controllers: [ CatController ]
     // if you want to import controllers with a directory can you follow the example
     // controllers : {
-    //   folder : `${__dirname}/controllers`,
-    //   name :  /controller\.(ts|js)$/i
+    //   folder : `${__dirname}/controllers`, // nestjs style `${__dirname}/modules/*`
+    //   name :  /controller\.(ts|js)$/i,
+
+    //   *Auto-generate route metadata for type-safe E2E usage, 
+    //   *and swagger documentation. By default if use .useSwagger() in app no need to set any description 
+    //   preRouteTypes : true 
     // }
   })
 
@@ -531,40 +549,48 @@ 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
+  createDtoDecorator,
+  Validate,
   type T
 } from 'tspace-spear';
 
 import z from "zod";
 
-const ValidateDtoBody = (keys: string[]) => {
+import { 
+  IsString, 
+  IsInt, 
+  validate 
+} from "class-validator";
+
+import { ClassConstructor, plainToInstance } from 'class-transformer';
+
+const ValidateDtoCustomBody = (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];
+      const key = keys[i];
 
-        if (body[key] == null) {
-            issues.push({
-                path: key,
-                message: "Missing field",
-            });
-        }
+      if (body[key] == null) {
+          issues.push({
+              path: key,
+              message: "Missing field",
+          });
+      }
     }
 
     if (issues.length > 0) {
-        throw {
-          message : "Validation failed",
-          issues
-        }
+      throw {
+        message : "Validation failed",
+        issues
+      }
     }
   });
 }
@@ -580,7 +606,12 @@ 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!');
+      const cats = await catRepository.findMany({ where : { name : ctx.body.name }});
+
+      if(!cats.length) {
+       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({
@@ -590,18 +621,70 @@ const ValidateDtoPromiseBody = (keys: string[]) => {
   });
 }
 
+const ValidateDtoClsBody = <T extends object>(
+  cls: ClassConstructor<T>
+) => {
+    return createDtoDecorator(async (ctx) => {
+
+      const dto = plainToInstance(
+          cls,
+          ctx.body
+      );
+
+      const errors = await validate(dto);
+
+      if (errors.length > 0) {
+          throw {
+            message: "Validation failed",
+            issues: errors.flatMap((error) => {
+              const constraints = error.constraints ?? {};
+
+              const firstError = Object.values(constraints)[0] ?? "Validation error";
+
+              return {
+                  path: error.property,
+                  message: firstError,
+              };
+            })
+          };
+      }
+
+      ctx.body = dto;
+    }
+  );
+};
+
 const catSchema = z.object({
   name: z.string(),
   age: z.number(),
 })
 
+class CreateCatDto {
+  @IsString()
+  name!: string;
+
+  @IsInt()
+  age!: number;
+}
+
 
 // file cat-controller.ts
 @Controller('/cats')
 export class CatController {
+
   @Post('/')
-  @ValidateDtoBody(["name", "age"])
-  public async basic(ctx : T.Context) {
+  // only required validation without type checking
+  @Validate(["name", "age"], { required: { allowEmptyString: false, allowNull: false } })
+  public async basic(ctx : T.Context<{ body : { name : any , age : any }}>) {
+    const body = ctx.body;
+    return {
+      body
+    }
+  }
+
+  @Post('/')
+  @ValidateDtoCustomBody(["name", "age"])
+  public async custom(ctx : T.Context<{ body : { name : string , age : number }}>) {
     const body = ctx.body;
     return {
       body
@@ -610,16 +693,26 @@ export class CatController {
 
   @Post('/zod')
   @ValidateDtoZodBody(catSchema)
-  public async zod(ctx : T.Context) {
-    const body = ctx.body as z.infer<typeof catSchema>;
+  public async zod(ctx : T.Context<z.infer<typeof catSchema>>) {
+    const body = ctx.body;
     return {
       body
     }
   }
 
   @Post('/promise')
-  @ValidateDtoPromiseBody(['name', 'age'])
-  public async promise(ctx : T.Context) {
+  @ValidateDtoPromiseBody(['name'])
+  public async promise(ctx : T.Context<{ body : { name : string }}>) {
+    const body = ctx.body;
+
+    return {
+      body
+    }
+  }
+
+  @Post('/cls')
+  @ValidateDtoClsBody(CreateCatDto)
+  public async cls(ctx : T.Context<{ body : CreateCatDto }>) {
     const body = ctx.body;
 
     return {
@@ -992,6 +1085,187 @@ new Spear()
 })
 
 
+```
+
+## E2E
+Provides end-to-end type safety and testing support across the full request lifecycle, from request input to
+response output. It allows you to:
+```js
+// file cat-controller.ts
+import z from 'zod';
+import {
+  type T,
+  Controller,
+  Get,
+  Post,
+  Put,
+  Delete,
+  createDtoDecorator
+} from "tspace-spear";
+
+const catSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  age: z.number(),
+});
+
+const catSchemaAction = z.object({
+  name: z.string(),
+  age: z.number(),
+});
+
+type Cat = z.infer<typeof catSchema>
+
+let cats: z.infer<typeof catSchema>[] = [
+  { id: 1, name: 'cat1', age: 1.6 },
+  { id: 2, name: 'cat2', age: 1.8 },
+];
+
+const ValidateDtoBody = (schema: z.ZodTypeAny) => {
+  return createDtoDecorator((ctx) => {
+    const result = schema.parse(ctx.body);
+    ctx.body = result as T.Body;
+  });
+};
+@Controller('/cats')
+class CatController {
+
+  @Get('/')
+  public async index({
+    query,
+  }: T.Context) {
+    return {
+      cats,
+    };
+  }
+
+  @Get('/:id')
+  public async show({ res, params }: T.Context<{ params: { id: number } }>) : Promise<{
+    cat : Cat
+  }> {
+    const cat = cats.find((d) => d.id === Number(params.id));
+
+    if(cat == null) {
+      return res.notFound('not found cat')
+    }
+
+    return {
+      cat
+    };
+  }
+
+  @Post('/')
+  @ValidateDtoBody(catSchemaAction)
+  public async create({
+    body,
+  }: T.Context<{ body: z.infer<typeof catSchemaAction> }>) {
+
+    const cat = {
+      id: cats.length + 1,
+      ...body
+    }
+
+    cats.push(cat);
+
+    return {
+      cat,
+      message: 'created',
+    };
+  }
+
+  @Put('/:id')
+  @ValidateDtoBody(catSchemaAction.partial())
+  public async update({
+    res,
+    params,
+    body,
+  }: T.Context<{
+    params: { id: number };
+    body: Partial<z.infer<typeof catSchemaAction>>;
+  }>) {
+    const id = Number(params.id);
+
+    const index = cats.findIndex((d) => d.id === id);
+
+    if (index === -1) {
+      return res.notFound('not found cat')
+    }
+
+    cats[index] = {
+      ...cats[index],
+      ...body,
+      id
+    };
+
+    const cat = cats[index]
+
+    return {
+      message: 'updated',
+      cat,
+    };
+  }
+
+  @Delete('/:id')
+  public async remove({ res, params }: T.Context<{ params: { id: number } }>) {
+    const id = Number(params.id);
+
+    const index = cats.findIndex((d) => d.id === id);
+
+    if (index === -1) {
+      throw res.notFound('not found cat')
+    }
+
+    cats = cats.filter((d) => d.id !== id);
+
+    return {
+      message: 'deleted',
+    };
+  }
+}
+
+export { CatController };
+export default CatController;
+
+// file server/app.ts
+import Spear from "tspace-spear";
+const app = new Spear({
+  logger : true,
+  controllers: {
+      folder : `${__dirname}/controllers`,
+      name:/controller\.(ts|js)$/i,
+      // don't forget to set this option for auto-generate route metadata for type-safe E2E usage, 
+      // and swagger documentation. By default if use .useSwagger() in app no need to set any description
+      preRouteTypes: true
+  }
+})
+
+app.useGlobalPrefix('api');
+app.useBodyParser();
+app.listen(3000 , () => console.log(`Server is now listening http://localhost:3000`));
+
+type AppRouter = typeof app.contract;
+export { AppRouter }
+export default app;
+
+// file frontend/index.ts
+import { AppRouter } from "./server/app";
+import { ApiClient } from "tspace-spear/client";
+
+const client: ApiClient<AppRouter> = new ApiClient(
+  `http://localhost:3000/api`
+);
+
+const test = await client.get("/catsq"); // Type error: Argument of type '"/catsq"' is not assignable to parameter of type '"/cats" | "/cats/:id" | ... 3 more
+const res = await client.get("/cats");
+  res.data.cats = 1 // Type error: Type 'number' is not assignable to type '{ id: number; name: string; age: number; }[]'
+  res.data.cats[0].name = 1 // Type error: Type 'number' is not assignable to type 'string'
+  res.data.cats[0].age = "1.6" // Type error: Type 'string' is not assignable to type 'number'
+
+  console.log(res) 
+  // res.ok -> boolean
+  // res.status -> number
+  // res.data -> { cats: [{ id: 1, name: 'cat1', age: 1.6 },{ id: 2, name: 'cat2', age: 1.8 }] }
+ 
 ```
 
 ## Example CRUD

package/dist/cli/app.d.ts

@@ -0,0 +1 @@
+export declare const app = "\nimport Spear from \"tspace-spear\";\n\nexport const app = new Spear({\n  logger: true,\n  controllers: {\n    folder: `${__dirname}/controllers`,\n    name: /controller\\\\.(ts|js)$/i,\n    preRouteTypes: true\n  }\n})\n\napp.useGlobalPrefix(\"api\");\n\napp.useBodyParser();\n\napp.listen(8000 , ({ port , server }) =>  {\n    console.log(`server listening on : http://localhost:${port}`)\n})\n";

package/dist/cli/app.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.app = void 0;
+exports.app = `
+import Spear from "tspace-spear";
+
+export const app = new Spear({
+  logger: true,
+  controllers: {
+    folder: \`\${__dirname}/controllers\`,
+    name: /controller\\\\.(ts|js)$/i,
+    preRouteTypes: true
+  }
+})
+
+app.useGlobalPrefix("api");
+
+app.useBodyParser();
+
+app.listen(8000 , ({ port , server }) =>  {
+    console.log(\`server listening on : http://localhost:\${port}\`)
+})
+`;
+//# sourceMappingURL=app.js.map

package/dist/cli/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/cli/app.ts"],"names":[],"mappings":";;;AAAa,QAAA,GAAG,GAAG;;;;;;;;;;;;;;;;;;;CAmBlB,CAAC"}

package/dist/cli/controller.d.ts

@@ -0,0 +1 @@
+export declare const CatController = "\nimport {\n  type T,\n  Controller,\n  Get,\n  Post,\n  Put,\n  Delete\n} from \"tspace-spear\";\n\ntype Cat = {\n  id: number;\n  name: string;\n  age: number;\n};\n\nlet cats: Cat[] = [\n  {\n    id: 1,\n    name: \"cat 1\",\n    age: 2\n  },\n  {\n    id: 2,\n    name: \"cat 2\",\n    age: 4\n  }\n];\n\n@Controller(\"/cats\")\nexport default class CatController {\n\n  @Get(\"/\")\n  async index() {\n    return {\n      cats\n    };\n  }\n\n  @Get(\"/:id\")\n  async show({\n    res,\n    params\n  }: T.Context<{\n    params: {\n      id: number;\n    };\n  }>) {\n\n    const cat = cats.find(\n      d => d.id === Number(params.id)\n    );\n\n    if (!cat) {\n      throw res.notFound(\n        \"Cat not found\"\n      );\n    }\n\n    return {\n      cat\n    };\n  }\n\n  @Post(\"/\")\n  async create({\n    body\n  }: T.Context<{\n    body: {\n      name: string;\n      age: number;\n    };\n  }>) {\n\n    const cat: Cat = {\n      id: cats.length + 1,\n      name: body.name,\n      age: body.age\n    };\n\n    cats.push(cat);\n\n    return {\n      message: \"Created\",\n      cat\n    };\n  }\n\n  @Put(\"/:id\")\n  async update({\n    res,\n    params,\n    body\n  }: T.Context<{\n    params: {\n      id: number;\n    };\n    body: Partial<{\n      name: string;\n      age: number;\n    }>;\n  }>) {\n\n    const index = cats.findIndex(\n      d => d.id === Number(params.id)\n    );\n\n    if (index === -1) {\n      throw res.notFound(\n        \"Cat not found\"\n      );\n    }\n\n    cats[index] = {\n      ...cats[index],\n      ...body\n    };\n\n    return {\n      message: \"Updated\",\n      cat: cats[index]\n    };\n  }\n\n  @Delete(\"/:id\")\n  async remove({\n    res,\n    params\n  }: T.Context<{\n    params: {\n      id: number;\n    };\n  }>) {\n\n    const index = cats.findIndex(\n      d => d.id === Number(params.id)\n    );\n\n    if (index === -1) {\n      throw res.notFound(\n        \"Cat not found\"\n      );\n    }\n\n    cats = cats.filter(\n      d => d.id !== Number(params.id)\n    );\n\n    return {\n      message: \"Deleted\"\n    };\n  }\n}\n";

package/dist/cli/controller.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CatController = void 0;
+exports.CatController = `
+import {
+  type T,
+  Controller,
+  Get,
+  Post,
+  Put,
+  Delete
+} from "tspace-spear";
+
+type Cat = {
+  id: number;
+  name: string;
+  age: number;
+};
+
+let cats: Cat[] = [
+  {
+    id: 1,
+    name: "cat 1",
+    age: 2
+  },
+  {
+    id: 2,
+    name: "cat 2",
+    age: 4
+  }
+];
+
+@Controller("/cats")
+export default class CatController {
+
+  @Get("/")
+  async index() {
+    return {
+      cats
+    };
+  }
+
+  @Get("/:id")
+  async show({
+    res,
+    params
+  }: T.Context<{
+    params: {
+      id: number;
+    };
+  }>) {
+
+    const cat = cats.find(
+      d => d.id === Number(params.id)
+    );
+
+    if (!cat) {
+      throw res.notFound(
+        "Cat not found"
+      );
+    }
+
+    return {
+      cat
+    };
+  }
+
+  @Post("/")
+  async create({
+    body
+  }: T.Context<{
+    body: {
+      name: string;
+      age: number;
+    };
+  }>) {
+
+    const cat: Cat = {
+      id: cats.length + 1,
+      name: body.name,
+      age: body.age
+    };
+
+    cats.push(cat);
+
+    return {
+      message: "Created",
+      cat
+    };
+  }
+
+  @Put("/:id")
+  async update({
+    res,
+    params,
+    body
+  }: T.Context<{
+    params: {
+      id: number;
+    };
+    body: Partial<{
+      name: string;
+      age: number;
+    }>;
+  }>) {
+
+    const index = cats.findIndex(
+      d => d.id === Number(params.id)
+    );
+
+    if (index === -1) {
+      throw res.notFound(
+        "Cat not found"
+      );
+    }
+
+    cats[index] = {
+      ...cats[index],
+      ...body
+    };
+
+    return {
+      message: "Updated",
+      cat: cats[index]
+    };
+  }
+
+  @Delete("/:id")
+  async remove({
+    res,
+    params
+  }: T.Context<{
+    params: {
+      id: number;
+    };
+  }>) {
+
+    const index = cats.findIndex(
+      d => d.id === Number(params.id)
+    );
+
+    if (index === -1) {
+      throw res.notFound(
+        "Cat not found"
+      );
+    }
+
+    cats = cats.filter(
+      d => d.id !== Number(params.id)
+    );
+
+    return {
+      message: "Deleted"
+    };
+  }
+}
+`;
+//# sourceMappingURL=controller.js.map

package/dist/cli/controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.js","sourceRoot":"","sources":["../../src/cli/controller.ts"],"names":[],"mappings":";;;AAAa,QAAA,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyJ5B,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};