meadow-integration 1.0.19 → 1.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "meadow-integration",
-    "version": "1.0.19",
+    "version": "1.0.20",
     "description": "Meadow Data Integration",
     "bin": {
         "mdwint": "source/cli/Meadow-Integration-CLI-Run.js"
@@ -39,12 +39,14 @@
     "dependencies": {
         "fable": "^3.1.63",
         "fable-serviceproviderbase": "^3.0.19",
+        "fast-xml-parser": "^4.4.1",
         "meadow": "^2.0.33",
         "meadow-connection-mssql": "^1.0.16",
         "meadow-connection-mysql": "^1.0.14",
         "orator": "^6.0.4",
         "orator-serviceserver-restify": "^2.0.9",
         "pict-service-commandlineutility": "^1.0.19",
-        "pict-sessionmanager": "^1.0.2"
+        "pict-sessionmanager": "^1.0.2",
+        "xlsx": "^0.18.5"
     }
 }

package/source/Meadow-Integration.js

@@ -11,6 +11,13 @@ const libOperation = require(`./services/clone/Meadow-Service-Operation.js`);
 const libIntegrationAdapter = require(`./Meadow-Service-Integration-Adapter.js`);
 const libGUIDMap = require(`./Meadow-Service-Integration-GUIDMap.js`);
 
