📈 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: Feature flags
Blue Moused0fe2078abe1
diff --git a/src/Lib.ts b/src/Lib.tsindex 8608b6ddd..272719169 100644--- a/src/Lib.ts+++ b/src/Lib.ts@@ -95,6 +95,31 @@ interface IPerfPayload {ttfb: number}+/**+ * Options for evaluating feature flags.+ */+export interface FeatureFlagsOptions {+ /**+ * Unique visitor ID for consistent rollout percentages.+ * If not provided, rollout-based flags may return different results on each evaluation.+ */+ visitorId?: string++ /**+ * Visitor attributes for targeting rules.+ * Common attributes: cc (country), dv (device), br (browser), os (operating system), pg (page).+ */+ attributes?: Record<string, string>+}++/**+ * Cached feature flags with timestamp.+ */+interface CachedFlags {+ flags: Record<string, boolean>+ timestamp: number+}+/*** The object returned by `trackPageViews()`, used to stop tracking pages.*/@@ -174,6 +199,10 @@ export const defaultActions = {}const DEFAULT_API_HOST = 'https://api.swetrix.com/log'+const DEFAULT_API_BASE = 'https://api.swetrix.com'++// Default cache duration: 5 minutes+const DEFAULT_CACHE_DURATION = 5 * 60 * 1000export class Lib {private pageData: PageData | null = null@@ -182,6 +211,7 @@ export class Lib {private perfStatsCollected: boolean = falseprivate activePage: string | null = nullprivate errorListenerExists = false+ private cachedFlags: CachedFlags | null = nullconstructor(private projectID: string, private options?: LibOptions) {this.trackPathChange = this.trackPathChange.bind(this)@@ -368,6 +398,100 @@ export class Lib {}}+ /**+ * Fetches all feature flags 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.+ * @returns A promise that resolves to a record of flag keys to boolean values.+ */+ async getFeatureFlags(options?: FeatureFlagsOptions, forceRefresh?: boolean): Promise<Record<string, boolean>> {+ if (!isInBrowser()) {+ return {}+ }++ // Check cache first+ if (!forceRefresh && this.cachedFlags) {+ const now = Date.now()+ if (now - this.cachedFlags.timestamp < DEFAULT_CACHE_DURATION) {+ return this.cachedFlags.flags+ }+ }++ try {+ const apiBase = this.getApiBase()+ const body: { pid: string; visitorId?: string; attributes?: Record<string, string> } = {+ pid: this.projectID,+ }++ if (options?.visitorId) {+ body.visitorId = options.visitorId+ }++ if (options?.attributes) {+ body.attributes = options.attributes+ }++ const response = await fetch(`${apiBase}/feature-flag/evaluate`, {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ },+ body: JSON.stringify(body),+ })++ if (!response.ok) {+ console.warn('[Swetrix] Failed to fetch feature flags:', response.status)+ return this.cachedFlags?.flags || {}+ }++ const data = (await response.json()) as { flags: Record<string, boolean> }++ // Update cache+ this.cachedFlags = {+ flags: data.flags,+ timestamp: Date.now(),+ }++ return data.flags+ } catch (error) {+ console.warn('[Swetrix] Error fetching feature flags:', error)+ return this.cachedFlags?.flags || {}+ }+ }++ /**+ * Gets the value of a single feature flag.+ *+ * @param key - The feature flag key.+ * @param options - Options for evaluating the feature flag.+ * @param defaultValue - Default value to return if the flag is not found. Defaults to false.+ * @returns A promise that resolves to the boolean value of the flag.+ */+ async getFeatureFlag(key: string, options?: FeatureFlagsOptions, defaultValue: boolean = false): Promise<boolean> {+ const flags = await this.getFeatureFlags(options)+ return flags[key] ?? defaultValue+ }++ /**+ * Clears the cached feature flags, forcing a fresh fetch on the next call.+ */+ clearFeatureFlagsCache(): void {+ this.cachedFlags = null+ }++ /**+ * Gets the API base URL (without /log suffix).+ */+ private getApiBase(): string {+ if (this.options?.apiURL) {+ // Remove trailing /log if present+ return this.options.apiURL.replace(/\/log\/?$/, '')+ }+ return DEFAULT_API_BASE+ }+private heartbeat(): void {if (!this.pageViewsOptions?.heartbeatOnBackground && document.visibilityState === 'hidden') {returndiff --git a/src/index.ts b/src/index.tsindex 5c889eff5..e68c49990 100644--- a/src/index.ts+++ b/src/index.ts@@ -9,6 +9,7 @@ import {defaultActions,IErrorEventPayload,IPageViewPayload,+ FeatureFlagsOptions,} from './Lib.js'export let LIB_INSTANCE: Lib | null = null@@ -120,6 +121,72 @@ export function pageview(options: IPageviewOptions): void {LIB_INSTANCE.submitPageView(options.payload, Boolean(options.unique), {})}+/**+ * Fetches all feature flags for the project.+ * Results are cached for 5 minutes by default.+ *+ * @param options - Options for evaluating feature flags (visitorId, attributes).+ * @param forceRefresh - If true, bypasses the cache and fetches fresh flags.+ * @returns A promise that resolves to a record of flag keys to boolean values.+ *+ * @example+ * ```typescript+ * const flags = await getFeatureFlags({+ * visitorId: 'user-123',+ * attributes: { cc: 'US', dv: 'desktop' }+ * })+ *+ * if (flags['new-checkout']) {+ * // Show new checkout flow+ * }+ * ```+ */+export async function getFeatureFlags(+ options?: FeatureFlagsOptions,+ forceRefresh?: boolean,+): Promise<Record<string, boolean>> {+ if (!LIB_INSTANCE) return {}++ return LIB_INSTANCE.getFeatureFlags(options, forceRefresh)+}++/**+ * Gets the value of a single feature flag.+ *+ * @param key - The feature flag key.+ * @param options - Options for evaluating the feature flag (visitorId, attributes).+ * @param defaultValue - Default value to return if the flag is not found. Defaults to false.+ * @returns A promise that resolves to the boolean value of the flag.+ *+ * @example+ * ```typescript+ * const isEnabled = await getFeatureFlag('dark-mode', { visitorId: 'user-123' })+ *+ * if (isEnabled) {+ * // Enable dark mode+ * }+ * ```+ */+export async function getFeatureFlag(+ key: string,+ options?: FeatureFlagsOptions,+ defaultValue: boolean = false,+): Promise<boolean> {+ if (!LIB_INSTANCE) return defaultValue++ return LIB_INSTANCE.getFeatureFlag(key, options, defaultValue)+}++/**+ * Clears the cached feature flags, forcing a fresh fetch on the next call.+ * Useful when you know the user's context has changed significantly.+ */+export function clearFeatureFlagsCache(): void {+ if (!LIB_INSTANCE) return++ LIB_INSTANCE.clearFeatureFlagsCache()+}+export {LibOptions,TrackEventOptions,@@ -129,4 +196,5 @@ export {ErrorActions,IErrorEventPayload,IPageViewPayload,+ FeatureFlagsOptions,}