@brandtg/flapjack 1.3.0 → 1.5.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
 
@@ -138,6 +181,36 @@ await featureFlags.isActiveForUser({
 });
 ```
 
+## Organizing Flags with Tags
+
+Tags are freeform labels for organizing flags without encoding that information in
+the flag name. They do **not** affect evaluation — they are purely organizational
+metadata. A common use is associating a release version with a flag, which can then
+be bumped via a database update without any code change.
+
+```typescript
+// Tag a flag with a release version (and any other labels)
+await featureFlags.create({
+  name: "checkout_v2",
+  tags: ["release:1.5.0", "checkout"],
+});
+
+// Find every flag shipping in a given release
+const flags = await featureFlags.listByTag("release:1.5.0");
+
+// Bump the release version later — no code change required
+await featureFlags.update(flag.id, { tags: ["release:1.6.0", "checkout"] });
+```
+
+The equivalent CLI commands:
+
+```bash
+flapjack create --name checkout_v2 --tags release:1.5.0 checkout
+flapjack list-by-tag release:1.5.0
+flapjack update <id> --tags release:1.6.0 checkout
+flapjack update <id> --clear-tags
+```
+
 ## Performance Considerations
 
 ⚠️ **Important**: Without caching, Flapjack queries the database on every `isActiveForUser()` call. For high-traffic applications, use the built-in caching layer:
@@ -299,17 +372,21 @@ await featureFlags.update(flagId, { percent: 100 });
 
 Creates a new feature flag.
 
-#### `getById(id: number): Promise<FeatureFlag | null>`
+#### `getById(id: number, options?: { includeArchived?: boolean }): Promise<FeatureFlag | null>`
 
-Retrieves a feature flag by its ID.
+Retrieves a feature flag by its ID. Archived flags are excluded unless `includeArchived` is `true`.
 
-#### `getByName(name: string): Promise<FeatureFlag | null>`
+#### `getByName(name: string, options?: { includeArchived?: boolean }): Promise<FeatureFlag | null>`
 
-Retrieves a feature flag by its name.
+Retrieves a feature flag by its name. Archived flags are excluded unless `includeArchived` is `true`.
 
-#### `list(): Promise<FeatureFlag[]>`
+#### `list(options?: { includeArchived?: boolean }): Promise<FeatureFlag[]>`
 
-Lists all feature flags, ordered by ID.
+Lists all feature flags, ordered by ID. Archived flags are excluded unless `includeArchived` is `true`.
+
+#### `listByTag(tag: string, options?: { includeArchived?: boolean }): Promise<FeatureFlag[]>`
+
+Lists all feature flags carrying the given tag (exact match), ordered by ID. Archived flags are excluded unless `includeArchived` is `true`.
 
 #### `update(id: number, changes: UpdateChanges): Promise<FeatureFlag | null>`
 
@@ -317,7 +394,13 @@ Updates a feature flag. Returns the updated flag or null if not found.
 
 #### `delete(id: number): Promise<boolean>`
 
-Deletes a feature flag. Returns true if deleted, false if not found.
+Permanently deletes a feature flag and all its relationships. Returns true if deleted, false if not found. To hide a flag while keeping its history, use `archive` instead.
+
+#### `archive(id: number): Promise<FeatureFlag | null>`
+
+Archives (hides) a feature flag while keeping the row for historical/audit purposes. Archived flags are excluded from normal reads and evaluate as inactive, but remain retrievable via `{ includeArchived: true }`. Returns the archived flag, or null if it does not exist or is already archived.
+
+Archiving is **irreversible** (there is no `unarchive`) and the `archived` timestamp is immutable once set. The flag's name stays reserved permanently — a new flag cannot reuse it; create a new flag with a different name instead. The same `archive(id)` / `includeArchived` semantics apply to `FeatureFlagGroupModel`.
 
 #### `isActiveForUser(params): Promise<boolean>`
 
@@ -341,21 +424,70 @@ flapjack create --name my_feature --roles admin --note "Admin-only feature"
 # List all flags
 flapjack list
 
+# Include archived (hidden) flags in any read command
+flapjack list --include-archived
+flapjack get-by-name my_feature --include-archived
+
+# List flags carrying a tag (e.g. a release version)
+flapjack list-by-tag release:1.5.0
+
 # Get a specific flag
 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
 
 # Clear specific fields
 flapjack update 1 --clear-roles --clear-percent
 
-# Delete a flag
+# Delete a flag (permanent — destroys all metadata)
 flapjack delete 1
 
+# Archive a flag (hide it but keep its history; irreversible)
+flapjack archive 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
+flapjack group-archive 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
 ```
@@ -409,8 +541,11 @@ await featureFlags.update(flagId, { percent: 10 });
 await featureFlags.update(flagId, { everyone: true });
 
 // 5. Cleanup (after feature is stable)
-// Remove feature flag checks from code
-await featureFlags.delete(flagId);
+// Remove feature flag checks from code, then either:
+//   - delete to remove it entirely, or
+//   - archive to hide it while keeping its history for audit
+await featureFlags.archive(flagId);
+// (archive is irreversible and the name stays reserved permanently)
 ```
 
 ### Error Handling

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);