feat: custom error handlers (#52)

From integrating Typewriter at Segment, we've learned that throwing an error whenever Typewriter discovers a validation issues is a pretty poor DX because it forces you to align your instrumentation and spec from day 1. Instead, we want to offer developers the opportunity to iteratively adopt Typewriter. To do so, this PR exposes an `onError` handler that can be configured at run-time when constructing an instance of a Typewriter client. As an example, this is what happens now when you have a validation error: ![image](https://user-images.githubusercontent.com/2907397/52014309-0f2edd00-2494-11e9-872a-d9e0b86e521f.png) Your entire app breaks while developing locally -- and that interrupts your developer flow. Now, you can hook in to that error handling logic like so: ```js const analytics = new Analytics(window.analytics, { onError: (error) => { console.error(JSON.stringify(error, null, 2)) } }) ``` After doing this, the errors will get logged instead: ![image](https://user-images.githubusercontent.com/2907397/52014714-228e7800-2495-11e9-9e68-84d3cdf7cee6.png) This allows you to handle errors however you want! For example, you could `alert` on errors: ![image](https://user-images.githubusercontent.com/2907397/52014438-5f0da400-2494-11e9-8744-263d82ef5f48.png) Or you could use this to ship validation to production without crashing your app and forward validation issues to Sentry/BugSnag/etc.
segmentio · Jan 31, 2019 · 7f073d8 · 7f073d8
1 parent 54d484e
commit 7f073d8
Show file tree

Hide file tree

Showing 19 changed files with 488 additions and 75 deletions.
diff --git a/examples/gen-js/js/analytics/generated/index.d.ts b/examples/gen-js/js/analytics/generated/index.d.ts
@@ -118,8 +118,32 @@ export interface ProfileViewed {
  * Analytics provides a strongly-typed wrapper around Segment Analytics
  * based on your Tracking Plan.
  */
+
+// From https://github.com/epoberezkin/ajv/blob/0c31c1e2a81e315511c60a0dd7420a72cb181e61/lib/ajv.d.ts#L279
+interface AjvErrorObject {
+  keyword: string;
+  dataPath: string;
+  schemaPath: string;
+  params: object;
+  message: string;
+  propertyName?: string;
+  parentSchema?: object;
+  data?: any;
+}
+
+// An invalid event with its associated collection of validation errors.
+interface InvalidEvent {
+  eventName: string;
+  validationErrors: AjvErrorObject[];
+}
+
+// Options to customize the runtime behavior of a Typewriter client.
+interface AnalyticsOptions {
+  onError(event: InvalidEvent): void;
+}
+
 export default class Analytics {
-  constructor(analytics: any);
+  constructor(analytics: any, options?: AnalyticsOptions);
 
   feedViewed(
     props?: FeedViewed,

diff --git a/examples/gen-js/js/analytics/generated/index.js b/examples/gen-js/js/analytics/generated/index.js
@@ -1,13 +1,21 @@
 export default class Analytics {
   /**
    * Instantiate a wrapper around an analytics library instance
-   * @param {Analytics} analytics - The analytics.js library to wrap
+   * @param {Analytics} analytics The analytics.js library to wrap
+   * @param {Object} [options] Optional configuration of the Typewriter client
+   * @param {function} [options.onError] Error handler fired when run-time validation errors
+   *     are raised.
    */
-  constructor(analytics) {
+  constructor(analytics, options = {}) {
     if (!analytics) {
       throw new Error("An instance of analytics.js must be provided");
     }
     this.analytics = analytics || { track: () => null };
+    this.onError =
+      options.onError ||
+      (error => {
+        throw new Error(JSON.stringify(error, null, 2));
+      });
   }
   addTypewriterContext(context = {}) {
     return {
@@ -97,7 +105,11 @@ export default class Analytics {
       return errors === 0;
     };
     if (!validate({ properties: props })) {
-      throw new Error(JSON.stringify(validate.errors, null, 2));
+      this.onError({
+        eventName: "Feed Viewed",
+        validationErrors: validate.errors
+      });
+      return;
     }
     this.analytics.track(
       "Feed Viewed",
@@ -188,7 +200,11 @@ export default class Analytics {
       return errors === 0;
     };
     if (!validate({ properties: props })) {
-      throw new Error(JSON.stringify(validate.errors, null, 2));
+      this.onError({
+        eventName: "Photo Viewed",
+        validationErrors: validate.errors
+      });
+      return;
     }
     this.analytics.track(
       "Photo Viewed",
@@ -279,7 +295,11 @@ export default class Analytics {
       return errors === 0;
     };
     if (!validate({ properties: props })) {
-      throw new Error(JSON.stringify(validate.errors, null, 2));
+      this.onError({
+        eventName: "Profile Viewed",
+        validationErrors: validate.errors
+      });
+      return;
     }
     this.analytics.track(
       "Profile Viewed",

diff --git a/examples/gen-js/node/analytics/generated/index.d.ts b/examples/gen-js/node/analytics/generated/index.d.ts
@@ -237,8 +237,32 @@ export interface Product {
  * Analytics provides a strongly-typed wrapper around Segment Analytics
  * based on your Tracking Plan.
  */
+
+// From https://github.com/epoberezkin/ajv/blob/0c31c1e2a81e315511c60a0dd7420a72cb181e61/lib/ajv.d.ts#L279
+interface AjvErrorObject {
+  keyword: string;
+  dataPath: string;
+  schemaPath: string;
+  params: object;
+  message: string;
+  propertyName?: string;
+  parentSchema?: object;
+  data?: any;
+}
+
+// An invalid event with its associated collection of validation errors.
+interface InvalidEvent {
+  eventName: string;
+  validationErrors: AjvErrorObject[];
+}
+
+// Options to customize the runtime behavior of a Typewriter client.
+interface AnalyticsOptions {
+  onError(event: InvalidEvent): void;
+}
+
 export default class Analytics {
-  constructor(analytics: any);
+  constructor(analytics: any, options?: AnalyticsOptions);
 
   orderCompleted(
     message?: TrackMessage<OrderCompleted>,

diff --git a/examples/gen-js/node/analytics/generated/index.js b/examples/gen-js/node/analytics/generated/index.js
@@ -3,13 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 class Analytics {
   /**
    * Instantiate a wrapper around an analytics library instance
-   * @param {Analytics} analytics - The analytics-node library to wrap
+   * @param {Analytics} analytics The analytics-node library to wrap
+   * @param {Object} [options] Optional configuration of the Typewriter client
+   * @param {function} [options.onError] Error handler fired when run-time validation errors
+   *     are raised.
    */
-  constructor(analytics) {
+  constructor(analytics, options = {}) {
     if (!analytics) {
       throw new Error("An instance of analytics-node must be provided");
     }
     this.analytics = analytics || { track: () => null };
+    this.onError =
+      options.onError ||
+      (error => {
+        throw new Error(JSON.stringify(error, null, 2));
+      });
   }
   addTypewriterContext(context = {}) {
     return Object.assign({}, context, {
@@ -563,7 +571,11 @@ class Analytics {
       return errors === 0;
     };
     if (!validate(message)) {
-      throw new Error(JSON.stringify(validate.errors, null, 2));
+      this.onError({
+        eventName: "Order Completed",
+        validationErrors: validate.errors
+      });
+      return;
     }
     message = Object.assign({}, message, {
       context: this.addTypewriterContext(message.context),

diff --git a/examples/gen-js/ts/analytics/generated/index.d.ts b/examples/gen-js/ts/analytics/generated/index.d.ts
@@ -118,8 +118,32 @@ export interface ProfileViewed {
  * Analytics provides a strongly-typed wrapper around Segment Analytics
  * based on your Tracking Plan.
  */
+
+// From https://github.com/epoberezkin/ajv/blob/0c31c1e2a81e315511c60a0dd7420a72cb181e61/lib/ajv.d.ts#L279
+interface AjvErrorObject {
+  keyword: string;
+  dataPath: string;
+  schemaPath: string;
+  params: object;
+  message: string;
+  propertyName?: string;
+  parentSchema?: object;
+  data?: any;
+}
+
+// An invalid event with its associated collection of validation errors.
+interface InvalidEvent {
+  eventName: string;
+  validationErrors: AjvErrorObject[];
+}
+
+// Options to customize the runtime behavior of a Typewriter client.
+interface AnalyticsOptions {
+  onError(event: InvalidEvent): void;
+}
+
 export default class Analytics {
-  constructor(analytics: any);
+  constructor(analytics: any, options?: AnalyticsOptions);
 
   feedViewed(
     props?: FeedViewed,

diff --git a/examples/gen-js/ts/analytics/generated/index.js b/examples/gen-js/ts/analytics/generated/index.js
@@ -1,13 +1,21 @@
 export default class Analytics {
   /**
    * Instantiate a wrapper around an analytics library instance
-   * @param {Analytics} analytics - The analytics.js library to wrap
+   * @param {Analytics} analytics The analytics.js library to wrap
+   * @param {Object} [options] Optional configuration of the Typewriter client
+   * @param {function} [options.onError] Error handler fired when run-time validation errors
+   *     are raised.
    */
-  constructor(analytics) {
+  constructor(analytics, options = {}) {
     if (!analytics) {
       throw new Error("An instance of analytics.js must be provided");
     }
     this.analytics = analytics || { track: () => null };
+    this.onError =
+      options.onError ||
+      (error => {
+        throw new Error(JSON.stringify(error, null, 2));
+      });
   }
   addTypewriterContext(context = {}) {
     return {
@@ -97,7 +105,11 @@ export default class Analytics {
       return errors === 0;
     };
     if (!validate({ properties: props })) {
-      throw new Error(JSON.stringify(validate.errors, null, 2));
+      this.onError({
+        eventName: "Feed Viewed",
+        validationErrors: validate.errors
+      });
+      return;
     }
     this.analytics.track(
       "Feed Viewed",
@@ -188,7 +200,11 @@ export default class Analytics {
       return errors === 0;
     };
     if (!validate({ properties: props })) {
-      throw new Error(JSON.stringify(validate.errors, null, 2));
+      this.onError({
+        eventName: "Photo Viewed",
+        validationErrors: validate.errors
+      });
+      return;
     }
     this.analytics.track(
       "Photo Viewed",
@@ -279,7 +295,11 @@ export default class Analytics {
       return errors === 0;
     };
     if (!validate({ properties: props })) {
-      throw new Error(JSON.stringify(validate.errors, null, 2));
+      this.onError({
+        eventName: "Profile Viewed",
+        validationErrors: validate.errors
+      });
+      return;
     }
     this.analytics.track(
       "Profile Viewed",

diff --git a/src/commands/gen-js/library.ts b/src/commands/gen-js/library.ts
@@ -28,15 +28,23 @@ export function genJS(
   if (!analytics) {
     throw new Error('An instance of ${clientName} must be provided')
   }`
+  const errorHandler = `
+  this.onError = options.onError || (error => {
+    throw new Error(JSON.stringify(error, null, 2));
+  })`
   const fileHeader = `
     export default class Analytics {
       /**
        * Instantiate a wrapper around an analytics library instance
-       * @param {Analytics} analytics - The ${clientName} library to wrap
+       * @param {Analytics} analytics The ${clientName} library to wrap
+       * @param {Object} [options] Optional configuration of the Typewriter client
+       * @param {function} [options.onError] Error handler fired when run-time validation errors
+       *     are raised.
        */
-      constructor(analytics) {
+      constructor(analytics, options = {}) {
         ${runtimeValidation ? analyticsValidation : ''}
         this.analytics = analytics || { track: () => null }
+        ${runtimeValidation ? errorHandler : ''}
       }
 
       addTypewriterContext(context = {}) {
@@ -82,7 +90,8 @@ export function genJS(
       const validationCode = `
       ${compiledValidationFn}
       if (!${validateCall}) {
-        throw new Error(JSON.stringify(validate.errors, null, 2));
+        this.onError({ eventName: '${name}', validationErrors: validate.errors })
+        return
       }`
 
       return `

diff --git a/src/commands/gen-js/typescript.ts b/src/commands/gen-js/typescript.ts
@@ -283,8 +283,32 @@ class AJSTSDeclarationsRenderer extends TypeScriptRenderer {
       'Analytics provides a strongly-typed wrapper around Segment Analytics',
       'based on your Tracking Plan.'
     ])
+    this.emitLine(`
+      // From https://github.com/epoberezkin/ajv/blob/0c31c1e2a81e315511c60a0dd7420a72cb181e61/lib/ajv.d.ts#L279
+      interface AjvErrorObject {
+        keyword: string;
+        dataPath: string;
+        schemaPath: string;
+        params: object;
+        message: string;
+        propertyName?: string;
+        parentSchema?: object;
+        data?: any;
+      }
+
+      // An invalid event with its associated collection of validation errors.
+      interface InvalidEvent {
+        eventName: string;
+        validationErrors: AjvErrorObject[];
+      }
+
+      // Options to customize the runtime behavior of a Typewriter client.
+      interface AnalyticsOptions {
+        onError(event: InvalidEvent): void;
+      }
+    `)
     this.emitBlock('export default class Analytics', '', () => {
-      this.emitLine('constructor(analytics: any)')
+      this.emitLine('constructor(analytics: any, options?: AnalyticsOptions)')
       this.ensureBlankLine()
 
       this.emitAnalyticsFunctions()