featurefly 0.1.0

package/dist/shared/edge-evaluator.js

@@ -0,0 +1,127 @@
+import { evaluateRules } from './targeting';
+import { isInRollout } from './rollout';
+import { assignVariation } from './experiment';
+/**
+ * Extracts the stickiness value from a context for a given key name.
+ */
+function getStickinessValue(context, key) {
+    if (!key)
+        return context.userId || context.workspaceId;
+    if (key === 'userId')
+        return context.userId;
+    if (key === 'workspaceId')
+        return context.workspaceId;
+    const attr = context.attributes?.[key];
+    return attr !== undefined ? String(attr) : undefined;
+}
+/**
+ * Offline / Local Evaluator Engine.
+ * Takes a pre-fetched `FlagDocument` and evaluates flags entirely in-memory
+ * without making any HTTP calls. Perfect for edge workers or serverless.
+ */
+export class EdgeEvaluator {
+    constructor(document, fallbackDefaults = {}, trackingCallback) {
+        this.flagIndex = new Map();
+        this.document = document;
+        this.fallbackDefaults = fallbackDefaults;
+        this.trackingCallback = trackingCallback;
+        this.rebuildIndex();
+    }
+    /**
+     * Update the internal document with a fresh one.
+     */
+    updateDocument(document) {
+        this.document = document;
+        this.rebuildIndex();
+    }
+    rebuildIndex() {
+        this.flagIndex.clear();
+        for (const flag of this.document.flags) {
+            this.flagIndex.set(flag.slug, flag);
+        }
+    }
+    /**
+     * Evaluate a single flag against a context.
+     */
+    evaluate(slug, context, localOverrides = {}) {
+        // 1. Local overrides always win
+        if (slug in localOverrides) {
+            return { value: localOverrides[slug], reason: 'LOCAL_OVERRIDE' };
+        }
+        const flag = this.flagIndex.get(slug);
+        // If flag doesn't exist in document, return fallback or false
+        if (!flag) {
+            if (slug in this.fallbackDefaults) {
+                return { value: this.fallbackDefaults[slug], reason: 'DEFAULT' };
+            }
+            return { value: false, reason: 'DEFAULT' };
+        }
+        // Evaluate the flag based on rules, rollout, and experiments
+        return this.evaluateInner(flag, context);
+    }
+    /**
+     * Evaluate all flags in the document at once.
+     */
+    evaluateAll(context, localOverrides = {}) {
+        const results = {};
+        for (const flag of this.document.flags) {
+            const result = this.evaluateInner(flag, context);
+            results[flag.slug] = result.value;
+        }
+        // Merge in any local overrides and fallbacks
+        return { ...this.fallbackDefaults, ...results, ...localOverrides };
+    }
+    evaluateInner(flag, context) {
+        // 2. Targeting rules
+        if (flag.targetingRules && flag.targetingRules.length > 0) {
+            // Return the value of the first matching rule
+            const ruleValue = evaluateRules(flag.targetingRules, context);
+            if (ruleValue !== null) {
+                // If the rule has a rollout percentage, evaluate it before accepting the value
+                const rule = flag.targetingRules.find(r => r.value === ruleValue);
+                if (rule && rule.rolloutPercentage !== undefined) {
+                    const key = context.userId || context.workspaceId;
+                    // Use rule ID as salt to prevent hash overlap
+                    if (isInRollout(key, { percentage: rule.rolloutPercentage, salt: rule.id })) {
+                        return { value: ruleValue, reason: 'TARGETING_MATCH' };
+                    }
+                    // If the rollout fails, we don't return the rule value. We fall through.
+                }
+                else {
+                    // No rule rollout, just standard targeting match
+                    return { value: ruleValue, reason: 'TARGETING_MATCH' };
+                }
+            }
+        }
+        // 3. Experiment Assignment (A/B testing)
+        if (flag.experiment) {
+            const assignment = assignVariation(flag.experiment, context);
+            if (assignment) {
+                // Trigger analytics callback synchronously if provided
+                if (this.trackingCallback) {
+                    try {
+                        this.trackingCallback(assignment);
+                    }
+                    catch (e) {
+                        // Ignore callback errors during evaluation
+                    }
+                }
+                return { value: assignment.value, reason: 'EXPERIMENT_ASSIGNMENT', assignment };
+            }
+        }
+        // 4. Base Gradual Rollout
+        if (flag.rollout) {
+            const key = getStickinessValue(context, flag.rollout.stickinessKey);
+            if (isInRollout(key || '', { ...flag.rollout, salt: flag.rollout.salt || flag.slug })) {
+                return { value: flag.defaultValue, reason: 'PERCENTAGE_ROLLOUT' };
+            }
+            // If flag HAS a rollout config, and user is NOT in it, they get false
+            // regardless of defaultValue (which applies to those IN the rollout).
+            // If we're returning boolean, return false. Otherwise, we can't safely 
+            // return a non-boolean default for "off". We return false as unmanaged value.
+            return { value: false, reason: 'DEFAULT' };
+        }
+        // 5. Default Base Value (if no targeting, no experiment, no rollout matched)
+        return { value: flag.defaultValue, reason: 'DEFAULT' };
+    }
+}

