utneque 1.0.0

package/packages/browser/src/lib/global-analytics-helper.ts

@@ -0,0 +1,31 @@
+import { HtEventsSnippet } from '../browser/standalone-interface'
+
+/**
+ * Stores the global window analytics key
+ */
+let _globalAnalyticsKey = 'htevents'
+
+/**
+ * Gets the global analytics/buffer
+ * @param key name of the window property where the buffer is stored (default: analytics)
+ * @returns HtEventsSnippet
+ */
+export function getGlobalAnalytics(): HtEventsSnippet | undefined {
+  return (window as any)[_globalAnalyticsKey]
+}
+
+/**
+ * Replaces the global window key for the analytics/buffer object
+ * @param key key name
+ */
+export function setGlobalAnalyticsKey(key: string) {
+  _globalAnalyticsKey = key
+}
+
+/**
+ * Sets the global analytics object
+ * @param analytics analytics snippet
+ */
+export function setGlobalAnalytics(analytics: HtEventsSnippet): void {
+  ;(window as any)[_globalAnalyticsKey] = analytics
+}

package/packages/browser/src/lib/group-by.ts

@@ -0,0 +1,30 @@
+type Grouper<T> = (obj: T) => string | number
+
+export function groupBy<T>(
+  collection: T[],
+  grouper: keyof T | Grouper<T>
+): Record<string, T[]> {
+  const results: Record<string, T[]> = {}
+
+  collection.forEach((item) => {
+    let key: string | number | undefined = undefined
+
+    if (typeof grouper === 'string') {
+      const suggestedKey = item[grouper]
+      key =
+        typeof suggestedKey !== 'string'
+          ? JSON.stringify(suggestedKey)
+          : suggestedKey
+    } else if (grouper instanceof Function) {
+      key = grouper(item)
+    }
+
+    if (key === undefined) {
+      return
+    }
+
+    results[key] = [...(results[key] ?? []), item]
+  })
+
+  return results
+}

package/packages/browser/src/lib/is-plan-event-enabled.ts

@@ -0,0 +1,20 @@
+import { PlanEvent, TrackPlan } from '../core/events/interfaces'
+
+/**
+ * Determines whether a track event is allowed to be sent based on the
+ * user's tracking plan.
+ * If the user does not have a tracking plan or the event is allowed based
+ * on the tracking plan configuration, returns true.
+ */
+export function isPlanEventEnabled(
+  plan: TrackPlan | undefined,
+  planEvent: PlanEvent | undefined
+): boolean {
+  // Always prioritize the event's `enabled` status
+  if (typeof planEvent?.enabled === 'boolean') {
+    return planEvent.enabled
+  }
+
+  // Assume absence of a tracking plan means events are enabled
+  return plan?.__default?.enabled ?? true
+}

package/packages/browser/src/lib/is-thenable.ts

@@ -0,0 +1,9 @@
+/**
+ *  Check if  thenable
+ *  (instanceof Promise doesn't respect realms)
+ */
+export const isThenable = (value: unknown): boolean =>
+  typeof value === 'object' &&
+  value !== null &&
+  'then' in value &&
+  typeof (value as any).then === 'function'

package/packages/browser/src/lib/load-script.ts

@@ -0,0 +1,66 @@
+function findScript(src: string): HTMLScriptElement | undefined {
+  const scripts = Array.prototype.slice.call(
+    window.document.querySelectorAll('script')
+  )
+  return scripts.find((s) => s.src === src)
+}
+
+export function loadScript(
+  src: string,
+  attributes?: Record<string, string>
+): Promise<HTMLScriptElement> {
+  const found = findScript(src)
+
+  if (found !== undefined) {
+    const status = found?.getAttribute('status')
+
+    if (status === 'loaded') {
+      return Promise.resolve(found)
+    }
+
+    if (status === 'loading') {
+      return new Promise((resolve, reject) => {
+        found.addEventListener('load', () => resolve(found))
+        found.addEventListener('error', (err) => reject(err))
+      })
+    }
+  }
+
+  return new Promise((resolve, reject) => {
+    const script = window.document.createElement('script')
+
+    script.type = 'text/javascript'
+    script.src = src
+    script.async = true
+
+    script.setAttribute('status', 'loading')
+    for (const [k, v] of Object.entries(attributes ?? {})) {
+      script.setAttribute(k, v)
+    }
+
+    script.onload = (): void => {
+      script.onerror = script.onload = null
+      script.setAttribute('status', 'loaded')
+      resolve(script)
+    }
+
+    script.onerror = (): void => {
+      script.onerror = script.onload = null
+      script.setAttribute('status', 'error')
+      reject(new Error(`Failed to load ${src}`))
+    }
+
+    const tag = window.document.getElementsByTagName('script')[0]
+    tag.parentElement?.insertBefore(script, tag)
+  })
+}
+
+export function unloadScript(src: string): Promise<void> {
+  const found = findScript(src)
+
+  if (found !== undefined) {
+    found.remove()
+  }
+
+  return Promise.resolve()
+}

