@terreno/feature-flags 0.18.0 → 0.20.0

package/dist/tests/openFeatureProvider.test.js

@@ -0,0 +1,395 @@
+"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 };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var bun_test_1 = require("bun:test");
+var server_sdk_1 = require("@openfeature/server-sdk");
+var tests_1 = require("@terreno/api/src/tests");
+var featureFlagModel_1 = require("../featureFlagModel");
+var openFeatureProvider_1 = require("../openFeatureProvider");
+var noopLogger = {
+    debug: function () { },
+    error: function () { },
+    info: function () { },
+    warn: function () { },
+};
+(0, bun_test_1.describe)("MongoFeatureFlagProvider", function () {
+    var provider;
+    (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();
+                    provider = new openFeatureProvider_1.MongoFeatureFlagProvider({ flagModel: featureFlagModel_1.FeatureFlag, segments: {} });
+                    return [4 /*yield*/, server_sdk_1.OpenFeature.clearProviders()];
+                case 3:
+                    _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 [4 /*yield*/, server_sdk_1.OpenFeature.clearProviders()];
+                case 2:
+                    _a.sent();
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("returns FLAG_NOT_FOUND for a missing flag", 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*/, provider.resolveBooleanEvaluation("nope", false, { targetingKey: "u1" }, noopLogger)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.errorCode).toBe(server_sdk_1.ErrorCode.FLAG_NOT_FOUND);
+                    (0, bun_test_1.expect)(res.reason).toBe(server_sdk_1.StandardResolutionReasons.ERROR);
+                    (0, bun_test_1.expect)(res.value).toBe(false);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("returns TYPE_MISMATCH when resolveStringEvaluation targets a boolean flag", 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: "bool-only",
+                        name: "Bool",
+                        rolloutPercentage: 100,
+                        type: "boolean",
+                    })];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, provider.resolveStringEvaluation("bool-only", "x", { targetingKey: "u1" }, noopLogger)];
+                case 2:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.errorCode).toBe(server_sdk_1.ErrorCode.TYPE_MISMATCH);
+                    (0, bun_test_1.expect)(res.value).toBe("x");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("returns TYPE_MISMATCH when resolveBooleanEvaluation targets a variant flag", 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: "var-only",
+                        name: "Var",
+                        rules: [],
+                        type: "variant",
+                        variants: [
+                            { key: "a", weight: 50 },
+                            { key: "b", weight: 50 },
+                        ],
+                    })];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, provider.resolveBooleanEvaluation("var-only", false, { targetingKey: "u1" }, noopLogger)];
+                case 2:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.errorCode).toBe(server_sdk_1.ErrorCode.TYPE_MISMATCH);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("returns DISABLED with defaultValue for a disabled boolean flag", 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({
+                        defaultVariant: "on",
+                        enabled: false,
+                        key: "disabled-bool",
+                        name: "Off",
+                        rolloutPercentage: 100,
+                        type: "boolean",
+                    })];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, provider.resolveBooleanEvaluation("disabled-bool", false, { targetingKey: "u1" }, noopLogger)];
+                case 2:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.reason).toBe(server_sdk_1.StandardResolutionReasons.DISABLED);
+                    (0, bun_test_1.expect)(res.value).toBe(false);
+                    (0, bun_test_1.expect)(res.variant).toBe("on");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("resolves boolean rollout via deterministic hash when no rules match", 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: "rollout",
+                        name: "Rollout",
+                        rolloutPercentage: 100,
+                        rules: [],
+                        type: "boolean",
+                    })];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, provider.resolveBooleanEvaluation("rollout", false, { targetingKey: "user-abc" }, noopLogger)];
+                case 2:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.reason).toBe(server_sdk_1.StandardResolutionReasons.TARGETING_MATCH);
+                    (0, bun_test_1.expect)(res.value).toBe(true);
+                    (0, bun_test_1.expect)(res.variant).toBe("on");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("matches a field rule on a boolean flag", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var adminRes, userRes;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, featureFlagModel_1.FeatureFlag.create({
+                        enabled: true,
+                        key: "rule-bool",
+                        name: "Rule",
+                        rolloutPercentage: 0,
+                        rules: [{ enabled: true, field: "admin", operator: "eq", value: true }],
+                        type: "boolean",
+                    })];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, provider.resolveBooleanEvaluation("rule-bool", false, { targetingKey: "id1", user: { admin: true } }, noopLogger)];
+                case 2:
+                    adminRes = _a.sent();
+                    (0, bun_test_1.expect)(adminRes.value).toBe(true);
+                    return [4 /*yield*/, provider.resolveBooleanEvaluation("rule-bool", false, { targetingKey: "id2", user: { admin: false } }, noopLogger)];
+                case 3:
+                    userRes = _a.sent();
+                    (0, bun_test_1.expect)(userRes.value).toBe(false);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("matches a segment rule when segments are registered", function () { return __awaiter(void 0, void 0, void 0, function () {
+        var segments, p, yes, no;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    segments = {
+                        "vip-users": function (u) { return u.vip === true; },
+                    };
+                    p = new openFeatureProvider_1.MongoFeatureFlagProvider({ flagModel: featureFlagModel_1.FeatureFlag, segments: segments });
+                    return [4 /*yield*/, featureFlagModel_1.FeatureFlag.create({
+                            enabled: true,
+                            key: "seg-flag",
+                            name: "Seg",
+                            rolloutPercentage: 0,
+                            rules: [{ enabled: true, segment: "vip-users" }],
+                            type: "boolean",
+                        })];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, p.resolveBooleanEvaluation("seg-flag", false, { targetingKey: "x", user: { vip: true } }, noopLogger)];
+                case 2:
+                    yes = _a.sent();
+                    (0, bun_test_1.expect)(yes.value).toBe(true);
+                    return [4 /*yield*/, p.resolveBooleanEvaluation("seg-flag", false, { targetingKey: "y", user: { vip: false } }, noopLogger)];
+                case 3:
+                    no = _a.sent();
+                    (0, bun_test_1.expect)(no.value).toBe(false);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("treats missing targetingKey as empty string for hashing", 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: "hash-key",
+                        name: "Hash",
+                        rolloutPercentage: 100,
+                        rules: [],
+                        type: "boolean",
+                    })];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, provider.resolveBooleanEvaluation("hash-key", false, {}, noopLogger)];
+                case 2:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.reason).toBe(server_sdk_1.StandardResolutionReasons.TARGETING_MATCH);
+                    (0, bun_test_1.expect)(typeof res.value).toBe("boolean");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("uses flat context as user when user field is absent", 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: "flat-ctx",
+                        name: "Flat",
+                        rolloutPercentage: 0,
+                        rules: [{ enabled: true, field: "admin", operator: "eq", value: true }],
+                        type: "boolean",
+                    })];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, provider.resolveBooleanEvaluation("flat-ctx", false, { admin: true, targetingKey: "t1" }, noopLogger)];
+                case 2:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.value).toBe(true);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("resolves variant assignment and returns TARGETING_MATCH", 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: "layout",
+                        name: "Layout",
+                        rules: [],
+                        type: "variant",
+                        variants: [
+                            { key: "compact", weight: 50 },
+                            { key: "detailed", weight: 50 },
+                        ],
+                    })];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, provider.resolveStringEvaluation("layout", "fallback", { targetingKey: "user-z" }, noopLogger)];
+                case 2:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.reason).toBe(server_sdk_1.StandardResolutionReasons.TARGETING_MATCH);
+                    (0, bun_test_1.expect)(["compact", "detailed"].includes(res.value)).toBe(true);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("returns DISABLED for variant flag when evaluateFlag yields null", 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({
+                        defaultVariant: "compact",
+                        enabled: false,
+                        key: "var-off",
+                        name: "Var off",
+                        rules: [],
+                        type: "variant",
+                        variants: [
+                            { key: "compact", weight: 50 },
+                            { key: "detailed", weight: 50 },
+                        ],
+                    })];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, provider.resolveStringEvaluation("var-off", "fallback", { targetingKey: "u1" }, noopLogger)];
+                case 2:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.reason).toBe(server_sdk_1.StandardResolutionReasons.DISABLED);
+                    (0, bun_test_1.expect)(res.value).toBe("fallback");
+                    (0, bun_test_1.expect)(res.variant).toBe("compact");
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("resolveNumberEvaluation returns FLAG_NOT_FOUND with default", 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*/, provider.resolveNumberEvaluation("any", 42, { targetingKey: "u" }, noopLogger)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.errorCode).toBe(server_sdk_1.ErrorCode.FLAG_NOT_FOUND);
+                    (0, bun_test_1.expect)(res.value).toBe(42);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("resolveObjectEvaluation returns FLAG_NOT_FOUND with default", 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*/, provider.resolveObjectEvaluation("any", { a: 1 }, { targetingKey: "u" }, noopLogger)];
+                case 1:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.errorCode).toBe(server_sdk_1.ErrorCode.FLAG_NOT_FOUND);
+                    (0, bun_test_1.expect)(res.value).toEqual({ a: 1 });
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    (0, bun_test_1.it)("does not resolve archived flags", 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({
+                        archived: true,
+                        enabled: true,
+                        key: "gone",
+                        name: "Gone",
+                        rolloutPercentage: 100,
+                        type: "boolean",
+                    })];
+                case 1:
+                    _a.sent();
+                    return [4 /*yield*/, provider.resolveBooleanEvaluation("gone", false, { targetingKey: "u1" }, noopLogger)];
+                case 2:
+                    res = _a.sent();
+                    (0, bun_test_1.expect)(res.errorCode).toBe(server_sdk_1.ErrorCode.FLAG_NOT_FOUND);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+});

