clearRows and clear(range)

docs/classes/google-spreadsheet-worksheet.md

@@ -129,6 +129,20 @@ Param|Type|Required|Description
 !> The older version of this module allowed you to filter and order the rows as you fetched them, but this is no longer supported by google
 
 
+#### `clearRows(options)` (async) :id=fn-clearRows
+> Clear rows in the sheet
+
+By default, this will clear all rows and leave the header (and anything above it) intact, but you can pass in start and/or end to limit which rows are cleared.
+
+Param|Type|Required|Description
+---|---|---|---
+`options`|Object|-|Options object
+`options.start`|Number<br>_int >= 1_|-|A1 style row number of first row to clear<br>_defaults to first non-header row_
+`options.end`|Number<br>_int >= 1_|-|A1 style row number of last row to clear<br>_defaults to last row_
+
+- ✨ **Side effects** - rows in the sheet are emptied
+
+
 ### Working With Cells
 
 The cell-based interface lets you load and update individual cells in a sheeet, including things like the formula and formatting within those cells. It is more feature rich, but tends to be more awkward to use for many simple use cases.
@@ -276,10 +290,16 @@ Param|Type|Required|Description
 
 ### Other
 
-#### `clear()` (async) :id=fn-clear
-> Clear all data/cells in the sheet
+#### `clear(a1Range)` (async) :id=fn-clear
+> Clear data/cells in the sheet
+
+Defaults to clearing the entire sheet, or pass in a specific a1 range
+
+| Param | Type | Required | Description |
+| --- | --- | --- | --- |
+| `a1Range` | String (A1 range) | - | Optional specific range within the sheet to clear |
 
-- ✨ **Side Effects -** clears the entire sheet, resets local cache
+- ✨ **Side Effects -** clears the sheet (entire sheet or specified range), resets local cache
 
 #### `delete()` (async) :id=fn-delete
 > Delete this sheet

lib/GoogleSpreadsheetWorksheet.js

@@ -444,6 +444,13 @@ class GoogleSpreadsheetWorksheet {
     return rows;
   }
 
+  async clearRows(options = {}) {
+    // default to first row after header
+    const startRowIndex = options.start || this._headerRowIndex + 1;
+    const endRowIndex = options.end || this.rowCount;
+    await this._spreadsheet.axios.post(`/values/${this.encodedA1SheetName}!${startRowIndex}:${endRowIndex}:clear`);
+  }
+
   // BASIC PROPS ///////////////////////////////////////////////////////////////////////////////////
   async updateProperties(properties) {
     // Request type = `updateSheetProperties`
@@ -858,10 +865,11 @@ class GoogleSpreadsheetWorksheet {
     });
   }
 
-  async clear() {
-    // clears all the data in the sheet
+  async clear(a1Range) {
+    // clears data in the sheet - defaults to entire sheet
+    const range = a1Range ? `!${a1Range}` : '';
     // sheet name without ie 'sheet1' rather than 'sheet1'!A1:B5 is all cells
-    await this._spreadsheet.axios.post(`/values/${this.encodedA1SheetName}:clear`);
+    await this._spreadsheet.axios.post(`/values/${this.encodedA1SheetName}${range}:clear`);
     this.resetLocalCache(true);
   }
   async downloadAsCSV(returnStreamInsteadOfBuffer = false) {

test/rows.test.js

@@ -408,5 +408,16 @@ describe('Row-based operations', () => {
       const aDataCell = newSheet.getCell(CUSTOM_HEADER_ROW_INDEX, 0);
       expect(aDataCell.value).toEqual('a1');
     });
+
+    it('can clear rows properly when custom header index is used', async () => {
+      await newSheet.clearRows();
+
+      await newSheet.loadCells();
+      // now verify header is still there and data is cleared
+      const aHeaderCell = newSheet.getCell(CUSTOM_HEADER_ROW_INDEX - 1, 0);
+      expect(aHeaderCell.value).toEqual('a');
+      const aDataCell = newSheet.getCell(CUSTOM_HEADER_ROW_INDEX, 0);
+      expect(aDataCell.value).toEqual(null);
+    });
   });
 });