@openobserve/browser-core 0.2.8

package/src/tools/mergeInto.ts

@@ -0,0 +1,177 @@
+import { getType } from './utils/typeUtils'
+
+type Merged<TDestination, TSource> =
+  // case 1 - source is undefined - return destination
+  TSource extends undefined
+    ? TDestination
+    : // case 2 - destination is undefined - return source
+    TDestination extends undefined
+    ? TSource
+    : // case 3 - source is an array - see if it merges or overwrites
+    TSource extends any[]
+    ? TDestination extends any[]
+      ? TDestination & TSource
+      : TSource
+    : // case 4 - source is an object - see if it merges or overwrites
+    TSource extends object
+    ? TDestination extends object
+      ? TDestination extends any[]
+        ? TSource
+        : TDestination & TSource
+      : TSource
+    : // case 5 - cannot merge - return source
+      TSource
+
+/**
+ * Iterate over source and affect its sub values into destination, recursively.
+ * If the source and destination can't be merged, return source.
+ */
+export function mergeInto<D, S>(
+  destination: D,
+  source: S,
+  circularReferenceChecker = createCircularReferenceChecker()
+): Merged<D, S> {
+  // ignore the source if it is undefined
+  if (source === undefined) {
+    return destination as Merged<D, S>
+  }
+
+  if (typeof source !== 'object' || source === null) {
+    // primitive values - just return source
+    return source as Merged<D, S>
+  } else if (source instanceof Date) {
+    return new Date(source.getTime()) as unknown as Merged<D, S>
+  } else if (source instanceof RegExp) {
+    const flags =
+      source.flags ||
+      // old browsers compatibility
+      [
+        source.global ? 'g' : '',
+        source.ignoreCase ? 'i' : '',
+        source.multiline ? 'm' : '',
+        source.sticky ? 'y' : '',
+        source.unicode ? 'u' : '',
+      ].join('')
+    return new RegExp(source.source, flags) as unknown as Merged<D, S>
+  }
+
+  if (circularReferenceChecker.hasAlreadyBeenSeen(source)) {
+    // remove circular references
+    return undefined as unknown as Merged<D, S>
+  } else if (Array.isArray(source)) {
+    const merged: any[] = Array.isArray(destination) ? destination : []
+    for (let i = 0; i < source.length; ++i) {
+      merged[i] = mergeInto(merged[i], source[i], circularReferenceChecker)
+    }
+    return merged as unknown as Merged<D, S>
+  }
+
+  const merged = getType(destination) === 'object' ? (destination as Record<any, any>) : {}
+  for (const key in source) {
+    if (Object.prototype.hasOwnProperty.call(source, key)) {
+      merged[key] = mergeInto(merged[key], source[key], circularReferenceChecker)
+    }
+  }
+  return merged as unknown as Merged<D, S>
+}
+
+/**
+ * A simplistic implementation of a deep clone algorithm.
+ * Caveats:
+ * - It doesn't maintain prototype chains - don't use with instances of custom classes.
+ * - It doesn't handle Map and Set
+ */
+export function deepClone<T>(value: T): T {
+  return mergeInto(undefined, value) as T
+}
+
+type Combined<A, B> = A extends null ? B : B extends null ? A : Merged<A, B>
+
+/*
+ * Performs a deep merge of objects and arrays.
+ * - Arguments won't be mutated
+ * - Object and arrays in the output value are de-referenced ("deep cloned")
+ * - Arrays values are merged index by index
+ * - Objects are merged by keys
+ * - Values get replaced, unless undefined
+ */
+export function combine<A, B>(a: A, b: B): Combined<A, B>
+export function combine<A, B, C>(a: A, b: B, c: C): Combined<Combined<A, B>, C>
+export function combine<A, B, C, D>(a: A, b: B, c: C, d: D): Combined<Combined<Combined<A, B>, C>, D>
+export function combine<A, B, C, D, E>(
+  a: A,
+  b: B,
+  c: C,
+  d: D,
+  e: E
+): Combined<Combined<Combined<Combined<A, B>, C>, D>, E>
+export function combine<A, B, C, D, E, F>(
+  a: A,
+  b: B,
+  c: C,
+  d: D,
+  e: E,
+  f: F
+): Combined<Combined<Combined<Combined<Combined<A, B>, C>, D>, E>, F>
+export function combine<A, B, C, D, E, F, G>(
+  a: A,
+  b: B,
+  c: C,
+  d: D,
+  e: E,
+  f: F,
+  g: G
+): Combined<Combined<Combined<Combined<Combined<Combined<A, B>, C>, D>, E>, F>, G>
+export function combine<A, B, C, D, E, F, G, H>(
+  a: A,
+  b: B,
+  c: C,
+  d: D,
+  e: E,
+  f: F,
+  g: G,
+  h: H
+): Combined<Combined<Combined<Combined<Combined<Combined<Combined<A, B>, C>, D>, E>, F>, G>, H>
+export function combine(...sources: any[]): unknown {
+  let destination: any
+
+  for (const source of sources) {
+    // Ignore any undefined or null sources.
+    if (source === undefined || source === null) {
+      continue
+    }
+
+    destination = mergeInto(destination, source)
+  }
+
+  return destination as unknown
+}
+
+interface CircularReferenceChecker {
+  hasAlreadyBeenSeen(value: any): boolean
+}
+
+function createCircularReferenceChecker(): CircularReferenceChecker {
+  if (typeof WeakSet !== 'undefined') {
+    const set: WeakSet<any> = new WeakSet()
+    return {
+      hasAlreadyBeenSeen(value) {
+        const has = set.has(value)
+        if (!has) {
+          set.add(value)
+        }
+        return has
+      },
+    }
+  }
+  const array: any[] = []
+  return {
+    hasAlreadyBeenSeen(value) {
+      const has = array.indexOf(value) >= 0
+      if (!has) {
+        array.push(value)
+      }
+      return has
+    },
+  }
+}