package/dist/shared/event-emitter.d.ts

@@ -0,0 +1,29 @@
+import { FeatureFlyEvent, EventHandler, EventPayloadMap } from './types';
+/**
+ * Typed event emitter for FeatureFly SDK.
+ * Allows consumers to subscribe to internal SDK events like flag changes,
+ * cache hits/misses, circuit breaker state changes, etc.
+ */
+export declare class EventEmitter {
+    private readonly listeners;
+    /**
+     * Subscribe to an event. Returns an unsubscribe function.
+     */
+    on<E extends FeatureFlyEvent>(event: E, handler: EventHandler<E>): () => void;
+    /**
+     * Subscribe to an event once (auto-unsubscribes after first invocation).
+     */
+    once<E extends FeatureFlyEvent>(event: E, handler: EventHandler<E>): () => void;
+    /**
+     * Emit an event to all registered listeners.
+     */
+    emit<E extends FeatureFlyEvent>(event: E, payload: EventPayloadMap[E]): void;
+    /**
+     * Remove all listeners for a specific event, or all events if no event is specified.
+     */
+    removeAllListeners(event?: FeatureFlyEvent): void;
+    /**
+     * Get the count of listeners for a given event.
+     */
+    listenerCount(event: FeatureFlyEvent): number;
+}

package/dist/shared/event-emitter.js

@@ -0,0 +1,68 @@
+/**
+ * Typed event emitter for FeatureFly SDK.
+ * Allows consumers to subscribe to internal SDK events like flag changes,
+ * cache hits/misses, circuit breaker state changes, etc.
+ */
+export class EventEmitter {
+    constructor() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.listeners = new Map();
+    }
+    /**
+     * Subscribe to an event. Returns an unsubscribe function.
+     */
+    on(event, handler) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(handler);
+        // Return unsubscribe function
+        return () => {
+            this.listeners.get(event)?.delete(handler);
+        };
+    }
+    /**
+     * Subscribe to an event once (auto-unsubscribes after first invocation).
+     */
+    once(event, handler) {
+        const wrappedHandler = (payload) => {
+            unsubscribe();
+            handler(payload);
+        };
+        const unsubscribe = this.on(event, wrappedHandler);
+        return unsubscribe;
+    }
+    /**
+     * Emit an event to all registered listeners.
+     */
+    emit(event, payload) {
+        const handlers = this.listeners.get(event);
+        if (!handlers || handlers.size === 0)
+            return;
+        for (const handler of handlers) {
+            try {
+                handler(payload);
+            }
+            catch {
+                // Swallow listener errors — SDK should never crash from user callbacks
+            }
+        }
+    }
+    /**
+     * Remove all listeners for a specific event, or all events if no event is specified.
+     */
+    removeAllListeners(event) {
+        if (event) {
+            this.listeners.delete(event);
+        }
+        else {
+            this.listeners.clear();
+        }
+    }
+    /**
+     * Get the count of listeners for a given event.
+     */
+    listenerCount(event) {
+        return this.listeners.get(event)?.size ?? 0;
+    }
+}

package/dist/shared/experiment.d.ts

@@ -0,0 +1,9 @@
+import { Experiment, EvaluationContext, ExperimentAssignment } from './types';
+/**
+ * Deterministically assigns a user to an experiment variation based on weights.
+ *
+ * @param experiment The experiment definition with variations and weights
+ * @param context The evaluation context (to extract stickiness key)
+ * @returns The assigned variation details, or null if assignment fails
+ */
+export declare function assignVariation(experiment: Experiment | undefined, context: EvaluationContext | undefined): ExperimentAssignment | null;

package/dist/shared/experiment.js

