@dash0/sdk-web 0.6.2

package/src/api/init.ts

@@ -0,0 +1,221 @@
+import { Endpoint, Vars, vars } from "../vars";
+import {
+  DEPLOYMENT_ENVIRONMENT_NAME,
+  DEPLOYMENT_ID,
+  DEPLOYMENT_NAME,
+  PAGE_LOAD_ID,
+  SERVICE_NAME,
+  SERVICE_VERSION,
+  USER_AGENT,
+} from "../semantic-conventions";
+import {
+  fetch,
+  generateUniqueId,
+  PAGE_LOAD_ID_BYTES,
+  warn,
+  debug,
+  perf,
+  nav,
+  win,
+  NO_VALUE_FALLBACK,
+  pick,
+} from "../utils";
+import { trackSessions } from "./session";
+import { startWebVitalsInstrumentation } from "../instrumentations/web-vitals";
+import { startErrorInstrumentation } from "../instrumentations/errors";
+import { addAttribute, AttributeValueType } from "../utils/otel";
+import { instrumentFetch } from "../instrumentations/http/fetch";
+import { AnyValue } from "../../types/otlp";
+import { startNavigationInstrumentation } from "../instrumentations/navigation";
+import { merge } from "ts-deepmerge";
+import { initializeTabId } from "../utils/tab-id";
+
+export type InitOptions = {
+  serviceName: string;
+  serviceVersion?: string;
+  environment?: string;
+  deploymentName?: string;
+  deploymentId?: string;
+
+  /**
+   * Additional attributes to include with transmitted signals
+   */
+  additionalSignalAttributes?: Record<string, AttributeValueType | AnyValue>;
+
+  /**
+   * OTLP endpoints to which the generated telemetry should be sent to.
+   */
+  endpoint: Endpoint | Endpoint[];
+
+  /**
+   * The  session inactivity timeout. Session inactivity is the maximum
+   * allowed time to pass between two page loads before the session is considered
+   * to be expired. Also think of cache time-to-idle configuration options.
+   */
+  sessionInactivityTimeoutMillis?: number;
+
+  /**
+   * The default session termination timeout. Session termination is the maximum
+   * allowed time to pass since session start before the session is considered
+   * to be expired. Also think of cache time-to-live configuration options.
+   */
+  sessionTerminationTimeoutMillis?: number;
+} & Partial<
+  Pick<
+    Vars,
+    | "ignoreUrls"
+    | "ignoreErrorMessages"
+    | "wrapEventHandlers"
+    | "wrapTimers"
+    | "propagateTraceHeadersCorsURLs"
+    | "maxWaitForResourceTimingsMillis"
+    | "maxToleranceForResourceTimingsMillis"
+    | "headersToCapture"
+    | "pageViewInstrumentation"
+  >
+>;
+
+let hasBeenInitialised: boolean = false;
+
+export function init(opts: InitOptions) {
+  if (hasBeenInitialised) {
+    debug("Dash0 SDK is being reinitialized, skipping ...");
+    return;
+  }
+
+  if (!isClient()) {
+    debug("Looks like we are not running in a browser context. Stopping Dash0 Web SDK initialization.");
+    return;
+  }
+
+  if (!isSupported()) {
+    debug("Stopping Dash0 Web SDK initialization. This browser does not support the necessary APIs");
+    return;
+  }
+
+  vars.endpoints = opts.endpoint instanceof Array ? opts.endpoint : [opts.endpoint];
+  if (vars.endpoints.length === 0) {
+    warn("No telemetry endpoint configured. Aborting Dash0 Web SDK initialization process.");
+    return;
+  }
+
+  Object.assign(
+    vars,
+    merge(
+      vars,
+      pick(opts, [
+        "ignoreUrls",
+        "ignoreErrorMessages",
+        "wrapEventHandlers",
+        "wrapTimers",
+        "propagateTraceHeadersCorsURLs",
+        "maxWaitForResourceTimingsMillis",
+        "maxToleranceForResourceTimingsMillis",
+        "headersToCapture",
+        "pageViewInstrumentation",
+      ])
+    )
+  );
+
+  initializeResourceAttributes(opts);
+  initializeSignalAttributes(opts);
+  initializeTabId();
+  trackSessions(opts.sessionInactivityTimeoutMillis, opts.sessionTerminationTimeoutMillis);
+  startNavigationInstrumentation();
+  startWebVitalsInstrumentation();
+  startErrorInstrumentation();
+  instrumentFetch();
+
+  hasBeenInitialised = true;
+}
+
+function initializeResourceAttributes(opts: InitOptions) {
+  addAttribute(vars.resource.attributes, SERVICE_NAME, opts["serviceName"]);
+
+  if (opts.serviceVersion) {
+    addAttribute(vars.resource.attributes, SERVICE_VERSION, opts["serviceVersion"]);
+  }
+
+  const env = detectEnvironment(opts);
+  if (env) {
+    addAttribute(vars.resource.attributes, DEPLOYMENT_ENVIRONMENT_NAME, env);
+  }
+
+  const deploymentName = detectDeploymentName(opts);
+  if (deploymentName) {
+    addAttribute(vars.resource.attributes, DEPLOYMENT_NAME, deploymentName);
+  }
+
+  const deploymentId = detectDeploymentId(opts);
+  if (deploymentId) {
+    addAttribute(vars.resource.attributes, DEPLOYMENT_ID, deploymentId);
+  }
+}
+
+function initializeSignalAttributes(opts: InitOptions) {
+  addAttribute(vars.signalAttributes, PAGE_LOAD_ID, generateUniqueId(PAGE_LOAD_ID_BYTES));
+  addAttribute(vars.signalAttributes, USER_AGENT, nav?.userAgent ?? NO_VALUE_FALLBACK);
+
+  if (opts.additionalSignalAttributes) {
+    Object.entries(opts.additionalSignalAttributes).forEach(([key, value]) => {
+      addAttribute(vars.signalAttributes, key, value);
+    });
+  }
+}
+
+function isSupported() {
+  return typeof fetch === "function" && perf && perf.getEntriesByType;
+}
+
+function isClient() {
+  return win != null;
+}
+
+function detectEnvironment(opts: InitOptions): string | undefined {
+  // if there is a manually specified value we use that
+  if (opts.environment) {
+    return opts.environment;
+  }
+
+  // if process isn't defined access to it causes an exception, but we can't check for its present due to how
+  // plugins like webpack define work.
+  try {
+    // vercel
+    // @ts-expect-error -- we need to access like this to allow webpack in the nextjs build to replace this
+    return process?.env?.NEXT_PUBLIC_VERCEL_ENV;
+  } catch (_ignored) {
+    return undefined;
+  }
+}
+
+function detectDeploymentName(opts: InitOptions): string | undefined {
+  if (opts.deploymentName) {
+    return opts.deploymentName;
+  }
+
+  // if process isn't defined access to it causes an exception, but we can't check for its present due to how
+  // plugins like webpack define work.
+  try {
+    // vercel
+    // @ts-expect-error -- we need to access like this to allow webpack in the nextjs build to replace this
+    return process?.env?.NEXT_PUBLIC_VERCEL_TARGET_ENV;
+  } catch (_ignored) {
+    return undefined;
+  }
+}
+
+function detectDeploymentId(opts: InitOptions): string | undefined {
+  if (opts.deploymentId) {
+    return opts.deploymentId;
+  }
+
+  // if process isn't defined access to it causes an exception, but we can't check for its present due to how
+  // plugins like webpack define work.
+  try {
+    // vercel
+    // @ts-expect-error -- we need to access like this to allow webpack in the nextjs build to replace this
+    return process?.env?.NEXT_PUBLIC_VERCEL_BRANCH_URL;
+  } catch (_ignored) {
+    return undefined;
+  }
+}

