Basic usage#

An entity for entity-router is nothing more than a TypeORM entity.

Please refer to the TypeORM documentation on how to make entities.

There are 3 steps to make and use an EntityRouter.

1. Creating your entities#

Every entities used by entity-routes should have an id property exposed through any route scope, so that they properly implement the GenericEntity.

#typescript
1interface GenericEntity {
2    [k: string]: any;
3    id: string | number;
4}

So a minimal implementation should look at least like this :

#typescript
1export class AbstractEntity {
2    @Groups("all")
3    @PrimaryGeneratedColumn()
4    id: number;
5}

And then you would make all your entities extends from this one, just like any other class inheritance with Typescript. You can learn more about TypeORM table inheritance here.

2. Creating an EntityRouter#

The @EntityRoute decorator creates an EntityRouter on the decorated entity.

The name distinction is to avoid any conflict between the service (EntityRouter) and the decorator (EntityRoute).

Example :

#typescript
1@EntityRoute({ path: "/users", operations: ["create", "update", "details", "list", "delete"] })
2@Entity()
3export class User extends AbstractEntity {
4    @Groups("basic")
5    @Column()
6    name: string;
7}

It takes two arguments, both optional. Complete definition here.

The first argument (EntityRouteArgs) defines your routes.

a string path, which will be the root path for all routes on that entity. Path should start with a "/".
an array of operations, which will enable matching CRUD actions. For example, adding create operation will lead to having a POST:/users route in the example above.

When no path is specified, it defaults to the entity name. With the example above on User entity, the base path would be equal to "/user"

The second argument (EntityRouteConfig) defines the options passed to every routes on that entity.

When no args are passed, the EntityRoute is registered to be used by others as a Subresource but generates no routes for its own entity.

If you don't wan't to write all basic operations everytime you just need to import & use CRUD_OPERATIONS. It looks like this.

#typescript
1@EntityRoute({ path: "/users", operations: CRUD_OPERATIONS })

3. Usage#

After you have decorated every entities for which you want to create an EntityRouter and exposed their properties (with the @Groups decorator), you must register your routes on your node application.

Maker#

Any maker should wrap the makeEntityRouters, so the arguments to pass (MakeEntityRouters) should remain the basically the same :

connection: the TypeORM Connection used
entities: an array of every entities that you decorated with @EntityRoute and for which you want its EntityRouter to be used
options: EntityRouteOptions, an object of global options that will be passed down to all EntityRouter (defaults)

#typescript
1const app = new Koa();
2const bridgeRouters = await makeKoaEntityRouters({ connection, entities, options });
3bridgeRouters.forEach((router) => app.use(router.instance.routes()));
Example with a Koa API

There are 2 built-in makers: makeKoaEntityRouters & makeExpressEntityRouters.

If your Node framework doesn't support classic middleware syntax (Express-like with (req, res, next) => void or Koa-like with (ctx, next) => void), you can make your own maker with your own custom ContextAdapter. TODO link

Route options#

Here are the options available :

#typescript
1type EntityRouteOptions = {
2    defaultMaxDepthOptions?: JoinAndSelectExposedPropsOptions;
3    /** Default ListDetailsOptions, deep merged with defaultEntityRouteOptions */
4    defaultListDetailsOptions?: ListDetailsOptions;
5    /** Default CreateUpdateOptions, deep merged with defaultEntityRouteOptions */
6    defaultCreateUpdateOptions?: CreateUpdateOptions;
7    /** Default subresources options, deep merged with defaultEntityRouteOptions */
8    defaultSubresourcesOptions?: SubresourceMakerOptions;
9    /** Default subresources options, deep merged with defaultEntityRouteOptions */
10    defaultWriterOptions?: WriterOptions;
11    /** Allow soft deletion using TypeORM @DeleteDateColumn */
12    allowSoftDelete?: boolean;
13    /** Hook schema of custom functions to be run at specific operations in a request processing */
14    hooks?: HookSchema;
15    /** Middlewares to be pushed before requestContext middleware */
16    beforeCtxMiddlewares?: Function[];
17    /** Middlewares to be pushed after requestContext middleware */
18    afterCtxMiddlewares?: Function[];
19};
Minimize

There are multiple stages where you can set an EntityRouteOptions.

You can set global options for your entity-routes by passing them to makeEntityRouters (or an implentation of it such as makeExpressEntityRouters) options key.
You can then override the global options by passing a custom options object to the @EntityRoute decorator as 2nd argument.
If you directly use a component's (such as RouteController, Reader or any other) method you can also pass just the options that are needed locally

Metadata#

You can retrieve the RouteMetadata registered by an @EntityRoute decorator by using the getRouteMetadata function.

Introduction

Operations