posthog-js-lite 3.0.0-beta.1 → 3.0.0

package/lib/index.d.ts

@@ -5,6 +5,12 @@ declare type PostHogCoreOptions = {
     flushAt?: number;
     /** The interval in milliseconds between periodic flushes */
     flushInterval?: number;
+    /** The maximum number of queued messages to be flushed as part of a single batch (must be higher than `flushAt`) */
+    maxBatchSize?: number;
+    /** The maximum number of cached messages either in memory or on the local storage.
+     * Defaults to 1000, (must be higher than `flushAt`)
+     */
+    maxQueueSize?: number;
     /** If set to true the SDK is essentially disabled (useful for local environments where you don't want to track anything) */
     disabled?: boolean;
     /** If set to false the SDK will not track until the `optIn` function is called. */
@@ -127,7 +133,10 @@ declare abstract class PostHogCoreStateless {
     private apiKey;
     host: string;
     private flushAt;
+    private maxBatchSize;
+    private maxQueueSize;
     private flushInterval;
+    private flushPromise;
     private requestTimeout;
     private featureFlagsRequestTimeoutMs;
     private captureMode;
@@ -157,7 +166,7 @@ declare abstract class PostHogCoreStateless {
     debug(enabled?: boolean): void;
     get isDebug(): boolean;
     private buildPayload;
-    protected addPendingPromise(promise: Promise<any>): void;
+    protected addPendingPromise<T>(promise: Promise<T>): Promise<T>;
     /***
      *** TRACKING
      ***/
@@ -189,11 +198,19 @@ declare abstract class PostHogCoreStateless {
      *** QUEUEING AND FLUSHING
      ***/
     protected enqueue(type: string, _message: any, options?: PostHogCaptureOptions): void;
-    flushAsync(): Promise<any>;
-    flush(callback?: (err?: any, data?: any) => void): void;
+    private clearFlushTimer;
+    /**
+     * Helper for flushing the queue in the background
+     * Avoids unnecessary promise errors
+     */
+    private flushBackground;
+    flush(): Promise<any[]>;
+    protected getCustomHeaders(): {
+        [key: string]: string;
+    };
+    private _flush;
     private fetchWithRetry;
-    shutdownAsync(shutdownTimeoutMs?: number): Promise<void>;
-    shutdown(shutdownTimeoutMs?: number): void;
+    shutdown(shutdownTimeoutMs?: number): Promise<void>;
 }
 declare abstract class PostHogCore extends PostHogCoreStateless {
     private sendFeatureFlagEvent;

package/lib/index.esm.js

@@ -942,6 +942,7 @@ function isPostHogFetchError(err) {
 }
 class PostHogCoreStateless {
     constructor(apiKey, options) {
+        this.flushPromise = null;
         this.disableGeoip = true;
         this.disabled = false;
         this.defaultOptIn = true;
@@ -953,6 +954,8 @@ class PostHogCoreStateless {
         this.apiKey = apiKey;
         this.host = removeTrailingSlash(options?.host || 'https://app.posthog.com');
         this.flushAt = options?.flushAt ? Math.max(options?.flushAt, 1) : 20;
+        this.maxBatchSize = Math.max(this.flushAt, options?.maxBatchSize ?? 100);
+        this.maxQueueSize = Math.max(this.flushAt, options?.maxQueueSize ?? 1000);
         this.flushInterval = options?.flushInterval ?? 10000;
         this.captureMode = options?.captureMode || 'form';
         // If enable is explicitly set to false we override the optout
@@ -1031,9 +1034,12 @@ class PostHogCoreStateless {
     addPendingPromise(promise) {
         const promiseUUID = uuidv7();
         this.pendingPromises[promiseUUID] = promise;
-        promise.finally(() => {
+        promise
+            .catch(() => { })
+            .finally(() => {
             delete this.pendingPromises[promiseUUID];
         });
+        return promise;
     }
     /***
      *** TRACKING
@@ -1098,7 +1104,7 @@ class PostHogCoreStateless {
         const url = `${this.host}/decide/?v=3`;
         const fetchOptions = {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
+            headers: { ...this.getCustomHeaders(), 'Content-Type': 'application/json' },
             body: JSON.stringify({
                 token: this.apiKey,
                 distinct_id: distinctId,
@@ -1208,80 +1214,106 @@ class PostHogCoreStateless {
                 delete message.distinctId;
             }
             const queue = this.getPersistedProperty(PostHogPersistedProperty.Queue) || [];
+            if (queue.length >= this.maxQueueSize) {
+                queue.shift();
+                console.info('Queue is full, the oldest event is dropped.');
+            }
             queue.push({ message });
             this.setPersistedProperty(PostHogPersistedProperty.Queue, queue);
             this._events.emit(type, message);
             // Flush queued events if we meet the flushAt length
             if (queue.length >= this.flushAt) {
-                this.flush();
+                this.flushBackground();
             }
             if (this.flushInterval && !this._flushTimer) {
-                this._flushTimer = safeSetTimeout(() => this.flush(), this.flushInterval);
+                this._flushTimer = safeSetTimeout(() => this.flushBackground(), this.flushInterval);
             }
         });
     }
-    async flushAsync() {
-        await this._initPromise;
-        return new Promise((resolve, reject) => {
-            this.flush((err, data) => {
-                return err ? reject(err) : resolve(data);
+    clearFlushTimer() {
+        if (this._flushTimer) {
+            clearTimeout(this._flushTimer);
+            this._flushTimer = undefined;
+        }
+    }
+    /**
+     * Helper for flushing the queue in the background
+     * Avoids unnecessary promise errors
+     */
+    flushBackground() {
+        void this.flush().catch(() => { });
+    }
+    async flush() {
+        if (!this.flushPromise) {
+            this.flushPromise = this._flush().finally(() => {
+                this.flushPromise = null;
             });
-        });
+            this.addPendingPromise(this.flushPromise);
+        }
+        return this.flushPromise;
     }
-    flush(callback) {
-        this.wrap(() => {
-            if (this._flushTimer) {
-                clearTimeout(this._flushTimer);
-                this._flushTimer = null;
-            }
-            const queue = this.getPersistedProperty(PostHogPersistedProperty.Queue) || [];
-            if (!queue.length) {
-                return callback?.();
+    getCustomHeaders() {
+        // Don't set the user agent if we're not on a browser. The latest spec allows
+        // the User-Agent header (see https://fetch.spec.whatwg.org/#terminology-headers
+        // and https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/setRequestHeader),
+        // but browsers such as Chrome and Safari have not caught up.
+        const customUserAgent = this.getCustomUserAgent();
+        const headers = {};
+        if (customUserAgent && customUserAgent !== '') {
+            headers['User-Agent'] = customUserAgent;
+        }
+        return headers;
+    }
+    async _flush() {
+        this.clearFlushTimer();
+        await this._initPromise;
+        const queue = this.getPersistedProperty(PostHogPersistedProperty.Queue) || [];
+        if (!queue.length) {
+            return [];
+        }
+        const items = queue.slice(0, this.maxBatchSize);
+        const messages = items.map((item) => item.message);
+        const persistQueueChange = () => {
+            const refreshedQueue = this.getPersistedProperty(PostHogPersistedProperty.Queue) || [];
+            this.setPersistedProperty(PostHogPersistedProperty.Queue, refreshedQueue.slice(items.length));
+        };
+        const data = {
+            api_key: this.apiKey,
+            batch: messages,
+            sent_at: currentISOTime(),
+        };
+        const payload = JSON.stringify(data);
+        const url = this.captureMode === 'form'
+            ? `${this.host}/e/?ip=1&_=${currentTimestamp()}&v=${this.getLibraryVersion()}`
+            : `${this.host}/batch/`;
+        const fetchOptions = this.captureMode === 'form'
+            ? {
+                method: 'POST',
+                mode: 'no-cors',
+                credentials: 'omit',
+                headers: { ...this.getCustomHeaders(), 'Content-Type': 'application/x-www-form-urlencoded' },
+                body: `data=${encodeURIComponent(LZString.compressToBase64(payload))}&compression=lz64`,
             }
-            const items = queue.splice(0, this.flushAt);
-            this.setPersistedProperty(PostHogPersistedProperty.Queue, queue);
-            const messages = items.map((item) => item.message);
-            const data = {
-                api_key: this.apiKey,
-                batch: messages,
-                sent_at: currentISOTime(),
-            };
-            const done = (err) => {
-                if (err) {
-                    this._events.emit('error', err);
-                }
-                callback?.(err, messages);
-                this._events.emit('flush', messages);
+            : {
+                method: 'POST',
+                headers: { ...this.getCustomHeaders(), 'Content-Type': 'application/json' },
+                body: payload,
             };
-            // Don't set the user agent if we're not on a browser. The latest spec allows
-            // the User-Agent header (see https://fetch.spec.whatwg.org/#terminology-headers
-            // and https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/setRequestHeader),
-            // but browsers such as Chrome and Safari have not caught up.
-            this.getCustomUserAgent();
-            const payload = JSON.stringify(data);
-            const url = this.captureMode === 'form'
-                ? `${this.host}/e/?ip=1&_=${currentTimestamp()}&v=${this.getLibraryVersion()}`
-                : `${this.host}/batch/`;
-            const fetchOptions = this.captureMode === 'form'
-                ? {
-                    method: 'POST',
-                    mode: 'no-cors',
-                    credentials: 'omit',
-                    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-                    body: `data=${encodeURIComponent(LZString.compressToBase64(payload))}&compression=lz64`,
-                }
-                : {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    body: payload,
-                };
-            const requestPromise = this.fetchWithRetry(url, fetchOptions);
-            this.addPendingPromise(requestPromise
-                .then(() => done())
-                .catch((err) => {
-                done(err);
-            }));
-        });
+        try {
+            await this.fetchWithRetry(url, fetchOptions);
+        }
+        catch (err) {
+            // depending on the error type, eg a malformed JSON or broken queue, it'll always return an error
+            // and this will be an endless loop, in this case, if the error isn't a network issue, we always remove the items from the queue
+            if (!(err instanceof PostHogFetchNetworkError)) {
+                persistQueueChange();
+            }
+            this._events.emit('error', err);
+            throw err;
+        }
+        persistQueueChange();
+        this._events.emit('flush', messages);
+        return messages;
     }
     async fetchWithRetry(url, options, retryOptions, requestTimeout) {
         var _a;
@@ -1312,15 +1344,12 @@ class PostHogCoreStateless {
             return res;
         }, { ...this._retryOptions, ...retryOptions });
     }
-    async shutdownAsync(shutdownTimeoutMs) {
+    async shutdown(shutdownTimeoutMs = 30000) {
         await this._initPromise;
-        clearTimeout(this._flushTimer);
+        this.clearFlushTimer();
         try {
-            await Promise.all(Object.values(this.pendingPromises).map((x) => x.catch(() => {
-                // ignore errors as we are shutting down and can't deal with them anyways.
-            })));
-            const timeout = shutdownTimeoutMs ?? 30000;
-            const startTimeWithDelay = Date.now() + timeout;
+            await Promise.all(Object.values(this.pendingPromises));
+            const startTimeWithDelay = Date.now() + shutdownTimeoutMs;
             while (true) {
                 const queue = this.getPersistedProperty(PostHogPersistedProperty.Queue) || [];
                 if (queue.length === 0) {
@@ -1329,7 +1358,7 @@ class PostHogCoreStateless {
                 // flush again to make sure we send all events, some of which might've been added
                 // while we were waiting for the pending promises to resolve
                 // For example, see sendFeatureFlags in posthog-node/src/posthog-node.ts::capture
-                await this.flushAsync();
+                await this.flush();
                 // If we've been waiting for more than the shutdownTimeoutMs, stop it
                 const now = Date.now();
                 if (startTimeWithDelay < now) {
@@ -1344,9 +1373,6 @@ class PostHogCoreStateless {
             console.error('Error while shutting down PostHog', e);
         }
     }
-    shutdown(shutdownTimeoutMs) {
-        void this.shutdownAsync(shutdownTimeoutMs);
-    }
 }
 class PostHogCore extends PostHogCoreStateless {
     constructor(apiKey, options) {
@@ -1812,7 +1838,7 @@ class PostHogCore extends PostHogCoreStateless {
     }
 }
 
-var version = "3.0.0-beta.1";
+var version = "3.0.0";
 
 function getContext(window) {
   let context = {};