@contractspec/lib.feature-flags 1.57.0 → 1.59.0

package/dist/node/docs/index.js

@@ -0,0 +1,71 @@
+// src/docs/feature-flags.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var featureFlagsDocBlocks = [
+  {
+    id: "docs.feature-flags.overview",
+    title: "Feature Flags & Experiments",
+    summary: "Reusable, spec-first feature flag and experiment module with targeting, gradual rollout, multivariate variants, and evaluation logging.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/feature-flags/overview",
+    tags: ["feature-flags", "experiments", "progressive-delivery"],
+    body: `## What this module provides
+
+- **Entities**: FeatureFlag, FlagTargetingRule, Experiment, ExperimentAssignment, FlagEvaluation.
+- **Contracts**: create/update/delete/toggle/list/get flags; create/delete rules; evaluate flags; create/start/stop/get experiments.
+- **Events**: flag.created/updated/deleted/toggled, rule.created/deleted, experiment.created/started/stopped, flag.evaluated, experiment.variant_assigned.
+- **Evaluation Engine**: Deterministic evaluator with gradual rollout, rule priority, audience filters, and experiment bucketing.
+
+## How to use
+
+1) Compose schema
+ - Add \`featureFlagsSchemaContribution\` to your module composition.
+
+2) Register contracts/events
+ - Import exports from \`@contractspec/lib.feature-flags\` into your spec registry.
+
+3) Evaluate at runtime
+ - Instantiate \`FlagEvaluator\` with a repository implementation and optional logger.
+ - Evaluate with context attributes (userId, orgId, plan, segment, sessionId, attributes).
+
+4) Wire observability
+ - Emit audit trail on config changes; emit \`flag.evaluated\` for analytics.
+
+## Usage example
+
+${"```"}ts
+import {
+  FlagEvaluator,
+  InMemoryFlagRepository,
+} from '@contractspec/lib.feature-flags';
+
+const repo = new InMemoryFlagRepository();
+repo.addFlag({
+  id: 'flag-1',
+  key: 'new_dashboard',
+  status: 'GRADUAL',
+  defaultValue: false,
+});
+
+const evaluator = new FlagEvaluator({ repository: repo });
+const result = await evaluator.evaluate('new_dashboard', {
+  userId: 'user-123',
+  orgId: 'org-456',
+  plan: 'pro',
+});
+
+if (result.enabled) {
+  // serve the new dashboard
+}
+${"```"},
+
+## Guardrails
+
+- Keep flag keys stable and human-readable; avoid PII in context.
+- Ensure experiments’ variant percentages sum to 100; default flag status to OFF.
+- Use org-scoped flags for multi-tenant isolation.
+- Log evaluations only when needed to control volume; prefer sampling for noisy paths.
+`
+  }
+];
+registerDocBlocks(featureFlagsDocBlocks);

package/dist/node/entities/index.js

@@ -0,0 +1,306 @@
+// src/entities/index.ts
+import {
+  defineEntity,
+  defineEntityEnum,
+  field,
+  index
+} from "@contractspec/lib.schema";
+var FlagStatusEnum = defineEntityEnum({
+  name: "FlagStatus",
+  values: ["OFF", "ON", "GRADUAL"],
+  schema: "lssm_feature_flags",
+  description: "Status of a feature flag."
+});
+var RuleOperatorEnum = defineEntityEnum({
+  name: "RuleOperator",
+  values: [
+    "EQ",
+    "NEQ",
+    "IN",
+    "NIN",
+    "CONTAINS",
+    "NOT_CONTAINS",
+    "GT",
+    "GTE",
+    "LT",
+    "LTE",
+    "PERCENTAGE"
+  ],
+  schema: "lssm_feature_flags",
+  description: "Operator for targeting rule conditions."
+});
+var ExperimentStatusEnum = defineEntityEnum({
+  name: "ExperimentStatus",
+  values: ["DRAFT", "RUNNING", "PAUSED", "COMPLETED", "CANCELLED"],
+  schema: "lssm_feature_flags",
+  description: "Status of an experiment."
+});
+var FeatureFlagEntity = defineEntity({
+  name: "FeatureFlag",
+  description: "A feature flag for controlling feature availability.",
+  schema: "lssm_feature_flags",
+  map: "feature_flag",
+  fields: {
+    id: field.id({ description: "Unique flag identifier" }),
+    key: field.string({
+      isUnique: true,
+      description: "Flag key (e.g., new_dashboard)"
+    }),
+    name: field.string({ description: "Human-readable name" }),
+    description: field.string({
+      isOptional: true,
+      description: "Description of the flag"
+    }),
+    status: field.enum("FlagStatus", {
+      default: "OFF",
+      description: "Flag status"
+    }),
+    defaultValue: field.boolean({
+      default: false,
+      description: "Default value when no rules match"
+    }),
+    variants: field.json({
+      isOptional: true,
+      description: "Variant definitions for multivariate flags"
+    }),
+    orgId: field.string({
+      isOptional: true,
+      description: "Organization scope (null = global)"
+    }),
+    tags: field.json({
+      isOptional: true,
+      description: "Tags for categorization"
+    }),
+    metadata: field.json({
+      isOptional: true,
+      description: "Additional metadata"
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    targetingRules: field.hasMany("FlagTargetingRule"),
+    experiments: field.hasMany("Experiment"),
+    evaluations: field.hasMany("FlagEvaluation")
+  },
+  indexes: [index.on(["orgId", "key"]), index.on(["status"])],
+  enums: [FlagStatusEnum]
+});
+var FlagTargetingRuleEntity = defineEntity({
+  name: "FlagTargetingRule",
+  description: "A targeting rule for conditional flag evaluation.",
+  schema: "lssm_feature_flags",
+  map: "flag_targeting_rule",
+  fields: {
+    id: field.id({ description: "Unique rule identifier" }),
+    flagId: field.foreignKey({ description: "Parent feature flag" }),
+    name: field.string({
+      isOptional: true,
+      description: "Rule name for debugging"
+    }),
+    priority: field.int({
+      default: 0,
+      description: "Rule priority (lower = higher priority)"
+    }),
+    enabled: field.boolean({
+      default: true,
+      description: "Whether rule is active"
+    }),
+    attribute: field.string({
+      description: "Target attribute (userId, orgId, plan, segment, etc.)"
+    }),
+    operator: field.enum("RuleOperator", {
+      description: "Comparison operator"
+    }),
+    value: field.json({ description: "Target value(s)" }),
+    rolloutPercentage: field.int({
+      isOptional: true,
+      description: "Percentage for gradual rollout (0-100)"
+    }),
+    serveValue: field.boolean({
+      isOptional: true,
+      description: "Boolean value to serve"
+    }),
+    serveVariant: field.string({
+      isOptional: true,
+      description: "Variant key to serve (for multivariate)"
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    flag: field.belongsTo("FeatureFlag", ["flagId"], ["id"], {
+      onDelete: "Cascade"
+    })
+  },
+  indexes: [index.on(["flagId", "priority"]), index.on(["attribute"])],
+  enums: [RuleOperatorEnum]
+});
+var ExperimentEntity = defineEntity({
+  name: "Experiment",
+  description: "An A/B test experiment.",
+  schema: "lssm_feature_flags",
+  map: "experiment",
+  fields: {
+    id: field.id({ description: "Unique experiment identifier" }),
+    key: field.string({ isUnique: true, description: "Experiment key" }),
+    name: field.string({ description: "Human-readable name" }),
+    description: field.string({
+      isOptional: true,
+      description: "Experiment description"
+    }),
+    hypothesis: field.string({
+      isOptional: true,
+      description: "Experiment hypothesis"
+    }),
+    flagId: field.foreignKey({ description: "Associated feature flag" }),
+    status: field.enum("ExperimentStatus", {
+      default: "DRAFT",
+      description: "Experiment status"
+    }),
+    variants: field.json({
+      description: "Variant definitions with split ratios"
+    }),
+    metrics: field.json({ isOptional: true, description: "Metrics to track" }),
+    audiencePercentage: field.int({
+      default: 100,
+      description: "Percentage of audience to include"
+    }),
+    audienceFilter: field.json({
+      isOptional: true,
+      description: "Audience filter criteria"
+    }),
+    scheduledStartAt: field.dateTime({
+      isOptional: true,
+      description: "Scheduled start time"
+    }),
+    scheduledEndAt: field.dateTime({
+      isOptional: true,
+      description: "Scheduled end time"
+    }),
+    startedAt: field.dateTime({
+      isOptional: true,
+      description: "Actual start time"
+    }),
+    endedAt: field.dateTime({
+      isOptional: true,
+      description: "Actual end time"
+    }),
+    winningVariant: field.string({
+      isOptional: true,
+      description: "Declared winning variant"
+    }),
+    results: field.json({
+      isOptional: true,
+      description: "Experiment results summary"
+    }),
+    orgId: field.string({
+      isOptional: true,
+      description: "Organization scope"
+    }),
+    createdAt: field.createdAt(),
+    updatedAt: field.updatedAt(),
+    flag: field.belongsTo("FeatureFlag", ["flagId"], ["id"], {
+      onDelete: "Cascade"
+    }),
+    assignments: field.hasMany("ExperimentAssignment")
+  },
+  indexes: [
+    index.on(["status"]),
+    index.on(["orgId", "status"]),
+    index.on(["flagId"])
+  ],
+  enums: [ExperimentStatusEnum]
+});
+var ExperimentAssignmentEntity = defineEntity({
+  name: "ExperimentAssignment",
+  description: "Tracks experiment variant assignments.",
+  schema: "lssm_feature_flags",
+  map: "experiment_assignment",
+  fields: {
+    id: field.id({ description: "Unique assignment identifier" }),
+    experimentId: field.foreignKey({ description: "Parent experiment" }),
+    subjectType: field.string({
+      description: "Subject type (user, org, session)"
+    }),
+    subjectId: field.string({ description: "Subject identifier" }),
+    variant: field.string({ description: "Assigned variant key" }),
+    bucket: field.int({ description: "Hash bucket (0-99)" }),
+    context: field.json({
+      isOptional: true,
+      description: "Context at assignment time"
+    }),
+    assignedAt: field.dateTime({ description: "Assignment timestamp" }),
+    experiment: field.belongsTo("Experiment", ["experimentId"], ["id"], {
+      onDelete: "Cascade"
+    })
+  },
+  indexes: [
+    index.unique(["experimentId", "subjectType", "subjectId"], {
+      name: "experiment_assignment_unique"
+    }),
+    index.on(["subjectType", "subjectId"])
+  ]
+});
+var FlagEvaluationEntity = defineEntity({
+  name: "FlagEvaluation",
+  description: "Log of flag evaluations for debugging and analytics.",
+  schema: "lssm_feature_flags",
+  map: "flag_evaluation",
+  fields: {
+    id: field.id({ description: "Unique evaluation identifier" }),
+    flagId: field.foreignKey({ description: "Evaluated flag" }),
+    flagKey: field.string({
+      description: "Flag key (denormalized for queries)"
+    }),
+    subjectType: field.string({
+      description: "Subject type (user, org, anonymous)"
+    }),
+    subjectId: field.string({ description: "Subject identifier" }),
+    result: field.boolean({ description: "Evaluation result" }),
+    variant: field.string({
+      isOptional: true,
+      description: "Served variant (for multivariate)"
+    }),
+    matchedRuleId: field.string({
+      isOptional: true,
+      description: "Rule that matched (if any)"
+    }),
+    reason: field.string({
+      description: "Evaluation reason (default, rule, experiment, etc.)"
+    }),
+    context: field.json({
+      isOptional: true,
+      description: "Evaluation context"
+    }),
+    evaluatedAt: field.dateTime({ description: "Evaluation timestamp" }),
+    flag: field.belongsTo("FeatureFlag", ["flagId"], ["id"], {
+      onDelete: "Cascade"
+    })
+  },
+  indexes: [
+    index.on(["flagKey", "evaluatedAt"]),
+    index.on(["subjectType", "subjectId", "evaluatedAt"]),
+    index.on(["flagId", "evaluatedAt"])
+  ]
+});
+var featureFlagEntities = [
+  FeatureFlagEntity,
+  FlagTargetingRuleEntity,
+  ExperimentEntity,
+  ExperimentAssignmentEntity,
+  FlagEvaluationEntity
+];
+var featureFlagsSchemaContribution = {
+  moduleId: "@contractspec/lib.feature-flags",
+  entities: featureFlagEntities,
+  enums: [FlagStatusEnum, RuleOperatorEnum, ExperimentStatusEnum]
+};
+export {
+  featureFlagsSchemaContribution,
+  featureFlagEntities,
+  RuleOperatorEnum,
+  FlagTargetingRuleEntity,
+  FlagStatusEnum,
+  FlagEvaluationEntity,
+  FeatureFlagEntity,
+  ExperimentStatusEnum,
+  ExperimentEntity,
+  ExperimentAssignmentEntity
+};

package/dist/node/evaluation/index.js

@@ -0,0 +1,223 @@
+// src/evaluation/index.ts
+function hashToBucket(value, seed = "") {
+  const input = `${seed}:${value}`;
+  let hash = 0;
+  for (let i = 0;i < input.length; i++) {
+    const char = input.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash % 100);
+}
+function getSubjectId(context) {
+  return context.userId || context.sessionId || context.orgId || "anonymous";
+}
+function evaluateRuleCondition(rule, context) {
+  const attributeValue = getAttributeValue(rule.attribute, context);
+  switch (rule.operator) {
+    case "EQ":
+      return attributeValue === rule.value;
+    case "NEQ":
+      return attributeValue !== rule.value;
+    case "IN":
+      if (!Array.isArray(rule.value))
+        return false;
+      return rule.value.includes(attributeValue);
+    case "NIN":
+      if (!Array.isArray(rule.value))
+        return true;
+      return !rule.value.includes(attributeValue);
+    case "CONTAINS":
+      if (typeof attributeValue !== "string" || typeof rule.value !== "string")
+        return false;
+      return attributeValue.includes(rule.value);
+    case "NOT_CONTAINS":
+      if (typeof attributeValue !== "string" || typeof rule.value !== "string")
+        return true;
+      return !attributeValue.includes(rule.value);
+    case "GT":
+      if (typeof attributeValue !== "number" || typeof rule.value !== "number")
+        return false;
+      return attributeValue > rule.value;
+    case "GTE":
+      if (typeof attributeValue !== "number" || typeof rule.value !== "number")
+        return false;
+      return attributeValue >= rule.value;
+    case "LT":
+      if (typeof attributeValue !== "number" || typeof rule.value !== "number")
+        return false;
+      return attributeValue < rule.value;
+    case "LTE":
+      if (typeof attributeValue !== "number" || typeof rule.value !== "number")
+        return false;
+      return attributeValue <= rule.value;
+    case "PERCENTAGE":
+      return hashToBucket(getSubjectId(context), rule.attribute) < (typeof rule.value === "number" ? rule.value : 0);
+    default:
+      return false;
+  }
+}
+function getAttributeValue(attribute, context) {
+  switch (attribute) {
+    case "userId":
+      return context.userId;
+    case "orgId":
+      return context.orgId;
+    case "plan":
+      return context.plan;
+    case "segment":
+      return context.segment;
+    case "sessionId":
+      return context.sessionId;
+    default:
+      return context.attributes?.[attribute];
+  }
+}
+
+class FlagEvaluator {
+  repository;
+  logger;
+  logEvaluations;
+  constructor(options) {
+    this.repository = options.repository;
+    this.logger = options.logger;
+    this.logEvaluations = options.logEvaluations ?? false;
+  }
+  async evaluate(key, context) {
+    const orgId = context.orgId;
+    const flag = await this.repository.getFlag(key, orgId);
+    if (!flag) {
+      return this.makeResult(false, "FLAG_NOT_FOUND");
+    }
+    if (flag.status === "OFF") {
+      return this.logAndReturn(flag, context, this.makeResult(false, "FLAG_OFF"));
+    }
+    if (flag.status === "ON") {
+      return this.logAndReturn(flag, context, this.makeResult(true, "FLAG_ON"));
+    }
+    const rules = await this.repository.getRules(flag.id);
+    const sortedRules = [...rules].filter((r) => r.enabled).sort((a, b) => a.priority - b.priority);
+    for (const rule of sortedRules) {
+      if (evaluateRuleCondition(rule, context)) {
+        if (rule.rolloutPercentage !== undefined && rule.rolloutPercentage !== null) {
+          const bucket = hashToBucket(getSubjectId(context), flag.key);
+          if (bucket >= rule.rolloutPercentage) {
+            continue;
+          }
+        }
+        const enabled = rule.serveValue ?? true;
+        return this.logAndReturn(flag, context, this.makeResult(enabled, "RULE_MATCH", rule.serveVariant, rule.id));
+      }
+    }
+    const experiment = await this.repository.getActiveExperiment(flag.id);
+    if (experiment && experiment.status === "RUNNING") {
+      const result = await this.evaluateExperiment(experiment, context);
+      if (result) {
+        return this.logAndReturn(flag, context, result);
+      }
+    }
+    return this.logAndReturn(flag, context, this.makeResult(flag.defaultValue, "DEFAULT_VALUE"));
+  }
+  async evaluateExperiment(experiment, context) {
+    const subjectId = getSubjectId(context);
+    const subjectType = context.userId ? "user" : context.orgId ? "org" : "session";
+    const audienceBucket = hashToBucket(subjectId, `${experiment.key}:audience`);
+    if (audienceBucket >= experiment.audiencePercentage) {
+      return null;
+    }
+    let variant = await this.repository.getExperimentAssignment(experiment.id, subjectType, subjectId);
+    if (!variant) {
+      const variantBucket = hashToBucket(subjectId, experiment.key);
+      variant = this.assignVariant(experiment.variants, variantBucket);
+      await this.repository.saveExperimentAssignment(experiment.id, subjectType, subjectId, variant, variantBucket);
+    }
+    const enabled = variant !== "control";
+    return this.makeResult(enabled, "EXPERIMENT_VARIANT", variant, undefined, experiment.id);
+  }
+  assignVariant(variants, bucket) {
+    let cumulative = 0;
+    for (const variant of variants) {
+      cumulative += variant.percentage;
+      if (bucket < cumulative) {
+        return variant.key;
+      }
+    }
+    return variants[variants.length - 1]?.key ?? "control";
+  }
+  makeResult(enabled, reason, variant, ruleId, experimentId) {
+    return {
+      enabled,
+      variant,
+      reason,
+      ruleId,
+      experimentId
+    };
+  }
+  logAndReturn(flag, context, result) {
+    if (this.logEvaluations && this.logger) {
+      const subjectId = getSubjectId(context);
+      const subjectType = context.userId ? "user" : context.orgId ? "org" : "session";
+      this.logger.log({
+        flagId: flag.id,
+        flagKey: flag.key,
+        subjectType,
+        subjectId,
+        result: result.enabled,
+        variant: result.variant,
+        reason: result.reason,
+        ruleId: result.ruleId,
+        experimentId: result.experimentId,
+        context
+      });
+    }
+    return result;
+  }
+}
+
+class InMemoryFlagRepository {
+  flags = new Map;
+  rules = new Map;
+  experiments = new Map;
+  assignments = new Map;
+  addFlag(flag) {
+    this.flags.set(flag.key, flag);
+  }
+  addRule(flagId, rule) {
+    const existing = this.rules.get(flagId) || [];
+    existing.push(rule);
+    this.rules.set(flagId, existing);
+  }
+  addExperiment(experiment, flagId) {
+    this.experiments.set(flagId, experiment);
+  }
+  async getFlag(key) {
+    return this.flags.get(key) || null;
+  }
+  async getRules(flagId) {
+    return this.rules.get(flagId) || [];
+  }
+  async getActiveExperiment(flagId) {
+    return this.experiments.get(flagId) || null;
+  }
+  async getExperimentAssignment(experimentId, subjectType, subjectId) {
+    const key = `${experimentId}:${subjectType}:${subjectId}`;
+    return this.assignments.get(key) || null;
+  }
+  async saveExperimentAssignment(experimentId, subjectType, subjectId, variant) {
+    const key = `${experimentId}:${subjectType}:${subjectId}`;
+    this.assignments.set(key, variant);
+  }
+  clear() {
+    this.flags.clear();
+    this.rules.clear();
+    this.experiments.clear();
+    this.assignments.clear();
+  }
+}
+export {
+  hashToBucket,
+  getSubjectId,
+  evaluateRuleCondition,
+  InMemoryFlagRepository,
+  FlagEvaluator
+};