@@ -0,0 +1,51 @@
+import { getHashBucket } from './rollout';
+/**
+ * Deterministically assigns a user to an experiment variation based on weights.
+ *
+ * @param experiment The experiment definition with variations and weights
+ * @param context The evaluation context (to extract stickiness key)
+ * @returns The assigned variation details, or null if assignment fails
+ */
+export function assignVariation(experiment, context) {
+    if (!experiment || !experiment.variations || experiment.variations.length === 0) {
+        return null;
+    }
+    // Determine stickiness key. Default to userId, then workspaceId.
+    let key;
+    if (experiment.stickinessKey) {
+        if (experiment.stickinessKey === 'userId')
+            key = context?.userId;
+        else if (experiment.stickinessKey === 'workspaceId')
+            key = context?.workspaceId;
+        else
+            key = context?.attributes?.[experiment.stickinessKey];
+    }
+    else {
+        key = context?.userId || context?.workspaceId;
+    }
+    // Anonymous users (no key) cannot be deterministically assigned to A/B tests.
+    if (!key) {
+        return null;
+    }
+    // Get a bucket from 0 to 9999 (for 0.01% precision in weights)
+    const bucket = getHashBucket(key, experiment.salt || experiment.id, 10000);
+    // Find which variation range this bucket falls into.
+    // Variations have weights from 0 to 100.
+    // We scale weights to 0-10000 for matching the bucket.
+    let cumulativeWeight = 0;
+    for (const variation of experiment.variations) {
+        const scaledWeight = variation.weight * 100; // e.g., 50.5% -> 5050
+        cumulativeWeight += scaledWeight;
+        if (bucket < cumulativeWeight) {
+            return {
+                experimentId: experiment.id,
+                variationId: variation.id,
+                value: variation.value,
+                context: context || {}
+            };
+        }
+    }
+    // Fallback: This only happens if variations sum to < 100% and the bucket
+    // falls into the unassigned remaining percentage. If so, they are not in the experiment.
+    return null;
+}

package/dist/shared/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types';
+export * from './client';
+export * from './cache';
+export * from './logger';
+export * from './circuit-breaker';
+export * from './event-emitter';
+export * from './retry';

package/dist/shared/index.js

@@ -0,0 +1,7 @@
+export * from './types';
+export * from './client';
+export * from './cache';
+export * from './logger';
+export * from './circuit-breaker';
+export * from './event-emitter';
+export * from './retry';

package/dist/shared/logger.d.ts

@@ -0,0 +1,14 @@
+import { ILogger, LogLevel } from './types';
+/**
+ * Default console-based logger with level filtering.
+ * Users can replace this with any ILogger implementation (pino, winston, etc).
+ */
+export declare class ConsoleLogger implements ILogger {
+    private readonly level;
+    private readonly prefix;
+    constructor(level?: LogLevel);
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}

package/dist/shared/logger.js

@@ -0,0 +1,37 @@
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+/**
+ * Default console-based logger with level filtering.
+ * Users can replace this with any ILogger implementation (pino, winston, etc).
+ */
+export class ConsoleLogger {
+    constructor(level = 'warn') {
+        this.prefix = '[FeatureFly]';
+        this.level = LOG_LEVELS[level];
+    }
+    debug(message, ...args) {
+        if (this.level <= LOG_LEVELS.debug) {
+            console.debug(`${this.prefix} ${message}`, ...args);
+        }
+    }
+    info(message, ...args) {
+        if (this.level <= LOG_LEVELS.info) {
+            console.info(`${this.prefix} ${message}`, ...args);
+        }
+    }
+    warn(message, ...args) {
+        if (this.level <= LOG_LEVELS.warn) {
+            console.warn(`${this.prefix} ${message}`, ...args);
+        }
+    }
+    error(message, ...args) {
+        if (this.level <= LOG_LEVELS.error) {
+            console.error(`${this.prefix} ${message}`, ...args);
+        }
+    }
+}

package/dist/shared/metrics.d.ts

