tspace-spear 1.2.9 → 1.3.0

package/README.md

@@ -15,12 +15,13 @@ It is designed with a strong focus on developer experience and provides end-to-e
 - 🚀 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, middleware, validation, and metadata
+- 🏷️ 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 [Cluster mode](#cluster) support for multi-core scalability and higher throughput
 - 🧪 Built-in testing utilities for [E2E](#e2e) validation
 - 🧩 Simple and intuitive developer experience
 - 📘 Auto-generated [Swagger](#swagger) documentation via `app.useSwagger()` with zero manual configuration
@@ -58,8 +59,11 @@ See the [`docs`](https://thanathip41.github.io/tspace-spear) directory for full
 - [Cookie](#cookie)
 - [Middleware](#middleware)
 - [Controller](#controller)
+- [Service](#service)
+- [Exception](#exception)
 - [Dto](#dto)
 - [Router](#router)
+- [Serve Static Files](#serve-static-files)
 - [Swagger](#swagger)
 - [WebSocket](#websocket)
 - [Graphql](#graphql)
@@ -120,8 +124,6 @@ npm run dev
 
 ✔ Run E2E client:
   ts-node src/client.ts
-
-ts-node src/client.ts // for E2E
 ```
 
 ## Adapter
@@ -176,12 +178,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
@@ -601,6 +622,142 @@ 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`));
+})()
+```
+## Exception
+Exceptions are used to return HTTP errors from your application.
+```js
+import {
+  BadRequestException,
+  UnauthorizedException,
+  ForbiddenException,
+  NotFoundException,
+  MethodNotAllowedException,
+  ConflictException,
+  GoneException,
+  UnsupportedMediaTypeException,
+  UnprocessableEntityException,
+  TooManyRequestsException,
+  InternalServerErrorException,
+  NotImplementedException,
+  BadGatewayException,
+  ServiceUnavailableException,
+  GatewayTimeoutException,
+} from 'tspace-spear/exception';
+
+@Controller('/users')
+class UserController {
+  @Get('/:id')
+  public async show({ params }) {
+
+    if (!params.id) {
+      throw new BadRequestException('User id is required');
+    }
+
+    return {
+      id: params.id,
+    };
+  }
+}
+```
+
+### Exception
+Exceptions are used to return HTTP errors from your application.
+```js
+import {
+  BadRequestException,
+  UnauthorizedException,
+  ForbiddenException,
+  NotFoundException,
+  MethodNotAllowedException,
+  ConflictException,
+  GoneException,
+  UnsupportedMediaTypeException,
+  UnprocessableEntityException,
+  TooManyRequestsException,
+  InternalServerErrorException,
+  NotImplementedException,
+  BadGatewayException,
+  ServiceUnavailableException,
+  GatewayTimeoutException,
+} from 'tspace-spear/exception';
+
+@Controller('/users')
+class UserController {
+  @Get('/:id')
+  public async show({ params }) {
+
+    if (!params.id) {
+      throw new BadRequestException('User id is required');
+    }
+
+    return {
+      id: params.id,
+    };
+  }
+}
+
+```
+
 ## Dto
 DTO (Data Transfer Object) is used to validate and transform incoming request data before it reaches your controller logic.
 ```js
@@ -794,6 +951,33 @@ app.listen(port , () => console.log(`Server is now listening http://localhost:80
 
 ```
 
+## Serve Static Files
+Serve files directly from a local directory.
+```js
+
+const path = require('path');
+
+new Spear({
+  logger: true
+})
+.get('/file/*', (ctx) => {
+  // Maps:
+  //   /file/example.pdf
+  // -> ./example/example.pdf
+  const filePath = path.join(
+    path.resolve(),
+    'example',
+    String(ctx.params['*'])
+  );
+
+  return ctx.res.serveMedia(filePath);
+})
+.listen(3000 , ({ port }) =>  {
+  console.log(`server listening on : http://localhost:${port}`)
+})
+
+```
+
 ## Swagger
 Provides built-in Swagger support to document your API endpoints.
 
@@ -1091,17 +1275,16 @@ new Spear()
 ```
 
 ## Graphql
-GraphQL CRUD Example with graphql-http + tspace-spear
+GraphQL CRUD Example with graphql-yoga + tspace-spear
 
-This example shows how to build a simple GraphQL CRUD API using graphql-http and 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-http
-- cURL testing examples
+- HTTP integration with graphql-yoga
 
 The server uses an in-memory array as a fake database for simplicity.
 
@@ -1113,221 +1296,141 @@ Features
 - Works with standard GraphQL clients and tools
 
 ```sh
-npm install graphql graphql-http
+npm install graphql graphql-yoga
 ```
 
 ```js
+import { type T, Spear } from "tspace-spear";
 
 import {
-  GraphQLSchema,
-  GraphQLObjectType,
-  GraphQLString,
-  GraphQLList,
-  GraphQLNonNull,
-  GraphQLID,
-} from 'graphql';
-
-import { createHandler } from 'graphql-http/lib/use/http';
-import { type T, Spear } from "tspace-spear";
+  createYoga,
+  createSchema,
+} from 'graphql-yoga';
+
+type User = {
+  id: number;
+  name: string;
+  email: string;
+};
 
-/**
- * Fake database
- */
-const users : { 
-  id    : string;
-  name  : string;
-  email :string
-}[] = [];
-
-/**
- * User Type
- */
-const UserType = new GraphQLObjectType({
-  name: 'User',
-
-  fields: {
-    id: { type: GraphQLID },
-    name: { type: GraphQLString },
-    email: { type: GraphQLString },
+const users: User[] = [
+  {
+    id: 1,
+    name: 'John',
+    email: 'john@gmail.com',
   },
-});
-
-/**
- * Queries (READ)
- */
-const QueryType = new GraphQLObjectType({
-  name: 'Query',
+];
 
-  fields: {
-    users: {
-      type: new GraphQLList(UserType),
+const yoga = createYoga({
+  graphqlEndpoint: '/graphql',
 
-      resolve: () => {
-        return users;
-      },
-    },
-
-    user: {
-      type: UserType,
+  schema: createSchema({
+    typeDefs: /* GraphQL */ `
+      type User {
+        id: Int!
+        name: String!
+        email: String!
+      }
 
-      args: {
-        id: { type: new GraphQLNonNull(GraphQLID) },
-      },
+      input CreateUserInput {
+        name: String!
+        email: String!
+      }
 
-      resolve: (_, args) => {
-        return users.find((v) => v.id === args.id);
-      },
-    },
-  },
-});
+      input UpdateUserInput {
+        id: Int!
+        name: String
+        email: String
+      }
 
-/**
- * Mutations (CREATE UPDATE DELETE)
- */
-const MutationType = new GraphQLObjectType({
-  name: 'Mutation',
-
-  fields: {
-    /**
-     * CREATE
-     */
-    createUser: {
-      type: UserType,
-
-      args: {
-        name: { type: new GraphQLNonNull(GraphQLString) },
-        email: { type: new GraphQLNonNull(GraphQLString) },
-      },
+      type Query {
+        users: [User!]!
+        user(id: Int!): User
+      }
 
-      resolve: (_, args) => {
-        const user = {
-          id: String(users.length + 1),
-          name: args.name,
-          email: args.email,
-        };
+      type Mutation {
+        createUser(input: CreateUserInput!): User!
+        updateUser(input: UpdateUserInput!): User!
+        removeUser(id: Int!): User!
+      }
+    `,
 
-        users.push(user);
+    resolvers: {
+      Query: {
+        users: () => users,
 
-        return user;
+        user: (_root, args) => {
+          return users.find(
+            (u) => u.id === args.id,
+          );
+        },
       },
-    },
 
-    /**
-     * UPDATE
-     */
-    updateUser: {
-      type: UserType,
+      Mutation: {
+        createUser: (_root, args) => {
+          const user = {
+            id: Date.now(),
+            name: args.input.name,
+            email: args.input.email,
+          };
 
-      args: {
-        id: { type: new GraphQLNonNull(GraphQLID) },
-        name: { type: GraphQLString },
-        email: { type: GraphQLString },
-      },
+          users.push(user);
 
-      resolve: (_, args) => {
-        const user = users.find((v) => v.id === args.id);
+          return user;
+        },
 
-        if (!user) {
-          throw new Error('User not found');
-        }
+        updateUser: (_root, args) => {
+          const user = users.find(
+            (u) => u.id === args.input.id,
+          );
 
-        if (args.name !== undefined) {
-          user.name = args.name;
-        }
+          if (!user) {
+            throw new Error(
+              'User not found',
+            );
+          }
 
-        if (args.email !== undefined) {
-          user.email = args.email;
-        }
+          if (args.input.name !== undefined) {
+            user.name = args.input.name;
+          }
 
-        return user;
-      },
-    },
+          if (args.input.email !== undefined) {
+            user.email = args.input.email;
+          }
 
-    /**
-     * DELETE
-     */
-    deleteUser: {
-      type: GraphQLString,
+          return user;
+        },
 
-      args: {
-        id: { type: new GraphQLNonNull(GraphQLID) },
-      },
+        removeUser: (_root, args) => {
+          const index = users.findIndex(
+            (u) => u.id === args.id,
+          );
 
-      resolve: (_, args) => {
-        const index = users.findIndex((v) => v.id === args.id);
+          if (index === -1) {
+            throw new Error(
+              'User not found',
+            );
+          }
 
-        if (index === -1) {
-          throw new Error('User not found');
-        }
+          const deleted = users[index];
 
-        users.splice(index, 1);
+          users.splice(index, 1);
 
-        return 'Deleted';
+          return deleted;
+        },
       },
     },
-  },
-});
-
-/**
- * Schema
- */
-const schema = new GraphQLSchema({
-  query: QueryType,
-  mutation: MutationType,
+  }),
 });
 
-/**
- * Handler
- */
-const graphqlHandler = createHandler({
-  schema,
-});
-
-const app =  new Spear()
-.post('/graphql',({ req , res }) => graphqlHandler(req , res))
-
-app.listen(4000 , ({ port , server }) =>  {
+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`)
 })
 ```
 
-```sh
-## Create
-curl -X POST http://localhost:4000/graphql \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "mutation { createUser(name:\"John\", email:\"john@example.com\") { id name email } }"
-  }'
-
-## Read all
-curl -X POST http://localhost:4000/graphql \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "query { users { id name email } }"
-  }'
-
-## Read one
-curl -X POST http://localhost:4000/graphql \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "query { user(id:\"1\") { id name email } }"
-  }'
-
-## Update
-curl -X POST http://localhost:4000/graphql \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "mutation { updateUser(id:\"1\", name:\"Johnny\") { id name email } }"
-  }'
-
-## Delete
-curl -X POST http://localhost:4000/graphql \
-  -H "Content-Type: application/json" \
-  -d '{
-    "query": "mutation { deleteUser(id:\"1\") }"
-  }'
-```
-
 ## 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:
@@ -1387,7 +1490,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 {
@@ -1429,7 +1532,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] = {
@@ -1472,7 +1575,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
@@ -1496,16 +1599,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 }] }
+// 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'
+}
+
+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 }}) ✅
+
+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 }  ✅
+});
+
+await client.put("/cats") ✅
+
+await client.put("/cats",{
+  body : {}  ✅
+});
+
+await client.put("/cats",{
+  body : { name : 1 } ❌ // Type 'number' is not assignable to type 'string'.
+});
+
+await client.put("/cats",{
+  body : { name : "super cat" } ✅
+});
+
+await client.put("/cats",{
+  body : { name : "super cat" , age : 5 }  ✅
+});
  
 ```
 

package/dist/cli/generators/app/index.js

@@ -24,7 +24,7 @@ const c = {
 };
 async function createApp(inputPath) {
     if (!inputPath) {
-        console.log("Missing target path, try: spear g app src");
+        console.log("Missing target path, try: spear create new app");
         process.exit(1);
     }
     const root = path_1.default.resolve(process.cwd(), inputPath);