package/src/api/report-error.ts

@@ -0,0 +1,6 @@
+import { ErrorLike, ReportErrorOpts } from "../../types/errors";
+import { reportError as reportErrorInternal } from "../instrumentations/errors/unhandled-error";
+
+export function reportError(error: string | ErrorLike, opts?: ReportErrorOpts) {
+  reportErrorInternal(error, opts);
+}

package/src/api/session.ts

@@ -0,0 +1,113 @@
+import { isSupported, getItem, setItem, removeItem, SESSION_ID_BYTES } from "../utils";
+import { debug, generateUniqueId, now } from "../utils";
+import { info, warn } from "../utils";
+
+interface Session {
+  id: string;
+  startTime: number;
+  lastActivityTime: number;
+}
+
+const SESSION_STORAGE_KEY = "d0_session";
+const STORAGE_SEPARATOR_KEY = "#";
+const DEFAULT_SESSION_INACTIVITY_TIMEOUT_MILLIS = 1000 * 60 * 60 * 3;
+const DEFAULT_SESSION_TERMINATION_TIMEOUT_MILLIS = 1000 * 60 * 60 * 6;
+const MAX_ALLOWED_SESSION_TIMEOUT_MILLIS = 1000 * 60 * 60 * 24;
+
+export let sessionId: string | null = null;
+
+export function trackSessions(sessionInactivityTimeoutMillis?: number, sessionTerminationTimeoutMillis?: number): void {
+  if (!isSupported) {
+    debug("Storage API is not available and session tracking is therefore not supported.");
+    return;
+  }
+
+  if (!sessionInactivityTimeoutMillis) {
+    sessionInactivityTimeoutMillis = DEFAULT_SESSION_INACTIVITY_TIMEOUT_MILLIS;
+  }
+  if (!sessionTerminationTimeoutMillis) {
+    sessionTerminationTimeoutMillis = DEFAULT_SESSION_TERMINATION_TIMEOUT_MILLIS;
+  }
+  sessionInactivityTimeoutMillis = Math.min(sessionInactivityTimeoutMillis, MAX_ALLOWED_SESSION_TIMEOUT_MILLIS);
+  sessionTerminationTimeoutMillis = Math.min(sessionTerminationTimeoutMillis, MAX_ALLOWED_SESSION_TIMEOUT_MILLIS);
+
+  try {
+    const storedValue = getItem(SESSION_STORAGE_KEY);
+
+    let session = parseSession(storedValue);
+    if (session && !isSessionValid(session, sessionInactivityTimeoutMillis, sessionTerminationTimeoutMillis)) {
+      session = null;
+    }
+
+    if (session) {
+      session.lastActivityTime = now();
+    } else {
+      session = {
+        id: generateUniqueId(SESSION_ID_BYTES),
+        startTime: now(),
+        lastActivityTime: now(),
+      };
+    }
+
+    setItem(SESSION_STORAGE_KEY, serializeSession(session));
+    sessionId = session.id;
+  } catch (e) {
+    warn("Failed to record session information", e);
+  }
+}
+
+export function terminateSession() {
+  sessionId = null;
+
+  if (!isSupported) {
+    return;
+  }
+
+  try {
+    removeItem(SESSION_STORAGE_KEY);
+  } catch (e) {
+    info("Failed to terminate session", e);
+  }
+}
+
+function parseSession(storedValue?: string | null): Session | null {
+  if (!storedValue) {
+    return null;
+  }
+
+  const values = storedValue.split(STORAGE_SEPARATOR_KEY);
+  if (values.length < 3) {
+    return null;
+  }
+
+  const id = values[0];
+  const startTime = parseInt(values[1]!, 10);
+  const lastActivityTime = parseInt(values[2]!, 10);
+  if (!id || isNaN(startTime) || isNaN(lastActivityTime)) {
+    return null;
+  }
+
+  return {
+    id,
+    startTime,
+    lastActivityTime,
+  };
+}
+
+function serializeSession(session: Session): string {
+  return session.id + STORAGE_SEPARATOR_KEY + session.startTime + STORAGE_SEPARATOR_KEY + session.lastActivityTime;
+}
+
+function isSessionValid(
+  session: Session,
+  sessionInactivityTimeoutMillis: number,
+  sessionTerminationTimeoutMillis: number
+): boolean {
+  const minAllowedLastActivityTime = now() - sessionInactivityTimeoutMillis;
+  if (session.lastActivityTime < minAllowedLastActivityTime) {
+    return false;
+  }
+
+  const minAllowedStartTime = now() - sessionTerminationTimeoutMillis;
+  return session.startTime >= minAllowedStartTime;
+}

