@istar-ts/core 0.13.7 → 0.14.0

package/README.md

@@ -176,7 +176,25 @@ const modelIssues = validateModelProperties(model, [resourceSchema]);
 ```
 
 `read` / `validate` accept `customProperties`, a full element/link, or `undefined`. `write` merges
-patches, preserves unknown keys, and serializes typed values back to strings.
+patches, preserves unknown keys, and serializes typed values back to strings. A value that
+didn't change keeps its string as read (`.2` stays `.2`).
+
+Two optional hints:
+
+- `prop.number({ min: 0, max: 1 })`: with `max: 1` (a probability) the reader also accepts a
+  percentage, so `0.2`, `.2` and `20.00%` read as 0.2. A changed value is written in the form
+  the old one was read in (`20.00%` → `35.00%`, `.2` → `.35`).
+- `prop.reference({ kinds })`: the value is another element's (or link's) id. The schema only
+  checks it isn't empty; `validateModelProperties` reports an id that isn't in the model, or
+  whose kind isn't in `kinds`.
+
+Formulas (a KAOS `FormalSpec`, a `BoundaryCondition`) stay `prop.string`: core has no formula
+language.
+
+A schema can be declared for the kinds an n-ary link generates (its hub, legs and end) like for
+any kind; `HubPartKind<'kaos.RefinementLink'>` is `'kaos.RefinementLinkHub' |
+'kaos.RefinementLinkStart' | 'kaos.RefinementLinkEnd'`. Legs keep their `customProperties` on
+disk.
 
 ## Extending the metamodel
 

package/dist/index.cjs

@@ -2500,19 +2500,50 @@ function string(options) {
 		}
 	};
 }
+/** `20.00%` → 20.00 as text, or undefined when `raw` isn't a percentage. */
+function percentBody(raw) {
+	const text = raw.trim();
+	if (!text.endsWith("%")) return void 0;
+	const body = text.slice(0, -1).trim();
+	return body === "" ? void 0 : body;
+}
+/** Digits after the decimal point of a number written as text (`20.00` → 2). */
+function decimals(text) {
+	const dot = text.indexOf(".");
+	return dot === -1 ? 0 : text.length - dot - 1;
+}
+/** `value` without floating-point noise from a ×100 (0.35 * 100 = 35.00000000000001). */
+function plain(value) {
+	return String(Number(value.toPrecision(12)));
+}
+/** Writes `value` in the form of `previous`: a percentage, a leading dot, or plain. */
+function formatNumber(value, previous, percent) {
+	if (previous === void 0) return String(value);
+	const body = percent ? percentBody(previous) : void 0;
+	if (body !== void 0) {
+		const text = plain(value * 100);
+		const places = decimals(body);
+		return `${places > decimals(text) ? (value * 100).toFixed(places) : text}%`;
+	}
+	if (/^\s*[+-]?\.\d/.test(previous) && Math.abs(value) < 1) return String(value).replace(/^(-?)0\./, "$1.");
+	return String(value);
+}
 function number(options) {
 	const opts = options ?? {};
 	const integer = options?.integer;
 	const min = options?.min;
 	const max = options?.max;
+	const percent = max === 1;
 	return {
 		type: "number",
 		options: opts,
 		integer,
 		min,
 		max,
+		...percent ? { percent } : {},
 		parse(raw) {
-			const value = Number(raw);
+			const body = percent ? percentBody(raw) : void 0;
+			const value = body !== void 0 ? Number(body) / 100 : Number(raw);
 			if (!Number.isFinite(value)) return {
 				ok: false,
 				error: "must be a finite number"
@@ -2534,8 +2565,8 @@ function number(options) {
 				value
 			};
 		},
-		serialize(value) {
-			return String(value);
+		serialize(value, previous) {
+			return formatNumber(value, previous, percent);
 		}
 	};
 }
@@ -2582,11 +2613,34 @@ function enumOf(values, options) {
 		}
 	};
 }
+/**
+* A value that is another element's or link's id, e.g. the goal a KAOS resolution restores. The
+* schema only checks it is non-empty; `validateModelProperties` reports an id that isn't in the
+* model or names a kind outside `kinds`.
+*/
+function reference(options) {
+	const { kinds, ...opts } = options ?? {};
+	return {
+		type: "reference",
+		options: opts,
+		...kinds ? { kinds } : {},
+		parse(raw) {
+			return {
+				ok: true,
+				value: raw
+			};
+		},
+		serialize(value) {
+			return value;
+		}
+	};
+}
 const prop = {
 	string,
 	number,
 	boolean,
-	enum: enumOf
+	enum: enumOf,
+	reference
 };
 function isCustomPropertiesRecord(source) {
 	if ("customProperties" in source) return false;
@@ -2628,7 +2682,7 @@ function readShape(shape, source) {
 			}
 			issues.push({
 				key,
-				message: field.type === "boolean" ? "must be true or false" : field.type === "enum" ? `must be one of: ${field.values?.join(", ") ?? ""}` : "must be a finite number"
+				message: field.type === "boolean" ? "must be true or false" : field.type === "enum" ? `must be one of: ${field.values?.join(", ") ?? ""}` : field.type === "reference" ? "must be an element or link id" : "must be a finite number"
 			});
 			continue;
 		}
@@ -2647,6 +2701,15 @@ function readShape(shape, source) {
 		issues
 	};
 }
+/**
+* A patched value as a string, written back as read: the current string is kept when it already
+* holds the value (`.2` stays `.2`), and otherwise the type writes the value in its form.
+*/
+function writeField(field, value, current) {
+	const parsed = field.parse(current);
+	if (parsed.ok && Object.is(parsed.value, value)) return current;
+	return field.serialize(value, current);
+}
 function defineProperties(kind, shape, options) {
 	const crossValidate = options?.validate;
 	return {
@@ -2668,7 +2731,7 @@ function defineProperties(kind, shape, options) {
 					const patched = patch[key];
 					if (patched === void 0) continue;
 					const field = shape[key];
-					if (field) result[key] = field.serialize(patched);
+					if (field) result[key] = writeField(field, patched, value);
 				} else result[key] = value;
 				seen.add(key);
 			}
@@ -2702,20 +2765,39 @@ function validateModelProperties(model, schemas) {
 		byKind.set(schema.kind, list);
 	}
 	const issues = [];
-	for (const element of model.elements.values()) {
-		const kindSchemas = byKind.get(element.kind);
-		if (!kindSchemas) continue;
-		for (const schema of kindSchemas) for (const issue of schema.validate(element)) issues.push({
-			...issue,
-			id: element.id
+	const check = (owner) => {
+		const kindSchemas = byKind.get(owner.kind);
+		if (!kindSchemas) return;
+		for (const schema of kindSchemas) {
+			for (const issue of schema.validate(owner)) issues.push({
+				...issue,
+				id: owner.id
+			});
+			for (const issue of referenceIssues(model, schema.shape, owner.customProperties)) issues.push({
+				...issue,
+				id: owner.id
+			});
+		}
+	};
+	for (const element of model.elements.values()) check(element);
+	for (const link of model.links.values()) check(link);
+	return issues;
+}
+/** References (`prop.reference`) to ids that aren't in the model, or to the wrong kind. */
+function referenceIssues(model, shape, custom) {
+	const issues = [];
+	for (const [key, field] of Object.entries(shape)) {
+		if (field.type !== "reference") continue;
+		const id = custom?.[key];
+		if (id === void 0 || id === "") continue;
+		const target = model.elements.get(id) ?? model.links.get(id);
+		if (!target) issues.push({
+			key,
+			message: `refers to "${id}", which is not in the model`
 		});
-	}
-	for (const link of model.links.values()) {
-		const kindSchemas = byKind.get(link.kind);
-		if (!kindSchemas) continue;
-		for (const schema of kindSchemas) for (const issue of schema.validate(link)) issues.push({
-			...issue,
-			id: link.id
+		else if (field.kinds && !field.kinds.includes(target.kind)) issues.push({
+			key,
+			message: `must refer to a ${field.kinds.join(" or ")}`
 		});
 	}
 	return issues;
@@ -2989,6 +3071,7 @@ exports.nestElement = nestElement;
 exports.number = number;
 exports.parsePistar = parsePistar;
 exports.prop = prop;
+exports.reference = reference;
 exports.removeElement = removeElement;
 exports.removeElements = removeElements;
 exports.removeLeg = removeLeg;