package/packages/browser/src/lib/merged-options.ts

@@ -0,0 +1,46 @@
+import { JSONObject, Options } from '../core/events/interfaces'
+import { LegacySettings } from '../browser'
+
+/**
+ * Merge legacy settings and initialized Integration option overrides.
+ *
+ * This will merge any options that were passed from initialization into
+ * overrides for settings that are returned by the Hightouch CDN.
+ *
+ * i.e. this allows for passing options directly into destinations from
+ * the Analytics constructor.
+ */
+export function mergedOptions(
+  settings: LegacySettings,
+  options: Options
+): Record<string, JSONObject> {
+  const optionOverrides = Object.entries(options.integrations ?? {}).reduce(
+    (overrides, [integration, options]) => {
+      if (typeof options === 'object') {
+        return {
+          ...overrides,
+          [integration]: options,
+        }
+      }
+
+      return {
+        ...overrides,
+        [integration]: {},
+      }
+    },
+    {} as Record<string, JSONObject>
+  )
+
+  return Object.entries(settings.integrations).reduce(
+    (integrationSettings, [integration, settings]) => {
+      return {
+        ...integrationSettings,
+        [integration]: {
+          ...settings,
+          ...optionOverrides[integration],
+        },
+      }
+    },
+    {} as Record<string, JSONObject>
+  )
+}

package/packages/browser/src/lib/on-page-change.ts

@@ -0,0 +1,29 @@
+/**
+ * Register event listener on document that fires when:
+ * * tab change or tab close (in mobile or desktop)
+ * * click back / forward button
+ * * click any link or perform any other navigation action
+ * * soft refresh / hard refresh
+ *
+ * adapted from https://stackoverflow.com/questions/3239834/window-onbeforeunload-not-working-on-the-ipad/52864508#52864508,
+ */
+export const onPageChange = (cb: (unloaded: boolean) => void) => {
+  let unloaded = false // prevents double firing if both are supported
+
+  window.addEventListener('pagehide', () => {
+    if (unloaded) return
+    unloaded = true
+    cb(unloaded)
+  })
+
+  // using document instead of window because of bug affecting browsers before safari 14 (detail in footnotes https://caniuse.com/?search=visibilitychange)
+  document.addEventListener('visibilitychange', () => {
+    if (document.visibilityState == 'hidden') {
+      if (unloaded) return
+      unloaded = true
+    } else {
+      unloaded = false
+    }
+    cb(unloaded)
+  })
+}

package/packages/browser/src/lib/p-while.ts

@@ -0,0 +1,12 @@
+export const pWhile = async <T>(
+  condition: (value: T | undefined) => boolean,
+  action: () => T | PromiseLike<T>
+): Promise<void> => {
+  const loop = async (actionResult: T | undefined): Promise<void> => {
+    if (condition(actionResult)) {
+      return loop(await action())
+    }
+  }
+
+  return loop(undefined)
+}

package/packages/browser/src/lib/parse-cdn.ts

