@brandtg/flapjack 0.1.0 → 0.1.2

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"],
+});
+```
+
+### 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"],
+});
 
-  constructor(pool: Pool) {
-    this.model = new FeatureFlagModel(pool);
+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

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 { 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,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"}

package/dist/index.js

@@ -1,2 +1,3 @@
 export { FeatureFlagModel } 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 } 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

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":"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"}

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);
@@ -230,6 +240,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 +345,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;

package/dist/types.d.ts

@@ -22,5 +22,24 @@ 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;
 };
 //# 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"}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brandtg/flapjack",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",