utneque 1.0.0

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

@@ -0,0 +1,228 @@
+import { Context } from '../../../core/context'
+import { PersistedPriorityQueue } from '../persisted'
+
+describe('Persisted Priority Queue', () => {
+  beforeEach(() => {
+    window.localStorage.clear()
+  })
+
+  const key = 'event-queue'
+
+  it('a queue remembers', () => {
+    const ctx = new Context(
+      {
+        type: 'track',
+        properties: {
+          banana: '🍌',
+        },
+      },
+      'abc'
+    )
+
+    window.localStorage.setItem(
+      `persisted-queue:v1:${key}:items`,
+      JSON.stringify([ctx])
+    )
+    window.localStorage.setItem(
+      `persisted-queue:v1:${key}:seen`,
+      JSON.stringify({ abc: 2 })
+    )
+
+    const queue = new PersistedPriorityQueue(3, key)
+    const included = queue.includes(ctx)
+
+    expect(included).toBe(true)
+    expect(queue.todo).toBe(1)
+    expect(queue.getAttempts(ctx)).toBe(2)
+  })
+
+  it('a queue always pays their debts', () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let onUnload: any = jest.fn()
+
+    jest
+      .spyOn(window, 'addEventListener')
+      .mockImplementation((evt, handler) => {
+        if (evt === 'pagehide') {
+          onUnload = handler
+        }
+      })
+
+    const ctx = new Context(
+      {
+        type: 'track',
+        properties: {
+          banana: '🍌',
+        },
+      },
+      'abc'
+    )
+
+    const queue = new PersistedPriorityQueue(3, key)
+    queue.push(ctx)
+
+    onUnload()
+
+    const items = JSON.parse(
+      localStorage.getItem(`persisted-queue:v1:${key}:items`) ?? ''
+    )
+    const seen = JSON.parse(
+      localStorage.getItem(`persisted-queue:v1:${key}:seen`) ?? ''
+    )
+
+    expect(items[0]).toEqual(ctx.toJSON())
+    expect(seen).toEqual({ abc: 1 })
+  })
+
+  it('a queue has a name', () => {
+    const ctx = new Context(
+      {
+        type: 'track',
+        properties: {
+          banana: '🍌',
+        },
+      },
+      'abc'
+    )
+    window.localStorage.setItem(
+      `persisted-queue:v1:different-key:items`,
+      JSON.stringify([ctx])
+    )
+
+    const queue = new PersistedPriorityQueue(3, key)
+    expect(queue.todo).toBe(0)
+
+    const correctQueue = new PersistedPriorityQueue(3, 'different-key')
+    expect(correctQueue.todo).toBe(1)
+  })
+
+  describe('merging', () => {
+    it('merges queue items with existing data', () => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let onUnload: any = jest.fn()
+
+      jest
+        .spyOn(window, 'addEventListener')
+        .mockImplementation((evt, handler) => {
+          if (evt === 'pagehide') {
+            onUnload = handler
+          }
+        })
+
+      const ctx = new Context(
+        {
+          type: 'track',
+          properties: {
+            banana: '🍌',
+          },
+        },
+        'abc'
+      )
+
+      window.localStorage.setItem(
+        `persisted-queue:v1:${key}:items`,
+        JSON.stringify([ctx])
+      )
+
+      const ctxFromDifferentTab = new Context(
+        {
+          type: 'page',
+          properties: {
+            banana: '🍌',
+          },
+        },
+        'cde'
+      )
+
+      const queue = new PersistedPriorityQueue(3, key)
+
+      expect(queue.includes(ctx)).toBe(true)
+      expect(queue.includes(ctxFromDifferentTab)).not.toBe(true)
+
+      // another tab sets these two events again
+      window.localStorage.setItem(
+        `persisted-queue:v1:${key}:items`,
+        JSON.stringify([ctx, ctxFromDifferentTab])
+      )
+
+      const newCtx = new Context(
+        {
+          type: 'identify',
+        },
+        'id'
+      )
+
+      expect(queue.push(newCtx)).toEqual([true])
+
+      // page is unloaded
+      onUnload()
+
+      const persisted = JSON.parse(
+        window.localStorage.getItem(`persisted-queue:v1:${key}:items`) ?? ''
+      ) as unknown[]
+
+      expect(persisted.length).toBe(3)
+      expect(persisted).toContainEqual(ctx.toJSON())
+      expect(persisted).toContainEqual(ctxFromDifferentTab.toJSON())
+      expect(persisted).toContainEqual(newCtx.toJSON())
+    })
+  })
+
+  describe('concurrency', () => {
+    it('only one tab unloads items from localstorage', () => {
+      const ctx = new Context(
+        {
+          type: 'track',
+          properties: {
+            banana: '🍌',
+          },
+        },
+        'abc'
+      )
+
+      window.localStorage.setItem(
+        `persisted-queue:v1:${key}:items`,
+        JSON.stringify([ctx])
+      )
+
+      const firstTabQueue = new PersistedPriorityQueue(3, key)
+      const secondTabQueue = new PersistedPriorityQueue(3, key)
+
+      // first tab gets a hold of it
+      expect(firstTabQueue.includes(ctx)).toBe(true)
+
+      // it's gone by the time the second tab comes in
+      expect(secondTabQueue.includes(ctx)).not.toBe(true)
+    })
+
+    it('does not allow multiple tabs to override each other when closed', () => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const onUnloadFunctions: any[] = []
+
+      jest
+        .spyOn(window, 'addEventListener')
+        .mockImplementation((evt, handler) => {
+          if (evt === 'pagehide') {
+            onUnloadFunctions.push(handler)
+          }
+        })
+
+      const firstTabQueue = new PersistedPriorityQueue(3, key)
+      const secondTabQueue = new PersistedPriorityQueue(3, key)
+
+      const firstTabItem = new Context({ type: 'track' }, 'firstTab')
+      const secondTabItem = new Context({ type: 'page' }, 'secondTab')
+
+      firstTabQueue.push(firstTabItem)
+      secondTabQueue.push(secondTabItem)
+
+      onUnloadFunctions[1]()
+      onUnloadFunctions[0]()
+
+      const stored = JSON.parse(
+        window.localStorage.getItem(`persisted-queue:v1:${key}:items`) ?? ''
+      )
+      expect(stored.length).toBe(2)
+    })
+  })
+})

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

