@terreno/feature-flags 0.7.1

package/src/tests/featureFlagModel.test.ts

@@ -0,0 +1,205 @@
+import {afterEach, describe, expect, it} from "bun:test";
+import {FeatureFlag} from "../featureFlagModel";
+
+describe("FeatureFlag model", () => {
+  afterEach(async () => {
+    await FeatureFlag.deleteMany({});
+  });
+
+  it("creates a boolean flag with defaults", async () => {
+    const flag = await FeatureFlag.create({
+      key: "new-checkout-flow",
+      name: "New Checkout Flow",
+    });
+
+    expect(flag.key).toBe("new-checkout-flow");
+    expect(flag.name).toBe("New Checkout Flow");
+    expect(flag.enabled).toBe(false);
+    expect(flag.archived).toBe(false);
+    expect(flag.type).toBe("boolean");
+    expect(flag.rolloutPercentage).toBe(100);
+    expect(flag.description).toBe("");
+    expect(flag.rules).toEqual([]);
+    expect(flag.variants).toEqual([]);
+  });
+
+  it("rejects unknown fields (strict: 'throw')", async () => {
+    await expect(
+      FeatureFlag.create({
+        key: "strict-test",
+        name: "Strict Test",
+        unknownField: true,
+      } as unknown as Record<string, unknown>)
+    ).rejects.toBeDefined();
+  });
+
+  it("requires a key and name", async () => {
+    await expect(
+      FeatureFlag.create({
+        name: "Missing key",
+      } as unknown as Record<string, unknown>)
+    ).rejects.toBeDefined();
+
+    await expect(
+      FeatureFlag.create({
+        key: "missing-name",
+      } as unknown as Record<string, unknown>)
+    ).rejects.toBeDefined();
+  });
+
+  it("enforces unique keys", async () => {
+    await FeatureFlag.syncIndexes();
+
+    await FeatureFlag.create({key: "dup-key", name: "First"});
+    await expect(FeatureFlag.create({key: "dup-key", name: "Second"})).rejects.toBeDefined();
+  });
+
+  it("clamps rolloutPercentage to the 0-100 range", async () => {
+    await expect(
+      FeatureFlag.create({
+        key: "over-rollout",
+        name: "Over",
+        rolloutPercentage: 150,
+      })
+    ).rejects.toBeDefined();
+
+    await expect(
+      FeatureFlag.create({
+        key: "under-rollout",
+        name: "Under",
+        rolloutPercentage: -5,
+      })
+    ).rejects.toBeDefined();
+  });
+
+  it("accepts variant flags with variants that sum to 100", async () => {
+    const flag = await FeatureFlag.create({
+      key: "variant-flag",
+      name: "Variant Flag",
+      type: "variant",
+      variants: [
+        {key: "control", weight: 40},
+        {key: "variant-a", weight: 60},
+      ],
+    });
+
+    expect(flag.type).toBe("variant");
+    expect(flag.variants.length).toBe(2);
+  });
+
+  it("rejects variant flags with no variants", async () => {
+    await expect(
+      FeatureFlag.create({
+        key: "variant-no-variants",
+        name: "No Variants",
+        type: "variant",
+        variants: [],
+      })
+    ).rejects.toMatchObject({title: "Variant flags must have at least one variant"});
+  });
+
+  it("rejects variant flags whose variant weights do not sum to 100", async () => {
+    await expect(
+      FeatureFlag.create({
+        key: "variant-bad-weights",
+        name: "Bad Weights",
+        type: "variant",
+        variants: [
+          {key: "control", weight: 10},
+          {key: "variant-a", weight: 10},
+        ],
+      })
+    ).rejects.toMatchObject({title: "Variant weights must sum to 100"});
+  });
+
+  it("allows boolean flags without variants", async () => {
+    const flag = await FeatureFlag.create({
+      key: "boolean-no-variants",
+      name: "Boolean",
+      type: "boolean",
+    });
+    expect(flag.variants).toEqual([]);
+  });
+
+  it("trims whitespace on keys", async () => {
+    const flag = await FeatureFlag.create({
+      key: "  padded-key  ",
+      name: "Padded",
+    });
+    expect(flag.key).toBe("padded-key");
+  });
+
+  it("stores complex rules including segments and field rules", async () => {
+    const flag = await FeatureFlag.create({
+      key: "complex-rules",
+      name: "Complex",
+      rules: [
+        {enabled: true, segment: "beta"},
+        {enabled: true, field: "plan", operator: "in", value: ["pro", "enterprise"]},
+        {enabled: false, field: "email", operator: "contains", value: "@example.com"},
+      ],
+    });
+    expect(flag.rules.length).toBe(3);
+    expect(flag.rules[0].segment).toBe("beta");
+    expect(flag.rules[1].operator).toBe("in");
+    expect(flag.rules[1].value).toEqual(["pro", "enterprise"]);
+    expect(flag.rules[2].enabled).toBe(false);
+  });
+
+  it("rejects invalid rule operators via the enum constraint", async () => {
+    await expect(
+      FeatureFlag.create({
+        key: "bad-op",
+        name: "Bad Operator",
+        rules: [{enabled: true, field: "plan", operator: "bogus", value: "pro"}],
+      })
+    ).rejects.toBeDefined();
+  });
+
+  it("rejects invalid type values via the enum constraint", async () => {
+    await expect(
+      FeatureFlag.create({
+        key: "bad-type",
+        name: "Bad Type",
+        type: "nonsense",
+      } as unknown as Record<string, unknown>)
+    ).rejects.toBeDefined();
+  });
+
+  it("supports the isDeleted soft-delete plugin", async () => {
+    const flag = await FeatureFlag.create({
+      key: "soft-delete",
+      name: "Soft",
+    });
+
+    expect(flag.deleted).toBe(false);
+
+    flag.deleted = true;
+    await flag.save();
+
+    const found = await FeatureFlag.findOne({key: "soft-delete"});
+    expect(found).toBeNull();
+
+    const foundWithDeleted = await FeatureFlag.findOne({deleted: true, key: "soft-delete"});
+    expect(foundWithDeleted?._id.toString()).toBe(flag._id.toString());
+  });
+
+  it("sets created/updated timestamps on save", async () => {
+    const flag = await FeatureFlag.create({
+      key: "timestamps",
+      name: "Timestamps",
+    });
+    expect(flag.created).toBeInstanceOf(Date);
+    expect(flag.updated).toBeInstanceOf(Date);
+  });
+
+  it("supports findExactlyOne and findOneOrNone plugins", async () => {
+    await FeatureFlag.create({key: "existing-flag", name: "Exists"});
+
+    const exact = await FeatureFlag.findExactlyOne({key: "existing-flag"});
+    expect(exact.name).toBe("Exists");
+
+    const maybe = await FeatureFlag.findOneOrNone({key: "missing-flag"});
+    expect(maybe).toBeNull();
+  });
+});

