Prevent subtype reduction from collapsing collection and paginator return types

2.3.1 (2026-02-27)

There was an issue with the BaseSerializer.serialize method, where returning a Union of collection or paginated data leads to TypeScript's subtype reduction on the inferred return type.

Each serialize call individually resolves to the correct overload:

• serialize(UserTransformer.paginate(...)) → Promise<{ data: UserData[]; metadata: SimplePaginatorMetaKeys }>
• serialize(UserTransformer.transform(...)) → Promise<{ data: UserData[] }>

But when TypeScript infers the combined return type, it sees that { data: UserData[]; metadata: ... } is structurally assignable to { data: UserData[] } (an object with extra properties is always assignable to one with fewer). This means Promise<PaginatedType> is a subtype of Promise<CollectionType>. TypeScript's subtype reduction removes the more specific type from the union, collapsing it down to just, Promise<{ data: UserData[] }>.

The metadata variant gets swallowed entirely.

The fix was to add metadata?: never to the collection return type and make these two types structurally different.

Here's a reproduction with simple code.

https://www.typescriptlang.org/play/?#code/GYVwdgxgLglg9mABMOcAUBnOBbAplACxjAHMAuRAI1QBtcBDMASkQG8BYAKEURmEUw58RUiw7ceiAE74QUpK0QATelHoUA2gEYANIgBMegMwBdPXjUq1FVgF9E9+hjbLV6xGBDZKuKRpMA3IgW9FbuAEq4EHBSSgA8GFBSxCR6icmkAHwOXDy2udKy8i5hmroGxiYOiE4lbhSe3r7+QfmcbVzRYIk1iAC8yKhoSSC4TEA

Bug Fixes

• prevent subtype reduction from collapsing collection and paginator return types (0fa2d7d)

Full Changelog: v2.3.0...v2.3.1