ultravisor 1.0.3 → 1.0.8

package/source/services/tasks/file-system/Ultravisor-TaskType-ReadFileBuffered.cjs

@@ -0,0 +1,123 @@
+const libUltravisorTaskType = require('../Ultravisor-TaskType-Base.cjs');
+const libFS = require('fs');
+const libPath = require('path');
+
+/**
+ * Read File Buffered task type.
+ *
+ * Reads a file in chunks up to a maximum buffer size, splitting on the
+ * last occurrence of a preferred split character within the buffer.
+ * Supports continuation via ByteOffset for processing large files
+ * incrementally.
+ */
+class UltravisorTaskTypeReadFileBuffered extends libUltravisorTaskType
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+	}
+
+	get definition()
+	{
+		return require('./definitions/read-file-buffered.json');
+	}
+
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		let tmpFilePath = pResolvedSettings.FilePath || '';
+		let tmpEncoding = pResolvedSettings.Encoding || 'utf8';
+		let tmpMaxBufferSize = parseInt(pResolvedSettings.MaxBufferSize, 10) || 65536;
+		let tmpSplitChar = pResolvedSettings.SplitCharacter;
+		let tmpByteOffset = parseInt(pResolvedSettings.ByteOffset, 10) || 0;
+
+		if (tmpSplitChar === undefined || tmpSplitChar === null)
+		{
+			tmpSplitChar = '\n';
+		}
+
+		if (!tmpFilePath)
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: {},
+				Log: ['ReadFileBuffered: no FilePath specified.']
+			});
+		}
+
+		// Resolve relative paths against the staging folder
+		tmpFilePath = this.resolveFilePath(tmpFilePath, pExecutionContext.StagingPath);
+
+		try
+		{
+			let tmpStat = libFS.statSync(tmpFilePath);
+			let tmpTotalSize = tmpStat.size;
+			let tmpRemainingBytes = tmpTotalSize - tmpByteOffset;
+
+			if (tmpRemainingBytes <= 0)
+			{
+				return fCallback(null, {
+					EventToFire: 'ReadComplete',
+					Outputs:
+					{
+						FileContent: '',
+						BytesRead: 0,
+						ByteOffset: tmpByteOffset,
+						IsComplete: true,
+						FileName: libPath.basename(tmpFilePath),
+						TotalFileSize: tmpTotalSize
+					},
+					Log: ['ReadFileBuffered: already at end of file.']
+				});
+			}
+
+			let tmpReadSize = Math.min(tmpMaxBufferSize, tmpRemainingBytes);
+			let tmpBuffer = Buffer.alloc(tmpReadSize);
+			let tmpFd = libFS.openSync(tmpFilePath, 'r');
+			let tmpActualBytesRead = libFS.readSync(tmpFd, tmpBuffer, 0, tmpReadSize, tmpByteOffset);
+			libFS.closeSync(tmpFd);
+
+			let tmpContent = tmpBuffer.slice(0, tmpActualBytesRead).toString(tmpEncoding);
+			let tmpIsComplete = (tmpByteOffset + tmpActualBytesRead) >= tmpTotalSize;
+			let tmpNewOffset = tmpByteOffset + tmpActualBytesRead;
+
+			// If not at EOF and we have a split character, find the last occurrence
+			if (!tmpIsComplete && tmpSplitChar && tmpSplitChar.length > 0)
+			{
+				let tmpLastSplitIndex = tmpContent.lastIndexOf(tmpSplitChar);
+
+				if (tmpLastSplitIndex > 0)
+				{
+					// Keep content up to and including the split character
+					tmpContent = tmpContent.substring(0, tmpLastSplitIndex + tmpSplitChar.length);
+					tmpNewOffset = tmpByteOffset + Buffer.byteLength(tmpContent, tmpEncoding);
+				}
+			}
+
+			let tmpBytesRead = Buffer.byteLength(tmpContent, tmpEncoding);
+
+			return fCallback(null, {
+				EventToFire: 'ReadComplete',
+				Outputs:
+				{
+					FileContent: tmpContent,
+					BytesRead: tmpBytesRead,
+					ByteOffset: tmpNewOffset,
+					IsComplete: tmpIsComplete,
+					FileName: libPath.basename(tmpFilePath),
+					TotalFileSize: tmpTotalSize
+				},
+				Log: [`ReadFileBuffered: read ${tmpBytesRead} bytes from offset ${tmpByteOffset} (${tmpIsComplete ? 'complete' : 'more data available'})`]
+			});
+		}
+		catch (pError)
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: {},
+				Log: [`ReadFileBuffered: failed: ${pError.message}`]
+			});
+		}
+	}
+}
+
+module.exports = UltravisorTaskTypeReadFileBuffered;

