manage-flags-eazy

A lightweight and type-safe feature flag management library for JavaScript/TypeScript applications.

Features

• 🎯 Simple and intuitive API
• 📦 TypeScript support out of the box
• 🔄 Runtime flag updates
• 👂 Subscribe to flag changes
• 🔙 Reset to default values
• 🎭 Zero dependencies
• 📦 ESM and CommonJS support
• 🌐 Load flags from JS/TS files or API
• 🔍 Support for both simple and structured flag formats

Installation

Using npm:

npm install manage-flags-eazy

Using yarn:

yarn add manage-flags-eazy

Using pnpm:

pnpm add manage-flags-eazy

Usage

Basic Usage with Direct Import

The simplest way to use feature flags is to define them in a JavaScript file and import them directly:

// features.js
module.exports = [
  { name: "darkMode", value: true },
  { name: "newFeatures", value: false },
  { name: "betaTesting", value: true }
];

// app.js
const { FeatureFlags } = require('manage-flags-eazy');
const featureFlags = require('./features.js');

// Initialize with the imported flags
const flags = new FeatureFlags(featureFlags);

// Check if a flag is enabled
if (flags.isEnabled('darkMode')) {
  // Enable dark mode
}

// Toggle flags at runtime
flags.enable('newFeatures');
flags.disable('darkMode');

TypeScript Usage

import { FeatureFlags } from 'manage-flags-eazy';
import type { FlagEntry } from 'manage-flags-eazy';

// Import flags dynamically from a JS file
async function loadFlags(): Promise<FlagEntry[]> {
  const flags = await import('./features.js');
  return flags.default || flags;
}

async function setupApp() {
  const featureFlags = await loadFlags();
  const flags = new FeatureFlags(featureFlags);
  
  if (flags.isEnabled('darkMode')) {
    // Dark mode is enabled
  }
}

Loading Flags from API

You can also load flags from an API endpoint:

import { FeatureFlags, APIFlagSource } from 'manage-flags-eazy';

const flags = new FeatureFlags();

// Create an API source
const apiSource = new APIFlagSource('https://api.example.com/feature-flags', {
  headers: {
    'Authorization': 'Bearer your-token-here'
  }
});

// Load flags from the API and merge with existing flags
await flags.loadFrom(apiSource, { 
  merge: true,
  updateDefaults: true
});

// Now use the flags loaded from the API
if (flags.isEnabled('darkMode')) {
  // Dark mode is enabled from API settings
}

The API can return flags in either format:

• Simple object: { "darkMode": true, "newFeature": false }
• Structured array: [{ name: "darkMode", value: true }, ...]

Flag Formats

This library supports two formats for feature flags:

Simple Format (Object)

{
  darkMode: true,
  newFeatures: false,
  betaTesting: true
}

Structured Format (Array of Objects)

[
  { name: "darkMode", value: true },
  { name: "newFeatures", value: false },
  { name: "betaTesting", value: true }
]

Subscribing to Changes

const unsubscribe = flags.subscribe((flagName, value) => {
  console.log(`Flag ${flagName} changed to ${value}`);
});

// Later, when you want to stop listening
unsubscribe();

Resetting Flags

// Reset all flags to their initial values
flags.reset();

Getting All Flags

const allFlags = flags.getAllFlags();
console.log(allFlags);

API Reference

FeatureFlags

Constructor

constructor(initialFlags: Record<string, boolean> | Array<{name: string, value: boolean}> = {})

Creates a new instance with optional initial flag values in either simple or structured format.

Methods

• isEnabled(flagName: string): boolean

  • Check if a feature flag is enabled

• enable(flagName: string): void

  • Enable a feature flag

• disable(flagName: string): void

  • Disable a feature flag

• setFlag(flagName: string, value: boolean): void

  • Set a feature flag's value

• reset(): void

  • Reset all flags to their default values

• subscribe(callback: (flagName: string, value: boolean) => void): () => void

  • Subscribe to flag changes
  • Returns an unsubscribe function

• getAllFlags(): Record<string, boolean>

  • Get all current flag values

• loadFrom(source: FlagSource, options?: FlagLoadOptions): Promise<void>

  • Load flags from a source (API or JS/TS file)
  • Options:
    • merge: Whether to merge with existing flags (default: true)
    • updateDefaults: Whether to update default values (default: false)

APIFlagSource

constructor(url: string, options?: RequestInit)

Creates a source that loads flags from an API endpoint.

License

MIT