fix error fileName for directLink,

Update Changelog for v2.0.0, Update ReadMe
RomainVialard · Apr 24, 2018 · cd5bda6 · cd5bda6
1 parent 542517b
commit cd5bda6
Show file tree

Hide file tree

Showing 4 changed files with 143 additions and 58 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,15 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 <!-- Add new, unreleased changes here. -->
 * none
 
+## [2.0.0] - 2018-04-24
+* Breaking changes: expBackoff(): use options to specify its behavior (throw on fail, verbose, retryNumber, doNotLogKnownErrors)
+* Leverage Normalized GAS error in logError()
+* Leverage Normalized GAS error in expBackoff()
+* new function: getNormalizedError(): Return the english version of the error if listed in this library
+* new function: getErrorLocale(): Try to find the locale of the localized thrown error
+* Normalize GAS error messages across language and variable messages (eg: when containing a document ID or a variable part)
+* List known GAS error message
+
 ## [1.1.2] - 2018-04-05
 * Fix issue for global Add-on name reference error
 

diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@ This is a library for **Google Apps Script** projects. It provides methods to pe
 ## Methods
 
 
-### expBackoff(func)
+### expBackoff(func, options)
 
 In some cases, Google APIs can return errors on which it make sense to retry, like '_We're sorry, a server error occurred. Please wait a bit and try again._'.
 
