⚗️ Add partial view updates foundation

- Add PARTIAL_VIEW_UPDATES to ExperimentalFeature enum
- Add VIEW_UPDATE to RumEventType, RawRumViewUpdateEvent, and RawRumEvent union
- Add viewDiff.ts: isEqual and diffMerge utilities implementing MERGE / REPLACE /
  APPEND strategies for computing minimal diffs between assembled view events

Author: mormubis

packages/core/src/tools/experimentalFeatures.ts

@@ -25,6 +25,8 @@ export enum ExperimentalFeature {
   LCP_SUBPARTS = 'lcp_subparts',
   INP_SUBPARTS = 'inp_subparts',
   TOO_MANY_REQUESTS_INVESTIGATION = 'too_many_requests_investigation',
+  PARTIAL_VIEW_UPDATES = 'partial_view_updates',
+  PARTIAL_VIEW_UPDATES_NO_CHECKPOINT = 'partial_view_updates_no_checkpoint',
 }
 
 const enabledExperimentalFeatures: Set<ExperimentalFeature> = new Set()

packages/rum-core/src/domain/view/viewDiff.spec.ts

@@ -0,0 +1,116 @@
+import { isEqual, diffMerge } from './viewDiff'
+
+describe('isEqual', () => {
+  it('should return true for identical primitives', () => {
+    expect(isEqual(1, 1)).toBe(true)
+    expect(isEqual('a', 'a')).toBe(true)
+    expect(isEqual(true, true)).toBe(true)
+    expect(isEqual(null, null)).toBe(true)
+    expect(isEqual(undefined, undefined)).toBe(true)
+  })
+
+  it('should return false for different primitives', () => {
+    expect(isEqual(1, 2)).toBe(false)
+    expect(isEqual('a', 'b')).toBe(false)
+    expect(isEqual(true, false)).toBe(false)
+    expect(isEqual(null, undefined)).toBe(false)
+  })
+
+  it('should return true for deeply equal objects', () => {
+    expect(isEqual({ a: 1, b: { c: 2 } }, { a: 1, b: { c: 2 } })).toBe(true)
+  })
+
+  it('should return false for objects with different values', () => {
+    expect(isEqual({ a: 1 }, { a: 2 })).toBe(false)
+  })
+
+  it('should return false for objects with different keys', () => {
+    expect(isEqual({ a: 1 }, { b: 1 })).toBe(false)
+  })
+
+  it('should return true for equal arrays', () => {
+    expect(isEqual([1, 2, 3], [1, 2, 3])).toBe(true)
+  })
+
+  it('should return false for arrays with different lengths', () => {
+    expect(isEqual([1, 2], [1, 2, 3])).toBe(false)
+  })
+
+  it('should return false for arrays with different values', () => {
+    expect(isEqual([1, 2, 3], [1, 2, 4])).toBe(false)
+  })
+
+  it('should return false when comparing array to non-array', () => {
+    expect(isEqual([1], { 0: 1 })).toBe(false)
+  })
+
+  it('should return false for type mismatch', () => {
+    expect(isEqual(1, '1')).toBe(false)
+  })
+})
+
+describe('diffMerge', () => {
+  it('should return undefined when there are no changes', () => {
+    const result = diffMerge({ a: 1, b: 'x' }, { a: 1, b: 'x' })
+    expect(result).toBeUndefined()
+  })
+
+  it('should return changed primitive fields', () => {
+    const result = diffMerge({ a: 1, b: 2 }, { a: 1, b: 1 })
+    expect(result).toEqual({ b: 2 })
+  })
+
+  it('should include new fields not present in lastSent', () => {
+    const result = diffMerge({ a: 1, b: 2 }, { a: 1 })
+    expect(result).toEqual({ b: 2 })
+  })
+
+  it('should set null for deleted keys', () => {
+    const result = diffMerge({ a: 1 }, { a: 1, b: 2 })
+    expect(result).toEqual({ b: null })
+  })
+
+  it('should recursively diff nested objects', () => {
+    const result = diffMerge({ nested: { x: 1, y: 2 } }, { nested: { x: 1, y: 1 } })
+    expect(result).toEqual({ nested: { y: 2 } })
+  })
+
+  it('should return undefined for unchanged nested objects', () => {
+    const result = diffMerge({ nested: { x: 1 } }, { nested: { x: 1 } })
+    expect(result).toBeUndefined()
+  })
+
+  it('should include new nested objects', () => {
+    const result = diffMerge({ nested: { x: 1 } }, {})
+    expect(result).toEqual({ nested: { x: 1 } })
+  })
+
+  describe('replaceKeys option', () => {
+    it('should use full replace strategy for specified keys', () => {
+      const result = diffMerge({ arr: [1, 2, 3] }, { arr: [1, 2] }, { replaceKeys: new Set(['arr']) })
+      expect(result).toEqual({ arr: [1, 2, 3] })
+    })
+
+    it('should not include replace key if unchanged', () => {
+      const result = diffMerge({ arr: [1, 2] }, { arr: [1, 2] }, { replaceKeys: new Set(['arr']) })
+      expect(result).toBeUndefined()
+    })
+  })
+
+  describe('appendKeys option', () => {
+    it('should append only new trailing elements for array keys', () => {
+      const result = diffMerge({ items: [1, 2, 3] }, { items: [1, 2] }, { appendKeys: new Set(['items']) })
+      expect(result).toEqual({ items: [3] })
+    })
+
+    it('should include full array when it first appears', () => {
+      const result = diffMerge({ items: [1, 2] }, {}, { appendKeys: new Set(['items']) })
+      expect(result).toEqual({ items: [1, 2] })
+    })
+
+    it('should not include append key if array has not grown', () => {
+      const result = diffMerge({ items: [1, 2] }, { items: [1, 2] }, { appendKeys: new Set(['items']) })
+      expect(result).toBeUndefined()
+    })
+  })
+})

