utneque 1.0.0

package/packages/core/LICENSE.MD

@@ -0,0 +1,45 @@
+The MIT License (MIT)
+
+Copyright © 2023 Hightouch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+---
+
+The MIT License (MIT)
+
+Copyright © 2021 Segment
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/packages/core/README.md

@@ -0,0 +1,3 @@
+# @ht-sdks/events-sdk-js-core
+
+This package represents core 'shared' functionality that is shared by analytics packages. This is not designed to be used directly, but internal to the node and browser packages.

package/packages/core/jest.config.js

@@ -0,0 +1,5 @@
+const { createJestTSConfig } = require('@internal/config')
+
+module.exports = createJestTSConfig(__dirname, {
+  projects: ['<rootDir>'],
+})

package/packages/core/jest.setup.js

@@ -0,0 +1,10 @@
+const { TextEncoder, TextDecoder } = require('util')
+const { setImmediate } = require('timers')
+
+// fix: "ReferenceError: TextEncoder is not defined" after upgrading JSDOM
+global.TextEncoder = TextEncoder
+global.TextDecoder = TextDecoder
+// fix: jsdom uses setImmediate under the hood for preflight XHR requests,
+// and jest removed setImmediate, so we need to provide it to prevent console
+// logging ReferenceErrors made by integration tests that call Amplitude.
+global.setImmediate = setImmediate

package/packages/core/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ht-sdks/events-sdk-js-core",
+  "version": "1.1.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ht-sdks/events-sdk-js-mono",
+    "directory": "packages/core"
+  },
+  "license": "MIT",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist/",
+    "src/",
+    "!**/__tests__/**",
+    "!*.tsbuildinfo"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    ".": "yarn run -T turbo run --filter=@ht-sdks/events-sdk-js-core",
+    "test": "yarn jest",
+    "lint": "yarn concurrently 'yarn:eslint .' 'yarn:tsc --noEmit'",
+    "build": "yarn concurrently 'yarn:build:*'",
+    "build:esm": "yarn tsc -p tsconfig.build.json",
+    "build:cjs": "yarn tsc -p tsconfig.build.json --outDir ./dist/cjs --module commonjs",
+    "watch": "yarn build:esm --watch",
+    "watch:test": "yarn test --watch",
+    "tsc": "yarn run -T tsc",
+    "eslint": "yarn run -T eslint",
+    "concurrently": "yarn run -T concurrently",
+    "jest": "yarn run -T jest"
+  },
+  "packageManager": "yarn@3.4.1",
+  "dependencies": {
+    "@lukeed/uuid": "^2.0.0",
+    "dset": "^3.1.2",
+    "tslib": "^2.4.1"
+  }
+}

