feat: typescript rewrite!

huge rewrite

.eslintignore

@@ -0,0 +1,4 @@
+.eslintrc.cjs
+build.config.js
+jest.config.cjs
+dist

.eslintrc.js → .eslintrc.cjs

@@ -4,16 +4,18 @@ module.exports = {
  parserOptions: {
  sourceType: 'module',
  ecmaVersion: 2018,
+ project: './tsconfig.json',
  },
  env: {
  es6: true,
  node: true,
  },
  extends: [
  'airbnb-base',
+ 'airbnb-typescript/base',
  ],
  plugins: [
- 'async-await',
+ 'no-floating-promise',
  ],
  // add your custom rules here
  rules: {
@@ -23,31 +25,51 @@ module.exports = {
  'radix': 0,
  'prefer-destructuring': 0,
  'no-param-reassign': 0, // sometimes it's just much easier
- 'lines-between-class-members': 0, // grouping related one-liners can be nice
+ '@typescript-eslint/lines-between-class-members': 0, // grouping related one-liners can be nice
  'no-continue': 0,
  // override airbnb - breaks old version of node - https://github.com/eslint/eslint/issues/7749
- 'comma-dangle': ['error', {
+ '@typescript-eslint/comma-dangle': ['error', {
  arrays: 'always-multiline',
  objects: 'always-multiline',
  imports: 'always-multiline',
  exports: 'always-multiline',
  functions: 'never', // this breaks
  }],
  'no-multiple-empty-lines': 0, // sometimes helpful to break up sections of code
+ 'import/prefer-default-export': 0,
+ 'import/no-cycle': 0,
+ 'grouped-accessor-pairs': 0,
+ "@typescript-eslint/naming-convention": 0,
+
+ "@typescript-eslint/no-unused-vars": [
+ "error",
+ {
+ argsIgnorePattern: "^_",
+ varsIgnorePattern: "^_",
+ },
+ ],
+
+ 'max-len': ['error', 120, 2, { // bumped to 120, otherwise same as airbnb's rule but ignoring comments
+ ignoreUrls: true,
+ ignoreComments: true,
+ ignoreRegExpLiterals: true,
+ ignoreStrings: true,
+ ignoreTemplateLiterals: true,
+ }],
+
  },
  overrides: [
  { // extra jest related rules for tests
  files: 'test/*',
- plugins: ["jest"],
- extends: ["plugin:jest/recommended"],
+ plugins: ['jest'],
+ extends: ['plugin:jest/recommended'],
  env: {
- "jest/globals": true,
+ 'jest/globals': true,
  },
  rules: {
- "jest/consistent-test-it": "error",
+ 'jest/consistent-test-it': 'error',
  'jest/expect-expect': 0, // sometimes the lack of an error thrown is a good test
  'no-await-in-loop': 0,
-
  }
  },
  { // relaxed rules for examples
@@ -58,4 +80,4 @@ module.exports = {
  },
  },
  ],
-}
+};

.gitignore

@@ -1,6 +1,7 @@
 node_modules/
-ignore/
+src/ignore/
 .env
 .DS_Store
 examples/
-TODO
+TODO
+dist

.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+pnpm run lint

.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+ "recommendations": [
+ "dbaeumer.vscode-eslint"
+ ]
+}

.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+ "editor.formatOnSave": true,
+ "[typescript]": {
+ "editor.defaultFormatter": "dbaeumer.vscode-eslint"
+ },
+ "[javascript]": {
+ "editor.defaultFormatter": "dbaeumer.vscode-eslint"
+ },
+ "editor.rulers": [
+ 120
+ ],
+ "eslint.packageManager": "pnpm"
+}

Changelog.md

@@ -1,10 +1,22 @@
 # Changelog
 
-TODO: set this up to be automated and pulled from git commits... for now just going to leave some notes manually!
+Sorry for not keeping a proper changelog from the beginning. Will try to keep this up to date from now on!
 
-### 3.2.0 (2021-11-07)
+### 4.0.0 (2021-11-07)
 
 - Added `insertDimension` functionality
 - Added custom header row index for row-based API
 - Bumped dependency versions