@@ -0,0 +1,24 @@
+type BackoffParams = {
+  /** The number of milliseconds before starting the first retry. Default is 500 */
+  minTimeout?: number
+
+  /** The maximum number of milliseconds between two retries. Default is Infinity */
+  maxTimeout?: number
+
+  /** The exponential factor to use. Default is 2. */
+  factor?: number
+
+  /** The current attempt */
+  attempt: number
+}
+
+export function backoff(params: BackoffParams): number {
+  const random = Math.random() + 1
+  const {
+    minTimeout = 500,
+    factor = 2,
+    attempt,
+    maxTimeout = Infinity,
+  } = params
+  return Math.min(random * minTimeout * Math.pow(factor, attempt), maxTimeout)
+}

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

@@ -0,0 +1,6 @@
+import {
+  PriorityQueue,
+  ON_REMOVE_FROM_FUTURE,
+} from '@ht-sdks/events-sdk-js-core'
+
+export { PriorityQueue, ON_REMOVE_FROM_FUTURE }

package/packages/browser/src/lib/priority-queue/persisted.ts

@@ -0,0 +1,127 @@
+import { PriorityQueue } from '.'
+import { Context, SerializedContext } from '../../core/context'
+import { isBrowser } from '../../core/environment'
+
+let loc:
+  | Storage
+  | { getItem: () => void; setItem: () => void; removeItem: () => void } = {
+  getItem() {},
+  setItem() {},
+  removeItem() {},
+}
+
+try {
+  loc = isBrowser() && window.localStorage ? window.localStorage : loc
+} catch (err) {
+  console.warn('Unable to access localStorage', err)
+}
+
+function persisted(key: string): Context[] {
+  const items = loc.getItem(key)
+  return (items ? JSON.parse(items) : []).map(
+    (p: SerializedContext) => new Context(p.event, p.id)
+  )
+}
+
+function persistItems(key: string, items: Context[]): void {
+  const existing = persisted(key)
+  const all = [...items, ...existing]
+
+  const merged = all.reduce((acc, item) => {
+    return {
+      ...acc,
+      [item.id]: item,
+    }
+  }, {} as Record<string, Context>)
+
+  loc.setItem(key, JSON.stringify(Object.values(merged)))
+}
+
+function seen(key: string): Record<string, number> {
+  const stored = loc.getItem(key)
+  return stored ? JSON.parse(stored) : {}
+}
+
+function persistSeen(key: string, memory: Record<string, number>): void {
+  const stored = seen(key)
+
+  loc.setItem(
+    key,
+    JSON.stringify({
+      ...stored,
+      ...memory,
+    })
+  )
+}
+
+function remove(key: string): void {
+  loc.removeItem(key)
+}
+
+const now = (): number => new Date().getTime()
+
+function mutex(key: string, onUnlock: Function, attempt = 0): void {
+  const lockTimeout = 50
+  const lockKey = `persisted-queue:v1:${key}:lock`
+
+  const expired = (lock: number): boolean => new Date().getTime() > lock
+  const rawLock = loc.getItem(lockKey)
+  const lock = rawLock ? (JSON.parse(rawLock) as number) : null
+
+  const allowed = lock === null || expired(lock)
+  if (allowed) {
+    loc.setItem(lockKey, JSON.stringify(now() + lockTimeout))
+    onUnlock()
+    loc.removeItem(lockKey)
+    return
+  }
+
+  if (!allowed && attempt < 3) {
+    setTimeout(() => {
+      mutex(key, onUnlock, attempt + 1)
+    }, lockTimeout)
+  } else {
+    console.error('Unable to retrieve lock')
+  }
+}
+
+export class PersistedPriorityQueue extends PriorityQueue<Context> {
+  constructor(maxAttempts: number, key: string) {
+    super(maxAttempts, [])
+
+    const itemsKey = `persisted-queue:v1:${key}:items`
+    const seenKey = `persisted-queue:v1:${key}:seen`
+
+    let saved: Context[] = []
+    let lastSeen: Record<string, number> = {}
+
+    mutex(key, () => {
+      try {
+        saved = persisted(itemsKey)
+        lastSeen = seen(seenKey)
+        remove(itemsKey)
+        remove(seenKey)
+
+        this.queue = [...saved, ...this.queue]
+        this.seen = { ...lastSeen, ...this.seen }
+      } catch (err) {
+        console.error(err)
+      }
+    })
+
+    window.addEventListener('pagehide', () => {
+      // we deliberately want to use the less powerful 'pagehide' API to only persist on events where the analytics instance gets destroyed, and not on tab away.
+      if (this.todo > 0) {
+        const items = [...this.queue, ...this.future]
+        try {
+          mutex(key, () => {
+            persistItems(itemsKey, items)
+            persistSeen(seenKey, this.seen)
+          })
+        } catch (err) {
+          console.error(err)
+        }
+      }
+    })
+  }
+}

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