package/src/tools/monitor.ts

@@ -0,0 +1,68 @@
+import { ConsoleApiName, display } from './display'
+
+let onMonitorErrorCollected: undefined | ((error: unknown) => void)
+let debugMode = false
+
+export function startMonitorErrorCollection(newOnMonitorErrorCollected: (error: unknown) => void) {
+  onMonitorErrorCollected = newOnMonitorErrorCollected
+}
+
+export function setDebugMode(newDebugMode: boolean) {
+  debugMode = newDebugMode
+}
+
+export function resetMonitor() {
+  onMonitorErrorCollected = undefined
+  debugMode = false
+}
+
+export function monitored<T extends (...params: any[]) => unknown>(
+  _: any,
+  __: string,
+  descriptor: TypedPropertyDescriptor<T>
+) {
+  const originalMethod = descriptor.value!
+  descriptor.value = function (this: any, ...args: Parameters<T>) {
+    const decorated = onMonitorErrorCollected ? monitor(originalMethod) : originalMethod
+    return decorated.apply(this, args) as ReturnType<T>
+  } as T
+}
+
+export function monitor<T extends (...args: any[]) => any>(fn: T): T {
+  return function (this: any) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return callMonitored(fn, this, arguments as unknown as Parameters<T>)
+  } as unknown as T // consider output type has input type
+}
+
+export function callMonitored<T extends (...args: any[]) => any>(
+  fn: T,
+  context: ThisParameterType<T>,
+  args: Parameters<T>
+): ReturnType<T> | undefined
+export function callMonitored<T extends (this: void) => any>(fn: T): ReturnType<T> | undefined
+export function callMonitored<T extends (...args: any[]) => any>(
+  fn: T,
+  context?: any,
+  args?: any
+): ReturnType<T> | undefined {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return fn.apply(context, args)
+  } catch (e) {
+    displayIfDebugEnabled(ConsoleApiName.error, e)
+    if (onMonitorErrorCollected) {
+      try {
+        onMonitorErrorCollected(e)
+      } catch (e) {
+        displayIfDebugEnabled(ConsoleApiName.error, e)
+      }
+    }
+  }
+}
+
+export function displayIfDebugEnabled(api: ConsoleApiName, ...args: any[]) {
+  if (debugMode) {
+    display(api, '[MONITOR]', ...args)
+  }
+}

package/src/tools/observable.ts

@@ -0,0 +1,40 @@
+export interface Subscription {
+  unsubscribe: () => void
+}
+
+export class Observable<T> {
+  private observers: Array<(data: T) => void> = []
+  private onLastUnsubscribe?: () => void
+
+  constructor(private onFirstSubscribe?: () => (() => void) | void) {}
+
+  subscribe(f: (data: T) => void): Subscription {
+    if (!this.observers.length && this.onFirstSubscribe) {
+      this.onLastUnsubscribe = this.onFirstSubscribe() || undefined
+    }
+    this.observers.push(f)
+    return {
+      unsubscribe: () => {
+        this.observers = this.observers.filter((other) => f !== other)
+        if (!this.observers.length && this.onLastUnsubscribe) {
+          this.onLastUnsubscribe()
+        }
+      },
+    }
+  }
+
+  notify(data: T) {
+    this.observers.forEach((observer) => observer(data))
+  }
+}
+
+export function mergeObservables<T>(...observables: Array<Observable<T>>) {
+  const globalObservable = new Observable<T>(() => {
+    const subscriptions: Subscription[] = observables.map((observable) =>
+      observable.subscribe((data) => globalObservable.notify(data))
+    )
+    return () => subscriptions.forEach((subscription) => subscription.unsubscribe())
+  })
+
+  return globalObservable
+}

