@kubesense/kubesense-browser-core 1.0.0

package/src/tools/stackTrace/computeStackTrace.ts

@@ -0,0 +1,251 @@
+/**
+ * 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 KubesenseTestCustomError extends Error {
+    constructor() {
+      super()
+      this.name = 'Error' // set name to Error so that no browser would default to the constructor name
+    }
+  }
+
+  const [customError, nativeError] = [KubesenseTestCustomError, 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
+    },
+  }
+}

package/src/tools/timer.ts

@@ -0,0 +1,21 @@
+import { getZoneJsOriginalValue } from './getZoneJsOriginalValue'
+import { monitor } from './monitor'
+import { getGlobalObject } from './globalObject'
+
+export type TimeoutId = ReturnType<typeof globalThis.setTimeout>
+
+export function setTimeout(callback: () => void, delay?: number): TimeoutId {
+  return getZoneJsOriginalValue(getGlobalObject(), 'setTimeout')(monitor(callback), delay)
+}
+
+export function clearTimeout(timeoutId: TimeoutId | undefined) {
+  getZoneJsOriginalValue(getGlobalObject(), 'clearTimeout')(timeoutId)
+}
+
+export function setInterval(callback: () => void, delay?: number): TimeoutId {
+  return getZoneJsOriginalValue(getGlobalObject(), 'setInterval')(monitor(callback), delay)
+}
+
+export function clearInterval(timeoutId: TimeoutId | undefined) {
+  getZoneJsOriginalValue(getGlobalObject(), 'clearInterval')(timeoutId)
+}

package/src/tools/utils/arrayUtils.ts

@@ -0,0 +1,16 @@
+export function removeDuplicates<T>(array: T[]) {
+  const set = new Set<T>()
+  array.forEach((item) => set.add(item))
+  return Array.from(set)
+}
+
+export function removeItem<T>(array: T[], item: T) {
+  const index = array.indexOf(item)
+  if (index >= 0) {
+    array.splice(index, 1)
+  }
+}
+
+export function isNonEmptyArray<T>(value: unknown): value is T[] {
+  return Array.isArray(value) && value.length > 0
+}

package/src/tools/utils/browserDetection.ts

@@ -0,0 +1,39 @@
+// Exported only for tests
+export const enum Browser {
+  CHROMIUM,
+  SAFARI,
+  OTHER,
+}
+
+export function isChromium() {
+  return detectBrowserCached() === Browser.CHROMIUM
+}
+
+export function isSafari() {
+  return detectBrowserCached() === Browser.SAFARI
+}
+
+let browserCache: Browser | undefined
+function detectBrowserCached() {
+  return browserCache ?? (browserCache = detectBrowser())
+}
+
+// Exported only for tests
+export function detectBrowser(browserWindow: Window = window) {
+  const userAgent = browserWindow.navigator.userAgent
+  if ((browserWindow as any).chrome || /HeadlessChrome/.test(userAgent)) {
+    return Browser.CHROMIUM
+  }
+
+  if (
+    // navigator.vendor is deprecated, but it is the most resilient way we found to detect
+    // "Apple maintained browsers" (AKA Safari). If one day it gets removed, we still have the
+    // useragent test as a semi-working fallback.
+    browserWindow.navigator.vendor?.indexOf('Apple') === 0 ||
+    (/safari/i.test(userAgent) && !/chrome|android/i.test(userAgent))
+  ) {
+    return Browser.SAFARI
+  }
+
+  return Browser.OTHER
+}

package/src/tools/utils/byteUtils.ts

@@ -0,0 +1,40 @@
+export const ONE_KIBI_BYTE = 1024
+export const ONE_MEBI_BYTE = 1024 * ONE_KIBI_BYTE
+
+// eslint-disable-next-line no-control-regex
+const HAS_MULTI_BYTES_CHARACTERS = /[^\u0000-\u007F]/
+
+export interface Uint8ArrayBuffer extends Uint8Array {
+  readonly buffer: ArrayBuffer
+
+  subarray(begin?: number, end?: number): Uint8ArrayBuffer
+}
+
+export function computeBytesCount(candidate: string): number {
+  // Accurate bytes count computations can degrade performances when there is a lot of events to process
+  if (!HAS_MULTI_BYTES_CHARACTERS.test(candidate)) {
+    return candidate.length
+  }
+
+  if (window.TextEncoder !== undefined) {
+    return new TextEncoder().encode(candidate).length
+  }
+
+  return new Blob([candidate]).size
+}
+
+export function concatBuffers(buffers: Uint8ArrayBuffer[]): Uint8ArrayBuffer {
+  // Optimization: if there is a single buffer, no need to copy it
+  if (buffers.length === 1) {
+    return buffers[0]
+  }
+  
+  const length = buffers.reduce((total, buffer) => total + buffer.length, 0)
+  const result: Uint8ArrayBuffer = new Uint8Array(length)
+  let offset = 0
+  for (const buffer of buffers) {
+    result.set(buffer, offset)
+    offset += buffer.length
+  }
+  return result
+}

package/src/tools/utils/functionUtils.ts

@@ -0,0 +1,45 @@
+import type { TimeoutId } from '../timer'
+import { setTimeout, clearTimeout } from '../timer'
+
+// use lodash API
+export function throttle<T extends (...args: any[]) => void>(
+  fn: T,
+  wait: number,
+  options?: { leading?: boolean; trailing?: boolean }
+) {
+  const needLeadingExecution = options && options.leading !== undefined ? options.leading : true
+  const needTrailingExecution = options && options.trailing !== undefined ? options.trailing : true
+  let inWaitPeriod = false
+  let pendingExecutionWithParameters: Parameters<T> | undefined
+  let pendingTimeoutId: TimeoutId
+
+  return {
+    throttled: (...parameters: Parameters<T>) => {
+      if (inWaitPeriod) {
+        pendingExecutionWithParameters = parameters
+        return
+      }
+      if (needLeadingExecution) {
+        fn(...parameters)
+      } else {
+        pendingExecutionWithParameters = parameters
+      }
+      inWaitPeriod = true
+      pendingTimeoutId = setTimeout(() => {
+        if (needTrailingExecution && pendingExecutionWithParameters) {
+          fn(...pendingExecutionWithParameters)
+        }
+        inWaitPeriod = false
+        pendingExecutionWithParameters = undefined
+      }, wait)
+    },
+    cancel: () => {
+      clearTimeout(pendingTimeoutId)
+      inWaitPeriod = false
+      pendingExecutionWithParameters = undefined
+    },
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+export function noop() {}

package/src/tools/utils/numberUtils.ts

@@ -0,0 +1,19 @@
+/**
+ * Return true if the draw is successful
+ * @param threshold - Threshold between 0 and 100
+ */
+export function performDraw(threshold: number): boolean {
+  return threshold !== 0 && Math.random() * 100 <= threshold
+}
+
+export function round(num: number, decimals: 0 | 1 | 2 | 3 | 4) {
+  return +num.toFixed(decimals)
+}
+
+export function isPercentage(value: unknown) {
+  return isNumber(value) && value >= 0 && value <= 100
+}
+
+export function isNumber(value: unknown): value is number {
+  return typeof value === 'number'
+}

