Projection, sorting and pagination

Query builders return plain serializable objects and do not execute HTTP. The root entry's singleQuery, listQuery, and pagedQuery build filter queries. Builders of the same names that build deprecated Condition queries, for Wow 8.10 servers, come from @ahoo-wang/wow-client/legacy; their defaults are listed with each signature below. Everything on this page is also exported by @ahoo-wang/wow-client/dsl, which loads no HTTP code — see entry points.

Builder / model	Defaults and precedence
pagination({ index?, size? }?)	index 1, size 10; no integer/range validation in this helper.
projection({ include?, exclude? }?)	Both omitted, so every field is returned. Each call returns a new object.
asc(field), desc(field)	`{ field, direction: ASC/DESC }`; no field validation in these helpers.
singleQuery(options?)	filter defaults to `filter.matchAll()`; projection/sort remain undefined.
listQuery(options?)	filter defaults to `filter.matchAll()`; limit is sent only when given. Without it Wow 9.1.5+ applies its default list size and Wow 8.11 to 9.1.3 answer 400.
pagedQuery(options?)	pagination defaults to a copy of DEFAULT_PAGINATION `{index:1,size:10}`.
pagedList({ total?, list? }?)	list defaults to a new []; total defaults to list.length; returns `{total,list}`.

A null filter throws TypeError (a null condition does the same in the /legacy builders). These checks are not full nested-expression validation. Pagination/list limit helpers do not enforce server limits. An absent or 0 limit leaves it to the server, and the answer depends on its version: Wow 9.1.5 and later apply the configured default list size over HTTP (100 by default); Wow 8.11 to 9.1.3 reject the query with HTTP 400 (IllegalArgument: HTTP list query limit[0] must be between 1 and 1000.), so pass limit explicitly against them. Wow 8.11 and later refuse a limit above the maximum list size (1000 by default). See list queries without a limit.

FilterQueryable and the Filter-prefixed forms use required filter. Queryable/SingleQuery/ListQuery/PagedQuery are the deprecated condition family and, with the *QueryRequest unions that accept either form, are exported by @ahoo-wang/wow-client/legacy; the query clients accept both forms. ProjectionCapable and SortCapable are optional mixins. PagedList is total/list, independent of the requested page index. DEFAULT_PAGINATION is frozen; the builders copy it. No network resources need cleanup. For validated cursor-size constraints use cursorQuery.

Complete example

import {
  listQuery,
  pagedQuery,
  filter,
  projection,
  desc,
  pagedList,
} from '@ahoo-wang/wow-client';
const page = pagedQuery({
  filter: filter.matchAll(),
  pagination: { index: 2, size: 20 },
  projection: projection({ include: ['state.name'] }),
  sort: [desc('state.name')],
});
console.assert(listQuery().limit === undefined);
console.assert(listQuery({ limit: 20 }).limit === 20);
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 = {}.

typescript/wow-client/src/dsl/pagination.ts

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

typescript/wow-client/src/dsl/pagination.ts

DEFAULT_PAGINATION

declare const DEFAULT_PAGINATION: Readonly<Pagination>;

typescript/wow-client/src/dsl/pagination.ts

projection

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

Implementation defaults: options = {}.

typescript/wow-client/src/dsl/projection.ts

Projection

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

typescript/wow-client/src/dsl/projection.ts

ProjectionCapable

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

typescript/wow-client/src/dsl/projection.ts

singleQuery

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

Implementation defaults: filter = filter.matchAll(); options = {}. A null filter throws TypeError.

typescript/wow-client/src/dsl/queryable.ts

Deprecated Condition form, exported by @ahoo-wang/wow-client/legacy (removed in v10):

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

Implementation defaults: condition = all(); options = {}.

typescript/wow-client/src/legacy/queryable.ts

listQuery

export function listQuery<FIELDS extends string = string>(
  options?: Partial<FilterQueryable<FIELDS>> & { limit?: number },
): FilterListQuery<FIELDS>;

Implementation defaults: filter = filter.matchAll(); limit stays undefined; options = {}. A null filter throws TypeError.

typescript/wow-client/src/dsl/queryable.ts

Deprecated Condition form, exported by @ahoo-wang/wow-client/legacy (removed in v10):

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