package/packages/core/src/analytics/__tests__/dispatch.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Properly type mocked functions to make it easy to do assertions
+ * for example, myModule.mock.calls[0] will have the typed parameters instead of any.
+ *
+ * TODO: share with rest of project
+ */
+type JestMockedFn<Fn> = Fn extends (...args: infer Args) => infer ReturnT
+  ? jest.Mock<ReturnT, Args>
+  : never
+
+const invokeCallback: JestMockedFn<
+  typeof import('../../callback')['invokeCallback']
+> = jest.fn()
+jest.mock('../../callback', () => ({
+  invokeCallback: invokeCallback,
+}))
+
+import { CoreEventQueue } from '../../queue/event-queue'
+import { Emitter } from '../../emitter'
+import { dispatch, getDelay } from '../dispatch'
+import { CoreContext } from '../../context'
+import { TestCtx, TestEventQueue } from '../../../test-helpers'
+
+let emitter!: Emitter
+let queue!: CoreEventQueue<CoreContext>
+const dispatchSingleSpy = jest.spyOn(CoreEventQueue.prototype, 'dispatchSingle')
+const dispatchSpy = jest.spyOn(CoreEventQueue.prototype, 'dispatch')
+const screenCtxMatcher = expect.objectContaining<Partial<CoreContext>>({
+  event: { type: 'screen' },
+})
+
+const screenCtx = new TestCtx({ type: 'screen' })
+describe('Dispatch', () => {
+  beforeEach(() => {
+    jest.resetAllMocks()
+    dispatchSingleSpy.mockImplementationOnce((ctx) => Promise.resolve(ctx))
+    invokeCallback.mockImplementationOnce((ctx) => Promise.resolve(ctx))
+    dispatchSpy.mockImplementationOnce((ctx) => Promise.resolve(ctx))
+    queue = new TestEventQueue()
+    queue.isEmpty = jest.fn().mockReturnValue(false)
+    emitter = new Emitter()
+  })
+
+  it('should call dispatchSingle correctly if queue is empty', async () => {
+    queue.isEmpty = jest.fn().mockReturnValue(true)
+    await dispatch(screenCtx, queue, emitter)
+    expect(dispatchSingleSpy).toBeCalledWith(screenCtxMatcher)
+    expect(dispatchSpy).not.toBeCalled()
+  })
+
+  it('should call dispatch correctly if queue has items', async () => {
+    await dispatch(screenCtx, queue, emitter)
+    expect(dispatchSpy).toBeCalledWith(screenCtxMatcher)
+    expect(dispatchSingleSpy).not.toBeCalled()
+  })
+
+  it('should only call invokeCallback if callback is passed', async () => {
+    await dispatch(screenCtx, queue, emitter)
+    expect(invokeCallback).not.toBeCalled()
+
+    const cb = jest.fn()
+    await dispatch(screenCtx, queue, emitter, {
+      callback: cb,
+    })
+    expect(invokeCallback).toBeCalledTimes(1)
+  })
+  it('should call invokeCallback with correct args', async () => {
+    const cb = jest.fn()
+    await dispatch(screenCtx, queue, emitter, {
+      callback: cb,
+    })
+    expect(dispatchSpy).toBeCalledWith(screenCtxMatcher)
+    expect(invokeCallback).toBeCalledTimes(1)
+    const [ctx, _cb] = invokeCallback.mock.calls[0]
+    expect(ctx).toEqual(screenCtxMatcher)
+    expect(_cb).toBe(cb)
+  })
+})
+
+describe(getDelay, () => {
+  it('should calculate the amount of time to delay before invoking the callback', () => {
+    const aShortTimeAgo = Date.now() - 200
+    const timeout = 5000
+    const result = getDelay(aShortTimeAgo, timeout)
+    expect(result).toBeLessThanOrEqual(4800)
+    expect(result).toBeGreaterThanOrEqual(4790)
+  })
+
+  it('should have a sensible default', () => {
+    const aShortTimeAgo = Date.now() - 200
+    const result = getDelay(aShortTimeAgo)
+    expect(result).toBeLessThanOrEqual(100)
+    expect(result).toBeGreaterThanOrEqual(90)
+  })
+})

package/packages/core/src/analytics/dispatch.ts

@@ -0,0 +1,58 @@
+import { CoreContext } from '../context'
+import { Callback } from '../events/interfaces'
+import { CoreEventQueue } from '../queue/event-queue'
+import { invokeCallback } from '../callback'
+import { Emitter } from '../emitter'
+
+export type DispatchOptions<Ctx extends CoreContext = CoreContext> = {
+  timeout?: number
+  debug?: boolean
+  callback?: Callback<Ctx>
+}
+
+/* The amount of time in ms to wait before invoking the callback. */
+export const getDelay = (startTimeInEpochMS: number, timeoutInMS?: number) => {
+  const elapsedTime = Date.now() - startTimeInEpochMS
+  // increasing the timeout increases the delay by almost the same amount -- this is weird legacy behavior.
+  return Math.max((timeoutInMS ?? 300) - elapsedTime, 0)
+}
+/**
+ * Push an event into the dispatch queue and invoke any callbacks.
+ *
+ * @param event - Hightouch event to enqueue.
+ * @param queue - Queue to dispatch against.
+ * @param emitter - This is typically an instance of "Analytics" -- used for metrics / progress information.
+ * @param options
+ */
+export async function dispatch<
+  Ctx extends CoreContext,
+  EQ extends CoreEventQueue<Ctx>
+>(
+  ctx: Ctx,
+  queue: EQ,
+  emitter: Emitter,
+  options?: DispatchOptions<Ctx>
+): Promise<Ctx> {
+  emitter.emit('dispatch_start', ctx)
+
+  const startTime = Date.now()
+  let dispatched: Ctx
+  if (queue.isEmpty()) {
+    dispatched = await queue.dispatchSingle(ctx)
+  } else {
+    dispatched = await queue.dispatch(ctx)
+  }
+
+  if (options?.callback) {
+    dispatched = await invokeCallback(
+      dispatched,
+      options.callback,
+      getDelay(startTime, options.timeout)
+    )
+  }
+  if (options?.debug) {
+    dispatched.flush()
+  }
+
+  return dispatched
+}

