@brandtg/flapjack 1.2.0 → 1.4.0

package/dist/model.d.ts

@@ -170,6 +170,23 @@ export declare class FeatureFlagModel {
      * ```
      */
     delete(id: number): Promise<boolean>;
+    /**
+     * Adds an external subject identifier to a feature flag.
+     */
+    addSubject(featureFlagId: number, subject: string): Promise<boolean>;
+    /**
+     * Removes an external subject identifier from a feature flag.
+     */
+    removeSubject(featureFlagId: number, subject: string): Promise<boolean>;
+    /**
+     * Gets all external subject identifiers associated with a feature flag.
+     */
+    getSubjects(featureFlagId: number): Promise<string[]>;
+    /**
+     * Gets all feature flags directly associated with an external subject identifier.
+     */
+    getFeatureFlagsForSubject(subject: string): Promise<FeatureFlag[]>;
+    private getSubjectMatchedFlagIds;
     /**
      * Checks if a user belongs to any of the specified groups
      */
@@ -178,10 +195,12 @@ export declare class FeatureFlagModel {
      * Evaluates a feature flag for a user based on flag configuration.
      * This is a stateless helper that performs the actual flag evaluation logic.
      */
-    evaluateFlagForUser(flag: FeatureFlag, { user, roles, groups, }: {
+    evaluateFlagForUser(flag: FeatureFlag, { user, roles, groups, subjects, subjectMatchedFlagIds, }: {
         user?: string;
         roles?: string[];
         groups?: string[];
+        subjects?: string[];
+        subjectMatchedFlagIds?: Set<number>;
     }): Promise<boolean>;
     /**
      * Computes the hash value for a user ID using MurmurHash3.
@@ -245,6 +264,16 @@ export declare class FeatureFlagModel {
         roles?: string[];
         groups?: string[];
     }): Promise<boolean>;
+    /**
+     * Checks if a feature flag is active for a context, including optional external subjects.
+     */
+    isActiveForContext({ name, user, roles, groups, subjects, }: {
+        name: string;
+        user?: string;
+        roles?: string[];
+        groups?: string[];
+        subjects?: string[];
+    }): Promise<boolean>;
     /**
      * Checks if multiple feature flags are active for a user based on configured rules.
      *
@@ -298,6 +327,32 @@ export declare class FeatureFlagModel {
         roles?: string[];
         groups?: string[];
     }): Promise<Record<string, boolean>>;
+    /**
+     * Checks if multiple feature flags are active for a context, including optional external subjects.
+     */
+    areActiveForContext({ names, user, roles, groups, subjects, }: {
+        names?: string[];
+        user?: string;
+        roles?: string[];
+        groups?: string[];
+        subjects?: string[];
+    }): Promise<Record<string, boolean>>;
+    /**
+     * Gets the latest modified timestamp across all feature flags.
+     *
+     * @returns The latest modified timestamp in milliseconds since epoch, or -1 if the table is empty
+     *
+     * @example
+     * ```typescript
+     * const lastModified = await model.getLastModified();
+     * if (lastModified === -1) {
+     *   console.log("No feature flags exist");
+     * } else {
+     *   console.log(`Last modified: ${new Date(lastModified)}`);
+     * }
+     * ```
+     */
+    getLastModified(): Promise<number>;
 }
 type CreateGroupInput = Omit<FeatureFlagGroup, "id" | "created" | "modified">;
 type UpdateGroupChanges = Partial<Omit<FeatureFlagGroup, "id" | "created" | "modified">>;
@@ -470,6 +525,22 @@ export declare class FeatureFlagGroupModel {
      * ```
      */
     getGroupsForFeatureFlag(featureFlagId: number): Promise<FeatureFlagGroup[]>;
+    /**
+     * Adds an external subject identifier to a feature flag group.
+     */
+    addSubject(groupId: number, subject: string): Promise<boolean>;
+    /**
+     * Removes an external subject identifier from a feature flag group.
+     */
+    removeSubject(groupId: number, subject: string): Promise<boolean>;
+    /**
+     * Gets all external subject identifiers associated with a feature flag group.
+     */
+    getSubjects(groupId: number): Promise<string[]>;
+    /**
+     * Gets all groups that are associated with a specific external subject identifier.
+     */
+    getGroupsForSubject(subject: string): Promise<FeatureFlagGroup[]>;
     /**
      * Updates all feature flags in a group with the same changes.
      *

package/dist/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,wBAAwB,EACxB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,IAAI,CAAC;AAItC,UAAU,SAAS;IACjB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;CAC/D;AAoBD,KAAK,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,SAAS,GAAG,UAAU,CAAC,CAAC;AACpE,KAAK,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC;AA0B/E;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,EAAE,CAAY;IACtB,OAAO,CAAC,aAAa,CAAC,CAA2B;IAEjD;;;;;;;;;;;OAWG;gBACS,EAAE,EAAE,SAAS,EAAE,aAAa,CAAC,EAAE,wBAAwB;IAKnE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAuCtD;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAOtD;;;;;;;;;;;;;OAaG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAO1D;;;;;;;;;;;OAWG;IACG,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAO5D;;;;;;;;;;;OAWG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAQpD;;;;;;;;;;;;;OAaG;IACG,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAMpC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,MAAM,CACV,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAiD9B;;;;;;;;;;;;;OAaG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK1C;;OAEG;IACG,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAa1E;;OAEG;IACG,aAAa,CACjB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC;IAMnB;;OAEG;IACG,WAAW,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAM3D;;OAEG;IACG,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;YAY1D,wBAAwB;IAqBtC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;;OAGG;IACG,mBAAmB,CACvB,IAAI,EAAE,WAAW,EACjB,EACE,IAAI,EACJ,KAAK,EACL,MAAM,EACN,QAAQ,EACR,qBAAqB,GACtB,EAAE;QACD,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;QACpB,qBAAqB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;KACrC,GACA,OAAO,CAAC,OAAO,CAAC;IAsDnB;;;;;;;;;;;;;;;;;;OAkBG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACG,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;IASpB;;OAEG;IACG,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;IA+BpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8CG;IACG,gBAAgB,CAAC,EACrB,KAAK,EACL,IAAI,EACJ,KAAK,EACL,MAAM,GACP,EAAE;QACD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;KACnB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IASpC;;OAEG;IACG,mBAAmB,CAAC,EACxB,KAAK,EACL,IAAI,EACJ,KAAK,EACL,MAAM,EACN,QAAQ,GACT,EAAE;QACD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,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,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAmDpC;;;;;;;;;;;;;;OAcG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;CAMzC;AAOD,KAAK,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,EAAE,IAAI,GAAG,SAAS,GAAG,UAAU,CAAC,CAAC;AAC9E,KAAK,kBAAkB,GAAG,OAAO,CAC/B,IAAI,CAAC,gBAAgB,EAAE,IAAI,GAAG,SAAS,GAAG,UAAU,CAAC,CACtD,CAAC;AACF,KAAK,gBAAgB,GAAG,OAAO,CAC7B,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC,CACzE,CAAC;AAYF;;;;;;;;;;;GAWG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,EAAE,CAAY;IAEtB;;;;;;;;;;OAUG;gBACS,EAAE,EAAE,SAAS;IAIzB;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAiBhE;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAM3D;;;;;;;;;;OAUG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAM/D;;;;;;;;;;;;OAYG;IACG,IAAI,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAMzC;;;;;;;;;;;;;OAaG;IACG,MAAM,CACV,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IA2BnC;;;;;;;;;;OAUG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ1C;;;;;;;;;;;;;OAaG;IACG,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,OAAO,CAAC;IAenB;;;;;;;;;;;OAWG;IACG,iBAAiB,CACrB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,OAAO,CAAC;IAOnB;;;;;;;;;;;;;OAaG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAY9D;;;;;;;;;;OAUG;IACG,uBAAuB,CAC3B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAY9B;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAcpE;;OAEG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOvE;;OAEG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAQrD;;OAEG;IACG,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAYvE;;;;;;;;;;;;;;;;;;OAkBG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;CA2C7E"}

package/dist/model.js

@@ -1,5 +1,7 @@
 import MurmurHash3 from "imurmurhash";
 const TABLE = "flapjack.feature_flag";
+const SUBJECT_TABLE = "flapjack.feature_flag_subject";
+const GROUP_SUBJECT_TABLE = "flapjack.feature_flag_group_subject";
 const COLUMNS = [
     "id",
     "name",
@@ -311,6 +313,69 @@ export class FeatureFlagModel {
         const res = await this.db.query(`DELETE FROM ${TABLE} WHERE id = $1`, [id]);
         return res.rowCount > 0;
     }
+    /**
+     * Adds an external subject identifier to a feature flag.
+     */
+    async addSubject(featureFlagId, subject) {
+        try {
+            const sql = `INSERT INTO ${SUBJECT_TABLE} (feature_flag_id, subject) VALUES ($1, $2)`;
+            await this.db.query(sql, [featureFlagId, subject]);
+            return true;
+        }
+        catch (err) {
+            if (err.code === "23505") {
+                return false;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Removes an external subject identifier from a feature flag.
+     */
+    async removeSubject(featureFlagId, subject) {
+        const sql = `DELETE FROM ${SUBJECT_TABLE} WHERE feature_flag_id = $1 AND subject = $2`;
+        const res = await this.db.query(sql, [featureFlagId, subject]);
+        return res.rowCount > 0;
+    }
+    /**
+     * Gets all external subject identifiers associated with a feature flag.
+     */
+    async getSubjects(featureFlagId) {
+        const sql = `SELECT subject FROM ${SUBJECT_TABLE} WHERE feature_flag_id = $1 ORDER BY created DESC`;
+        const res = await this.db.query(sql, [featureFlagId]);
+        return res.rows.map((row) => row.subject);
+    }
+    /**
+     * Gets all feature flags directly associated with an external subject identifier.
+     */
+    async getFeatureFlagsForSubject(subject) {
+        const sql = `
+      SELECT ${COLUMNS.map((c) => `f.${c}`).join(", ")}
+      FROM ${TABLE} f
+      INNER JOIN ${SUBJECT_TABLE} s ON f.id = s.feature_flag_id
+      WHERE s.subject = $1
+      ORDER BY f.created DESC
+    `;
+        const res = await this.db.query(sql, [subject]);
+        return res.rows.map(mapRow);
+    }
+    async getSubjectMatchedFlagIds(subjects = []) {
+        if (subjects.length === 0) {
+            return new Set();
+        }
+        const sql = `
+      SELECT s.feature_flag_id AS feature_flag_id
+      FROM ${SUBJECT_TABLE} s
+      WHERE s.subject = ANY($1)
+      UNION
+      SELECT gm.feature_flag_id AS feature_flag_id
+      FROM ${GROUP_SUBJECT_TABLE} gs
+      INNER JOIN ${GROUP_MEMBER_TABLE} gm ON gs.feature_flag_group_id = gm.group_id
+      WHERE gs.subject = ANY($1)
+    `;
+        const res = await this.db.query(sql, [subjects]);
+        return new Set(res.rows.map((row) => Number(row.feature_flag_id)));
+    }
     /**
      * Checks if a user belongs to any of the specified groups
      */
@@ -323,7 +388,7 @@ export class FeatureFlagModel {
      * Evaluates a feature flag for a user based on flag configuration.
      * This is a stateless helper that performs the actual flag evaluation logic.
      */
-    async evaluateFlagForUser(flag, { user, roles, groups, }) {
+    async evaluateFlagForUser(flag, { user, roles, groups, subjects, subjectMatchedFlagIds, }) {
         // Everyone Override: If everyone is true or false, return that value immediately
         if (flag.everyone !== undefined && flag.everyone !== null) {
             return flag.everyone;
@@ -332,6 +397,20 @@ export class FeatureFlagModel {
         if (user && flag.users && flag.users.includes(user)) {
             return true;
         }
+        // Subject Check: If any external subject maps to this flag directly or via group, return true
+        if (subjects && subjects.length > 0) {
+            let isSubjectMatched = false;
+            if (subjectMatchedFlagIds) {
+                isSubjectMatched = subjectMatchedFlagIds.has(flag.id);
+            }
+            else {
+                const matchedFlagIds = await this.getSubjectMatchedFlagIds(subjects);
+                isSubjectMatched = matchedFlagIds.has(flag.id);
+            }
+            if (isSubjectMatched) {
+                return true;
+            }
+        }
         // Group Check: If any of the user's groups match any group in the groups array, return true
         if (groups && this.isActiveForGroups(groups, flag.groups)) {
             return true;
@@ -414,6 +493,17 @@ export class FeatureFlagModel {
      * ```
      */
     async isActiveForUser({ name, user, roles, groups, }) {
+        return this.isActiveForContext({
+            name,
+            user,
+            roles,
+            groups,
+        });
+    }
+    /**
+     * Checks if a feature flag is active for a context, including optional external subjects.
+     */
+    async isActiveForContext({ name, user, roles, groups, subjects, }) {
         const flag = await this.getByName(name);
         // No such flag
         if (!flag) {
@@ -429,7 +519,14 @@ export class FeatureFlagModel {
                 return expiredResult;
             }
         }
-        return this.evaluateFlagForUser(flag, { user, roles, groups });
+        const subjectMatchedFlagIds = await this.getSubjectMatchedFlagIds(subjects);
+        return this.evaluateFlagForUser(flag, {
+            user,
+            roles,
+            groups,
+            subjects,
+            subjectMatchedFlagIds,
+        });
     }
     /**
      * Checks if multiple feature flags are active for a user based on configured rules.
@@ -479,6 +576,17 @@ export class FeatureFlagModel {
      * ```
      */
     async areActiveForUser({ names, user, roles, groups, }) {
+        return this.areActiveForContext({
+            names,
+            user,
+            roles,
+            groups,
+        });
+    }
+    /**
+     * Checks if multiple feature flags are active for a context, including optional external subjects.
+     */
+    async areActiveForContext({ names, user, roles, groups, subjects, }) {
         let flags;
         let requestedNames;
         if (names === undefined) {
@@ -493,6 +601,7 @@ export class FeatureFlagModel {
         }
         const flagMap = new Map(flags.map((flag) => [flag.name, flag]));
         const result = {};
+        const subjectMatchedFlagIds = await this.getSubjectMatchedFlagIds(subjects);
         for (const name of requestedNames) {
             const flag = flagMap.get(name);
             if (!flag) {
@@ -513,10 +622,33 @@ export class FeatureFlagModel {
                 user,
                 roles,
                 groups,
+                subjects,
+                subjectMatchedFlagIds,
             });
         }
         return result;
     }
+    /**
+     * Gets the latest modified timestamp across all feature flags.
+     *
+     * @returns The latest modified timestamp in milliseconds since epoch, or -1 if the table is empty
+     *
+     * @example
+     * ```typescript
+     * const lastModified = await model.getLastModified();
+     * if (lastModified === -1) {
+     *   console.log("No feature flags exist");
+     * } else {
+     *   console.log(`Last modified: ${new Date(lastModified)}`);
+     * }
+     * ```
+     */
+    async getLastModified() {
+        const sql = `SELECT MAX(modified) as max_modified FROM ${TABLE}`;
+        const res = await this.db.query(sql);
+        const maxModified = res.rows[0]?.max_modified;
+        return maxModified ? new Date(maxModified).getTime() : -1;
+    }
 }
 const GROUP_TABLE = "flapjack.feature_flag_group";
 const GROUP_MEMBER_TABLE = "flapjack.feature_flag_group_member";
@@ -789,6 +921,56 @@ export class FeatureFlagGroupModel {
         const res = await this.db.query(sql, [featureFlagId]);
         return res.rows.map(mapGroupRow);
     }
+    /**
+     * Adds an external subject identifier to a feature flag group.
+     */
+    async addSubject(groupId, subject) {
+        try {
+            const sql = `INSERT INTO ${GROUP_SUBJECT_TABLE} (feature_flag_group_id, subject)
+        VALUES ($1, $2)`;
+            await this.db.query(sql, [groupId, subject]);
+            return true;
+        }
+        catch (err) {
+            if (err.code === "23505") {
+                return false;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Removes an external subject identifier from a feature flag group.
+     */
+    async removeSubject(groupId, subject) {
+        const sql = `DELETE FROM ${GROUP_SUBJECT_TABLE}
+      WHERE feature_flag_group_id = $1 AND subject = $2`;
+        const res = await this.db.query(sql, [groupId, subject]);
+        return res.rowCount > 0;
+    }
+    /**
+     * Gets all external subject identifiers associated with a feature flag group.
+     */
+    async getSubjects(groupId) {
+        const sql = `SELECT subject FROM ${GROUP_SUBJECT_TABLE}
+      WHERE feature_flag_group_id = $1
+      ORDER BY created DESC`;
+        const res = await this.db.query(sql, [groupId]);
+        return res.rows.map((row) => row.subject);
+    }
+    /**
+     * Gets all groups that are associated with a specific external subject identifier.
+     */
+    async getGroupsForSubject(subject) {
+        const sql = `
+      SELECT ${GROUP_COLUMNS.map((c) => `g.${c}`).join(", ")}
+      FROM ${GROUP_TABLE} g
+      INNER JOIN ${GROUP_SUBJECT_TABLE} gs ON g.id = gs.feature_flag_group_id
+      WHERE gs.subject = $1
+      ORDER BY g.created DESC
+    `;
+        const res = await this.db.query(sql, [subject]);
+        return res.rows.map(mapGroupRow);
+    }
     /**
      * Updates all feature flags in a group with the same changes.
      *

package/migrations/1779210257698_add-feature-flag-subjects.js

@@ -0,0 +1,93 @@
+/**
+ * @type {import('node-pg-migrate').ColumnDefinitions | undefined}
+ */
+export const shorthands = undefined;
+
+/**
+ * @param pgm {import('node-pg-migrate').MigrationBuilder}
+ * @param run {() => void | undefined}
+ * @returns {Promise<void> | void}
+ */
+export const up = (pgm) => {
+  pgm.createTable(
+    { schema: "flapjack", name: "feature_flag_subject" },
+    {
+      id: "id",
+      feature_flag_id: {
+        type: "integer",
+        notNull: true,
+        references: { schema: "flapjack", name: "feature_flag" },
+        onDelete: "CASCADE",
+      },
+      subject: { type: "text", notNull: true },
+      created: {
+        type: "timestamptz",
+        notNull: true,
+        default: pgm.func("now()"),
+      },
+    },
+  );
+
+  pgm.addConstraint(
+    { schema: "flapjack", name: "feature_flag_subject" },
+    "unique_feature_flag_subject",
+    {
+      unique: ["feature_flag_id", "subject"],
+    },
+  );
+
+  pgm.createIndex(
+    { schema: "flapjack", name: "feature_flag_subject" },
+    "feature_flag_id",
+  );
+  pgm.createIndex(
+    { schema: "flapjack", name: "feature_flag_subject" },
+    "subject",
+  );
+
+  pgm.createTable(
+    { schema: "flapjack", name: "feature_flag_group_subject" },
+    {
+      id: "id",
+      feature_flag_group_id: {
+        type: "integer",
+        notNull: true,
+        references: { schema: "flapjack", name: "feature_flag_group" },
+        onDelete: "CASCADE",
+      },
+      subject: { type: "text", notNull: true },
+      created: {
+        type: "timestamptz",
+        notNull: true,
+        default: pgm.func("now()"),
+      },
+    },
+  );
+
+  pgm.addConstraint(
+    { schema: "flapjack", name: "feature_flag_group_subject" },
+    "unique_feature_flag_group_subject",
+    {
+      unique: ["feature_flag_group_id", "subject"],
+    },
+  );
+
+  pgm.createIndex(
+    { schema: "flapjack", name: "feature_flag_group_subject" },
+    "feature_flag_group_id",
+  );
+  pgm.createIndex(
+    { schema: "flapjack", name: "feature_flag_group_subject" },
+    "subject",
+  );
+};
+
+/**
+ * @param pgm {import('node-pg-migrate').MigrationBuilder}
+ * @param run {() => void | undefined}
+ * @returns {Promise<void> | void}
+ */
+export const down = (pgm) => {
+  pgm.dropTable({ schema: "flapjack", name: "feature_flag_group_subject" });
+  pgm.dropTable({ schema: "flapjack", name: "feature_flag_subject" });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brandtg/flapjack",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "A simple feature flags library with PostgreSQL integration",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,7 +27,7 @@
     "clean": "rm -rf dist",
     "dev": "npx tsc --watch",
     "dev:env": "bash bin/dev/env.sh",
-    "dev:migrate": "npx dotenv-cli -e env -- node-pg-migrate up",
+    "dev:migrate": "npx dotenv-cli -e .env -- node-pg-migrate up -s flapjack --create-schema -t pgmigrations",
     "dev:docker:up": "docker compose -f docker-compose.yml up -d",
     "dev:docker:down": "docker compose -f docker-compose.yml down -v",
     "create-migration": "npx node-pg-migrate create --",