@brandtg/flapjack 0.1.0 → 0.2.0

package/README.md

@@ -140,49 +140,97 @@ await featureFlags.isActiveForUser({
 
 ## Performance Considerations
 
-⚠️ **Important**: Flapjack queries the database on every `isActiveForUser()` call. For high-traffic applications, consider:
+⚠️ **Important**: Without caching, Flapjack queries the database on every `isActiveForUser()` call. For high-traffic applications, use the built-in caching layer:
 
-### Recommended Caching Strategy
+### Built-in Caching Layer
+
+Flapjack includes a high-performance caching layer with TTL support:
 
 ```typescript
 import { Pool } from "pg";
-import { FeatureFlagModel } from "@brandtg/flapjack";
+import {
+  FeatureFlagModel,
+  FeatureFlagCache,
+  InMemoryCache,
+} from "@brandtg/flapjack";
+
+// Set up the database model
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+// Create cached feature flags instance
+const featureFlags = new FeatureFlagCache({
+  model: new FeatureFlagModel(pool),
+  cache: new InMemoryCache<boolean>(),
+  ttl: 300, // Set TTL to 5 minutes (300 seconds)
+});
 
-// Simple in-memory cache with TTL
-class CachedFeatureFlags {
-  private model: FeatureFlagModel;
-  private cache = new Map<string, { flag: any; expires: number }>();
-  private ttlMs = 60000; // 1 minute
+// Use exactly the same as the model, but with automatic caching
+const isActive = await featureFlags.isActiveForUser({
+  name: "new_feature",
+  user: "user_123",
+  roles: ["admin"],
+  groups: ["beta_testers"],
+});
+```
 
-  constructor(pool: Pool) {
-    this.model = new FeatureFlagModel(pool);
+### Cache Key Generation
+
+The cache automatically generates deterministic keys using MurmurHash3 of the flag name and user parameters:
+
+```typescript
+// These calls generate the same cache key:
+await featureFlags.isActiveForUser({
+  name: "test",
+  roles: ["admin", "user"],
+  groups: ["beta", "alpha"],
+});
+
+await featureFlags.isActiveForUser({
+  name: "test",
+  roles: ["user", "admin"], // Different order
+  groups: ["alpha", "beta"], // Different order
+});
+```
+
+### Custom Cache Implementation
+
+You can implement your own cache (Redis, Memcached, etc.) by implementing the `Cache` interface:
+
+```typescript
+import type { Cache } from "@brandtg/flapjack";
+
+class RedisCache implements Cache {
+  private redis: RedisClient;
+
+  constructor(redis: RedisClient) {
+    this.redis = redis;
   }
 
-  async isActiveForUser(params: {
-    name: string;
-    user?: string;
-    roles?: string[];
-    groups?: string[];
-  }): Promise<boolean> {
-    const now = Date.now();
-    const cached = this.cache.get(params.name);
-
-    // Use cached flag if still valid
-    if (cached && cached.expires > now) {
-      // Re-evaluate with cached flag data
-      return this.evaluateLocally(cached.flag, params);
-    }
+  get(key: string): any {
+    const value = this.redis.get(key);
+    return value ? JSON.parse(value) : undefined;
+  }
 
-    // Cache miss or expired - fetch from DB
-    return await this.model.isActiveForUser(params);
+  set(key: string, value: any, ttl?: number): void {
+    const serialized = JSON.stringify(value);
+    if (ttl) {
+      this.redis.setex(key, ttl, serialized);
+    } else {
+      this.redis.set(key, serialized);
+    }
   }
 
-  private evaluateLocally(flag: any, params: any): boolean {
-    // Implement evaluation logic locally to avoid DB queries
-    // See model.ts isActiveForUser() for reference
-    // ...
+  delete(key: string): void {
+    this.redis.del(key);
   }
 }
+
+// Use your custom cache
+const featureFlags = new FeatureFlagCache({
+  model,
+  cache: new RedisCache(redisClient),
+  ttl: 300,
+});
 ```
 
 ### Database Connection Pooling
@@ -432,6 +480,12 @@ flapjack hash-user user_123
 
 ### Setup
 
+Install dependencies
+
+```bash
+npm install
+```
+
 Create an environment file:
 
 ```bash
@@ -453,7 +507,7 @@ npm run dev:migrate
 ### Running Tests
 
 ```bash
-npm test
+npm run test
 ```
 
 ### Database Management

package/dist/cache.d.ts

@@ -0,0 +1,48 @@
+import { FeatureFlagModel } from "./model.js";
+export interface Cache<T> {
+    get(key: string): T | undefined;
+    set(key: string, value: T, ttl?: number): void;
+    delete(key: string): void;
+}
+/**
+ * Simple in-memory cache with TTL support.
+ */
+export declare class InMemoryCache<T> implements Cache<T> {
+    private cache;
+    get(key: string): T | undefined;
+    set(key: string, value: T, ttl?: number): void;
+    delete(key: string): void;
+    /**
+     * Clear all expired entries from the cache.
+     */
+    clearExpired(): void;
+    /**
+     * Get the current size of the cache (including expired entries).
+     */
+    size(): number;
+    /**
+     * Clear all entries from the cache.
+     */
+    clear(): void;
+}
+export declare class FeatureFlagCache {
+    private model;
+    private cache;
+    private ttl;
+    constructor({ model, cache, ttl, }: {
+        model: FeatureFlagModel;
+        cache: Cache<boolean>;
+        ttl?: number;
+    });
+    /**
+     * Generates a cache key using murmur3 hash of the flag name and parameters.
+     */
+    private generateCacheKey;
+    isActiveForUser({ name, user, roles, groups, }: {
+        name: string;
+        user?: string;
+        roles?: string[];
+        groups?: string[];
+    }): Promise<boolean>;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9C,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAChC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AASD;;GAEG;AACH,qBAAa,aAAa,CAAC,CAAC,CAAE,YAAW,KAAK,CAAC,CAAC,CAAC;IAC/C,OAAO,CAAC,KAAK,CAAoC;IAEjD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAgB/B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAK9C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB;;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"}

package/dist/cache.js

@@ -0,0 +1,96 @@
+import MurmurHash3 from "imurmurhash";
+const DEFAULT_TTL = 60 * 5; // 5 minutes
+/**
+ * Simple in-memory cache with TTL support.
+ */
+export class InMemoryCache {
+    cache = new Map();
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return undefined;
+        }
+        const now = Date.now();
+        if (entry.expiresAt !== undefined && now >= entry.expiresAt) {
+            // Entry has expired, remove it
+            this.cache.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, ttl) {
+        const expiresAt = ttl !== undefined ? Date.now() + ttl * 1000 : undefined;
+        this.cache.set(key, { value, expiresAt });
+    }
+    delete(key) {
+        this.cache.delete(key);
+    }
+    /**
+     * Clear all expired entries from the cache.
+     */
+    clearExpired() {
+        const now = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.expiresAt !== undefined && now >= entry.expiresAt) {
+                this.cache.delete(key);
+            }
+        }
+    }
+    /**
+     * Get the current size of the cache (including expired entries).
+     */
+    size() {
+        return this.cache.size;
+    }
+    /**
+     * Clear all entries from the cache.
+     */
+    clear() {
+        this.cache.clear();
+    }
+}
+export class FeatureFlagCache {
+    model;
+    cache;
+    ttl;
+    constructor({ model, cache, ttl = DEFAULT_TTL, }) {
+        this.model = model;
+        this.cache = cache;
+        this.ttl = ttl;
+    }
+    /**
+     * Generates a cache key using murmur3 hash of the flag name and parameters.
+     */
+    generateCacheKey({ name, user, roles, groups, }) {
+        // Create a consistent string representation of the parameters
+        const keyParts = [
+            name,
+            user || "",
+            (roles || []).sort().join(","),
+            (groups || []).sort().join(","),
+        ];
+        const keyString = keyParts.join("|");
+        // Generate murmur3 hash
+        const hash = MurmurHash3(keyString).result();
+        return `flag:${hash}`;
+    }
+    async isActiveForUser({ name, user, roles, groups, }) {
+        // Generate cache key
+        const cacheKey = this.generateCacheKey({ name, user, roles, groups });
+        // Try to get from cache first
+        const cachedResult = this.cache.get(cacheKey);
+        if (cachedResult !== undefined) {
+            return cachedResult;
+        }
+        // Cache miss, get from model
+        const result = await this.model.isActiveForUser({
+            name,
+            user,
+            roles,
+            groups,
+        });
+        // Store in cache with TTL
+        this.cache.set(cacheKey, result, this.ttl);
+        return result;
+    }
+}

package/dist/cli.js

@@ -4,7 +4,7 @@ import { hideBin } from "yargs/helpers";
 import { Pool } from "pg";
 import { FeatureFlagModel } from "./model.js";
 import dotenv from "dotenv";
-dotenv.config();
+dotenv.config({ quiet: true });
 function createDatabase() {
     const connectionString = process.env.DATABASE_URL;
     if (!connectionString) {
@@ -51,6 +51,10 @@ const flagOptions = {
         type: "string",
         describe: "Description of where this flag is used and what it does",
     },
+    expires: {
+        type: "string",
+        describe: "Expiration date (ISO 8601 format)",
+    },
 };
 // Create command
 cli.command("create", "Create a new feature flag", (yargs) => {
@@ -76,6 +80,8 @@ cli.command("create", "Create a new feature flag", (yargs) => {
             input.users = argv.users;
         if (argv.note !== undefined)
             input.note = argv.note;
+        if (argv.expires !== undefined)
+            input.expires = new Date(argv.expires);
         const flag = await model.create(input);
         console.log(JSON.stringify(flag, null, 2));
     }
@@ -190,6 +196,10 @@ cli.command("update <id>", "Update a feature flag", (yargs) => {
             type: "boolean",
             describe: "Clear the note",
         },
+        "clear-expires": {
+            type: "boolean",
+            describe: "Clear the expiration date",
+        },
     });
 }, async (argv) => {
     const db = createDatabase();
@@ -228,6 +238,11 @@ cli.command("update <id>", "Update a feature flag", (yargs) => {
             changes.note = null;
         else if (argv.note !== undefined)
             changes.note = argv.note;
+        // Expires: clear flag takes precedence
+        if (argv.clearExpires)
+            changes.expires = null;
+        else if (argv.expires !== undefined)
+            changes.expires = new Date(argv.expires);
         const flag = await model.update(argv.id, changes);
         if (flag) {
             console.log(JSON.stringify(flag, null, 2));

package/dist/index.d.ts

@@ -1,4 +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,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,2 +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 } 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>;
@@ -19,10 +19,12 @@ type UpdateChanges = Partial<Omit<FeatureFlag, "id" | "created" | "modified">>;
  */
 export declare class FeatureFlagModel {
     private db;
+    private eventHandlers?;
     /**
      * Creates a new FeatureFlagModel instance.
      *
      * @param db - A PostgreSQL Pool or Client instance that implements the Queryable interface
+     * @param eventHandlers - Optional event handlers for feature flag events
      *
      * @example
      * ```typescript
@@ -30,7 +32,7 @@ export declare class FeatureFlagModel {
      * const model = new FeatureFlagModel(pool);
      * ```
      */
-    constructor(db: Queryable);
+    constructor(db: Queryable, eventHandlers?: FeatureFlagEventHandlers);
     /**
      * Creates a new feature flag in the database.
      *
@@ -42,6 +44,7 @@ export declare class FeatureFlagModel {
      * @param input.groups - Optional list of user groups that have this flag enabled
      * @param input.users - Optional list of specific user IDs that have this flag enabled
      * @param input.note - Optional description of the flag's purpose
+     * @param input.expires - Optional expiration date for the feature flag
      * @returns The created feature flag with generated id, created, and modified timestamps
      *
      * @throws Will throw an error if a flag with the same name already exists
@@ -86,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.
      *
@@ -208,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,MAAM,YAAY,CAAC;AAC9C,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;AAiBD,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;AAyB/E;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,EAAE,CAAY;IAEtB;;;;;;;;;;OAUG;gBACS,EAAE,EAAE,SAAS;IAIzB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAmCtD;;;;;;;;;;;;;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;IA6C9B;;;;;;;;;;;;;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;CA4CrB"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"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"}

package/dist/model.js

@@ -11,6 +11,7 @@ const COLUMNS = [
     "note",
     "created",
     "modified",
+    "expires",
 ];
 function mapRow(row) {
     return {
@@ -28,6 +29,7 @@ function mapRow(row) {
         note: row.note ?? undefined,
         created: new Date(row.created),
         modified: new Date(row.modified),
+        expires: row.expires ? new Date(row.expires) : undefined,
     };
 }
 /**
@@ -44,10 +46,12 @@ function mapRow(row) {
  */
 export class FeatureFlagModel {
     db;
+    eventHandlers;
     /**
      * Creates a new FeatureFlagModel instance.
      *
      * @param db - A PostgreSQL Pool or Client instance that implements the Queryable interface
+     * @param eventHandlers - Optional event handlers for feature flag events
      *
      * @example
      * ```typescript
@@ -55,8 +59,9 @@ export class FeatureFlagModel {
      * const model = new FeatureFlagModel(pool);
      * ```
      */
-    constructor(db) {
+    constructor(db, eventHandlers) {
         this.db = db;
+        this.eventHandlers = eventHandlers;
     }
     /**
      * Creates a new feature flag in the database.
@@ -69,6 +74,7 @@ export class FeatureFlagModel {
      * @param input.groups - Optional list of user groups that have this flag enabled
      * @param input.users - Optional list of specific user IDs that have this flag enabled
      * @param input.note - Optional description of the flag's purpose
+     * @param input.expires - Optional expiration date for the feature flag
      * @returns The created feature flag with generated id, created, and modified timestamps
      *
      * @throws Will throw an error if a flag with the same name already exists
@@ -109,6 +115,10 @@ export class FeatureFlagModel {
             cols.push("note");
             vals.push(input.note ?? null);
         }
+        if ("expires" in input) {
+            cols.push("expires");
+            vals.push(input.expires ?? null);
+        }
         const placeholders = cols.map((_, i) => `$${i + 1}`).join(", ");
         const sql = `INSERT INTO ${TABLE} (${cols.join(", ")}) VALUES (${placeholders}) RETURNING ${COLUMNS.join(", ")}`;
         const res = await this.db.query(sql, vals);
@@ -156,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.
      *
@@ -230,6 +259,10 @@ export class FeatureFlagModel {
             sets.push(`note = $${sets.length + 1}`);
             vals.push(changes.note ?? null);
         }
+        if ("expires" in changes) {
+            sets.push(`expires = $${sets.length + 1}`);
+            vals.push(changes.expires ?? null);
+        }
         if (sets.length === 0) {
             return this.getById(id);
         }
@@ -331,6 +364,16 @@ export class FeatureFlagModel {
         if (!flag) {
             return false;
         }
+        // If the flag has expired, trigger event and return false
+        if (this.eventHandlers?.onExpired &&
+            flag &&
+            flag.expires &&
+            flag.expires <= new Date()) {
+            const expiredResult = await this.eventHandlers.onExpired({ flag });
+            if (expiredResult !== undefined) {
+                return expiredResult;
+            }
+        }
         // Everyone Override: If everyone is true or false, return that value immediately
         if (flag.everyone !== undefined && flag.everyone !== null) {
             return flag.everyone;
@@ -363,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

@@ -22,5 +22,39 @@ export type FeatureFlag = {
     created: Date;
     /** Date when the feature flag was last modified */
     modified: Date;
+    /** Optional expiration date for the feature flag */
+    expires?: Date;
+};
+/**
+ * Called when a feature flag which has expired is used.
+ *
+ * If the handler returns `true` or `false`, that value will be used as the result of the feature
+ * flag check. If it returns `undefined` the behavior will be the same as if the flag has not
+ * expired. This can be used to implement a grace period for expired flags, or to emit metrics to
+ * alert that an expired flag is still in use.
+ */
+export type ExpiredFeatureFlagEventHandler = ({ flag, }: {
+    flag: FeatureFlag;
+}) => Promise<boolean | undefined>;
+/**
+ * Event handlers for feature flag events.
+ */
+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;CAChB,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/1760502793520_add-feature-flag-expires.js

@@ -0,0 +1,24 @@
+/**
+ * @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.addColumn("flapjack_feature_flag", {
+    expires: { type: "timestamptz" },
+  });
+};
+
+/**
+ * @param pgm {import('node-pg-migrate').MigrationBuilder}
+ * @param run {() => void | undefined}
+ * @returns {Promise<void> | void}
+ */
+export const down = (pgm) => {
+  pgm.dropColumn("flapjack_feature_flag", "expires");
+};

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.0",
+  "version": "0.2.0",
   "description": "A simple feature flags library with PostgreSQL integration",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,7 +40,7 @@
     "smoke": "npm run build && node dist/cli.js --help && node dist/cli.js hash-user smoke"
   },
   "dependencies": {
-    "dotenv": "^16.4.5",
+    "dotenv": "^17.2.3",
     "imurmurhash": "^0.1.4",
     "node-pg-migrate": "^8.0.3",
     "pg": "^8.12.0",