package/source/services/tasks/file-system/Ultravisor-TaskType-WriteFile.cjs

@@ -0,0 +1,106 @@
+const libUltravisorTaskType = require('../Ultravisor-TaskType-Base.cjs');
+const libFS = require('fs');
+const libPath = require('path');
+
+/**
+ * Write File task type.
+ *
+ * Writes content from state to a file on disk. The file path can be
+ * absolute or relative to the operation's staging folder.
+ */
+class UltravisorTaskTypeWriteFile extends libUltravisorTaskType
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+	}
+
+	get definition()
+	{
+		return require('./definitions/write-file.json');
+	}
+
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		let tmpFileLocation = pResolvedSettings.FilePath || '';
+		let tmpContent = pResolvedSettings.Content;
+		let tmpEncoding = pResolvedSettings.Encoding || 'utf8';
+
+		if (!tmpFileLocation)
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: {},
+				Log: ['WriteFile: no FilePath specified.']
+			});
+		}
+
+		if (tmpContent === undefined || tmpContent === null)
+		{
+			tmpContent = '';
+		}
+
+		// Ensure content is a string
+		if (typeof(tmpContent) !== 'string')
+		{
+			tmpContent = JSON.stringify(tmpContent, null, '\t');
+		}
+
+		// Apply line ending conversion
+		let tmpLineEnding = pResolvedSettings.LineEnding || '';
+		if (tmpLineEnding === 'crlf')
+		{
+			tmpContent = tmpContent.replace(/(?<!\r)\n/g, '\r\n');
+		}
+		else if (tmpLineEnding === 'lf')
+		{
+			tmpContent = tmpContent.replace(/\r\n/g, '\n');
+		}
+
+		// Resolve relative paths against the staging folder
+		let tmpFilePath = this.resolveFilePath(tmpFileLocation, pExecutionContext.StagingPath);
+
+		try
+		{
+			// Ensure the directory exists
+			let tmpDir = libPath.dirname(tmpFilePath);
+			if (!libFS.existsSync(tmpDir))
+			{
+				libFS.mkdirSync(tmpDir, { recursive: true });
+			}
+
+			if (pResolvedSettings.Append)
+			{
+				libFS.appendFileSync(tmpFilePath, tmpContent, tmpEncoding);
+			}
+			else
+			{
+				libFS.writeFileSync(tmpFilePath, tmpContent, tmpEncoding);
+			}
+
+			let tmpBytesWritten = Buffer.byteLength(tmpContent, tmpEncoding);
+
+			return fCallback(null, {
+				EventToFire: 'WriteComplete',
+				Outputs:
+				{
+					FileLocation: tmpFileLocation,
+					FileName: libPath.basename(tmpFilePath),
+					FilePath: tmpFilePath,
+					BytesWritten: tmpBytesWritten
+				},
+				Log: [`WriteFile: wrote ${tmpBytesWritten} bytes to ${tmpFilePath}`]
+			});
+		}
+		catch (pError)
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: {},
+				Log: [`WriteFile: failed to write ${tmpFilePath}: ${pError.message}`]
+			});
+		}
+	}
+}
+
+module.exports = UltravisorTaskTypeWriteFile;

