@faststats/react 0.1.9 → 0.2.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ConsentMode, WebAnalyticsOptions, reportError } from "@faststats/web";
+import { ConsentMode, FeatureFlagEvaluation, WebAnalyticsOptions, reportError } from "@faststats/web";
 
 //#region src/analytics.d.ts
 type AnalyticsProps = WebAnalyticsOptions;
@@ -18,4 +18,17 @@ declare function useConsentMode(): (mode: ConsentMode) => void;
 declare function useOptIn(): () => void;
 declare function useOptOut(): () => void;
 //#endregion
-export { Analytics, reportError, useConsentMode, useEvent, useIdentify, useLogout, useOptIn, useOptOut, useTrack };
+//#region src/use-flag.d.ts
+type UseFlagOptions = {
+  attributes?: Record<string, unknown>;
+  externalId?: string;
+  skip?: boolean;
+};
+type UseFlagResult = FeatureFlagEvaluation & {
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => void;
+};
+declare function useFlag(flagKey: string, options?: UseFlagOptions): UseFlagResult;
+//#endregion
+export { Analytics, type UseFlagOptions, type UseFlagResult, reportError, useConsentMode, useEvent, useFlag, useIdentify, useLogout, useOptIn, useOptOut, useTrack };

package/dist/index.js

@@ -1,10 +1,21 @@
 "use client";
 import { WebAnalytics, getInstance, reportError } from "@faststats/web";
-import { useEffect, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 //#region src/instance.ts
 let instance = null;
+const listeners = /* @__PURE__ */ new Set();
+function subscribeToInstance(onStoreChange) {
+	listeners.add(onStoreChange);
+	return () => {
+		listeners.delete(onStoreChange);
+	};
+}
+function getInstanceSnapshot() {
+	return instance;
+}
 function setInstance(wa) {
 	instance = wa;
+	for (const l of listeners) l();
 }
 //#endregion
 //#region src/analytics.tsx
@@ -81,4 +92,75 @@ function useOptOut() {
 	};
 }
 //#endregion
-export { Analytics, reportError, useConsentMode, useEvent, useIdentify, useLogout, useOptIn, useOptOut, useTrack };
+//#region src/use-flag.ts
+const defaultEvaluation = { enabled: false };
+function stableSerialize(attributes) {
+	if (!attributes) return "";
+	const keys = Object.keys(attributes).sort();
+	const obj = {};
+	for (const k of keys) obj[k] = attributes[k];
+	return JSON.stringify(obj);
+}
+function useFlag(flagKey, options) {
+	const wa = useSyncExternalStore(subscribeToInstance, getInstanceSnapshot, () => null);
+	const attributes = options?.attributes;
+	const externalId = options?.externalId;
+	const skip = options?.skip ?? false;
+	const attrKey = useMemo(() => stableSerialize(attributes), [attributes]);
+	const [refetchCount, setRefetchCount] = useState(0);
+	const [evaluation, setEvaluation] = useState(defaultEvaluation);
+	const [isLoading, setIsLoading] = useState(!skip);
+	const [error, setError] = useState(null);
+	const refetch = useCallback(() => setRefetchCount((n) => n + 1), []);
+	useEffect(() => {
+		if (skip || typeof window === "undefined") {
+			setIsLoading(false);
+			setEvaluation(defaultEvaluation);
+			setError(null);
+			return;
+		}
+		if (!wa) {
+			setIsLoading(false);
+			setEvaluation(defaultEvaluation);
+			setError(null);
+			return;
+		}
+		const ac = new AbortController();
+		setIsLoading(true);
+		setError(null);
+		const requestAttributes = attrKey ? JSON.parse(attrKey) : void 0;
+		wa.checkFeatureFlag(flagKey, requestAttributes, {
+			externalId,
+			signal: ac.signal
+		}).then((result) => {
+			if (ac.signal.aborted) return;
+			setEvaluation(result);
+			setIsLoading(false);
+		}).catch((e) => {
+			if (ac.signal.aborted) return;
+			const err = e instanceof Error ? e : new Error(String(e));
+			if (err.name === "AbortError") return;
+			setError(err);
+			setEvaluation(defaultEvaluation);
+			setIsLoading(false);
+		});
+		return () => {
+			ac.abort();
+		};
+	}, [
+		wa,
+		flagKey,
+		externalId,
+		skip,
+		attrKey,
+		refetchCount
+	]);
+	return {
+		...evaluation,
+		isLoading,
+		error,
+		refetch
+	};
+}
+//#endregion
+export { Analytics, reportError, useConsentMode, useEvent, useFlag, useIdentify, useLogout, useOptIn, useOptOut, useTrack };

package/package.json

@@ -4,7 +4,7 @@
 		"type": "git",
 		"url": "https://github.com/faststats-dev/web-analytics.git"
 	},
-	"version": "0.1.9",
+	"version": "0.2.1",
 	"type": "module",
 	"main": "./dist/index.js",
 	"module": "./dist/index.js",
@@ -31,7 +31,7 @@
 		"react": ">=18"
 	},
 	"dependencies": {
-		"@faststats/web": "^0.1.9"
+		"@faststats/web": "^0.2.1"
 	},
 	"devDependencies": {
 		"@types/react": "^19.0.0",