Querying & Pagination

The canonical list/read surface on BaseRepository<T>. Every read here merges the current tenant's schoolId into the where for you — see Multi-Tenancy. Year-scoped lists additionally require an explicit campusAcademicYearId in the query DTO — that filter is yours to apply, never auto-merged; see Request Scoping.

Two ways to read a list

Both auto-merge the tenant predicate.

Find options

findAll takes FindManyOptions<T> — the per-request extend surface. Pass where, relations, select, order inline:

const rows = await this.repo.findAll({
  where: { status: 'active' },
  relations: { profile: true },
  select: { id: true, firstName: true },
  order: { createdAt: 'DESC' },
});

Same shape works across findOne, findById, findOneWhere, findAndCount, count, exists. The repo's scopeManyOptions rewrites where to add the tenant predicate, then passes through.

Query builder

createQueryBuilder(alias) returns a normal TypeORM builder with the tenant filter already andWhere-d on, and .where rewired to .andWhere:

qb.where = ((where, params) => boundAndWhere(where, params)) as typeof qb.where;

Cursor pagination

repo.cursorPaginate(alias, options) builds a tenant-injected query builder and pages it with a cursor. Service collection methods that page are named list, not findAll.

async list(query: TransactionListQueryDto) {
  const scope = this.permissionScope.getScope<TransactionEntity>(
    Action.LIST,
    Resource.TRANSACTION,
  );
  return this.transactionRepository.cursorPaginate('tn', {
    ...query,
    scope: scope ?? undefined,
    searchColumns: TransactionService.SEARCH_COLUMNS,
  });
}

The DTO field names line up with the options, so ...query does most of the wiring. The options object:

On the cursor path, findOptions.select, skip, take, and order are ignored — the cursor owns ordering and slicing. (They still work on plain findAll.)

Mechanics: results come back createdAt DESC, id DESC (id is the stable tiebreak; sortPrefix prepends keys ahead of that pair). The helper fetches limit + 1 rows to compute hasMore without a second query, then trims. Backward paging flips order internally, then reverses rows so you read newest-first.

What you get back

export interface CursorPaginatedResult<T> {
  data: T[];
  totalCount: number;
  hasMore: boolean;
  nextCursor: string | null;
  previousCursor: string | null;
}

Controllers document this in OpenAPI with the CursorPaginatedResponseDto(ItemDto) mixin, which wraps the item DTO in the paginated envelope.

The query DTO

List request DTOs extend CursorPaginationQueryDto from @app/shared — it carries search, both cursors, limit, and the date range, already validated:

export class CursorPaginationQueryDto {
  @IsOptional() @IsString() search?: string;
  @IsOptional() @IsUUID() afterId?: string;
  @IsOptional() @IsUUID() beforeId?: string;

  @IsOptional() @Type(() => Number) @IsInt() @Min(1) @Max(100)
  limit?: number; // default 10, coerced from the query string
}

@Type(() => Number) on limit coerces the query-string value before @Min/@Max run — see DTOs & Validation. A feature adds its own filters by extending the base:

export class JobApplicationListQueryDto extends CursorPaginationQueryDto {
  @IsOptional() @IsUUID() vacancyId?: string;
  @IsOptional() @IsEnum(JobApplicationStatus) status?: JobApplicationStatus;
}

The service decides which extra fields map to cursorPaginate options and which become findOptions.where.

Why cursors

An offset is a position, and positions drift: insert or delete a row on page one while a user reads page two and every later offset shifts — they see a row twice or skip one. A cursor anchors on an exact record, so the next page stays correct under concurrent writes.

Where to go next