@istar-ts/core 0.13.3 → 0.13.5

package/README.md

@@ -35,7 +35,14 @@ writeFileSync('model.pistar', toPistar(model));
 - Files saved by the piStar web tool round-trip **byte-identically** through
   `toPistar(parsePistar(file))` when you do not edit the model.
 - Pass `{ saveDate: new Date() }` when saving an edited model (piStar updates `saveDate` on save).
-  Omit it to preserve the model’s existing `saveDate` on a load/save cycle.
+  Omit it to preserve the model’s existing `saveDate` on a load/save cycle; a file that had none
+  keeps none until a save passes one.
+- A model's metamodel and layout are kept beside it, in registries shared by every copy of
+  `@istar-ts/core` in the process (ESM and CommonJS builds alike), so a model parsed by one copy
+  is read correctly by another.
+- A parsed file is written back with its own key order at every level (top level, each element,
+  link, hub entry and the diagram), so files other tools wrote stay byte-identical. `inheritSourceLayout`
+  carries that over to an edited model; the store does it on every edit.
 
 ```ts
 toPistar(editedModel, { saveDate: new Date() });

package/dist/index.cjs

@@ -551,6 +551,26 @@ function elementBehavesLike(metamodel, kind, ancestor) {
 	return false;
 }
 //#endregion
+//#region src/shared.ts
+/**
+* Registries the library keeps beside models (their metamodel, their file's layout) are
+* shared across every copy of `@istar-ts/core` loaded in a process. A bundle may load the
+* package twice, once as ESM and once as CommonJS (an application parsing with the ESM build
+* while a CommonJS dependency reads the model with the CJS build): a module-level WeakMap in
+* each copy would make a model parsed by one copy unknown to the other, so `metamodelOf`
+* would fall back to iStar 2.0 there. The registries live on `globalThis` under one symbol
+* instead, keyed by name, and every copy finds the same ones.
+*/
+const REGISTRIES = Symbol.for("@istar-ts/core/registries");
+/** The WeakMap named `name`, the same object in every copy of the library in this process. */
+function sharedWeakMap(name) {
+	const host = globalThis;
+	const registries = host[REGISTRIES] ??= /* @__PURE__ */ new Map();
+	let map = registries.get(name);
+	if (!map) registries.set(name, map = /* @__PURE__ */ new WeakMap());
+	return map;
+}
+//#endregion
 //#region src/model.ts
 /** Tool identifier written by piStar 2.1.0, whose file format this library emulates. */
 const PISTAR_TOOL = "pistar.2.1.0";
@@ -581,7 +601,7 @@ const DEFAULT_DIAGRAM = {
 * so a model's shape (and `JSON.stringify`, deep equality, snapshots) is the same as before
 * metamodels existed. Operations and the store carry it to every model they derive.
 */
-const metamodels = /* @__PURE__ */ new WeakMap();
+const metamodels = sharedWeakMap("metamodels");
 /**
 * Associates `metamodel` with `model` and returns the same model, typed for it. Use when a
 * model was built without the library's operations (e.g. with an object spread), which loses
@@ -596,7 +616,7 @@ function withMetamodel(model, metamodel) {
 * For models whose file declares part of their metamodel (see `withFileMetamodel`): the
 * metamodel the host supplied, without the file's kinds.
 */
-const hostMetamodels = /* @__PURE__ */ new WeakMap();
+const hostMetamodels = sharedWeakMap("hostMetamodels");
 /** @internal Records the host part of a model's metamodel (used by serialization). */
 function setHostMetamodel(model, metamodel) {
 	if (metamodel) hostMetamodels.set(model, metamodel);
@@ -1235,7 +1255,13 @@ var PistarParseError = class extends Error {
 var PistarWriteError = class extends Error {
 	name = "PistarWriteError";
 };
-const layouts = /* @__PURE__ */ new WeakMap();
+/** The `objects` key of a hub's entry (`{ hub, starts, end }`) in a `SourceLayout`. */
+function hubEntryLayoutKey(hubId) {
+	return `${hubId}\u0000entry`;
+}
+/** The `objects` key of the diagram in a `SourceLayout`. */
+const DIAGRAM_LAYOUT_KEY = "\0diagram";
+const layouts = sharedWeakMap("layouts");
 /** The key order recorded when `model` was parsed, if it came from `parsePistar`. */
 function getSourceLayout(model) {
 	return layouts.get(model);
@@ -1342,6 +1368,7 @@ function parsePistar(input, options = {}) {
 		usedDisplay.add(id);
 		return entry;
 	};
+	const objects = /* @__PURE__ */ new Map();
 	const readElement = (raw, where, known, extras) => {
 		if (!isRecord(raw)) throw new PistarParseError(`${where}: expected an object`);
 		const { id, type } = raw;
@@ -1361,6 +1388,7 @@ function parsePistar(input, options = {}) {
 			...optional("extra", extraOf(raw, known))
 		};
 		elements.set(id, element);
+		objects.set(id, Object.keys(raw));
 		return element;
 	};
 	asArray(json.actors, "actors").forEach((raw, i) => {
@@ -1405,12 +1433,14 @@ function parsePistar(input, options = {}) {
 			...optional("extra", extraOf(raw, LINK_KEYS))
 		};
 		links.set(id, link);
+		objects.set(id, Object.keys(raw));
 		return link;
 	};
 	const readHubEntry = (raw, where) => {
 		const hub = readElement(raw.hub, `${where}.hub`, HUB_KEYS, {});
 		const hubKind = metamodel.elements.get(hub.kind);
 		if (hubKind?.role !== "hub") throw new PistarParseError(`${where}.hub (${hub.id}): ${hub.kind} is not a hub kind`);
+		objects.set(hubEntryLayoutKey(hub.id), Object.keys(raw));
 		const entryExtra = extraOf(raw, HUB_ENTRY_KEYS);
 		if (entryExtra) elements.set(hub.id, {
 			...hub,
@@ -1448,6 +1478,7 @@ function parsePistar(input, options = {}) {
 			...isRecord(d.customProperties) ? { customProperties: d.customProperties } : {},
 			...optional("extra", extraOf(d, DIAGRAM_KEYS))
 		};
+		objects.set(DIAGRAM_LAYOUT_KEY, Object.keys(d));
 	}
 	const model = {
 		elements,
@@ -1461,7 +1492,8 @@ function parsePistar(input, options = {}) {
 	};
 	layouts.set(model, {
 		keys: Object.keys(json),
-		display: Object.keys(display)
+		display: Object.keys(display),
+		objects
 	});
 	setHostMetamodel(model, host);
 	return withMetamodel(model, metamodel);
@@ -1534,6 +1566,19 @@ function pistarTypeOf(type, kind, metamodel) {
 	if (type === void 0) throw new PistarWriteError(`kind "${kind}" is not part of ${metamodel.name}; pass its metamodel (toPistar(model, { metamodel }) or withMetamodel)`);
 	return type;
 }
+/**
+* `value` with its keys in the order `keys` gives (those present), then the rest as built (piStar's
+* order): an object read from a file is written back with the file's key order, and keys the
+* file lacked follow.
+*/
+function inSourceOrder(value, keys) {
+	if (!keys) return value;
+	const result = {};
+	const record = value;
+	for (const key of keys) if (key in record) result[key] = record[key];
+	for (const key of Object.keys(record)) if (!(key in result)) result[key] = record[key];
+	return result;
+}
 function elementJson(element, metamodel) {
 	return {
 		id: element.id,
@@ -1554,38 +1599,40 @@ function toPistarObject(input, options = {}) {
 	const orphans = [];
 	const dependencies = [];
 	const children = /* @__PURE__ */ new Map();
+	const layout = layouts.get(model);
+	const sourceOrder = (id, value) => inSourceOrder(value, layout?.objects?.get(id));
 	for (const element of model.elements.values()) {
 		if (isHub(element)) continue;
 		if (element.parent !== void 0 && !isActorKind(element.kind)) {
 			let list = children.get(element.parent);
 			if (!list) children.set(element.parent, list = []);
-			list.push({
+			list.push(sourceOrder(element.id, {
 				...elementJson(element, metamodel),
 				...element.extra
-			});
+			}));
 		}
 	}
 	for (const element of model.elements.values()) {
 		if (isHub(element)) continue;
-		if (isActorKind(element.kind)) actors.push({
+		if (isActorKind(element.kind)) actors.push(sourceOrder(element.id, {
 			...elementJson(element, metamodel),
 			nodes: children.get(element.id) ?? [],
 			...element.extra
-		});
+		}));
 		else if (element.isDependum) {
 			const { inbound, outbound } = dependencyLinksOf(model, element.id);
-			dependencies.push({
+			dependencies.push(sourceOrder(element.id, {
 				...elementJson(element, metamodel),
 				source: inbound?.source ?? element.dependency?.source ?? "",
 				target: outbound?.target ?? element.dependency?.target ?? "",
 				...element.extra
-			});
-		} else if (element.parent === void 0 || !model.elements.has(element.parent)) orphans.push({
+			}));
+		} else if (element.parent === void 0 || !model.elements.has(element.parent)) orphans.push(sourceOrder(element.id, {
 			...elementJson(element, metamodel),
 			...element.extra
-		});
+		}));
 	}
-	const linkJson = (link) => ({
+	const linkJson = (link) => sourceOrder(link.id, {
 		id: link.id,
 		type: pistarTypeOf(metamodel.links.get(link.kind)?.pistarType, link.kind, metamodel),
 		source: link.source,
@@ -1617,19 +1664,19 @@ function toPistarObject(input, options = {}) {
 	const hubEntry = (hub) => {
 		const parts = hubs.get(hub.id) ?? { legs: [] };
 		const { [HUB_ENTRY_KEY]: entryExtra, ...hubExtra } = hub.extra ?? {};
-		return {
-			hub: {
+		return sourceOrder(hubEntryLayoutKey(hub.id), {
+			hub: sourceOrder(hub.id, {
 				id: hub.id,
 				type: pistarTypeOf(metamodel.elements.get(hub.kind)?.pistarType, hub.kind, metamodel),
 				x: hub.x,
 				y: hub.y,
 				...hub.customProperties ? { customProperties: { ...hub.customProperties } } : {},
 				...hubExtra
-			},
+			}),
 			starts: parts.legs.map(linkJson),
 			...parts.end ? { end: linkJson(parts.end) } : {},
 			...isRecord(entryExtra) ? entryExtra : {}
-		};
+		});
 	};
 	const links = [];
 	const written = /* @__PURE__ */ new Set();
@@ -1643,7 +1690,6 @@ function toPistarObject(input, options = {}) {
 		}
 	}
 	for (const element of model.elements.values()) if (isHub(element) && !written.has(element.id)) links.push(hubEntry(element));
-	const layout = layouts.get(model);
 	const display = {};
 	const displayOf = (id) => {
 		const owner = model.elements.get(id) ?? model.links.get(id);
@@ -1658,15 +1704,16 @@ function toPistarObject(input, options = {}) {
 	for (const [id, entry] of Object.entries(model.extraDisplay ?? {})) if (!(id in display)) display[id] = entry;
 	let saveDate;
 	if (options.saveDate instanceof Date) saveDate = formatDate(options.saveDate);
-	else saveDate = options.saveDate ?? model.saveDate ?? formatDate(/* @__PURE__ */ new Date());
+	else if (options.saveDate !== void 0 || model.saveDate !== void 0) saveDate = options.saveDate ?? model.saveDate;
+	else if (!layout || layout.keys.includes("saveDate")) saveDate = formatDate(/* @__PURE__ */ new Date());
 	const d = model.diagram;
-	const diagram = d && {
+	const diagram = d && sourceOrder("\0diagram", {
 		...d.width !== void 0 ? { width: d.width } : {},
 		...d.height !== void 0 ? { height: d.height } : {},
 		...d.name !== void 0 ? { name: d.name } : {},
 		...d.customProperties ? { customProperties: { ...d.customProperties } } : {},
 		...d.extra
-	};
+	});
 	const values = {
 		...model.extra,
 		actors,
@@ -2851,6 +2898,7 @@ exports.DEFAULT_DIAGRAM = DEFAULT_DIAGRAM;
 exports.DEFAULT_ELEMENT_SIZE = DEFAULT_ELEMENT_SIZE;
 exports.DEPENDENCY_LINK_KINDS = DEPENDENCY_LINK_KINDS;
 exports.DIAGNOSTIC_SEVERITIES = DIAGNOSTIC_SEVERITIES;
+exports.DIAGRAM_LAYOUT_KEY = DIAGRAM_LAYOUT_KEY;
 exports.DSM3_FILE_KEYS = DSM3_FILE_KEYS;
 exports.DSM3_TOOL = DSM3_TOOL;
 exports.ELEMENT_KINDS = ELEMENT_KINDS;
@@ -2909,6 +2957,7 @@ exports.fromNodeIdDiagnostics = fromNodeIdDiagnostics;
 exports.getSourceLayout = getSourceLayout;
 exports.groupDiagnostics = groupDiagnostics;
 exports.hostMetamodelOf = hostMetamodelOf;
+exports.hubEntryLayoutKey = hubEntryLayoutKey;
 exports.hubLinkOf = hubLinkOf;
 exports.hubOfLink = hubOfLink;
 exports.inheritMetamodel = inheritMetamodel;