Add pagination for getNftsForCollection (#6)

Author: thebrianchen

README.md

@@ -32,11 +32,12 @@ const alchemy = initializeAlchemy(settings);
 The SDK's modular approach exports all functions at the top-level to reduce bundle size. However,
 this can make it harder to discover the full API surface. If you want your IDE to find all functions, you can import
 the entire SDK:
+
 ```ts
 import * as alchemySdk from 'exploring-pioneer';
 
 const alchemy = alchemySdk.initializeAlchemy();
-alchemySdk.getNfts(alchemy, {owner: '0x123'});
+alchemySdk.getNfts(alchemy, { owner: '0x123' });
 ```
 
 ## SDK Structure

src/api/nft-api.ts

@@ -63,7 +63,7 @@ export async function getNftMetadata(
   tokenType?: NftTokenType
 ): Promise<Nft> {
   let response;
-  let contractAddress = '';
+  let contractAddress: string;
   if (typeof contractAddressOrBaseNft === 'string') {
     validateContractAddress(contractAddressOrBaseNft);
     contractAddress = contractAddressOrBaseNft;
@@ -95,7 +95,7 @@ export async function getNftMetadata(
 }
 
 /**
- * - Fetches all NFTs for a given owner and yields them in an async iterable.
+ * Fetches all NFTs for a given owner and yields them in an async iterable.
  *
  * This method returns the base NFTs that omit the associated metadata and pages
  * through all page keys until all NFTs have been fetched.
@@ -126,10 +126,16 @@ export async function* getNftsPaginated(
   params: GetNftsParams | GetBaseNftsParams
 ): AsyncIterable<OwnedBaseNft | OwnedNft> {
   const withMetadata = params.withMetadata ?? true;
-  for await (const response of paginateEndpoint(alchemy, 'getNFTs', 'pageKey', {
-    ...params,
-    withMetadata
-  })) {
+  for await (const response of paginateEndpoint(
+    alchemy,
+    'getNFTs',
+    'pageKey',
+    'pageKey',
+    {
+      ...params,
+      withMetadata
+    }
+  )) {
     for (const ownedNft of response.ownedNfts as
       | RawOwnedNft[]
       | RawOwnedBaseNft[]) {
@@ -199,7 +205,6 @@ export async function getNfts(
  * @param params The parameters to use for the request.
  * @beta
  */
-// TODO: Add pagination for this endpoint.
 export async function getNftsForCollection(
   alchemy: Alchemy,
   params: GetBaseNftsForCollectionParams
@@ -216,7 +221,6 @@ export async function getNftsForCollection(
  *   {@link CollectionNftsResponse} response.
  * @beta
  */
-// TODO: add pagination for this endpoint.
 export async function getNftsForCollection(
   alchemy: Alchemy,
   params: GetNftsForCollectionParams
@@ -287,6 +291,63 @@ export function getOwnersForToken(
   }
 }
 
+/**
+ * Fetches all base NFTs for a given contract address and yields them in an
+ * async iterable.
+ *
+ * This method returns the base NFTs that omit the associated metadata and pages
+ * through all page keys until all NFTs have been fetched. To get all NFTs with
+ * their associated metadata, use {@link GetNftsForCollectionParams}.
+ *
+ * @param alchemy The Alchemy SDK instance.
+ * @param params The parameters to use for the request.
+ * @beta
+ */
+export function getNftsForCollectionPaginated(
+  alchemy: Alchemy,
+  params: GetBaseNftsForCollectionParams
+): AsyncIterable<BaseNft>;
+
+/**
+ * Fetches all NFTs for a given contract address and yields them in an async iterable.
+ *
+ * This method returns the full NFTs in the contract and pages through all page
+ * keys until all NFTs have been fetched. To get all NFTs without their
+ * associated metadata, use {@link GetBaseNftsForCollectionParams}.
+ *
+ * @param alchemy The Alchemy SDK instance.
+ * @param params The parameters to use for the request.
+ * @beta
+ */
+export function getNftsForCollectionPaginated(
+  alchemy: Alchemy,
+  params: GetNftsForCollectionParams
+): AsyncIterable<Nft>;
+export async function* getNftsForCollectionPaginated(
+  alchemy: Alchemy,
+  params: GetBaseNftsForCollectionParams | GetNftsForCollectionParams
+): AsyncIterable<BaseNft | Nft> {
+  const withMetadata =
+    params.withMetadata !== undefined ? params.withMetadata : true;
+  for await (const response of paginateEndpoint(
+    alchemy,
+    'getNFTsForCollection',
+    'startToken',
+    'nextToken',
+    {
+      contractAddress: params.contractAddress,
+      startToken: params.pageKey,
+      withMetadata
+    }
+  )) {
+    for (const nft of response.nfts as
+      | RawCollectionBaseNft[]
+      | RawCollectionNft[]) {
+      yield nftFromGetNftCollectionResponse(nft, params.contractAddress);
+    }
+  }
+}
+
 /**
  * Helper method to convert a NFT response received from Alchemy backend to an
  * SDK NFT type.

src/api/nft.ts

@@ -27,7 +27,9 @@ export class BaseNft {
   static fromResponse(ownedNft: RawBaseNft, contractAddress: string): BaseNft {
     return new BaseNft(
       contractAddress,
-      ownedNft.id.tokenId,
+      // We have to normalize the token id here since the backend sometimes
+      // returns the token ID as a hex string and sometimes as an integer.
+      normalizeTokenIdToHex(ownedNft.id.tokenId),
       ownedNft.id.tokenMetadata?.tokenType ?? NftTokenType.UNKNOWN
     );
   }

src/index.ts

@@ -10,6 +10,7 @@ export {
   getNfts,
   getNftsPaginated,
   getNftsForCollection,
+  getNftsForCollectionPaginated,
   getOwnersForToken
 } from './api/nft-api';
 

src/internal/dispatch.ts

@@ -79,13 +79,15 @@ function isRetryableHttpError(err: AxiosError): boolean {
  * @internal
  */
 export async function* paginateEndpoint<
-  PageKey extends string,
-  Req extends Partial<Record<PageKey, string>>,
-  Res extends Partial<Record<string, any> & Record<PageKey, string>>
+  ReqPageKey extends string,
+  ResPageKey extends string,
+  Req extends Partial<Record<string, any> & Record<ReqPageKey, string>>,
+  Res extends Partial<Record<string, any> & Record<ResPageKey, string>>
 >(
   alchemy: Alchemy,
   methodName: string,
-  pageKey: PageKey,
+  reqPageKey: ReqPageKey,
+  resPageKey: ResPageKey,
   params: Req
 ): AsyncIterable<Res> {
   let hasNext = true;
@@ -97,9 +99,8 @@ export async function* paginateEndpoint<
       requestParams
     );
     yield response;
-    if (response[pageKey] !== undefined) {
-      /* eslint-disable @typescript-eslint/no-explicit-any */
-      requestParams[pageKey] = response[pageKey] as any;
+    if (response[resPageKey] !== undefined) {
+      requestParams[reqPageKey] = response[resPageKey] as any;
     } else {
       hasNext = false;
     }

src/types/types.ts

@@ -282,7 +282,8 @@ export interface RawContract {
 }
 
 /**
- * Parameters object for the {@link getNftsForCollection} function.
+ * Parameters object for the {@link getNftsForCollection} and
+ * {@link getNftsForCollectionPaginated} functions.
  *
  * This interface is used to fetch NFTs with their associated metadata. To get
  * Nfts without their associated metadata, use
@@ -307,7 +308,8 @@ export interface GetNftsForCollectionParams {
 }
 
 /**
- * Parameters object for the {@link getNftsForCollection} function.
+ * Parameters object for the {@link getNftsForCollection} and
+ * {@link getNftsForCollectionPaginated} functions.
  *
  * This interface is used to fetch NFTs without their associated metadata. To
  * get Nfts with their associated metadata, use

src/util/util.ts

@@ -9,6 +9,7 @@ export function formatBlock(block: string | number): string {
   return block.toString();
 }
 
+// TODO: Add loglevel options to avoid always logging everything
 export function logger(methodName: string, message: string) {
   console.log(`[${methodName}]: ${message}`);
 }

test/integration.test.ts

@@ -8,6 +8,7 @@ import {
   NftTokenType
 } from '../src';
 import { Alchemy } from '../src/api/alchemy';
+import { getNftsForCollectionPaginated } from '../src/api/nft-api';
 
 /**
  * Temporary test
@@ -117,4 +118,22 @@ describe('E2E integration tests', () => {
     }
     console.log('done', allNfts.length, allNfts);
   });
+
+  it('getNftsForCollectionPaginated', async () => {
+    jest.setTimeout(15000);
+    console.log('lets paginate');
+    const allNfts = [];
+    let totalCount = 0;
+    for await (const nft of getNftsForCollectionPaginated(alchemy, {
+      contractAddress,
+      withMetadata: false
+    })) {
+      if (totalCount === 150) {
+        break;
+      }
+      allNfts.push(nft);
+      totalCount += 1;
+    }
+    console.log('done', allNfts.length, allNfts[100], totalCount);
+  });
 });