Projection, sorting and pagination

5.x only

This page applies to the 5.x line only (npm 5.1.x, branch 5.x). From 6.0, @ahoo-wang/fetcher-wow lives in the Wow repository (typescript/) and is documented at wow.ahoo.me; its successor @ahoo-wang/wow-client is on npm from Wow 9.2.0 (9.2.1 or later accepts fetcher 6).

Query builders return plain serializable objects and do not execute HTTP. The new filter form and legacy condition form have distinct request types and different list defaults. Prefer an explicit limit when migrating.

Builder / model	Defaults and precedence
pagination({ index?, size? }?)	index 1, size 10; no integer/range validation in this helper.
projection({ include?, exclude? }?)	Both omitted; DEFAULT_PROJECTION is {}. defaultProjection() returns the shared default object, not a fresh copy.
asc(field), desc(field)	{ field, direction: ASC/DESC }; no field validation in these helpers.
singleQuery(options?)	No filter → condition all(); projection/sort remain undefined.
listQuery(options?)	Legacy condition form defaults limit 10; filter form defaults limit 0. Explicit 0 is retained.
pagedQuery(options?)	pagination DEFAULT_PAGINATION {index:1,size:10}.
pagedList({ total?, list? }?)	list defaults []; total defaults to list.length; returns {total,list}.

When filter is defined it wins over condition; builders output only one of these fields. Null filter throws. Null condition throws when it is selected. These checks are not full nested-expression validation. Pagination/list limit helpers do not enforce server limits, and limit 0's endpoint semantics must be supported by the server. The filter-form default is the wire value 0, not a client-side promise to fetch all rows.

Queryable/SingleQuery/ListQuery/PagedQuery are the legacy condition family. FilterQueryable and the Filter-prefixed forms use required filter. *QueryRequest unions accept either. ProjectionCapable and SortCapable are optional mixins. PagedList is total/list, independent of the requested page index. Shared DEFAULT_* and EMPTY_PAGED_LIST constants are mutable objects in JavaScript; treat them as read-only defaults. No network resources need cleanup. For validated cursor-size constraints use cursorQuery.

Complete example

import {
  listQuery,
  pagedQuery,
  filter,
  projection,
  desc,
  pagedList,
} from '@ahoo-wang/fetcher-wow';
const page = pagedQuery({
  filter: filter.matchAll(),
  pagination: { index: 2, size: 20 },
  projection: projection({ include: ['state.name'] }),
  sort: [desc('state.name')],
});
console.assert(listQuery().limit === 10);
console.assert(listQuery({ filter: filter.matchAll() }).limit === 0);
console.assert(pagedList({ list: ['a'] }).total === 1);
console.log(page);

Public signatures and types

These signatures follow declarations reachable from the current root entry. ? marks optional input; generics/interfaces only constrain compile-time types. Locate inherited and related types through the symbol index. Runtime defaults and failure behavior are described above.

pagination

export function pagination(options?: Partial<Pagination>): Pagination;

Implementation defaults: index = DEFAULT_PAGINATION.index; size = DEFAULT_PAGINATION.size; options = DEFAULT_PAGINATION.

packages/wow/src/query/pagination.ts:46

Pagination

export interface Pagination {
  index: number;
  size: number;
}

packages/wow/src/query/pagination.ts:20

DEFAULT_PAGINATION

declare const DEFAULT_PAGINATION: Pagination;

packages/wow/src/query/pagination.ts:29

defaultProjection

export function defaultProjection<
  FIELDS extends string = string,
>(): Projection<FIELDS>;

packages/wow/src/query/projection.ts:28

projection

export function projection<FIELDS extends string = string>(
  options?: Projection<FIELDS>,
): Projection<FIELDS>;

Implementation defaults: options = defaultProjection().

packages/wow/src/query/projection.ts:46

Projection

export interface Projection<FIELDS extends string = string> {
  include?: FIELDS[];
  exclude?: FIELDS[];
}

packages/wow/src/query/projection.ts:17

DEFAULT_PROJECTION

declare const DEFAULT_PROJECTION: Projection<string>;

packages/wow/src/query/projection.ts:26

ProjectionCapable

export interface ProjectionCapable<FIELDS extends string = string> {
  projection?: Projection<FIELDS>;
}

packages/wow/src/query/projection.ts:58

singleQuery

export function singleQuery<FIELDS extends string = string>(
  options: FilterQueryOptions<FilterSingleQuery<FIELDS>>,
): FilterSingleQuery<FIELDS>;

packages/wow/src/query/queryable.ts:91

export function singleQuery<FIELDS extends string = string>(
  options?: Partial<SingleQuery<FIELDS>>,
): SingleQuery<FIELDS>;

packages/wow/src/query/queryable.ts:95

