📈 Open source, privacy-first web analytics — a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!
TypeScript chartsclickhousedockergdprgoogle-analyticsmetricsmonitoringmysqlnestjsprivacyredisself-hostedselfhostedstatisticstailwindcssweb-analyticswebanalyticswebsite
feat: Experiments
Blue Mouse94309305dcdc
diff --git a/src/Lib.ts b/src/Lib.tsindex 526deaa39..d341df082 100644--- a/src/Lib.ts+++ b/src/Lib.ts@@ -120,11 +120,26 @@ export interface FeatureFlagsOptions {}/**- * Cached feature flags with timestamp.+ * Options for evaluating experiments.*/-interface CachedFlags {+export interface ExperimentOptions {+ /**+ * Optional profile ID for long-term user tracking.+ * If not provided, an anonymous profile ID will be generated server-side based on IP and user agent.+ * Overrides the global profileId if set.+ */+ profileId?: string+}++/**+ * Cached feature flags and experiments with timestamp.+ */+interface CachedData {flags: Record<string, boolean>+ experiments: Record<string, string>timestamp: number+ /** The profileId used when fetching this cached data */+ profileId?: string}/**@@ -218,7 +233,7 @@ export class Lib {private perfStatsCollected: boolean = falseprivate activePage: string | null = nullprivate errorListenerExists = false- private cachedFlags: CachedFlags | null = null+ private cachedData: CachedData | null = nullconstructor(private projectID: string, private options?: LibOptions) {this.trackPathChange = this.trackPathChange.bind(this)@@ -407,11 +422,11 @@ export class Lib {}/**- * Fetches all feature flags for the project.+ * Fetches all feature flags and experiments for the project.* Results are cached for 5 minutes by default.** @param options - Options for evaluating feature flags.- * @param forceRefresh - If true, bypasses the cache and fetches fresh flags.+ * @param forceRefresh - If true, bypasses the cache and fetches fresh data.* @returns A promise that resolves to a record of flag keys to boolean values.*/async getFeatureFlags(options?: FeatureFlagsOptions, forceRefresh?: boolean): Promise<Record<string, boolean>> {@@ -419,51 +434,68 @@ export class Lib {return {}}- // Check cache first- if (!forceRefresh && this.cachedFlags) {+ const requestedProfileId = options?.profileId ?? this.options?.profileId++ // Check cache first - must match profileId and not be expired+ if (!forceRefresh && this.cachedData) {const now = Date.now()- if (now - this.cachedFlags.timestamp < DEFAULT_CACHE_DURATION) {- return this.cachedFlags.flags+ const isSameProfile = this.cachedData.profileId === requestedProfileId+ if (isSameProfile && now - this.cachedData.timestamp < DEFAULT_CACHE_DURATION) {+ return this.cachedData.flags}}try {- const apiBase = this.getApiBase()- const body: { pid: string; profileId?: string } = {- pid: this.projectID,- }+ await this.fetchFlagsAndExperiments(options)+ return this.cachedData?.flags || {}+ } catch (error) {+ console.warn('[Swetrix] Error fetching feature flags:', error)+ return this.cachedData?.flags || {}+ }+ }- // Use profileId from options, or fall back to global profileId- const profileId = options?.profileId ?? this.options?.profileId- if (profileId) {- body.profileId = profileId- }+ /**+ * Internal method to fetch both feature flags and experiments from the API.+ */+ private async fetchFlagsAndExperiments(options?: FeatureFlagsOptions | ExperimentOptions): Promise<void> {+ const apiBase = this.getApiBase()+ const body: { pid: string; profileId?: string } = {+ pid: this.projectID,+ }- const response = await fetch(`${apiBase}/feature-flag/evaluate`, {- method: 'POST',- headers: {- 'Content-Type': 'application/json',- },- body: JSON.stringify(body),- })+ // Use profileId from options, or fall back to global profileId+ const profileId = options?.profileId ?? this.options?.profileId+ if (profileId) {+ body.profileId = profileId+ }- if (!response.ok) {- console.warn('[Swetrix] Failed to fetch feature flags:', response.status)- return this.cachedFlags?.flags || {}- }+ const response = await fetch(`${apiBase}/feature-flag/evaluate`, {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ },+ body: JSON.stringify(body),+ })- const data = (await response.json()) as { flags: Record<string, boolean> }+ if (!response.ok) {+ console.warn('[Swetrix] Failed to fetch feature flags and experiments:', response.status)+ return+ }- // Update cache- this.cachedFlags = {- flags: data.flags,- timestamp: Date.now(),- }+ const data = (await response.json()) as {+ flags: Record<string, boolean>+ experiments?: Record<string, string>+ }- return data.flags- } catch (error) {- console.warn('[Swetrix] Error fetching feature flags:', error)- return this.cachedFlags?.flags || {}+ // Use profileId from options, or fall back to global profileId+ const cachedProfileId = options?.profileId ?? this.options?.profileId++ // Update cache with both flags and experiments+ this.cachedData = {+ flags: data.flags || {},+ experiments: data.experiments || {},+ timestamp: Date.now(),+ profileId: cachedProfileId,}}@@ -481,10 +513,84 @@ export class Lib {}/**- * Clears the cached feature flags, forcing a fresh fetch on the next call.+ * Clears the cached feature flags and experiments, forcing a fresh fetch on the next call.*/clearFeatureFlagsCache(): void {- this.cachedFlags = null+ this.cachedData = null+ }++ /**+ * Fetches all A/B test experiments for the project.+ * Results are cached for 5 minutes by default (shared cache with feature flags).+ *+ * @param options - Options for evaluating experiments.+ * @param forceRefresh - If true, bypasses the cache and fetches fresh data.+ * @returns A promise that resolves to a record of experiment IDs to variant keys.+ *+ * @example+ * ```typescript+ * const experiments = await getExperiments()+ * // experiments = { 'exp-123': 'variant-a', 'exp-456': 'control' }+ * ```+ */+ async getExperiments(options?: ExperimentOptions, forceRefresh?: boolean): Promise<Record<string, string>> {+ if (!isInBrowser()) {+ return {}+ }++ const requestedProfileId = options?.profileId ?? this.options?.profileId++ // Check cache first - must match profileId and not be expired+ if (!forceRefresh && this.cachedData) {+ const now = Date.now()+ const isSameProfile = this.cachedData.profileId === requestedProfileId+ if (isSameProfile && now - this.cachedData.timestamp < DEFAULT_CACHE_DURATION) {+ return this.cachedData.experiments+ }+ }++ try {+ await this.fetchFlagsAndExperiments(options)+ return this.cachedData?.experiments || {}+ } catch (error) {+ console.warn('[Swetrix] Error fetching experiments:', error)+ return this.cachedData?.experiments || {}+ }+ }++ /**+ * Gets the variant key for a specific A/B test experiment.+ *+ * @param experimentId - The experiment ID.+ * @param options - Options for evaluating the experiment.+ * @param defaultVariant - Default variant key to return if the experiment is not found. Defaults to null.+ * @returns A promise that resolves to the variant key assigned to this user, or defaultVariant if not found.+ *+ * @example+ * ```typescript+ * const variant = await getExperiment('checkout-redesign')+ *+ * if (variant === 'new-checkout') {+ * // Show new checkout flow+ * } else {+ * // Show control (original) checkout+ * }+ * ```+ */+ async getExperiment(+ experimentId: string,+ options?: ExperimentOptions,+ defaultVariant: string | null = null,+ ): Promise<string | null> {+ const experiments = await this.getExperiments(options)+ return experiments[experimentId] ?? defaultVariant+ }++ /**+ * Clears the cached experiments (alias for clearFeatureFlagsCache since they share the same cache).+ */+ clearExperimentsCache(): void {+ this.cachedData = null}/**diff --git a/src/index.ts b/src/index.tsindex e68c49990..b45f0b93f 100644--- a/src/index.ts+++ b/src/index.ts@@ -10,6 +10,7 @@ import {IErrorEventPayload,IPageViewPayload,FeatureFlagsOptions,+ ExperimentOptions,} from './Lib.js'export let LIB_INSTANCE: Lib | null = null@@ -187,6 +188,81 @@ export function clearFeatureFlagsCache(): void {LIB_INSTANCE.clearFeatureFlagsCache()}+/**+ * Fetches all A/B test experiments for the project.+ * Results are cached for 5 minutes by default (shared cache with feature flags).+ *+ * @param options - Options for evaluating experiments.+ * @param forceRefresh - If true, bypasses the cache and fetches fresh data.+ * @returns A promise that resolves to a record of experiment IDs to variant keys.+ *+ * @example+ * ```typescript+ * const experiments = await getExperiments()+ * // experiments = { 'exp-123': 'variant-a', 'exp-456': 'control' }+ *+ * // Use the assigned variant+ * const checkoutVariant = experiments['checkout-experiment-id']+ * if (checkoutVariant === 'new-checkout') {+ * showNewCheckout()+ * } else {+ * showOriginalCheckout()+ * }+ * ```+ */+export async function getExperiments(+ options?: ExperimentOptions,+ forceRefresh?: boolean,+): Promise<Record<string, string>> {+ if (!LIB_INSTANCE) return {}++ return LIB_INSTANCE.getExperiments(options, forceRefresh)+}++/**+ * Gets the variant key for a specific A/B test experiment.+ *+ * @param experimentId - The experiment ID.+ * @param options - Options for evaluating the experiment.+ * @param defaultVariant - Default variant key to return if the experiment is not found. Defaults to null.+ * @returns A promise that resolves to the variant key assigned to this user, or defaultVariant if not found.+ *+ * @example+ * ```typescript+ * const variant = await getExperiment('checkout-redesign-experiment-id')+ *+ * if (variant === 'new-checkout') {+ * // Show new checkout flow+ * showNewCheckout()+ * } else if (variant === 'control') {+ * // Show original checkout (control group)+ * showOriginalCheckout()+ * } else {+ * // Experiment not running or user not included+ * showOriginalCheckout()+ * }+ * ```+ */+export async function getExperiment(+ experimentId: string,+ options?: ExperimentOptions,+ defaultVariant: string | null = null,+): Promise<string | null> {+ if (!LIB_INSTANCE) return defaultVariant++ return LIB_INSTANCE.getExperiment(experimentId, options, defaultVariant)+}++/**+ * Clears the cached experiments, forcing a fresh fetch on the next call.+ * This is an alias for clearFeatureFlagsCache since experiments and flags share the same cache.+ */+export function clearExperimentsCache(): void {+ if (!LIB_INSTANCE) return++ LIB_INSTANCE.clearExperimentsCache()+}+export {LibOptions,TrackEventOptions,@@ -197,4 +273,5 @@ export {IErrorEventPayload,IPageViewPayload,FeatureFlagsOptions,+ ExperimentOptions,}diff --git a/tests/experiments.test.ts b/tests/experiments.test.tsnew file mode 100644index 000000000..f2d278e99--- /dev/null+++ b/tests/experiments.test.ts@@ -0,0 +1,330 @@+import { init, getExperiment, getExperiments, clearExperimentsCache } from '../src/index'+import { Lib } from '../src/Lib'++// Mock fetch globally+const mockFetch = jest.fn()+global.fetch = mockFetch++describe('A/B Testing Experiments', () => {+ const PROJECT_ID = 'test-project-id'+ let libInstance: Lib++ beforeEach(() => {+ jest.clearAllMocks()+ jest.resetModules()++ // Reset fetch mock+ mockFetch.mockReset()++ Object.defineProperty(window, 'location', {+ value: {+ hostname: 'example.com',+ pathname: '/test-page',+ hash: '',+ search: '',+ },+ writable: true,+ })+ })++ describe('getExperiments', () => {+ beforeEach(async () => {+ jest.resetModules()+ const { init: freshInit } = await import('../src/index')+ libInstance = freshInit(PROJECT_ID, { devMode: true }) as Lib+ })++ test('should return experiments from API response', async () => {+ // Arrange+ mockFetch.mockResolvedValueOnce({+ ok: true,+ json: async () => ({+ flags: { 'feature-flag-1': true },+ experiments: {+ 'exp-checkout': 'variant-b',+ 'exp-pricing': 'control',+ },+ }),+ })++ // Act+ const { getExperiments: freshGetExperiments } = await import('../src/index')+ const experiments = await freshGetExperiments()++ // Assert+ expect(experiments).toEqual({+ 'exp-checkout': 'variant-b',+ 'exp-pricing': 'control',+ })+ })++ test('should return empty object when no experiments in response', async () => {+ // Arrange+ mockFetch.mockResolvedValueOnce({+ ok: true,+ json: async () => ({+ flags: { 'feature-flag-1': true },+ }),+ })++ // Act+ const { getExperiments: freshGetExperiments } = await import('../src/index')+ const experiments = await freshGetExperiments()++ // Assert+ expect(experiments).toEqual({})+ })++ test('should use cached experiments on subsequent calls', async () => {+ // Arrange+ mockFetch.mockResolvedValueOnce({+ ok: true,+ json: async () => ({+ flags: {},+ experiments: { 'exp-1': 'variant-a' },+ }),+ })++ // Act+ const { getExperiments: freshGetExperiments } = await import('../src/index')+ await freshGetExperiments()+ await freshGetExperiments()++ // Assert - fetch should only be called once+ expect(mockFetch).toHaveBeenCalledTimes(1)+ })++ test('should bypass cache when forceRefresh is true', async () => {+ // Arrange+ mockFetch+ .mockResolvedValueOnce({+ ok: true,+ json: async () => ({+ flags: {},+ experiments: { 'exp-1': 'variant-a' },+ }),+ })+ .mockResolvedValueOnce({+ ok: true,+ json: async () => ({+ flags: {},+ experiments: { 'exp-1': 'variant-b' },+ }),+ })++ // Act+ const { getExperiments: freshGetExperiments } = await import('../src/index')+ const first = await freshGetExperiments()+ const second = await freshGetExperiments(undefined, true)++ // Assert+ expect(mockFetch).toHaveBeenCalledTimes(2)+ expect(first).toEqual({ 'exp-1': 'variant-a' })+ expect(second).toEqual({ 'exp-1': 'variant-b' })+ })+ })++ describe('getExperiment', () => {+ beforeEach(async () => {+ jest.resetModules()+ const { init: freshInit } = await import('../src/index')+ libInstance = freshInit(PROJECT_ID, { devMode: true }) as Lib+ })++ test('should return specific experiment variant', async () => {+ // Arrange+ mockFetch.mockResolvedValueOnce({+ ok: true,+ json: async () => ({+ flags: {},+ experiments: {+ 'exp-checkout': 'new-checkout',+ 'exp-pricing': 'control',+ },+ }),+ })++ // Act+ const { getExperiment: freshGetExperiment } = await import('../src/index')+ const variant = await freshGetExperiment('exp-checkout')++ // Assert+ expect(variant).toBe('new-checkout')+ })++ test('should return defaultVariant when experiment not found', async () => {+ // Arrange+ mockFetch.mockResolvedValueOnce({+ ok: true,+ json: async () => ({+ flags: {},+ experiments: {},+ }),+ })++ // Act+ const { getExperiment: freshGetExperiment } = await import('../src/index')+ const variant = await freshGetExperiment('non-existent', undefined, 'fallback')++ // Assert+ expect(variant).toBe('fallback')+ })++ test('should return null when experiment not found and no default provided', async () => {+ // Arrange+ mockFetch.mockResolvedValueOnce({+ ok: true,+ json: async () => ({+ flags: {},+ experiments: {},+ }),+ })++ // Act+ const { getExperiment: freshGetExperiment } = await import('../src/index')+ const variant = await freshGetExperiment('non-existent')++ // Assert+ expect(variant).toBeNull()+ })+ })++ describe('clearExperimentsCache', () => {+ test('should clear cache and fetch fresh data on next call', async () => {+ jest.resetModules()+ const {+ init: freshInit,+ getExperiments: freshGetExperiments,+ clearExperimentsCache: freshClearCache,+ } = await import('../src/index')+ freshInit(PROJECT_ID, { devMode: true })++ // Arrange+ mockFetch+ .mockResolvedValueOnce({+ ok: true,+ json: async () => ({+ flags: {},+ experiments: { 'exp-1': 'variant-a' },+ }),+ })+ .mockResolvedValueOnce({+ ok: true,+ json: async () => ({+ flags: {},+ experiments: { 'exp-1': 'variant-b' },+ }),+ })++ // Act+ await freshGetExperiments()+ freshClearCache()+ const newExperiments = await freshGetExperiments()++ // Assert+ expect(mockFetch).toHaveBeenCalledTimes(2)+ expect(newExperiments).toEqual({ 'exp-1': 'variant-b' })+ })+ })++ describe('profileId handling', () => {+ test('should include profileId in request when provided in options', async () => {+ jest.resetModules()+ const { init: freshInit, getExperiments: freshGetExperiments } = await import('../src/index')+ freshInit(PROJECT_ID, { devMode: true })++ mockFetch.mockResolvedValueOnce({+ ok: true,+ json: async () => ({+ flags: {},+ experiments: {},+ }),+ })++ // Act+ await freshGetExperiments({ profileId: 'user-123' })++ // Assert+ expect(mockFetch).toHaveBeenCalledWith(+ expect.any(String),+ expect.objectContaining({+ body: JSON.stringify({+ pid: PROJECT_ID,+ profileId: 'user-123',+ }),+ }),+ )+ })++ test('should use global profileId when not provided in options', async () => {+ jest.resetModules()+ const { init: freshInit, getExperiments: freshGetExperiments } = await import('../src/index')+ freshInit(PROJECT_ID, { devMode: true, profileId: 'global-user' })++ mockFetch.mockResolvedValueOnce({+ ok: true,+ json: async () => ({+ flags: {},+ experiments: {},+ }),+ })++ // Act+ await freshGetExperiments()++ // Assert+ expect(mockFetch).toHaveBeenCalledWith(+ expect.any(String),+ expect.objectContaining({+ body: JSON.stringify({+ pid: PROJECT_ID,+ profileId: 'global-user',+ }),+ }),+ )+ })+ })++ describe('error handling', () => {+ test('should return empty object when fetch fails', async () => {+ jest.resetModules()+ const { init: freshInit, getExperiments: freshGetExperiments } = await import('../src/index')+ freshInit(PROJECT_ID, { devMode: true })++ // Arrange+ mockFetch.mockRejectedValueOnce(new Error('Network error'))++ // Suppress console.warn for this test+ const consoleSpy = jest.spyOn(console, 'warn').mockImplementation()++ // Act+ const experiments = await freshGetExperiments()++ // Assert+ expect(experiments).toEqual({})+ consoleSpy.mockRestore()+ })++ test('should return empty object when response is not ok', async () => {+ jest.resetModules()+ const { init: freshInit, getExperiments: freshGetExperiments } = await import('../src/index')+ freshInit(PROJECT_ID, { devMode: true })++ // Arrange+ mockFetch.mockResolvedValueOnce({+ ok: false,+ status: 500,+ })++ // Suppress console.warn for this test+ const consoleSpy = jest.spyOn(console, 'warn').mockImplementation()++ // Act+ const experiments = await freshGetExperiments()++ // Assert+ expect(experiments).toEqual({})+ consoleSpy.mockRestore()+ })+ })+})