evaluate function
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);
}
}