@configdirector/nuxt-sdk 1.5.0 → 1.6.0

package/dist/module.json

@@ -4,5 +4,5 @@
   "compatibility": {
     "nuxt": ">=4.0.0"
   },
-  "version": "1.5.0"
+  "version": "1.6.0"
 }

package/dist/runtime/nitro/plugin.mjs

@@ -6938,9 +6938,6 @@ const equals = (value, target) => value !== null && target !== null && semver.eq
 const ordered = (value, target, compare) => value !== null && target !== null && compare(value, target);
 //#endregion
 //#region ../config-evaluator/src/render.ts
-/**
-* Rendering a resolved context value to text.
-*/
 /** A value the context does not carry. Compared as "", so a negative operator can still match. */
 const ABSENT = Symbol("absent");
 /** An attribute this SDK version does not know about. Not compared at all. */
@@ -6962,6 +6959,12 @@ const renderScalar = (value) => {
 };
 /** The raw value, for comparisons that inspect its JSON type rather than its text. */
 const unwrap = (value) => value === ABSENT ? void 0 : value;
+const resolvedTypeOf = (value) => {
+	if (value === UNKNOWN_ATTRIBUTE) return "unknown-attribute";
+	if (value === ABSENT) return "absent";
+	if (isScalar(value)) return "scalar";
+	return Array.isArray(value) ? "array" : "object";
+};
 //#endregion
 //#region ../config-evaluator/src/array-comparison.ts
 /**
@@ -6992,8 +6995,28 @@ var ConditionEvaluator = class {
 	* a condition can still match or not match on its own terms.
 	*/
 	evaluate(condition, context) {
+		return this.explain(condition, context).matched;
+	}
+	/**
+	* Decide whether a condition holds for a context, and say what the condition was compared
+	* against: the raw resolved value and its shape.
+	*/
+	explain(condition, context) {
 		const value = this.resolve(condition, context);
-		if (value === UNKNOWN_ATTRIBUTE) return false;
+		const resolvedType = resolvedTypeOf(value);
+		const resolvedValue = value === ABSENT || value === UNKNOWN_ATTRIBUTE ? void 0 : value;
+		if (value === UNKNOWN_ATTRIBUTE) return {
+			matched: false,
+			resolvedValue,
+			resolvedType
+		};
+		return {
+			matched: this.compare(condition, value),
+			resolvedValue,
+			resolvedType
+		};
+	}
+	compare(condition, value) {
 		const targetValues = condition.targetValues ?? [];
 		switch (condition.targetType) {
 			case "text": return compareText(render(value), condition.operator, targetValues);
@@ -7047,61 +7070,130 @@ var ConfigEvaluator = class {
 			id: config.id,
 			key: config.key,
 			type: config.type,
-			value: this.getConfigValue(config, context)
+			value: this.explain(config, context).value
 		};
 	}
-	getConfigValue(config, context) {
+	/**
+	* Evaluate a config for a context and record how the value was reached: every rule in the
+	* order it was walked with its outcome, the conditions that were checked with what they
+	* resolved to, and the share a rollout assigned the context to. `evaluate` is this walk with
+	* only the value kept, so the two cannot disagree.
+	*/
+	explain(config, context) {
 		const rules = [...config.target?.rules ?? []].sort((a, b) => (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER));
+		const explanations = [];
+		let served;
 		for (const rule of rules) {
-			const result = this.evaluateRule(rule, config, context);
-			if (result.success) return result.value;
+			if (served) {
+				explanations.push({
+					ruleId: rule.id,
+					outcome: "not-evaluated",
+					conditions: [],
+					bucket: void 0
+				});
+				continue;
+			}
+			const result = this.explainRule(rule, config, context);
+			explanations.push(result.explanation);
+			if (result.value !== void 0) served = {
+				ruleId: rule.id,
+				value: result.value
+			};
 		}
-		return config.target?.defaultValue;
+		return {
+			value: served?.value ?? config.target?.defaultValue,
+			servedBy: served ? {
+				kind: "rule",
+				ruleId: served.ruleId
+			} : { kind: "default" },
+			rules: explanations
+		};
 	}
-	evaluateRule(rule, config, context) {
+	explainRule(rule, config, context) {
+		const explanation = {
+			ruleId: rule.id,
+			outcome: "not-matched",
+			conditions: [],
+			bucket: void 0
+		};
 		try {
-			if (rule.type == "percentage") return this.evaluatePercentageRule(rule, config, context);
-			else if (rule.type == "conditional") return this.evaluateConditionalRule(rule, config, context);
+			let value;
+			if (rule.type == "percentage") value = this.explainPercentage(rule.percentages ?? [], config, context, explanation);
+			else if (rule.type == "conditional") value = this.explainConditionalRule(rule, config, context, explanation);
+			if (value !== void 0) explanation.outcome = "matched";
+			return {
+				explanation,
+				value
+			};
 		} catch (error) {
 			this.logger.warn(`There was an error while evaluating a targeting rule '${rule?.id}' for '${config?.key}'. The rule will be disregarded.`, {
 				error,
 				configKey: config?.key,
 				ruleId: rule?.id
 			});
+			return {
+				explanation: {
+					ruleId: rule.id,
+					outcome: "errored",
+					conditions: [],
+					bucket: void 0
+				},
+				value: void 0
+			};
 		}
-		return { success: false };
 	}
-	evaluatePercentageRule(rule, config, context) {
-		return this.evaluatePercentage(rule.percentages ?? [], config, context);
-	}
-	evaluatePercentage(percentages, config, context) {
+	explainPercentage(percentages, config, context, explanation) {
+		const contextIdentifier = context?.context?.id;
+		const identifier = contextIdentifier ?? crypto.randomUUID();
 		const assignedPercentage = assignPercentage({
 			configId: config.id,
-			contextIdentifier: context?.context?.id ?? crypto.randomUUID()
+			contextIdentifier: identifier
 		});
+		const shares = [];
 		let sum = 0;
-		let bucket = void 0;
+		let selected = void 0;
 		for (const percentage of percentages) {
-			if (assignedPercentage < percentage.percentage + sum) {
-				bucket = percentage;
-				break;
-			}
-			sum += percentage.percentage;
+			const to = sum + percentage.percentage;
+			shares.push({
+				percentageId: percentage.id,
+				from: sum,
+				to,
+				value: percentage.value?.toString()
+			});
+			if (selected === void 0 && assignedPercentage < to) selected = percentage;
+			sum = to;
 		}
-		if (bucket?.value != null) return {
-			success: true,
-			value: bucket.value.toString()
+		explanation.bucket = {
+			identifier,
+			identifierWasGenerated: contextIdentifier == null,
+			assignedPercentage,
+			shares,
+			selectedPercentageId: selected?.id
 		};
-		return { success: false };
-	}
-	evaluateConditionalRule(rule, config, context) {
-		const conditionsMet = (rule.conditions ?? []).every((candidate) => this.conditionEvaluator.evaluate(candidate, context));
-		if (conditionsMet && rule.target == "value" && rule.value != null) return {
-			success: true,
-			value: rule.value.toString()
-		};
-		else if (conditionsMet && rule.target == "percentage") return this.evaluatePercentage(rule.percentages ?? [], config, context);
-		return { success: false };
+		return selected?.value != null ? selected.value.toString() : void 0;
+	}
+	explainConditionalRule(rule, config, context, explanation) {
+		let failed = false;
+		for (const condition of rule.conditions ?? []) {
+			if (failed) {
+				explanation.conditions.push({
+					conditionId: condition.id,
+					outcome: "not-evaluated"
+				});
+				continue;
+			}
+			const check = this.conditionEvaluator.explain(condition, context);
+			explanation.conditions.push({
+				conditionId: condition.id,
+				outcome: check.matched ? "matched" : "not-matched",
+				resolvedValue: check.resolvedValue,
+				resolvedType: check.resolvedType
+			});
+			failed = !check.matched;
+		}
+		if (failed) return;
+		if (rule.target == "value") return rule.value != null ? rule.value.toString() : void 0;
+		if (rule.target == "percentage") return this.explainPercentage(rule.percentages ?? [], config, context, explanation);
 	}
 };
 //#endregion
@@ -7124,6 +7216,11 @@ const getRequestedType = (defaultValue) => {
 const isNumericNativeType = (requestedType) => {
 	return requestedType === "number" || requestedType === "bigint";
 };
+const configTypesNotReadableAsString = new Set([
+	"boolean",
+	"integer",
+	"float"
+]);
 const parseConfigValue = (configState, defaultValue) => {
 	const value = configState.value;
 	const requestedType = getRequestedType(defaultValue);
@@ -7135,13 +7232,22 @@ const parseConfigValue = (configState, defaultValue) => {
 		reason: "value-missing"
 	};
 	if (configState.type === "json") return parseJson(value, defaultValue, requestedType, configState.valueId);
-	if (typeof defaultValue === "string") return {
-		parsedValue: value,
-		parsedValueId: configState.valueId,
-		requestedType,
-		usedDefault: false,
-		reason: "found-match"
-	};
+	if (typeof defaultValue === "string") {
+		if (configTypesNotReadableAsString.has(configState.type)) return {
+			parsedValue: defaultValue,
+			parsedValueId: void 0,
+			requestedType,
+			usedDefault: true,
+			reason: "type-mismatch"
+		};
+		return {
+			parsedValue: value,
+			parsedValueId: configState.valueId,
+			requestedType,
+			usedDefault: false,
+			reason: "found-match"
+		};
+	}
 	if (typeof defaultValue === "boolean" && (configState.type === "boolean" || configState.type === "string" || configState.type === "enum")) {
 		const boolValue = parseConfigBoolean(value);
 		const hasBoolean = typeof boolValue === "boolean";
@@ -7970,7 +8076,7 @@ var plugin_default = defineNitroPlugin((nitroApp) => {
 	const { serverSdkKey, baseUrl, connection } = runtimeConfig.configdirector;
 	const client = new DefaultConfigDirectorClient(serverSdkKey, {
 		sdkName: "nuxt-sdk",
-		sdkVersion: "1.5.0"
+		sdkVersion: "1.6.0"
 	}, {
 		logger,
 		connection: {

package/dist/runtime/plugin.client.mjs

@@ -504,6 +504,11 @@ const getRequestedType = (defaultValue) => {
 const isNumericNativeType = (requestedType) => {
 	return requestedType === "number" || requestedType === "bigint";
 };
+const configTypesNotReadableAsString = new Set([
+	"boolean",
+	"integer",
+	"float"
+]);
 const parseConfigValue = (configState, defaultValue) => {
 	const value = configState.value;
 	const requestedType = getRequestedType(defaultValue);
@@ -515,13 +520,22 @@ const parseConfigValue = (configState, defaultValue) => {
 		reason: "value-missing"
 	};
 	if (configState.type === "json") return parseJson(value, defaultValue, requestedType, configState.valueId);
-	if (typeof defaultValue === "string") return {
-		parsedValue: value,
-		parsedValueId: configState.valueId,
-		requestedType,
-		usedDefault: false,
-		reason: "found-match"
-	};
+	if (typeof defaultValue === "string") {
+		if (configTypesNotReadableAsString.has(configState.type)) return {
+			parsedValue: defaultValue,
+			parsedValueId: void 0,
+			requestedType,
+			usedDefault: true,
+			reason: "type-mismatch"
+		};
+		return {
+			parsedValue: value,
+			parsedValueId: configState.valueId,
+			requestedType,
+			usedDefault: false,
+			reason: "found-match"
+		};
+	}
 	if (typeof defaultValue === "boolean" && (configState.type === "boolean" || configState.type === "string" || configState.type === "enum")) {
 		const boolValue = parseConfigBoolean(value);
 		const hasBoolean = typeof boolValue === "boolean";
@@ -1463,7 +1477,7 @@ var plugin_client_default = defineNuxtPlugin((nuxtApp) => {
 	const { clientSdkKey, appName, appVersion, baseUrl } = runtimeConfig.public.configdirector;
 	const client = createBrowserClient(clientSdkKey, {
 		sdkName: "nuxt-sdk",
-		sdkVersion: "1.5.0"
+		sdkVersion: "1.6.0"
 	}, {
 		metadata: {
 			appName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@configdirector/nuxt-sdk",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Nuxt SDK for ConfigDirector. ConfigDirector is a remote configuration and feature flag service.",
   "license": "MIT",
   "author": "ConfigDirector",