Paginator

Reference for the Paginator class in the X API TypeScript SDK. Iterate paginated response results with async iterators and cursor helpers.

X API paginator with rich functionality

This class provides comprehensive pagination support for the X API, including:

• Automatic iteration with for await...of loops
• Manual page control with fetchNext() and fetchPrevious()
• Metadata access for pagination tokens and counts
• Error handling and rate limit detection
• Support for both forward and backward pagination

Example

// Automatic iteration
const followers = await client.users.getFollowers('783214');
for await (const follower of followers) {
  console.log(follower.username);
}

// Manual control
const followers = await client.users.getFollowers('783214');
await followers.fetchNext();
console.log(followers.items.length); // Number of followers
console.log(followers.meta.nextToken); // Next page token

// Check status
if (!followers.done) {
  await followers.fetchNext();
}

Type parameters

Name	Description
T	The type of items being paginated

Hierarchy

• Paginator

  ↳ PostPaginator

  ↳ UserPaginator

  ↳ EventPaginator

Implements

• AsyncIterable<T>

Constructors

constructor

• new Paginator<T>(fetchPage): Paginator<T>

Creates a new paginator instance

Type parameters

Name
T

Parameters

Name	Type	Description
fetchPage	(token?: string) => Promise<PaginatedResponse<T>>	Function that fetches a page of data given a pagination token

Returns

Paginator<T>

Defined in

paginator.ts:90

Accessors

items

• get items(): T[]

Get all fetched items

Returns

T[]

Defined in

paginator.ts:97

---

meta

• get meta(): any

Get current pagination metadata

Returns

any

Defined in

paginator.ts:104

---

includes

• get includes(): undefined | Record<string, any>

Get current includes data

Returns

undefined | Record<string, any>

Defined in

paginator.ts:111

---

errors

• get errors(): undefined | any[]

Get current errors

Returns

undefined | any[]

Defined in

paginator.ts:118

---

done

• get done(): boolean

Check if pagination is done

Returns

boolean

Defined in

paginator.ts:125

---

rateLimited

• get rateLimited(): boolean

Check if rate limit was hit

Returns

boolean

Defined in

paginator.ts:132

Methods

fetchNext

▸ fetchNext(): Promise<void>

Fetch the next page and add items to current instance

This method fetches the next page of data and appends the items to the current paginator instance. It updates the pagination state and metadata.

Returns

Promise<void>

Example

const followers = await client.users.getFollowers('783214');
await followers.fetchNext(); // Fetch first page
console.log(followers.items.length); // Number of followers

if (!followers.done) {
  await followers.fetchNext(); // Fetch second page
  console.log(followers.items.length); // Total followers across pages
}

Throws

When the API request fails

Defined in

paginator.ts:156

---

next

▸ next(): Promise<Paginator<T>>

Get next page as a new instance

This method creates a new paginator instance that starts from the next page, without affecting the current paginator’s state.

Returns

Promise<Paginator<T>>

New paginator instance for the next page

Example

const followers = await client.users.getFollowers('783214');
await followers.fetchNext(); // Fetch first page

if (!followers.done) {
  const nextPage = await followers.next(); // Get next page as new instance
  console.log(followers.items.length); // Still first page
  console.log(nextPage.items.length); // Second page
}

Defined in

paginator.ts:211

---

fetchPrevious

▸ fetchPrevious(): Promise<void>

Fetch previous page (if supported)

Returns

Promise<void>

Defined in

paginator.ts:225

---

previous

▸ previous(): Promise<Paginator<T>>

Get previous page as a new instance

Returns

Promise<Paginator<T>>

Defined in

paginator.ts:260

---

fetchLast

▸ fetchLast(count): Promise<void>

Fetch up to a specified number of additional items

Parameters

Name	Type
count	number

Returns

Promise<void>

Defined in

paginator.ts:274

---

reset

▸ reset(): void

Reset paginator to initial state

Returns

void

Defined in

paginator.ts:288

---

[iterator]

▸ [iterator](): Iterator<T, any, undefined>

Iterator for all fetched items

Returns

Iterator<T, any, undefined>

Defined in

paginator.ts:303

---

[asyncIterator]

▸ [asyncIterator](): AsyncIterator<T, any, undefined>

Async iterator that fetches pages automatically

Returns

AsyncIterator<T, any, undefined>

Implementation of

AsyncIterable.[asyncIterator]

Defined in

paginator.ts:312