Writing custom pipes in NestJS

A wallet top-up sends its amount as the text "1234.50", and the handler needs 123450 paise. Converting it inside every handler that takes money repeats the same code and invites the classic slip: in JavaScript 4.35 * 100 is 434.99999999999994, so Math.floor() loses a paisa.

This lesson writes the conversion once, as a custom pipe that runs before the handler, then decides where other work belongs: in a pipe, a guardA class whose canActivate() method decides, before any pipe runs, whether a request may reach its handler; returning false or throwing refuses the request., an interceptor, middleware or a service. You will write a pipe class, read what Nest tells it about the argument, and turn bad input into a clear 400.

A pipe is a class with one method, transform(value, metadata)

A custom pipe implements PipeTransformPipeTransform: The interface every Nest pipe implements: one method, transform(value, metadata), whose return value replaces the handler's argument and whose thrown exception becomes the response. It may return a promise.: one method, transform(value, metadata), whose return value replaces the argument. ParsePaisePipe accepts rupees as text with at most two decimals and returns whole paise, computed from the digits, so no binary fraction is ever multiplied:

import { type ArgumentMetadata, BadRequestException, Injectable, type PipeTransform } from '@nestjs/common';

// Rupees as text with at most two decimals, "1234.50" or "99": no sign, no digit grouping, no exponent.
const RUPEES = /^(\d{1,7})(?:\.(\d{1,2}))?$/;

// Turns an amount in rupees, sent as text, into a whole number of paise, or answers 400.
@Injectable()
export class ParsePaisePipe implements PipeTransform<unknown, number> {
  transform(value: unknown, metadata: ArgumentMetadata): number {
    console.log(`  transform(${JSON.stringify(value)}, { type: '${metadata.type}', data: '${metadata.data}', metatype: ${metadata.metatype?.name} })`);
    const field = metadata.data ?? 'amount';
    if (value === undefined) throw new BadRequestException(`${field} is missing`);
    if (typeof value !== 'string') throw new BadRequestException(`${field} must be text such as "1234.50", not a ${typeof value}`);
    const match = RUPEES.exec(value);
    if (!match) throw new BadRequestException(`${field} must be rupees with at most two decimals, such as "1234.50"`);
    const [, rupees, fraction = ''] = match;
    return Number(rupees) * 100 + Number(fraction.padEnd(2, '0'));
  }
}

Step through one amount, then run the endpoint with seven bodies:

import { session } from '../session.mjs';

// Builds a wallet top-up endpoint whose amount goes through ParsePaisePipe, then sends it seven bodies.
session(`
npx tsc -p tsconfig.json
node dist/main.js
`);

$ npx tsc -p tsconfig.json
$ node dist/main.js
POST /wallet/top-ups {"amount":"1234.50"}
  transform("1234.50", { type: 'body', data: 'amount', metatype: Number })
  -> 201 {"creditedPaise":123450}
POST /wallet/top-ups {"amount":"99"}
  transform("99", { type: 'body', data: 'amount', metatype: Number })
  -> 201 {"creditedPaise":9900}
POST /wallet/top-ups {"amount":"0.5"}
  transform("0.5", { type: 'body', data: 'amount', metatype: Number })
  -> 201 {"creditedPaise":50}
POST /wallet/top-ups {"amount":"12.345"}
  transform("12.345", { type: 'body', data: 'amount', metatype: Number })
  -> 400 {"message":"amount must be rupees with at most two decimals, such as \"1234.50\"","error":"Bad Request","statusCode":400}
POST /wallet/top-ups {"amount":"1,234.50"}
  transform("1,234.50", { type: 'body', data: 'amount', metatype: Number })
  -> 400 {"message":"amount must be rupees with at most two decimals, such as \"1234.50\"","error":"Bad Request","statusCode":400}
POST /wallet/top-ups {"amount":1234.5}
  transform(1234.5, { type: 'body', data: 'amount', metatype: Number })
  -> 400 {"message":"amount must be text such as \"1234.50\", not a number","error":"Bad Request","statusCode":400}
POST /wallet/top-ups {}
  transform(undefined, { type: 'body', data: 'amount', metatype: Number })
  -> 400 {"message":"amount is missing","error":"Bad Request","statusCode":400}
4.35 * 100 in JavaScript is 434.99999999999994, and Math.floor() of it is 434