package/dist/types.d.ts

@@ -17,6 +17,8 @@ export type FeatureFlagDocument = mongoose.Document<mongoose.Types.ObjectId> & {
     key: string;
     name: string;
     description: string;
+    /** OpenFeature default variant key; see schema description on {@link FeatureFlag}. */
+    defaultVariant?: string;
     enabled: boolean;
     type: FeatureFlagType;
     variants: FeatureFlagVariant[];
@@ -29,6 +31,19 @@ export type FeatureFlagDocument = mongoose.Document<mongoose.Types.ObjectId> & {
 };
 export type FeatureFlagModel = mongoose.Model<FeatureFlagDocument> & FindExactlyOnePlugin<FeatureFlagDocument> & FindOneOrNonePlugin<FeatureFlagDocument>;
 export type SegmentFunction = (user: unknown) => boolean;
+/** Minimal Socket.io server shape for broadcasting flag change notifications. */
+export interface FeatureFlagsSocketEmitter {
+    emit(event: string, ...args: unknown[]): unknown;
+}
+export interface FeatureFlagsLiveUpdatesOptions {
+    /**
+     * Socket.io server (or a getter returning it once initialized). When null,
+     * live updates are skipped.
+     */
+    socketIoServer: FeatureFlagsSocketEmitter | (() => FeatureFlagsSocketEmitter | null);
+    /** Custom event name. Default: `featureFlagsChanged`. */
+    eventName?: string;
+}
 export interface FeatureFlagsOptions {
     basePath?: string;
     segments?: Record<string, SegmentFunction>;
@@ -45,5 +60,21 @@ export interface FeatureFlagsOptions {
      * to checking `user.admin === true` when not provided.
      */
     segmentsPermission?: (user: unknown) => boolean;
+    /** Optional Socket.io integration for live client refresh when flags change. */
+    liveUpdates?: FeatureFlagsLiveUpdatesOptions;
+    /**
+     * OpenFeature provider domain for {@link OpenFeature.setProvider}. Defaults
+     * to `"feature-flags"` so the global default provider is left untouched.
+     */
+    openFeatureDomain?: string;
 }
 export type EvaluationResult = Record<string, boolean | string | null>;
+/** One flag entry in the `/flagConfiguration` response (OpenFeature static shape). */
+export interface FlagDefinition {
+    variants: Record<string, boolean | string>;
+    disabled: boolean;
+    defaultVariant: string;
+}
+export interface FlagConfigurationResponse {
+    data: Record<string, FlagDefinition>;
+}

package/package.json

@@ -4,7 +4,8 @@
     "url": "https://github.com/FlourishHealth/terreno/issues"
   },
   "dependencies": {
-    "@terreno/api": "0.18.0",
+    "@openfeature/server-sdk": "^1.22.0",
+    "@terreno/api": "0.20.0",
     "express": "^5.2.1",
     "lodash": "^4.17.23"
   },
@@ -51,5 +52,5 @@
     "test:coverage": "bun run ../scripts/check-coverage.ts"
   },
   "types": "dist/index.d.ts",