package/source/services/tasks/file-system/definitions/copy-file.json

@@ -0,0 +1,27 @@
+{
+	"Hash": "copy-file",
+	"Type": "copy-file",
+	"Name": "Copy File",
+	"Description": "Copies a file from source to target path.",
+	"Category": "file-io",
+	"Capability": "File System",
+	"Action": "Copy",
+	"Tier": "Platform",
+	"EventInputs": [{ "Name": "Trigger" }],
+	"EventOutputs": [
+		{ "Name": "Done" },
+		{ "Name": "Error", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "Source", "DataType": "String", "Required": true, "Description": "Source file path" },
+		{ "Name": "TargetFile", "DataType": "String", "Required": true, "Description": "Target file path" },
+		{ "Name": "Overwrite", "DataType": "Boolean", "Required": false, "Description": "Allow overwriting existing target file (default true)" }
+	],
+	"StateOutputs": [
+		{ "Name": "FileLocation", "DataType": "String", "Description": "The target path the file was referenced at (may be relative)" },
+		{ "Name": "FileName", "DataType": "String", "Description": "The name of the target file only (no directory)" },
+		{ "Name": "FilePath", "DataType": "String", "Description": "The fully resolved absolute path of the target file" },
+		{ "Name": "BytesCopied", "DataType": "Number", "Description": "Size of the copied file in bytes" }
+	],
+	"DefaultSettings": { "Source": "", "TargetFile": "", "Overwrite": true }
+}

package/source/services/tasks/file-system/definitions/list-files.json

@@ -0,0 +1,27 @@
+{
+	"Hash": "list-files",
+	"Type": "list-files",
+	"Name": "List Files",
+	"Description": "Lists files in a directory with optional glob pattern filtering.",
+	"Category": "file-io",
+	"Capability": "File System",
+	"Action": "List",
+	"Tier": "Platform",
+	"EventInputs": [{ "Name": "Trigger" }],
+	"EventOutputs": [
+		{ "Name": "Complete" },
+		{ "Name": "Error", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "Folder", "DataType": "String", "Required": true, "Description": "Directory path to list" },
+		{ "Name": "Pattern", "DataType": "String", "Required": false, "Description": "Glob-style pattern filter (e.g. *.txt)" },
+		{ "Name": "Destination", "DataType": "String", "Required": false, "Description": "State address to store file list" },
+		{ "Name": "Recursive", "DataType": "Boolean", "Required": false, "Description": "Recursively list files in subdirectories" },
+		{ "Name": "IncludeDirectories", "DataType": "Boolean", "Required": false, "Description": "Include directory entries in results" }
+	],
+	"StateOutputs": [
+		{ "Name": "Files", "DataType": "Array", "Description": "Array of file names" },
+		{ "Name": "FileCount", "DataType": "Number", "Description": "Number of entries found" }
+	],
+	"DefaultSettings": { "Folder": "", "Pattern": "*", "Destination": "", "Recursive": false, "IncludeDirectories": false }
+}

package/source/services/tasks/file-system/definitions/read-file-buffered.json

