@weaverslab/feature-flags/README.md

Feature flags for CodeWeavers

# @weaverslab/feature-flags

A robust feature flag management service for CodeWeavers applications. This library provides a simple and efficient way to manage feature flags in your application with PostgreSQL support and real-time updates.

## Features

-  🚀 Real-time feature flag updates using PostgreSQL notifications
-  💾 LRU caching for improved performance
-  🔄 Event-based updates for seamless flag changes
-  📦 TypeScript support
-  🔒 Type-safe API

## Installation

```bash
npm install @weaverslab/feature-flags
# or
yarn add @weaverslab/feature-flags
# or
pnpm add @weaverslab/feature-flags
```

## Prerequisites

-  PostgreSQL database
-  Node.js 14 or higher
-  TypeScript (for TypeScript projects)

## Configuration

1. Set up your environment variables:

   ```env
   DATABASE_URL=postgresql://user:password@localhost:5432/database
   ```

2. Create the required database table:

   ```sql
   CREATE TABLE hub_feature_flag (
     name VARCHAR(255) PRIMARY KEY,
     enabled BOOLEAN NOT NULL DEFAULT false
   );
   ```

3. Set up the notification trigger in PostgreSQL:

   ```sql
   CREATE OR REPLACE FUNCTION notify_feature_flag_changes()
   RETURNS trigger AS $$
   BEGIN
     PERFORM pg_notify('feature_flag_changes', NEW.name);
     RETURN NEW;
   END;
   $$ LANGUAGE plpgsql;

   CREATE TRIGGER feature_flag_changes_trigger
   AFTER UPDATE ON hub_feature_flag
   FOR EACH ROW
   EXECUTE FUNCTION notify_feature_flag_changes();
   ```

## Usage

```typescript
import { FeatureFlagService } from '@weaverslab/feature-flags'

// Initialize the service
const featureFlags = new FeatureFlagService()

// Check if a feature is enabled
if (featureFlags.isEnabled('my-feature')) {
   // Feature is enabled
   console.log('Feature is active!')
}

// Listen for feature flag updates
featureFlags.onUpdate(() => {
   console.log('Feature flags have been updated!')
})

// Set database URL programmatically (optional)
FeatureFlagService.setDatabaseUrl('postgresql://user:password@localhost:5432/database')
```

## API Reference

### `FeatureFlagService`

The main class for managing feature flags.

#### Methods

-  `isEnabled(flagName: string): boolean`

   -  Checks if a specific feature flag is enabled
   -  Returns `false` if the flag doesn't exist

-  `onUpdate(callback: () => void): void`

   -  Registers a callback to be called when feature flags are updated

-  `static setDatabaseUrl(url: string): void`
   -  Sets the database URL programmatically

## Database Schema

The library expects a PostgreSQL table with the following structure:

```sql
CREATE TABLE hub_feature_flag (
  name VARCHAR(255) PRIMARY KEY,
  enabled BOOLEAN NOT NULL DEFAULT false
);
```

## Performance Considerations

-  The library uses an LRU cache with a maximum of 100 entries and a TTL of 60 seconds
-  Real-time updates are handled through PostgreSQL notifications
-  Database connections are managed efficiently using connection pooling

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT © CodeWeavers