@@ -0,0 +1,79 @@
+import { EventEmitter } from './event-emitter';
+/**
+ * Per-flag metrics summary.
+ */
+export interface FlagMetric {
+    evaluations: number;
+    cacheHits: number;
+    cacheMisses: number;
+    changes: number;
+    lastEvaluatedAt: number;
+    latencies: number[];
+}
+/**
+ * Experiment exposure summary.
+ */
+export interface ExperimentMetric {
+    experimentId: string;
+    exposures: number;
+    variationCounts: Record<string, number>;
+}
+/**
+ * Full metrics snapshot returned by `getSnapshot()`.
+ */
+export interface MetricsSnapshot {
+    totalEvaluations: number;
+    totalCacheHits: number;
+    totalCacheMisses: number;
+    cacheHitRate: number;
+    flags: Record<string, FlagMetric>;
+    experiments: Record<string, ExperimentMetric>;
+    latency: {
+        p50: number;
+        p95: number;
+        p99: number;
+        avg: number;
+    };
+    collectedSince: number;
+}
+/**
+ * Passive impact metrics collector.
+ *
+ * Subscribes to SDK events and aggregates per-flag evaluation counts,
+ * cache hit/miss ratios, latency percentiles, change frequency,
+ * and experiment exposure counts. No network calls, no external dependencies.
+ *
+ * @example
+ * ```ts
+ * const metrics = client.getImpactMetrics();
+ * console.log(metrics.cacheHitRate);         // 0.87
+ * console.log(metrics.latency.p95);          // 12ms
+ * console.log(metrics.flags['my-flag'].evaluations); // 42
+ * ```
+ */
+export declare class ImpactMetrics {
+    private totalEvaluations;
+    private totalCacheHits;
+    private totalCacheMisses;
+    private readonly flags;
+    private readonly experiments;
+    private readonly latencies;
+    private readonly collectedSince;
+    private readonly unsubscribers;
+    constructor(events: EventEmitter);
+    /**
+     * Returns a full immutable snapshot of all collected metrics.
+     */
+    getSnapshot(): MetricsSnapshot;
+    /**
+     * Reset all collected metrics.
+     */
+    reset(): void;
+    /**
+     * Unsubscribe from all events. Called on client dispose.
+     */
+    destroy(): void;
+    private getOrCreateFlag;
+    private getOrCreateExperiment;
+    private computeLatencyPercentiles;
+}

package/dist/shared/metrics.js

@@ -0,0 +1,147 @@
+const MAX_LATENCY_SAMPLES = 1000;
+/**
+ * Passive impact metrics collector.
+ *
+ * Subscribes to SDK events and aggregates per-flag evaluation counts,
+ * cache hit/miss ratios, latency percentiles, change frequency,
+ * and experiment exposure counts. No network calls, no external dependencies.
+ *
+ * @example
+ * ```ts
+ * const metrics = client.getImpactMetrics();
+ * console.log(metrics.cacheHitRate);         // 0.87
+ * console.log(metrics.latency.p95);          // 12ms
+ * console.log(metrics.flags['my-flag'].evaluations); // 42
+ * ```
+ */
+export class ImpactMetrics {
+    constructor(events) {
+        this.totalEvaluations = 0;
+        this.totalCacheHits = 0;
+        this.totalCacheMisses = 0;
+        this.flags = new Map();
+        this.experiments = new Map();
+        this.latencies = [];
+        this.collectedSince = Date.now();
+        this.unsubscribers = [];
+        this.unsubscribers.push(events.on('flagEvaluated', (payload) => {
+            this.totalEvaluations++;
+            // Per-flag tracking
+            const metric = this.getOrCreateFlag(payload.slug);
+            metric.evaluations++;
+            metric.lastEvaluatedAt = Date.now();
+            // Latency tracking (ring buffer)
+            if (payload.durationMs !== undefined) {
+                metric.latencies.push(payload.durationMs);
+                if (metric.latencies.length > MAX_LATENCY_SAMPLES) {
+                    metric.latencies.shift();
+                }
+                this.latencies.push(payload.durationMs);
+                if (this.latencies.length > MAX_LATENCY_SAMPLES) {
+                    this.latencies.shift();
+                }
+            }
+        }));
+        this.unsubscribers.push(events.on('cacheHit', () => {
+            this.totalCacheHits++;
+        }));
+        this.unsubscribers.push(events.on('cacheMiss', () => {
+            this.totalCacheMisses++;
+        }));
+        this.unsubscribers.push(events.on('flagChanged', (payload) => {
+            const metric = this.getOrCreateFlag(payload.slug);
+            metric.changes++;
+        }));
+        this.unsubscribers.push(events.on('experimentAssigned', (payload) => {
+            const exp = this.getOrCreateExperiment(payload.experimentId);
+            exp.exposures++;
+            exp.variationCounts[payload.variationId] =
+                (exp.variationCounts[payload.variationId] || 0) + 1;
+        }));
+    }
+    /**
+     * Returns a full immutable snapshot of all collected metrics.
+     */
+    getSnapshot() {
+        const flagsRecord = {};
+        for (const [slug, metric] of this.flags) {
+            flagsRecord[slug] = { ...metric, latencies: [...metric.latencies] };
+        }
+        const experimentsRecord = {};
+        for (const [id, metric] of this.experiments) {
+            experimentsRecord[id] = { ...metric, variationCounts: { ...metric.variationCounts } };
+        }
+        const totalCacheOps = this.totalCacheHits + this.totalCacheMisses;
+        return {
+            totalEvaluations: this.totalEvaluations,
+            totalCacheHits: this.totalCacheHits,
+            totalCacheMisses: this.totalCacheMisses,
+            cacheHitRate: totalCacheOps > 0 ? this.totalCacheHits / totalCacheOps : 0,
+            flags: flagsRecord,
+            experiments: experimentsRecord,
+            latency: this.computeLatencyPercentiles(),
+            collectedSince: this.collectedSince,
+        };
+    }
+    /**
+     * Reset all collected metrics.
+     */
+    reset() {
+        this.totalEvaluations = 0;
+        this.totalCacheHits = 0;
+        this.totalCacheMisses = 0;
+        this.flags.clear();
+        this.experiments.clear();
+        this.latencies.length = 0;
+    }
+    /**
+     * Unsubscribe from all events. Called on client dispose.
+     */
+    destroy() {
+        for (const unsub of this.unsubscribers) {
+            unsub();
+        }
+        this.unsubscribers.length = 0;
+    }
+    // ─── Internal ────────────────────────────────────────────────────────────────
+    getOrCreateFlag(slug) {
+        let metric = this.flags.get(slug);
+        if (!metric) {
+            metric = {
+                evaluations: 0,
+                cacheHits: 0,
+                cacheMisses: 0,
+                changes: 0,
+                lastEvaluatedAt: 0,
+                latencies: [],
+            };
+            this.flags.set(slug, metric);
+        }
+        return metric;
+    }
+    getOrCreateExperiment(experimentId) {
+        let metric = this.experiments.get(experimentId);
+        if (!metric) {
+            metric = {
+                experimentId,
+                exposures: 0,
+                variationCounts: {},
+            };
+            this.experiments.set(experimentId, metric);
+        }
+        return metric;
+    }
+    computeLatencyPercentiles() {
+        if (this.latencies.length === 0) {
+            return { p50: 0, p95: 0, p99: 0, avg: 0 };
+        }
+        const sorted = [...this.latencies].sort((a, b) => a - b);
+        const len = sorted.length;
+        return {
+            p50: sorted[Math.floor(len * 0.5)],
+            p95: sorted[Math.floor(len * 0.95)],
+            p99: sorted[Math.floor(len * 0.99)],
+            avg: Math.round(sorted.reduce((a, b) => a + b, 0) / len * 100) / 100,
+        };
+    }
+}

