google-spreadsheet 3.3.0 → 4.0.0

package/src/lib/GoogleSpreadsheetCell.ts

@@ -0,0 +1,307 @@
+/* eslint-disable max-classes-per-file */
+import * as _ from 'lodash-es';
+
+import { columnToLetter } from './utils';
+
+import { GoogleSpreadsheetWorksheet } from './GoogleSpreadsheetWorksheet';
+import { GoogleSpreadsheetCellErrorValue } from './GoogleSpreadsheetCellErrorValue';
+
+import {
+  CellData,
+  CellFormat, CellValueType, ColumnIndex, RowIndex,
+} from './types/sheets-types';
+
+export class GoogleSpreadsheetCell {
+  private _rawData?: CellData;
+  private _draftData: any = {};
+  private _error?: GoogleSpreadsheetCellErrorValue;
+
+  constructor(
+    readonly _sheet: GoogleSpreadsheetWorksheet,
+    private _rowIndex: RowIndex,
+    private _columnIndex: ColumnIndex,
+    rawCellData: CellData
+  ) {
+    this._updateRawData(rawCellData);
+    this._rawData = rawCellData; // so TS does not complain
+  }
+
+  // TODO: figure out how to deal with empty rawData
+  // newData can be undefined/null if the cell is totally empty and unformatted
+  /**
+   * update cell using raw CellData coming back from sheets API
+   * @internal
+   */
+  _updateRawData(newData: CellData) {
+    this._rawData = newData;
+    this._draftData = {};
+    if (this._rawData?.effectiveValue && 'errorValue' in this._rawData.effectiveValue) {
+      this._error = new GoogleSpreadsheetCellErrorValue(this._rawData.effectiveValue.errorValue);
+    } else {
+      this._error = undefined;
+    }
+  }
+
+  // CELL LOCATION/ADDRESS /////////////////////////////////////////////////////////////////////////
+  get rowIndex() { return this._rowIndex; }
+  get columnIndex() { return this._columnIndex; }
+  get a1Column() { return columnToLetter(this._columnIndex + 1); }
+  get a1Row() { return this._rowIndex + 1; } // a1 row numbers start at 1 instead of 0
+  get a1Address() { return `${this.a1Column}${this.a1Row}`; }
+
+  // CELL CONTENTS - VALUE/FORMULA/NOTES ///////////////////////////////////////////////////////////
+  get value(): number | boolean | string | null | GoogleSpreadsheetCellErrorValue {
+    // const typeKey = _.keys(this._rawData.effectiveValue)[0];
+    if (this._draftData.value !== undefined) throw new Error('Value has been changed');
+    if (this._error) return this._error;
+    if (!this._rawData?.effectiveValue) return null;
+    return _.values(this._rawData.effectiveValue)[0];
+  }
+
+
+  set value(newValue: number | boolean | Date | string | null | undefined | GoogleSpreadsheetCellErrorValue) {
+    // 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");
+    }
+
+    if (_.isBoolean(newValue)) {
+      this._draftData.valueType = 'boolValue';
+    } else if (_.isString(newValue)) {
+      if (newValue.substring(0, 1) === '=') this._draftData.valueType = 'formulaValue';
+      else this._draftData.valueType = 'stringValue';
+    } else if (_.isFinite(newValue)) {
+      this._draftData.valueType = 'numberValue';
+    } else if (_.isNil(newValue)) {
+      // null or undefined
+      this._draftData.valueType = 'stringValue';
+      newValue = '';
+    } else {
+      throw new Error('Set value to boolean, string, or number');
+    }
+    this._draftData.value = newValue;
+  }
+
+  get valueType(): CellValueType | null {
+    // an error only happens with a formula (as far as I know)
+    if (this._error) return 'errorValue';
+    if (!this._rawData?.effectiveValue) return null;
+    return _.keys(this._rawData.effectiveValue)[0] as CellValueType;
+  }
+
+  /** The formatted value of the cell - this is the value as it's shown to the user */
+  get formattedValue(): string | null { return this._rawData?.formattedValue || null; }
+
+  get formula() { return _.get(this._rawData, 'userEnteredValue.formulaValue', null); }
+  set formula(newValue: string | null) {
+    if (!newValue) throw new Error('To clear a formula, set `cell.value = null`');
+    if (newValue.substring(0, 1) !== '=') throw new Error('formula must begin with "="');
+    this.value = newValue; // use existing value setter
+  }
+  /**
+   * @deprecated use `cell.errorValue` instead
+   */
+  get formulaError() { return this._error; }
+  /**
+   * error contained in the cell, which can happen with a bad formula (maybe some other weird cases?)
+   */
+  get errorValue() { return this._error; }
+
+  get numberValue(): number | undefined {
+    if (this.valueType !== 'numberValue') return undefined;
+    return this.value as number;
+  }
+  set numberValue(val: number | undefined) {
+    this.value = val;
+  }
+
+  get boolValue(): boolean | undefined {
+    if (this.valueType !== 'boolValue') return undefined;
+    return this.value as boolean;
+  }
+  set boolValue(val: boolean | undefined) {
+    this.value = val;
+  }
+
+  get stringValue(): string | undefined {
+    if (this.valueType !== 'stringValue') return undefined;
+    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;
+  }
+
+  /**
+   * Hyperlink contained within the cell.
+   *
+   * To modify, do not set directly. Instead set cell.formula, for example `cell.formula = \'=HYPERLINK("http://google.com", "Google")\'`
+   */
+  get hyperlink() {
+    if (this._draftData.value) throw new Error('Save cell to be able to read hyperlink');
+    return this._rawData?.hyperlink;
+  }
+
+  /** a note attached to the cell */
+  get note(): string {
+    return this._draftData.note !== undefined ? this._draftData.note : this._rawData?.note;
+  }
+  set note(newVal: string | null | undefined | false) {
+    if (newVal === null || newVal === undefined || newVal === false) newVal = '';
+    if (!_.isString(newVal)) throw new Error('Note must be a string');
+    if (newVal === this._rawData?.note) delete this._draftData.note;
+    else this._draftData.note = newVal;
+  }
+
+  // CELL FORMATTING ///////////////////////////////////////////////////////////////////////////////
+  get userEnteredFormat() { return Object.freeze(this._rawData?.userEnteredFormat); }
+  get effectiveFormat() { return Object.freeze(this._rawData?.effectiveFormat); }
+
+  private _getFormatParam<T extends keyof CellFormat>(param: T): Readonly<CellFormat[T]> {
+    // we freeze the object so users don't change nested props accidentally
+    // TODO: figure out something that would throw an error if you try to update it?
+    if (_.get(this._draftData, `userEnteredFormat.${param}`)) {
+      throw new Error('User format is unsaved - save the cell to be able to read it again');
+    }
+    // TODO: figure out how to deal with possible empty rawData
+    // if (!this._rawData?.userEnteredFormat?.[param]) {
+    //   return undefined;
+    // }
+    return Object.freeze(this._rawData!.userEnteredFormat[param]);
+  }
+
+  private _setFormatParam<T extends keyof CellFormat>(param: T, newVal: CellFormat[T]) {
+    if (_.isEqual(newVal, _.get(this._rawData, `userEnteredFormat.${param}`))) {
+      _.unset(this._draftData, `userEnteredFormat.${param}`);
+    } else {
+      _.set(this._draftData, `userEnteredFormat.${param}`, newVal);
+      this._draftData.clearFormat = false;
+    }
+  }
+
+  // format getters
+  get numberFormat() { return this._getFormatParam('numberFormat'); }
+  get backgroundColor() { return this._getFormatParam('backgroundColor'); }
+  get backgroundColorStyle() { return this._getFormatParam('backgroundColorStyle'); }
+  get borders() { return this._getFormatParam('borders'); }
+  get padding() { return this._getFormatParam('padding'); }
+  get horizontalAlignment() { return this._getFormatParam('horizontalAlignment'); }
+  get verticalAlignment() { return this._getFormatParam('verticalAlignment'); }
+  get wrapStrategy() { return this._getFormatParam('wrapStrategy'); }
+  get textDirection() { return this._getFormatParam('textDirection'); }
+  get textFormat() { return this._getFormatParam('textFormat'); }
+  get hyperlinkDisplayType() { return this._getFormatParam('hyperlinkDisplayType'); }
+  get textRotation() { return this._getFormatParam('textRotation'); }
+
+  // format setters
+  set numberFormat(newVal: CellFormat['numberFormat']) { this._setFormatParam('numberFormat', newVal); }
+  set backgroundColor(newVal: CellFormat['backgroundColor']) { this._setFormatParam('backgroundColor', newVal); }
+  set backgroundColorStyle(newVal: CellFormat['backgroundColorStyle']) { this._setFormatParam('backgroundColorStyle', newVal); }
+  set borders(newVal: CellFormat['borders']) { this._setFormatParam('borders', newVal); }
+  set padding(newVal: CellFormat['padding']) { this._setFormatParam('padding', newVal); }
+  set horizontalAlignment(newVal: CellFormat['horizontalAlignment']) { this._setFormatParam('horizontalAlignment', newVal); }
+  set verticalAlignment(newVal: CellFormat['verticalAlignment']) { this._setFormatParam('verticalAlignment', newVal); }
+  set wrapStrategy(newVal: CellFormat['wrapStrategy']) { this._setFormatParam('wrapStrategy', newVal); }
+  set textDirection(newVal: CellFormat['textDirection']) { this._setFormatParam('textDirection', newVal); }
+  set textFormat(newVal: CellFormat['textFormat']) { this._setFormatParam('textFormat', newVal); }
+  set hyperlinkDisplayType(newVal: CellFormat['hyperlinkDisplayType']) { this._setFormatParam('hyperlinkDisplayType', newVal); }
+  set textRotation(newVal: CellFormat['textRotation']) { this._setFormatParam('textRotation', newVal); }
+
+  clearAllFormatting() {
+    // need to track this separately since by setting/unsetting things, we may end up with
+    // this._draftData.userEnteredFormat as an empty object, but not an intent to clear it
+    this._draftData.clearFormat = true;
+    delete this._draftData.userEnteredFormat;
+  }
+
+  // SAVING + UTILS ////////////////////////////////////////////////////////////////////////////////
+
+  // returns true if there are any updates that have not been saved yet
+  get _isDirty() {
+    // have to be careful about checking undefined rather than falsy
+    // in case a new value is empty string or 0 or false
+    if (this._draftData.note !== undefined) return true;
+    if (_.keys(this._draftData.userEnteredFormat).length) return true;
+    if (this._draftData.clearFormat) return true;
+    if (this._draftData.value !== undefined) return true;
+    return false;
+  }
+
+  discardUnsavedChanges() {
+    this._draftData = {};
+  }
+
+  /**
+   * saves updates for single cell
+   * usually it's better to make changes and call sheet.saveUpdatedCells
+   * */
+  async save() {
+    await this._sheet.saveCells([this]);
+  }
+
+  /**
+   * used by worksheet when saving cells
+   * returns an individual batchUpdate request to update the cell
+   * @internal
+   */
+  _getUpdateRequest() {
+    // this logic should match the _isDirty logic above
+    // but we need it broken up to build the request below
+    const isValueUpdated = this._draftData.value !== undefined;
+    const isNoteUpdated = this._draftData.note !== undefined;
+    const isFormatUpdated = !!_.keys(this._draftData.userEnteredFormat || {}).length;
+    const isFormatCleared = this._draftData.clearFormat;
+
+    // if no updates, we return null, which we can filter out later before sending requests
+    if (!_.some([isValueUpdated, isNoteUpdated, isFormatUpdated, isFormatCleared])) {
+      return null;
+    }
+
+    // build up the formatting object, which has some quirks...
+    const format = {
+      // have to pass the whole object or it will clear existing properties
+      ...this._rawData?.userEnteredFormat,
+      ...this._draftData.userEnteredFormat,
+    };
+    // if background color already set, cell has backgroundColor and backgroundColorStyle
+    // but backgroundColorStyle takes precendence so we must remove to set the color
+    // see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/cells#CellFormat
+    if (_.get(this._draftData, 'userEnteredFormat.backgroundColor')) {
+      delete (format.backgroundColorStyle);
+    }
+
+    return {
+      updateCells: {
+        rows: [{
+          values: [{
+            ...isValueUpdated && {
+              userEnteredValue: { [this._draftData.valueType]: this._draftData.value },
+            },
+            ...isNoteUpdated && {
+              note: this._draftData.note,
+            },
+            ...isFormatUpdated && {
+              userEnteredFormat: format,
+            },
+            ...isFormatCleared && {
+              userEnteredFormat: {},
+            },
+          }],
+        }],
+        // turns into a string of which fields to update ex "note,userEnteredFormat"
+        fields: _.keys(_.pickBy({
+          userEnteredValue: isValueUpdated,
+          note: isNoteUpdated,
+          userEnteredFormat: isFormatUpdated || isFormatCleared,
+        })).join(','),
+        start: {
+          sheetId: this._sheet.sheetId,
+          rowIndex: this.rowIndex,
+          columnIndex: this.columnIndex,
+        },
+      },
+    };
+  }
+}

