posthog-node 4.12.0 → 4.13.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 4.13.0 - 2025-04-21
+
+1. feat: Add method to wait for local evaluation feature flag definitions to be loaded
+
 # 4.12.0 – 2025-04-17
 
 1. chore: roll out new feature flag evaluation backend to majority of customers

package/lib/index.cjs.js

@@ -22,7 +22,7 @@ function _interopNamespace(e) {
   return Object.freeze(n);
 }
 
-var version = "4.12.0";
+var version = "4.13.0";
 
 var PostHogPersistedProperty;
 (function (PostHogPersistedProperty) {
@@ -1988,6 +1988,7 @@ class FeatureFlagsPoller {
     this.fetch = options.fetch || fetch$1;
     this.onError = options.onError;
     this.customHeaders = customHeaders;
+    this.onLoad = options.onLoad;
     void this.loadFeatureFlags();
   }
   debug(enabled = true) {
@@ -2204,6 +2205,13 @@ class FeatureFlagsPoller {
       await this._loadFeatureFlags();
     }
   }
+  /**
+   * Returns true if the feature flags poller has loaded successfully at least once and has more than 0 feature flags.
+   * This is useful to check if local evaluation is ready before calling getFeatureFlag.
+   */
+  isLocalEvaluationReady() {
+    return (this.loadedSuccessfullyOnce ?? false) && (this.featureFlags?.length ?? 0) > 0;
+  }
   /**
    * If a client is misconfigured with an invalid or improper API key, the polling interval is doubled each time
    * until a successful request is made, up to a maximum of 60 seconds.
@@ -2279,6 +2287,7 @@ class FeatureFlagsPoller {
             this.loadedSuccessfullyOnce = true;
             this.shouldBeginExponentialBackoff = false;
             this.backOffCount = 0;
+            this.onLoad?.(this.featureFlags.length);
             break;
           }
         default:
@@ -3069,16 +3078,28 @@ async function propertiesFromUnknownInput(stackParser, input, hint) {
     handled: true,
     type: 'generic'
   };
-  const error = getError(mechanism, input, hint);
-  const exception = await exceptionFromError(stackParser, error);
-  exception.value = exception.value || '';
-  exception.type = exception.type || 'Error';
-  exception.mechanism = mechanism;
+  const errorList = getErrorList(mechanism, input, hint);
+  const exceptionList = await Promise.all(errorList.map(async error => {
+    const exception = await exceptionFromError(stackParser, error);
+    exception.value = exception.value || '';
+    exception.type = exception.type || 'Error';
+    exception.mechanism = mechanism;
+    return exception;
+  }));
   const properties = {
-    $exception_list: [exception]
+    $exception_list: exceptionList
   };
   return properties;
 }
+// Flatten error causes into a list of errors
+// See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
+function getErrorList(mechanism, input, hint) {
+  const error = getError(mechanism, input, hint);
+  if (error.cause) {
+    return [error, ...getErrorList(mechanism, error.cause, hint)];
+  }
+  return [error];
+}
 function getError(mechanism, exception, hint) {
   if (isError(exception)) {
     return exception;
@@ -3105,7 +3126,7 @@ function getErrorPropertyFromObject(obj) {
   for (const prop in obj) {
     if (Object.prototype.hasOwnProperty.call(obj, prop)) {
       const value = obj[prop];
-      if (value instanceof Error) {
+      if (isError(value)) {
         return value;
       }
     }
@@ -3532,6 +3553,9 @@ class PostHog extends PostHogCoreStateless {
         onError: err => {
           this._events.emit('error', err);
         },
+        onLoad: count => {
+          this._events.emit('localEvaluationFlagsLoaded', count);
+        },
         customHeaders: this.getCustomHeaders()
       });
     }
@@ -3664,6 +3688,28 @@ class PostHog extends PostHogCoreStateless {
       disableGeoip: data.disableGeoip
     });
   }
+  isLocalEvaluationReady() {
+    return this.featureFlagsPoller?.isLocalEvaluationReady() ?? false;
+  }
+  async waitForLocalEvaluationReady(timeoutMs = THIRTY_SECONDS) {
+    if (this.isLocalEvaluationReady()) {
+      return true;
+    }
+    if (this.featureFlagsPoller === undefined) {
+      return false;
+    }
+    return new Promise(resolve => {
+      const timeout = setTimeout(() => {
+        cleanup();
+        resolve(false);
+      }, timeoutMs);
+      const cleanup = this._events.on('localEvaluationFlagsLoaded', count => {
+        clearTimeout(timeout);
+        cleanup();
+        resolve(count > 0);
+      });
+    });
+  }
   async getFeatureFlag(key, distinctId, options) {
     const {
       groups,
@@ -3841,6 +3887,10 @@ class PostHog extends PostHogCoreStateless {
       disableGeoip
     }, distinctId);
   }
+  /**
+   * Reloads the feature flag definitions from the server for local evaluation.
+   * This is useful to call if you want to ensure that the feature flags are up to date before calling getFeatureFlag.
+   */
   async reloadFeatureFlags() {
     await this.featureFlagsPoller?.loadFeatureFlags(true);
   }