DEV Community: Hector Angel Gomez Robaina

The Criteria pattern in NestJS: what a client may ask for is a file, not a signature

Hector Angel Gomez Robaina — Fri, 21 Aug 2026 03:10:36 +0000

The Criteria pattern in NestJS

One single way to filter, sort and paginate any list.

Five parameters and a `find()`

The example running through this article is a library catalogue. A book stores this:

// src/book/book.schema.ts
@Schema({ timestamps: true })
export class Book {
  @Prop() title: string;
  @Prop({ type: Types.ObjectId, ref: "Author" }) author: Types.ObjectId;
  @Prop() publishedAt: Date;
  @Prop() copies: number; // copies on the shelf
  @Prop() available: boolean;
  @Prop() acquisitionPrice: number; // what it cost us: internal, never published
}

The author's name is not here: it lives in the authors collection, on the other side of that reference. And the screen consuming the catalogue is a table with a search box, per-column filters and pagination.

The endpoint feeding it is written once and grows by accretion. It starts returning a page with a fixed order, and by the time the table has all its filters it has become this:

// src/book/book.controller.ts
@Controller("books")
export class BookController {
  constructor(
    @InjectModel(Book.name) private readonly model: Model<BookDocument>,
  ) {}

  @Get()
  async getAll(
    @Query("title") title?: string,
    @Query("available") available?: string,
    @Query("minCopies") minCopies?: string,
    @Query("sortBy") sortBy?: string,
    @Query("page") page?: string,
  ) {
    const filter: FilterQuery<BookDocument> = {};

    if (title) {
      filter.title = { $regex: title, $options: "i" };
    }

    if (available) {
      filter.available = available === "true";
    }

    if (minCopies) {
      filter.copies = { $gte: Number(minCopies) };
    }

    const current = Number(page ?? 1);

    const [items, total] = await Promise.all([
      this.model
        .find(filter)
        .sort({ [sortBy ?? "createdAt"]: -1 })
        .skip((current - 1) * 20)
        .limit(20),
      this.model.countDocuments(filter),
    ]);

    return { items: items, total: total, page: current };
  }
}

There are correct decisions inside that method: the total comes out of the same filter as the items, so the pagination cannot contradict itself, and both queries travel in parallel. A list written like this holds years of production without an incident, and its behaviour is not what this article sets out to fix.

What is worth measuring is what ends up written outside the file. The endpoint's signature and the URL needed to call it are, together, a contract:

GET /books?title=dune&available=true&minCopies=3&sortBy=publishedAt&page=2

That contract is declared nowhere and is already in production: the moment somebody shares that URL in a ticket or writes it into an import script, the five names in the query string have consumers outside the repository. And the vocabulary it is written in is not the catalogue's, it is the collection's: sortBy=publishedAt names a document field exactly as the database calls it, minCopies also pins down an operator that does not appear in the name, and whoever reads title=dune cannot tell whether it looks for an exact or a partial match, because that is only written inside the if.

Where this is going

What this article builds is the Criteria pattern: an object describing a list —what is filtered, how it is sorted, which page— travelling from the client to the repository and being translated twice, once at each border. It is worth seeing the result before the analysis, because everything that follows is the justification for this shape and not another.

The same table, against the same endpoint, is requested like this:

GET /books
  ?filters[0][field]=title&filters[0][operator]=CONTAINS&filters[0][value][0]=dune
  &filters[1][field]=authorName&filters[1][operator]=EQUAL&filters[1][value][0]=Herbert
  &order[by]=publishedAt&order[type]=DESC
  &page=2&pageSize=20

The response carries the page and what is needed to draw the paginator:

{ "items": [], "totalItems": 143, "totalPages": 8, "pageSize": 20 }

And the controller is left without a single column name inside it:

// src/book/infrastructure/nest/book.controller.ts
@Get()
async getAll(
  @Query() request: CriteriaRequest,
): Promise<PaginationResponse<BookResponse>> {
  const useCase = new GetAllBooks(this.repository, new BookCriteriaRequestMapper());

  return await useCase.execute({ request: request });
}

With both URLs side by side, four differences show up without reading the server:

The operator is written down. CONTAINS travels in the request, so whoever reads the URL knows dune looks for a partial match. In the previous version that lived inside an if.
The name is not the column's. authorName exists in no document —the author is in another collection— and it is still filtered and sorted by like any other column.
The endpoint's signature does not grow. Adding the copies filter, the date range or the tenth field changes not one line of the controller: it changes one line of an enum.
The format is the same for every list. Authors and loans are requested the same way, so the client writes one serialiser instead of one per screen.

None of that comes free: getting there is four files per entity plus one translator per database engine, and there are projects where it does not pay off. The rest of the article is why this shape, what it costs and when it is not worth it.

Five coupling points, and one of a different kind

The places where the endpoint and whoever calls it are tied together are five, and they are not all of the same kind. The first four are visible by reading the file; the fifth only becomes visible when the second list appears.

1. The operator lives in the body of the method. title is resolved with a $regex and minCopies with a $gte, but neither name says so, which means the filter's behaviour can change without touching the signature: turning that $regex into an exact match breaks no compilation, and the only signal is that responses start bringing back fewer rows.

2. The parameter name is the field name. sortBy=publishedAt works because that string is passed straight to .sort(). Renaming the property in the schema leaves two ways out: breaking URLs that are already circulating, or keeping an alias table from old name to new one inside the controller — which is the very translation map the pattern ends up formalising, written too late and only for the field that moved.

3. The signature grows with fields multiplied by operators. minCopies covers one of the possible comparisons over copies; the maximum is another parameter and the exact range a third. The endpoint does not accumulate one parameter per column, it accumulates one per question somebody wanted to ask a column.

4. What can be filtered is written nowhere: it is the residue of the ifs. To know what the endpoint accepts you have to read the whole method and keep the branches. With sorting there are not even branches to read, because sortBy goes straight into .sort(): any path in the document is a valid order, including those of the fields the list does not return.

5. The format is private to this endpoint. The next list —authors, loans, copies— decides everything again from scratch: whether the page is requested with page or offset, whether ordering is sortBy plus order or a single sort=-publishedAt, whether a boolean travels as true, as 1 or as the mere presence of the parameter. On the client side, every screen writes its own serialiser and none resembles the previous one enough to be shared.

The first four are coupling nuisances: they live inside one file, they are fixed by editing that file, and what they cost to fix does not depend on how long you waited. The fifth is of a different kind. It lives in no file, but in the agreement between whoever writes the endpoint and whoever consumes it, and it does not grow with the number of fields: it grows with the number of lists multiplied by the number of clients.

With a single list, four fixed filters and one screen calling it, none of the five has an observable cost and the method above is the proportionate answer to the problem. They become measurable when three conditions appear, and they tend to appear together: the list stops being one, the client stops being one, and the filters stop being fixed because the user composes them from a table header.

Three costs

1. The URL is a public part of the schema

The names travelling in the query string are the names of the document's fields, and a published URL has no version and no deprecation: it exists as long as somebody keeps it. The day publishedAt becomes firstPublishedAt, neither the compiler nor the tests say anything, and what breaks are links already circulating outside the repository. The cost, however, is not paid on renaming: it is paid in the fact that you do not rename, because since there is no way to know who calls with the old name, the migration gets postponed and the name that no longer describes what it stores stays.

2. The endpoint grows by multiplication, not by addition

The signature accumulates one parameter per question that can be asked of a field, and the useful questions about a date or a number are several; multiply that by the number of lists, because each one repeats the exercise from scratch. The effect is in the direction of the growth: parameters come in but do not go out, because removing minCopies requires proving nobody calls it and that proof cannot be produced against a contract that is not declared anywhere. The method ends up being the sum of every screen that ever called it, including the ones that no longer exist.

3. What can be asked for is written nowhere

sortBy arrives as text and goes straight into .sort(), so the list of fields you can sort by is not decided by the endpoint: it is decided by the schema. And sorting by a field is a way of reading it — with sortBy=acquisitionPrice and a few pages you reconstruct the relative order of the acquisition prices of the entire catalogue, without the response ever returning a single price. The second-order effect is where the control sits: that surface widens by editing the schema, not the controller, so whoever adds the supplier margin tomorrow is widening what the API exposes with a diff that touches none of the files anybody would look in.

The three costs share one root: what a client may ask for does not exist as data anywhere, but scattered across a method signature, the body of a few ifs and the way each screen assembles its URL.

The justification worth discarding

The Criteria pattern is almost always introduced with the same argument: it avoids the explosion of repository methods. In CodelyTV's formulation, which is the reference for this pattern in the Spanish-speaking world, if you have to filter by several fields "we can end up with a repository with one method per field to filter by, plus whatever permutations there may be" — and the criteria solves it while respecting the open/closed principle.

The problem it describes is real and the reasoning is correct. What is worth measuring is its size. A real repository does not accumulate permutations, it accumulates the methods somebody actually needed: findByTitle, findByAuthorAndAvailable, and little more. The growth is not combinatorial but equal to the number of screens, and four or five similar methods in an interface are awkward to read and cheap to fix — they are, exactly, one of the four local and reversible points from the inventory above.

There is also something that argument does not touch. The method explosion is solved entirely inside the backend: a criteria the use case assembles by hand, with new BookCriteria({ filters: [...] }), already removes it, and for that you need neither the DTO, nor validation, nor a list of public fields, nor operators travelling in the URL. An implementation justified only by that stops just short of the half where costs 1 and 3 live, which are the ones that live in no file of the server.

That is why it is worth discarding explicitly rather than merely completing: as long as the method explosion is the reason, the pattern gets implemented up to the edge of the backend and stops there, which is where this article's problem begins. The other argument in circulation —that this way you can change databases— is weaker still here, because the criteria's translator is precisely the cheap part of a migration; the TypeORM section shows it, but as a verifiable consequence and not as a motive.

Note: the portability argument does have a place where it is defended seriously, which is the Repository pattern, and I measured it there in detail: The Repository pattern in NestJS — a collection that happens to live in a database. If that discussion interests you, it is all there; for what follows it is enough to know it is not what pays for the criteria.

The question that takes its place is what is available for the whole contract: not for avoiding repeated methods in an interface, but so that a client knows what it may ask for and the server knows what it accepts. There the ecosystem offers more than is usually acknowledged.

What is already solved

nestjs-paginate is the option that goes furthest out of the box, and that is worth saying without qualification. The catalogue list, in full, on version 15.0.1:

// src/book/book.controller.ts
@Get()
async getAll(@Paginate() query: PaginateQuery): Promise<Paginated<Book>> {
  return paginate(query, this.repository, {
    relations: ["author"],
    sortableColumns: ["title", "publishedAt", "copies"],
    searchableColumns: ["title", "author.name"],
    filterableColumns: {
      available: [FilterOperator.EQ],
      copies: [FilterOperator.GTE, FilterOperator.LTE],
      "author.name": [FilterOperator.ILIKE],
    },
    defaultSortBy: [["publishedAt", "DESC"]],
    defaultLimit: 20,
    maxLimit: 100,
  });
}

GET /books?filter.available=$eq:true&filter.copies=$gte:3&sortBy=publishedAt:DESC&page=2&limit=20

sortableColumns is a required field, not an optional one, and filterableColumns declares which operators each column accepts out of a catalogue of eleven —$eq, $gte, $in, $btw, $ilike, $null, $contains and company— plus the $not suffix and the $all / $any / $none quantifiers. maxLimit sets the page ceiling, searchableColumns gives you free-text search, there is cursor pagination, and a filterExpressionMaxComplexity bounds how many nodes a filter expression may hold so nobody takes the server down with a nested filter=. Notice too that "author.name" works: names can cross a relation, so even the case this article uses as its acid test is covered. Cost 2 disappears —one parameter— and so does cost 3: what is not declared does not get in.

What it does not solve is the vocabulary, and everything else follows from that. The accepted names are of type Column<T>, which is the entity's property path, so publishedAt in the URL is publishedAt in the class and cost 1 remains untouched. And paginate() takes a TypeORM Repository<T> or SelectQueryBuilder<T> and returns TypeORM entities: the contract is excellent and it is inseparable from the ORM, so it does not exist for anyone using Mongoose or Prisma, and a use case cannot express it without importing TypeORM.

GraphQL solves the whole problem by another route — the client declares what it wants and the schema is the contract:

query {
  books(where: { available: true }, orderBy: { publishedAt: DESC }, first: 20) {
    title
    author {
      name
    }
  }
}

The three costs disappear at once. The price is not the library, it is the transport: HTTP caching, authorisation, rate limiting and observability all move somewhere else, and that makes it an architectural decision rather than a layer you add to a list.

Passing the whole req.query to find() solves the endpoint's growth in zero lines:

@Get()
async getAll(@Query() query: FilterQuery<BookDocument>) {
  return this.model.find(query);
}

And it aggravates the other two costs all the way, because the public vocabulary becomes the engine's entire one: ?acquisitionPrice[$gt]=0 filters by a field nobody decided to expose, and the endpoint's surface stops having a limit anyone can state.

Specification and Query Object, the classic patterns, solve the composition of conditions inside the domain — in sketch form, repository.match(new Available().and(new PublishedAfter(2020))). That is a real problem and it is the one the previous section discusses, but neither says anything about HTTP transport or about validating what arrives, which here is half the work.

	Cost 1 · URL coupled to the schema	Cost 2 · endpoint growth	Cost 3 · accidental surface
`nestjs-paginate`	Does not address it: the public name is the entity property	Solved: a single parameter	Solved: `sortableColumns` is required
GraphQL	Solved: the schema is the contract	Solved	Solved
The ORM's `where` into `find()`	Aggravates it	Solved, without a limit	Aggravates it: the surface is the whole engine
Specification / Query Object	Does not address it	Solved inside the backend	Does not address it

Note: the table does not measure ergonomics or time-to-first-endpoint in production, and nestjs-paginate wins both by a distance. Nor does it measure the condition that decides before any other: which persistence engine sits underneath. Checked against nestjs-paginate 15.0.1 and TypeORM 1.1.0 in August 2026; these APIs change across major versions.

The gap is right there. For anyone not on TypeORM, none of that is available, and for anyone on it, the contract ends up expressed in the ORM's vocabulary. What is missing is a description of the list that names neither the column nor the library.

The thesis

Fowler defines the Query Object in one line —"an object that represents a database query"— and develops it as an interpreter: a structure of objects able to turn itself into SQL. Both formulations look towards the engine. This article's looks the other way:

A criteria is not a query travelling in a URL: it is the description of a list —what is filtered, how it is sorted, which page— written in the vocabulary of the domain and translated twice, once at each border.

That sentence determines three pieces, and the three of them take up the rest of the article.

A public field enum per entity. The contract's vocabulary comes to exist as data in a file, instead of being the residue of a few ifs. That is where you decide what a client may name, and that decision stops depending on whatever the schema happens to contain: it is the direct answer to costs 1 and 3.

A domain criteria with no dependencies. The object describing the list imports neither NestJS, nor the driver, nor the ORM. The use case builds it and hands it to the repository without knowing what is behind, which is what allows the same list to be served from Mongo, from Postgres or from an in-memory double during tests.

Two translations that know nothing of each other. The first turns the HTTP request into a criteria and lives in the application layer; the second turns the criteria into the engine's query and lives in infrastructure. Neither knows the other exists, and that is the property the next two sections put to the test: changing engine touches only the second, and changing what a client may ask for touches only the first.

The implementation

The domain criteria

This is the whole file, not an extract:

// src/shared/domain/criteria/criteria.ts
type Props = {
  filters?: CriteriaFilter[];
  order?: CriteriaOrder | null;
  page?: number | null;
  pageSize?: number | null;
  search?: string | null;
};

export abstract class Criteria<T extends string> {
  private _filters: CriteriaFilter[];
  private _order: CriteriaOrder | null;
  private _page: number | null;
  private _pageSize: number | null;
  private _search: string | null;

  constructor({ filters, order, page, pageSize, search }: Props = {}) {
    this._filters = filters ?? [];
    this._order = order ?? null;
    this._page = page ?? null;
    this._pageSize = pageSize ?? null;
    this._search = search ?? null;
  }

  get filters() {
    return this._filters;
  }

  get order() {
    return this._order;
  }

  get page() {
    return this._page;
  }

  get pageSize() {
    return this._pageSize;
  }

  get search() {
    return this._search;
  }

  // Replaces the whole list: this is what the mapper does with the request's filters.
  setFilters(v: CriteriaFilter[]) {
    this._filters = v;
  }

  // Accumulates: what the server imposes is added and the request cannot drop it.
  addFilters(v: CriteriaFilter[]) {
    this._filters = [...this._filters, ...v];
  }

  find(field: T): CriteriaFilter[] {
    return this._filters.filter((f) => f.field === field);
  }
}

What matters about this file is what it does not contain: not a decorator, not a NestJS import, not a database driver one. The property is checkable — it compiles with the project's dependencies uninstalled — and everything else depends on it: that the same object can be built in a use case, travel to a Mongo repository, and also to an in-memory double during tests.

Three details carry more weight than they look. The T extends string parameter is what ties each criteria to its field list, so criteria.find("subtitle") does not compile if that name is not in the entity's enum. find returns a list and not a filter because one field can carry two —publishedAt after one date and before another is an interval— and whoever translates needs both at once. And the split between setFilters and addFilters exists because they are two different situations: the client's filters replace the list, whereas the ones the server imposes accumulate, and with different names the difference is visible in the use case instead of having to be remembered.

The typed filters

A filter is a field, an operator and some values. The base class fixes the first two and leaves the third to each type:

// src/shared/domain/criteria/criteria-filter.ts
export abstract class CriteriaFilter {
  readonly field: string;
  readonly operator: CriteriaFilterOperator;

  constructor({ field, operator }: CriteriaFilterProps) {
    this.field = field;
    this.operator = operator;
  }

  abstract hasValues(): boolean;
}

// src/shared/domain/criteria/criteria-number-filter.ts
export class CriteriaNumberFilter extends CriteriaFilter {
  readonly values: number[];

  constructor(props: CriteriaFilterProps & { values: number[] }) {
    super(props);

    this.values = props.values;
  }

  numbers(): number[] {
    return this.values;
  }

  // A filter with no values must not restrict the query.
  hasValues(): boolean {
    return this.numbers().length > 0;
  }
}

There is a frequent alternative and it is worth saying why it is worse: storing values: unknown[] alongside a discriminant field type: "string" | "number" | "date" | "boolean". With that shape, the translator does a switch on type and the compiler does not check that the values it reads match the branch it is in, so an as number[] assertion is needed in every case. With one class per type, filter instanceof CriteriaNumberFilter narrows the type and filter.numbers() already returns number[]. The difference is charged in the infrastructure translator, which is a long switch over operators and the spot in the pattern where it is easiest to be wrong in silence.

The public field enum

This file is the entire surface of what a client may name:

// src/book/domain/criteria/book-criteria-field.ts
export enum BookCriteriaField {
  ID = "id",
  TITLE = "title",
  AUTHOR_NAME = "authorName",
  PUBLISHED_AT = "publishedAt",
  COPIES = "copies",
  AVAILABLE = "available",
}

// src/book/domain/criteria/book-criteria.ts
export class BookCriteria extends Criteria<BookCriteriaField> {}

acquisitionPrice is not there, and that absence is the whole answer to cost 3: the API's surface is no longer decided by the schema. Whoever adds the supplier margin to the document tomorrow widens nothing, because naming it from a URL would mean editing this file, which is exactly where somebody would look for it in a review.

authorName, on the other hand, is there, and it is not a document field. The enum is the vocabulary of the list, not of the schema — and that is where cost 1 is settled, because the public name stops being tied to the column name and renaming a property becomes an internal change. That authorName lives in another collection is the translator's problem, and the acid test deals with it further down.

The concrete criteria is one line because all of its typing comes from the enum: from here on, any find outside those six names stops compiling.

The request

This is the only file of the pattern carrying decorators, and the concentration is deliberate: it is the border everything you do not control comes through.

// src/shared/application/dto/criteria-request.ts
export class CriteriaFilterRequest {
  @IsString()
  @IsNotEmpty()
  field: string;

  @IsEnum(CriteriaFilterOperator)
  operator: CriteriaFilterOperator;

  // qs returns a string when the query carries `value=x` once, and an array when it
  // carries indexes (`value[0]=x`); normalised so it does not depend on how many
  // values the client happened to send.
  @IsDefined()
  @Transform(({ value }) => (Array.isArray(value) ? value : [value]))
  @IsArray()
  @IsString({ each: true })
  value: string[];
}

export class CriteriaRequest {
  @IsOptional()
  @IsArray()
  @ValidateNested({ each: true })
  @Type(() => CriteriaFilterRequest)
  filters?: CriteriaFilterRequest[];

  @IsOptional()
  @ValidateNested()
  @Type(() => CriteriaOrderRequest)
  order?: CriteriaOrderRequest;

  @IsOptional()
  @Type(() => Number)
  @IsInt()
  @Min(1)
  page?: number;

  @IsOptional()
  @Type(() => Number)
  @IsInt()
  @Min(1)
  pageSize?: number;

  @IsOptional()
  @IsString()
  search?: string;
}

Two settings at application start-up decide whether this works, and both fail silently:

// src/main.ts
const app = await NestFactory.create<NestExpressApplication>(AppModule);

// Express 5 parses the query with `simple`, which is querystring.parse and does not
// nest: `order[by]` would arrive as a key literally called "order[by]".
app.set("query parser", "extended");

// Without `transform`, the DTO's @Type() decorators are not applied and `page` is
// still a string.
app.useGlobalPipes(new ValidationPipe({ transform: true }));

The first one is a change in version 5: in lib/application.js of Express 5.2.1, the default configuration is this.set('query parser', 'simple'), and extended is what plugs in qs. Without it, a filters[0][field]=title does not arrive as a nested object and validation rejects the whole request through no fault of the client.

The request mapper

This is the first of the two translations. It turns the DTO into a criteria, and along the way it makes three decisions:

// src/shared/application/criteria/criteria-request-mapper.ts
export type CriteriaFilterOption<T extends string> = {
  field: T;
  type: CriteriaFilterType;
};

export abstract class CriteriaRequestMapper<T extends string> {
  abstract options(): CriteriaFilterOption<T>[];

  execute({ criteria, request }: Props<T>): Criteria<T> {
    if (request.search !== undefined) {
      criteria.setSearch(this.mapSearch(request.search));
    }

    // Pagination is always set, whether the request carries it or not: a criteria
    // with no pageSize translates into a query with no limit.
    criteria.setPage(this.mapPage(request.page));
    criteria.setPageSize(this.mapPageSize(request.pageSize));

    if (request.order !== undefined) {
      criteria.setOrder(
        new CriteriaOrder({
          orderBy: request.order.by,
          orderType: request.order.type,
        }),
      );
    }

    if (request.filters !== undefined) {
      const options = this.options();
      const result: CriteriaFilter[] = [];

      for (const filter of request.filters) {
        const mapped = this.mapFilter(filter, options);

        if (mapped !== null) {
          result.push(mapped);
        }
      }

      criteria.setFilters(result);
    }

    return criteria;
  }

  // The ceiling is what stops an absurd pageSize from ending up an unbounded find().
  private mapPageSize(value: number | undefined): number {
    if (value === undefined || !Number.isFinite(value)) {
      return DEFAULT_PAGE_SIZE;
    }

    return Math.min(Math.max(Math.trunc(value), 1), MAX_PAGE_SIZE);
  }

  // What is not in options() is not filtered: there is no field to apply it to.
  private mapFilter(
    filter: CriteriaFilterRequest,
    options: CriteriaFilterOption<T>[],
  ): CriteriaFilter | null {
    const option = options.find((o) => o.field === filter.field);

    if (option === undefined) {
      return null;
    }

    const props = { field: option.field, operator: filter.operator };

    switch (option.type) {
      case CriteriaFilterType.STRING:
        return new CriteriaStringFilter({ ...props, values: filter.value });

      case CriteriaFilterType.NUMBER:
        return new CriteriaNumberFilter({
          ...props,
          values: this.mapNumbers(filter.value),
        });

      // ...dates and booleans, the same way
    }
  }
}

And the entity's one declares the list, which is the only part that has to be written per list:

// src/book/application/criteria/book-criteria-request-mapper.ts
export class BookCriteriaRequestMapper extends CriteriaRequestMapper<BookCriteriaField> {
  options(): CriteriaFilterOption<BookCriteriaField>[] {
    return [
      { field: BookCriteriaField.ID, type: CriteriaFilterType.STRING },
      { field: BookCriteriaField.TITLE, type: CriteriaFilterType.STRING },
      { field: BookCriteriaField.AUTHOR_NAME, type: CriteriaFilterType.STRING },
      { field: BookCriteriaField.PUBLISHED_AT, type: CriteriaFilterType.DATE },
      { field: BookCriteriaField.COPIES, type: CriteriaFilterType.NUMBER },
      { field: BookCriteriaField.AVAILABLE, type: CriteriaFilterType.BOOLEAN },
    ];
  }
}

The first decision is that the type declared in options() is what converts the text. A query string has no types, so the "3" of copies becomes the number 3 here, once, and not in every engine translator on its own. The second is the page ceiling: always setting page and pageSize, with MAX_PAGE_SIZE as the roof, is what stops a client from turning a list into a dump of the collection.

The third is worth stating with its cost. A filter over an undeclared field is dropped silently, it does not return a 400, and that means a typo on the client produces the unfiltered list instead of a visible error — which is worse to debug. The reason for choosing it that way is that a URL saved months ago keeps returning something sensible when a field stops being filterable, instead of breaking. nestjs-paginate takes the opposite decision and offers throwOnInvalidFilter; both are defensible, and what is not defensible is not having chosen.

Note: the compiler does not check that options() covers the whole enum. Declaring it as a Record<BookCriteriaField, CriteriaFilterType> instead of a list would enforce that, at the price of losing the table shape. As it stands, an enum field left without a type is an oversight you only notice by filtering.

Here is also the cost of the pattern, in the same place as the benefit: per list you have to write four files —the enum, the one-line criteria, the mapper with its options() and the infrastructure map that appears further down— where there used to be five @Query(). What you get in exchange is that those four are read in a minute and tell the whole truth about what the endpoint accepts.

The use case and the port

The domain repository exposes a single method for listing:

// src/book/domain/repository/book.repository.ts
export interface BookRepository {
  pagination(criteria: BookCriteria): Promise<PaginationRepositoryResult<Book>>;
}

// src/book/application/use-cases/get-all-books.ts
export class GetAllBooks {
  constructor(
    private readonly repository: BookRepository,
    private readonly criteriaMapper: BookCriteriaRequestMapper,
  ) {}

  async execute({ request }: Props): Promise<PaginationResponse<BookResponse>> {
    const criteria = this.criteriaMapper.execute({
      // the default order is the most recently published; if the request carries
      // `order`, the mapper overrides it
      criteria: new BookCriteria({
        order: new CriteriaOrder({
          orderBy: BookCriteriaField.PUBLISHED_AT,
          orderType: CriteriaOrderType.DESC,
        }),
      }),
      request: request,
    });

    const result = await this.repository.pagination(criteria);

    return PaginationResponseMapper.execute({
      result: {
        ...result,
        items: result.items.map((b) => BookMapper.execute(b)),
      },
    });
  }
}

