Convert project to V8 Runtime with Classes. #83 #56

Convert JavaScript to Typescript and create custom typings. #64
Added Typings from gapi.client, google-apps-script, and jsonwebtoken.
Generated typings from Firestore Discovery URL from google-api-typings-generator.
Embraced ESLint and Prettier for code style.
Integrated Unit Tests utilizing GSUnit.
Added a plethora of badges and updated documentation.
Create workaround for duplicate "console" definitions (DefinitelyTyped/DefinitelyTyped#32585).

Author: LaughDonor

.claspignore

@@ -1,4 +1,10 @@
 LICENSE
-!appsscript.json
 *.md
-package*.json
+*.json
+!appsscript.json
+node_modules/**
+node_modules/**/.*/**
+node_modules/**/.*
+typings/**
+typings/**/.*/**
+typings/**/.*

.github/CONTRIBUTING.md

@@ -2,20 +2,30 @@
 Contributions are welcome! To contribute, fork this repository and create a pull request with your changes.
 
 #### Pull requests
-* Please create an issue before creating a pull request. Your changes are more likely to be pulled in after we discuss implementation, scope, etc. in an issue.
+* Please create (or link to) an issue before creating a pull request. Your changes are more likely to be pulled in after we discuss implementation, scope, etc. in the issue.
 * Please be responsive to change requests on your pull request.
 
 #### Checklist for your code
-* Have you tested the code yourself?
+- [ ] Have you all the appropriate dependencies (after `git clone`)?
+  * Install all packages from `package.json` with a bare `npm install`.
+- [ ] Have you tested the code yourself?
   * Install [clasp](https://developers.google.com/apps-script/guides/clasp) `npm install --global @google/clasp`
   * Log into your Google Account `clasp login`
-  * Create/Clone Apps Script Project
-  * Create a Test.js file which creates a Firestore instance (via. `getFirestore()`)
-  * Debug/Test your code against your database
-* Have you [documented your functions and their parameters and return values with JSDoc](http://usejsdoc.org/about-getting-started.html)?
-* Have you made all functions that an end user of the library should not see private? (You can make a function private by adding `_` to the end of its name, as in `publicFunction()` and `privateFunction_()`).
-  * Add new "global" functions to `package.json`
-* Does your code follow the [Standard Javascript Style Guide](https://github.com/standard/standard)?
-  * Install [standard](https://github.com/standard/standard) `npm install --global standard`
-  * Check code against rules `standard --verbose`
-  * Autofix most issues `standard --fix`
+  * Create/Clone Apps Script Project to link and set file extension to "ts". Example `.clasp.json` file:
+    ```javascript
+    {
+      "scriptId": "1yIYw-your-scriptID-here-las12jsA2sd",
+      "fileExtension": "ts"
+    }
+    ```
+  * Add storable credentials to your script to connect to your Firestore database.
+  * Add test methods to `Test.ts` file which validates your change.
+  * Debug/Test your code against your database.
+- [ ] Have you [documented your functions and their parameters and return values with JSDoc](http://usejsdoc.org/about-getting-started.html)?
+- [ ] Have you modernized the code to run with the new [V8 Runtime](https://developers.google.com/apps-script/guides/v8-runtime)?
+- [ ] Have you privatized or encapsulated all intended functions in a class?
+  * Global functions can be privatized by appending the "`_`" to the function name.
+- [ ] Have you ensured all the appropriate Typescript Definitions are available?
+- [ ] Does your code follow the [Prettier Javascript Style](https://prettier.io/docs/en/install.html)?
+  * Check syntax and style in one go with `npm run lint`.
+  * Autofix most issues with `npm run fix`.

.github/README.md

@@ -1,7 +1,13 @@
 # Firestore for Google Apps Scripts
 
-[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/grahamearley/FirestoreGoogleAppsScript)
+[![Google Apps Script](https://img.shields.io/badge/google%20apps%20script-v8-%234285f4)](https://developers.google.com/apps-script/guides/v8-runtime)
+[![TypeScript](https://img.shields.io/badge/typescript-3.9.3-%23294E80)](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-9.html)
 [![clasp](https://img.shields.io/badge/built%20with-clasp-4285f4.svg)](https://github.com/google/clasp)
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
+[![GitHub pull requests](https://img.shields.io/github/issues-pr/grahamearley/FirestoreGoogleAppsScript)](https://github.com/grahamearley/FirestoreGoogleAppsScript/pulls)
+[![GitHub issues](https://img.shields.io/github/issues/grahamearley/FirestoreGoogleAppsScript)](https://github.com/grahamearley/FirestoreGoogleAppsScript/issues)
+![Tests](https://img.shields.io/endpoint?url=https%3A%2F%2Fscript.google.com%2Fmacros%2Fs%2FAKfycbyvSXmyngRI1CPvMzIm7opGgB_19fFuvLC6AakL5ezxjKsIT6I%2Fexec)
 
 ### A Google Apps Script library for accessing Google Cloud Firestore.
 
@@ -10,6 +16,8 @@ This library allows a user (or service account) to authenticate with Firestore a
 
 Read how this project was started [here](http://grahamearley.website/blog/2017/10/18/firestore-in-google-apps-script.html).
 
+As of **v27**, this project has been updated to use the [GAS V8 runtime](https://developers.google.com/apps-script/guides/v8-runtime) with [Typescript](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-9.html)! This introduces a number of [breaking changes](#breaking-changes).
+
 ## Installation
 In the Google online script editor, select the `Resources` menu item and choose `Libraries...`. In the "Add a library" input box, enter `1VUSl4b1r1eoNcRWotZM3e87ygkxvXltOgyDZhixqncz9lQ3MjfT1iKFw` and click "Add." Choose the most recent version number.
 
@@ -28,10 +36,10 @@ To make a service account,
 5. When you press "Create," your browser will download a `.json` file with your private key (`private_key`), service account email (`client_email`), and project ID (`project_id`). Copy these values into your Google Apps Script — you'll need them to authenticate with Firestore.
 
 #### Create a test document in Firestore from your script
-Now, with your service account client email address `email`, private key `key`, project ID `projectId`, and Firestore API version, we will authenticate with Firestore to get our `Firestore` object. To do this, get the `Firestore` object from the library:
+Now, with your service account client email address `email`, private key `key`, project ID `projectId`, we will authenticate with Firestore to get our `Firestore` object. To do this, get the `Firestore` object from the library:
 
 ```javascript
-var firestore = FirestoreApp.getFirestore(email, key, projectId, "v1");
+const firestore = FirestoreApp.getFirestore(email, key, projectId);
 ```
 
 Using this Firestore instance, we will create a Firestore document with a field `name` with value `test!`. Let's encode this as a JSON object:
@@ -42,59 +50,87 @@ const data = {
 }
 ```
 
-We can choose to create a document in collection called `FirstCollection` without an ID:
+We can choose to create a document in collection called `FirstCollection` without a name (Firestore will generate one):
 
 ```javascript
-firestore.createDocument("FirstCollection", data)
+firestore.createDocument("FirstCollection", data);
 ```
 
 Alternatively, we can create the document in the `FirstCollection` collection called `FirstDocument`:
 ```javascript
-firestore.createDocument("FirstCollection/FirstDocument", data)
+firestore.createDocument("FirstCollection/FirstDocument", data);
 ```
 
-To update the document at this location, we can use the `updateDocument` function:
+To update (overwrite) the document at this location, we can use the `updateDocument` function:
 ```javascript
-firestore.updateDocument("FirstCollection/FirstDocument", data)
+firestore.updateDocument("FirstCollection/FirstDocument", data);
 ```
 
-**Note:** Although you can call `updateDocument` without using `createDocument` to create the document, any documents in your path will not be created and thus you can only access the document by using the path explicitly.
+To update only specific fields of a document at this location, we can set the `mask` parameter to `true`:
+```javascript
+firestore.updateDocument("FirstCollection/FirstDocument", data, true);
+```
 
-You can retrieve your data by calling the `getDocument` function:
+You can retrieve documents by calling the `getDocument` function:
 
 ```javascript
-const dataWithMetadata = firestore.getDocument("FirstCollection/FirstDocument")
+const documentWithMetadata = firestore.getDocument("FirstCollection/FirstDocument");
+const storedObject = documentWithMetadata.obj;
 ```
 
 You can also retrieve all documents within a collection by using the `getDocuments` function:
 
 ```javascript
-const allDocuments = firestore.getDocuments("FirstCollection")
+const allDocuments = firestore.getDocuments("FirstCollection");
 ```
 
 You can also get specific documents by providing an array of document names
 
 ```javascript
-const someDocuments = firestore.getDocuments("FirstCollection", ["Doc1", "Doc2", "Doc3"])
+const someDocuments = firestore.getDocuments("FirstCollection", ["Doc1", "Doc2", "Doc3"]);
 ```
 
-
-If more specific queries need to be performed, you can use the `query` function followed by an `execute` invocation to get that data:
+If more specific queries need to be performed, you can use the `query` function followed by an `Execute` invocation to get that data:
 
 ```javascript
-const allDocumentsWithTest = firestore.query("FirstCollection").where("name", "==", "Test!").execute()
+const allDocumentsWithTest = firestore.query("FirstCollection").Where("name", "==", "Test!").Execute();
+```
+
+The `Where` function can take other operators too: `==`, `<`, `<=`, `>`, `>=`, `contains`, `contains_any`, `in`.
+
+Queries looking for `null` values can also be given:
+```javascript
+const allDocumentsNullNames = firestore.query("FirstCollection").Where("name", null).Execute();
+```
+
+Query results can be ordered:
+```javascript
+const allDocumentsNameAsc = firestore.query("FirstCollection").OrderBy("name").Execute();
+const allDocumentsNameDesc = firestore.query("FirstCollection").OrderBy("name", "desc").Execute();
+```
+
+To limit, offset, or just select a range of results:
+```javascript
+const documents2_3_4_5 = firestore.query("FirstCollection").Limit(4).Offset(2).Execute();
+const documents3_4_5_6 = firestore.query("FirstCollection").Range(3, 7).Execute();
 ```
 
-See other library methods and details [in the wiki](https://github.com/grahamearley/FirestoreGoogleAppsScript/wiki/).
+See other library methods and details [in the wiki](/grahamearley/FirestoreGoogleAppsScript/wiki/).
 
 ### Breaking Changes
-* v23: When retrieving documents the createTime and updateTime document properties are JS Date objects and not Timestamp Strings.
-* v16: **Removed:** `createDocumentWithId(documentId, path, fields)`
+* **v27:** Library rewritten with Typescript and Prettier.
+  * Query function names have been capitalized (`Select`, `Where`, `OrderBy`, `Limit`, `Offset`, `Range`).
+  *  **All functions return `Document` or `Document[]` types directly from Firebase. Use `document.obj` to extract the raw object.**
+  *  Undo breaking change from v23. `document.createTime` and `document.updateTime` will remain as timestamped strings. However `document.created`, `document.updated`, and `document.read` are Date objects.
+* **v23:** When retrieving documents the createTime and updateTime document properties are JS Date objects and not Timestamp Strings.
+* **v16:** **Removed:** `createDocumentWithId(documentId, path, fields)`
   > Utilize `createDocument(path + '/' + documentId, fields)` instead to create a document with a specific ID. 
 
 ## Contributions
-Contributions are welcome — send a pull request! This library is a work in progress. See [here](https://github.com/grahamearley/FirestoreGoogleAppsScript/blob/master/.github/CONTRIBUTING.md) for more information on contributing.
+Contributions are welcome — send a pull request! See [here](/grahamearley/FirestoreGoogleAppsScript/blob/master/.github/CONTRIBUTING.md) for more information on contributing.
 
 After cloning this repository, you can push it to your own private copy of this Google Apps Script project to test it yourself. See [here](https://github.com/google/clasp) for directions on using `clasp` to develop App Scripts locally.
+Install all packages from `package.json` with a bare `npm install`.
+ 
 
-If you want to view the source code directly on Google Apps Script, where you can make a copy for yourself to edit, click [here](https://script.google.com/d/1VUSl4b1r1eoNcRWotZM3e87ygkxvXltOgyDZhixqncz9lQ3MjfT1iKFw/edit?usp=sharing). 
+If you want to view the source code directly on Google Apps Script, where you can make a copy for yourself to edit, click [here](https://script.google.com/d/1VUSl4b1r1eoNcRWotZM3e87ygkxvXltOgyDZhixqncz9lQ3MjfT1iKFw/edit). 

.gitignore

@@ -1,4 +1,4 @@
-gapps.config.json
-appsscript.json
 .clasp.json
 .vs
+gapps.config.json
+node_modules

Auth.ts

@@ -0,0 +1,75 @@
+/**
+ * Auth token is formatted to {@link https://developers.google.com/identity/protocols/oauth2/service-account#authorizingrequests}
+ *
+ * @private
+ * @param email the database service account email address
+ * @param key the database service account private key
+ * @param authUrl the authorization url
+ * @returns {string} the access token needed for making future requests
+ */
+class Auth {
+  email: string;
+  key: string;
+  authUrl: string;
+  scope: string;
+  jwtHeaderBase64_: string;
+
+  constructor(email: string, key: string) {
+    this.email = email;
+    this.key = key;
+
+    // TODO: Fix below variables to be static private when V8 allows for it.
+    // @see {@link https://issuetracker.google.com/issues/150896358 Google Issue Tracker}
+    this.authUrl = 'https://oauth2.googleapis.com/token';
+    this.scope = 'https://www.googleapis.com/auth/datastore';
+    this.jwtHeaderBase64_ = Utilities.base64EncodeWebSafe(JSON.stringify(this.jwtHeader_));
+  }
+
+  /**
+   * Fetch the access token
+   *
+   * @returns {string} The generated access token string
+   */
+  get accessToken(): string {
+    const request = new Request(this.authUrl, '', this.options_).post<TokenResponse>();
+    return request.access_token;
+  }
+
+  /**
+   * Creates the JSON Web Token for OAuth 2.0
+   *
+   * @returns {string} JWT to utilize
+   */
+  get createJwt_(): string {
+    const jwtClaimBase64 = Utilities.base64EncodeWebSafe(JSON.stringify(this.jwtPayload_));
+    const signatureInput = `${this.jwtHeaderBase64_}.${jwtClaimBase64}`;
+    const signature: number[] = Utilities.computeRsaSha256Signature(signatureInput, this.key);
+    return `${signatureInput}.${Utilities.base64EncodeWebSafe(signature)}`;
+  }
+
+  get jwtPayload_(): JwtClaim {
+    const seconds = ~~(new Date().getTime() / 1000);
+    return {
+      iss: this.email,
+      scope: this.scope,
+      aud: this.authUrl,
+      exp: seconds + 3600, // Expiry set to 1 hour (maximum)
+      iat: seconds,
+    };
+  }
+
+  get jwtHeader_(): JwtHeader {
+    return {
+      alg: 'RS256',
+      typ: 'JWT',
+    };
+  }
+
+  get options_(): RequestOptions {
+    const payload = {
+      grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+      assertion: this.createJwt_,
+    };
+    return { payload: Util_.parameterize(payload, false) };
+  }
+}