The second argument is ArgumentMetadataArgumentMetadata: What Nest passes to a pipe about the argument: type (body, query, param or custom), data (the name given to the decorator, if any), metatype (the declared type of the parameter) and, in Nest 12, schema., and the run printed it for every request: type: 'body' because the value came from @Body(), data: 'amount' because the decorator named one property, and metatype: Number, the handler’s declared type, which is what the pipe must produce. The pipe used data to name the field in its messages. "12.345" and "1,234.50" got 400 with an actionable message, the number 1234.5 got 400 because a JSON number cannot promise two exact decimals, and a missing amount got amount is missing. An exception thrown in a pipe is a response: the handler never ran for those four.

transform() may also return a promise, and Nest waits for it before the next pipe or the handler runs, which is how a pipe can look something up in a database. Bind a pipe by class, @Body('amount', ParsePaisePipe), and Nest builds it and can inject its dependencies; bind an instance, as with new ParseEnumPipe(OrderStatus), when the pipe takes options in its constructor.

A pipe changes one argument, and the other enhancers do the rest

A pipe sees one argument at a time, after Nest has extracted it, and nothing about the user, the route’s metadata or the handler’s result. That decides what belongs in it. Nest runs a request through middleware, then guards, then interceptors, then pipes and the handler, and the response back through the interceptors:

Choose for your own case in the table below; it marks what each answer rules out:

Three more matters have trade-offs of their own. A pipe bound by class can inject a provider, such as a repository that turns a kitchen id into the kitchen itself. Nest 12 changed the types of the built-in pipes, which hand-written pipes that call them must follow. And whatever a pipe throws reaches the client as its answer, so its messages need the care of any response.

Pipes that load data: injection, async lookups and 404s, with a wiring error reproduced Pro: opens with a Pro, Premium or Ultimate pass

Upgrading and hardening hand-written pipes, with the Nest 12 type errors and an error leak reproduced Pro: opens with a Pro, Premium or Ultimate pass

Practise: build a money pipe in two steps

The lab builds the two halves of a production ParsePaisePipe: the function that reads an amount, then the chain that runs a parameter’s pipes the way Nest does. The sample tests of both steps run in your browser.

/**
 * Parses a rupee amount typed by a person into whole paise: "1234.5", "₹1,234.50" and "1,23,456" are accepted;
 * returns null for anything it refuses, so a pipe can answer 400.
 */
export function parseRupeesToPaise(input) {
  // Handles plain amounts only, as the lesson's pipe does: add the rupee sign and both kinds of digit grouping.
  const match = /^(\d{1,9})(?:\.(\d{1,2}))?$/.exec(input);
  if (!match) return null;
  return Number(match[1]) * 100 + Number((match[2] ?? '').padEnd(2, '0'));
}

import { assert, test } from 'mysmartcopilot:test';
import { parseRupeesToPaise } from './rupees.mjs';

test('plain rupees, with and without paise', () => {
  assert.equal(parseRupeesToPaise('1234.5'), 123450);
  assert.equal(parseRupeesToPaise('1234.50'), 123450);
  assert.equal(parseRupeesToPaise('99'), 9900);
  assert.equal(parseRupeesToPaise('0.05'), 5);
});

test('the rupee sign at the start', () => {
  assert.equal(parseRupeesToPaise('₹1,234.50'), 123450);
  assert.equal(parseRupeesToPaise('₹99'), 9900);
});

test('Indian digit grouping', () => {
  assert.equal(parseRupeesToPaise('1,23,456'), 12345600);
  assert.equal(parseRupeesToPaise('12,34,567.89'), 123456789);
});

test('grouping in thousands', () => {
  assert.equal(parseRupeesToPaise('123,456'), 12345600);
  assert.equal(parseRupeesToPaise('1,234,567'), 123456700);
});

test('a comma before two digits could be a decimal point, so it is refused', () => {
  assert.equal(parseRupeesToPaise('12,34'), null);
});

test('three digits after the point are refused', () => {
  assert.equal(parseRupeesToPaise('12.345'), null);
});

test('groups that fit neither system are refused', () => {
  for (const text of ['1,2345', '1,234,56', ',123', '1,,234', '12,34,56']) assert.equal(parseRupeesToPaise(text), null, text);
});

