@contractspec/lib.feature-flags 1.56.1 → 1.58.0

package/dist/evaluation/index.d.ts

@@ -1,109 +1,108 @@
-//#region src/evaluation/index.d.ts
 /**
  * Feature flag evaluation engine.
  *
  * Provides deterministic evaluation of feature flags based on targeting rules
  * and experiment assignments.
  */
-interface EvaluationContext {
-  /** User identifier */
-  userId?: string;
-  /** Organization identifier */
-  orgId?: string;
-  /** User's plan (free, pro, enterprise, etc.) */
-  plan?: string;
-  /** User segment or cohort */
-  segment?: string;
-  /** Session identifier for anonymous users */
-  sessionId?: string;
-  /** Additional custom attributes */
-  attributes?: Record<string, unknown>;
+export interface EvaluationContext {
+    /** User identifier */
+    userId?: string;
+    /** Organization identifier */
+    orgId?: string;
+    /** User's plan (free, pro, enterprise, etc.) */
+    plan?: string;
+    /** User segment or cohort */
+    segment?: string;
+    /** Session identifier for anonymous users */
+    sessionId?: string;
+    /** Additional custom attributes */
+    attributes?: Record<string, unknown>;
 }
-interface FeatureFlag {
-  id: string;
-  key: string;
-  status: 'OFF' | 'ON' | 'GRADUAL';
-  defaultValue: boolean;
-  variants?: VariantConfig[];
+export interface FeatureFlag {
+    id: string;
+    key: string;
+    status: 'OFF' | 'ON' | 'GRADUAL';
+    defaultValue: boolean;
+    variants?: VariantConfig[];
 }
-interface TargetingRule {
-  id: string;
-  priority: number;
-  enabled: boolean;
-  attribute: string;
-  operator: RuleOperator;
-  value: unknown;
-  rolloutPercentage?: number;
-  serveValue?: boolean;
-  serveVariant?: string;
+export interface TargetingRule {
+    id: string;
+    priority: number;
+    enabled: boolean;
+    attribute: string;
+    operator: RuleOperator;
+    value: unknown;
+    rolloutPercentage?: number;
+    serveValue?: boolean;
+    serveVariant?: string;
 }
-interface Experiment {
-  id: string;
-  key: string;
-  status: 'DRAFT' | 'RUNNING' | 'PAUSED' | 'COMPLETED' | 'CANCELLED';
-  variants: ExperimentVariant[];
-  audiencePercentage: number;
-  audienceFilter?: Record<string, unknown>;
+export interface Experiment {
+    id: string;
+    key: string;
+    status: 'DRAFT' | 'RUNNING' | 'PAUSED' | 'COMPLETED' | 'CANCELLED';
+    variants: ExperimentVariant[];
+    audiencePercentage: number;
+    audienceFilter?: Record<string, unknown>;
 }
-interface VariantConfig {
-  key: string;
-  name: string;
-  description?: string;
-  weight?: number;
+export interface VariantConfig {
+    key: string;
+    name: string;
+    description?: string;
+    weight?: number;
 }
-interface ExperimentVariant {
-  key: string;
-  name: string;
-  percentage: number;
+export interface ExperimentVariant {
+    key: string;
+    name: string;
+    percentage: number;
 }
-interface EvaluationResult {
-  enabled: boolean;
-  variant?: string;
-  reason: EvaluationReason;
-  ruleId?: string;
-  experimentId?: string;
+export interface EvaluationResult {
+    enabled: boolean;
+    variant?: string;
+    reason: EvaluationReason;
+    ruleId?: string;
+    experimentId?: string;
 }
-type EvaluationReason = 'FLAG_OFF' | 'FLAG_ON' | 'DEFAULT_VALUE' | 'RULE_MATCH' | 'PERCENTAGE_ROLLOUT' | 'EXPERIMENT_VARIANT' | 'FLAG_NOT_FOUND';
-type RuleOperator = 'EQ' | 'NEQ' | 'IN' | 'NIN' | 'CONTAINS' | 'NOT_CONTAINS' | 'GT' | 'GTE' | 'LT' | 'LTE' | 'PERCENTAGE';
+export type EvaluationReason = 'FLAG_OFF' | 'FLAG_ON' | 'DEFAULT_VALUE' | 'RULE_MATCH' | 'PERCENTAGE_ROLLOUT' | 'EXPERIMENT_VARIANT' | 'FLAG_NOT_FOUND';
+export type RuleOperator = 'EQ' | 'NEQ' | 'IN' | 'NIN' | 'CONTAINS' | 'NOT_CONTAINS' | 'GT' | 'GTE' | 'LT' | 'LTE' | 'PERCENTAGE';
 /**
  * Simple hash function for consistent bucketing.
  * Uses a deterministic algorithm so the same input always produces the same bucket.
  */
-declare function hashToBucket(value: string, seed?: string): number;
+export declare function hashToBucket(value: string, seed?: string): number;
 /**
  * Get subject identifier from context for consistent hashing.
  */
-declare function getSubjectId(context: EvaluationContext): string;
+export declare function getSubjectId(context: EvaluationContext): string;
 /**
  * Evaluate a single targeting rule condition.
  */
-declare function evaluateRuleCondition(rule: TargetingRule, context: EvaluationContext): boolean;
-interface FlagRepository {
-  getFlag(key: string, orgId?: string): Promise<FeatureFlag | null>;
-  getRules(flagId: string): Promise<TargetingRule[]>;
-  getActiveExperiment(flagId: string): Promise<Experiment | null>;
-  getExperimentAssignment(experimentId: string, subjectType: string, subjectId: string): Promise<string | null>;
-  saveExperimentAssignment(experimentId: string, subjectType: string, subjectId: string, variant: string, bucket: number): Promise<void>;
+export declare function evaluateRuleCondition(rule: TargetingRule, context: EvaluationContext): boolean;
+export interface FlagRepository {
+    getFlag(key: string, orgId?: string): Promise<FeatureFlag | null>;
+    getRules(flagId: string): Promise<TargetingRule[]>;
+    getActiveExperiment(flagId: string): Promise<Experiment | null>;
+    getExperimentAssignment(experimentId: string, subjectType: string, subjectId: string): Promise<string | null>;
+    saveExperimentAssignment(experimentId: string, subjectType: string, subjectId: string, variant: string, bucket: number): Promise<void>;
 }
-interface EvaluationLogger {
-  log(evaluation: {
-    flagId: string;
-    flagKey: string;
-    subjectType: string;
-    subjectId: string;
-    result: boolean;
-    variant?: string;
-    reason: string;
-    ruleId?: string;
-    experimentId?: string;
-    context?: EvaluationContext;
-  }): void;
+export interface EvaluationLogger {
+    log(evaluation: {
+        flagId: string;
+        flagKey: string;
+        subjectType: string;
+        subjectId: string;
+        result: boolean;
+        variant?: string;
+        reason: string;
+        ruleId?: string;
+        experimentId?: string;
+        context?: EvaluationContext;
+    }): void;
 }
-interface FlagEvaluatorOptions {
-  repository: FlagRepository;
-  logger?: EvaluationLogger;
-  /** Whether to log evaluations (default: false for performance) */
-  logEvaluations?: boolean;
+export interface FlagEvaluatorOptions {
+    repository: FlagRepository;
+    logger?: EvaluationLogger;
+    /** Whether to log evaluations (default: false for performance) */
+    logEvaluations?: boolean;
 }
 /**
  * Feature flag evaluator.
@@ -114,50 +113,48 @@ interface FlagEvaluatorOptions {
  * 3. Experiments (if running)
  * 4. Default value (fallback)
  */
-declare class FlagEvaluator {
-  private repository;
-  private logger?;
-  private logEvaluations;
-  constructor(options: FlagEvaluatorOptions);
-  /**
-   * Evaluate a feature flag.
-   */
-  evaluate(key: string, context: EvaluationContext): Promise<EvaluationResult>;
-  /**
-   * Evaluate experiment and assign variant.
-   */
-  private evaluateExperiment;
-  /**
-   * Assign a variant based on bucket and variant percentages.
-   */
-  private assignVariant;
-  /**
-   * Create evaluation result.
-   */
-  private makeResult;
-  /**
-   * Log evaluation and return result.
-   */
-  private logAndReturn;
+export declare class FlagEvaluator {
+    private repository;
+    private logger?;
+    private logEvaluations;
+    constructor(options: FlagEvaluatorOptions);
+    /**
+     * Evaluate a feature flag.
+     */
+    evaluate(key: string, context: EvaluationContext): Promise<EvaluationResult>;
+    /**
+     * Evaluate experiment and assign variant.
+     */
+    private evaluateExperiment;
+    /**
+     * Assign a variant based on bucket and variant percentages.
+     */
+    private assignVariant;
+    /**
+     * Create evaluation result.
+     */
+    private makeResult;
+    /**
+     * Log evaluation and return result.
+     */
+    private logAndReturn;
 }
 /**
  * In-memory flag repository for testing and development.
  */
-declare class InMemoryFlagRepository implements FlagRepository {
-  private flags;
-  private rules;
-  private experiments;
-  private assignments;
-  addFlag(flag: FeatureFlag): void;
-  addRule(flagId: string, rule: TargetingRule): void;
-  addExperiment(experiment: Experiment, flagId: string): void;
-  getFlag(key: string): Promise<FeatureFlag | null>;
-  getRules(flagId: string): Promise<TargetingRule[]>;
-  getActiveExperiment(flagId: string): Promise<Experiment | null>;
-  getExperimentAssignment(experimentId: string, subjectType: string, subjectId: string): Promise<string | null>;
-  saveExperimentAssignment(experimentId: string, subjectType: string, subjectId: string, variant: string): Promise<void>;
-  clear(): void;
+export declare class InMemoryFlagRepository implements FlagRepository {
+    private flags;
+    private rules;
+    private experiments;
+    private assignments;
+    addFlag(flag: FeatureFlag): void;
+    addRule(flagId: string, rule: TargetingRule): void;
+    addExperiment(experiment: Experiment, flagId: string): void;
+    getFlag(key: string): Promise<FeatureFlag | null>;
+    getRules(flagId: string): Promise<TargetingRule[]>;
+    getActiveExperiment(flagId: string): Promise<Experiment | null>;
+    getExperimentAssignment(experimentId: string, subjectType: string, subjectId: string): Promise<string | null>;
+    saveExperimentAssignment(experimentId: string, subjectType: string, subjectId: string, variant: string): Promise<void>;
+    clear(): void;
 }
-//#endregion
-export { EvaluationContext, EvaluationLogger, EvaluationReason, EvaluationResult, Experiment, ExperimentVariant, FeatureFlag, FlagEvaluator, FlagEvaluatorOptions, FlagRepository, InMemoryFlagRepository, RuleOperator, TargetingRule, VariantConfig, evaluateRuleCondition, getSubjectId, hashToBucket };
 //# sourceMappingURL=index.d.ts.map

package/dist/evaluation/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/evaluation/index.ts"],"sourcesContent":[],"mappings":";;AASA;AAeA;AAQA;AAYA;AASA;AAOiB,UAnDA,iBAAA,CAmDiB;EAMjB;EAQL,MAAA,CAAA,EAAA,MAAA;EASA;EAmBI,KAAA,CAAA,EAAA,MAAA;EAeA;EASA,IAAA,CAAA,EAAA,MAAA;EAwFC;EAC+B,OAAA,CAAA,EAAA,MAAA;EAAR;EACJ,SAAA,CAAA,EAAA,MAAA;EAAR;EACmB,UAAA,CAAA,EApMhC,MAoMgC,CAAA,MAAA,EAAA,OAAA,CAAA;;AAK1C,UAtMY,WAAA,CAsMZ;EAOA,EAAA,EAAA,MAAA;EAAO,GAAA,EAAA,MAAA;EAGK,MAAA,EAAA,KAAA,GAAA,IAAgB,GAAA,SAWnB;EAIG,YAAA,EAAA,OAAA;EAgBJ,QAAA,CAAA,EA1OA,aA0Oa,EAAA;;AAgBb,UAvPI,aAAA,CAuPJ;EACA,EAAA,EAAA,MAAA;EAAR,QAAA,EAAA,MAAA;EAAO,OAAA,EAAA,OAAA;EAsMC,SAAA,EAAA,MAAA;EAMG,QAAA,EA/bJ,YA+bI;EAIgB,KAAA,EAAA,OAAA;EAMJ,iBAAA,CAAA,EAAA,MAAA;EAIU,UAAA,CAAA,EAAA,OAAA;EAAR,YAAA,CAAA,EAAA,MAAA;;AAII,UA1cjB,UAAA,CA0ciB;EAImB,EAAA,EAAA,MAAA;EAAR,GAAA,EAAA,MAAA;EAQxC,MAAA,EAAA,OAAA,GAAA,SAAA,GAAA,QAAA,GAAA,WAAA,GAAA,WAAA;EAUA,QAAA,EA5dO,iBA4dP,EAAA;EA9C0C,kBAAA,EAAA,MAAA;EAAc,cAAA,CAAA,EA5a1C,MA4a0C,CAAA,MAAA,EAAA,OAAA,CAAA;;UAza5C,aAAA;;;;;;UAOA,iBAAA;;;;;UAMA,gBAAA;;;UAGP;;;;KAKE,gBAAA;KASA,YAAA;;;;;iBAmBI,YAAA;;;;iBAeA,YAAA,UAAsB;;;;iBAStB,qBAAA,OACR,wBACG;UAsFM,cAAA;wCACuB,QAAQ;4BACpB,QAAQ;uCACG,QAAQ;yFAK1C;2HAOA;;UAGY,gBAAA;;;;;;;;;;;cAWH;;;UAIG,oBAAA;cACH;WACH;;;;;;;;;;;;;cAcE,aAAA;;;;uBAKU;;;;iCAWV,oBACR,QAAQ;;;;;;;;;;;;;;;;;;;;;cAsMA,sBAAA,YAAkC;;;;;gBAM/B;gCAIgB;4BAMJ;wBAIE,QAAQ;4BAIJ,QAAQ;uCAIG,QAAQ;yFAQhD;2GAUA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/evaluation/index.ts"],"names":[],"mappings":"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"}