feat: Typescript typings update (#1183)

* Updates to typescript types definitions.
* Update captureException to match support of ErrorEvent and string as permitted inputs for the exception (fixes issue #1167).
* Update setExtraContext to allow using setExtraContext() to clear the extra data.
* Update setTagsContext to allow using setTagsContext() to clear the tags data.
* Add tests for the above changes.
* Add additional test calls for the Raven.context and Raven.wrap to take a function that throws an ErrorEvent.
* Update minimum Typescript version to 2.3.0, as the type definitions for ErrorEvent are incorrect/unusable in versions of Typescript less than 2.3.0.
* Update usage documentation - add documentation for how to remove a tag from the tag context data, and how to remove a value from the extra context data, as described in issue #614.
* Add missing console log levels to LogLevel.

Author: dawnmist

docs/usage.rst

@@ -142,6 +142,19 @@ functions all allow passing additional data to be tagged onto the error.
 
         Raven.setTagsContext({ key: "value" });
 
+    Tags given in ``setTagsContext`` are merged with the existing tags. If you need to remove a tag,
+    use ``getContext`` to get the current context value, call ``setTagsContext`` with no parameters
+    to remove all tags context data, and then call ``setTagsContext`` again with the tags that you
+    want to keep.
+
+    .. code-block:: javascript
+
+        const context = Raven.getContext(); // Note: Do not mutate context directly.
+        const tags = {...context.tags};
+        delete tags['TagNameToDelete'];
+        Raven.setTagsContext();             // Clear all current tags from the context.
+        Raven.setTagsContext(tags);         // Add back the tags you want to keep.
+
 .. describe:: extra
 
     Arbitrary data to associate with the event.
@@ -160,6 +173,18 @@ functions all allow passing additional data to be tagged onto the error.
 
         Raven.setExtraContext({ foo: "bar" })
 
+    Data given in ``setExtraContext`` is merged with the existing extra data. If you need to remove
+    a field from the extra context data, use ``getContext`` to get the current context value, call
+    ``setExtraContext`` with no parameters to remove all extra context data, and then call
+    ``setExtraContext`` again with the extra data content that you want to keep.
+
+    .. code-block:: javascript
+
+        const context = Raven.getContext(); // Note: Do not mutate context directly.
+        const extra = {...context.extra};
+        delete extra['FieldKeyToDelete'];
+        Raven.setExtraContext();            // Clear all extra data from the context.
+        Raven.setExtraContext(extra);       // Add back the extra data that you want to keep.
 
 .. _raven-js-recording-breadcrumbs:
 

package.json

@@ -67,7 +67,7 @@
     "proxyquireify": "^3.0.2",
     "sinon": "^3.2.1",
     "through2": "^2.0.0",
-    "typescript": "^1.8.10",
+    "typescript": "^2.3.0",
     "whatwg-fetch": "^2.0.3"
   },
   "prettier": {

typescript/raven-tests.ts

@@ -45,19 +45,42 @@ try {
     Raven.captureException(e, {tags: { key: "value" }});
 }
 
+// ErrorEvent requires at least Typescript 2.3.0 due to incorrect ErrorEvent definitions
+// prior to that version.
+var throwsErrorEvent = () => {
+    throw new ErrorEvent('oops', {error: new Error('Oops')});
+};
+
+try {
+    throwsErrorEvent();
+} catch(ee) {
+    Raven.captureException(ee);
+    Raven.captureException(ee, {tags: { key: "value" }});
+}
+
+Raven.captureException('Something broke');
+Raven.captureException('Something broke', {tags: { key: "value" }});
+
 Raven.context(throwsError);
 Raven.context({tags: { key: "value" }}, throwsError);
+Raven.context(throwsErrorEvent);
+Raven.context({tags: { key: "value" }}, throwsErrorEvent);
 
 setTimeout(Raven.wrap(throwsError), 1000);
 Raven.wrap({logger: "my.module"}, throwsError)();
+Raven.wrap(throwsErrorEvent)();
+Raven.wrap({logger: "my.module"}, throwsErrorEvent)();
 
+Raven.setUserContext();
 Raven.setUserContext({
     email: 'matt@example.com',
     id: '123'
 });
 
 Raven.setExtraContext({foo: 'bar'});
+Raven.setExtraContext();
 Raven.setTagsContext({env: 'prod'});
+Raven.setTagsContext();
 Raven.clearContext();
 var obj:Object = Raven.getContext();
 var err:Error = Raven.lastException();
@@ -69,6 +92,7 @@ Raven.captureMessage('Warning', { level: 'warning' });
 Raven.captureBreadcrumb({
     message: "This is a breadcrumb message."
 });
+Raven.captureBreadcrumb({category: "console", level: "log", message: "A console.log() message"});
 
 Raven.setRelease('abc123');
 Raven.setEnvironment('production');

typescript/raven.d.ts

@@ -65,12 +65,12 @@ declare module Raven {
 
         /** Append headers to the fetch or XMLHttpRequest request. Should be in a form of hash, were value can be string or function */
         headers?: {
-          [key: string]: (string | Function);
+            [key: string]: (string | Function);
         };
 
         /** `fetch` init parameters */
         fetchParameters?: {
-          [key: string]: (string | Function);
+            [key: string]: (string | Function);
         };
 
         /** Allow use of private/secretKey. */
@@ -187,11 +187,11 @@ declare module Raven {
         /*
         * Manually capture an exception and send it over to Sentry
         *
-        * @param {error} ex An exception to be logged
+        * @param {error|ErrorEvent|string} ex An exception to be logged
         * @param {object} options A specific set of options for this error [optional]
         * @return {Raven}
         */
-        captureException(ex: Error, options?: RavenOptions): RavenStatic;
+        captureException(ex: Error | ErrorEvent | string, options?: RavenOptions): RavenStatic;
 
         /*
         * Manually send a message to Sentry
@@ -205,28 +205,36 @@ declare module Raven {
         /** Log a breadcrumb */
         captureBreadcrumb(crumb: Breadcrumb): RavenStatic;
 
-        /**
-         * Clear the user context, removing the user data that would be sent to Sentry.
-         */
-        setUserContext(): RavenStatic;
-
         /*
         * Set a user to be sent along with the payload.
         *
         * @param {object} user An object representing user data [optional]
+        *                 If user is undefined, the current user context will be removed.
         * @return {Raven}
         */
-        setUserContext(user: {
+        setUserContext(user?: {
             id?: string;
             username?: string;
             email?: string;
         }): RavenStatic;
 
-        /** Merge extra attributes to be sent along with the payload. */
-        setExtraContext(context: Object): RavenStatic;
+        /*
+        * Merge extra attributes to be sent along with the payload.
+        *
+        * @param {object} context A set of data to be merged with the current extra context data [optional]
+        *                 If context is undefined, the current extra context data will be removed.
+        * @return {Raven}
+        */
+        setExtraContext(context?: Object): RavenStatic;
 
-        /** Merge tags to be sent along with the payload. */
-        setTagsContext(tags: Object): RavenStatic;
+        /*
+        * Merge tags to be sent along with the payload.
+        *
+        * @param {object} tags A set of data to be merged with the current tag context data [optional]
+        *                 If tags is undefined, the current tag context data will be removed.
+        * @return {Raven}
+        */
+        setTagsContext(tags?: Object): RavenStatic;
 
         /** Clear all of the context. */
         clearContext(): RavenStatic;
@@ -308,5 +316,5 @@ declare module Raven {
         sentry?: boolean;
     }
 
-    type LogLevel = "critical" | "error" | "warning" | "info" | "debug";
+    type LogLevel = "critical" | "error" | "warning" | "info" | "debug" | "warn" | "log";
 }