resolveSelectOffset function

int? resolveSelectOffset({
  1. int? page,
  2. int? offset,
  3. int? limit,
})

Resolves the effective offset of a select* operation from a 1-based page, where limit is the page size.

Returns offset unchanged when page is null, otherwise (page - 1) * limit. A page of 1 resolves to an offset of 0, which still activates the ordering (see OrderDirection.resolveOrderByID), so a paginated select is stable by default.

Throws an ArgumentError when:

  • page and offset are both defined: they are two spellings of the same thing, so passing both is a bug rather than a precedence question;
  • page is defined without a positive limit: a page has no meaning without a page size, and a limit of 0 means "no limit";
  • page is < 1: pages are numbered from 1.

Implementation

int? resolveSelectOffset({int? page, int? offset, int? limit}) {
  if (page == null) return offset;

  if (offset != null) {
    throw ArgumentError.value(
      page,
      'page',
      "`page` and `offset` are mutually exclusive (offset: $offset)",
    );
  }

  if (limit == null || limit <= 0) {
    throw ArgumentError.value(
      page,
      'page',
      '`page` requires a positive `limit` (the page size), got: $limit',
    );
  }

  if (page < 1) {
    throw ArgumentError.value(page, 'page', '`page` is 1-based, must be >= 1');
  }

  return (page - 1) * limit;
}