Listings
A TypeScript SDK listing: awaited, one page as the API answers it; iterated, every item of every page, each page fetched as the loop reaches it.
An operation that takes a cursor and answers a page with a nextCursor is a
listing, and its method answers a PagePromise:
const page = await openemail.messages.list(mailboxId, { limit: 50 }) // one page, nextCursor and all
for await (const message of openemail.messages.list(mailboxId)) {} // every message of every page
for await (const page of openemail.messages.list(mailboxId).pages()) {} // page by page
const all = await openemail.routes.list({ domain: 'example.com' }).all() // every item in one array- Awaited, it is its first page, exactly as the API answers it: the
items and the
nextCursor, typed by the method's own page type (MessagesListResult). - Iterated with
for await, it is every item of every page, each page fetched as the loop reaches it. Stop the loop and no further page is fetched. .pages()gives each page whole, for a loop that needs the cursor;.all()gathers every item into one array. A listing can be long: iterate it where it might not fit in memory..withResponse()answers the first page with theResponseit came in (Responses and headers).
How it pages
- Nothing is sent until it is awaited or iterated, and its first page is fetched once, however often it is asked for.
- Each next page is the same call with the cursor the last page named; the other options stay as they were, as the API asks of a crawl (its filters, its order, its sort).
- A page whose
nextCursoris missing, empty, or a cursor already fetched is the last, so a cycle cannot loop. - Where a page holds several lists, the item is the one the page is about: an
event log's
events, a search'sresults(or, withfields: 'ids', itsids).
The API's own rules for cursors are in the
API reference's overview: limit caps at 200 on most
listings, and a cursor is opaque. Each listing's page in this reference says
its item type, for example messages.list.
Calling methods
How a TypeScript SDK method takes its arguments: the path's parameters, the body or its raw bytes, the operation's options, and what every call takes.
Responses and headers
What a TypeScript SDK method answers, how withResponse() gives its Response for the headers, and conditional reads and writes with ETags.