google-spreadsheet 5.0.3 → 5.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "google-spreadsheet",
-  "version": "5.0.3",
+  "version": "5.2.0",
   "description": "Google Sheets API -- simple interface to read/write data and manage sheets",
   "keywords": [
     "google spreadsheets",
@@ -66,6 +66,7 @@
     "eslint-plugin-import": "^2.27.5",
     "eslint-plugin-no-floating-promise": "^1.0.2",
     "google-auth-library": "^10.5.0",
+    "nock": "^14.0.11",
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "varlock": "^0.2.2",
@@ -79,4 +80,4 @@
       "optional": true
     }
   }
-}
+}

package/src/lib/GoogleSpreadsheet.ts

@@ -1,10 +1,18 @@
-import ky, { HTTPError, KyInstance } from 'ky'; // eslint-disable-line import/no-extraneous-dependencies
+import ky, { HTTPError, KyInstance, RetryOptions } from 'ky'; // eslint-disable-line import/no-extraneous-dependencies
 import * as _ from './toolkit';
 import { GoogleSpreadsheetWorksheet } from './GoogleSpreadsheetWorksheet';
 import { getFieldMask } from './utils';
 import {
-  DataFilter, GridRange, NamedRangeId, ProtectedRange,
-  SpreadsheetId, SpreadsheetProperties, WorksheetId, WorksheetProperties,
+  DataFilter,
+  DataFilterObject,
+  DeveloperMetadata,
+  GridRange,
+  NamedRangeId,
+  ProtectedRange,
+  SpreadsheetId,
+  SpreadsheetProperties,
+  WorksheetId,
+  WorksheetProperties,
 } from './types/sheets-types';
 import { PermissionRoles, PermissionsList, PublicPermissionRoles } from './types/drive-types';
 import { RecursivePartial } from './types/util-types';
@@ -112,11 +120,20 @@ export class GoogleSpreadsheet {
    * @category Initialization
    * */
   constructor(
-    /** id of google spreadsheet doc */
+    /** id of Google spreadsheet doc */
     spreadsheetId: SpreadsheetId,
     /** authentication to use with Google Sheets API */
-    auth: GoogleApiAuth
+    auth: GoogleApiAuth,
+    /** Additional options */
+    options?: {
+      /**
+       * customize retry behavior --
+       * see the [ky documentation](https://github.com/sindresorhus/ky#retry) for details of the available options and defaults.
+       * */
+      retryConfig?: RetryOptions | number
+    }
   ) {
+    const { retryConfig } = options || {};
     this.spreadsheetId = spreadsheetId;
     this.auth = auth;
 
@@ -131,6 +148,7 @@ export class GoogleSpreadsheet {
         beforeRequest: [(r) => this._setAuthRequestHook(r)],
         beforeError: [(e) => this._errorHook(e)],
       },
+      retry: retryConfig,
     });
     this.driveApi = ky.create({
       prefixUrl: `${DRIVE_API_BASE_URL}/${spreadsheetId}`,
@@ -138,6 +156,7 @@ export class GoogleSpreadsheet {
         beforeRequest: [(r) => this._setAuthRequestHook(r)],
         beforeError: [(e) => this._errorHook(e)],
       },
+      retry: retryConfig,
     });
   }
 
