@atlaskit/insm 0.0.2 → 0.1.0

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

@@ -0,0 +1,193 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.AnimationFPSIM = void 0;
+var _classCallCheck2 = _interopRequireDefault(require("@babel/runtime/helpers/classCallCheck"));
+var _createClass2 = _interopRequireDefault(require("@babel/runtime/helpers/createClass"));
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var AnimationFPSIM = exports.AnimationFPSIM = /*#__PURE__*/function () {
+  function AnimationFPSIM() {
+    (0, _classCallCheck2.default)(this, AnimationFPSIM);
+    /**
+     * AFPS stands for Animation Frames Per Second
+     */
+    (0, _defineProperty2.default)(this, "name", 'afps');
+    (0, _defineProperty2.default)(this, "monitor", new AnimationFPSMonitor());
+  }
+  return (0, _createClass2.default)(AnimationFPSIM, [{
+    key: "start",
+    value: function start(paused) {
+      var result = this.monitor.startNewWindow(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 AnimationFPSMonitor = /*#__PURE__*/function () {
+  function AnimationFPSMonitor() {
+    (0, _classCallCheck2.default)(this, AnimationFPSMonitor);
+    (0, _defineProperty2.default)(this, "paused", false);
+    (0, _defineProperty2.default)(this, "currentState", {
+      numerator: 0,
+      denominator: 0,
+      max: 0,
+      average: 0,
+      min: 0
+    });
+    // Current measurement window
+    (0, _defineProperty2.default)(this, "windowFrameCount", 0);
+    (0, _defineProperty2.default)(this, "windowTotalTime", 0);
+    (0, _defineProperty2.default)(this, "currentFrameStart", 0);
+  }
+  return (0, _createClass2.default)(AnimationFPSMonitor, [{
+    key: "measureWindowFPS",
+    value: function measureWindowFPS() {
+      // Calculate FPS for this window
+      // Note: windowFrameCount and windowTotalTime is reset after each window measurement
+      var windowSeconds = this.windowTotalTime / 1000;
+      // frames / seconds
+      var 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
+     */
+  }, {
+    key: "startWindowTracking",
+    value: function startWindowTracking() {
+      var _this = this;
+      // Clear any previous tracking state
+      this.resetOverallTracking();
+      var _measureFrame = function measureFrame() {
+        _this.currentFrameStart = global.performance.now();
+        _this.animationFrame = requestAnimationFrame(function () {
+          // While measurement is paused -- we don't count the animation frame towards the monitored
+          // period.
+          if (!_this.paused) {
+            var 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();
+    }
+  }, {
+    key: "startNewWindow",
+    value: function startNewWindow(paused) {
+      var 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;
+    }
+  }, {
+    key: "resetWindow",
+    value: function resetWindow() {
+      this.windowFrameCount = 0;
+      this.windowTotalTime = 0;
+      // Note this.currentFrameStart is over ridden
+      // as part of tracking - so does not need to be
+      // reset.
+    }
+  }, {
+    key: "endWindowTracking",
+    value: function endWindowTracking() {
+      if (this.animationFrame) {
+        cancelAnimationFrame(this.animationFrame);
+      }
+    }
+  }, {
+    key: "resetOverallTracking",
+    value: function resetOverallTracking() {
+      this.resetWindow();
+      this.endWindowTracking();
+      this.currentState = {
+        numerator: 0,
+        denominator: 0,
+        max: 0,
+        min: 0,
+        average: 0
+      };
+    }
+  }, {
+    key: "end",
+    value: function end() {
+      try {
+        this.measureWindowFPS();
+        return this.currentState;
+      } finally {
+        this.resetOverallTracking();
+      }
+    }
+  }, {
+    key: "pause",
+    value: function 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;
+    }
+  }, {
+    key: "resume",
+    value: function 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/cjs/types.js

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/dist/es2019/index.js

@@ -1,4 +1,57 @@
+import { INSM } from './insm';
+let 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 const insm = {
+  startHeavyTask(heavyTaskName) {
+    if (insmInitialised()) {
+      initialisedInsm.startHeavyTask(heavyTaskName);
+    }
+  },
+  endHeavyTask(heavyTaskName) {
+    if (insmInitialised()) {
+      initialisedInsm.endHeavyTask(heavyTaskName);
+    }
+  },
+  start(experienceKey, experienceProperties) {
+    if (insmInitialised()) {
+      initialisedInsm.start(experienceKey, experienceProperties);
+    }
+  },
+  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(analyticsWebClient) {
+    if (initialisedInsm) {
+      initialisedInsm.analyticsWebClient = analyticsWebClient;
+    }
+  }
+};

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

@@ -0,0 +1,142 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+export class INPTracker {
+  constructor(options) {
+    /**
+     * 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);
+  }
+  start(paused) {
+    const result = this.monitor.start(paused);
+    return result;
+  }
+  end() {
+    const result = this.monitor.end();
+    return result;
+  }
+  pause() {
+    this.monitor.pause();
+  }
+  resume() {
+    this.monitor.resume();
+  }
+}
+class InteractionResult {
+  constructor() {
+    this.min = Infinity;
+    this.max = 0;
+    this.average = 0;
+    this.numerator = 0;
+    this.count = 0;
+  }
+  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;
+  }
+  toMeasure() {
+    return {
+      min: this.count === 0 ? 0 : this.min,
+      max: this.max,
+      average: this.average,
+      numerator: this.numerator,
+      denominator: this.count
+    };
+  }
+}
+class InteractionTracker {
+  constructor(includedInteractions) {
+    _defineProperty(this, "paused", false);
+    this.performanceObserver = null;
+    this.interactionResult = new InteractionResult();
+    this.includedInteractions = includedInteractions;
+  }
+  stopTracking() {
+    var _this$performanceObse;
+    (_this$performanceObse = this.performanceObserver) === null || _this$performanceObse === void 0 ? void 0 : _this$performanceObse.disconnect();
+    this.performanceObserver = null;
+  }
+  startTracking() {
+    this.performanceObserver = new PerformanceObserver(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(() => {
+        const entries = list.getEntries();
+        entries.forEach(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
+      });
+    }
+  }
+  reset() {
+    this.stopTracking();
+    this.interactionResult = new InteractionResult();
+  }
+  start(paused) {
+    const lastResult = this.interactionResult.toMeasure();
+    this.reset();
+    this.paused = paused;
+    if (!paused) {
+      this.startTracking();
+    }
+    return lastResult;
+  }
+  end() {
+    try {
+      return this.interactionResult.toMeasure();
+    } finally {
+      this.reset();
+    }
+  }
+  pause() {
+    if (this.paused) {
+      return;
+    }
+    this.paused = true;
+    this.stopTracking();
+  }
+  resume() {
+    if (!this.paused) {
+      return;
+    }
+    this.paused = false;
+    this.startTracking();
+  }
+}

package/dist/es2019/insm-period.js

@@ -0,0 +1,246 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+/* eslint-disable @repo/internal/dom-events/no-unsafe-event-listeners */
+
+export class PeriodTracking {
+  constructor(session) {
+    _defineProperty(this, "periodMeasurements", {
+      active: {
+        features: new Set(),
+        heavyTasks: new Set(),
+        measurements: {},
+        duration: 0,
+        count: 0
+      },
+      inactive: {
+        features: new Set(),
+        heavyTasks: new Set(),
+        measurements: {},
+        duration: 0,
+        count: 0
+      }
+    });
+    _defineProperty(this, "state", 'inactive');
+    _defineProperty(this, "pauses", new Set());
+    /**
+     * Warning: this can be reset mid period when pausing/resuming.
+     * It's intended use is to build the `periodMeasurements` duration.
+     */
+    _defineProperty(this, "currentPeriodStart", performance.now());
+    _defineProperty(this, "activeStartListeners", []);
+    _defineProperty(this, "activeEndListeners", []);
+    /**
+     * This works by;
+     * On setup
+     * - starts activity listeners
+     *   - on activity received
+     *     - possible end active count down started.
+     *       3 animation frames or 3 seconds of inactivity - whichever comes first
+     *     - any existing end count down ended
+     */
+    _defineProperty(this, "activeEndCountDownAbortController", new AbortController());
+    this.session = session;
+    this.latestPeriodFeatures = new Set(session.runningFeatures);
+    this.latestHeavyTasks = new Set(session.insm.runningHeavyTasks);
+    this.pauses = new Set(session.insm.runningHeavyTasks);
+    const startInteractivityMeasuresPaused = this.latestHeavyTasks.size !== 0;
+    for (const periodMeasurer of session.insm.periodMeasurers) {
+      periodMeasurer.start(startInteractivityMeasuresPaused);
+      this.periodMeasurements.active.measurements[periodMeasurer.name] = {
+        numerator: 0,
+        denominator: 0,
+        max: 0,
+        min: 0,
+        average: 0
+      };
+      this.periodMeasurements.inactive.measurements[periodMeasurer.name] = {
+        numerator: 0,
+        denominator: 0,
+        max: 0,
+        min: 0,
+        average: 0
+      };
+    }
+    this.setupActiveStartInteractionListeners();
+  }
+  startFeature(featureName) {
+    this.latestPeriodFeatures.add(featureName);
+    this.periodMeasurements[this.state].features.add(featureName);
+  }
+  startHeavyTask(heavyTaskName) {
+    this.latestHeavyTasks.add(heavyTaskName);
+    this.periodMeasurements[this.state].heavyTasks.add(heavyTaskName);
+    this.pause(heavyTaskName);
+  }
+  endHeavyTask(heavyTaskName) {
+    this.resume(heavyTaskName);
+  }
+
+  /**
+   * Sets a pause based on a key.  If this is the first pause, then it will also halt
+   * running interactivity measures, and update the current measurements duration.
+   */
+  pause(pauseName) {
+    if (this.pauses.size === 0) {
+      this.periodMeasurements[this.state].duration = this.periodMeasurements[this.state].duration + (performance.now() - this.currentPeriodStart);
+      for (const periodMeasurer of this.session.insm.periodMeasurers) {
+        periodMeasurer.pause();
+      }
+    }
+    this.pauses.add(pauseName);
+  }
+
+  /**
+   * Releases a pause for a key.
+   *
+   * **NOTE**: The session will only resume if this was the only
+   * currently tracked pause key.
+   */
+  resume(pauseName) {
+    this.pauses.delete(pauseName);
+    if (this.pauses.size === 0) {
+      this.currentPeriodStart = performance.now();
+      for (const periodMeasurer of this.session.insm.periodMeasurers) {
+        periodMeasurer.resume();
+      }
+    }
+  }
+  get endResults() {
+    this.changePeriodAndTrackLast(this.state);
+    return this.periodMeasurements;
+  }
+  setupActiveStartInteractionListeners() {
+    const events = ['mousemove', 'pointerdown', 'pointerup', 'click', 'keydown', 'keyup', 'scroll'];
+    for (const event of events) {
+      const eventListener = () => {
+        // start event
+        this.changePeriodAndTrackLast('inactive', 'active');
+      };
+      window.addEventListener(event, eventListener, {
+        once: true
+      });
+      this.activeStartListeners.push([event, eventListener]);
+    }
+  }
+  setupEndActiveInteractionListeners() {
+    this.activeEndCountDownVisibilityListener = () => {
+      if (document.visibilityState === 'hidden') {
+        endSession();
+      }
+    };
+    window.addEventListener('visibilitychange', this.activeEndCountDownVisibilityListener);
+    const events = ['mousemove', 'pointerdown', 'pointerup', 'click', 'keydown', 'keyup', 'scroll'];
+    for (const event of events) {
+      const eventListener = () => {
+        this.activeEndCountDownAbortController.abort();
+        this.activeEndCountDownAbortController = new AbortController();
+        startPeriodEndCountDown(this.activeEndCountDownAbortController.signal, () => {
+          endSession();
+        });
+      };
+      window.addEventListener(event, eventListener);
+      this.activeEndListeners.push([event, eventListener]);
+    }
+    const endSession = () => {
+      this.activeEndCountDownAbortController.abort();
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      window.removeEventListener('visibilitychange', this.activeEndCountDownVisibilityListener);
+      for (const activeEndListener of this.activeEndListeners) {
+        window.removeEventListener(activeEndListener[0], activeEndListener[1]);
+      }
+      this.changePeriodAndTrackLast('active', 'inactive');
+    };
+
+    // When first setting up -- there has just been an interaction -- so we start a countdown
+    this.activeEndCountDownAbortController.abort();
+    this.activeEndCountDownAbortController = new AbortController();
+    startPeriodEndCountDown(this.activeEndCountDownAbortController.signal, () => {
+      endSession();
+    });
+  }
+  changePeriodAndTrackLast(lastPeriod, newPeriod) {
+    var _this$activeEndCountD;
+    this.periodMeasurements[lastPeriod].duration = this.periodMeasurements[lastPeriod].duration + (performance.now() - this.currentPeriodStart);
+    this.periodMeasurements[lastPeriod].count++;
+    const interactivityMeasuresPaused = this.latestHeavyTasks.size !== 0;
+    for (const interactivityMeasure of this.session.insm.periodMeasurers) {
+      const finalResult = newPeriod ? interactivityMeasure.start(interactivityMeasuresPaused) : interactivityMeasure.end();
+      const tracked = this.periodMeasurements[lastPeriod].measurements[interactivityMeasure.name];
+      if (finalResult.average === 0) {
+        // In this case -- we haven't had any measurements complete since last measurement
+        // so we do nothing
+      } else if (tracked.average === 0) {
+        // In this case -- we haven't had any entries come through yet - so we replace any existing entries
+        this.periodMeasurements[lastPeriod].measurements[interactivityMeasure.name] = finalResult;
+      } else {
+        // In this case there is a new measurement which we merge with the previous measurement
+        const merged = {
+          numerator: finalResult.numerator + tracked.numerator,
+          denominator: finalResult.denominator + tracked.denominator,
+          average: (finalResult.numerator + tracked.numerator) / (finalResult.denominator + tracked.denominator),
+          max: tracked.max === 0 || finalResult.max > tracked.max ? finalResult.max : tracked.max,
+          min: tracked.min === 0 || finalResult.min < tracked.min ? finalResult.min : tracked.min
+        };
+        this.periodMeasurements[lastPeriod].measurements[interactivityMeasure.name] = merged;
+      }
+    }
+    for (const listener of this.activeStartListeners) {
+      window.removeEventListener(listener[0], listener[1]);
+    }
+    for (const listener of this.activeEndListeners) {
+      window.removeEventListener(listener[0], listener[1]);
+    }
+    (_this$activeEndCountD = this.activeEndCountDownAbortController) === null || _this$activeEndCountD === void 0 ? void 0 : _this$activeEndCountD.abort();
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    window.removeEventListener('visibilitychange', this.activeEndCountDownVisibilityListener);
+    if (newPeriod) {
+      this.latestPeriodFeatures = new Set(this.session.runningFeatures);
+      this.session.runningFeatures.forEach(featureName => {
+        this.periodMeasurements[newPeriod].features.add(featureName);
+      });
+      this.latestHeavyTasks = new Set(this.session.insm.runningHeavyTasks);
+      this.currentPeriodStart = performance.now();
+      switch (newPeriod) {
+        case 'active':
+          this.setupEndActiveInteractionListeners();
+          this.state = 'active';
+          break;
+        case 'inactive':
+          this.setupActiveStartInteractionListeners();
+          this.state = 'inactive';
+          break;
+      }
+    }
+  }
+}
+function startPeriodEndCountDown(signal, handleEnd) {
+  let animationFramesSinceLastInteraction = 0;
+  let inactiveTimeReached = false;
+  let timer;
+  let animationFrameHandler;
+  const monitorAnimationFrames = () => {
+    animationFrameHandler = requestAnimationFrame(() => {
+      animationFramesSinceLastInteraction++;
+      if (animationFramesSinceLastInteraction < 3) {
+        monitorAnimationFrames();
+      } else {
+        if (inactiveTimeReached) {
+          handleEnd();
+        }
+      }
+    });
+  };
+  const monitorTime = () => {
+    timer = setTimeout(() => {
+      inactiveTimeReached = true;
+      if (animationFramesSinceLastInteraction === 3) {
+        handleEnd();
+      }
+    }, 3000);
+  };
+  monitorTime();
+  monitorAnimationFrames();
+  signal.addEventListener('abort', () => {
+    clearTimeout(timer);
+    cancelAnimationFrame(animationFrameHandler);
+  });
+}