feat: support retrying requests when rate limited

Author: Niallfitzy1

docs/classes/google-spreadsheet.md

@@ -9,7 +9,7 @@ _Class Reference_
 ## Initialization
 
 ### Existing documents
-#### `new GoogleSpreadsheet(id, auth)` :id=fn-newGoogleSpreadsheet
+#### `new GoogleSpreadsheet(id, auth, rateLimitedRetryConfig)` :id=fn-newGoogleSpreadsheet
 > Work with an existing document
 
 >  You'll need the document ID, which you can find in your browser's URL when you navigate to the document.<br/>
@@ -19,7 +19,7 @@ Param|Type|Required|Description
 ---|---|---|---
 `spreadsheetId` | String | ✅ | Document ID
 `auth` | `GoogleAuth` \|<br/> `JWT` \|<br/> `OAuth2Client` \|<br/> `{ apiKey: string }` \|<br/> `{ token: string }` | ✅ | Authentication to use<br/>See [Authentication](guides/authentication) for more info
-
+`rateLimitedRetryConfig`  | `{` <br/>`maxRetries: number,`<br/>`retryStrategy: (retryCount: number) => number`<br/> `}`  | ❎ | Configure handling for rate limited responses
 
 ### Creating a new document
 

src/lib/GoogleSpreadsheet.ts

@@ -28,8 +28,17 @@ const EXPORT_CONFIG: Record<string, { singleWorksheet?: boolean }> = {
 };
 type ExportFileTypes = keyof typeof EXPORT_CONFIG;
 
-
-
+type RateLimitedRetryConfig = {
+  /**
+   * The maximum number of times to retry the request. 0 means no retries.
+   */
+  maxRetries: number,
+  /**
+   * A function that takes the current retry count and returns the number of milliseconds to wait before the next retry.
+   * @see https://developers.google.com/sheets/api/limits#example-algorithm
+   */
+  retryStrategy: (retryCount: number) => number,
+};
 
 function getAuthMode(auth: GoogleApiAuth) {
   if ('getRequestHeaders' in auth) return AUTH_MODES.GOOGLE_AUTH_CLIENT;
@@ -81,6 +90,7 @@ export class GoogleSpreadsheet {
   private _rawProperties = null as SpreadsheetProperties | null;
   private _spreadsheetUrl = null as string | null;
   private _deleted = false;
+  private _rateLimitedRetryConfig: RateLimitedRetryConfig | undefined;
 
   /**
    * Sheets API [axios](https://axios-http.com) instance
@@ -108,7 +118,8 @@ export class GoogleSpreadsheet {
     /** id of google spreadsheet doc */
     spreadsheetId: SpreadsheetId,
     /** authentication to use with Google Sheets API */
-    auth: GoogleApiAuth
+    auth: GoogleApiAuth,
+    rateLimitedRetryConfig?: RateLimitedRetryConfig
   ) {
     this.spreadsheetId = spreadsheetId;
     this.auth = auth;
@@ -140,8 +151,11 @@ export class GoogleSpreadsheet {
       this._handleAxiosResponse.bind(this),
       this._handleAxiosErrors.bind(this)
     );
-  }
 
+    if (rateLimitedRetryConfig) {
+      this._rateLimitedRetryConfig = rateLimitedRetryConfig;
+    }
+  }
 
   // AUTH RELATED FUNCTIONS ////////////////////////////////////////////////////////////////////////
 
@@ -160,25 +174,48 @@ export class GoogleSpreadsheet {
   /** @internal */
   async _handleAxiosResponse(response: AxiosResponse) { return response; }
   /** @internal */
-  async _handleAxiosErrors(error: AxiosError) {
-    // console.log(error);
-    const errorData = error.response?.data as any;
+  async _handleAxiosErrors(axiosInstance: AxiosInstance) {
+    return (error: AxiosError) => {
+      const responseStatusCode = _.get(error, 'response.status');
+
+      // Handle rate limited responses by retrying based on the rate limited retry config
+      if (responseStatusCode === 429) {
+        const config = error.config as InternalAxiosRequestConfig & { retryCount?: number };
+        const retryCount = config?.retryCount ?? 0;
+
+        const rateLimitedRetryConfig = this._rateLimitedRetryConfig;
+        if (rateLimitedRetryConfig && retryCount < rateLimitedRetryConfig.maxRetries) {
+          config.retryCount = retryCount + 1;
+          const backoff = rateLimitedRetryConfig.retryStrategy(retryCount);
+          return new Promise((resolve) => {
+            setTimeout(
+              () => {
+                resolve(axiosInstance(config));
+              },
+              backoff
+            );
+          });
+        }
+      }
+      // console.log(error);
+      const errorData = error.response?.data as any;
 
-    if (errorData) {
+      if (errorData) {
       // usually the error has a code and message, but occasionally not
-      if (!errorData.error) throw error;
+        if (!errorData.error) throw error;
 
-      const { code, message } = errorData.error;
-      error.message = `Google API error - [${code}] ${message}`;
-      throw error;
-    }
+        const { code, message } = errorData.error;
+        error.message = `Google API error - [${code}] ${message}`;
+        throw error;
+      }
 
-    if (_.get(error, 'response.status') === 403) {
-      if ('apiKey' in this.auth) {
-        throw new Error('Sheet is private. Use authentication or make public. (see https://github.com/theoephraim/node-google-spreadsheet#a-note-on-authentication for details)');
+      if (responseStatusCode === 403) {
+        if ('apiKey' in this.auth) {
+          throw new Error('Sheet is private. Use authentication or make public. (see https://github.com/theoephraim/node-google-spreadsheet#a-note-on-authentication for details)');
+        }
       }
-    }
-    throw error;
+      throw error;
+    };
   }
 
   /** @internal */