clean up setDataValidation

Author: theoephraim

README.md

@@ -25,7 +25,7 @@ Full docs available at [https://theoephraim.github.io/node-google-spreadsheet](h
 
 _The following examples are meant to give you an idea of just some of the things you can do_
 
-> **IMPORTANT NOTE** - To keep the examples concise, I'm calling await [at the top level](https://v8.dev/features/top-level-await) which is not allowed by default in most versions of node. If you need to call await in a script at the root level, you must instead wrap it in an async function like so:
+> **IMPORTANT NOTE** - To keep the examples concise, I'm calling await [at the top level](https://v8.dev/features/top-level-await) which is not allowed in some older versions of node. If you need to call await in a script at the root level and your environment does not support it, you must instead wrap it in an async function like so:
 
 ```javascript
 (async function () {

docs/classes/google-spreadsheet-worksheet.md

@@ -333,6 +333,24 @@ Param|Type|Required|Description
 
 ?> The authentication method being used must have write access to the destination document as well
 
+
+#### `setDataValidation(range, rule)` (async) :id=fn-setDataValidation
+> Sets a data validation rule to every cell in the range
+
+Param|Type|Required|Description
+---|---|---|---
+`range`|Object<br>[GridRange](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/other#GridRange)|✅|Range of cells to apply the rule to, sheetId not required!
+`rule`|Object<br>[DataValidationRule](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/cells#DataValidationRule)<br>or `false`|✅|Object describing the validation rule<br/>Or `false` to unset the rule
+
+
+- ✨ **Side Effects -** sheet is copied to the other doc
+
+?> The authentication method being used must have write access to the destination document as well
+
+
+
+
+
 ### Exports
 
 See [Exports guide](guides/exports) for more info.

pnpm-lock.yaml

@@ -11,7 +11,8 @@ import { GoogleSpreadsheet } from './GoogleSpreadsheet';
 import {
   A1Range, SpreadsheetId, DimensionRangeIndexes, WorksheetDimension, WorksheetId, WorksheetProperties, A1Address,
   RowIndex, ColumnIndex, DataFilterWithoutWorksheetId, DataFilter, GetValuesRequestOptions, WorksheetGridProperties,
-  WorksheetDimensionProperties, CellDataRange, AddRowOptions, GridRangeWithOptionalWorksheetId, GridRange, DataValidationRule,
+  WorksheetDimensionProperties, CellDataRange, AddRowOptions, GridRangeWithOptionalWorksheetId,
+  DataValidationRule,
 } from './types/sheets-types';
 
 
@@ -820,15 +821,20 @@ export class GoogleSpreadsheetWorksheet {
   }
 
   /**
+   * Sets (or unsets) a data validation rule to every cell in the range
    * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#SetDataValidationRequest
    */
-  async setDataValidation({ range, rule }:{ range: Omit<GridRange, 'sheetId'>, rule: DataValidationRule }) {
+  async setDataValidation(
+    range: GridRangeWithOptionalWorksheetId,
+    /** data validation rule object, or set to false to clear an existing rule */
+    rule: DataValidationRule | false
+  ) {
     return this._makeSingleUpdateRequest('setDataValidation', {
       range: {
         sheetId: this.sheetId,
         ...range,
       },
-      rule
+      ...rule && { rule },
     });
   }
 

src/lib/GoogleSpreadsheetWorksheet.ts

@@ -586,16 +586,14 @@ export type ConditionValue =
  * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/other#BooleanCondition
  */
 export type BooleanCondition = {
-  /**
-   * The type of condition.
-   */
+  /** The type of condition. */
   type: ConditionType;
-
   /**
-   * The values of the condition. The number of supported values depends on the condition type. Some support zero values, others one or two values, and ConditionType.ONE_OF_LIST supports an arbitrary number of values.
+   * The values of the condition.
+   * The number of supported values depends on the condition type. Some support zero values, others one or two values, and ConditionType.ONE_OF_LIST supports an arbitrary number of values.
    */
   values: ConditionValue[];
-}
+};
 
 /**
  * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/cells#DataValidationRule
@@ -604,23 +602,12 @@ export type BooleanCondition = {
  * - https://stackoverflow.com/a/43442775/3068233
  */
 export type DataValidationRule = {
-  /**
-   * The condition that data in the cell must match.
-   */
+  /** The condition that data in the cell must match. */
   condition: BooleanCondition;
-
-  /**
-   * A message to show the user when adding data to the cell.
-   */
+  /** A message to show the user when adding data to the cell. */
   inputMessage?: string;
-
-  /**
-   * True if invalid data should be rejected.
-   */
+  /** True if invalid data should be rejected. */
   strict: boolean;
-
-  /**
-   * True if the UI should be customized based on the kind of condition. If true, "List" conditions will show a dropdown.
-   */
+  /** True if the UI should be customized based on the kind of condition. If true, "List" conditions will show a dropdown. */
   showCustomUi: boolean;
-}
+};

src/lib/types/sheets-types.ts

@@ -188,17 +188,29 @@ describe('Managing doc info and sheets', () => {
       await sheet.loadCells();
       expect(sheet.cellStats.nonEmpty).toBe(0);
     });
+  });
+
+  describe.only('data validation rules', () => {
+    let sheet: GoogleSpreadsheetWorksheet;
+
+    beforeAll(async () => {
+      sheet = await doc.addSheet({ title: 'validation rules test' });
+    });
+    afterAll(async () => {
+      await sheet.delete();
+    });
+
 
     it('can set data validation', async () => {
       // add a dropdown; ref: https://stackoverflow.com/a/43442775/3068233
-      await sheet.setDataValidation({
-        range: {
+      await sheet.setDataValidation(
+        {
           startRowIndex: 2,
           endRowIndex: 100,
           startColumnIndex: 3,
           endColumnIndex: 4,
         },
-        rule: {
+        {
           condition: {
             type: 'ONE_OF_LIST',
             values: [
@@ -215,9 +227,21 @@ describe('Managing doc info and sheets', () => {
           },
           showCustomUi: true,
           strict: true,
+        }
+      );
+    });
+
+    it('can clear a data validation', async () => {
+      await sheet.setDataValidation(
+        {
+          startRowIndex: 2,
+          endRowIndex: 100,
+          startColumnIndex: 3,
+          endColumnIndex: 4,
         },
-      })
-    })
+        false
+      );
+    });
   });
 
   describe('deleting a sheet', () => {