@@ -0,0 +1,31 @@
+{
+	"Hash": "read-file-buffered",
+	"Type": "read-file-buffered",
+	"Name": "Read File Buffered",
+	"Description": "Reads a file in chunks up to a maximum buffer size, splitting on a preferred character boundary.",
+	"Category": "file-io",
+	"Capability": "File System",
+	"Action": "ReadBuffered",
+	"Tier": "Platform",
+	"EventInputs": [{ "Name": "BeginRead", "Description": "Triggers the buffered file read" }],
+	"EventOutputs": [
+		{ "Name": "ReadComplete", "Description": "Fires when chunk is read successfully" },
+		{ "Name": "Error", "Description": "Fires on read failure", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "FilePath", "DataType": "String", "Required": true, "Description": "Path to the file to read" },
+		{ "Name": "Encoding", "DataType": "String", "Required": false, "Description": "File encoding" },
+		{ "Name": "MaxBufferSize", "DataType": "Number", "Required": false, "Description": "Maximum bytes per chunk" },
+		{ "Name": "SplitCharacter", "DataType": "String", "Required": false, "Description": "Preferred character to split on (reads up to last occurrence within buffer)" },
+		{ "Name": "ByteOffset", "DataType": "Number", "Required": false, "Description": "Byte offset to start reading from (for continuation)" }
+	],
+	"StateOutputs": [
+		{ "Name": "FileContent", "DataType": "String", "Description": "Content of this chunk" },
+		{ "Name": "BytesRead", "DataType": "Number", "Description": "Bytes in this chunk" },
+		{ "Name": "ByteOffset", "DataType": "Number", "Description": "Updated byte offset for the next read" },
+		{ "Name": "IsComplete", "DataType": "Boolean", "Description": "True when entire file has been read" },
+		{ "Name": "FileName", "DataType": "String", "Description": "Base name of the file" },
+		{ "Name": "TotalFileSize", "DataType": "Number", "Description": "Total size of the file in bytes" }
+	],
+	"DefaultSettings": { "FilePath": "", "Encoding": "utf8", "MaxBufferSize": 65536, "SplitCharacter": "\n", "ByteOffset": 0 }
+}

package/source/services/tasks/file-system/definitions/read-file.json

@@ -0,0 +1,26 @@
+{
+	"Hash": "read-file",
+	"Type": "read-file",
+	"Name": "Read File",
+	"Description": "Reads a file from disk into state.",
+	"Category": "file-io",
+	"Capability": "File System",
+	"Action": "Read",
+	"Tier": "Platform",
+	"EventInputs": [{ "Name": "BeginRead", "Description": "Triggers the file read" }],
+	"EventOutputs": [
+		{ "Name": "ReadComplete", "Description": "Fires when file is read successfully" },
+		{ "Name": "Error", "Description": "Fires on read failure", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "FilePath", "DataType": "String", "Required": true, "Description": "Path to the file to read" },
+		{ "Name": "Encoding", "DataType": "String", "Required": false, "Default": "utf8", "Description": "File encoding" },
+		{ "Name": "MaxBytes", "DataType": "Number", "Required": false, "Description": "Maximum bytes to read (0 = unlimited)" }
+	],
+	"StateOutputs": [
+		{ "Name": "FileContent", "DataType": "String", "Description": "Contents of the file" },
+		{ "Name": "BytesRead", "DataType": "Number", "Description": "Number of bytes read" },
+		{ "Name": "FileName", "DataType": "String", "Description": "Base name of the file" }
+	],
+	"DefaultSettings": { "FilePath": "", "Encoding": "utf8", "MaxBytes": 0 }
+}

package/source/services/tasks/file-system/definitions/read-json.json

@@ -0,0 +1,23 @@
+{
+	"Hash": "read-json",
+	"Type": "read-json",
+	"Name": "Read JSON",
+	"Description": "Reads a JSON file from disk and parses it into state.",
+	"Category": "file-io",
+	"Capability": "File System",
+	"Action": "ReadJSON",
+	"Tier": "Platform",
+	"EventInputs": [{ "Name": "Trigger" }],
+	"EventOutputs": [
+		{ "Name": "Complete" },
+		{ "Name": "Error", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "FilePath", "DataType": "String", "Required": true, "Description": "Path to the JSON file" },
+		{ "Name": "Destination", "DataType": "String", "Required": false, "Description": "State address to store the parsed data" }
+	],
+	"StateOutputs": [
+		{ "Name": "Data", "DataType": "Object", "Description": "Parsed JSON data" }
+	],
+	"DefaultSettings": { "FilePath": "", "Destination": "" }
+}

