@newrelic/browser-agent 0.0.9 → 0.1.229

package/dist/esm/common/window/nreum.js

@@ -0,0 +1,91 @@
+import { now } from '../timing/now';
+import { globalScope } from '../util/global-scope';
+export const defaults = {
+  beacon: 'bam.nr-data.net',
+  errorBeacon: 'bam.nr-data.net'
+};
+export function gosNREUM() {
+  if (!globalScope.NREUM) {
+    globalScope.NREUM = {};
+  }
+  if (typeof globalScope.newrelic === 'undefined') globalScope.newrelic = globalScope.NREUM;
+  return globalScope.NREUM;
+}
+export function gosNREUMInfo() {
+  let nr = gosNREUM();
+  const externallySupplied = nr.info || {};
+  nr.info = {
+    beacon: defaults.beacon,
+    errorBeacon: defaults.errorBeacon,
+    ...externallySupplied
+  };
+  return nr;
+}
+export function gosNREUMLoaderConfig() {
+  let nr = gosNREUM();
+  const externallySupplied = nr.loader_config || {};
+  nr.loader_config = {
+    ...externallySupplied
+  };
+  return nr;
+}
+export function gosNREUMInit() {
+  let nr = gosNREUM();
+  const externallySupplied = nr.init || {};
+  nr.init = {
+    ...externallySupplied
+  };
+  return nr;
+}
+export function gosNREUMOriginals() {
+  let nr = gosNREUM();
+  if (!nr.o) {
+    nr.o = {
+      ST: globalScope.setTimeout,
+      SI: globalScope.setImmediate,
+      CT: globalScope.clearTimeout,
+      XHR: globalScope.XMLHttpRequest,
+      REQ: globalScope.Request,
+      EV: globalScope.Event,
+      PR: globalScope.Promise,
+      MO: globalScope.MutationObserver,
+      // this'll be undefined if not in a web window
+      FETCH: globalScope.fetch
+    };
+  }
+  return nr;
+}
+export function gosNREUMInitializedAgents(id, obj, target) {
+  let nr = gosNREUM();
+  const externallySupplied = nr.initializedAgents || {};
+  const curr = externallySupplied[id] || {};
+  if (!Object.keys(curr).length) {
+    curr.initializedAt = {
+      ms: now(),
+      date: new Date()
+    };
+  }
+  nr.initializedAgents = {
+    ...externallySupplied,
+    [id]: {
+      ...curr,
+      [target]: obj
+    }
+  };
+  return nr;
+}
+export function addToNREUM(fnName, fn) {
+  let nr = gosNREUM();
+  nr[fnName] = fn;
+}
+export function NREUMinitialized() {
+  const nr = gosNREUM();
+  nr.initialized = true;
+}
+export function gosCDN() {
+  gosNREUMInfo();
+  gosNREUMInit();
+  gosNREUMOriginals();
+  gosNREUMLoaderConfig();
+  return gosNREUM();
+}

package/dist/esm/common/window/page-visibility.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2020 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { documentAddEventListener } from '../event-listener/event-listener-opts';
+
+/**
+ * @param {function} cb - called when a visibility change occurs with the vis state at that time
+ * @param {boolean} [toHiddenOnly=false] - only execute the 'cb' when the vis is changing to the hidden state; no arg is passed to 'cb' if used
+ * @returns void
+ */
+export function subscribeToVisibilityChange(cb, toHiddenOnly = false) {
+  documentAddEventListener('visibilitychange', handleVisibilityChange);
+  return;
+  function handleVisibilityChange() {
+    if (toHiddenOnly) {
+      // trigger cb on change to hidden state only
+      if (document.visibilityState == 'hidden') cb();else return;
+    }
+    cb(document.visibilityState);
+  }
+}

package/dist/esm/common/window/session-storage.js

