Merge branch 'flag' into staging

Author: izadoesdev

.cursor/rules/01-MUST-DO.mdc

@@ -30,14 +30,8 @@ Decouple state management, data transformations, and API interactions from the R
 Simplify data flow to eliminate prop drilling and callback hell.
 Prioritize modularity and testability in all components.
 
-Never throw errors in server actions, use try catch and return the error to the client
-
-For all blogs and content pages, add TL;DRs near the title on the top for better conversion
-
 ALWAYS use error boundaries properly
 
-use console properly, like console.error, console.time, console.json, console.table, etc
-
 Use Dayjs NEVER date-fns, and Tanstack query for hooks, NEVER SWR
 
 use Icon at the end of phosphor react icons, like CaretIcon not Caret AND THATS THE DEFAULT IMPORT, NOT AS
@@ -46,4 +40,8 @@ use json.stringify() when adding debugging
 
 Almost NEVER use useEffect unless it's critical
 
-do NOT use types any, unknown or never, use proper explicit types
+do NOT use types any, unknown or never, use proper explicit types
+
+Suffix functions with Action in types, like type Test = { testAction }
+
+Never use barrel exports or create index files

.gitattributes

@@ -1,2 +0,0 @@
-apps/dashboard/public/countries.json filter=lfs diff=lfs merge=lfs -text
-apps/dashboard/public/subdivisions.json filter=lfs diff=lfs merge=lfs -text

apps/api/package.json

@@ -42,6 +42,7 @@
     "elysia": "^1.4.19",
     "jszip": "^3.10.1",
     "keypal": "^0.1.11",
+    "bullmq": "^5.34.0",
     "zod": "catalog:"
   }
 }

apps/api/src/index.ts

@@ -24,10 +24,14 @@ import { agent } from "./routes/agent";
 import { health } from "./routes/health";
 import { publicApi } from "./routes/public";
 import { query } from "./routes/query";
+import { createFlagSchedulerWorker } from "./workers/flag-scheduler-worker";
 
 initTracing();
 setupUncaughtErrorHandlers();
 
+// Start BullMQ worker for flag schedules
+const flagSchedulerWorker = createFlagSchedulerWorker();
+
 const rpcHandler = new RPCHandler(appRouter, {
 	interceptors: [
 		createAbortSignalInterceptor(),
@@ -171,6 +175,7 @@ export default {
 
 process.on("SIGINT", async () => {
 	logger.info("SIGINT received, shutting down gracefully...");
+	await flagSchedulerWorker.close();
 	await shutdownTracing().catch((error) =>
 		logger.error({ error }, "Shutdown error")
 	);
@@ -179,6 +184,7 @@ process.on("SIGINT", async () => {
 
 process.on("SIGTERM", async () => {
 	logger.info("SIGTERM received, shutting down gracefully...");
+	await flagSchedulerWorker.close();
 	await shutdownTracing().catch((error) =>
 		logger.error({ error }, "Shutdown error")
 	);

apps/api/src/routes/public/flags.test.ts

@@ -6,6 +6,7 @@ import {
 	evaluateValueRule,
 	hashString,
 	parseProperties,
+	selectVariant,
 } from "./flags";
 
 const ROLLOUT_REASON_REGEX = /ROLLOUT_(ENABLED|DISABLED)/;
@@ -453,6 +454,131 @@ describe("evaluateRule - non-batch mode", () => {
 	});
 });
 
+describe("selectVariant", () => {
+	it("selects variant based on user hash", () => {
+		const flag = {
+			key: "button-color",
+			variants: [
+				{ key: "control", value: "gray", weight: 50 },
+				{ key: "variant-a", value: "blue", weight: 25 },
+				{ key: "variant-b", value: "green", weight: 25 },
+			],
+		};
+
+		const result = selectVariant(flag, { userId: "user-123" });
+		expect(["gray", "blue", "green"]).toContain(result.value);
+		expect(["control", "variant-a", "variant-b"]).toContain(result.variant);
+	});
+
+	it("provides sticky assignment for same user", () => {
+		const flag = {
+			key: "button-color",
+			variants: [
+				{ key: "control", value: "gray", weight: 50 },
+				{ key: "variant-a", value: "blue", weight: 50 },
+			],
+		};
+
+		const result1 = selectVariant(flag, { userId: "user-123" });
+		const result2 = selectVariant(flag, { userId: "user-123" });
+
+		expect(result1.variant).toBe(result2.variant);
+		expect(result1.value).toBe(result2.value);
+	});
+
+	it("supports string variants", () => {
+		const flag = {
+			key: "theme",
+			variants: [
+				{ key: "light", value: "light-theme", weight: 50 },
+				{ key: "dark", value: "dark-theme", weight: 50 },
+			],
+		};
+
+		const result = selectVariant(flag, { userId: "user-456" });
+		expect(typeof result.value).toBe("string");
+		expect(["light-theme", "dark-theme"]).toContain(result.value);
+	});
+
+	it("supports number variants", () => {
+		const flag = {
+			key: "price-point",
+			variants: [
+				{ key: "low", value: 9.99, weight: 33 },
+				{ key: "medium", value: 14.99, weight: 33 },
+				{ key: "high", value: 19.99, weight: 34 },
+			],
+		};
+
+		const result = selectVariant(flag, { userId: "user-789" });
+		expect(typeof result.value).toBe("number");
+		expect([9.99, 14.99, 19.99]).toContain(result.value);
+	});
+
+	it("supports object variants", () => {
+		const flag = {
+			key: "feature-config",
+			variants: [
+				{ key: "basic", value: { features: ["a", "b"] }, weight: 50 },
+				{
+					key: "premium",
+					value: { features: ["a", "b", "c", "d"] },
+					weight: 50,
+				},
+			],
+		};
+
+		const result = selectVariant(flag, { userId: "user-abc" });
+		expect(typeof result.value).toBe("object");
+		expect(result.value).toHaveProperty("features");
+	});
+
+	it("returns default when no variants", () => {
+		const flag = {
+			key: "test",
+			defaultValue: true,
+			variants: [],
+		};
+
+		const result = selectVariant(flag, { userId: "user-123" });
+		expect(result.variant).toBe("default");
+		expect(result.value).toBe(true);
+	});
+});
+
+describe("evaluateFlag - multi-variant", () => {
+	it("evaluates multivariant flags correctly", () => {
+		const flag = {
+			key: "button-color",
+			type: "multivariant",
+			variants: [
+				{ key: "control", value: "gray", weight: 50 },
+				{ key: "variant-a", value: "blue", weight: 50 },
+			],
+			payload: { experiment: "button-test" },
+		};
+
+		const result = evaluateFlag(flag, { userId: "user-123" });
+		expect(result.enabled).toBe(true);
+		expect(["gray", "blue"]).toContain(result.value);
+		expect(["control", "variant-a"]).toContain(result.variant as string);
+		expect(result.reason).toBe("MULTIVARIANT_EVALUATED");
+		expect(result.payload).toEqual({ experiment: "button-test" });
+	});
+
+	it("falls back to boolean for non-multivariant flags", () => {
+		const flag = {
+			key: "simple-flag",
+			type: "boolean",
+			defaultValue: true,
+		};
+
+		const result = evaluateFlag(flag, { userId: "user-123" });
+		expect(result.value).toBe(true);
+		expect(result.variant).toBeUndefined();
+	});
+});
+
 describe("evaluateFlag - rules present", () => {
 	it("returns first matching rule", () => {
 		const flag = {