@atlaskit/insm 0.0.2 → 0.1.1

package/dist/es2019/insm-session.js

@@ -0,0 +1,149 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+import { PeriodTracking } from './insm-period';
+
+/**
+ * Only intended for internal use.
+ *
+ * Exported for consumers who may require the type.
+ */
+export class INSMSession {
+  constructor(experienceKey, experienceProperties, insm) {
+    _defineProperty(this, "startedAt", performance.now());
+    _defineProperty(this, "running", true);
+    _defineProperty(this, "addedProperties", []);
+    _defineProperty(this, "runningFeatures", new Set());
+    this.experienceKey = experienceKey;
+    this.experienceProperties = experienceProperties;
+    this.insm = insm;
+    this.periodTracking = new PeriodTracking(this);
+
+    /**
+     * Note: Events are not reliably fired from mobile browsers (ie. when a browser is closed when not in use)
+     */
+  }
+
+  /**
+   * Adds a feature to the currently running session
+   */
+  startFeature(featureName) {
+    var _this$periodTracking;
+    this.runningFeatures.add(featureName);
+    (_this$periodTracking = this.periodTracking) === null || _this$periodTracking === void 0 ? void 0 : _this$periodTracking.startFeature(featureName);
+  }
+
+  /**
+   * Ends a features usage in the currently running session
+   */
+  endFeature(featureName) {
+    this.runningFeatures.delete(featureName);
+  }
+
+  /**
+   * Returns details on the current session.
+   */
+  get details() {
+    return {
+      experienceKey: this.experienceKey,
+      experienceProperties: this.experienceProperties,
+      paused: this.periodTracking.pauses.size > 0,
+      periodState: this.periodTracking.state,
+      /**
+       * The only scenario where this value should return false is when
+       * the experience has been stopped early.
+       */
+      running: this.running
+    };
+  }
+
+  /**
+   * This api takes either a static single-level key-value object, or callbacks which return the same and
+   * will be evaluated on session end.
+   *
+   * When ending a session, all properties received via this api are merged, in order, into the resulting
+   * insm event’s properties; last write wins.
+   *
+   * Callback values are evaluated at session end.
+   *
+   * For example, for the following
+   *
+   * ```ts
+   * insm.experience.addProperties({ one: 1, two: 2 });
+   * insm.experience.addProperties(() => ({ one: 'one' }));
+   * insm.experience.addProperties({ three: 3 });
+   * ```
+   *
+   * The resulting added properties will be
+   *
+   * ```ts
+   * { one: 'one', two: 2, three: 3 }
+   * ```
+   */
+  addProperties(propertiesToAdd) {
+    this.addedProperties.push(propertiesToAdd);
+  }
+
+  /**
+   * In some scenarios (ie. when a page error boundary is hit), you will want to exit early.
+   * This is api supports these scenarios
+   *
+   * ```ts
+   * insm.stopEarly(reasonKey: string, description: string);
+   * ```
+   *
+   * Sessions closed early are identifiable by their end details
+   * `"endDetails": { stoppedBy: "early-stop", reasonKey, description }`.
+   *
+   * **Note**: The session is ended as soon as this is called, and any `addProperties` handlers will
+   * called immediately.
+   */
+  earlyStop(reason, description) {
+    this.end({
+      stoppedBy: 'early-stop',
+      reason,
+      description
+    });
+  }
+  end(endDetails) {
+    var _this$insm$analyticsW;
+    if (this.running === false) {
+      // If an experience has already been ended -- don't repeat the ending
+      return;
+    }
+    this.running = false;
+    const endedAt = performance.now();
+    const duration = endedAt - this.startedAt;
+    const evaluatedAddedProperties = {};
+    for (const addedProperty of this.addedProperties) {
+      if (typeof addedProperty === 'function') {
+        Object.assign(evaluatedAddedProperties, addedProperty());
+      } else {
+        Object.assign(evaluatedAddedProperties, addedProperty);
+      }
+    }
+    const periodResults = this.periodTracking.endResults;
+
+    /**
+     * This event ends up as "insm measured"
+     */
+    const operationalEvent = {
+      actionSubject: 'insm',
+      action: 'measured',
+      attributes: {
+        // Added first to ensure these don't overwrite any insm properties
+        ...evaluatedAddedProperties,
+        experienceKey: this.experienceKey,
+        initial: this.experienceProperties.initial,
+        contentId: this.experienceProperties.contentId,
+        timing: {
+          startedAt: this.startedAt,
+          duration
+        },
+        periods: periodResults,
+        endDetails: endDetails
+      },
+      tags: ['insm'],
+      source: 'insm'
+    };
+    (_this$insm$analyticsW = this.insm.analyticsWebClient) === null || _this$insm$analyticsW === void 0 ? void 0 : _this$insm$analyticsW.sendOperationalEvent(operationalEvent);
+  }
+}

