Fields Projection

The fields query parameter supports comma-separated field names and nested relation selections.

id,email,profile{firstName,lastName}

Use it when a client should receive only selected DTO fields while the server still validates every requested field against an explicit schema.

Parsing

FieldsParser converts the raw string into a projection tree:

{
  id: true,
  email: true,
  profile: {
    firstName: true,
    lastName: true
  }
}

Whitespace is allowed around tokens. Empty values are treated as no projection. Invalid syntax throws FieldsBadRequestException.

Syntax

The parser accepts a small identifier-based syntax:

Rule	Example
Field names start with A-Z, a-z, or _.	id, _meta
Remaining field name characters may also contain digits.	line1, profile2
Commas separate sibling selections.	id,email
Braces select nested relation fields.	profile{firstName}
Whitespace around tokens is ignored.	id, profile { firstName }

Empty nested selections such as profile{} and unsupported field-name characters are rejected before validation.

Validation

FieldsValidator checks the projection against a FieldSchema.

const schema = {
  id: true,
  email: true,
  profile: relation({
    firstName: true,
    lastName: true,
  }),
};

Scalar fields accept only true. Relation fields accept nested selection objects. Unknown fields and nested selections on scalar fields are rejected.

Includes

Fields.include derives includes for selected relation fields:

Fields.include({ profile: { firstName: true } }, schema);
// { profile: true }

Existing include configuration is preserved. Dotted include keys are normalized through @querry-kit/nest-util.

When generated relation includes are merged into an existing Prisma-style include object, caller-provided include and select configuration stays in place.

Projection

Fields.project applies a validated projection to response DTOs:

Fields.project(userDto, { id: true, profile: { firstName: true } });

Arrays are projected item by item. Primitive values, null, and undefined are returned unchanged.