package/src/tools/utils/objectUtils.ts

@@ -0,0 +1,19 @@
+export function shallowClone<T>(object: T): T & Record<string, never> {
+  return { ...object } as T & Record<string, never>
+}
+
+export function objectHasValue<T extends { [key: string]: unknown }>(object: T, value: unknown): value is T[keyof T] {
+  return Object.keys(object).some((key) => object[key] === value)
+}
+
+export function isEmptyObject(object: object) {
+  return Object.keys(object).length === 0
+}
+
+export function mapValues<A, B>(object: { [key: string]: A }, fn: (arg: A) => B) {
+  const newObject: { [key: string]: B } = {}
+  for (const key of Object.keys(object)) {
+    newObject[key] = fn(object[key])
+  }
+  return newObject
+}

package/src/tools/utils/polyfills.ts

@@ -0,0 +1,23 @@
+export function findLast<T, S extends T>(
+  array: readonly T[],
+  predicate: (item: T, index: number, array: readonly T[]) => item is S
+): S | undefined {
+  for (let i = array.length - 1; i >= 0; i -= 1) {
+    const item = array[i]
+    if (predicate(item, i, array)) {
+      return item
+    }
+  }
+  return undefined
+}
+
+// Keep the following wrapper functions as it can be mangled and will result in smaller bundle size that using
+// the native Object.values and Object.entries directly
+
+export function objectValues<T = unknown>(object: { [key: string]: T }) {
+  return Object.values(object)
+}
+
+export function objectEntries<T = unknown>(object: { [key: string]: T }): Array<[string, T]> {
+  return Object.entries(object)
+}

