@brandtg/flapjack 1.4.0 → 1.5.0

package/README.md

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

package/dist/cli.js

@@ -47,6 +47,10 @@ const flagOptions = {
         type: "array",
         describe: "List of specific user IDs that have this flag enabled",
     },
+    tags: {
+        type: "array",
+        describe: "List of tags for organizing this flag (e.g. release:1.5.0)",
+    },
     note: {
         type: "string",
         describe: "Description of where this flag is used and what it does",
@@ -56,6 +60,14 @@ const flagOptions = {
         describe: "Expiration date (ISO 8601 format)",
     },
 };
+// Option to include archived (hidden) records in read commands
+const includeArchivedOption = {
+    "include-archived": {
+        type: "boolean",
+        default: false,
+        describe: "Include archived (hidden) records in the results",
+    },
+};
 // Create command
 cli.command("create", "Create a new feature flag", (yargs) => {
     return yargs
@@ -78,6 +90,8 @@ cli.command("create", "Create a new feature flag", (yargs) => {
             input.groups = argv.groups;
         if (argv.users !== undefined)
             input.users = argv.users;
+        if (argv.tags !== undefined)
+            input.tags = argv.tags;
         if (argv.note !== undefined)
             input.note = argv.note;
         if (argv.expires !== undefined)
@@ -95,15 +109,19 @@ cli.command("create", "Create a new feature flag", (yargs) => {
 });
 // Get by ID command
 cli.command("get <id>", "Get a feature flag by ID", (yargs) => {
-    return yargs.positional("id", {
+    return yargs
+        .positional("id", {
         type: "number",
         describe: "Feature flag ID",
-    });
+    })
+        .options(includeArchivedOption);
 }, async (argv) => {
     const db = createDatabase();
     const model = new FeatureFlagModel(db);
     try {
-        const flag = await model.getById(argv.id);
+        const flag = await model.getById(argv.id, {
+            includeArchived: argv.includeArchived,
+        });
         if (flag) {
             console.log(JSON.stringify(flag, null, 2));
         }
@@ -122,15 +140,19 @@ cli.command("get <id>", "Get a feature flag by ID", (yargs) => {
 });
 // Get by name command
 cli.command("get-by-name <name>", "Get a feature flag by name", (yargs) => {
-    return yargs.positional("name", {
+    return yargs
+        .positional("name", {
         type: "string",
         describe: "Feature flag name",
-    });
+    })
+        .options(includeArchivedOption);
 }, async (argv) => {
     const db = createDatabase();
     const model = new FeatureFlagModel(db);
     try {
-        const flag = await model.getByName(argv.name);
+        const flag = await model.getByName(argv.name, {
+            includeArchived: argv.includeArchived,
+        });
         if (flag) {
             console.log(JSON.stringify(flag, null, 2));
         }
@@ -148,11 +170,15 @@ cli.command("get-by-name <name>", "Get a feature flag by name", (yargs) => {
     }
 });
 // List command
-cli.command("list", "List all feature flags", () => { }, async () => {
+cli.command("list", "List all feature flags", (yargs) => {
+    return yargs.options(includeArchivedOption);
+}, async (argv) => {
     const db = createDatabase();
     const model = new FeatureFlagModel(db);
     try {
-        const flags = await model.list();
+        const flags = await model.list({
+            includeArchived: argv.includeArchived,
+        });
         console.log(JSON.stringify(flags, null, 2));
     }
     catch (error) {
@@ -163,6 +189,31 @@ cli.command("list", "List all feature flags", () => { }, async () => {
         await db.end();
     }
 });
+// List flags carrying a given tag
+cli.command("list-by-tag <tag>", "List feature flags carrying a given tag (e.g. release:1.5.0)", (yargs) => {
+    return yargs
+        .positional("tag", {
+        type: "string",
+        describe: "Tag to filter by",
+    })
+        .options(includeArchivedOption);
+}, async (argv) => {
+    const db = createDatabase();
+    const model = new FeatureFlagModel(db);
+    try {
+        const flags = await model.listByTag(argv.tag, {
+            includeArchived: argv.includeArchived,
+        });
+        console.log(JSON.stringify(flags, null, 2));
+    }
+    catch (error) {
+        console.error("Error listing feature flags by tag:", error);
+        process.exit(1);
+    }
+    finally {
+        await db.end();
+    }
+});
 // Update command
 cli.command("update <id>", "Update a feature flag", (yargs) => {
     return yargs
@@ -192,6 +243,10 @@ cli.command("update <id>", "Update a feature flag", (yargs) => {
             type: "boolean",
             describe: "Clear users list",
         },
+        "clear-tags": {
+            type: "boolean",
+            describe: "Clear tags list",
+        },
         "clear-note": {
             type: "boolean",
             describe: "Clear the note",
@@ -233,6 +288,11 @@ cli.command("update <id>", "Update a feature flag", (yargs) => {
             changes.users = null;
         else if (argv.users !== undefined)
             changes.users = argv.users;
+        // Tags: clear flag takes precedence
+        if (argv.clearTags)
+            changes.tags = null;
+        else if (argv.tags !== undefined)
+            changes.tags = argv.tags;
         // Note: clear flag takes precedence
         if (argv.clearNote)
             changes.note = null;
@@ -287,6 +347,33 @@ cli.command("delete <id>", "Delete a feature flag", (yargs) => {
         await db.end();
     }
 });
+// Archive command (soft delete; irreversible, hides the flag but keeps history)
+cli.command("archive <id>", "Archive (hide) a feature flag while keeping its history. Irreversible.", (yargs) => {
+    return yargs.positional("id", {
+        type: "number",
+        describe: "Feature flag ID",
+    });
+}, async (argv) => {
+    const db = createDatabase();
+    const model = new FeatureFlagModel(db);
+    try {
+        const flag = await model.archive(argv.id);
+        if (flag) {
+            console.log(JSON.stringify(flag, null, 2));
+        }
+        else {
+            console.log(`Feature flag with ID ${argv.id} not found or already archived`);
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        console.error("Error archiving feature flag:", error);
+        process.exit(1);
+    }
+    finally {
+        await db.end();
+    }
+});
 // Check if active for user command
 cli.command("is-active <name>", "Check if a feature flag is active for a user", (yargs) => {
     return yargs
@@ -626,11 +713,15 @@ cli.command("group-create", "Create a feature flag group", (yargs) => {
     }
 });
 // List feature flag groups command
-cli.command("group-list", "List all feature flag groups", () => { }, async () => {
+cli.command("group-list", "List all feature flag groups", (yargs) => {
+    return yargs.options(includeArchivedOption);
+}, async (argv) => {
     const db = createDatabase();
     const model = new FeatureFlagGroupModel(db);
     try {
-        const groups = await model.list();
+        const groups = await model.list({
+            includeArchived: argv.includeArchived,
+        });
         console.log(JSON.stringify(groups, null, 2));
     }
     catch (error) {
@@ -643,15 +734,19 @@ cli.command("group-list", "List all feature flag groups", () => { }, async () =>
 });
 // Get feature flag group by ID command
 cli.command("group-get <id>", "Get a feature flag group by ID", (yargs) => {
-    return yargs.positional("id", {
+    return yargs
+        .positional("id", {
         type: "number",
         describe: "Feature flag group ID",
-    });
+    })
+        .options(includeArchivedOption);
 }, async (argv) => {
     const db = createDatabase();
     const model = new FeatureFlagGroupModel(db);
     try {
-        const group = await model.getById(argv.id);
+        const group = await model.getById(argv.id, {
+            includeArchived: argv.includeArchived,
+        });
         if (!group) {
             console.log(`Feature flag group with ID ${argv.id} not found`);
             process.exit(1);
@@ -668,15 +763,19 @@ cli.command("group-get <id>", "Get a feature flag group by ID", (yargs) => {
 });
 // Get feature flag group by name command
 cli.command("group-get-by-name <name>", "Get a feature flag group by name", (yargs) => {
-    return yargs.positional("name", {
+    return yargs
+        .positional("name", {
         type: "string",
         describe: "Feature flag group name",
-    });
+    })
+        .options(includeArchivedOption);
 }, async (argv) => {
     const db = createDatabase();
     const model = new FeatureFlagGroupModel(db);
     try {
-        const group = await model.getByName(argv.name);
+        const group = await model.getByName(argv.name, {
+            includeArchived: argv.includeArchived,
+        });
         if (!group) {
             console.log(`Feature flag group with name "${argv.name}" not found`);
             process.exit(1);
@@ -763,6 +862,31 @@ cli.command("group-delete <id>", "Delete a feature flag group", (yargs) => {
         await db.end();
     }
 });
+// Archive a feature flag group (soft delete; irreversible, keeps history)
+cli.command("group-archive <id>", "Archive (hide) a feature flag group while keeping its history. Irreversible.", (yargs) => {
+    return yargs.positional("id", {
+        type: "number",
+        describe: "Feature flag group ID",
+    });
+}, async (argv) => {
+    const db = createDatabase();
+    const model = new FeatureFlagGroupModel(db);
+    try {
+        const group = await model.archive(argv.id);
+        if (!group) {
+            console.log(`Feature flag group with ID ${argv.id} not found or already archived`);
+            process.exit(1);
+        }
+        console.log(JSON.stringify(group, null, 2));
+    }
+    catch (error) {
+        console.error("Error archiving feature flag group:", error);
+        process.exit(1);
+    }
+    finally {
+        await db.end();
+    }
+});
 // Add flag to feature flag group command
 cli.command("group-add-flag <groupId> <flagId>", "Add a feature flag to a group", (yargs) => {
     return yargs

package/dist/model.d.ts

@@ -3,8 +3,8 @@ import type { QueryResult } from "pg";
 interface Queryable {
     query: (text: string, params?: any[]) => Promise<QueryResult>;
 }
-type CreateInput = Omit<FeatureFlag, "id" | "created" | "modified">;
-type UpdateChanges = Partial<Omit<FeatureFlag, "id" | "created" | "modified">>;
+type CreateInput = Omit<FeatureFlag, "id" | "created" | "modified" | "archived">;
+type UpdateChanges = Partial<Omit<FeatureFlag, "id" | "created" | "modified" | "archived">>;
 /**
  * Model for managing feature flags stored in PostgreSQL.
  *
@@ -43,6 +43,7 @@ export declare class FeatureFlagModel {
      * @param input.roles - Optional list of roles that have this flag enabled
      * @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.tags - Optional list of tags for organizing the flag (e.g. a release version)
      * @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
@@ -73,7 +74,9 @@ export declare class FeatureFlagModel {
      * }
      * ```
      */
-    getById(id: number): Promise<FeatureFlag | null>;
+    getById(id: number, { includeArchived }?: {
+        includeArchived?: boolean;
+    }): Promise<FeatureFlag | null>;
     /**
      * Retrieves a feature flag by its name.
      *
@@ -88,7 +91,9 @@ export declare class FeatureFlagModel {
      * }
      * ```
      */
-    getByName(name: string): Promise<FeatureFlag | null>;
+    getByName(name: string, { includeArchived }?: {
+        includeArchived?: boolean;
+    }): Promise<FeatureFlag | null>;
     /**
      * Retrieves multiple feature flags by their names.
      *
@@ -101,7 +106,9 @@ export declare class FeatureFlagModel {
      * console.log(`Found ${flags.length} flags`);
      * ```
      */
-    getManyByName(names: string[]): Promise<FeatureFlag[]>;
+    getManyByName(names: string[], { includeArchived }?: {
+        includeArchived?: boolean;
+    }): Promise<FeatureFlag[]>;
     /**
      * Retrieves multiple feature flags by their IDs.
      *
@@ -114,7 +121,9 @@ export declare class FeatureFlagModel {
      * console.log(`Found ${flags.length} flags`);
      * ```
      */
-    getMany(ids: number[]): Promise<FeatureFlag[]>;
+    getMany(ids: number[], { includeArchived }?: {
+        includeArchived?: boolean;
+    }): Promise<FeatureFlag[]>;
     /**
      * Retrieves all feature flags, ordered by ID.
      *
@@ -129,7 +138,24 @@ export declare class FeatureFlagModel {
      * });
      * ```
      */
-    list(): Promise<FeatureFlag[]>;
+    list({ includeArchived, }?: {
+        includeArchived?: boolean;
+    }): Promise<FeatureFlag[]>;
+    /**
+     * Retrieves all feature flags that carry the given tag.
+     *
+     * @param tag - The tag to filter by (exact match against a tag in the flag's tags array)
+     * @returns Array of feature flags tagged with the given value
+     *
+     * @example
+     * ```typescript
+     * // Find every flag associated with a release version
+     * const flags = await model.listByTag("release:1.5.0");
+     * ```
+     */
+    listByTag(tag: string, { includeArchived }?: {
+        includeArchived?: boolean;
+    }): Promise<FeatureFlag[]>;
     /**
      * Updates an existing feature flag.
      *
@@ -156,11 +182,16 @@ export declare class FeatureFlagModel {
      */
     update(id: number, changes: UpdateChanges): Promise<FeatureFlag | null>;
     /**
-     * Deletes a feature flag from the database.
+     * Permanently deletes a feature flag from the database, including its
+     * subject and group-member relationships (via ON DELETE CASCADE).
      *
      * @param id - The unique identifier of the feature flag to delete
      * @returns true if the flag was deleted, false if not found
      *
+     * @remarks
+     * This is a hard delete that destroys all metadata. To hide a flag while
+     * retaining its history for audit purposes, use {@link archive} instead.
+     *
      * @example
      * ```typescript
      * const deleted = await model.delete(flagId);
@@ -170,6 +201,30 @@ export declare class FeatureFlagModel {
      * ```
      */
     delete(id: number): Promise<boolean>;
+    /**
+     * Archives (hides) a feature flag while keeping the row for historical/audit
+     * purposes. Archived flags are excluded from normal reads and evaluation
+     * (an archived flag evaluates to inactive), but can still be retrieved by
+     * passing `{ includeArchived: true }` to the read methods.
+     *
+     * @param id - The unique identifier of the feature flag to archive
+     * @returns The archived feature flag, or null if it does not exist or is already archived
+     *
+     * @remarks
+     * Archiving is irreversible: there is intentionally no `unarchive` method.
+     * The `archived` timestamp is set once and never changed (a second call is a
+     * no-op that returns null). The flag's name remains reserved permanently, so
+     * a new flag cannot reuse it — create a new flag with a different name.
+     *
+     * @example
+     * ```typescript
+     * const archived = await model.archive(flagId);
+     * if (archived) {
+     *   console.log(`Archived at ${archived.archived}`);
+     * }
+     * ```
+     */
+    archive(id: number): Promise<FeatureFlag | null>;
     /**
      * Adds an external subject identifier to a feature flag.
      */
@@ -185,7 +240,9 @@ export declare class FeatureFlagModel {
     /**
      * Gets all feature flags directly associated with an external subject identifier.
      */
-    getFeatureFlagsForSubject(subject: string): Promise<FeatureFlag[]>;
+    getFeatureFlagsForSubject(subject: string, { includeArchived }?: {
+        includeArchived?: boolean;
+    }): Promise<FeatureFlag[]>;
     private getSubjectMatchedFlagIds;
     /**
      * Checks if a user belongs to any of the specified groups
@@ -354,8 +411,8 @@ export declare class FeatureFlagModel {
      */
     getLastModified(): Promise<number>;
 }
-type CreateGroupInput = Omit<FeatureFlagGroup, "id" | "created" | "modified">;
-type UpdateGroupChanges = Partial<Omit<FeatureFlagGroup, "id" | "created" | "modified">>;
+type CreateGroupInput = Omit<FeatureFlagGroup, "id" | "created" | "modified" | "archived">;
+type UpdateGroupChanges = Partial<Omit<FeatureFlagGroup, "id" | "created" | "modified" | "archived">>;
 type UpdateAllChanges = Partial<Pick<FeatureFlag, "everyone" | "percent" | "roles" | "groups" | "users">>;
 /**
  * Model for managing feature flag groups stored in PostgreSQL.
@@ -416,7 +473,9 @@ export declare class FeatureFlagGroupModel {
      * }
      * ```
      */
-    getById(id: number): Promise<FeatureFlagGroup | null>;
+    getById(id: number, { includeArchived }?: {
+        includeArchived?: boolean;
+    }): Promise<FeatureFlagGroup | null>;
     /**
      * Retrieves a feature flag group by its name.
      *
@@ -428,7 +487,9 @@ export declare class FeatureFlagGroupModel {
      * const group = await model.getByName("billing_redesign");
      * ```
      */
-    getByName(name: string): Promise<FeatureFlagGroup | null>;
+    getByName(name: string, { includeArchived }?: {
+        includeArchived?: boolean;
+    }): Promise<FeatureFlagGroup | null>;
     /**
      * Lists all feature flag groups.
      *
@@ -442,7 +503,9 @@ export declare class FeatureFlagGroupModel {
      * }
      * ```
      */
-    list(): Promise<FeatureFlagGroup[]>;
+    list({ includeArchived, }?: {
+        includeArchived?: boolean;
+    }): Promise<FeatureFlagGroup[]>;
     /**
      * Updates a feature flag group.
      *
@@ -459,17 +522,43 @@ export declare class FeatureFlagGroupModel {
      */
     update(id: number, changes: UpdateGroupChanges): Promise<FeatureFlagGroup | null>;
     /**
-     * Deletes a feature flag group and all its member relationships.
+     * Permanently deletes a feature flag group and all its member and subject
+     * relationships (via ON DELETE CASCADE).
      *
      * @param id - The group ID to delete
      * @returns true if deleted, false if not found
      *
+     * @remarks
+     * This is a hard delete that destroys all metadata. To hide a group while
+     * retaining its history for audit purposes, use {@link archive} instead.
+     *
      * @example
      * ```typescript
      * const deleted = await model.delete(1);
      * ```
      */
     delete(id: number): Promise<boolean>;
+    /**
+     * Archives (hides) a feature flag group while keeping the row for
+     * historical/audit purposes. Archived groups are excluded from normal reads
+     * and no longer contribute subject-based targeting. Member flags are left
+     * untouched and remain active; the membership and subject rows are kept for
+     * audit but become inert.
+     *
+     * @param id - The group ID to archive
+     * @returns The archived group, or null if it does not exist or is already archived
+     *
+     * @remarks
+     * Archiving is irreversible: there is intentionally no `unarchive` method.
+     * The `archived` timestamp is set once and never changed (a second call is a
+     * no-op that returns null). The group's name remains reserved permanently.
+     *
+     * @example
+     * ```typescript
+     * const archived = await model.archive(1);
+     * ```
+     */
+    archive(id: number): Promise<FeatureFlagGroup | null>;
     /**
      * Adds a feature flag to a group.
      *
@@ -512,7 +601,9 @@ export declare class FeatureFlagGroupModel {
      * }
      * ```
      */
-    getFeatureFlags(groupId: number): Promise<FeatureFlag[]>;
+    getFeatureFlags(groupId: number, { includeArchived }?: {
+        includeArchived?: boolean;
+    }): Promise<FeatureFlag[]>;
     /**
      * Gets all groups that contain a specific feature flag.
      *
@@ -524,7 +615,9 @@ export declare class FeatureFlagGroupModel {
      * const groups = await model.getGroupsForFeatureFlag(5);
      * ```
      */
-    getGroupsForFeatureFlag(featureFlagId: number): Promise<FeatureFlagGroup[]>;
+    getGroupsForFeatureFlag(featureFlagId: number, { includeArchived }?: {
+        includeArchived?: boolean;
+    }): Promise<FeatureFlagGroup[]>;
     /**
      * Adds an external subject identifier to a feature flag group.
      */
@@ -540,7 +633,9 @@ export declare class FeatureFlagGroupModel {
     /**
      * Gets all groups that are associated with a specific external subject identifier.
      */
-    getGroupsForSubject(subject: string): Promise<FeatureFlagGroup[]>;
+    getGroupsForSubject(subject: string, { includeArchived }?: {
+        includeArchived?: boolean;
+    }): Promise<FeatureFlagGroup[]>;
     /**
      * Updates all feature flags in a group with the same changes.
      *

package/dist/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"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"}

package/dist/model.js

@@ -10,10 +10,12 @@ const COLUMNS = [
     "roles",
     "groups",
     "users",
+    "tags",
     "note",
     "created",
     "modified",
     "expires",
+    "archived",
 ];
 function mapRow(row) {
     return {
@@ -28,10 +30,12 @@ function mapRow(row) {
             ? row.groups
             : undefined,
         users: row.users && row.users.length > 0 ? row.users : undefined,
+        tags: row.tags && row.tags.length > 0 ? row.tags : undefined,
         note: row.note ?? undefined,
         created: new Date(row.created),
         modified: new Date(row.modified),
         expires: row.expires ? new Date(row.expires) : undefined,
+        archived: row.archived ? new Date(row.archived) : undefined,
     };
 }
 /**
@@ -75,6 +79,7 @@ export class FeatureFlagModel {
      * @param input.roles - Optional list of roles that have this flag enabled
      * @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.tags - Optional list of tags for organizing the flag (e.g. a release version)
      * @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
@@ -113,6 +118,10 @@ export class FeatureFlagModel {
             cols.push("users");
             vals.push(input.users ?? null);
         }
+        if ("tags" in input) {
+            cols.push("tags");
+            vals.push(input.tags ?? null);
+        }
         if ("note" in input) {
             cols.push("note");
             vals.push(input.note ?? null);
@@ -140,8 +149,9 @@ export class FeatureFlagModel {
      * }
      * ```
      */
-    async getById(id) {
-        const sql = `SELECT ${COLUMNS.join(", ")} FROM ${TABLE} WHERE id = $1`;
+    async getById(id, { includeArchived = false } = {}) {
+        const filter = includeArchived ? "" : " AND archived IS NULL";
+        const sql = `SELECT ${COLUMNS.join(", ")} FROM ${TABLE} WHERE id = $1${filter}`;
         const res = await this.db.query(sql, [id]);
         if (res.rows.length === 0)
             return null;
@@ -161,8 +171,9 @@ export class FeatureFlagModel {
      * }
      * ```
      */
-    async getByName(name) {
-        const sql = `SELECT ${COLUMNS.join(", ")} FROM ${TABLE} WHERE name = $1`;
+    async getByName(name, { includeArchived = false } = {}) {
+        const filter = includeArchived ? "" : " AND archived IS NULL";
+        const sql = `SELECT ${COLUMNS.join(", ")} FROM ${TABLE} WHERE name = $1${filter}`;
         const res = await this.db.query(sql, [name]);
         if (res.rows.length === 0)
             return null;
@@ -180,10 +191,11 @@ export class FeatureFlagModel {
      * console.log(`Found ${flags.length} flags`);
      * ```
      */
-    async getManyByName(names) {
+    async getManyByName(names, { includeArchived = false } = {}) {
         if (names.length === 0)
             return [];
-        const sql = `SELECT ${COLUMNS.join(", ")} FROM ${TABLE} WHERE name = ANY($1)`;
+        const filter = includeArchived ? "" : " AND archived IS NULL";
+        const sql = `SELECT ${COLUMNS.join(", ")} FROM ${TABLE} WHERE name = ANY($1)${filter}`;
         const res = await this.db.query(sql, [names]);
         return res.rows.map(mapRow);
     }
@@ -199,10 +211,11 @@ export class FeatureFlagModel {
      * console.log(`Found ${flags.length} flags`);
      * ```
      */
-    async getMany(ids) {
+    async getMany(ids, { includeArchived = false } = {}) {
         if (ids.length === 0)
             return [];
-        const sql = `SELECT ${COLUMNS.join(", ")} FROM ${TABLE} WHERE id = ANY($1)`;
+        const filter = includeArchived ? "" : " AND archived IS NULL";
+        const sql = `SELECT ${COLUMNS.join(", ")} FROM ${TABLE} WHERE id = ANY($1)${filter}`;
         const res = await this.db.query(sql, [ids]);
         return res.rows.map(mapRow);
     }
@@ -220,11 +233,30 @@ export class FeatureFlagModel {
      * });
      * ```
      */
-    async list() {
-        const sql = `SELECT ${COLUMNS.join(", ")} FROM ${TABLE} ORDER BY id`;
+    async list({ includeArchived = false, } = {}) {
+        const filter = includeArchived ? "" : " WHERE archived IS NULL";
+        const sql = `SELECT ${COLUMNS.join(", ")} FROM ${TABLE}${filter} ORDER BY id`;
         const res = await this.db.query(sql);
         return res.rows.map(mapRow);
     }
+    /**
+     * Retrieves all feature flags that carry the given tag.
+     *
+     * @param tag - The tag to filter by (exact match against a tag in the flag's tags array)
+     * @returns Array of feature flags tagged with the given value
+     *
+     * @example
+     * ```typescript
+     * // Find every flag associated with a release version
+     * const flags = await model.listByTag("release:1.5.0");
+     * ```
+     */
+    async listByTag(tag, { includeArchived = false } = {}) {
+        const filter = includeArchived ? "" : " AND archived IS NULL";
+        const sql = `SELECT ${COLUMNS.join(", ")} FROM ${TABLE} WHERE $1 = ANY(tags)${filter} ORDER BY id`;
+        const res = await this.db.query(sql, [tag]);
+        return res.rows.map(mapRow);
+    }
     /**
      * Updates an existing feature flag.
      *
@@ -276,6 +308,10 @@ export class FeatureFlagModel {
             sets.push(`users = $${sets.length + 1}`);
             vals.push(changes.users ?? null);
         }
+        if ("tags" in changes) {
+            sets.push(`tags = $${sets.length + 1}`);
+            vals.push(changes.tags ?? null);
+        }
         if ("note" in changes) {
             sets.push(`note = $${sets.length + 1}`);
             vals.push(changes.note ?? null);
@@ -296,11 +332,16 @@ export class FeatureFlagModel {
         return mapRow(res.rows[0]);
     }
     /**
-     * Deletes a feature flag from the database.
+     * Permanently deletes a feature flag from the database, including its
+     * subject and group-member relationships (via ON DELETE CASCADE).
      *
      * @param id - The unique identifier of the feature flag to delete
      * @returns true if the flag was deleted, false if not found
      *
+     * @remarks
+     * This is a hard delete that destroys all metadata. To hide a flag while
+     * retaining its history for audit purposes, use {@link archive} instead.
+     *
      * @example
      * ```typescript
      * const deleted = await model.delete(flagId);
@@ -313,6 +354,36 @@ export class FeatureFlagModel {
         const res = await this.db.query(`DELETE FROM ${TABLE} WHERE id = $1`, [id]);
         return res.rowCount > 0;
     }
+    /**
+     * Archives (hides) a feature flag while keeping the row for historical/audit
+     * purposes. Archived flags are excluded from normal reads and evaluation
+     * (an archived flag evaluates to inactive), but can still be retrieved by
+     * passing `{ includeArchived: true }` to the read methods.
+     *
+     * @param id - The unique identifier of the feature flag to archive
+     * @returns The archived feature flag, or null if it does not exist or is already archived
+     *
+     * @remarks
+     * Archiving is irreversible: there is intentionally no `unarchive` method.
+     * The `archived` timestamp is set once and never changed (a second call is a
+     * no-op that returns null). The flag's name remains reserved permanently, so
+     * a new flag cannot reuse it — create a new flag with a different name.
+     *
+     * @example
+     * ```typescript
+     * const archived = await model.archive(flagId);
+     * if (archived) {
+     *   console.log(`Archived at ${archived.archived}`);
+     * }
+     * ```
+     */
+    async archive(id) {
+        const sql = `UPDATE ${TABLE} SET archived = now() WHERE id = $1 AND archived IS NULL RETURNING ${COLUMNS.join(", ")}`;
+        const res = await this.db.query(sql, [id]);
+        if (res.rows.length === 0)
+            return null;
+        return mapRow(res.rows[0]);
+    }
     /**
      * Adds an external subject identifier to a feature flag.
      */
@@ -348,12 +419,13 @@ export class FeatureFlagModel {
     /**
      * Gets all feature flags directly associated with an external subject identifier.
      */
-    async getFeatureFlagsForSubject(subject) {
+    async getFeatureFlagsForSubject(subject, { includeArchived = false } = {}) {
+        const filter = includeArchived ? "" : " AND f.archived IS NULL";
         const sql = `
       SELECT ${COLUMNS.map((c) => `f.${c}`).join(", ")}
       FROM ${TABLE} f
       INNER JOIN ${SUBJECT_TABLE} s ON f.id = s.feature_flag_id
-      WHERE s.subject = $1
+      WHERE s.subject = $1${filter}
       ORDER BY f.created DESC
     `;
         const res = await this.db.query(sql, [subject]);
@@ -363,15 +435,20 @@ export class FeatureFlagModel {
         if (subjects.length === 0) {
             return new Set();
         }
+        // Archived flags and archived groups do not contribute subject-based
+        // targeting: a flag matched directly must itself be active, and a flag
+        // matched via group membership must belong to an active group.
         const sql = `
       SELECT s.feature_flag_id AS feature_flag_id
       FROM ${SUBJECT_TABLE} s
-      WHERE s.subject = ANY($1)
+      INNER JOIN ${TABLE} f ON f.id = s.feature_flag_id
+      WHERE s.subject = ANY($1) AND f.archived IS NULL
       UNION
       SELECT gm.feature_flag_id AS feature_flag_id
       FROM ${GROUP_SUBJECT_TABLE} gs
       INNER JOIN ${GROUP_MEMBER_TABLE} gm ON gs.feature_flag_group_id = gm.group_id
-      WHERE gs.subject = ANY($1)
+      INNER JOIN ${GROUP_TABLE} g ON g.id = gs.feature_flag_group_id
+      WHERE gs.subject = ANY($1) AND g.archived IS NULL
     `;
         const res = await this.db.query(sql, [subjects]);
         return new Set(res.rows.map((row) => Number(row.feature_flag_id)));
@@ -652,7 +729,14 @@ export class FeatureFlagModel {
 }
 const GROUP_TABLE = "flapjack.feature_flag_group";
 const GROUP_MEMBER_TABLE = "flapjack.feature_flag_group_member";
-const GROUP_COLUMNS = ["id", "name", "note", "created", "modified"];
+const GROUP_COLUMNS = [
+    "id",
+    "name",
+    "note",
+    "created",
+    "modified",
+    "archived",
+];
 function mapGroupRow(row) {
     return {
         id: row.id,
@@ -660,6 +744,7 @@ function mapGroupRow(row) {
         note: row.note ?? undefined,
         created: new Date(row.created),
         modified: new Date(row.modified),
+        archived: row.archived ? new Date(row.archived) : undefined,
     };
 }
 /**
@@ -736,8 +821,9 @@ export class FeatureFlagGroupModel {
      * }
      * ```
      */
-    async getById(id) {
-        const sql = `SELECT ${GROUP_COLUMNS.join(", ")} FROM ${GROUP_TABLE} WHERE id = $1`;
+    async getById(id, { includeArchived = false } = {}) {
+        const filter = includeArchived ? "" : " AND archived IS NULL";
+        const sql = `SELECT ${GROUP_COLUMNS.join(", ")} FROM ${GROUP_TABLE} WHERE id = $1${filter}`;
         const res = await this.db.query(sql, [id]);
         return res.rows.length > 0 ? mapGroupRow(res.rows[0]) : null;
     }
@@ -752,8 +838,9 @@ export class FeatureFlagGroupModel {
      * const group = await model.getByName("billing_redesign");
      * ```
      */
-    async getByName(name) {
-        const sql = `SELECT ${GROUP_COLUMNS.join(", ")} FROM ${GROUP_TABLE} WHERE name = $1`;
+    async getByName(name, { includeArchived = false } = {}) {
+        const filter = includeArchived ? "" : " AND archived IS NULL";
+        const sql = `SELECT ${GROUP_COLUMNS.join(", ")} FROM ${GROUP_TABLE} WHERE name = $1${filter}`;
         const res = await this.db.query(sql, [name]);
         return res.rows.length > 0 ? mapGroupRow(res.rows[0]) : null;
     }
@@ -770,8 +857,9 @@ export class FeatureFlagGroupModel {
      * }
      * ```
      */
-    async list() {
-        const sql = `SELECT ${GROUP_COLUMNS.join(", ")} FROM ${GROUP_TABLE} ORDER BY created DESC`;
+    async list({ includeArchived = false, } = {}) {
+        const filter = includeArchived ? "" : " WHERE archived IS NULL";
+        const sql = `SELECT ${GROUP_COLUMNS.join(", ")} FROM ${GROUP_TABLE}${filter} ORDER BY created DESC`;
         const res = await this.db.query(sql);
         return res.rows.map(mapGroupRow);
     }
@@ -813,11 +901,16 @@ export class FeatureFlagGroupModel {
         return res.rows.length > 0 ? mapGroupRow(res.rows[0]) : null;
     }
     /**
-     * Deletes a feature flag group and all its member relationships.
+     * Permanently deletes a feature flag group and all its member and subject
+     * relationships (via ON DELETE CASCADE).
      *
      * @param id - The group ID to delete
      * @returns true if deleted, false if not found
      *
+     * @remarks
+     * This is a hard delete that destroys all metadata. To hide a group while
+     * retaining its history for audit purposes, use {@link archive} instead.
+     *
      * @example
      * ```typescript
      * const deleted = await model.delete(1);
@@ -827,6 +920,31 @@ export class FeatureFlagGroupModel {
         const res = await this.db.query(`DELETE FROM ${GROUP_TABLE} WHERE id = $1`, [id]);
         return res.rowCount > 0;
     }
+    /**
+     * Archives (hides) a feature flag group while keeping the row for
+     * historical/audit purposes. Archived groups are excluded from normal reads
+     * and no longer contribute subject-based targeting. Member flags are left
+     * untouched and remain active; the membership and subject rows are kept for
+     * audit but become inert.
+     *
+     * @param id - The group ID to archive
+     * @returns The archived group, or null if it does not exist or is already archived
+     *
+     * @remarks
+     * Archiving is irreversible: there is intentionally no `unarchive` method.
+     * The `archived` timestamp is set once and never changed (a second call is a
+     * no-op that returns null). The group's name remains reserved permanently.
+     *
+     * @example
+     * ```typescript
+     * const archived = await model.archive(1);
+     * ```
+     */
+    async archive(id) {
+        const sql = `UPDATE ${GROUP_TABLE} SET archived = now() WHERE id = $1 AND archived IS NULL RETURNING ${GROUP_COLUMNS.join(", ")}`;
+        const res = await this.db.query(sql, [id]);
+        return res.rows.length > 0 ? mapGroupRow(res.rows[0]) : null;
+    }
     /**
      * Adds a feature flag to a group.
      *
@@ -888,12 +1006,13 @@ export class FeatureFlagGroupModel {
      * }
      * ```
      */
-    async getFeatureFlags(groupId) {
+    async getFeatureFlags(groupId, { includeArchived = false } = {}) {
+        const filter = includeArchived ? "" : " AND f.archived IS NULL";
         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
+      WHERE gm.group_id = $1${filter}
       ORDER BY f.created DESC
     `;
         const res = await this.db.query(sql, [groupId]);
@@ -910,12 +1029,13 @@ export class FeatureFlagGroupModel {
      * const groups = await model.getGroupsForFeatureFlag(5);
      * ```
      */
-    async getGroupsForFeatureFlag(featureFlagId) {
+    async getGroupsForFeatureFlag(featureFlagId, { includeArchived = false } = {}) {
+        const filter = includeArchived ? "" : " AND g.archived IS NULL";
         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
+      WHERE gm.feature_flag_id = $1${filter}
       ORDER BY g.created DESC
     `;
         const res = await this.db.query(sql, [featureFlagId]);
@@ -960,12 +1080,13 @@ export class FeatureFlagGroupModel {
     /**
      * Gets all groups that are associated with a specific external subject identifier.
      */
-    async getGroupsForSubject(subject) {
+    async getGroupsForSubject(subject, { includeArchived = false } = {}) {
+        const filter = includeArchived ? "" : " AND g.archived IS NULL";
         const sql = `
       SELECT ${GROUP_COLUMNS.map((c) => `g.${c}`).join(", ")}
       FROM ${GROUP_TABLE} g
       INNER JOIN ${GROUP_SUBJECT_TABLE} gs ON g.id = gs.feature_flag_group_id
-      WHERE gs.subject = $1
+      WHERE gs.subject = $1${filter}
       ORDER BY g.created DESC
     `;
         const res = await this.db.query(sql, [subject]);
@@ -1019,10 +1140,10 @@ export class FeatureFlagGroupModel {
         }
         vals.push(groupId);
         const sql = `
-      UPDATE ${TABLE} 
+      UPDATE ${TABLE}
       SET ${updates.join(", ")}
-      WHERE id IN (
-        SELECT feature_flag_id 
+      WHERE archived IS NULL AND id IN (
+        SELECT feature_flag_id
         FROM ${GROUP_MEMBER_TABLE}
         WHERE group_id = $${paramIdx}
       )

package/dist/types.d.ts

@@ -16,6 +16,8 @@ export type FeatureFlag = {
     groups?: string[];
     /** List of specific user IDs that have this feature flag enabled */
     users?: string[];
+    /** List of tags for organizing flags (e.g. a release version like "release:1.5.0") */
+    tags?: string[];
     /** Description of where this flag is used and what it does */
     note?: string;
     /** Date when the feature flag was created */
@@ -24,6 +26,11 @@ export type FeatureFlag = {
     modified: Date;
     /** Optional expiration date for the feature flag */
     expires?: Date;
+    /**
+     * Date when the feature flag was archived (hidden). Set once and immutable;
+     * archiving is irreversible and the name remains reserved permanently.
+     */
+    archived?: Date;
 };
 /**
  * Called when a feature flag which has expired is used.
@@ -56,5 +63,10 @@ export type FeatureFlagGroup = {
     created: Date;
     /** Date when the group was last modified */
     modified: Date;
+    /**
+     * Date when the group was archived (hidden). Set once and immutable;
+     * archiving is irreversible and the name remains reserved permanently.
+     */
+    archived?: 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;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"}
+{"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,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,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;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,IAAI,CAAC;CACjB,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;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,IAAI,CAAC;CACjB,CAAC"}

package/migrations/1781107651000_add-feature-flag-tags.js

@@ -0,0 +1,38 @@
+/**
+ * @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(
+    { schema: "flapjack", name: "feature_flag" },
+    {
+      tags: {
+        type: "text[]",
+        default: pgm.func("'{}'::text[]"),
+      },
+    },
+  );
+
+  // GIN index for efficient lookups by tag (e.g. WHERE $1 = ANY(tags))
+  pgm.createIndex({ schema: "flapjack", name: "feature_flag" }, "tags", {
+    method: "gin",
+  });
+};
+
+/**
+ * @param pgm {import('node-pg-migrate').MigrationBuilder}
+ * @param run {() => void | undefined}
+ * @returns {Promise<void> | void}
+ */
+export const down = (pgm) => {
+  pgm.dropIndex({ schema: "flapjack", name: "feature_flag" }, "tags", {
+    method: "gin",
+  });
+  pgm.dropColumn({ schema: "flapjack", name: "feature_flag" }, "tags");
+};

package/migrations/1781200000000_add-archived.js

@@ -0,0 +1,37 @@
+/**
+ * @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) => {
+  // Add a nullable archived timestamp to the core data models. When set, the
+  // record is considered archived (hidden) but kept for historical/audit
+  // purposes. Archiving is irreversible and the name remains reserved forever
+  // (the existing UNIQUE(name) constraint is intentionally left unchanged).
+  pgm.addColumn(
+    { schema: "flapjack", name: "feature_flag" },
+    { archived: { type: "timestamptz" } },
+  );
+  pgm.addColumn(
+    { schema: "flapjack", name: "feature_flag_group" },
+    { archived: { type: "timestamptz" } },
+  );
+};
+
+/**
+ * @param pgm {import('node-pg-migrate').MigrationBuilder}
+ * @param run {() => void | undefined}
+ * @returns {Promise<void> | void}
+ */
+export const down = (pgm) => {
+  pgm.dropColumn({ schema: "flapjack", name: "feature_flag" }, "archived");
+  pgm.dropColumn(
+    { schema: "flapjack", name: "feature_flag_group" },
+    "archived",
+  );
+};

package/package.json

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