evaluate function

Evaluation evaluate(
  1. Object? bundle,
  2. String flagKey,
  3. Map<String, Object?> ctx,
  4. Object? fallback,
)

Evaluates one flag of bundle (a parsed bundle document; null for "no configuration loaded").

Never throws: on any problem it returns fallback with reason flag_not_found or error, so callers always have an explicit default.

Implementation

Evaluation evaluate(Object? bundle, String flagKey, Map<String, Object?> ctx, Object? fallback) {
  final nullish = isNullish(bundle);
  Object? revision = 0;
  if (!nullish) {
    final r = jsGet(bundle, 'revision');
    if (!isNullish(r)) revision = r;
  }
  final trace = <TraceStep>[];
  try {
    final flag = nullish ? undefined : jsOwn(jsGet(bundle, 'flags'), flagKey);
    if (!jsTruthy(bundle) || !jsTruthy(flag)) {
      final detail = jsTruthy(bundle)
          ? 'Flag is not in this configuration. The application fallback applies.'
          : 'No configuration is loaded. The application fallback applies.';
      trace.add(TraceStep('result', 'Returned ${fmt(fallback)}', detail));
      return Evaluation(flagKey: flagKey, value: fallback, reason: Reasons.flagNotFound, revision: revision, trace: trace);
    }
    trace.add(TraceStep('config', 'Configuration loaded', jsToNumber(revision) > 0 ? 'r${jsString(revision)}' : 'draft'));
    if (!jsTruthy(jsGet(flag, 'enabled'))) {
      final off = jsGet(flag, 'off');
      trace.add(TraceStep('result', 'Returned ${fmt(off)}', 'Flag is disabled in this environment.'));
      return Evaluation(flagKey: flagKey, value: _out(off), reason: Reasons.off, revision: revision, trace: trace);
    }
    final segments = jsGet(bundle, 'segments');
    for (var i = 0;; i++) {
      final rules = jsGet(flag, 'rules');
      if (!(i < jsToNumber(jsGet(rules, 'length')))) break;
      final rule = jsGet(rules, '$i');
      final match = jsGet(rule, 'match');
      final conditions = jsGet(rule, 'conditions');
      final matched = _matchAll(match, conditions, ctx, segments, 0);
      final label = 'Rule ${'${i + 1}'.padLeft(2, '0')}';
      var summary = 'all contexts';
      if (jsTruthy(jsGet(conditions, 'length'))) {
        if (conditions is! List) throw JsTypeError('rule.conditions.map is not a function');
        summary = conditions.map(describeCondition).join(match == 'any' ? ' OR ' : ' AND ');
      }
      trace.add(TraceStep('rule', matched ? '$label matched' : '$label did not match', summary, matched));
      if (!matched) continue;
      final serve = jsGet(rule, 'serve');
      final serveType = jsGet(serve, 'type');
      final ruleId = _out(jsGet(rule, 'id'));
      if (serveType == 'fixed') {
        final value = jsGet(serve, 'value');
        trace.add(TraceStep('result', 'Returned ${fmt(value)}', '$label serves a fixed value.'));
        return Evaluation(flagKey: flagKey, value: _out(value), reason: Reasons.ruleMatch, revision: revision, trace: trace, ruleIndex: i, ruleId: ruleId);
      }
      final bucketBy = jsGet(serve, 'bucketBy');
      final attr = isNullish(bucketBy) ? 'key' : jsString(bucketBy);
      final identity = ctx.containsKey(attr) ? ctx[attr] : undefined;
      final otherwise = jsGet(serve, 'otherwise');
      if (isNullish(identity) || identity == '') {
        trace.add(TraceStep('allocation', 'Allocation skipped', 'Context has no "$attr" to bucket by; treated as outside the allocation.', false));
        trace.add(TraceStep('result', 'Returned ${fmt(otherwise)}', 'Remaining eligible users.'));
        return Evaluation(flagKey: flagKey, value: _out(otherwise), reason: Reasons.ruleMatch, revision: revision, trace: trace, ruleIndex: i, ruleId: ruleId, inRollout: false);
      }
      final seed = jsGet(serve, 'seed');
      final bucket = bucketOf(isNullish(seed) ? flagKey : jsString(seed), jsString(identity));
      final percentage = jsGet(serve, 'percentage');
      final inRollout = bucket < jsToNumber(percentage);
      final pct = jsString(percentage);
      trace.add(TraceStep('allocation', 'Allocation evaluated',
          '$pct% rollout ยท $attr ${inRollout ? 'inside' : 'outside'} allocation (bucket ${bucket.toStringAsFixed(2)})', inRollout));
      final value = inRollout ? jsGet(serve, 'value') : otherwise;
      trace.add(TraceStep('result', 'Returned ${fmt(value)}', inRollout ? 'Inside the $pct% allocation.' : 'Remaining eligible users.'));
      return Evaluation(
          flagKey: flagKey, value: _out(value), reason: Reasons.ruleMatch, revision: revision, trace: trace, ruleIndex: i, ruleId: ruleId, inRollout: inRollout, bucket: bucket);
    }
    final def = jsGet(flag, 'default');
    trace.add(TraceStep('result', 'Returned ${fmt(def)}', 'No rule matched. The flag default applies.'));
    return Evaluation(flagKey: flagKey, value: _out(def), reason: Reasons.defaultValue, revision: revision, trace: trace);
  } catch (e) {
    final error = e is JsTypeError ? e.message : e.toString();
    trace.add(TraceStep('result', 'Returned ${fmt(fallback)}', 'Evaluation error: $error. The application fallback applies.'));
    return Evaluation(flagKey: flagKey, value: fallback, reason: Reasons.error, revision: revision, trace: trace, error: error);
  }
}