@@ -0,0 +1,36 @@
+/**
+ * Interface for Agents' usage of the Window.sessionStorage as a replacement to third-party cookies.
+ *  (All agents on a tab|window will share the same sessionStorage.)
+ *
+ * @design https://newrelic.atlassian.net/wiki/spaces/INST/pages/2522513791/JSESSIONID+Cookie+Change+Design+Document
+ * @environment Browser script
+ */
+import { generateRandomHexString } from '../ids/unique-id';
+import { isBrowserScope } from '../util/global-scope';
+export { getCurrentSessionIdOrMakeNew };
+const SESS_ID = 'NRBA_SESSION_ID'; // prevents potential key collisions in session storage
+
+/**
+ * @returns {string} This tab|window's session identifier, or a new ID if not found in storage
+ */
+function getCurrentSessionIdOrMakeNew() {
+  if (!isBrowserScope) {
+    return null;
+  }
+  try {
+    let sessionId;
+    if ((sessionId = window.sessionStorage.getItem(SESS_ID)) === null) {
+      // Generate a new one if storage is empty (no previous ID was created or currently exists)
+      sessionId = generateRandomHexString(16);
+      window.sessionStorage.setItem(SESS_ID, sessionId);
+    }
+    return sessionId;
+  } catch (ex) {
+    // Session storage quota most likely 0mb and cannot be written to
+    // OR the agent is running in a security context that does not allow
+    // access to the browser sessionStorage
+    return null;
+  }
+}
+
+// In the future, we may expand sessionStorage to, say, auto-save some other agent data between page refreshes.

package/dist/esm/common/window/supports-performance-observer.js

@@ -0,0 +1,9 @@
+/*
+ * Copyright 2020 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { globalScope } from '../util/global-scope';
+export function supportsPerformanceObserver() {
+  return typeof globalScope?.PerformanceObserver === 'function';
+}

package/dist/esm/common/window/top-level-callers.js

@@ -0,0 +1,17 @@
+import { gosCDN } from './nreum';
+export function setTopLevelCallers() {
+  const nr = gosCDN();
+  const funcs = ['setErrorHandler', 'finished', 'addToTrace', 'inlineHit', 'addRelease', 'addPageAction', 'setCurrentRouteName', 'setPageViewName', 'setCustomAttribute', 'interaction', 'noticeError'];
+  funcs.forEach(f => {
+    nr[f] = (...args) => caller(f, ...args);
+  });
+  function caller(fnName, ...args) {
+    let returnVals = [];
+    Object.values(nr.initializedAgents).forEach(val => {
+      if (val.exposed && val.api[fnName]) {
+        returnVals.push(val.api[fnName](...args));
+      }
+    });
+    return returnVals.length > 1 ? returnsVals : returnVals[0];
+  }
+}

package/dist/esm/common/wrap/index.js

@@ -0,0 +1,14 @@
+/**
+ * @file Wraps assorted native objects and functions for instrumentation.
+ */
+
+import { wrapFetch } from './wrap-fetch';
+import { wrapTimer } from './wrap-timer';
+import { wrapRaf } from './wrap-raf';
+import { wrapHistory } from './wrap-history';
+import { wrapJsonP } from './wrap-jsonp';
+import { wrapMutation } from './wrap-mutation';
+import { wrapPromise } from './wrap-promise';
+import { wrapXhr } from './wrap-xhr';
+import { wrapEvents } from './wrap-events';
+export { wrapEvents, wrapFetch, wrapHistory, wrapJsonP, wrapMutation, wrapPromise, wrapRaf, wrapTimer, wrapXhr };

package/dist/esm/common/wrap/wrap-events.js

