nmc

nest-mikro-crud

Easily build RESTful CRUD APIs for production.

Showing:

Popularity

Downloads/wk

6

GitHub Stars

10

Maintenance

Last Commit

5d ago

Contributors

1

Package

Dependencies

0

License

Apache-2.0

Type Definitions

Tree-Shakeable

No?

Categories

Readme

Nest.js + MikroORM CRUD

Easily build RESTful CRUD APIs for production.

Features

Default API Endpoints

ActionMethodURLCodeResponse
ListGET/200,400{ total: number; results: Entity[] }
CreatePOST/201,400Entity
RetrieveGET/:lookup/200,404Entity
ReplacePUT/:lookup/200,400,404Entity
UpdatePATCH/:lookup/200,400,404Entity
DestroyDELETE/:lookup/204,404void

Of course, the response bodies are customizable by overriding the controller's routing methods.

Quick Start

Creating the Service

The methods of the service are designed to be highly composable and universal to allow you to use it in various places, not just limited to integration with the controller.

@Injectable()
export class BooksService extends new MikroCrudServiceFactory({
  entityClass: Book,
  dtoClasses: {
    create: CreateBookDto,
    update: UpdateBookDto,
  },
}).product {}

NOTE: Replace actions use the same DTO class as Create actions.

You find that few options are passed to the factory, right? Actually, these options passed to the factory are only the parts necessary to create the class. Most of the configurable things are implemented by overriding its composable methods.

Creating the Controller


There are some wonderful types which are able to get literal types of all the nested circular relation fields' paths and scalar fields' paths like "owner.books.author". Enjoy them in the queryDtoClass.order, queryDtoClass.filter and queryDtoClass.expand options.


@Controller("api/books")
export class BooksController extends new MikroCrudControllerFactory<BooksService>(
  {
    serviceClass: BooksService,
    /**
     * Specify which actions will be enabled.
     */
    actions: ["list", "retrieve", "create", "replace", "update", "destroy"],
    /**
     * `type` should be one of "number", "string" and "uuid" and will be inferred from the metadata
     * type if not specified: Number -> "number", String -> "uuid".
     *
     * `name` is the param name in the url, useful when overriding routing methods, default `"lookup"`.
     */
    lookup: { field: "id", type: "number", name: "id" },

    // options below are optional

    /**
     * Configure the query params.
     *
     * You could also pass your own class or extend the product.
     */
    queryDtoClass: new QueryDtoFactory<Book>({
      // min value is always 0
      limit: { max: 200, default: 100 },
      // min value is always 0
      offset: { max: 100000 },
      order: {
        // can be either a path or a path + order.
        // literal types completely supported
        in: ["name", "price", "writer.name:asc"],
        default: ["price:desc"],
      },
      filter: {
        // allowed fields
        // literal types completely supported
        in: ["name", "price", "writer.name"],
        default: ["price|gte:50", "price|lte:100"],
      },
      expand: {
        // allowed fields
        // literal types completely supported
        in: ["writer", "writer.profile"],
        default: ["writer"],
      },
    }).product,
    /**
     * `type`: the metadata type of the user parameter in routing methods, default `Object`.
     * `decorators`: custom decorators to pick the user from the request.
     * By default, `ReqUser()` is applied to pick the user from `request.user`.
     */
    requestUser: { type: User, decorators: [RequestUser()] },
    /**
     * Customize the options to pass to the validation pipe
     * `transform` and `transformOptions.exposeDefaultValues` will be forced to be `true`
     */
    validationPipeOptions: {},
  }
).product {}

NOTE: order and filter param should always be arrays in the url like /?order[]=&filter[]=

Available Filter Operators:

OperatorFull Name
eqEqual
gtGreater Than
gteGreater Than or Equal
inIn
ltLess Than
lteLess Than or Equal
neNot Equal
ninNot In
likeLike
ilikeInsensitive Like
isnullIs Null
notnullNot Null

Excluding Fields from the Response

See MikroORM's docs