-- Readme/docs cleanup
+- Readme/docs cleanup
+
+### 5.0.0 (2023-03-01)
+
+- rewrite in typescript! no more lagging/outdated types from DefinitelyTyped (`@types/google-spreadsheet`)
+- refactor `GoogleSpreadsheetRow` to be more TS friendly
+- refactor authentication to rely directly on [google-auth-library](https://www.npmjs.com/package/google-auth-library) as a peer dependency
+- support Application Default Credentials (auto inject credentials in some environments)
+- refactor document creation into static method, similar auth setup
+- support basic sharing / permissions management (drive api)
+- support document delete
+- replaced `GoogleSpreadsheetFormulaError` with `GoogleSpreadsheetCellErrorValue` and now handles all possible cell error types
+- fully deprecated `sheet.getInfo`, 

README.md

@@ -1,29 +1,24 @@
 # google-spreadsheet
-> The most popular [Google Sheets API](https://developers.google.com/sheets/api/reference/rest) wrapper for javascript
+> The most popular [Google Sheets API](https://developers.google.com/sheets/api/guides/concepts) wrapper for javascript / typescript
 
 [![NPM version](https://img.shields.io/npm/v/google-spreadsheet)](https://www.npmjs.com/package/google-spreadsheet)
 [![CircleCI](https://circleci.com/gh/theoephraim/node-google-spreadsheet.svg?style=shield)](https://circleci.com/gh/theoephraim/node-google-spreadsheet)
 [![Known Vulnerabilities](https://snyk.io/test/github/theoephraim/node-google-spreadsheet/badge.svg?targetFile=package.json)](https://snyk.io/test/github/theoephraim/node-google-spreadsheet?targetFile=package.json)
 [![NPM](https://img.shields.io/npm/dw/google-spreadsheet)](https://www.npmtrends.com/google-spreadsheet)
 
-- multiple auth options - service account (w/ optional impersonation), OAuth 2.0, API key (read-only)
+- multiple auth options (via [google-auth-library](https://www.npmjs.com/package/google-auth-library)) - service account, OAuth, API key, ADC, etc
 - cell-based API - read, write, bulk-updates, formatting
 - row-based API - read, update, delete (based on the old v3 row-based calls)
-- managing worksheets - add, remove, resize, change title, formatting
+- managing worksheets - add, remove, resize, change title, formatting, duplicate, copy to other sheet
+- managing docs - create new doc, delete doc, basic sharing/permissions
+- export - download sheet/docs in various formats
 
 **Docs site -**
 Full docs available at [https://theoephraim.github.io/node-google-spreadsheet](https://theoephraim.github.io/node-google-spreadsheet)
 
-> **🚨 Google Deprecation Warning - affects older version (v2) of this module 🚨**
->
-> Google is [phasing out their old v3 api](https://cloud.google.com/blog/products/g-suite/migrate-your-apps-use-latest-sheets-api), which the older version of this module used. Originally they were going to shut it down on March 3rd 2020, but have pushed that date back to June 2021.
-
-
-**Regardless, please upgrade to the latest version of this module (v3) which uses the newer sheets v4 API**
-
 -------------
 
-> 🌈 **Installation** - `npm i google-spreadsheet --save` or `yarn add google-spreadsheet`
+> 🌈 **Installation** - `pnpm i google-spreadsheet` (or `npm i google-spreadsheet --save` or `yarn add google-spreadsheet`)
 
 ## Examples
 _the following examples are meant to give you an idea of just some of the things you can do_
@@ -38,42 +33,46 @@ _the following examples are meant to give you an idea of just some of the things
 
 
 ### The Basics
-```javascript
-const { GoogleSpreadsheet } = require('google-spreadsheet');
+```js
+import { GoogleSpreadsheet } = from 'google-spreadsheet';
+import { JWT } from 'google-auth-library'
 
-// 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 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
+// Initialize auth - see https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication
+const serviceAccountAuth = new JWT({
+ // env var values here 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,
+ email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,
+ key: process.env.GOOGLE_PRIVATE_KEY,
+ scopes: [
+ 'https://www.googleapis.com/auth/spreadsheets',
+ ],
 });
 
+const doc = new GoogleSpreadsheet('<the sheet ID from the url>', serviceAccountAuth);
+
 await doc.loadInfo(); // loads document properties and worksheets
 console.log(doc.title);
 await doc.updateProperties({ title: 'renamed doc' });
 
-const sheet = doc.sheetsByIndex[0]; // or use doc.sheetsById[id] or doc.sheetsByTitle[title]
+const sheet = doc.sheetsByIndex[0]; // or use `doc.sheetsById[id]` or `doc.sheetsByTitle[title]`
 console.log(sheet.title);
 console.log(sheet.rowCount);
 
 // adding / removing sheets
-const newSheet = await doc.addSheet({ title: 'hot new sheet!' });
+const newSheet = await doc.addSheet({ title: 'another sheet' });
 await newSheet.delete();
 ```
 More info:
 - [GoogleSpreadsheet](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet)
 - [GoogleSpreadsheetWorksheet](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-worksheet)
-- [Authentication](https://theoephraim.github.io/node-google-spreadsheet/#/getting-started/authentication)
+- [Authentication](https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication)
 
 
 
 ### Working with rows
-```javascript
-// create a sheet and set the header row
+```js
+// if creating a new sheet, you can set the header row
 const sheet = await doc.addSheet({ headerValues: ['name', 'email'] });
 
 // append rows
@@ -87,19 +86,35 @@ const moreRows = await sheet.addRows([
 const rows = await sheet.getRows(); // can pass in { limit, offset }
 
 // read/write row values
-console.log(rows[0].name); // 'Larry Page'
-rows[1].email = 'sergey@abc.xyz'; // update a value
-await rows[1].save(); // save updates
-await rows[1].delete(); // delete a row
+console.log(rows[0].get('name')); // 'Larry Page'
+rows[1].set('email') = 'sergey@abc.xyz'; // update a value
+rows[2].assign({ name: 'Sundar Pichai', email: 'sundar@google.com' }); // set multiple values
+await rows[2].save(); // save updates on a row
+await rows[2].delete(); // delete a row
+```
+
+Row methods support explicit TypeScript types for shape of the data
+
+```typescript
+type UsersRowData = {
+ name: string;
+ email: string;
+ type?: 'admin' | 'user';
+};
+const userRows = await sheet.getRows<UsersRowData>();
+
+userRows[0].get('name'); // <- TS is happy, knows it will be a string
+userRows[0].get('badColumn'); // <- will throw a type error
 ```
+
 More info:
 - [GoogleSpreadsheetWorksheet > Working With Rows](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-worksheet#working-with-rows)
 - [GoogleSpreadsheetRow](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-row)
 
 
 
 ### Working with cells
-```javascript
+```js
 await sheet.loadCells('A1:E10'); // loads range of cells into local cache - DOES NOT RETURN THE CELLS
 console.log(sheet.cellStats); // total cells, loaded, how many non-empty
 const a1 = sheet.getCell(0, 0); // access cells using a zero-based index
@@ -120,15 +135,39 @@ More info:
 - [GoogleSpreadsheetCell](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-cell)
 
 
+### Managing docs and sharing
+
+```js
+const auth = new JWT({
+ email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,
+ key: process.env.GOOGLE_PRIVATE_KEY,
+ scopes: [
+ 'https://www.googleapis.com/auth/spreadsheets',
+ // note that sharing-related calls require the google drive scope
+ 'https://www.googleapis.com/auth/drive.file',
+ ],
+});
+
+// create a new doc
+const newDoc = await GoogleSpreadsheet.createNewSpreadsheetDocument(auth, { title: 'new fancy doc' });
+
+// share with specific users, domains, or make public
+await newDoc.share('someone.else@example.com');
+await newDoc.share('mycorp.com');
+await newDoc.setPublicAccessLevel('reader');
+
+// delete doc
+await newDoc.delete();
+```
 
 ## Why?
 > **This module provides an intuitive wrapper around Google's API to simplify common interactions**
 
-While Google's v4 sheets api is much easier to use than v3 was, the official [googleapis npm module](https://www.npmjs.com/package/googleapis) is a giant meta-tool that handles _every Google product_. The module and the API itself are awkward and the docs are pretty terrible, at least to get started.
+While Google's v4 sheets api is much easier to use than v3 was, the official [googleapis npm module](https://www.npmjs.com/package/googleapis) is a giant autogenerated meta-tool that handles _every Google product_. The module and the API itself are awkward and the docs are pretty terrible, at least to get started.
 
 **In what situation should you use Google's API directly?**<br>
 This module makes trade-offs for simplicity of the interface.
-Google's API provides a mechanism to make many requests in parallel, so if speed and efficiency is extremely important to your use case, you may want to use their API directly. There are also several features of their API that are not implemented here yet.
+Google's API provides a mechanism to make many requests in parallel, so if speed and efficiency is extremely important to your use case, you may want to use their API directly. There are also many lesser-used features of their API that are not implemented here yet.
 
 
 ## Support & Contributions
@@ -138,11 +177,11 @@ This module was written and is actively maintained by [Theo Ephraim](https://the
 **Are you actively using this module for a commercial project? Want to help support it?**<br>
 [Buy Theo a beer](https://paypal.me/theoephraim)
 
-#### Sponsors
+### Sponsors
 
 None yet - get in touch!
 
-#### Contributing
+### Contributing
 
 Contributions are welcome, but please follow the existing conventions, use the linter, add relevant tests, add relevant documentation.
 

build.config.js

@@ -0,0 +1,16 @@
+import { defineBuildConfig } from 'unbuild';
+
+export default defineBuildConfig({
+ entries: ['./src/index'],
+ outDir: 'dist',
+ declaration: true,
+ clean: true,
+ failOnWarn: true,
+ externals: ['google-auth-library'],
+ rollup: {
+ emitCJS: true,
+ esbuild: {
+ minify: process.env.NODE_ENV === 'production'
+ },
+ },
+});