The criteria is built in the use case and not in the controller because the default order is a product decision —what the person opening the screen sees first— and not a transport one. The mapper receives it already built and only overrides what the request brings.

That split is also what makes it safe to impose conditions from the server. If the public list must only show available copies, the filter is added after the mapper:

criteria.addFilters([
  new CriteriaBooleanFilter({
    field: BookCriteriaField.AVAILABLE,
    operator: CriteriaFilterOperator.EQUAL,
    value: true,
  }),
]);

With setFilters in that position, a client sending its own filters would erase the restriction and the failure would throw nothing: it would be extra rows in the response. That is exactly why the two operations have different names.

The translation to Mongo

The second translation lives in infrastructure and starts with a map:

// src/book/infrastructure/mongo/book-mongo-repository.ts
private readonly criteriaFields: MongoCriteriaField<BookCriteriaField>[] = [
  { field: BookCriteriaField.ID, mongo: "_id", canSearch: false },
  { field: BookCriteriaField.TITLE, mongo: "title", canSearch: true },
  { field: BookCriteriaField.AUTHOR_NAME, mongo: "author.name", canSearch: true },
  { field: BookCriteriaField.PUBLISHED_AT, mongo: "publishedAt", canSearch: false },
  { field: BookCriteriaField.COPIES, mongo: "copies", canSearch: false },
  { field: BookCriteriaField.AVAILABLE, mongo: "available", canSearch: false },
];

That map is the alias table point 2 of the inventory described as the patch written too late and only for the field that moved. Here it exists from the start and covers every field, so id → _id stops being a special case and becomes one more row. canSearch settles the other question: what free-text search looks at. Only the title and the author, which are the two things the table shows — searching by a field you cannot see leaves rows without an apparent explanation.

The query builder walks that map:

// src/shared/infrastructure/mongo/mongo-criteria-builder.ts
execute({ criteria, fields }: Props<T>): CriteriaResult {
  const result: CriteriaResult = { filter: {}, order: null, skip: null, limit: null };

  // Each field can contribute several fragments —one filter per operator— so they
  // are flattened: `$and` is a list of conditions, not a list of lists.
  const fragments = fields.flatMap((f) =>
    this.filterMapper.execute({ name: f.mongo, filters: criteria.find(f.field) }),
  );

  if (fragments.length > 0) {
    result.filter.$and = fragments;
  }

  if (criteria.search !== null) {
    const value = criteria.search;

    const search = fields
      .filter((f) => f.canSearch)
      // the text comes from a search box and `$regex` interprets it: escape it
      .map((f) => ({ [f.mongo]: { $regex: escape(value), $options: "i" } }));

    if (search.length > 0) {
      result.filter.$or = search;
    }
  }

  const order = criteria.order;

  if (order !== null && order.hasOrder()) {
    // sorting resolves against the same map as the filters: you cannot sort by a
    // field that is not in it
    const found = fields.find((f) => f.field === order.orderBy);

    if (found) {
      const direction = order.orderType === CriteriaOrderType.ASC ? 1 : -1;

      result.order = { [found.mongo]: direction };
    }
  }

  if (criteria.pageSize !== null) {
    const page = criteria.page ?? 1;

    result.skip = (page - 1) * criteria.pageSize;
    result.limit = criteria.pageSize;
  }

  return result;
}

That sorting resolves against the same map closes cost 3 from the other end: the enum controls what can be named on the way in, and the map controls what exists on the way out. Sorting by acquisitionPrice would require it to be in both files.

The operators are translated separately, one method per filter type:

// src/shared/infrastructure/mongo/mongo-criteria-filter-mapper.ts
private mapNumber(name: string, filter: CriteriaNumberFilter): FilterQuery<unknown> | null {
  const values = filter.numbers();
  const [first] = values;
  const single = values.length === 1;

  switch (filter.operator) {
    case CriteriaFilterOperator.EQUAL:
      return { [name]: single ? first : { $in: values } };

    case CriteriaFilterOperator.NOT_EQUAL:
      return { [name]: single ? { $ne: first } : { $nin: values } };

    // Comparison operators are binary: with several values only the first one
    // means anything.
    case CriteriaFilterOperator.GTE:
      return { [name]: { $gte: first } };

    default:
      return null;
  }
}

The default returning null is what makes an operator that is meaningless for the type —CONTAINS over a boolean— not filter at all instead of breaking the query. And it is worth looking at what this file returns: fragments and loose values, not an assembled query. The builder hands over filter, order, skip and limit separately, and who uses them and how is the repository's decision. That choice looks like a matter of style and it is the one that decides whether the pattern survives the acid test.

The page and the total come out of the same filter

async pagination(criteria: BookCriteria): Promise<PaginationRepositoryResult<Book>> {
  const result = this.criteriaBuilder.execute({
    criteria: criteria,
    fields: this.criteriaFields,
  });

  const query = this.model.find(result.filter);

  if (result.order !== null) {
    query.sort(result.order);
  }

  if (result.skip !== null) {
    query.skip(result.skip);
  }

  if (result.limit !== null) {
    query.limit(result.limit);
  }

  // Both queries come out of the same filter and travel in parallel; the count
  // carries no skip or limit, because those bound the page and not the total.
  const [list, count] = await Promise.all([
    query,
    this.model.countDocuments(result.filter),
  ]);

  return {
    items: list.map((i) => BookMongoMapper.execute(i)),
    count: count,
    pageSize: criteria.pageSize,
  };
}

It is the only decision from the original list the pattern keeps as it was, and it is worth saying why it matters: if the count were built on its own, the total and the page could answer to different filters and the pagination would lie without failing. The symptom is an empty last page, or a result count that does not match what you see, and neither of those shows up in a log.

Point by point

Of the five in the inventory, four are settled. The operator no longer lives in the body of the method: it travels explicitly in the URL and an @IsEnum validates it. The public name stopped being the column name, which is now a cell in the infrastructure map. The endpoint's signature is @Query() request: CriteriaRequest and it does not change when a filter is added, so the growth by multiplication disappears. And what can be filtered and sorted is written in two files that are read in a minute, instead of being inferred from a few branches. The fifth —the format shared across lists and clients— is settled as soon as there is a second list, because of everything written in this section only the catalogue's four files are its own: the rest is already in place.

There is one row of the map still lying. authorName points at author.name, and a books document has no author.name property: it stores a reference. With the find() above, that filter does not fail — it simply finds nothing, which is the worse of the two options.

The acid test: the field that does not live in the collection

The table shows the author's name in a column, so it has to be filterable and sortable just like the title. The data is in authors, on the other side of a reference, and the list is paginated: the page and the total have to come out of the same set of rows.

The way out people try first is populate, and it fails in a way worth looking at closely:

this.model
  .find(result.filter)
  .populate({ path: "author", match: { name: "Herbert" } });

populate solves reading, not filtering. The match applies to the populated document, not to the book, so books by other authors keep coming back — with author: null instead of disappearing. countDocuments counts those too, and the result is a table with holes and a total that does not correspond to what is shown.

The second way out does filter, and it is the one that installs the real problem:

const filters = criteria.find(BookCriteriaField.AUTHOR_NAME);

if (filters.length > 0) {
  const ids = await this.authorModel.find({ name: /* ... */ }).distinct("_id");

  result.filter.author = { $in: ids };
}

It works, and in exchange the repository goes back to having a branch per special field. It still cannot sort by the author's name, because $sort operates over the books collection and there is no name there. And the knowledge that two collections exist, which the pattern had shown out the door, comes back in through an if — with the aggravating factor that every derived field added later will bring its own.

The good way out depends on a decision already made: the builder does not return a query, it returns filter, order, skip and limit separately. Who uses them and in what order is the repository's business:

// src/book/infrastructure/mongo/book-mongo-repository.ts
async pagination(criteria: BookCriteria): Promise<PaginationRepositoryResult<Book>> {
  const result = this.criteriaBuilder.execute({
    criteria: criteria,
    fields: this.criteriaFields,
  });

  // The author travels on every row, so the lookup goes BEFORE the match: that is
  // the only way to filter and sort by their name like any other column.
  //
  // The $unwind does NOT preserve empties: a book with no author is not a row with
  // a hole, it is a broken reference. It does not show up here.
  const join: PipelineStage[] = [
    {
      $lookup: {
        from: this.authorModel.collection.name,
        localField: "author",
        foreignField: "_id",
        as: "author",
      },
    },
    { $unwind: "$author" },
    { $match: result.filter },
  ];

  const page: PipelineStage[] = [...join];

  if (result.order !== null) {
    page.push({ $sort: result.order });
  }

  if (result.skip !== null) {
    page.push({ $skip: result.skip });
  }

  if (result.limit !== null) {
    page.push({ $limit: result.limit });
  }

  const [list, counted] = await Promise.all([
    this.model.aggregate<MongoBook>(page),
    this.model.aggregate<{ count: number }>([...join, { $count: "count" }]),
  ]);

  return {
    items: list.map((i) => BookMongoMapper.execute(i)),
    count: counted[0]?.count ?? 0,
    pageSize: criteria.pageSize,
  };
}

The $lookup goes before the $match because author.name has to exist in the document by the time the filter is evaluated, and that ordering of stages is exactly what a builder returning an assembled query could not decide. It would have to know the collections in order to place the $lookup —and then the translator would know about relations, which is the contamination we were avoiding— or it would have to be bypassed for this field, which is going back to the if. Returning pieces was not a style preference: it was what left this decision to whoever does know the engine.

The $unwind without preserveNullAndEmptyArrays is the other decision, and it is a business one: a book whose author no longer exists does not appear in the catalogue. If the business said otherwise, you change that stage and nothing else.

What this section had to demonstrate is what did not change. authorName filters and sorts like any other column, and getting there touched neither the enum, nor the criteria, nor the DTO, nor the request mapper, nor the use case, nor the URL the client writes. The find became an aggregate inside one infrastructure file, and the contract never noticed — which is the property the thesis promised and the one that decides whether the pattern holds up by the third list. The row of the map that used to find nothing now tells the truth, and getting there it never stopped being a row.

The same criteria against TypeORM

Everything so far is written against Mongo, and the only piece that knows there is a Mongo underneath is the builder. Changing engine means writing another one:

// src/shared/infrastructure/typeorm/typeorm-criteria-builder.ts
export type TypeOrmCriteriaField<T extends string> = {
  field: T;
  column: string;
  canSearch: boolean;
};

export class TypeOrmCriteriaBuilder<T extends string, E> {
  execute({ criteria, fields }: Props<T>): TypeOrmCriteriaResult<E> {
    const where: FindOptionsWhere<E> = {};

    for (const f of fields) {
      const operators = criteria
        .find(f.field)
        .filter((filter) => filter.hasValues())
        .map((filter) => this.operatorMapper.execute(filter));

      if (operators.length === 0) {
        continue;
      }

      // Two filters over the same field are an interval, and TypeORM combines them
      // with And(): the equivalent of the two `$and` fragments in Mongo.
      const condition =
        operators.length === 1 ? operators[0] : And(...operators);

      // `author.name` is nested as `{ author: { name: ... } }`: TypeORM does not
      // take a dotted path as a key, so the column is split on the dot.
      this.assign(where, f.column.split("."), condition);
    }

    const pageSize = criteria.pageSize;

    return {
      where: where,
      order: this.mapOrder(criteria, fields),
      skip:
        pageSize === null ? undefined : ((criteria.page ?? 1) - 1) * pageSize,
      take: pageSize ?? undefined,
    };
  }
}

The operator translator is the same switch with a different vocabulary:

private map(filter: CriteriaNumberFilter): FindOperator<number> | null {
  const values = filter.numbers();
  const [first] = values;
  const single = values.length === 1;

  switch (filter.operator) {
    case CriteriaFilterOperator.EQUAL:
      return single ? Equal(first) : In(values);

    case CriteriaFilterOperator.NOT_EQUAL:
      return single ? Not(Equal(first)) : Not(In(values));

    case CriteriaFilterOperator.GTE:
      return MoreThanOrEqual(first);

    case CriteriaFilterOperator.LTE:
      return LessThanOrEqual(first);

    default:
      return null;
  }
}

And the repository ends up shorter than its Mongo twin, because findAndCount returns the page and the total in a single call and against the same where — the rule that in Mongo had to be held up by hand is imposed here by the method's signature:

async pagination(criteria: BookCriteria): Promise<PaginationRepositoryResult<Book>> {
  const result = this.criteriaBuilder.execute({
    criteria: criteria,
    fields: this.criteriaFields,
  });

  const [list, count] = await this.repository.findAndCount({
    relations: { author: true },
    where: result.where,
    order: result.order,
    skip: result.skip,
    take: result.take,
  });

  return {
    items: list.map((i) => BookTypeOrmMapper.execute(i)),
    count: count,
    pageSize: criteria.pageSize,
  };
}

The field that does not live in the table —the one that cost a whole section in Mongo— is here the same map row with a dot, authorName → "author.name", and the JOIN is put in by the ORM when it sees the relation in the where. When the query needs more control, the alternative is to push the same pieces onto a SelectQueryBuilder with an explicit leftJoin, which is the literal equivalent of the $lookup; what does not change in either case is where the pieces come from.

Note: ILike does not mean the same thing on every engine. In TypeORM 1.1.0 the condition is emitted as native ILIKE on PostgreSQL and CockroachDB, and on any other driver it is translated to UPPER(column) LIKE UPPER(parameter). It behaves the same and performs differently: the second form does not take advantage of an index on the column, you need a functional one on the expression. It is the kind of difference the criteria cannot hide, because it is not about vocabulary but about the engine.

With Prisma the exercise is the same with a third vocabulary: the builder would return where, orderBy, skip and take, and the repository would pass them to findMany alongside a count with the same where.

What has to be written to port a whole list, then, is one builder and one field map; everything else is the same pieces as before, untouched. This is what the section on justifications promised to show as a consequence and not as a motive — portability exists and is checkable, but it is still not the reason you pay for the pattern, because changing database engine is rare and having three lists and two clients is normal.

The other end, briefly

The client builds the same object and hands it over as the request's parameters:

// src/modules/criteria/criteria-request.ts
params(): CriteriaRequestDTO {
  const result: CriteriaRequestDTO = {};

  // A filter with no values restricts nothing: it does not travel.
  const filters = this.filters.filter((f) => f.hasValues());

  if (filters.length > 0) {
    result.filters = filters.map((f) => f.dto());
  }

  if (this.order !== undefined && this.order.hasOrder()) {
    result.order = this.order.dto();
  }

  // An empty search box is not a search for "".
  if (this.search !== undefined && this.search.trim() !== "") {
    result.search = this.search;
  }

  return result;
}

And the request is an ordinary call, with nothing around it:

import axios from "axios";

const { data } = await axios.get<PaginationResponse<BookResponse>>("/books", {
  params: criteria.params(),
  // without this, cancelling a search while typing is decorative
  signal: controller?.signal,
});

That params is what produces the URL from the beginning of the article, brackets and all: nobody writes it by hand. There is no custom serialiser on either side, because axios already writes nested objects in bracket notation and qs reconstructs them on the other end, which is exactly what the extended query parser from start-up enables. The two rules in the previous snippet exist because they affect the URL and not the server: what does not restrict does not travel, and a URL without noise is the difference between being able to share it and not.

It is worth saying where the type safety ends. The enum is the entire surface of what a client may name, but that guarantee lives on the server: what travels in the URL is text, and on the client field is a string again. That both lists say the same thing is a team convention, not a contract anybody checks — and when a field stops being filterable, the symptom is the one already described: the list arrives unfiltered. Closing it completely requires generating the names from a shared source, or publishing the enum in a shared package, and both tie the client's deployment to the server's.

Note: how a table keeps that object in sync with the browser URL, with the column state and with the cancellation of in-flight requests is material for an article of its own.

Two honest caveats, and what this is not

The pattern makes exposing a filter cheap, not serving it. Adding a filterable field costs one line in the enum and one in the map, and that ease is precisely the risk: six filterable fields in any combination are far more distinct queries than the team is ever going to look at in an execution plan. No index is inferred from the criteria, so it is worth deciding which combinations to offer knowing which ones are indexed, instead of finding out when the table grows.

Pagination by skip degrades with the offset. The engine walks what it skips, so page 500 costs more than page 2. With the MAX_PAGE_SIZE ceiling and admin-panel lists it is not observable, and in a long feed the right answer is a cursor — which the pattern accommodates without changing shape. The criteria would carry a cursor instead of a page, the translator would turn it into one more condition over the last item seen, and the enum, the filters and the two translations stay where they are. What does change is a restriction in the contract: the order has to include a unique column as a tie-breaker, so you can no longer sort by any field of the enum.

And it is worth saying what this is not: a query engine. There is no OR between different filters, no groups, no parentheses — every filter is combined with AND and the OR is reserved for free-text search. Anyone who needs to compose expressions needs GraphQL or a language of their own, and it is better to know that before writing the first file than after the third list.

Who this is for, and who it is not for

Starting with the no: a backend with one list, three or four fixed filters and a single screen consuming it. There this is some fifteen shared files plus four per list to replace five @Query() that work, and none of the three costs has an observable symptom yet. The right answer in that project is the simple one, and adopting the pattern up front is paying for a problem that may never arrive.

Four conditions flip the balance, and they rarely turn up alone: three or more paginated lists; more than one client consuming them —an internal panel, an app, somebody integrating over the API—; filters the user composes from a table header instead of picking off a fixed list; and lists that get shared by URL. With two of them present, the cost is amortised by the second list, because the fifteen shared files are written once and from then on each list is four, one of which is a single line.

The practical rule fits in one line: if what a client may ask for still fits in a method signature, leave it there; the moment it stops fitting, the place where that list lives is a file, not a method.

The code

The runnable project is at hgomezrobaina/nestjs-criteria-pattern, with the library catalogue running on Mongo: docker compose up -d && npm install && npm run seed && npm run dev.

What is worth looking at is not that it starts, but its suite: 26 tests in 19 milliseconds, with no database. Inside it is checked what this article claims — that a filter over an undeclared field is dropped, that pageSize has a ceiling, that a filter imposed by the server survives a filters sent by the client, that id is translated to _id and authorName to author.name, that the search term is escaped before it reaches a $regex, and that the same criteria produces TypeORM's nested where and Mongo's pieces. None of those claims needs a container to be verified, because none of them is about the database: they are about what the contract decides before reaching it.

Let's talk

Questions, feedback or a different take? I would love to read you. You can find me here:

GitHub — hgomezrobaina
LinkedIn — Héctor Gómez Robaina
X — @hgomezrobaina

El patrón Criteria en NestJS: lo que un cliente puede pedir es un archivo, no una firma

Hector Angel Gomez Robaina — Fri, 21 Aug 2026 02:56:35 +0000

Cinco parámetros y un `find()`

El ejemplo de todo el artículo es el catálogo de una biblioteca. Un libro guarda esto:

// src/book/book.schema.ts
@Schema({ timestamps: true })
export class Book {
  @Prop() title: string;
  @Prop({ type: Types.ObjectId, ref: "Author" }) author: Types.ObjectId;
  @Prop() publishedAt: Date;
  @Prop() copies: number; // ejemplares en la estantería
  @Prop() available: boolean;
  @Prop() acquisitionPrice: number; // lo que costó adquirirlo: interno, no se publica
}

El nombre del autor no está aquí: vive en la colección authors, al otro lado de esa referencia. Y la pantalla que consume el catálogo es una tabla con buscador, filtros por columna y paginación.

El endpoint que la alimenta se escribe una vez y crece por acumulación. Empieza devolviendo una página con un orden fijo, y para cuando la tabla tiene todos sus filtros ha llegado a esto:

// src/book/book.controller.ts
@Controller("books")
export class BookController {
  constructor(
    @InjectModel(Book.name) private readonly model: Model<BookDocument>,
  ) {}

  @Get()
  async getAll(
    @Query("title") title?: string,
    @Query("available") available?: string,
    @Query("minCopies") minCopies?: string,
    @Query("sortBy") sortBy?: string,
    @Query("page") page?: string,
  ) {
    const filter: FilterQuery<BookDocument> = {};

    if (title) {
      filter.title = { $regex: title, $options: "i" };
    }

    if (available) {
      filter.available = available === "true";
    }

    if (minCopies) {
      filter.copies = { $gte: Number(minCopies) };
    }

    const current = Number(page ?? 1);

    const [items, total] = await Promise.all([
      this.model
        .find(filter)
        .sort({ [sortBy ?? "createdAt"]: -1 })
        .skip((current - 1) * 20)
        .limit(20),
      this.model.countDocuments(filter),
    ]);

    return { items: items, total: total, page: current };
  }
}

El método tiene decisiones correctas dentro: el total sale del mismo filtro que los elementos, así que la paginación no puede contradecirse, y las dos consultas viajan en paralelo. Un listado escrito así sostiene años de producción sin dar un incidente, y su comportamiento no es lo que este artículo se propone corregir.

Lo que conviene medir es lo que queda escrito fuera del archivo. La firma del endpoint y la URL que hace falta para llamarlo son, juntas, un contrato:

GET /books?title=dune&available=true&minCopies=3&sortBy=publishedAt&page=2

Ese contrato no está declarado en ningún sitio y ya está en producción: en cuanto alguien comparte esa URL en un ticket o la deja escrita en un script de importación, los cinco nombres de la query string tienen consumidores fuera del repositorio. Y el vocabulario en el que está redactado no es el del catálogo, es el de la colección: sortBy=publishedAt nombra un campo del documento tal como se llama en la base de datos, minCopies fija además un operador que no aparece en el nombre, y quien lee title=dune no puede saber si busca una coincidencia exacta o parcial, porque eso solo está escrito dentro del if.

Adónde va esto

Lo que este artículo construye es el patrón Criteria: un objeto que describe un listado —qué se filtra, cómo se ordena, qué página— y que viaja del cliente al repositorio traduciéndose dos veces, una en cada frontera. Conviene ver el resultado antes que el análisis, porque todo lo que viene después es la justificación de esta forma y no de otra.

La misma tabla, contra el mismo endpoint, se pide así:

GET /books
  ?filters[0][field]=title&filters[0][operator]=CONTAINS&filters[0][value][0]=dune
  &filters[1][field]=authorName&filters[1][operator]=EQUAL&filters[1][value][0]=Herbert
  &order[by]=publishedAt&order[type]=DESC
  &page=2&pageSize=20

La respuesta trae la página y lo que hace falta para dibujar el paginador:

{ "items": [], "totalItems": 143, "totalPages": 8, "pageSize": 20 }

Y el controlador se queda sin un solo nombre de columna dentro:

// src/book/infrastructure/nest/book.controller.ts
@Get()
async getAll(
  @Query() request: CriteriaRequest,
): Promise<PaginationResponse<BookResponse>> {
  const useCase = new GetAllBooks(this.repository, new BookCriteriaRequestMapper());

  return await useCase.execute({ request: request });
}

Puestas las dos URL una al lado de la otra, cuatro diferencias se ven sin leer el servidor:

El operador está escrito. CONTAINS viaja en la petición, así que quien lee la URL sabe que dune busca una coincidencia parcial. En la versión anterior eso solo estaba dentro de un if.
El nombre no es el de la columna. authorName no existe en ningún documento —el autor está en otra colección— y aun así se filtra y se ordena por él como por cualquier otra columna.
La firma del endpoint no crece. Añadir el filtro por ejemplares, el rango de fechas o el décimo campo no cambia ni una línea del controlador: cambia una línea de un enum.
El formato es el mismo para todos los listados. El de autores y el de préstamos se piden igual, así que el cliente escribe un serializador y no uno por pantalla.

Nada de eso sale gratis: llegar ahí son cuatro archivos por entidad y un traductor por motor de base de datos, y hay proyectos donde no compensa. El resto del artículo es por qué esa forma, qué cuesta y cuándo no vale la pena.

Cinco puntos, y uno de otra naturaleza

Los sitios donde el endpoint y quien lo llama quedan atados son cinco, y no son todos del mismo tipo. Los cuatro primeros se ven leyendo el archivo; el quinto solo se ve cuando aparece el segundo listado.

1. El operador vive en el cuerpo del método. title se resuelve con un $regex y minCopies con un $gte, pero ninguno de los dos nombres lo dice, así que el comportamiento del filtro se puede cambiar sin tocar la firma: convertir ese $regex en una coincidencia exacta no rompe ninguna compilación y la única señal es que las respuestas empiezan a traer menos filas.

2. El nombre del parámetro es el nombre del campo. sortBy=publishedAt funciona porque ese string se pasa tal cual a .sort(). Renombrar la propiedad en el esquema deja dos salidas: romper las URL que ya circulan, o mantener en el controlador una tabla de alias del nombre viejo al nuevo — que es el mapa de traducción que el patrón acaba formalizando, escrito a destiempo y solo para el campo que se movió.

3. La firma crece con los campos multiplicados por los operadores. minCopies cubre una de las comparaciones posibles sobre copies; el máximo es otro parámetro y el rango exacto un tercero. El endpoint no acumula un parámetro por columna, acumula uno por cada pregunta que alguien quiso hacerle a una columna.

4. Lo que se puede filtrar no está escrito en ningún sitio: es el residuo de los if. Para saber qué acepta el endpoint hay que leer el método entero y quedarse con las ramas. Con el orden no hay ni ramas que leer, porque sortBy entra directo en .sort(): cualquier ruta del documento es un orden válido, incluidas las de los campos que el listado no devuelve.

5. El formato es privado de este endpoint. El siguiente listado —autores, préstamos, ejemplares— vuelve a decidirlo todo desde cero: si la página se pide con page o con offset, si el orden es sortBy más order o un único sort=-publishedAt, si un booleano viaja como true, como 1 o como la simple presencia del parámetro. Del lado del cliente, cada pantalla escribe su propio serializador y ninguno se parece al anterior lo bastante como para compartirlo.

Los cuatro primeros son molestias de acoplamiento: viven dentro de un archivo, se corrigen editando ese archivo, y lo que cuesta corregirlas no depende de cuánto se haya tardado. El quinto es de otra naturaleza. No vive en ningún archivo, sino en el acuerdo entre quien escribe el endpoint y quien lo consume, y no crece con el número de campos: crece con el producto del número de listados por el número de clientes.

Con un solo listado, cuatro filtros fijos y una única pantalla llamándolo, ninguno de los cinco tiene coste observable y el método de arriba es la respuesta proporcionada al problema. Se vuelven medibles cuando aparecen tres condiciones, que suelen aparecer juntas: el listado deja de ser uno, el cliente deja de ser uno, y los filtros dejan de ser fijos porque quien los compone es el usuario desde la cabecera de una tabla.

Tres costes

1. La URL es una parte pública del esquema

Los nombres que viajan en la query string son los nombres de los campos del documento, y una URL publicada no tiene versión ni deprecación: existe mientras alguien la conserve. El día que publishedAt pasa a firstPublishedAt, ni el compilador ni los tests dicen nada, y lo que se rompe son enlaces que ya circulan fuera del repositorio. El coste, sin embargo, no se paga al renombrar: se paga en que no se renombra, porque como no hay forma de saber quién llama con el nombre viejo, la migración se pospone y el nombre que ya no describe lo que guarda se queda.

