@2amtech/Crudx

The @2amtech/Crudx is a refactor inspired by the impressive work of nestjsx/crud, consolidating its three packages into one cohesive solution. It simplifies the creation of CRUD (Create, Read, Update, Delete) endpoints for RESTful applications with remarkable ease within Nest.js.

This tool provides decorators specifically designed for endpoint generation, global configurations, request validation, and specialized services, all tailored to enhance the efficiency and usability of Crudx across various contexts.

A comprehensive documentation offers a structured exploration of Crudx functionalities, meticulously divided into distinct sections. Each section is accompanied by illustrative samples and insightful comments, fostering a deeper understanding of how to effectively leverage Crudx in your projects.

Install

$ npm i @2amtech/crudx

Basics

Before diving into Crudx features, it's essential to define a basic Nest.js module for CRUD operations. Let's use the User module as a sample:

First, let's define an entity.

Crudx supports TypeORM for building entities, so let's implement it:

import { 
  AfterLoad,
  BaseEntity,
  Entity, 
  PrimaryGeneratedColumn, 
  Column,
  BeforeInsert,
  BeforeUpdate,
} from "typeorm";
import * as bcrypt from "bcryptjs";

@Entity()
export class User extends BaseEntity {
  @PrimaryGeneratedColumn("uuid") 
  id: string;

  @Column({ unique: true, length: 125 })
  email: string;

  @Column({ type: "varchar", length: 80 })
  password: string; 

  private tempPassword?: string;

  @AfterLoad()
  private loadTempPassword(): void {
    this.tempPassword = this.password;
  }

  @BeforeInsert()
  private async hashPassword(): Promise<void> {
    this.password = await bcrypt.hash(this.password, 10);
  }

  @BeforeUpdate()
  private async encryptPassword(): Promise<void> {
    if (this.tempPassword !== null && this.tempPassword !== this.password) {
      try {
        await this.hashPassword();

        this.tempPassword = this.password;
      } catch (error) {
        if (error instanceof Error) {
          throw new Error("Unable to encrypt password: " + error.message);
        }
      }
    }
  }
}

Next, let's create a service:

import {Injectable} from "@nestjs/common";
import { InjectRepository } from "@nestjs/typeorm";
import { TypeOrmCrudService } from "@2amtech/crudx";
import { Catch, Injectable } from "@nestjs/common";
import { EntityNotFoundError, QueryFailedError } from "typeorm";

@Injectable()
@Catch(QueryFailedError, EntityNotFoundError)
export class UserService extends TypeOrmCrudService<User> {
  constructor(@InjectRepository(User) readonly repo) {
    super(repo);
  }
}

With the service in place, let's define our controller:

Note that we're utilizing the @Crud decorator. When it’s defined for a controller, it automatically creates the basic CRUD routes:

• get /user
• get /user/:id
• post /user
• post /user/bulk
• patch /user/:id
• put /user/:id
• delete /user/:id

For further details, you can refer to the Controllers section.

In our sample, we're specifying some options for our @CRUD decorator: model and params.

The model option is the only required one for the @Crud() decorator. Its type property defines a class as the request body type, enabling data validation. Though not covered in our basics, you can find all related information in the request validation section. The provided type should be an Entity, Model or DTO.

By default, the generated routes will have a parameter named :id. This parameter is intended to represent the model's primary key. We're using the params options to instruct Crudx to define our param :id as a uuid type, indicating that it should match the id field of the User entity.

import { Crud, CrudController } from "@2amtech/crudx";
import { Controller } from "@nestjs/common";
import { User } from "./user.entity";
import { UserService } from "./user.service";

@Crud({
  model: {
    type: User,
  },
  params: {
    id: {
        field: "id",
        type: "uuid",
        primary: true,
    }
  }
})
@Controller("users")
export class UserController implements CrudController<User> {
  constructor(public service: UserService) {}
}

With the entity, service, and controller defined, all that's left is to export a module and import it into the application's main module:

import { Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm";

import { UserController } from "./user.controller";
import { User } from "./user.entity";
import { UserService } from "./user.service";

@Module({
  imports: [TypeOrmModule.forFeature([User])],
  controllers: [UserController],
  providers: [UserService],
  exports: [UserService],
})
export class UserModule {}

IntelliSense

Due to the CRUD controllers being composed by the logic of the @Crud decorator, IntelliSense will not be available on composed methods. To enable your code to properly access the controller's methods from the this keyword, you can add these lines to your class:

import { Crud, CrudController } from '@2amtech/crudx';
import { User } from './user.entity.ts';

@Crud(User)
@Controller('user')
export class UserController implements CrudController<User> {
  constructor(public service: UserService) {}

  get base(): CrudController<User> {
    return this;
  }
}

While the examples provided above offer a simplistic demonstration, they effectively highlight the fundamental principles of utilizing Crudx. For more in-depth insights and comprehensive guidance, we encourage you to explore the dedicated sections outlined below, which deal with specific functionalities and advanced usage scenarios.

Further Reading

• Controllers
• Nested Controllers
• Routes
• Queries and Fiters
• Request Validation
• Response Serialization
• Actions and Access Management
• Request Authenticaten
• Global Options
• ORM
• Requests and Query Params
• Swagger - @2amtech/crudx-swagger

Thank you for exploring our resources. Happy coding!