utneque 1.0.0

package/packages/core/src/utils/__tests__/is-thenable.test.ts

@@ -0,0 +1,39 @@
+import { isThenable } from '../is-thenable'
+
+describe('isThenable', () => {
+  test('es6 promises', () => {
+    const p = Promise.resolve(1)
+    expect(isThenable(p)).toBeTruthy()
+  })
+
+  test('on the prototype', () => {
+    class Foo {
+      then() {
+        return '123'
+      }
+    }
+    const p = new Foo()
+    expect(isThenable(p)).toBeTruthy()
+  })
+
+  test('on the pojo', () => {
+    const p = {
+      then: () => {
+        return '123'
+      },
+    }
+    expect(isThenable(p)).toBeTruthy()
+  })
+
+  test('unhappy path', () => {
+    expect(isThenable(null)).toBeFalsy()
+    expect(isThenable(undefined)).toBeFalsy()
+    expect(isThenable({})).toBeFalsy()
+    expect(
+      isThenable({
+        then: true,
+      })
+    ).toBeFalsy()
+    expect(isThenable(new (class Foo {})())).toBeFalsy()
+  })
+})

package/packages/core/src/utils/bind-all.ts

@@ -0,0 +1,19 @@
+export function bindAll<
+  ObjType extends { [key: string]: any },
+  KeyType extends keyof ObjType
+>(obj: ObjType): ObjType {
+  const proto = obj.constructor.prototype
+  for (const key of Object.getOwnPropertyNames(proto)) {
+    if (key !== 'constructor') {
+      const desc = Object.getOwnPropertyDescriptor(
+        obj.constructor.prototype,
+        key
+      )
+      if (!!desc && typeof desc.value === 'function') {
+        obj[key as KeyType] = obj[key].bind(obj)
+      }
+    }
+  }
+
+  return obj
+}

package/packages/core/src/utils/get-global.ts

@@ -0,0 +1,17 @@
+/* eslint-disable no-restricted-globals */
+// This an imperfect polyfill for globalThis
+export const getGlobal = () => {
+  if (typeof globalThis !== 'undefined') {
+    return globalThis
+  }
+  if (typeof self !== 'undefined') {
+    return self
+  }
+  if (typeof window !== 'undefined') {
+    return window
+  }
+  if (typeof global !== 'undefined') {
+    return global
+  }
+  return null
+}

package/packages/core/src/utils/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/core/src/utils/has-properties.ts

@@ -0,0 +1,7 @@
+export function hasProperties<T extends object, K extends string>(
+  obj: T,
+  ...keys: K[]
+): obj is T & { [J in K]: unknown } {
+  // eslint-disable-next-line no-prototype-builtins
+  return !!obj && keys.every((key) => obj.hasOwnProperty(key))
+}

package/packages/core/src/utils/is-plain-object.ts

@@ -0,0 +1,26 @@
+// Code derived from https://github.com/jonschlinkert/is-plain-object/blob/master/is-plain-object.js
+
+function isObject(o: unknown): o is Object {
+  return Object.prototype.toString.call(o) === '[object Object]'
+}
+
+export function isPlainObject(o: unknown): o is Record<PropertyKey, unknown> {
+  if (isObject(o) === false) return false
+
+  // If has modified constructor
+  const ctor = (o as any).constructor
+  if (ctor === undefined) return true
+
+  // If has modified prototype
+  const prot = ctor.prototype
+  if (isObject(prot) === false) return false
+
+  // If constructor does not have an Object-specific method
+  // eslint-disable-next-line no-prototype-builtins
+  if ((prot as Object).hasOwnProperty('isPrototypeOf') === false) {
+    return false
+  }
+
+  // Most likely a plain Object
+  return true
+}

package/packages/core/src/utils/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/core/src/utils/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/core/src/utils/pick.ts

@@ -0,0 +1,8 @@
+export const pickBy = <T extends object, K extends keyof T>(
+  obj: T,
+  fn: (key: K, v: T[K]) => boolean
+) => {
+  return (Object.keys(obj) as K[])
+    .filter((k) => fn(k, obj[k]))
+    .reduce((acc, key) => ((acc[key] = obj[key]), acc), {} as Partial<T>)
+}

package/packages/core/src/utils/ts-helpers.ts

@@ -0,0 +1,13 @@
+/**
+ * Remove Index Signature
+ */
+export type RemoveIndexSignature<T> = {
+  [K in keyof T as {} extends Record<K, 1> ? never : K]: T[K]
+}
+
+/**
+ * Recursively make all object properties nullable
+ */
+export type DeepNullable<T> = {
+  [K in keyof T]: T[K] extends object ? DeepNullable<T[K]> | null : T[K] | null
+}

