react-event-tracking 1.0.8 → 1.0.10

package/README.md

@@ -19,6 +19,7 @@ A convenient React context for tracking analytics events.
   * [Multiple Trackers & Factory](#multiple-trackers--factory)
   * [Filtering Events](#filtering-events)
   * [Transforming Events](#transforming-events)
+  * [TypeScript Generics Support](#typescript-generics-support)
 - [Best Practices](#best-practices)
 - [Built-in Hooks](#built-in-hooks)
   * [useMountEvent](#usemountevent)
@@ -59,20 +60,20 @@ const Dashboard = () => (
 
 3. Send events conveniently. On button click, parameters will be merged.
 ```tsx
-import { useTracker } from 'react-event-tracking';
+import { useReactEventTracking } from 'react-event-tracking';
 
 const MyButton = () => {
-  const { sendEvent } = useTracker();
+  const { track } = useReactEventTracking();
 
   return (
     <>
     // event sent with parameters: { screen: 'dashboard', button_id: '123' }
-    <button onClick={() => sendEvent('click', { button_id: '123' })}>
+    <button onClick={() => track('click', { button_id: '123' })}>
       Click me
     </button>
 
     {/* Option B: Object call */}                                                                                                           
-    <button onClick={() => sendEvent({ eventName: 'click', params: { button_id: '456' } })}>                                                
+    <button onClick={() => track({ eventName: 'click', params: { button_id: '456' } })}>                                                
       Click me too                                                                                                                          
     </button>  
     </>
@@ -164,6 +165,22 @@ const AmpltitudeUS = TrackRoot.factory(
 );
 ```
 
+### TypeScript Generics Support
+
+`TrackProvider` supports generics for strict typing of the passed parameters.
+
+```tsx
+interface ScreenParams {
+  screen: "dashboard" | "authScreen"
+}
+
+const MyPage = () => (
+  <TrackProvider<ScreenParams> params={{ screen: 'dashboard' }}>
+    <Content />
+  </TrackProvider>
+);
+```
+
 ## Best Practices
 
 A common pattern is to layer data from global to specific. Here is how parameters merge:
@@ -186,12 +203,12 @@ A common pattern is to layer data from global to specific. Here is how parameter
 </TrackRoot>
 
 // Inside AddToCartButton:
-const { sendEvent } = useTracker();
+const { track } = useReactEventTracking();
 
 // 4. EVENT: Action-specific data
 // When clicked, we only pass what changed right now.
 const handleClick = () => {
-  sendEvent('add_to_cart', { quantity: 1 });
+  track('add_to_cart', { quantity: 1 });
 };
 ```
 

package/dist/index.cjs

@@ -20,10 +20,10 @@ function parseEventArgs(eventNameOrObject, eventParams) {
 }
 
 const TrackContext = React__default.createContext(null);
-const useTracker = () => {
+const useReactEventTracking = () => {
   const ctx = React.useContext(TrackContext);
   if (!ctx) {
-    throw new Error("useTracker must be used within TrackRoot");
+    throw new Error("useReactEventTracking must be used within TrackRoot");
   }
   return ctx;
 };
@@ -33,7 +33,7 @@ const TrackRootComponent = ({ onEvent, children, filter, transform }) => {
   const onEventRef = useFreshRef(onEvent);
   const filterRef = useFreshRef(filter);
   const transformRef = useFreshRef(transform);
-  function sendEvent(eventNameOrObject, eventParams) {
+  function track(eventNameOrObject, eventParams) {
     const { eventName, params: incomingParams } = parseEventArgs(
       eventNameOrObject,
       eventParams
@@ -68,20 +68,19 @@ const TrackRootComponent = ({ onEvent, children, filter, transform }) => {
       }
     }
     if (parentCtx) {
-      parentCtx.sendEvent(eventName, incomingParams);
+      parentCtx.track(eventName, incomingParams);
     }
   }
-  const sendEventCached = React.useCallback(sendEvent, [parentCtx]);
-  const value = React.useMemo(() => ({ sendEvent: sendEventCached }), [sendEventCached]);
+  const value = React.useMemo(() => ({ track }), [parentCtx]);
   return /* @__PURE__ */ React__default.createElement(TrackContext.Provider, { value }, children);
 };
-const factory = (onEvent, filter, transform) => {
+const factory = (args) => {
   return (props) => /* @__PURE__ */ React__default.createElement(
     TrackRootComponent,
     {
-      onEvent,
-      filter,
-      transform,
+      onEvent: args.onEvent,
+      filter: args.filter,
+      transform: args.transform,
       ...props
     }
   );
@@ -91,21 +90,20 @@ const TrackProvider = ({
   params,
   children
 }) => {
-  const ctx = useTracker();
+  const ctx = useReactEventTracking();
   const paramsRef = useFreshRef(params);
-  function sendEvent(eventNameOrObject, eventParams) {
+  function track(eventNameOrObject, eventParams) {
     const { eventName, params: incomingParams } = parseEventArgs(
       eventNameOrObject,
       eventParams
     );
     const currentParams = paramsRef.current;
-    ctx.sendEvent(eventName, {
+    ctx.track(eventName, {
       ...currentParams,
       ...incomingParams
     });
   }
-  const sendEventCached = React.useCallback(sendEvent, [ctx]);
-  const value = React.useMemo(() => ({ sendEvent: sendEventCached }), [sendEventCached]);
+  const value = React.useMemo(() => ({ track }), [ctx]);
   return /* @__PURE__ */ React__default.createElement(TrackContext.Provider, { value }, children);
 };
 function useFreshRef(data) {
@@ -115,7 +113,7 @@ function useFreshRef(data) {
 }
 
 function useMountEvent(eventNameOrObject, eventParams) {
-  const { sendEvent } = useTracker();
+  const { track } = useReactEventTracking();
   const counterRef = React.useRef(0);
   const { eventName, params } = parseEventArgs(eventNameOrObject, eventParams);
   React.useEffect(() => {
@@ -123,11 +121,11 @@ function useMountEvent(eventNameOrObject, eventParams) {
       return;
     }
     counterRef.current++;
-    sendEvent(eventName, params);
+    track(eventName, params);
   }, []);
 }
 
 exports.TrackProvider = TrackProvider;
 exports.TrackRoot = TrackRoot;
 exports.useMountEvent = useMountEvent;
-exports.useTracker = useTracker;
+exports.useReactEventTracking = useReactEventTracking;

package/dist/index.d.cts

@@ -1,10 +1,10 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { PropsWithChildren } from 'react';
 
-type EventParams = Record<string, any>;
+type EventParams<T extends Record<string, any> = Record<string, any>> = T;
 interface TrackContextValue {
-    sendEvent(eventName: string, params?: EventParams): void;
-    sendEvent(event: EventObject): void;
+    track(eventName: string, params?: EventParams): void;
+    track(event: EventObject): void;
 }
 type EventObject = {
     eventName: string;
@@ -17,20 +17,24 @@ type TransformedEvent = {
 };
 type EventTransformer = (eventName: string, params: EventParams) => TransformedEvent;
 
-declare const useTracker: () => TrackContextValue;
+declare const useReactEventTracking: () => TrackContextValue;
 type TrackRootProps = PropsWithChildren<{
     onEvent: (eventName: string, params: EventParams) => void;
     filter?: EventFilter;
     transform?: EventTransformer;
 }>;
 declare const TrackRoot: (({ onEvent, children, filter, transform }: TrackRootProps) => react_jsx_runtime.JSX.Element) & {
-    factory: (onEvent: (eventName: string, params?: EventParams) => void, filter?: EventFilter, transform?: EventTransformer) => (props: Omit<TrackRootProps, "onEvent" | "filter" | "transform">) => react_jsx_runtime.JSX.Element;
+    factory: (args: {
+        onEvent: (eventName: string, params?: EventParams) => void;
+        filter?: EventFilter;
+        transform?: EventTransformer;
+    }) => (props: Omit<TrackRootProps, "onEvent" | "filter" | "transform">) => react_jsx_runtime.JSX.Element;
 };
-declare const TrackProvider: ({ params, children }: PropsWithChildren<{
-    params: EventParams;
+declare const TrackProvider: <T extends Record<string, any>>({ params, children }: PropsWithChildren<{
+    params: EventParams<T>;
 }>) => react_jsx_runtime.JSX.Element;
 
 declare function useMountEvent(eventName: string, params?: EventParams): void;
 declare function useMountEvent(event: EventObject): void;
 
-export { TrackProvider, TrackRoot, useMountEvent, useTracker };
+export { TrackProvider, TrackRoot, useMountEvent, useReactEventTracking };

package/dist/index.d.mts

@@ -1,10 +1,10 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { PropsWithChildren } from 'react';
 
-type EventParams = Record<string, any>;
+type EventParams<T extends Record<string, any> = Record<string, any>> = T;
 interface TrackContextValue {
-    sendEvent(eventName: string, params?: EventParams): void;
-    sendEvent(event: EventObject): void;
+    track(eventName: string, params?: EventParams): void;
+    track(event: EventObject): void;
 }
 type EventObject = {
     eventName: string;
@@ -17,20 +17,24 @@ type TransformedEvent = {
 };
 type EventTransformer = (eventName: string, params: EventParams) => TransformedEvent;
 
-declare const useTracker: () => TrackContextValue;
+declare const useReactEventTracking: () => TrackContextValue;
 type TrackRootProps = PropsWithChildren<{
     onEvent: (eventName: string, params: EventParams) => void;
     filter?: EventFilter;
     transform?: EventTransformer;
 }>;
 declare const TrackRoot: (({ onEvent, children, filter, transform }: TrackRootProps) => react_jsx_runtime.JSX.Element) & {
-    factory: (onEvent: (eventName: string, params?: EventParams) => void, filter?: EventFilter, transform?: EventTransformer) => (props: Omit<TrackRootProps, "onEvent" | "filter" | "transform">) => react_jsx_runtime.JSX.Element;
+    factory: (args: {
+        onEvent: (eventName: string, params?: EventParams) => void;
+        filter?: EventFilter;
+        transform?: EventTransformer;
+    }) => (props: Omit<TrackRootProps, "onEvent" | "filter" | "transform">) => react_jsx_runtime.JSX.Element;
 };
-declare const TrackProvider: ({ params, children }: PropsWithChildren<{
-    params: EventParams;
+declare const TrackProvider: <T extends Record<string, any>>({ params, children }: PropsWithChildren<{
+    params: EventParams<T>;
 }>) => react_jsx_runtime.JSX.Element;
 
 declare function useMountEvent(eventName: string, params?: EventParams): void;
 declare function useMountEvent(event: EventObject): void;
 
-export { TrackProvider, TrackRoot, useMountEvent, useTracker };
+export { TrackProvider, TrackRoot, useMountEvent, useReactEventTracking };

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { PropsWithChildren } from 'react';
 
-type EventParams = Record<string, any>;
+type EventParams<T extends Record<string, any> = Record<string, any>> = T;
 interface TrackContextValue {
-    sendEvent(eventName: string, params?: EventParams): void;
-    sendEvent(event: EventObject): void;
+    track(eventName: string, params?: EventParams): void;
+    track(event: EventObject): void;
 }
 type EventObject = {
     eventName: string;
@@ -17,20 +17,24 @@ type TransformedEvent = {
 };
 type EventTransformer = (eventName: string, params: EventParams) => TransformedEvent;
 
-declare const useTracker: () => TrackContextValue;
+declare const useReactEventTracking: () => TrackContextValue;
 type TrackRootProps = PropsWithChildren<{
     onEvent: (eventName: string, params: EventParams) => void;
     filter?: EventFilter;
     transform?: EventTransformer;
 }>;
 declare const TrackRoot: (({ onEvent, children, filter, transform }: TrackRootProps) => react_jsx_runtime.JSX.Element) & {
-    factory: (onEvent: (eventName: string, params?: EventParams) => void, filter?: EventFilter, transform?: EventTransformer) => (props: Omit<TrackRootProps, "onEvent" | "filter" | "transform">) => react_jsx_runtime.JSX.Element;
+    factory: (args: {
+        onEvent: (eventName: string, params?: EventParams) => void;
+        filter?: EventFilter;
+        transform?: EventTransformer;
+    }) => (props: Omit<TrackRootProps, "onEvent" | "filter" | "transform">) => react_jsx_runtime.JSX.Element;
 };
-declare const TrackProvider: ({ params, children }: PropsWithChildren<{
-    params: EventParams;
+declare const TrackProvider: <T extends Record<string, any>>({ params, children }: PropsWithChildren<{
+    params: EventParams<T>;
 }>) => react_jsx_runtime.JSX.Element;
 
 declare function useMountEvent(eventName: string, params?: EventParams): void;
 declare function useMountEvent(event: EventObject): void;
 
-export { TrackProvider, TrackRoot, useMountEvent, useTracker };
+export { TrackProvider, TrackRoot, useMountEvent, useReactEventTracking };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import React, { useContext, useCallback, useMemo, useRef, useEffect } from 'react';
+import React, { useContext, useMemo, useRef, useEffect } from 'react';
 
 function parseEventArgs(eventNameOrObject, eventParams) {
   if (typeof eventNameOrObject === "object") {
@@ -14,10 +14,10 @@ function parseEventArgs(eventNameOrObject, eventParams) {
 }
 
 const TrackContext = React.createContext(null);
-const useTracker = () => {
+const useReactEventTracking = () => {
   const ctx = useContext(TrackContext);
   if (!ctx) {
-    throw new Error("useTracker must be used within TrackRoot");
+    throw new Error("useReactEventTracking must be used within TrackRoot");
   }
   return ctx;
 };
@@ -27,7 +27,7 @@ const TrackRootComponent = ({ onEvent, children, filter, transform }) => {
   const onEventRef = useFreshRef(onEvent);
   const filterRef = useFreshRef(filter);
   const transformRef = useFreshRef(transform);
-  function sendEvent(eventNameOrObject, eventParams) {
+  function track(eventNameOrObject, eventParams) {
     const { eventName, params: incomingParams } = parseEventArgs(
       eventNameOrObject,
       eventParams
@@ -62,20 +62,19 @@ const TrackRootComponent = ({ onEvent, children, filter, transform }) => {
       }
     }
     if (parentCtx) {
-      parentCtx.sendEvent(eventName, incomingParams);
+      parentCtx.track(eventName, incomingParams);
     }
   }
-  const sendEventCached = useCallback(sendEvent, [parentCtx]);
-  const value = useMemo(() => ({ sendEvent: sendEventCached }), [sendEventCached]);
+  const value = useMemo(() => ({ track }), [parentCtx]);
   return /* @__PURE__ */ React.createElement(TrackContext.Provider, { value }, children);
 };
-const factory = (onEvent, filter, transform) => {
+const factory = (args) => {
   return (props) => /* @__PURE__ */ React.createElement(
     TrackRootComponent,
     {
-      onEvent,
-      filter,
-      transform,
+      onEvent: args.onEvent,
+      filter: args.filter,
+      transform: args.transform,
       ...props
     }
   );
@@ -85,21 +84,20 @@ const TrackProvider = ({
   params,
   children
 }) => {
-  const ctx = useTracker();
+  const ctx = useReactEventTracking();
   const paramsRef = useFreshRef(params);
-  function sendEvent(eventNameOrObject, eventParams) {
+  function track(eventNameOrObject, eventParams) {
     const { eventName, params: incomingParams } = parseEventArgs(
       eventNameOrObject,
       eventParams
     );
     const currentParams = paramsRef.current;
-    ctx.sendEvent(eventName, {
+    ctx.track(eventName, {
       ...currentParams,
       ...incomingParams
     });
   }
-  const sendEventCached = useCallback(sendEvent, [ctx]);
-  const value = useMemo(() => ({ sendEvent: sendEventCached }), [sendEventCached]);
+  const value = useMemo(() => ({ track }), [ctx]);
   return /* @__PURE__ */ React.createElement(TrackContext.Provider, { value }, children);
 };
 function useFreshRef(data) {
@@ -109,7 +107,7 @@ function useFreshRef(data) {
 }
 
 function useMountEvent(eventNameOrObject, eventParams) {
-  const { sendEvent } = useTracker();
+  const { track } = useReactEventTracking();
   const counterRef = useRef(0);
   const { eventName, params } = parseEventArgs(eventNameOrObject, eventParams);
   useEffect(() => {
@@ -117,8 +115,8 @@ function useMountEvent(eventNameOrObject, eventParams) {
       return;
     }
     counterRef.current++;
-    sendEvent(eventName, params);
+    track(eventName, params);
   }, []);
 }
 
-export { TrackProvider, TrackRoot, useMountEvent, useTracker };
+export { TrackProvider, TrackRoot, useMountEvent, useReactEventTracking };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-event-tracking",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "files": [
     "dist"
   ],