2. El endpoint crece multiplicando, no sumando

La firma acumula un parámetro por cada pregunta que se le puede hacer a un campo, y las preguntas útiles sobre una fecha o un número son varias; a eso se le multiplica el número de listados, porque cada uno repite la operación desde cero. El efecto está en la dirección del crecimiento: los parámetros entran pero no salen, porque retirar minCopies exige demostrar que nadie lo llama y esa demostración no se puede hacer contra un contrato que no está declarado. El método acaba siendo la suma de todas las pantallas que alguna vez lo llamaron, incluidas las que ya no existen.

3. Lo que se puede pedir no está escrito en ninguna parte

sortBy llega como texto y entra directo en .sort(), así que la lista de campos por los que se puede ordenar no la decide el endpoint: la decide el esquema. Y ordenar por un campo es una forma de leerlo — con sortBy=acquisitionPrice y unas cuantas páginas se reconstruye el orden relativo de los precios de adquisición del catálogo entero, sin que la respuesta haya devuelto ni un solo precio. El efecto de segundo orden es dónde queda el control: esa superficie se amplía editando el esquema, no el controlador, así que quien añada mañana el margen del proveedor está ampliando lo que la API expone con un diff que no toca ninguno de los archivos donde alguien lo buscaría.

Los tres costes tienen la misma raíz: lo que el cliente puede pedir no existe como dato en ningún sitio, sino repartido entre la firma de un método, el cuerpo de unos if y la forma en que cada pantalla arma su URL.

La justificación que conviene descartar

El patrón Criteria casi siempre se presenta con el mismo argumento: evita la explosión de métodos del repositorio. En la formulación de CodelyTV, que es la referencia del patrón en castellano, si hay que filtrar por varios campos "podemos acabar con un repository con un método por cada campo a filtrar sumado a las permutaciones que puedan haber", y el criteria lo resuelve respetando el principio abierto/cerrado.

El problema que describe existe y el razonamiento es correcto. Lo que conviene medir es su tamaño. Un repositorio real no acumula las permutaciones, acumula los métodos que alguien llegó a necesitar: findByTitle, findByAuthorAndAvailable, y poco más. El crecimiento no es combinatorio sino igual al número de pantallas, y cuatro o cinco métodos parecidos en una interfaz son incómodos de leer y baratos de corregir — son, exactamente, uno de los cuatro puntos locales y reversibles de la clasificación de arriba.

Hay además algo que ese argumento no toca. La explosión de métodos se resuelve entera dentro del backend: un criteria que el caso de uso monta a mano, con new BookCriteria({ filters: [...] }), ya la elimina, y para eso no hacen falta ni el DTO, ni la validación, ni una lista de campos públicos, ni operadores que viajen por la URL. Una implementación justificada solo por ahí se detiene justo antes de la mitad donde están los costes 1 y 3, que son los que no viven en ningún archivo del servidor.

Por eso conviene descartarlo explícitamente y no solo completarlo: mientras la explosión de métodos sea la razón, el patrón se implementa hasta el borde del backend y se para ahí, que es donde empieza el problema de este artículo. El otro argumento que circula —que así se puede cambiar de base de datos— es todavía más flojo en este caso, porque el traductor del criteria es precisamente la pieza barata de una migración; la sección sobre TypeORM lo enseña, pero como consecuencia comprobable y no como motivo.

Nota: el argumento de la portabilidad sí tiene un sitio donde se defiende en serio, que es el patrón Repository, y allí lo medí con detalle: El patrón Repository en NestJS — una colección que, casualmente, vive en una base de datos. Si esa discusión te interesa, está entera ahí; para lo que sigue basta con saber que no es lo que paga el criteria.

La pregunta que ocupa su lugar es qué hay disponible para el contrato entero: no para evitar métodos repetidos en una interfaz, sino para que un cliente sepa qué puede pedir y el servidor sepa qué acepta. Ahí el ecosistema ofrece más de lo que suele reconocerse.

Qué hay ya resuelto

nestjs-paginate es la opción que más lejos llega de fábrica, y conviene decirlo sin matizarlo. El listado del catálogo, entero, en la versión 15.0.1:

// src/book/book.controller.ts
@Get()
async getAll(@Paginate() query: PaginateQuery): Promise<Paginated<Book>> {
  return paginate(query, this.repository, {
    relations: ["author"],
    sortableColumns: ["title", "publishedAt", "copies"],
    searchableColumns: ["title", "author.name"],
    filterableColumns: {
      available: [FilterOperator.EQ],
      copies: [FilterOperator.GTE, FilterOperator.LTE],
      "author.name": [FilterOperator.ILIKE],
    },
    defaultSortBy: [["publishedAt", "DESC"]],
    defaultLimit: 20,
    maxLimit: 100,
  });
}

GET /books?filter.available=$eq:true&filter.copies=$gte:3&sortBy=publishedAt:DESC&page=2&limit=20

sortableColumns es un campo requerido, no opcional, y filterableColumns declara qué operadores admite cada columna de un catálogo de once —$eq, $gte, $in, $btw, $ilike, $null, $contains y compañía— más el sufijo $not y los cuantificadores $all / $any / $none. maxLimit pone el techo de página, searchableColumns da la búsqueda libre, hay paginación por cursor, y un filterExpressionMaxComplexity acota cuántos nodos puede tener una expresión de filtro para que nadie tumbe el servidor con un filter= anidado. Fíjate además en que "author.name" funciona: los nombres pueden atravesar una relación, así que hasta el caso que este artículo usa como prueba de fuego está cubierto. El coste 2 desaparece —un parámetro— y el coste 3 también: lo que no está declarado no entra.

Lo que no resuelve es el vocabulario, y de ahí sale todo lo demás. Los nombres admitidos son del tipo Column<T>, que es la ruta de propiedad de la entidad, de modo que publishedAt en la URL es publishedAt en la clase y el coste 1 permanece intacto. Y paginate() recibe un Repository<T> o un SelectQueryBuilder<T> de TypeORM y devuelve entidades de TypeORM: el contrato es excelente y es inseparable del ORM, así que no existe para quien use Mongoose o Prisma, y un caso de uso no puede expresarlo sin importar TypeORM.

GraphQL resuelve el problema entero por otra vía — el cliente declara qué quiere y el esquema es el contrato:

query {
  books(where: { available: true }, orderBy: { publishedAt: DESC }, first: 20) {
    title
    author {
      name
    }
  }
}

Los tres costes desaparecen a la vez. El precio no es la librería, es el transporte: caché HTTP, autorización, límite de tasa y observabilidad cambian de sitio, y eso lo convierte en una decisión de arquitectura y no en una capa que se añade a un listado.

Pasar req.query entero al find() resuelve el crecimiento del endpoint en cero líneas:

@Get()
async getAll(@Query() query: FilterQuery<BookDocument>) {
  return this.model.find(query);
}

Y agrava los otros dos costes hasta el final, porque el vocabulario público pasa a ser el del motor completo: ?acquisitionPrice[$gt]=0 filtra por un campo que nadie decidió exponer, y la superficie del endpoint deja de tener un límite que alguien pueda enunciar.

Specification y Query Object, los patrones clásicos, resuelven la composición de condiciones dentro del dominio — en esbozo, repository.match(new Available().and(new PublishedAfter(2020))). Es un problema real y es el que discute la sección anterior, pero ninguno de los dos dice nada sobre el transporte HTTP ni sobre validar lo que llega, que aquí es la mitad del trabajo.

	Coste 1 · URL acoplada al esquema	Coste 2 · crecimiento del endpoint	Coste 3 · superficie accidental
`nestjs-paginate`	No lo aborda: el nombre público es la propiedad de la entidad	Resuelto: un solo parámetro	Resuelto: `sortableColumns` es obligatorio
GraphQL	Resuelto: el esquema es el contrato	Resuelto	Resuelto
`where` del ORM al `find()`	Lo agrava	Resuelto, sin límite	Lo agrava: la superficie es el motor entero
Specification / Query Object	No lo aborda	Resuelto dentro del backend	No lo aborda

Nota: la tabla no mide ergonomía ni tiempo hasta el primer endpoint en producción, y en las dos cosas nestjs-paginate gana con diferencia. Tampoco mide la condición que decide antes que ninguna: qué motor de persistencia hay debajo. Comprobada contra nestjs-paginate 15.0.1 y TypeORM 1.1.0 en agosto de 2026; estas APIs cambian entre versiones mayores.

El hueco está ahí. Para quien no use TypeORM no hay nada de todo eso disponible, y para quien lo use, el contrato queda expresado en el vocabulario del ORM. Lo que falta es una descripción del listado que no nombre ni la columna ni la librería.

La tesis

Fowler define el Query Object en una línea —"un objeto que representa una consulta a la base de datos"— y lo desarrolla como un intérprete: una estructura de objetos capaz de convertirse a sí misma en SQL. Las dos formulaciones miran hacia el motor. La de este artículo mira hacia el otro extremo:

Un criteria no es una consulta que viaja por la URL: es la descripción de un listado —qué se filtra, cómo se ordena, qué página— escrita en el vocabulario del dominio y traducida dos veces, una en cada frontera.

Esa frase determina tres piezas, y las tres ocupan el resto del artículo.

Un enum de campos públicos por entidad. El vocabulario del contrato pasa a existir como dato en un archivo, en vez de ser el residuo de unos if. Ahí se decide qué puede nombrar un cliente, y esa decisión deja de depender de lo que contenga el esquema: es la respuesta directa a los costes 1 y 3.

Un criteria de dominio sin dependencias. El objeto que describe el listado no importa NestJS, ni el driver, ni el ORM. El caso de uso lo construye y lo pasa al repositorio sin saber qué hay detrás, que es lo que permite que el mismo listado se sirva desde Mongo, desde Postgres o desde un doble en memoria durante los tests.

Dos traducciones que no se conocen entre sí. La primera convierte el request HTTP en criteria y vive en la capa de aplicación; la segunda convierte el criteria en la consulta del motor y vive en infraestructura. Ninguna sabe de la existencia de la otra, y esa es la propiedad que las dos secciones siguientes ponen a prueba: cambiar de motor toca solo la segunda, y cambiar lo que el cliente puede pedir toca solo la primera.

La implementación

El criteria de dominio

Es el archivo completo, no un extracto:

// src/shared/domain/criteria/criteria.ts
type Props = {
  filters?: CriteriaFilter[];
  order?: CriteriaOrder | null;
  page?: number | null;
  pageSize?: number | null;
  search?: string | null;
};

export abstract class Criteria<T extends string> {
  private _filters: CriteriaFilter[];
  private _order: CriteriaOrder | null;
  private _page: number | null;
  private _pageSize: number | null;
  private _search: string | null;

  constructor({ filters, order, page, pageSize, search }: Props = {}) {
    this._filters = filters ?? [];
    this._order = order ?? null;
    this._page = page ?? null;
    this._pageSize = pageSize ?? null;
    this._search = search ?? null;
  }

  get filters() {
    return this._filters;
  }

  get order() {
    return this._order;
  }

  get page() {
    return this._page;
  }

  get pageSize() {
    return this._pageSize;
  }

  get search() {
    return this._search;
  }

  // Reemplaza la lista entera: es lo que hace el mapper con lo que trae el request.
  setFilters(v: CriteriaFilter[]) {
    this._filters = v;
  }

  // Acumula: lo que impone el servidor se añade y el request no puede quitarlo.
  addFilters(v: CriteriaFilter[]) {
    this._filters = [...this._filters, ...v];
  }

  find(field: T): CriteriaFilter[] {
    return this._filters.filter((f) => f.field === field);
  }
}

Lo que interesa de este archivo es lo que no contiene: ni un decorador, ni un import de NestJS, ni uno del driver de base de datos. La propiedad es comprobable — compila con las dependencias del proyecto desinstaladas —, y de ella depende que el mismo objeto pueda construirse en un caso de uso, viajar a un repositorio de Mongo y también a un doble en memoria durante los tests.

Tres detalles cargan más peso del que aparentan. El parámetro T extends string es el que ata cada criteria a su lista de campos, de modo que criteria.find("titulo") no compila si ese nombre no está en el enum de la entidad. find devuelve una lista y no un filtro porque un mismo campo puede llevar dos —publishedAt mayor que una fecha y menor que otra es un intervalo—, y quien traduce necesita los dos a la vez. Y la separación entre setFilters y addFilters existe porque son dos situaciones distintas: los filtros del cliente sustituyen la lista, mientras que los que impone el servidor se acumulan, y con nombres distintos la diferencia se ve en el caso de uso en lugar de tener que recordarla.

Los filtros tipados

Un filtro es un campo, un operador y unos valores. La clase base fija las dos primeras cosas y deja la tercera a cada tipo:

// src/shared/domain/criteria/criteria-filter.ts
export abstract class CriteriaFilter {
  readonly field: string;
  readonly operator: CriteriaFilterOperator;

  constructor({ field, operator }: CriteriaFilterProps) {
    this.field = field;
    this.operator = operator;
  }

  abstract hasValues(): boolean;
}

// src/shared/domain/criteria/criteria-number-filter.ts
export class CriteriaNumberFilter extends CriteriaFilter {
  readonly values: number[];

  constructor(props: CriteriaFilterProps & { values: number[] }) {
    super(props);

    this.values = props.values;
  }

  numbers(): number[] {
    return this.values;
  }

  // Un filtro sin valores no debe restringir la consulta.
  hasValues(): boolean {
    return this.numbers().length > 0;
  }
}

Hay una alternativa frecuente y conviene decir por qué es peor: guardar values: unknown[] junto a un campo discriminante type: "string" | "number" | "date" | "boolean". Con esa forma, el traductor hace un switch sobre type y el compilador no comprueba que los valores que lee correspondan a la rama en la que está, así que hace falta una aserción as number[] en cada caso. Con una clase por tipo, filter instanceof CriteriaNumberFilter estrecha el tipo y filter.numbers() ya devuelve number[]. La diferencia se cobra en el traductor de infraestructura, que es un switch largo sobre operadores y el sitio del patrón donde más fácil resulta equivocarse en silencio.

El enum de campos públicos

Este archivo es la superficie entera de lo que un cliente puede nombrar:

// src/book/domain/criteria/book-criteria-field.ts
export enum BookCriteriaField {
  ID = "id",
  TITLE = "title",
  AUTHOR_NAME = "authorName",
  PUBLISHED_AT = "publishedAt",
  COPIES = "copies",
  AVAILABLE = "available",
}

// src/book/domain/criteria/book-criteria.ts
export class BookCriteria extends Criteria<BookCriteriaField> {}

acquisitionPrice no está, y esa ausencia es toda la respuesta al coste 3: la superficie de la API ya no la decide el esquema. Quien añada mañana el margen del proveedor al documento no amplía nada, porque para nombrarlo desde una URL habría que editar este archivo, que es exactamente donde alguien lo buscaría en una revisión.

authorName, en cambio, sí está, y no es un campo del documento. El enum es el vocabulario del listado, no el del esquema — y ahí se resuelve el coste 1, porque el nombre público deja de estar atado al nombre de la columna y renombrar una propiedad se convierte en un cambio interno. Que authorName viva en otra colección es un problema del traductor, y de él se ocupa la prueba de fuego, más adelante.

El criteria concreto es una línea porque toda su tipificación viene del enum: a partir de aquí, cualquier find fuera de esos seis nombres deja de compilar.

El request

Este es el único archivo del patrón con decoradores, y la concentración es deliberada: es la frontera por donde entra lo que no controlas.

// src/shared/application/dto/criteria-request.ts
export class CriteriaFilterRequest {
  @IsString()
  @IsNotEmpty()
  field: string;

  @IsEnum(CriteriaFilterOperator)
  operator: CriteriaFilterOperator;

  // qs devuelve string cuando el query trae `value=x` una sola vez, y array cuando
  // trae índices (`value[0]=x`); se normaliza para no depender de cuántos valores
  // haya mandado el cliente.
  @IsDefined()
  @Transform(({ value }) => (Array.isArray(value) ? value : [value]))
  @IsArray()
  @IsString({ each: true })
  value: string[];
}

export class CriteriaRequest {
  @IsOptional()
  @IsArray()
  @ValidateNested({ each: true })
  @Type(() => CriteriaFilterRequest)
  filters?: CriteriaFilterRequest[];

  @IsOptional()
  @ValidateNested()
  @Type(() => CriteriaOrderRequest)
  order?: CriteriaOrderRequest;

  @IsOptional()
  @Type(() => Number)
  @IsInt()
  @Min(1)
  page?: number;

  @IsOptional()
  @Type(() => Number)
  @IsInt()
  @Min(1)
  pageSize?: number;

  @IsOptional()
  @IsString()
  search?: string;
}

Dos ajustes del arranque de la aplicación deciden si esto funciona, y los dos fallan en silencio:

// src/main.ts
const app = await NestFactory.create<NestExpressApplication>(AppModule);

// Express 5 parsea el query con `simple`, que es querystring.parse y no anida:
// `order[by]` llegaría como una clave llamada literalmente "order[by]".
app.set("query parser", "extended");

// Sin `transform`, los @Type() del DTO no se aplican y `page` sigue siendo string.
app.useGlobalPipes(new ValidationPipe({ transform: true }));

El primero es un cambio de la versión 5: en lib/application.js de Express 5.2.1, la configuración por defecto es this.set('query parser', 'simple'), y extended es lo que enchufa qs. Sin él, un filters[0][field]=title no llega como objeto anidado y la validación rechaza el request entero sin que sea culpa del cliente.

El mapper del request

Es la primera de las dos traducciones. Convierte el DTO en criteria, y por el camino toma tres decisiones:

// src/shared/application/criteria/criteria-request-mapper.ts
export type CriteriaFilterOption<T extends string> = {
  field: T;
  type: CriteriaFilterType;
};

export abstract class CriteriaRequestMapper<T extends string> {
  abstract options(): CriteriaFilterOption<T>[];

  execute({ criteria, request }: Props<T>): Criteria<T> {
    if (request.search !== undefined) {
      criteria.setSearch(this.mapSearch(request.search));
    }

    // La paginación se fija siempre, la traiga el request o no: un criteria sin
    // pageSize se traduce en una consulta sin límite.
    criteria.setPage(this.mapPage(request.page));
    criteria.setPageSize(this.mapPageSize(request.pageSize));

    if (request.order !== undefined) {
      criteria.setOrder(
        new CriteriaOrder({
          orderBy: request.order.by,
          orderType: request.order.type,
        }),
      );
    }

    if (request.filters !== undefined) {
      const options = this.options();
      const result: CriteriaFilter[] = [];

      for (const filter of request.filters) {
        const mapped = this.mapFilter(filter, options);

        if (mapped !== null) {
          result.push(mapped);
        }
      }

      criteria.setFilters(result);
    }

    return criteria;
  }

  // El tope es lo que impide que un pageSize absurdo acabe en un find() sin límite.
  private mapPageSize(value: number | undefined): number {
    if (value === undefined || !Number.isFinite(value)) {
      return DEFAULT_PAGE_SIZE;
    }

    return Math.min(Math.max(Math.trunc(value), 1), MAX_PAGE_SIZE);
  }

  // Lo que no está en options() no se filtra: no hay campo al que aplicarlo.
  private mapFilter(
    filter: CriteriaFilterRequest,
    options: CriteriaFilterOption<T>[],
  ): CriteriaFilter | null {
    const option = options.find((o) => o.field === filter.field);

    if (option === undefined) {
      return null;
    }

    const props = { field: option.field, operator: filter.operator };

    switch (option.type) {
      case CriteriaFilterType.STRING:
        return new CriteriaStringFilter({ ...props, values: filter.value });

      case CriteriaFilterType.NUMBER:
        return new CriteriaNumberFilter({
          ...props,
          values: this.mapNumbers(filter.value),
        });

      // ...fechas y booleanos, igual
    }
  }
}

Y el de la entidad declara la lista, que es lo único que hay que escribir por listado:

// src/book/application/criteria/book-criteria-request-mapper.ts
export class BookCriteriaRequestMapper extends CriteriaRequestMapper<BookCriteriaField> {
  options(): CriteriaFilterOption<BookCriteriaField>[] {
    return [
      { field: BookCriteriaField.ID, type: CriteriaFilterType.STRING },
      { field: BookCriteriaField.TITLE, type: CriteriaFilterType.STRING },
      { field: BookCriteriaField.AUTHOR_NAME, type: CriteriaFilterType.STRING },
      { field: BookCriteriaField.PUBLISHED_AT, type: CriteriaFilterType.DATE },
      { field: BookCriteriaField.COPIES, type: CriteriaFilterType.NUMBER },
      { field: BookCriteriaField.AVAILABLE, type: CriteriaFilterType.BOOLEAN },
    ];
  }
}

La primera decisión es que el tipo declarado en options() es quien convierte el texto. La query string no tiene tipos, así que el "3" de copies se vuelve el número 3 aquí, una sola vez, y no en cada traductor de motor por su cuenta. La segunda es el tope de página: fijar page y pageSize siempre, con MAX_PAGE_SIZE por techo, es lo que impide que un cliente convierta un listado en un volcado de la colección.

La tercera conviene decirla con su coste. Un filtro sobre un campo no declarado se descarta en silencio, no devuelve un 400, y eso significa que una errata del cliente produce la lista sin filtrar en vez de un error visible — que es peor para depurar. La razón de elegirlo así es que una URL guardada hace meses sigue devolviendo algo sensato cuando un campo deja de ser filtrable, en lugar de romperse. nestjs-paginate toma la decisión contraria y ofrece throwOnInvalidFilter; las dos son defendibles, y lo que no es defendible es no haber elegido.

Nota: el compilador no comprueba que options() cubra el enum entero. Declararlo como un Record<BookCriteriaField, CriteriaFilterType> en vez de una lista sí lo exigiría, a cambio de perder la forma de tabla. Tal como está, que un campo del enum se quede sin tipo es un descuido que solo se nota filtrando.

Aquí está también el coste del patrón, en el mismo sitio que el beneficio: por cada listado hay que escribir cuatro archivos —el enum, el criteria de una línea, el mapper con su options() y el mapa de infraestructura que aparece más abajo— donde antes había cinco @Query(). Lo que se gana a cambio es que esos cuatro se leen en un minuto y dicen la verdad completa sobre lo que el endpoint acepta.

El caso de uso y el puerto

El repositorio de dominio expone un solo método para listar:

// src/book/domain/repository/book.repository.ts
export interface BookRepository {
  pagination(criteria: BookCriteria): Promise<PaginationRepositoryResult<Book>>;
}

// src/book/application/use-cases/get-all-books.ts
export class GetAllBooks {
  constructor(
    private readonly repository: BookRepository,
    private readonly criteriaMapper: BookCriteriaRequestMapper,
  ) {}

  async execute({ request }: Props): Promise<PaginationResponse<BookResponse>> {
    const criteria = this.criteriaMapper.execute({
      // el orden por defecto es la publicación más reciente; si el request trae
      // `order`, el mapper lo pisa
      criteria: new BookCriteria({
        order: new CriteriaOrder({
          orderBy: BookCriteriaField.PUBLISHED_AT,
          orderType: CriteriaOrderType.DESC,
        }),
      }),
      request: request,
    });

    const result = await this.repository.pagination(criteria);

    return PaginationResponseMapper.execute({
      result: {
        ...result,
        items: result.items.map((b) => BookMapper.execute(b)),
      },
    });
  }
}

El criteria se construye en el caso de uso y no en el controlador porque el orden por defecto es una decisión de producto —qué ve primero quien abre la pantalla—, no una del transporte. El mapper lo recibe ya construido y solo pisa lo que el request traiga.

Ese reparto es también el que hace seguro imponer condiciones desde el servidor. Si el listado público solo debe enseñar los ejemplares disponibles, el filtro se añade después del mapper:

criteria.addFilters([
  new CriteriaBooleanFilter({
    field: BookCriteriaField.AVAILABLE,
    operator: CriteriaFilterOperator.EQUAL,
    value: true,
  }),
]);

Con setFilters en ese lugar, un cliente que mandara su propio filters borraría la restricción y el fallo no lanzaría nada: serían filas de más en la respuesta. Es exactamente el motivo por el que las dos operaciones tienen nombres distintos.

La traducción a Mongo

La segunda traducción vive en infraestructura y arranca con un mapa:

// src/book/infrastructure/mongo/book-mongo-repository.ts
private readonly criteriaFields: MongoCriteriaField<BookCriteriaField>[] = [
  { field: BookCriteriaField.ID, mongo: "_id", canSearch: false },
  { field: BookCriteriaField.TITLE, mongo: "title", canSearch: true },
  { field: BookCriteriaField.AUTHOR_NAME, mongo: "author.name", canSearch: true },
  { field: BookCriteriaField.PUBLISHED_AT, mongo: "publishedAt", canSearch: false },
  { field: BookCriteriaField.COPIES, mongo: "copies", canSearch: false },
  { field: BookCriteriaField.AVAILABLE, mongo: "available", canSearch: false },
];

Ese mapa es la tabla de alias que el punto 2 del inventario describía como el parche que se escribe tarde y solo para el campo que se movió. Aquí existe desde el principio y cubre todos los campos, así que id → _id deja de ser un caso especial y pasa a ser una fila más. canSearch resuelve la otra pregunta: qué entra en la búsqueda libre. Solo el título y el autor, que son las dos cosas que la tabla enseña — buscar por un campo que no se ve deja filas sin explicación aparente.

El constructor de la consulta recorre ese mapa:

// src/shared/infrastructure/mongo/mongo-criteria-builder.ts
execute({ criteria, fields }: Props<T>): CriteriaResult {
  const result: CriteriaResult = { filter: {}, order: null, skip: null, limit: null };

  // Cada campo puede aportar varios fragmentos —un filtro por operador—, así que se
  // aplanan: `$and` es una lista de condiciones, no de listas.
  const fragments = fields.flatMap((f) =>
    this.filterMapper.execute({ name: f.mongo, filters: criteria.find(f.field) }),
  );

  if (fragments.length > 0) {
    result.filter.$and = fragments;
  }

  if (criteria.search !== null) {
    const value = criteria.search;

    const search = fields
      .filter((f) => f.canSearch)
      // el texto viene del buscador y `$regex` lo interpreta: hay que escaparlo
      .map((f) => ({ [f.mongo]: { $regex: escape(value), $options: "i" } }));

    if (search.length > 0) {
      result.filter.$or = search;
    }
  }

  const order = criteria.order;

  if (order !== null && order.hasOrder()) {
    // el orden se resuelve contra el mismo mapa que los filtros: no se puede ordenar
    // por un campo que no esté en él
    const found = fields.find((f) => f.field === order.orderBy);

    if (found) {
      const direction = order.orderType === CriteriaOrderType.ASC ? 1 : -1;

      result.order = { [found.mongo]: direction };
    }
  }

  if (criteria.pageSize !== null) {
    const page = criteria.page ?? 1;

    result.skip = (page - 1) * criteria.pageSize;
    result.limit = criteria.pageSize;
  }

  return result;
}

Que el orden se resuelva contra el mismo mapa cierra el coste 3 por el otro extremo: el enum controla lo que se puede nombrar al entrar, y el mapa controla lo que existe al salir. Para ordenar por acquisitionPrice haría falta que estuviera en los dos archivos.