package/src/tools/readBytesFromStream.ts

@@ -0,0 +1,77 @@
+import { monitor } from './monitor'
+import { noop } from './utils/functionUtils'
+
+type Options = {
+  bytesLimit: number
+  collectStreamBody?: boolean
+}
+/**
+ * Read bytes from a ReadableStream until at least `limit` bytes have been read (or until the end of
+ * the stream). The callback is invoked with the at most `limit` bytes, and indicates that the limit
+ * has been exceeded if more bytes were available.
+ */
+export function readBytesFromStream(
+  stream: ReadableStream<Uint8Array>,
+  callback: (error?: Error, bytes?: Uint8Array, limitExceeded?: boolean) => void,
+  options: Options
+) {
+  const reader = stream.getReader()
+  const chunks: Uint8Array[] = []
+  let readBytesCount = 0
+
+  readMore()
+
+  function readMore() {
+    reader.read().then(
+      monitor((result: ReadableStreamReadResult<Uint8Array>) => {
+        if (result.done) {
+          onDone()
+          return
+        }
+
+        if (options.collectStreamBody) {
+          chunks.push(result.value)
+        }
+        readBytesCount += result.value.length
+
+        if (readBytesCount > options.bytesLimit) {
+          onDone()
+        } else {
+          readMore()
+        }
+      }),
+      monitor((error) => callback(error))
+    )
+  }
+
+  function onDone() {
+    reader.cancel().catch(
+      // we don't care if cancel fails, but we still need to catch the error to avoid reporting it
+      // as an unhandled rejection
+      noop
+    )
+
+    let bytes: Uint8Array | undefined
+    let limitExceeded: boolean | undefined
+    if (options.collectStreamBody) {
+      let completeBuffer: Uint8Array
+      if (chunks.length === 1) {
+        // optimization: if the response is small enough to fit in a single buffer (provided by the browser), just
+        // use it directly.
+        completeBuffer = chunks[0]
+      } else {
+        // else, we need to copy buffers into a larger buffer to concatenate them.
+        completeBuffer = new Uint8Array(readBytesCount)
+        let offset = 0
+        chunks.forEach((chunk) => {
+          completeBuffer.set(chunk, offset)
+          offset += chunk.length
+        })
+      }
+      bytes = completeBuffer.slice(0, options.bytesLimit)
+      limitExceeded = completeBuffer.length > options.bytesLimit
+    }
+
+    callback(undefined, bytes, limitExceeded)
+  }
+}

package/src/tools/sendToExtension.ts

@@ -0,0 +1,12 @@
+interface BrowserWindow {
+  __ooBrowserSdkExtensionCallback?: (message: unknown) => void
+}
+
+type ExtensionMessageType = 'logs' | 'record' | 'rum' | 'telemetry'
+
+export function sendToExtension(type: ExtensionMessageType, payload: unknown) {
+  const callback = (window as BrowserWindow).__ooBrowserSdkExtensionCallback
+  if (callback) {
+    callback({ type, payload })
+  }
+}

package/src/tools/serialisation/context.ts

@@ -0,0 +1,8 @@
+export interface Context {
+  [x: string]: ContextValue
+}
+
+export type ContextValue = string | number | boolean | Context | ContextArray | undefined | null
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface ContextArray extends Array<ContextValue> {}

package/src/tools/serialisation/contextManager.ts

