feat: Accumulate Events

.editorconfig

@@ -0,0 +1,8 @@
+root=true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+indent_style = space
+indent_size = 2

src/EventAccumulator.ts

@@ -0,0 +1,99 @@
+import type { CountlyWebSdk, IEventAccumulator, CountlyEvent, CountlyEventData } from 'countly-sdk-web'
+
+const eventDefaults: CountlyEventData = {
+  key: '',
+  count: 1,
+  sum: 1,
+  dur: Date.now(),
+  segmentation: {}
+}
+
+interface eventStore {
+  eventData: CountlyEventData
+  startTime: number
+  timeout: NodeJS.Timeout
+}
+
+/**
+ * EventAccumulator is a class that accumulates events and flushes them to the Countly server.
+ */
+export class EventAccumulator implements IEventAccumulator {
+  private readonly metricsService: CountlyWebSdk
+  private readonly events: Record<string, eventStore>
+  private readonly flushInterval: number
+
+  /**
+   * Create a new EventAccumulator
+   *
+   * @param {CountlyWebSdk} metricsService - instance
+   * @param {number} flushInterval - in milliseconds
+   */
+  constructor (metricsService: CountlyWebSdk, flushInterval: number = 5 * 60 * 1000) {
+    this.metricsService = metricsService
+    this.flushInterval = flushInterval
+    this.events = {}
+  }
+
+  /**
+   * Add an event to the accumulator
+   *
+   * @param {CountlyEvent} event - event to add
+   * @param {boolean} flush - optionally whether to flush the event immediately
+   */
+  addEvent (event: CountlyEvent, flush: boolean = false): void {
+    // create a new event object with defaults.
+    const newEvent: CountlyEventData = { ...eventDefaults, ...event }
+    const { key, count } = newEvent
+
+    // validate event
+    if (key === '') {
+      throw new Error('Event key is required')
+    }
+
+    // if event is not in the store, add it.
+    if (!(key in this.events)) {
+      this.events[key] = {
+        eventData: newEvent,
+        // set start time to now. This will be updated when the event is flushed.
+        startTime: Date.now(),
+        // set a timeout to flush the event after the flush interval.
+        timeout: setTimeout(() => {
+          this.flush(key)
+        }, this.flushInterval)
+      }
+    } else {
+      // if event is in the store, update the event data.
+      const { eventData } = this.events[key]
+      eventData.count += count
+      eventData.sum += 1
+      eventData.segmentation = { ...eventData.segmentation, ...newEvent.segmentation }
+    }
+
+    // flush the event if flush is true.
+    if (flush) {
+      this.flush(key)
+    }
+  }
+
+  /**
+   * Flush an event from the accumulator
+   *
+   * @param {string} key - event key
+   */
+  flush (key: string): void {
+    // if event is not in the store, return.
+    if (!(key in this.events)) {
+      return
+    }
+
+    const { eventData, startTime, timeout } = this.events[key]
+
+    // update duration to ms from start.
+    eventData.dur = Date.now() - startTime
+    // add event to the async queue.
+    this.metricsService.q.push(['add_event', eventData])
+    clearTimeout(timeout)
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+    delete this.events[key]
+  }
+}

src/MetricsProvider.ts

@@ -1,21 +1,23 @@
 import { COUNTLY_SETUP_DEFAULTS } from './config.js'
+import { EventAccumulator } from './EventAccumulator.js'
 
-import type { metricFeatures, CountlyWebSdk } from 'countly-sdk-web'
 import type { CountlyNodeSdk } from 'countly-sdk-nodejs'
+import type { CountlyWebSdk, metricFeatures } from 'countly-sdk-web'
 import type { consentTypes, consentTypesExceptAll } from './types/index.js'
 
 export interface MetricsProviderConstructorOptions<T> {
   appKey: string
   autoTrack?: boolean
   interval?: number
   max_events?: number
+  metricsService: T
   queue_size?: number
   session_update?: number
   url?: string
-  metricsService: T
 }
 
 export default class MetricsProvider<T extends CountlyWebSdk & CountlyNodeSdk> {
+  public readonly accumulate: EventAccumulator
   private readonly groupedFeatures: Record<consentTypes, metricFeatures[]> = this.mapAllEvents({
     minimal: ['sessions', 'views', 'events'],
     performance: ['crashes', 'apm'],
@@ -40,6 +42,7 @@ export default class MetricsProvider<T extends CountlyWebSdk & CountlyNodeSdk> {
       url,
       require_consent: true
     })
+    this.accumulate = new EventAccumulator(metricsService)
 
     this.metricsService.init(serviceConfig)
     this.metricsService.group_features(this.groupedFeatures)

src/types/countly.d.ts

@@ -1,11 +1,12 @@
 declare module 'countly-sdk-web' {
-  interface CountlyEventData {
+  export interface CountlyEventData {
     key: string
     count: number
     sum: number
-    segmentation: Record<string, string | number>
+    dur: number
+    segmentation: Segments
   }
-  interface CountlyEvent {
+  export interface CountlyEvent {
     // name or id of the event
     key: string
     // how many times did event occur
@@ -18,12 +19,18 @@ declare module 'countly-sdk-web' {
     segmentation?: Segments
   }
 
+  export interface IEventAccumulator {
+    addEvent: (event: CountlyEvent, flush: boolean) => void
+    flush: (key: string) => void
+  }
+
   export type metricFeatures = 'apm' | 'attribution' | 'clicks' | 'crashes' | 'events' | 'feedback' | 'forms' |
   'location' | 'scrolls' | 'sessions' | 'star-rating' | 'users' | 'views'
   type Segments = Record<string, string>
   type IgnoreList = Array<string | RegExp>
   type CountlyEventQueueItem = [string, CountlyEventData] | [eventName: string, key: string] | [eventName: string]
   export interface CountlyWebSdk {
+    accumulate: IEventAccumulator
     group_features: (arg0: Record<import('./index.js').consentTypes, metricFeatures[]>) => unknown
     check_consent: (consentFeature: metricFeatures | import('./index.js').consentTypes) => boolean
     add_consent: (consentFeature: import('./index.js').consentTypes | Array<import('./index.js').consentTypes>) => void