featurefly 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { FeatureFlagsClient } from './shared/client';
+export { InMemoryCache } from './shared/cache';
+export { ConsoleLogger } from './shared/logger';
+export { CircuitBreaker, CircuitOpenError } from './shared/circuit-breaker';
+export { EventEmitter } from './shared/event-emitter';
+export { withRetry } from './shared/retry';
+export { EdgeEvaluator } from './shared/edge-evaluator';
+export { FlagStreamClient } from './shared/streaming';
+export { evaluateRules, evaluateRule } from './shared/targeting';
+export { isInRollout, getHashBucket } from './shared/rollout';
+export { assignVariation } from './shared/experiment';
+export { ImpactMetrics } from './shared/metrics';
+export type { FeatureFlag, WorkspaceFeatureFlag, FlagValue, FlagValueType, CreateFlagData, UpdateFlagData, SetWorkspaceFlagData, EvaluationContext, EvaluationReason, FeatureFlagEvaluation, BatchEvaluation, FeatureFlagStats, FeatureFlagsConfig, RetryConfig, CircuitBreakerConfig, LogLevel, ILogger, FeatureFlyEvent, EventHandler, EventPayloadMap, FlagEvaluatedPayload, FlagChangedPayload, RequestFailedPayload, CircuitStatePayload, TargetingOperator, TargetingCondition, TargetingRule, RolloutConfig, Variation, Experiment, ExperimentAssignment, TrackingCallback, StreamingConfig, FlagDocument, } from './shared/types';
+export type { MetricsSnapshot, FlagMetric, ExperimentMetric, } from './shared/metrics';

package/dist/index.js

@@ -0,0 +1,22 @@
+// ═══════════════════════════════════════════════════════════════════════════════
+// FeatureFly - Framework-Agnostic Feature Flags SDK
+// ═══════════════════════════════════════════════════════════════════════════════
+// Core client
+export { FeatureFlagsClient } from './shared/client';
+// Cache
+export { InMemoryCache } from './shared/cache';
+// Logger
+export { ConsoleLogger } from './shared/logger';
+// Circuit Breaker
+export { CircuitBreaker, CircuitOpenError } from './shared/circuit-breaker';
+// Event Emitter
+export { EventEmitter } from './shared/event-emitter';
+// Retry
+export { withRetry } from './shared/retry';
+// New Advanced Modules
+export { EdgeEvaluator } from './shared/edge-evaluator';
+export { FlagStreamClient } from './shared/streaming';
+export { evaluateRules, evaluateRule } from './shared/targeting';
+export { isInRollout, getHashBucket } from './shared/rollout';
+export { assignVariation } from './shared/experiment';
+export { ImpactMetrics } from './shared/metrics';

package/dist/react/index.d.ts

