Fanion 🏁

A lightweight, flexible feature flagging library for Node.js applications

Fanion is a modern feature flagging library that allows you to control feature rollouts, conduct A/B tests, and manage application behavior dynamically. Built with TypeScript and designed for simplicity and performance.

Features

🚀 Lightweight & Fast - Minimal overhead with maximum performance
🔧 TypeScript First - Full type safety and IntelliSense support
🏪 Pluggable Storage - Memory, database, or custom storage providers
🎯 Context-Aware - Dynamic feature evaluation based on user context
🔄 Async Support - Built for modern async/await patterns
📦 Zero Dependencies - No external dependencies in core package

Quick Start

Installation

npm install fanion
# or
yarn add fanion
# or
pnpm add fanion

For database support, also install the appropriate database driver:

# For SQL databases (SQLite, PostgreSQL, MySQL)
npm install knex sqlite3  # or pg, mysql2

# For DynamoDB
npm install @aws-sdk/client-dynamodb @aws-sdk/util-dynamodb

Basic Usage

import { featureManager } from 'fanion';

// Create a feature manager instance
const features = featureManager();

// Define a simple feature flag
features.define('new-dashboard', () => true);

// Check if feature is active
const isActive = await features.active('new-dashboard');
console.log(isActive); // true

Context-Based Feature Flags

// Define a feature flag with user context
features.define('premium-features', (context: { user: { plan: string } }) => {
  return context.user.plan === 'premium';
});

// Check feature with context
const hasAccess = await features.active('premium-features', {
  user: { plan: 'premium' }
});

Using Storage Providers

import { featureManager, createInMemoryDriver } from 'fanion';

// Create feature manager with storage
const features = featureManager({
  store: createInMemoryDriver()
});

// Define and store a feature flag
features.defineAndStore('beta-feature', true);

// Feature flags stored in the provider are automatically retrieved
const isEnabled = await features.active('beta-feature');

Using Database Storage

import { featureManagerWithDatabase, createKnexDatabaseDriver } from 'fanion';
import knex from 'knex';

// Create database connection
const db = knex({
  client: 'sqlite3',
  connection: {
    filename: './features.db'
  },
  useNullAsDefault: true
});

// Create feature manager with database storage
const features = await featureManagerWithDatabase({
  store: createKnexDatabaseDriver({
    connection: db,
    tableName: 'feature_flags', // optional, defaults to 'feature_flags'
    featureNameColumn: 'feature_name', // optional, defaults to 'feature_name'
    valueColumn: 'value' // optional, defaults to 'value'
  })
});

// The database table is automatically created
// Feature flags are now persisted in the database
features.defineAndStore('persistent-feature', true);

Using DynamoDB Storage

import { featureManagerWithDatabase, createDynamoDBDatabaseDriver } from 'fanion';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

// Create DynamoDB client
const dynamoClient = new DynamoDBClient({
  region: 'us-east-1',
  // Add other configuration as needed (credentials, endpoint, etc.)
});

// Create feature manager with DynamoDB storage
const features = await featureManagerWithDatabase({
  store: createDynamoDBDatabaseDriver({
    client: dynamoClient,
    tableName: 'feature_flags', // optional, defaults to 'feature_flags'
    featureNameAttribute: 'feature_name', // optional, defaults to 'feature_name'
    valueAttribute: 'value' // optional, defaults to 'value'
  })
});

// The DynamoDB table is automatically created with pay-per-request billing
// Feature flags are now persisted in DynamoDB
features.defineAndStore('persistent-feature', true);

API Reference

FeatureManager

The main class for managing feature flags.

`define<T>(flagName: string, check?: (context: T) => boolean | Promise<boolean>)`

Define a feature flag with an optional check function.

// Simple flag (always true when no check function provided)
features.define('simple-flag');

// Flag with synchronous check
features.define('admin-feature', (ctx: { isAdmin: boolean }) => ctx.isAdmin);

// Flag with asynchronous check
features.define('database-feature', async (ctx) => {
  return await checkDatabaseFeature(ctx.userId);
});

`defineAndStore(flagName: string, defaultValue: boolean = true)`

Define a feature flag and store it in the configured storage provider.

features.defineAndStore('new-ui', false);

`featureManagerWithDatabase(config: { store: FeatureStorageProvider })`

Create a feature manager instance with database initialization. This function automatically initializes the database connection and creates necessary tables.

const features = await featureManagerWithDatabase({
  store: createKnexDatabaseDriver({ connection: db })
});

`initStore(): Promise<void>`

Initialize the storage provider (useful for database connections). This is called automatically when using featureManagerWithDatabase().

const features = featureManager({ store: dbDriver });
await features.initStore(); // Initialize database tables

