@lssm/lib.feature-flags 0.0.0-canary-20251217054315 → 0.0.0-canary-20251217060433

package/dist/docs/feature-flags.docblock.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/docs/index.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/entities/index.d.ts

@@ -0,0 +1,200 @@
+import * as _lssm_lib_schema257 from "@lssm/lib.schema";
+import { ModuleSchemaContribution } from "@lssm/lib.schema";
+
+//#region src/entities/index.d.ts
+/**
+ * Feature flag status enum.
+ */
+declare const FlagStatusEnum: _lssm_lib_schema257.EntityEnumDef;
+/**
+ * Targeting rule operator enum.
+ */
+declare const RuleOperatorEnum: _lssm_lib_schema257.EntityEnumDef;
+/**
+ * Experiment status enum.
+ */
+declare const ExperimentStatusEnum: _lssm_lib_schema257.EntityEnumDef;
+/**
+ * FeatureFlag entity - defines a feature flag.
+ */
+declare const FeatureFlagEntity: _lssm_lib_schema257.EntitySpec<{
+  id: _lssm_lib_schema257.EntityScalarField;
+  key: _lssm_lib_schema257.EntityScalarField;
+  name: _lssm_lib_schema257.EntityScalarField;
+  description: _lssm_lib_schema257.EntityScalarField;
+  status: _lssm_lib_schema257.EntityEnumField;
+  defaultValue: _lssm_lib_schema257.EntityScalarField;
+  variants: _lssm_lib_schema257.EntityScalarField;
+  orgId: _lssm_lib_schema257.EntityScalarField;
+  tags: _lssm_lib_schema257.EntityScalarField;
+  metadata: _lssm_lib_schema257.EntityScalarField;
+  createdAt: _lssm_lib_schema257.EntityScalarField;
+  updatedAt: _lssm_lib_schema257.EntityScalarField;
+  targetingRules: _lssm_lib_schema257.EntityRelationField;
+  experiments: _lssm_lib_schema257.EntityRelationField;
+  evaluations: _lssm_lib_schema257.EntityRelationField;
+}>;
+/**
+ * FlagTargetingRule entity - conditions for targeting.
+ */
+declare const FlagTargetingRuleEntity: _lssm_lib_schema257.EntitySpec<{
+  id: _lssm_lib_schema257.EntityScalarField;
+  flagId: _lssm_lib_schema257.EntityScalarField;
+  name: _lssm_lib_schema257.EntityScalarField;
+  priority: _lssm_lib_schema257.EntityScalarField;
+  enabled: _lssm_lib_schema257.EntityScalarField;
+  attribute: _lssm_lib_schema257.EntityScalarField;
+  operator: _lssm_lib_schema257.EntityEnumField;
+  value: _lssm_lib_schema257.EntityScalarField;
+  rolloutPercentage: _lssm_lib_schema257.EntityScalarField;
+  serveValue: _lssm_lib_schema257.EntityScalarField;
+  serveVariant: _lssm_lib_schema257.EntityScalarField;
+  createdAt: _lssm_lib_schema257.EntityScalarField;
+  updatedAt: _lssm_lib_schema257.EntityScalarField;
+  flag: _lssm_lib_schema257.EntityRelationField;
+}>;
+/**
+ * Experiment entity - A/B test configuration.
+ */
+declare const ExperimentEntity: _lssm_lib_schema257.EntitySpec<{
+  id: _lssm_lib_schema257.EntityScalarField;
+  key: _lssm_lib_schema257.EntityScalarField;
+  name: _lssm_lib_schema257.EntityScalarField;
+  description: _lssm_lib_schema257.EntityScalarField;
+  hypothesis: _lssm_lib_schema257.EntityScalarField;
+  flagId: _lssm_lib_schema257.EntityScalarField;
+  status: _lssm_lib_schema257.EntityEnumField;
+  variants: _lssm_lib_schema257.EntityScalarField;
+  metrics: _lssm_lib_schema257.EntityScalarField;
+  audiencePercentage: _lssm_lib_schema257.EntityScalarField;
+  audienceFilter: _lssm_lib_schema257.EntityScalarField;
+  scheduledStartAt: _lssm_lib_schema257.EntityScalarField;
+  scheduledEndAt: _lssm_lib_schema257.EntityScalarField;
+  startedAt: _lssm_lib_schema257.EntityScalarField;
+  endedAt: _lssm_lib_schema257.EntityScalarField;
+  winningVariant: _lssm_lib_schema257.EntityScalarField;
+  results: _lssm_lib_schema257.EntityScalarField;
+  orgId: _lssm_lib_schema257.EntityScalarField;
+  createdAt: _lssm_lib_schema257.EntityScalarField;
+  updatedAt: _lssm_lib_schema257.EntityScalarField;
+  flag: _lssm_lib_schema257.EntityRelationField;
+  assignments: _lssm_lib_schema257.EntityRelationField;
+}>;
+/**
+ * ExperimentAssignment entity - tracks which variant a subject is assigned to.
+ */
+declare const ExperimentAssignmentEntity: _lssm_lib_schema257.EntitySpec<{
+  id: _lssm_lib_schema257.EntityScalarField;
+  experimentId: _lssm_lib_schema257.EntityScalarField;
+  subjectType: _lssm_lib_schema257.EntityScalarField;
+  subjectId: _lssm_lib_schema257.EntityScalarField;
+  variant: _lssm_lib_schema257.EntityScalarField;
+  bucket: _lssm_lib_schema257.EntityScalarField;
+  context: _lssm_lib_schema257.EntityScalarField;
+  assignedAt: _lssm_lib_schema257.EntityScalarField;
+  experiment: _lssm_lib_schema257.EntityRelationField;
+}>;
+/**
+ * FlagEvaluation entity - evaluation log for analytics.
+ */
+declare const FlagEvaluationEntity: _lssm_lib_schema257.EntitySpec<{
+  id: _lssm_lib_schema257.EntityScalarField;
+  flagId: _lssm_lib_schema257.EntityScalarField;
+  flagKey: _lssm_lib_schema257.EntityScalarField;
+  subjectType: _lssm_lib_schema257.EntityScalarField;
+  subjectId: _lssm_lib_schema257.EntityScalarField;
+  result: _lssm_lib_schema257.EntityScalarField;
+  variant: _lssm_lib_schema257.EntityScalarField;
+  matchedRuleId: _lssm_lib_schema257.EntityScalarField;
+  reason: _lssm_lib_schema257.EntityScalarField;
+  context: _lssm_lib_schema257.EntityScalarField;
+  evaluatedAt: _lssm_lib_schema257.EntityScalarField;
+  flag: _lssm_lib_schema257.EntityRelationField;
+}>;
+/**
+ * All feature flag entities for schema composition.
+ */
+declare const featureFlagEntities: (_lssm_lib_schema257.EntitySpec<{
+  id: _lssm_lib_schema257.EntityScalarField;
+  key: _lssm_lib_schema257.EntityScalarField;
+  name: _lssm_lib_schema257.EntityScalarField;
+  description: _lssm_lib_schema257.EntityScalarField;
+  status: _lssm_lib_schema257.EntityEnumField;
+  defaultValue: _lssm_lib_schema257.EntityScalarField;
+  variants: _lssm_lib_schema257.EntityScalarField;
+  orgId: _lssm_lib_schema257.EntityScalarField;
+  tags: _lssm_lib_schema257.EntityScalarField;
+  metadata: _lssm_lib_schema257.EntityScalarField;
+  createdAt: _lssm_lib_schema257.EntityScalarField;
+  updatedAt: _lssm_lib_schema257.EntityScalarField;
+  targetingRules: _lssm_lib_schema257.EntityRelationField;
+  experiments: _lssm_lib_schema257.EntityRelationField;
+  evaluations: _lssm_lib_schema257.EntityRelationField;
+}> | _lssm_lib_schema257.EntitySpec<{
+  id: _lssm_lib_schema257.EntityScalarField;
+  flagId: _lssm_lib_schema257.EntityScalarField;
+  name: _lssm_lib_schema257.EntityScalarField;
+  priority: _lssm_lib_schema257.EntityScalarField;
+  enabled: _lssm_lib_schema257.EntityScalarField;
+  attribute: _lssm_lib_schema257.EntityScalarField;
+  operator: _lssm_lib_schema257.EntityEnumField;
+  value: _lssm_lib_schema257.EntityScalarField;
+  rolloutPercentage: _lssm_lib_schema257.EntityScalarField;
+  serveValue: _lssm_lib_schema257.EntityScalarField;
+  serveVariant: _lssm_lib_schema257.EntityScalarField;
+  createdAt: _lssm_lib_schema257.EntityScalarField;
+  updatedAt: _lssm_lib_schema257.EntityScalarField;
+  flag: _lssm_lib_schema257.EntityRelationField;
+}> | _lssm_lib_schema257.EntitySpec<{
+  id: _lssm_lib_schema257.EntityScalarField;
+  key: _lssm_lib_schema257.EntityScalarField;
+  name: _lssm_lib_schema257.EntityScalarField;
+  description: _lssm_lib_schema257.EntityScalarField;
+  hypothesis: _lssm_lib_schema257.EntityScalarField;
+  flagId: _lssm_lib_schema257.EntityScalarField;
+  status: _lssm_lib_schema257.EntityEnumField;
+  variants: _lssm_lib_schema257.EntityScalarField;
+  metrics: _lssm_lib_schema257.EntityScalarField;
+  audiencePercentage: _lssm_lib_schema257.EntityScalarField;
+  audienceFilter: _lssm_lib_schema257.EntityScalarField;
+  scheduledStartAt: _lssm_lib_schema257.EntityScalarField;
+  scheduledEndAt: _lssm_lib_schema257.EntityScalarField;
+  startedAt: _lssm_lib_schema257.EntityScalarField;
+  endedAt: _lssm_lib_schema257.EntityScalarField;
+  winningVariant: _lssm_lib_schema257.EntityScalarField;
+  results: _lssm_lib_schema257.EntityScalarField;
+  orgId: _lssm_lib_schema257.EntityScalarField;
+  createdAt: _lssm_lib_schema257.EntityScalarField;
+  updatedAt: _lssm_lib_schema257.EntityScalarField;
+  flag: _lssm_lib_schema257.EntityRelationField;
+  assignments: _lssm_lib_schema257.EntityRelationField;
+}> | _lssm_lib_schema257.EntitySpec<{
+  id: _lssm_lib_schema257.EntityScalarField;
+  experimentId: _lssm_lib_schema257.EntityScalarField;
+  subjectType: _lssm_lib_schema257.EntityScalarField;
+  subjectId: _lssm_lib_schema257.EntityScalarField;
+  variant: _lssm_lib_schema257.EntityScalarField;
+  bucket: _lssm_lib_schema257.EntityScalarField;
+  context: _lssm_lib_schema257.EntityScalarField;
+  assignedAt: _lssm_lib_schema257.EntityScalarField;
+  experiment: _lssm_lib_schema257.EntityRelationField;
+}> | _lssm_lib_schema257.EntitySpec<{
+  id: _lssm_lib_schema257.EntityScalarField;
+  flagId: _lssm_lib_schema257.EntityScalarField;
+  flagKey: _lssm_lib_schema257.EntityScalarField;
+  subjectType: _lssm_lib_schema257.EntityScalarField;
+  subjectId: _lssm_lib_schema257.EntityScalarField;
+  result: _lssm_lib_schema257.EntityScalarField;
+  variant: _lssm_lib_schema257.EntityScalarField;
+  matchedRuleId: _lssm_lib_schema257.EntityScalarField;
+  reason: _lssm_lib_schema257.EntityScalarField;
+  context: _lssm_lib_schema257.EntityScalarField;
+  evaluatedAt: _lssm_lib_schema257.EntityScalarField;
+  flag: _lssm_lib_schema257.EntityRelationField;
+}>)[];
+/**
+ * Module schema contribution for feature flags.
+ */
+declare const featureFlagsSchemaContribution: ModuleSchemaContribution;
+//#endregion
+export { ExperimentAssignmentEntity, ExperimentEntity, ExperimentStatusEnum, FeatureFlagEntity, FlagEvaluationEntity, FlagStatusEnum, FlagTargetingRuleEntity, RuleOperatorEnum, featureFlagEntities, featureFlagsSchemaContribution };

package/dist/evaluation/index.d.ts

@@ -0,0 +1,162 @@
+//#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>;
+}
+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;
+}
+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;
+}
+interface ExperimentVariant {
+  key: string;
+  name: string;
+  percentage: number;
+}
+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';
+/**
+ * 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;
+/**
+ * Get subject identifier from context for consistent hashing.
+ */
+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>;
+}
+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;
+}
+/**
+ * Feature flag evaluator.
+ *
+ * Evaluates flags based on:
+ * 1. Flag status (OFF/ON/GRADUAL)
+ * 2. Targeting rules (in priority order)
+ * 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;
+}
+/**
+ * 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;
+}
+//#endregion
+export { EvaluationContext, EvaluationLogger, EvaluationReason, EvaluationResult, Experiment, ExperimentVariant, FeatureFlag, FlagEvaluator, FlagEvaluatorOptions, FlagRepository, InMemoryFlagRepository, RuleOperator, TargetingRule, VariantConfig, evaluateRuleCondition, getSubjectId, hashToBucket };