package/dist/shared/retry.d.ts

@@ -0,0 +1,10 @@
+import { ILogger, RetryConfig } from './types';
+/**
+ * Retry a function with exponential backoff and jitter.
+ *
+ * @param fn        - The async function to retry
+ * @param config    - Retry configuration
+ * @param logger    - Logger for retry attempts
+ * @param onRetry   - Optional callback invoked on each retry with (attempt, error)
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, config: Partial<RetryConfig> | undefined, logger: ILogger, onRetry?: (attempt: number, error: unknown) => void): Promise<T>;

package/dist/shared/retry.js

@@ -0,0 +1,39 @@
+const DEFAULT_RETRY = {
+    maxAttempts: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 10000,
+};
+/**
+ * Retry a function with exponential backoff and jitter.
+ *
+ * @param fn        - The async function to retry
+ * @param config    - Retry configuration
+ * @param logger    - Logger for retry attempts
+ * @param onRetry   - Optional callback invoked on each retry with (attempt, error)
+ */
+export async function withRetry(fn, config = {}, logger, onRetry) {
+    const { maxAttempts, baseDelayMs, maxDelayMs } = { ...DEFAULT_RETRY, ...config };
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= maxAttempts)
+                break;
+            // Exponential backoff with jitter
+            const exponentialDelay = baseDelayMs * Math.pow(2, attempt - 1);
+            const jitter = Math.random() * baseDelayMs * 0.5;
+            const delay = Math.min(exponentialDelay + jitter, maxDelayMs);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.warn(`Request failed (attempt ${attempt}/${maxAttempts}): ${errorMessage}. Retrying in ${Math.round(delay)}ms...`);
+            onRetry?.(attempt, error);
+            await sleep(delay);
+        }
+    }
+    throw lastError;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/shared/rollout.d.ts

@@ -0,0 +1,14 @@
+import { RolloutConfig } from './types';
+/**
+ * Deterministically checks if a given key falls within a rollout percentage.
+ *
+ * @param key The stickiness key (e.g. userId)
+ * @param config Rollout configuration including percentage, salt, and bucket max
+ * @returns true if the key hashes to a bucket < percentage
+ */
+export declare function isInRollout(key: string | undefined, config: RolloutConfig | undefined): boolean;
+/**
+ * Returns a deterministic bucket number (default 0-99) for a given key and salt.
+ * Uses MurmurHash3 (32-bit).
+ */
+export declare function getHashBucket(key: string, salt?: string, buckets?: number): number;