@@ -0,0 +1,97 @@
+/*
+ * Copyright 2020 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @file Wraps `addEventListener` and `removeEventListener` for instrumentation.
+ * This module is used directly by: session_trace.
+ * It is also called by -> wrapXhr <-, so see "wrap-xhr.js" for features that use this indirectly.
+ */
+import { ee as baseEE } from '../event-emitter/contextual-ee';
+import { createWrapperWithEmitter as wfn, unwrapFunction } from './wrap-function';
+import { getOrSet } from '../util/get-or-set';
+import { globalScope, isBrowserScope } from '../util/global-scope';
+const wrapped = {};
+const XHR = XMLHttpRequest;
+const ADD_EVENT_LISTENER = 'addEventListener';
+const REMOVE_EVENT_LISTENER = 'removeEventListener';
+
+/**
+ * Wraps `addEventListener` and `removeEventListener` on: global scope; the prototype of `XMLHttpRequest`, and
+ * `document` (if in a browser scope). Adds custom events in context of a new emitter scoped only to these methods.
+ * @param {Object} sharedEE - The shared event emitter on which a new scoped
+ *     event emitter will be based.
+ * @returns {Object} Scoped event emitter with a debug ID of `events`.
+ */
+export function wrapEvents(sharedEE) {
+  var ee = scopedEE(sharedEE);
+  if (wrapped[ee.debugId]++)
+    // Notice if our wrapping never ran yet, the falsey NaN will not early return; but if it has,
+    {
+      return ee;
+    } // then we increment the count to track # of feats using this at runtime.
+  wrapped[ee.debugId] = 1;
+  var wrapFn = wfn(ee, true);
+
+  // Guard against instrumenting environments w/o necessary features
+  if ('getPrototypeOf' in Object) {
+    if (isBrowserScope) {
+      findEventListenerProtoAndCb(document, wrapNode);
+    }
+    findEventListenerProtoAndCb(globalScope, wrapNode);
+    findEventListenerProtoAndCb(XHR.prototype, wrapNode);
+  }
+  ee.on(ADD_EVENT_LISTENER + '-start', function (args, target) {
+    var originalListener = args[1];
+    if (originalListener === null || typeof originalListener !== 'function' && typeof originalListener !== 'object') {
+      return;
+    }
+    var wrapped = getOrSet(originalListener, 'nr@wrapped', function () {
+      var listener = {
+        object: wrapHandleEvent,
+        function: originalListener
+      }[typeof originalListener];
+      return listener ? wrapFn(listener, 'fn-', null, listener.name || 'anonymous') : originalListener;
+      function wrapHandleEvent() {
+        if (typeof originalListener.handleEvent !== 'function') return;
+        return originalListener.handleEvent.apply(originalListener, arguments);
+      }
+    });
+    this.wrapped = args[1] = wrapped;
+  });
+  ee.on(REMOVE_EVENT_LISTENER + '-start', function (args) {
+    args[1] = this.wrapped || args[1];
+  });
+  function wrapNode(node) {
+    wrapFn.inPlace(node, [ADD_EVENT_LISTENER, REMOVE_EVENT_LISTENER], '-', uniqueListener);
+  }
+  function uniqueListener(args, obj) {
+    // Context for the listener is stored on itself.
+    return args[1];
+  }
+  return ee;
+}
+/**
+ * Find the base prototype of 'object' that has its own "addEventListener" property, and run some function on it.
+ * @param {Object} object - the initial object to traverse prototype chain on
+ * @param {Function} cb - the function to run on the ancestral object once found, accepts an object as a arg
+ * @param {Array} rest - [optional] any additional arguments to pass to the cb
+ */
+function findEventListenerProtoAndCb(object, cb, ...rest) {
+  let step = object;
+  while (typeof step === 'object' && !Object.prototype.hasOwnProperty.call(step, ADD_EVENT_LISTENER)) {
+    step = Object.getPrototypeOf(step);
+  }
+  if (step) cb(step, ...rest);
+}
+
+/**
+ * Returns an event emitter scoped specifically for the `events` context. This scoping is a remnant from when all the
+ * features shared the same group in the event, to isolate events between features. It will likely be revisited.
+ * @param {Object} sharedEE - Optional event emitter on which to base the scoped emitter.
+ *     Uses `ee` on the global scope if undefined).
+ * @returns {Object} Scoped event emitter with a debug ID of 'events'.
+ */
+export function scopedEE(sharedEE) {
+  return (sharedEE || baseEE).get('events');
+}

package/dist/esm/common/wrap/wrap-fetch.js