Los operadores se traducen aparte, un método por tipo de filtro:

// src/shared/infrastructure/mongo/mongo-criteria-filter-mapper.ts
private mapNumber(name: string, filter: CriteriaNumberFilter): FilterQuery<unknown> | null {
  const values = filter.numbers();
  const [first] = values;
  const single = values.length === 1;

  switch (filter.operator) {
    case CriteriaFilterOperator.EQUAL:
      return { [name]: single ? first : { $in: values } };

    case CriteriaFilterOperator.NOT_EQUAL:
      return { [name]: single ? { $ne: first } : { $nin: values } };

    // Los operadores de comparación son binarios: con varios valores solo tiene
    // sentido el primero.
    case CriteriaFilterOperator.GTE:
      return { [name]: { $gte: first } };

    default:
      return null;
  }
}

El default que devuelve null es lo que hace que un operador sin sentido para el tipo —CONTAINS sobre un booleano— no filtre en lugar de romper la consulta. Y conviene fijarse en lo que este archivo devuelve: fragmentos y valores sueltos, no una consulta montada. El builder entrega filter, order, skip y limit por separado, y quién los usa y cómo es decisión del repositorio. Esa elección parece un detalle de estilo y es la que decide si el patrón sobrevive a la prueba de fuego.

La página y el total salen del mismo filtro

async pagination(criteria: BookCriteria): Promise<PaginationRepositoryResult<Book>> {
  const result = this.criteriaBuilder.execute({
    criteria: criteria,
    fields: this.criteriaFields,
  });

  const query = this.model.find(result.filter);

  if (result.order !== null) {
    query.sort(result.order);
  }

  if (result.skip !== null) {
    query.skip(result.skip);
  }

  if (result.limit !== null) {
    query.limit(result.limit);
  }

  // Las dos consultas salen del mismo filtro y viajan en paralelo; el conteo no
  // lleva skip ni limit porque acotan la página, no el total.
  const [list, count] = await Promise.all([
    query,
    this.model.countDocuments(result.filter),
  ]);

  return {
    items: list.map((i) => BookMongoMapper.execute(i)),
    count: count,
    pageSize: criteria.pageSize,
  };
}

Es la única decisión del listado original que el patrón conserva tal cual, y conviene decir por qué importa: si el conteo se construyera por su cuenta, el total y la página podrían responder a filtros distintos y la paginación mentiría sin fallar. El síntoma es una última página vacía, o un número de resultados que no cuadra con lo que se ve, y ninguna de las dos cosas aparece en un log.

Punto por punto

De los cinco del inventario, cuatro quedan cerrados. El operador ya no vive en el cuerpo del método: viaja explícito en la URL y lo valida un @IsEnum. El nombre público dejó de ser el nombre de la columna, que ahora es una celda del mapa de infraestructura. La firma del endpoint es @Query() request: CriteriaRequest y no cambia al añadir un filtro, así que el crecimiento por multiplicación desaparece. Y lo que se puede filtrar y ordenar está escrito en dos archivos que se leen en un minuto, en lugar de deducirse de unas ramas. El quinto —el formato compartido entre listados y clientes— queda cerrado en cuanto hay un segundo listado, porque de todo lo que se ha escrito en esta sección solo los cuatro archivos del catálogo son suyos: el resto ya está puesto.

Queda una fila del mapa que todavía miente. authorName apunta a author.name, y un documento de books no tiene ninguna propiedad author.name: guarda una referencia. Con el find() de arriba, ese filtro no falla — sencillamente no encuentra nada, que es la peor de las dos opciones.

La prueba de fuego: el campo que no vive en la colección

La tabla enseña el nombre del autor en una columna, así que hay que poder filtrar y ordenar por él igual que por el título. El dato está en authors, al otro lado de una referencia, y el listado se pagina: la página y el total tienen que salir del mismo conjunto de filas.

La salida que se prueba primero es populate, y falla de una manera que conviene mirar de cerca:

this.model
  .find(result.filter)
  .populate({ path: "author", match: { name: "Herbert" } });

populate resuelve la lectura, no el filtrado. El match se aplica al documento poblado, no al libro, así que los libros de otros autores siguen viniendo — con author: null en lugar de desaparecer—. El countDocuments cuenta esos también, y el resultado es una tabla con huecos y un total que no corresponde a lo que se ve.

La segunda salida sí filtra, y es la que instala el problema de verdad:

const filters = criteria.find(BookCriteriaField.AUTHOR_NAME);

if (filters.length > 0) {
  const ids = await this.authorModel.find({ name: /* ... */ }).distinct("_id");

  result.filter.author = { $in: ids };
}

Funciona, y a cambio el repositorio vuelve a tener una rama por campo especial. Sigue sin poder ordenar por el nombre del autor, porque el $sort opera sobre la colección de libros y ahí no hay ningún nombre. Y el conocimiento de que existen dos colecciones, que el patrón había sacado por la puerta, vuelve a entrar por un if — con el agravante de que cada campo derivado que se añada después traerá el suyo.

La salida buena depende de una decisión que ya está tomada: el builder no devuelve una consulta, devuelve filter, order, skip y limit por separado. Quién los usa y en qué orden es cosa del repositorio:

// src/book/infrastructure/mongo/book-mongo-repository.ts
async pagination(criteria: BookCriteria): Promise<PaginationRepositoryResult<Book>> {
  const result = this.criteriaBuilder.execute({
    criteria: criteria,
    fields: this.criteriaFields,
  });

  // El autor viaja en cada fila, así que el lookup va ANTES del match: solo así se
  // puede filtrar y ordenar por su nombre como por cualquier otra columna.
  //
  // El $unwind NO preserva los vacíos: un libro sin autor no es una fila con un
  // hueco, es una referencia rota. Aquí no aparece.
  const join: PipelineStage[] = [
    {
      $lookup: {
        from: this.authorModel.collection.name,
        localField: "author",
        foreignField: "_id",
        as: "author",
      },
    },
    { $unwind: "$author" },
    { $match: result.filter },
  ];

  const page: PipelineStage[] = [...join];

  if (result.order !== null) {
    page.push({ $sort: result.order });
  }

  if (result.skip !== null) {
    page.push({ $skip: result.skip });
  }

  if (result.limit !== null) {
    page.push({ $limit: result.limit });
  }

  const [list, counted] = await Promise.all([
    this.model.aggregate<MongoBook>(page),
    this.model.aggregate<{ count: number }>([...join, { $count: "count" }]),
  ]);

  return {
    items: list.map((i) => BookMongoMapper.execute(i)),
    count: counted[0]?.count ?? 0,
    pageSize: criteria.pageSize,
  };
}

El $lookup va antes del $match porque author.name tiene que existir en el documento cuando el filtro se evalúa, y esa ordenación de etapas es exactamente lo que un builder que devolviera una consulta montada no podría decidir. Tendría que conocer las colecciones para colocar el $lookup —y entonces el traductor sabría de relaciones, que es la contaminación que se quería evitar— o bien habría que saltárselo para este campo, que es volver al if. Devolver piezas no era una preferencia de estilo: era lo que dejaba esta decisión en manos de quien sí conoce el motor.

El $unwind sin preserveNullAndEmptyArrays es la otra decisión, y es de negocio: un libro cuyo autor ya no existe no aparece en el catálogo. Si el negocio dijera lo contrario, cambia esa etapa y nada más.

Lo que la sección tenía que demostrar es lo que no cambió. authorName filtra y ordena como cualquier otra columna, y para conseguirlo no se tocaron el enum, ni el criteria, ni el DTO, ni el mapper del request, ni el caso de uso, ni la URL que escribe el cliente. El find se convirtió en un aggregate dentro de un archivo de infraestructura, y el contrato no se enteró — que es la propiedad que la tesis prometía y la que decide si el patrón aguanta el tercer listado. La fila del mapa que antes no encontraba nada dice ahora la verdad, y para conseguirlo no ha dejado de ser una fila.

El mismo criteria contra TypeORM

Todo lo anterior está escrito contra Mongo, y la única pieza que sabe que hay un Mongo debajo es el builder. Cambiar de motor es escribir otro:

// src/shared/infrastructure/typeorm/typeorm-criteria-builder.ts
export type TypeOrmCriteriaField<T extends string> = {
  field: T;
  column: string;
  canSearch: boolean;
};

export class TypeOrmCriteriaBuilder<T extends string, E> {
  execute({ criteria, fields }: Props<T>): TypeOrmCriteriaResult<E> {
    const where: FindOptionsWhere<E> = {};

    for (const f of fields) {
      const operators = criteria
        .find(f.field)
        .filter((filter) => filter.hasValues())
        .map((filter) => this.operatorMapper.execute(filter));

      if (operators.length === 0) {
        continue;
      }

      // Dos filtros sobre el mismo campo son un intervalo, y TypeORM los combina
      // con And(): es el equivalente de los dos fragmentos del `$and` de Mongo.
      const condition =
        operators.length === 1 ? operators[0] : And(...operators);

      // `author.name` se anida como `{ author: { name: ... } }`: TypeORM no acepta
      // la ruta con punto como clave, así que la columna se parte por el punto.
      this.assign(where, f.column.split("."), condition);
    }

    const pageSize = criteria.pageSize;

    return {
      where: where,
      order: this.mapOrder(criteria, fields),
      skip:
        pageSize === null ? undefined : ((criteria.page ?? 1) - 1) * pageSize,
      take: pageSize ?? undefined,
    };
  }
}

El traductor de operadores es el mismo switch con otro vocabulario:

private map(filter: CriteriaNumberFilter): FindOperator<number> | null {
  const values = filter.numbers();
  const [first] = values;
  const single = values.length === 1;

  switch (filter.operator) {
    case CriteriaFilterOperator.EQUAL:
      return single ? Equal(first) : In(values);

    case CriteriaFilterOperator.NOT_EQUAL:
      return single ? Not(Equal(first)) : Not(In(values));

    case CriteriaFilterOperator.GTE:
      return MoreThanOrEqual(first);

    case CriteriaFilterOperator.LTE:
      return LessThanOrEqual(first);

    default:
      return null;
  }
}

Y el repositorio queda más corto que su gemelo de Mongo, porque findAndCount devuelve la página y el total en una sola llamada y contra el mismo where — la regla que en Mongo había que sostener a mano la impone aquí la firma del método:

async pagination(criteria: BookCriteria): Promise<PaginationRepositoryResult<Book>> {
  const result = this.criteriaBuilder.execute({
    criteria: criteria,
    fields: this.criteriaFields,
  });

  const [list, count] = await this.repository.findAndCount({
    relations: { author: true },
    where: result.where,
    order: result.order,
    skip: result.skip,
    take: result.take,
  });

  return {
    items: list.map((i) => BookTypeOrmMapper.execute(i)),
    count: count,
    pageSize: criteria.pageSize,
  };
}

El campo que no vive en la tabla —el que costó una sección entera en Mongo— aquí es la misma fila del mapa con un punto, authorName → "author.name", y el JOIN lo pone el ORM al ver la relación en el where. Cuando la consulta necesita más control, la alternativa es empujar las mismas piezas sobre un SelectQueryBuilder con leftJoin explícito, que es el equivalente literal del $lookup; lo que no cambia en ninguno de los dos casos es de dónde salen las piezas.

Nota: ILike no significa lo mismo en todos los motores. En TypeORM 1.1.0, la condición se emite como ILIKE nativo en PostgreSQL y CockroachDB, y en cualquier otro driver se traduce a UPPER(columna) LIKE UPPER(parámetro). Funciona igual y rinde distinto: la segunda forma no aprovecha un índice sobre la columna, hace falta uno funcional sobre la expresión. Es la clase de diferencia que el criteria no puede ocultar, porque no es de vocabulario sino de motor.

Con Prisma el ejercicio es el mismo con un tercer vocabulario: el builder devolvería where, orderBy, skip y take, y el repositorio los pasaría a findMany junto a un count con el mismo where.

Lo que hay que escribir para portar un listado entero, entonces, es un builder y un mapa de campos; lo demás son las mismas piezas de antes, sin tocar. Esto es lo que la sección de las justificaciones prometía enseñar como consecuencia y no como motivo — la portabilidad existe y es comprobable, pero sigue sin ser la razón por la que se paga el patrón, porque cambiar de motor de base de datos es raro y tener tres listados y dos clientes es lo normal.

El otro extremo, en un apartado

El cliente construye el mismo objeto y lo entrega como parámetros de la petición:

// src/modules/criteria/criteria-request.ts
params(): CriteriaRequestDTO {
  const result: CriteriaRequestDTO = {};

  // Un filtro sin valores no restringe nada: no viaja.
  const filters = this.filters.filter((f) => f.hasValues());

  if (filters.length > 0) {
    result.filters = filters.map((f) => f.dto());
  }

  if (this.order !== undefined && this.order.hasOrder()) {
    result.order = this.order.dto();
  }

  // El buscador vacío no es una búsqueda por "".
  if (this.search !== undefined && this.search.trim() !== "") {
    result.search = this.search;
  }

  return result;
}

Y la petición es una llamada normal, sin nada alrededor:

import axios from "axios";

const { data } = await axios.get<PaginationResponse<BookResponse>>("/books", {
  params: criteria.params(),
  // sin esto, cancelar una búsqueda mientras se teclea es decorativo
  signal: controller?.signal,
});

Ese params es lo que produce la URL del principio del artículo, con sus corchetes y todo: nadie la escribe a mano. No hay serializador propio en ninguno de los dos lados, porque axios ya escribe los objetos anidados en notación de corchetes y qs los reconstruye del otro lado, que es justo lo que el query parser extended del arranque habilita. Las dos reglas del snippet anterior existen porque afectan a la URL y no al servidor: lo que no restringe no viaja, y una URL sin ruido es la diferencia entre poder compartirla y no.

Conviene decir dónde se acaba la seguridad de tipos. El enum es la superficie entera de lo que un cliente puede nombrar, pero esa garantía vive en el servidor: lo que viaja por la URL es texto, y en el cliente field vuelve a ser un string. Que las dos listas digan lo mismo es una convención de equipo, no un contrato que alguien compruebe — y cuando un campo deja de ser filtrable, el síntoma es el que ya se describió: la lista llega sin filtrar. Cerrarlo del todo exige generar los nombres desde una fuente común, o publicar el enum en un paquete compartido, y las dos cosas atan el despliegue del cliente al del servidor.

Nota: cómo una tabla mantiene ese objeto sincronizado con la URL del navegador, con el estado de las columnas y con la cancelación de peticiones en vuelo es material de un artículo propio.

Dos matices honestos, y lo que esto no es

El patrón abarata exponer un filtro, no servirlo. Añadir un campo filtrable cuesta una línea en el enum y otra en el mapa, y esa facilidad es justo el riesgo: seis campos filtrables en cualquier combinación son muchas más consultas distintas de las que el equipo va a mirar en un plan de ejecución. Ningún índice se deduce del criteria, así que conviene decidir qué combinaciones se ofrecen sabiendo cuáles están indexadas, en lugar de descubrirlo cuando la tabla crezca.

La paginación por skip se degrada con el desplazamiento. El motor recorre lo que salta, así que la página 500 cuesta más que la 2. Con el techo de MAX_PAGE_SIZE y listados de panel no se observa, y en un feed largo la respuesta correcta es un cursor — que el patrón admite sin cambiar de forma. El criteria llevaría un cursor en lugar de una página, el traductor lo convertiría en una condición más sobre el último elemento visto, y el enum, los filtros y las dos traducciones se quedan donde están. Lo que sí cambia es una restricción del contrato: el orden tiene que incluir una columna única como desempate, así que ya no se puede ordenar por cualquier campo del enum.

Y conviene decir lo que esto no es: un motor de consultas. No hay OR entre filtros distintos, ni grupos, ni paréntesis — todos los filtros se combinan con AND y el OR está reservado a la búsqueda libre. Quien necesite componer expresiones necesita GraphQL o un lenguaje propio, y es mejor saberlo antes de escribir el primer archivo que después del tercer listado.

Para quién es esto, y para quién no

Empezando por el no: un backend con un listado, tres o cuatro filtros fijos y una sola pantalla que lo consume. Ahí esto son unos quince archivos compartidos más cuatro por listado para sustituir cinco @Query() que funcionan, y ninguno de los tres costes tiene todavía un síntoma observable. La respuesta correcta en ese proyecto es la simple, y adoptar el patrón por adelantado es pagar por un problema que quizá no llegue.

Cuatro condiciones invierten el balance, y rara vez aparecen solas: tres o más listados paginados; más de un cliente consumiéndolos —un panel interno, una app, alguien integrando por API—; filtros que el usuario compone desde la cabecera de una tabla en vez de elegir de una lista fija; y listados que se comparten por URL. Con dos de ellas presentes, el coste queda amortizado en el segundo listado, porque los quince archivos compartidos se escriben una sola vez y a partir de ahí cada listado son cuatro, uno de los cuales es una línea.

La regla práctica cabe en una línea: si lo que el cliente puede pedir aún cabe en la firma de un método, déjalo ahí; en cuanto deje de caber, el sitio donde vive esa lista es un archivo, no un método.

El código

El proyecto ejecutable está en hgomezrobaina/nestjs-criteria-pattern, con el catálogo de la biblioteca montado sobre Mongo: docker compose up -d && npm install && npm run seed && npm run dev.

Lo que conviene mirar no es que arranque, sino su suite: 26 tests en 19 milisegundos, sin base de datos. Ahí dentro está comprobado lo que este artículo afirma — que un filtro sobre un campo no declarado se descarta, que el pageSize tiene techo, que un filtro que impone el servidor sobrevive a un filters del cliente, que id se traduce a _id y authorName a author.name, que el término de búsqueda se escapa antes de entrar en un $regex, y que el mismo criteria produce el where anidado de TypeORM y las piezas de Mongo. Ninguna de esas afirmaciones necesita un contenedor para verificarse, porque ninguna de ellas es sobre la base de datos: son sobre lo que el contrato decide antes de llegar a ella.

Hablemos

¿Preguntas, feedback o una visión distinta? Me encantaría leerte. Me encuentras aquí:

GitHub — hgomezrobaina
LinkedIn — Héctor Gómez Robaina
X — @hgomezrobaina

The Repository Pattern in NestJS: a collection that happens to live in a database

Hector Angel Gomez Robaina — Sat, 15 Aug 2026 19:12:46 +0000

The canonical starting point for a NestJS module backed by TypeORM is the one the framework itself documents: the module declares TypeOrmModule.forFeature([Order]) and the service receives the repository by injection.

@Injectable()
export class OrderService {
  constructor(
    @InjectRepository(Order) private readonly repo: Repository<Order>,
  ) {}
}

From there the service has find, findOne, save and delete at hand, and can write its first business rule with no further scaffolding. It is the path of least friction and the best documented one, which is why it is the one most codebases are built on.

The code that ends up living inside that service takes this shape:

async confirm(orderId: string): Promise<Order> {
  const order = await this.repo.findOne({
    where: { id: orderId, status: 'pending' },
    relations: { lines: true },
  });

  if (!order) throw new NotFoundException('Order not found');
  if (order.lines.length === 0) {
    throw new BadRequestException('Cannot confirm an order without lines');
  }

  order.status = 'confirmed';
  return this.repo.save(order);
}

The method is correct: it does what it promises, it reads well, and it can carry years of production without an incident. What is worth analysing is not its behaviour but its coupling surface. There is a genuine business rule in there —an order cannot be confirmed with no lines— and it pays to measure how much knowledge of the persistence engine ended up embedded in it.

The inventory is longer than it looks:

The rule depends on how the row was loaded. The invariant is evaluated over order.lines, and that collection only exists if the query asked for the relation explicitly. If relations: { lines: true } disappears in a refactor, order.lines arrives empty, the check fires when it should not, and the invariant is inverted without anything failing: no compile error, no exception, no trace. The rule's correctness is a property of the query, not of the rule.
The business condition is expressed in table vocabulary. "Pending" is not a domain concept in this code; it is the string 'pending' compared against a column inside a where object.
Control flow is dictated by the ORM's API. The first if exists because findOne returns null; that is a TypeORM decision, not a business one.
Write semantics are implicit. save decides on its own whether the operation is an INSERT or an UPDATE based on the state of the primary key. The service inherits that ambiguity.
The business class is the schema definition. Order —where the total calculation and the state transitions will eventually live— is the same class carrying the @Column decorators that describe the table.

The first four are coupling nuisances: awkward, but local and reversible. The fifth is of another kind. It is not a consequence of how this method was written, but of a structural decision —that the business model and the persistence model be the same object— which the project adopted without deliberating it, by following the documented path.

That coupling has no observable cost as long as the module stays on single-entity operations over a single table. It becomes measurable when three conditions show up, and almost every real domain ends up meeting them: that the entity accumulates invariants of its own, that a query with business meaning is needed from more than one place, and that a rule has to be verified without depending on the database.

Each of the three produces a distinct cost, and they are worth examining separately.

Three costs of the coupling

1. The business entity is the table definition

The Order class serves two consumers with incompatible requirements. The business needs an object that can only exist in valid states and that expresses its concepts precisely. The ORM needs an object that mirrors the row and that it can build knowing nothing about the business. When both consumers share the same class, this is the result:

@Entity('order')
export class Order {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column()
  customerId: string;

  @ManyToOne(() => Customer)
  customer: Customer;

  @Column({ type: 'varchar', default: 'pending' })
  status: string;

  @Column({ type: 'numeric', precision: 12, scale: 2 })
  total: string;

  @OneToMany(() => OrderLine, (line) => line.order)
  lines: OrderLine[];

  @CreateDateColumn() createdAt: Date;
  @UpdateDateColumn() updatedAt: Date;
  @DeleteDateColumn() deletedAt: Date | null;
}

The contamination runs in both directions, and there is a third consequence that is not about types but about construction.

From persistence into the domain. createdAt, updatedAt and deletedAt are infrastructure requirements —auditing and soft deletion— that no business rule ever consults, yet they are part of the type the whole module works with. More to the point: customerId and customer are two representations of the same fact living side by side in the same object, with no guarantee that they are in sync. And customer is declared as Customer, not as Customer | undefined, even though its value is undefined whenever the query did not ask for the relation. The type asserts something the value does not honour, and strictNullChecks cannot catch it because the property is declared as present.

From the domain into persistence. total is typed as string because the PostgreSQL driver returns numeric columns as strings so precision is not lost in JavaScript's number. That is a correct decision by the driver and a leak for the business: an order's amount is a number, and here any calculation on it requires converting first, in every place where it is calculated. Fixing it inside the class itself is possible with a column transformer, but that leaves the representation of a business concept conditioned on what the ORM knows how to serialise.

The constructor cannot demand anything. TypeORM's documentation states it explicitly: an entity's constructor arguments must be optional, because the ORM instantiates the class when materialising each row and knows nothing about those arguments. The consequence is that the class cannot guarantee its own invariant at construction time. new Order() —no customer, no lines, no status— is valid for the compiler and for the ORM. The invariant "a confirmed order has at least one line" cannot be a property of the type; it can only be a check repeated in every method that needs it, which is exactly what confirm() was doing in the example above. The class is structurally incapable of sustaining an always-valid state.

2. Queries have no name

"A customer's pending orders" is a business concept: it has a definition, and that definition can change. In the code it does not exist as a unit. It exists as an object literal replicated in every place that needs it:

// order.service.ts
where: { customerId, status: 'pending' }

// notification.service.ts
where: { customerId, status: In(['pending', 'awaiting_payment']) }

// report.service.ts
where: { customerId, status: 'pending' }, relations: { lines: true }

All three claim to express the same concept and all three diverge. None is marked as canonical, so reading the code there is no way to tell which definition is the correct one, and the compiler accepts all three: the divergence is semantic, not a type error. The third one, on top of that, returns entities of a different shape, because relations changes what arrives populated; a rule that depends on order.lines behaves differently depending on the entry point.

The cost lands when the definition of "pending" changes: it is proportional to the number of copies, and there is no reliable procedure for enumerating them —searching for the literal 'pending' fails the moment someone extracted it into a constant or received it as a parameter—.

3. The rule cannot be verified without a database

Running a test for "you cannot reserve more units than there are in stock" takes four things that have nothing to do with the rule: a PostgreSQL instance, a migrated schema, fixtures that leave the row in the starting state, and a mechanism for isolation between cases.

The test then covers far more than it intends to. When it fails, the cause may be in the rule, in the column mapping, in a pending migration or in the state another case left behind: the signal does not localise the defect. And the cycle moves from the order of milliseconds to the order of seconds, multiplied by the number of cases —a stock rule has plenty: the exact boundary, one over, zero on hand, two concurrent reservations—.

The second-order effect is the expensive one. A slow suite is run less often, and the edge cases that are awkward to set up tend not to get written: the cost is not only in the tests that take long, but in the ones that never come to exist.

The three costs share one origin: there is no boundary between the object that expresses the business and the object that describes the row. Before proposing one, it is worth reviewing what the ecosystem offers, because the available tools do not all attack the same problem.

State of the art: what each option solves

NestJS's documented path. @InjectRepository(Order) injects a Repository<Order> built by the DataSource. What it solves is the wiring: the connection, the pool, the lifecycle and the injection. It is a complete solution to that problem, and it does not claim to be anything else. On the ownership of the model it takes no position: the type it hands you is the same one that defines the table.

Active Record. TypeORM offers the alternative of extending BaseEntity, so the class acquires its own persistence operations:

const order = await Order.findOneBy({ id });
await order.save();

It removes the ceremony of injection and, in exchange, takes the coupling as far as it can go: the business class not only describes the table, it also knows how to connect to it. The three costs above remain, plus the impossibility of instantiating the class outside a context with an initialised DataSource.

Custom repositories. This is TypeORM's answer to cost #2: giving the named query a place of its own, by extending the repository instance.

const OrderRepository = dataSource.getRepository(Order).extend({
  findPendingByCustomer(customerId: string) {
    return this.findBy({ customerId, status: 'pending' });
  },
});

With this the query comes to have a single owner, which was the problem in cost #2. The other two are untouched: the object is built from the DataSource rather than by injection —which forces registering it as a provider with a factory of its own— and, above all, the type its methods return is still the persistence model.

MikroORM. It is the option that goes furthest out of the box, and that deserves saying without qualification: it implements Data Mapper, Unit of Work and Identity Map natively. The EntityManager tracks loaded objects, resolves by identity —two lookups by the same primary key return the same instance— and groups pending changes into an implicit transaction when flush() is called. In other words, it solves by design the problem that takes up the longest section of this article. What it does not solve is cost #1: its entities are still decorated classes that describe the table, so the boundary between the business model and the persistence model remains the job of whoever writes the code.

Prisma. There are no repositories or entities in the earlier sense: you inject the client and the generated types are the rows, flat data structures with no behaviour. The effect on cost #1 is ambivalent: there is no business class that can be contaminated, because there is no class at all, so any domain model is born separate. In exchange, cost #2 gets worse —there is no natural place for named queries to live— and the coupling moves from the type to the call site: the service invokes the client directly.