@@ -17,7 +17,7 @@ Things are different for Google Apps Script [advanced services](https://develope
 
 #### Example
 
-```JS
+```javascript
 
 // Calls an anonymous function that gets the subject of the vacation responder in Gmail for the currently authenticated user.
 
@@ -28,31 +28,20 @@ Things are different for Google Apps Script [advanced services](https://develope
 
 #### Parameters
 
-
-<table>
-  <tr>
-   <td>Name
-   </td>
-   <td>Type
-   </td>
-   <td>Description
-   </td>
-  </tr>
-  <tr>
-   <td>Func
-   </td>
-   <td>Function
-   </td>
-   <td>The anonymous or named function to call.
-   </td>
-  </tr>
-</table>
-
-
+Name    | Type     | Default value | Description
+--------|----------|---------------|------------
+func    | Function |               | The anonymous or named function to call.
+options | Object   | {}            | OPTIONAL, options for exponential backoff
+options.throwOnFailure      | boolean | false | If true, throw a CustomError on failure
+options.doNotLogKnownErrors | boolean | false | If true, will not log known errors to stackdriver
+options.verbose             | boolean | false | If true, will log a warning on a successful call that failed at least once
+options.retryNumber         | number  | 5     | Maximum number of retry on error
 
 #### Return 
 
-The value returned by the called function or nothing if the called function isn't returning anything.
+The value returned by the called function, or a CustomError on failure if options.throwOnFailure == false
+
+CustomError is an instance of Error
 
 
 ### urlFetchWithExpBackOff(url, params)
@@ -66,11 +55,12 @@ We advise to replace all existing calls to `UrlFetchApp.fetch()` by this new met
 `UrlFetchApp.fetch(url, params)` => `ErrorHandler.urlFetchWithExpBackOff(url, params)`
 
 
-### logError(e, additionalParams)
+### logError(error, additionalParams)
 
 When exception logging is enabled, unhandled exceptions are automatically sent to Stackdriver Logging with a stack trace ([see official documentation](https://developers.google.com/apps-script/guides/logging#exception_logging)).
 
 But if you wrap your code in a try...catch statement and use `console.error(error)` to send the exception to Stackdriver Logging, only the error message will be logged and not the stack trace.
+This method will also leverage the list of known errors and their translation to better aggregate on Stackdriver Logging: the message will be the English version if available.
 
 We advise to replace all existing calls to `console.error(error)` by this new method to correctly log the stack trace, in the exact same format used for unhandled exceptions.
 
@@ -79,27 +69,103 @@ We advise to replace all existing calls to `console.error(error)` by this new me
 
 #### Parameters
 
+Name    | Type     | Default value | Description
+--------|----------|---------------|------------
+error   | String, Error, or { lineNumber: number, fileName: string, responseCode: string} | | A standard error object retrieved in a try...catch statement or created with new Error() or a simple error message or an object
+additionalParams | Object, {addonName: string} | {} | Add custom values to the logged Error, the 'addonName' property will pass the AddonName to remove from error fileName
+options | Object   | {}            | Options for logError
+options.asWarning | boolean | false | If true, use console.warn instead console.error
+options.doNotLogKnownErrors | booleab | false | if true, will not log known errors to stackdriver
+
+
+#### Return
+
+Return the CustomError, which is an Error, with a property 'context', as defined below:
+```javascript
+/**
+ * @typedef {Error} CustomError
+ *
+ * @property {{
+ *   locale: string,
+ *   originalMessage: string,
+ *   knownError: boolean,
+ *   variables: Array<{}>,
+ *   errorName: string,
+ *   reportLocation: {
+ *     lineNumber: number,
+ *     filePath: string,
+ *     directLink: string,
+ *   },
+ * }} context
+ */
+```
+
+
+### getNormalizedError(localizedErrorMessage, partialMatches)
+
+Try to get the corresponding english version of the error if listed in this library.
+
+There are Error match exactly, and Errors that can be partially matched, for example when it contains a variable part (eg: a document ID, and email)
+
+To get variable part, use the following pattern:
+```javascript
+var variables = []; // The empty array will be filled if necessary in the function
+var normalizedError = ErrorHandler.getNormalizedError('Documento 1234567890azerty mancante (forse è stato eliminato?)', variables);
+
+// The normalized Error, with its message in English, or '' of no match are found:
+// normalizedError = 'Document is missing (perhaps it was deleted?)'
+
+// the variable part:
+// variables = [{variable: 'docId', value: '1234567890azerty'}]
+```
+
+
+#### Parameters
+
+Name                  | Type     | Default value | Description
+----------------------|----------|---------------|------------
+localizedErrorMessage | String   |               | The Error message in the user's locale
+partialMatches        | Array<{ variable: string, value: string }>    | [] | OPTIONAL, Pass an empty array, getNormalizedError() will populate it with found extracted variables in case of a partial match
+
+
+The value returned is the error in English or '' if no matching error was found
+
+
+### getErrorLocale(localizedErrorMessage)
+
+Try to find the locale of the localized thrown error
+
+
+#### Parameters
+
+Name                  | Type     | Default value | Description
+----------------------|----------|---------------|------------
+localizedErrorMessage | String   |               | The Error message in the user's locale
+
+
+#### Return
+
+The locale ('en', 'it', ...) or '' if no matching error found
 
-<table>
-  <tr>
-   <td>Name
-   </td>
-   <td>Type
-   </td>
-   <td>Description
-   </td>
-  </tr>
-  <tr>
-   <td>e
-   </td>
-   <td>String || Error || {lineNumber: number, fileName: string, responseCode: string}
-   </td>
-   <td>A standard error object retrieved in a try...catch statement or created with new Error() or a simple error message or an object
-   </td>
-  </tr>
-</table>
+### NORMALIZED_ERRORS
+constant
 
+List all known Errors in a fixed explicit English message.
+Serves as reference for locallizing Errors.
 
+Use this to check which error a normalized error is:
+```javascript
+var normalizedError = ErrorHandler.getNormalizedError('Documento 1234567890azerty mancante (forse è stato eliminato?)');
+
+if (normalizedError === ErrorHandler.NORMALIZED_ERRORS.DOCUMENT_MISSING) {
+  // Do something on document missing error
+}
+```
+
+### NORETRY_ERRORS
+constant
+
+List all Errors for which there are no benefit in re-trying
 
 ## Setup
 
@@ -120,12 +186,18 @@ To be documented
 
 ## Warning
 
-This library contains 3 methods directly available as functions and callable without using the ErrorHandler class / namespace:
-
-
+This library contains 5 methods directly available as functions and callable without using the ErrorHandler class / namespace:
 
 *   expBackoff()
 *   urlFetchWithExpBackOff()
 *   logError()
+*   getNormalizedError()
+*   getErrorLocale()
+
+and 2 Object constant
+
+* NORMALIZED_ERRORS
+* NORETRY_ERRORS
+
 
 For this reason, if you copy the code in your project, make sure you don't have any other function with the exact same name.
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "@scriptaddicts/gas-error-handler",
-	"version": "1.1.2",
+	"version": "2.0.0",
 	"description": "Methods to handle error in GAS",
 	"author": {
 		"name": "Romain Vialard",

diff --git a/src/ErrorHandler.gs.js b/src/ErrorHandler.gs.js
@@ -34,7 +34,7 @@
  * @param {Function} func - The anonymous or named function to call.
  *
  * @param {{}} [options] - options for exponential backoff
- * @param {boolean} options.throwOnFailure - default to FALSE,  If true, throw the ErrorHandler_.CustomError on failure
+ * @param {boolean} options.throwOnFailure - default to FALSE, if true, throw the ErrorHandler_.CustomError on failure
  * @param {boolean} options.doNotLogKnownErrors - default to FALSE, if true, will not log known errors to stackdriver
  * @param {boolean} options.verbose - default to FALSE, if true, will log a warning on a successful call that failed at least once
  * @param {number} options.retryNumber - default to 5, maximum number of retry on error
@@ -212,8 +212,9 @@ function urlFetchWithExpBackOff(url, params) {
  *   variables: Array<{}>,
  *   errorName: string,
  *   reportLocation: {
- *     lineNumber: number
+ *     lineNumber: number,
  *     filePath: string,
+ *     directLink: string,
  *   },
  * }} context
  */
@@ -225,7 +226,7 @@ function urlFetchWithExpBackOff(url, params) {
  * @param {String || Error || {lineNumber: number, fileName: string, responseCode: string}} error
  * @param {Object || {addonName: string}} [additionalParams]
  *
- * @param {{}} [options] - default to FALSE, use console.warn instead console.error
+ * @param {{}} [options] - Options for logError
  * @param {boolean} options.asWarning - default to FALSE, use console.warn instead console.error
  * @param {boolean} options.doNotLogKnownErrors - default to FALSE, if true, will not log known errors to stackdriver
  *
@@ -284,10 +285,12 @@ function logError(error, additionalParams, options) {
 
   // Manage error Stack
   if (error.lineNumber && error.fileName && error.stack) {
+    var fileName = addonName && error.fileName.replace(' ('+ addonName +')', '') || error.fileName;
+
     log.context.reportLocation = {
       lineNumber: error.lineNumber,
-      filePath: addonName && error.fileName.replace(' ('+ addonName +')', '') || error.fileName,
-      directLink: 'https://script.google.com/macros/d/'+ scriptId +'/edit?f='+ error.fileName +'&s='+ error.lineNumber
+      filePath: fileName,
+      directLink: 'https://script.google.com/macros/d/'+ scriptId +'/edit?f='+ fileName +'&s='+ error.lineNumber
     };
 
     var res = ErrorHandler_._convertErrorStack(error.stack, addonName);
@@ -329,7 +332,7 @@ function logError(error, additionalParams, options) {
  * @type {Array<{
  *   variable: string,
  *   value: string
- * }>} partialMatches - Pass an empty array, getNormalizedError() will populate it with found extracted variables in case of a partial match
+ * }>} [partialMatches] - Pass an empty array, getNormalizedError() will populate it with found extracted variables in case of a partial match
  *
  * @return {ErrorHandler_.NORMALIZED_ERROR | ''} the error in English or '' if no matching error was found
  */
@@ -360,11 +363,12 @@ function getNormalizedError(localizedErrorMessage, partialMatches) {
   if (!match) return '';
 
   // Extract partial match variables
-  for (var j = 0, variable; variable = matcher.variables[j] ; j++) {
-    partialMatches.push({
-      variable: variable,
-      value: match[j+1] !== undefined && match[j+1] || ''
-    });
+  if (partialMatches && Array.isArray(partialMatches)) {
+    for (var j = 0, variable; variable = matcher.variables[j]; j++) {
+      partialMatches.push({
+        variable: variable, value: match[j + 1] !== undefined && match[j + 1] || ''
+      });
+    }
   }
 
   return matcher.ref;