package/src/tools/utils/responseUtils.ts

@@ -0,0 +1,12 @@
+export function isServerError(status: number) {
+  return status >= 500
+}
+
+export function tryToClone(response: Response): Response | undefined {
+  try {
+    return response.clone()
+  } catch {
+    // clone can throw if the response has already been used by another instrumentation or is disturbed
+    return
+  }
+}

package/src/tools/utils/stringUtils.ts

@@ -0,0 +1,86 @@
+/**
+ * UUID v4
+ * from https://gist.github.com/jed/982883
+ */
+export function generateUUID(placeholder?: string): string {
+  return placeholder
+    ? // eslint-disable-next-line  no-bitwise
+      (parseInt(placeholder, 10) ^ ((Math.random() * 16) >> (parseInt(placeholder, 10) / 4))).toString(16)
+    : `${1e7}-${1e3}-${4e3}-${8e3}-${1e11}`.replace(/[018]/g, generateUUID)
+}
+
+const COMMA_SEPARATED_KEY_VALUE = /([\w-]+)\s*=\s*([^;]+)/g
+
+/**
+ * Returns the value of the key with the given name
+ * If there are multiple values with the same key, returns the first one
+ */
+export function findCommaSeparatedValue(rawString: string, name: string): string | undefined {
+  COMMA_SEPARATED_KEY_VALUE.lastIndex = 0
+  while (true) {
+    const match = COMMA_SEPARATED_KEY_VALUE.exec(rawString)
+    if (match) {
+      if (match[1] === name) {
+        return match[2]
+      }
+    } else {
+      break
+    }
+  }
+}
+
+/**
+ * Returns a map of all the values with the given key
+ * If there are multiple values with the same key, returns all the values
+ */
+export function findAllCommaSeparatedValues(rawString: string): Map<string, string[]> {
+  const result = new Map<string, string[]>()
+  COMMA_SEPARATED_KEY_VALUE.lastIndex = 0
+  while (true) {
+    const match = COMMA_SEPARATED_KEY_VALUE.exec(rawString)
+    if (match) {
+      const key = match[1]
+      const value = match[2]
+      if (result.has(key)) {
+        result.get(key)!.push(value)
+      } else {
+        result.set(key, [value])
+      }
+    } else {
+      break
+    }
+  }
+  return result
+}
+
+/**
+ * Returns a map of the values with the given key
+ * ⚠️ If there are multiple values with the same key, returns the LAST one
+ *
+ * @deprecated use `findAllCommaSeparatedValues()` instead
+ */
+export function findCommaSeparatedValues(rawString: string): Map<string, string> {
+  const result = new Map<string, string>()
+  COMMA_SEPARATED_KEY_VALUE.lastIndex = 0
+  while (true) {
+    const match = COMMA_SEPARATED_KEY_VALUE.exec(rawString)
+    if (match) {
+      result.set(match[1], match[2])
+    } else {
+      break
+    }
+  }
+  return result
+}
+
+export function safeTruncate(candidate: string, length: number, suffix = '') {
+  const lastChar = candidate.charCodeAt(length - 1)
+  const isLastCharSurrogatePair = lastChar >= 0xd800 && lastChar <= 0xdbff
+  const correctedLength = isLastCharSurrogatePair ? length + 1 : length
+
+  if (candidate.length <= correctedLength) {
+    return candidate
+  }
+
+  return `${candidate.slice(0, correctedLength)}${suffix}`
+}