DDD and CQRS templates. Hexagonal boilerplates and @nestjs/cqrs do show the port-and-adapter structure, and in that sense they point at the right problem. The limitation is one of scope: most stop at a demonstration CRUD over a single entity, where the pattern is trivially applicable. The three questions that show up from the third module onwards —how two different repositories share a transaction, who translates between entity and model, and how the implementation is substituted in a test— tend to fall outside the example.

Laid out in a table against the three costs, the split looks like this:

Tool	1. The entity is the table	2. Unnamed queries	3. Verifying without a database
Nest's documented path	Does not address it	Does not address it	Does not address it
Active Record	Makes it worse: the class also knows how to connect	Does not address it	Does not address it
Extended repositories (`.extend()`)	Does not address it: returns the model	Solved: the query has an owner	Does not address it
MikroORM	Does not address it: decorated entities	Solved: its own `EntityRepository`	Partial: the usual answer is running against in-memory SQLite, which is still a database
Prisma	Neutral by absence: no business class to contaminate	Makes it worse: nowhere to put them	Does not address it
DDD/CQRS templates	Solved in the example	Solved in the example	Solved in the example

Note: the three marks in the last row carry the same caveat, and it is a large one: they are solved over a single-entity CRUD. There is also a column the table does not have, because it is not one of the three initial costs but what shows up right after them —the transaction shared across several repositories—, and there only MikroORM brings an out-of-the-box answer. The table measures what each tool addresses, not how it behaves once the module grows.

The summary is that the ecosystem has the wiring solved, has transaction management solved in at least one implementation, and the available literature on ports and adapters rarely gets past the interface and its implements. The gap is not in the definition of the pattern, but in how it behaves under the conditions that make it necessary.

The justification worth discarding

The reason most often given for introducing repositories is infrastructure independence: if the domain only knows an interface, changing ORM does not force you to touch it. The argument is logically sound; what is worth measuring is the size of the benefit it promises.

If the migration does happen, the adapters are rewritten entirely, the shared-transaction mechanism is rewritten too —it depends on the specific EntityManager and QueryRunner— and the persistence models are redone from scratch. The only thing that survives intact is the port: ten lines with no dependencies, the cheapest file in the module to rewrite. The pattern localises the migration, it does not make it cheap: what is saved is the cheap part. And that benefit is collected once, in an event that in most projects never arrives, while the cost —an interface, a mapper and a separate model per entity— is paid on every entity added.

If that were the main benefit, the reasonable conclusion would be not to apply the pattern. It is worth discarding explicitly because, while it stands, it occupies the place of the useful question: what does the project gain today. And that answer is the three inverses of the costs above —an entity that can demand its invariants, a query with a single owner, a rule verifiable in milliseconds—, which are collected on every working day and not in a hypothetical migration.

The thesis

The original definition of the pattern, in the Patterns of Enterprise Application Architecture catalogue, predates this debate and mentions portability nowhere:

"Mediates between the domain and data mapping layers using a collection-like interface for accessing domain objects."

The operative term there is collection-like. Fowler develops it in the next line: objects are added to and removed from the repository as they would be from a plain collection, and the mapping code the repository encapsulates carries out the appropriate operations behind the scenes. A collection has a membership interface —what is inside, how something is found, what gets added— and no notion of storage whatsoever.

From there comes the formulation that carries the rest of this article:

A repository is not a layer on top of the database: it is a collection of your domain that happens to live in one.

The difference between the two readings is not rhetorical; it determines different things when writing the code. If the repository is a layer on top of the database, its methods are named after what the engine does and its types are the row's, because the goal is to give orderly access to the table. If it is a collection of domain objects, its methods are named after what the business looks for and its types are the domain's, because storage is an implementation detail that stays on the other side.

Two pieces follow from that formulation, and they take up the rest of the article:

The port is a TypeScript interface with no decorators, no Nest dependencies and no ORM dependencies, written in business vocabulary, whose input and output types are domain entities and never persistence models.
The adapter is the only piece in the module that knows TypeORM, and its job is to translate in both directions.

The rest —how two repositories share a transaction, how the implementation is substituted in a test— are consequences of those two definitions, and that is where the pattern is put to the test.

The minimum contract: the port

The port is the whole file, not an excerpt:

// src/order/domain/repositories/order.repository.ts
import { Order } from '../entities/order.entity';

export interface OrderRepository {
  create(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
  findByReference(reference: string): Promise<Order | null>;
  findPendingByCustomer(customerId: string): Promise<Order[]>;
  update(order: Order): Promise<void>;
}

It has a single import, and it points at the domain itself. There is nothing from @nestjs/common, nothing from typeorm, and no decorators; the file compiles with the project's dependencies uninstalled. That is a checkable property, and it is what defines the boundary: whatever this file does not mention is what the domain cannot know.

The input and output types are Order, the entity, and not OrderModel. That is the difference with the extended repositories from the previous section: .extend() also let you name the query, but it returned the row. Naming without changing the type solves half the problem.

findPendingByCustomer is cost #2 in its solved form. The definition of "pending" comes to have a single place where it lives, and modifying it means modifying one method whose change the compiler propagates to every caller. The comparison with the three divergent literals earlier is direct: that was a coincidence between copies, this is a declaration.

Two observations about what the port does not have. There is no generic method —no findAll(options), no query(), nothing that takes arbitrary criteria—: every entry answers a concrete need, and the port grows on business demand rather than in anticipation. And lookups return Order | null: the port reports the absence, it does not decide what to do about it. Turning "does not exist" into an error —a domain exception, a 404— is the caller's job, because the caller is the one who knows the context.

The entity is not the table

Cost #1 is solved by splitting into three files what used to be one. Each has a single consumer and therefore a single set of requirements.

The domain entity is no longer instantiated by the ORM, and that is exactly what gives it back the ability to demand:

// src/order/domain/entities/order.entity.ts
interface Props {
  id: string;
  customerId: string;
  reference: string;
  status: OrderStatus;
  lines: OrderLine[];
}

export class Order {
  readonly id: string;
  readonly customerId: string;
  readonly reference: string;
  status: OrderStatus;
  lines: OrderLine[];

  constructor(props: Props) {
    this.id = props.id;
    this.customerId = props.customerId;
    this.reference = props.reference;
    this.status = props.status;
    this.lines = props.lines;
  }

  confirm(): void {
    if (this.lines.length === 0) {
      throw new EmptyOrderException(this.reference);
    }
    this.status = OrderStatus.CONFIRMED;
  }

  total(): number {
    return this.lines.reduce((sum, line) => sum + line.subtotal(), 0);
  }
}

The constructor has required parameters, which is precisely what TypeORM's documentation forbids in an entity of its own. The class has no createdAt, no deletedAt, and no raw FK living next to its relation; it has the data the business needs and the methods that operate on it. The invariant in confirm() is still a check, but now it sits in the only place that can change the state, instead of being repeated in every service that confirms an order.

The persistence model is the decorated class from the first cost under another name, and with a different expectation attached: it is no longer expected to hold rules.

// src/order/infrastructure/typeorm/models/order.model.ts
@Entity('order')
export class OrderModel {
  @PrimaryColumn('varchar', { length: 26 }) id: string;
  @Column() customerId: string;
  @Column() reference: string;

  @Column({ type: 'enum', enum: OrderStatus })
  status: OrderStatus;

  @OneToMany(() => OrderLineModel, (line) => line.order, { cascade: true })
  lines: OrderLineModel[];

  @CreateDateColumn() createdAt: Date;
  @DeleteDateColumn() deletedAt: Date | null;
}

Being anemic stopped being a flaw: it describes a row, and a row has no behaviour. The audit columns, the raw FKs and the driver-imposed types live here without contaminating anything, because their only consumer is the ORM.

The mapper is the translation, and it concentrates decisions that used to be scattered:

// src/order/infrastructure/typeorm/mappers/order.mapper.ts
export class OrderMapper {
  static toDomain(model: OrderModel): Order {
    return new Order({
      id: model.id,
      customerId: model.customerId,
      reference: model.reference,
      status: model.status,
      lines: OrderLineMapper.toDomainList(model.lines ?? []),
    });
  }

  static toDomainList(models: OrderModel[]): Order[] {
    return models.map((model) => this.toDomain(model));
  }

  static toModel(entity: Order): OrderModel {
    const model = new OrderModel();
    model.id = entity.id;
    model.customerId = entity.customerId;
    model.reference = entity.reference;
    model.status = entity.status;
    model.lines = entity.lines.map(OrderLineMapper.toModel);
    return model;
  }
}

Every row entering the domain goes through toDomain, so the conversions that used to be scattered across the services now have a single location: the numeric the driver hands over as a string is converted to number, inside OrderLineMapper, over each line's price.

status, on the other hand, is not converted: it is assigned. It is worth pausing on why, because the alternative is a common mistake. If the column were a free varchar, the type of model.status would be string and the mapper would have to resolve the mismatch somehow: with model.status as OrderStatus, which is an assertion and checks nothing, or with a type guard validating on every read. The second option is correct but it is paying at runtime, row by row, for a guarantee the schema can give for free. By declaring the column as an enum, the constraint lives in the database, model.status is already of type OrderStatus, and there is nothing to assert and nothing to check.

The difference with customer: Customer from the first cost is exactly that. There the type asserted something the value could fail to honour; here the type is true because there is a constraint behind it holding it up. A type is only worth as much as the guarantee backing it, and validating in the mapper against a schema that does not constrain is treating the symptom.

Note: the model.lines ?? [] is the problem from the opening of this article coming back. If the query did not ask for the relation, the mapper builds an order with no lines and the invariant in confirm() is inverted again without anything failing. The difference from the starting point is not that the risk disappears: it is that the query is now written in a single place —the adapter—, so the guarantee is established once instead of depending on every caller.

The cost deserves stating in the same place as the benefit: it is three files per entity instead of one, and the mapper has to be maintained by hand. The compiler helps in one direction only —a new required field in Props breaks toDomain until you add it—, but a new column in the model forces nothing, so an incomplete mapping is an error the tooling does not catch.

The adapter: the only piece that knows the ORM

The adapter implements the port and concentrates everything the domain stopped knowing:

// src/order/infrastructure/typeorm/repositories/typeorm-order.repository.ts
@Injectable()
export class TypeOrmOrderRepository implements OrderRepository {
  constructor(
    @InjectRepository(OrderModel)
    private readonly repository: Repository<OrderModel>,
  ) {}

  async create(order: Order): Promise<void> {
    await this.repository.save(OrderMapper.toModel(order));
  }

  async findById(id: string): Promise<Order | null> {
    const model = await this.repository.findOne({
      where: { id },
      relations: { lines: true },
    });
    return model ? OrderMapper.toDomain(model) : null;
  }

  async findPendingByCustomer(customerId: string): Promise<Order[]> {
    const models = await this.repository.find({
      where: { customerId, status: OrderStatus.PENDING },
      relations: { lines: true },
    });
    return OrderMapper.toDomainList(models);
  }

  async update(order: Order): Promise<void> {
    await this.repository.save(OrderMapper.toModel(order));
  }
}

@InjectRepository(OrderModel) is the very line this article started with. It did not disappear and it was not replaced by anything: it moved. The pattern does not reject NestJS's documented path, it confines it to the class where that knowledge is legitimate.

Every method has the same shape —query and translation— and none contains a business decision. That gives a review criterion that needs no debate: if an if that inspects an order's state to decide something shows up here, it is in the wrong file.

relations: { lines: true } appears twice, and that repetition is the residue of what, at the opening of the article, was scattered across every service. It is still repetition, but it is local now: it fits on one screen and can be audited by reading one file.

create and update are both resolved with save, which does what it always did —decide between insert and update based on the primary key—. The difference is where that ambiguity lives: the port declares two operations because the business distinguishes creating from updating, and that the implementation resolves both with the same call is a detail that need not surface in the name.

The wiring

A TypeScript interface does not exist at runtime, so it cannot serve as an injection token. An explicit one is needed, declared next to the port:

// src/order/domain/repositories/order.repository.ts
export const ORDER_REPOSITORY = Symbol('OrderRepository');

And the module associates the token with the implementation:

// src/order/order.module.ts
@Module({
  imports: [TypeOrmModule.forFeature([OrderModel, OrderLineModel])],
  providers: [
    ConfirmOrderService,
    { provide: ORDER_REPOSITORY, useClass: TypeOrmOrderRepository },
  ],
})
export class OrderModule {}

This line is where it is decided which implementation the domain receives, and it is the only one that would need touching to swap it. It is also the reason the consumer needs an explicit @Inject, which was not necessary when it injected a class.

The service, again

With the pieces in place, the method from the beginning of the article ends up like this:

@Injectable()
export class ConfirmOrderService {
  constructor(
    @Inject(ORDER_REPOSITORY)
    private readonly orders: OrderRepository,
  ) {}

  async execute(orderId: string): Promise<void> {
    const order = await this.orders.findById(orderId);
    if (!order) throw new OrderNotFoundException(orderId);

    order.confirm();
    await this.orders.update(order);
  }
}

The behaviour is the same as at the start. What changed is the distribution of knowledge, and it is worth going back over the opening inventory to check it point by point: there is no where here, no relations that a rule's correctness depends on, no save with its ambiguity, and no table vocabulary. The lines invariant is no longer in this file: it is in order.confirm(), the only place capable of changing the order's state.

One absence if remains, and it stays deliberately. It is not a response to findOne returning null, but to the port declaring Promise<Order | null> as part of its contract: the repository reports that the order is not there, and this service decides that this is a business error. The check is the same; its cause is not.

Up to here the pattern holds on one entity and one operation. The real test arrives when the operation touches two.

The shared transaction

Confirming an order also draws down stock — the rule from the third cost enters the picture. The service now uses two ports:

async execute(orderId: string): Promise<void> {
  const order = await this.orders.findById(orderId);
  if (!order) throw new OrderNotFoundException(orderId);

  order.confirm();

  for (const line of order.lines) {
    const stock = await this.inventory.findByProduct(line.productId);
    if (!stock) throw new ProductNotFoundException(line.productId);
    stock.reserve(line.quantity); // throws InsufficientStockException if it does not add up
    await this.inventory.update(stock);
  }

  await this.orders.update(order);
}

The writes are several and the requirement is one: either all of them land or none does. If reserve throws on the order's third line, the two previous reservations cannot stay written.

The problem has a precise shape. In TypeORM, a transaction is a specific EntityManager —the one belonging to the QueryRunner that opened it—, and every query that wants to take part must run through it. The transaction is opened at the edge, in the controller, because the use case is what defines the scope of atomicity. But the queries run two layers below, in the adapters. That manager has to travel from the edge down to the adapters, and there are only two routes.

The first is passing it as a parameter. What it forces is immediately visible:

export interface OrderRepository {
  findById(id: string, manager?: EntityManager): Promise<Order | null>;
  update(order: Order, manager?: EntityManager): Promise<void>;
  // ...
}

The port —the file that compiled without TypeORM— now imports EntityManager, and every domain signature carries a parameter the business cannot explain. The contamination the pattern showed out the door comes back through the signature, and not into one file: into every method of every port that takes part in any transaction.

The second route is for the manager to travel not through the signatures but through the execution context. Node has a standard mechanism for exactly this: AsyncLocalStorage, a store bound to the async chain in flight. Anything running inside storage.run(value, fn) —at any depth of await— can read value with storage.getStore(), without any intermediary carrying it. It is the same mechanism used to propagate request context for logging, and also the one libraries like typeorm-transactional package up; here it is used directly, because it fits in a short file and it is worth seeing what is inside.

The piece that encapsulates it is an executor:

// src/shared/infrastructure/typeorm/transaction.executor.ts
@Injectable()
export class TransactionExecutor {
  private static readonly storage = new AsyncLocalStorage<EntityManager>();

  constructor(private readonly dataSource: DataSource) {}

  async execute<T>(work: () => Promise<T>): Promise<T> {
    const queryRunner = this.dataSource.createQueryRunner();
    await queryRunner.connect();
    await queryRunner.startTransaction();

    try {
      return await TransactionExecutor.storage.run(
        queryRunner.manager,
        async () => {
          const result = await work();
          await queryRunner.commitTransaction();
          return result;
        },
      );
    } catch (err) {
      await queryRunner.rollbackTransaction();
      throw err;
    } finally {
      await queryRunner.release();
    }
  }

  getManagerIfActive(): EntityManager | null {
    return TransactionExecutor.storage.getStore() ?? null;
  }
}

execute opens the QueryRunner, runs the work inside storage.run with the transactional manager as the value, commits if the work completed and rolls back if it threw. The domain exception thereby acquires a second function without knowing it: InsufficientStockException was the way to reject an invalid reservation, and now it is also the transaction's abort signal. The business error and the rollback end up unified without either side knowing about the other.

The counterpart lives in the adapter, and it is three lines:

private getRepository(): Repository<OrderModel> {
  const manager = this.transactionExecutor.getManagerIfActive();
  return manager ? manager.getRepository(OrderModel) : this.repository;
}

Every adapter method queries through this.getRepository() instead of this.repository. If there is a transaction active in the context, it takes part in it; if there is not, it uses the injected repository and the query runs standalone, as before. The adapter works the same inside and outside a transaction, and it is the same class in both cases.

With both pieces in place, the edge looks like this:

@Post(':id/confirm')
async confirm(@Param('id') id: string): Promise<void> {
  return this.transactionExecutor.execute(() =>
    this.confirmOrder.execute(id),
  );
}

And this is the result the section had to demonstrate: the domain service performs all its writes —one per order line, plus the order's own— atomically and contains no reference to the transaction at all. It takes no manager, imports no TypeORM, and does not know the controller wrapped it in anything. The port still compiles with no dependencies. Atomicity was decided at the edge, the mechanism lives in infrastructure, and the domain ended up between the two without learning about either.

Note: the agreement between the executor and the adapters is invisible to the compiler. Nothing in the OrderRepository type forces an implementation to consult getManagerIfActive(): an adapter using this.repository directly compiles just the same, runs outside the transaction, and its writes survive the rollback. It is the most fragile point of the mechanism —a team convention, not a typed contract— and it is worth protecting where you can: in code review, and in the integration test that verifies a failure reverts every write.

Two ways to wire the port

The token-based wiring from the adapter section is the canonical form in Nest, but not the only one compatible with the pattern. The alternative is not registering the port in the container at all: the module registers the concrete classes, and the controller —which receives them by injection— composes the domain service by hand in each endpoint:

@Post(':id/confirm')
async confirm(@Param('id') id: string): Promise<void> {
  return this.transactionExecutor.execute(() => {
    const confirmOrder = new ConfirmOrderService(
      this.orderRepository,
      this.inventoryRepository,
    );
    return confirmOrder.execute(id);
  });
}

A new inside a framework built around the container raises suspicion, so it is worth fixing the invariant both forms share: the ConfirmOrderService constructor still declares OrderRepository, the interface, and the compiler checks at the new exactly what it was checking at the useClass. The pattern's boundary is respected identically; the only thing that changes is who performs the composition. As a side effect, the domain service loses its last two decorators —@Injectable, @Inject— and the domain/ folder ends up with not a single framework import; in exchange, swapping the implementation stops being a one-line change and the composition is repeated per endpoint.

For this article that is enough: the pattern works the same with either wiring, and everything above —port, adapter, transaction— is independent of which one you pick.

Note: manual composition is not an isolated decision: it is part of a way of structuring the project —use cases as classes, composition at the edge, what exactly the application layer does— that needs more room than it deserves here. That is for an article of its own.

The test that is now possible

Cost #3 demanded four things unrelated to the rule in order to verify it: the database, the schema, the fixtures and the isolation. With the port in between, the test implementation is a class that implements it with stubs:

// tests/unit/order/mocks/mock-inventory-repository.ts
export class MockInventoryRepository implements InventoryRepository {
  findByProduct = vi.fn<(productId: string) => Promise<Inventory | null>>();
  update = vi.fn<(inventory: Inventory) => Promise<void>>();
}

Its twin for OrderRepository has the same shape, and the stock rule's test reads in full like this:

it('rejects the confirmation when stock is insufficient', async () => {
  const orders = new MockOrderRepository();
  const inventory = new MockInventoryRepository();

  const order = new Order({
    id: 'order-1',
    customerId: 'customer-1',
    reference: 'ORD-001',
    status: OrderStatus.PENDING,
    lines: [
      new OrderLine({
        id: 'line-1',
        productId: 'product-1',
        quantity: 5,
        unitPrice: 100,
      }),
    ],
  });
  orders.findById.mockResolvedValue(order);
  inventory.findByProduct.mockResolvedValue(
    new Inventory({ productId: 'product-1', available: 3 }),
  );

  const service = new ConfirmOrderService(orders, inventory);

  await expect(service.execute('order-1')).rejects.toThrow(InsufficientStockException);
  expect(inventory.update).not.toHaveBeenCalled();
  expect(orders.update).not.toHaveBeenCalled();
});

Not one of the four things is left: the starting state is built by calling constructors —the same ones that already demand their parameters—, and the test runs in milliseconds. The edge cases the third cost flagged as the ones that "tend not to get written" are now copies of this test with one number changed: the exact boundary, zero on hand, one over. Their marginal cost is close to zero, which was what it took for them to exist at all.

Two details carry the weight. The implements InventoryRepository is not decorative: when the port grows a method, every mock stops compiling until it is updated — the contract keeps the test doubles in sync with no extra discipline. And the last two assertions verify what cost #3 could not even express with the database in the way: that the rejection happens before any write.

What this test does not cover is worth saying too: not the adapter's SQL, not the mapper, not the transaction. Those pieces are verified with integration tests, which still need the database — but there are few of them now and they test infrastructure, while the rules, which are many, are tested here.

Two honest caveats

The executor's scope can propagate. The TransactionExecutor in this article is a singleton and can stay one: its only state, the AsyncLocalStorage, is static. But in production that class tends to accumulate per-request responsibilities —auditing is the typical one: recording which user ran the transaction— and the day it declares Scope.REQUEST for that, the scope propagates transitively: every adapter injecting it becomes request-scoped, and so does anything injecting one of those adapters. The measurable consequence shows up in cron jobs: @nestjs/schedule does not register @Cron handlers defined in non-static providers — it leaves a WARN at boot and the job simply never runs. It is a silent failure of the expensive kind: nothing throws, nothing retries, and the signal is the absence of something. There are two known ways out: resolving the repository inside the handler with ModuleRef instead of injecting it through the constructor, or keeping the executor free of per-request dependencies so the propagation never starts.

This is not a Unit of Work. The mechanism in the transaction section shares one transaction between repositories, and that is all it does. There is no identity map: two findById calls for the same order within the same transaction return two distinct objects in memory, and if both are modified and persisted, the last write silently overwrites the first. There is no deferred writing either: each update runs its SQL when called, not in a final flush. MikroORM offers both out of the box, as noted in the state of the art; with this pattern, the equivalent discipline is a design one: each use case loads an entity once and passes the instance around, instead of looking it up again.

Who this is for (and who it is not for)

The pattern's total cost was spread across the article and is worth adding up here: three files and a mapper per entity, a transaction executor, an untyped agreement between executor and adapters, and two operational caveats. That cost is paid on every new entity, so the adoption question is which projects see a return that outweighs it.

There are projects where it does not. A single-module CRUD, an MVP looking for a market, an internal back office where the rules are "save whatever arrived": there the three coupling costs never materialise —there are no invariants to protect, there are no repeated queries because there are few queries, and rule tests do not exist because there are barely any rules—. In those projects, @InjectRepository straight into the service is the correct answer, and this pattern is ceremony with no return.

The conditions that flip the balance are the ones this article has been using from the start: real invariants —money, states, stock—, writes that cross several tables and must be atomic, rules you want verified in milliseconds, and a team large enough that "where does this query live" needs an answer that does not depend on who wrote it. With two or more of those present, every piece of the pattern is paying for something concrete; with none, all of them are dead weight.

For the module sitting on the fence, the rule of thumb that sums up the article fits in one line: if someone from the business would understand the method name, it belongs to the port; if it describes what the engine does, it belongs to the adapter.

The code

All of the above lives in a runnable project: nestjs-repository-pattern.

A single use case —confirming an order, which draws down stock—, because it is the minimum that forces the interesting problem into the open: two repositories writing inside the same transaction without the domain knowing. It comes up with docker compose up -d && npm run dev, and the ten business-rule tests run in seven milliseconds with no database.

That leaves the closing, which is the thesis seen from the end. The ORM and this pattern are not competing, because they do not answer the same question: TypeORM solves how to talk to the database —connections, SQL, row mapping—, and it solves it well. The pattern solves where the business knowledge lives and how much it knows about the database — which is a question the ORM has no reason to answer. They are different layers. The collection of your domain needs both: one to be a collection, the other to live somewhere.

Let's talk

Questions, feedback, or a different take? I'd love to hear from you. You can find me here:

GitHub — hgomezrobaina
LinkedIn — Héctor Gómez Robaina
X — @hgomezrobaina

El patrón Repository en NestJS: una colección que, casualmente, vive en una base de datos

Hector Angel Gomez Robaina — Sat, 15 Aug 2026 19:02:33 +0000

El punto de partida canónico de un módulo de NestJS con TypeORM es el que documenta el propio framework: el módulo declara TypeOrmModule.forFeature([Order]) y el servicio recibe el repositorio por inyección.

@Injectable()
export class OrderService {
  constructor(
    @InjectRepository(Order) private readonly repo: Repository<Order>,
  ) {}
}

A partir de ahí el servicio dispone de find, findOne, save y delete, y puede escribir la primera regla de negocio sin más andamiaje. Es el camino con menos fricción y el mejor documentado, y por eso es el que aparece en la mayoría de las bases de código.

El código que acaba viviendo dentro de ese servicio tiene esta forma:

async confirm(orderId: string): Promise<Order> {
  const order = await this.repo.findOne({
    where: { id: orderId, status: 'pending' },
    relations: { lines: true },
  });

  if (!order) throw new NotFoundException('Order not found');
  if (order.lines.length === 0) {
    throw new BadRequestException('Cannot confirm an order without lines');
  }

  order.status = 'confirmed';
  return this.repo.save(order);
}

El método es correcto: hace lo que promete, es legible y puede sostener años de producción sin incidentes. Lo que interesa analizar no es su comportamiento, sino su superficie de acoplamiento. Dentro hay una regla de negocio —un pedido no se puede confirmar si no tiene líneas— y conviene medir qué conocimiento del motor de persistencia quedó incorporado en ella.

El inventario es más largo de lo que parece a simple vista:

La regla depende de cómo se cargó la fila. El invariante se evalúa sobre order.lines, y esa colección solo existe si la consulta pidió la relación explícitamente. Si relations: { lines: true } desaparece en un refactor, order.lines llega vacío, la comprobación se dispara cuando no debe y el invariante queda invertido sin que nada falle: no hay error de compilación, no hay excepción, no hay traza. La corrección de la regla es una propiedad de la consulta, no de la regla.
La condición de negocio está expresada en vocabulario de tabla. "Pendiente" no es un concepto del dominio en este código; es el string 'pending' comparado contra una columna dentro de un objeto where.
El control de flujo lo dicta la API del ORM. El primer if existe porque findOne devuelve null; es una decisión de TypeORM, no del negocio.
La semántica de escritura es implícita. save resuelve por sí mismo si la operación es un INSERT o un UPDATE según el estado de la clave primaria. El servicio hereda esa ambigüedad.
La clase de negocio es la definición del esquema. Order —donde vivirán el cálculo del total y las transiciones de estado— es la misma clase que lleva los decoradores @Column que describen la tabla.

Los cuatro primeros puntos son molestias de acoplamiento: incómodas, pero locales y reversibles. El quinto es de otra naturaleza. No es una consecuencia de cómo se escribió este método, sino de una decisión estructural —que el modelo de negocio y el modelo de persistencia sean el mismo objeto— que el proyecto adoptó sin deliberarla, por seguir el camino documentado.

Ese acoplamiento no tiene coste observable mientras el módulo se mantenga en operaciones de una sola entidad sobre una sola tabla. Se vuelve medible cuando aparecen tres condiciones que casi cualquier dominio real acaba cumpliendo: que la entidad acumule invariantes propios, que una consulta con significado de negocio se necesite desde más de un lugar, y que haga falta verificar una regla sin depender de la base de datos.

Cada una de las tres produce un coste distinto, y conviene examinarlas por separado.

Tres costes del acoplamiento

1. La entidad de negocio es la definición de la tabla

La clase Order atiende a dos consumidores con requisitos incompatibles. El negocio necesita un objeto que solo pueda existir en estados válidos y que exprese sus conceptos con precisión. El ORM necesita un objeto que refleje la fila y que él pueda construir sin conocer nada del negocio. Cuando ambos consumidores comparten la misma clase, el resultado es este:

@Entity('order')
export class Order {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column()
  customerId: string;