+const libFileParser = require(`./services/parser/Service-FileParser.js`);
+const libFileParserCSV = require(`./services/parser/Service-FileParser-CSV.js`);
+const libFileParserJSON = require(`./services/parser/Service-FileParser-JSON.js`);
+const libFileParserXLSX = require(`./services/parser/Service-FileParser-XLSX.js`);
+const libFileParserXML = require(`./services/parser/Service-FileParser-XML.js`);
+const libFileParserFixedWidth = require(`./services/parser/Service-FileParser-FixedWidth.js`);
+
 module.exports = (
 	{
 		TabularCheck: libTabularCheck,
@@ -24,5 +31,12 @@ module.exports = (
 		Operation: libOperation,
 
 		IntegrationAdapter: libIntegrationAdapter,
-		GUIDMap: libGUIDMap
+		GUIDMap: libGUIDMap,
+
+		FileParser: libFileParser,
+		FileParserCSV: libFileParserCSV,
+		FileParserJSON: libFileParserJSON,
+		FileParserXLSX: libFileParserXLSX,
+		FileParserXML: libFileParserXML,
+		FileParserFixedWidth: libFileParserFixedWidth
 	});

package/source/services/parser/Service-FileParser-CSV.js

@@ -0,0 +1,263 @@
+'use strict';
+
+const libFableServiceProviderBase = require('fable-serviceproviderbase');
+const libFS = require('fs');
+const libReadline = require('readline');
+
+const defaultCSVParserOptions = (
+	{
+		delimiter: ',',
+		quoteChar: '"',
+		hasHeaders: true,
+		skipRows: 0,
+		commentPrefix: '',
+		trim: true,
+		chunkSize: 100
+	});
+
+class MeadowIntegrationFileParserCSV extends libFableServiceProviderBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		let tmpOptions = Object.assign({}, defaultCSVParserOptions, pOptions);
+		super(pFable, tmpOptions, pServiceHash);
+
+		this.serviceType = 'MeadowIntegrationFileParserCSV';
+
+		this._headers = null;
+	}
+
+	/**
+	 * Parse a single CSV line into an array of values.
+	 * Handles quoted fields (including embedded commas and escaped quotes).
+	 *
+	 * @param {string} pLine - Raw CSV line
+	 * @param {string} pDelimiter - Field delimiter character
+	 * @param {string} pQuoteChar - Quote character
+	 * @param {boolean} pTrim - Whether to trim field values
+	 * @returns {Array<string>} Parsed field values
+	 */
+	_parseCSVLine(pLine, pDelimiter, pQuoteChar, pTrim)
+	{
+		let tmpDelimiter = pDelimiter || ',';
+		let tmpQuoteChar = pQuoteChar || '"';
+		let tmpValues = [];
+		let tmpCurrent = '';
+		let tmpInQuotes = false;
+
+		for (let i = 0; i < pLine.length; i++)
+		{
+			let tmpChar = pLine[i];
+
+			if (tmpChar === tmpQuoteChar)
+			{
+				if (tmpInQuotes && pLine[i + 1] === tmpQuoteChar)
+				{
+					// Escaped quote (doubled)
+					tmpCurrent += tmpQuoteChar;
+					i++;
+				}
+				else
+				{
+					tmpInQuotes = !tmpInQuotes;
+				}
+			}
+			else if (tmpChar === tmpDelimiter && !tmpInQuotes)
+			{
+				tmpValues.push(pTrim ? tmpCurrent.trim() : tmpCurrent);
+				tmpCurrent = '';
+			}
+			else
+			{
+				tmpCurrent += tmpChar;
+			}
+		}
+
+		tmpValues.push(pTrim ? tmpCurrent.trim() : tmpCurrent);
+		return tmpValues;
+	}
+
+	/**
+	 * Parse a CSV file using streaming readline.
+	 * Fires chunkCallback with arrays of records as they accumulate.
+	 * Fires completionCallback when the file is fully consumed.
+	 *
+	 * @param {string} pFilePath - Absolute path to the CSV file
+	 * @param {object} pOptions - Parser options (overrides instance options)
+	 * @param {function} pChunkCallback - Called with (pError, pRecords) per chunk
+	 * @param {function} pCompletionCallback - Called with (pError, pTotalCount) when done
+	 */
+	parseFile(pFilePath, pOptions, pChunkCallback, pCompletionCallback)
+	{
+		let tmpOptions = Object.assign({}, this.options, pOptions);
+		let tmpChunkSize = tmpOptions.chunkSize || 100;
+		let tmpHasHeaders = tmpOptions.hasHeaders !== false;
+		let tmpSkipRows = parseInt(tmpOptions.skipRows, 10) || 0;
+		let tmpCommentPrefix = tmpOptions.commentPrefix || '';
+		let tmpTrim = tmpOptions.trim !== false;
+		let tmpDelimiter = tmpOptions.delimiter || ',';
+		let tmpQuoteChar = tmpOptions.quoteChar || '"';
+
+		this._headers = null;
+
+		let tmpLineIndex = 0;
+		let tmpRecordCount = 0;
+		let tmpChunkBuffer = [];
+
+		const tmpReadline = libReadline.createInterface(
+			{
+				input: libFS.createReadStream(pFilePath),
+				crlfDelay: Infinity
+			});
+
+		tmpReadline.on('line',
+			(pLine) =>
+			{
+				// Skip comment lines
+				if (tmpCommentPrefix && pLine.startsWith(tmpCommentPrefix))
+				{
+					return;
+				}
+
+				// Skip header/preamble rows
+				if (tmpLineIndex < tmpSkipRows)
+				{
+					tmpLineIndex++;
+					return;
+				}
+
+				let tmpValues = this._parseCSVLine(pLine, tmpDelimiter, tmpQuoteChar, tmpTrim);
+
+				// First non-skipped, non-comment line becomes headers
+				if (tmpHasHeaders && !this._headers)
+				{
+					this._headers = tmpValues;
+					tmpLineIndex++;
+					return;
+				}
+
+				let tmpRecord;
+				if (this._headers)
+				{
+					tmpRecord = {};
+					for (let i = 0; i < this._headers.length; i++)
+					{
+						tmpRecord[this._headers[i]] = (tmpValues && tmpValues[i] !== undefined) ? tmpValues[i] : '';
+					}
+				}
+				else
+				{
+					tmpRecord = tmpValues || [];
+				}
+
+				tmpChunkBuffer.push(tmpRecord);
+				tmpRecordCount++;
+				tmpLineIndex++;
+
+				if (tmpChunkBuffer.length >= tmpChunkSize)
+				{
+					pChunkCallback(null, tmpChunkBuffer.splice(0, tmpChunkBuffer.length));
+				}
+			});
+
+		tmpReadline.on('close',
+			() =>
+			{
+				if (tmpChunkBuffer.length > 0)
+				{
+					pChunkCallback(null, tmpChunkBuffer.splice(0, tmpChunkBuffer.length));
+				}
+				return pCompletionCallback(null, tmpRecordCount);
+			});
+
+		tmpReadline.on('error',
+			(pError) =>
+			{
+				return pCompletionCallback(pError);
+			});
+	}
+
+	/**
+	 * Parse CSV content string into a full array of records.
+	 *
+	 * @param {string} pContent - Raw CSV text
+	 * @param {object} pOptions - Parser options
+	 * @param {function} fCallback - Called with (pError, pRecords)
+	 */
+	parseContent(pContent, pOptions, fCallback)
+	{
+		let tmpOptions = Object.assign({}, this.options, pOptions);
+		let tmpHasHeaders = tmpOptions.hasHeaders !== false;
+		let tmpSkipRows = parseInt(tmpOptions.skipRows, 10) || 0;
+		let tmpCommentPrefix = tmpOptions.commentPrefix || '';
+		let tmpTrim = tmpOptions.trim !== false;
+		let tmpDelimiter = tmpOptions.delimiter || ',';
+		let tmpQuoteChar = tmpOptions.quoteChar || '"';
+
+		let tmpLines = pContent.split('\n');
+		let tmpHeaders = null;
+		let tmpRecords = [];
+		let tmpLineIndex = 0;
+
+		for (let i = 0; i < tmpLines.length; i++)
+		{
+			let tmpLine = tmpLines[i];
+
+			// Strip trailing \r for Windows line endings
+			if (tmpLine.length > 0 && tmpLine[tmpLine.length - 1] === '\r')
+			{
+				tmpLine = tmpLine.slice(0, -1);
+			}
+
+			// Skip comment lines
+			if (tmpCommentPrefix && tmpLine.startsWith(tmpCommentPrefix))
+			{
+				continue;
+			}
+
+			// Skip preamble rows
+			if (tmpLineIndex < tmpSkipRows)
+			{
+				tmpLineIndex++;
+				continue;
+			}
+
+			// Skip blank lines
+			if (!tmpLine || tmpLine.trim().length === 0)
+			{
+				tmpLineIndex++;
+				continue;
+			}
+
+			let tmpValues = this._parseCSVLine(tmpLine, tmpDelimiter, tmpQuoteChar, tmpTrim);
+
+			if (tmpHasHeaders && !tmpHeaders)
+			{
+				tmpHeaders = tmpValues;
+				tmpLineIndex++;
+				continue;
+			}
+
+			let tmpRecord;
+			if (tmpHeaders)
+			{
+				tmpRecord = {};
+				for (let j = 0; j < tmpHeaders.length; j++)
+				{
+					tmpRecord[tmpHeaders[j]] = (tmpValues && tmpValues[j] !== undefined) ? tmpValues[j] : '';
+				}
+			}
+			else
+			{
+				tmpRecord = tmpValues || [];
+			}
+
+			tmpRecords.push(tmpRecord);
+			tmpLineIndex++;
+		}
+
+		return fCallback(null, tmpRecords);
+	}
+}
+
+module.exports = MeadowIntegrationFileParserCSV;