`active<T>(flagName: string, context?: T): Promise<boolean>`

Check if a feature flag is active for the given context.

const isActive = await features.active('feature-name');
const isActiveWithContext = await features.active('feature-name', { userId: 123 });

Storage Providers

In-Memory Driver

import { createInMemoryDriver } from 'fanion';

const memoryStore = createInMemoryDriver();
const features = featureManager({ store: memoryStore });

SQL Database Driver (Knex)

The Knex database driver supports all databases that Knex supports (PostgreSQL, MySQL, SQLite, etc.).

import { createKnexDatabaseDriver, featureManagerWithDatabase, KnexDatabaseDriver } from 'fanion';
import knex from 'knex';

// Setup database connection
const db = knex({
  client: 'postgresql', // or 'mysql', 'sqlite3', etc.
  connection: {
    host: 'localhost',
    user: 'username',
    password: 'password',
    database: 'myapp'
  }
});

// Create database driver with custom configuration
const dbDriver = createKnexDatabaseDriver({
  connection: db,
  tableName: 'my_feature_flags',       // defaults to 'feature_flags'
  featureNameColumn: 'flag_name',      // defaults to 'feature_name'
  valueColumn: 'is_enabled'            // defaults to 'value'
});

// Initialize feature manager with database
const features = await featureManagerWithDatabase({
  store: dbDriver
});

Configuration Options:

connection: Knex database connection instance (required)
tableName: Name of the database table (optional, defaults to 'feature_flags')
featureNameColumn: Name of the feature name column (optional, defaults to 'feature_name')
valueColumn: Name of the value column (optional, defaults to 'value')

DynamoDB Driver

The DynamoDB driver uses AWS SDK v3 to connect to Amazon DynamoDB.

import { createDynamoDBDatabaseDriver, featureManagerWithDatabase } from 'fanion';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

// Setup DynamoDB client
const dynamoClient = new DynamoDBClient({
  region: 'us-east-1',
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  },
  // For local development with DynamoDB Local
  // endpoint: 'http://localhost:8000',
});

// Create DynamoDB driver with custom configuration
const dynamoDriver = createDynamoDBDatabaseDriver({
  client: dynamoClient,
  tableName: 'my_feature_flags',        // defaults to 'feature_flags'
  featureNameAttribute: 'flag_name',    // defaults to 'feature_name'
  valueAttribute: 'is_enabled'          // defaults to 'value'
});

// Initialize feature manager with DynamoDB
const features = await featureManagerWithDatabase({
  store: dynamoDriver
});

Configuration Options:

client: DynamoDB client instance from AWS SDK v3 (required)
tableName: Name of the DynamoDB table (optional, defaults to 'feature_flags')
featureNameAttribute: Name of the partition key attribute (optional, defaults to 'feature_name')
valueAttribute: Name of the value attribute (optional, defaults to 'value')

DynamoDB Table Structure: The driver automatically creates a table with:

Partition key: feature_name (or custom attribute name)
Pay-per-request billing mode
No sort key (simple key-value storage)

Custom Storage Provider

Implement the FeatureStorageProvider interface:

interface FeatureStorageProvider {
  set(flag: string, value: boolean): Promise<void>;
  get(flag: string): Promise<boolean | undefined>;
  delete(featureName: string): Promise<void>;
  initStore?(): Promise<void>; // Optional initialization method
}

class RedisStorage implements FeatureStorageProvider {
  async set(flag: string, value: boolean): Promise<void> {
    // Implement Redis storage
  }

  async get(flag: string): Promise<boolean | undefined> {
    // Implement Redis retrieval
  }

  async delete(featureName: string): Promise<void> {
    // Implement Redis deletion
  }

  async initStore(): Promise<void> {
    // Optional: Initialize Redis connection
  }
}

For database providers, implement the DatabaseStorageProvider interface:

import { DatabaseStorageProvider } from 'fanion';

interface DatabaseStorageProvider extends FeatureStorageProvider {
  createTableIfNotExists(): Promise<void>;
  isDatabaseDriver(): boolean;
  initStore(): Promise<void>;
}

class CustomDatabaseDriver implements DatabaseStorageProvider {
  async set(flag: string, value: boolean): Promise<void> {
    // Implement database upsert
  }

  async get(flag: string): Promise<boolean | undefined> {
    // Implement database retrieval
  }

  async delete(featureName: string): Promise<void> {
    // Implement database deletion
  }

  async createTableIfNotExists(): Promise<void> {
    // Create the feature flags table if it doesn't exist
  }

  isDatabaseDriver(): boolean {
    return true;
  }

  async initStore(): Promise<void> {
    await this.createTableIfNotExists();
  }
}

Utilities