@@ -0,0 +1,4 @@
+export const sleep = (time: number): Promise<void> =>
+  new Promise((resolve) => {
+    setTimeout(resolve, time)
+  })

package/packages/browser/src/lib/to-facade.ts

@@ -0,0 +1,53 @@
+import {
+  Alias,
+  Facade,
+  Group,
+  Identify,
+  Options,
+  Page,
+  Screen,
+  Track,
+} from '@segment/facade'
+import { HightouchEvent } from '../core/events'
+
+export type SegmentFacade = Facade<HightouchEvent> & {
+  obj: HightouchEvent
+}
+
+export function toFacade(
+  evt: HightouchEvent,
+  options?: Options
+): SegmentFacade {
+  let fcd = new Facade(evt, options)
+
+  if (evt.type === 'track') {
+    fcd = new Track(evt, options)
+  }
+
+  if (evt.type === 'identify') {
+    fcd = new Identify(evt, options)
+  }
+
+  if (evt.type === 'page') {
+    fcd = new Page(evt, options)
+  }
+
+  if (evt.type === 'alias') {
+    fcd = new Alias(evt, options)
+  }
+
+  if (evt.type === 'group') {
+    fcd = new Group(evt, options)
+  }
+
+  if (evt.type === 'screen') {
+    fcd = new Screen(evt, options)
+  }
+
+  Object.defineProperty(fcd, 'obj', {
+    value: evt,
+    writable: true,
+  })
+
+  return fcd as SegmentFacade
+}

package/packages/browser/src/lib/version-type.ts

@@ -0,0 +1,10 @@
+// Default value will be updated to 'web' in `bundle-umd.ts` for web build.
+let _version: 'web' | 'npm' = 'npm'
+
+export function setVersionType(version: typeof _version) {
+  _version = version
+}
+
+export function getVersionType(): typeof _version {
+  return _version
+}

package/packages/browser/src/node/__tests__/node-integration.test.ts

@@ -0,0 +1,19 @@
+import { AnalyticsNode } from '../..'
+
+const writeKey = 'foo'
+
+describe('Initialization', () => {
+  it('loads analytics-node-next plugin', async () => {
+    const [analytics] = await AnalyticsNode.load({
+      writeKey,
+    })
+
+    expect(analytics.queue.plugins.length).toBe(2)
+
+    const ajsNodeXt = analytics.queue.plugins.find(
+      (xt) => xt.name === 'analytics-node-next'
+    )
+    expect(ajsNodeXt).toBeDefined()
+    expect(ajsNodeXt?.isLoaded()).toBeTruthy()
+  })
+})

package/packages/browser/src/node/index.ts

@@ -0,0 +1,36 @@
+import { Analytics } from '../core/analytics'
+import { Context } from '../core/context'
+import { validation } from '../plugins/validation'
+import { analyticsNode } from '../plugins/analytics-node'
+import { Plugin } from '../core/plugin'
+import { EventQueue } from '../core/queue/event-queue'
+import { PriorityQueue } from '../lib/priority-queue'
+
+export class AnalyticsNode {
+  static async load(settings: {
+    writeKey: string
+  }): Promise<[Analytics, Context]> {
+    const cookieOptions = {
+      persist: false,
+    }
+
+    const queue = new EventQueue(new PriorityQueue(3, []))
+    const options = { user: cookieOptions, group: cookieOptions }
+    const analytics = new Analytics(settings, options, queue)
+
+    const nodeSettings = {
+      writeKey: settings.writeKey,
+      name: 'analytics-node-next',
+      type: 'after' as Plugin['type'],
+      version: 'latest',
+    }
+
+    const ctx = await analytics.register(
+      validation,
+      analyticsNode(nodeSettings)
+    )
+    analytics.emit('initialize', settings, cookieOptions ?? {})
+
+    return [analytics, ctx]
+  }
+}

package/packages/browser/src/node/node.browser.ts

@@ -0,0 +1,7 @@
+export class AnalyticsNode {
+  static load(): Promise<never> {
+    return Promise.reject(
+      new Error('AnalyticsNode is not available in browsers.')
+    )
+  }
+}