package/src/attributes/common.ts

@@ -0,0 +1,42 @@
+import { KeyValue } from "../../types/otlp";
+import { nav, NO_VALUE_FALLBACK, win } from "../utils";
+import {
+  BROWSER_TAB_ID,
+  NETWORK_CONNECTION_TYPE,
+  SESSION_ID,
+  WINDOW_HEIGHT,
+  WINDOW_WIDTH,
+} from "../semantic-conventions";
+import { sessionId } from "../api/session";
+import { vars } from "../vars";
+import { addAttribute } from "../utils/otel";
+import { addUrlAttributes } from "./url";
+import { tabId } from "../utils/tab-id";
+
+type Options = {
+  url?: string | URL;
+};
+
+export function addCommonAttributes(attributes: KeyValue[], options?: Options): void {
+  for (let i = 0; i < vars.signalAttributes.length; i++) {
+    attributes.push(vars.signalAttributes[i]!);
+  }
+
+  addUrlAttributes(attributes, options?.url ?? win?.location.href ?? NO_VALUE_FALLBACK);
+
+  if (sessionId) {
+    addAttribute(attributes, SESSION_ID, sessionId);
+  }
+  if (tabId) {
+    addAttribute(attributes, BROWSER_TAB_ID, tabId);
+  }
+
+  addAttribute(attributes, WINDOW_WIDTH, win?.innerWidth ?? NO_VALUE_FALLBACK);
+  addAttribute(attributes, WINDOW_HEIGHT, win?.innerHeight ?? NO_VALUE_FALLBACK);
+
+  // @ts-expect-error -- TypeScript is not aware of navigator.connection.effectiveType
+  const connectionType = nav?.connection?.effectiveType;
+  if (connectionType) {
+    addAttribute(attributes, NETWORK_CONNECTION_TYPE, connectionType);
+  }
+}