package/source/services/parser/Service-FileParser-FixedWidth.js

@@ -0,0 +1,158 @@
+'use strict';
+
+const libFableServiceProviderBase = require('fable-serviceproviderbase');
+const libFS = require('fs');
+const libReadline = require('readline');
+
+const defaultFixedWidthParserOptions = (
+	{
+		skipLines: 0,
+		columns: []
+	});
+
+class MeadowIntegrationFileParserFixedWidth extends libFableServiceProviderBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		let tmpOptions = Object.assign({}, defaultFixedWidthParserOptions, pOptions);
+		super(pFable, tmpOptions, pServiceHash);
+
+		this.serviceType = 'MeadowIntegrationFileParserFixedWidth';
+	}
+
+	/**
+	 * Extract fields from a fixed-width line using a columns definition.
+	 * Column start positions are 1-based.
+	 *
+	 * @param {string} pLine - Raw text line
+	 * @param {Array} pColumns - Array of {name, start, width}
+	 * @returns {object} Extracted record
+	 */
+	_parseLine(pLine, pColumns)
+	{
+		let tmpRecord = {};
+		for (let i = 0; i < pColumns.length; i++)
+		{
+			let tmpCol = pColumns[i];
+			// start is 1-based
+			let tmpStartIdx = (parseInt(tmpCol.start, 10) || 1) - 1;
+			let tmpWidth = parseInt(tmpCol.width, 10) || 0;
+			let tmpValue = pLine.substring(tmpStartIdx, tmpStartIdx + tmpWidth).trim();
+			tmpRecord[tmpCol.name] = tmpValue;
+		}
+		return tmpRecord;
+	}
+
+	/**
+	 * Parse a fixed-width file using streaming readline.
+	 *
+	 * @param {string} pFilePath - Absolute path to the fixed-width file
+	 * @param {object} pOptions - Parser options: skipLines, columns, chunkSize
+	 * @param {function} pChunkCallback - Called with (pError, pRecords) per chunk
+	 * @param {function} pCompletionCallback - Called with (pError, pTotalCount) when done
+	 */
+	parseFile(pFilePath, pOptions, pChunkCallback, pCompletionCallback)
+	{
+		let tmpOptions = Object.assign({}, this.options, pOptions);
+		let tmpColumns = tmpOptions.columns || [];
+		let tmpSkipLines = parseInt(tmpOptions.skipLines, 10) || 0;
+		let tmpChunkSize = parseInt(tmpOptions.chunkSize, 10) || 100;
+
+		if (!tmpColumns || tmpColumns.length === 0)
+		{
+			return pCompletionCallback(new Error('FixedWidth parser requires options.columns array of {name, start, width}'));
+		}
+
+		let tmpLineIndex = 0;
+		let tmpRecordCount = 0;
+		let tmpChunkBuffer = [];
+
+		const tmpReadline = libReadline.createInterface(
+			{
+				input: libFS.createReadStream(pFilePath),
+				crlfDelay: Infinity
+			});
+
+		tmpReadline.on('line',
+			(pLine) =>
+			{
+				if (tmpLineIndex < tmpSkipLines)
+				{
+					tmpLineIndex++;
+					return;
+				}
+
+				// Skip blank lines
+				if (!pLine || pLine.trim().length === 0)
+				{
+					tmpLineIndex++;
+					return;
+				}
+
+				let tmpRecord = this._parseLine(pLine, tmpColumns);
+				tmpChunkBuffer.push(tmpRecord);
+				tmpRecordCount++;
+				tmpLineIndex++;
+
+				if (tmpChunkBuffer.length >= tmpChunkSize)
+				{
+					pChunkCallback(null, tmpChunkBuffer.splice(0, tmpChunkBuffer.length));
+				}
+			});
+
+		tmpReadline.on('close',
+			() =>
+			{
+				if (tmpChunkBuffer.length > 0)
+				{
+					pChunkCallback(null, tmpChunkBuffer.splice(0, tmpChunkBuffer.length));
+				}
+				return pCompletionCallback(null, tmpRecordCount);
+			});
+
+		tmpReadline.on('error',
+			(pError) =>
+			{
+				return pCompletionCallback(pError);
+			});
+	}
+
+	/**
+	 * Parse fixed-width content string into a full array of records.
+	 *
+	 * @param {string} pContent - Raw fixed-width text
+	 * @param {object} pOptions - Parser options
+	 * @param {function} fCallback - Called with (pError, pRecords)
+	 */
+	parseContent(pContent, pOptions, fCallback)
+	{
+		let tmpOptions = Object.assign({}, this.options, pOptions);
+		let tmpColumns = tmpOptions.columns || [];
+		let tmpSkipLines = parseInt(tmpOptions.skipLines, 10) || 0;
+
+		if (!tmpColumns || tmpColumns.length === 0)
+		{
+			return fCallback(new Error('FixedWidth parser requires options.columns array of {name, start, width}'));
+		}
+
+		let tmpLines = pContent.split('\n');
+		let tmpRecords = [];
+
+		for (let i = tmpSkipLines; i < tmpLines.length; i++)
+		{
+			let tmpLine = tmpLines[i];
+
+			// Skip blank lines
+			if (!tmpLine || tmpLine.trim().length === 0)
+			{
+				continue;
+			}
+
+			tmpRecords.push(this._parseLine(tmpLine, tmpColumns));
+		}
+
+		return fCallback(null, tmpRecords);
+	}
+}
+
+module.exports = MeadowIntegrationFileParserFixedWidth;

