Nust TS

Nust TS is a lightweight package designed to simplify the process of creating APIs in TypeScript. It leverages the power of uWebSockets, offering a fast and efficient web server. This package provides decorators and utilities to easily define controllers and routes, offering a developer-friendly approach to building web APIs with minimal boilerplate and enhanced readability.

Features

• High Performance: Built with uWebSockets, known for its high performance and efficiency. Nust TS is up to 8.5x faster than Fastify and 20x faster than Express, thanks to its use of C++ addons.
• Lightweight: Only uses reflect-metadata, class-validator, and uWebsockets.
• Parameter Scanning and DTO Validation: Optionally provide DTO classes for automatic validation of request parameters using class-validator.
• Error Handling: Throw an object with status 400 and a message to handle errors gracefully.
• Auto Controller Import: Automatically imports controllers for streamlined setup. Manual import is also supported.
• JavaScript Modular Approach: Leverages JavaScript classes and importing for a clean and modular codebase.

Getting Started

Quick Start

1. Create your project directory and navigate into it:

cd my-project

2. Initialize a new Nust TS project:

npx nust-ts

3. Install the dependencies:

npm install

4. Start the development server with watch mode:

npm run watch

Your project will now be set up and running with hot-reloading enabled.

Installation

To install Nust TS, run:

npm install nust-ts

Example Usage

Create a simple Nust TS server with controller and routes.

src/index.ts

import { bootstrap, importControllers } from "nust-ts";
import path from "path";

const main = async () => {
  const basePath = path.resolve(__dirname, "./controllers");
  await importControllers(basePath);
  await bootstrap();
};

main();

src/controllers/user.controller.ts

import { IsMongoId, IsNotEmpty, IsString } from "class-validator";
import { Controller, Route } from "nust-ts";

class UserDto {
  @IsNotEmpty()
  @IsString()
  name: string;
}

class UserIdDto {
  @IsNotEmpty()
  @IsMongoId()
  userId: string;
}

@Controller("/users")
export class UserController {
  @Route("post", "/")
  createUser(body: UserDto) {
    return { body };
  }

  @Route("get", "/:userId")
  getUser(params: UserIdDto) {
    return { params };
  }

  @Route("put", "/:userId")
  updateUser(params: UserIdDto, body: UserDto) {
    return { params, body };
  }
  
  @Route("delete", "/:userId")
  deleteUser(params: UserIdDto) {
    return { params };
  }
}

Running the Server

Set the environment variable PORT and run your server:

npx ts-node src/index.ts

Your server will start running at http://localhost:9001.

Feature Highlights

• High Performance: Built with uWebSockets, known for its high performance and efficiency. Nust TS is up to 8.5x faster than Fastify and 20x faster than Express, thanks to its use of C++ addons.
• Lightweight: Only uses reflect-metadata, class-validator, and uWebsockets.
• Parameter Scanning and DTO Validation: Optionally provide DTO classes for automatic validation of request parameters using class-validator.
• Error Handling: Throw an object with status 400 and a message to handle errors gracefully.
• Auto Controller Import: Automatically imports controllers for streamlined setup. Manual import is also supported.
• JavaScript Modular Approach: Leverages JavaScript classes and importing for a clean and modular codebase.

Parameter Scanning and DTO Validation

To validate request parameters, define DTO classes with class-validator decorators. Nust TS automatically passes body, params, and query parameters to the handler methods. For example:

import { IsMongoId, IsNotEmpty, IsString } from "class-validator";
import { Controller, Route } from "nust-ts";

class UserDto {
  @IsNotEmpty()
  @IsString()
  name: string;
}

class UserIdDto {
  @IsNotEmpty()
  @IsMongoId()
  userId: string;
}

@Controller("/users")
export class UserController {
  @Route("post", "/")
  createUser(body: UserDto) {
    return { body };
  }

  @Route("get", "/:userId")
  getUser(params: UserIdDto) {
    return { params };
  }

  @Route("put", "/:userId")
  updateUser(params: UserIdDto, body: UserDto) {
    return { params, body };
  }

  @Route("delete", "/:userId")
  deleteUser(params: UserIdDto, query: any) {
    return { params, query };
  }
}

Error Handling

To handle errors, throw an object with a status property (set to 400 for bad requests) and a message property. For example:

import { IsNotEmpty, IsString } from "class-validator";
import { Controller, Route } from "nust-ts";

class UserDto {
  @IsNotEmpty()
  @IsString()
  name: string;
}

@Controller("/users")
export class UserController {
  @Route("post", "/")
  createUser(body: UserDto) {
    if (!body.name) {
      throw { status: 400, message: "Name is required" };
    }
    return { body };
  }
}

Auto Controller Import

Nust TS supports automatic import of controllers. To use it, place your controllers in a specific directory and call importControllers with the path to that directory. Manual import is also supported if you prefer.

Automatic Import

import { bootstrap, importControllers } from "nust-ts";
import path from "path";

const main = async () => {
  const basePath = path.resolve(__dirname, "./controllers");
  await importControllers(basePath);
  await bootstrap();
};

main();

Manual Import

import { bootstrap } from "nust-ts";
import { UserController } from "./controllers/user.controller";

const main = async () => {
  await bootstrap();
};

main();

JavaScript Modular Approach

Nust TS follows JavaScript's modular approach, using classes and imports to maintain a clean and organized codebase.

// user.controller.js
import { Controller, Route } from "nust-ts";

@Controller("/users")
class UserController {
  @Route("post", "/")
  createUser(body) {
    return { body };
  }

  @Route("get", "/:userId")
  getUser(params) {
    return { params };
  }
}

export default UserController;

// index.js
import { bootstrap, importControllers } from "nust-ts";
import path from "path";

const main = async () => {
  const basePath = path.resolve(__dirname, "./controllers");
  await importControllers(basePath);
  await bootstrap();
};

main();

By leveraging Nust TS, you can build efficient, scalable, and maintainable web APIs with ease. Enjoy the simplicity and performance boost that comes with this lightweight framework!