Added dataLayer utility

Author: Gijs Nieuwenhuis

README.md

@@ -21,6 +21,8 @@ A library containing javascript utilities that we until now often copy between p
         -   [`createNamespacedLogger`](#createnamespacedlogger)
     -   [`RestartableTimeout`](#restartabletimeout)
     -   [`PromiseQueue`](#promisequeue)
+    -   [`dataLayer`](#datalayer)
+        -   [`pushTrackingEvent`](#pushtrackingevent)
 -   [React](#react)
     -   [Components](#components)
         -   [`ErrorBoundary`](#errorboundary)
@@ -317,6 +319,20 @@ queue.length; // returns the current length of the queue
 queue.started; // returns true if started
 ```
 
+### dataLayer
+
+#### `pushTrackingEvent`
+
+Pushes an event to the dataLayer to be picked up by Google Tag Manager, in a standardized format.
+
+Usage:
+
+```typescript
+import { pushTrackingEvent } from '@freshheads/javascript-essentials/build/utilities/dataLayer';
+
+pushTrackingEvent('preorder', 'submit', { subscribeToNewsletter: false });
+```
+
 ## React
 
 ### Components

src/global.d.ts

@@ -0,0 +1,7 @@
+interface Window {
+    dataLayer?: Array<{
+        event: string;
+        action: string;
+        [key: string]: any;
+    }>;
+}

src/utilities/__tests__/dataLayer.test.ts

@@ -0,0 +1,67 @@
+import { pushTrackingEvent } from '../dataLayer';
+
+describe('dataLayer', () => {
+    describe('pushTrackingEvent', () => {
+        describe('When no dataLayer exists', () => {
+            it('should create a new data layer and add the event to it', () => {
+                // @ts-ignore => typescript does not know about dataLayer on window
+                delete window.dataLayer;
+
+                pushTrackingEvent('preorder', 'submit', {
+                    subscribeToNewsletter: true,
+                });
+
+                // @ts-ignore => typescript does not know about dataLayer on window
+                expect(window.dataLayer).toBeDefined();
+
+                // @ts-ignore => typescript does not know about dataLayer on window
+                expect(Array.isArray(window.dataLayer)).toBe(true);
+
+                // @ts-ignore => typescript does not know about dataLayer on window
+                expect(window.dataLayer).toHaveLength(1);
+
+                // @ts-ignore => typescript does not know about dataLayer on window
+                const firstItem = window.dataLayer[0];
+
+                expect(firstItem).toEqual({
+                    event: 'preorder',
+                    action: 'submit',
+                    context: {
+                        subscribeToNewsletter: true,
+                    },
+                });
+            });
+        });
+
+        describe('When a dataLayer already exists', () => {
+            it('should add the event to the existing events in the dataLayer', () => {
+                // @ts-ignore => typescript does not know about dataLayer on window
+                window.dataLayer = [
+                    {
+                        event: 'other_event',
+                        action: 'click',
+                    },
+                ];
+
+                pushTrackingEvent('preorder', 'submit');
+
+                // @ts-ignore => Typescript does not know about dataLayer property
+                expect(window.dataLayer).toBeDefined();
+
+                // @ts-ignore => typescript does not know about dataLayer on window
+                expect(Array.isArray(window.dataLayer)).toBe(true);
+
+                // @ts-ignore => typescript does not know about dataLayer on window
+                expect(window.dataLayer).toHaveLength(2);
+
+                // @ts-ignore => typescript does not know about dataLayer on window
+                const addedItem = window.dataLayer[1];
+
+                expect(addedItem).toEqual({
+                    event: 'preorder',
+                    action: 'submit',
+                });
+            });
+        });
+    });
+});

src/utilities/dataLayer.ts

@@ -0,0 +1,15 @@
+import { Serializable } from '../types/utility';
+
+/**
+ * @param {String} event            i.e. preorder
+ * @param {String} action           i.e. submit
+ * @param {Serializable=} context   i.e. { subscribeToNewsletter: true }
+ */
+export function pushTrackingEvent(
+    event: string,
+    action: string,
+    context?: Serializable
+): void {
+    window.dataLayer = window.dataLayer || [];
+    window.dataLayer.push({ event, action, context });
+}