@@ -0,0 +1,56 @@
+import { getGlobalAnalytics } from './global-analytics-helper'
+
+const analyticsScriptRegex =
+  /(https:\/\/.*)\/analytics\.js\/v1\/(?:.*?)\/(?:platform|analytics.*)?/
+const getCDNUrlFromScriptTag = (): string | undefined => {
+  let cdn: string | undefined
+  const scripts = Array.prototype.slice.call(
+    document.querySelectorAll('script')
+  )
+  scripts.forEach((s) => {
+    const src = s.getAttribute('src') ?? ''
+    const result = analyticsScriptRegex.exec(src)
+
+    if (result && result[1]) {
+      cdn = result[1]
+    }
+  })
+  return cdn
+}
+
+let _globalCDN: string | undefined // set globalCDN as in-memory singleton
+const getGlobalCDNUrl = (): string | undefined => {
+  const result = _globalCDN ?? getGlobalAnalytics()?._cdn
+  return result
+}
+
+export const setGlobalCDNUrl = (cdn: string) => {
+  const globalAnalytics = getGlobalAnalytics()
+  if (globalAnalytics) {
+    globalAnalytics._cdn = cdn
+  }
+  _globalCDN = cdn
+}
+
+export const getCDN = (): string => {
+  const globalCdnUrl = getGlobalCDNUrl()
+
+  if (globalCdnUrl) return globalCdnUrl
+
+  const cdnFromScriptTag = getCDNUrlFromScriptTag()
+
+  if (cdnFromScriptTag) {
+    return cdnFromScriptTag
+  } else {
+    // it's possible that the CDN is not found in the page because:
+    // - the script is loaded through a proxy
+    // - the script is removed after execution
+    // in this case, we fall back to the default Hightouch CDN
+    return `https://cdn.hightouch-events.com`
+  }
+}
+
+export const getNextIntegrationsURL = () => {
+  const cdn = getCDN()
+  return `${cdn}/next-integrations`
+}

package/packages/browser/src/lib/pick.ts

@@ -0,0 +1,28 @@
+export function pick<T extends Record<string, any>, K extends keyof T>(
+  object: T,
+  keys: readonly K[]
+): Pick<T, K>
+
+export function pick<T extends Record<string, any>>(
+  object: T,
+  keys: string[]
+): Partial<T>
+
+/**
+ * @example
+ * pick({ 'a': 1, 'b': '2', 'c': 3 }, ['a', 'c'])
+ * => { 'a': 1, 'c': 3 }
+ */
+export function pick<T extends Record<string, any>, K extends keyof T>(
+  object: T,
+  keys: string[] | K[] | readonly K[]
+) {
+  return Object.assign(
+    {},
+    ...keys.map((key) => {
+      if (object && Object.prototype.hasOwnProperty.call(object, key)) {
+        return { [key]: object[key] }
+      }
+    })
+  )
+}

package/packages/browser/src/lib/priority-queue/__tests__/backoff.test.ts

@@ -0,0 +1,23 @@
+import { backoff } from '../backoff'
+
+describe('backoff', () => {
+  it('increases with the number of attempts', () => {
+    expect(backoff({ attempt: 1 })).toBeGreaterThan(1000)
+    expect(backoff({ attempt: 2 })).toBeGreaterThan(2000)
+    expect(backoff({ attempt: 3 })).toBeGreaterThan(3000)
+    expect(backoff({ attempt: 4 })).toBeGreaterThan(4000)
+  })
+
+  it('accepts a max timeout', () => {
+    expect(backoff({ attempt: 1, maxTimeout: 3000 })).toBeGreaterThan(1000)
+    expect(backoff({ attempt: 3, maxTimeout: 3000 })).toBeLessThanOrEqual(3000)
+    expect(backoff({ attempt: 4, maxTimeout: 3000 })).toBeLessThanOrEqual(3000)
+  })
+
+  it('accepts a growth factor', () => {
+    const f2 = backoff({ attempt: 2, factor: 2 })
+    const f3 = backoff({ attempt: 2, factor: 3 })
+
+    expect(f3).toBeGreaterThan(f2)
+  })
+})

package/packages/browser/src/lib/priority-queue/__tests__/index.test.ts

