ultravisor 1.0.3 → 1.0.8

package/source/services/tasks/flow-control/Ultravisor-TaskConfigs-FlowControl.cjs

@@ -0,0 +1,353 @@
+/**
+ * Flow Control task configurations for Ultravisor.
+ *
+ * Contains task types for controlling execution flow:
+ *   if-conditional, split-execute, launch-operation
+ *
+ * Each entry defines a task type as a config object with:
+ *   Definition  {object}   - Port schema, metadata, default settings
+ *   Execute     {function} - Runtime logic: function(pTask, pSettings, pContext, fCb, fFireEvent)
+ */
+
+
+// ── Module-scoped helpers ───────────────────────────────────────────
+
+/**
+ * Get a service instance from the fable services map.
+ */
+function _getService(pTask, pTypeName)
+{
+	if (pTask.fable.servicesMap[pTypeName])
+	{
+		return Object.values(pTask.fable.servicesMap[pTypeName])[0];
+	}
+	return null;
+}
+
+/**
+ * Compare two values using an operator (used by if-conditional).
+ */
+function _compare(pLeft, pRight, pOperator)
+{
+	switch (pOperator)
+	{
+		case '==':
+			return String(pLeft) == String(pRight);
+		case '===':
+			return pLeft === pRight;
+		case '!=':
+			return String(pLeft) != String(pRight);
+		case '!==':
+			return pLeft !== pRight;
+		case '>':
+			return Number(pLeft) > Number(pRight);
+		case '<':
+			return Number(pLeft) < Number(pRight);
+		case '>=':
+			return Number(pLeft) >= Number(pRight);
+		case '<=':
+			return Number(pLeft) <= Number(pRight);
+		case 'contains':
+			return String(pLeft).indexOf(String(pRight)) > -1;
+		case 'startsWith':
+			return String(pLeft).startsWith(String(pRight));
+		case 'endsWith':
+			return String(pLeft).endsWith(String(pRight));
+		case 'truthy':
+			return !!pLeft;
+		case 'falsy':
+			return !pLeft;
+		default:
+			return String(pLeft) == String(pRight);
+	}
+}
+
+/**
+ * Handle PerformSplit event for split-execute.
+ */
+function _handlePerformSplit(pSettings, pContext, fCallback)
+{
+	let tmpInputString = pSettings.InputString;
+	let tmpDelimiter = pSettings.SplitDelimiter;
+
+	if (typeof(tmpInputString) !== 'string')
+	{
+		return fCallback(null, {
+			EventToFire: 'Error',
+			Outputs: { CurrentToken: '', TokenIndex: 0, TokenCount: 0, CompletedCount: 0 },
+			Log: ['InputString is not a string.']
+		});
+	}
+
+	if (tmpDelimiter === undefined || tmpDelimiter === null)
+	{
+		tmpDelimiter = '\n';
+	}
+
+	let tmpTokens = tmpInputString.split(tmpDelimiter);
+	if (pSettings.TrimTokens)
+	{
+		tmpTokens = tmpTokens.map(function (pT) { return pT.trim(); });
+	}
+	if (pSettings.SkipEmpty)
+	{
+		tmpTokens = tmpTokens.filter(function (pT) { return pT.length > 0; });
+	}
+	let tmpTokenCount = tmpTokens.length;
+	let tmpLog = [`Splitting input (${tmpInputString.length} chars) by "${tmpDelimiter}" into ${tmpTokenCount} tokens.`];
+
+	if (tmpTokenCount === 0)
+	{
+		return fCallback(null, {
+			EventToFire: 'CompletedAllSubtasks',
+			Outputs: { CurrentToken: '', TokenIndex: 0, TokenCount: 0, CompletedCount: 0 },
+			Log: tmpLog.concat(['No tokens to process.'])
+		});
+	}
+
+	let tmpFirstToken = tmpTokens[0];
+	tmpLog.push(`Emitting token 1/${tmpTokenCount}: "${tmpFirstToken.substring(0, 50)}"`);
+
+	return fCallback(null, {
+		EventToFire: 'TokenDataSent',
+		Outputs: {
+			_Tokens: tmpTokens,
+			CurrentToken: tmpFirstToken,
+			TokenIndex: 0,
+			TokenCount: tmpTokenCount,
+			CompletedCount: 0
+		},
+		Log: tmpLog
+	});
+}
+
+/**
+ * Handle StepComplete event for split-execute.
+ */
+function _handleStepComplete(pContext, fCallback)
+{
+	let tmpStoredState = pContext.TaskOutputs[pContext.NodeHash] || {};
+	let tmpTokens = tmpStoredState._Tokens;
+
+	if (!Array.isArray(tmpTokens))
+	{
+		return fCallback(null, {
+			EventToFire: 'Error',
+			Outputs: { CurrentToken: '', TokenIndex: 0, TokenCount: 0, CompletedCount: 0 },
+			Log: ['StepComplete received but no stored tokens found. Was PerformSplit called first?']
+		});
+	}
+
+	let tmpTokenCount = tmpTokens.length;
+	let tmpPreviousIndex = tmpStoredState.TokenIndex || 0;
+	let tmpCompletedCount = (tmpStoredState.CompletedCount || 0) + 1;
+	let tmpNextIndex = tmpPreviousIndex + 1;
+
+	if (tmpNextIndex >= tmpTokenCount)
+	{
+		return fCallback(null, {
+			EventToFire: 'CompletedAllSubtasks',
+			Outputs: {
+				_Tokens: tmpTokens,
+				CurrentToken: tmpTokens[tmpTokenCount - 1],
+				TokenIndex: tmpTokenCount - 1,
+				TokenCount: tmpTokenCount,
+				CompletedCount: tmpCompletedCount
+			},
+			Log: [`All ${tmpTokenCount} tokens processed (${tmpCompletedCount} completed).`]
+		});
+	}
+
+	let tmpNextToken = tmpTokens[tmpNextIndex];
+
+	return fCallback(null, {
+		EventToFire: 'TokenDataSent',
+		Outputs: {
+			_Tokens: tmpTokens,
+			CurrentToken: tmpNextToken,
+			TokenIndex: tmpNextIndex,
+			TokenCount: tmpTokenCount,
+			CompletedCount: tmpCompletedCount
+		},
+		Log: [`Emitting token ${tmpNextIndex + 1}/${tmpTokenCount}: "${tmpNextToken.substring(0, 50)}"`]
+	});
+}
+
+
+// ═══════════════════════════════════════════════════════════════════
+//  FLOW CONTROL TASK CONFIGS
+// ═══════════════════════════════════════════════════════════════════
+
+module.exports =
+[
+	// ── if-conditional ─────────────────────────────────────────
+	{
+		Definition: require('./definitions/if-conditional.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			let tmpResult = false;
+
+			if (pResolvedSettings.Expression && typeof(pResolvedSettings.Expression) === 'string')
+			{
+				try
+				{
+					if (pTask.fable.ExpressionParser)
+					{
+						tmpResult = pTask.fable.ExpressionParser.resolve(pResolvedSettings.Expression, pExecutionContext);
+					}
+					else
+					{
+						tmpResult = !!pResolvedSettings.Expression;
+					}
+				}
+				catch (pError)
+				{
+					return fCallback(null, {
+						EventToFire: 'False',
+						Outputs: { Result: false },
+						Log: [`Expression error: ${pError.message}`]
+					});
+				}
+			}
+			else if (pResolvedSettings.DataAddress)
+			{
+				let tmpDataValue = undefined;
+				let tmpStateManager = pExecutionContext.StateManager;
+
+				if (tmpStateManager)
+				{
+					tmpDataValue = tmpStateManager.resolveAddress(pResolvedSettings.DataAddress, pExecutionContext, pExecutionContext.NodeHash);
+				}
+
+				tmpResult = _compare(tmpDataValue, pResolvedSettings.CompareValue, pResolvedSettings.Operator || '==');
+			}
+
+			return fCallback(null, {
+				EventToFire: tmpResult ? 'True' : 'False',
+				Outputs: { Result: tmpResult },
+				Log: [`Condition evaluated to ${tmpResult}.`]
+			});
+		}
+	},
+
+	// ── split-execute ──────────────────────────────────────────
+	{
+		Definition: require('./definitions/split-execute.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			if (pExecutionContext.TriggeringEventName === 'StepComplete')
+			{
+				return _handleStepComplete(pExecutionContext, fCallback);
+			}
+
+			return _handlePerformSplit(pResolvedSettings, pExecutionContext, fCallback);
+		}
+	},
+
+	// ── launch-operation ───────────────────────────────────────
+	{
+		Definition: require('./definitions/launch-operation.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			let tmpOperationHash = pResolvedSettings.OperationHash;
+
+			if (!tmpOperationHash || typeof(tmpOperationHash) !== 'string' || tmpOperationHash.length === 0)
+			{
+				return fCallback(null, { EventToFire: 'Error', Outputs: { Result: '', Status: 'Error', ElapsedMs: 0 }, Log: ['No OperationHash specified.'] });
+			}
+
+			let tmpStateService = _getService(pTask, 'UltravisorHypervisorState');
+			if (!tmpStateService)
+			{
+				return fCallback(null, { EventToFire: 'Error', Outputs: { Result: '', Status: 'Error', ElapsedMs: 0 }, Log: ['UltravisorHypervisorState service not found.'] });
+			}
+
+			let tmpEngine = _getService(pTask, 'UltravisorExecutionEngine');
+			if (!tmpEngine)
+			{
+				return fCallback(null, { EventToFire: 'Error', Outputs: { Result: '', Status: 'Error', ElapsedMs: 0 }, Log: ['UltravisorExecutionEngine service not found.'] });
+			}
+
+			tmpStateService.getOperation(tmpOperationHash,
+				function (pError, pOperation)
+				{
+					if (pError)
+					{
+						return fCallback(null, { EventToFire: 'Error', Outputs: { Result: '', Status: 'Error', ElapsedMs: 0 }, Log: [`Operation [${tmpOperationHash}] not found: ${pError.message}`] });
+					}
+
+					let tmpInitialState = {
+						GlobalState: (pResolvedSettings.InheritGlobalState === false) ? {} : JSON.parse(JSON.stringify(pExecutionContext.GlobalState || {})),
+						OperationState: {},
+						RunMode: pExecutionContext.RunMode || 'standard'
+					};
+
+					if (pResolvedSettings.InputData && typeof(pResolvedSettings.InputData) === 'string' && pResolvedSettings.InputData.length > 0)
+					{
+						try
+						{
+							let tmpInputData = JSON.parse(pResolvedSettings.InputData);
+							if (typeof(tmpInputData) === 'object' && tmpInputData !== null)
+							{
+								tmpInitialState.OperationState = tmpInputData;
+							}
+						}
+						catch (pParseError)
+						{
+							tmpInitialState.OperationState.InputData = pResolvedSettings.InputData;
+						}
+					}
+
+					let tmpStartTime = Date.now();
+					let tmpTimeoutMs = parseInt(pResolvedSettings.TimeoutMs, 10) || 0;
+					let tmpCompleted = false;
+					let tmpTimeoutHandle = null;
+
+					if (tmpTimeoutMs > 0)
+					{
+						tmpTimeoutHandle = setTimeout(function()
+						{
+							if (!tmpCompleted)
+							{
+								tmpCompleted = true;
+								let tmpElapsedMs = Date.now() - tmpStartTime;
+								return fCallback(null, {
+									EventToFire: 'Error',
+									Outputs: { Result: 'Operation timed out', Status: 'Timeout', ElapsedMs: tmpElapsedMs },
+									Log: [`Child operation [${tmpOperationHash}] timed out after ${tmpTimeoutMs}ms`]
+								});
+							}
+						}, tmpTimeoutMs);
+					}
+
+					tmpEngine.executeOperation(pOperation, tmpInitialState,
+						function (pExecError, pContext)
+						{
+							if (tmpCompleted) { return; }
+							tmpCompleted = true;
+							if (tmpTimeoutHandle) { clearTimeout(tmpTimeoutHandle); }
+
+							let tmpElapsedMs = Date.now() - tmpStartTime;
+
+							if (pExecError)
+							{
+								return fCallback(null, {
+									EventToFire: 'Error',
+									Outputs: { Result: pExecError.message, Status: 'Error', ElapsedMs: tmpElapsedMs },
+									Log: [`Child operation [${tmpOperationHash}] failed: ${pExecError.message}`]
+								});
+							}
+
+							let tmpStatus = pContext.Status || 'Unknown';
+							let tmpResultSummary = JSON.stringify({ Status: tmpStatus, TaskOutputs: pContext.TaskOutputs || {}, Errors: pContext.Errors || [] });
+
+							return fCallback(null, {
+								EventToFire: 'Completed',
+								Outputs: { Result: tmpResultSummary, Status: tmpStatus, ElapsedMs: tmpElapsedMs },
+								Log: [`Child operation [${tmpOperationHash}] completed with status: ${tmpStatus} (${tmpElapsedMs}ms)`]
+							});
+						});
+				});
+		}
+	}
+];

