@brandtg/flapjack 0.1.0

package/dist/model.js

@@ -0,0 +1,365 @@
+import MurmurHash3 from "imurmurhash";
+const TABLE = "flapjack_feature_flag";
+const COLUMNS = [
+    "id",
+    "name",
+    "everyone",
+    "percent",
+    "roles",
+    "groups",
+    "users",
+    "note",
+    "created",
+    "modified",
+];
+function mapRow(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        everyone: row.everyone ?? undefined,
+        percent: row.percent === null || row.percent === undefined
+            ? undefined
+            : Number(row.percent),
+        roles: row.roles && row.roles.length > 0 ? row.roles : undefined,
+        groups: row.groups && row.groups.length > 0
+            ? row.groups
+            : undefined,
+        users: row.users && row.users.length > 0 ? row.users : undefined,
+        note: row.note ?? undefined,
+        created: new Date(row.created),
+        modified: new Date(row.modified),
+    };
+}
+/**
+ * Model for managing feature flags stored in PostgreSQL.
+ *
+ * @example
+ * ```typescript
+ * import { Pool } from "pg";
+ * import { FeatureFlagModel } from "@brandtg/flapjack";
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const featureFlags = new FeatureFlagModel(pool);
+ * ```
+ */
+export class FeatureFlagModel {
+    db;
+    /**
+     * Creates a new FeatureFlagModel 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 FeatureFlagModel(pool);
+     * ```
+     */
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Creates a new feature flag in the database.
+     *
+     * @param input - Feature flag configuration
+     * @param input.name - Unique name for the feature flag (required)
+     * @param input.everyone - Optional boolean to enable/disable for everyone (overrides all other settings)
+     * @param input.percent - Optional percentage rollout (0-99.9)
+     * @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.note - Optional description of the flag's purpose
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const flag = await model.create({
+     *   name: "new_checkout_flow",
+     *   roles: ["admin"],
+     *   note: "New checkout redesign",
+     * });
+     * ```
+     */
+    async create(input) {
+        const cols = ["name"];
+        const vals = [input.name];
+        if ("everyone" in input) {
+            cols.push("everyone");
+            vals.push(input.everyone ?? null);
+        }
+        if ("percent" in input) {
+            cols.push("percent");
+            vals.push(input.percent ?? null);
+        }
+        if ("roles" in input) {
+            cols.push("roles");
+            vals.push(input.roles ?? null);
+        }
+        if ("groups" in input) {
+            cols.push("groups");
+            vals.push(input.groups ?? null);
+        }
+        if ("users" in input) {
+            cols.push("users");
+            vals.push(input.users ?? null);
+        }
+        if ("note" in input) {
+            cols.push("note");
+            vals.push(input.note ?? 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);
+        return mapRow(res.rows[0]);
+    }
+    /**
+     * Retrieves a feature flag by its ID.
+     *
+     * @param id - The unique identifier of the feature flag
+     * @returns The feature flag if found, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const flag = await model.getById(123);
+     * if (flag) {
+     *   console.log(`Flag ${flag.name} is configured`);
+     * }
+     * ```
+     */
+    async getById(id) {
+        const sql = `SELECT ${COLUMNS.join(", ")} FROM ${TABLE} WHERE id = $1`;
+        const res = await this.db.query(sql, [id]);
+        if (res.rows.length === 0)
+            return null;
+        return mapRow(res.rows[0]);
+    }
+    /**
+     * Retrieves a feature flag by its name.
+     *
+     * @param name - The unique name of the feature flag
+     * @returns The feature flag if found, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const flag = await model.getByName("new_checkout_flow");
+     * if (flag) {
+     *   console.log(`Flag is ${flag.everyone ? 'enabled' : 'disabled'} for everyone`);
+     * }
+     * ```
+     */
+    async getByName(name) {
+        const sql = `SELECT ${COLUMNS.join(", ")} FROM ${TABLE} WHERE name = $1`;
+        const res = await this.db.query(sql, [name]);
+        if (res.rows.length === 0)
+            return null;
+        return mapRow(res.rows[0]);
+    }
+    /**
+     * Retrieves all feature flags, ordered by ID.
+     *
+     * @returns Array of all feature flags in the database
+     *
+     * @example
+     * ```typescript
+     * const flags = await model.list();
+     * console.log(`Total flags: ${flags.length}`);
+     * flags.forEach(flag => {
+     *   console.log(`${flag.name}: ${flag.everyone ?? 'conditional'}`);
+     * });
+     * ```
+     */
+    async list() {
+        const sql = `SELECT ${COLUMNS.join(", ")} FROM ${TABLE} ORDER BY id`;
+        const res = await this.db.query(sql);
+        return res.rows.map(mapRow);
+    }
+    /**
+     * Updates an existing feature flag.
+     *
+     * @param id - The unique identifier of the feature flag to update
+     * @param changes - Object containing the fields to update
+     * @returns The updated feature flag if found, null otherwise
+     *
+     * @remarks
+     * The modified timestamp is automatically updated by a database trigger.
+     * Pass `null` for a field to clear it (e.g., `everyone: null` removes the override).
+     * If no changes are provided, returns the flag unchanged.
+     *
+     * @example
+     * ```typescript
+     * // Gradually increase rollout percentage
+     * await model.update(flagId, { percent: 25 });
+     *
+     * // Enable for everyone
+     * await model.update(flagId, { everyone: true });
+     *
+     * // Remove everyone override, reverting to other rules
+     * await model.update(flagId, { everyone: null });
+     * ```
+     */
+    async update(id, changes) {
+        const sets = [];
+        const vals = [];
+        if ("name" in changes) {
+            sets.push(`name = $${sets.length + 1}`);
+            vals.push(changes.name ?? null);
+        }
+        if ("everyone" in changes) {
+            sets.push(`everyone = $${sets.length + 1}`);
+            vals.push(changes.everyone ?? null);
+        }
+        if ("percent" in changes) {
+            sets.push(`percent = $${sets.length + 1}`);
+            vals.push(changes.percent ?? null);
+        }
+        if ("roles" in changes) {
+            sets.push(`roles = $${sets.length + 1}`);
+            vals.push(changes.roles ?? null);
+        }
+        if ("groups" in changes) {
+            sets.push(`groups = $${sets.length + 1}`);
+            vals.push(changes.groups ?? null);
+        }
+        if ("users" in changes) {
+            sets.push(`users = $${sets.length + 1}`);
+            vals.push(changes.users ?? null);
+        }
+        if ("note" in changes) {
+            sets.push(`note = $${sets.length + 1}`);
+            vals.push(changes.note ?? null);
+        }
+        if (sets.length === 0) {
+            return this.getById(id);
+        }
+        const idParamIndex = sets.length + 1;
+        vals.push(id);
+        const sql = `UPDATE ${TABLE} SET ${sets.join(", ")} WHERE id = $${idParamIndex} RETURNING ${COLUMNS.join(", ")}`;
+        const res = await this.db.query(sql, vals);
+        if (res.rows.length === 0)
+            return null;
+        return mapRow(res.rows[0]);
+    }
+    /**
+     * Deletes a feature flag from the database.
+     *
+     * @param id - The unique identifier of the feature flag to delete
+     * @returns true if the flag was deleted, false if not found
+     *
+     * @example
+     * ```typescript
+     * const deleted = await model.delete(flagId);
+     * if (deleted) {
+     *   console.log("Flag successfully removed");
+     * }
+     * ```
+     */
+    async delete(id) {
+        const res = await this.db.query(`DELETE FROM ${TABLE} WHERE id = $1`, [id]);
+        return res.rowCount > 0;
+    }
+    /**
+     * Checks if a user belongs to any of the specified groups
+     */
+    isActiveForGroups(userGroups = [], flagGroups = []) {
+        if (flagGroups.length === 0)
+            return false;
+        return flagGroups.some((group) => userGroups.includes(group));
+    }
+    /**
+     * Computes the hash value for a user ID using MurmurHash3.
+     *
+     * @param userId - The user ID to hash
+     * @returns The hash value used for percentage bucketing
+     *
+     * @remarks
+     * This method is useful for debugging percentage rollouts.
+     * The hash value is consistent for the same user ID.
+     * The bucket is computed as `hash % 100`.
+     *
+     * @example
+     * ```typescript
+     * const hash = await model.hashUserId("user_123");
+     * const bucket = hash % 100;
+     * console.log(`User bucket: ${bucket}`);
+     * // If bucket is 42 and percent is 50, user is in the rollout
+     * ```
+     */
+    async hashUserId(userId) {
+        return MurmurHash3(userId).result();
+    }
+    /**
+     * Checks if a feature flag is active for a user based on configured rules.
+     *
+     * @param params - Parameters for flag evaluation
+     * @param params.name - The name of the feature flag to check
+     * @param params.user - Optional user ID
+     * @param params.roles - Optional list of roles the user has
+     * @param params.groups - Optional list of groups the user belongs to
+     * @returns true if the flag is active for the user, false otherwise
+     *
+     * @remarks
+     * Evaluation order (first match wins):
+     * 1. Everyone override (if set to true/false, returns immediately)
+     * 2. User ID is in the users list
+     * 3. User belongs to any group in the groups list
+     * 4. User has any role in the roles list
+     * 5. User falls within the percentage rollout (based on consistent hashing)
+     * 6. Default: returns false
+     *
+     * @example
+     * ```typescript
+     * // Check for admin user
+     * const isActive = await model.isActiveForUser({
+     *   name: "new_feature",
+     *   user: "user_123",
+     *   roles: ["admin"],
+     *   groups: ["beta_testers"],
+     * });
+     *
+     * if (isActive) {
+     *   // Show new feature
+     * } else {
+     *   // Show old feature
+     * }
+     * ```
+     */
+    async isActiveForUser({ name, user, roles, groups, }) {
+        const flag = await this.getByName(name);
+        // No such flag
+        if (!flag) {
+            return false;
+        }
+        // Everyone Override: If everyone is true or false, return that value immediately
+        if (flag.everyone !== undefined && flag.everyone !== null) {
+            return flag.everyone;
+        }
+        // User-Specific Check: If user ID is in the users array, return true
+        if (user && flag.users && flag.users.includes(user)) {
+            return true;
+        }
+        // Group Check: If any of the user's groups match any group in the groups array, return true
+        if (groups && this.isActiveForGroups(groups, flag.groups)) {
+            return true;
+        }
+        // Role Check: If any of the user's roles match any role in the roles array, return true
+        if (flag.roles && roles) {
+            for (const role of roles) {
+                if (flag.roles.includes(role)) {
+                    return true;
+                }
+            }
+        }
+        // Percentage Check: If percentage rollout applies to this user, return rollout result
+        if (user && flag.percent && flag.percent > 0) {
+            const userHash = await this.hashUserId(user);
+            const bucket = userHash % 100;
+            if (bucket < flag.percent) {
+                return true;
+            }
+        }
+        // Default: Return false
+        return false;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Represents a feature flag used to enable or disable features in an application.
+ */
+export type FeatureFlag = {
+    /** Unique identifier for the feature flag */
+    id: number;
+    /** Human readable of the feature flag */
+    name: string;
+    /** Flip this flag on or off for everyone, overriding all other settings */
+    everyone?: boolean | null;
+    /** Number between 0 and 99.9 for percentage rollout */
+    percent?: number;
+    /** List of roles that have this feature flag enabled */
+    roles?: string[];
+    /** List of user groups that have this feature flag enabled */
+    groups?: string[];
+    /** List of specific user IDs that have this feature flag enabled */
+    users?: string[];
+    /** Description of where this flag is used and what it does */
+    note?: string;
+    /** Date when the feature flag was created */
+    created: Date;
+    /** Date when the feature flag was last modified */
+    modified: Date;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +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"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/migrations/1759720355601_create-feature-flag.js

@@ -0,0 +1,65 @@
+/**
+ * @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 table
+  pgm.createTable("flapjack_feature_flag", {
+    id: "id",
+    name: { type: "text", notNull: true, unique: true },
+    everyone: { type: "boolean" },
+    percent: {
+      type: "numeric(3,1)",
+      check: "percent >= 0 AND percent <= 99.9",
+    },
+    roles: { type: "text[]", default: pgm.func("'{}'::text[]") },
+    groups: { type: "text[]", default: pgm.func("'{}'::text[]") },
+    users: { type: "text[]", default: pgm.func("'{}'::text[]") },
+    note: { type: "text" },
+    created: { type: "timestamptz", notNull: true, default: pgm.func("now()") },
+    modified: {
+      type: "timestamptz",
+      notNull: true,
+      default: pgm.func("now()"),
+    },
+  });
+
+  // Create a trigger to update the modified timestamp on row update
+  pgm.sql(`
+    CREATE OR REPLACE FUNCTION flapjack_set_modified_timestamp()
+    RETURNS trigger AS $$
+    BEGIN
+    NEW.modified = now();
+    RETURN NEW;
+    END;
+    $$ LANGUAGE plpgsql;
+  `);
+
+  // Attach the trigger to the flapjack_feature_flag table
+  pgm.sql(`
+    CREATE TRIGGER flapjack_feature_flag_set_modified
+    BEFORE UPDATE ON flapjack_feature_flag
+    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_set_modified 
+    ON flapjack_feature_flag;
+  `);
+  pgm.sql(`DROP FUNCTION IF EXISTS flapjack_set_modified_timestamp;`);
+  pgm.dropTable("flapjack_feature_flag");
+};

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@brandtg/flapjack",
+  "version": "0.1.0",
+  "description": "A simple feature flags library with PostgreSQL integration",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "flapjack": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "migrations",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "npm run clean && npx tsc",
+    "clean": "rm -rf dist",
+    "dev": "npx tsc --watch",
+    "dev:env": "bash bin/dev/env.sh",
+    "dev:migrate": "npx dotenv-cli -e env -- node-pg-migrate up",
+    "dev:docker:up": "docker compose -f docker-compose.yml up -d",
+    "dev:docker:down": "docker compose -f docker-compose.yml down -v",
+    "create-migration": "npx node-pg-migrate create --",
+    "test": "npm run build && vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "prepublishOnly": "npm run lint && npm run test && npm run build",
+    "pack:dev": "npm run build && npm pack",
+    "smoke": "npm run build && node dist/cli.js --help && node dist/cli.js hash-user smoke"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.5",
+    "imurmurhash": "^0.1.4",
+    "node-pg-migrate": "^8.0.3",
+    "pg": "^8.12.0",
+    "yargs": "^18.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.37.0",
+    "@types/imurmurhash": "^0.1.4",
+    "@types/pg": "^8.11.10",
+    "@types/yargs": "^17.0.33",
+    "dotenv-cli": "^10.0.0",
+    "eslint": "^9.37.0",
+    "prettier": "^3.6.2",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.45.0",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "feature-flags",
+    "postgres",
+    "database",
+    "configuration"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brandtg/flapjack.git"
+  },
+  "bugs": {
+    "url": "https://github.com/brandtg/flapjack/issues"
+  },
+  "homepage": "https://github.com/brandtg/flapjack#readme",
+  "license": "BSD-3-Clause",
+  "author": "Greg Brandt",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}