posthog-node 4.15.0 → 4.16.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 4.16.0 - 2025-05-01
+
+1. chore: improve flush event
+
 # 4.15.0 - 2025-04-30
 
 1. chore: add immediate-mode

package/lib/index.cjs.js

@@ -22,7 +22,7 @@ function _interopNamespace(e) {
   return Object.freeze(n);
 }
 
-var version = "4.15.0";
+var version = "4.16.0";
 
 var PostHogPersistedProperty;
 (function (PostHogPersistedProperty) {
@@ -1260,6 +1260,9 @@ async function logFlushError(err) {
 function isPostHogFetchError(err) {
     return typeof err === 'object' && (err instanceof PostHogFetchHttpError || err instanceof PostHogFetchNetworkError);
 }
+function isPostHogFetchContentTooLargeError(err) {
+    return typeof err === 'object' && err instanceof PostHogFetchHttpError && err.status === 413;
+}
 var QuotaLimitedFeature;
 (function (QuotaLimitedFeature) {
     QuotaLimitedFeature["FeatureFlags"] = "feature_flags";
@@ -1268,6 +1271,7 @@ var QuotaLimitedFeature;
 class PostHogCoreStateless {
     constructor(apiKey, options) {
         this.flushPromise = null;
+        this.shutdownPromise = null;
         this.pendingPromises = {};
         // internal
         this._events = new SimpleEventEmitter();
@@ -1780,13 +1784,21 @@ class PostHogCoreStateless {
         });
     }
     async flush() {
-        if (!this.flushPromise) {
-            this.flushPromise = this._flush().finally(() => {
+        // Wait for the current flush operation to finish (regardless of success or failure), then try to flush again.
+        // Use allSettled instead of finally to be defensive around flush throwing errors immediately rather than rejecting.
+        const nextFlushPromise = Promise.allSettled([this.flushPromise]).then(() => {
+            return this._flush();
+        });
+        this.flushPromise = nextFlushPromise;
+        void this.addPendingPromise(nextFlushPromise);
+        Promise.allSettled([nextFlushPromise]).then(() => {
+            // If there are no others waiting to flush, clear the promise.
+            // We don't strictly need to do this, but it could make debugging easier
+            if (this.flushPromise === nextFlushPromise) {
                 this.flushPromise = null;
-            });
-            this.addPendingPromise(this.flushPromise);
-        }
-        return this.flushPromise;
+            }
+        });
+        return nextFlushPromise;
     }
     getCustomHeaders() {
         // Don't set the user agent if we're not on a browser. The latest spec allows
@@ -1803,56 +1815,80 @@ class PostHogCoreStateless {
     async _flush() {
         this.clearFlushTimer();
         await this._initPromise;
-        const queue = this.getPersistedProperty(PostHogPersistedProperty.Queue) || [];
+        let 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(),
-        };
-        if (this.historicalMigration) {
-            data.historical_migration = true;
-        }
-        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 sentMessages = [];
+        const originalQueueLength = queue.length;
+        while (queue.length > 0 && sentMessages.length < originalQueueLength) {
+            const batchItems = queue.slice(0, this.maxBatchSize);
+            const batchMessages = batchItems.map((item) => item.message);
+            const persistQueueChange = () => {
+                const refreshedQueue = this.getPersistedProperty(PostHogPersistedProperty.Queue) || [];
+                const newQueue = refreshedQueue.slice(batchItems.length);
+                this.setPersistedProperty(PostHogPersistedProperty.Queue, newQueue);
+                queue = newQueue;
+            };
+            const data = {
+                api_key: this.apiKey,
+                batch: batchMessages,
+                sent_at: currentISOTime(),
+            };
+            if (this.historicalMigration) {
+                data.historical_migration = true;
             }
-            : {
-                method: 'POST',
-                headers: { ...this.getCustomHeaders(), 'Content-Type': 'application/json' },
-                body: payload,
+            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`,
+                }
+                : {
+                    method: 'POST',
+                    headers: { ...this.getCustomHeaders(), 'Content-Type': 'application/json' },
+                    body: payload,
+                };
+            const retryOptions = {
+                retryCheck: (err) => {
+                    // don't automatically retry on 413 errors, we want to reduce the batch size first
+                    if (isPostHogFetchContentTooLargeError(err)) {
+                        return false;
+                    }
+                    // otherwise, retry on network errors
+                    return isPostHogFetchError(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();
+            try {
+                await this.fetchWithRetry(url, fetchOptions, retryOptions);
             }
-            this._events.emit('error', err);
-            throw err;
+            catch (err) {
+                if (isPostHogFetchContentTooLargeError(err) && batchMessages.length > 1) {
+                    // if we get a 413 error, we want to reduce the batch size and try again
+                    this.maxBatchSize = Math.max(1, Math.floor(batchMessages.length / 2));
+                    this.logMsgIfDebug(() => console.warn(`Received 413 when sending batch of size ${batchMessages.length}, reducing batch size to ${this.maxBatchSize}`));
+                    // do not persist the queue change, we want to retry the same batch
+                    continue;
+                }
+                // 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();
+            sentMessages.push(...batchMessages);
         }
-        persistQueueChange();
-        this._events.emit('flush', messages);
-        return messages;
+        this._events.emit('flush', sentMessages);
+        return sentMessages;
     }
     async fetchWithRetry(url, options, retryOptions, requestTimeout) {
         var _a;
@@ -1885,7 +1921,7 @@ class PostHogCoreStateless {
             return res;
         }, { ...this._retryOptions, ...retryOptions });
     }
-    async shutdown(shutdownTimeoutMs = 30000) {
+    async _shutdown(shutdownTimeoutMs = 30000) {
         // A little tricky - we want to have a max shutdown time and enforce it, even if that means we have some
         // dangling promises. We'll keep track of the timeout and resolve/reject based on that.
         await this._initPromise;
@@ -1926,6 +1962,22 @@ class PostHogCoreStateless {
             doShutdown(),
         ]);
     }
+    /**
+     *  Call shutdown() once before the node process exits, so ensure that all events have been sent and all promises
+     *  have resolved. Do not use this function if you intend to keep using this PostHog instance after calling it.
+     * @param shutdownTimeoutMs
+     */
+    async shutdown(shutdownTimeoutMs = 30000) {
+        if (this.shutdownPromise) {
+            this.logMsgIfDebug(() => console.warn('shutdown() called while already shutting down. shutdown() is meant to be called once before process exit - use flush() for per-request cleanup'));
+        }
+        else {
+            this.shutdownPromise = this._shutdown(shutdownTimeoutMs).finally(() => {
+                this.shutdownPromise = null;
+            });
+        }
+        return this.shutdownPromise;
+    }
 }
 
 class PostHogMemoryStorage {
@@ -4117,9 +4169,9 @@ class PostHog extends PostHogCoreStateless {
   async reloadFeatureFlags() {
     await this.featureFlagsPoller?.loadFeatureFlags(true);
   }
-  async shutdown(shutdownTimeoutMs) {
+  async _shutdown(shutdownTimeoutMs) {
     this.featureFlagsPoller?.stopPoller();
-    return super.shutdown(shutdownTimeoutMs);
+    return super._shutdown(shutdownTimeoutMs);
   }
   addLocalPersonAndGroupProperties(distinctId, groups, personProperties, groupProperties) {
     const allPersonProperties = {