@brandtg/flapjack 0.1.2 → 0.2.0

package/README.md

@@ -480,6 +480,12 @@ flapjack hash-user user_123
 
 ### Setup
 
+Install dependencies
+
+```bash
+npm install
+```
+
 Create an environment file:
 
 ```bash
@@ -501,7 +507,7 @@ npm run dev:migrate
 ### Running Tests
 
 ```bash
-npm test
+npm run test
 ```
 
 ### Database Management

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export type { FeatureFlag } from "./types.js";
-export { FeatureFlagModel } from "./model.js";
+export type { FeatureFlag, FeatureFlagGroup } from "./types.js";
+export { FeatureFlagModel, FeatureFlagGroupModel } from "./model.js";
 export { FeatureFlagCache, InMemoryCache, type Cache } from "./cache.js";
 export { runMigrations, type MigrationOptions } from "./migrate.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,3 +1,3 @@
-export { FeatureFlagModel } from "./model.js";
+export { FeatureFlagModel, FeatureFlagGroupModel } from "./model.js";
 export { FeatureFlagCache, InMemoryCache } from "./cache.js";
 export { runMigrations } from "./migrate.js";

package/dist/model.d.ts

@@ -1,4 +1,4 @@
-import type { FeatureFlag, FeatureFlagEventHandlers } from "./types.js";
+import type { FeatureFlag, FeatureFlagEventHandlers, FeatureFlagGroup } from "./types.js";
 import type { QueryResult } from "pg";
 interface Queryable {
     query: (text: string, params?: any[]) => Promise<QueryResult>;
@@ -89,6 +89,19 @@ export declare class FeatureFlagModel {
      * ```
      */
     getByName(name: string): Promise<FeatureFlag | null>;
