Implement LUX.spaMode

Author: josephwynn-sc

docs/debug-parser/events.ts

@@ -154,9 +154,6 @@ export function getMessageForEvent(event: LogEventRecord, filters: string[]): st
 
       return "POST beacon send failed.";
 
-    case LogEvent.PostBeaconAlreadySent:
-      return "POST beacon cancelled (already sent).";
-
     case LogEvent.PostBeaconCancelled:
       return "POST beacon cancelled.";
 
@@ -272,6 +269,14 @@ function getEventName(event: LogEvent) {
       return "MarkLoadTimeCalled";
     case LogEvent.SendCancelledPageHidden:
       return "SendCancelledPageHidden";
+    case LogEvent.TriggerSoftNavigationCalled:
+      return "TriggerSoftNavigationCalled";
+    case LogEvent.SendTriggeredBySoftNavigation:
+      return "SendTriggeredBySoftNavigation";
+    case LogEvent.SendCancelledSpaMode:
+      return "SendCancelledSpaMode";
+    case LogEvent.BfCacheRestore:
+      return "BfCacheRestore";
     case LogEvent.SessionIsSampled:
       return "SessionIsSampled";
     case LogEvent.SessionIsNotSampled:
@@ -318,8 +323,6 @@ function getEventName(event: LogEvent) {
       return "PostBeaconTimeoutReached";
     case LogEvent.PostBeaconSent:
       return "PostBeaconSent";
-    case LogEvent.PostBeaconAlreadySent:
-      return "PostBeaconAlreadySent";
     case LogEvent.PostBeaconCancelled:
       return "PostBeaconCancelled";
     case LogEvent.PostBeaconStopRecording:
@@ -333,4 +336,6 @@ function getEventName(event: LogEvent) {
     case LogEvent.PostBeaconCollector:
       return "PostBeaconCollector";
   }
+
+  return "Unknown Event";
 }

docs/spa-mode.md

@@ -0,0 +1,7 @@
+# SPA Mode in lux.js
+
+## Migrating from `LUX.auto = false`
+
+- Remove `LUX.auto = false`.
+- Remove all `LUX.send()` calls. In SPA mode, the beacon is sent automatically. In some very rare cases you may want to send the beacon manually, which can be done by calling `LUX.send(true)` - **this is not recommended**.
+- Replace all `LUX.init()` calls with `LUX.startSoftNavigation()`.

src/beacon.ts

@@ -1,5 +1,6 @@
 import { ConfigObject, UserConfig } from "./config";
 import { wasPrerendered } from "./document";
+import * as Events from "./events";
 import Flags, { addFlag } from "./flags";
 import { addListener } from "./listeners";
 import Logger, { LogEvent } from "./logger";
@@ -160,6 +161,10 @@ export class Beacon {
   }
 
   send() {
+    if (this.isSent) {
+      return;
+    }
+
     this.logger.logEvent(LogEvent.PostBeaconSendCalled);
 
     for (const cb of this.onBeforeSendCbs) {
@@ -187,11 +192,6 @@ export class Beacon {
       return;
     }
 
-    if (this.isSent) {
-      this.logger.logEvent(LogEvent.PostBeaconAlreadySent);
-      return;
-    }
-
     // Only clear the max measure timeout if there's data to send.
     clearTimeout(this.maxMeasureTimeout);
 
@@ -215,6 +215,7 @@ export class Beacon {
       if (sendBeacon(beaconUrl, JSON.stringify(payload))) {
         this.isSent = true;
         this.logger.logEvent(LogEvent.PostBeaconSent, [beaconUrl, payload]);
+        Events.emit("beacon", payload);
       }
     } catch (e) {
       // Intentionally empty; handled below

src/config.ts

@@ -2,6 +2,10 @@ import { LuxGlobal } from "./global";
 import { ServerTimingConfig } from "./server-timing";
 import { UrlPatternMapping } from "./url-matcher";
 
+/**
+ * ConfigObject holds the parsed and normalised lux.js configuration. It is initialised once based
+ * on the `LUX` global.
+ */
 export interface ConfigObject {
   allowEmptyPostBeacon: boolean;
   auto: boolean;
@@ -28,6 +32,7 @@ export interface ConfigObject {
   sendBeaconOnPageHidden: boolean;
   serverTiming?: ServerTimingConfig;
   snippetVersion?: LuxGlobal["snippetVersion"];
+  spaMode: boolean;
   trackErrors: boolean;
   trackHiddenPages: boolean;
 }
@@ -37,7 +42,8 @@ export type UserConfig = Partial<ConfigObject>;
 const luxOrigin = "https://lux.speedcurve.com";
 
 export function fromObject(obj: UserConfig): ConfigObject {
-  const autoMode = getProperty(obj, "auto", true);
+  const spaMode = getProperty(obj, "spaMode", false);
+  const autoMode = spaMode ? false : getProperty(obj, "auto", true);
 
   return {
     allowEmptyPostBeacon: getProperty(obj, "allowEmptyPostBeacon", false),
@@ -57,13 +63,14 @@ export function fromObject(obj: UserConfig): ConfigObject {
     maxBeaconUTEntries: getProperty(obj, "maxBeaconUTEntries", 20),
     maxErrors: getProperty(obj, "maxErrors", 5),
     maxMeasureTime: getProperty(obj, "maxMeasureTime", 60_000),
-    measureUntil: getProperty(obj, "measureUntil", "onload"),
+    measureUntil: getProperty(obj, "measureUntil", spaMode ? "pagehidden" : "onload"),
     minMeasureTime: getProperty(obj, "minMeasureTime", 0),
     newBeaconOnPageShow: getProperty(obj, "newBeaconOnPageShow", false),
     pagegroups: getProperty(obj, "pagegroups"),
     samplerate: getProperty(obj, "samplerate", 100),
-    sendBeaconOnPageHidden: getProperty(obj, "sendBeaconOnPageHidden", autoMode),
+    sendBeaconOnPageHidden: getProperty(obj, "sendBeaconOnPageHidden", spaMode || autoMode),
     serverTiming: getProperty(obj, "serverTiming"),
+    spaMode,
     trackErrors: getProperty(obj, "trackErrors", true),
     trackHiddenPages: getProperty(obj, "trackHiddenPages", false),
   };

src/global.ts renamed to src/global.d.ts

@@ -3,30 +3,43 @@ import type { Event } from "./events";
 import type { LogEventRecord } from "./logger";
 
 export type Command = [CommandFunction, ...CommandArg[]];
-type CommandFunction = "addData" | "init" | "mark" | "markLoadTime" | "measure" | "on" | "send";
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type CommandArg = any;
+type CommandFunction =
+  | "addData"
+  | "init"
+  | "mark"
+  | "markLoadTime"
+  | "measure"
+  | "on"
+  | "send"
+  | "startSoftNavigation";
+
+type CommandArg = unknown;
 type PerfMarkFn = typeof performance.mark;
 type PerfMeasureFn = typeof performance.measure;
 
+/**
+ * LuxGlobal is the global `LUX` object. It is defined and modified by the snippet, lux.js and by
+ * the implementor.
+ */
 export interface LuxGlobal extends UserConfig {
   /** Command queue used to store actions that were initiated before the full script loads */
   ac?: Command[];
-  addData: (name: string, value: unknown) => void;
+  addData: (name: string, value?: unknown) => void;
   cmd: (cmd: Command) => void;
   /** @deprecated */
   doUpdate?: () => void;
   forceSample?: () => void;
-  getDebug?: () => LogEventRecord[];
+  getDebug: () => LogEventRecord[];
   getSessionId?: () => void;
-  init: () => void;
+  init: (time?: number) => void;
   mark: (...args: Parameters<PerfMarkFn>) => ReturnType<PerfMarkFn> | void;
-  markLoadTime?: (time?: number) => void;
+  markLoadTime: (time?: number) => void;
   measure: (...args: Parameters<PerfMeasureFn>) => ReturnType<PerfMeasureFn> | void;
   on: (event: Event, callback: (data?: unknown) => void) => void;
   /** Timestamp representing when the LUX snippet was evaluated */
   ns?: number;
-  send: () => void;
+  send: (force?: boolean) => void;
   snippetVersion?: string;
+  startSoftNavigation: (time?: number) => void;
   version?: string;
 }

src/logger.ts

@@ -15,6 +15,11 @@ export const enum LogEvent {
   OnloadHandlerTriggered = 11,
   MarkLoadTimeCalled = 12,
   SendCancelledPageHidden = 13,
+  TriggerSoftNavigationCalled = 14,
+  SendTriggeredBySoftNavigation = 15,
+  SendCancelledSpaMode = 16,
+  BfCacheRestore = 17,
+  InitCallIgnored = 18,
 
   // Data collection events
   SessionIsSampled = 21,
@@ -48,7 +53,6 @@ export const enum LogEvent {
   PostBeaconSendCalled = 81,
   PostBeaconTimeoutReached = 82,
   PostBeaconSent = 83,
-  PostBeaconAlreadySent = 84,
   PostBeaconCancelled = 85,
   PostBeaconStopRecording = 86,
   PostBeaconMetricRejected = 87,