Formating#

Response are formated using the Writer, itself called in the getDetails/getList methods of RouteController. That means auto-reloaded entities are also formated

The writer process each response item/items and call every Decorator functions that are registered.

These are the defaults decorator functions that will be used when enabled in WriterOptions :

Function	Description	WriterOptions's key	Default enabled
setComputedPropsOnItem	Add computed properties to this item	shouldSetComputedPropsOnItem	true
setSubresourcesIriOnItem	Set subresources IRI	shouldSetSubresourcesIriOnItem	true
flattenItem	Flatten item with only id if needed	shouldEntityWithOnlyIdBeFlattened	true

The Writer also performs the following tasks :

Sort item's property keys (if shouldSortItemKeys is true), can pass a custom sortComparatorFn, defaults to sort()
Remove any object that is not another Entity (object that implements GenericEntity) or is not a Date
Can opt-in/out IRI's usage with the useIris option

Examples#

Below examples use these entities

#ts
1abstract class AbstractEntity {
2    @PrimaryGeneratedColumn()
3    id: number;
4
5    @Groups(["details"])
6    get repository() {
7        return getRepository(this.constructor.name);
8    }
9
10    @Groups(["details"])
11    getTableName() {
12        return this.repository.metadata.tableName;
13    }
14}
15
16@Entity()
17class Role extends AbstractEntity {
18    @Column()
19    identifier: string;
20}
21
22@Entity()
23class User extends AbstractEntity {
24    @Column()
25    name: string;
26
27    @ManyToOne(() => Role)
28    role: Role;
29}

1. Remove any object that is not another Entity#

Let's say you have a User entity such as :

#ts
1@EntityRoute({ path: "/users", operation: ["details"] })
2@Entity()
3class User extends AbstractEntity {
4    @Column()
5    name: string;
6
7    @ManyToOne(() => Role)
8    role: Role;
9
10    @Groups(["details"])
11    get repository() {
12        return getRepository(this.constructor.name);
13    }
14
15    @Groups(["details"])
16    getTableName() {
17        return this.repository.metadata.tableName;
18    }
19}

The repository key will not be returned in response since it does not implement the GenericEntity interface.
The tableName will be returned since it's just a string

#json
1{
2    "@context": {
3        "operation": "details",
4        "entity": "user"
5    },
6    "id": 1,
7    "name": "Alex",
8    "tableName": "user"
9}
GET:/users/1

2. Flatten item with only id if needed#

Enabled by default (see defaultEntityRouteOptions). You can opt-out of this behavior by setting the shouldEntityWithOnlyIdBeFlattened key of EntityRouteOptions to false.

Let's say you have a Role and a User entity such as :

#ts
1abstract class AbstractEntity {
2    @Groups("all")
3    @PrimaryGeneratedColumn()
4    id: number;
5}
6
7@Entity()
8class Role extends AbstractEntity {
9    @Column()
10    identifier: string;
11}
12
13@EntityRoute(
14    { path: "/users", operation: ["details"] },
15    { defaultWriterOptions: { shouldEntityWithOnlyIdBeFlattened: true } }
16)
17@Entity()
18class User extends AbstractEntity {
19    @Groups(["details"])
20    @Column()
21    name: string;
22
23    @Groups(["details"])
24    @ManyToOne(() => Role)
25    role: Role;
26}

The User.id = 1 has a relation to the Role.id = 321.

Since no properties except id is exposed on the user.details route scope :

The role relation will be returned as an IRI.
If you opted-out of IRIs, then the id will be returned as is.

#json
1{
2    "@context": {
3        "operation": "details",
4        "entity": "user"
5    },
6    "id": 1,
7    "name": "Alex",
8    "role": "/api/role/321"
9    // or if not using IRIs "role": 321
10}
GET:/users/1

3. Set subresources IRI#

Enabled by default (see defaultEntityRouteOptions). You can opt-out of this behavior by setting the defaultWriterOptions.shouldSetSubresourcesIriOnItem key of EntityRouteOptions to false.

#typescript
1@EntityRoute()
2@Entity()
3class Article extends AbstractEntity {
4    @ManyToOne(() => User, (user) => user.articles)
5    author: User;
6
7    @Column()
8    title: string;
9}
10
11@EntityRoute(
12    { path: "/users/", operations: ["list"] },
13    { defaultWriterOptions: { shouldSetSubresourcesIriOnItem: true } }
14)
15@Entity()
16class User extends AbstractEntity {
17    @Groups({ user: ["create", "details"], article: ["list"] })
18    @Column()
19    name: string;
20
21    @Subresource(() => Article)
22    @OneToMany(() => Article, (article) => article.author)
23    articles: Article[];
24}

The articles property will be set to its IRI /api/user/1/articles (if not exposed through @Groups)

#json
1{
2    "@context": {
3        "operation": "details",
4        "entity": "user"
5    },
6    "articles": "/api/users/1/articles",
7    "id": 1,
8    "name": "Alex"
9}
GET:/users/1

4. Sort item's property keys#

Enabled by default (see defaultEntityRouteOptions). You can opt-out of this behavior by setting the defaultWriterOptions.shouldSortItemKeys key of EntityRouteOptions to false.

#typescript
1@EntityRoute({ path: "/users/", operations: ["list"] }, { defaultWriterOptions: { shouldSortItemKeys: true } })
2@Entity()
3class User extends AbstractEntity {
4    @Groups(["details"])
5    @Column()
6    name: string;
7
8    @Groups(["details"])
9    @OneToMany(() => Article, (article) => article.author)
10    articles: Article[];
11}

All responses keys will be sorted alphabetically, recursively through all nested entities as well

Introduction

Examples