`generateFeatureName(context: string, flag: string, subFlag?: string)`

Generate consistent feature flag names with namespacing.

import { generateFeatureName } from 'fanion';

const flagName = generateFeatureName('auth', 'oauth', 'google');
// Returns: "auth:oauth.google"

Advanced Usage

A/B Testing

features.define('homepage-variant', (context: { userId: number }) => {
  // Simple hash-based A/B test
  return context.userId % 2 === 0;
});

const showVariantA = await features.active('homepage-variant', { userId: 123 });

Gradual Rollouts

features.define('new-feature', (context: { userId: number }) => {
  // Roll out to 20% of users
  return (context.userId % 100) < 20;
});

Environment-Based Flags

features.define('debug-mode', () => {
  return process.env.NODE_ENV === 'development';
});

Complex Business Logic

features.define('enterprise-features', async (context: {
  user: { id: number; plan: string; createdAt: Date }
}) => {
  const { user } = context;

  // Multiple conditions
  if (user.plan !== 'enterprise') return false;

  // Check account age
  const accountAge = Date.now() - user.createdAt.getTime();
  const thirtyDays = 30 * 24 * 60 * 60 * 1000;

  return accountAge > thirtyDays;
});

Error Handling

Fanion provides specific error types for better error handling:

import { FeatureNotExistsError } from 'fanion';

try {
  await features.active('non-existent-flag');
} catch (error) {
  if (error instanceof FeatureNotExistsError) {
    console.log('Feature flag not found');
  }
}

Best Practices

1. Use Descriptive Names

// Good
features.define('checkout-express-shipping');

// Avoid
features.define('flag1');

2. Implement Fallbacks

features.define('external-api-feature', async (context) => {
  try {
    return await checkExternalAPI(context);
  } catch {
    // Fallback to safe default
    return false;
  }
});

3. Type Your Contexts

interface UserContext {
  userId: number;
  plan: 'free' | 'premium' | 'enterprise';
  features: string[];
}

features.define<{ user: UserContext }>('premium-dashboard', (context) => {
  return context.user.plan !== 'free';
});

4. Keep Checks Simple

// Good - simple and fast
features.define('new-ui', (ctx: { version: string }) => {
  return ctx.version >= '2.0.0';
});

// Avoid - complex logic that might slow down requests
features.define('complex-feature', async (ctx) => {
  // Avoid heavy database queries or API calls
  const result = await heavyDatabaseQuery(ctx);
  return processComplexLogic(result);
});

Framework Integration

Express.js

import express from 'express';
import { featureManager } from 'fanion';

const app = express();
const features = featureManager();

features.define('rate-limiting', (ctx: { ip: string }) => {
  // Enable rate limiting for specific IPs
  return ctx.ip !== '127.0.0.1';
});

app.use(async (req, res, next) => {
  const shouldRateLimit = await features.active('rate-limiting', {
    ip: req.ip
  });

  if (shouldRateLimit) {
    // Apply rate limiting middleware
  }

  next();
});

Next.js

// lib/features.ts
import { featureManagerWithDatabase, createKnexDatabaseDriver } from 'fanion';
import knex from 'knex';

const db = knex({
  client: 'postgresql',
  connection: process.env.DATABASE_URL
});

export const features = await featureManagerWithDatabase({
  store: createKnexDatabaseDriver({ connection: db })
});

features.define('beta-features', (ctx: { user?: { isBetaTester: boolean } }) => {
  return ctx.user?.isBetaTester ?? false;
});

// pages/dashboard.tsx
import { features } from '../lib/features';

export async function getServerSideProps(context) {
  const showBetaFeatures = await features.active('beta-features', {
    user: context.user
  });

  return {
    props: { showBetaFeatures }
  };
}

Database Schemas

SQL Databases (Knex Driver)

When using SQL database storage providers, Fanion automatically creates a table with the following structure:

CREATE TABLE feature_flags (
  feature_name VARCHAR PRIMARY KEY,
  value BOOLEAN NOT NULL
);

The table and column names are configurable through the driver configuration.

DynamoDB

When using the DynamoDB driver, Fanion automatically creates a table with:

Partition Key: feature_name (String)
Attributes: value (Boolean)
Billing Mode: Pay-per-request
No sort key: Simple key-value storage

The table and attribute names are configurable through the driver configuration.

Migration from In-Memory to Database Storage

If you're migrating from in-memory storage to database storage, here's how to transition smoothly:

import { featureManager, featureManagerWithDatabase, createKnexDatabaseDriver, createDynamoDBDatabaseDriver } from 'fanion';

// Old in-memory setup
const oldFeatures = featureManager();
oldFeatures.define('feature-a', () => true);
oldFeatures.define('feature-b', (ctx) => ctx.user.isPremium);

