@atlaskit/insm 0.0.1 → 0.1.0

package/dist/types-ts4.5/insm-period.d.ts

@@ -0,0 +1,72 @@
+import type { INSMSession } from './insm-session';
+import type { Measure } from './types';
+export declare class PeriodTracking {
+    private periodMeasurements;
+    /**
+     * On creation - this is set to the currently running sessions features,
+     * and is updated throughout the period for any additional features triggered.
+     * It is reset when starting a new period.
+     */
+    private latestPeriodFeatures;
+    private latestHeavyTasks;
+    state: 'inactive' | 'active';
+    pauses: Set<string>;
+    /**
+     * Warning: this can be reset mid period when pausing/resuming.
+     * It's intended use is to build the `periodMeasurements` duration.
+     */
+    private currentPeriodStart;
+    private session;
+    constructor(session: INSMSession);
+    startFeature(featureName: string): void;
+    startHeavyTask(heavyTaskName: string): void;
+    endHeavyTask(heavyTaskName: string): void;
+    /**
+     * 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: string): void;
+    /**
+     * Releases a pause for a key.
+     *
+     * **NOTE**: The session will only resume if this was the only
+     * currently tracked pause key.
+     */
+    resume(pauseName: string): void;
+    get endResults(): {
+        active: {
+            features: Set<string>;
+            heavyTasks: Set<string>;
+            measurements: {
+                [key: string]: Measure;
+            };
+            duration: number;
+            count: number;
+        };
+        inactive: {
+            features: Set<string>;
+            heavyTasks: Set<string>;
+            measurements: {
+                [key: string]: Measure;
+            };
+            duration: number;
+            count: number;
+        };
+    };
+    private activeStartListeners;
+    private setupActiveStartInteractionListeners;
+    private 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
+     */
+    private activeEndCountDownAbortController;
+    private activeEndCountDownVisibilityListener;
+    private setupEndActiveInteractionListeners;
+    private changePeriodAndTrackLast;
+}

package/dist/types-ts4.5/insm-session.d.ts

@@ -0,0 +1,91 @@
+import type { INSM } from './insm';
+import type { AddedProperties, ExperienceProperties } from './types';
+import { PeriodTracking } from './insm-period';
+/**
+ * Only intended for internal use.
+ *
+ * Exported for consumers who may require the type.
+ */
+export declare class INSMSession {
+    private experienceKey;
+    private experienceProperties;
+    private startedAt;
+    insm: INSM;
+    private running;
+    private addedProperties;
+    runningFeatures: Set<string>;
+    periodTracking: PeriodTracking;
+    constructor(experienceKey: string, experienceProperties: ExperienceProperties, insm: INSM);
+    /**
+     * Adds a feature to the currently running session
+     */
+    startFeature(featureName: string): void;
+    /**
+     * Ends a features usage in the currently running session
+     */
+    endFeature(featureName: string): void;
+    /**
+     * Returns details on the current session.
+     */
+    get details(): {
+        experienceKey: string;
+        experienceProperties: ExperienceProperties;
+        paused: boolean;
+        periodState: "inactive" | "active";
+        /**
+         * The only scenario where this value should return false is when
+         * the experience has been stopped early.
+         */
+        running: boolean;
+    };
+    /**
+     * 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: AddedProperties): void;
+    /**
+     * 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: string, description?: string): void;
+    end(endDetails: {
+        stoppedBy: 'new-experience';
+        experienceKey: string;
+        contentId?: string | null;
+    } | {
+        stoppedBy: 'pagehide';
+    } | {
+        stoppedBy: 'early-stop';
+        reason: string;
+        description?: string;
+    }): void;
+}

package/dist/types-ts4.5/insm.d.ts

@@ -0,0 +1,61 @@
+import type { AnalyticsWebClient } from '@atlaskit/analytics-listeners';
+import { INSMSession } from './insm-session';
+import type { ExperienceProperties, INSMOptions } from './types';
+import { AnimationFPSIM } from './period-measurers/afps';
+import { INPTracker } from './inp-measurers/inp';
+export declare class INSM {
+    analyticsWebClient?: AnalyticsWebClient;
+    runningSession?: INSMSession;
+    options: INSMOptions;
+    periodMeasurers: [
+        AnimationFPSIM,
+        INPTracker,
+        INPTracker,
+        INPTracker,
+        INPTracker,
+        INPTracker,
+        INPTracker
+    ];
+    /**
+     * Heavy tasks are tracked at the insm layer as heavy tasks
+     * are expected at times to be unrelated to the current
+     * page session.
+     */
+    runningHeavyTasks: Set<string>;
+    constructor(options: INSMOptions);
+    /**
+     * Starts a heavy task in the currently running session.
+     *
+     * This also pauses measurement.
+     */
+    startHeavyTask(heavyTaskName: string): void;
+    /**
+     * Ends a heavy task in the currently running session
+     */
+    endHeavyTask(heavyTaskName: string): void;
+    /**
+     * 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: string, experienceProperties: ExperienceProperties): void;
+    /**
+     * This prematurely halts any running experience measurement. It's expected to be used in
+     * scenarios such as when error boundaries are hit.
+     */
+    stopEarly(reasonKey: string, description: string): void;
+    /**
+     * Gets the current running session details
+     */
+    get session(): INSMSession | undefined;
+}

