tspace-spear 1.2.7 → 1.2.9-beta.1

package/README.md

@@ -12,12 +12,20 @@ It is designed with a strong focus on developer experience and provides end-to-e
 ## 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
+- 🚀 Optional [uWebSockets.js](#adapter) adapter support for ultra-low latency and maximum throughput
+- 🧠 End-to-end [E2E](#e2e) type safety across the entire request → response lifecycle
+- 🎮 Built-in support for [Controllers](#controller) and route-based architecture
+- 🏷️ Powerful Decorator system for [routes](#router), [middleware](#middleware), validation, and metadata
+- 💉 Built-in constructor-based dependency injection (DI) for [Services](#service)
+- 📦 [DTO](#dto) (Data Transfer Object) support for structured and type-safe request handling
+- 📂 Built-in [File Upload](#file-upload) support via `useFileUpload()` with zero configuration required
+- 🔌 Native [WebSocket](#web-socket) support for real-time applications and event-driven systems
+- ⚛️ [GraphQL](#graphql) support with flexible schema integration and HTTP adapters
+- 🖥️ Built-in [Cluster mode](#cluster) support for multi-core scalability and higher throughput
+- 🧪 Built-in testing utilities for [E2E](#e2e) validation
 - 🧩 Simple and intuitive developer experience
-- 🔌 Flexible architecture for plugins and extensions
-- 📘 Auto-generated Swagger documentation via `app.useSwagger()` (zero manual configuration required)
+- 📘 Auto-generated [Swagger](#swagger) documentation via `app.useSwagger()` with zero manual configuration
+- 🔥 Lightweight and optimized for high-performance APIs and microservices
 
 ---
 
@@ -36,7 +44,7 @@ See the [`docs`](https://thanathip41.github.io/tspace-spear) directory for full
 
 ## Basic Usage
 - [Getting Started](#getting-started)
-- [Cli](#cli)
+- [Quick Started](#quick-started)
 - [Adapter](#adapter)
 - [Cluster](#cluster)
 - [Global Prefix](#global-prefix)
@@ -51,12 +59,13 @@ See the [`docs`](https://thanathip41.github.io/tspace-spear) directory for full
 - [Cookie](#cookie)
 - [Middleware](#middleware)
 - [Controller](#controller)
+- [Service](#service)
 - [Dto](#dto)
 - [Router](#router)
 - [Swagger](#swagger)
 - [WebSocket](#websocket)
+- [Graphql](#graphql)
 - [E2E](#e2e)
-- [Example CRUD](#example-crud)
 
 ## Getting Started
 ```js
@@ -72,29 +81,47 @@ new Spear()
 .listen(8000 , () => console.log(`Server is now listening http://localhost:8000`))
 ```
 
-## Cli
+## Quick Started
+Generate applications, modules, controllers, services, and middleware with the Spear CLI.
 ```sh
 # Install CLI globally
 npm install -g tspace-spear
 
 # Create a new application structure
-tspace-spear create app src
+spear create new my-app
 
-# Create a new controller
-tspace-spear create controller src/controllers/dog
+✔ Successfully created project "my-app"
+
+📦 Project Structure
 
-# Generated structure
 src/
-├── controllers/
-│   └── cat-controller.ts
-│   └── dog-controller.ts
+├── common/
+│   └── middlewares/
+│       └── log.middleware.ts
+│
+├── modules/
+│   └── cats/
+│       ├── cat.controller.ts
+│       ├── cat.service.ts
+│       └── cat.dto.ts
+│
+├── client.ts
 └── index.ts
 
-npm install ts-node --save-dev
+🚀 Next Steps
+
+cd my-app
+
+npm run dev
 
-ts-node src/index.ts
-## Server is now listening http://localhost:8000
-## Docs is now listening http://localhost:8000/api/docs
+✔ Server is running at:
+  http://localhost:8000
+
+✔ Swagger Docs:
+  http://localhost:8000/api/docs
+
+✔ Run E2E client:
+  ts-node src/client.ts
 ```
 
 ## Adapter
@@ -149,12 +176,31 @@ Global Prefix allows you to define a base path for all routes in your applicatio
 It helps keep your API structured and consistent (e.g. /api, /v1, /app).
 ```js
 const app = new Spear({
-  globalPrefix : '/api' // prefix all routes
+  globalPrefix : '/api', // prefix all routes
 })
-.get('/' , () => 'Hello world!')
+.get('/' , () => 'Hello world!') // http://localhost:8000/api
+.get('/cats' , () => `Hello all cats`) // http://localhost:8000/api/cats
+.get('/cats/:id' , ({ params }) => `Hello cat: ${params.id}`) // http://localhost:8000/api/cats/1
 .listen(8000 , () => console.log(`Server is now listening http://localhost:8000`))
 
 // http://localhost:8000/api => 'Hello world!'
+
+// Or this
+
+const app = new Spear()
+.useGlobalPrefix('api', {
+  exclude : [
+    {
+      path : '/cats/*',
+      // methods : '*'
+      // methods : ['GET','POST']
+    }
+  ]
+})
+.get('/' , () => 'Hello world!') // http://localhost:8000/api
+.get('/cats' , () => `Hello all cats`) // http://localhost:8000/cats
+.get('/cats/:id' , ({ params }) => `Hello cat: ${params.id}`) // http://localhost:8000/cats/1
+.listen(8000 , () => console.log(`Server is now listening http://localhost:8000`))
 ```
 
 ## Logger
@@ -574,14 +620,77 @@ import CatController from './cat-controller.ts'
 })()
 ```
 
+## Service
+Registers one or more service classes for Dependency Injection.
+
+All registered services will be available in the controller constructor
+without manual instantiation.
+```js
+// cat-service.ts
+class CatService {
+  public index () {
+    return [
+      {
+        id: 1,
+        name: 'cat1'
+      },
+      {
+        id: 2,
+        name: 'cat2'
+      }
+    ]
+  }
+}
+
+// cat-controller.ts
+import { 
+  Controller, 
+  Get
+} from 'tspace-spear';
+import CatService from './cat-service.ts'
+
+@Service([CatService]) // don't forgot this to send CatService for Dependency Injection(DI)
+@Controller('/cats')
+class CatController {
+
+  constructor(
+    private catService: CatService
+  ) {}
+
+  @Get('/')
+  public index() {
+    return this.catService.index();
+  }
+}
+
+// app.ts
+import { Spear } from "tspace-spear";
+
+(async () => {
+
+  const app = new Spear({
+    controllers : {
+      folder : `${__dirname}/controllers`,
+      name :  /controller\.(ts|js)$/i,
+      preRouteTypes : true 
+    }
+  });
+  
+  app.useSwagger();
+
+  app.listen(8000 , () => console.log(`Server is now listening http://localhost:8000`));
+})()
+```
+
 ## 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,
   Validate,
+  ValidateDto,
+  createDtoDecorator,
   type T
 } from 'tspace-spear';
 
@@ -593,8 +702,6 @@ import {
   validate 
 } from "class-validator";
 
-import { ClassConstructor, plainToInstance } from 'class-transformer';
-
 const ValidateDtoCustomBody = (keys: string[]) => {
   return createDtoDecorator((ctx) => {
     const body = ctx.body ?? {};
@@ -620,13 +727,6 @@ const ValidateDtoCustomBody = (keys: string[]) => {
   });
 }
 
-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));
@@ -646,39 +746,6 @@ 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(),
@@ -692,7 +759,6 @@ class CreateCatDto {
   age!: number;
 }
 
-
 // file cat-controller.ts
 @Controller('/cats')
 export class CatController {
@@ -701,47 +767,40 @@ export class CatController {
   // 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
+      body : ctx.body
     }
   }
 
-  @Post('/')
+  @Post('/custom')
   @ValidateDtoCustomBody(["name", "age"])
   public async custom(ctx : T.Context<{ body : { name : string , age : number }}>) {
-    const body = ctx.body;
-    return {
-      body
-    }
-  }
-
-  @Post('/zod')
-  @ValidateDtoZodBody(catSchema)
-  public async zod(ctx : T.Context<z.infer<typeof catSchema>>) {
-    const body = ctx.body;
     return {
-      body
+      body : ctx.body
     }
   }
 
   @Post('/promise')
   @ValidateDtoPromiseBody(['name'])
   public async promise(ctx : T.Context<{ body : { name : string }}>) {
-    const body = ctx.body;
+    return {
+      body : ctx.body
+    }
+  }
 
+  @Post('/zod')
+  @ValidateDto(catSchema, { adaptor : "zod" })
+  public async zod(ctx : T.Context<{ body : z.infer<typeof catSchema>}>) {
     return {
-      body
+      body : ctx.body
     }
   }
 
   @Post('/cls')
-  @ValidateDtoClsBody(CreateCatDto)
+  @ValidateDto(CreateCatDto)
   public async cls(ctx : T.Context<{ body : CreateCatDto }>) {
-    const body = ctx.body;
-
     return {
-      body
+      body : ctx.body
     }
   }
 }
@@ -1112,6 +1171,163 @@ new Spear()
 
 ```
 
+## Graphql
+GraphQL CRUD Example with graphql-yoga + tspace-spear
+
+This example shows how to build a simple GraphQL CRUD API using graphql-yoga and tspace-spear.
+
+It includes:
+
+- GraphQL schema setup
+- Query and Mutation examples
+- Create / Read / Update / Delete operations
+- HTTP integration with graphql-yoga
+
+The server uses an in-memory array as a fake database for simplicity.
+
+Features
+- High performance HTTP server with tspace-spear
+- Native GraphQL schema definitions
+- Full CRUD operations
+- Simple and dependency-light setup
+- Works with standard GraphQL clients and tools
+
+```sh
+npm install graphql graphql-yoga
+```
+
+```js
+import { type T, Spear } from "tspace-spear";
+
+import {
+  createYoga,
+  createSchema,
+} from 'graphql-yoga';
+
+type User = {
+  id: number;
+  name: string;
+  email: string;
+};
+
+const users: User[] = [
+  {
+    id: 1,
+    name: 'John',
+    email: 'john@gmail.com',
+  },
+];
+
+const yoga = createYoga({
+  graphqlEndpoint: '/graphql',
+
+  schema: createSchema({
+    typeDefs: /* GraphQL */ `
+      type User {
+        id: Int!
+        name: String!
+        email: String!
+      }
+
+      input CreateUserInput {
+        name: String!
+        email: String!
+      }
+
+      input UpdateUserInput {
+        id: Int!
+        name: String
+        email: String
+      }
+
+      type Query {
+        users: [User!]!
+        user(id: Int!): User
+      }
+
+      type Mutation {
+        createUser(input: CreateUserInput!): User!
+        updateUser(input: UpdateUserInput!): User!
+        removeUser(id: Int!): User!
+      }
+    `,
+
+    resolvers: {
+      Query: {
+        users: () => users,
+
+        user: (_root, args) => {
+          return users.find(
+            (u) => u.id === args.id,
+          );
+        },
+      },
+
+      Mutation: {
+        createUser: (_root, args) => {
+          const user = {
+            id: Date.now(),
+            name: args.input.name,
+            email: args.input.email,
+          };
+
+          users.push(user);
+
+          return user;
+        },
+
+        updateUser: (_root, args) => {
+          const user = users.find(
+            (u) => u.id === args.input.id,
+          );
+
+          if (!user) {
+            throw new Error(
+              'User not found',
+            );
+          }
+
+          if (args.input.name !== undefined) {
+            user.name = args.input.name;
+          }
+
+          if (args.input.email !== undefined) {
+            user.email = args.input.email;
+          }
+
+          return user;
+        },
+
+        removeUser: (_root, args) => {
+          const index = users.findIndex(
+            (u) => u.id === args.id,
+          );
+
+          if (index === -1) {
+            throw new Error(
+              'User not found',
+            );
+          }
+
+          const deleted = users[index];
+
+          users.splice(index, 1);
+
+          return deleted;
+        },
+      },
+    },
+  }),
+});
+
+const app = new Spear()
+.get('/graphql',({ req , res }) => yoga(req , res))
+.post('/graphql',({ req , res }) => yoga(req , res)) 
+.listen(4000 , ({ port , server }) =>  {
+  console.log(`server listening on : http://localhost:${port}/graphql`)
+})
+```
+
 ## 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:
@@ -1171,7 +1387,7 @@ class CatController {
     const cat = cats.find((d) => d.id === Number(params.id));
 
     if(cat == null) {
-      return res.notFound('not found cat')
+      throw res.notFound('not found cat')
     }
 
     return {
@@ -1213,7 +1429,7 @@ class CatController {
     const index = cats.findIndex((d) => d.id === id);
 
     if (index === -1) {
-      return res.notFound('not found cat')
+      throw res.notFound('not found cat')
     }
 
     cats[index] = {
@@ -1256,7 +1472,7 @@ import Spear from "tspace-spear";
 const app = new Spear({
   logger : true,
   controllers: {
-      folder : `${__dirname}/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
@@ -1280,79 +1496,55 @@ const client: ApiClient<AppRouter> = new ApiClient(
   `http://localhost:8000/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
+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
-```js
-import { Spear } from "tspace-spear";
-
-const spears = [
-  {
-    id : 1,
-    damage : 100
-  },
-  {
-    id : 2,
-    damage : 75
-  },
-  {
-    id : 3,
-    damage : 50
-  }
-]
-
-new Spear()
-// enable body payload
-.useBodyParser()
-.get('/' , () => spears)
-.get('/:id' , ({ params }) => spears.find(spear => spear.id === Number(params.id ?? 0)))
-.post('/' , ({ body }) =>  {
-    // please validation the your body 
-    const damage  = Number(body.damage ?? (Math.random() * 100).toFixed(0))
-
-    const id = spears.reduce((max, spear) => spear.id > max ? spear.id : max, 0) + 1
-
-    spears.push({ id , damage })
-
-    return spears.find(spear => spear.id === id)
-})
-.patch('/:id' , ({ params , body , res }) =>  {
-    
-    const damage  = Number(body.damage ?? (Math.random() * 100).toFixed(0))
-
-    const id = Number(params.id)
-
-    const spear = spears.find(spear => spear.id === id)
-
-    if (spear == null) return res.status(404).json({ message : 'Spear not found'})
+// res.ok -> true or false
+// res.status -> number
+// res.headers -> Hearders
+// res.data -> { cats: [{ id: 1, name: 'cat1', age: 1.6 },{ id: 2, name: 'cat2', age: 1.8 }] }
+
+// Without checking `res.ok`, `res.data` is always typed as `any`.
+if(res.ok) {
+  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'
+}
 
-    spear.damage = damage;
+await client.get("/cats/:id") ❌ // Expected 2 arguments, but got 1.
+await client.get("/cats/:id", { params : { id : "1" }}) ❌ 
+// The expected type comes from property 'id' which is declared here on type '{ id: number; }'
+await client.get("/cats/:id", { params : { id : 1 }}) ✅
 
-    return spears.find(spear => spear.id === id)
-})
-.delete('/:id', ({ params , res }) => {
+await client.post("/cats") ❌ // Expected 2 arguments, but got 1.
+await client.post("/cats",{
+  body : {}  ❌ // Type '{}' is missing the following properties from type '{ name: string; age: number; }'
+});
+await client.post("/cats",{
+  body : { name : "super cat" } ❌ 
+  // Property 'age' is missing in type '{ name: string; }' 
+  // but required in type '{ name: string; age: number; }'.
+});
+await client.post("/cats",{
+  body : { name : "super cat" , age : 5 }  ✅
+});
 
-  const id = Number(params.id)
+await client.put("/cats") ✅
 
-  const spear = spears.find(spear => spear.id === id)
+await client.put("/cats",{
+  body : {}  ✅
+});
 
-  if (spear == null) return res.status(404).json({ message : 'Spear not found'})
+await client.put("/cats",{
+  body : { name : 1 } ❌ // Type 'number' is not assignable to type 'string'.
+});
 
-  spears.splice(spears.findIndex(spear => spear.id === Number(params.id ?? 0)), 1)
+await client.put("/cats",{
+  body : { name : "super cat" } ✅
+});
 
-  return res.status(204).json()
-})
-.listen(8000 , () => console.log(`Server is now listening http://localhost:8000`))
+await client.put("/cats",{
+  body : { name : "super cat" , age : 5 }  ✅
+});
+ 
+```
 
-```

package/dist/cli/generators/app/index.d.ts

@@ -0,0 +1 @@
+export declare function createApp(inputPath?: string): Promise<void>;