ref(replay): Add jsdoc to all replay modules (#6654)

This is one more step of #6323.

Note that this also renames/moves a few things to make more sense.

Author: mydea

docs/event-sending.md

@@ -77,8 +77,8 @@ This document gives an outline for how event sending works, and which which plac
 ## Replay (WIP)
 
 * `replay.sendReplayRequest()`
-  * `createPayload()`
-  * `getReplayEvent()`
+  * `createRecordingData()`
+  * `prepareReplayEvent()`
     * `client._prepareEvent()` (see baseclient)
       * `baseclient._applyClientOptions()`
       * `baseclient._applyIntegrationsMetadata()`

packages/replay/.eslintrc.js

@@ -25,10 +25,8 @@ module.exports = {
       rules: {
         // TODO (high-prio): Re-enable this after migration
         '@typescript-eslint/explicit-member-accessibility': 'off',
-        // TODO (high-prio): Re-enable this after migration
+        // Since we target only es6 here, we can leave this off
         '@sentry-internal/sdk/no-async-await': 'off',
-        // TODO (medium-prio): Re-enable this after migration
-        'jsdoc/require-jsdoc': 'off',
       },
     },
     {

packages/replay/src/coreHandlers/breadcrumbHandler.ts

@@ -4,6 +4,9 @@ import type { InstrumentationTypeBreadcrumb } from '../types';
 import { DomHandlerData, handleDom } from './handleDom';
 import { handleScope } from './handleScope';
 
+/**
+ * An event handler to react to breadcrumbs.
+ */
 export function breadcrumbHandler(type: InstrumentationTypeBreadcrumb, handlerData: unknown): Breadcrumb | null {
   if (type === 'scope') {
     return handleScope(handlerData as Scope);

packages/replay/src/coreHandlers/handleDom.ts

@@ -9,6 +9,9 @@ export interface DomHandlerData {
   event: Node | { target: Node };
 }
 
+/**
+ * An event handler to react to DOM events.
+ */
 export function handleDom(handlerData: DomHandlerData): Breadcrumb | null {
   // Taken from https://github.com/getsentry/sentry-javascript/blob/master/packages/browser/src/integrations/breadcrumbs.ts#L112
   let target;

packages/replay/src/coreHandlers/handleFetch.ts

@@ -1,5 +1,4 @@
-import type { ReplayPerformanceEntry } from '../createPerformanceEntry';
-import type { ReplayContainer } from '../types';
+import type { ReplayContainer, ReplayPerformanceEntry } from '../types';
 import { createPerformanceSpans } from '../util/createPerformanceSpans';
 import { shouldFilterRequest } from '../util/shouldFilterRequest';
 

packages/replay/src/coreHandlers/handleHistory.ts

@@ -1,5 +1,4 @@
-import { ReplayPerformanceEntry } from '../createPerformanceEntry';
-import type { ReplayContainer } from '../types';
+import type { ReplayContainer, ReplayPerformanceEntry } from '../types';
 import { createPerformanceSpans } from '../util/createPerformanceSpans';
 
 interface HistoryHandlerData {

packages/replay/src/coreHandlers/handleScope.ts

@@ -4,6 +4,9 @@ import { createBreadcrumb } from '../util/createBreadcrumb';
 
 let _LAST_BREADCRUMB: null | Breadcrumb = null;
 
+/**
+ * An event handler to handle scope changes.
+ */
 export function handleScope(scope: Scope): Breadcrumb | null {
   const newBreadcrumb = scope.getLastBreadcrumb();
 

packages/replay/src/coreHandlers/handleXhr.ts

@@ -1,5 +1,4 @@
-import { ReplayPerformanceEntry } from '../createPerformanceEntry';
-import type { ReplayContainer } from '../types';
+import type { ReplayContainer, ReplayPerformanceEntry } from '../types';
 import { createPerformanceSpans } from '../util/createPerformanceSpans';
 import { shouldFilterRequest } from '../util/shouldFilterRequest';
 

packages/replay/src/createPerformanceEntry.ts

@@ -2,40 +2,12 @@ import { browserPerformanceTimeOrigin } from '@sentry/utils';
 import { record } from 'rrweb';
 
 import { WINDOW } from './constants';
-import type { AllPerformanceEntry, PerformanceNavigationTiming, PerformancePaintTiming } from './types';
-
-export interface ReplayPerformanceEntry {
-  /**
-   * One of these types https://developer.mozilla.org/en-US/docs/Web/API/PerformanceEntry/entryType
-   */
-  type: string;
-
-  /**
-   * A more specific description of the performance entry
-   */
-  name: string;
-
-  /**
-   * The start timestamp in seconds
-   */
-  start: number;
-
-  /**
-   * The end timestamp in seconds
-   */
-  end: number;
-
-  /**
-   * Additional unstructured data to be included
-   */
-  data?: Record<string, unknown>;
-}
-
-interface MemoryInfo {
-  jsHeapSizeLimit: number;
-  totalJSHeapSize: number;
-  usedJSHeapSize: number;
-}
+import type {
+  AllPerformanceEntry,
+  PerformanceNavigationTiming,
+  PerformancePaintTiming,
+  ReplayPerformanceEntry,
+} from './types';
 
 // Map entryType -> function to normalize data for event
 // @ts-ignore TODO: entry type does not fit the create* functions entry type
@@ -46,9 +18,12 @@ const ENTRY_TYPES: Record<string, (entry: AllPerformanceEntry) => null | ReplayP
   // @ts-ignore TODO: entry type does not fit the create* functions entry type
   navigation: createNavigationEntry,
   // @ts-ignore TODO: entry type does not fit the create* functions entry type
-  ['largest-contentful-paint']: createLargestContentfulPaint,
+  'largest-contentful-paint': createLargestContentfulPaint,
 };
 
+/**
+ * Create replay performance entries from the browser performance entries.
+ */
 export function createPerformanceEntries(entries: AllPerformanceEntry[]): ReplayPerformanceEntry[] {
   return entries.map(createPerformanceEntry).filter(Boolean) as ReplayPerformanceEntry[];
 }
@@ -67,9 +42,7 @@ function getAbsoluteTime(time: number): number {
   return ((browserPerformanceTimeOrigin || WINDOW.performance.timeOrigin) + time) / 1000;
 }
 
-// TODO: type definition!
-// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-function createPaintEntry(entry: PerformancePaintTiming) {
+function createPaintEntry(entry: PerformancePaintTiming): ReplayPerformanceEntry {
   const { duration, entryType, name, startTime } = entry;
 
   const start = getAbsoluteTime(startTime);
@@ -81,9 +54,7 @@ function createPaintEntry(entry: PerformancePaintTiming) {
   };
 }
 
-// TODO: type definition!
-// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-function createNavigationEntry(entry: PerformanceNavigationTiming) {
+function createNavigationEntry(entry: PerformanceNavigationTiming): ReplayPerformanceEntry | null {
   // TODO: There looks to be some more interesting bits in here (domComplete, domContentLoaded)
   const { entryType, name, duration, domComplete, startTime, transferSize, type } = entry;
 
@@ -104,9 +75,7 @@ function createNavigationEntry(entry: PerformanceNavigationTiming) {
   };
 }
 
-// TODO: type definition!
-// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-function createResourceEntry(entry: PerformanceResourceTiming) {
+function createResourceEntry(entry: PerformanceResourceTiming): ReplayPerformanceEntry | null {
   const { entryType, initiatorType, name, responseEnd, startTime, encodedBodySize, transferSize } = entry;
 
   // Core SDK handles these
@@ -126,9 +95,9 @@ function createResourceEntry(entry: PerformanceResourceTiming) {
   };
 }
 
-// TODO: type definition!
-// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-function createLargestContentfulPaint(entry: PerformanceEntry & { size: number; element: Node }) {
+function createLargestContentfulPaint(
+  entry: PerformanceEntry & { size: number; element: Node },
+): ReplayPerformanceEntry {
   const { duration, entryType, startTime, size } = entry;
 
   const start = getAbsoluteTime(startTime);
@@ -147,25 +116,3 @@ function createLargestContentfulPaint(entry: PerformanceEntry & { size: number;
     },
   };
 }
-
-type ReplayMemoryEntry = ReplayPerformanceEntry & { data: { memory: MemoryInfo } };
-
-export function createMemoryEntry(memoryEntry: MemoryInfo): ReplayMemoryEntry {
-  const { jsHeapSizeLimit, totalJSHeapSize, usedJSHeapSize } = memoryEntry;
-  // we don't want to use `getAbsoluteTime` because it adds the event time to the
-  // time origin, so we get the current timestamp instead
-  const time = new Date().getTime() / 1000;
-  return {
-    type: 'memory',
-    name: 'memory',
-    start: time,
-    end: time,
-    data: {
-      memory: {
-        jsHeapSizeLimit,
-        totalJSHeapSize,
-        usedJSHeapSize,
-      },
-    },
-  };
-}

packages/replay/src/eventBuffer.ts

@@ -12,6 +12,9 @@ interface CreateEventBufferParams {
   useCompression: boolean;
 }
 
+/**
+ * Create an event buffer for replays.
+ */
 export function createEventBuffer({ useCompression }: CreateEventBufferParams): EventBuffer {
   // eslint-disable-next-line no-restricted-globals
   if (useCompression && window.Worker) {
@@ -72,7 +75,10 @@ class EventBufferArray implements EventBuffer {
   }
 }
 
-// exporting for testing
+/**
+ * Event buffer that uses a web worker to compress events.
+ * Exported only for testing.
+ */
 export class EventBufferCompressionWorker implements EventBuffer {
   private _worker: null | Worker;
   private _eventBufferItemLength: number = 0;
@@ -90,12 +96,18 @@ export class EventBufferCompressionWorker implements EventBuffer {
     return this._eventBufferItemLength;
   }
 
+  /**
+   * Destroy the event buffer.
+   */
   public destroy(): void {
     __DEBUG_BUILD__ && logger.log('[Replay] Destroying compression worker');
     this._worker?.terminate();
     this._worker = null;
   }
 
+  /**
+   * Add an event to the event buffer.
+   */
   public async addEvent(event: RecordingEvent, isCheckout?: boolean): Promise<ReplayRecordingData> {
     if (isCheckout) {
       // This event is a checkout, make sure worker buffer is cleared before
@@ -110,6 +122,9 @@ export class EventBufferCompressionWorker implements EventBuffer {
     return this._sendEventToWorker(event);
   }
 
+  /**
+   * Finish the event buffer and return the compressed data.
+   */
   public finish(): Promise<Uint8Array> {
     return this._finishRequest(this._getAndIncrementId());
   }
@@ -160,6 +175,9 @@ export class EventBufferCompressionWorker implements EventBuffer {
     });
   }
 
+  /**
+   * Send the event to the worker.
+   */
   private _sendEventToWorker(event: RecordingEvent): Promise<ReplayRecordingData> {
     const promise = this._postMessage({
       id: this._getAndIncrementId(),
@@ -173,6 +191,9 @@ export class EventBufferCompressionWorker implements EventBuffer {
     return promise;
   }
 
+  /**
+   * Finish the request and return the compressed data from the worker.
+   */
   private async _finishRequest(id: number): Promise<Uint8Array> {
     const promise = this._postMessage({ id, method: 'finish', args: [] });
 
@@ -182,6 +203,7 @@ export class EventBufferCompressionWorker implements EventBuffer {
     return promise as Promise<Uint8Array>;
   }
 
+  /** Get the current ID and increment it for the next call. */
   private _getAndIncrementId(): number {
     return this._id++;
   }