Pagination & sorting

findAll(filters?, pagination?, options?) returns a paginated result envelope — not a bare array.

Return shape

type FindAllResult<T> = {
  data: T[];
  total: number;   // total rows matching the filter, ignoring pagination
  page: number;    // echo of the page you requested (1-indexed)
  limit: number;   // echo of the limit you requested, after capping
};

const { data, total, page, limit } = await service.findAll(
  { status: 'active' },
  { page: 2, limit: 25 },
  { search: { term: 'john', columns: ['name', 'email'] } },
);
// data: 25 active users matching "john" for page 2
// total: 240 active users matching "john"
// page: 2
// limit: 25

Pagination options

Sorting

Explicit sortBy

await service.findAll(
  {},
  { sortBy: 'createdAt', sortOrder: 'desc' },
);

sortBy accepts a string or an array. When an array is passed, sortOrder is ignored — each column carries its own order via the entity's defaultSort definition (see below).

Default sort per entity

Define an ordered list of columns in forFeature config — they're applied as the ORDER BY clause when no explicit sortBy is passed. The first column is the primary sort, the rest are tiebreakers.

DrizzleCrudModule.forFeature([
  {
    service: PostsService,
    table: posts,
    config: {
      defaultSort: [
        { column: 'position', order: 'asc' },
        { column: 'created_at', order: 'desc' }, // tiebreaker
      ],
    },
  },
])

// ORDER BY position ASC, created_at DESC
await service.findAll();

// ORDER BY name DESC  — the default is replaced, not appended
await service.findAll({}, { sortBy: 'name' });

Opt-in created_at fallback

Set defaults.sortOrder in forRoot to apply a created_at fallback to every entity that doesn't define its own defaultSort:

DrizzleCrudModule.forRoot({
  dialect: 'postgresql',
  connectionString: process.env.DATABASE_URL,
  schema,
  defaults: {
    sortOrder: 'desc', // every findAll() orders by created_at DESC unless overridden
  },
});

Per-column order defaults to 'asc' when you don't specify it. Unknown columns in defaultSort are skipped and emit a [nestjs-drizzle-crud] defaultSort references unknown column "<col>"; skipping. warning at startup — they never throw. (Caller-supplied sortBy is different: it throws on unknown columns, see below.)

Cap on limit

limit is capped at defaults.pagination.maxLimit. Anything over the cap is silently lowered to the cap. To return more rows per page, raise the cap in forRoot:

defaults: {
  pagination: { defaultLimit: 20, maxLimit: 200 },
}

Clamping & fail-fast

Pagination and sorting inputs are normalized before they reach SQL. Bad input is either silently clamped to a safe value or rejected as BadRequestException (→ 400), depending on the failure mode.

Silently clamped (never throws):

A LIMIT 0 or negative OFFSET can never reach SQL — every value is clamped via the package's shared resolvePagination helper.

Throws BadRequestException (→ 400):

For the full per-method exception table (404 / 409 / 400 / 500 mapping), see Errors.

Cursor-based pagination

The package does not ship cursor-based pagination out of the box. findAll is offset-based. For large datasets, write a custom method that uses Drizzle's where(...).orderBy(...).limit(...) chain with a cursor column (e.g. id > lastSeenId).

Next

• → Relations — eager loading via options.relations
• → Bulk operations — transactional pagination-free reads