@@ -0,0 +1,79 @@
+import { computeBytesCount } from '../utils/byteUtils'
+import { throttle } from '../utils/functionUtils'
+import { deepClone } from '../mergeInto'
+import { getType } from '../utils/typeUtils'
+import { jsonStringify } from './jsonStringify'
+import { sanitize } from './sanitize'
+import { warnIfCustomerDataLimitReached } from './heavyCustomerDataWarning'
+import type { CustomerDataType } from './heavyCustomerDataWarning'
+import type { Context, ContextValue } from './context'
+
+export const BYTES_COMPUTATION_THROTTLING_DELAY = 200
+
+export type ContextManager = ReturnType<typeof createContextManager>
+
+export function createContextManager(customerDataType: CustomerDataType, computeBytesCountImpl = computeBytesCount) {
+  let context: Context = {}
+  let bytesCountCache: number
+  let alreadyWarned = false
+
+  // Throttle the bytes computation to minimize the impact on performance.
+  // Especially useful if the user call context APIs synchronously multiple times in a row
+  const { throttled: computeBytesCountThrottled } = throttle((context: Context) => {
+    bytesCountCache = computeBytesCountImpl(jsonStringify(context)!)
+    if (!alreadyWarned) {
+      alreadyWarned = warnIfCustomerDataLimitReached(bytesCountCache, customerDataType)
+    }
+  }, BYTES_COMPUTATION_THROTTLING_DELAY)
+
+  const contextManager = {
+    getBytesCount: () => bytesCountCache,
+    /** @deprecated use getContext instead */
+    get: () => context,
+
+    /** @deprecated use setContextProperty instead */
+    add: (key: string, value: any) => {
+      context[key] = value as ContextValue
+      computeBytesCountThrottled(context)
+    },
+
+    /** @deprecated renamed to removeContextProperty */
+    remove: (key: string) => {
+      delete context[key]
+      computeBytesCountThrottled(context)
+    },
+
+    /** @deprecated use setContext instead */
+    set: (newContext: object) => {
+      context = newContext as Context
+      computeBytesCountThrottled(context)
+    },
+
+    getContext: () => deepClone(context),
+
+    setContext: (newContext: Context) => {
+      if (getType(newContext) === 'object') {
+        context = sanitize(newContext)
+        computeBytesCountThrottled(context)
+      } else {
+        contextManager.clearContext()
+      }
+    },
+
+    setContextProperty: (key: string, property: any) => {
+      context[key] = sanitize(property)
+      computeBytesCountThrottled(context)
+    },
+
+    removeContextProperty: (key: string) => {
+      delete context[key]
+      computeBytesCountThrottled(context)
+    },
+
+    clearContext: () => {
+      context = {}
+      bytesCountCache = 0
+    },
+  }
+  return contextManager
+}

package/src/tools/serialisation/heavyCustomerDataWarning.ts

@@ -0,0 +1,26 @@
+import { ONE_KIBI_BYTE } from '../utils/byteUtils'
+import { display } from '../display'
+
+// RUM and logs batch bytes limit is 16KB
+// ensure that we leave room for other event attributes and maintain a decent amount of event per batch
+// (3KB (customer data) + 1KB (other attributes)) * 4 (events per batch) = 16KB
+export const CUSTOMER_DATA_BYTES_LIMIT = 3 * ONE_KIBI_BYTE
+
+export const enum CustomerDataType {
+  FeatureFlag = 'feature flag evaluation',
+  User = 'user',
+  GlobalContext = 'global context',
+  LoggerContext = 'logger context',
+}
+
+export function warnIfCustomerDataLimitReached(bytesCount: number, customerDataType: CustomerDataType): boolean {
+  if (bytesCount > CUSTOMER_DATA_BYTES_LIMIT) {
+    display.warn(
+      `The ${customerDataType} data exceeds the recommended ${
+        CUSTOMER_DATA_BYTES_LIMIT / ONE_KIBI_BYTE
+      }KiB threshold. More details: https://docs.datadoghq.com/real_user_monitoring/browser/troubleshooting/#customer-data-exceeds-the-recommended-3kib-warning`
+    )
+    return true
+  }
+  return false
+}

package/src/tools/serialisation/jsonStringify.ts

@@ -0,0 +1,53 @@
+import { noop } from '../utils/functionUtils'
+
+/**
+ * Custom implementation of JSON.stringify that ignores some toJSON methods. We need to do that
+ * because some sites badly override toJSON on certain objects. Removing all toJSON methods from
+ * nested values would be too costly, so we just detach them from the root value, and native classes
+ * used to build JSON values (Array and Object).
+ *
+ * Note: this still assumes that JSON.stringify is correct.
+ */
+export function jsonStringify(
+  value: unknown,
+  replacer?: Array<string | number>,
+  space?: string | number
+): string | undefined {
+  if (typeof value !== 'object' || value === null) {
+    return JSON.stringify(value)
+  }
+
+  // Note: The order matter here. We need to detach toJSON methods on parent classes before their
+  // subclasses.
+  const restoreObjectPrototypeToJson = detachToJsonMethod(Object.prototype)
+  const restoreArrayPrototypeToJson = detachToJsonMethod(Array.prototype)
+  const restoreValuePrototypeToJson = detachToJsonMethod(Object.getPrototypeOf(value))
+  const restoreValueToJson = detachToJsonMethod(value)
+
+  try {
+    return JSON.stringify(value, replacer, space)
+  } catch {
+    return '<error: unable to serialize object>'
+  } finally {
+    restoreObjectPrototypeToJson()
+    restoreArrayPrototypeToJson()
+    restoreValuePrototypeToJson()
+    restoreValueToJson()
+  }
+}
+
+export interface ObjectWithToJsonMethod {
+  toJSON?: () => unknown
+}
+
+export function detachToJsonMethod(value: object) {
+  const object = value as ObjectWithToJsonMethod
+  const objectToJson = object.toJSON
+  if (objectToJson) {
+    delete object.toJSON
+    return () => {
+      object.toJSON = objectToJson
+    }
+  }
+  return noop
+}