  @ManyToOne(() => Customer)
  customer: Customer;

  @Column({ type: 'varchar', default: 'pending' })
  status: string;

  @Column({ type: 'numeric', precision: 12, scale: 2 })
  total: string;

  @OneToMany(() => OrderLine, (line) => line.order)
  lines: OrderLine[];

  @CreateDateColumn() createdAt: Date;
  @UpdateDateColumn() updatedAt: Date;
  @DeleteDateColumn() deletedAt: Date | null;
}

La contaminación va en las dos direcciones, y hay una tercera consecuencia que no es de tipos sino de construcción.

De la persistencia hacia el dominio. createdAt, updatedAt y deletedAt son requisitos de infraestructura —auditoría y borrado lógico— que ninguna regla de negocio consulta, pero que forman parte del tipo con el que trabaja todo el módulo. Más relevante: customerId y customer son dos representaciones del mismo hecho conviviendo en el mismo objeto, sin garantía de que estén sincronizadas. Y customer está declarada como Customer, no como Customer | undefined, aunque su valor sea undefined siempre que la consulta no haya pedido la relación. El tipo afirma algo que el valor no cumple, y strictNullChecks no puede detectarlo porque la propiedad está declarada como presente.

Del dominio hacia la persistencia. total está tipado como string porque el driver de PostgreSQL devuelve las columnas numeric como cadena para no perder precisión en el number de JavaScript. Es una decisión correcta del driver y una filtración para el negocio: el importe de un pedido es un número, y aquí cualquier cálculo sobre él exige convertirlo primero, en cada sitio donde se calcule. Corregirlo dentro de la propia clase es posible con un transformer de columna, pero eso deja la representación de un concepto de negocio condicionada a lo que el ORM sabe serializar.

El constructor no puede exigir nada. La documentación de TypeORM lo establece explícitamente: los argumentos del constructor de una entidad deben ser opcionales, porque el ORM instancia la clase al materializar cada fila y desconoce esos argumentos. La consecuencia es que la clase no puede garantizar su propio invariante en construcción. new Order() —sin cliente, sin líneas y sin estado— es válido para el compilador y para el ORM. El invariante "un pedido confirmado tiene al menos una línea" no puede ser una propiedad del tipo; solo puede ser una comprobación repetida en cada método que la necesite, que es exactamente lo que hacía confirm() en el ejemplo anterior. La clase queda estructuralmente incapacitada para sostener un estado siempre válido.

2. Las consultas no tienen nombre

"Los pedidos pendientes de un cliente" es un concepto del negocio: tiene una definición, y esa definición puede cambiar. En el código no existe como unidad. Existe como un objeto literal replicado en cada sitio que lo necesita:

// order.service.ts
where: { customerId, status: 'pending' }

// notification.service.ts
where: { customerId, status: In(['pending', 'awaiting_payment']) }

// report.service.ts
where: { customerId, status: 'pending' }, relations: { lines: true }

Las tres pretenden expresar el mismo concepto y las tres divergen. Ninguna está marcada como canónica, así que leyendo el código no hay forma de saber cuál es la definición correcta, y el compilador acepta las tres: la divergencia es semántica, no de tipos. La tercera, además, devuelve entidades con otra forma, porque relations cambia qué llega poblado; una regla que dependa de order.lines se comporta distinto según el punto de entrada.

El coste se cobra cuando la definición de "pendiente" cambia: es proporcional al número de copias, y no hay procedimiento fiable para enumerarlas —buscar el literal 'pending' falla en cuanto alguien lo extrajo a una constante o lo recibió como parámetro—.

3. La regla no se puede verificar sin base de datos

Para ejecutar un test sobre "no se puede reservar más unidades de las que hay en stock" hacen falta cuatro elementos ajenos a la regla: una instancia de PostgreSQL, el esquema migrado, fixtures que dejen la fila en el estado inicial y un mecanismo de aislamiento entre casos.

El test cubre entonces mucho más de lo que pretende. Cuando falla, la causa puede estar en la regla, en el mapeo de columnas, en una migración pendiente o en el estado que dejó otro caso: la señal no localiza el defecto. Y el ciclo pasa del orden de los milisegundos al de los segundos, multiplicado por el número de casos —una regla de stock tiene bastantes: el límite exacto, uno por encima, existencias en cero, dos reservas concurrentes—.

El efecto de segundo orden es el más caro. Una suite lenta se ejecuta con menos frecuencia, y los casos límite incómodos de montar tienden a no escribirse: el coste no está solo en los tests que tardan, sino en los que no llegan a existir.

Los tres costes tienen el mismo origen: no hay ninguna frontera entre el objeto que expresa el negocio y el objeto que describe la fila. Antes de proponer una, conviene revisar qué ofrece el ecosistema, porque las herramientas disponibles no atacan todas el mismo problema.

Estado del arte: qué resuelve cada opción

El camino documentado de NestJS. @InjectRepository(Order) inyecta un Repository<Order> construido por el DataSource. Lo que resuelve es el cableado: la conexión, el pool, el ciclo de vida y la inyección. Es una solución completa para ese problema, y no pretende ser otra cosa. Sobre la propiedad del modelo no se pronuncia: el tipo que entrega es el mismo que define la tabla.

Active Record. TypeORM ofrece la alternativa de heredar de BaseEntity, con lo que la clase adquiere sus propias operaciones de persistencia:

const order = await Order.findOneBy({ id });
await order.save();

Elimina la ceremonia de la inyección y, a cambio, lleva el acoplamiento al máximo posible: la clase de negocio no solo describe la tabla, además sabe conectarse a ella. Los tres costes de la sección anterior se mantienen y se les suma la imposibilidad de instanciar la clase fuera de un contexto con DataSource inicializado.

Repositorios personalizados. Es la respuesta de TypeORM al coste nº 2: darle a la consulta con nombre un lugar propio, extendiendo la instancia del repositorio.

const OrderRepository = dataSource.getRepository(Order).extend({
  findPendingByCustomer(customerId: string) {
    return this.findBy({ customerId, status: 'pending' });
  },
});

Con esto la consulta pasa a tener un único dueño, que era el problema del coste nº 2. Los otros dos quedan intactos: el objeto se construye a partir del DataSource en lugar de por inyección —lo que obliga a registrarlo como provider con una factoría propia— y, sobre todo, el tipo que devuelven sus métodos sigue siendo el modelo de persistencia.

MikroORM. Es la opción que más lejos llega de fábrica y conviene decirlo sin matizarlo: implementa Data Mapper, Unit of Work e Identity Map de forma nativa. El EntityManager rastrea los objetos cargados, resuelve por identidad —dos búsquedas por la misma clave primaria devuelven la misma instancia— y agrupa los cambios pendientes en una transacción implícita al llamar a flush(). Es decir, resuelve por diseño el problema que ocupa la sección más larga de este artículo. Lo que no resuelve es el coste nº 1: sus entidades siguen siendo clases decoradas que describen la tabla, de modo que la frontera entre el modelo de negocio y el de persistencia sigue siendo trabajo de quien escribe el código.

Prisma. No hay repositorios ni entidades en el sentido anterior: se inyecta el cliente y los tipos generados son las filas, estructuras de datos planas sin comportamiento. El efecto sobre el coste nº 1 es ambivalente: no existe una clase de negocio que se pueda contaminar, porque directamente no existe la clase, así que cualquier modelo de dominio nace separado. A cambio, el coste nº 2 se agrava —no hay ningún sitio natural donde vivan las consultas con nombre— y el acoplamiento se desplaza del tipo a la llamada: el servicio invoca al cliente directamente.

Plantillas DDD y CQRS. Los boilerplates hexagonales y @nestjs/cqrs sí muestran la estructura de puerto y adaptador, y en ese sentido apuntan al problema correcto. La limitación es de alcance: la mayoría se detiene en un CRUD de demostración de una sola entidad, donde el patrón es trivialmente aplicable. Las tres preguntas que aparecen a partir del tercer módulo —cómo comparten transacción dos repositorios distintos, quién traduce entre entidad y modelo, y cómo se sustituye la implementación en un test— suelen quedar fuera del ejemplo.

Puesto en una tabla contra los tres costes, el reparto queda así:

Herramienta	1. La entidad es la tabla	2. Consultas sin nombre	3. Verificar sin base de datos
Camino documentado de Nest	No lo aborda	No lo aborda	No lo aborda
Active Record	Lo agrava: la clase además sabe conectarse	No lo aborda	No lo aborda
Repositorios extendidos (`.extend()`)	No lo aborda: devuelve el modelo	Resuelto: la consulta tiene un dueño	No lo aborda
MikroORM	No lo aborda: entidades decoradas	Resuelto: `EntityRepository` propio	Parcial: lo habitual es correr contra SQLite en memoria, que sigue siendo una base de datos
Prisma	Neutro por ausencia: no hay clase de negocio que contaminar	Lo agrava: no hay dónde ubicarlas	No lo aborda
Plantillas DDD/CQRS	Resuelto en el ejemplo	Resuelto en el ejemplo	Resuelto en el ejemplo

Nota: las tres marcas de la última fila llevan la misma reserva, y es grande: están resueltas sobre un CRUD de una sola entidad. Hay además una columna que la tabla no tiene, porque no es uno de los tres costes iniciales sino lo que aparece justo después —la transacción compartida entre varios repositorios—, y ahí solo MikroORM trae una respuesta de fábrica. La tabla mide qué aborda cada herramienta, no cómo se comporta cuando el módulo crece.

El resumen es que el ecosistema tiene resuelto el cableado, tiene resuelta la gestión transaccional en al menos una implementación, y la literatura disponible sobre puertos y adaptadores rara vez pasa del interface con su implements. El hueco no está en la definición del patrón, sino en su comportamiento bajo las condiciones que lo hacen necesario.

La justificación que conviene descartar

La razón que se ofrece con más frecuencia para introducir repositorios es la independencia de la infraestructura: si el dominio solo conoce una interfaz, cambiar de ORM no obliga a tocarlo. El argumento es correcto en su lógica; lo que conviene medir es el tamaño del beneficio que promete.

Si la migración llega a ocurrir, los adaptadores se reescriben por completo, el mecanismo de transacción compartida también —depende del EntityManager y del QueryRunner concretos— y los modelos de persistencia se rehacen enteros. Lo único que sobrevive intacto es el puerto: diez líneas sin dependencias, el archivo más barato de reescribir del módulo. El patrón localiza la migración, no la abarata: lo que se salva es lo barato. Y ese beneficio se cobra una sola vez, en un evento que en la mayoría de los proyectos no llega a ocurrir, mientras el coste —una interfaz, un mapper y un modelo aparte por entidad— se paga en cada entidad que se añade.

Si ese fuera el beneficio principal, lo razonable sería no aplicar el patrón. Conviene descartarlo de forma explícita porque, mientras siga en pie, ocupa el lugar de la pregunta útil: qué gana el proyecto hoy. Y esa respuesta son los tres inversos de los costes anteriores —una entidad que puede exigir sus invariantes, una consulta con dueño único, una regla verificable en milisegundos—, que se realizan en cada jornada de desarrollo y no en una migración hipotética.

La tesis

La definición original del patrón, en el catálogo de Patterns of Enterprise Application Architecture, es anterior a este debate y no menciona la portabilidad por ningún lado:

"Mediates between the domain and data mapping layers using a collection-like interface for accessing domain objects."

El término operativo ahí es collection-like. Fowler lo desarrolla en la línea siguiente: los objetos se añaden y se quitan del repositorio igual que de una colección cualquiera, y el código de mapeo que el repositorio encapsula ejecuta por detrás las operaciones que correspondan. Una colección tiene una interfaz de pertenencia —qué hay dentro, cómo se encuentra, qué se agrega— y no tiene ninguna noción de almacenamiento.

De ahí sale la formulación que sostiene el resto del artículo:

Un repositorio no es una capa sobre la base de datos: es una colección de tu dominio que, casualmente, vive en una.

La diferencia entre las dos lecturas no es retórica; determina cosas distintas al escribir el código. Si el repositorio es una capa sobre la base de datos, sus métodos se nombran según lo que hace el motor y sus tipos son los de la fila, porque el objetivo es dar acceso a la tabla de forma ordenada. Si es una colección de objetos de dominio, sus métodos se nombran según lo que el negocio busca y sus tipos son los del dominio, porque el almacenamiento es un detalle de implementación que queda del otro lado.

De esa formulación se derivan las dos piezas que ocupan el resto del artículo:

El puerto es una interfaz de TypeScript sin decoradores, sin dependencias de Nest y sin dependencias del ORM, escrita en vocabulario de negocio, cuyos tipos de entrada y salida son entidades de dominio y nunca modelos de persistencia.
El adaptador es la única pieza del módulo que conoce TypeORM, y su trabajo consiste en traducir en ambas direcciones.

El resto —cómo dos repositorios comparten una transacción, cómo se sustituye la implementación en un test— son consecuencias de esas dos definiciones, y es donde el patrón se pone a prueba.

El contrato mínimo: el puerto

El puerto es el archivo completo, no un extracto:

// src/order/domain/repositories/order.repository.ts
import { Order } from '../entities/order.entity';

export interface OrderRepository {
  create(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
  findByReference(reference: string): Promise<Order | null>;
  findPendingByCustomer(customerId: string): Promise<Order[]>;
  update(order: Order): Promise<void>;
}

Tiene una sola importación y apunta al propio dominio. No hay nada de @nestjs/common, nada de typeorm y ningún decorador; el archivo compila con las dependencias del proyecto desinstaladas. Esa es una propiedad comprobable, y es la que define la frontera: todo lo que este archivo no menciona es lo que el dominio no puede saber.

Los tipos de entrada y salida son Order, la entidad, y no OrderModel. Ahí está la diferencia con los repositorios extendidos de la sección anterior: .extend() también permitía nombrar la consulta, pero devolvía la fila. Nombrar sin cambiar el tipo resuelve la mitad del problema.

findPendingByCustomer es el coste nº 2 en su forma resuelta. La definición de "pendiente" pasa a tener un único lugar donde vive, y modificarla es modificar un método cuyo cambio el compilador propaga a todos los llamadores. La comparación con los tres literales divergentes de antes es directa: aquello era una coincidencia entre copias, esto es una declaración.

Dos observaciones sobre lo que el puerto no tiene. No hay ningún método genérico —ni findAll(options), ni query(), ni nada que reciba criterios arbitrarios—: cada entrada responde a una necesidad concreta, y el puerto crece por demanda del negocio en lugar de crecer por anticipación. Y las búsquedas devuelven Order | null: el puerto informa de la ausencia, no decide qué hacer con ella. Convertir "no existe" en un error —una excepción de dominio, un 404— es trabajo de quien llama, que es quien conoce el contexto.

La entidad no es la tabla

El coste nº 1 se resuelve separando en tres archivos lo que antes era uno. Cada uno tiene un único consumidor y, por lo tanto, un único conjunto de requisitos.

La entidad de dominio ya no la instancia el ORM, y eso es exactamente lo que le devuelve la capacidad de exigir:

// src/order/domain/entities/order.entity.ts
interface Props {
  id: string;
  customerId: string;
  reference: string;
  status: OrderStatus;
  lines: OrderLine[];
}

export class Order {
  readonly id: string;
  readonly customerId: string;
  readonly reference: string;
  status: OrderStatus;
  lines: OrderLine[];

  constructor(props: Props) {
    this.id = props.id;
    this.customerId = props.customerId;
    this.reference = props.reference;
    this.status = props.status;
    this.lines = props.lines;
  }

  confirm(): void {
    if (this.lines.length === 0) {
      throw new EmptyOrderException(this.reference);
    }
    this.status = OrderStatus.CONFIRMED;
  }

  total(): number {
    return this.lines.reduce((sum, line) => sum + line.subtotal(), 0);
  }
}

El constructor tiene parámetros obligatorios, que era justo lo que la documentación de TypeORM prohíbe en una entidad suya. La clase no tiene createdAt, ni deletedAt, ni una FK cruda conviviendo con su relación; tiene los datos que el negocio necesita y los métodos que operan sobre ellos. El invariante de confirm() sigue siendo una comprobación, pero ahora está en el único sitio que puede cambiar el estado, en lugar de repetirse en cada servicio que confirme un pedido.

El modelo de persistencia es la clase decorada del primer coste con otro nombre, y con una diferencia de expectativas: ya no se espera que contenga reglas.

// src/order/infrastructure/typeorm/models/order.model.ts
@Entity('order')
export class OrderModel {
  @PrimaryColumn('varchar', { length: 26 }) id: string;
  @Column() customerId: string;
  @Column() reference: string;

  @Column({ type: 'enum', enum: OrderStatus })
  status: OrderStatus;

  @OneToMany(() => OrderLineModel, (line) => line.order, { cascade: true })
  lines: OrderLineModel[];

  @CreateDateColumn() createdAt: Date;
  @DeleteDateColumn() deletedAt: Date | null;
}

Su anemia dejó de ser un defecto: describe una fila, y una fila no tiene comportamiento. Las columnas de auditoría, las FKs crudas y los tipos que impone el driver viven aquí sin contaminar nada, porque su único consumidor es el ORM.

El mapper es la traducción, y concentra tres decisiones que antes estaban repartidas:

// src/order/infrastructure/typeorm/mappers/order.mapper.ts
export class OrderMapper {
  static toDomain(model: OrderModel): Order {
    return new Order({
      id: model.id,
      customerId: model.customerId,
      reference: model.reference,
      status: model.status,
      lines: OrderLineMapper.toDomainList(model.lines ?? []),
    });
  }

  static toDomainList(models: OrderModel[]): Order[] {
    return models.map((model) => this.toDomain(model));
  }

  static toModel(entity: Order): OrderModel {
    const model = new OrderModel();
    model.id = entity.id;
    model.customerId = entity.customerId;
    model.reference = entity.reference;
    model.status = entity.status;
    model.lines = entity.lines.map(OrderLineMapper.toModel);
    return model;
  }
}

Toda fila que entra al dominio pasa por toDomain, así que las conversiones que antes estaban repartidas por los servicios tienen ahora una ubicación única: el numeric que el driver entrega como cadena se convierte a number, dentro de OrderLineMapper, sobre el precio de cada línea.

El status, en cambio, no se convierte: se asigna. Conviene detenerse en por qué, porque la alternativa es un error frecuente. Si la columna fuera un varchar libre, el tipo de model.status sería string y el mapper tendría que resolver el desajuste de alguna manera: con model.status as OrderStatus, que es una aserción y no comprueba nada, o con un type guard que valide en cada lectura. La segunda opción es correcta pero está pagando en tiempo de ejecución, fila a fila, una garantía que el esquema puede dar gratis. Declarando la columna como enum, la restricción vive en la base de datos, model.status ya es del tipo OrderStatus, y no hay nada que afirmar ni que comprobar.

La diferencia con customer: Customer del primer coste es exactamente esa. Allí el tipo afirmaba algo que el valor podía incumplir; aquí el tipo es verdadero porque hay una restricción detrás que lo sostiene. Un tipo solo vale lo que vale la garantía que lo respalda, y validar en el mapper contra un esquema que no restringe es tratar el síntoma.

Nota: el model.lines ?? [] es el problema del arranque del artículo reapareciendo. Si la consulta no pidió la relación, el mapper construye un pedido sin líneas y el invariante de confirm() vuelve a quedar invertido sin que nada falle. La diferencia respecto al punto de partida no es que el riesgo desaparezca: es que la consulta ahora se escribe en un solo lugar —el adaptador—, de modo que la garantía se establece una vez en lugar de depender de cada llamador.

El coste conviene decirlo en el mismo sitio que el beneficio: son tres archivos por entidad en lugar de uno, y el mapper hay que mantenerlo a mano. El compilador ayuda en una sola dirección —un campo nuevo y obligatorio en Props rompe toDomain hasta que lo añadas—, pero una columna nueva en el modelo no obliga a nada, así que el mapeo incompleto es un error que las herramientas no detectan.

El adaptador: la única pieza que conoce el ORM

El adaptador implementa el puerto y concentra todo lo que el dominio dejó de saber:

// src/order/infrastructure/typeorm/repositories/typeorm-order.repository.ts
@Injectable()
export class TypeOrmOrderRepository implements OrderRepository {
  constructor(
    @InjectRepository(OrderModel)
    private readonly repository: Repository<OrderModel>,
  ) {}

  async create(order: Order): Promise<void> {
    await this.repository.save(OrderMapper.toModel(order));
  }

  async findById(id: string): Promise<Order | null> {
    const model = await this.repository.findOne({
      where: { id },
      relations: { lines: true },
    });
    return model ? OrderMapper.toDomain(model) : null;
  }

  async findPendingByCustomer(customerId: string): Promise<Order[]> {
    const models = await this.repository.find({
      where: { customerId, status: OrderStatus.PENDING },
      relations: { lines: true },
    });
    return OrderMapper.toDomainList(models);
  }

  async update(order: Order): Promise<void> {
    await this.repository.save(OrderMapper.toModel(order));
  }
}

@InjectRepository(OrderModel) es la misma línea con la que empezó el artículo. No desapareció ni se sustituyó por nada: cambió de sitio. El patrón no rechaza el camino documentado de NestJS, lo confina a la clase donde ese conocimiento es legítimo.

Todos los métodos tienen la misma forma —consulta y traducción— y ninguno contiene una decisión de negocio. Eso da un criterio de revisión aplicable sin discusión: si aparece aquí un if que consulta el estado de un pedido para decidir algo, está en el archivo equivocado.

El relations: { lines: true } aparece dos veces, y esa repetición es el residuo de lo que en el arranque del artículo estaba disperso por todos los servicios. Sigue siendo repetición, pero ahora es local: cabe en una pantalla y se puede auditar leyendo un archivo.

create y update se resuelven ambos con save, que hace lo que ya hacía —decidir entre inserción y actualización según la clave primaria—. La diferencia es dónde vive esa ambigüedad: el puerto declara dos operaciones porque el negocio distingue crear de actualizar, y que la implementación las resuelva con la misma llamada es un detalle que no tiene por qué aparecer en el nombre.

El cableado

Una interfaz de TypeScript no existe en tiempo de ejecución, así que no puede servir de token de inyección. Hace falta uno explícito, declarado junto al puerto:

// src/order/domain/repositories/order.repository.ts
export const ORDER_REPOSITORY = Symbol('OrderRepository');

Y el módulo asocia el token con la implementación:

// src/order/order.module.ts
@Module({
  imports: [TypeOrmModule.forFeature([OrderModel, OrderLineModel])],
  providers: [
    ConfirmOrderService,
    { provide: ORDER_REPOSITORY, useClass: TypeOrmOrderRepository },
  ],
})
export class OrderModule {}

Esta línea es el punto donde se decide qué implementación recibe el dominio, y es la única que habría que tocar para sustituirla. También es la razón de que el consumidor necesite un @Inject explícito, cosa que no hacía falta cuando inyectaba una clase.

El servicio, otra vez

Con las piezas colocadas, el método del principio del artículo queda así:

@Injectable()
export class ConfirmOrderService {
  constructor(
    @Inject(ORDER_REPOSITORY)
    private readonly orders: OrderRepository,
  ) {}

  async execute(orderId: string): Promise<void> {
    const order = await this.orders.findById(orderId);
    if (!order) throw new OrderNotFoundException(orderId);

    order.confirm();
    await this.orders.update(order);
  }
}

El comportamiento es el mismo que al principio. Lo que cambió es el reparto del conocimiento, y conviene volver sobre el inventario del arranque para comprobarlo punto por punto: aquí no hay where, no hay relations de las que dependa la corrección de una regla, no hay save con su ambigüedad, y no hay vocabulario de tabla. El invariante de las líneas ya no está en este archivo: está en order.confirm(), que es el único sitio capaz de cambiar el estado del pedido.

Queda un if de ausencia, y es una permanencia deliberada. No responde a que findOne devuelva null, sino a que el puerto declara Promise<Order | null> como parte de su contrato: el repositorio informa de que el pedido no está, y este servicio decide que eso es un error de negocio. La comprobación es la misma; su causa, no.

Hasta aquí el patrón se sostiene sobre una entidad y una operación. La prueba real llega cuando la operación toca dos.

La transacción compartida

Confirmar un pedido también descuenta stock — la regla del tercer coste entra en escena. El servicio pasa a usar dos puertos:

async execute(orderId: string): Promise<void> {
  const order = await this.orders.findById(orderId);
  if (!order) throw new OrderNotFoundException(orderId);

  order.confirm();

  for (const line of order.lines) {
    const stock = await this.inventory.findByProduct(line.productId);
    if (!stock) throw new ProductNotFoundException(line.productId);
    stock.reserve(line.quantity); // lanza InsufficientStockException si no alcanza
    await this.inventory.update(stock);
  }

  await this.orders.update(order);
}

Las escrituras son varias y el requisito es uno: o entran todas o no entra ninguna. Si reserve lanza en la tercera línea del pedido, las dos reservas anteriores no pueden quedar escritas.

El problema tiene una forma precisa. En TypeORM, una transacción es un EntityManager concreto —el del QueryRunner que la abrió—, y toda consulta que quiera participar debe ejecutarse a través de él. La transacción se abre en el borde, en el controller, porque el alcance de la atomicidad lo define el caso de uso. Pero las consultas se ejecutan dos capas más abajo, en los adaptadores. Ese manager tiene que viajar desde el borde hasta los adaptadores, y solo hay dos caminos.

El primero es pasarlo como parámetro. Se ve enseguida a qué obliga:

export interface OrderRepository {
  findById(id: string, manager?: EntityManager): Promise<Order | null>;
  update(order: Order, manager?: EntityManager): Promise<void>;
  // ...
}

El puerto —el archivo que compilaba sin TypeORM— pasa a importar EntityManager, y cada firma del dominio carga con un parámetro que el negocio no puede explicar. La contaminación que el patrón sacó por la puerta vuelve por la firma, y no a un archivo: a todos los métodos de todos los puertos que participen en alguna transacción.

El segundo camino es que el manager no viaje por las firmas sino por el contexto de ejecución. Node tiene un mecanismo estándar para exactamente esto: AsyncLocalStorage, un almacén ligado a la cadena asíncrona en curso. Todo lo que se ejecute dentro de storage.run(valor, fn) —a cualquier profundidad de await— puede leer valor con storage.getStore(), sin que ningún intermediario lo transporte. Es el mismo mecanismo con el que se propaga el contexto de una petición para logging, y también el que empaquetan librerías como typeorm-transactional; aquí se usa directo, porque cabe en un archivo corto y conviene ver qué hay dentro.

La pieza que lo encapsula es un ejecutor:

// src/shared/infrastructure/typeorm/transaction.executor.ts
@Injectable()
export class TransactionExecutor {
  private static readonly storage = new AsyncLocalStorage<EntityManager>();