package/dist/es2019/insm.js

@@ -0,0 +1,105 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+import { INSMSession } from './insm-session';
+import { AnimationFPSIM } from './period-measurers/afps';
+import { INPTracker } from './inp-measurers/inp';
+export class INSM {
+  constructor(options) {
+    /**
+     * Heavy tasks are tracked at the insm layer as heavy tasks
+     * are expected at times to be unrelated to the current
+     * page session.
+     */
+    _defineProperty(this, "runningHeavyTasks", new Set());
+    this.periodMeasurers = [new AnimationFPSIM(), new INPTracker(), new INPTracker({
+      includedInteractions: ['pointerup']
+    }), new INPTracker({
+      includedInteractions: ['pointerdown']
+    }), new INPTracker({
+      includedInteractions: ['click']
+    }), new INPTracker({
+      includedInteractions: ['keydown']
+    }), new INPTracker({
+      includedInteractions: ['keyup']
+    })];
+    this.options = options;
+
+    // If this does throw -- we do want an unhandledRejection rejection to be passed to the window
+    // this is to ease debugging.
+    options.getAnalyticsWebClient.then(analyticsWebClient => this.analyticsWebClient = analyticsWebClient);
+
+    // No cleanup needs to be performed -- as this is intended to run until the tab is closed
+    // eslint-disable-next-line @repo/internal/dom-events/no-unsafe-event-listeners
+    window.addEventListener('pagehide', () => {
+      var _this$runningSession;
+      (_this$runningSession = this.runningSession) === null || _this$runningSession === void 0 ? void 0 : _this$runningSession.end({
+        stoppedBy: 'pagehide'
+      });
+    });
+  }
+
+  /**
+   * Starts a heavy task in the currently running session.
+   *
+   * This also pauses measurement.
+   */
+  startHeavyTask(heavyTaskName) {
+    var _this$runningSession2, _this$runningSession3, _this$runningSession4;
+    this.runningHeavyTasks.add(heavyTaskName);
+    (_this$runningSession2 = this.runningSession) === null || _this$runningSession2 === void 0 ? void 0 : (_this$runningSession3 = _this$runningSession2.periodTracking) === null || _this$runningSession3 === void 0 ? void 0 : _this$runningSession3.startHeavyTask(heavyTaskName);
+    (_this$runningSession4 = this.runningSession) === null || _this$runningSession4 === void 0 ? void 0 : _this$runningSession4.periodTracking.pause(heavyTaskName);
+  }
+
+  /**
+   * Ends a heavy task in the currently running session
+   */
+  endHeavyTask(heavyTaskName) {
+    var _this$runningSession5;
+    this.runningHeavyTasks.delete(heavyTaskName);
+    (_this$runningSession5 = this.runningSession) === null || _this$runningSession5 === void 0 ? void 0 : _this$runningSession5.periodTracking.resume(heavyTaskName);
+  }
+
+  /**
+   * Call this when starting a new experience.  This is expected to be wired to the product
+   * routing solution.
+   *
+   * It's expected this call will be paired with a `insm.session.startHeavyTask('page-load')` and subsequent `insm.session.endHeavyTask('page-load')`
+   * so that performance degradations linked to the page initialisation are excluded from the active interactivity monitoring.
+   *
+   *
+   * ```ts
+   * insm.start('edit-page', { initial: true, contentId: '9001' })
+   * insm.session.startHeavyTask(''page-load')
+   * // ... heavy initialisation work
+   * insm.session.endHeavyTask(''page-load')
+   * ```
+   */
+  start(experienceKey, experienceProperties) {
+    var _this$options$experie;
+    if (this.runningSession !== undefined) {
+      this.runningSession.end({
+        stoppedBy: 'new-experience',
+        experienceKey: experienceKey,
+        contentId: experienceProperties.contentId
+      });
+    }
+    if ((_this$options$experie = this.options.experiences[experienceKey]) !== null && _this$options$experie !== void 0 && _this$options$experie.enabled) {
+      this.runningSession = new INSMSession(experienceKey, experienceProperties, this);
+    }
+  }
+
+  /**
+   * This prematurely halts any running experience measurement. It's expected to be used in
+   * scenarios such as when error boundaries are hit.
+   */
+  stopEarly(reasonKey, description) {
+    var _this$runningSession6;
+    (_this$runningSession6 = this.runningSession) === null || _this$runningSession6 === void 0 ? void 0 : _this$runningSession6.earlyStop(reasonKey, description);
+  }
+
+  /**
+   * Gets the current running session details
+   */
+  get session() {
+    return this.runningSession;
+  }
+}