+    /**
+     * Retrieves multiple feature flags by their IDs.
+     *
+     * @param ids - Array of feature flag IDs to retrieve
+     * @returns Array of feature flags found (may be shorter than input if some IDs don't exist)
+     *
+     * @example
+     * ```typescript
+     * const flags = await model.getMany([1, 2, 3]);
+     * console.log(`Found ${flags.length} flags`);
+     * ```
+     */
+    getMany(ids: number[]): Promise<FeatureFlag[]>;
     /**
      * Retrieves all feature flags, ordered by ID.
      *
@@ -211,5 +224,197 @@ export declare class FeatureFlagModel {
         groups?: string[];
     }): Promise<boolean>;
 }
+type CreateGroupInput = Omit<FeatureFlagGroup, "id" | "created" | "modified">;
+type UpdateGroupChanges = Partial<Omit<FeatureFlagGroup, "id" | "created" | "modified">>;
+type UpdateAllChanges = Partial<Pick<FeatureFlag, "everyone" | "percent" | "roles" | "groups" | "users">>;
+/**
+ * Model for managing feature flag groups stored in PostgreSQL.
+ *
+ * @example
+ * ```typescript
+ * import { Pool } from "pg";
+ * import { FeatureFlagGroupModel } from "@brandtg/flapjack";
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const groups = new FeatureFlagGroupModel(pool);
+ * ```
+ */
+export declare class FeatureFlagGroupModel {
+    private db;
+    /**
+     * Creates a new FeatureFlagGroupModel instance.
+     *
+     * @param db - A PostgreSQL Pool or Client instance that implements the Queryable interface
+     *
+     * @example
+     * ```typescript
+     * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+     * const model = new FeatureFlagGroupModel(pool);
+     * ```
+     */
+    constructor(db: Queryable);
+    /**
+     * Creates a new feature flag group in the database.
+     *
+     * @param input - Feature flag group configuration
+     * @param input.name - Unique name for the group (required)
+     * @param input.note - Optional description of the group's purpose
+     * @returns The created group with generated id, created, and modified timestamps
+     *
+     * @throws Will throw an error if a group with the same name already exists
+     *
+     * @example
+     * ```typescript
+     * const group = await model.create({
+     *   name: "billing_redesign",
+     *   note: "All flags related to the new billing flow",
+     * });
+     * ```
+     */
+    create(input: CreateGroupInput): Promise<FeatureFlagGroup>;
+    /**
+     * Retrieves a feature flag group by its ID.
+     *
+     * @param id - The group ID
+     * @returns The group if found, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const group = await model.getById(1);
+     * if (group) {
+     *   console.log(group.name);
+     * }
+     * ```
+     */
+    getById(id: number): Promise<FeatureFlagGroup | null>;
+    /**
+     * Retrieves a feature flag group by its name.
+     *
+     * @param name - The group name
+     * @returns The group if found, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const group = await model.getByName("billing_redesign");
+     * ```
+     */
+    getByName(name: string): Promise<FeatureFlagGroup | null>;
+    /**
+     * Lists all feature flag groups.
+     *
+     * @returns Array of all groups
+     *
+     * @example
+     * ```typescript
+     * const groups = await model.list();
+     * for (const group of groups) {
+     *   console.log(group.name);
+     * }
+     * ```
+     */
+    list(): Promise<FeatureFlagGroup[]>;
+    /**
+     * Updates a feature flag group.
+     *
+     * @param id - The group ID to update
+     * @param changes - Fields to update
+     * @returns The updated group if found, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const updated = await model.update(1, {
+     *   note: "Updated description",
+     * });
+     * ```
+     */
+    update(id: number, changes: UpdateGroupChanges): Promise<FeatureFlagGroup | null>;
+    /**
+     * Deletes a feature flag group and all its member relationships.
+     *
+     * @param id - The group ID to delete
+     * @returns true if deleted, false if not found
+     *
+     * @example
+     * ```typescript
+     * const deleted = await model.delete(1);
+     * ```
+     */
+    delete(id: number): Promise<boolean>;
+    /**
+     * Adds a feature flag to a group.
+     *
+     * @param groupId - The group ID
+     * @param featureFlagId - The feature flag ID to add
+     * @returns true if added successfully, false if already exists
+     *
+     * @throws Will throw an error if group or feature flag doesn't exist
+     *
+     * @example
+     * ```typescript
+     * await model.addFeatureFlag(1, 5);
+     * ```
+     */
+    addFeatureFlag(groupId: number, featureFlagId: number): Promise<boolean>;
+    /**
+     * Removes a feature flag from a group.
+     *
+     * @param groupId - The group ID
+     * @param featureFlagId - The feature flag ID to remove
+     * @returns true if removed, false if relationship didn't exist
+     *
+     * @example
+     * ```typescript
+     * await model.removeFeatureFlag(1, 5);
+     * ```
+     */
+    removeFeatureFlag(groupId: number, featureFlagId: number): Promise<boolean>;
+    /**
+     * Gets all feature flags in a group.
+     *
+     * @param groupId - The group ID
+     * @returns Array of feature flags in the group
+     *
+     * @example
+     * ```typescript
+     * const flags = await model.getFeatureFlags(1);
+     * for (const flag of flags) {
+     *   console.log(flag.name);
+     * }
+     * ```
+     */
+    getFeatureFlags(groupId: number): Promise<FeatureFlag[]>;
+    /**
+     * Gets all groups that contain a specific feature flag.
+     *
+     * @param featureFlagId - The feature flag ID
+     * @returns Array of groups containing the feature flag
+     *
+     * @example
+     * ```typescript
+     * const groups = await model.getGroupsForFeatureFlag(5);
+     * ```
+     */
+    getGroupsForFeatureFlag(featureFlagId: number): Promise<FeatureFlagGroup[]>;
+    /**
+     * Updates all feature flags in a group with the same changes.
+     *
+     * @param groupId - The group ID
+     * @param changes - Fields to update (only everyone, percent, roles, groups, users allowed)
+     * @returns The number of feature flags updated
+     *
+     * @example
+     * ```typescript
+     * // Enable all flags in a group for everyone
+     * const count = await model.updateAll(1, { everyone: true });
+     *
+     * // Set percentage rollout for all flags in a group
+     * const count = await model.updateAll(1, { percent: 25 });
+     *
+     * // Add roles to all flags in a group
+     * const count = await model.updateAll(1, { roles: ["admin", "beta"] });
+     * ```
+     */
+    updateAll(groupId: number, changes: UpdateAllChanges): Promise<number>;
+}
 export {};
 //# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACxE,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;AAkBD,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;;;;;;;;;;;;;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;IACH,OAAO,CAAC,iBAAiB;IAQzB;;;;;;;;;;;;;;;;;;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;CAyDrB"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"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"}

