@istar-ts/actions 0.15.0-beta.3 → 0.15.0-beta.5

package/dist/index.d.cts

@@ -2,6 +2,10 @@ import { AnyIstarModel, AnyMetamodel, AnyPaletteDescription, CustomProperties, D
 //#region src/actions.d.ts
 /** GLSP's custom arguments: a flat map of primitives. */
 export type Args = Readonly<Record<string, string | number | boolean>>;
+/** A value that survives a JSON round trip, for `istar.updateModelExtra`'s `set`. */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+  readonly [key: string]: JsonValue;
+};
 export interface Point {
   readonly x: number;
   readonly y: number;
@@ -243,8 +247,35 @@ export interface SetFileMetamodelOperation extends Operation {
   readonly kind: "istar.setFileMetamodel";
   readonly block: FileMetamodel | null;
 }
+/**
+ * Sets, removes or reads back the model's own top-level keys that core keeps in `model.extra`
+ * (e.g. a dialect's `metamodelVersion`): `set`'s keys are written (other extra keys and their
+ * order are kept; a new key is appended where `toPistar` would place it), `remove`'s keys are
+ * deleted. `tool` sets (or, with `null`, removes) the model's own `tool` field in the same undo
+ * step — `set`/`remove` reject it, and every key core models itself (`actors`, `orphans`,
+ * `dependencies`, `links`, `display`, `istar`, `saveDate`, `diagram`), and `"metamodel"` (use
+ * `istar.setFileMetamodel` for that one). One undo step.
+ */
+export interface UpdateModelExtraOperation extends Operation {
+  readonly kind: "istar.updateModelExtra";
+  readonly set?: Readonly<Record<string, JsonValue>>;
+  readonly remove?: readonly string[];
+  readonly tool?: string | null;
+}
+/**
+ * Replaces the whole model from a piStar save file, as one undo step: ids, order and extra keys
+ * come from `model`, so a parse → `toPistar` round trip is byte-identical to it. Parsed with
+ * `parsePistar` under the dispatcher's own metamodel (`fileMetamodel` as in `parsePistar`); a
+ * parse error rejects with a typed diagnostic, the model untouched. Pre-guards and postGuards
+ * run against this operation, the model before and the model after, like any other operation.
+ */
+export interface ReplaceModelOperation extends Operation {
+  readonly kind: "istar.replaceModel";
+  readonly model: PistarFile;
+  readonly fileMetamodel?: boolean;
+}
 /** Every operation, keyed by `kind`. */
-export type IstarOperation<EK extends string = ElementKind, LK extends string = LinkKind> = CreateNodeOperation<EK> | CreateEdgeOperation<EK, LK> | DeleteElementOperation | ChangeBoundsOperation | ChangeContainerOperation | ReconnectEdgeOperation | ApplyLabelEditOperation | CompoundOperation<EK, LK> | AddLegOperation | RemoveLegOperation | SetCollapsedOperation | UpdateDiagramOperation | UpdatePropertiesOperation | UpdateDisplayOperation | SetLinkValueOperation | UpdateLinkDisplayOperation | ChangeLinkKindOperation<LK> | SetFileMetamodelOperation;
+export type IstarOperation<EK extends string = ElementKind, LK extends string = LinkKind> = CreateNodeOperation<EK> | CreateEdgeOperation<EK, LK> | DeleteElementOperation | ChangeBoundsOperation | ChangeContainerOperation | ReconnectEdgeOperation | ApplyLabelEditOperation | CompoundOperation<EK, LK> | AddLegOperation | RemoveLegOperation | SetCollapsedOperation | UpdateDiagramOperation | UpdatePropertiesOperation | UpdateDisplayOperation | SetLinkValueOperation | UpdateLinkDisplayOperation | ChangeLinkKindOperation<LK> | SetFileMetamodelOperation | UpdateModelExtraOperation | ReplaceModelOperation;
 export interface RequestModelAction extends RequestAction {
   readonly kind: "requestModel";
   readonly options?: Args;
@@ -470,6 +501,11 @@ export declare function isOperation<EK extends string, LK extends string>(action
 /** True for the requests (actions answered with a response action). */
 export declare function isRequestAction(action: Action): action is IstarRequestAction;
 //#endregion
+//#region src/created-ids.d.ts
+type Operation$1 = IstarOperation<string, string>;
+/** `operation`, with `createdIds` (an accepted result's) injected as explicit ids. */
+export declare function injectCreatedIds(operation: Operation$1, createdIds: readonly string[], model: AnyIstarModel): Operation$1;
+//#endregion
 //#region src/dispatcher.d.ts
 /** The response a request is answered with; `never` for other actions. */
 export type ResponseFor<A> = A extends RequestModelAction ? SetModelAction : A extends RequestTypeHintsAction ? SetTypeHintsAction : A extends RequestCheckEdgeAction ? CheckEdgeResultAction : A extends RequestContextActions ? SetContextActions : A extends RequestMarkersAction ? SetMarkersAction : never;

package/dist/index.d.ts

@@ -2,6 +2,10 @@ import { AnyIstarModel, AnyMetamodel, AnyPaletteDescription, CustomProperties, D
 //#region src/actions.d.ts
 /** GLSP's custom arguments: a flat map of primitives. */
 export type Args = Readonly<Record<string, string | number | boolean>>;
+/** A value that survives a JSON round trip, for `istar.updateModelExtra`'s `set`. */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+  readonly [key: string]: JsonValue;
+};
 export interface Point {
   readonly x: number;
   readonly y: number;
@@ -243,8 +247,35 @@ export interface SetFileMetamodelOperation extends Operation {
   readonly kind: "istar.setFileMetamodel";
   readonly block: FileMetamodel | null;
 }
+/**
+ * Sets, removes or reads back the model's own top-level keys that core keeps in `model.extra`
+ * (e.g. a dialect's `metamodelVersion`): `set`'s keys are written (other extra keys and their
+ * order are kept; a new key is appended where `toPistar` would place it), `remove`'s keys are
+ * deleted. `tool` sets (or, with `null`, removes) the model's own `tool` field in the same undo
+ * step — `set`/`remove` reject it, and every key core models itself (`actors`, `orphans`,
+ * `dependencies`, `links`, `display`, `istar`, `saveDate`, `diagram`), and `"metamodel"` (use
+ * `istar.setFileMetamodel` for that one). One undo step.
+ */
+export interface UpdateModelExtraOperation extends Operation {
+  readonly kind: "istar.updateModelExtra";
+  readonly set?: Readonly<Record<string, JsonValue>>;
+  readonly remove?: readonly string[];
+  readonly tool?: string | null;
+}
+/**
+ * Replaces the whole model from a piStar save file, as one undo step: ids, order and extra keys
+ * come from `model`, so a parse → `toPistar` round trip is byte-identical to it. Parsed with
+ * `parsePistar` under the dispatcher's own metamodel (`fileMetamodel` as in `parsePistar`); a
+ * parse error rejects with a typed diagnostic, the model untouched. Pre-guards and postGuards
+ * run against this operation, the model before and the model after, like any other operation.
+ */
+export interface ReplaceModelOperation extends Operation {
+  readonly kind: "istar.replaceModel";
+  readonly model: PistarFile;
+  readonly fileMetamodel?: boolean;
+}
 /** Every operation, keyed by `kind`. */
-export type IstarOperation<EK extends string = ElementKind, LK extends string = LinkKind> = CreateNodeOperation<EK> | CreateEdgeOperation<EK, LK> | DeleteElementOperation | ChangeBoundsOperation | ChangeContainerOperation | ReconnectEdgeOperation | ApplyLabelEditOperation | CompoundOperation<EK, LK> | AddLegOperation | RemoveLegOperation | SetCollapsedOperation | UpdateDiagramOperation | UpdatePropertiesOperation | UpdateDisplayOperation | SetLinkValueOperation | UpdateLinkDisplayOperation | ChangeLinkKindOperation<LK> | SetFileMetamodelOperation;
+export type IstarOperation<EK extends string = ElementKind, LK extends string = LinkKind> = CreateNodeOperation<EK> | CreateEdgeOperation<EK, LK> | DeleteElementOperation | ChangeBoundsOperation | ChangeContainerOperation | ReconnectEdgeOperation | ApplyLabelEditOperation | CompoundOperation<EK, LK> | AddLegOperation | RemoveLegOperation | SetCollapsedOperation | UpdateDiagramOperation | UpdatePropertiesOperation | UpdateDisplayOperation | SetLinkValueOperation | UpdateLinkDisplayOperation | ChangeLinkKindOperation<LK> | SetFileMetamodelOperation | UpdateModelExtraOperation | ReplaceModelOperation;
 export interface RequestModelAction extends RequestAction {
   readonly kind: "requestModel";
   readonly options?: Args;
@@ -470,6 +501,11 @@ export declare function isOperation<EK extends string, LK extends string>(action
 /** True for the requests (actions answered with a response action). */
 export declare function isRequestAction(action: Action): action is IstarRequestAction;
 //#endregion
+//#region src/created-ids.d.ts
+type Operation$1 = IstarOperation<string, string>;
+/** `operation`, with `createdIds` (an accepted result's) injected as explicit ids. */
+export declare function injectCreatedIds(operation: Operation$1, createdIds: readonly string[], model: AnyIstarModel): Operation$1;
+//#endregion
 //#region src/dispatcher.d.ts
 /** The response a request is answered with; `never` for other actions. */
 export type ResponseFor<A> = A extends RequestModelAction ? SetModelAction : A extends RequestTypeHintsAction ? SetTypeHintsAction : A extends RequestCheckEdgeAction ? CheckEdgeResultAction : A extends RequestContextActions ? SetContextActions : A extends RequestMarkersAction ? SetMarkersAction : never;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { DIAGNOSTIC_SEVERITIES, FILE_METAMODEL_KEY, LINK_SELECTOR, MetamodelError, ModelOperationError, canLink, connectResultToDiagnostic, createEmptyModel, dependencyEnds, effectiveLinkKind, elementBehavesLike, inheritMetamodel, inheritSourceLayout, linkBehavesLike, metamodelOf, parsePistar, toPistarObject, validateModel, validateModelProperties, withFileMetamodel } from "@istar-ts/core";
+import { DIAGNOSTIC_SEVERITIES, FILE_METAMODEL_KEY, LINK_SELECTOR, MetamodelError, ModelOperationError, PistarParseError, TOP_LEVEL_KEYS, canLink, connectResultToDiagnostic, createEmptyModel, dependencyEnds, effectiveLinkKind, elementBehavesLike, hostMetamodelOf, inheritMetamodel, inheritSourceLayout, linkBehavesLike, metamodelOf, parsePistar, toPistarObject, validateModel, validateModelProperties, withFileMetamodel } from "@istar-ts/core";
 //#region src/actions.ts
 const OPERATION_KIND_LIST = [
 	"createNode",
@@ -18,7 +18,9 @@ const OPERATION_KIND_LIST = [
 	"istar.setLinkValue",
 	"istar.updateLinkDisplay",
 	"istar.changeLinkKind",
-	"istar.setFileMetamodel"
+	"istar.setFileMetamodel",
+	"istar.updateModelExtra",
+	"istar.replaceModel"
 ];
 const REQUEST_KIND_LIST = [
 	"requestModel",
@@ -63,6 +65,141 @@ function isRequestAction(action) {
 	return REQUEST_KINDS.has(action.kind);
 }
 //#endregion
+//#region src/created-ids.ts
+/** How many new element ids, then new link ids, `operation` creates, mirroring the dispatcher's
+* `createdIds` diff (`dispatcher.ts`) and `connect`/`addDependency`/`addLeg`
+* (`packages/core/src/operations.ts`). */
+function countCreatedIds(operation, model) {
+	switch (operation.kind) {
+		case "createNode": return {
+			elements: 1,
+			links: 0
+		};
+		case "createEdge": {
+			const metamodel = metamodelOf(model);
+			const definition = metamodel.links.get(operation.elementTypeId);
+			if (definition?.category === "dependency") return {
+				elements: 1,
+				links: 2
+			};
+			if (definition?.parts && !targetIsHub(operation, model, metamodel)) return {
+				elements: 1,
+				links: 2
+			};
+			return {
+				elements: 0,
+				links: 1
+			};
+		}
+		case "istar.addLeg": return {
+			elements: 0,
+			links: 1
+		};
+		case "compound": {
+			let elements = 0;
+			let links = 0;
+			for (const child of operation.operationList) {
+				const counts = countCreatedIds(child, model);
+				elements += counts.elements;
+				links += counts.links;
+			}
+			return {
+				elements,
+				links
+			};
+		}
+		default: return {
+			elements: 0,
+			links: 0
+		};
+	}
+}
+function targetIsHub(operation, model, metamodel) {
+	const targetKind = model.elements.get(operation.targetElementId)?.kind;
+	return targetKind !== void 0 && metamodel.elements.get(targetKind)?.role === "hub";
+}
+/** `operation` with ids from `elementIds`/`linkIds` (consumed in model order) injected as the
+* explicit ids its creates take, so a dispatcher that applies it against the same model state
+* creates the same ids. */
+function withCreatedIds(operation, elementIds, linkIds, model) {
+	switch (operation.kind) {
+		case "createNode": {
+			const id = elementIds.shift();
+			return id === void 0 ? operation : {
+				...operation,
+				args: {
+					...operation.args,
+					id
+				}
+			};
+		}
+		case "createEdge": {
+			const metamodel = metamodelOf(model);
+			const definition = metamodel.links.get(operation.elementTypeId);
+			if (definition?.category === "dependency") {
+				const dependumId = elementIds.shift();
+				const linkIds2 = [linkIds.shift(), linkIds.shift()];
+				if (dependumId === void 0 || linkIds2[0] === void 0 || linkIds2[1] === void 0) return operation;
+				return {
+					...operation,
+					args: {
+						...operation.args,
+						dependum: {
+							...operation.args?.dependum,
+							id: dependumId
+						},
+						linkIds: linkIds2
+					}
+				};
+			}
+			if (definition?.parts && !targetIsHub(operation, model, metamodel)) {
+				const hubId = elementIds.shift();
+				const legId = linkIds.shift();
+				const endId = linkIds.shift();
+				return hubId === void 0 || legId === void 0 || endId === void 0 ? operation : {
+					...operation,
+					args: {
+						...operation.args,
+						id: hubId,
+						legId,
+						endId
+					}
+				};
+			}
+			const id = linkIds.shift();
+			return id === void 0 ? operation : {
+				...operation,
+				args: {
+					...operation.args,
+					id
+				}
+			};
+		}
+		case "istar.addLeg": {
+			const id = linkIds.shift();
+			return id === void 0 ? operation : {
+				...operation,
+				args: {
+					...operation.args,
+					id
+				}
+			};
+		}
+		case "compound": return {
+			...operation,
+			operationList: operation.operationList.map((child) => withCreatedIds(child, elementIds, linkIds, model))
+		};
+		default: return operation;
+	}
+}
+/** `operation`, with `createdIds` (an accepted result's) injected as explicit ids. */
+function injectCreatedIds(operation, createdIds, model) {
+	const counts = countCreatedIds(operation, model);
+	const elementIds = createdIds.slice(0, counts.elements);
+	const linkIds = createdIds.slice(counts.elements, counts.elements + counts.links);
+	return withCreatedIds(operation, [...elementIds], [...linkIds], model);
+}
+//#endregion
 //#region src/hints.ts
 /**
 * What a client can know before it asks: type hints from the metamodel, and the palette as
@@ -275,6 +412,11 @@ function rejectCheck(check, endpoints) {
 function metaOf(model) {
 	return metamodelOf(model);
 }
+/**
+* Keys `istar.updateModelExtra`'s `set`/`remove` must not touch: every key core models itself
+* (`TOP_LEVEL_KEYS`, which includes `tool`), and `"metamodel"` (`istar.setFileMetamodel`'s own).
+*/
+const RESERVED_EXTRA_KEYS = /* @__PURE__ */ new Set([...TOP_LEVEL_KEYS, FILE_METAMODEL_KEY]);
 /** A model with `links` changed, as the core operations derive one. */
 function withLinks(model, links) {
 	return inheritMetamodel(model, inheritSourceLayout(model, {
@@ -581,6 +723,48 @@ function createActionDispatcher(store, options = {}) {
 				s.replace(next);
 				return;
 			}
+			case "istar.updateModelExtra": {
+				const { set, remove, tool } = operation;
+				for (const key of [...Object.keys(set ?? {}), ...remove ?? []]) {
+					if (!RESERVED_EXTRA_KEYS.has(key)) continue;
+					if (key === "tool") reject(`"tool" is a modelled field: set it with this operation's own "tool"`, "", "reserved-key");
+					if (key === FILE_METAMODEL_KEY) reject(`"${key}" is set with istar.setFileMetamodel, not updateModelExtra`, "", "reserved-key");
+					reject(`"${key}" is modelled by the file itself and cannot be an extra key`, "", "reserved-key");
+				}
+				let withTool = model;
+				if (tool === null) {
+					const { tool: _tool, ...rest } = withTool;
+					withTool = rest;
+				} else if (tool !== void 0) withTool = {
+					...withTool,
+					tool
+				};
+				const extra = { ...withTool.extra };
+				if (set) for (const [key, value] of Object.entries(set)) extra[key] = value;
+				if (remove) for (const key of remove) delete extra[key];
+				const { extra: _extra, ...rest } = withTool;
+				const next = {
+					...rest,
+					...Object.keys(extra).length > 0 ? { extra } : {}
+				};
+				s.replace(inheritMetamodel(model, inheritSourceLayout(model, next)));
+				return;
+			}
+			case "istar.replaceModel": {
+				const host = hostMetamodelOf(model) ?? meta;
+				let next;
+				try {
+					next = parsePistar(operation.model, {
+						metamodel: host,
+						fileMetamodel: operation.fileMetamodel ?? false
+					});
+				} catch (error) {
+					if (error instanceof PistarParseError) reject(error.message, "", "parse-error");
+					throw error;
+				}
+				s.replace(next);
+				return;
+			}
 			default: reject(`unknown operation "${operation.kind}"`, "", "unknown-action");
 		}
 	};
@@ -593,7 +777,8 @@ function createActionDispatcher(store, options = {}) {
 		for (const [key, value] of Object.entries(properties)) if (value === null) delete next[key];
 		else if (typeof value === "string") next[key] = value;
 		else reject(`the value of "${key}" must be a string or null`, id, "invalid-value");
-		const customProperties = Object.keys(next).length > 0 ? next : null;
+		if (Object.keys(next).length === 0 && owner.customProperties === void 0) return;
+		const customProperties = next;
 		if (model.elements.has(id)) s.updateElement(id, { customProperties });
 		else s.updateLink(id, { customProperties });
 	};
@@ -1206,6 +1391,6 @@ function createRemoteDispatcher(port) {
 /** Version of the action protocol this package speaks. */
 const ACTIONS_PROTOCOL_VERSION = "0.0.0";
 //#endregion
-export { ACTIONS_PROTOCOL_VERSION, HANDLED_ACTION_KINDS, connectDispatcher, contextActionsFor, contextText, createActionDispatcher, createMirrorStore, createRemoteDispatcher, diagnosticToMarker, hostToolContext, isOperation, isRequestAction, markerToDiagnostic, paletteFromMetamodel, readOnlyDispatcher, typeHintsFor };
+export { ACTIONS_PROTOCOL_VERSION, HANDLED_ACTION_KINDS, connectDispatcher, contextActionsFor, contextText, createActionDispatcher, createMirrorStore, createRemoteDispatcher, diagnosticToMarker, hostToolContext, injectCreatedIds, isOperation, isRequestAction, markerToDiagnostic, paletteFromMetamodel, readOnlyDispatcher, typeHintsFor };
 
 //# sourceMappingURL=index.js.map