-  "version": "0.18.0"
+  "version": "0.20.0"
 }

package/src/featureFlagModel.ts

@@ -16,6 +16,14 @@ const featureFlagSchema = new mongoose.Schema<FeatureFlagDocument, FeatureFlagMo
         "Archived flags are excluded from evaluation. Use this instead of deleting flags to prevent bloat as new features are added.",
       type: Boolean,
     },
+    defaultVariant: {
+      description:
+        "OpenFeature defaultVariant key. Returned when the flag is disabled or errors during evaluation. " +
+        "For boolean flags, must be 'on' or 'off'. For variant flags, must be one of the keys in `variants`. " +
+        "Auto-populated on save when omitted (boolean → 'off', variant → first variant key).",
+      required: false,
+      type: String,
+    },
     description: {
       default: "",
       description: "Explanation of what this flag controls",
@@ -130,6 +138,37 @@ featureFlagSchema.pre("save", function () {
       });
     }
   }
+
+  if (
+    this.defaultVariant === undefined ||
+    this.defaultVariant === null ||
+    this.defaultVariant === ""
+  ) {
+    if (this.type === "boolean") {
+      this.set("defaultVariant", "off");
+    } else if (this.type === "variant" && this.variants?.length) {
+      this.set("defaultVariant", this.variants[0].key);
+    }
+  }
+
+  if (this.defaultVariant) {
+    if (this.type === "boolean") {
+      if (this.defaultVariant !== "on" && this.defaultVariant !== "off") {
+        throw new APIError({
+          status: 400,
+          title: "Boolean flags must use defaultVariant 'on' or 'off'",
+        });
+      }
+    } else if (this.type === "variant") {
+      const keys = new Set(this.variants.map((v) => v.key));
+      if (!keys.has(this.defaultVariant)) {
+        throw new APIError({
+          status: 400,
+          title: "defaultVariant must match one of the variant keys",
+        });
+      }
+    }
+  }
 });
 
 export const FeatureFlag = mongoose.model<FeatureFlagDocument, FeatureFlagModel>(
@@ -156,7 +195,7 @@ export const FeatureFlag = mongoose.model<FeatureFlagDocument, FeatureFlagModel>
  */
 export const featureFlagAdminConfig = {
   displayName: "Feature Flags",
-  listFields: ["key", "name", "type", "enabled", "archived", "created"],
+  listFields: ["key", "name", "type", "enabled", "archived", "defaultVariant", "created"],
   model: FeatureFlag,
   routePath: "/feature-flags",
 };