@Entity()
class MyEntity {
  @PrimaryKey()
  id: number;

  @Property({ hidden: true }) // exclude
  price: number;
}

Mandatory Filtering

By default, the MikroORM's entity filters with name "crud" will be enabled. The user parameter is picked from request.user by default, which is customizable through the requestUser option.

NOTE: user may be undefined if no auth guards are used.

@Filter({
  name: "crud",
  cond: ({ user }: { user: User }) => ({
    owner: user,
    writer: { age: { $gte: 18 } }, // MikroORM will join the required relations automatically
  }),
})
@Entity()
class Book extends BaseEntity<Book, "id"> {
  @PrimaryKey()
  id: number;

  @ManyToOne(() => User)
  owner: User;
}

You could dicide which filters to enable and what parameters to pass to the filters by overriding the service's .decideEntityFilters() method.

class BooksService /* extends ... */ {
  async decideEntityFilters({ user }: { user: User }) {
    return { filterName: { these_are: "parameters" } };
  }
}

Populating Relations

By default, the unhidden Collection fields of the entity will be populated mandatorily. The user can populate relations by passing the expand query param like book.owner.profile, and you could specify which fields is allowed to be expanded by specifying the expand.in option when creating the query DTO.

You could populate any relations when handling the request and don't need to worry there will be extra relations expanded unexpectedly in the response. All the entities will be processed before responding to ensure only the relations mentioned in the expand query param are marked as populated to shape the response, therefore, although Collection fields are populated mandatorily, they will be only an array of primary keys in the response if they are not mentioned in the expand query param.

Additional Operations During Database CRUD

There are seven CRUD methods in the service: .list(), .create(), .retrieve(), .replace(), .update(), .destroy() and .save(). As mentioned before, the methods in the service are composable, so each CRUD method is only responsible for its own CRUD operation. Multiple CRUD methods will be called in a routing method.

.save() will be always called once at the end of each routing method to flush the repository. In Create, Replace, Update actions, it will be called one more time right after the entity is created/updated.

NOTE: repository.flush() will flush changes of all the managed entities, which means booksRepo.flush() will also flush changes of User entities.

.replace() has the same code as .update() by default, while Replace actions will call .replace() and Update actions will call .update().

class BooksService /* extends... */ {
  @Inject()
  authorsService: AuthorsService;

  async create({
    data,
    user,
  }: {
    data: CreateBookDto | EntityData<Book>;
    user: User;
  }) {
    const book = await super.create({ data: { ...data, owner: user } });
    const author = await this.authorsService.create({
      data: { user, book },
      user,
    });
    return book;
  }

  async destroy({ entity: book, user }: { entity: Book; user: User }) {
    if (user.username != "admin") throw new ForbiddenException();
    return await super.destroy({ entity: book, user });
  }
}

Applying Additional Decorators

All the factories provide a variety of utility methods, including applying different decorators.

export class UsersController extends new MikroCrudControllerFactory<UsersService>(
  {
    // ...
    queryDtoClass: new QuerDtoFactory<User>({
      // ...
    })
      .applyPropertyDecorators("limit", Min(100))
      .applyPropertyDecorators("offset", Min(100)).product,
    // ...
  }
)
  .applyMethodDecorators("list", UseGuards(JwtAuthGuard))
  .applyMethodDecorators("create", UseGuards(JwtAuthGuard)).product {}

Overriding Routing Methods

In Nest.js, decorators have different behaviors when decorating different things.

DecoratingMetadata Stored ToLookup Metadata From
a classthe classthe prototype chain
a methodthe methodthe method
a parameterthe classthe prototype chain

So we see if a routing method is overridden, it will lose all its metadata.

class UsersController /*extends ...*/ {
  // The url parameter name should be what you have specified
  // in the `lookup.name` option.
  @Patch(":userId") // method decorators should be applied again
  // params do not need to apply decorators
  async update(lookup: number, data: UpdateUserDto, user: User) {
    // ...
  }
}

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100