admin
9bf56a806b
Relocate the ~6k-file docs tree from the repo root into plugins/document-navigator/docs/ so the plugin is self-contained and portable. docs/superpowers/ (specs and plans) stays at the repo root. Moved via cp+rm rather than git mv because directory rename() fails with EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the identical-content files at commit time. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@suaveplan/feature-flags - Provider-agnostic feature flag evaluation with typed flag values, strategy chains, and deterministic bucketing
Summary
Provider-agnostic feature flag evaluation engine for controlling feature rollout without code deploys. The package ships a FlagManager high-level façade, a FlagRegistry backed by any pluggable FlagProvider, and an Evaluator strategy chain. Five composable strategies cover the full rollout playbook: PercentageStrategy (deterministic FNV-1a bucketing for consistent user cohorts), UserTargetStrategy (allowlist), AttributeStrategy (10 comparison operators for segment targeting), ScheduleStrategy (time-window gating), and CompositeStrategy (AND/OR combinator). Built-in providers include MemoryProvider and JsonProvider for file-based flag definitions. Evaluation priority is: flag disabled → in-process override → first matching strategy → default value. This package is for runtime flag evaluation only — it is not a flag management UI or remote config service.
Documentation tree
- evaluator — (no submodules)
- evaluator — (no submodules)
- manager — (no submodules)
- flag-manager — (no submodules)
- registry — (no submodules)
- flag-registry — (no submodules)
- errors — (no submodules)
- feature-flags-error — (no submodules)
- json — (no submodules)
- json — (no submodules)
- memory — (no submodules)
- memory — (no submodules)
- attribute — (no submodules)
- attribute — (no submodules)
- composite — (no submodules)
- composite — (no submodules)
- percentage — (no submodules)
- percentage — (no submodules)
- schedule — (no submodules)
- schedule — (no submodules)
- user-target — (no submodules)
- user-target — (no submodules)
- types — (no submodules)
- common — (no submodules)
- utils — (no submodules)
- hash — (no submodules)
Overview
@suaveplan/feature-flags provides a complete, enterprise-grade feature flag system with:
FlagManager— high-level façade for flag access (isEnabled,getString, etc.)FlagRegistry— typed registry backed by a pluggableFlagProviderEvaluator— strategy chain engine with OTel metrics- Strategies —
PercentageStrategy,UserTargetStrategy,AttributeStrategy,ScheduleStrategy,CompositeStrategy - Providers —
MemoryProvider,JsonProvider - Deterministic bucketing — FNV-1a 32-bit hash for stable percentage rollouts
Installation
bun add @suaveplan/feature-flags
Quick Start
import { FlagManager, FlagRegistry, Evaluator, MemoryProvider, PercentageStrategy } from '@suaveplan/feature-flags';
const provider = new MemoryProvider([
{ key: 'dark-mode', type: 'boolean', defaultValue: false },
{ key: 'checkout-variant', type: 'string', defaultValue: 'v1' },
]);
const registry = new FlagRegistry({ provider });
const evaluator = new Evaluator({
strategies: [new PercentageStrategy({ percentage: 20, value: true })],
});
const manager = new FlagManager({ registry, evaluator });
// Type-safe accessors
const enabled = manager.isEnabled('dark-mode', { userId: 'user-42' });
const variant = manager.getString('checkout-variant', { userId: 'user-42' });
// In-process overrides (for testing)
manager.setOverride('dark-mode', true);
manager.clearAllOverrides();
Module Map
| Subpath | Contents | Docs |
|---|---|---|
. |
All public exports | This file |
./strategies |
All five strategy classes | percentage-strategy · user-target · attribute · schedule · composite |
./providers |
MemoryProvider, JsonProvider |
memory-provider · json-provider |
./registry |
FlagRegistry |
flag-registry |
./evaluator |
Evaluator |
evaluator |
./manager |
FlagManager |
flag-manager |
./errors |
FeatureFlagsError, FEATURE_FLAGS_CODES |
feature-flags-error |
Evaluation Priority
flag.enabled === false→DISABLED(default value returned)- In-process override present →
OVERRIDE - First matching strategy →
STRATEGY - No match →
DEFAULT