package/src/tests/featureFlagsApp.test.ts

@@ -0,0 +1,221 @@
+import {afterEach, beforeEach, describe, expect, it} from "bun:test";
+import {
+  addAuthRoutes,
+  apiErrorMiddleware,
+  apiUnauthorizedMiddleware,
+  setupAuth,
+  type UserModel as UserModelType,
+} from "@terreno/api";
+import {authAsUser, getBaseServer, setupDb, UserModel} from "@terreno/api/src/tests";
+import type express from "express";
+import supertest from "supertest";
+import type TestAgent from "supertest/lib/agent";
+
+import {FeatureFlag} from "../featureFlagModel";
+import {FeatureFlagsApp} from "../featureFlagsApp";
+import type {SegmentFunction} from "../types";
+
+const buildApp = (options?: {
+  basePath?: string;
+  segments?: Record<string, SegmentFunction>;
+}): express.Application => {
+  const app = getBaseServer();
+  setupAuth(app, UserModel as unknown as UserModelType);
+  addAuthRoutes(app, UserModel as unknown as UserModelType);
+
+  const plugin = new FeatureFlagsApp(options);
+  plugin.register(app);
+
+  app.use(apiUnauthorizedMiddleware);
+  app.use(apiErrorMiddleware);
+  return app;
+};
+
+describe("FeatureFlagsApp", () => {
+  let app: express.Application;
+  let adminAgent: TestAgent;
+  let notAdminAgent: TestAgent;
+
+  beforeEach(async () => {
+    await setupDb();
+    await FeatureFlag.deleteMany({});
+  });
+
+  afterEach(async () => {
+    await FeatureFlag.deleteMany({});
+  });
+
+  describe("construction", () => {
+    it("defaults basePath to /feature-flags and segments to an empty object", async () => {
+      app = buildApp();
+      adminAgent = await authAsUser(app, "admin");
+
+      const res = await adminAgent.get("/feature-flags/segments").expect(200);
+      expect(res.body.data).toEqual([]);
+    });
+
+    it("respects a custom basePath", async () => {
+      app = buildApp({basePath: "/flags"});
+      adminAgent = await authAsUser(app, "admin");
+
+      await adminAgent.get("/flags/segments").expect(200);
+      await adminAgent.get("/feature-flags/segments").expect(404);
+    });
+
+    it("accepts an empty options object", async () => {
+      app = buildApp({});
+      adminAgent = await authAsUser(app, "admin");
+
+      const res = await adminAgent.get("/feature-flags/segments").expect(200);
+      expect(res.body.data).toEqual([]);
+    });
+  });
+
+  describe("admin CRUD routes", () => {
+    beforeEach(async () => {
+      app = buildApp();
+      adminAgent = await authAsUser(app, "admin");
+      notAdminAgent = await authAsUser(app, "notAdmin");
+    });
+
+    it("lets admins create, list, read, update, and delete flags", async () => {
+      const createRes = await adminAgent
+        .post("/feature-flags/flags")
+        .send({enabled: true, key: "new-flag", name: "New Flag"})
+        .expect(201);
+
+      const flagId: string = createRes.body.data._id;
+      expect(createRes.body.data.key).toBe("new-flag");
+
+      const listRes = await adminAgent.get("/feature-flags/flags").expect(200);
+      expect(listRes.body.data.length).toBe(1);
+
+      const readRes = await adminAgent.get(`/feature-flags/flags/${flagId}`).expect(200);
+      expect(readRes.body.data.key).toBe("new-flag");
+
+      const updateRes = await adminAgent
+        .patch(`/feature-flags/flags/${flagId}`)
+        .send({rolloutPercentage: 50})
+        .expect(200);
+      expect(updateRes.body.data.rolloutPercentage).toBe(50);
+
+      await adminAgent.delete(`/feature-flags/flags/${flagId}`).expect(204);
+      const finalList = await adminAgent.get("/feature-flags/flags").expect(200);
+      expect(finalList.body.data.length).toBe(0);
+    });
+
+    it("rejects non-admins from the CRUD routes", async () => {
+      // modelRouter responds with 405 Method Not Allowed when permissions fail
+      await notAdminAgent.get("/feature-flags/flags").expect(405);
+      await notAdminAgent
+        .post("/feature-flags/flags")
+        .send({key: "nope", name: "Nope"})
+        .expect(405);
+    });
+
+    it("rejects unauthenticated requests to CRUD routes", async () => {
+      const unauth = supertest(app);
+      await unauth.get("/feature-flags/flags").expect(401);
+    });
+  });
+
+  describe("GET /feature-flags/evaluate", () => {
+    beforeEach(async () => {
+      const segments: Record<string, SegmentFunction> = {
+        admins: (user: unknown) => (user as {admin?: boolean}).admin === true,
+      };
+      app = buildApp({segments});
+    });
+
+    it("returns 401 for unauthenticated callers", async () => {
+      const unauth = supertest(app);
+      await unauth.get("/feature-flags/evaluate").expect(401);
+    });
+
+    it("returns all enabled, non-archived flag values for the current user", async () => {
+      await FeatureFlag.create({
+        enabled: true,
+        key: "rolled-out",
+        name: "Rolled out",
+        rolloutPercentage: 100,
+      });
+      await FeatureFlag.create({
+        enabled: false,
+        key: "disabled-flag",
+        name: "Disabled",
+        rolloutPercentage: 100,
+      });
+      await FeatureFlag.create({
+        archived: true,
+        enabled: true,
+        key: "archived-flag",
+        name: "Archived",
+        rolloutPercentage: 100,
+      });
+      await FeatureFlag.create({
+        enabled: true,
+        key: "admins-only",
+        name: "Admins",
+        rolloutPercentage: 0,
+        rules: [{enabled: true, segment: "admins"}],
+      });
+
+      adminAgent = await authAsUser(app, "admin");
+
+      const res = await adminAgent.get("/feature-flags/evaluate").expect(200);
+      expect(res.body.data["rolled-out"]).toBe(true);
+      expect(res.body.data["admins-only"]).toBe(true);
+      expect(res.body.data["disabled-flag"]).toBeUndefined();
+      expect(res.body.data["archived-flag"]).toBeUndefined();
+    });
+
+    it("includes an admin's own evaluated flags", async () => {
+      await FeatureFlag.create({
+        enabled: true,
+        key: "user-only",
+        name: "User only",
+        rolloutPercentage: 0,
+        rules: [{enabled: true, field: "admin", operator: "eq", value: true}],
+      });
+
+      adminAgent = await authAsUser(app, "admin");
+      const res = await adminAgent.get("/feature-flags/evaluate").expect(200);
+      expect(res.body.data["user-only"]).toBe(true);
+
+      notAdminAgent = await authAsUser(app, "notAdmin");
+      const notAdminRes = await notAdminAgent.get("/feature-flags/evaluate").expect(200);
+      // notAdmin isn't admin, rolloutPercentage is 0 → should evaluate false
+      expect(notAdminRes.body.data["user-only"]).toBe(false);
+    });
+  });
+
+  describe("GET /feature-flags/segments", () => {
+    beforeEach(async () => {
+      app = buildApp({
+        segments: {
+          admins: () => true,
+          "beta-testers": () => false,
+        },
+      });
+    });
+
+    it("returns the registered segment keys for admins", async () => {
+      adminAgent = await authAsUser(app, "admin");
+
+      const res = await adminAgent.get("/feature-flags/segments").expect(200);
+      expect(res.body.data.sort()).toEqual(["admins", "beta-testers"]);
+    });
+
+    it("rejects non-admin users", async () => {
+      notAdminAgent = await authAsUser(app, "notAdmin");
+
+      const res = await notAdminAgent.get("/feature-flags/segments").expect(403);
+      expect(res.body.title).toInclude("Only admins can view segments");
+    });
+
+    it("requires authentication", async () => {
+      const unauth = supertest(app);
+      await unauth.get("/feature-flags/segments").expect(401);
+    });
+  });
+});

package/src/types.ts

@@ -0,0 +1,46 @@
+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/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "allowSyntheticDefaultImports": true,
+    "baseUrl": "./",
+    "declaration": true,
+    "downlevelIteration": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "jsx": "react",
+    "lib": ["es2017", "dom", "es2017.object"],
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "noEmit": false,
+    "noImplicitAny": false,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "outDir": "./dist",
+    "preserveConstEnums": true,
+    "removeComments": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "strictFunctionTypes": true,
+    "strictNullChecks": true,
+    "target": "es5"
+  },
+  "exclude": ["node_modules"],
+  "include": ["src/**/*.ts*", "src/*.ts"]
+}