listQuery

export function listQuery<FIELDS extends string = string>(
  options: FilterQueryOptions<FilterListQuery<FIELDS>>,
): FilterListQuery<FIELDS>;

packages/wow/src/query/queryable.ts:149

export function listQuery<FIELDS extends string = string>(
  options?: Partial<ListQuery<FIELDS>>,
): ListQuery<FIELDS>;

packages/wow/src/query/queryable.ts:153

pagedQuery

export function pagedQuery<FIELDS extends string = string>(
  options: FilterQueryOptions<FilterPagedQuery<FIELDS>>,
): FilterPagedQuery<FIELDS>;

packages/wow/src/query/queryable.ts:208

export function pagedQuery<FIELDS extends string = string>(
  options?: Partial<PagedQuery<FIELDS>>,
): PagedQuery<FIELDS>;

packages/wow/src/query/queryable.ts:212

pagedList

export function pagedList<T>(options?: Partial<PagedList<T>>): PagedList<T>;

Implementation defaults: list = []; options = EMPTY_PAGED_LIST.

packages/wow/src/query/queryable.ts:257

Queryable

export interface Queryable<FIELDS extends string = string>
  extends
    ConditionCapable<FIELDS>,
    ProjectionCapable<FIELDS>,
    SortCapable<FIELDS> {}

packages/wow/src/query/queryable.ts:24

FilterQueryable

export interface FilterQueryable<FIELDS extends string = string>
  extends
    FilterCapable<FIELDS>,
    ProjectionCapable<FIELDS>,
    SortCapable<FIELDS> {}

packages/wow/src/query/queryable.ts:31

SingleQuery

export interface SingleQuery<
  FIELDS extends string = string,
> extends Queryable<FIELDS> {}

packages/wow/src/query/queryable.ts:42

FilterSingleQuery

export interface FilterSingleQuery<
  FIELDS extends string = string,
> extends FilterQueryable<FIELDS> {}

packages/wow/src/query/queryable.ts:47

SingleQueryRequest

export type SingleQueryRequest<FIELDS extends string = string> =
  SingleQuery<FIELDS> | FilterSingleQuery<FIELDS>;

packages/wow/src/query/queryable.ts:51

ListQuery

export interface ListQuery<
  FIELDS extends string = string,
> extends Queryable<FIELDS> {
  limit?: number;
}

packages/wow/src/query/queryable.ts:119

FilterListQuery

export interface FilterListQuery<
  FIELDS extends string = string,
> extends FilterQueryable<FIELDS> {
  limit?: number;
}

packages/wow/src/query/queryable.ts:125

ListQueryRequest

export type ListQueryRequest<FIELDS extends string = string> =
  ListQuery<FIELDS> | FilterListQuery<FIELDS>;

packages/wow/src/query/queryable.ts:132

PagedQuery

export interface PagedQuery<
  FIELDS extends string = string,
> extends Queryable<FIELDS> {
  pagination?: Pagination;
}

packages/wow/src/query/queryable.ts:178

FilterPagedQuery

export interface FilterPagedQuery<
  FIELDS extends string = string,
> extends FilterQueryable<FIELDS> {
  pagination?: Pagination;
}

packages/wow/src/query/queryable.ts:184

PagedQueryRequest

export type PagedQueryRequest<FIELDS extends string = string> =
  PagedQuery<FIELDS> | FilterPagedQuery<FIELDS>;

packages/wow/src/query/queryable.ts:190

PagedList

export interface PagedList<T> {
  total: number;
  list: T[];
}

packages/wow/src/query/queryable.ts:236

EMPTY_PAGED_LIST

declare const EMPTY_PAGED_LIST: PagedList<any>;

packages/wow/src/query/queryable.ts:241

asc

export function asc<FIELDS extends string = string>(
  field: FIELDS,
): FieldSort<FIELDS>;

packages/wow/src/query/sort.ts:36

desc

export function desc<FIELDS extends string = string>(
  field: FIELDS,
): FieldSort<FIELDS>;

packages/wow/src/query/sort.ts:50

SortDirection

export enum SortDirection {
  ASC = 'ASC',
  DESC = 'DESC',
}

packages/wow/src/query/sort.ts:18

FieldSort

export interface FieldSort<FIELDS extends string = string> {
  field: FIELDS;
  direction: SortDirection;
}

packages/wow/src/query/sort.ts:26

SortCapable

export interface SortCapable<FIELDS extends string = string> {
  sort?: FieldSort<FIELDS>[];
}

packages/wow/src/query/sort.ts:62

Related topics

Client configuration and metadata · Commands and wait results · Snapshot queries · Filter expressions and legacy conditions · Cursor queries · Aggregation builders · Events and historical state · Identity and resource attribution