test('signs, exponents, spaces and empty text are refused', () => {
  for (const text of ['-5', '+5', '1e3', '', '₹', ' 12', '12 ', '₹ 12', '1234.', '.5']) assert.equal(parseRupeesToPaise(text), null, JSON.stringify(text));
});

test('values that are not text are refused', () => {
  for (const value of [1234.5, undefined, null, ['12']]) assert.equal(parseRupeesToPaise(value), null, String(value));
});

test('at most nine digits of rupees', () => {
  assert.equal(parseRupeesToPaise('99,99,99,999'), 99999999900);
  assert.equal(parseRupeesToPaise('1,00,00,00,000'), null);
});

/**
 * Runs a parameter's pipes as Nest does: in order, each on the result of the one before, awaiting each, with the same
 * metadata, stopping at the first error. Returns a promise of the final value.
 */
export function runPipes(value, metadata, pipes) {
  let current = value;
  for (const pipe of pipes) {
    // Each pipe should receive the previous result, and a promise should be awaited before the next pipe runs.
    current = pipe.transform(value, metadata);
  }
  return Promise.resolve(current);
}

import { assert, test } from 'mysmartcopilot:test';
import { runPipes } from './run_pipes.mjs';

const meta = { type: 'body', data: 'amount' };

/** A pipe that appends a letter, to see the order. */
const append = (letter) => ({ transform: (v) => `${v}${letter}` });

/** The lesson's two pipes for an amount: a default for a missing value, then rupees to whole paise. */
const defaultZero = { transform: (v) => (v === undefined || v === null ? '0' : v) };
const parsePaise = {
  transform(v, m) {
    const match = /^(\d{1,7})(?:\.(\d{1,2}))?$/.exec(typeof v === 'string' ? v : '');
    if (!match) throw new Error(`${m.data} must be rupees with at most two decimals`);
    return Number(match[1]) * 100 + Number((match[2] ?? '').padEnd(2, '0'));
  },
};

test('no pipes: the value as it was', async () => {
  assert.equal(await runPipes('1234.50', meta, []), '1234.50');
});

test('each pipe receives the result of the one before, in order', async () => {
  assert.equal(await runPipes('', meta, [append('a'), append('b'), append('c')]), 'abc');
});

test('a promise is awaited before the next pipe runs', async () => {
  const slowDouble = { transform: (v) => new Promise((done) => setTimeout(() => done(v * 2), 5)) };
  const addOne = { transform: (v) => v + 1 };
  assert.equal(await runPipes(10, meta, [slowDouble, addOne]), 21);
});

test('every pipe gets the same metadata object', async () => {
  const seen = [];
  const spy = { transform: (v, m) => (seen.push(m), v) };
  await runPipes('x', meta, [spy, spy]);
  assert.equal(seen.length, 2);
  assert.ok(seen[0] === meta && seen[1] === meta, 'the metadata passed on unchanged');
});

test('the money chain of the lesson: a default, then paise', async () => {
  assert.equal(await runPipes(undefined, meta, [defaultZero, parsePaise]), 0);
  assert.equal(await runPipes('12.5', meta, [defaultZero, parsePaise]), 1250);
});

test('a pipe that throws stops the chain and rejects with its error', async () => {
  let later = false;
  const after = { transform: (v) => ((later = true), v) };
  await assert.rejects(runPipes('12.345', meta, [parsePaise, after]), 'amount must be rupees with at most two decimals', 'the error of parsePaise');
  assert.equal(later, false, 'no pipe runs after the one that threw');
});

test('a rejected promise stops the chain as well', async () => {
  let later = false;
  const failing = { transform: () => Promise.reject(new Error('kitchen 99 not found')) };
  const after = { transform: (v) => ((later = true), v) };
  await assert.rejects(runPipes(99, meta, [failing, after]), 'kitchen 99 not found', 'the rejection of the lookup');
  assert.equal(later, false, 'no pipe runs after the rejected one');
});

Then the questions on the pipe contract and on where work belongs:

Interview questions

Key takeaways

• A custom pipe implements transform(value, metadata): its return value replaces the argument, a thrown exception becomes the response, and the method may return a promise that Nest awaits.
• ArgumentMetadata says where the value came from (type), which property the decorator named (data) and the type the handler declared (metatype), which is the type the pipe must produce.
• Pipes convert and check one argument; guards decide access, interceptors wrap the handler, middleware sees the raw request first, and services keep the rules that need data.