package/source/services/tasks/file-system/definitions/write-file.json

@@ -0,0 +1,29 @@
+{
+	"Hash": "write-file",
+	"Type": "write-file",
+	"Name": "Write File",
+	"Description": "Writes content to a file on disk.",
+	"Category": "file-io",
+	"Capability": "File System",
+	"Action": "Write",
+	"Tier": "Platform",
+	"EventInputs": [{ "Name": "BeginWrite", "Description": "Triggers the file write" }],
+	"EventOutputs": [
+		{ "Name": "WriteComplete", "Description": "Fires when file is written successfully" },
+		{ "Name": "Error", "Description": "Fires on write failure", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "FilePath", "DataType": "String", "Required": true, "Description": "Path to the output file" },
+		{ "Name": "Content", "DataType": "String", "Required": true, "Description": "Content to write" },
+		{ "Name": "Encoding", "DataType": "String", "Required": false, "Default": "utf8", "Description": "File encoding" },
+		{ "Name": "Append", "DataType": "Boolean", "Required": false, "Description": "Append to existing file instead of overwriting" },
+		{ "Name": "LineEnding", "DataType": "String", "Required": false, "Description": "Force line ending style: \"lf\", \"crlf\", or empty for no conversion" }
+	],
+	"StateOutputs": [
+		{ "Name": "FileLocation", "DataType": "String", "Description": "The path the file was referenced at (may be relative)" },
+		{ "Name": "FileName", "DataType": "String", "Description": "The name of the file only (no directory)" },
+		{ "Name": "FilePath", "DataType": "String", "Description": "The fully resolved absolute path of the file" },
+		{ "Name": "BytesWritten", "DataType": "Number", "Description": "Number of bytes written" }
+	],
+	"DefaultSettings": { "FilePath": "", "Content": "", "Encoding": "utf8", "Append": false, "LineEnding": "" }
+}

package/source/services/tasks/file-system/definitions/write-json.json

@@ -0,0 +1,30 @@
+{
+	"Hash": "write-json",
+	"Type": "write-json",
+	"Name": "Write JSON",
+	"Description": "Writes a JSON object to a file on disk.",
+	"Category": "file-io",
+	"Capability": "File System",
+	"Action": "WriteJSON",
+	"Tier": "Platform",
+	"EventInputs": [{ "Name": "Trigger" }],
+	"EventOutputs": [
+		{ "Name": "Done" },
+		{ "Name": "Error", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "FilePath", "DataType": "String", "Required": true, "Description": "Path to the output JSON file" },
+		{ "Name": "DataAddress", "DataType": "String", "Required": false, "Description": "State address of the data to write" },
+		{ "Name": "PrettyFormat", "DataType": "Boolean", "Required": false, "Description": "Pretty-print with indentation (default true)" },
+		{ "Name": "IndentType", "DataType": "String", "Required": false, "Description": "Indent character: \"tab\" or \"space\" (default \"tab\")" },
+		{ "Name": "IndentCount", "DataType": "Number", "Required": false, "Description": "Number of indent characters per level (default 1)" },
+		{ "Name": "SortKeys", "DataType": "Boolean", "Required": false, "Description": "Alphabetically sort object keys" }
+	],
+	"StateOutputs": [
+		{ "Name": "FileLocation", "DataType": "String", "Description": "The path the file was referenced at (may be relative)" },
+		{ "Name": "FileName", "DataType": "String", "Description": "The name of the file only (no directory)" },
+		{ "Name": "FilePath", "DataType": "String", "Description": "The fully resolved absolute path of the file" },
+		{ "Name": "BytesWritten", "DataType": "Number", "Description": "Number of bytes written" }
+	],
+	"DefaultSettings": { "FilePath": "", "DataAddress": "", "PrettyFormat": true, "IndentType": "tab", "IndentCount": 1, "SortKeys": false }
+}