@@ -0,0 +1,105 @@
+/*
+ * Copyright 2020 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @file Wraps `fetch` and related methods for instrumentation.
+ * This module is used by: ajax, spa.
+ */
+import { ee as baseEE } from '../event-emitter/contextual-ee';
+import slice from 'lodash._slice';
+import { globalScope } from '../util/global-scope';
+import { flag, unwrapFunction } from './wrap-function';
+var prefix = 'fetch-';
+var bodyPrefix = prefix + 'body-';
+var bodyMethods = ['arrayBuffer', 'blob', 'json', 'text', 'formData'];
+var Req = globalScope.Request;
+var Res = globalScope.Response;
+var proto = 'prototype';
+var ctxId = 'nr@context';
+const wrapped = {};
+
+/**
+ * Wraps the `fetch` method of the global scope for instrumentation. Also wraps the prototypes of the async methods
+ * that parse Request and Response bodies to generate start and end events for each, in context of a new event
+ * emitter scoped only to fetch and related methods.
+ * @param {Object} sharedEE - The shared event emitter on which a new scoped
+ *     event emitter will be based.
+ * @returns {Object} Scoped event emitter with a debug ID of `fetch`.
+ */
+export function wrapFetch(sharedEE) {
+  const ee = scopedEE(sharedEE);
+  if (!(Req && Res && globalScope.fetch)) {
+    return ee;
+  }
+  if (wrapped[ee.debugId]++)
+    // Notice if our wrapping never ran yet, the falsey NaN will not early return; but if it has,
+    {
+      return ee;
+    } // then we increment the count to track # of feats using this at runtime.
+  wrapped[ee.debugId] = 1;
+  bodyMethods.forEach(method => {
+    wrapPromiseMethod(Req[proto], method, bodyPrefix);
+    wrapPromiseMethod(Res[proto], method, bodyPrefix);
+  });
+  wrapPromiseMethod(globalScope, 'fetch', prefix);
+  ee.on(prefix + 'end', function (err, res) {
+    var ctx = this;
+    if (res) {
+      var size = res.headers.get('content-length');
+      if (size !== null) {
+        ctx.rxSize = size;
+      }
+      ee.emit(prefix + 'done', [null, res], ctx);
+    } else {
+      ee.emit(prefix + 'done', [err], ctx);
+    }
+  });
+
+  /**
+   * Wraps a Promise-returning function (referenced by `target[name]`) to emit custom events before and after
+   * execution, each decorated with metadata (arguments, payloads, errors). Used to wrap the async body
+   * parsing methods of Request and Response (e.g. `json`, `text`, `formData`).
+   * @param {Object} target - The object having the method to be wrapped.
+   * @param {string} name - The name of the method to wrap.
+   * @param {string} prefix - Used to decorate event names with context.
+   */
+  function wrapPromiseMethod(target, name, prefix) {
+    var fn = target[name];
+    if (typeof fn === 'function') {
+      target[name] = function () {
+        var args = slice(arguments);
+        var ctx = {};
+        // we are wrapping args in an array so we can preserve the reference
+        ee.emit(prefix + 'before-start', [args], ctx);
+        var dtPayload;
+        if (ctx[ctxId] && ctx[ctxId].dt) dtPayload = ctx[ctxId].dt;
+        var origPromiseFromFetch = fn.apply(this, args);
+        ee.emit(prefix + 'start', [args, dtPayload], origPromiseFromFetch);
+
+        // Note we need to cast the returned (orig) Promise from native APIs into the current global Promise, which may or may not be our WrappedPromise.
+        return origPromiseFromFetch.then(function (val) {
+          ee.emit(prefix + 'end', [null, val], origPromiseFromFetch);
+          return val;
+        }, function (err) {
+          ee.emit(prefix + 'end', [err], origPromiseFromFetch);
+          throw err;
+        });
+      };
+      target[name][flag] = fn; // track original similar to in wrap-function.js, so that they can be unwrapped with ease
+    }
+  }
+
+  return ee;
+}
+
+/**
+ * Returns an event emitter scoped specifically for the `fetch` context. This scoping is a remnant from when all the
+ * features shared the same group in the event, to isolate events between features. It will likely be revisited.
+ * @param {Object} sharedEE - Optional event emitter on which to base the scoped emitter.
+ *     Uses `ee` on the global scope if undefined).
+ * @returns {Object} Scoped event emitter with a debug ID of 'fetch'.
+ */
+export function scopedEE(sharedEE) {
+  return (sharedEE || baseEE).get('fetch');
+}

package/dist/esm/common/wrap/wrap-function.js

