@posthog/core 1.1.0 → 1.2.0

package/src/utils/bucketed-rate-limiter.spec.ts

@@ -0,0 +1,33 @@
+import { Logger } from '@/types'
+import { BucketedRateLimiter } from './bucketed-rate-limiter'
+
+jest.useFakeTimers()
+
+describe('BucketedRateLimiter', () => {
+  let rateLimiter: BucketedRateLimiter<string>
+
+  beforeEach(() => {
+    rateLimiter = new BucketedRateLimiter({
+      bucketSize: 10,
+      refillRate: 1,
+      refillInterval: 1000,
+      _logger: {} as unknown as Logger,
+    })
+  })
+
+  afterEach(() => {
+    jest.clearAllMocks()
+  })
+
+  test('it is not rate limited by default', () => {
+    const result = rateLimiter.consumeRateLimit('ResizeObserver')
+    expect(result).toBe(false)
+  })
+
+  test('returns true if no mutations are left', () => {
+    rateLimiter['_buckets']['ResizeObserver'] = 0
+
+    const result = rateLimiter.consumeRateLimit('ResizeObserver')
+    expect(result).toBe(true)
+  })
+})

package/src/utils/bucketed-rate-limiter.ts

@@ -0,0 +1,85 @@
+import { Logger } from '../types'
+import { clampToRange } from './number-utils'
+
+export class BucketedRateLimiter<T extends string | number> {
+  private _bucketSize
+  private _refillRate
+  private _refillInterval
+  private _onBucketRateLimited?: (key: T) => void
+
+  private _buckets: Record<string, number> = {}
+  private _removeInterval: NodeJS.Timeout | undefined
+
+  constructor(
+    private readonly _options: {
+      bucketSize: number
+      refillRate: number
+      refillInterval: number
+      _logger: Logger
+      _onBucketRateLimited?: (key: T) => void
+    }
+  ) {
+    this._onBucketRateLimited = this._options._onBucketRateLimited
+    this._bucketSize = clampToRange(this._options.bucketSize, 0, 100, this._options._logger)
+    this._refillRate = clampToRange(
+      this._options.refillRate,
+      0,
+      this._bucketSize, // never refill more than bucket size
+      this._options._logger
+    )
+    this._refillInterval = clampToRange(
+      this._options.refillInterval,
+      0,
+      86400000, // one day in milliseconds
+      this._options._logger
+    )
+    this._removeInterval = setInterval(() => {
+      this._refillBuckets()
+    }, this._refillInterval)
+  }
+
+  private _refillBuckets = () => {
+    Object.keys(this._buckets).forEach((key) => {
+      const newTokens = this._getBucket(key) + this._refillRate
+
+      if (newTokens >= this._bucketSize) {
+        delete this._buckets[key]
+      } else {
+        this._setBucket(key, newTokens)
+      }
+    })
+  }
+
+  private _getBucket = (key: T | string) => {
+    return this._buckets[String(key)]
+  }
+  private _setBucket = (key: T | string, value: number) => {
+    this._buckets[String(key)] = value
+  }
+
+  public consumeRateLimit = (key: T) => {
+    let tokens = this._getBucket(key) ?? this._bucketSize
+    tokens = Math.max(tokens - 1, 0)
+
+    if (tokens === 0) {
+      return true
+    }
+
+    this._setBucket(key, tokens)
+
+    const hasReachedZero = tokens === 0
+
+    if (hasReachedZero) {
+      this._onBucketRateLimited?.(key)
+    }
+
+    return hasReachedZero
+  }
+
+  public stop() {
+    if (this._removeInterval) {
+      clearInterval(this._removeInterval)
+      this._removeInterval = undefined
+    }
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,98 @@
+import { FetchLike } from '../types'
+
+export * from './bucketed-rate-limiter'
+export * from './number-utils'
+export * from './string-utils'
+export * from './type-utils'
+export * from './promise-queue'
+
+export const STRING_FORMAT = 'utf8'
+
+export function assert(truthyValue: any, message: string): void {
+  if (!truthyValue || typeof truthyValue !== 'string' || isEmpty(truthyValue)) {
+    throw new Error(message)
+  }
+}
+
+function isEmpty(truthyValue: string): boolean {
+  if (truthyValue.trim().length === 0) {
+    return true
+  }
+  return false
+}
+
+export function removeTrailingSlash(url: string): string {
+  return url?.replace(/\/+$/, '')
+}
+
+export interface RetriableOptions {
+  retryCount: number
+  retryDelay: number
+  retryCheck: (err: unknown) => boolean
+}
+
+export async function retriable<T>(fn: () => Promise<T>, props: RetriableOptions): Promise<T> {
+  let lastError = null
+
+  for (let i = 0; i < props.retryCount + 1; i++) {
+    if (i > 0) {
+      // don't wait when it's the last try
+      await new Promise<void>((r) => setTimeout(r, props.retryDelay))
+    }
+
+    try {
+      const res = await fn()
+      return res
+    } catch (e) {
+      lastError = e
+      if (!props.retryCheck(e)) {
+        throw e
+      }
+    }
+  }
+
+  throw lastError
+}
+
+export function currentTimestamp(): number {
+  return new Date().getTime()
+}
+
+export function currentISOTime(): string {
+  return new Date().toISOString()
+}
+
+export function safeSetTimeout(fn: () => void, timeout: number): any {
+  // NOTE: we use this so rarely that it is totally fine to do `safeSetTimeout(fn, 0)``
+  // rather than setImmediate.
+  const t = setTimeout(fn, timeout) as any
+  // We unref if available to prevent Node.js hanging on exit
+  t?.unref && t?.unref()
+  return t
+}
+
+// NOTE: We opt for this slightly imperfect check as the global "Promise" object can get mutated in certain environments
+export const isPromise = (obj: any): obj is Promise<any> => {
+  return obj && typeof obj.then === 'function'
+}
+
+export const isError = (x: unknown): x is Error => {
+  return x instanceof Error
+}
+
+export function getFetch(): FetchLike | undefined {
+  return typeof fetch !== 'undefined' ? fetch : typeof globalThis.fetch !== 'undefined' ? globalThis.fetch : undefined
+}
+
+export function allSettled<T>(
+  promises: (Promise<T> | null | undefined)[]
+): Promise<({ status: 'fulfilled'; value: T } | { status: 'rejected'; reason: any })[]> {
+  return Promise.all(
+    promises.map((p) =>
+      (p ?? Promise.resolve()).then(
+        (value: any) => ({ status: 'fulfilled' as const, value }),
+        (reason: any) => ({ status: 'rejected' as const, reason })
+      )
+    )
+  )
+}

package/src/utils/number-utils.spec.ts

@@ -0,0 +1,89 @@
+import { createMockLogger } from '@/testing'
+import { clampToRange } from './number-utils'
+
+describe('number-utils', () => {
+  const mockLogger = createMockLogger()
+
+  describe('clampToRange', () => {
+    it.each([
+      [
+        'returns max when value is not a number',
+        {
+          value: null,
+          min: 10,
+          max: 100,
+          expected: 100,
+          fallback: undefined,
+        },
+      ],
+      [
+        'returns max when value is not a number',
+        {
+          value: 'not-a-number',
+          min: 10,
+          max: 100,
+          expected: 100,
+          fallback: undefined,
+        },
+      ],
+      [
+        'returns max when value is greater than max',
+        {
+          value: 150,
+          min: 10,
+          max: 100,
+          expected: 100,
+          fallback: undefined,
+        },
+      ],
+      [
+        'returns min when value is less than min',
+        {
+          value: 5,
+          min: 10,
+          max: 100,
+          expected: 10,
+          fallback: undefined,
+        },
+      ],
+      [
+        'returns the value when it is within the range',
+        {
+          value: 50,
+          min: 10,
+          max: 100,
+          expected: 50,
+          fallback: undefined,
+        },
+      ],
+      [
+        'returns the fallback value when provided is not valid',
+        {
+          value: 'invalid',
+          min: 10,
+          max: 100,
+          expected: 20,
+          fallback: 20,
+        },
+      ],
+      [
+        'returns the max value when fallback is not valid',
+        {
+          value: 'invalid',
+          min: 10,
+          max: 75,
+          expected: 75,
+          fallback: '20',
+        },
+      ],
+    ])('%s', (_description, { value, min, max, expected, fallback }) => {
+      const result = clampToRange(value, min, max, mockLogger, fallback as any)
+      expect(result).toBe(expected)
+    })
+
+    it('logs a warning when min is greater than max', () => {
+      expect(clampToRange(50, 100, 10, mockLogger)).toBe(10)
+      expect(mockLogger.warn).toHaveBeenCalledWith('min cannot be greater than max.')
+    })
+  })
+})

package/src/utils/number-utils.ts

@@ -0,0 +1,30 @@
+import { Logger } from '../types'
+import { isNumber } from './type-utils'
+
+/**
+ * Clamps a value to a range.
+ * @param value the value to clamp
+ * @param min the minimum value
+ * @param max the maximum value
+ * @param label if provided then enables logging and prefixes all logs with labels
+ * @param fallbackValue if provided then returns this value if the value is not a valid number
+ */
+export function clampToRange(value: unknown, min: number, max: number, logger: Logger, fallbackValue?: number): number {
+  if (min > max) {
+    logger.warn('min cannot be greater than max.')
+    min = max
+  }
+
+  if (!isNumber(value)) {
+    logger.warn(' must be a number. using max or fallback. max: ' + max + ', fallback: ' + fallbackValue)
+    return clampToRange(fallbackValue || max, min, max, logger)
+  } else if (value > max) {
+    logger.warn(' cannot be  greater than max: ' + max + '. Using max value instead.')
+    return max
+  } else if (value < min) {
+    logger.warn(' cannot be less than min: ' + min + '. Using min value instead.')
+    return min
+  } else {
+    return value
+  }
+}

package/src/utils/promise-queue.spec.ts

@@ -0,0 +1,55 @@
+import { PromiseQueue } from './promise-queue'
+
+function buildPromise(time: number): Promise<number> {
+  return new Promise((res, rej) => setTimeout(() => res(42), time))
+}
+
+function buildRecursivePromise(time: number, cb: () => void) {
+  return new Promise((res, rej) => {
+    setTimeout(() => {
+      cb()
+      res(42)
+    }, time)
+  })
+}
+
+describe('promise-queue', () => {
+  beforeAll(() => jest.useRealTimers())
+  afterAll(() => jest.useFakeTimers())
+
+  it('should exit directly if the queue is empty', async () => {
+    const queue = new PromiseQueue()
+    expect(queue.length).toBe(0)
+    expect(queue.join()).resolves.toBe(undefined)
+  })
+
+  it('should add a promise to the queue', async () => {
+    const queue = new PromiseQueue()
+    queue.add(buildPromise(100))
+    expect(queue.length).toBe(1)
+    await queue.join()
+    expect(queue.length).toBe(0)
+  })
+
+  it('should wait even when promises create other promises', async () => {
+    const queue = new PromiseQueue()
+    const addSpy = jest.spyOn(queue, 'add')
+    queue.add(
+      buildRecursivePromise(100, () => {
+        queue.add(buildPromise(100))
+      })
+    )
+    expect(queue.length).toBe(1)
+    await queue.join()
+    expect(queue.length).toBe(0)
+    expect(addSpy).toHaveBeenCalledTimes(2)
+  })
+
+  it('it should reject if a promise reject', async () => {
+    const queue = new PromiseQueue()
+    queue.add(Promise.reject(new Error('test')))
+    expect(queue.length).toBe(1)
+    await expect(queue.join()).rejects.toHaveProperty('message', 'test')
+    expect(queue.length).toBe(0)
+  })
+})

package/src/utils/promise-queue.ts

@@ -0,0 +1,30 @@
+import { uuidv7 } from '../vendor/uuidv7'
+
+export class PromiseQueue {
+  private promiseByIds: Record<string, Promise<any>> = {}
+
+  public add(promise: Promise<any>): Promise<any> {
+    const promiseUUID = uuidv7()
+    this.promiseByIds[promiseUUID] = promise
+    promise
+      .catch(() => {})
+      .finally(() => {
+        delete this.promiseByIds[promiseUUID]
+      })
+    return promise
+  }
+
+  public async join(): Promise<void> {
+    let promises = Object.values(this.promiseByIds)
+    let length = promises.length
+    while (length > 0) {
+      await Promise.all(promises)
+      promises = Object.values(this.promiseByIds)
+      length = promises.length
+    }
+  }
+
+  public get length(): number {
+    return Object.keys(this.promiseByIds).length
+  }
+}

package/src/utils/string-utils.ts

@@ -0,0 +1,23 @@
+export function includes(str: string, needle: string): boolean
+export function includes<T>(arr: T[], needle: T): boolean
+export function includes(str: unknown[] | string, needle: unknown): boolean {
+  return (str as any).indexOf(needle) !== -1
+}
+
+export const trim = function (str: string): string {
+  // Previous implementation was using underscore's trim function.
+  // When switching to just using the native trim() function, we ran some tests to make sure that it was able to trim both the BOM character \uFEFF and the NBSP character \u00A0.
+  // We tested modern Chrome (134.0.6998.118) and Firefox (136.0.2), and IE11 running on Windows 10, and all of them were able to trim both characters.
+  // See https://posthog.slack.com/archives/C0113360FFV/p1742811455647359
+  return str.trim()
+}
+
+// UNDERSCORE
+// Embed part of the Underscore Library
+export const stripLeadingDollar = function (s: string): string {
+  return s.replace(/^\$/, '')
+}
+
+export function isDistinctIdStringLike(value: string): boolean {
+  return ['distinct_id', 'distinctid'].includes(value.toLowerCase())
+}

package/src/utils/type-utils.ts

@@ -0,0 +1,134 @@
+import { knownUnsafeEditableEvent, KnownUnsafeEditableEvent } from '../types'
+import { includes } from './string-utils'
+
+// eslint-disable-next-line posthog-js/no-direct-array-check
+const nativeIsArray = Array.isArray
+const ObjProto = Object.prototype
+export const hasOwnProperty = ObjProto.hasOwnProperty
+const toString = ObjProto.toString
+
+export const isArray =
+  nativeIsArray ||
+  function (obj: any): obj is any[] {
+    return toString.call(obj) === '[object Array]'
+  }
+
+// from a comment on http://dbj.org/dbj/?p=286
+// fails on only one very rare and deliberate custom object:
+// let bomb = { toString : undefined, valueOf: function(o) { return "function BOMBA!"; }};
+export const isFunction = (x: unknown): x is (...args: any[]) => any => {
+  // eslint-disable-next-line posthog-js/no-direct-function-check
+  return typeof x === 'function'
+}
+
+export const isNativeFunction = (x: unknown): x is (...args: any[]) => any =>
+  isFunction(x) && x.toString().indexOf('[native code]') !== -1
+
+// Underscore Addons
+export const isObject = (x: unknown): x is Record<string, any> => {
+  // eslint-disable-next-line posthog-js/no-direct-object-check
+  return x === Object(x) && !isArray(x)
+}
+export const isEmptyObject = (x: unknown) => {
+  if (isObject(x)) {
+    for (const key in x) {
+      if (hasOwnProperty.call(x, key)) {
+        return false
+      }
+    }
+    return true
+  }
+  return false
+}
+export const isUndefined = (x: unknown): x is undefined => x === void 0
+
+export const isString = (x: unknown): x is string => {
+  // eslint-disable-next-line posthog-js/no-direct-string-check
+  return toString.call(x) == '[object String]'
+}
+
+export const isEmptyString = (x: unknown): boolean => isString(x) && x.trim().length === 0
+
+export const isNull = (x: unknown): x is null => {
+  // eslint-disable-next-line posthog-js/no-direct-null-check
+  return x === null
+}
+
+/*
+    sometimes you want to check if something is null or undefined
+    that's what this is for
+ */
+export const isNullish = (x: unknown): x is null | undefined => isUndefined(x) || isNull(x)
+
+export const isNumber = (x: unknown): x is number => {
+  // eslint-disable-next-line posthog-js/no-direct-number-check
+  return toString.call(x) == '[object Number]'
+}
+export const isBoolean = (x: unknown): x is boolean => {
+  // eslint-disable-next-line posthog-js/no-direct-boolean-check
+  return toString.call(x) === '[object Boolean]'
+}
+
+export const isFormData = (x: unknown): x is FormData => {
+  // eslint-disable-next-line posthog-js/no-direct-form-data-check
+  return x instanceof FormData
+}
+
+export const isFile = (x: unknown): x is File => {
+  // eslint-disable-next-line posthog-js/no-direct-file-check
+  return x instanceof File
+}
+
+export const isPlainError = (x: unknown): x is Error => {
+  return x instanceof Error
+}
+
+export const isKnownUnsafeEditableEvent = (x: unknown): x is KnownUnsafeEditableEvent => {
+  return includes(knownUnsafeEditableEvent as unknown as string[], x)
+}
+
+export function isInstanceOf(candidate: unknown, base: any): boolean {
+  try {
+    return candidate instanceof base
+  } catch {
+    return false
+  }
+}
+
+export function isPrimitive(value: unknown): boolean {
+  return value === null || typeof value !== 'object'
+}
+
+export function isBuiltin(candidate: unknown, className: string): boolean {
+  return Object.prototype.toString.call(candidate) === `[object ${className}]`
+}
+
+export function isError(candidate: unknown): candidate is Error {
+  switch (Object.prototype.toString.call(candidate)) {
+    case '[object Error]':
+    case '[object Exception]':
+    case '[object DOMException]':
+    case '[object DOMError]':
+    case '[object WebAssembly.Exception]':
+      return true
+    default:
+      return isInstanceOf(candidate, Error)
+  }
+}
+
+export function isErrorEvent(event: unknown): boolean {
+  return isBuiltin(event, 'ErrorEvent')
+}
+
+export function isEvent(candidate: unknown): candidate is Event {
+  return !isUndefined(Event) && isInstanceOf(candidate, Event)
+}
+
+export function isPlainObject(candidate: unknown): candidate is Record<string, unknown> {
+  return isBuiltin(candidate, 'Object')
+}
+
+export const yesLikeValues = [true, 'true', 1, '1', 'yes']
+export const isYesLike = (val: string | boolean | number): boolean => includes(yesLikeValues, val)
+export const noLikeValues = [false, 'false', 0, '0', 'no']
+export const isNoLike = (val: string | boolean | number): boolean => includes(noLikeValues, val)