  constructor(private readonly dataSource: DataSource) {}

  async execute<T>(work: () => Promise<T>): Promise<T> {
    const queryRunner = this.dataSource.createQueryRunner();
    await queryRunner.connect();
    await queryRunner.startTransaction();

    try {
      return await TransactionExecutor.storage.run(
        queryRunner.manager,
        async () => {
          const result = await work();
          await queryRunner.commitTransaction();
          return result;
        },
      );
    } catch (err) {
      await queryRunner.rollbackTransaction();
      throw err;
    } finally {
      await queryRunner.release();
    }
  }

  getManagerIfActive(): EntityManager | null {
    return TransactionExecutor.storage.getStore() ?? null;
  }
}

execute abre el QueryRunner, corre el trabajo dentro de storage.run con el manager transaccional como valor, confirma si el trabajo terminó y revierte si lanzó. La excepción de dominio adquiere así una segunda función sin saberlo: InsufficientStockException era la forma de rechazar una reserva inválida, y ahora es también la señal de aborto de la transacción. El error de negocio y el rollback quedan unificados sin que ninguna de las dos partes conozca a la otra.

La contraparte está en el adaptador, y son tres líneas:

private getRepository(): Repository<OrderModel> {
  const manager = this.transactionExecutor.getManagerIfActive();
  return manager ? manager.getRepository(OrderModel) : this.repository;
}

Cada método del adaptador consulta a través de this.getRepository() en lugar de this.repository. Si hay una transacción activa en el contexto, participa en ella; si no la hay, usa el repositorio inyectado y la consulta se ejecuta suelta, como hasta ahora. El adaptador funciona igual dentro y fuera de una transacción, y es la misma clase en ambos casos.

Con las dos piezas colocadas, el borde queda así:

@Post(':id/confirm')
async confirm(@Param('id') id: string): Promise<void> {
  return this.transactionExecutor.execute(() =>
    this.confirmOrder.execute(id),
  );
}

Y este es el resultado que la sección debía demostrar: el servicio de dominio ejecuta todas sus escrituras —una por línea del pedido, más la del propio pedido— de forma atómica y no contiene ninguna referencia a la transacción. No recibe un manager, no importa TypeORM, no sabe que el controller lo envolvió en nada. El puerto sigue compilando sin dependencias. La atomicidad se decidió en el borde, el mecanismo vive en infraestructura, y el dominio quedó entre ambos sin enterarse de ninguno de los dos.

Nota: el acuerdo entre ejecutor y adaptadores es invisible para el compilador. Nada en el tipo OrderRepository obliga a una implementación a consultar getManagerIfActive(): un adaptador que use this.repository directamente compila igual, se ejecuta fuera de la transacción, y sus escrituras sobreviven al rollback. Es el punto más frágil del mecanismo —una convención de equipo, no un contrato tipado— y conviene protegerlo donde se pueda: en la revisión de código y en el test de integración que verifica que un fallo revierte todas las escrituras.

Dos maneras de cablear el puerto

El cableado con token de la sección del adaptador es la forma canónica en Nest, pero no la única compatible con el patrón. La alternativa es no registrar el puerto en el contenedor: el módulo registra las clases concretas, y el controller —que las recibe por inyección— compone el servicio de dominio a mano en cada endpoint:

@Post(':id/confirm')
async confirm(@Param('id') id: string): Promise<void> {
  return this.transactionExecutor.execute(() => {
    const confirmOrder = new ConfirmOrderService(
      this.orderRepository,
      this.inventoryRepository,
    );
    return confirmOrder.execute(id);
  });
}

Un new dentro de un framework construido alrededor del contenedor levanta sospecha, así que conviene fijar el invariante que comparten las dos formas: el constructor de ConfirmOrderService sigue declarando OrderRepository, la interfaz, y el compilador comprueba en el punto del new exactamente lo que comprobaba en el useClass. La frontera del patrón se respeta idéntica; lo único que cambia es quién ejecuta la composición. Como efecto lateral, el servicio de dominio pierde sus dos últimos decoradores —@Injectable, @Inject— y la carpeta domain/ queda sin un solo import del framework; a cambio, sustituir la implementación deja de ser un cambio de una línea y la composición se repite por endpoint.

Para este artículo basta con eso: el patrón funciona igual con cualquiera de los dos cableados, y todo lo anterior —puerto, adaptador, transacción— es independiente de cuál se elija.

Nota: la composición manual no es una decisión aislada: forma parte de una manera de estructurar el proyecto —los casos de uso como clases, la composición en el borde, qué hace exactamente la capa de aplicación— que necesita más espacio del que le corresponde aquí. Queda para un artículo propio.

El test que ahora es posible

El coste nº 3 pedía cuatro elementos ajenos a la regla para poder verificarla: la base, el esquema, los fixtures y el aislamiento. Con el puerto en medio, la implementación de prueba es una clase que lo implementa con stubs:

// tests/unit/order/mocks/mock-inventory-repository.ts
export class MockInventoryRepository implements InventoryRepository {
  findByProduct = vi.fn<(productId: string) => Promise<Inventory | null>>();
  update = vi.fn<(inventory: Inventory) => Promise<void>>();
}

Su gemelo para OrderRepository tiene la misma forma, y el test de la regla de stock queda completo así:

it('rechaza la confirmación cuando no hay stock suficiente', async () => {
  const orders = new MockOrderRepository();
  const inventory = new MockInventoryRepository();

  const order = new Order({
    id: 'order-1',
    customerId: 'customer-1',
    reference: 'ORD-001',
    status: OrderStatus.PENDING,
    lines: [
      new OrderLine({
        id: 'line-1',
        productId: 'product-1',
        quantity: 5,
        unitPrice: 100,
      }),
    ],
  });
  orders.findById.mockResolvedValue(order);
  inventory.findByProduct.mockResolvedValue(
    new Inventory({ productId: 'product-1', available: 3 }),
  );

  const service = new ConfirmOrderService(orders, inventory);

  await expect(service.execute('order-1')).rejects.toThrow(InsufficientStockException);
  expect(inventory.update).not.toHaveBeenCalled();
  expect(orders.update).not.toHaveBeenCalled();
});

De los cuatro elementos no queda ninguno: el estado de partida se construye llamando constructores —los mismos que ya exigen sus parámetros—, y el test corre en milisegundos. Los casos límite que el tercer coste señalaba como los que "tienden a no escribirse" son ahora copias de este test con un número cambiado: el límite exacto, existencias en cero, uno por encima. Su coste marginal es cercano a cero, que es lo que hacía falta para que existan.

Dos detalles llevan el peso. El implements InventoryRepository no es decorativo: cuando el puerto crezca un método, cada mock dejará de compilar hasta ser actualizado — el contrato mantiene los dobles de prueba sincronizados sin disciplina adicional. Y las dos últimas aserciones verifican lo que el coste nº 3 no podía ni plantear con la base de por medio: que el rechazo ocurre antes de cualquier escritura.

Lo que este test no cubre también conviene decirlo: ni el SQL del adaptador, ni el mapper, ni la transacción. Esas piezas se verifican con tests de integración, que siguen necesitando la base — pero ahora son pocos y prueban infraestructura, mientras las reglas, que son muchas, se prueban aquí.

Dos matices honestos

El alcance del ejecutor puede propagarse. El TransactionExecutor del artículo es un singleton y puede seguir siéndolo: su único estado, el AsyncLocalStorage, es estático. Pero en producción esa clase tiende a acumular responsabilidades por petición —la típica es auditoría: registrar qué usuario ejecutó la transacción— y el día que para eso declare Scope.REQUEST, el alcance se propaga por transitividad: todo adaptador que lo inyecta se vuelve request-scoped, y todo lo que inyecte uno de esos adaptadores, también. La consecuencia medible está en los cron: @nestjs/schedule no registra handlers @Cron definidos en providers no estáticos — deja un WARN en el arranque y el job, simplemente, no corre nunca. Es un fallo silencioso de los caros: nada lanza, nada reintenta, y la señal es la ausencia de algo. Las salidas conocidas son dos: resolver el repositorio dentro del handler con ModuleRef en lugar de inyectarlo por constructor, o mantener al ejecutor libre de dependencias por petición para que la propagación no empiece.

Esto no es un Unit of Work. El mecanismo de la sección de transacciones comparte una transacción entre repositorios, y eso es todo lo que hace. No hay identity map: dos findById del mismo pedido dentro de la misma transacción devuelven dos objetos distintos en memoria, y si ambos se modifican y se persisten, la última escritura pisa a la primera sin aviso. Tampoco hay escritura diferida: cada update ejecuta su SQL al ser llamado, no en un flush final. MikroORM ofrece ambas cosas de fábrica, como se dijo en el estado del arte; con este patrón, la disciplina equivalente es de diseño: cada caso de uso carga una entidad una vez y pasa la instancia, en lugar de volver a buscarla.

Para quién es esto (y para quién no)

El coste total del patrón quedó repartido a lo largo del artículo y conviene sumarlo aquí: tres archivos y un mapper por entidad, un ejecutor de transacciones, un acuerdo no tipado entre ejecutor y adaptadores, y dos matices de operación. Ese coste se paga en cada entidad nueva, así que la pregunta de adopción es para qué proyectos el retorno lo supera.

Hay proyectos donde no lo supera. Un CRUD de un módulo, un MVP que busca mercado, un backoffice interno donde las reglas son "guardar lo que llegó": ahí los tres costes del acoplamiento no llegan a materializarse —no hay invariantes que proteger, no hay consultas repetidas porque hay pocas consultas, y los tests de reglas no existen porque casi no hay reglas—. En esos proyectos, @InjectRepository directo en el servicio es la respuesta correcta, y este patrón es ceremonia sin retorno.

Las condiciones que invierten el balance son las que el artículo viene usando desde el principio: invariantes de verdad —dinero, estados, stock—, escrituras que cruzan varias tablas y deben ser atómicas, reglas que se quieren verificar en milisegundos, y un equipo lo bastante grande como para que "dónde vive esta consulta" necesite una respuesta que no dependa de quién la escribió. Con dos o más de esas condiciones presentes, cada pieza del patrón está pagando algo concreto; con ninguna, todas son peso muerto.

Para el módulo que está en la frontera, la regla práctica que resume el artículo cabe en una línea: si el nombre del método lo entendería alguien del negocio, pertenece al puerto; si describe lo que hace el motor, pertenece al adaptador.

El código

Todo lo anterior está en un proyecto ejecutable: nestjs-repository-pattern.

Un solo caso de uso —confirmar un pedido, que descuenta stock—, porque es el mínimo que obliga a resolver el problema interesante: dos repositorios escribiendo en la misma transacción sin que el dominio se entere. Se levanta con docker compose up -d && npm run dev, y los diez tests de reglas de negocio corren en siete milisegundos sin base de datos.

Queda el cierre, que es la tesis vista desde el final. El ORM y este patrón no compiten, porque no responden la misma pregunta: TypeORM resuelve cómo hablar con la base de datos —conexiones, SQL, mapeo de filas—, y lo resuelve bien. El patrón resuelve dónde vive el conocimiento del negocio y qué sabe de la base — que es una pregunta que el ORM no tiene por qué responder. Son capas distintas. La colección de tu dominio necesita las dos: una para ser colección, la otra para vivir en alguna parte.

Hablemos

¿Preguntas, feedback o una visión distinta? Me encantaría leerte. Me encuentras aquí:

GitHub — hgomezrobaina
LinkedIn — Héctor Gómez Robaina
X — @hgomezrobaina

Chaca 2.2: mock data generation, now in the browser

Hector Angel Gomez Robaina — Wed, 05 Aug 2026 03:10:08 +0000

Chaca is a TypeScript library for generating realistic, relational mock data — schemas that reference each other, exported to JSON, CSV, SQL, Java, Python and more. Until now, it only ran in Node. Version 2.2 changes that.

🌐 Chaca is now isomorphic

You can install and use Chaca in any browser app — React, Vue, Svelte, vanilla JS. No configuration needed: your bundler automatically resolves the browser-safe build through the package exports map. The package now ships both ESM and CommonJS builds, each with its own type definitions.

The key piece is transform, which serializes your data to any supported format fully in memory — no filesystem involved. That makes it the natural way to get file contents in the browser, for example to trigger a download:

import { chaca, modules } from "chaca";

const schema = chaca.schema({
  id: chaca.key(() => modules.id.uuid()),
  name: () => modules.person.firstName(),
});

const [file] = await schema.transform(50, {
  filename: "users",
  format: "json",
});

// file.filename -> "users.json"
// file.content  -> serialized string, ready to download or display

transform supports every format: json, csv, yaml, postgresql, sqlite, mysql, java, python, typescript and javascript.

Note: export (which writes files to disk) is not available in the browser build and throws a descriptive error pointing you to transform. In Node, export keeps working exactly as before.

🗄️ New export formats: SQLite and MySQL

Two new SQL targets join postgresql, sharing all of its options (keys, uniques, nulls, refs, generateIds, declarationOnly, ...):

await dataset.export({
  filename: "data",
  location: "./data",
  format: "sqlite", // or "mysql"
});

Both are also available from the CLI (chaca sqlite, chaca mysql) and generate scripts with native types for each engine:

SQLite: PRAGMA foreign_keys = ON, INTEGER PRIMARY KEY for generated ids, TEXT for strings and ISO dates, REAL for floats.
MySQL: INT AUTO_INCREMENT PRIMARY KEY, VARCHAR(255)/TEXT, DATETIME(3) for dates, table-level FOREIGN KEY constraints, and reserved words safely quoted with backticks.

🧯 A single `Errors` namespace

Every Chaca exception is now grouped under one namespace, so error handling is easier to discover:

import { Errors } from "chaca";

try {
  await schema.export(/* ... */);
} catch (e) {
  if (e instanceof Errors.TryRefANoKeyFieldError) {
    /* handle the specific error */
  }
  if (e instanceof Errors.ChacaError) {
    /* catch-all for any chaca error */
  }
}

The existing flat exports keep working, and three error classes announced in 2.0.0 but never actually exported are finally reachable.

🪛 40+ fixes

This release closes a long list of bugs. Some highlights:

chaca.pick and isArray with { min, max } could never reach max — the upper bound is now inclusive, as documented.
The Java exporter generated code that didn't compile (missing semicolons, wrong float literals, invalid bigint types, reserved-word identifiers). It compiles now.
PostgreSQL export: single quotes in strings are properly escaped, all-null columns get a TEXT type, dates keep their time as TIMESTAMP, and reserved-word identifiers are double quoted.
An array ref field that runs out of values no longer pads the array with null — it stops at the references it could actually resolve. Check your code if you relied on the padding; as a bonus, large isArray refs are noticeably faster.
modules.date.past/soon/between no longer mutate the Date you pass in.
modules.internet.email no longer produces pedro@yahoo.com.com, and modules.datatype.hexadecimal no longer outputs the letter G.
CSV missing values are empty cells instead of the literal string undefined, and YAML no longer silently drops bigint values.

The full list — including a few small behavior changes worth checking (ethereumAddress now includes the 0x prefix, color.rgb CSS output no longer carries the hex prefix, and the continent typos Oseania/Antartica were corrected) — is in the changelog.

Try it

npm install chaca

Docs and guides at chaca.app. If you build something with it — or hit a bug — issues and PRs are welcome on GitHub.

Chaca 2.2: generación de datos de prueba, ahora en el navegador

Hector Angel Gomez Robaina — Wed, 05 Aug 2026 03:05:41 +0000

Chaca es una librería TypeScript para generar datos de prueba realistas y relacionales — esquemas que se referencian entre sí, exportables a JSON, CSV, SQL, Java, Python y más. Hasta ahora solo funcionaba en Node. La versión 2.2 cambia eso.

🌐 Chaca ahora es isomórfica

Puedes instalar y usar Chaca en cualquier aplicación de navegador — React, Vue, Svelte, JS vanilla. Sin configuración: tu bundler resuelve automáticamente el build seguro para navegador a través del mapa de exports del paquete. El paquete ahora incluye builds en ESM y CommonJS, cada uno con sus propias definiciones de tipos.

La pieza clave es transform, que serializa tus datos a cualquier formato soportado completamente en memoria — sin tocar el sistema de archivos. Eso lo convierte en la forma natural de obtener el contenido de un archivo en el navegador, por ejemplo para lanzar una descarga:

import { chaca, modules } from "chaca";

const schema = chaca.schema({
  id: chaca.key(() => modules.id.uuid()),
  name: () => modules.person.firstName(),
});

const [file] = await schema.transform(50, {
  filename: "users",
  format: "json",
});

// file.filename -> "users.json"
// file.content  -> string serializado, listo para descargar o mostrar

transform soporta todos los formatos: json, csv, yaml, postgresql, sqlite, mysql, java, python, typescript y javascript.

Nota: export (que escribe archivos en disco) no está disponible en el build de navegador y lanza un error descriptivo que te dirige a transform. En Node, export sigue funcionando exactamente igual que antes.

🗄️ Nuevos formatos de exportación: SQLite y MySQL

Dos nuevos destinos SQL se suman a postgresql, compartiendo todas sus opciones (keys, uniques, nulls, refs, generateIds, declarationOnly, ...):

await dataset.export({
  filename: "data",
  location: "./data",
  format: "sqlite", // o "mysql"
});

Ambos están disponibles también desde la CLI (chaca sqlite, chaca mysql) y generan scripts con tipos nativos de cada motor:

SQLite: PRAGMA foreign_keys = ON, INTEGER PRIMARY KEY para ids generados, TEXT para strings y fechas ISO, REAL para floats.
MySQL: INT AUTO_INCREMENT PRIMARY KEY, VARCHAR(255)/TEXT, DATETIME(3) para fechas, constraints FOREIGN KEY a nivel de tabla, y palabras reservadas protegidas con backticks.

🧯 Un único namespace `Errors`

Todas las excepciones de chaca están ahora agrupadas bajo un solo namespace, lo que hace el manejo de errores mucho más fácil de descubrir:

import { Errors } from "chaca";

try {
  await schema.export(/* ... */);
} catch (e) {
  if (e instanceof Errors.TryRefANoKeyFieldError) {
    /* manejar el error específico */
  }
  if (e instanceof Errors.ChacaError) {
    /* catch-all para cualquier error de chaca */
  }
}

Los exports planos existentes siguen funcionando, y tres clases de error anunciadas en la 2.0.0 pero que nunca se llegaron a exportar por fin son accesibles.

🪛 Más de 40 fixes

Esta versión cierra una larga lista de bugs. Algunos destacados:

chaca.pick e isArray con { min, max } nunca podían alcanzar max — el límite superior ahora es inclusivo, como indica la documentación.
El exportador de Java generaba código que no compilaba (puntos y coma faltantes, literales float incorrectos, tipos bigint inválidos, identificadores con palabras reservadas). Ahora compila.
Export a PostgreSQL: las comillas simples en strings se escapan correctamente, las columnas donde todo es null reciben tipo TEXT, las fechas conservan la hora como TIMESTAMP y los identificadores con palabras reservadas van entre comillas dobles.
Un campo ref en array que se queda sin valores ya no rellena el array con null — se detiene en las referencias que pudo resolver. Revisa tu código si dependías del relleno; como bonus, los isArray grandes con refs son notablemente más rápidos.
modules.date.past/soon/between ya no mutan el Date que les pasas.
modules.internet.email ya no produce pedro@yahoo.com.com, y modules.datatype.hexadecimal ya no incluye la letra G.
En CSV los valores ausentes son celdas vacías en lugar del string literal undefined, y YAML ya no descarta silenciosamente los valores bigint.

La lista completa — incluidos algunos pequeños cambios de comportamiento que conviene revisar (ethereumAddress ahora incluye el prefijo 0x, la salida CSS de color.rgb ya no lleva el prefijo hexadecimal, y se corrigieron los typos Oseania/Antartica en continent) — está en el changelog.

Pruébalo

npm install chaca

Documentación y guías en chaca.app. Si construyes algo con ella — o encuentras un bug — los issues y PRs son bienvenidos en GitHub.

Form validation without Formik or React Hook Form: treat your rules as domain logic

Hector Angel Gomez Robaina — Mon, 29 Jun 2026 00:16:50 +0000

We've all been here. A new form shows up, you install React Hook Form, add Zod or Yup, and in ten minutes you have something that "works." The problem doesn't surface that day. It surfaces three months later, when the same VIN you validate in the create car form also has to be validated in edit, in import from Excel, and it turns out the rule —"17 characters, the last 5 numeric"— is written three times, each one slightly different, and none of them lives in a place you can point to and say "here is what a valid VIN is."

A typical form with a library looks roughly like this:

const schema = z.object({
  vin: z.string().length(17, "The VIN must be 17 characters"),
  miles: z.number().min(0, "Miles cannot be negative"),
  // ...and 8 more fields
});

const {
  register,
  handleSubmit,
  watch,
  formState: { errors },
} = useForm({
  resolver: zodResolver(schema),
});

It works. But if you stop to look at it, you're paying three costs that almost never get named:

1. Clean code dissolves. The business rule ends up scattered across the schema, the resolver, the register calls, the Controllers, and the JSX. The knowledge —what makes a car valid— has no home. It's wired into the UI. And what's wired into the UI doesn't get reused: it gets copied.

2. Performance and coupling are paid silently. These libraries live on subscriptions: watch, re-renders on every keystroke, internal state to keep in sync. For a contact form, who cares. For a screen with 15 fields, sub-forms, and cross-field validation, your component is tied to the library's lifecycle —not yours— and you start fighting it instead of using it.

3. Developer convenience is a trap. It's wonderfully convenient at first. But that same rule: how do you test it without mounting a component? How do you move it to the backend? How do you translate it into two languages without polluting the schema? Everything the library gave you for free, it charges you for the day you need to step outside its mold.

None of these problems are Formik's or React Hook Form's fault. They're excellent at what they do: wiring inputs to state. The problem is that we delegate to them something that was never their job —deciding what is valid— and that's where the domain leaks out into the presentation layer.

The thesis

The whole approach I'm about to show comes from a single idea:

An invalid field is a domain rule, not a UI state.

If you accept that, the consequences are direct. Validation doesn't belong to the component: it belongs to the domain, just like your models and your services. A rule stops being a line in a schema and becomes a nameable, testable unit. The component goes back to its only job —render and trigger— and asks the domain "is this valid?", the same way it asks a service "did this save?".

It's not more code for the sake of it. It's moving the business knowledge to the place where it can be reused, tested without React, translated effortlessly, and —the day it's needed— moved to the backend without rewriting a single line of logic.

In what follows I'll take apart the system I use in my projects: a four-line contract, rules as classes, composition without weird inheritance, and how all of it is consumed from a component with a plain useState.

3. The minimal contract: a rule and an error

Before writing a single validation, we need to define two things: what a rule is and what an error is. Both are pretty small.

A rule is any object that knows how to answer "what's wrong here?":

export interface ValidationRule {
  validate(): AppException[];
}

That's it. No state, no React, no generics. A ValidationRule receives whatever it needs through its constructor and returns a list of errors. If the list is empty, the field is valid. The detail that seems minor but isn't: it returns an array, not a boolean or a string. A field can fail for several reasons at once, and whoever validates only reports —it doesn't decide how things get shown.

And what is an error? Not a loose string:

export class AppException {
  readonly id: string;
  readonly message: TranslationConfig;

  constructor({ id, message }: { id: string; message: TranslationConfig }) {
    this.id = id;
    this.message = message;
  }
}

Two fields, two decisions.

The message is a TranslationConfig ({ es, en }): the error is born already translated, deep in the domain, instead of being a string someone has to remember to run through i18n in the UI layer. Not every system needs this, but if your app is multi-language it saves you from maintaining a key map kept in sync with every rule. I'll leave it here and move on, because the really interesting piece is the other one.

The id is what turns this error into something genuinely testable. A stable, language-independent id —"car.vin.empty", "car.miles.negative"— gives you an identifier that doesn't change even if you rewrite the text or switch languages. And that unlocks two things:

In E2E tests, you can render that id as a data-error-id in the DOM and assert "the empty-VIN error appeared" without coupling the test to the exact message text (which changes, gets translated, gets tweaked). The test verifies the rule, not the copy.
In unit tests, you can go a step further and make each error its own subclass of AppException:

  export class VinEmptyException extends AppException {
    constructor() {
      super({
        id: "car.vin.empty",
        message: {
          es: "El VIN no puede estar vacío",
          en: "The VIN cannot be empty",
        },
      });
    }
  }

And then the assertion is about types, not strings:

  const errors = new CarVinValidator("").validate();

  expect(errors.some((e) => e instanceof VinEmptyException)).toBe(true);
  // or, if you prefer the id:
  expect(errors[0].id).toBe("car.vin.empty");

Compare that with the fragile alternative we've all written: expect(errors[0].message).toContain("empty"). That assertion breaks the day someone fixes a typo. The one above survives any copy change, in any language.

With that, the system's full contract is two pieces:

ValidationRule → "I know how to decide whether something is valid and, if not, I enumerate exactly what failed."
AppException → "I'm an error with a stable identity (id) and, while we're at it, I know how to say myself in every language the app speaks."

Everything that follows —rules, composition, triggering from the component— rests on these two. There's no more "framework" to learn: an interface and a data class. The day someone new joins the project, this is all they have to read to understand how we validate.

Design note: the fact that validate() takes no arguments is intentional. The value comes in through the constructor, not the method. That makes each rule a self-contained object —you build it with its data and it's ready to be asked— and it's what lets you drop them all into a list and run them in a loop without the orchestrator knowing anything about any of them (section 5).

4. A rule = a class

This is the central idea, and now that we have the contract it fits in very little. A business rule is a class that implements ValidationRule, puts all its logic inside, and returns whatever errors it finds.

Let's take one with substance. A VIN (a car's chassis number) is valid if it's not empty, has exactly 17 characters, and ends with at least 5 numbers. Three different ways to fail, one single class:

export class CarVinValidator implements ValidationRule {
  constructor(private readonly value: string) {}

