Create/Update Document returns create/update timestamp as Date.

Fix JS date creation to omit microseconds since Apps Script JavaScript Engine doesn't support it.
Added lots of missing documentation.

Author: LaughDonor

Delete.js

@@ -4,6 +4,7 @@
  * Delete the Firestore document at the given path.
  * Note: this deletes ONLY this document, and not any subcollections.
  *
+ * @private
  * @param {string} path the path to the document to delete
  * @param {string} request the Firestore Request object to manipulate
  * @return {object} the JSON response from the DELETE request

FirestoreDocument.js

@@ -4,6 +4,7 @@
 /**
  * Create a Firestore documents with the corresponding fields.
  *
+ * @private
  * @param {object} fields the document's fields
  * @return {object} a Firestore document with the given fields
  */
@@ -20,6 +21,7 @@ function createFirestoreDocument_ (fields) {
 /**
  * Extract fields from a Firestore document.
  *
+ * @private
  * @param {object} firestoreDoc the Firestore document whose fields will be extracted
  * @return {object} an object with the given document's fields and values
  */
@@ -49,6 +51,12 @@ function unwrapDocumentFields_ (docResponse) {
   if (docResponse.fields) {
     docResponse.fields = getFieldsFromFirestoreDocument_(docResponse)
   }
+  if (docResponse.createTime) {
+    docResponse.createTime = unwrapDate_(docResponse.createTime)
+  }
+  if (docResponse.updateTime) {
+    docResponse.updateTime = unwrapDate_(docResponse.updateTime)
+  }
   return docResponse
 }
 
@@ -89,7 +97,7 @@ function unwrapValue_ (value) {
     case 'arrayValue':
       return unwrapArray_(value.values)
     case 'timestampValue':
-      return new Date(value)
+      return unwrapDate_(value)
     case 'nullValue':
     default: // error
       return null
@@ -179,3 +187,8 @@ function unwrapArray_ (wrappedArray) {
   const array = (wrappedArray || []).map(unwrapValue_)
   return array
 }
+
+function unwrapDate_ (wrappedDate) {
+  // Trim out extra microsecond precision
+  return new Date(wrappedDate.replace(regexDatePrecision_, '$1'))
+}

Query.js

@@ -1,15 +1,6 @@
 /* eslint no-unused-vars: ["error", { "varsIgnorePattern": "_" }] */
 /* eslint quote-props: ["error", "always"] */
 
-/**
- * This callback type is called `queryCallback`.
- *  Callback should utilize the Query parameter to send a request and return the response.
- *
- * @callback queryCallback
- * @param {object} query the Structured Query to utilize in the query request {@link FirestoreQuery_}
- * @returns [object] response of the sent query
- */
-
 /**
  * An object that acts as a Query to be a structured query.
  * Chain methods to update query. Must call .execute to send request.
@@ -101,8 +92,8 @@ var FirestoreQuery_ = function (from, callback) {
 
   /**
    * Filter Query by a given field and operator (or additionally a value).
-   *  Can be repeated if multiple filters required.
-   *  Results must satisfy all filters.
+   * Can be repeated if multiple filters required.
+   * Results must satisfy all filters.
    *
    * @param {string} field The field to reference for filtering
    * @param {string} operator The operator to filter by. {@link fieldOps} {@link unaryOps}
@@ -130,7 +121,7 @@ var FirestoreQuery_ = function (from, callback) {
 
   /**
    * Orders the Query results based on a field and specific direction.
-   *  Can be repeated if additional ordering is needed.
+   * Can be repeated if additional ordering is needed.
    *
    * @see {@link https://firebase.google.com/docs/firestore/reference/rest/v1beta1/StructuredQuery#Projection Select}
    * @param {string} field The field to order by.
@@ -209,7 +200,7 @@ var FirestoreQuery_ = function (from, callback) {
 
   /**
    * Executes the query with the given callback method and the generated query.
-   *  Must be used at the end of any query for execution.
+   * Must be used at the end of any query for execution.
    *
    * @returns {object} The query results from the execution
    */

Util.js

@@ -5,39 +5,79 @@ var regexPath_ = /^projects\/.+?\/databases\/\(default\)\/documents\/(.+\/.+)$/
 // RegEx test for testing for binary data by checking for non-printable characters.
 // Parsing strings for binary data is completely dependent on the data being sent over.
 var regexBinary_ = /[\x00-\x08\x0E-\x1F]/ // eslint-disable-line no-control-regex
+// RegEx test for finding and capturing milliseconds.
+// Apps Scripts doesn't support RFC3339 Date Formats, nanosecond precision must be trimmed.
+var regexDatePrecision_ = /(\.\d{3})\d+/
 
-// Assumes n is a Number.
+/**
+ * Checks if a number is an integer.
+ *
+ * @private 
+ * @param {value} n value to check
+ * @returns {boolean} true if value can be coerced into an integer, false otherwise
+ */
 function isInt_ (n) {
   return n % 1 === 0
 }
 
+
+/**
+ * Check if a value is a valid number.
+ *
+ * @private
+ * @param {value} val value to check
+ * @returns {boolean} true if a valid number, false otherwise
+ */
 function isNumeric_ (val) {
   return Number(parseFloat(val)) === val
 }
 
 /**
  * Check if a value is of type Number but is NaN.
- *  This check prevents seeing non-numeric values as NaN.
+ * This check prevents seeing non-numeric values as NaN.
  *
- * @param {value} the value to check
- * @returns {boolean} whether the given value is of type number and equal to NaN
+ * @private
+ * @param {value} value value to check
+ * @returns {boolean} true if NaN, false otherwise
  */
 function isNumberNaN_ (value) {
   return typeof (value) === 'number' && isNaN(value)
 }
 
+/**
+ * Base64 Encodes a string without equals (=) symbol
+ *
+ * @private
+ * @param {string} string string to encode
+ * @returns {string} base64 encoded string (without =)
+ */
 function base64EncodeSafe_ (string) {
   const encoded = Utilities.base64EncodeWebSafe(string)
   return encoded.replace(/=/g, '')
 }
 
+/**
+ * Send HTTP request with provided options
+ *
+ * @private
+ * @param {string} url Location path to send request to
+ * @param {object} options HTTP related options to send
+ * @returns {object} Response object from HTTP request
+ */
 function fetchObject_ (url, options) {
   const response = UrlFetchApp.fetch(url, options)
   const responseObj = JSON.parse(response.getContentText())
   checkForError_(responseObj)
   return responseObj
 }
 
+/**
+ * Validate response object for errors
+ *
+ * @private
+ * @param {object} responseObj HTTP response object to validate
+ * @throws Error if HTTP requests errors found
+ */
 function checkForError_ (responseObj) {
   if (responseObj.error) {
     throw new Error(responseObj.error.message)
@@ -46,13 +86,36 @@ function checkForError_ (responseObj) {
     throw new Error(responseObj[0].error.message)
   }
 }
+
+/**
+ * Gets collection of documents with the given path
+ *
+ * @private
+ * @param {string} path Collection path
+ * @returns {array} Collection of documents
+ */
 function getCollectionFromPath_ (path) {
   return getColDocFromPath_(path, false)
 }
+
+/**
+ * Gets document with the given path
+ *
+ * @private
+ * @param {string} path Document path
+ * @returns {object} Document object 
+ */
 function getDocumentFromPath_ (path) {
   return getColDocFromPath_(path, true)
 }
 
+/**
+ * Gets collection or document with the given path
+ *
+ * @private
+ * @param {string} path Document/Collection path
+ * @returns {array|object} Collection of documents or a single document
+ */
 function getColDocFromPath_ (path, isDocument) {
   // Path defaults to empty string if it doesn't exist. Remove insignificant slashes.
   const splitPath = (path || '').split('/').filter(function (p) {

Write.js

@@ -18,7 +18,9 @@ function createDocument_ (path, fields, request) {
   if (documentId) {
     request.addParam('documentId', documentId)
   }
-  return request.post(pathDoc[0], firestoreObject)
+
+  const newDoc = request.post(pathDoc[0], firestoreObject)
+  return unwrapDocumentFields_(newDoc)
 }
 
 /**
@@ -28,7 +30,7 @@ function createDocument_ (path, fields, request) {
  * @param {string} path the path of the document to update
  * @param {object} fields the document's new fields
  * @param {string} request the Firestore Request object to manipulate
- * @param {boolean} if true, the update will use a mask
+ * @param {boolean} if true, the update will use a mask. i.e. true: updates only specific fields, false: overwrites document with specified fields
  * @return {object} the Document object written to Firestore
  */
 function updateDocument_ (path, fields, request, mask) {
@@ -43,6 +45,6 @@ function updateDocument_ (path, fields, request, mask) {
   }
 
   const firestoreObject = createFirestoreDocument_(fields)
-
-  return request.patch(path, firestoreObject)
+  const updatedDoc = request.patch(path, firestoreObject)
+  return unwrapDocumentFields_(updatedDoc)
 }

package.json

@@ -26,6 +26,7 @@
       "isNumeric_",
       "query_",
       "regexBinary_",
+      "regexDatePrecision_",
       "regexPath_",
       "unwrapDocumentFields_",
       "updateDocument_",