@brandtg/flapjack 1.2.0 → 1.4.0

package/README.md

@@ -9,6 +9,7 @@ A simple feature flags library with PostgreSQL integration, inspired by [django-
 ## Features
 
 - **Multiple targeting strategies**: Enable features for specific users, roles, groups, or percentage rollouts
+- **External subject targeting**: Assign flags (or flag groups) to external subjects like tenants or org IDs
 - **Consistent hashing**: Deterministic user bucketing for A/B testing and experimentation
 - **PostgreSQL-backed**: Reliable, transactional flag storage with your existing database
 - **CLI included**: Manage feature flags from the command line
@@ -63,6 +64,16 @@ const active = await featureFlag.isActiveForUser({
   user: "1234",
 });
 
+// Assign a flag to an external subject ID (for example, a tenant)
+await featureFlags.addSubject(flag.id, "tenant:acme");
+
+// Check if active for a broader context that includes external subject IDs
+const activeForTenant = await featureFlags.isActiveForContext({
+  name: "enable_new_checkout_20250101_gbrandt",
+  user: "1234",
+  subjects: ["tenant:acme"],
+});
+
 // Enable the feature flag for certain roles
 await featureFlags.update(flag.id, {
   roles: ["admin", "staff"],
@@ -101,9 +112,41 @@ When checking if a feature flag is active for a user, Flapjack evaluates rules i
 1. **Everyone Override** (`everyone: true/false`): If set, immediately returns this value, ignoring all other rules
 2. **User List** (`users: [...]`): If the user ID is in this list, returns `true`
 3. **Group Membership** (`groups: [...]`): If the user belongs to any specified group, returns `true`
-4. **Role Membership** (`roles: [...]`): If the user has any specified role, returns `true`
-5. **Percentage Rollout** (`percent: 0-99.9`): Uses consistent hashing to deterministically bucket users
-6. **Default**: Returns `false` if no conditions are met
+4. **External Subject Match** (`subjects: [...]`): If any provided subject matches a direct flag subject or a flag-group subject, returns `true`
+5. **Role Membership** (`roles: [...]`): If the user has any specified role, returns `true`
+6. **Percentage Rollout** (`percent: 0-99.9`): Uses consistent hashing to deterministically bucket users
+7. **Default**: Returns `false` if no conditions are met
+
+## External Subject Targeting
+
+Use subjects when identity/group membership is managed outside Flapjack (for example, tenant IDs from another system).
+
+```typescript
+const groupModel = new FeatureFlagGroupModel(pool);
+const flagModel = new FeatureFlagModel(pool);
+
+const rolloutGroup = await groupModel.create({
+  name: "checkout_rollout",
+});
+
+const checkoutFlag = await flagModel.create({
+  name: "enable_checkout_v2",
+});
+
+await groupModel.addFeatureFlag(rolloutGroup.id, checkoutFlag.id);
+
+// Attach external subject to all flags in this feature flag group
+await groupModel.addSubject(rolloutGroup.id, "tenant:acme");
+
+// You can also attach a subject directly to a single flag
+await flagModel.addSubject(checkoutFlag.id, "tenant:beta");
+
+const isActive = await flagModel.isActiveForContext({
+  name: "enable_checkout_v2",
+  user: "user_123",
+  subjects: ["tenant:acme"],
+});
+```
 
 ### Example Evaluation
 
@@ -347,6 +390,15 @@ flapjack get-by-name my_feature
 # Check if active for a user
 flapjack is-active my_feature --user user123 --roles admin
 
+# Check if multiple flags are active for a user
+flapjack are-active --names my_feature other_feature --user user123 --roles admin
+
+# Check if active for context (with external subject IDs)
+flapjack is-active-context my_feature --user user123 --subjects tenant:acme
+
+# Check multiple flags for context
+flapjack are-active-context --names my_feature other_feature --subjects tenant:acme
+
 # Update a flag
 flapjack update 1 --percent 50 --everyone false
 
@@ -356,6 +408,35 @@ flapjack update 1 --clear-roles --clear-percent
 # Delete a flag
 flapjack delete 1
 
+# Add/remove/list subject mappings on a flag
+flapjack add-subject 1 tenant:acme
+flapjack remove-subject 1 tenant:acme
+flapjack list-subjects 1
+flapjack list-by-subject tenant:acme
+
+# Feature flag groups
+flapjack group-create --name checkout_rollout --note "Checkout launch cohort"
+flapjack group-list
+flapjack group-get 1
+flapjack group-get-by-name checkout_rollout
+flapjack group-update 1 --note "Updated"
+flapjack group-delete 1
+
+# Group membership
+flapjack group-add-flag 1 10
+flapjack group-remove-flag 1 10
+flapjack group-list-flags 1
+flapjack group-list-for-flag 10
+
+# Bulk update all flags in a group
+flapjack group-update-all 1 --percent 25 --roles admin
+
+# Group-level subject mappings
+flapjack group-add-subject 1 tenant:acme
+flapjack group-remove-subject 1 tenant:acme
+flapjack group-list-subjects 1
+flapjack group-list-by-subject tenant:acme
+
 # Debug user bucketing
 flapjack hash-user user123
 ```

package/dist/cache.d.ts

@@ -44,5 +44,12 @@ export declare class FeatureFlagCache {
         roles?: string[];
         groups?: string[];
     }): Promise<boolean>;
+    isActiveForContext({ name, user, roles, groups, subjects, }: {
+        name: string;
+        user?: string;
+        roles?: string[];
+        groups?: string[];
+        subjects?: string[];
+    }): Promise<boolean>;
 }
 //# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9C,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AASD;;GAEG;AACH,qBAAa,aAAa,CAAC,CAAC,CAAE,YAAW,KAAK,CAAC,CAAC,CAAC;IAC/C,OAAO,CAAC,KAAK,CAAoC;IAE3C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAgBxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC;;OAEG;IACH,YAAY,IAAI,IAAI;IASpB;;OAEG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,GAAG,CAAS;gBAER,EACV,KAAK,EACL,KAAK,EACL,GAAiB,GAClB,EAAE;QACD,KAAK,EAAE,gBAAgB,CAAC;QACxB,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QACtB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd;IAMD;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAyBlB,eAAe,CAAC,EACpB,IAAI,EACJ,IAAI,EACJ,KAAK,EACL,MAAM,GACP,EAAE;QACD,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;KACnB,GAAG,OAAO,CAAC,OAAO,CAAC;CAuBrB"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9C,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AASD;;GAEG;AACH,qBAAa,aAAa,CAAC,CAAC,CAAE,YAAW,KAAK,CAAC,CAAC,CAAC;IAC/C,OAAO,CAAC,KAAK,CAAoC;IAE3C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAgBxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC;;OAEG;IACH,YAAY,IAAI,IAAI;IASpB;;OAEG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,GAAG,CAAS;gBAER,EACV,KAAK,EACL,KAAK,EACL,GAAiB,GAClB,EAAE;QACD,KAAK,EAAE,gBAAgB,CAAC;QACxB,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QACtB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd;IAMD;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA4BlB,eAAe,CAAC,EACpB,IAAI,EACJ,IAAI,EACJ,KAAK,EACL,MAAM,GACP,EAAE;QACD,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;KACnB,GAAG,OAAO,CAAC,OAAO,CAAC;IASd,kBAAkB,CAAC,EACvB,IAAI,EACJ,IAAI,EACJ,KAAK,EACL,MAAM,EACN,QAAQ,GACT,EAAE;QACD,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,GAAG,OAAO,CAAC,OAAO,CAAC;CA8BrB"}

package/dist/cache.js

@@ -61,13 +61,14 @@ export class FeatureFlagCache {
     /**
      * Generates a cache key using murmur3 hash of the flag name and parameters.
      */
-    generateCacheKey({ name, user, roles, groups, }) {
+    generateCacheKey({ name, user, roles, groups, subjects, }) {
         // Create a consistent string representation of the parameters
         const keyParts = [
             name,
             user || "",
             (roles || []).sort().join(","),
             (groups || []).sort().join(","),
+            (subjects || []).sort().join(","),
         ];
         const keyString = keyParts.join("|");
         // Generate murmur3 hash
@@ -75,19 +76,34 @@ export class FeatureFlagCache {
         return `flag:${hash}`;
     }
     async isActiveForUser({ name, user, roles, groups, }) {
+        return this.isActiveForContext({
+            name,
+            user,
+            roles,
+            groups,
+        });
+    }
+    async isActiveForContext({ name, user, roles, groups, subjects, }) {
         // Generate cache key
-        const cacheKey = this.generateCacheKey({ name, user, roles, groups });
+        const cacheKey = this.generateCacheKey({
+            name,
+            user,
+            roles,
+            groups,
+            subjects,
+        });
         // Try to get from cache first
         const cachedResult = await this.cache.get(cacheKey);
         if (cachedResult !== undefined) {
             return cachedResult;
         }
         // Cache miss, get from model
-        const result = await this.model.isActiveForUser({
+        const result = await this.model.isActiveForContext({
             name,
             user,
             roles,
             groups,
+            subjects,
         });
         // Store in cache with TTL
         this.cache.set(cacheKey, result, this.ttl);