Getting Started

This guide shows how to install @querry-kit/nest-util, register QueryTransformPipe, and use the utility functions directly in application code.

Installation

Install the package from npm:

pnpm add @querry-kit/nest-util

GitHub release tags remain available as a fallback. The main branch contains source only; release tags contain the built dist files required by Node.js.

pnpm add github:querry-kit/nest-util#vX.Y.Z

TypeScript ESM

This package is ESM-first. In TypeScript projects that emit ESM, keep relative local imports explicit with .js extensions.

Register the Query Pipe

Use QueryTransformPipe globally when all controller query parameters should be normalized before they reach route handlers:

import { NestFactory } from '@nestjs/core';
import { QueryTransformPipe } from '@querry-kit/nest-util';
import { AppModule } from './app.module.js';

const app = await NestFactory.create(AppModule);

app.useGlobalPipes(new QueryTransformPipe());

await app.listen(3000);

You can also apply the pipe to a single controller or route when only selected endpoints should normalize queries:

import { Controller, Get, Query, UsePipes } from '@nestjs/common';
import { QueryTransformPipe } from '@querry-kit/nest-util';

@Controller('users')
export class UsersController {
  @Get()
  @UsePipes(new QueryTransformPipe())
  findMany(@Query() query: unknown) {
    return query;
  }
}

Use the Object Utilities Directly

parseObject is useful outside Nest pipes, for example when normalizing test fixtures, adapter inputs, or framework-specific query objects:

import { parseObject } from '@querry-kit/nest-util/object';

const parsed = parseObject({
  page: '1',
  perPage: '25',
  active: 'true',
  'where.profile.name': 'Ada',
});

For detailed parsing rules, continue with Query Transformation.

Map Validation Errors

ValidationUtil maps class-validator errors into an object keyed by property name:

import { ValidationUtil } from '@querry-kit/nest-util';

const errorMap = ValidationUtil.mapValidationErrorsToObject(errors);

The mapped object can be returned from exception filters or normalized for API responses.

Runtime Expectations

• QueryTransformPipe only transforms Nest arguments where metadata.type === 'query'.
• Non-query arguments are returned unchanged.
• Plain query objects are parsed recursively.
• ValidationUtil maps existing class-validator errors; it does not run validation itself.

Minimal Verification

After installation, add a small controller test or pipe unit test:

import { QueryTransformPipe } from '@querry-kit/nest-util';

it('normalizes query parameters', () => {
  const pipe = new QueryTransformPipe();

  expect(pipe.transform({ page: '1' }, { type: 'query' } as never)).toEqual({
    page: 1,
  });
});