frodovdr/node-red
1
0
Fork 0
mirror of https://github.com/node-red/node-red.git synced 2025-03-01 10:36:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve docs and comments

Browse Source
This commit is contained in:
GogoVega 2024-11-10 17:14:02 +01:00
parent 8395ef6e26
commit 7ba7333310
No known key found for this signature in database
GPG Key ID: E1E048B63AC5AC2B
1 changed files with 199 additions and 122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

321
packages/node_modules/@node-red/editor-client/src/js/history.js vendored
View File

@ -19,7 +19,36 @@
* @namespace RED.history
*/
RED.history = (function () {
/**
* GLOBAL NOTE: Handle event and users ONLY for edit/change event
* TODO: Import types from RED.nodes
*
* @typedef {object} Node
* @typedef {{ source: Node; sourcePort: number; target: Node; }} Link
* @typedef {Node & { env?: Array<object>; }} Group
* @typedef {Node & {}} Junction
* @typedef {Node & { in: Array<object>; out: Array<object>;
* instances: Array<Node>; env?: Array<object>; }} Subflow
* @typedef {Node & { type: "subflow"; direction: "in"|"out"; }} SubflowNode
* @typedef {Node & {}} Workspace
*
* @typedef {"add"|"delete"|"edit"|"move"|"multi"|"reorder"|"replace"|
* "createSubflow"|"deleteSubflow"|"addToGroup"|"createGroup"|"ungroup"|
* "removeFromGroup"} HistoryType
* @typedef {{ t: HistoryType; dirty: boolean; callback?: (ev: HistoryEvent) => void; }
* & (AddEvent | DeleteEvent | EditEvent | MoveEvent | MultiEvent | ReorderEvent |
* ReplaceEvent | CreateSubflowEvent | DeleteSubflowEvent | AddToGroupEvent |
* CreateGroupEvent | UngroupEvent | RemoveFromGroupEvent) } HistoryEvent
*/
/**
* @type {Array<HistoryEvent>}
*/
let undoHistory = [];
/**
* @type {Array<HistoryEvent>}
*/
let redoHistory = [];
function nodeOrJunction(id) {
@ -39,32 +68,23 @@ RED.history = (function () {
}
}
/**
* @typedef {"add"|"delete"|"edit"|"move"|"multi"|"remove"|"reorder"|"replace"|
* "createSubflow"|"deleteSubflow"|"addToGroup"|"createGroup"|"ungroup"|"removeFromGroup"} HistoryType
* @typedef {{ t: HistoryType; dirty: boolean; callback?: (ev: HistoryEvent) => void; } & {}} HistoryEvent
*
* @typedef {{ source: Node; sourcePort: number; target: Node; }} Link
* @typedef {Node & {}} Group
* @typedef {Node & {}} Junction
* @typedef {Node & { instances: Array<Node>; }} Subflow
* @typedef {Node & {}} Workspace
*/
/**
* Called on the `add` history event
* @param {object} ev The history event to undo
* @param {"add"} ev.t The history event type
* @param {Array<Group>} [ev.groups]
* @param {Array<Junction>} [ev.junctions]
* @param {Array<Link>} [ev.links]
* @param {Array<Node>} [ev.nodes]
* @param {Array<Link>} [ev.removedLinks]
* @param {Subflow} [ev.subflow]
* @param {Array<Subflow>} [ev.subflows]
* @param {Array<Workspace>} [ev.workspaces]
*
* @typedef {object} AddEvent
* @property {"add"} t The history event type
* @property {Array<Group>} [groups] An array with added groups
* @property {Array<Junction>} [junctions] An array with added junctions
* @property {Array<Link>} [links] An array with added links
* @property {Array<Node>} [nodes] An array with added nodes
* @property {Array<Link>} [removedLinks] An array with removed links
* @property {{ id: string; changed?: boolean; instances: Array<Node>; }} [subflow]
* @property {Array<Subflow>} [subflows] An array with added subflows (tabs)
* @property {Array<Workspace>} [workspaces] An array with added workspaces
*
* @param {AddEvent} ev The history event to undo
* @param {object} [modifiedTabs]
* @returns {HistoryEvent} The generated history event to redo
* @returns {DeleteEvent} The generated history event to redo
*/
function onAdd(ev, modifiedTabs) {
const inverseEv = {
@ -157,7 +177,6 @@ RED.history = (function () {
}
}
// Mark each nodes which use this subflow has changed
// TODO: why?
if (ev.subflow) {
inverseEv.subflow = {};
@ -195,22 +214,25 @@ RED.history = (function () {
/**
* Called on the `delete` history event
* @param {object} ev The history event to undo
* @param {"delete"} ev.t The history event type
* @param {Record<string, object>} [ev.changes]
* @param {Array<Link>} [ev.createdLinks]
* @param {boolean} [ev.dirty]
* @param {Array<Group>} [ev.groups]
* @param {Array<Junction>} [ev.junctions]
* @param {Array<Link>} [ev.links]
* @param {Array<Node>} [ev.nodes]
* @param {Subflow} [ev.subflow]
* @param {Array<Node>} [ev.subflowInputs]
* @param {Array<Node>} [ev.subflowOutputs]
* @param {Array<Subflow>} [ev.subflows]
* @param {Array<Workspace>} [ev.workspaces]
*
* @typedef {object} DeleteEvent
* @property {"delete"} t The history event type
* @property {Record<string, object>} [changes] An object with changes.
* The key is the id of a node and the value is an object with the changes to apply
* @property {Array<Link>} [createdLinks] An array with created links
* @property {Array<Group>} [groups] An array with removed groups
* @property {Array<Junction>} [junctions] An array with removed junctions
* @property {Array<Link>} [links] An array with removed links
* @property {Array<Node>} [nodes] An array with removed nodes
* @property {{ id?: string; instances?: Array<Subflow>; status?: string;}} [subflow]
* @property {Array<SubflowNode>} [subflowInputs] An array with removed subflow input
* @property {Array<SubflowNode>} [subflowOutputs] An array with removed subflow outputs
* @property {Array<Subflow>} [subflows] An array with removed subflows (tabs)
* @property {Array<Workspace>} [workspaces] An array with removed workspace
*
* @param {DeleteEvent} ev The history event to undo
* @param {object} [modifiedTabs]
* @returns {HistoryEvent} The generated history event to redo
* @returns {AddEvent} The generated history event to redo
*/
function onDelete(ev, modifiedTabs) {
// TODO: check why global
@ -266,6 +288,7 @@ RED.history = (function () {
}
}
// TODO: why?
if (ev.subflow) {
inverseEv.subflow = {};
if (ev.subflow.hasOwnProperty("instances")) {
@ -400,14 +423,18 @@ RED.history = (function () {
/**
* Called on the `move` history event
* @param {object} ev The history event to undo
* @param {"move"} ev.t The history event type
* @param {Group} [ev.addToGroup]
* @param {Array<Link>} [ev.links]
* @param {Array<{ n: Group; ox: number; oy: number; dx: number; dy: number; }>} ev.nodes
* @param {Array<Link>} [ev.removedLinks]
* @param {Group} [ev.removeFromGroup]
* @returns {HistoryEvent} The generated history event to redo
*
* @typedef {object} MoveEvent
* @property {"move"} t The history event type
* @property {Group} [addToGroup] The group in which the nodes were added
* @property {Array<Link>} [links]
* @property {Array<{ n: Node; ox: number; oy: number; dx: number;
* dy: number; }>} nodes An array with nodes moved
* @property {Array<Link>} [removedLinks]
* @property {Group} [removeFromGroup] The group in which the nodes were removed
*
* @param {MoveEvent} ev The history event to undo
* @returns {MoveEvent} The generated history event to redo
*/
function onMove(ev) {
const inverseEv = {
@ -428,7 +455,7 @@ RED.history = (function () {
}
// A move could have caused a link splice
// So remove each links then readd them
// TODO: still used? Ctrl + X ?
if (ev.links) {
inverseEv.removedLinks = [];
for (let i = 0; i < ev.links.length; i++) {
@ -462,14 +489,20 @@ RED.history = (function () {
/**
* Called on the `createSubflow` history event
* @param {object} ev The history event to undo
* @param {"createSubflow"} ev.t The history event type
* @param {string} ev.activeWorkspace
* @param {Array<Link>} [ev.links]
* @param {Array<string>} [ev.nodes]
* @param {Array<Link>} [ev.removedLinks]
* @param {{ subflow: Subflow; offsetX?: number; offsetY?: number; }} ev.subflow
* @returns {HistoryEvent} The generated history event to redo
*
* @typedef {object} CreateSubflowEvent
* @property {"createSubflow"} t The history event type
* @property {string} activeWorkspace The id of the active workspace
* @property {Array<Link>} [links] An array with added links (during
* conversion to Subflow - links inside the subflow)
* @property {Array<string>} [nodes] An array with subflow node ids
* @property {Array<Link>} [removedLinks] An array with removed links
* (during conversion to Subflow - links from active workspace)
* @property {{ subflow: Subflow; offsetX?: number;
* offsetY?: number; }} subflow The subflow created to delete
*
* @param {CreateSubflowEvent} ev The history event to undo
* @returns {DeleteSubflowEvent} The generated history event to redo
*/
function onCreateSubflow(ev) {
const inverseEv = {
@ -478,11 +511,12 @@ RED.history = (function () {
dirty: RED.nodes.dirty()
};
// Remove all nodes from the subflow
// Remove all subflow nodes and move all nodes from subflow definition
// to the active workspace
if (ev.nodes) {
inverseEv.movedNodes = [];
const z = ev.activeWorkspace;
// Get all nodes from the subflow defiition
// Get all nodes from the subflow definition
let fullNodeList = RED.nodes.filterNodes({ z: ev.subflow.subflow.id });
fullNodeList = fullNodeList.concat(RED.nodes.groups(ev.subflow.subflow.id));
fullNodeList = fullNodeList.concat(RED.nodes.junctions(ev.subflow.subflow.id));
@ -500,7 +534,7 @@ RED.history = (function () {
}
}
// Remove each links
// Remove each links (from the conversion - inside the subflow)
if (ev.links) {
inverseEv.links = [];
for (let i = 0; i < ev.links.length; i++) {
@ -514,7 +548,7 @@ RED.history = (function () {
RED.nodes.removeSubflow(ev.subflow.subflow);
RED.workspaces.remove(ev.subflow.subflow);
// Add each links
// Add each links (from the undo of conversion - active workspace)
if (ev.removedLinks) {
inverseEv.createdLinks = [];
for (let i = 0; i < ev.removedLinks.length; i++) {
@ -528,15 +562,23 @@ RED.history = (function () {
/**
* Called on the `deleteSubflow` history event
* @param {object} ev The history event to undo
* @param {"deleteSubflow"} ev.t The history event type
* @param {string} ev.activeWorkspace
* @param {Array<Link>} [ev.createdLinks]
* @param {Array<Link>} [ev.links]
* @param {Array<Node>} [ev.movedNodes]
* @param {{ subflow: Subflow; offsetX?: number; offsetY?: number; }} ev.subflow
* @param {Array<Subflow>} [ev.subflows]
* @returns {HistoryEvent} The generated history event to redo
*
* @typedef {object} DeleteSubflowEvent
* @property {"deleteSubflow"} t The history event type
* @property {string} activeWorkspace The id of the active workspace
* @property {Array<Link>} [createdLinks] An array with added links
* (during undo conversion to Subflow - links from active workspace)
* @property {Array<Link>} [links] An array with removed links (during
* undo conversion to Subflow - links inside the subflow)
* @property {Array<Node>} [movedNodes] An array with nodes to move to the
* subflow to create
* @property {{ subflow: Subflow; offsetX?: number;
* offsetY?: number; }} subflow The deleted subflow to create
* @property {Array<Subflow>} [subflows] An array with subflow nodes
* (redo conversion to subflow)
*
* @param {DeleteSubflowEvent} ev The history event to undo
* @returns {CreateSubflowEvent} The generated history event to redo
*/
function onDeleteSubflow(ev) {
const inverseEv = {
@ -555,7 +597,7 @@ RED.history = (function () {
}
}
// Create all nodes of the subflow
// Create all subflow nodes
if (ev.subflows) {
inverseEv.nodes = [];
for (let i = 0; i < ev.subflows.length; i++) {
@ -564,6 +606,8 @@ RED.history = (function () {
}
}
// Move each node from the active workspace to the subflow created
// Nodes selected for the conversion to subflow
if (ev.movedNodes) {
ev.movedNodes.forEach(function (nid) {
let nn = RED.nodes.node(nid);
@ -577,7 +621,7 @@ RED.history = (function () {
});
}
// Add each links
// Add each links (from redo of conversion - inside the subflow)
if (ev.links) {
inverseEv.links = [];
for (let i = 0; i < ev.links.length; i++) {
@ -586,7 +630,7 @@ RED.history = (function () {
}
}
// Remove each links
// Remove each links (from redo of conversion - on active workspace)
if (ev.createdLinks) {
inverseEv.removedLinks = [];
for (let i = 0; i < ev.createdLinks.length; i++) {
@ -600,11 +644,14 @@ RED.history = (function () {
/**
* Called on the `reorder` history event
* @param {object} ev The history event to undo
* @param {"reorder"} ev.t The history event type
* @param {{ from: string; to: string; z: string; }} [ev.nodes]
* @param {{ from: Array<string>; to: Array<string>; }} [ev.workspaces]
* @returns {HistoryEvent} The generated history event to redo
*
* @typedef {object} ReorderEvent
* @property {"reorder"} t The history event type
* @property {{ from: string; to: string; z: string; }} [nodes]
* @property {{ from: Array<string>; to: Array<string>; }} [workspaces]
*
* @param {ReorderEvent} ev The history event to undo
* @returns {ReorderEvent} The generated history event to redo
*/
function onReoder(ev) {
const inverseEv = {
@ -634,10 +681,13 @@ RED.history = (function () {
/**
* Called on the `createGroup` history event
* @param {object} ev The history event to undo
* @param {"createGroup"} ev.t The history event type
* @param {Array<Group>} [ev.groups]
* @returns {HistoryEvent} The generated history event to redo
*
* @typedef {object} CreateGroupEvent
* @property {"createGroup"} t The history event type
* @property {Array<Group>} [groups] An array with groups to remove
*
* @param {CreateGroupEvent} ev The history event to undo
* @returns {UngroupEvent} The generated history event to redo
*/
function onCreateGroup(ev) {
const inverseEv = {
@ -659,10 +709,13 @@ RED.history = (function () {
/**
* Called on the `ungroup` history event
* @param {object} ev The history event to undo
* @param {"ungroup"} ev.t The history event type
* @param {Array<Group>} [ev.groups]
* @returns {HistoryEvent} The generated history event to redo
*
* @typedef {object} UngroupEvent
* @property {"ungroup"} t The history event type
* @property {Array<Group>} [groups] An array with groups to create
*
* @param {UngroupEvent} ev The history event to undo
* @returns {CreateGroupEvent} The generated history event to redo
*/
function onUngroup(ev) {
const inverseEv = {
@ -695,12 +748,16 @@ RED.history = (function () {
/**
* Called on the `addToGroup` history event
* @param {object} ev The history event to undo
* @param {"addToGroup"} ev.t The history event type
* @param {Group} [ev.group]
* @param {Array<Node> | Node} [ev.nodes]
* @param {boolean} [ev.reparent]
* @returns {HistoryEvent} The generated history event to redo
*
* @typedef {object} AddToGroupEvent
* @property {"addToGroup"} t The history event type
* @property {Group} group The group in which remove nodes
* @property {Array<Node> | Node} [nodes] An array of nodes or one node
* to remove from the group
* @property {boolean} [reparent]
*
* @param {AddToGroupEvent} ev The history event to undo
* @returns {RemoveFromGroupEvent} The generated history event to redo
*/
function onAddTogroup(ev) {
const inverseEv = {
@ -721,12 +778,16 @@ RED.history = (function () {
/**
* Called on the `removeFromGroup` history event
* @param {object} ev The history event to undo
* @param {"removeFromGroup"} ev.t The history event type
* @param {Group} [ev.group]
* @param {Array<Node> | Node} [ev.nodes]
* @param {boolean} [ev.reparent]
* @returns {HistoryEvent} The generated history event to redo
*
* @typedef {object} RemoveFromGroupEvent
* @property {"removeFromGroup"} t The history event type
* @property {Group} group The group in which add nodes
* @property {Array<Node> | Node} [nodes] An array of nodes or one node
* to add to the group
* @property {boolean} [reparent]
*
* @param {RemoveFromGroupEvent} ev The history event to undo
* @returns {AddToGroupEvent} The generated history event to redo
*/
function onRemoveFromgroup(ev) {
const inverseEv = {
@ -747,17 +808,20 @@ RED.history = (function () {
/**
* Called on the `edit` history event
* @param {object} ev The history event to undo
* @param {"edit"} ev.t The history event type
* @param {boolean} ev.changed
* @param {object} ev.changes
* @param {Array<Link>} [ev.createdLinks]
* @param {Array<Link>} [ev.links]
* @param {Node} ev.node
* @param {object} [ev.outputMap]
* @param {{ instances?: Array<Subflow>; inputCount?: number;
* outputCount?: number; status?: string; }} [ev.subflow]
* @returns {HistoryEvent} The generated history event to redo
*
* @typedef {object} EditEvent
* @property {"edit"} t The history event type
* @property {boolean} changed The changed node state before modifications
* @property {object} changes An object with previous node properties value
* @property {Array<Link>} [createdLinks] An array with links to create (redo)
* @property {Array<Link>} [links] An array with removed links
* @property {Node} node The current node
* @property {object} [outputMap]
* @property {{ instances?: Array<Subflow>; inputCount?: number;
* outputCount?: number; status?: string; }} [subflow]
*
* @param {EditEvent} ev The history event to undo
* @returns {EditEvent} The generated history event to redo
*/
function onEdit(ev) {
const inverseEv = {
@ -769,7 +833,7 @@ RED.history = (function () {
};
// Apply old values to the current node
// And saves values ​​changed by old values
// And saves values ​​changed by old values for the redo
for (const i in ev.changes) {
if (ev.changes.hasOwnProperty(i)) {
inverseEv.changes[i] = ev.node[i];
@ -908,7 +972,7 @@ RED.history = (function () {
}
}
// Remove links previously created (undo)
// Remove links previously created (redo)
if (ev.createdLinks) {
inverseEv.links = [];
for (let i = 0; i < ev.createdLinks.length; i++) {
@ -922,14 +986,22 @@ RED.history = (function () {
/**
* Called on the `replace` history event
* @param {object} ev The history event to undo
* @param {"replace"} ev.t The history event type
* @param {Record<string, boolean>} ev.changed
* @param {boolean} [ev.complete]
* @param {Array<Node>} ev.config
* @param {Record<string, boolean>} ev.moved
* @param {string} [ev.rev]
* @returns {HistoryEvent} The generated history event to redo
*
* @typedef {object} ReplaceEvent
* @property {"replace"} t The history event type
* @property {Record<string, boolean>} [changed] An object with a node id
* as key and the node changed property as value
* @property {boolean} [complete] If the {@link ReplaceEvent.config}
* property contains the complete flows
* @property {Array<Node>} config An array with config nodes and/or
* subflow definitions to replace. Can be the complete flows too
* @property {boolean} [dirty] The dirty state before replacement
* @property {Record<string, boolean>} [moved] An object with a node id
* as key and the node moved property as value
* @property {string} [rev] A revision version
*
* @param {ReplaceEvent} ev The history event to undo
* @returns {ReplaceEvent} The generated history event to redo
*/
function onReplace(ev) {
let inverseEv;
@ -954,6 +1026,7 @@ RED.history = (function () {
const node = RED.nodes.node(n.id);
if (node) {
inverseEv.changed[n.id] = node.changed;
// TODO: Why moved?
inverseEv.moved[n.id] = node.moved;
}
});
@ -1005,10 +1078,13 @@ RED.history = (function () {
/**
* Called on the `multi` history event
* @param {object} ev The history event to undo
* @param {"multi"} ev.t The history event type
* @param {Array<HistoryEvent>} ev.events
* @returns {HistoryEvent} The generated history event to redo
*
* @typedef {object} MultiEvent
* @property {"multi"} t The history event type
* @property {Array<HistoryEvent>} events An array with events
*
* @param {MultiEvent} ev The history event to undo
* @returns {MultiEvent} The generated history event to redo
*/
function onMultipleEvents(ev) {
const inverseEv = {
@ -1027,6 +1103,7 @@ RED.history = (function () {
/**
* Called to undo the history event
*
* @param {HistoryEvent} ev The history event to undo
* @returns {HistoryEvent} The generated history event to redo
*/