package/dist/model.js

@@ -166,6 +166,25 @@ export class FeatureFlagModel {
             return null;
         return mapRow(res.rows[0]);
     }
+    /**
+     * Retrieves multiple feature flags by their IDs.
+     *
+     * @param ids - Array of feature flag IDs to retrieve
+     * @returns Array of feature flags found (may be shorter than input if some IDs don't exist)
+     *
+     * @example
+     * ```typescript
+     * const flags = await model.getMany([1, 2, 3]);
+     * console.log(`Found ${flags.length} flags`);
+     * ```
+     */
+    async getMany(ids) {
+        if (ids.length === 0)
+            return [];
+        const sql = `SELECT ${COLUMNS.join(", ")} FROM ${TABLE} WHERE id = ANY($1)`;
+        const res = await this.db.query(sql, [ids]);
+        return res.rows.map(mapRow);
+    }
     /**
      * Retrieves all feature flags, ordered by ID.
      *
@@ -387,3 +406,334 @@ export class FeatureFlagModel {
         return false;
     }
 }
+const GROUP_TABLE = "flapjack_feature_flag_group";
+const GROUP_MEMBER_TABLE = "flapjack_feature_flag_group_member";
+const GROUP_COLUMNS = ["id", "name", "note", "created", "modified"];
+function mapGroupRow(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        note: row.note ?? undefined,
+        created: new Date(row.created),
+        modified: new Date(row.modified),
+    };
+}
+/**
+ * Model for managing feature flag groups stored in PostgreSQL.
+ *
+ * @example
+ * ```typescript
+ * import { Pool } from "pg";
+ * import { FeatureFlagGroupModel } from "@brandtg/flapjack";
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const groups = new FeatureFlagGroupModel(pool);
+ * ```
+ */
+export class FeatureFlagGroupModel {
+    db;
+    /**
+     * Creates a new FeatureFlagGroupModel instance.
+     *
+     * @param db - A PostgreSQL Pool or Client instance that implements the Queryable interface
+     *
+     * @example
+     * ```typescript
+     * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+     * const model = new FeatureFlagGroupModel(pool);
+     * ```
+     */
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Creates a new feature flag group in the database.
+     *
+     * @param input - Feature flag group configuration
+     * @param input.name - Unique name for the group (required)
+     * @param input.note - Optional description of the group's purpose
+     * @returns The created group with generated id, created, and modified timestamps
+     *
+     * @throws Will throw an error if a group with the same name already exists
+     *
+     * @example
+     * ```typescript
+     * const group = await model.create({
+     *   name: "billing_redesign",
+     *   note: "All flags related to the new billing flow",
+     * });
+     * ```
+     */
+    async create(input) {
+        const cols = ["name"];
+        const vals = [input.name];
+        if ("note" in input) {
+            cols.push("note");
+            vals.push(input.note ?? null);
+        }
+        const placeholders = cols.map((_, i) => `$${i + 1}`).join(", ");
+        const sql = `INSERT INTO ${GROUP_TABLE} (${cols.join(", ")}) 
+      VALUES (${placeholders}) 
+      RETURNING ${GROUP_COLUMNS.join(", ")}`;
+        const res = await this.db.query(sql, vals);
+        return mapGroupRow(res.rows[0]);
+    }
+    /**
+     * Retrieves a feature flag group by its ID.
+     *
+     * @param id - The group ID
+     * @returns The group if found, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const group = await model.getById(1);
+     * if (group) {
+     *   console.log(group.name);
+     * }
+     * ```
+     */
+    async getById(id) {
+        const sql = `SELECT ${GROUP_COLUMNS.join(", ")} FROM ${GROUP_TABLE} WHERE id = $1`;
+        const res = await this.db.query(sql, [id]);
+        return res.rows.length > 0 ? mapGroupRow(res.rows[0]) : null;
+    }
+    /**
+     * Retrieves a feature flag group by its name.
+     *
+     * @param name - The group name
+     * @returns The group if found, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const group = await model.getByName("billing_redesign");
+     * ```
+     */
+    async getByName(name) {
+        const sql = `SELECT ${GROUP_COLUMNS.join(", ")} FROM ${GROUP_TABLE} WHERE name = $1`;
+        const res = await this.db.query(sql, [name]);
+        return res.rows.length > 0 ? mapGroupRow(res.rows[0]) : null;
+    }
+    /**
+     * Lists all feature flag groups.
+     *
+     * @returns Array of all groups
+     *
+     * @example
+     * ```typescript
+     * const groups = await model.list();
+     * for (const group of groups) {
+     *   console.log(group.name);
+     * }
+     * ```
+     */
+    async list() {
+        const sql = `SELECT ${GROUP_COLUMNS.join(", ")} FROM ${GROUP_TABLE} ORDER BY created DESC`;
+        const res = await this.db.query(sql);
+        return res.rows.map(mapGroupRow);
+    }
+    /**
+     * Updates a feature flag group.
+     *
+     * @param id - The group ID to update
+     * @param changes - Fields to update
+     * @returns The updated group if found, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const updated = await model.update(1, {
+     *   note: "Updated description",
+     * });
+     * ```
+     */
+    async update(id, changes) {
+        const updates = [];
+        const vals = [];
+        let paramIdx = 1;
+        if ("name" in changes) {
+            updates.push(`name = $${paramIdx++}`);
+            vals.push(changes.name);
+        }
+        if ("note" in changes) {
+            updates.push(`note = $${paramIdx++}`);
+            vals.push(changes.note ?? null);
+        }
+        if (updates.length === 0) {
+            return this.getById(id);
+        }
+        vals.push(id);
+        const sql = `UPDATE ${GROUP_TABLE} 
+      SET ${updates.join(", ")} 
+      WHERE id = $${paramIdx} 
+      RETURNING ${GROUP_COLUMNS.join(", ")}`;
+        const res = await this.db.query(sql, vals);
+        return res.rows.length > 0 ? mapGroupRow(res.rows[0]) : null;
+    }
+    /**
+     * Deletes a feature flag group and all its member relationships.
+     *
+     * @param id - The group ID to delete
+     * @returns true if deleted, false if not found
+     *
+     * @example
+     * ```typescript
+     * const deleted = await model.delete(1);
+     * ```
+     */
+    async delete(id) {
+        const res = await this.db.query(`DELETE FROM ${GROUP_TABLE} WHERE id = $1`, [id]);
+        return res.rowCount > 0;
+    }
+    /**
+     * Adds a feature flag to a group.
+     *
+     * @param groupId - The group ID
+     * @param featureFlagId - The feature flag ID to add
+     * @returns true if added successfully, false if already exists
+     *
+     * @throws Will throw an error if group or feature flag doesn't exist
+     *
+     * @example
+     * ```typescript
+     * await model.addFeatureFlag(1, 5);
+     * ```
+     */
+    async addFeatureFlag(groupId, featureFlagId) {
+        try {
+            const sql = `INSERT INTO ${GROUP_MEMBER_TABLE} (group_id, feature_flag_id) 
+        VALUES ($1, $2)`;
+            await this.db.query(sql, [groupId, featureFlagId]);
+            return true;
+        }
+        catch (err) {
+            // If unique constraint violation, return false
+            if (err.code === "23505") {
+                return false;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Removes a feature flag from a group.
+     *
+     * @param groupId - The group ID
+     * @param featureFlagId - The feature flag ID to remove
+     * @returns true if removed, false if relationship didn't exist
+     *
+     * @example
+     * ```typescript
+     * await model.removeFeatureFlag(1, 5);
+     * ```
+     */
+    async removeFeatureFlag(groupId, featureFlagId) {
+        const sql = `DELETE FROM ${GROUP_MEMBER_TABLE} 
+      WHERE group_id = $1 AND feature_flag_id = $2`;
+        const res = await this.db.query(sql, [groupId, featureFlagId]);
+        return res.rowCount > 0;
+    }
+    /**
+     * Gets all feature flags in a group.
+     *
+     * @param groupId - The group ID
+     * @returns Array of feature flags in the group
+     *
+     * @example
+     * ```typescript
+     * const flags = await model.getFeatureFlags(1);
+     * for (const flag of flags) {
+     *   console.log(flag.name);
+     * }
+     * ```
+     */
+    async getFeatureFlags(groupId) {
+        const sql = `
+      SELECT ${COLUMNS.map((c) => `f.${c}`).join(", ")}
+      FROM ${TABLE} f
+      INNER JOIN ${GROUP_MEMBER_TABLE} gm ON f.id = gm.feature_flag_id
+      WHERE gm.group_id = $1
+      ORDER BY f.created DESC
+    `;
+        const res = await this.db.query(sql, [groupId]);
+        return res.rows.map(mapRow);
+    }
+    /**
+     * Gets all groups that contain a specific feature flag.
+     *
+     * @param featureFlagId - The feature flag ID
+     * @returns Array of groups containing the feature flag
+     *
+     * @example
+     * ```typescript
+     * const groups = await model.getGroupsForFeatureFlag(5);
+     * ```
+     */
+    async getGroupsForFeatureFlag(featureFlagId) {
+        const sql = `
+      SELECT ${GROUP_COLUMNS.map((c) => `g.${c}`).join(", ")}
+      FROM ${GROUP_TABLE} g
+      INNER JOIN ${GROUP_MEMBER_TABLE} gm ON g.id = gm.group_id
+      WHERE gm.feature_flag_id = $1
+      ORDER BY g.created DESC
+    `;
+        const res = await this.db.query(sql, [featureFlagId]);
+        return res.rows.map(mapGroupRow);
+    }
+    /**
+     * Updates all feature flags in a group with the same changes.
+     *
+     * @param groupId - The group ID
+     * @param changes - Fields to update (only everyone, percent, roles, groups, users allowed)
+     * @returns The number of feature flags updated
+     *
+     * @example
+     * ```typescript
+     * // Enable all flags in a group for everyone
+     * const count = await model.updateAll(1, { everyone: true });
+     *
+     * // Set percentage rollout for all flags in a group
+     * const count = await model.updateAll(1, { percent: 25 });
+     *
+     * // Add roles to all flags in a group
+     * const count = await model.updateAll(1, { roles: ["admin", "beta"] });
+     * ```
+     */
+    async updateAll(groupId, changes) {
+        const updates = [];
+        const vals = [];
+        let paramIdx = 1;
+        if ("everyone" in changes) {
+            updates.push(`everyone = $${paramIdx++}`);
+            vals.push(changes.everyone ?? null);
+        }
+        if ("percent" in changes) {
+            updates.push(`percent = $${paramIdx++}`);
+            vals.push(changes.percent ?? null);
+        }
+        if ("roles" in changes) {
+            updates.push(`roles = $${paramIdx++}`);
+            vals.push(changes.roles ?? null);
+        }
+        if ("groups" in changes) {
+            updates.push(`groups = $${paramIdx++}`);
+            vals.push(changes.groups ?? null);
+        }
+        if ("users" in changes) {
+            updates.push(`users = $${paramIdx++}`);
+            vals.push(changes.users ?? null);
+        }
+        if (updates.length === 0) {
+            return 0;
+        }
+        vals.push(groupId);
+        const sql = `
+      UPDATE ${TABLE} 
+      SET ${updates.join(", ")}
+      WHERE id IN (
+        SELECT feature_flag_id 
+        FROM ${GROUP_MEMBER_TABLE}
+        WHERE group_id = $${paramIdx}
+      )
+    `;
+        const res = await this.db.query(sql, vals);
+        return res.rowCount;
+    }
+}

package/dist/types.d.ts

@@ -42,4 +42,19 @@ export type ExpiredFeatureFlagEventHandler = ({ flag, }: {
 export type FeatureFlagEventHandlers = {
     onExpired?: ExpiredFeatureFlagEventHandler;
 };
+/**
+ * Represents a feature flag group used to manage multiple feature flags together.
+ */
+export type FeatureFlagGroup = {
+    /** Unique identifier for the feature flag group */
+    id: number;
+    /** Human readable name of the feature flag group */
+    name: string;
+    /** Description of what this group is for */
+    note?: string;
+    /** Date when the group was created */
+    created: Date;
+    /** Date when the group was last modified */
+    modified: Date;
+};
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,OAAO,EAAE,IAAI,CAAC;IACd,mDAAmD;IACnD,QAAQ,EAAE,IAAI,CAAC;IACf,oDAAoD;IACpD,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,8BAA8B,GAAG,CAAC,EAC5C,IAAI,GACL,EAAE;IACD,IAAI,EAAE,WAAW,CAAC;CACnB,KAAK,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;AAEnC;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,SAAS,CAAC,EAAE,8BAA8B,CAAC;CAC5C,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,OAAO,EAAE,IAAI,CAAC;IACd,mDAAmD;IACnD,QAAQ,EAAE,IAAI,CAAC;IACf,oDAAoD;IACpD,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,8BAA8B,GAAG,CAAC,EAC5C,IAAI,GACL,EAAE;IACD,IAAI,EAAE,WAAW,CAAC;CACnB,KAAK,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;AAEnC;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,SAAS,CAAC,EAAE,8BAA8B,CAAC;CAC5C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,OAAO,EAAE,IAAI,CAAC;IACd,4CAA4C;IAC5C,QAAQ,EAAE,IAAI,CAAC;CAChB,CAAC"}

package/migrations/1764560643657_add-feature-flag-groups.js

@@ -0,0 +1,77 @@
+/**
+ * @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) => {
+  // Create the flapjack_feature_flag_group table
+  pgm.createTable("flapjack_feature_flag_group", {
+    id: "id",
+    name: { type: "text", notNull: true, unique: true },
+    note: { type: "text" },
+    created: { type: "timestamptz", notNull: true, default: pgm.func("now()") },
+    modified: {
+      type: "timestamptz",
+      notNull: true,
+      default: pgm.func("now()"),
+    },
+  });
+
+  // Create the flapjack_feature_flag_group_member relation table
+  pgm.createTable("flapjack_feature_flag_group_member", {
+    id: "id",
+    group_id: {
+      type: "integer",
+      notNull: true,
+      references: "flapjack_feature_flag_group",
+      onDelete: "CASCADE",
+    },
+    feature_flag_id: {
+      type: "integer",
+      notNull: true,
+      references: "flapjack_feature_flag",
+      onDelete: "CASCADE",
+    },
+    created: { type: "timestamptz", notNull: true, default: pgm.func("now()") },
+  });
+
+  // Add unique constraint on group_id and feature_flag_id
+  pgm.addConstraint(
+    "flapjack_feature_flag_group_member",
+    "unique_group_feature_flag",
+    {
+      unique: ["group_id", "feature_flag_id"],
+    },
+  );
+
+  // Create indexes for efficient lookups
+  pgm.createIndex("flapjack_feature_flag_group_member", "group_id");
+  pgm.createIndex("flapjack_feature_flag_group_member", "feature_flag_id");
+
+  // Attach the modified timestamp trigger to the group table
+  pgm.sql(`
+    CREATE TRIGGER flapjack_feature_flag_group_set_modified
+    BEFORE UPDATE ON flapjack_feature_flag_group
+    FOR EACH ROW
+    EXECUTE FUNCTION flapjack_set_modified_timestamp();
+  `);
+};
+
+/**
+ * @param pgm {import('node-pg-migrate').MigrationBuilder}
+ * @param run {() => void | undefined}
+ * @returns {Promise<void> | void}
+ */
+export const down = (pgm) => {
+  pgm.sql(`
+    DROP TRIGGER IF EXISTS flapjack_feature_flag_group_set_modified 
+    ON flapjack_feature_flag_group;
+  `);
+  pgm.dropTable("flapjack_feature_flag_group_member");
+  pgm.dropTable("flapjack_feature_flag_group");
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brandtg/flapjack",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "A simple feature flags library with PostgreSQL integration",
   "type": "module",
   "main": "./dist/index.js",