// New SQL database setup
const sqlFeatures = await featureManagerWithDatabase({
  store: createKnexDatabaseDriver({ connection: db })
});

// Or new DynamoDB setup
const dynamoFeatures = await featureManagerWithDatabase({
  store: createDynamoDBDatabaseDriver({ client: dynamoClient })
});

// Migrate stored flags to database
sqlFeatures.defineAndStore('feature-a', true);
// Keep dynamic flags as code-based
sqlFeatures.define('feature-b', (ctx) => ctx.user.isPremium);

Best Practices for Database Storage

1. Use Database Storage for Administrative Flags

// Good: Use database for flags controlled by admins/operators
features.defineAndStore('maintenance-mode', false);
features.defineAndStore('new-ui-rollout', true);

2. Use Code-Based Flags for Complex Logic

// Good: Keep complex logic in code
features.define('premium-features', (ctx) => {
  return ctx.user.plan === 'premium' && ctx.user.verified;
});

3. Connection Management

For SQL Databases:

// Good: Reuse database connections
const db = knex({
  client: 'postgresql',
  connection: process.env.DATABASE_URL,
  pool: { min: 2, max: 10 } // Configure connection pooling
});

// Use the same connection for your app and feature flags
const features = await featureManagerWithDatabase({
  store: createKnexDatabaseDriver({ connection: db })
});

For DynamoDB:

// Good: Reuse DynamoDB client
const dynamoClient = new DynamoDBClient({
  region: process.env.AWS_REGION,
  // Configure connection settings, retries, etc.
  maxAttempts: 3,
});

// Use the same client for your app and feature flags
const features = await featureManagerWithDatabase({
  store: createDynamoDBDatabaseDriver({ client: dynamoClient })
});

4. Error Handling in Production

// Good: Handle database errors gracefully
try {
  const isEnabled = await features.active('new-feature');
  if (isEnabled) {
    // Feature logic
  }
} catch (error) {
  // Log error and use safe default
  console.error('Feature flag error:', error);
  // Fall back to safe behavior
}

Performance Considerations

Feature checks are designed to be fast and lightweight
Use in-memory storage for high-performance scenarios
Database providers automatically create tables and handle upserts efficiently
Consider connection pooling for SQL database-backed storage in production
DynamoDB provides automatic scaling and low-latency access
Implement caching for frequently accessed database-backed feature flags
Consider the frequency of feature flag evaluations in hot code paths
DynamoDB pay-per-request billing is cost-effective for most feature flag workloads

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

Changelog

See CHANGELOG.md for a detailed list of changes.

Made with ❤️ by Maxence Guyonvarho

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
.github		.github
packages/fanion		packages/fanion
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
SECURITY.md		SECURITY.md
biome.json		biome.json
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml

mgvdev/fanion

Folders and files

Latest commit

History

Repository files navigation

Fanion 🏁

Features

Quick Start

Installation

Basic Usage

Context-Based Feature Flags

Using Storage Providers

Using Database Storage

Using DynamoDB Storage

API Reference

FeatureManager

define<T>(flagName: string, check?: (context: T) => boolean | Promise<boolean>)

defineAndStore(flagName: string, defaultValue: boolean = true)

featureManagerWithDatabase(config: { store: FeatureStorageProvider })

initStore(): Promise<void>

active<T>(flagName: string, context?: T): Promise<boolean>

Storage Providers

In-Memory Driver

SQL Database Driver (Knex)

DynamoDB Driver

Custom Storage Provider

Utilities

generateFeatureName(context: string, flag: string, subFlag?: string)

Advanced Usage

A/B Testing

Gradual Rollouts

Environment-Based Flags

Complex Business Logic

Error Handling

Best Practices

1. Use Descriptive Names

2. Implement Fallbacks

3. Type Your Contexts

4. Keep Checks Simple

Framework Integration

Express.js

Next.js

Database Schemas

SQL Databases (Knex Driver)

DynamoDB

Migration from In-Memory to Database Storage

Best Practices for Database Storage

1. Use Database Storage for Administrative Flags

2. Use Code-Based Flags for Complex Logic

3. Connection Management

4. Error Handling in Production

Performance Considerations

Contributing

License

Changelog

About

Resources

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Contributors 2

Uh oh!

Languages

`define<T>(flagName: string, check?: (context: T) => boolean | Promise<boolean>)`

`defineAndStore(flagName: string, defaultValue: boolean = true)`

`featureManagerWithDatabase(config: { store: FeatureStorageProvider })`

`initStore(): Promise<void>`

`active<T>(flagName: string, context?: T): Promise<boolean>`

`generateFeatureName(context: string, flag: string, subFlag?: string)`

Packages