@aperture.io/analytics - npm Package Compare versions

Comparing version 0.1.6 to 0.1.7

package.json

 {
   "private": false,
   "name": "@aperture.io/analytics",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Declarative React analytics library",
@@ -6,0 +6,0 @@ "author": "Eldar Shamukhamedov",

README.md

@@ -338,2 +338,66 @@ # Analytics library
 
+### Error handling
+
+Despite our best efforts, our code will inevitably throw unexpected runtime errors. In this library's case, the most common errors we might run into are:
+
+1. Logic errors in our `dispatch` functions
+2. Validation errors that we might throw on purpose in our validation middleware
+
+When an error is thrown, the `useAnalytics` hook returns an additional `error` object:
+
+```js
+const { error } = useAnalytics(
+  { some: 'data' },
+  {
+    dispatch: () => {
+      throw Error('Uh oh');
+    },
+  },
+);
+```
+
+Given the _highly-nested_ nature of this library, it is important to note that errors are handled in the _local_ call to `useAnalytics`, and do not bubble up to parents.
+
+In our grocery list example from earlier, events were triggered from the `<GroceryCheckbox />` component, so that is where the `error` object will be available:
+
+```js
+const GroceryCheckbox = () => {
+  // 👇 Call to trackEvent happens in this component, so the error is caught here
+  const { trackEvent, error } = useAnalytics();
+  const [checked, setChecked] = useState(false);
+  return (
+    <input
+      type="checkbox"
+      checked={checked}
+      onChange={() => {
+        trackEvent({
+          action: 'done-button-toggle',
+          bought: !checked,
+        });
+        setChecked(!checked);
+      }}
+    />
+  );
+};
+```
+
+### Overriding default merge behavior
+
+To avoid making assumption about the desired merging behavior, this library _merges event data shallowly_ by default. Deeply merging event data is a large application with many levels of tracked parent and child components can get complicated quickly, so it is generally discouraged.
+
+If you do require more complex data shapes, you have the option to override the default merge using the `mergeData` config option:
+
+```js
+import { merge } from 'lodash';
+
+const { error } = useAnalytics(
+  { nested: { some: 'data' } },
+  { mergeData: (parentData, localData) => merge({}, parentData, localData) },
+);
+```
+
+💡 Note that you can pass different `mergeData` functions to each call to `useAnalytics`, so each nested tracked component has full control over how its local event data merging is handled.
+
+---
+
 And that's the library! Happy tracking! 🚀🚀🚀
@@ -340,0 +404,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

178517

increased by1.53%

Number of package files

10

increased by25%

Lines of code

1067

increased by1.62%

Number of lines in readme file

457

increased by16.28%

No dependency changes