posthog-node 5.11.2 → 5.13.0

package/dist/extensions/feature-flags/feature-flags.mjs

@@ -35,6 +35,7 @@ class FeatureFlagsPoller {
         this.debugMode = false;
         this.shouldBeginExponentialBackoff = false;
         this.backOffCount = 0;
+        this.hasAttemptedCacheLoad = false;
         this.pollingInterval = pollingInterval;
         this.personalApiKey = personalApiKey;
         this.featureFlags = [];
@@ -50,6 +51,7 @@ class FeatureFlagsPoller {
         this.onError = options.onError;
         this.customHeaders = customHeaders;
         this.onLoad = options.onLoad;
+        this.cacheProvider = options.cacheProvider;
         this.loadFeatureFlags();
     }
     debug(enabled = true) {
@@ -237,8 +239,39 @@ class FeatureFlagsPoller {
         });
         return lookupTable;
     }
+    updateFlagState(flagData) {
+        this.featureFlags = flagData.flags;
+        this.featureFlagsByKey = flagData.flags.reduce((acc, curr)=>(acc[curr.key] = curr, acc), {});
+        this.groupTypeMapping = flagData.groupTypeMapping;
+        this.cohorts = flagData.cohorts;
+        this.loadedSuccessfullyOnce = true;
+    }
+    async loadFromCache(debugMessage) {
+        if (!this.cacheProvider) return false;
+        try {
+            const cached = await this.cacheProvider.getFlagDefinitions();
+            if (cached) {
+                this.updateFlagState(cached);
+                this.logMsgIfDebug(()=>console.debug(`[FEATURE FLAGS] ${debugMessage} (${cached.flags.length} flags)`));
+                this.onLoad?.(this.featureFlags.length);
+                return true;
+            }
+            return false;
+        } catch (err) {
+            this.onError?.(new Error(`Failed to load from cache: ${err}`));
+            return false;
+        }
+    }
     async loadFeatureFlags(forceReload = false) {
-        if (!this.loadedSuccessfullyOnce || forceReload) await this._loadFeatureFlags();
+        if (this.cacheProvider && !this.hasAttemptedCacheLoad) {
+            this.hasAttemptedCacheLoad = true;
+            await this.loadFromCache('Loaded flags from cache');
+        }
+        if (this.loadingPromise) return this.loadingPromise;
+        if (!this.loadedSuccessfullyOnce || forceReload) {
+            this.loadingPromise = this._loadFeatureFlags();
+            await this.loadingPromise;
+        }
     }
     isLocalEvaluationReady() {
         return (this.loadedSuccessfullyOnce ?? false) && (this.featureFlags?.length ?? 0) > 0;
@@ -254,6 +287,17 @@ class FeatureFlagsPoller {
         }
         this.poller = setTimeout(()=>this._loadFeatureFlags(), this.getPollingInterval());
         try {
+            let shouldFetch = true;
+            if (this.cacheProvider) try {
+                shouldFetch = await this.cacheProvider.shouldFetchFlagDefinitions();
+            } catch (err) {
+                this.onError?.(new Error(`Error in shouldFetchFlagDefinitions: ${err}`));
+            }
+            if (!shouldFetch) {
+                const loaded = await this.loadFromCache('Loaded flags from cache (skipped fetch)');
+                if (loaded) return;
+                if (this.loadedSuccessfullyOnce) return;
+            }
             const res = await this._requestFeatureFlagDefinitions();
             if (!res) return;
             switch(res.status){
@@ -280,13 +324,19 @@ class FeatureFlagsPoller {
                     {
                         const responseJson = await res.json() ?? {};
                         if (!('flags' in responseJson)) return void this.onError?.(new Error(`Invalid response when getting feature flags: ${JSON.stringify(responseJson)}`));
-                        this.featureFlags = responseJson.flags ?? [];
-                        this.featureFlagsByKey = this.featureFlags.reduce((acc, curr)=>(acc[curr.key] = curr, acc), {});
-                        this.groupTypeMapping = responseJson.group_type_mapping || {};
-                        this.cohorts = responseJson.cohorts || {};
-                        this.loadedSuccessfullyOnce = true;
+                        const flagData = {
+                            flags: responseJson.flags ?? [],
+                            groupTypeMapping: responseJson.group_type_mapping || {},
+                            cohorts: responseJson.cohorts || {}
+                        };
+                        this.updateFlagState(flagData);
                         this.shouldBeginExponentialBackoff = false;
                         this.backOffCount = 0;
+                        if (this.cacheProvider && shouldFetch) try {
+                            await this.cacheProvider.onFlagDefinitionsReceived(flagData);
+                        } catch (err) {
+                            this.onError?.(new Error(`Failed to store in cache: ${err}`));
+                        }
                         this.onLoad?.(this.featureFlags.length);
                         break;
                     }
@@ -295,6 +345,8 @@ class FeatureFlagsPoller {
             }
         } catch (err) {
             if (err instanceof ClientError) this.onError?.(err);
+        } finally{
+            this.loadingPromise = void 0;
         }
     }
     getPersonalApiKeyRequestOptions(method = 'GET') {
@@ -307,7 +359,7 @@ class FeatureFlagsPoller {
             }
         };
     }
-    async _requestFeatureFlagDefinitions() {
+    _requestFeatureFlagDefinitions() {
         const url = `${this.host}/api/feature_flag/local_evaluation?token=${this.projectApiKey}&send_cohorts`;
         const options = this.getPersonalApiKeyRequestOptions();
         let abortTimeout = null;
@@ -319,13 +371,23 @@ class FeatureFlagsPoller {
             options.signal = controller.signal;
         }
         try {
-            return await this.fetch(url, options);
+            const fetch1 = this.fetch;
+            return fetch1(url, options);
         } finally{
             clearTimeout(abortTimeout);
         }
     }
-    stopPoller() {
+    async stopPoller(timeoutMs = 30000) {
         clearTimeout(this.poller);
+        if (this.cacheProvider) try {
+            const shutdownResult = this.cacheProvider.shutdown();
+            if (shutdownResult instanceof Promise) await Promise.race([
+                shutdownResult,
+                new Promise((_, reject)=>setTimeout(()=>reject(new Error(`Cache shutdown timeout after ${timeoutMs}ms`)), timeoutMs))
+            ]);
+        } catch (err) {
+            this.onError?.(new Error(`Error during cache shutdown: ${err}`));
+        }
     }
 }
 async function _hash(key, distinctId, salt = '') {

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { PostHogCoreOptions, FeatureFlagValue, JsonType, PostHogFetchOptions, PostHogFetchResponse } from '@posthog/core';
+import type { FlagDefinitionCacheProvider } from './extensions/feature-flags/cache';
 export interface IdentifyMessage {
     distinctId: string;
     properties?: Record<string | number, any>;
@@ -52,6 +53,32 @@ export type PostHogOptions = PostHogCoreOptions & {
     maxCacheSize?: number;
     fetch?: (url: string, options: PostHogFetchOptions) => Promise<PostHogFetchResponse>;
     enableLocalEvaluation?: boolean;
+    /**
+     * @experimental This API is experimental and may change in minor versions.
+     *
+     * Optional cache provider for feature flag definitions.
+     *
+     * Allows custom caching strategies (Redis, database, etc.) for flag definitions
+     * in multi-worker environments. If not provided, defaults to in-memory cache.
+     *
+     * This enables distributed coordination where only one worker fetches flags while
+     * others use cached data, reducing API calls and improving performance.
+     *
+     * @example
+     * ```typescript
+     * import { FlagDefinitionCacheProvider } from 'posthog-node/experimental'
+     *
+     * class RedisCacheProvider implements FlagDefinitionCacheProvider {
+     *   // ... implementation
+     * }
+     *
+     * const client = new PostHog('api-key', {
+     *   personalApiKey: 'personal-key',
+     *   flagDefinitionCacheProvider: new RedisCacheProvider(redis)
+     * })
+     * ```
+     */
+    flagDefinitionCacheProvider?: FlagDefinitionCacheProvider;
     /**
      * Allows modification or dropping of events before they're sent to PostHog.
      * If an array is provided, the functions are run in order.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const version = "5.11.2";
+export declare const version = "5.13.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -26,7 +26,7 @@ __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     version: ()=>version
 });
-const version = '5.11.2';
+const version = '5.13.0';
 exports.version = __webpack_exports__.version;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "version"

package/dist/version.mjs

@@ -1,2 +1,2 @@
-const version = '5.11.2';
+const version = '5.13.0';
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posthog-node",
-  "version": "5.11.2",
+  "version": "5.13.0",
   "description": "PostHog Node.js integration",
   "repository": {
     "type": "git",
@@ -25,11 +25,12 @@
   "module": "dist/entrypoints/index.node.mjs",
   "types": "dist/entrypoints/index.node.d.ts",
   "dependencies": {
-    "@posthog/core": "1.5.2"
+    "@posthog/core": "1.5.3"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "jest": "^29.7.0",
+    "@types/jest": "^29.5.0",
     "@rslib/core": "^0.10.5",
     "@posthog-tooling/tsconfig-base": "1.0.0"
   },
@@ -64,6 +65,9 @@
       },
       "import": "./dist/entrypoints/index.node.mjs",
       "require": "./dist/entrypoints/index.node.js"
+    },
+    "./experimental": {
+      "types": "./dist/experimental.d.ts"
     }
   },
   "scripts": {

package/src/client.ts

@@ -112,6 +112,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
             this._events.emit('localEvaluationFlagsLoaded', count)
           },
           customHeaders: this.getCustomHeaders(),
+          cacheProvider: options.flagDefinitionCacheProvider,
         })
       }
     }
@@ -1179,7 +1180,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    * @returns Promise that resolves when shutdown is complete
    */
   async _shutdown(shutdownTimeoutMs?: number): Promise<void> {
-    this.featureFlagsPoller?.stopPoller()
+    this.featureFlagsPoller?.stopPoller(shutdownTimeoutMs)
     this.errorTracking.shutdown()
     return super._shutdown(shutdownTimeoutMs)
   }

package/src/entrypoints/index.edge.ts

@@ -12,7 +12,7 @@ ErrorTracking.errorPropertiesBuilder = new CoreErrorTracking.ErrorPropertiesBuil
     new CoreErrorTracking.StringCoercer(),
     new CoreErrorTracking.PrimitiveCoercer(),
   ],
-  [CoreErrorTracking.nodeStackLineParser]
+  CoreErrorTracking.createStackParser('node:javascript', CoreErrorTracking.nodeStackLineParser)
 )
 
 export class PostHog extends PostHogBackendClient {

package/src/entrypoints/index.node.ts

@@ -15,7 +15,7 @@ ErrorTracking.errorPropertiesBuilder = new CoreErrorTracking.ErrorPropertiesBuil
     new CoreErrorTracking.StringCoercer(),
     new CoreErrorTracking.PrimitiveCoercer(),
   ],
-  [CoreErrorTracking.nodeStackLineParser],
+  CoreErrorTracking.createStackParser('node:javascript', CoreErrorTracking.nodeStackLineParser),
   [createModulerModifier(), addSourceContext]
 )
 

package/src/experimental.ts

@@ -0,0 +1,11 @@
+/**
+ * Experimental APIs
+ *
+ * This module exports experimental features that may change or be removed in minor versions.
+ * Use these APIs with caution and be prepared for breaking changes.
+ *
+ * @packageDocumentation
+ * @experimental
+ */
+
+export type { FlagDefinitionCacheProvider, FlagDefinitionCacheData } from './extensions/feature-flags/cache'

package/src/extensions/feature-flags/cache.ts

@@ -0,0 +1,114 @@
+import type { PostHogFeatureFlag, PropertyGroup } from '../../types'
+
+/**
+ * Represents the complete set of feature flag data needed for local evaluation.
+ *
+ * This includes flag definitions, group type mappings, and cohort property groups.
+ */
+export interface FlagDefinitionCacheData {
+  /** Array of feature flag definitions */
+  flags: PostHogFeatureFlag[]
+  /** Mapping of group type index to group name */
+  groupTypeMapping: Record<string, string>
+  /** Cohort property groups for local evaluation */
+  cohorts: Record<string, PropertyGroup>
+}
+
+/**
+ * @experimental This API is experimental and may change in minor versions.
+ *
+ * Provider interface for caching feature flag definitions.
+ *
+ * Implementations can use this to control when flag definitions are fetched
+ * and how they're cached (Redis, database, filesystem, etc.).
+ *
+ * This interface is designed for server-side environments where multiple workers
+ * need to share flag definitions and coordinate fetching to reduce API calls.
+ *
+ * All methods may throw errors - the poller will catch and log them gracefully,
+ * ensuring cache provider errors never break flag evaluation.
+ *
+ * @example
+ * ```typescript
+ * import { FlagDefinitionCacheProvider } from 'posthog-node/experimental'
+ *
+ * class RedisFlagCache implements FlagDefinitionCacheProvider {
+ *   constructor(private redis: Redis, private teamKey: string) { }
+ *
+ *   async getFlagDefinitions(): Promise<FlagDefinitionCacheData | undefined> {
+ *     const cached = await this.redis.get(`posthog:flags:${this.teamKey}`)
+ *     return cached ? JSON.parse(cached) : undefined
+ *   }
+ *
+ *   async shouldFetchFlagDefinitions(): Promise<boolean> {
+ *     // Acquire distributed lock - only one worker fetches
+ *     const acquired = await this.redis.set(`posthog:flags:${this.teamKey}:lock`, '1', 'EX', 60, 'NX')
+ *     return acquired === 'OK'
+ *   }
+ *
+ *   async onFlagDefinitionsReceived(data: FlagDefinitionCacheData): Promise<void> {
+ *     await this.redis.set(`posthog:flags:${this.teamKey}`, JSON.stringify(data), 'EX', 300)
+ *     await this.redis.del(`posthog:flags:${this.teamKey}:lock`)
+ *   }
+ *
+ *   async shutdown(): Promise<void> {
+ *     await this.redis.del(`posthog:flags:${this.teamKey}:lock`)
+ *   }
+ * }
+ * ```
+ */
+export interface FlagDefinitionCacheProvider {
+  /**
+   * Retrieve cached flag definitions.
+   *
+   * Called when the poller is refreshing in-memory flag definitions. If this returns undefined
+   * (or throws an error), the poller will fetch fresh data from the PostHog API if no flag
+   * definitions are in memory. Otherwise, stale cache data is used until the next poll cycle.
+   *
+   * @returns cached definitions if available, undefined if cache is empty
+   * @throws if an error occurs while accessing the cache (error will be logged)
+   */
+  getFlagDefinitions(): Promise<FlagDefinitionCacheData | undefined> | FlagDefinitionCacheData | undefined
+
+  /**
+   * Determines whether this instance should fetch new flag definitions.
+   *
+   * Use this to implement distributed coordination (e.g., via distributed locks)
+   * to ensure only one instance fetches at a time in a multi-worker setup.
+   *
+   * When multiple workers share a cache, typically only one should fetch while
+   * others use cached data. Implementations can use Redis locks, database locks,
+   * or other coordination mechanisms.
+   *
+   * @returns true if this instance should fetch, false to skip and read cache
+   * @throws if coordination backend is unavailable (error will be logged, fetch continues)
+   */
+  shouldFetchFlagDefinitions(): Promise<boolean> | boolean
+
+  /**
+   * Called after successfully receiving new flag definitions from PostHog.
+   *
+   * Store the definitions in your cache backend here. This is called only
+   * after a successful API response with valid flag data.
+   *
+   * If this method throws, the error is logged but flag definitions are still
+   * stored in memory, ensuring local evaluation can still be performed.
+   *
+   * @param data - The complete flag definition data from PostHog
+   * @throws if storage backend is unavailable (error will be logged)
+   */
+  onFlagDefinitionsReceived(data: FlagDefinitionCacheData): Promise<void> | void
+
+  /**
+   * Called when the PostHog client shuts down.
+   *
+   * Release any held locks, close connections, or clean up resources here.
+   *
+   * Both sync and async cleanup are supported. Async cleanup has a timeout
+   * (default 30s, configurable via client shutdown options) to prevent the
+   * process shutdown from hanging indefinitely.
+   *
+   * @returns Promise that resolves when cleanup is complete, or void for sync cleanup
+   */
+  shutdown(): Promise<void> | void
+}

package/src/extensions/feature-flags/feature-flags.ts

@@ -2,6 +2,7 @@ import { FeatureFlagCondition, FlagProperty, FlagPropertyValue, PostHogFeatureFl
 import type { FeatureFlagValue, JsonType, PostHogFetchOptions, PostHogFetchResponse } from '@posthog/core'
 import { safeSetTimeout } from '@posthog/core'
 import { hashSHA1 } from './crypto'
+import { FlagDefinitionCacheProvider, FlagDefinitionCacheData } from './cache'
 
 const SIXTY_SECONDS = 60 * 1000
 
@@ -53,6 +54,7 @@ type FeatureFlagsPollerOptions = {
   onError?: (error: Error) => void
   onLoad?: (count: number) => void
   customHeaders?: { [key: string]: string }
+  cacheProvider?: FlagDefinitionCacheProvider
 }
 
 class FeatureFlagsPoller {
@@ -74,6 +76,9 @@ class FeatureFlagsPoller {
   shouldBeginExponentialBackoff: boolean = false
   backOffCount: number = 0
   onLoad?: (count: number) => void
+  private cacheProvider?: FlagDefinitionCacheProvider
+  private hasAttemptedCacheLoad: boolean = false
+  private loadingPromise?: Promise<void>
 
   constructor({
     pollingInterval,
@@ -99,6 +104,7 @@ class FeatureFlagsPoller {
     this.onError = options.onError
     this.customHeaders = customHeaders
     this.onLoad = options.onLoad
+    this.cacheProvider = options.cacheProvider
     void this.loadFeatureFlags()
   }
 
@@ -537,9 +543,59 @@ class FeatureFlagsPoller {
     return lookupTable
   }
 
+  /**
+   * Updates the internal flag state with the provided flag data.
+   */
+  private updateFlagState(flagData: FlagDefinitionCacheData): void {
+    this.featureFlags = flagData.flags
+    this.featureFlagsByKey = flagData.flags.reduce(
+      (acc, curr) => ((acc[curr.key] = curr), acc),
+      <Record<string, PostHogFeatureFlag>>{}
+    )
+    this.groupTypeMapping = flagData.groupTypeMapping
+    this.cohorts = flagData.cohorts
+    this.loadedSuccessfullyOnce = true
+  }
+
+  /**
+   * Attempts to load flags from cache and update internal state.
+   * Returns true if flags were successfully loaded from cache, false otherwise.
+   */
+  private async loadFromCache(debugMessage: string): Promise<boolean> {
+    if (!this.cacheProvider) {
+      return false
+    }
+
+    try {
+      const cached = await this.cacheProvider.getFlagDefinitions()
+      if (cached) {
+        this.updateFlagState(cached)
+        this.logMsgIfDebug(() => console.debug(`[FEATURE FLAGS] ${debugMessage} (${cached.flags.length} flags)`))
+        this.onLoad?.(this.featureFlags.length)
+        return true
+      }
+      return false
+    } catch (err) {
+      this.onError?.(new Error(`Failed to load from cache: ${err}`))
+      return false
+    }
+  }
+
   async loadFeatureFlags(forceReload = false): Promise<void> {
+    // On first load, try to initialize from cache (if a cache provider is configured)
+    if (this.cacheProvider && !this.hasAttemptedCacheLoad) {
+      this.hasAttemptedCacheLoad = true
+      await this.loadFromCache('Loaded flags from cache')
+    }
+
+    // If a fetch is already in progress, wait for it
+    if (this.loadingPromise) {
+      return this.loadingPromise
+    }
+
     if (!this.loadedSuccessfullyOnce || forceReload) {
-      await this._loadFeatureFlags()
+      this.loadingPromise = this._loadFeatureFlags()
+      await this.loadingPromise
     }
   }
 
@@ -574,6 +630,42 @@ class FeatureFlagsPoller {
     this.poller = setTimeout(() => this._loadFeatureFlags(), this.getPollingInterval())
 
     try {
+      let shouldFetch = true
+      if (this.cacheProvider) {
+        try {
+          shouldFetch = await this.cacheProvider.shouldFetchFlagDefinitions()
+        } catch (err) {
+          this.onError?.(new Error(`Error in shouldFetchFlagDefinitions: ${err}`))
+          // Important: if `shouldFetchFlagDefinitions` throws, we
+          // default to fetching.
+        }
+      }
+
+      if (!shouldFetch) {
+        // If we're not supposed to fetch, we assume another instance
+        // is handling it. In this case, we'll just reload from cache.
+        const loaded = await this.loadFromCache('Loaded flags from cache (skipped fetch)')
+        if (loaded) {
+          return
+        }
+
+        if (this.loadedSuccessfullyOnce) {
+          // Respect the decision to not fetch, even if it means
+          // keeping stale feature flags.
+          return
+        }
+
+        // If we've gotten here:
+        // - A cache provider is configured
+        // - We've been asked not to fetch
+        // - We failed to load from cache
+        // - We have no feature flag definitions to work with.
+        //
+        // This is the only case where we'll ignore the shouldFetch
+        // decision and proceed to fetch, because the alternative is
+        // worse: local evaluation is impossible.
+      }
+
       const res = await this._requestFeatureFlagDefinitions()
 
       // Handle undefined res case, this shouldn't happen, but it doesn't hurt to handle it anyway
@@ -637,16 +729,28 @@ class FeatureFlagsPoller {
             return
           }
 
-          this.featureFlags = (responseJson.flags as PostHogFeatureFlag[]) ?? []
-          this.featureFlagsByKey = this.featureFlags.reduce(
-            (acc, curr) => ((acc[curr.key] = curr), acc),
-            <Record<string, PostHogFeatureFlag>>{}
-          )
-          this.groupTypeMapping = (responseJson.group_type_mapping as Record<string, string>) || {}
-          this.cohorts = (responseJson.cohorts as Record<string, PropertyGroup>) || {}
-          this.loadedSuccessfullyOnce = true
+          const flagData: FlagDefinitionCacheData = {
+            flags: (responseJson.flags as PostHogFeatureFlag[]) ?? [],
+            groupTypeMapping: (responseJson.group_type_mapping as Record<string, string>) || {},
+            cohorts: (responseJson.cohorts as Record<string, PropertyGroup>) || {},
+          }
+
+          this.updateFlagState(flagData)
           this.shouldBeginExponentialBackoff = false
           this.backOffCount = 0
+
+          if (this.cacheProvider && shouldFetch) {
+            // Only notify the cache if it's actually expecting new data
+            // E.g., if we weren't supposed to fetch but we missed the
+            // cache, we may not have a lock, so we skip this step
+            try {
+              await this.cacheProvider.onFlagDefinitionsReceived(flagData)
+            } catch (err) {
+              this.onError?.(new Error(`Failed to store in cache: ${err}`))
+              // Continue anyway, the data at least made it to memory
+            }
+          }
+
           this.onLoad?.(this.featureFlags.length)
           break
         }
@@ -660,6 +764,8 @@ class FeatureFlagsPoller {
       if (err instanceof ClientError) {
         this.onError?.(err)
       }
+    } finally {
+      this.loadingPromise = undefined
     }
   }
 
@@ -674,7 +780,7 @@ class FeatureFlagsPoller {
     }
   }
 
-  async _requestFeatureFlagDefinitions(): Promise<PostHogFetchResponse> {
+  _requestFeatureFlagDefinitions(): Promise<PostHogFetchResponse> {
     const url = `${this.host}/api/feature_flag/local_evaluation?token=${this.projectApiKey}&send_cohorts`
 
     const options = this.getPersonalApiKeyRequestOptions()
@@ -690,14 +796,37 @@ class FeatureFlagsPoller {
     }
 
     try {
-      return await this.fetch(url, options)
+      // Unbind fetch from `this` to avoid potential issues in edge environments, e.g., Cloudflare Workers:
+      // https://developers.cloudflare.com/workers/observability/errors/#illegal-invocation-errors
+      const fetch = this.fetch
+      return fetch(url, options)
     } finally {
       clearTimeout(abortTimeout)
     }
   }
 
-  stopPoller(): void {
+  async stopPoller(timeoutMs: number = 30000): Promise<void> {
     clearTimeout(this.poller)
+
+    if (this.cacheProvider) {
+      try {
+        const shutdownResult = this.cacheProvider.shutdown()
+
+        if (shutdownResult instanceof Promise) {
+          // This follows the same timeout logic defined in _shutdown.
+          // We time out after some period of time to avoid hanging the entire
+          // shutdown process if the cache provider misbehaves.
+          await Promise.race([
+            shutdownResult,
+            new Promise((_, reject) =>
+              setTimeout(() => reject(new Error(`Cache shutdown timeout after ${timeoutMs}ms`)), timeoutMs)
+            ),
+          ])
+        }
+      } catch (err) {
+        this.onError?.(new Error(`Error during cache shutdown: ${err}`))
+      }
+    }
   }
 }