package/source/services/tasks/flow-control/Ultravisor-TaskType-IfConditional.cjs

@@ -0,0 +1,125 @@
+const libTaskTypeBase = require('../Ultravisor-TaskType-Base.cjs');
+
+/**
+ * IfConditional Task Type
+ *
+ * Evaluates a simple expression and fires either the True or False event.
+ * Supports comparisons via DataAddress and CompareValue, or a direct Expression string.
+ *
+ * If DataAddress is set, reads the value at that address and compares
+ * it to CompareValue using the Operator (default: '==').
+ *
+ * If Expression is set instead, evaluates it using fable.ExpressionParser.
+ */
+class UltravisorTaskTypeIfConditional extends libTaskTypeBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorTaskTypeIfConditional';
+	}
+
+	get definition()
+	{
+		return require('./definitions/if-conditional.json');
+	}
+
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		let tmpResult = false;
+
+		if (pResolvedSettings.Expression && typeof(pResolvedSettings.Expression) === 'string')
+		{
+			// Expression-based evaluation using Fable's ExpressionParser
+			try
+			{
+				if (this.fable.ExpressionParser)
+				{
+					tmpResult = this.fable.ExpressionParser.resolve(pResolvedSettings.Expression, pExecutionContext);
+				}
+				else
+				{
+					// Simple truthy evaluation fallback
+					tmpResult = !!pResolvedSettings.Expression;
+				}
+			}
+			catch (pError)
+			{
+				return fCallback(null, {
+					EventToFire: 'False',
+					Outputs: { Result: false },
+					Log: [`Expression error: ${pError.message}`]
+				});
+			}
+		}
+		else if (pResolvedSettings.DataAddress)
+		{
+			// Address-based comparison
+			let tmpDataValue = undefined;
+			let tmpStateManager = pExecutionContext.StateManager;
+
+			if (tmpStateManager)
+			{
+				tmpDataValue = tmpStateManager.resolveAddress(
+					pResolvedSettings.DataAddress, pExecutionContext, pExecutionContext.NodeHash);
+			}
+
+			let tmpCompareValue = pResolvedSettings.CompareValue;
+			let tmpOperator = pResolvedSettings.Operator || '==';
+
+			tmpResult = this._compare(tmpDataValue, tmpCompareValue, tmpOperator);
+		}
+
+		return fCallback(null, {
+			EventToFire: tmpResult ? 'True' : 'False',
+			Outputs: { Result: tmpResult },
+			Log: [`Condition evaluated to ${tmpResult}.`]
+		});
+	}
+
+	/**
+	 * Compare two values using an operator.
+	 *
+	 * @param {*} pLeft - Left operand.
+	 * @param {*} pRight - Right operand.
+	 * @param {string} pOperator - The comparison operator.
+	 * @returns {boolean} Result of comparison.
+	 */
+	_compare(pLeft, pRight, pOperator)
+	{
+		switch (pOperator)
+		{
+			case '==':
+				return String(pLeft) == String(pRight);
+			case '===':
+				return pLeft === pRight;
+			case '!=':
+				return String(pLeft) != String(pRight);
+			case '!==':
+				return pLeft !== pRight;
+			case '>':
+				return Number(pLeft) > Number(pRight);
+			case '<':
+				return Number(pLeft) < Number(pRight);
+			case '>=':
+				return Number(pLeft) >= Number(pRight);
+			case '<=':
+				return Number(pLeft) <= Number(pRight);
+			case 'contains':
+				return String(pLeft).indexOf(String(pRight)) > -1;
+			case 'startsWith':
+				return String(pLeft).startsWith(String(pRight));
+			case 'endsWith':
+				return String(pLeft).endsWith(String(pRight));
+			case 'truthy':
+				return !!pLeft;
+			case 'falsy':
+				return !pLeft;
+			default:
+				return String(pLeft) == String(pRight);
+		}
+	}
+}
+
+module.exports = UltravisorTaskTypeIfConditional;

