@terreno/feature-flags 0.7.1

package/dist/tests/featureFlagsApp.test.js

@@ -0,0 +1,391 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var bun_test_1 = require("bun:test");
+var api_1 = require("@terreno/api");
+var tests_1 = require("@terreno/api/src/tests");
+var supertest_1 = __importDefault(require("supertest"));
+var featureFlagModel_1 = require("../featureFlagModel");
+var featureFlagsApp_1 = require("../featureFlagsApp");
+var buildApp = function (options) {
+    var app = (0, tests_1.getBaseServer)();
+    (0, api_1.setupAuth)(app, tests_1.UserModel);
+    (0, api_1.addAuthRoutes)(app, tests_1.UserModel);
+    var plugin = new featureFlagsApp_1.FeatureFlagsApp(options);
+    plugin.register(app);
+    app.use(api_1.apiUnauthorizedMiddleware);
+    app.use(api_1.apiErrorMiddleware);
+    return app;
+};
+(0, bun_test_1.describe)("FeatureFlagsApp", function () {
+    var app;
+    var adminAgent;
+    var notAdminAgent;
+    (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, (0, tests_1.setupDb)()];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, featureFlagModel_1.FeatureFlag.deleteMany({})];
+                case 2:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.afterEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, featureFlagModel_1.FeatureFlag.deleteMany({})];
+                case 1:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.describe)("construction", function () {
+        (0, bun_test_1.it)("defaults basePath to /feature-flags and segments to an empty object", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var res;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        app = buildApp();
+                        return [4 /*yield*/, (0, tests_1.authAsUser)(app, "admin")];
+                    case 1:
+                        adminAgent = _a.sent();
+                        return [4 /*yield*/, adminAgent.get("/feature-flags/segments").expect(200)];
+                    case 2:
+                        res = _a.sent();
+                        (0, bun_test_1.expect)(res.body.data).toEqual([]);
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("respects a custom basePath", function () { return __awaiter(void 0, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        app = buildApp({ basePath: "/flags" });
+                        return [4 /*yield*/, (0, tests_1.authAsUser)(app, "admin")];
+                    case 1:
+                        adminAgent = _a.sent();
+                        return [4 /*yield*/, adminAgent.get("/flags/segments").expect(200)];
+                    case 2:
+                        _a.sent();
+                        return [4 /*yield*/, adminAgent.get("/feature-flags/segments").expect(404)];
+                    case 3:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("accepts an empty options object", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var res;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        app = buildApp({});
+                        return [4 /*yield*/, (0, tests_1.authAsUser)(app, "admin")];
+                    case 1:
+                        adminAgent = _a.sent();
+                        return [4 /*yield*/, adminAgent.get("/feature-flags/segments").expect(200)];
+                    case 2:
+                        res = _a.sent();
+                        (0, bun_test_1.expect)(res.body.data).toEqual([]);
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+    });
+    (0, bun_test_1.describe)("admin CRUD routes", function () {
+        (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        app = buildApp();
+                        return [4 /*yield*/, (0, tests_1.authAsUser)(app, "admin")];
+                    case 1:
+                        adminAgent = _a.sent();
+                        return [4 /*yield*/, (0, tests_1.authAsUser)(app, "notAdmin")];
+                    case 2:
+                        notAdminAgent = _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("lets admins create, list, read, update, and delete flags", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var createRes, flagId, listRes, readRes, updateRes, finalList;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, adminAgent
+                            .post("/feature-flags/flags")
+                            .send({ enabled: true, key: "new-flag", name: "New Flag" })
+                            .expect(201)];
+                    case 1:
+                        createRes = _a.sent();
+                        flagId = createRes.body.data._id;
+                        (0, bun_test_1.expect)(createRes.body.data.key).toBe("new-flag");
+                        return [4 /*yield*/, adminAgent.get("/feature-flags/flags").expect(200)];
+                    case 2:
+                        listRes = _a.sent();
+                        (0, bun_test_1.expect)(listRes.body.data.length).toBe(1);
+                        return [4 /*yield*/, adminAgent.get("/feature-flags/flags/".concat(flagId)).expect(200)];
+                    case 3:
+                        readRes = _a.sent();
+                        (0, bun_test_1.expect)(readRes.body.data.key).toBe("new-flag");
+                        return [4 /*yield*/, adminAgent
+                                .patch("/feature-flags/flags/".concat(flagId))
+                                .send({ rolloutPercentage: 50 })
+                                .expect(200)];
+                    case 4:
+                        updateRes = _a.sent();
+                        (0, bun_test_1.expect)(updateRes.body.data.rolloutPercentage).toBe(50);
+                        return [4 /*yield*/, adminAgent.delete("/feature-flags/flags/".concat(flagId)).expect(204)];
+                    case 5:
+                        _a.sent();
+                        return [4 /*yield*/, adminAgent.get("/feature-flags/flags").expect(200)];
+                    case 6:
+                        finalList = _a.sent();
+                        (0, bun_test_1.expect)(finalList.body.data.length).toBe(0);
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("rejects non-admins from the CRUD routes", function () { return __awaiter(void 0, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: 
+                    // modelRouter responds with 405 Method Not Allowed when permissions fail
+                    return [4 /*yield*/, notAdminAgent.get("/feature-flags/flags").expect(405)];
+                    case 1:
+                        // modelRouter responds with 405 Method Not Allowed when permissions fail
+                        _a.sent();
+                        return [4 /*yield*/, notAdminAgent
+                                .post("/feature-flags/flags")
+                                .send({ key: "nope", name: "Nope" })
+                                .expect(405)];
+                    case 2:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("rejects unauthenticated requests to CRUD routes", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var unauth;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        unauth = (0, supertest_1.default)(app);
+                        return [4 /*yield*/, unauth.get("/feature-flags/flags").expect(401)];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+    });
+    (0, bun_test_1.describe)("GET /feature-flags/evaluate", function () {
+        (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+            var segments;
+            return __generator(this, function (_a) {
+                segments = {
+                    admins: function (user) { return user.admin === true; },
+                };
+                app = buildApp({ segments: segments });
+                return [2 /*return*/];
+            });
+        }); });
+        (0, bun_test_1.it)("returns 401 for unauthenticated callers", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var unauth;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        unauth = (0, supertest_1.default)(app);
+                        return [4 /*yield*/, unauth.get("/feature-flags/evaluate").expect(401)];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("returns all enabled, non-archived flag values for the current user", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var res;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, featureFlagModel_1.FeatureFlag.create({
+                            enabled: true,
+                            key: "rolled-out",
+                            name: "Rolled out",
+                            rolloutPercentage: 100,
+                        })];
+                    case 1:
+                        _a.sent();
+                        return [4 /*yield*/, featureFlagModel_1.FeatureFlag.create({
+                                enabled: false,
+                                key: "disabled-flag",
+                                name: "Disabled",
+                                rolloutPercentage: 100,
+                            })];
+                    case 2:
+                        _a.sent();
+                        return [4 /*yield*/, featureFlagModel_1.FeatureFlag.create({
+                                archived: true,
+                                enabled: true,
+                                key: "archived-flag",
+                                name: "Archived",
+                                rolloutPercentage: 100,
+                            })];
+                    case 3:
+                        _a.sent();
+                        return [4 /*yield*/, featureFlagModel_1.FeatureFlag.create({
+                                enabled: true,
+                                key: "admins-only",
+                                name: "Admins",
+                                rolloutPercentage: 0,
+                                rules: [{ enabled: true, segment: "admins" }],
+                            })];
+                    case 4:
+                        _a.sent();
+                        return [4 /*yield*/, (0, tests_1.authAsUser)(app, "admin")];
+                    case 5:
+                        adminAgent = _a.sent();
+                        return [4 /*yield*/, adminAgent.get("/feature-flags/evaluate").expect(200)];
+                    case 6:
+                        res = _a.sent();
+                        (0, bun_test_1.expect)(res.body.data["rolled-out"]).toBe(true);
+                        (0, bun_test_1.expect)(res.body.data["admins-only"]).toBe(true);
+                        (0, bun_test_1.expect)(res.body.data["disabled-flag"]).toBeUndefined();
+                        (0, bun_test_1.expect)(res.body.data["archived-flag"]).toBeUndefined();
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("includes an admin's own evaluated flags", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var res, notAdminRes;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, featureFlagModel_1.FeatureFlag.create({
+                            enabled: true,
+                            key: "user-only",
+                            name: "User only",
+                            rolloutPercentage: 0,
+                            rules: [{ enabled: true, field: "admin", operator: "eq", value: true }],
+                        })];
+                    case 1:
+                        _a.sent();
+                        return [4 /*yield*/, (0, tests_1.authAsUser)(app, "admin")];
+                    case 2:
+                        adminAgent = _a.sent();
+                        return [4 /*yield*/, adminAgent.get("/feature-flags/evaluate").expect(200)];
+                    case 3:
+                        res = _a.sent();
+                        (0, bun_test_1.expect)(res.body.data["user-only"]).toBe(true);
+                        return [4 /*yield*/, (0, tests_1.authAsUser)(app, "notAdmin")];
+                    case 4:
+                        notAdminAgent = _a.sent();
+                        return [4 /*yield*/, notAdminAgent.get("/feature-flags/evaluate").expect(200)];
+                    case 5:
+                        notAdminRes = _a.sent();
+                        // notAdmin isn't admin, rolloutPercentage is 0 → should evaluate false
+                        (0, bun_test_1.expect)(notAdminRes.body.data["user-only"]).toBe(false);
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+    });
+    (0, bun_test_1.describe)("GET /feature-flags/segments", function () {
+        (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                app = buildApp({
+                    segments: {
+                        admins: function () { return true; },
+                        "beta-testers": function () { return false; },
+                    },
+                });
+                return [2 /*return*/];
+            });
+        }); });
+        (0, bun_test_1.it)("returns the registered segment keys for admins", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var res;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, (0, tests_1.authAsUser)(app, "admin")];
+                    case 1:
+                        adminAgent = _a.sent();
+                        return [4 /*yield*/, adminAgent.get("/feature-flags/segments").expect(200)];
+                    case 2:
+                        res = _a.sent();
+                        (0, bun_test_1.expect)(res.body.data.sort()).toEqual(["admins", "beta-testers"]);
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("rejects non-admin users", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var res;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, (0, tests_1.authAsUser)(app, "notAdmin")];
+                    case 1:
+                        notAdminAgent = _a.sent();
+                        return [4 /*yield*/, notAdminAgent.get("/feature-flags/segments").expect(403)];
+                    case 2:
+                        res = _a.sent();
+                        (0, bun_test_1.expect)(res.body.title).toInclude("Only admins can view segments");
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("requires authentication", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var unauth;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        unauth = (0, supertest_1.default)(app);
+                        return [4 /*yield*/, unauth.get("/feature-flags/segments").expect(401)];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+    });
+});

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+import type { FindExactlyOnePlugin, FindOneOrNonePlugin } from "@terreno/api";
+import type mongoose from "mongoose";
+export interface FeatureFlagVariant {
+    key: string;
+    weight: number;
+}
+export interface FeatureFlagRule {
+    field?: string;
+    operator?: "eq" | "neq" | "in" | "nin" | "gt" | "lt" | "contains";
+    value?: unknown;
+    segment?: string;
+    enabled?: boolean;
+    variant?: string;
+}
+export type FeatureFlagType = "boolean" | "variant";
+export type FeatureFlagDocument = mongoose.Document<mongoose.Types.ObjectId> & {
+    key: string;
+    name: string;
+    description: string;
+    enabled: boolean;
+    type: FeatureFlagType;
+    variants: FeatureFlagVariant[];
+    rules: FeatureFlagRule[];
+    rolloutPercentage: number;
+    archived: boolean;
+    created: Date;
+    updated: Date;
+    deleted: boolean;
+};
+export type FeatureFlagModel = mongoose.Model<FeatureFlagDocument> & FindExactlyOnePlugin<FeatureFlagDocument> & FindOneOrNonePlugin<FeatureFlagDocument>;
+export type SegmentFunction = (user: unknown) => boolean;
+export interface FeatureFlagsOptions {
+    basePath?: string;
+    segments?: Record<string, SegmentFunction>;
+}
+export type EvaluationResult = Record<string, boolean | string | null>;

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,55 @@
+{
+  "author": "Josh Gachnang",
+  "bugs": {
+    "url": "https://github.com/FlourishHealth/terreno/issues"
+  },
+  "dependencies": {
+    "@terreno/api": "^0.12.0",
+    "express": "^5.2.1",
+    "lodash": "^4.17.23"
+  },
+  "description": "Feature flags and A/B testing plugin for @terreno/api",
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.6",
+    "@types/bun": "^1.2.4",
+    "@types/express": "^5.0.6",
+    "@types/lodash": "^4.17.17",
+    "@types/supertest": "^6.0.2",
+    "passport-local-mongoose": "^9.0.1",
+    "supertest": "^7.0.0",
+    "typescript": "~5.9.2"
+  },
+  "homepage": "https://github.com/FlourishHealth/terreno#readme",
+  "keywords": [
+    "feature-flags",
+    "ab-testing",
+    "api",
+    "express",
+    "terreno"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "mongoose": ">=8.0.0"
+  },
+  "main": "dist/index.js",
+  "name": "@terreno/feature-flags",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/FlourishHealth/terreno.git"
+  },
+  "scripts": {
+    "compile": "bun tsc",
+    "compile:watch": "bun tsc -w",
+    "dev": "bun tsc -w",
+    "lint": "biome check ./src",
+    "lint:fix": "biome check --write ./src",
+    "test": "bun test",
+    "test:ci": "bun test",
+    "test:coverage": "bun run ../scripts/check-coverage.ts"
+  },
+  "types": "dist/index.d.ts",
+  "version": "0.7.1"
+}