@@ -395,15 +414,12 @@ export class GoogleSpreadsheet {
   async loadCells(
     /**
      * single filter or array of filters
-     * strings are treated as A1 ranges, objects are treated as GridRange objects
+     * strings are treated as A1 ranges, objects are treated as GridRange objects,
+     * objects with a `developerMetadataLookup` key are treated as DeveloperMetadataLookup filters
      * pass nothing to fetch all cells
      * */
     filters?: DataFilter | DataFilter[]
   ) {
-    // TODO: make it support DeveloperMetadataLookup objects
-
-
-
     // TODO: switch to this mode if using a read-only auth token?
     const readOnlyMode = this.authMode === AUTH_MODES.API_KEY;
 
@@ -416,7 +432,9 @@ export class GoogleSpreadsheet {
         if (readOnlyMode) {
           throw new Error('Only A1 ranges are supported when fetching cells with read-only access (using only an API key)');
         }
-        // TODO: make this support Developer Metadata filters
+        if ('developerMetadataLookup' in filter) {
+          return { developerMetadataLookup: filter.developerMetadataLookup };
+        }
         return { gridRange: filter };
       }
       throw new Error('Each filter must be an A1 range string or a gridrange object');
@@ -631,6 +649,24 @@ export class GoogleSpreadsheet {
     await this.driveApi.delete(`permissions/${permissionId}`);
   }
 
+  // DEVELOPER METADATA ///////////////////////////////////////////////////////////////////////////
+
+  /**
+   * search for developer metadata entries matching the given filters
+   * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.developerMetadata/search
+   */
+  async searchDeveloperMetadata(
+    /** array of DataFilter objects to match against */
+    filters: DataFilterObject[]
+  ): Promise<DeveloperMetadata[]> {
+    const response = await this.sheetsApi.post('developerMetadata:search', {
+      json: { dataFilters: filters },
+    });
+    const data = await response.json<any>();
+    if (!data.matchedDeveloperMetadata) return [];
+    return data.matchedDeveloperMetadata.map((m: any) => m.developerMetadata);
+  }
+
   //
   // CREATE NEW DOC ////////////////////////////////////////////////////////////////////////////////
   static async createNewSpreadsheetDocument(auth: GoogleApiAuth, properties?: Partial<SpreadsheetProperties>) {

package/src/lib/GoogleSpreadsheetCell.ts

@@ -15,6 +15,7 @@ export class GoogleSpreadsheetCell {
   private _rawData?: CellData;
   private _draftData: any = {};
   private _error?: GoogleSpreadsheetCellErrorValue;
+  private _deleted = false;
 
   constructor(
     readonly _sheet: GoogleSpreadsheetWorksheet,
@@ -26,6 +27,8 @@ export class GoogleSpreadsheetCell {
     this._rawData = rawCellData; // so TS does not complain
   }
 
+  get deleted() { return this._deleted; }
+
   // TODO: figure out how to deal with empty rawData
   // newData can be undefined/null if the cell is totally empty and unformatted
   /**
@@ -49,6 +52,25 @@ export class GoogleSpreadsheetCell {
   get a1Row() { return this._rowIndex + 1; } // a1 row numbers start at 1 instead of 0
   get a1Address() { return `${this.a1Column}${this.a1Row}`; }
 
+  /**
+   * @internal
+   * Used internally to update cell indices after deleting rows/columns.
+   * Should not be called directly.
+   */
+  _updateIndices(rowIndex: RowIndex, columnIndex: ColumnIndex) {
+    this._rowIndex = rowIndex;
+    this._columnIndex = columnIndex;
+  }
+
+  /**
+   * @internal
+   * Used internally to mark cell as deleted.
+   * Should not be called directly.
+   */
+  _markDeleted() {
+    this._deleted = true;
+  }
+
   // CELL CONTENTS - VALUE/FORMULA/NOTES ///////////////////////////////////////////////////////////
   get value(): number | boolean | string | null | GoogleSpreadsheetCellErrorValue {
     // const typeKey = _.keys(this._rawData.effectiveValue)[0];
@@ -60,6 +82,8 @@ export class GoogleSpreadsheetCell {
 
 
   set value(newValue: number | boolean | Date | string | null | undefined | GoogleSpreadsheetCellErrorValue) {
+    if (this._deleted) throw new Error('This cell has been deleted - reload cells before making updates.');
+
     // had to include the GoogleSpreadsheetCellErrorValue in the type to make TS happy
     if (newValue instanceof GoogleSpreadsheetCellErrorValue) {
       throw new Error("You can't manually set a value to an error");
@@ -128,10 +152,8 @@ export class GoogleSpreadsheetCell {
     return this.value as string;
   }
   set stringValue(val: string | undefined) {
-    if (val?.startsWith('=')) {
-      throw new Error('Use cell.formula to set formula values');
-    }
-    this.value = val;
+    this._draftData.valueType = 'stringValue';
+    this._draftData.value = val || '';
   }
 
   /**

package/src/lib/GoogleSpreadsheetRow.ts

@@ -13,7 +13,15 @@ export class GoogleSpreadsheetRow<T extends Record<string, any> = Record<string,
     /** raw underlying data for row */
     private _rawData: any[]
   ) {
+    this._padRawData();
+  }
 
+  /** pad _rawData with empty strings so it always matches header length */
+  private _padRawData() {
+    const headerLength = this._worksheet.headerValues.length;
+    while (this._rawData.length < headerLength) {
+      this._rawData.push('');
+    }
   }
 
   private _deleted = false;
@@ -29,6 +37,16 @@ export class GoogleSpreadsheetRow<T extends Record<string, any> = Record<string,
   _updateRowNumber(newRowNumber: number) {
     this._rowNumber = newRowNumber;
   }
+
+  /**
+   * @internal
+   * Used internally to mark row as deleted.
+   * Should not be called directly.
+   */
+  _markDeleted() {
+    this._deleted = true;
+  }
+
   get a1Range() {
     return [
       this._worksheet.a1SheetName,
@@ -82,7 +100,8 @@ export class GoogleSpreadsheetRow<T extends Record<string, any> = Record<string,
       },
     });
     const data = await response.json<any>();
-    this._rawData = data.updatedData.values[0];
+    this._rawData = data.updatedData.values?.[0] || [];
+    this._padRawData();
   }
 
   /** delete this row */