Skip to content

Search & Pagination ​

Every */search operation is a POST that shares one request DSL and returns a PagedList<T> envelope.

The request shape ​

ts
const page = await zr.parcels.search({
  pageNumber: 1,          // 1-based, min 1
  pageSize: 25,           // 1–1000
  orderBy: ['createdAt desc', 'amount asc'],
  keyword: 'amine',       // simple search across default fields
  advancedSearch: {       // targeted keyword search
    fields: ['trackingNumber', 'customer.name'],
    keyword: 'amine',
  },
  advancedFilter: {       // structured filter (see below)
    field: 'state.id',
    operator: 'eq',
    value: stateId,
  },
});

Field paths are dotted camelCase into the response DTO (customer.name, state.id).

advancedFilter ​

A filter node is either a leaf or a branch.

A leaf targets one field:

ts
{ field: 'level', operator: 'eq', value: 'wilaya' }

A branch combines leaves with a single logic per level (and / or — no mixing within one node):

ts
{
  logic: 'and',
  filters: [
    { field: 'state.id', operator: 'eq', value: stateId },
    { field: 'amount', operator: 'gte', value: 1000 },
  ],
}

Operators ​

eq, neq, contains, startswith, endswith, gt, lt, gte, lte (availability depends on the field type).

Validate paging client-side

The live server tolerates out-of-range paging (pageNumber: 0 returned 200 with defaults, not 400 — drift §9.5). Don't rely on server validation for client bugs.

The PagedList<T> envelope ​

ts
interface PagedList<T> {
  items: T[];
  pageNumber: number;
  pageSize: number;
  totalCount: number;
  totalPages: number;
  hasPrevious: boolean;
  hasNext: boolean;
}

See the generated PagedList.

Auto-paging ​

Every search method exposes a searchAll async iterator built on paginate(). It advances pageNumber itself, stops on hasNext === false, guards against servers that never terminate (the page must advance), and respects an optional maxItems:

ts
let count = 0;
for await (const parcel of zr.parcels.searchAll({ pageSize: 200 }, { maxItems: 1000 })) {
  count++;
}

Sub-resource searches expose their own iterators (e.g. zr.pickupBags.searchParcelsAll(trackingNumber, body), zr.claims.searchCommentsAll(claimId, body), zr.treasury.searchPaymentsAll(body)).

You can also call paginate() directly:

ts
import { paginate } from '@terminaldz/zrexpress-sdk';

for await (const item of paginate((b) => zr.customers.search(b), { pageSize: 100 })) {
  // …
}

Released under the MIT License. Not affiliated with ZR Express.