package/dist/es2019/period-measurers/afps.js

@@ -0,0 +1,153 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+export class AnimationFPSIM {
+  constructor() {
+    /**
+     * AFPS stands for Animation Frames Per Second
+     */
+    _defineProperty(this, "name", 'afps');
+    _defineProperty(this, "monitor", new AnimationFPSMonitor());
+  }
+  start(paused) {
+    const result = this.monitor.startNewWindow(paused);
+    return result;
+  }
+  end() {
+    const result = this.monitor.end();
+    return result;
+  }
+  pause() {
+    this.monitor.pause();
+  }
+  resume() {
+    this.monitor.resume();
+  }
+}
+class AnimationFPSMonitor {
+  constructor() {
+    _defineProperty(this, "paused", false);
+    _defineProperty(this, "currentState", {
+      numerator: 0,
+      denominator: 0,
+      max: 0,
+      average: 0,
+      min: 0
+    });
+    // Current measurement window
+    _defineProperty(this, "windowFrameCount", 0);
+    _defineProperty(this, "windowTotalTime", 0);
+    _defineProperty(this, "currentFrameStart", 0);
+  }
+  measureWindowFPS() {
+    // Calculate FPS for this window
+    // Note: windowFrameCount and windowTotalTime is reset after each window measurement
+    const windowSeconds = this.windowTotalTime / 1000;
+    // frames / seconds
+    const windowFPS = this.windowFrameCount / windowSeconds;
+
+    // Update overall tracking
+    this.currentState.numerator += this.windowFrameCount;
+    // The denominator is seconds not ms
+    this.currentState.denominator += windowSeconds;
+
+    // Calculate overall average FPS: (total frames / total time measured in seconds
+    this.currentState.average = this.currentState.numerator / this.currentState.denominator;
+    if (this.currentState.max === 0 || windowFPS > this.currentState.max) {
+      this.currentState.max = windowFPS;
+    }
+    if (this.currentState.min === 0 || windowFPS < this.currentState.min) {
+      this.currentState.min = windowFPS;
+    }
+  }
+
+  /**
+   * If there is running tracking - it will be reset
+   */
+  startWindowTracking() {
+    // Clear any previous tracking state
+    this.resetOverallTracking();
+    const measureFrame = () => {
+      this.currentFrameStart = global.performance.now();
+      this.animationFrame = requestAnimationFrame(() => {
+        // While measurement is paused -- we don't count the animation frame towards the monitored
+        // period.
+        if (!this.paused) {
+          const frameDuration = performance.now() - this.currentFrameStart;
+
+          // Add frame to current window
+          this.windowFrameCount++;
+          this.windowTotalTime += frameDuration;
+
+          // Check if window is >= 1 second (1000ms)
+          // When the page is running smoothly it's expected this will not be hit frequently
+          if (this.windowTotalTime >= 1000) {
+            this.measureWindowFPS();
+            // Reset window for next measurement
+            this.resetWindow();
+          }
+        }
+        measureFrame();
+      });
+    };
+    measureFrame();
+  }
+  startNewWindow(paused) {
+    const lastWindowResult = {
+      numerator: this.currentState.numerator,
+      denominator: this.currentState.denominator,
+      max: this.currentState.max,
+      min: this.currentState.min,
+      average: this.currentState.average
+    };
+    this.paused = paused;
+    this.startWindowTracking();
+    return lastWindowResult;
+  }
+  resetWindow() {
+    this.windowFrameCount = 0;
+    this.windowTotalTime = 0;
+    // Note this.currentFrameStart is over ridden
+    // as part of tracking - so does not need to be
+    // reset.
+  }
+  endWindowTracking() {
+    if (this.animationFrame) {
+      cancelAnimationFrame(this.animationFrame);
+    }
+  }
+  resetOverallTracking() {
+    this.resetWindow();
+    this.endWindowTracking();
+    this.currentState = {
+      numerator: 0,
+      denominator: 0,
+      max: 0,
+      min: 0,
+      average: 0
+    };
+  }
+  end() {
+    try {
+      this.measureWindowFPS();
+      return this.currentState;
+    } finally {
+      this.resetOverallTracking();
+    }
+  }
+  pause() {
+    // Note - we leave the tracking animationFrame monitoring running, and on resume
+    // simply set the currentFrameStart and paused to true
+    // This works because the tracking builds windows of tracked time rather than
+    // basing itself off a window start time and time elapsed time since then.
+    this.paused = true;
+  }
+  resume() {
+    // Note - We don't need to handle the gap in measurement - as the raf logic builds/increments a window time
+    // based on the currentFrameStart (and any previous measurements which can only happen while the tracking
+    // is not paused).
+    this.currentFrameStart = performance.now();
+    this.paused = false;
+    if (!this.animationFrame) {
+      this.startWindowTracking();
+    }
+  }
+}

