@noloco/google-spreadsheet - npm Package Compare versions

Comparing version 3.4.0 to 4.1.2

package.json

 {
-  "author": "Theo Ephraim <[e-mail]> (https://theoephraim.com)",
   "name": "@noloco/google-spreadsheet",
-  "description": "Google Sheets API (v4) -- simple interface to read/write data and manage sheets",
-  "version": "3.4.0",
-  "license": "Unlicense",
+  "version": "4.1.2",
+  "description": "Google Sheets API -- simple interface to read/write data and manage sheets",
   "keywords": [
     "google spreadsheets",
     "google sheets",
-    "google docs",
     "google",
@@ -17,5 +14,8 @@ "spreadsheet",
     "api",
-    "googleapis"
+    "googleapis",
+    "drive",
+    "google docs",
+    "google drive"
   ],
-  "homepage": "https://github.com/theoephraim/node-google-spreadsheet",
+  "homepage": "https://theoephraim.github.io/node-google-spreadsheet",
   "repository": {
@@ -25,45 +25,83 @@ "type": "git",
   },
-  "main": "index.js",
-  "engines": {
-    "node": ">=0.8.0"
+  "license": "Unlicense",
+  "author": "Theo Ephraim <[e-mail]> (https://theoephraim.com)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
   },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src/index.ts",
+    "src/lib"
+  ],
+  "scripts": {
+    "build": "NODE_ENV=production unbuild",
+    "build2": "tsc",
+    "build:dev": "unbuild",
+    "commit": "cz",
+    "docs:preview": "docsify serve docs",
+    "lint": "eslint ./ --ext .ts",
+    "lint:fix": "npm run lint --fix",
+    "nodev": "node -v",
+    "readme:copy": "echo \"<!-- DO NOT EDIT THIS FILE, EDIT MAIN README.md AND RUN \\`npm readme:copy\\` instead -->\n\n_Welcome to the docs site for_\n\" | cat - README.md > docs/README.md",
+    "changelog": "auto-changelog --commit-limit false --unreleased-only --stdout",
+    "release": "pnpm run build && release-it",
+    "runscript": "NODE_NO_WARNINGS=1 node --experimental-specifier-resolution=node --loader ts-node/esm",
+    "test": "jest --runInBand"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  },
   "dependencies": {
-    "axios": "^0.21.4",
-    "google-auth-library": "^6.1.3",
+    "axios": "1.6.7",
     "lodash": "^4.17.21"
   },
   "devDependencies": {
+    "@swc/core": "^1.3.60",
+    "@swc/jest": "^0.2.26",
+    "@types/jest": "^29.5.1",
+    "@types/lodash": "^4.14.195",
+    "@types/node": "^20.2.5",
+    "@typescript-eslint/eslint-plugin": "^5.59.7",
+    "@typescript-eslint/parser": "^5.59.7",
+    "auto-changelog": "^2.4.0",
+    "commitizen": "^4.3.0",
+    "cz-conventional-changelog": "^3.3.0",
     "delay": "^4.3.0",
-    "docsify-cli": "^4.4.0",
-    "eslint": "^6.8.0",
-    "eslint-config-airbnb-base": "^14.0.0",
-    "eslint-plugin-async-await": "0.0.0",
-    "eslint-plugin-import": "^2.20.0",
-    "eslint-plugin-jest": "^23.6.0",
-    "husky": "^4.2.0",
-    "jest": "^24.9.0",
-    "jest-junit": "^10.0.0"
+    "docsify-cli": "^4.4.3",
+    "eslint": "^8.41.0",
+    "eslint-config-airbnb-base": "^15.0.0",
+    "eslint-config-airbnb-typescript": "^17.0.0",
+    "eslint-plugin-import": "^2.27.5",
+    "eslint-plugin-jest": "^27.2.1",
+    "eslint-plugin-no-floating-promise": "^1.0.2",
+    "google-auth-library": "^9.2.0",
+    "jest": "^29.5.0",
+    "jest-junit": "^16.0.0",
+    "release-it": "^15.11.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^4.9.5",
+    "unbuild": "^1.2.1"
   },