package/dist/types-ts4.5/period-measurers/afps.d.ts

@@ -0,0 +1,57 @@
+import type { PeriodMeasurer } from '../types';
+export declare class AnimationFPSIM implements PeriodMeasurer {
+    /**
+     * AFPS stands for Animation Frames Per Second
+     */
+    name: string;
+    monitor: AnimationFPSMonitor;
+    start(paused: boolean): {
+        numerator: number;
+        denominator: number;
+        max: number;
+        min: number;
+        average: number;
+    };
+    end(): {
+        numerator: number;
+        denominator: number;
+        max: number;
+        min: number;
+        average: number;
+    };
+    pause(): void;
+    resume(): void;
+}
+declare class AnimationFPSMonitor {
+    paused: boolean;
+    private currentState;
+    private windowFrameCount;
+    private windowTotalTime;
+    private currentFrameStart;
+    animationFrame?: ReturnType<typeof requestAnimationFrame>;
+    private measureWindowFPS;
+    /**
+     * If there is running tracking - it will be reset
+     */
+    private startWindowTracking;
+    startNewWindow(paused: boolean): {
+        numerator: number;
+        denominator: number;
+        max: number;
+        min: number;
+        average: number;
+    };
+    private resetWindow;
+    private endWindowTracking;
+    private resetOverallTracking;
+    end(): {
+        numerator: number;
+        denominator: number;
+        max: number;
+        min: number;
+        average: number;
+    };
+    pause(): void;
+    resume(): void;
+}
+export {};

package/dist/types-ts4.5/types.d.ts

@@ -0,0 +1,81 @@
+import type { AnalyticsWebClient } from '@atlaskit/analytics-listeners';
+export type INSMOptions = {
+    getAnalyticsWebClient: Promise<AnalyticsWebClient>;
+    /**
+     * If an experience is missing or not enabled - no session event will be fired
+     */
+    experiences: {
+        [key: string]: {
+            enabled: boolean;
+        } | undefined;
+    };
+};
+export type ExperienceProperties = {
+    /**
+     * Whether this represents the initial page the user is visiting
+     */
+    initial: boolean;
+    /**
+     * An optional content id (ie. for a Confluence page - the page id)
+     *
+     * Leaf experiences such as the Confluence Space Overview are
+     * not expected to provide this property.
+     */
+    contentId?: string | null;
+};
+export type AddedProperties = {
+    [key: string]: string | number | boolean;
+} | (() => {
+    [key: string]: string | number | boolean;
+});
+export type Measure = {
+    numerator: number;
+    denominator: number;
+    max: number;
+    min: number;
+    average: number;
+};
+export interface PeriodMeasurer {
+    /**
+     * Name of the interactivity measurement (measures in the resulting insm event will be under this key)
+     */
+    name: string;
+    /**
+     * Called when an the state changes, and/or a new experience session starts.
+     *
+     * Implementers should take care to handle if measurements can be received after
+     * an animation frame.  In this scenario, on resetting - the consumer needs to
+     * discard any measurements started before the reset.
+     *
+     * The possibility of data loss due to this is mitigated by the inactive period logic
+     * where a session can not be marked as inactive until
+     * - at least 3 seconds of no user activity
+     * - and 2 animation frames since the last user activity.
+     *
+     * **Important** consumers need to handle starting up both initial tracking and also
+     * when tracking is restarted after an end.
+     *
+     * @returns The interactivity measurements for the current period (or undefined for the initial start)
+     */
+    start: (
+    /**
+     * When started with paused = true. it indicates a heavy task is running at startup time.
+     */
+    paused: boolean) => Measure | undefined;
+    /**
+     * Run any cleanup, and report the last periods interactivity.
+     *
+     * Important note: A new period can start after the end has been reached
+     * in cases where the measurement was ended due to a scenario such as an
+     * error boundary being hit (via `insm.stopEarly`).
+     */
+    end: () => Measure;
+    /**
+     * Pauses measurement (ie. when heavy work is triggered)
+     */
+    pause: () => void;
+    /**
+     * Pauses measurement (ie. when heavy work completes)
+     */
+    resume: () => void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/insm",
-	"version": "0.0.1",
+	"version": "0.1.0",
 	"description": "INSM tooling measures user-perceived interactivity of a page",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -24,13 +24,14 @@
 		}
 	},
 	"atlaskit:src": "src/index.ts",
-	"af:exports": {
-		".": "./src/index.ts"
-	},
 	"dependencies": {
-		"@atlaskit/tmp-editor-statsig": "^10.0.0",
+		"@atlaskit/analytics-listeners": "^9.0.0",
+		"@atlaskit/tmp-editor-statsig": "^11.9.0",
 		"@babel/runtime": "^7.0.0"
 	},
+	"devDependencies": {
+		"@atlaskit/editor-test-helpers": "workspace:^"
+	},
 	"peerDependencies": {
 		"react": "^18.2.0"
 	},