package/packages/core/src/analytics/index.ts

@@ -0,0 +1,11 @@
+export interface CoreAnalytics {
+  track(...args: unknown[]): unknown
+  page(...args: unknown[]): unknown
+  identify(...args: unknown[]): unknown
+  group(...args: unknown[]): unknown
+  alias(...args: unknown[]): unknown
+  screen(...args: unknown[]): unknown
+  register(...plugins: unknown[]): Promise<unknown>
+  deregister(...plugins: unknown[]): Promise<unknown>
+  readonly VERSION: string
+}

package/packages/core/src/callback/__tests__/index.test.ts

@@ -0,0 +1,85 @@
+import { invokeCallback } from '..'
+import { TestCtx } from '../../../test-helpers'
+
+describe(invokeCallback, () => {
+  afterEach(() => {
+    jest.useRealTimers()
+  })
+
+  it('invokes a callback asynchronously', async () => {
+    const ctx = new TestCtx({
+      type: 'track',
+    })
+
+    const fn = jest.fn()
+    const returned = await invokeCallback(ctx, fn, 0)
+
+    expect(fn).toHaveBeenCalledWith(ctx)
+    expect(returned).toBe(ctx)
+  })
+
+  // Fixes GitHub issue: https://github.com/segmentio/analytics-next/issues/409
+  // A.JS classic waited for the timeout/delay before invoking callback,
+  // so keep same behavior in A.JS next.
+  it('calls the callback after a delay', async () => {
+    const ctx = new TestCtx({
+      type: 'track',
+    })
+
+    const fn = jest.fn()
+    const delay = 100
+
+    const startTime = Date.now()
+    const returned = await invokeCallback(ctx, fn, delay)
+    const endTime = Date.now()
+
+    expect(fn).toHaveBeenCalled()
+    expect(endTime - startTime).toBeGreaterThanOrEqual(delay - 1)
+    expect(returned).toBe(ctx)
+  })
+
+  it('ignores the callback if it takes too long to resolve', async () => {
+    const ctx = new TestCtx({
+      type: 'track',
+    })
+
+    const slow = (_ctx: TestCtx): Promise<void> => {
+      return new Promise((resolve) => {
+        setTimeout(resolve, 1100)
+      })
+    }
+
+    const returned = await invokeCallback(ctx, slow, 0)
+    expect(returned).toBe(ctx)
+
+    const logs = returned.logs()
+    expect(logs[0].extras).toMatchInlineSnapshot(`
+      Object {
+        "error": [Error: Promise timed out],
+      }
+    `)
+
+    expect(logs[0].level).toEqual('warn')
+  })
+
+  it('does not crash if the callback crashes', async () => {
+    const ctx = new TestCtx({
+      type: 'track',
+    })
+
+    const boo = (_ctx: TestCtx): Promise<void> => {
+      throw new Error('👻 boo!')
+    }
+
+    const returned = await invokeCallback(ctx, boo, 0)
+    expect(returned).toBe(ctx)
+
+    const logs = returned.logs()
+    expect(logs[0].extras).toMatchInlineSnapshot(`
+      Object {
+        "error": [Error: 👻 boo!],
+      }
+    `)
+    expect(logs[0].level).toEqual('warn')
+  })
+})

package/packages/core/src/callback/index.ts