  validate(): AppException[] {
    const value = this.value.trim();

    if (value.length === 0) {
      return [
        new AppException({
          id: "car.vin.empty",
          message: {
            es: "El VIN no puede estar vacío",
            en: "The VIN cannot be empty",
          },
        }),
      ];
    }

    if (value.length !== 17) {
      return [
        new AppException({
          id: "car.vin.length",
          message: {
            es: "El VIN debe tener 17 caracteres",
            en: "The VIN must be 17 characters",
          },
        }),
      ];
    }

    const end = value.slice(-5);

    if (end.split("").some((c) => isNaN(Number(c)))) {
      return [
        new AppException({
          id: "car.vin.end-numbers",
          message: {
            es: "El VIN debe terminar con al menos 5 números",
            en: "The VIN must end with at least 5 numbers",
          },
        }),
      ];
    }

    return [];
  }
}

That's all. It reads top to bottom like the business definition: empty → error; not 17 → error; doesn't end in numbers → error; otherwise valid. The knowledge of "what makes a VIN valid" now has a place with a first and last name —CarVinValidator— instead of being diluted across a schema, a resolver, and the JSX.

And look at what you got almost for free compared to the library version:

It tests with nothing around it. It's a TypeScript class with no dependencies on React or the DOM. You build it with a value and ask it:

const errors = new CarVinValidator("123").validate();

expect(errors[0].id).toBe("car.vin.length"); // 3 characters → fails on length

And here's where the id from the previous section pays for itself: the test verifies the rule (car.vin.length), not the text of the message. You can rewrite the copy, fix a typo, or add a third language, and the test stays green. Compare that with expect(errors[0].message).toContain("17"), which breaks on the first rewording.

It lives in the domain, not the UI. CarVinValidator imports nothing from the front end. The day you want to test it, reuse it on another screen, or even share the logic with the backend, you take the whole class with you without dragging along a presentation dependency.

If a rule had genuinely heavy logic and you wanted to share it as-is with the backend, you could extract that part into a separate pure class and leave this validator as a thin adapter that only attaches the messages. It's an optimization for specific cases —not the normal one— so don't chase it by default: one class per rule is enough most of the time.

5. Composition: a form is a list of rules

We now have individual rules. What's missing is the orchestrator that gathers and runs them.

export abstract class Validator {
  private readonly rules: ValidationRule[];

  constructor(rules: ValidationRule[]) {
    this.rules = rules;
  }

  execute({ success, error }: Props) {
    const errors: AppException[] = [];

    for (const rule of this.rules) {
      errors.push(...rule.validate());
    }

    if (errors.length === 0) {
      success();
    } else {
      error(errors);
    }
  }
}

The Validator knows nothing about VINs, miles, or cars. It knows one thing only: I got a list of rules, I run them all, gather the errors, and branch. If there were no errors, it calls success(); if there were, it hands them to error(). This is exactly what section 3 anticipated: because each rule receives its data through the constructor, the orchestrator can loop over them without knowing a single one.

And what does validating "a whole car" look like? A class that extends Validator and, in its constructor, assembles the rules:

export class CarValidator extends Validator {
  constructor({ vin, miles, year, brand, model /* ... */ }: CarValidatorProps) {
    super([
      new CarVinValidator(vin),
      new CarMilesValidator(miles),
      new CarYearValidator(year),
      new NotNullValidator(brand, {
        id: "car.brand.required",
        message: {
          es: "El auto debe tener una marca",
          en: "The car must have a brand",
        },
      }),
      new NotNullValidator(model, {
        id: "car.model.required",
        message: {
          es: "El auto debe tener un modelo",
          en: "The car must have a model",
        },
      }),
    ]);
  }
}

Two things here are worth underlining.

A new form is assembling, not rewriting. Validating a car doesn't mean writing validation logic: it means choosing which rules apply and passing them their data. The logic already exists, encapsulated in each ValidationRule. The entity's validator is a shopping list.

Generic rules get reused everywhere. Look at NotNullValidator. It's not specific to cars: it's a reusable rule that takes the value and the error to throw if it's null:

export class NotNullValidator<T> implements ValidationRule {
  constructor(
    private readonly value: T | null,
    private readonly exception: AppException,
  ) {}

  validate(): AppException[] {
    return this.value === null ? [this.exception] : [];
  }
}

Ten lines that validate "this field is required" for any type, in any form. A car's brand, a deal's customer, a user's role: they all reuse the same piece, only changing the message. That's the opposite of copying z.string().min(1) all over the codebase: the rule lives once and gets composed wherever it's needed.

And because Validator is abstract and takes an array, nothing ties you to a rigid hierarchy. Need a rule that's conditional on another field? Drop it into the list when it applies. The orchestrator never finds out —to it, everything is "a rule that returns errors."

6. The consumption: the component just triggers

We've reached the only point where any of this touches React. And the promise from the intro holds here: the component doesn't know how anything is validated. It just builds its state, constructs the validator, and pulls the trigger.

Here's a complete login form, in a hook:

export default function useLogin() {
  const { errors } = useToast();

  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");

  const handleSubmit = () => {
    const validator = new UserLoginValidator({ email, password });

    validator.execute({
      success: () => loginUser({ email, password }).then(/* ... */),
      error: errors,
    });
  };

  return { email, setEmail, password, setPassword, handleSubmit };
}

Read it slowly, because the entire argument of the article is condensed here:

State is plain useState. One useState per field. No useForm, no register, no control, no resolver. React does what React knows how to do and nothing more.
execute branches for you. If every rule passes, it runs success —which chains the backend call—. If any fails, the errors go straight to error. The component doesn't write a single if: it declares what to do in each branch and steps away.
error: errors connects the domain to the UI in one line. errors comes from useToast and receives the AppException[] as-is. Since each error was born translated (section 3), the toast just reads message[language] and renders it. The rule traveled from the domain all the way to the screen without anyone translating a thing along the way.

And the JSX consuming that hook stays completely unaware of the validation system:

<FormInput label={{ es: "Correo", en: "Email" }} required>
  <input value={email} onChange={(e) => setEmail(e.target.value)} />
</FormInput>

This is where the contrast we opened in the intro closes. Your input speaks value / onChange. Compare that with what the library forces you to write:

// React Hook Form: the markup now speaks the library's dialect
<input {...register("email")} />

<Controller
  name="email"
  control={control}
  render={({ field }) => <MyInput {...field} />}
/>

That register, that control, that <Controller> are plumbing props that seep through your entire component tree. And the cost isn't aesthetic —whether the JSX looks busier doesn't matter—; the cost is coupling: the day you want to swap libraries, or drop one, you don't touch a config file, you touch every input in every form. Your presentation layer got married to an external dependency.

In this approach that bond doesn't exist. The FormInput doesn't know there's validation; the <input> doesn't know there are rules; the component only knows useState and "on submit, trigger the validator." If tomorrow you deleted the entire validation folder, the JSX wouldn't notice. That independence —UI that renders, domain that validates, no props tying them together— is exactly what we promised when we said "an invalid field is a domain rule, not a UI state."

Two clarifications

On asynchronous validation. In every example, validate() and execute() are synchronous: the rule receives its data, decides, and returns the list of errors on the spot. For most form validation that's exactly what you want. But the contract doesn't tie you to synchronous: if you need a rule that depends on a server call —checking that an email isn't already registered, for instance— nothing stops you from making validate() return a Promise<AppException[]> and having execute() await it. The idea —a rule is an object that knows how to enumerate what's wrong— doesn't change; what changes is that the answer can now take time. Use it where it's needed, without turning the whole system asynchronous just because.

On the framework. I used React in the examples because it's what I have in production, but notice that the heart of the system —ValidationRule, AppException, the Validator that composes rules— is pure TypeScript: it doesn't import a single line of React. The layer that touches the framework is minimal and lives only in the component (the useState, the handleSubmit). Taking this to Vue, Angular, or Svelte means rewriting that thin layer —a ref instead of useState, a component method instead of a hook— and reusing the entire domain as-is.

Let's talk

Questions, feedback, or a different take? I'd love to hear from you. You can find me here:

GitHub — hgomezrobaina
LinkedIn — Héctor Gómez Robaina
X — @hgomezrobaina

Validación de formularios sin dependencias: trata las reglas como lógica de dominio en el frontend

Hector Angel Gomez Robaina — Sun, 28 Jun 2026 22:13:01 +0000

Todos hemos pasado por esto. Llega un formulario nuevo, instalas React Hook Form, le sumas Zod o Yup, y en diez minutos tienes algo que "funciona". El problema no aparece ese día. Aparece tres meses después, cuando esa misma regla que validas al crear también hay que validarla al editar, al importar desde Excel, y resulta que está escrita tres veces, ligeramente distinta cada una, y ninguna vive en un lugar que puedas señalar y decir "aquí está la definición". La validación se diluyó por toda la app y dejó de tener dueño.

Para no hablar en abstracto, durante el artículo usaré un caso concreto: validar el VIN de un auto —el número de chasis—, porque es una regla real de un proyecto personal y tiene la sustancia justa para mostrar el patrón. Pero todo lo que sigue aplica igual a un email, a un monto o a cualquier campo con reglas de negocio: el VIN es solo el ejemplo, no el tema.

Un formulario típico con librería se ve más o menos así:

const schema = z.object({
  vin: z.string().length(17, "El VIN debe tener 17 caracteres"),
  miles: z.number().min(0, "Las millas no pueden ser negativas"),
  // ...y 8 campos más
});

const {
  register,
  handleSubmit,
  watch,
  formState: { errors },
} = useForm({
  resolver: zodResolver(schema),
});

Funciona. Pero si te detienes a mirarlo, estás pagando tres costos que casi nunca se nombran:

1. El código limpio se diluye. La regla de negocio termina repartida entre el schema, el resolver, los register, los Controller y el JSX. El conocimiento —qué hace válido a un auto— no tiene una casa. Está cableado a la UI. Y lo que está cableado a la UI no se reutiliza: se copia.

2. El rendimiento y el acople se pagan en silencio. Estas librerías viven de suscripciones: watch, re-renders por tecla, estado interno que sincronizar. Para un formulario de contacto da igual. Para una pantalla con 15 campos, sub-formularios y validaciones cruzadas, tu componente queda atado al ciclo de vida de la librería —no al tuyo— y empiezas a pelear contra ella en lugar de usarla.

3. La comodidad de desarrollo es una trampa. Es comodísimo al principio. Pero esa misma regla, ¿cómo la pruebas sin montar un componente? ¿Cómo la mueves al backend? ¿Cómo la traduces a dos idiomas sin ensuciar el schema? Cada cosa que la librería te resolvió gratis, te la cobra el día que necesitas salir de su molde.

Ninguno de estos problemas es culpa de Formik ni de React Hook Form. Son excelentes en lo que hacen: cablear inputs a estado. El problema es que les delegamos algo que nunca fue su trabajo —decidir qué es válido— y ahí es donde el dominio se nos escapa hacia la capa de presentación.

La tesis

Todo el enfoque que voy a mostrar sale de una sola idea:

Un campo inválido es una regla de dominio, no un estado de la UI.

Si lo aceptas, las consecuencias son directas. La validación no pertenece al componente: pertenece al dominio, igual que tus modelos y tus servicios. Una regla deja de ser una línea en un schema y pasa a ser una unidad nombrable y testeable. El componente vuelve a su único trabajo —pintar y disparar— y le pregunta al dominio "¿esto es válido?"

No es más código por gusto. Es mover el conocimiento del negocio al lugar donde se puede reutilizar, probar sin React, traducir sin esfuerzo y, el día que toque, llevar al backend sin reescribir una línea de lógica.

En lo que sigue voy a desarmar el sistema que uso en mis proyectos: un contrato de cuatro líneas, reglas como clases, y cómo todo eso se consume desde un componente con un simple useState.

3. El contrato mínimo: una regla y un error

Antes de escribir una sola validación necesitamos definir dos cosas: qué es una regla y qué es un error. Ambas son bastante pequeñas.

Una regla es cualquier objeto que sepa responder "¿qué está mal aquí?":

export interface ValidationRule {
  validate(): AppException[];
}

Eso es todo. Sin estado, sin React, sin genéricos. Una ValidationRule recibe lo que necesite por su constructor y devuelve una lista de errores. Si la lista está vacía, el campo es válido. El detalle que parece menor pero no lo es: devuelve un array, no un boolean ni un string. Un campo puede fallar por varias razones a la vez, y quien valida solo reporta —no decide cómo se muestran.

¿Y qué es un error? No un string suelto:

export class AppException {
  readonly id: string;
  readonly message: TranslationConfig;

  constructor({ id, message }: { id: string; message: TranslationConfig }) {
    this.id = id;
    this.message = message;
  }
}

Dos campos, dos decisiones.

El message es un TranslationConfig ({ es, en }): el error nace ya traducido, en lo profundo del dominio, en lugar de ser un string que alguien tiene que acordarse de pasar por i18n en la capa de UI.

Nota: No todos los sistemas necesitan esto. Si tu app es multi-idioma te ahorra mantener un mapa de claves sincronizado con cada regla; si no, puedes dejar message como un simple string. Lo dejo aquí y sigo, porque la pieza realmente interesante es la otra.

El id es lo que convierte este error en algo testeable de verdad. Un id estable e independiente del idioma —"car.vin.empty", "car.miles.negative"— te da un identificador que no cambia aunque reescribas el texto ni cambies el idioma. Y eso desbloquea dos cosas:

En pruebas E2E, puedes pintar ese id como data-error-id en el DOM y aseverar "apareció el error de VIN vacío" sin acoplar la prueba al texto exacto del mensaje (que cambia, que se traduce, que se ajusta). La prueba verifica la regla, no la copia.
En pruebas unitarias, puedes ir un paso más allá y hacer que cada error sea su propia subclase de AppException:

  export class VinEmptyException extends AppException {
    constructor() {
      super({
        id: "car.vin.empty",
        message: {
          es: "El VIN no puede estar vacío",
          en: "The VIN cannot be empty",
        },
      });
    }
  }

Y entonces el assert es de tipos, no de strings:

  const errors = new CarVinValidator("").validate();

  expect(errors.some((e) => e instanceof VinEmptyException)).toBe(true);
  // o, si prefieres el id:
  expect(errors[0].id).toBe("car.vin.empty");

Compáralo con la alternativa frágil de toda la vida: expect(errors[0].message).toContain("vacío"). Esa aserción se rompe el día que alguien corrige una tilde. La de arriba sobrevive a cualquier cambio de copy, en cualquier idioma.

Con eso, el contrato completo del sistema son dos piezas:

ValidationRule → "sé decidir si algo es válido y, si no, enumero exactamente qué falló".
AppException → "soy un error con identidad estable (id) y, ya de paso, sé decirme en todos los idiomas que la app habla".

Todo lo que viene —reglas, composición, el disparo desde el componente— se apoya en estas dos. No hay más "framework" que aprender: una interfaz y una clase de datos. El día que entra alguien nuevo al proyecto, esto es todo lo que tiene que leer para entender cómo validamos.

Nota de diseño: que validate() no reciba argumentos es a propósito. El valor entra por el constructor, no por el método. Eso hace que cada regla sea un objeto autocontenido —lo construyes con su dato y queda listo para preguntarle—, y es lo que permite meterlas todas en una lista y correrlas en bucle sin que el orquestador sepa nada de cada una (sección 5).

4. Una regla = una clase

Esta es la idea central, y ahora que tenemos el contrato cabe en muy poco. Una regla de negocio es una clase que implementa ValidationRule, mete toda su lógica adentro y devuelve los errores que encuentre.

Tomemos una con sustancia. Un VIN (el número de chasis de un auto) es válido si no está vacío, tiene exactamente 17 caracteres y termina en al menos 5 números. Tres formas distintas de fallar, una sola clase:

export class CarVinValidator implements ValidationRule {
  constructor(private readonly value: string) {}

  validate(): AppException[] {
    const value = this.value.trim();

    if (value.length === 0) {
      return [
        new AppException({
          id: "car.vin.empty",
          message: {
            es: "El VIN no puede estar vacío",
            en: "The VIN cannot be empty",
          },
        }),
      ];
    }

    if (value.length !== 17) {
      return [
        new AppException({
          id: "car.vin.length",
          message: {
            es: "El VIN debe tener 17 caracteres",
            en: "The VIN must be 17 characters",
          },
        }),
      ];
    }

    const end = value.slice(-5);

    if (end.split("").some((c) => isNaN(Number(c)))) {
      return [
        new AppException({
          id: "car.vin.end-numbers",
          message: {
            es: "El VIN debe terminar con al menos 5 números",
            en: "The VIN must end with at least 5 numbers",
          },
        }),
      ];
    }

    return [];
  }
}

Eso es todo. Se lee de arriba abajo como la definición del negocio: vacío → error; no son 17 → error; no termina en números → error; si no, válido. El conocimiento de "qué hace válido a un VIN" ahora tiene un lugar con nombre y apellido —CarVinValidator— en vez de estar diluido entre un schema, un resolver y el JSX.

Y mira lo que ganaste casi gratis frente a la versión con librería:

Se prueba sin nada alrededor. Es una clase de TypeScript sin dependencias de React ni del DOM. La construyes con un valor y le preguntas:

const errors = new CarVinValidator("123").validate();

expect(errors[0].id).toBe("car.vin.length"); // 3 caracteres → falla por longitud

Y aquí es donde el id de la sección anterior se paga solo: la prueba verifica la regla (car.vin.length), no el texto del mensaje. Puedes reescribir la copy, corregir una tilde o agregar un tercer idioma, y la prueba sigue verde. Compáralo con expect(errors[0].message).toContain("17"), que se rompe a la primera reformulación.

Vive en el dominio, no en la UI. CarVinValidator no importa nada del front. El día que quieras probarlo, reusarlo en otra pantalla o incluso compartir la lógica con el backend, te llevas la clase entera sin arrastrar una dependencia de presentación.

Si una regla tuviera lógica de verdad pesada y la quisieras compartir tal cual con el backend, podrías extraer esa parte a una clase pura aparte y dejar este validador como un fino adaptador que solo le pone los mensajes. Es una optimización para casos puntuales —no el caso normal—, así que no la persigas por defecto: una clase por regla alcanza para la mayoría de ocasiones.

5. Composición: un formulario es una lista de reglas

Ya tenemos reglas sueltas. Falta el orquestador que las junte y las corra.

export abstract class Validator {
  private readonly rules: ValidationRule[];

  constructor(rules: ValidationRule[]) {
    this.rules = rules;
  }

  execute({ success, error }: Props) {
    const errors: AppException[] = [];

    for (const rule of this.rules) {
      errors.push(...rule.validate());
    }

    if (errors.length === 0) {
      success();
    } else {
      error(errors);
    }
  }
}

El Validator no sabe nada de VINs, ni de millas, ni de autos. Solo sabe una cosa: recibí una lista de reglas, las corro todas, junto los errores y bifurco. Si no hubo errores, llama a success(); si los hubo, se los pasa a error(). Esto es justo lo que la sección 3 anticipaba: como cada regla recibe su dato por el constructor, el orquestador puede recorrerlas en bucle sin conocer ni una.

¿Y cómo se ve validar "un auto entero"? Una clase que extiende Validator y, en su constructor, ensambla las reglas:

export class CarValidator extends Validator {
  constructor({ vin, miles, year, brand, model /* ... */ }: CarValidatorProps) {
    super([
      new CarVinValidator(vin),
      new CarMilesValidator(miles),
      new CarYearValidator(year),
      new NotNullValidator(brand, {
        id: "car.brand.required",
        message: {
          es: "El auto debe tener una marca",
          en: "The car must have a brand",
        },
      }),
      new NotNullValidator(model, {
        id: "car.model.required",
        message: {
          es: "El auto debe tener un modelo",
          en: "The car must have a model",
        },
      }),
    ]);
  }
}

Aquí pasan dos cosas que vale la pena subrayar.

Un formulario nuevo es ensamblar, no reescribir. Validar un auto no implica escribir lógica de validación: implica elegir qué reglas aplican y pasarles sus datos. La lógica ya existe, encapsulada en cada ValidationRule. El validador de la entidad es una lista de la compra.

Las reglas genéricas se reusan en todos lados. Fíjate en NotNullValidator. No es específico de autos: es una regla reutilizable que recibe el valor y el error a lanzar si es null:

export class NotNullValidator<T> implements ValidationRule {
  constructor(
    private readonly value: T | null,
    private readonly exception: AppException,
  ) {}

  validate(): AppException[] {
    return this.value === null ? [this.exception] : [];
  }
}

Diez líneas que validan "este campo es obligatorio" para cualquier tipo, en cualquier formulario. La marca de un auto, el cliente de un deal, el rol de un usuario: todos reusan la misma pieza, solo cambiando el mensaje. Eso es lo opuesto a copiar z.string().min(1) por todo el código: la regla vive una vez y se compone donde haga falta.

Y como Validator es abstracto y recibe un array, no hay nada que te ate a una jerarquía rígida. ¿Necesitas una regla condicional según otro campo? La metes en la lista cuando corresponda. El orquestador ni se entera —para él, todo es "una regla que devuelve errores".

6. El consumo: el componente solo dispara

Llegamos al único punto donde todo esto toca React. Y la promesa de la intro se cumple aquí: el componente no sabe cómo se valida nada. Solo arma su estado, construye el validador y aprieta el gatillo.

Así se ve un formulario de login completo, en un hook:

export default function useLogin() {
  const { errors } = useToast();

  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");

  const handleSubmit = () => {
    const validator = new UserLoginValidator({ email, password });

    validator.execute({
      success: () => loginUser({ email, password }).then(/* ... */),
      error: errors,
    });
  };

  return { email, setEmail, password, setPassword, handleSubmit };
}

Léelo despacio, porque aquí está todo el argumento del artículo condensado:

El estado es useState plano. Un useState por campo. Sin useForm, sin register, sin control, sin resolver. React hace lo que React sabe hacer y nada más.
execute bifurca por ti. Si todas las reglas pasan, corre success —que encadena la llamada al backend—. Si alguna falla, los errores van directo a error. El componente no escribe ni un if: declara qué hacer en cada rama y se desentiende.
error: errors conecta el dominio con la UI en una línea. errors viene de useToast, y recibe el AppException[] tal cual. Como cada error ya nació traducido (sección 3), el toast solo lee message[idioma] y lo pinta. La regla viajó desde el dominio hasta la pantalla sin que nadie tradujera nada por el camino.

Y el JSX que consume ese hook se mantiene completamente ajeno al sistema de validación:

<FormInput label={{ es: "Correo", en: "Email" }} required>
  <input value={email} onChange={(e) => setEmail(e.target.value)} />
</FormInput>

Aquí cierra el contraste que abrimos en la intro. Tu input habla value / onChange. Compáralo con lo que la librería te obliga a escribir:

// React Hook Form: el markup ahora habla el dialecto de la librería
<input {...register("email")} />

<Controller
  name="email"
  control={control}
  render={({ field }) => <MyInput {...field} />}
/>

Ese register, control o <Controller> son props de fontanería que se cuelan por todo tu árbol de componentes. Y el costo no es estético —que el JSX se vea más cargado da igual—; el costo es acoplamiento: el día que quieras cambiar de librería, o sacarla, no tocas un archivo de configuración, tocas cada input de cada formulario. Tu capa de presentación quedó casada con una dependencia externa.

En este enfoque esa atadura no existe. El FormInput no sabe que hay validación; el <input> no sabe que hay reglas; el componente solo sabe useState y "al enviar, dispara el validador". Si mañana borraras toda la carpeta de validación, el JSX no se enteraría. Esa independencia —UI que pinta, dominio que valida, sin props que los aten— es justamente lo que prometimos cuando dijimos "un campo inválido es una regla de dominio, no un estado de la UI".

Dos aclaraciones

Sobre validaciones asíncronas. En todos los ejemplos, validate() y execute() son síncronos: la regla recibe su dato, decide y devuelve la lista de errores en el acto. Para la mayoría de las validaciones de formulario eso es justo lo que quieres. Pero el contrato no te ata a lo síncrono: si necesitas una regla que dependa de una llamada al servidor —comprobar que un email no esté ya registrado, por ejemplo—, nada te impide hacer que validate() devuelva una Promise<AppException[]> y que execute() la espere con await. La idea —una regla es un objeto que sabe enumerar qué está mal— no cambia; solo cambia que ahora la respuesta puede tardar. Úsalo donde haga falta, sin convertir todo el sistema en asíncrono porque sí.

Sobre el framework. Usé React en los ejemplos porque es lo que tengo en producción, pero fíjate que el corazón del sistema —ValidationRule, AppException, el Validator que compone reglas— es TypeScript puro: no importa ni una línea de React. La capa que toca el framework es mínima y vive solo en el componente (el useState, el handleSubmit). Llevar esto a Vue, Angular o Svelte es reescribir esa capita fina —un ref en vez de useState, un método del componente en vez de un hook— y reutilizar todo el dominio tal cual.

Hablemos

¿Tienes dudas, comentarios o un enfoque distinto? Me encantará leerte. Puedes encontrarme aquí:

GitHub — hgomezrobaina
LinkedIn — Héctor Gómez Robaina
X — @hgomezrobaina

DEV Community: Hector Angel Gomez Robaina

The Criteria pattern in NestJS: what a client may ask for is a file, not a signature

The Criteria pattern in NestJS

Five parameters and a find()

Where this is going

Five coupling points, and one of a different kind

Three costs

1. The URL is a public part of the schema

2. The endpoint grows by multiplication, not by addition

3. What can be asked for is written nowhere

The justification worth discarding

What is already solved

The thesis

The implementation

The domain criteria

The typed filters

The public field enum

The request

The request mapper

The use case and the port

The translation to Mongo

The page and the total come out of the same filter

Point by point

The acid test: the field that does not live in the collection

The same criteria against TypeORM

The other end, briefly

Two honest caveats, and what this is not

Who this is for, and who it is not for

The code

Let's talk

El patrón Criteria en NestJS: lo que un cliente puede pedir es un archivo, no una firma

Cinco parámetros y un find()

Adónde va esto

Cinco puntos, y uno de otra naturaleza

Tres costes

1. La URL es una parte pública del esquema

2. El endpoint crece multiplicando, no sumando

3. Lo que se puede pedir no está escrito en ninguna parte

La justificación que conviene descartar

Qué hay ya resuelto

La tesis

La implementación

El criteria de dominio

Los filtros tipados

El enum de campos públicos

El request

El mapper del request

El caso de uso y el puerto

La traducción a Mongo

La página y el total salen del mismo filtro

Punto por punto

La prueba de fuego: el campo que no vive en la colección

El mismo criteria contra TypeORM

El otro extremo, en un apartado

Dos matices honestos, y lo que esto no es

Para quién es esto, y para quién no

El código

Hablemos

The Repository Pattern in NestJS: a collection that happens to live in a database

Three costs of the coupling

1. The business entity is the table definition

2. Queries have no name

3. The rule cannot be verified without a database

State of the art: what each option solves

The justification worth discarding

The thesis

The minimum contract: the port

The entity is not the table

The adapter: the only piece that knows the ORM

The wiring

The service, again

The shared transaction

Two ways to wire the port

The test that is now possible

Two honest caveats

Who this is for (and who it is not for)

The code

Let's talk

El patrón Repository en NestJS: una colección que, casualmente, vive en una base de datos

Tres costes del acoplamiento

Five parameters and a `find()`

Cinco parámetros y un `find()`

🧯 A single `Errors` namespace

🧯 Un único namespace `Errors`