@@ -0,0 +1,257 @@
+/*
+ * Copyright 2020 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @file Provides helper functions for wrapping functions in various scenarios.
+ */
+
+import { ee } from '../event-emitter/contextual-ee';
+import slice from 'lodash._slice';
+export const flag = 'nr@original';
+
+/**
+ * A convenience alias of `hasOwnProperty`.
+ * @type {function}
+ */
+var has = Object.prototype.hasOwnProperty;
+
+/**
+ * For tracking whether an event is already being emitted inside the wrapper.
+ * @type {boolean}
+ */
+var inWrapper = false;
+
+// eslint-disable-next-line
+export default createWrapperWithEmitter;
+
+/**
+ * Wraps a function in order to emit events on start, end, and error.
+ * @param {Object} [emitter] - The desired emitter for events emitted by the wrapper. Defaults to the global emitter.
+ * @param {boolean} always - If `true`, emit events even if already emitting an event.
+ * @returns {function} The wrapped function.
+ */
+export function createWrapperWithEmitter(emitter, always) {
+  emitter || (emitter = ee);
+  wrapFn.inPlace = inPlace;
+
+  /**
+   * A flag used to determine if a native function has already been wrapped.
+   * As a property on a wrapped function, contains the original function.
+   * @type {string}
+   */
+  wrapFn.flag = flag;
+  return wrapFn;
+
+  /**
+   * Wraps a function with event emitting functionality.
+   * @param {function} fn - The function to wrap.
+   * @param {string} prefix - A prefix for the names of emitted events.
+   * @param {function|object} getContext - The function or object that will serve as the 'this' context for handlers of events emitted by this wrapper.
+   * @param {string} methodName - The name of the method being wrapped.
+   * @param {boolean} bubble - If true, emitted events should also bubble up to the old emitter upon which the `emitter` in the current scope was based (if it defines one).
+   * @returns {function} The wrapped function.
+   */
+  function wrapFn(fn, prefix, getContext, methodName, bubble) {
+    // Unless fn is both wrappable and unwrapped, return it unchanged.
+    if (notWrappable(fn)) return fn;
+    if (!prefix) prefix = '';
+    nrWrapper[flag] = fn;
+    copy(fn, nrWrapper, emitter);
+    return nrWrapper;
+
+    /**
+     * A wrapper function that emits events before and after calling the wrapped function.
+     * Any arguments will be passed along to the original function.
+     * @returns {any} The return value of the wrapped function.
+     */
+    function nrWrapper() {
+      var args;
+      var originalThis;
+      var ctx;
+      var result;
+      try {
+        originalThis = this;
+        args = slice(arguments);
+        if (typeof getContext === 'function') {
+          ctx = getContext(args, originalThis);
+        } else {
+          ctx = getContext || {};
+        }
+      } catch (e) {
+        report([e, '', [args, originalThis, methodName], ctx], emitter);
+      }
+
+      // Warning: start events may mutate args!
+      safeEmit(prefix + 'start', [args, originalThis, methodName], ctx, bubble);
+      try {
+        result = fn.apply(originalThis, args);
+        return result;
+      } catch (err) {
+        safeEmit(prefix + 'err', [args, originalThis, err], ctx, bubble);
+
+        // rethrow error so we don't effect execution by observing.
+        throw err;
+      } finally {
+        // happens no matter what.
+        safeEmit(prefix + 'end', [args, originalThis, result], ctx, bubble);
+      }
+    }
+  }
+
+  /**
+   * Creates wrapper functions around each of an array of methods on a specified object.
+   * @param {Object} obj - The object to which the specified methods belong.
+   * @param {string[]} methods - An array of method names to be wrapped.
+   * @param {string} [prefix=''] - A prefix to add to the names of emitted events.
+   * @param {function|object} [getContext] - The function or object that will serve as the 'this' context for handlers
+   *     of events emitted by this wrapper.
+   * @param {boolean} [bubble=false] - If `true`, emitted events should also bubble up to the old emitter upon which
+   *     the `emitter` in the current scope was based (if it defines one).
+   */
+  function inPlace(obj, methods, prefix, getContext, bubble) {
+    if (!prefix) prefix = '';
+    // If prefix starts with '-' set this boolean to add the method name to
+    // the prefix before passing each one to wrap.
+    var prependMethodPrefix = prefix.charAt(0) === '-';
+    var fn;
+    var method;
+    var i;
+    for (i = 0; i < methods.length; i++) {
+      method = methods[i];
+      fn = obj[method];
+
+      // Unless fn is both wrappable and unwrapped bail,
+      // so we don't add extra properties with undefined values.
+      if (notWrappable(fn)) continue;
+      obj[method] = wrapFn(fn, prependMethodPrefix ? method + prefix : prefix, getContext, method, bubble);
+    }
+  }
+
+  /**
+   * Emits an event using the `emit` method of the `emitter` object in the executing scope, but only if an event is not
+   * already being emitted (except when the executing scope defines `always` as `true`).
+   * @param {string} evt - The name of the event to be emitted.
+   * @param {array} arr - An array of arguments to pass with the event.
+   * @param {Object} store - The function or object that will serve as the 'this'
+   *     context when applying handler functions for this event.
+   * @param {boolean} bubble - If `true`, emitted events should also
+   *     bubble up to the old emitter upon which the `emitter` in the
+   *     executing scope was based (if it defines one).
+   */
+  function safeEmit(evt, arr, store, bubble) {
+    if (inWrapper && !always) return;
+    var prev = inWrapper;
+    inWrapper = true;
+    try {
+      emitter.emit(evt, arr, store, always, bubble);
+    } catch (e) {
+      report([e, evt, arr, store], emitter);
+    }
+    inWrapper = prev;
+  }
+}
+
+/**
+ * Emits an "internal-error" event. Used to report errors encountered when emitting events using `safeEmit`.
+ * @param {array} args - Arguments to be passed to the "internal-error" event.
+ * @param {Object} [emitter] - The (optional) desired event emitter. Defaults to the global event emitter.
+ */
+function report(args, emitter) {
+  emitter || (emitter = ee);
+  try {
+    emitter.emit('internal-error', args);
+  } catch (err) {
+    // do nothing
+  }
+}
+
+/**
+ * Copies properties from one object to another. Used for creating a wrapper function from an original function and for
+ * copying an original function to a property of a wrapper function named by `flag` in the executing context.
+ * @param {Object} from - The source function or object.
+ * @param {Object} to - The destination function or object.
+ * @param {Object} [emitter] - The (optional) desired event emitter if errors are encountered while copying.
+ *     Defaults to the global event emitter.
+ * @returns {object} - The destination founction or object with copied properties.
+ */
+function copy(from, to, emitter) {
+  if (Object.defineProperty && Object.keys) {
+    // Create accessors that proxy to actual function
+    try {
+      var keys = Object.keys(from);
+      // eslint-disable-next-line
+      keys.forEach(function (key) {
+        Object.defineProperty(to, key, {
+          get: function () {
+            return from[key];
+          },
+          // eslint-disable-next-line
+          set: function (val) {
+            from[key] = val;
+            return val;
+          }
+        });
+      });
+      return to;
+    } catch (e) {
+      report([e], emitter);
+    }
+  }
+  // fall back to copying properties
+  for (var i in from) {
+    if (has.call(from, i)) {
+      to[i] = from[i];
+    }
+  }
+  return to;
+}
+
+/**
+ * Determines whether a function is eligible to be wrapped in part based on whether it has already been wrapped.
+ * @param {function} fn - The function in question.
+ * @returns {boolean} Whether the passed function is ineligible to be wrapped.
+ */
+function notWrappable(fn) {
+  return !(fn && fn instanceof Function && fn.apply && !fn[flag]);
+}
+
+/**
+ * Creates a wrapped version of a function using a specified wrapper function. The new wrapped function references the
+ * original function. Also copies the properties of the original function to the wrapped function.
+ * @param {function} fn - A function to be wrapped.
+ * @param {function} wrapper - A higher order function that returns a new function, which executes the function passed
+ *     to the higher order function as an argument.
+ * @returns {function} A wrapped function with an internal reference to the original function.
+ */
+export function wrapFunction(fn, wrapper) {
+  var wrapped = wrapper(fn);
+  wrapped[flag] = fn;
+  copy(fn, wrapped, ee);
+  return wrapped;
+}
+
+/**
+ * Replaces a function with a wrapped version of itself. To preserve object references, rather than taking the function
+ * itself as an argument, takes the object on which the particular named function is a property.
+ * @param {Object} obj - The object on which the named function is a property.
+ * @param {string} fnName - The name of the function to be wrapped.
+ * @param {function} wrapper - A higher order function that returns a new function, which executes the function passed
+ *     to the higher order function as an argument.
+ */
+export function wrapInPlace(obj, fnName, wrapper) {
+  var fn = obj[fnName];
+  obj[fnName] = wrapFunction(fn, wrapper);
+}
+
+/**
+ * If a function property on an object (e.g. window) was previously wrapped (by this module), removes the wrapper.
+ * @param {Object} obj - The object on which the named function is a property.
+ * @param {string} fnName - The name of the function to be unwrapped.
+ */
+export function unwrapFunction(obj, fnName) {
+  if (obj?.[fnName]?.[flag]) {
+    // previous state of the function property is stored under our wrapper's "flag"; we don't wrap properties that *were* undefined to begin with
+    obj[fnName] = obj[fnName][flag];
+  }
+}