package/dist/es2019/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/index.js

@@ -1,4 +1,57 @@
+import { INSM } from './insm';
+var initialisedInsm;
+
 /**
  * Initializes the INSM (Interactivity Session Measurement) tooling
  */
-export function init() {}
+export function init(options) {
+  initialisedInsm = new INSM(options);
+}
+function insmInitialised() {
+  if (!initialisedInsm) {
+    // eslint-disable-next-line no-console
+    console.error('INSM used when not initialised');
+    return false;
+  }
+  return true;
+}
+
+/**
+ * **In**teractivity **s**ession **m**onitoring
+ */
+export var insm = {
+  startHeavyTask: function startHeavyTask(heavyTaskName) {
+    if (insmInitialised()) {
+      initialisedInsm.startHeavyTask(heavyTaskName);
+    }
+  },
+  endHeavyTask: function endHeavyTask(heavyTaskName) {
+    if (insmInitialised()) {
+      initialisedInsm.endHeavyTask(heavyTaskName);
+    }
+  },
+  start: function start(experienceKey, experienceProperties) {
+    if (insmInitialised()) {
+      initialisedInsm.start(experienceKey, experienceProperties);
+    }
+  },
+  stopEarly: function stopEarly(reasonKey, description) {
+    if (insmInitialised()) {
+      initialisedInsm.stopEarly(reasonKey, description);
+    }
+  },
+  // We only expose details and feature start/stop to consumers
+  // as the other properties are internals for the insm and InsmPeriod
+  // to interact with the running session.
+  get session() {
+    if (insmInitialised()) {
+      return initialisedInsm.runningSession;
+    }
+  },
+  // @ts-expect-error Private method for testing purposes
+  __setAnalyticsWebClient: function __setAnalyticsWebClient(analyticsWebClient) {
+    if (initialisedInsm) {
+      initialisedInsm.analyticsWebClient = analyticsWebClient;
+    }
+  }
+};

package/dist/esm/inp-measurers/inp.js