package/src/evaluate.ts

@@ -0,0 +1,195 @@
+import {logger} from "@terreno/api";
+import get from "lodash/get";
+import type {
+  EvaluationResult,
+  FeatureFlagDocument,
+  FeatureFlagRule,
+  SegmentFunction,
+} from "./types";
+
+const isDebugEnabled = (): boolean => process.env.FEATURE_FLAGS_DEBUG !== "false";
+
+/**
+ * Deterministic hash of a string to a number between 0 and 99.
+ * Uses a simple but effective hash (djb2) to ensure the same user+flag
+ * combination always produces the same result.
+ */
+export const deterministicHash = (input: string): number => {
+  let hash = 5381;
+  for (let i = 0; i < input.length; i++) {
+    hash = (hash * 33) ^ input.charCodeAt(i);
+  }
+  return Math.abs(hash) % 100;
+};
+
+const matchesFieldRule = (user: unknown, rule: FeatureFlagRule): boolean => {
+  if (!rule.field || !rule.operator) {
+    return false;
+  }
+
+  const fieldValue = get(user, rule.field);
+  const ruleValue = rule.value;
+  let result = false;
+
+  switch (rule.operator) {
+    case "eq":
+      result = ruleValue !== undefined && fieldValue === ruleValue;
+      break;
+    case "neq":
+      result = ruleValue !== undefined && fieldValue !== ruleValue;
+      break;
+    case "in":
+      result = Array.isArray(ruleValue) && ruleValue.includes(fieldValue);
+      break;
+    case "nin":
+      result = Array.isArray(ruleValue) && !ruleValue.includes(fieldValue);
+      break;
+    case "gt":
+      result =
+        typeof fieldValue === "number" && typeof ruleValue === "number" && fieldValue > ruleValue;
+      break;
+    case "lt":
+      result =
+        typeof fieldValue === "number" && typeof ruleValue === "number" && fieldValue < ruleValue;
+      break;
+    case "contains":
+      result =
+        typeof fieldValue === "string" &&
+        typeof ruleValue === "string" &&
+        fieldValue.includes(ruleValue);
+      break;
+    default:
+      break;
+  }
+
+  if (isDebugEnabled()) {
+    logger.info(
+      `[feature-flags] field rule: user.${rule.field}=${JSON.stringify(fieldValue)} ${rule.operator} ${JSON.stringify(ruleValue)} → ${result}`
+    );
+  }
+
+  return result;
+};
+
+const matchesRule = (
+  user: unknown,
+  rule: FeatureFlagRule,
+  segments: Record<string, SegmentFunction>
+): boolean => {
+  if (rule.segment) {
+    const segmentFn = segments[rule.segment];
+    if (!segmentFn) {
+      logger.warn(`Segment function not found: ${rule.segment}`);
+      return false;
+    }
+    try {
+      const result = segmentFn(user);
+      if (isDebugEnabled()) {
+        logger.info(`[feature-flags] segment rule: "${rule.segment}" → ${result}`);
+      }
+      return result;
+    } catch (err) {
+      logger.warn(`Segment function "${rule.segment}" threw: ${err}`);
+      return false;
+    }
+  }
+
+  return matchesFieldRule(user, rule);
+};
+
+/**
+ * Evaluate a single feature flag for a user.
+ * Returns boolean for boolean flags, string key for variant flags, or null for disabled variant flags.
+ */
+export const evaluateFlag = (
+  flag: FeatureFlagDocument,
+  userId: string,
+  user: unknown,
+  segments: Record<string, SegmentFunction>
+): boolean | string | null => {
+  const debug = isDebugEnabled();
+
+  if (!flag.enabled) {
+    if (debug) {
+      logger.info(
+        `[feature-flags] "${flag.key}" is disabled → ${flag.type === "variant" ? "null" : "false"}`
+      );
+    }
+    return flag.type === "variant" ? null : false;
+  }
+
+  // Check rules in order — first match wins
+  for (let i = 0; i < flag.rules.length; i++) {
+    const rule = flag.rules[i];
+    const matched = matchesRule(user, rule, segments);
+    if (matched) {
+      const result = flag.type === "variant" ? (rule.variant ?? null) : (rule.enabled ?? false);
+      if (debug) {
+        logger.info(`[feature-flags] "${flag.key}" matched rule ${i} → ${JSON.stringify(result)}`);
+      }
+      return result;
+    }
+  }
+
+  // No rules matched — use deterministic hashing
+  const hash = deterministicHash(`${userId}:${flag.key}`);
+
+  if (flag.type === "boolean") {
+    const result = hash < flag.rolloutPercentage;
+    if (debug) {
+      logger.info(
+        `[feature-flags] "${flag.key}" no rules matched, hash=${hash} rollout=${flag.rolloutPercentage}% → ${result}`
+      );
+    }
+    return result;
+  }
+
+  // Variant assignment based on cumulative weights
+  let cumulativeWeight = 0;
+  for (const variant of flag.variants) {
+    cumulativeWeight += variant.weight;
+    if (hash < cumulativeWeight) {
+      if (debug) {
+        logger.info(
+          `[feature-flags] "${flag.key}" no rules matched, hash=${hash} → variant "${variant.key}"`
+        );
+      }
+      return variant.key;
+    }
+  }
+
+  // Fallback (shouldn't happen if weights sum to 100)
+  const fallback = flag.variants.length > 0 ? flag.variants[flag.variants.length - 1].key : null;
+  if (debug) {
+    logger.info(`[feature-flags] "${flag.key}" variant fallback → ${JSON.stringify(fallback)}`);
+  }
+  return fallback;
+};
+
+/**
+ * Evaluate all enabled, non-archived feature flags for a user.
+ * Returns a map of flag key to evaluation result.
+ */
+export const evaluateAllFlags = async (
+  flagModel: typeof import("./featureFlagModel").FeatureFlag,
+  userId: string,
+  user: unknown,
+  segments: Record<string, SegmentFunction>
+): Promise<EvaluationResult> => {
+  const flags = await flagModel.find({archived: {$ne: true}, enabled: true});
+  const results: EvaluationResult = {};
+
+  if (isDebugEnabled()) {
+    logger.info(`[feature-flags] evaluating ${flags.length} flags for user ${userId}`);
+  }
+
+  for (const flag of flags) {
+    results[flag.key] = evaluateFlag(flag, userId, user, segments);
+  }
+
+  if (isDebugEnabled()) {
+    logger.info(`[feature-flags] results: ${JSON.stringify(results)}`);
+  }
+
+  return results;
+};