Example Project

The repository includes a small NestJS books API under examples/books-api.

It demonstrates the complete fields controller flow:

• build field schemas from Swagger-decorated response DTOs.
• parse and validate query.fields.
• derive relation includes from selected nested fields.
• call the service with the merged include object.
• map models to DTOs.
• project DTOs before returning the response.

Run Locally

Start the example server:

pnpm examples:start

The server listens on http://localhost:3000 by default. Override the port with PORT:

PORT=3001 pnpm examples:start

Local Checks

Build the package first when you want to validate the example against the local source:

pnpm build
pnpm examples:check

Request Example

The books controller supports nested author projections:

GET /api/v1/books?fields=id,title,author{name,books{title}}

For relation loading, the controller derives the include object for author and author.books, passes it to the service, and returns only the selected DTO fields.

Use bracket notation when a request should provide explicit include values:

GET /api/v1/books?fields=id,title,author{name,books{title}}&include[author][include][books]=true