@pratham.raval/browser-core 6.22.3

package/src/tools/serialisation/context.ts

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

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
+}

package/src/tools/serialisation/sanitize.ts

@@ -0,0 +1,273 @@
+import { display } from '../display'
+import { ONE_KIBI_BYTE } from '../utils/byteUtils'
+import type { Context, ContextArray, ContextValue } from './context'
+import type { ObjectWithToJsonMethod } from './jsonStringify'
+import { detachToJsonMethod } from './jsonStringify'
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+type PrimitivesAndFunctions = string | number | boolean | undefined | null | symbol | bigint | Function
+type ExtendedContextValue = PrimitivesAndFunctions | object | ExtendedContext | ExtendedContextArray
+interface ExtendedContext {
+  [key: string]: ExtendedContextValue
+}
+type ExtendedContextArray = ExtendedContextValue[]
+
+interface ContainerElementToProcess {
+  source: ExtendedContextArray | ExtendedContext
+  target: ContextArray | Context
+  path: string
+}
+
+interface SanitizedEvent extends Context {
+  type: string
+  isTrusted: boolean
+  currentTarget: string | null | undefined
+  target: string | null | undefined
+}
+
+// The maximum size of a single event is 256KiB. By default, we ensure that user-provided data
+// going through sanitize fits inside our events, while leaving room for other contexts, metadata, ...
+const SANITIZE_DEFAULT_MAX_CHARACTER_COUNT = 220 * ONE_KIBI_BYTE
+
+// Symbol for the root element of the JSONPath used for visited objects
+const JSON_PATH_ROOT_ELEMENT = '$'
+
+// When serializing (using JSON.stringify) a key of an object, { key: 42 } gets wrapped in quotes as "key".
+// With the separator (:), we need to add 3 characters to the count.
+const KEY_DECORATION_LENGTH = 3
+
+/**
+ * Ensures user-provided data is 'safe' for the SDK
+ * - Deep clones data
+ * - Removes cyclic references
+ * - Transforms unserializable types to a string representation
+ *
+ * LIMITATIONS:
+ * - Size is in characters, not byte count (may differ according to character encoding)
+ * - Size does not take into account indentation that can be applied to JSON.stringify
+ * - Non-numerical properties of Arrays are ignored. Same behavior as JSON.stringify
+ *
+ * @param source              - User-provided data meant to be serialized using JSON.stringify
+ * @param maxCharacterCount   - Maximum number of characters allowed in serialized form
+ */
+export function sanitize(source: string, maxCharacterCount?: number): string | undefined
+export function sanitize(source: Context, maxCharacterCount?: number): Context
+export function sanitize(source: unknown, maxCharacterCount?: number): ContextValue
+export function sanitize(source: unknown, maxCharacterCount = SANITIZE_DEFAULT_MAX_CHARACTER_COUNT) {
+  // Unbind any toJSON function we may have on [] or {} prototypes
+  const restoreObjectPrototypeToJson = detachToJsonMethod(Object.prototype)
+  const restoreArrayPrototypeToJson = detachToJsonMethod(Array.prototype)
+
+  // Initial call to sanitizeProcessor - will populate containerQueue if source is an Array or a plain Object
+  const containerQueue: ContainerElementToProcess[] = []
+  const visitedObjectsWithPath = new WeakMap<object, string>()
+  const sanitizedData = sanitizeProcessor(
+    source as ExtendedContextValue,
+    JSON_PATH_ROOT_ELEMENT,
+    undefined,
+    containerQueue,
+    visitedObjectsWithPath
+  )
+  const serializedSanitizedData = JSON.stringify(sanitizedData)
+  let accumulatedCharacterCount = serializedSanitizedData ? serializedSanitizedData.length : 0
+
+  if (accumulatedCharacterCount > maxCharacterCount) {
+    warnOverCharacterLimit(maxCharacterCount, 'discarded', source)
+    return undefined
+  }
+
+  while (containerQueue.length > 0 && accumulatedCharacterCount < maxCharacterCount) {
+    const containerToProcess = containerQueue.shift()!
+    let separatorLength = 0 // 0 for the first element, 1 for subsequent elements
+
+    // Arrays and Objects have to be handled distinctly to ensure
+    // we do not pick up non-numerical properties from Arrays
+    if (Array.isArray(containerToProcess.source)) {
+      for (let key = 0; key < containerToProcess.source.length; key++) {
+        const targetData = sanitizeProcessor(
+          containerToProcess.source[key],
+          containerToProcess.path,
+          key,
+          containerQueue,
+          visitedObjectsWithPath
+        )
+
+        if (targetData !== undefined) {
+          accumulatedCharacterCount += JSON.stringify(targetData).length
+        } else {
+          // When an element of an Array (targetData) is undefined, it is serialized as null:
+          // JSON.stringify([undefined]) => '[null]' - This accounts for 4 characters
+          accumulatedCharacterCount += 4
+        }
+        accumulatedCharacterCount += separatorLength
+        separatorLength = 1
+        if (accumulatedCharacterCount > maxCharacterCount) {
+          warnOverCharacterLimit(maxCharacterCount, 'truncated', source)
+          break
+        }
+        ;(containerToProcess.target as ContextArray)[key] = targetData
+      }
+    } else {
+      for (const key in containerToProcess.source) {
+        if (Object.prototype.hasOwnProperty.call(containerToProcess.source, key)) {
+          const targetData = sanitizeProcessor(
+            containerToProcess.source[key],
+            containerToProcess.path,
+            key,
+            containerQueue,
+            visitedObjectsWithPath
+          )
+          // When a property of an object has an undefined value, it will be dropped during serialization:
+          // JSON.stringify({a:undefined}) => '{}'
+          if (targetData !== undefined) {
+            accumulatedCharacterCount +=
+              JSON.stringify(targetData).length + separatorLength + key.length + KEY_DECORATION_LENGTH
+            separatorLength = 1
+          }
+          if (accumulatedCharacterCount > maxCharacterCount) {
+            warnOverCharacterLimit(maxCharacterCount, 'truncated', source)
+            break
+          }
+          ;(containerToProcess.target as Context)[key] = targetData
+        }
+      }
+    }
+  }
+
+  // Rebind detached toJSON functions
+  restoreObjectPrototypeToJson()
+  restoreArrayPrototypeToJson()
+
+  return sanitizedData
+}
+
+/**
+ * Internal function to factorize the process common to the
+ * initial call to sanitize, and iterations for Arrays and Objects
+ *
+ */
+function sanitizeProcessor(
+  source: ExtendedContextValue,
+  parentPath: string,
+  key: string | number | undefined,
+  queue: ContainerElementToProcess[],
+  visitedObjectsWithPath: WeakMap<object, string>
+) {
+  // Start by handling toJSON, as we want to sanitize its output
+  const sourceToSanitize = tryToApplyToJSON(source)
+
+  if (!sourceToSanitize || typeof sourceToSanitize !== 'object') {
+    return sanitizePrimitivesAndFunctions(sourceToSanitize)
+  }
+
+  const sanitizedSource = sanitizeObjects(sourceToSanitize)
+  if (sanitizedSource !== '[Object]' && sanitizedSource !== '[Array]' && sanitizedSource !== '[Error]') {
+    return sanitizedSource
+  }
+
+  // Handle potential cyclic references
+  // We need to use source as sourceToSanitize could be a reference to a new object
+  // At this stage, we know the source is an object type
+  const sourceAsObject = source as object
+  if (visitedObjectsWithPath.has(sourceAsObject)) {
+    return `[Reference seen at ${visitedObjectsWithPath.get(sourceAsObject)!}]`
+  }
+
+  // Add processed source to queue
+  const currentPath = key !== undefined ? `${parentPath}.${key}` : parentPath
+  const target = Array.isArray(sourceToSanitize) ? ([] as ContextArray) : ({} as Context)
+  visitedObjectsWithPath.set(sourceAsObject, currentPath)
+  queue.push({ source: sourceToSanitize as ExtendedContext | ExtendedContextArray, target, path: currentPath })
+
+  return target
+}
+
+/**
+ * Handles sanitization of simple, non-object types
+ *
+ */
+function sanitizePrimitivesAndFunctions(value: PrimitivesAndFunctions) {
+  // BigInt cannot be serialized by JSON.stringify(), convert it to a string representation
+  if (typeof value === 'bigint') {
+    return `[BigInt] ${value.toString()}`
+  }
+  // Functions cannot be serialized by JSON.stringify(). Moreover, if a faulty toJSON is present, it needs to be converted
+  // so it won't prevent stringify from serializing later
+  if (typeof value === 'function') {
+    return `[Function] ${value.name || 'unknown'}`
+  }
+  // JSON.stringify() does not serialize symbols.
+  if (typeof value === 'symbol') {
+    // symbol.description is part of ES2019+
+    type symbolWithDescription = symbol & { description: string }
+    return `[Symbol] ${(value as symbolWithDescription).description || value.toString()}`
+  }
+
+  return value
+}
+
+/**
+ * Handles sanitization of object types
+ *
+ * LIMITATIONS
+ * - If a class defines a toStringTag Symbol, it will fall in the catch-all method and prevent enumeration of properties.
+ * To avoid this, a toJSON method can be defined.
+ */
+function sanitizeObjects(value: object): string | SanitizedEvent {
+  try {
+    if (value instanceof Event) {
+      return sanitizeEvent(value)
+    }
+
+    if (value instanceof RegExp) {
+      return `[RegExp] ${value.toString()}`
+    }
+
+    // Handle all remaining object types in a generic way
+    const result = Object.prototype.toString.call(value)
+    const match = result.match(/\[object (.*)\]/)
+    if (match && match[1]) {
+      return `[${match[1]}]`
+    }
+  } catch {
+    // If the previous serialization attempts failed, and we cannot convert using
+    // Object.prototype.toString, declare the value unserializable
+  }
+  return '[Unserializable]'
+}
+
+function sanitizeEvent(event: Event): SanitizedEvent {
+  return {
+    type: event.type,
+    isTrusted: event.isTrusted,
+    currentTarget: event.currentTarget ? (sanitizeObjects(event.currentTarget) as string) : null,
+    target: event.target ? (sanitizeObjects(event.target) as string) : null,
+  }
+}
+
+/**
+ * Checks if a toJSON function exists and tries to execute it
+ *
+ */
+function tryToApplyToJSON(value: ExtendedContextValue) {
+  const object = value as ObjectWithToJsonMethod
+  if (object && typeof object.toJSON === 'function') {
+    try {
+      return object.toJSON() as ExtendedContextValue
+    } catch {
+      // If toJSON fails, we continue by trying to serialize the value manually
+    }
+  }
+
+  return value
+}
+
+/**
+ * Helper function to display the warning when the accumulated character count is over the limit
+ */
+function warnOverCharacterLimit(maxCharacterCount: number, changeType: 'discarded' | 'truncated', source: unknown) {
+  display.warn(
+    `The data provided has been ${changeType} as it is over the limit of ${maxCharacterCount} characters:`,
+    source
+  )
+}