@@ -0,0 +1,177 @@
+import _classCallCheck from "@babel/runtime/helpers/classCallCheck";
+import _createClass from "@babel/runtime/helpers/createClass";
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+export var INPTracker = /*#__PURE__*/function () {
+  function INPTracker(options) {
+    _classCallCheck(this, INPTracker);
+    /**
+     * INP stands for Interaction to Next Paint
+     */
+    _defineProperty(this, "name", 'inp');
+    this.includedInteractions = (options === null || options === void 0 ? void 0 : options.includedInteractions) || ['pointerdown', 'pointerup', 'click', 'keydown', 'keyup'];
+    this.monitor = new InteractionTracker(this.includedInteractions);
+  }
+  return _createClass(INPTracker, [{
+    key: "start",
+    value: function start(paused) {
+      var result = this.monitor.start(paused);
+      return result;
+    }
+  }, {
+    key: "end",
+    value: function end() {
+      var result = this.monitor.end();
+      return result;
+    }
+  }, {
+    key: "pause",
+    value: function pause() {
+      this.monitor.pause();
+    }
+  }, {
+    key: "resume",
+    value: function resume() {
+      this.monitor.resume();
+    }
+  }]);
+}();
+var InteractionResult = /*#__PURE__*/function () {
+  function InteractionResult() {
+    _classCallCheck(this, InteractionResult);
+    this.min = Infinity;
+    this.max = 0;
+    this.average = 0;
+    this.numerator = 0;
+    this.count = 0;
+  }
+  return _createClass(InteractionResult, [{
+    key: "update",
+    value: function update(duration) {
+      if (duration > this.max) {
+        this.max = duration;
+      }
+      if (duration < this.min) {
+        this.min = duration;
+      }
+      this.numerator += this.average * (this.count - 1) + duration;
+      this.count += 1;
+      this.average = this.numerator / this.count;
+    }
+  }, {
+    key: "toMeasure",
+    value: function toMeasure() {
+      return {
+        min: this.count === 0 ? 0 : this.min,
+        max: this.max,
+        average: this.average,
+        numerator: this.numerator,
+        denominator: this.count
+      };
+    }
+  }]);
+}();
+var InteractionTracker = /*#__PURE__*/function () {
+  function InteractionTracker(includedInteractions) {
+    _classCallCheck(this, InteractionTracker);
+    _defineProperty(this, "paused", false);
+    this.performanceObserver = null;
+    this.interactionResult = new InteractionResult();
+    this.includedInteractions = includedInteractions;
+  }
+  return _createClass(InteractionTracker, [{
+    key: "stopTracking",
+    value: function stopTracking() {
+      var _this$performanceObse;
+      (_this$performanceObse = this.performanceObserver) === null || _this$performanceObse === void 0 || _this$performanceObse.disconnect();
+      this.performanceObserver = null;
+    }
+  }, {
+    key: "startTracking",
+    value: function startTracking() {
+      var _this = this;
+      this.performanceObserver = new PerformanceObserver(function (list) {
+        // Note: find link to actual safari issue .. good to get rid of this if Safari has fixed this
+        // Delay by a microtask to workaround a bug in Safari where the
+        // callback is invoked immediately, rather than in a separate task.
+        // See: https://github.com/GoogleChrome/web-vitals/issues/277
+        Promise.resolve().then(function () {
+          var entries = list.getEntries();
+          entries.forEach(function (entry) {
+            // Skip further processing for entries that cannot be INP candidates.
+            //
+            // When a user interacts with a web page, a user interaction (for example a click) usually triggers a sequence of events.
+            // To measure the latency of this series of events, the events share the same interactionId.
+            // An interactionId is only computed for the following event types belonging to a user interaction. It is 0 otherwise.
+            // * click / tap / drag events: 'pointerdown', 'pointerup', 'click'
+            // * keypress events: 'keydown', 'keyup'
+            //
+            if (!entry.interactionId) {
+              return;
+            }
+            if (_this.includedInteractions.includes(entry.name)) {
+              _this.interactionResult.update(entry.duration);
+            }
+          });
+        });
+      });
+
+      // Event Timing entries have their durations rounded to the nearest 8ms,
+      // so a duration of 40ms would be any event that spans 2.5 or more frames
+      // at 60Hz. This threshold is chosen to strike a balance between usefulness
+      // and performance. Running this callback for any interaction that spans
+      // just one or two frames is likely not worth the insight that could be
+      // gained.
+      if (PerformanceObserver.supportedEntryTypes.includes('event')) {
+        this.performanceObserver.observe({
+          type: 'event',
+          buffered: true,
+          durationThreshold: 40
+        });
+      }
+    }
+  }, {
+    key: "reset",
+    value: function reset() {
+      this.stopTracking();
+      this.interactionResult = new InteractionResult();
+    }
+  }, {
+    key: "start",
+    value: function start(paused) {
+      var lastResult = this.interactionResult.toMeasure();
+      this.reset();
+      this.paused = paused;
+      if (!paused) {
+        this.startTracking();
+      }
+      return lastResult;
+    }
+  }, {
+    key: "end",
+    value: function end() {
+      try {
+        return this.interactionResult.toMeasure();
+      } finally {
+        this.reset();
+      }
+    }
+  }, {
+    key: "pause",
+    value: function pause() {
+      if (this.paused) {
+        return;
+      }
+      this.paused = true;
+      this.stopTracking();
+    }
+  }, {
+    key: "resume",
+    value: function resume() {
+      if (!this.paused) {
+        return;
+      }
+      this.paused = false;
+      this.startTracking();
+    }
+  }]);
+}();