package/src/attributes/index.ts

@@ -0,0 +1,2 @@
+export * from "./common";
+export * from "./url";

package/src/attributes/url.ts

@@ -0,0 +1,25 @@
+import { KeyValue } from "../../types/otlp";
+import { addAttribute } from "../utils/otel";
+import { URL_DOMAIN, URL_FRAGMENT, URL_FULL, URL_PATH, URL_QUERY, URL_SCHEME } from "../semantic-conventions";
+import { parseUrl } from "../utils/url";
+
+export function addUrlAttributes(attributes: KeyValue[], url: string | URL) {
+  try {
+    const parsed = parseUrl(url);
+    if (parsed.username) parsed.username = "REDACTED";
+    if (parsed.password) parsed.password = "REDACTED";
+
+    addAttribute(attributes, URL_FULL, parsed.href);
+    addAttribute(attributes, URL_PATH, parsed.pathname);
+    addAttribute(attributes, URL_DOMAIN, parsed.hostname);
+    addAttribute(attributes, URL_SCHEME, parsed.protocol.replace(":", ""));
+    if (parsed.hash) {
+      addAttribute(attributes, URL_FRAGMENT, parsed.hash.replace("#", ""));
+    }
+    if (parsed.search) {
+      addAttribute(attributes, URL_QUERY, parsed.search.replace("?", ""));
+    }
+  } catch (_e) {
+    addAttribute(attributes, URL_FULL, String(url));
+  }
+}

package/src/entrypoint/npm-package.ts

@@ -0,0 +1,14 @@
+import { debug, INIT_MESSAGE } from "../utils";
+import { init as initApi, InitOptions } from "../api/init";
+
+export * from "../api/identify";
+export * from "../api/debug";
+export * from "../api/attributes";
+export * from "../api/events";
+export { terminateSession } from "../api/session";
+export { reportError } from "../api/report-error";
+
+export function init(opts: InitOptions): void {
+  debug(`${INIT_MESSAGE} (via package)`);
+  initApi(opts);
+}

package/src/entrypoint/script-tag.html

@@ -0,0 +1,23 @@
+<script>
+  (function (d, a, s, h, z, e, r, o) {
+    d[a] ||
+      ((z = d[a] =
+        function () {
+          h.push(arguments);
+        }),
+      (z._t = new Date()),
+      (z._v = 1),
+      (h = z._q = []));
+  })(window, "dash0");
+  dash0("init", {
+    serviceName: "dash0.com",
+    serviceVersion: "1.2.3",
+    environment: "production",
+    endpoint: {
+      url: "https://ingress.eu-west-1.aws.dash0-dev.com",
+      authToken: "auth_abc123",
+      dataset: "production",
+    },
+  });
+</script>
+<script defer crossorigin="anonymous" src="dash0.min.js"></script>

package/src/entrypoint/script.ts