package/packages/core/src/validation/__tests__/assertions.test.ts

@@ -0,0 +1,155 @@
+import { CoreHightouchEvent } from '../../events'
+import { validateEvent } from '../assertions'
+
+const baseEvent: Partial<CoreHightouchEvent> = {
+  userId: 'foo',
+  event: 'Test Event',
+}
+describe(validateEvent, () => {
+  test('should be capable of working with empty properties and traits', () => {
+    expect(() => validateEvent(undefined)).toThrowError()
+    expect(() => validateEvent(null)).toThrowError()
+    expect(() => validateEvent({} as any)).toThrowError()
+    expect(() => validateEvent('foo' as any)).toThrowError()
+  })
+
+  test('on track, properties should be plain objects', () => {
+    expect(() =>
+      validateEvent({
+        ...baseEvent,
+        type: 'track',
+        properties: [],
+      })
+    ).toThrowError(/properties/i)
+    expect(() =>
+      validateEvent({
+        ...baseEvent,
+        type: 'track',
+        properties: undefined,
+      })
+    ).toThrowError(/properties/i)
+    expect(() =>
+      validateEvent({
+        ...baseEvent,
+        type: 'track',
+        properties: {},
+      })
+    ).not.toThrow()
+  })
+
+  test('identify: traits should be an object', () => {
+    expect(() =>
+      validateEvent({
+        type: 'identify',
+        traits: undefined,
+      })
+    ).toThrowError(/traits/i)
+
+    expect(() =>
+      validateEvent({
+        ...baseEvent,
+        properties: {},
+        type: 'identify',
+        traits: undefined,
+      })
+    ).toThrowError(/traits/i)
+
+    expect(() =>
+      validateEvent({
+        ...baseEvent,
+        properties: undefined,
+        type: 'identify',
+        traits: null as any,
+      })
+    ).toThrowError(/traits/i)
+  })
+
+  test('alias: should allow both traits and properties to be undefined (unlike other events)', () => {
+    expect(() =>
+      validateEvent({
+        ...baseEvent,
+        previousId: 'foo',
+        type: 'alias',
+        properties: undefined,
+        traits: undefined,
+      })
+    ).not.toThrow()
+  })
+
+  describe('User Validation', () => {
+    test('should pass if either a userID/anonymousID/previousID/groupID are defined', () => {
+      expect(() =>
+        validateEvent({
+          ...baseEvent,
+          type: 'track',
+          properties: {},
+          userId: undefined,
+          anonymousId: 'foo',
+        })
+      ).not.toThrow()
+
+      expect(() =>
+        validateEvent({
+          ...baseEvent,
+          type: 'identify',
+          traits: {},
+          userId: 'foo',
+          anonymousId: undefined,
+        })
+      ).not.toThrow()
+
+      expect(() =>
+        validateEvent({
+          ...baseEvent,
+          type: 'alias',
+          previousId: 'foo',
+          userId: undefined,
+          anonymousId: undefined,
+        })
+      ).not.toThrow()
+
+      expect(() =>
+        validateEvent({
+          ...baseEvent,
+          type: 'group',
+          traits: {},
+          groupId: 'foo',
+        })
+      ).not.toThrow()
+    })
+
+    test('should fail if ID is _not_ string', () => {
+      expect(() =>
+        validateEvent({
+          ...baseEvent,
+          type: 'track',
+          properties: {},
+          userId: undefined,
+          anonymousId: 123 as any,
+        })
+      ).toThrowError(/string/)
+
+      expect(() =>
+        validateEvent({
+          ...baseEvent,
+          type: 'track',
+          properties: {},
+          userId: undefined,
+          anonymousId: 123 as any,
+        })
+      ).toThrowError(/string/)
+    })
+
+    test('should handle null as well as undefined', () => {
+      expect(() =>
+        validateEvent({
+          ...baseEvent,
+          type: 'track',
+          properties: {},
+          userId: undefined,
+          anonymousId: null,
+        })
+      ).toThrowError(/nil/i)
+    })
+  })
+})

package/packages/core/src/validation/assertions.ts