@@ -0,0 +1,54 @@
+import { type ReactNode } from 'react';
+import type { FeatureFlagsClient } from '../shared/client';
+import type { EvaluationContext, FlagValue } from '../shared/types';
+/**
+ * Provider component that makes the FeatureFlagsClient available to all hooks.
+ *
+ * @example
+ * ```tsx
+ * <FeatureFlyProvider client={client}>
+ *   <App />
+ * </FeatureFlyProvider>
+ * ```
+ */
+export declare function FeatureFlyProvider({ client, children, }: {
+    client: FeatureFlagsClient;
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<FeatureFlagsClient | null>>;
+export interface UseFeatureFlagResult<T> {
+    value: T;
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * React hook for evaluating a single feature flag.
+ * Automatically re-evaluates when the flag changes via streaming or cache invalidation.
+ *
+ * @param slug Flag slug identifier
+ * @param defaultValue Default value while loading
+ * @param context Optional evaluation context
+ *
+ * @example
+ * ```tsx
+ * const { value, loading } = useFeatureFlag('new-checkout', false);
+ *
+ * if (loading) return <Spinner />;
+ * return value ? <NewCheckout /> : <LegacyCheckout />;
+ * ```
+ */
+export declare function useFeatureFlag<T extends FlagValue = boolean>(slug: string, defaultValue: T, context?: EvaluationContext): UseFeatureFlagResult<T>;
+export interface UseAllFlagsResult {
+    flags: Record<string, FlagValue>;
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * React hook for batch-evaluating all feature flags.
+ *
+ * @example
+ * ```tsx
+ * const { flags, loading } = useAllFlags({ workspaceId: 'ws-123' });
+ * if (flags['dark-mode']) { ... }
+ * ```
+ */
+export declare function useAllFlags(context?: EvaluationContext): UseAllFlagsResult;

package/dist/react/index.js

@@ -0,0 +1,126 @@
+// ═══════════════════════════════════════════════════════════════════════════════
+// FeatureFly — React Hooks
+// ═══════════════════════════════════════════════════════════════════════════════
+//
+// Thin wrapper providing React hooks for FeatureFly SDK.
+// Requires React 18+ (useSyncExternalStore).
+//
+// Usage:
+//   import { FeatureFlyProvider, useFeatureFlag, useAllFlags } from 'featurefly/react';
+//
+// ═══════════════════════════════════════════════════════════════════════════════
+import { createContext, useContext, useState, useEffect, useCallback, useMemo, createElement, } from 'react';
+// ─── Context ────────────────────────────────────────────────────────────────────
+const FeatureFlyContext = createContext(null);
+/**
+ * Provider component that makes the FeatureFlagsClient available to all hooks.
+ *
+ * @example
+ * ```tsx
+ * <FeatureFlyProvider client={client}>
+ *   <App />
+ * </FeatureFlyProvider>
+ * ```
+ */
+export function FeatureFlyProvider({ client, children, }) {
+    return createElement(FeatureFlyContext.Provider, { value: client }, children);
+}
+function useClient() {
+    const client = useContext(FeatureFlyContext);
+    if (!client) {
+        throw new Error('useFeatureFlag must be used within a <FeatureFlyProvider>. ' +
+            'Wrap your component tree with <FeatureFlyProvider client={client}>.');
+    }
+    return client;
+}
+/**
+ * React hook for evaluating a single feature flag.
+ * Automatically re-evaluates when the flag changes via streaming or cache invalidation.
+ *
+ * @param slug Flag slug identifier
+ * @param defaultValue Default value while loading
+ * @param context Optional evaluation context
+ *
+ * @example
+ * ```tsx
+ * const { value, loading } = useFeatureFlag('new-checkout', false);
+ *
+ * if (loading) return <Spinner />;
+ * return value ? <NewCheckout /> : <LegacyCheckout />;
+ * ```
+ */
+export function useFeatureFlag(slug, defaultValue, context) {
+    const client = useClient();
+    const [value, setValue] = useState(defaultValue);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    // Memoize context to avoid infinite re-renders
+    const contextKey = useMemo(() => JSON.stringify(context ?? {}), [context?.userId, context?.workspaceId, context?.attributes]);
+    const evaluate = useCallback(async () => {
+        try {
+            setLoading(true);
+            const result = await client.evaluateFlag(slug, context);
+            setValue(result);
+            setError(null);
+        }
+        catch (e) {
+            setError(e instanceof Error ? e : new Error(String(e)));
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client, slug, contextKey]);
+    // Initial evaluation
+    useEffect(() => {
+        evaluate();
+    }, [evaluate]);
+    // Re-evaluate on stream updates or flag changes
+    useEffect(() => {
+        const unsubs = [];
+        unsubs.push(client.on('flagsUpdated', () => evaluate()));
+        unsubs.push(client.on('flagChanged', (payload) => {
+            if (payload.slug === slug)
+                evaluate();
+        }));
+        return () => unsubs.forEach((u) => u());
+    }, [client, slug, evaluate]);
+    return { value, loading, error };
+}
+/**
+ * React hook for batch-evaluating all feature flags.
+ *
+ * @example
+ * ```tsx
+ * const { flags, loading } = useAllFlags({ workspaceId: 'ws-123' });
+ * if (flags['dark-mode']) { ... }
+ * ```
+ */
+export function useAllFlags(context) {
+    const client = useClient();
+    const [flags, setFlags] = useState({});
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const contextKey = useMemo(() => JSON.stringify(context ?? {}), [context?.userId, context?.workspaceId, context?.attributes]);
+    const evaluate = useCallback(async () => {
+        try {
+            setLoading(true);
+            const result = await client.evaluateAllFlags(context);
+            setFlags(result);
+            setError(null);
+        }
+        catch (e) {
+            setError(e instanceof Error ? e : new Error(String(e)));
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client, contextKey]);
+    useEffect(() => {
+        evaluate();
+    }, [evaluate]);
+    useEffect(() => {
+        const unsub = client.on('flagsUpdated', () => evaluate());
+        return () => unsub();
+    }, [client, evaluate]);
+    return { flags, loading, error };
+}

package/dist/shared/cache.d.ts

@@ -0,0 +1,40 @@
+/**
+ * In-memory cache with TTL expiration and automatic cleanup.
+ *
+ * Uses a wrapper object `{ hit: true, value: T }` pattern internally
+ * to correctly handle falsy values (false, 0, '', null).
+ */
+export declare class InMemoryCache {
+    private readonly store;
+    private readonly ttlMs;
+    private cleanupTimer;
+    constructor(ttlMs?: number);
+    /**
+     * Get a cached value. Returns `{ hit: true, value }` if found and not expired,
+     * or `{ hit: false }` otherwise. This avoids ambiguity with falsy values.
+     */
+    get<T>(key: string): {
+        hit: true;
+        value: T;
+    } | {
+        hit: false;
+    };
+    /**
+     * Check if a key exists AND is not expired.
+     */
+    has(key: string): boolean;
+    set<T>(key: string, value: T): void;
+    delete(key: string): boolean;
+    clear(): void;
+    getStats(): {
+        size: number;
+        keys: string[];
+        enabled: boolean;
+    };
+    /**
+     * Release the cleanup timer. Call this when the client is being disposed
+     * to prevent memory leaks and dangling timers.
+     */
+    destroy(): void;
+    private cleanup;
+}

package/dist/shared/cache.js

@@ -0,0 +1,80 @@
+/**
+ * In-memory cache with TTL expiration and automatic cleanup.
+ *
+ * Uses a wrapper object `{ hit: true, value: T }` pattern internally
+ * to correctly handle falsy values (false, 0, '', null).
+ */
+export class InMemoryCache {
+    constructor(ttlMs = 60000) {
+        this.store = new Map();
+        this.cleanupTimer = null;
+        this.ttlMs = ttlMs;
+        if (ttlMs > 0) {
+            this.cleanupTimer = setInterval(() => this.cleanup(), Math.max(ttlMs, 30000));
+        }
+    }
+    // ─── Read ────────────────────────────────────────────────────────────────────
+    /**
+     * Get a cached value. Returns `{ hit: true, value }` if found and not expired,
+     * or `{ hit: false }` otherwise. This avoids ambiguity with falsy values.
+     */
+    get(key) {
+        if (this.ttlMs <= 0)
+            return { hit: false };
+        const entry = this.store.get(key);
+        if (!entry)
+            return { hit: false };
+        if (Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return { hit: false };
+        }
+        return { hit: true, value: entry.value };
+    }
+    /**
+     * Check if a key exists AND is not expired.
+     */
+    has(key) {
+        return this.get(key).hit;
+    }
+    // ─── Write ───────────────────────────────────────────────────────────────────
+    set(key, value) {
+        if (this.ttlMs <= 0)
+            return;
+        this.store.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+    }
+    delete(key) {
+        return this.store.delete(key);
+    }
+    clear() {
+        this.store.clear();
+    }
+    // ─── Stats ───────────────────────────────────────────────────────────────────
+    getStats() {
+        return {
+            size: this.store.size,
+            keys: Array.from(this.store.keys()),
+            enabled: this.ttlMs > 0,
+        };
+    }
+    // ─── Lifecycle ───────────────────────────────────────────────────────────────
+    /**
+     * Release the cleanup timer. Call this when the client is being disposed
+     * to prevent memory leaks and dangling timers.
+     */
+    destroy() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        this.store.clear();
+    }
+    // ─── Internal ────────────────────────────────────────────────────────────────
+    cleanup() {
+        const now = Date.now();
+        for (const [key, entry] of this.store.entries()) {
+            if (now > entry.expiresAt) {
+                this.store.delete(key);
+            }
+        }
+    }
+}

package/dist/shared/circuit-breaker.d.ts

@@ -0,0 +1,46 @@
+import { ILogger } from './types';
+export type CircuitState = 'closed' | 'open' | 'half-open';
+export interface CircuitBreakerOptions {
+    failureThreshold: number;
+    resetTimeoutMs: number;
+    logger: ILogger;
+    onStateChange?: (state: CircuitState, failures: number) => void;
+}
+/**
+ * Circuit breaker to prevent cascading failures when the feature flag API is down.
+ *
+ * States:
+ *  - CLOSED: Requests pass through. Failures increment counter.
+ *  - OPEN:   Requests are rejected immediately. After resetTimeoutMs, transitions to HALF-OPEN.
+ *  - HALF-OPEN: One probe request is allowed. Success → CLOSED, failure → OPEN.
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failures;
+    private lastFailureTime;
+    private readonly options;
+    constructor(options: CircuitBreakerOptions);
+    getState(): CircuitState;
+    getFailures(): number;
+    /**
+     * Execute a function through the circuit breaker.
+     * If the circuit is open, throws immediately.
+     * If the circuit is half-open, allows one probe request.
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Manually reset the circuit to closed state.
+     */
+    reset(): void;
+    private onSuccess;
+    private onFailure;
+    private shouldAttemptReset;
+    private transitionTo;
+}
+/**
+ * Error thrown when the circuit breaker is open and rejecting requests.
+ */
+export declare class CircuitOpenError extends Error {
+    readonly name = "CircuitOpenError";
+    constructor(message: string);
+}

package/dist/shared/circuit-breaker.js

@@ -0,0 +1,90 @@
+/**
+ * Circuit breaker to prevent cascading failures when the feature flag API is down.
+ *
+ * States:
+ *  - CLOSED: Requests pass through. Failures increment counter.
+ *  - OPEN:   Requests are rejected immediately. After resetTimeoutMs, transitions to HALF-OPEN.
+ *  - HALF-OPEN: One probe request is allowed. Success → CLOSED, failure → OPEN.
+ */
+export class CircuitBreaker {
+    constructor(options) {
+        this.state = 'closed';
+        this.failures = 0;
+        this.lastFailureTime = 0;
+        this.options = options;
+    }
+    getState() {
+        return this.state;
+    }
+    getFailures() {
+        return this.failures;
+    }
+    /**
+     * Execute a function through the circuit breaker.
+     * If the circuit is open, throws immediately.
+     * If the circuit is half-open, allows one probe request.
+     */
+    async execute(fn) {
+        if (this.state === 'open') {
+            if (this.shouldAttemptReset()) {
+                this.transitionTo('half-open');
+            }
+            else {
+                throw new CircuitOpenError(`Circuit breaker is OPEN. ${this.failures} consecutive failures. ` +
+                    `Will retry after ${new Date(this.lastFailureTime + this.options.resetTimeoutMs).toISOString()}`);
+            }
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure();
+            throw error;
+        }
+    }
+    /**
+     * Manually reset the circuit to closed state.
+     */
+    reset() {
+        this.transitionTo('closed');
+        this.failures = 0;
+        this.lastFailureTime = 0;
+    }
+    // ─── Internal ────────────────────────────────────────────────────────────────
+    onSuccess() {
+        if (this.state === 'half-open' || this.failures > 0) {
+            this.failures = 0;
+            this.transitionTo('closed');
+        }
+    }
+    onFailure() {
+        this.failures++;
+        this.lastFailureTime = Date.now();
+        if (this.failures >= this.options.failureThreshold) {
+            this.transitionTo('open');
+        }
+    }
+    shouldAttemptReset() {
+        return Date.now() - this.lastFailureTime >= this.options.resetTimeoutMs;
+    }
+    transitionTo(newState) {
+        if (this.state === newState)
+            return;
+        const oldState = this.state;
+        this.state = newState;
+        this.options.logger.info(`Circuit breaker: ${oldState} → ${newState} (failures: ${this.failures})`);
+        this.options.onStateChange?.(newState, this.failures);
+    }
+}
+/**
+ * Error thrown when the circuit breaker is open and rejecting requests.
+ */
+export class CircuitOpenError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CircuitOpenError';
+        Object.setPrototypeOf(this, CircuitOpenError.prototype);
+    }
+}

package/dist/shared/client.d.ts

@@ -0,0 +1,153 @@
+import { FeatureFlag, WorkspaceFeatureFlag, CreateFlagData, UpdateFlagData, FeatureFlagStats, FeatureFlagsConfig, FlagValue, EvaluationContext, FeatureFlyEvent, EventHandler } from './types';
+import { MetricsSnapshot } from './metrics';
+/**
+ * FeatureFly SDK Client
+ *
+ * Framework-agnostic feature flags client with:
+ * - In-memory caching with TTL
+ * - Retry with exponential backoff + jitter
+ * - Circuit breaker for resilience
+ * - Typed event system
+ * - Local overrides for dev/testing
+ * - Fallback defaults for graceful degradation
+ * - Multi-type flag values (boolean, string, number, JSON)
+ *
+ * @example
+ * ```ts
+ * const client = new FeatureFlagsClient({
+ *   baseUrl: 'https://api.example.com',
+ *   apiKey: 'your-key',
+ * });
+ *
+ * const isEnabled = await client.evaluateFlag('new-feature', { workspaceId: '123' });
+ * ```
+ */
+export declare class FeatureFlagsClient {
+    private readonly http;
+    private readonly cache;
+    private readonly circuitBreaker;
+    private readonly events;
+    private readonly logger;
+    private readonly retryConfig;
+    private readonly localOverrides;
+    private readonly fallbackDefaults;
+    private readonly previousValues;
+    private streamClient?;
+    private edgeEvaluator?;
+    private readonly metrics;
+    private disposed;
+    constructor(config: FeatureFlagsConfig);
+    /**
+     * Start or resume the SSE streaming connection.
+     */
+    startStreaming(): void;
+    /**
+     * Stop the SSE streaming connection.
+     */
+    stopStreaming(): void;
+    /**
+     * Fetch a full FlagDocument from the API to initialize Edge Evaluation mode.
+     * If streaming is enabled, updates will auto-refresh the document.
+     */
+    loadEdgeDocument(): Promise<void>;
+    private refreshEdgeDocument;
+    /**
+     * Subscribe to SDK events.
+     * @returns Unsubscribe function
+     */
+    on<E extends FeatureFlyEvent>(event: E, handler: EventHandler<E>): () => void;
+    /**
+     * Subscribe to an event once.
+     */
+    once<E extends FeatureFlyEvent>(event: E, handler: EventHandler<E>): () => void;
+    /**
+     * Evaluate a single flag. Returns the flag value.
+     *
+     * Resolution order:
+     * 1. Local overrides (dev/testing)
+     * 2. Cache hit
+     * 3. Remote API call
+     * 4. Fallback defaults
+     */
+    evaluateFlag<T extends FlagValue = boolean>(slug: string, context?: EvaluationContext): Promise<T>;
+    /**
+     * Evaluate all flags in a single batch request.
+     */
+    evaluateAllFlags(context?: EvaluationContext): Promise<Record<string, FlagValue>>;
+    createFlag(data: CreateFlagData): Promise<FeatureFlag>;
+    getAllFlags(): Promise<FeatureFlag[]>;
+    getFlagById(id: string): Promise<FeatureFlag | null>;
+    getFlagBySlug(slug: string): Promise<FeatureFlag | null>;
+    updateFlag(id: string, data: UpdateFlagData): Promise<FeatureFlag>;
+    deleteFlag(id: string): Promise<void>;
+    setWorkspaceFlag(slug: string, workspaceId: string, value: FlagValue): Promise<WorkspaceFeatureFlag>;
+    removeWorkspaceFlag(slug: string, workspaceId: string): Promise<void>;
+    getWorkspaceFlags(workspaceId: string): Promise<WorkspaceFeatureFlag[]>;
+    getFlagStats(): Promise<FeatureFlagStats>;
+    getFlagsByCategory(category: 'frontend' | 'backend' | 'both'): Promise<FeatureFlag[]>;
+    getFlagsByTargetService(serviceName: string): Promise<FeatureFlag[]>;
+    /**
+     * Set a local override for a flag. Overrides skip HTTP entirely.
+     * Useful for development and testing.
+     */
+    setLocalOverride(slug: string, value: FlagValue): void;
+    /**
+     * Remove a local override.
+     */
+    removeLocalOverride(slug: string): void;
+    /**
+     * Get all local overrides.
+     */
+    getLocalOverrides(): Record<string, FlagValue>;
+    /**
+     * Clear all local overrides.
+     */
+    clearLocalOverrides(): void;
+    /**
+     * Clear all cached data.
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics.
+     */
+    getCacheStats(): {
+        size: number;
+        keys: string[];
+        enabled: boolean;
+    };
+    /**
+     * Get current circuit breaker state.
+     */
+    getCircuitBreakerState(): {
+        state: string;
+        failures: number;
+    };
+    /**
+     * Reset the circuit breaker to closed state.
+     */
+    resetCircuitBreaker(): void;
+    /**
+     * Check if the client has been disposed.
+     */
+    isDisposed(): boolean;
+    /**
+     * Get a snapshot of all collected impact metrics.
+     * Includes per-flag evaluation counts, cache hit rates, latency percentiles,
+     * and experiment exposure counts.
+     */
+    getImpactMetrics(): MetricsSnapshot;
+    /**
+     * Reset all collected impact metrics counters.
+     */
+    resetMetrics(): void;
+    /**
+     * Dispose the client, releasing all resources (timers, listeners, metrics).
+     * After calling dispose, the client cannot be used again.
+     */
+    dispose(): void;
+    private fetchWithResiliency;
+    private buildCacheKey;
+    private detectChange;
+    private emitEvaluated;
+    private assertNotDisposed;
+}