package/src/lib/GoogleSpreadsheetCellErrorValue.ts

@@ -0,0 +1,25 @@
+import { CellValueErrorType, ErrorValue } from './types/sheets-types';
+
+/**
+ * Cell error
+ *
+ * not a js "error" that gets thrown, but a value that holds an error code and message for a cell
+ * it's useful to use a class so we can check `instanceof`
+
+ * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/other#ErrorType
+ */
+export class GoogleSpreadsheetCellErrorValue {
+  /**
+   * type of the error
+   * @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/other#ErrorType
+   * */
+  readonly type: CellValueErrorType;
+
+  /** A message with more information about the error (in the spreadsheet's locale) */
+  readonly message: string;
+
+  constructor(rawError: ErrorValue) {
+    this.type = rawError.type;
+    this.message = rawError.message;
+  }
+}

package/src/lib/GoogleSpreadsheetRow.ts

@@ -0,0 +1,117 @@
+import { GoogleSpreadsheetWorksheet } from './GoogleSpreadsheetWorksheet';
+import { columnToLetter } from './utils';
+
+
+// TODO: add type for possible row values (currently any)
+
+export class GoogleSpreadsheetRow<T extends Record<string, any> = Record<string, any>> {
+  constructor(
+    /** parent GoogleSpreadsheetWorksheet instance */
+    readonly _worksheet: GoogleSpreadsheetWorksheet,
+    /** the A1 row (1-indexed) */
+    private _rowNumber: number,
+    /** raw underlying data for row */
+    private _rawData: any[]
+  ) {
+
+  }
+
+  private _deleted = false;
+  get deleted() { return this._deleted; }
+
+  /** row number (matches A1 notation, ie first row is 1) */
+  get rowNumber() { return this._rowNumber; }
+  /**
+   * @internal
+   * Used internally to update row numbers after deleting rows.
+   * Should not be called directly.
+  */
+  _updateRowNumber(newRowNumber: number) {
+    this._rowNumber = newRowNumber;
+  }
+  get a1Range() {
+    return [
+      this._worksheet.a1SheetName,
+      '!',
+      `A${this._rowNumber}`,
+      ':',
+      `${columnToLetter(this._worksheet.headerValues.length)}${this._rowNumber}`,
+    ].join('');
+  }
+
+  /** get row's value of specific cell (by header key) */
+  get(key: keyof T) {
+    const index = this._worksheet.headerValues.indexOf(key as string);
+    return this._rawData[index];
+  }
+  /** set row's value of specific cell (by header key) */
+  set<K extends keyof T>(key: K, val: T[K]) {
+    const index = this._worksheet.headerValues.indexOf(key as string);
+    this._rawData[index] = val;
+  }
+  /** set multiple values in the row at once from an object */
+  assign(obj: T) {
+    // eslint-disable-next-line no-restricted-syntax, guard-for-in
+    for (const key in obj) this.set(key, obj[key]);
+  }
+
+  /** return raw object of row data */
+  toObject() {
+    const o: Partial<T> = {};
+    for (let i = 0; i < this._worksheet.headerValues.length; i++) {
+      const key: keyof T = this._worksheet.headerValues[i];
+      if (!key) continue;
+      o[key] = this._rawData[i];
+    }
+    return o;
+  }
+
+  /** save row values */
+  async save(options?: { raw?: boolean }) {
+    if (this._deleted) throw new Error('This row has been deleted - call getRows again before making updates.');
+
+    const response = await this._worksheet._spreadsheet.sheetsApi.request({
+      method: 'put',
+      url: `/values/${encodeURIComponent(this.a1Range)}`,
+      params: {
+        valueInputOption: options?.raw ? 'RAW' : 'USER_ENTERED',
+        includeValuesInResponse: true,
+      },
+      data: {
+        range: this.a1Range,
+        majorDimension: 'ROWS',
+        values: [this._rawData],
+      },
+    });
+    this._rawData = response.data.updatedData.values[0];
+  }
+
+  /** delete this row */
+  async delete() {
+    if (this._deleted) throw new Error('This row has been deleted - call getRows again before making updates.');
+
+    const result = await this._worksheet._makeSingleUpdateRequest('deleteRange', {
+      range: {
+        sheetId: this._worksheet.sheetId,
+        startRowIndex: this._rowNumber - 1, // this format is zero indexed, because of course...
+        endRowIndex: this._rowNumber,
+      },
+      shiftDimension: 'ROWS',
+    });
+    this._deleted = true;
+    this._worksheet._shiftRowCache(this.rowNumber);
+
+    return result;
+  }
+
+  /**
+   * @internal
+   * Used internally to clear row data after calling sheet.clearRows
+   * Should not be called directly.
+  */
+  _clearRowData() {
+    for (let i = 0; i < this._rawData.length; i++) {
+      this._rawData[i] = '';
+    }
+  }
+}