@terreno/feature-flags 0.7.1

package/src/featureFlagModel.ts

@@ -0,0 +1,138 @@
+import {
+  APIError,
+  createdUpdatedPlugin,
+  findExactlyOne,
+  findOneOrNone,
+  isDeletedPlugin,
+} from "@terreno/api";
+import mongoose from "mongoose";
+import type {FeatureFlagDocument, FeatureFlagModel} from "./types";
+
+const featureFlagSchema = new mongoose.Schema<FeatureFlagDocument, FeatureFlagModel>(
+  {
+    archived: {
+      default: false,
+      description:
+        "Archived flags are excluded from evaluation. Use this instead of deleting flags to prevent bloat as new features are added.",
+      type: Boolean,
+    },
+    description: {
+      default: "",
+      description: "Explanation of what this flag controls",
+      type: String,
+    },
+    enabled: {
+      default: false,
+      description: "Global kill switch — if false, flag is off for everyone",
+      type: Boolean,
+    },
+    key: {
+      description: "Unique identifier for the flag, e.g., 'new-checkout-flow'",
+      required: true,
+      trim: true,
+      type: String,
+      unique: true,
+    },
+    name: {
+      description: "Human-readable display name",
+      required: true,
+      type: String,
+    },
+    rolloutPercentage: {
+      default: 100,
+      description: "For boolean flags with no matching rules: percentage of users who get true",
+      max: 100,
+      min: 0,
+      type: Number,
+    },
+    rules: [
+      {
+        enabled: {
+          description:
+            "Whether the flag/variant is turned on when this rule matches. For boolean flags this is the override value; for variant flags it gates whether the forced variant applies.",
+          type: Boolean,
+        },
+        field: {
+          description:
+            "User field to match against (use with operator + value). Supports dot notation, e.g., 'email', 'admin', 'address.zip'. Use field/operator/value together, OR segment alone.",
+          type: String,
+        },
+        operator: {
+          description:
+            "Comparison operator for field-based rules (use with field + value). Use field/operator/value together, OR segment alone.",
+          enum: ["eq", "neq", "in", "nin", "gt", "lt", "contains"],
+          type: String,
+        },
+        segment: {
+          description:
+            "Name of a registered segment function, e.g., 'pro-users'. Use segment alone, OR field/operator/value together.",
+          type: String,
+        },
+        value: {
+          description:
+            "Value to compare against (use with field + operator). String, number, boolean, or array for in/nin. Use field/operator/value together, OR segment alone.",
+          type: mongoose.Schema.Types.Mixed,
+        },
+        variant: {
+          description:
+            "For variant flags only: forced variant key when this rule matches. Use field/operator/value together, OR segment alone.",
+          type: String,
+        },
+      },
+    ],
+    type: {
+      default: "boolean",
+      description: "Boolean toggle or multi-variant A/B test",
+      enum: ["boolean", "variant"],
+      type: String,
+    },
+    variants: [
+      {
+        key: {
+          description: "Variant identifier, e.g., 'control', 'variant-a'",
+          required: true,
+          type: String,
+        },
+        weight: {
+          description: "Percentage weight for assignment (0-100, all must sum to 100)",
+          max: 100,
+          min: 0,
+          required: true,
+          type: Number,
+        },
+      },
+    ],
+  },
+  {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
+);
+
+featureFlagSchema.plugin(createdUpdatedPlugin);
+featureFlagSchema.plugin(isDeletedPlugin);
+featureFlagSchema.plugin(findExactlyOne);
+featureFlagSchema.plugin(findOneOrNone);
+
+featureFlagSchema.index({archived: 1, enabled: 1});
+
+featureFlagSchema.pre("save", function () {
+  if (this.type === "variant") {
+    if (!this.variants || this.variants.length === 0) {
+      throw new APIError({
+        status: 400,
+        title: "Variant flags must have at least one variant",
+      });
+    }
+    const totalWeight = this.variants.reduce((sum, v) => sum + v.weight, 0);
+    if (totalWeight !== 100) {
+      throw new APIError({
+        detail: `Total weight is ${totalWeight}, expected 100`,
+        status: 400,
+        title: "Variant weights must sum to 100",
+      });
+    }
+  }
+});
+
+export const FeatureFlag = mongoose.model<FeatureFlagDocument, FeatureFlagModel>(
+  "FeatureFlag",
+  featureFlagSchema
+);

package/src/featureFlagsApp.ts

@@ -0,0 +1,95 @@
+import {
+  APIError,
+  asyncHandler,
+  authenticateMiddleware,
+  type ModelRouterOptions,
+  modelRouter,
+  type OpenApiMiddleware,
+  Permissions,
+  type TerrenoPlugin,
+} from "@terreno/api";
+import type express from "express";
+import type {Model} from "mongoose";
+import {evaluateAllFlags} from "./evaluate";
+import {FeatureFlag} from "./featureFlagModel";
+import type {FeatureFlagDocument, FeatureFlagsOptions, SegmentFunction} from "./types";
+
+/**
+ * TerrenoPlugin that provides feature flags and A/B testing.
+ *
+ * Creates admin CRUD endpoints for managing flags and a user-facing
+ * evaluation endpoint that returns all flag values for the current user.
+ *
+ * @example
+ * ```typescript
+ * const segments = {
+ *   "pro-users": (user) => user.plan === "pro",
+ *   "beta-testers": (user) => user.betaTester === true,
+ * };
+ *
+ * new TerrenoApp({ userModel: User })
+ *   .register(new FeatureFlagsApp({ segments }))
+ *   .start();
+ * ```
+ */
+export class FeatureFlagsApp implements TerrenoPlugin {
+  private options: FeatureFlagsOptions;
+  private segments: Record<string, SegmentFunction>;
+
+  constructor(options?: FeatureFlagsOptions) {
+    this.options = options ?? {};
+    this.segments = this.options.segments ?? {};
+  }
+
+  register(app: express.Application, openApi?: unknown): void {
+    const basePath = this.options.basePath ?? "/feature-flags";
+    const routerOptions: ModelRouterOptions<FeatureFlagDocument> = {
+      ...(openApi ? {openApi: openApi as OpenApiMiddleware} : {}),
+      permissions: {
+        create: [Permissions.IsAdmin],
+        delete: [Permissions.IsAdmin],
+        list: [Permissions.IsAdmin],
+        read: [Permissions.IsAdmin],
+        update: [Permissions.IsAdmin],
+      },
+      sort: "-created",
+    };
+
+    // Admin CRUD routes for flags
+    app.use(
+      `${basePath}/flags`,
+      modelRouter(FeatureFlag as Model<FeatureFlagDocument>, routerOptions)
+    );
+
+    // GET /feature-flags/evaluate — evaluate all flags for current user
+    app.get(
+      `${basePath}/evaluate`,
+      authenticateMiddleware(),
+      asyncHandler(async (req: express.Request, res: express.Response) => {
+        const user = req.user as {_id?: unknown; id?: string} | undefined;
+        if (!user) {
+          throw new APIError({status: 401, title: "Authentication required"});
+        }
+
+        const userId = String(user._id ?? user.id);
+        const results = await evaluateAllFlags(FeatureFlag, userId, user, this.segments);
+
+        return res.json({data: results});
+      })
+    );
+
+    // GET /feature-flags/segments — list registered segment names (admin only)
+    app.get(
+      `${basePath}/segments`,
+      authenticateMiddleware(),
+      asyncHandler(async (req: express.Request, res: express.Response) => {
+        const user = req.user as {admin?: boolean} | undefined;
+        if (!user?.admin) {
+          throw new APIError({status: 403, title: "Only admins can view segments"});
+        }
+
+        return res.json({data: Object.keys(this.segments)});
+      })
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export {deterministicHash, evaluateAllFlags, evaluateFlag} from "./evaluate";
+export {FeatureFlag} from "./featureFlagModel";
+export {FeatureFlagsApp} from "./featureFlagsApp";
+export type {
+  EvaluationResult,
+  FeatureFlagDocument,
+  FeatureFlagModel,
+  FeatureFlagRule,
+  FeatureFlagsOptions,
+  FeatureFlagType,
+  FeatureFlagVariant,
+  SegmentFunction,
+} from "./types";

package/src/tests/bunSetup.ts

@@ -0,0 +1,36 @@
+import {mock} from "bun:test";
+
+// Mock @sentry/bun module
+mock.module("@sentry/bun", () => {
+  const mockFn = (): ReturnType<typeof mock> => mock(() => {});
+
+  return {
+    addBreadcrumb: mockFn(),
+    captureException: mockFn(),
+    captureMessage: mockFn(),
+    close: mock(() => Promise.resolve(true)),
+    default: {
+      captureException: mockFn(),
+      captureMessage: mockFn(),
+      Handlers: {
+        errorHandler: mock(
+          () => (err: unknown, _req: unknown, _res: unknown, next: (e?: unknown) => void) =>
+            next(err)
+        ),
+        requestHandler: mock(() => (_req: unknown, _res: unknown, next: () => void) => next()),
+        tracingHandler: mock(() => (_req: unknown, _res: unknown, next: () => void) => next()),
+      },
+      init: mockFn(),
+      isInitialized: mock(() => true),
+      setupExpressErrorHandler: mockFn(),
+    },
+    flush: mock(() => Promise.resolve(true)),
+    init: mockFn(),
+    isInitialized: mock(() => true),
+    setContext: mockFn(),
+    setTag: mockFn(),
+    setUser: mockFn(),
+    setupExpressErrorHandler: mockFn(),
+    withScope: mock((callback: (scope: unknown) => void) => callback({})),
+  };
+});