@@ -0,0 +1,158 @@
+import { PriorityQueue } from '..'
+
+type Item = {
+  id: string
+}
+
+describe('RetryQueue', () => {
+  it('accepts new work', () => {
+    const queue = new PriorityQueue<Item>(10, [])
+    queue.push({ id: 'abc' }, { id: 'cde' })
+    expect(queue.length).toBe(2)
+  })
+
+  it('pops items off the queue', () => {
+    const queue = new PriorityQueue<Item>(10, [])
+    queue.push({ id: 'abc' }, { id: 'cde' })
+
+    expect(queue.pop()).toEqual({ id: 'abc' })
+    expect(queue.length).toBe(1)
+
+    expect(queue.pop()).toEqual({ id: 'cde' })
+    expect(queue.length).toBe(0)
+  })
+
+  it('deprioritizes repeated items', () => {
+    const queue = new PriorityQueue<Item>(10, [])
+    queue.push({ id: 'abc' })
+    queue.push({ id: 'abc' })
+
+    queue.push({ id: 'cde' })
+
+    // deprioritizes 'abc' because it was seen twice
+    expect(queue.pop()).toEqual({ id: 'cde' })
+  })
+
+  it('deprioritizes repeated items even though they have been popped before', () => {
+    const queue = new PriorityQueue<Item>(10, [])
+    queue.push({ id: 'abc' })
+    queue.pop()
+
+    queue.push({ id: 'abc' })
+    queue.push({ id: 'cde' })
+
+    // a queue does not forget
+    expect(queue.pop()).toEqual({ id: 'cde' })
+  })
+
+  it('stops accepting an item after attempts have been exausted', () => {
+    const queue = new PriorityQueue<Item>(3, [])
+    queue.push({ id: 'abc' })
+    expect(queue.length).toBe(1)
+    queue.pop()
+
+    queue.push({ id: 'abc' })
+    expect(queue.length).toBe(1)
+    queue.pop()
+
+    queue.push({ id: 'abc' })
+    expect(queue.length).toBe(1)
+    queue.pop()
+
+    queue.push({ id: 'abc' })
+    // does not accept it anymore
+    expect(queue.length).toBe(0)
+  })
+})
+
+describe('backoffs', () => {
+  afterEach(() => {
+    jest.clearAllTimers()
+  })
+
+  it('accepts new work', () => {
+    const queue = new PriorityQueue<Item>(10, [])
+
+    queue.pushWithBackoff({ id: 'abc' })
+    queue.pushWithBackoff({ id: 'cde' })
+
+    expect(queue.length).toBe(2)
+    expect(queue.todo).toBe(2)
+  })
+
+  it('ignores when item has not been worked on', () => {
+    const queue = new PriorityQueue<Item>(10, [])
+
+    expect(queue.pushWithBackoff({ id: 'abc' })).toBe(true)
+    expect(queue.pushWithBackoff({ id: 'abc' })).toBe(false)
+    expect(queue.length).toBe(1)
+    expect(queue.todo).toBe(1)
+  })
+
+  it('schedules as future work when item returns to the queue', () => {
+    const queue = new PriorityQueue<Item>(10, [])
+
+    queue.pushWithBackoff({ id: 'abc' })
+    queue.pop()
+
+    // accepted work
+    expect(queue.pushWithBackoff({ id: 'abc' })).toBe(true)
+
+    // not in the main queue yet
+    expect(queue.length).toBe(0)
+
+    // present in future work
+    expect(queue.todo).toBe(1)
+    expect(queue.includes({ id: 'abc' })).toBe(true)
+  })
+
+  it('schedules as future work for later', () => {
+    jest.useFakeTimers()
+    const spy = jest.spyOn(global, 'setTimeout')
+
+    const queue = new PriorityQueue<Item>(10, [])
+
+    queue.pushWithBackoff({ id: 'abc' })
+    expect(spy).not.toHaveBeenCalled()
+
+    queue.pop()
+
+    queue.pushWithBackoff({ id: 'abc' })
+    expect(spy).toHaveBeenCalled()
+
+    const delay = spy.mock.calls[0][1]
+    expect(delay).toBeGreaterThan(1000)
+  })
+
+  it('increases the delay as work gets requeued', () => {
+    jest.useFakeTimers()
+    const spy = jest.spyOn(global, 'setTimeout')
+
+    const queue = new PriorityQueue<Item>(10, [])
+
+    queue.pushWithBackoff({ id: 'abc' })
+    jest.advanceTimersToNextTimer()
+    queue.pop()
+
+    queue.pushWithBackoff({ id: 'abc' })
+    jest.advanceTimersToNextTimer()
+    queue.pop()
+
+    queue.pushWithBackoff({ id: 'abc' })
+    jest.advanceTimersToNextTimer()
+    queue.pop()
+
+    queue.pushWithBackoff({ id: 'abc' })
+    jest.advanceTimersToNextTimer()
+    queue.pop()
+
+    const firstDelay = spy.mock.calls[0][1]
+    expect(firstDelay).toBeGreaterThan(1000)
+
+    const secondDelay = spy.mock.calls[1][1]
+    expect(secondDelay).toBeGreaterThan(2000)
+
+    const thirdDelay = spy.mock.calls[2][1]
+    expect(thirdDelay).toBeGreaterThan(3000)
+  })
+})