Implementation defaults: condition = all(); limit = DEFAULT_PAGINATION.size; options = {}.

typescript/wow-client/src/legacy/queryable.ts

pagedQuery

export function pagedQuery<FIELDS extends string = string>(
  options?: Partial<FilterQueryable<FIELDS>> & { pagination?: Pagination },
): FilterPagedQuery<FIELDS>;

Implementation defaults: filter = filter.matchAll(); pagination = { ...DEFAULT_PAGINATION }; options = {}. A null filter throws TypeError.

typescript/wow-client/src/dsl/queryable.ts

Deprecated Condition form, exported by @ahoo-wang/wow-client/legacy (removed in v10):

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

Implementation defaults: condition = all(); pagination = { ...DEFAULT_PAGINATION }; options = {}.

typescript/wow-client/src/legacy/queryable.ts

pagedList

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

Implementation defaults: list = [] (a new array per call); total = list.length; options = {}.

typescript/wow-client/src/dsl/queryable.ts

Queryable

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

Exported by @ahoo-wang/wow-client/legacy; deprecated, removed in v10.

typescript/wow-client/src/legacy/queryable.ts

FilterQueryable

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

typescript/wow-client/src/dsl/queryable.ts

SingleQuery

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

Exported by @ahoo-wang/wow-client/legacy; deprecated, removed in v10.

typescript/wow-client/src/legacy/queryable.ts

FilterSingleQuery

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

typescript/wow-client/src/dsl/queryable.ts

SingleQueryRequest

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

Exported by @ahoo-wang/wow-client/legacy; deprecated, removed in v10. The query clients accept this union, so either form can be sent.

typescript/wow-client/src/legacy/queryable.ts

ListQuery

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

Exported by @ahoo-wang/wow-client/legacy; deprecated, removed in v10.

typescript/wow-client/src/legacy/queryable.ts

FilterListQuery

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

typescript/wow-client/src/dsl/queryable.ts

ListQueryRequest

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

Exported by @ahoo-wang/wow-client/legacy; deprecated, removed in v10. The query clients accept this union, so either form can be sent.

typescript/wow-client/src/legacy/queryable.ts

PagedQuery

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

Exported by @ahoo-wang/wow-client/legacy; deprecated, removed in v10.

typescript/wow-client/src/legacy/queryable.ts

FilterPagedQuery

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

typescript/wow-client/src/dsl/queryable.ts

PagedQueryRequest

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

Exported by @ahoo-wang/wow-client/legacy; deprecated, removed in v10. The query clients accept this union, so either form can be sent.

typescript/wow-client/src/legacy/queryable.ts

PagedList

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

typescript/wow-client/src/dsl/queryable.ts

asc

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

typescript/wow-client/src/dsl/sort.ts

desc

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

typescript/wow-client/src/dsl/sort.ts

SortDirection

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

typescript/wow-client/src/dsl/sort.ts

FieldSort

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

typescript/wow-client/src/dsl/sort.ts

SortCapable

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

typescript/wow-client/src/dsl/sort.ts

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

Projection, sorting and pagination ​

Complete example ​

Public signatures and types ​

pagination ​

Pagination ​

DEFAULT_PAGINATION ​

projection ​

Projection ​

ProjectionCapable ​

singleQuery ​

listQuery ​

pagedQuery ​

pagedList ​

Queryable ​

FilterQueryable ​

SingleQuery ​

FilterSingleQuery ​

SingleQueryRequest ​

ListQuery ​

FilterListQuery ​

ListQueryRequest ​

PagedQuery ​

FilterPagedQuery ​

PagedQueryRequest ​

PagedList ​

asc ​

desc ​

SortDirection ​

FieldSort ​

SortCapable ​

Related topics ​

Projection, sorting and pagination

Complete example

Public signatures and types

pagination

Pagination

DEFAULT_PAGINATION

projection

Projection

ProjectionCapable

singleQuery

listQuery

pagedQuery

pagedList

Queryable

FilterQueryable

SingleQuery

FilterSingleQuery

SingleQueryRequest

ListQuery

FilterListQuery

ListQueryRequest

PagedQuery

FilterPagedQuery

PagedQueryRequest

PagedList

asc

desc

SortDirection

FieldSort

SortCapable

Related topics