@@ -0,0 +1,51 @@
+import { CoreContext } from '../context'
+import type { Callback } from '../events'
+
+export function pTimeout<T>(promise: Promise<T>, timeout: number): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timeoutId = setTimeout(() => {
+      reject(Error('Promise timed out'))
+    }, timeout)
+
+    promise
+      .then((val) => {
+        clearTimeout(timeoutId)
+        return resolve(val)
+      })
+      .catch(reject)
+  })
+}
+
+export function sleep(timeoutInMs: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, timeoutInMs))
+}
+
+/**
+ * @param ctx
+ * @param callback - the function to invoke
+ * @param delay - aka "timeout". The amount of time in ms to wait before invoking the callback.
+ */
+export function invokeCallback<Ctx extends CoreContext>(
+  ctx: Ctx,
+  callback: Callback<Ctx>,
+  delay: number
+): Promise<Ctx> {
+  const cb = () => {
+    try {
+      return Promise.resolve(callback(ctx))
+    } catch (err) {
+      return Promise.reject(err)
+    }
+  }
+
+  return (
+    sleep(delay)
+      // pTimeout ensures that the callback can't cause the context to hang
+      .then(() => pTimeout(cb(), 1000))
+      .catch((err) => {
+        ctx?.log('warn', 'Callback Error', { error: err })
+        ctx?.stats.increment('callback_error')
+      })
+      .then(() => ctx)
+  )
+}

package/packages/core/src/context/index.ts

@@ -0,0 +1,123 @@
+import { CoreHightouchEvent } from '../events/interfaces'
+
+import { v4 as uuid } from '@lukeed/uuid'
+import { dset } from 'dset'
+import { CoreLogger, LogLevel, LogMessage } from '../logger'
+import { CoreStats, CoreMetric, NullStats } from '../stats'
+
+export interface SerializedContext {
+  id: string
+  event: CoreHightouchEvent
+  logs: LogMessage[]
+  metrics?: CoreMetric[]
+}
+
+export interface ContextFailedDelivery {
+  reason: unknown
+}
+
+export interface CancelationOptions {
+  retry?: boolean
+  reason?: string
+  type?: string
+}
+
+export class ContextCancelation {
+  retry: boolean
+  type: string
+  reason?: string
+
+  constructor(options: CancelationOptions) {
+    this.retry = options.retry ?? true
+    this.type = options.type ?? 'plugin Error'
+    this.reason = options.reason ?? ''
+  }
+}
+
+export abstract class CoreContext<
+  Event extends CoreHightouchEvent = CoreHightouchEvent
+> {
+  event: Event
+  logger: CoreLogger
+  stats: CoreStats
+  attempts = 0
+
+  private _failedDelivery?: ContextFailedDelivery
+  private _id: string
+
+  constructor(
+    event: Event,
+    id = uuid(),
+    stats: CoreStats = new NullStats(),
+    logger = new CoreLogger()
+  ) {
+    this.event = event
+    this._id = id
+    this.logger = logger
+    this.stats = stats
+  }
+
+  static system(): void {
+    // This should be overridden by the subclass to return an instance of the subclass.
+  }
+
+  isSame(other: CoreContext): boolean {
+    return other.id === this.id
+  }
+
+  cancel(error?: Error | ContextCancelation): never {
+    if (error) {
+      throw error
+    }
+
+    throw new ContextCancelation({ reason: 'Context Cancel' })
+  }
+
+  log(level: LogLevel, message: string, extras?: object): void {
+    this.logger.log(level, message, extras)
+  }
+
+  get id(): string {
+    return this._id
+  }
+
+  updateEvent(path: string, val: unknown): Event {
+    // Don't allow integrations that are set to false to be overwritten with integration settings.
+    if (path.split('.')[0] === 'integrations') {
+      const integrationName = path.split('.')[1]
+
+      if (this.event.integrations?.[integrationName] === false) {
+        return this.event
+      }
+    }
+
+    dset(this.event, path, val)
+    return this.event
+  }
+
+  failedDelivery(): ContextFailedDelivery | undefined {
+    return this._failedDelivery
+  }
+
+  setFailedDelivery(options: ContextFailedDelivery) {
+    this._failedDelivery = options
+  }
+
+  logs(): LogMessage[] {
+    return this.logger.logs
+  }
+
+  flush(): void {
+    this.logger.flush()
+    this.stats.flush()
+  }
+
+  toJSON(): SerializedContext {
+    return {
+      id: this._id,
+      event: this.event,
+      logs: this.logger.logs,
+      metrics: this.stats.metrics,
+    }
+  }
+}

package/packages/core/src/emitter/__tests__/emitter.test.ts

