google-spreadsheet 3.1.15 → 3.2.0

package/.eslintrc.js

@@ -33,6 +33,7 @@ module.exports = {
       exports: 'always-multiline',
       functions: 'never', // this breaks
     }],
+    'no-multiple-empty-lines': 0, // sometimes helpful to break up sections of code
   },
   overrides: [
     { // extra jest related rules for tests

package/Changelog.md

@@ -0,0 +1,10 @@
+# Changelog
+
+TODO: set this up to be automated and pulled from git commits... for now just going to leave some notes manually!
+
+### 3.2.0 (2021-11-07)
+
+- Added `insertDimension` functionality
+- Added custom header row index for row-based API
+- Bumped dependency versions
+- Readme/docs cleanup

package/README.md

@@ -44,8 +44,10 @@ const { GoogleSpreadsheet } = require('google-spreadsheet');
 // Initialize the sheet - doc ID is the long id in the sheets URL
 const doc = new GoogleSpreadsheet('<the sheet ID from the url>');
 
-// Initialize Auth - see more available options at https://theoephraim.github.io/node-google-spreadsheet/#/getting-started/authentication
+// Initialize Auth - see https://theoephraim.github.io/node-google-spreadsheet/#/getting-started/authentication
 await doc.useServiceAccountAuth({
+  // env var values are copied from service account credentials generated by google
+  // see "Authentication" section in docs for more info
   client_email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,
   private_key: process.env.GOOGLE_PRIVATE_KEY,
 });

package/TODO

@@ -1,3 +1,7 @@
+- support more cell functionality
+  - data validation rules - https://github.com/theoephraim/node-google-spreadsheet/issues/487
+
+- dont explode if sheet contains charts - https://github.com/theoephraim/node-google-spreadsheet/issues/444
 - add row.toJSON()
   https://github.com/theoephraim/node-google-spreadsheet/issues/247
 - google auth - Application Default Creds
@@ -16,6 +20,16 @@
   https://github.com/theoephraim/node-google-spreadsheet/issues/404
 
 
+- nice tips here - https://github.com/mikro-orm/mikro-orm/issues/12
+- start using semantic release? or similar https://semantic-release.gitbook.io/semantic-release/
+- better commit messages to autogenerate changelog
+  - commitizen - https://github.com/commitizen/cz-cli
+    - https://gist.github.com/brianclements/841ea7bffdb01346392c
+  - commitlint checks - https://github.com/conventional-changelog/commitlint
+  - https://github.com/conventional-changelog/conventional-changelog
+
+
+
 
 
 BUGS

package/lib/GoogleSpreadsheet.js

@@ -299,15 +299,16 @@ class GoogleSpreadsheet {
     // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#AddSheetRequest
 
     const response = await this._makeSingleUpdateRequest('addSheet', {
-      properties: _.omit(properties, 'headers', 'headerValues'),
+      properties: _.omit(properties, 'headers', 'headerValues', 'headerRowIndex'),
     });
     // _makeSingleUpdateRequest already adds the sheet
     const newSheetId = response.properties.sheetId;
     const newSheet = this.sheetsById[newSheetId];
 
     // allow it to work with `.headers` but `.headerValues` is the real prop
-    if (properties.headerValues || properties.headers) {
-      await newSheet.setHeaderRow(properties.headerValues || properties.headers);
+    const headers = properties.headerValues || properties.headers;
+    if (headers) {
+      await newSheet.setHeaderRow(headers, properties.headerRowIndex);
     }
 
     return newSheet;

package/lib/GoogleSpreadsheetCell.js

@@ -202,7 +202,6 @@ class GoogleSpreadsheetCell {
       delete (format.backgroundColorStyle);
     }
 
-
     return {
       updateCells: {
         rows: [{

package/lib/GoogleSpreadsheetWorksheet.js

@@ -20,6 +20,8 @@ class GoogleSpreadsheetWorksheet {
   constructor(parentSpreadsheet, { properties, data }) {
     this._spreadsheet = parentSpreadsheet; // the parent GoogleSpreadsheet instance
 
+    this._headerRowIndex = 1; // assume "header row" (for row-based calls) is in first row
+
     // basic properties
     this._rawProperties = properties;
 
@@ -51,6 +53,7 @@ class GoogleSpreadsheetWorksheet {
   resetLocalCache(dataOnly) {
     if (!dataOnly) this._rawProperties = null;
     this.headerValues = null;
+    this._headerRowIndex = 1;
     this._cells = [];
   }
 
@@ -174,7 +177,6 @@ class GoogleSpreadsheetWorksheet {
     return this._cells[rowIndex][columnIndex];
   }
 
-
   async loadCells(sheetFilters) {
     // load the whole sheet
     if (!sheetFilters) return this._spreadsheet.loadCells(this.a1SheetName);
@@ -283,11 +285,11 @@ class GoogleSpreadsheetWorksheet {
   //   });
   // }
 
-
   // ROW BASED FUNCTIONS ///////////////////////////////////////////////////////////////////////////
 
-  async loadHeaderRow() {
-    const rows = await this.getCellsInRange(`A1:${this.lastColumnLetter}1`);
+  async loadHeaderRow(headerRowIndex) {
+    if (headerRowIndex !== undefined) this._headerRowIndex = headerRowIndex;
+    const rows = await this.getCellsInRange(`A${this._headerRowIndex}:${this.lastColumnLetter}${this._headerRowIndex}`);
     if (!rows) {
       throw new Error('No values in the header row - fill the first row with header values before trying to interact with rows');
     }
@@ -298,7 +300,7 @@ class GoogleSpreadsheetWorksheet {
     checkForDuplicateHeaders(this.headerValues);
   }
 
-  async setHeaderRow(headerValues) {
+  async setHeaderRow(headerValues, headerRowIndex) {
     if (!headerValues) return;
     if (headerValues.length > this.columnCount) {
       throw new Error(`Sheet is not large enough to fit ${headerValues.length} columns. Resize the sheet first.`);
@@ -310,15 +312,17 @@ class GoogleSpreadsheetWorksheet {
       throw new Error('All your header cells are blank -');
     }
 
+    if (headerRowIndex) this._headerRowIndex = headerRowIndex;
+
     const response = await this._spreadsheet.axios.request({
       method: 'put',
-      url: `/values/${this.encodedA1SheetName}!1:1`,
+      url: `/values/${this.encodedA1SheetName}!${this._headerRowIndex}:${this._headerRowIndex}`,
       params: {
         valueInputOption: 'USER_ENTERED', // other option is RAW
         includeValuesInResponse: true,
       },
       data: {
-        range: `${this.a1SheetName}!1:1`,
+        range: `${this.a1SheetName}!${this._headerRowIndex}:${this._headerRowIndex}`,
         majorDimension: 'ROWS',
         values: [[
           ...trimmedHeaderValues,
@@ -369,7 +373,7 @@ class GoogleSpreadsheetWorksheet {
 
     const response = await this._spreadsheet.axios.request({
       method: 'post',
-      url: `/values/${this.encodedA1SheetName}!A1:append`,
+      url: `/values/${this.encodedA1SheetName}!A${this._headerRowIndex}:append`,
       params: {
         valueInputOption: options.raw ? 'RAW' : 'USER_ENTERED',
         insertDataOption: options.insert ? 'INSERT_ROWS' : 'OVERWRITE',
@@ -423,7 +427,7 @@ class GoogleSpreadsheetWorksheet {
 
     if (!this.headerValues) await this.loadHeaderRow();
 
-    const firstRow = 2 + options.offset; // skip first row AND not zero indexed
+    const firstRow = 1 + this._headerRowIndex + options.offset;
     const lastRow = firstRow + options.limit - 1; // inclusive so we subtract 1
     const lastColumn = columnToLetter(this.headerValues.length);
     const rawRows = await this.getCellsInRange(
@@ -632,9 +636,35 @@ class GoogleSpreadsheetWorksheet {
     // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#FindReplaceRequest
   }
 
-  async insertDimension() {
+  async insertDimension(columnsOrRows, range, inheritFromBefore = null) {
     // Request type = `insertDimension`
     // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#InsertDimensionRequest
+
+    if (!columnsOrRows) throw new Error('You need to specify a dimension. i.e. COLUMNS|ROWS');
+    if (!_.isObject(range)) throw new Error('`range` must be an object containing `startIndex` and `endIndex`');
+    if (!_.isInteger(range.startIndex) || range.startIndex < 0) throw new Error('range.startIndex must be an integer >=0');
+    if (!_.isInteger(range.endIndex) || range.endIndex < 0) throw new Error('range.endIndex must be an integer >=0');
+    if (range.endIndex <= range.startIndex) throw new Error('range.endIndex must be greater than range.startIndex');
+
+    // default inheritFromBefore to true - unless inserting in the first row/column
+    if (inheritFromBefore === null) {
+      inheritFromBefore = range.startIndex > 0;
+    }
+
+    // do not allow inheritFromBefore if inserting at first row/column
+    if (inheritFromBefore && range.startIndex === 0) {
+      throw new Error('Cannot set inheritFromBefore to true if inserting in first row/column');
+    }
+
+    return this._makeSingleUpdateRequest('insertDimension', {
+      range: {
+        sheetId: this.sheetId,
+        dimension: columnsOrRows,
+        startIndex: range.startIndex,
+        endIndex: range.endIndex,
+      },
+      inheritFromBefore,
+    });
   }
 
   async insertRange() {

package/package.json

@@ -2,7 +2,7 @@
   "author": "Theo Ephraim <theozero@gmail.com> (https://theoephraim.com)",
   "name": "google-spreadsheet",
   "description": "Google Sheets API (v4) -- simple interface to read/write data and manage sheets",
-  "version": "3.1.15",
+  "version": "3.2.0",
   "license": "Unlicense",
   "keywords": [
     "google spreadsheets",
@@ -26,9 +26,9 @@
     "node": ">=0.8.0"
   },
   "dependencies": {
-    "axios": "^0.21.1",
+    "axios": "^0.21.4",
     "google-auth-library": "^6.1.3",
-    "lodash": "^4.17.20"
+    "lodash": "^4.17.21"
   },
   "devDependencies": {
     "delay": "^4.3.0",