package/source/services/parser/Service-FileParser-JSON.js

@@ -0,0 +1,255 @@
+'use strict';
+
+const libFableServiceProviderBase = require('fable-serviceproviderbase');
+const libFS = require('fs');
+
+const defaultJSONParserOptions = (
+	{
+		rootPath: '',
+		flattenNested: false,
+		flattenDelimiter: '_'
+	});
+
+class MeadowIntegrationFileParserJSON extends libFableServiceProviderBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		let tmpOptions = Object.assign({}, defaultJSONParserOptions, pOptions);
+		super(pFable, tmpOptions, pServiceHash);
+
+		this.serviceType = 'MeadowIntegrationFileParserJSON';
+	}
+
+	/**
+	 * Navigate a nested object using a dot-separated path with optional
+	 * array index notation (e.g. "Results.series[0].data").
+	 *
+	 * @param {object} pObject - The object to navigate
+	 * @param {string} pPath - Dot-separated path, segments may include [n]
+	 * @returns {*} The resolved value, or null if the path is invalid
+	 */
+	_resolveDataPath(pObject, pPath)
+	{
+		if (!pPath || typeof pPath !== 'string')
+		{
+			return pObject;
+		}
+
+		let tmpSegments = pPath.split('.');
+		let tmpCurrent = pObject;
+
+		for (let i = 0; i < tmpSegments.length; i++)
+		{
+			if (tmpCurrent === null || tmpCurrent === undefined || typeof tmpCurrent !== 'object')
+			{
+				return null;
+			}
+
+			let tmpSegment = tmpSegments[i];
+			// Check for array index notation: name[index]
+			let tmpMatch = tmpSegment.match(/^([^\[]+)\[(\d+)\]$/);
+			if (tmpMatch)
+			{
+				let tmpKey = tmpMatch[1];
+				let tmpIndex = parseInt(tmpMatch[2], 10);
+				if (!(tmpKey in tmpCurrent) || !Array.isArray(tmpCurrent[tmpKey]))
+				{
+					return null;
+				}
+				tmpCurrent = tmpCurrent[tmpKey][tmpIndex];
+			}
+			else
+			{
+				if (!(tmpSegment in tmpCurrent))
+				{
+					return null;
+				}
+				tmpCurrent = tmpCurrent[tmpSegment];
+			}
+		}
+
+		return tmpCurrent;
+	}
+
+	/**
+	 * Flatten a nested object into a single-level object using a delimiter.
+	 *
+	 * @param {object} pObject - Nested object
+	 * @param {string} pDelimiter - Key delimiter (default '_')
+	 * @param {string} pPrefix - Key prefix for recursion
+	 * @returns {object} Flat object
+	 */
+	_flattenObject(pObject, pDelimiter, pPrefix)
+	{
+		let tmpDelimiter = pDelimiter || '_';
+		let tmpPrefix = pPrefix || '';
+		let tmpResult = {};
+
+		let tmpKeys = Object.keys(pObject);
+		for (let i = 0; i < tmpKeys.length; i++)
+		{
+			let tmpKey = tmpKeys[i];
+			let tmpFullKey = tmpPrefix ? `${tmpPrefix}${tmpDelimiter}${tmpKey}` : tmpKey;
+			let tmpValue = pObject[tmpKey];
+
+			if (tmpValue !== null && typeof tmpValue === 'object' && !Array.isArray(tmpValue))
+			{
+				let tmpNested = this._flattenObject(tmpValue, tmpDelimiter, tmpFullKey);
+				let tmpNestedKeys = Object.keys(tmpNested);
+				for (let j = 0; j < tmpNestedKeys.length; j++)
+				{
+					tmpResult[tmpNestedKeys[j]] = tmpNested[tmpNestedKeys[j]];
+				}
+			}
+			else
+			{
+				tmpResult[tmpFullKey] = tmpValue;
+			}
+		}
+
+		return tmpResult;
+	}
+
+	/**
+	 * Resolve parsed JSON to a records array, applying rootPath navigation.
+	 *
+	 * @param {*} pParsed - Parsed JSON value
+	 * @param {object} pOptions - Parser options
+	 * @returns {Array|null} Array of records or null on failure
+	 */
+	_resolveRecords(pParsed, pOptions)
+	{
+		let tmpData = pParsed;
+
+		if (pOptions && pOptions.rootPath)
+		{
+			tmpData = this._resolveDataPath(pParsed, pOptions.rootPath);
+			if (tmpData === null || tmpData === undefined)
+			{
+				return null;
+			}
+		}
+
+		let tmpRecords;
+		if (Array.isArray(tmpData))
+		{
+			tmpRecords = tmpData;
+		}
+		else if (typeof tmpData === 'object' && tmpData !== null)
+		{
+			// Common envelope keys
+			if (Array.isArray(tmpData.data))
+			{
+				tmpRecords = tmpData.data;
+			}
+			else if (Array.isArray(tmpData.records))
+			{
+				tmpRecords = tmpData.records;
+			}
+			else if (Array.isArray(tmpData.rows))
+			{
+				tmpRecords = tmpData.rows;
+			}
+			else
+			{
+				tmpRecords = [tmpData];
+			}
+		}
+		else
+		{
+			return null;
+		}
+
+		return tmpRecords;
+	}
+
+	/**
+	 * Parse a JSON file into an array of records.
+	 * Reads the entire file into memory.
+	 *
+	 * @param {string} pFilePath - Absolute path to the JSON file
+	 * @param {object} pOptions - Parser options
+	 * @param {function} pChunkCallback - Called with (pError, pRecords) once with all records
+	 * @param {function} pCompletionCallback - Called with (pError, pTotalCount) when done
+	 */
+	parseFile(pFilePath, pOptions, pChunkCallback, pCompletionCallback)
+	{
+		let tmpOptions = Object.assign({}, this.options, pOptions);
+
+		let tmpContent;
+		try
+		{
+			tmpContent = libFS.readFileSync(pFilePath, 'utf8');
+		}
+		catch (pError)
+		{
+			return pCompletionCallback(new Error(`JSON file read error: ${pError.message}`));
+		}
+
+		this.parseContent(tmpContent, tmpOptions,
+			(pError, pRecords) =>
+			{
+				if (pError)
+				{
+					return pCompletionCallback(pError);
+				}
+				pChunkCallback(null, pRecords);
+				return pCompletionCallback(null, pRecords.length);
+			});
+	}
+
+	/**
+	 * Parse JSON content string into a full array of records.
+	 *
+	 * @param {string} pContent - Raw JSON text
+	 * @param {object} pOptions - Parser options
+	 * @param {function} fCallback - Called with (pError, pRecords)
+	 */
+	parseContent(pContent, pOptions, fCallback)
+	{
+		let tmpOptions = Object.assign({}, this.options, pOptions);
+		let tmpFlattenNested = tmpOptions.flattenNested || false;
+		let tmpFlattenDelimiter = tmpOptions.flattenDelimiter || '_';
+
+		let tmpParsed;
+		try
+		{
+			tmpParsed = JSON.parse(pContent);
+		}
+		catch (pError)
+		{
+			return fCallback(new Error(`JSON parse error: ${pError.message}`));
+		}
+
+		let tmpRecords = this._resolveRecords(tmpParsed, tmpOptions);
+		if (tmpRecords === null)
+		{
+			if (tmpOptions.rootPath)
+			{
+				return fCallback(new Error(`rootPath '${tmpOptions.rootPath}' not found in JSON content`));
+			}
+			return fCallback(new Error(`Could not resolve records from JSON content`));
+		}
+
+		if (tmpFlattenNested)
+		{
+			let tmpFlattened = [];
+			for (let i = 0; i < tmpRecords.length; i++)
+			{
+				if (tmpRecords[i] !== null && typeof tmpRecords[i] === 'object')
+				{
+					tmpFlattened.push(this._flattenObject(tmpRecords[i], tmpFlattenDelimiter));
+				}
+				else
+				{
+					tmpFlattened.push(tmpRecords[i]);
+				}
+			}
+			return fCallback(null, tmpFlattened);
+		}
+
+		return fCallback(null, tmpRecords);
+	}
+}
+
+module.exports = MeadowIntegrationFileParserJSON;

