Introduction#

By using the @Groups decorator, you can expose entity properties through one or more route scopes.

That also means that by default, there will be no properties exposed for your entities. This allows you to have optimized queries by specifiying precisely which properties and relations are selected from the database.

Definitions#

Operation kind#

There are 2 operation kind :

the persist operations (create/update)
the read operations (details/list)

Exposed#

An "exposed" property has different meaning depending on the operation kind.

For a read operation, an exposed property will be returned in a route response.
For a persist operation, an exposed property value will be upsertable from a request body.
A custom operation is considered both a read and persistoperation

You can expose a property locally (for an entity route scope using an object with entity route scope as keys and values as operations :

#typescript
1// The decorated property value will be insertable
2// when creating this entity from the POST:/users route
3// and also returned in GET:/users/:userId
4@Groups({ user: ["create", "details"] })

Or you can expose a property globally (for any entity route scope using an array of operations :

#typescript
1// The decorated property value will be insertable
2// when creating this entity from any POST:/xxx route
3// and also returned in any GET:/xxx/:xxxId
4@Groups(["create", "details"])

On a persist operation, any property not exposed through @Groups will be ignored from the request body.

There are also the shortcuts all and basic that you can use directly, or use as a route scope value.

Below is a summary.

Groups	Route Scope	Operations for the User route scope
@Groups(["create", "details"])	All	["create", "details"]
@Groups({ user: ["create", "details"], article: ["list"]})	User(C+D)/Article(L)	["create", "details"]
@Groups("basic")	All	["create", "update", "details", "list",]
@Groups("all")	All	All
@Groups({ user: "all", article: ["list"], role: "basic"})	User(all)/Article(list)/Role(basic)	All

Relations IRIs#

If you need to expose a nested property of a relation (single or collections), you can just add the same group on both the relation entity and the nested property wanted.

On the other hand, if you need to retrieve a relation id but no nested property, just decorate the relation with @Groups and the relation property will have its id (or IRI) as value in the response.

By default, IRIs, or Internationalized Resource Identifier, are used instead of a simple id to clearly identify relations. A relation IRI is made with the idToIRI function using the (route path|entity table name) & id.

You can opt-out of using IRIs by setting the useIris key of EntityRouteOptions to false.

See the example.

Request Lifecycle

Computed property