-  "scripts": {
-    "test": "jest --runInBand",
-    "lint": "eslint ./",
-    "lint:fix": "eslint ./ --fix",
-    "docs:preview": "docsify serve docs",
-    "readme:copy": "echo \"<!-- DO NOT EDIT THIS FILE, EDIT MAIN README.md AND RUN \\`npm readme:copy\\` instead -->\n\n_Welcome to the docs site for_\n\" | cat - README.md > docs/README.md"
+  "peerDependencies": {
+    "google-auth-library": "^8.8.0 || ^9.0.0"
   },
-  "husky": {
-    "hooks": {
-      "pre-commit": "npm run lint",
-      "pre-push": "npm run test"
+  "peerDependenciesMeta": {
+    "google-auth-library": {
+      "optional": true
     }
   },
-  "jest": {
-    "testEnvironment": "node",
-    "testTimeout": 10000,
-    "coveragePathIgnorePatterns": [
-      "/node_modules/",
-      "/examples/",
-      "/test/"
-    ]
-  }
+  "volta": {
+    "node": "18.16.0"
+  },
+  "packageManager": "pnpm@8.15.4+sha256.cea6d0bdf2de3a0549582da3983c70c92ffc577ff4410cbf190817ddc35137c2"
 }

README.md

 # google-spreadsheet
-> The most popular [Google Sheets API](https://developers.google.com/sheets/api/reference/rest) wrapper for javascript
 
+> A fork of the most popular [Google Sheets API](https://developers.google.com/sheets/api/guides/concepts) wrapper for javascript / typescript
+
+## Differences from the original
+- DeveloperMetadata is supported
+- Rate limited requests are retried
+
+
 [![NPM version](https://img.shields.io/npm/v/google-spreadsheet)](https://www.npmjs.com/package/google-spreadsheet)
@@ -9,6 +15,8 @@ [![CircleCI](https://circleci.com/gh/theoephraim/node-google-spreadsheet.svg?style=shield)](https://circleci.com/gh/theoephraim/node-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, update properties (ex: title), duplicate to same or other document
+- managing docs - create new doc, delete doc, basic sharing/permissions
+- export - download sheet/docs in various formats
 
@@ -18,40 +26,35 @@ **Docs site -**
 
-> **🚨 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.
+---
 
+> 🌈 **Installation** - `pnpm i google-spreadsheet`<br/>(or `npm i google-spreadsheet --save` or `yarn add google-spreadsheet`)
 
-**Regardless, please upgrade to the latest version of this module (v3) which uses the newer sheets v4 API**
+## Examples
 
--------------
+_The following examples are meant to give you an idea of just some of the things you can do_
 
-> 🌈 **Installation** - `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_
-
 > **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:
 
 ```javascript
-(async function() {
+(async function () {
   await someAsyncFunction();
-}());
+})();
 ```
 
-
 ### The Basics
-```javascript
-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>');
+```js
+import { GoogleSpreadsheet } from 'google-spreadsheet';
+import { JWT } from 'google-auth-library';
 
-// 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
@@ -61,3 +64,3 @@ console.log(doc.title);
 
-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);
@@ -67,15 +70,16 @@ 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
 
-
-### 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'] });
@@ -94,16 +98,32 @@
 // read/write row values
-console.log(rows[0].name); // 'Larry Page'
-rows[1].email = '[e-mail]'; // 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', '[e-mail]'); // update a value
+rows[2].assign({ name: 'Sundar Pichai', email: '[e-mail]' }); // 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
 
-
-### Working with cells
-```javascript
-await sheet.loadCells('A1:E10'); // loads a range of cells
+```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
@@ -123,18 +143,43 @@ const a1 = sheet.getCell(0, 0); // access cells using a zero-based index
 ```
+
 More info:
+
 - [GoogleSpreadsheetWorksheet > Working With Cells](https://theoephraim.github.io/node-google-spreadsheet/#/classes/google-spreadsheet-worksheet#working-with-cells)
 - [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('[e-mail]');
+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 are 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
@@ -147,9 +192,9 @@
 
-#### 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.
+Contributions are welcome, but please follow the existing conventions, use the linter, add relevant tests, and add relevant documentation.
 
@@ -160,2 +205,3 @@ The docs site is generated using [docsify](https://docsify.js.org). To preview and run locally so you can make edits, run `npm run docs:preview` and head to http://localhost:3000
 ## License
+
 This is free and unencumbered public domain software. For more info, see https://unlicense.org.

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Minified code

Quality

This package contains minified code. This may be harmless in some cases where minified code is included in packaged libraries, however packages on npm should not minify code.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

225388

increased by195.23%

Number of package files

17

increased by30.77%

Lines of code

3852

increased by145.19%

Number of lines in readme file

200

increased by29.87%

Is type module

Yes

Worsened metrics

Dev dependency count

25

increased by150%

Number of low quality alerts

1

increased byInfinity%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Addedagent-base@7.1.3(transitive)

• + Addedasynckit@0.4.0(transitive)

• + Addedaxios@1.6.7(transitive)

• + Addedcombined-stream@1.0.8(transitive)

• + Addeddelayed-stream@1.0.0(transitive)

• + Addedform-data@4.0.1(transitive)

• + Addedgaxios@6.7.1(transitive)

• + Addedgcp-metadata@6.1.1(transitive)

• + Addedgoogle-auth-library@9.15.1(transitive)

• + Addedgoogle-logging-utils@0.0.2(transitive)

• + Addedgtoken@7.1.0(transitive)

• + Addedhttps-proxy-agent@7.0.6(transitive)

• + Addedmime-db@1.52.0(transitive)

• + Addedmime-types@2.1.35(transitive)

• + Addedproxy-from-env@1.1.0(transitive)

• + Addeduuid@9.0.1(transitive)

• - Removedgoogle-auth-library@^6.1.3

• - Removedabort-controller@3.0.0(transitive)

• - Removedagent-base@6.0.2(transitive)

• - Removedarrify@2.0.1(transitive)

• - Removedaxios@0.21.4(transitive)

• - Removedevent-target-shim@5.0.1(transitive)

• - Removedfast-text-encoding@1.0.6(transitive)

• - Removedgaxios@4.3.3(transitive)

• - Removedgcp-metadata@4.3.1(transitive)

• - Removedgoogle-auth-library@6.1.6(transitive)

• - Removedgoogle-p12-pem@3.1.4(transitive)

• - Removedgtoken@5.3.2(transitive)

• - Removedhttps-proxy-agent@5.0.1(transitive)

• - Removedlru-cache@6.0.0(transitive)

• - Removednode-forge@1.3.1(transitive)

• - Removedyallist@4.0.0(transitive)

• Updatedaxios@1.6.7