@@ -0,0 +1,72 @@
+import { CoreHightouchEvent } from '../events'
+import { ValidationError } from './errors'
+import { isString, isPlainObject, exists } from './helpers'
+
+const stringError = 'is not a string'
+const objError = 'is not an object'
+const nilError = 'is nil'
+
+export function assertUserIdentity(event: CoreHightouchEvent): void {
+  const USER_FIELD_NAME = '.userId/anonymousId/previousId/groupId'
+
+  const getAnyUserId = (event: CoreHightouchEvent) =>
+    event.userId ?? event.anonymousId ?? event.groupId ?? event.previousId
+
+  const id = getAnyUserId(event)
+  if (!exists(id)) {
+    throw new ValidationError(USER_FIELD_NAME, nilError)
+  } else if (!isString(id)) {
+    throw new ValidationError(USER_FIELD_NAME, stringError)
+  }
+}
+
+export function assertEventExists(
+  event?: CoreHightouchEvent | null
+): asserts event is CoreHightouchEvent {
+  if (!exists(event)) {
+    throw new ValidationError('Event', nilError)
+  }
+  if (typeof event !== 'object') {
+    throw new ValidationError('Event', objError)
+  }
+}
+
+export function assertEventType(event: CoreHightouchEvent): void {
+  if (!isString(event.type)) {
+    throw new ValidationError('.type', stringError)
+  }
+}
+
+export function assertTrackEventName(event: CoreHightouchEvent): void {
+  if (!isString(event.event)) {
+    throw new ValidationError('.event', stringError)
+  }
+}
+
+export function assertTrackEventProperties(event: CoreHightouchEvent): void {
+  if (!isPlainObject(event.properties)) {
+    throw new ValidationError('.properties', objError)
+  }
+}
+
+export function assertTraits(event: CoreHightouchEvent): void {
+  if (!isPlainObject(event.traits)) {
+    throw new ValidationError('.traits', objError)
+  }
+}
+
+export function validateEvent(event?: CoreHightouchEvent | null) {
+  assertEventExists(event)
+  assertEventType(event)
+
+  if (event.type === 'track') {
+    assertTrackEventName(event)
+    assertTrackEventProperties(event)
+  }
+
+  if (['group', 'identify'].includes(event.type)) {
+    assertTraits(event)
+  }
+
+  assertUserIdentity(event)
+}

package/packages/core/src/validation/errors.ts

@@ -0,0 +1,8 @@
+export class ValidationError extends Error {
+  field: string
+
+  constructor(field: string, message: string) {
+    super(`${field} ${message}`)
+    this.field = field
+  }
+}

package/packages/core/src/validation/helpers.ts

@@ -0,0 +1,23 @@
+export function isString(obj: unknown): obj is string {
+  return typeof obj === 'string'
+}
+
+export function isNumber(obj: unknown): obj is number {
+  return typeof obj === 'number'
+}
+
+export function isFunction(obj: unknown): obj is Function {
+  return typeof obj === 'function'
+}
+
+export function exists<T>(val: unknown): val is NonNullable<T> {
+  return val !== undefined && val !== null
+}
+
+export function isPlainObject(
+  obj: unknown
+): obj is Record<string | symbol | number, unknown> {
+  return (
+    Object.prototype.toString.call(obj).slice(8, -1).toLowerCase() === 'object'
+  )
+}

package/packages/core/test-helpers/index.ts

@@ -0,0 +1,2 @@
+export * from './test-ctx'
+export * from './test-event-queue'

package/packages/core/test-helpers/test-ctx.ts

@@ -0,0 +1,7 @@
+import { CoreContext } from '../src/context'
+
+export class TestCtx extends CoreContext {
+  static override system() {
+    return new this({ type: 'track', event: 'system' })
+  }
+}

package/packages/core/test-helpers/test-event-queue.ts

@@ -0,0 +1,7 @@
+import { CoreEventQueue, PriorityQueue } from '../src'
+
+export class TestEventQueue extends CoreEventQueue {
+  constructor() {
+    super(new PriorityQueue(4, []))
+  }
+}

package/packages/core/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["src"],
+  "exclude": ["**/__tests__/**", "**/*.test.*"],
+  "compilerOptions": {
+    "outDir": "./dist/esm",
+    "declarationDir": "./dist/types"
+  }
+}

package/packages/core/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "exclude": ["node_modules", "dist"],
+  "compilerOptions": {
+    "module": "esnext",
+    "target": "ES5",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "lib": ["es2020"]
+  }
+}

package/packages/node/.eslintrc.js

@@ -0,0 +1,7 @@
+/** @type { import('eslint').Linter.Config } */
+module.exports = {
+  extends: ['../../.eslintrc.isomorphic'],
+  rules: {
+    '@typescript-eslint/no-empty-interface': 'off', // since this is a lib, sometimes we want to use interfaces rather than types for the ease of declaration merging.
+  },
+}

package/packages/node/.lintstagedrc.js

@@ -0,0 +1 @@
+module.exports = require("@internal/config").lintStagedConfig

package/packages/node/LICENSE

@@ -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.