google-spreadsheet 5.1.0 → 5.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "google-spreadsheet",
-  "version": "5.1.0",
+  "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

@@ -152,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;
@@ -92,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 */

package/src/lib/GoogleSpreadsheetWorksheet.ts

@@ -250,7 +250,10 @@ export class GoogleSpreadsheetWorksheet {
         return `${this.a1SheetName}!${filter}`;
       }
       if (_.isObject(filter)) {
-        // TODO: detect and support DeveloperMetadata filters
+        // pass through developer metadata filters without adding sheetId
+        if ('developerMetadataLookup' in filter) {
+          return filter;
+        }
 
         // check if the user passed in a sheet id
         const filterAny = filter as any;
@@ -714,7 +717,7 @@ export class GoogleSpreadsheetWorksheet {
    */
   async updateDimensionProperties(
     columnsOrRows: WorksheetDimension,
-    properties: WorksheetDimensionProperties,
+    properties: Partial<WorksheetDimensionProperties>,
     bounds: Partial<DimensionRangeIndexes>
   ) {
     // Request type = `updateDimensionProperties`

package/src/lib/types/sheets-types.ts

@@ -410,8 +410,8 @@ export type GridRange = {
 };
 export type GridRangeWithoutWorksheetId = Omit<GridRange, 'sheetId'>;
 export type GridRangeWithOptionalWorksheetId = MakeOptional<GridRange, 'sheetId'>;
-export type DataFilter = A1Range | GridRange;
-export type DataFilterWithoutWorksheetId = A1Range | GridRangeWithoutWorksheetId;
+export type DataFilter = A1Range | GridRange | DataFilterObject;
+export type DataFilterWithoutWorksheetId = A1Range | GridRangeWithoutWorksheetId | DataFilterObject;
 
 /**
  * A coordinate in a sheet. All indexes are zero-based.