package/source/services/parser/Service-FileParser-XLSX.js

@@ -0,0 +1,194 @@
+'use strict';
+
+const libFableServiceProviderBase = require('fable-serviceproviderbase');
+const libFS = require('fs');
+
+const defaultXLSXParserOptions = (
+	{
+		sheetName: '',
+		sheetIndex: 0,
+		headerRow: 1,
+		dataStartRow: 2,
+		maxFileSizeMB: 50
+	});
+
+class MeadowIntegrationFileParserXLSX extends libFableServiceProviderBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		let tmpOptions = Object.assign({}, defaultXLSXParserOptions, pOptions);
+		super(pFable, tmpOptions, pServiceHash);
+
+		this.serviceType = 'MeadowIntegrationFileParserXLSX';
+	}
+
+	/**
+	 * Parse an XLSX file into an array of records.
+	 * Entire file is read into memory. Enforces maxFileSizeMB guard.
+	 *
+	 * @param {string} pFilePath - Absolute path to the XLSX file
+	 * @param {object} pOptions - Parser options
+	 * @param {function} pChunkCallback - Called with (pError, pRecords) once with all records
+	 * @param {function} pCompletionCallback - Called with (pError, pTotalCount) when done
+	 */
+	parseFile(pFilePath, pOptions, pChunkCallback, pCompletionCallback)
+	{
+		let tmpOptions = Object.assign({}, this.options, pOptions);
+		let tmpMaxFileSizeMB = parseFloat(tmpOptions.maxFileSizeMB) || 50;
+		let tmpMaxBytes = tmpMaxFileSizeMB * 1024 * 1024;
+
+		let tmpStat;
+		try
+		{
+			tmpStat = libFS.statSync(pFilePath);
+		}
+		catch (pError)
+		{
+			return pCompletionCallback(new Error(`XLSX file stat error: ${pError.message}`));
+		}
+
+		if (tmpStat.size > tmpMaxBytes)
+		{
+			return pCompletionCallback(new Error(`XLSX file size ${(tmpStat.size / 1024 / 1024).toFixed(1)}MB exceeds maxFileSizeMB limit of ${tmpMaxFileSizeMB}MB`));
+		}
+
+		let tmpBuffer;
+		try
+		{
+			tmpBuffer = libFS.readFileSync(pFilePath);
+		}
+		catch (pError)
+		{
+			return pCompletionCallback(new Error(`XLSX file read error: ${pError.message}`));
+		}
+
+		this._parseBuffer(tmpBuffer, tmpOptions,
+			(pError, pRecords) =>
+			{
+				if (pError)
+				{
+					return pCompletionCallback(pError);
+				}
+				pChunkCallback(null, pRecords);
+				return pCompletionCallback(null, pRecords.length);
+			});
+	}
+
+	/**
+	 * Parse XLSX content (Buffer) into a full array of records.
+	 * Content must be a Buffer containing xlsx file bytes.
+	 *
+	 * @param {Buffer|string} pContent - XLSX file as Buffer (or base64 string)
+	 * @param {object} pOptions - Parser options
+	 * @param {function} fCallback - Called with (pError, pRecords)
+	 */
+	parseContent(pContent, pOptions, fCallback)
+	{
+		let tmpOptions = Object.assign({}, this.options, pOptions);
+		let tmpBuffer = Buffer.isBuffer(pContent) ? pContent : Buffer.from(pContent, 'base64');
+		return this._parseBuffer(tmpBuffer, tmpOptions, fCallback);
+	}
+
+	/**
+	 * Internal: parse an xlsx Buffer into records using the xlsx library.
+	 *
+	 * @param {Buffer} pBuffer - XLSX bytes
+	 * @param {object} pOptions - Merged options
+	 * @param {function} fCallback - Called with (pError, pRecords)
+	 */
+	_parseBuffer(pBuffer, pOptions, fCallback)
+	{
+		let tmpXLSX;
+		try
+		{
+			tmpXLSX = require('xlsx');
+		}
+		catch (pError)
+		{
+			return fCallback(new Error(`xlsx library not available: ${pError.message}`));
+		}
+
+		let tmpWorkbook;
+		try
+		{
+			tmpWorkbook = tmpXLSX.read(pBuffer, { type: 'buffer' });
+		}
+		catch (pError)
+		{
+			return fCallback(new Error(`XLSX parse error: ${pError.message}`));
+		}
+
+		// Determine sheet to use
+		let tmpSheetName;
+		if (pOptions.sheetName && typeof pOptions.sheetName === 'string' && pOptions.sheetName.length > 0)
+		{
+			tmpSheetName = pOptions.sheetName;
+		}
+		else
+		{
+			let tmpSheetIndex = parseInt(pOptions.sheetIndex, 10) || 0;
+			tmpSheetName = tmpWorkbook.SheetNames[tmpSheetIndex];
+		}
+
+		if (!tmpSheetName || !tmpWorkbook.Sheets[tmpSheetName])
+		{
+			return fCallback(new Error(`XLSX sheet '${tmpSheetName}' not found in workbook`));
+		}
+
+		let tmpSheet = tmpWorkbook.Sheets[tmpSheetName];
+		let tmpHeaderRow = parseInt(pOptions.headerRow, 10) || 1;
+		let tmpDataStartRow = parseInt(pOptions.dataStartRow, 10) || 2;
+
+		// When headerRow and dataStartRow are at their defaults (1 and 2),
+		// use xlsx's built-in sheet_to_json which handles this automatically
+		if (tmpHeaderRow === 1 && tmpDataStartRow === 2)
+		{
+			try
+			{
+				let tmpRecords = tmpXLSX.utils.sheet_to_json(tmpSheet);
+				return fCallback(null, tmpRecords);
+			}
+			catch (pError)
+			{
+				return fCallback(new Error(`XLSX sheet_to_json error: ${pError.message}`));
+			}
+		}
+
+		// Custom header/data row offsets: read as raw array first
+		try
+		{
+			let tmpRawRows = tmpXLSX.utils.sheet_to_json(tmpSheet, { header: 1 });
+
+			// Header row is 1-based; convert to 0-based index
+			let tmpHeaderIdx = tmpHeaderRow - 1;
+			let tmpDataIdx = tmpDataStartRow - 1;
+
+			if (tmpHeaderIdx >= tmpRawRows.length)
+			{
+				return fCallback(new Error(`XLSX headerRow ${tmpHeaderRow} is beyond sheet row count`));
+			}
+
+			let tmpHeaders = tmpRawRows[tmpHeaderIdx];
+			let tmpRecords = [];
+
+			for (let i = tmpDataIdx; i < tmpRawRows.length; i++)
+			{
+				let tmpRow = tmpRawRows[i];
+				let tmpRecord = {};
+				for (let j = 0; j < tmpHeaders.length; j++)
+				{
+					tmpRecord[tmpHeaders[j]] = (tmpRow && tmpRow[j] !== undefined) ? tmpRow[j] : '';
+				}
+				tmpRecords.push(tmpRecord);
+			}
+
+			return fCallback(null, tmpRecords);
+		}
+		catch (pError)
+		{
+			return fCallback(new Error(`XLSX custom row parse error: ${pError.message}`));
+		}
+	}
+}
+
+module.exports = MeadowIntegrationFileParserXLSX;

