@astahmer/entity-routes NPM

entity-routes allows you to make an instant CRUD with a single @EntityRoute decorator. Compatible with Koa/Express/Next/Nuxt.

No boilerplate controllers. No code generation. No custom schema.

Documentation

Check the docs here.

Motivation

Basically this is a Node / Typescript route handler tightly coupled with TypeORM entities.

I wanted to get rid of writing the same boring controllers again & again for each entities and I could not find a NodeJS project that would fit my needs : being simple enough not to require any configuration (or controllers), yet easily customizable when needed.

Core Features

Instant CRUD with a simple @EntityRoute decorator
Independant service components (Database Reader, Persister, RelationManager etc...)
Built-in validation using class-validator/entity-validator decorators on your entities
Granular control over which properties are exposed (with @Groups) in which context
(nestable) Subresources (Entity properties that have dedicated endpoints)
Inferred entity route mappings (with generated endpoints to get the summary of an entity exposed properties for each contexts)
(async?) Computed properties (methods exposed as properties)
@MaxDepth decorator for entity/properties
Optimized SQL queries with only exposed properties selected
Soft delete/restoration supported (also for Subresources)
Built-in powerful filters for lists (Search/Pagination) that should fit well for 99% use cases
Custom filters if you find yourself in the 1%
Hooks to alter a request handling at any point in the process
Standardized REST responses

Installation

Since this library depends on TS Decorators just like typeorm, we need to install ReflectMetadata.

npm i @astahmer/entity-routes reflect-metadata typeorm

Don't forget to import ReflectMetadata in your app entrypoint.

import "reflect-metadata";

You also need this in your tsconfig.json

{
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true
}

Learn about typescript decorators here.

Quick start

Make your entities

You're just gonna have to create your TypeORM entities just like you always did. Then there are 2 @ decorators that are specific to entity-routes :

@EntityRoute which is a class decorator, must be placed at the top of it so that your entities can be exposed through an EntityRouter.
@Groups which is a property decorator, must be placed at the top of every properties you want to expose through your routes, more details on it later

Here is a simple example.

export class AbstractEntity {
    @Groups("all")
    @PrimaryGeneratedColumn()
    id: number;
}

@EntityRoute({ path: "/users", operations: ["create", "update", "details", "list", "delete"] })
@Entity()
export class User extends AbstractEntity {
    @Groups("basic")
    @Column()
    name: string;

    @Subresource(() => Article)
    @OneToMany(() => Article, (article) => article.author)
    articles: Article[];
}

@EntityRoute()
@Entity()
export class Article extends AbstractEntity {
    @Groups("basic")
    @Column()
    title: string;

    @Groups("basic")
    @Column()
    content: string;

    @Groups("basic")
    @ManyToOne(() => User, (user) => user.articles)
    author: User;
}

It will automatically generate those routes :

[
    "/users : post",
    "/users/mapping : post",
    "/users/:id(\\d+) : put",
    "/users/:id(\\d+)/mapping : put",
    "/users/:id(\\d+) : get",
    "/users/:id(\\d+)/mapping : get",
    "/users : get",
    "/users/mapping : get",
    "/users/:id(\\d+) : delete",
    "/users/:UserId(\\d+)/articles : post",
    "/users/:UserId(\\d+)/articles : get",
    "/users/:UserId(\\d+)/articles/:id(\\d+) : delete",
];

Register your Entity Routes

Using Koa

import { AddressInfo } from "net";
import { makeKoaEntityRouters } from "@astahmer/entity-routes";
import * as Koa from "koa";
import * as bodyParser from "koa-bodyparser";
import { Connection } from "typeorm";
export async function setupKoaApp(connection: Connection) {
    const entities = connection.entityMetadatas.map((meta) => meta.target) as Function[];
    const bridgeRouters = await makeKoaEntityRouters({ connection, entities, options });
    const app = new Koa();
    app.use(bodyParser());
    / Register all routes on koa server
    bridgeRouters.forEach((router) => app.use(router.instance.routes()));
    / Always validate when no groups are passed on validators
    setEntityValidatorsDefaultOption(entities);
    const server = app.listen(); / random port
    const baseURL = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
    const client = axios.create({ baseURL });
    return { baseURL, server, client };
}

Using Express/Next/Nuxt

import { AddressInfo } from "net";
import { makeExpressEntityRouters } from "@astahmer/entity-routes";
import * as bodyParser from "body-parser";
import * as express from "express";
import { Connection } from "typeorm";
export async function setupExpressApp(connection: Connection) {
    const entities = connection.entityMetadatas.map((meta) => meta.target) as Function[];
    const bridgeRouters = await makeExpressEntityRouters({ connection, entities, options });
    const app = express();
    app.use(bodyParser.json());
    app.use(bodyParser.urlencoded({ extended: true }));
    / Register all routes on Express server
    bridgeRouters.forEach((router) => app.use(router.instance));
    const server = app.listen(); / random port
    const baseURL = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
    const client = axios.create({ baseURL });
    return { baseURL, server, client };
}

Final step

That's it. There is no final step. Your routes are ready.

Benefits

0 config required
Compatible with Express, Koa, Next, Nuxt and any other middleware-based framework using adapters
Out-of-the-box support for Koa/Express integrations
Type-safe API
Almost complete code coverage (95%+)
Everything (types included) is exported so you can use it your own way