package/source/services/tasks/flow-control/Ultravisor-TaskType-LaunchOperation.cjs

@@ -0,0 +1,186 @@
+const libTaskTypeBase = require('../Ultravisor-TaskType-Base.cjs');
+
+/**
+ * LaunchOperation Task Type
+ *
+ * Executes a child operation within the current operation's graph.
+ * Looks up the target operation by hash from the Hypervisor's state,
+ * creates an isolated execution context for it, and runs it via the
+ * ExecutionEngine.
+ *
+ * The child operation gets its own OperationState (optionally seeded
+ * from InputData) but shares the parent's GlobalState (as a copy).
+ *
+ * Flow:
+ *   Launch -> (execute child operation) -> Completed or Error
+ */
+class UltravisorTaskTypeLaunchOperation extends libTaskTypeBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorTaskTypeLaunchOperation';
+	}
+
+	get definition()
+	{
+		return require('./definitions/launch-operation.json');
+	}
+
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		let tmpOperationHash = pResolvedSettings.OperationHash;
+
+		if (!tmpOperationHash || typeof(tmpOperationHash) !== 'string' || tmpOperationHash.length === 0)
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: { Result: '', Status: 'Error', ElapsedMs: 0 },
+				Log: ['No OperationHash specified.']
+			});
+		}
+
+		// Get the Hypervisor state service to look up the operation
+		let tmpStateService = this._getService('UltravisorHypervisorState');
+
+		if (!tmpStateService)
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: { Result: '', Status: 'Error', ElapsedMs: 0 },
+				Log: ['UltravisorHypervisorState service not found.']
+			});
+		}
+
+		// Get the ExecutionEngine to run the child operation
+		let tmpEngine = this._getService('UltravisorExecutionEngine');
+
+		if (!tmpEngine)
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: { Result: '', Status: 'Error', ElapsedMs: 0 },
+				Log: ['UltravisorExecutionEngine service not found.']
+			});
+		}
+
+		// Look up the target operation
+		tmpStateService.getOperation(tmpOperationHash,
+			(pError, pOperation) =>
+			{
+				if (pError)
+				{
+					return fCallback(null, {
+						EventToFire: 'Error',
+						Outputs: { Result: '', Status: 'Error', ElapsedMs: 0 },
+						Log: [`Operation [${tmpOperationHash}] not found: ${pError.message}`]
+					});
+				}
+
+				// Build initial state for the child operation
+				let tmpInitialState = {
+					// Share a copy of the parent's global state (unless InheritGlobalState is false)
+					GlobalState: (pResolvedSettings.InheritGlobalState === false) ? {} : JSON.parse(JSON.stringify(pExecutionContext.GlobalState || {})),
+					// Isolated operation state, optionally seeded from InputData
+					OperationState: {},
+					RunMode: pExecutionContext.RunMode || 'standard'
+				};
+
+				// Parse InputData if provided (expects JSON string)
+				if (pResolvedSettings.InputData && typeof(pResolvedSettings.InputData) === 'string' && pResolvedSettings.InputData.length > 0)
+				{
+					try
+					{
+						let tmpInputData = JSON.parse(pResolvedSettings.InputData);
+						if (typeof(tmpInputData) === 'object' && tmpInputData !== null)
+						{
+							tmpInitialState.OperationState = tmpInputData;
+						}
+					}
+					catch (pParseError)
+					{
+						// If not valid JSON, store as a raw string in OperationState.InputData
+						tmpInitialState.OperationState.InputData = pResolvedSettings.InputData;
+					}
+				}
+
+				let tmpStartTime = Date.now();
+				let tmpTimeoutMs = parseInt(pResolvedSettings.TimeoutMs, 10) || 0;
+				let tmpCompleted = false;
+				let tmpTimeoutHandle = null;
+
+				if (tmpTimeoutMs > 0)
+				{
+					tmpTimeoutHandle = setTimeout(function()
+					{
+						if (!tmpCompleted)
+						{
+							tmpCompleted = true;
+							let tmpElapsedMs = Date.now() - tmpStartTime;
+							return fCallback(null, {
+								EventToFire: 'Error',
+								Outputs: { Result: 'Operation timed out', Status: 'Timeout', ElapsedMs: tmpElapsedMs },
+								Log: [`Child operation [${tmpOperationHash}] timed out after ${tmpTimeoutMs}ms`]
+							});
+						}
+					}, tmpTimeoutMs);
+				}
+
+				// Execute the child operation
+				tmpEngine.executeOperation(pOperation, tmpInitialState,
+					(pExecError, pContext) =>
+					{
+						if (tmpCompleted) { return; }
+						tmpCompleted = true;
+						if (tmpTimeoutHandle) { clearTimeout(tmpTimeoutHandle); }
+
+						let tmpElapsedMs = Date.now() - tmpStartTime;
+
+						if (pExecError)
+						{
+							return fCallback(null, {
+								EventToFire: 'Error',
+								Outputs: {
+									Result: pExecError.message,
+									Status: 'Error',
+									ElapsedMs: tmpElapsedMs
+								},
+								Log: [`Child operation [${tmpOperationHash}] failed: ${pExecError.message}`]
+							});
+						}
+
+						let tmpStatus = pContext.Status || 'Unknown';
+						let tmpResultSummary = JSON.stringify({
+							Status: tmpStatus,
+							TaskOutputs: pContext.TaskOutputs || {},
+							Errors: pContext.Errors || []
+						});
+
+						return fCallback(null, {
+							EventToFire: 'Completed',
+							Outputs: {
+								Result: tmpResultSummary,
+								Status: tmpStatus,
+								ElapsedMs: tmpElapsedMs
+							},
+							Log: [`Child operation [${tmpOperationHash}] completed with status: ${tmpStatus} (${tmpElapsedMs}ms)`]
+						});
+					});
+			});
+	}
+
+	/**
+	 * Get a service instance from the fable services map.
+	 */
+	_getService(pTypeName)
+	{
+		if (this.fable.servicesMap[pTypeName])
+		{
+			return Object.values(this.fable.servicesMap[pTypeName])[0];
+		}
+		return null;
+	}
+}
+
+module.exports = UltravisorTaskTypeLaunchOperation;