@@ -0,0 +1,82 @@
+import { win, debug, warn, INIT_MESSAGE } from "../utils";
+
+import { reportError } from "../api/report-error";
+import { identify } from "../api/identify";
+import { debug as debugApi } from "../api/debug";
+import { init as initApi } from "../api/init";
+import { terminateSession } from "../api/session";
+import { addSignalAttribute, removeSignalAttribute } from "../api/attributes";
+import { sendEvent } from "../api/events";
+
+/**
+ * All the APIs exposed through the script tag via `dash0('{{api name}}')`
+ */
+const scriptApis = {
+  init: initApi,
+  debug: debugApi,
+  identify,
+  terminateSession,
+  reportError,
+  addSignalAttribute,
+  removeSignalAttribute,
+  sendEvent,
+} as const;
+
+type GlobalObject = {
+  /**
+   * Queued API calls. We will work through this queue during the initialization and then set it to `undefined`
+   * afterward to signal completion
+   */
+  _q?: Array<IArguments>;
+};
+
+init();
+
+function init(): void {
+  debug(`${INIT_MESSAGE} (via Script)`);
+
+  const globalObject: GlobalObject = (win as any)["dash0"] as GlobalObject;
+
+  if (!globalObject) {
+    warn("global 'dash0' not found. Did you use the correct Dash0 Web SDK initializer?");
+    return;
+  }
+
+  if (!globalObject["_q"]) {
+    warn("Dash0 Web SDK command queue not defined. Did you add the script tag multiple times to your website?");
+    return;
+  }
+
+  processQueuedApiCalls(globalObject["_q"]);
+  addApiCallAfterInitializationSupport();
+}
+
+function processQueuedApiCalls(apiCalls: Array<any>) {
+  for (let i = 0, len = apiCalls.length; i < len; i++) {
+    processQueuedApiCall(apiCalls[i]);
+  }
+}
+
+function processQueuedApiCall(apiCall: IArguments) {
+  const apiName = apiCall[0];
+  // @ts-expect-error the APIs are dynamic
+  const apiFn = scriptApis[apiName] as (typeof scriptApis)[apiName];
+
+  if (!apiFn) {
+    warn("Unsupported Dash0 Web SDK api: ", apiCall[0]);
+    return;
+  }
+
+  const args: any[] = [];
+  for (let i = 1; i < apiCall.length; i++) {
+    args.push(apiCall[i]);
+  }
+
+  apiFn.apply(null, args);
+}
+
+function addApiCallAfterInitializationSupport() {
+  (win as any)["dash0"] = function () {
+    return processQueuedApiCall(arguments as any);
+  };
+}

package/src/instrumentations/errors/async-function-wrapping.ts