package/src/tools/stackTrace/computeStackTrace.ts

@@ -0,0 +1,250 @@
+/**
+ * Cross-browser stack trace computation.
+ *
+ * Reference implementation: https://github.com/csnover/TraceKit/blob/04530298073c3823de72deb0b97e7b38ca7bcb59/tracekit.js
+ */
+
+export interface StackFrame {
+  url?: string
+  func?: string
+  /** The arguments passed to the function, if known. */
+  args?: string[]
+  line?: number
+  column?: number
+  /** An array of source code lines; the middle element corresponds to the correct line. */
+  context?: string[]
+}
+
+export interface StackTrace {
+  name?: string
+  message?: string
+  url?: string
+  stack: StackFrame[]
+  incomplete?: boolean
+  partial?: boolean
+}
+
+const UNKNOWN_FUNCTION = '?'
+
+export function computeStackTrace(ex: unknown): StackTrace {
+  const stack: StackFrame[] = []
+
+  let stackProperty = tryToGetString(ex, 'stack')
+  const exString = String(ex)
+  if (stackProperty && stackProperty.startsWith(exString)) {
+    stackProperty = stackProperty.slice(exString.length)
+  }
+  if (stackProperty) {
+    stackProperty.split('\n').forEach((line) => {
+      const stackFrame =
+        parseChromeLine(line) || parseChromeAnonymousLine(line) || parseWinLine(line) || parseGeckoLine(line)
+      if (stackFrame) {
+        if (!stackFrame.func && stackFrame.line) {
+          stackFrame.func = UNKNOWN_FUNCTION
+        }
+
+        stack.push(stackFrame)
+      }
+    })
+  }
+
+  if (stack.length > 0 && isWronglyReportingCustomErrors() && ex instanceof Error) {
+    // if we are wrongly reporting custom errors
+    const constructors: string[] = []
+
+    // go through each inherited constructor
+    let currentPrototype: object | undefined = ex
+    while (
+      (currentPrototype = Object.getPrototypeOf(currentPrototype)) &&
+      isNonNativeClassPrototype(currentPrototype)
+    ) {
+      const constructorName = currentPrototype.constructor?.name || UNKNOWN_FUNCTION
+      constructors.push(constructorName)
+    }
+
+    // traverse the stacktrace in reverse order because the stacktrace starts with the last inherited constructor
+    // we check constructor names to ensure we remove the correct frame (and there isn't a weird unsupported environment behavior)
+    for (let i = constructors.length - 1; i >= 0 && stack[0]?.func === constructors[i]; i--) {
+      // if the first stack frame is the custom error constructor
+      // null stack frames may represent frames that failed to be parsed because the error class did not have a constructor
+      stack.shift() // remove it
+    }
+  }
+
+  return {
+    message: tryToGetString(ex, 'message'),
+    name: tryToGetString(ex, 'name'),
+    stack,
+  }
+}
+const fileUrl =
+  '((?:file|https?|blob|chrome-extension|electron|native|eval|webpack|snippet|<anonymous>|\\w+\\.|\\/).*?)'
+const filePosition = '(?::(\\d+))'
+const CHROME_LINE_RE = new RegExp(`^\\s*at (.*?) ?\\(${fileUrl}${filePosition}?${filePosition}?\\)?\\s*$`, 'i')
+
+const CHROME_EVAL_RE = new RegExp(`\\((\\S*)${filePosition}${filePosition}\\)`)
+
+function parseChromeLine(line: string): StackFrame | undefined {
+  const parts = CHROME_LINE_RE.exec(line)
+
+  if (!parts) {
+    return
+  }
+
+  const isNative = parts[2] && parts[2].indexOf('native') === 0 // start of line
+  const isEval = parts[2] && parts[2].indexOf('eval') === 0 // start of line
+  const submatch = CHROME_EVAL_RE.exec(parts[2])
+
+  if (isEval && submatch) {
+    // throw out eval line/column and use top-most line/column number
+    parts[2] = submatch[1] // url
+    parts[3] = submatch[2] // line
+    parts[4] = submatch[3] // column
+  }
+
+  return {
+    args: isNative ? [parts[2]] : [],
+    column: parts[4] ? +parts[4] : undefined,
+    func: parts[1] || UNKNOWN_FUNCTION,
+    line: parts[3] ? +parts[3] : undefined,
+    url: !isNative ? parts[2] : undefined,
+  }
+}
+
+const CHROME_ANONYMOUS_FUNCTION_RE = new RegExp(`^\\s*at ?${fileUrl}${filePosition}?${filePosition}??\\s*$`, 'i')
+
+function parseChromeAnonymousLine(line: string): StackFrame | undefined {
+  const parts = CHROME_ANONYMOUS_FUNCTION_RE.exec(line)
+
+  if (!parts) {
+    return
+  }
+
+  return {
+    args: [],
+    column: parts[3] ? +parts[3] : undefined,
+    func: UNKNOWN_FUNCTION,
+    line: parts[2] ? +parts[2] : undefined,
+    url: parts[1],
+  }
+}
+
+const WINJS_LINE_RE =
+  /^\s*at (?:((?:\[object object\])?.+) )?\(?((?:file|ms-appx|https?|webpack|blob):.*?):(\d+)(?::(\d+))?\)?\s*$/i
+
+function parseWinLine(line: string): StackFrame | undefined {
+  const parts = WINJS_LINE_RE.exec(line)
+  if (!parts) {
+    return
+  }
+
+  return {
+    args: [],
+    column: parts[4] ? +parts[4] : undefined,
+    func: parts[1] || UNKNOWN_FUNCTION,
+    line: +parts[3],
+    url: parts[2],
+  }
+}
+
+const GECKO_LINE_RE =
+  /^\s*(.*?)(?:\((.*?)\))?(?:(?:(?:^|@)((?:file|https?|blob|chrome|webpack|resource|capacitor|\[native).*?|[^@]*bundle|\[wasm code\])(?::(\d+))?(?::(\d+))?)|@)\s*$/i
+const GECKO_EVAL_RE = /(\S+) line (\d+)(?: > eval line \d+)* > eval/i
+
+function parseGeckoLine(line: string): StackFrame | undefined {
+  const parts = GECKO_LINE_RE.exec(line)
+  if (!parts) {
+    return
+  }
+
+  const isEval = parts[3] && parts[3].indexOf(' > eval') > -1
+  const submatch = GECKO_EVAL_RE.exec(parts[3])
+
+  if (isEval && submatch) {
+    // throw out eval line/column and use top-most line number
+    parts[3] = submatch[1]
+    parts[4] = submatch[2]
+    parts[5] = undefined! // no column when eval
+  }
+
+  return {
+    args: parts[2] ? parts[2].split(',') : [],
+    column: parts[5] ? +parts[5] : undefined,
+    func: parts[1] || UNKNOWN_FUNCTION,
+    line: parts[4] ? +parts[4] : undefined,
+    url: parts[3],
+  }
+}
+
+function tryToGetString(candidate: unknown, property: string) {
+  if (typeof candidate !== 'object' || !candidate || !(property in candidate)) {
+    return undefined
+  }
+  const value = (candidate as { [k: string]: unknown })[property]
+  return typeof value === 'string' ? value : undefined
+}
+
+export function computeStackTraceFromOnErrorMessage(
+  messageObj: unknown,
+  url?: string,
+  line?: number,
+  column?: number
+): StackTrace | undefined {
+  if (url === undefined) {
+    return
+  }
+  const { name, message } = tryToParseMessage(messageObj)
+  return {
+    name,
+    message,
+    stack: [{ url, column, line }],
+  }
+}
+
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#Error_types
+const ERROR_TYPES_RE =
+  /^(?:[Uu]ncaught (?:exception: )?)?(?:((?:Eval|Internal|Range|Reference|Syntax|Type|URI|)Error): )?([\s\S]*)$/
+
+function tryToParseMessage(messageObj: unknown) {
+  let name
+  let message
+  if ({}.toString.call(messageObj) === '[object String]') {
+    ;[, name, message] = ERROR_TYPES_RE.exec(messageObj as string)!
+  }
+  return { name, message }
+}
+
+// Custom error stacktrace fix
+// Some browsers (safari/firefox) add the error constructor as a frame in the stacktrace
+// In order to normalize the stacktrace, we need to remove it
+
+function isNonNativeClassPrototype(prototype: object) {
+  return String(prototype.constructor).startsWith('class ')
+}
+
+let isWronglyReportingCustomErrorsCache: boolean | undefined
+
+function isWronglyReportingCustomErrors() {
+  if (isWronglyReportingCustomErrorsCache !== undefined) {
+    return isWronglyReportingCustomErrorsCache
+  }
+
+  /* eslint-disable no-restricted-syntax */
+  class DatadogTestCustomError extends Error {
+    constructor() {
+      super()
+      this.name = 'Error' // set name to Error so that no browser would default to the constructor name
+    }
+  }
+
+  const [customError, nativeError] = [DatadogTestCustomError, Error].map((errConstructor) => new errConstructor()) // so that both errors should exactly have the same stacktrace
+
+  isWronglyReportingCustomErrorsCache =
+    // If customError is not a class, it means that this was built with ES5 as target, converting the class to a normal object.
+    // Thus, error constructors will be reported on all browsers, which is the expected behavior.
+    isNonNativeClassPrototype(Object.getPrototypeOf(customError)) &&
+    // If the browser is correctly reporting the stacktrace, the normal error stacktrace should be the same as the custom error stacktrace
+    nativeError.stack !== customError.stack
+
+  return isWronglyReportingCustomErrorsCache
+}

package/src/tools/stackTrace/handlingStack.ts

@@ -0,0 +1,48 @@
+import { callMonitored } from '../monitor'
+import type { StackTrace } from './computeStackTrace'
+import { computeStackTrace } from './computeStackTrace'
+
+/**
+ * Creates a stacktrace without SDK internal frames.
+ * Constraints:
+ * - Has to be called at the utmost position of the call stack.
+ * - No monitored function should encapsulate it, that is why we need to use callMonitored inside it.
+ */
+export function createHandlingStack(
+  type: 'console error' | 'action' | 'error' | 'instrumented method' | 'log' | 'react error'
+): string {
+  /**
+   * Skip the two internal frames:
+   * - SDK API (console.error, ...)
+   * - this function
+   * in order to keep only the user calls
+   */
+  const internalFramesToSkip = 2
+  const error = new Error(type)
+  error.name = 'HandlingStack'
+  let formattedStack: string
+
+  callMonitored(() => {
+    const stackTrace = computeStackTrace(error)
+    stackTrace.stack = stackTrace.stack.slice(internalFramesToSkip)
+    formattedStack = toStackTraceString(stackTrace)
+  })
+
+  return formattedStack!
+}
+
+export function toStackTraceString(stack: StackTrace) {
+  let result = formatErrorMessage(stack)
+  stack.stack.forEach((frame) => {
+    const func = frame.func === '?' ? '<anonymous>' : frame.func
+    const args = frame.args && frame.args.length > 0 ? `(${frame.args.join(', ')})` : ''
+    const line = frame.line ? `:${frame.line}` : ''
+    const column = frame.line && frame.column ? `:${frame.column}` : ''
+    result += `\n  at ${func!}${args} @ ${frame.url!}${line}${column}`
+  })
+  return result
+}
+
+export function formatErrorMessage(stack: StackTrace) {
+  return `${stack.name || 'Error'}: ${stack.message!}`
+}

package/src/tools/taskQueue.ts

@@ -0,0 +1,63 @@
+import { ONE_SECOND } from './utils/timeUtils'
+import { requestIdleCallback } from './requestIdleCallback'
+
+/**
+ * Maximum delay before starting to execute tasks in the queue. We don't want to wait too long
+ * before running tasks, as it might hurt reliability (ex: if the user navigates away, we might lose
+ * the opportunity to send some data). We also don't want to run tasks too often, as it might hurt
+ * performance.
+ */
+const IDLE_CALLBACK_TIMEOUT = ONE_SECOND
+
+/**
+ * Maximum amount of time allocated to running tasks when a timeout (`IDLE_CALLBACK_TIMEOUT`) is
+ * reached. We should not run tasks for too long as it will hurt performance, but we should still
+ * run some tasks to avoid postponing them forever.
+ *
+ * Rational: Running tasks for 30ms every second (IDLE_CALLBACK_TIMEOUT) should be acceptable.
+ */
+export const MAX_EXECUTION_TIME_ON_TIMEOUT = 30
+
+export interface TaskQueue {
+  push(task: Task): void
+  stop(): void
+}
+
+type Task = () => void
+
+export function createTaskQueue(): TaskQueue {
+  const pendingTasks: Task[] = []
+
+  function run(deadline: IdleDeadline) {
+    let executionTimeRemaining: () => number
+    if (deadline.didTimeout) {
+      const start = performance.now()
+      executionTimeRemaining = () => MAX_EXECUTION_TIME_ON_TIMEOUT - (performance.now() - start)
+    } else {
+      executionTimeRemaining = deadline.timeRemaining.bind(deadline)
+    }
+
+    while (executionTimeRemaining() > 0 && pendingTasks.length) {
+      pendingTasks.shift()!()
+    }
+
+    if (pendingTasks.length) {
+      scheduleNextRun()
+    }
+  }
+
+  function scheduleNextRun() {
+    requestIdleCallback(run, { timeout: IDLE_CALLBACK_TIMEOUT })
+  }
+
+  return {
+    push(task) {
+      if (pendingTasks.push(task) === 1) {
+        scheduleNextRun()
+      }
+    },
+    stop() {
+      pendingTasks.length = 0
+    },
+  }
+}