@terreno/feature-flags 57.2.0 → 57.3.0

package/README.md

@@ -0,0 +1,48 @@
+# @terreno/feature-flags
+
+Feature flags and A/B testing plugin for @terreno/api.
+
+## Install
+
+```bash
+bun add @terreno/feature-flags
+```
+
+Peer dependency: `mongoose ^8.0.0 || ^9.0.0`. `@terreno/api` is required at runtime.
+
+## Quick start
+
+```typescript
+import {TerrenoApp} from "@terreno/api";
+import {AdminApp} from "@terreno/admin-backend";
+import {FeatureFlagsApp, featureFlagAdminConfig} from "@terreno/feature-flags";
+import {User} from "./models/user";
+
+new TerrenoApp({userModel: User})
+  .register(new FeatureFlagsApp({}))
+  .register(new AdminApp({models: [featureFlagAdminConfig]}))
+  .start();
+```
+
+Authenticated clients load flags from `GET /feature-flags/flagConfiguration`. Prefer that bulk map over the deprecated `GET /feature-flags/evaluate` endpoint (responses include `Deprecation: true` and a `Sunset` header).
+
+Pass `liveUpdates: {socketIoServer: io}` to broadcast flag-key changes over Socket.io. Live updates require MongoDB running as a replica set (a single-node replica set is enough).
+
+## What's included
+
+- `FeatureFlagsApp` — TerrenoPlugin for admin CRUD, `/flagConfiguration`, and `/evaluate`
+- `FeatureFlag` — Mongoose model for flag documents
+- `featureFlagAdminConfig` — ready-to-use `AdminApp` model config
+- `evaluateFlag` / `evaluateAllFlags` — server-side evaluation helpers
+- `MongoFeatureFlagProvider` — OpenFeature server provider
+- Optional socket live updates on change streams
+
+## Documentation
+
+Full API reference: [docs/reference/feature-flags.md](https://github.com/flourishhealth/terreno/blob/master/docs/reference/feature-flags.md)
+
+How-to: [Add feature flags](https://github.com/flourishhealth/terreno/blob/master/docs/how-to/add-feature-flags.md)
+
+## License and Contributing
+
+Licensed under the [MIT License](https://github.com/flourishhealth/terreno/blob/master/LICENSE). See [CONTRIBUTING.md](https://github.com/flourishhealth/terreno/blob/master/CONTRIBUTING.md) for contribution guidelines.

package/package.json

@@ -5,14 +5,14 @@
   },
   "dependencies": {
     "@openfeature/server-sdk": "^1.22.0",
-    "@terreno/api": "57.2.0",
+    "@terreno/api": "57.3.0",
     "express": "^5.2.1",
     "lodash": "^4.18.1"
   },
-  "description": "Feature flags and A/B testing plugin for @terreno/api",
+  "description": "Feature flags and A/B testing plugin for @terreno/api — part of Terreno, the batteries-included TypeScript framework for universal apps.",
   "devDependencies": {
     "@biomejs/biome": "^2.3.6",
-    "@terreno/test": "57.2.0",
+    "@terreno/test": "57.3.0",
     "@types/bun": "^1.4.0",
     "@types/express": "^5.0.6",
     "@types/lodash": "^4.17.17",
@@ -54,5 +54,5 @@
     "test:coverage": "bun run ../scripts/check-coverage.ts"
   },
   "types": "dist/index.d.ts",
-  "version": "57.2.0"
+  "version": "57.3.0"
 }

package/src/flagConfiguration.test.ts

@@ -0,0 +1,80 @@
+import {describe, expect, it} from "bun:test";
+
+import {buildFlagDefinition, effectiveDefaultVariantForFlag} from "./flagConfiguration";
+import type {FeatureFlagDocument, SegmentFunction} from "./types";
+
+const booleanFlag = (overrides: Partial<FeatureFlagDocument> = {}): FeatureFlagDocument =>
+  ({
+    archived: false,
+    description: "d",
+    enabled: true,
+    key: "bool",
+    name: "Bool",
+    rolloutPercentage: 100,
+    rules: [],
+    type: "boolean",
+    variants: [],
+    ...overrides,
+  }) as unknown as FeatureFlagDocument;
+
+const variantFlag = (overrides: Partial<FeatureFlagDocument> = {}): FeatureFlagDocument =>
+  ({
+    archived: false,
+    description: "d",
+    enabled: true,
+    key: "exp",
+    name: "Exp",
+    rolloutPercentage: 100,
+    rules: [],
+    type: "variant",
+    variants: [
+      {key: "control", weight: 50},
+      {key: "treatment", weight: 50},
+    ],
+    ...overrides,
+  }) as unknown as FeatureFlagDocument;
+
+const noSegments: Record<string, SegmentFunction> = {};
+
+describe("effectiveDefaultVariantForFlag", () => {
+  it("uses defaultVariant when present", () => {
+    expect(effectiveDefaultVariantForFlag(booleanFlag({defaultVariant: "on"}))).toBe("on");
+  });
+
+  it("defaults boolean flags to off", () => {
+    expect(effectiveDefaultVariantForFlag(booleanFlag())).toBe("off");
+  });
+
+  it("defaults variant flags to the first variant key", () => {
+    expect(effectiveDefaultVariantForFlag(variantFlag())).toBe("control");
+    expect(effectiveDefaultVariantForFlag(variantFlag({variants: []}))).toBe("off");
+  });
+});
+
+describe("buildFlagDefinition", () => {
+  it("maps a boolean evaluation to on/off variants", () => {
+    expect(buildFlagDefinition(booleanFlag(), "user-1", {}, noSegments)).toEqual({
+      defaultVariant: "on",
+      disabled: false,
+      variants: {off: false, on: true},
+    });
+  });
+
+  it("maps a disabled variant flag onto the default variant", () => {
+    const definition = buildFlagDefinition(variantFlag({enabled: false}), "user-1", {}, noSegments);
+    expect(definition.defaultVariant).toBe("control");
+    expect(definition.variants).toEqual({control: "control", treatment: "treatment"});
+  });
+
+  it("uses the evaluated variant key when it matches a defined variant", () => {
+    const definition = buildFlagDefinition(
+      variantFlag({
+        rules: [{field: "id", operator: "eq", value: "user-1", variant: "treatment"}],
+      }),
+      "user-1",
+      {id: "user-1"},
+      noSegments
+    );
+    expect(definition.defaultVariant).toBe("treatment");
+  });
+});