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

package/CHANGELOG.md

@@ -1,11 +1,42 @@
+# 3.0.0 - 2024-03-18
+
+## Added
+
+1. Adds a `disabled` option and the ability to change it later via `posthog.disabled = true`. Useful for disabling PostHog tracking for example in a testing environment without having complex conditional checking
+2. `shutdown` takes a `shutdownTimeoutMs` param with a default of 30000 (30s). This is the time to wait for flushing events before shutting down the client. If the timeout is reached, the client will be shut down regardless of pending events.
+3. Adds a new `featureFlagsRequestTimeoutMs` timeout parameter for feature flags which defaults to 10 seconds.
+4. Flushes will now try to flush up to `maxBatchSize` (default 100) in one go
+5. Queued events are limited up to `maxQueueSize` (default 1000) and the oldest events are dropped when the limit is reached
+
+## Removed
+
+1. Removes the `enable` option. You can now specify `defaultOptIn: false` to start the SDK opted out of tracking
+2. `flushAsync` and `shutdownAsync` are removed with `flush` and `shutdown` now being the async methods.
+
+## Changed
+
+1. `flush` and `shutdown` now being async methods.
+2. Many methods such as `capture` and `identify` no longer return the `this` object instead returning nothing
+
+## Fixed
+
+1. Fixed an issue where `shutdown` would potentially exit early if a flush was already in progress
+2. Fixes some typos in types
+
+# 3.0.0-beta.2 - 2024-03-12
+
+1. `flushAsync` and `shutdownAsync` are removed with `flush` and `shutdown` now being the async methods.
+2. Fixed an issue where `shutdownAsync` would potentially exit early if a flush was already in progress
+3. Flushes will now try to flush up to `maxBatchSize` (default 100) in one go
+
 # 3.0.0-beta.1 - 2024-03-04
 
-- Removes the `enable` option. You can now specify `defaultOptIn: false` to start the SDK opted out of tracking
-- Adds a `disabled` option and the ability to change it later via `posthog.disabled = true`. Useful for disabling PostHog tracking for example in a testing environment without having complex conditional checking
-- Many methods such as `capture` and `identify` no longer return the `this` object instead returning nothing
-- Fixes some typos in types
-- `shutdown` and `shutdownAsync` takes a `shutdownTimeoutMs` param with a default of 30000 (30s). This is the time to wait for flushing events before shutting down the client. If the timeout is reached, the client will be shut down regardless of pending events.
-- Adds a new `featureFlagsRequestTimeoutMs` timeout parameter for feature flags which defaults to 10 seconds.
+1. Removes the `enable` option. You can now specify `defaultOptIn: false` to start the SDK opted out of tracking
+2. Adds a `disabled` option and the ability to change it later via `posthog.disabled = true`. Useful for disabling PostHog tracking for example in a testing environment without having complex conditional checking
+3. Many methods such as `capture` and `identify` no longer return the `this` object instead returning nothing
+4. Fixes some typos in types
+5. `shutdown` and `shutdownAsync` takes a `shutdownTimeoutMs` param with a default of 30000 (30s). This is the time to wait for flushing events before shutting down the client. If the timeout is reached, the client will be shut down regardless of pending events.
+6. Adds a new `featureFlagsRequestTimeoutMs` timeout parameter for feature flags which defaults to 10 seconds.
 
 # 2.6.2 - 2024-02-15
 

package/lib/index.cjs.js

@@ -946,6 +946,7 @@ function isPostHogFetchError(err) {
 }
 class PostHogCoreStateless {
     constructor(apiKey, options) {
+        this.flushPromise = null;
         this.disableGeoip = true;
         this.disabled = false;
         this.defaultOptIn = true;
@@ -957,6 +958,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
@@ -1035,9 +1038,12 @@ class PostHogCoreStateless {
     addPendingPromise(promise) {
         const promiseUUID = uuidv7();
         this.pendingPromises[promiseUUID] = promise;
-        promise.finally(() => {
+        promise
+            .catch(() => { })
+            .finally(() => {
             delete this.pendingPromises[promiseUUID];
         });
+        return promise;
     }
     /***
      *** TRACKING
@@ -1102,7 +1108,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,
@@ -1212,80 +1218,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;
@@ -1316,15 +1348,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) {
@@ -1333,7 +1362,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) {
@@ -1348,9 +1377,6 @@ class PostHogCoreStateless {
             console.error('Error while shutting down PostHog', e);
         }
     }
-    shutdown(shutdownTimeoutMs) {
-        void this.shutdownAsync(shutdownTimeoutMs);
-    }
 }
 class PostHogCore extends PostHogCoreStateless {
     constructor(apiKey, options) {
@@ -1816,7 +1842,7 @@ class PostHogCore extends PostHogCoreStateless {
     }
 }
 
-var version = "3.0.0-beta.1";
+var version = "3.0.0";
 
 function getContext(window) {
   let context = {};