packages/rum-core/src/domain/view/viewDiff.ts

@@ -0,0 +1,145 @@
+import { isEmptyObject } from '@datadog/browser-core'
+
+/**
+ * Compare two values for deep equality
+ */
+export function isEqual(a: unknown, b: unknown): boolean {
+  // Reference equality
+  if (a === b) {
+    return true
+  }
+
+  // Handle null/undefined
+  if (a === null || b === null || a === undefined || b === undefined) {
+    return a === b
+  }
+
+  // Type mismatch
+  if (typeof a !== typeof b) {
+    return false
+  }
+
+  // Primitives
+  if (typeof a !== 'object') {
+    return a === b
+  }
+
+  // Arrays
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) {
+      return false
+    }
+    return a.every((val, idx) => isEqual(val, b[idx]))
+  }
+
+  // One is array, other is not
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return false
+  }
+
+  // Objects
+  const aObj = a as Record<string, unknown>
+  const bObj = b as Record<string, unknown>
+  const aKeys = Object.keys(aObj)
+  const bKeys = Object.keys(bObj)
+
+  if (aKeys.length !== bKeys.length) {
+    return false
+  }
+
+  return aKeys.every((key) => bKeys.includes(key) && isEqual(aObj[key], bObj[key]))
+}
+
+/**
+ * Options for controlling diff merge behavior
+ */
+export interface DiffMergeOptions {
+  replaceKeys?: Set<string>
+  appendKeys?: Set<string>
+}
+
+/**
+ * MERGE strategy: compare two objects and return an object with only changed fields.
+ * Returns undefined if no changes.
+ */
+export function diffMerge(
+  current: Record<string, unknown>,
+  lastSent: Record<string, unknown>,
+  options?: DiffMergeOptions
+): Record<string, unknown> | undefined {
+  const result: Record<string, unknown> = {}
+  const replaceKeys = options?.replaceKeys || new Set<string>()
+  const appendKeys = options?.appendKeys || new Set<string>()
+
+  // Check all keys in current
+  for (const key of Object.keys(current)) {
+    const currentVal = current[key]
+    const lastSentVal = lastSent[key]
+
+    // REPLACE strategy for specific keys
+    if (replaceKeys.has(key)) {
+      if (!isEqual(currentVal, lastSentVal)) {
+        result[key] = currentVal
+      }
+      continue
+    }
+
+    // APPEND strategy for array keys
+    if (appendKeys.has(key)) {
+      if (Array.isArray(currentVal) && Array.isArray(lastSentVal)) {
+        if (currentVal.length > lastSentVal.length) {
+          // Include only new trailing elements
+          result[key] = currentVal.slice(lastSentVal.length)
+        }
+      } else if (Array.isArray(currentVal) && !lastSentVal) {
+        // Array appeared for the first time
+        result[key] = currentVal
+      }
+      continue
+    }
+
+    // Primitive comparison
+    if (currentVal !== null && typeof currentVal !== 'object') {
+      if (currentVal !== lastSentVal) {
+        result[key] = currentVal
+      }
+      continue
+    }
+
+    // Handle null explicitly
+    if (currentVal === null) {
+      if (currentVal !== lastSentVal) {
+        result[key] = currentVal
+      }
+      continue
+    }
+
+    // Array comparison (not in appendKeys)
+    if (Array.isArray(currentVal)) {
+      if (!isEqual(currentVal, lastSentVal)) {
+        result[key] = currentVal
+      }
+      continue
+    }
+
+    // Object comparison - recurse (no options propagation: replaceKeys/appendKeys apply only at top level)
+    if (typeof currentVal === 'object' && lastSentVal && typeof lastSentVal === 'object') {
+      const nestedDiff = diffMerge(currentVal as Record<string, unknown>, lastSentVal as Record<string, unknown>)
+      if (nestedDiff && !isEmptyObject(nestedDiff)) {
+        result[key] = nestedDiff
+      }
+    } else if (typeof currentVal === 'object' && !lastSentVal) {
+      // New object appeared
+      result[key] = currentVal
+    }
+  }
+
+  // Check for deleted keys (present in lastSent but not in current)
+  for (const key of Object.keys(lastSent)) {
+    if (!(key in current)) {
+      result[key] = null
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined
+}

packages/rum-core/src/rawRumEvent.types.ts

@@ -18,6 +18,7 @@ import type {
   RumLongTaskEvent,
   RumResourceEvent,
   RumViewEvent,
+  RumViewUpdateEvent,
   RumVitalEvent,
 } from './rumEvent.types'
 
@@ -26,6 +27,7 @@ export const RumEventType = {
   ERROR: 'error',
   LONG_TASK: 'long_task',
   VIEW: 'view',
+  VIEW_UPDATE: 'view_update',
   RESOURCE: 'resource',
   VITAL: 'vital',
 } as const
@@ -34,6 +36,7 @@ export type RumEventType = (typeof RumEventType)[keyof typeof RumEventType]
 
 export type AssembledRumEvent = (
   | RumViewEvent
+  | RumViewUpdateEvent
   | RumActionEvent
   | RumResourceEvent
   | RumErrorEvent
@@ -181,6 +184,19 @@ export interface RawRumViewEvent {
   }
 }
 
+export interface RawRumViewUpdateEvent {
+  date: TimeStamp
+  type: typeof RumEventType.VIEW_UPDATE
+  view: Partial<RawRumViewEvent['view']>
+  _dd: Partial<RawRumViewEvent['_dd']> & {
+    document_version: number
+  }
+  display?: Partial<ViewDisplay>
+  privacy?: RawRumViewEvent['privacy']
+  device?: RawRumViewEvent['device']
+  feature_flags?: Context
+}
+
 interface ViewDisplay {
   scroll: {
     max_depth?: number
@@ -407,6 +423,7 @@ export type RawRumEvent =
   | RawRumErrorEvent
   | RawRumResourceEvent
   | RawRumViewEvent
+  | RawRumViewUpdateEvent
   | RawRumLongTaskEvent
   | RawRumLongAnimationFrameEvent
   | RawRumActionEvent

packages/rum-core/test/fixtures.ts

@@ -119,6 +119,18 @@ export function createRawRumEvent(type: RumEventType, overrides?: Context): RawR
         },
         overrides
       )
+    case RumEventType.VIEW_UPDATE:
+      return combine(
+        {
+          type,
+          date: 0 as TimeStamp,
+          view: {},
+          _dd: {
+            document_version: 1,
+          },
+        },
+        overrides
+      )
   }
 }