@@ -0,0 +1,74 @@
+import { Emitter } from '../'
+
+describe(Emitter, () => {
+  it('emits events', () => {
+    const em = new Emitter()
+
+    const fn = jest.fn()
+    em.on('test', fn)
+    em.emit('test', 'banana')
+
+    expect(fn).toHaveBeenCalledWith('banana')
+  })
+
+  it('allows for subscribing to events', () => {
+    const em = new Emitter()
+
+    const fn = jest.fn()
+    const anotherFn = jest.fn()
+
+    em.on('test', fn)
+    em.on('test', anotherFn)
+
+    em.emit('test', 'banana', 'phone')
+
+    expect(fn).toHaveBeenCalledWith('banana', 'phone')
+    expect(anotherFn).toHaveBeenCalledWith('banana', 'phone')
+  })
+
+  it('allows for subscribing to the same event multiple times', () => {
+    const em = new Emitter()
+
+    const fn = jest.fn()
+
+    em.on('test', fn)
+    em.emit('test', 'banana')
+    em.emit('test', 'phone')
+
+    expect(fn).toHaveBeenCalledTimes(2)
+    expect(fn).toHaveBeenCalledWith('banana')
+    expect(fn).toHaveBeenCalledWith('phone')
+  })
+
+  it('allows for subscribers to subscribe only once', () => {
+    const em = new Emitter()
+
+    const fn = jest.fn()
+    em.once('test', fn)
+
+    // 2 emits
+    em.emit('test', 'banana')
+    em.emit('test', 'phone')
+
+    expect(fn).toHaveBeenCalledTimes(1)
+    expect(fn).toHaveBeenCalledWith('banana')
+  })
+
+  it('allows for unsubscribing', () => {
+    const em = new Emitter()
+
+    const fn = jest.fn()
+    em.on('test', fn)
+
+    // 2 emits
+    em.emit('test', 'banana')
+    em.emit('test', 'phone')
+
+    em.off('test', fn)
+
+    // 3rd emit
+    em.emit('test', 'phone')
+
+    expect(fn).toHaveBeenCalledTimes(2)
+  })
+})

package/packages/core/src/emitter/index.ts

@@ -0,0 +1,65 @@
+type EventName = string
+type EventFnArgs = any[]
+type EmitterContract = Record<EventName, EventFnArgs>
+
+/**
+ * Event Emitter that takes the expected contract as a generic
+ * @example
+ * ```ts
+ *  type Contract = {
+ *    delivery_success: [DeliverySuccessResponse, Metrics],
+ *    delivery_failure: [DeliveryError]
+ * }
+ *  new Emitter<Contract>()
+ *  .on('delivery_success', (res, metrics) => ...)
+ *  .on('delivery_failure', (err) => ...)
+ * ```
+ */
+export class Emitter<Contract extends EmitterContract = EmitterContract> {
+  private callbacks: Partial<Contract> = {}
+  on<EventName extends keyof Contract>(
+    event: EventName,
+    callback: (...args: Contract[EventName]) => void
+  ): this {
+    if (!this.callbacks[event]) {
+      this.callbacks[event] = [callback] as Contract[EventName]
+    } else {
+      this.callbacks[event]!.push(callback)
+    }
+    return this
+  }
+
+  once<EventName extends keyof Contract>(
+    event: EventName,
+    callback: (...args: Contract[EventName]) => void
+  ): this {
+    const on = (...args: Contract[EventName]): void => {
+      this.off(event, on)
+      callback.apply(this, args)
+    }
+
+    this.on(event, on)
+    return this
+  }
+
+  off<EventName extends keyof Contract>(
+    event: EventName,
+    callback: (...args: Contract[EventName]) => void
+  ): this {
+    const fns = this.callbacks[event] ?? []
+    const without = fns.filter((fn) => fn !== callback) as Contract[EventName]
+    this.callbacks[event] = without
+    return this
+  }
+
+  emit<EventName extends keyof Contract>(
+    event: EventName,
+    ...args: Contract[EventName]
+  ): this {
+    const callbacks = this.callbacks[event] ?? []
+    callbacks.forEach((callback) => {
+      callback.apply(this, args)
+    })
+    return this
+  }
+}