@@ -0,0 +1,157 @@
+const WRAPPED_EVENT_HANDLERS_ORIGINAL_FUNCTION_STORAGE_KEY = "__dash0OriginalFunctions";
+
+export type EventListenerOptionsOrUseCapture =
+  | boolean
+  | {
+      capture?: boolean;
+    };
+
+// Asynchronous function wrapping: The process of wrapping a listener which goes into one function, e.g.
+//
+//  - EventTarget#addEventListener
+//  - EventEmitter#on
+//
+// and is removed via another function, e.g.
+//
+//  - EventTarget#removeEventListener
+//  - EventEmitter#off
+//
+// What is complicated about this, is that these methods identify registered listeners by function reference.
+// When we wrap a function, we naturally change the reference. We must therefore keep track of which
+// original function belongs to what wrapped function.
+//
+// This file provides helpers that help in the typical cases. It is removed from all browser specific APIs
+// in order to allow simple unit test execution.
+//
+// Note that this file follows the behavior outlined in DOM specification. Among others, this means that it is not
+// possible to register the same listener twice.
+// http://dom.spec.whatwg.org
+
+export function addWrappedFunction(
+  storageTarget: EventTarget,
+  wrappedFunction: EventListenerOrEventListenerObject,
+  valuesForEqualityCheck: any[]
+): EventListenerOrEventListenerObject {
+  if (!storageTarget) return wrappedFunction;
+
+  const storage = ((storageTarget as any)[WRAPPED_EVENT_HANDLERS_ORIGINAL_FUNCTION_STORAGE_KEY] =
+    (storageTarget as any)[WRAPPED_EVENT_HANDLERS_ORIGINAL_FUNCTION_STORAGE_KEY] || []);
+  const index = findInStorage(storageTarget, valuesForEqualityCheck);
+  if (index !== -1) {
+    // already registered. Do not allow re-registration
+    return storage[index].wrappedFunction;
+  }
+
+  storage.push({
+    wrappedFunction,
+    valuesForEqualityCheck,
+  });
+  return wrappedFunction;
+}
+
+function findInStorage(storageTarget: EventTarget, valuesForEqualityCheck: any[]): number {
+  const storage = (storageTarget as any)[WRAPPED_EVENT_HANDLERS_ORIGINAL_FUNCTION_STORAGE_KEY];
+  for (let i = 0; i < storage.length; i++) {
+    const storageItem = storage[i];
+
+    if (matchesEqualityCheck(storageItem.valuesForEqualityCheck, valuesForEqualityCheck)) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+export function popWrappedFunction(
+  storageTarget: EventTarget,
+  valuesForEqualityCheck: any[],
+  fallback?: EventListenerOrEventListenerObject
+): EventListenerOrEventListenerObject | undefined {
+  const storage = (storageTarget as any)?.[WRAPPED_EVENT_HANDLERS_ORIGINAL_FUNCTION_STORAGE_KEY];
+  if (storage == null) {
+    return fallback;
+  }
+
+  const index = findInStorage(storageTarget, valuesForEqualityCheck);
+  if (index === -1) {
+    return fallback;
+  }
+
+  const storageItem = storage[index];
+  storage.splice(index, 1);
+  return storageItem.wrappedFunction;
+}
+
+function matchesEqualityCheck(valuesForEqualityCheckA: any, valuesForEqualityCheckB: any) {
+  if (valuesForEqualityCheckA.length !== valuesForEqualityCheckB.length) {
+    return false;
+  }
+
+  for (let i = 0; i < valuesForEqualityCheckA.length; i++) {
+    if (valuesForEqualityCheckA[i] !== valuesForEqualityCheckB[i]) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export function addWrappedDomEventListener(
+  storageTarget: EventTarget,
+  wrappedFunction: EventListenerOrEventListenerObject,
+  eventName: string,
+  eventListener: EventListenerOrEventListenerObject,
+  optionsOrCapture?: EventListenerOptionsOrUseCapture
+): EventListenerOrEventListenerObject {
+  return addWrappedFunction(
+    storageTarget,
+    wrappedFunction,
+    getDomEventListenerValuesForEqualityCheck(eventName, eventListener, optionsOrCapture)
+  );
+}
+
+function getDomEventListenerValuesForEqualityCheck(
+  eventName: string,
+  eventListener: EventListenerOrEventListenerObject,
+  optionsOrCapture?: EventListenerOptionsOrUseCapture
+): any[] {
+  return [eventName, eventListener, getDomEventListenerCaptureValue(optionsOrCapture)];
+}
+
+export function getDomEventListenerCaptureValue(optionsOrCapture?: EventListenerOptionsOrUseCapture): boolean {
+  // > Let capture, passive, and once be the result of flattening more options.
+  // https://dom.spec.whatwg.org/#dom-eventtarget-addeventlistener
+  //
+  // > To flatten more options, run these steps:
+  // > 1. Let capture be the result of flattening options.
+  // https://dom.spec.whatwg.org/#event-flatten-more
+  //
+  // > To flatten options, run these steps:
+  // > 1. If options is a boolean, then return options.
+  // > 2. Return options’s capture.
+  // https://dom.spec.whatwg.org/#concept-flatten-options
+  //
+  // > dictionary EventListenerOptions {
+  // >   boolean capture = false;
+  // > };
+  // https://dom.spec.whatwg.org/#dom-eventlisteneroptions-capture
+  if (optionsOrCapture == null) {
+    return false;
+  } else if (typeof optionsOrCapture === "object") {
+    return Boolean(optionsOrCapture.capture);
+  }
+  return Boolean(optionsOrCapture);
+}
+
+export function popWrappedDomEventListener(
+  storageTarget: EventTarget,
+  eventName: string,
+  eventListener: EventListenerOrEventListenerObject,
+  optionsOrCapture?: EventListenerOptionsOrUseCapture,
+  fallback?: EventListenerOrEventListenerObject
+): EventListenerOrEventListenerObject | undefined {
+  return popWrappedFunction(
+    storageTarget,
+    getDomEventListenerValuesForEqualityCheck(eventName, eventListener, optionsOrCapture),
+    fallback
+  );
+}