package/source/services/parser/Service-FileParser-XML.js

@@ -0,0 +1,190 @@
+'use strict';
+
+const libFableServiceProviderBase = require('fable-serviceproviderbase');
+const libFS = require('fs');
+
+const defaultXMLParserOptions = (
+	{
+		recordPath: '',
+		attributePrefix: '@_',
+		ignoreAttributes: false
+	});
+
+class MeadowIntegrationFileParserXML extends libFableServiceProviderBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		let tmpOptions = Object.assign({}, defaultXMLParserOptions, pOptions);
+		super(pFable, tmpOptions, pServiceHash);
+
+		this.serviceType = 'MeadowIntegrationFileParserXML';
+	}
+
+	/**
+	 * Walk an XML-parsed object looking for the first array of object records.
+	 * Recurses one level at a time: checks direct children first, then recurses.
+	 *
+	 * @param {object} pObject - Parsed XML object node
+	 * @returns {Array|null} First array of objects found, or null
+	 */
+	_extractXMLRecords(pObject)
+	{
+		if (!pObject || typeof pObject !== 'object')
+		{
+			return null;
+		}
+
+		let tmpKeys = Object.keys(pObject);
+
+		// First pass: look for array-valued keys whose elements are objects
+		for (let i = 0; i < tmpKeys.length; i++)
+		{
+			let tmpValue = pObject[tmpKeys[i]];
+			if (Array.isArray(tmpValue) && tmpValue.length > 0 && typeof tmpValue[0] === 'object')
+			{
+				return tmpValue;
+			}
+		}
+
+		// Second pass: recurse into object-valued keys
+		for (let i = 0; i < tmpKeys.length; i++)
+		{
+			let tmpValue = pObject[tmpKeys[i]];
+			if (typeof tmpValue === 'object' && !Array.isArray(tmpValue))
+			{
+				let tmpResult = this._extractXMLRecords(tmpValue);
+				if (tmpResult)
+				{
+					return tmpResult;
+				}
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Navigate a parsed XML object using a dot-separated recordPath.
+	 *
+	 * @param {object} pParsed - Parsed XML object
+	 * @param {string} pRecordPath - Dot-separated path to the records array
+	 * @returns {Array|null} Records array or null
+	 */
+	_resolveRecordPath(pParsed, pRecordPath)
+	{
+		let tmpParts = pRecordPath.split('.');
+		let tmpCurrent = pParsed;
+
+		for (let i = 0; i < tmpParts.length; i++)
+		{
+			if (!tmpCurrent || typeof tmpCurrent !== 'object' || !(tmpParts[i] in tmpCurrent))
+			{
+				return null;
+			}
+			tmpCurrent = tmpCurrent[tmpParts[i]];
+		}
+
+		return Array.isArray(tmpCurrent) ? tmpCurrent : [tmpCurrent];
+	}
+
+	/**
+	 * Parse an XML file into an array of records.
+	 * Reads the entire file into memory.
+	 *
+	 * @param {string} pFilePath - Absolute path to the XML file
+	 * @param {object} pOptions - Parser options
+	 * @param {function} pChunkCallback - Called with (pError, pRecords) once with all records
+	 * @param {function} pCompletionCallback - Called with (pError, pTotalCount) when done
+	 */
+	parseFile(pFilePath, pOptions, pChunkCallback, pCompletionCallback)
+	{
+		let tmpOptions = Object.assign({}, this.options, pOptions);
+
+		let tmpContent;
+		try
+		{
+			tmpContent = libFS.readFileSync(pFilePath, 'utf8');
+		}
+		catch (pError)
+		{
+			return pCompletionCallback(new Error(`XML file read error: ${pError.message}`));
+		}
+
+		this.parseContent(tmpContent, tmpOptions,
+			(pError, pRecords) =>
+			{
+				if (pError)
+				{
+					return pCompletionCallback(pError);
+				}
+				pChunkCallback(null, pRecords);
+				return pCompletionCallback(null, pRecords.length);
+			});
+	}
+
+	/**
+	 * Parse XML content string into a full array of records.
+	 *
+	 * @param {string} pContent - Raw XML text
+	 * @param {object} pOptions - Parser options
+	 * @param {function} fCallback - Called with (pError, pRecords)
+	 */
+	parseContent(pContent, pOptions, fCallback)
+	{
+		let tmpOptions = Object.assign({}, this.options, pOptions);
+		let tmpRecordPath = tmpOptions.recordPath || '';
+		let tmpAttributePrefix = tmpOptions.attributePrefix || '@_';
+		let tmpIgnoreAttributes = tmpOptions.ignoreAttributes === true;
+
+		let tmpXMLParser;
+		try
+		{
+			let libFastXMLParser = require('fast-xml-parser');
+			tmpXMLParser = new libFastXMLParser.XMLParser(
+				{
+					ignoreAttributes: tmpIgnoreAttributes,
+					attributeNamePrefix: tmpAttributePrefix
+				});
+		}
+		catch (pError)
+		{
+			return fCallback(new Error(`fast-xml-parser library not available: ${pError.message}`));
+		}
+
+		let tmpParsed;
+		try
+		{
+			tmpParsed = tmpXMLParser.parse(pContent);
+		}
+		catch (pError)
+		{
+			return fCallback(new Error(`XML parse error: ${pError.message}`));
+		}
+
+		let tmpRecords;
+
+		if (tmpRecordPath)
+		{
+			tmpRecords = this._resolveRecordPath(tmpParsed, tmpRecordPath);
+			if (!tmpRecords)
+			{
+				return fCallback(new Error(`recordPath '${tmpRecordPath}' not found in XML`));
+			}
+		}
+		else
+		{
+			// Smart extraction: walk tree looking for first array of objects
+			tmpRecords = this._extractXMLRecords(tmpParsed);
+		}
+
+		if (!tmpRecords)
+		{
+			// Wrap the entire parsed result as a single record
+			tmpRecords = [tmpParsed];
+		}
+
+		return fCallback(null, tmpRecords);
+	}
+}
+
+module.exports = MeadowIntegrationFileParserXML;

package/source/services/parser/Service-FileParser.js

@@ -0,0 +1,142 @@
+'use strict';
+
+const libFableServiceProviderBase = require('fable-serviceproviderbase');
+const libPath = require('path');
+
+const defaultFileParserOptions = (
+	{
+		format: ''
+	});
+
+// Extension to format mapping
+const EXTENSION_FORMAT_MAP = (
+	{
+		'.csv': 'csv',
+		'.tsv': 'csv',
+		'.txt': 'csv',
+		'.json': 'json',
+		'.jsonl': 'json',
+		'.xlsx': 'xlsx',
+		'.xlsm': 'xlsx',
+		'.xls': 'xlsx',
+		'.xml': 'xml',
+		'.fw': 'fixedwidth',
+		'.dat': 'fixedwidth'
+	});
+
+class MeadowIntegrationFileParser extends libFableServiceProviderBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		let tmpOptions = Object.assign({}, defaultFileParserOptions, pOptions);
+		super(pFable, tmpOptions, pServiceHash);
+
+		this.serviceType = 'MeadowIntegrationFileParser';
+
+		// Register sub-parser service types
+		this.fable.addAndInstantiateServiceTypeIfNotExists('MeadowIntegrationFileParserCSV', require('./Service-FileParser-CSV.js'));
+		this.fable.addAndInstantiateServiceTypeIfNotExists('MeadowIntegrationFileParserJSON', require('./Service-FileParser-JSON.js'));
+		this.fable.addAndInstantiateServiceTypeIfNotExists('MeadowIntegrationFileParserXLSX', require('./Service-FileParser-XLSX.js'));
+		this.fable.addAndInstantiateServiceTypeIfNotExists('MeadowIntegrationFileParserXML', require('./Service-FileParser-XML.js'));
+		this.fable.addAndInstantiateServiceTypeIfNotExists('MeadowIntegrationFileParserFixedWidth', require('./Service-FileParser-FixedWidth.js'));
+	}
+
+	/**
+	 * Detect the format of a file from its extension, then from a content prefix.
+	 *
+	 * @param {string} pFilePath - File path (used for extension detection)
+	 * @param {string} [pContentPrefix] - First bytes of content for content-based detection
+	 * @returns {string} Format string: 'csv', 'json', 'xlsx', 'xml', 'fixedwidth'
+	 */
+	detectFormat(pFilePath, pContentPrefix)
+	{
+		// Extension-based detection
+		if (pFilePath && typeof pFilePath === 'string')
+		{
+			let tmpExt = libPath.extname(pFilePath).toLowerCase();
+			if (tmpExt && EXTENSION_FORMAT_MAP[tmpExt])
+			{
+				return EXTENSION_FORMAT_MAP[tmpExt];
+			}
+		}
+
+		// Content-based detection
+		if (pContentPrefix && typeof pContentPrefix === 'string')
+		{
+			let tmpTrimmed = pContentPrefix.trim();
+			if (tmpTrimmed.startsWith('[') || tmpTrimmed.startsWith('{'))
+			{
+				return 'json';
+			}
+			if (tmpTrimmed.startsWith('<?xml') || tmpTrimmed.startsWith('<'))
+			{
+				return 'xml';
+			}
+		}
+
+		return 'csv';
+	}
+
+	/**
+	 * Get the appropriate sub-parser service for a given format.
+	 *
+	 * @param {string} pFormat - Format string
+	 * @returns {object} Sub-parser service instance
+	 */
+	_getParser(pFormat)
+	{
+		switch (pFormat)
+		{
+			case 'json':
+				return this.fable.MeadowIntegrationFileParserJSON;
+			case 'xlsx':
+				return this.fable.MeadowIntegrationFileParserXLSX;
+			case 'xml':
+				return this.fable.MeadowIntegrationFileParserXML;
+			case 'fixedwidth':
+				return this.fable.MeadowIntegrationFileParserFixedWidth;
+			case 'csv':
+			default:
+				return this.fable.MeadowIntegrationFileParserCSV;
+		}
+	}
+
+	/**
+	 * Parse a file using streaming, dispatching to the appropriate sub-parser.
+	 * Format is determined from options.format, then from file extension, then content.
+	 *
+	 * @param {string} pFilePath - Absolute path to the file
+	 * @param {object} pOptions - Parser options; pOptions.format overrides detection
+	 * @param {function} pChunkCallback - Called with (pError, pRecords) as records are ready
+	 * @param {function} pCompletionCallback - Called with (pError, pTotalCount) when done
+	 */
+	parseFile(pFilePath, pOptions, pChunkCallback, pCompletionCallback)
+	{
+		let tmpOptions = Object.assign({}, this.options, pOptions);
+		let tmpFormat = tmpOptions.format ? tmpOptions.format.toLowerCase() : this.detectFormat(pFilePath);
+		let tmpParser = this._getParser(tmpFormat);
+
+		this.fable.log.info(`FileParser: parsing [${pFilePath}] as format [${tmpFormat}]`);
+		return tmpParser.parseFile(pFilePath, tmpOptions, pChunkCallback, pCompletionCallback);
+	}
+
+	/**
+	 * Parse content using a full-array (non-streaming) interface.
+	 * Format is determined from options.format, then from content prefix detection.
+	 *
+	 * @param {string|Buffer} pContent - Raw file content
+	 * @param {object} pOptions - Parser options; pOptions.format overrides detection
+	 * @param {function} fCallback - Called with (pError, pRecords)
+	 */
+	parseContent(pContent, pOptions, fCallback)
+	{
+		let tmpOptions = Object.assign({}, this.options, pOptions);
+		let tmpContentPrefix = Buffer.isBuffer(pContent) ? '' : (pContent || '').substring(0, 100);
+		let tmpFormat = tmpOptions.format ? tmpOptions.format.toLowerCase() : this.detectFormat('', tmpContentPrefix);
+		let tmpParser = this._getParser(tmpFormat);
+
+		return tmpParser.parseContent(pContent, tmpOptions, fCallback);
+	}
+}
+
+module.exports = MeadowIntegrationFileParser;