pict-section-dataimport 1.0.0

package/source/providers/Pict-Provider-DataImport.js

@@ -0,0 +1,149 @@
+const libPictProvider = require('pict-provider');
+
+const libPictViewWizard = require('../views/PictView-DataImport-Wizard.js');
+const libComprehensionBuilder = require('../services/DataImport-ComprehensionBuilder.js');
+const libDataImportCSS = require('../Pict-Section-DataImport-CSS.js');
+
+const libParserDelimited = require('../seams/DataImport-Parser-Delimited.js');
+const libParserFixedWidth = require('../seams/DataImport-Parser-FixedWidth.js');
+const libParserXlsx = require('../seams/DataImport-Parser-Xlsx.js');
+const libSchemaProvider = require('../seams/DataImport-SchemaProvider.js');
+const libPushTarget = require('../seams/DataImport-PushTarget.js');
+const libStateStore = require('../seams/DataImport-StateStore.js');
+
+/** @type {Record<string, any>} */
+const _DEFAULT_CONFIGURATION =
+{
+	ProviderIdentifier: 'Pict-Section-DataImport',
+
+	AutoInitialize: true,
+	AutoInitializeOrdinal: 0,
+};
+
+/**
+ * The pict-section-dataimport provider — the embeddable API surface. Registers the wizard CSS, then
+ * createImportWizard(hash, config) drops the whole upload -> validate -> map -> generate -> push flow
+ * into the host's DOM. The four seams (Parser / Schema / Push / State) are normalized here from
+ * strings, instances, or functions into live objects the wizard view consumes.
+ */
+class PictProviderDataImport extends libPictProvider
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		let tmpOptions = Object.assign({}, _DEFAULT_CONFIGURATION, pOptions);
+		super(pFable, tmpOptions, pServiceHash);
+
+		if (this.pict && this.pict.CSSMap && typeof this.pict.CSSMap.addCSS === 'function')
+		{
+			this.pict.CSSMap.addCSS('Pict-Section-DataImport-CSS', libDataImportCSS, 500);
+		}
+		this._meadowAdapter = null;
+	}
+
+	/** Lazily require the Meadow seam adapters (only when a Meadow schema source / EntityProvider push is used). */
+	_meadow()
+	{
+		if (!this._meadowAdapter) { this._meadowAdapter = require('./Pict-Provider-DataImport-Meadow.js'); }
+		return this._meadowAdapter;
+	}
+
+	/**
+	 * Create (or reconfigure + reuse) an embedded import wizard.
+	 * @param {string} pWizardHash @param {Record<string, any>} pConfig
+	 * @return {any} The wizard view instance.
+	 */
+	createImportWizard(pWizardHash, pConfig)
+	{
+		const tmpConfig = Object.assign(
+			{
+				DestinationAddress: `#${pWizardHash}`,
+				RenderMode: 'wizard',
+				URLPrefix: '/1.0/',
+				GUIDPrefix: 'INTG-DEF',
+				EntityGUIDPrefix: '',
+				AllowGUIDTruncation: false,
+				AllowedFileTypes: [ 'csv', 'tsv', 'xlsx', 'fixedwidth' ],
+				SchemaSource: 'meadow',
+				PushMode: 'entityprovider',
+				StateStore: 'memory',
+			},
+			pConfig || {},
+			{ WizardHash: pWizardHash });
+
+		// Resolve the seams onto the config — the wizard view reads these directly.
+		tmpConfig.ResolvedParsers = this._resolveParsers(tmpConfig);
+		tmpConfig.ResolvedSchemaProvider = this._resolveSchemaProvider(tmpConfig);
+		tmpConfig.ResolvedPushTarget = this._resolvePushTarget(tmpConfig);
+		tmpConfig.ResolvedStateStore = this._resolveStateStore(tmpConfig);
+		tmpConfig.ComprehensionBuilder = new libComprehensionBuilder(this.pict);
+
+		if (this.pict.views[pWizardHash])
+		{
+			Object.assign(this.pict.views[pWizardHash].options, tmpConfig);
+			return this.pict.views[pWizardHash];
+		}
+		return this.pict.addView(pWizardHash, tmpConfig, libPictViewWizard);
+	}
+
+	/** Build the parser registry { kind: instance }, merging any host-supplied custom parsers. */
+	_resolveParsers(pConfig)
+	{
+		const tmpParsers =
+		{
+			csv: new libParserDelimited(this.pict, { Kind: 'csv' }),
+			tsv: new libParserDelimited(this.pict, { Kind: 'tsv' }),
+			fixedwidth: new libParserFixedWidth(this.pict, {}),
+			xlsx: new libParserXlsx(this.pict, {}),
+		};
+		if (pConfig.Parsers && typeof pConfig.Parsers === 'object')
+		{
+			Object.keys(pConfig.Parsers).forEach((pKind) => { tmpParsers[pKind] = pConfig.Parsers[pKind]; });
+		}
+		return tmpParsers;
+	}
+
+	/** Normalize SchemaSource: 'meadow' | 'config' | instance | function(ctx)->Promise<schema>. */
+	_resolveSchemaProvider(pConfig)
+	{
+		const tmpSource = pConfig.SchemaSource;
+		if (tmpSource && typeof tmpSource.getSchema === 'function') { return tmpSource; }
+		if (typeof tmpSource === 'function') { return { getSchema: (pContext) => Promise.resolve(tmpSource(pContext)) }; }
+		if (tmpSource === 'meadow')
+		{
+			return new (this._meadow().DataImportSchemaProviderMeadow)(this.pict, { MeadowEntities: pConfig.MeadowEntities || [], URLPrefix: pConfig.URLPrefix });
+		}
+		// default: a config-supplied schema descriptor
+		return new libSchemaProvider.DataImportSchemaProviderConfig(this.pict, { Schema: pConfig.Schema || { Entities: [] } });
+	}
+
+	/** Normalize PushMode: 'entityprovider' | 'comprehension' | instance | function(comp,ctx)->Promise<result>. */
+	_resolvePushTarget(pConfig)
+	{
+		const tmpMode = pConfig.PushMode;
+		if (tmpMode && typeof tmpMode.push === 'function') { return tmpMode; }
+		if (typeof tmpMode === 'function') { return { push: (pComprehension, pContext) => Promise.resolve(tmpMode(pComprehension, pContext)) }; }
+		if (tmpMode === 'entityprovider')
+		{
+			return new (this._meadow().DataImportPushTargetEntityProvider)(this.pict, {});
+		}
+		// default: POST the whole comprehension to an endpoint
+		return new libPushTarget.DataImportPushTargetComprehension(this.pict, { URL: pConfig.ComprehensionPushURL });
+	}
+
+	/** Normalize StateStore: 'memory' | 'localStorage' | instance, or a PersistenceHook on the config. */
+	_resolveStateStore(pConfig)
+	{
+		if (pConfig.PersistenceHook && typeof pConfig.PersistenceHook.save === 'function')
+		{
+			return new libStateStore.DataImportStateStoreHook(this.pict, { Hook: pConfig.PersistenceHook });
+		}
+		const tmpStore = pConfig.StateStore;
+		if (tmpStore && typeof tmpStore.save === 'function') { return tmpStore; }
+		if (tmpStore === 'localStorage') { return new libStateStore.DataImportStateStoreLocal(this.pict, { KeyPrefix: pConfig.StateStoreKeyPrefix }); }
+		return new libStateStore.DataImportStateStoreMemory(this.pict, {});
+	}
+}
+
+module.exports = PictProviderDataImport;
+
+module.exports.default_configuration = _DEFAULT_CONFIGURATION;

package/source/seams/DataImport-Parser-Delimited.js

@@ -0,0 +1,128 @@
+// DataImport-Parser-Delimited — CSV + TSV parser (hand-rolled, RFC-4180-aware, no dependency).
+//
+// Handles quoted fields, embedded delimiters + newlines inside quotes, and doubled "" escapes. One
+// class serves both CSV and TSV; the delimiter comes from ParseConfig.Delimited.Delimiter (defaulting
+// from the instance Kind). Registered as a 'csv' instance and a 'tsv' instance by the provider.
+
+const libParserProvider = require('./DataImport-ParserProvider.js');
+
+class DataImportParserDelimited extends libParserProvider
+{
+	get Kind()
+	{
+		return this.options.Kind || 'csv';
+	}
+
+	/** @param {Record<string, any>} pParseConfig @return {{Delimiter:string, HasHeader:boolean, SampleRowLimit:number}} */
+	_settings(pParseConfig)
+	{
+		const tmpDelimitedConfig = (pParseConfig && pParseConfig.Delimited) || {};
+		const tmpDefaultDelimiter = (this.Kind === 'tsv') ? '\t' : ',';
+		return {
+			Delimiter: tmpDelimitedConfig.Delimiter || tmpDefaultDelimiter,
+			HasHeader: (tmpDelimitedConfig.HasHeader !== false),
+			SampleRowLimit: (pParseConfig && pParseConfig.SampleRowLimit) || 25,
+		};
+	}
+
+	/**
+	 * Parse delimited text into an array of cell-arrays (one per record), quote-aware + multiline-safe.
+	 * @param {string} pText @param {string} pDelimiter @return {Array<Array<string>>}
+	 */
+	parseDelimited(pText, pDelimiter)
+	{
+		const tmpRows = [];
+		let tmpRow = [];
+		let tmpField = '';
+		let tmpInQuotes = false;
+		const tmpText = (pText || '').replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+		let tmpRowHasContent = false;
+
+		for (let i = 0; i < tmpText.length; i++)
+		{
+			const tmpChar = tmpText[i];
+			if (tmpInQuotes)
+			{
+				if (tmpChar === '"')
+				{
+					if (tmpText[i + 1] === '"') { tmpField += '"'; i++; }   // escaped doubled quote
+					else { tmpInQuotes = false; }
+				}
+				else { tmpField += tmpChar; }
+			}
+			else if (tmpChar === '"')
+			{
+				tmpInQuotes = true;
+				tmpRowHasContent = true;
+			}
+			else if (tmpChar === pDelimiter)
+			{
+				tmpRow.push(tmpField);
+				tmpField = '';
+				tmpRowHasContent = true;
+			}
+			else if (tmpChar === '\n')
+			{
+				tmpRow.push(tmpField);
+				// Skip wholly-empty lines (a trailing newline shouldn't yield a blank record).
+				if (tmpRowHasContent || tmpRow.length > 1 || tmpRow[0] !== '') { tmpRows.push(tmpRow); }
+				tmpRow = [];
+				tmpField = '';
+				tmpRowHasContent = false;
+			}
+			else
+			{
+				tmpField += tmpChar;
+				tmpRowHasContent = true;
+			}
+		}
+		// Flush the final field/row if the file didn't end on a newline.
+		if (tmpField !== '' || tmpRow.length > 0)
+		{
+			tmpRow.push(tmpField);
+			if (tmpRowHasContent || tmpRow.length > 1 || tmpRow[0] !== '') { tmpRows.push(tmpRow); }
+		}
+		return tmpRows;
+	}
+
+	/** @param {number} pCount @return {Array<string>} Generated column names (Column1, Column2, …). */
+	_generatedHeader(pCount)
+	{
+		const tmpHeader = [];
+		for (let i = 0; i < pCount; i++) { tmpHeader.push(`Column${i + 1}`); }
+		return tmpHeader;
+	}
+
+	detect(pFileHandle, pParseConfig)
+	{
+		const tmpSettings = this._settings(pParseConfig);
+		return this._readText(pFileHandle).then((pText) =>
+		{
+			const tmpRows = this.parseDelimited(pText, tmpSettings.Delimiter);
+			if (tmpRows.length === 0) { return { Columns: [], SampleRows: [], RowCountEstimate: 0 }; }
+			const tmpHeader = tmpSettings.HasHeader ? tmpRows[0].map((pCell) => String(pCell).trim()) : this._generatedHeader(tmpRows[0].length);
+			const tmpDataRows = tmpSettings.HasHeader ? tmpRows.slice(1) : tmpRows;
+			return this._buildDetection(tmpHeader, tmpDataRows, tmpSettings.SampleRowLimit);
+		});
+	}
+
+	parse(pFileHandle, pParseConfig)
+	{
+		const tmpSettings = this._settings(pParseConfig);
+		return this._readText(pFileHandle).then((pText) =>
+		{
+			const tmpRows = this.parseDelimited(pText, tmpSettings.Delimiter);
+			if (tmpRows.length === 0) { return []; }
+			const tmpHeader = tmpSettings.HasHeader ? tmpRows[0].map((pCell) => String(pCell).trim()) : this._generatedHeader(tmpRows[0].length);
+			const tmpDataRows = tmpSettings.HasHeader ? tmpRows.slice(1) : tmpRows;
+			return tmpDataRows.map((pRow) =>
+			{
+				const tmpObject = {};
+				for (let c = 0; c < tmpHeader.length; c++) { tmpObject[tmpHeader[c]] = (pRow[c] !== undefined) ? pRow[c] : ''; }
+				return tmpObject;
+			});
+		});
+	}
+}
+
+module.exports = DataImportParserDelimited;

package/source/seams/DataImport-Parser-FixedWidth.js

@@ -0,0 +1,87 @@
+// DataImport-Parser-FixedWidth — fixed-width / column-position file parser (hand-rolled, no dependency).
+//
+// Fixed-width files have no reliable auto-detect, so detect() with NO column spec returns the raw
+// lines (so the validate UI can show a monospaced ruler for the user to define boundaries). Once
+// ParseConfig.FixedWidth.Columns is set (each { Name, Start, End } — End exclusive, 0-based), detect()
+// and parse() slice + trim each line into fields.
+
+const libParserProvider = require('./DataImport-ParserProvider.js');
+
+class DataImportParserFixedWidth extends libParserProvider
+{
+	get Kind()
+	{
+		return this.options.Kind || 'fixedwidth';
+	}
+
+	/** @param {Record<string, any>} pParseConfig @return {{Columns:Array<any>, HasHeader:boolean, SampleRowLimit:number}} */
+	_settings(pParseConfig)
+	{
+		const tmpFixedConfig = (pParseConfig && pParseConfig.FixedWidth) || {};
+		return {
+			Columns: Array.isArray(tmpFixedConfig.Columns) ? tmpFixedConfig.Columns : [],
+			HasHeader: !!tmpFixedConfig.HasHeader,
+			SampleRowLimit: (pParseConfig && pParseConfig.SampleRowLimit) || 25,
+		};
+	}
+
+	/** @param {string} pText @return {Array<string>} Non-empty lines. */
+	_lines(pText)
+	{
+		return (pText || '').replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n').filter((pLine) => pLine.length > 0);
+	}
+
+	/** Slice one line into a cell array per the column spec. @param {string} pLine @param {Array<any>} pColumns @return {Array<string>} */
+	_sliceLine(pLine, pColumns)
+	{
+		return pColumns.map((pColumn) =>
+		{
+			const tmpStart = (typeof pColumn.Start === 'number') ? pColumn.Start : 0;
+			const tmpEnd = (typeof pColumn.End === 'number') ? pColumn.End : pLine.length;
+			return pLine.substring(tmpStart, tmpEnd).trim();
+		});
+	}
+
+	detect(pFileHandle, pParseConfig)
+	{
+		const tmpSettings = this._settings(pParseConfig);
+		return this._readText(pFileHandle).then((pText) =>
+		{
+			const tmpLines = this._lines(pText);
+			// No column spec yet — hand the raw lines back so the UI can render a boundary ruler.
+			if (tmpSettings.Columns.length === 0)
+			{
+				return { Columns: [], SampleRows: [], RowCountEstimate: tmpLines.length, RawLines: tmpLines.slice(0, tmpSettings.SampleRowLimit) };
+			}
+			const tmpHeader = tmpSettings.Columns.map((pColumn) => pColumn.Name);
+			const tmpDataLines = tmpSettings.HasHeader ? tmpLines.slice(1) : tmpLines;
+			const tmpDataRows = tmpDataLines.map((pLine) => this._sliceLine(pLine, tmpSettings.Columns));
+			const tmpDetection = this._buildDetection(tmpHeader, tmpDataRows, tmpSettings.SampleRowLimit);
+			tmpDetection.RawLines = tmpLines.slice(0, tmpSettings.SampleRowLimit);
+			return tmpDetection;
+		});
+	}
+
+	parse(pFileHandle, pParseConfig)
+	{
+		const tmpSettings = this._settings(pParseConfig);
+		if (tmpSettings.Columns.length === 0)
+		{
+			return Promise.reject(new Error('pict-section-dataimport: fixed-width parse requires a column spec (ParseConfig.FixedWidth.Columns).'));
+		}
+		return this._readText(pFileHandle).then((pText) =>
+		{
+			const tmpHeader = tmpSettings.Columns.map((pColumn) => pColumn.Name);
+			const tmpDataLines = tmpSettings.HasHeader ? this._lines(pText).slice(1) : this._lines(pText);
+			return tmpDataLines.map((pLine) =>
+			{
+				const tmpCells = this._sliceLine(pLine, tmpSettings.Columns);
+				const tmpObject = {};
+				for (let c = 0; c < tmpHeader.length; c++) { tmpObject[tmpHeader[c]] = tmpCells[c]; }
+				return tmpObject;
+			});
+		});
+	}
+}
+
+module.exports = DataImportParserFixedWidth;

package/source/seams/DataImport-Parser-Xlsx.js

@@ -0,0 +1,81 @@
+// DataImport-Parser-Xlsx — Excel parser, wrapping SheetJS (xlsx). LAZY-required so the ~1MB library
+// is only pulled into the bundle/process when xlsx import is actually used; xlsx is an OPTIONAL peer
+// dependency (the default AllowedFileTypes can omit 'xlsx' entirely). Reads the first worksheet.
+
+const libParserProvider = require('./DataImport-ParserProvider.js');
+
+class DataImportParserXlsx extends libParserProvider
+{
+	get Kind()
+	{
+		return this.options.Kind || 'xlsx';
+	}
+
+	/** @return {any} The xlsx library, or throws a friendly error if it isn't installed. */
+	_xlsx()
+	{
+		if (this._xlsxLib) { return this._xlsxLib; }
+		try { this._xlsxLib = require('xlsx'); }
+		catch (pError) { throw new Error('pict-section-dataimport: xlsx import needs the optional "xlsx" (SheetJS) dependency installed.'); }
+		return this._xlsxLib;
+	}
+
+	/** @param {Record<string, any>} pParseConfig @return {Promise<Array<Array<any>>>} The sheet as array-of-arrays. */
+	_readSheetMatrix(pFileHandle, pParseConfig)
+	{
+		const tmpXLSX = this._xlsx();
+		return this._readArrayBuffer(pFileHandle).then((pBuffer) =>
+		{
+			const tmpWorkbook = tmpXLSX.read(pBuffer, { type: 'array' });
+			const tmpSheetName = (pParseConfig && pParseConfig.Xlsx && pParseConfig.Xlsx.SheetName) || tmpWorkbook.SheetNames[0];
+			const tmpSheet = tmpWorkbook.Sheets[tmpSheetName];
+			if (!tmpSheet) { return []; }
+			// header:1 → array-of-arrays; blank cells become '' so columns line up.
+			return tmpXLSX.utils.sheet_to_json(tmpSheet, { header: 1, defval: '', blankrows: false });
+		});
+	}
+
+	_settings(pParseConfig)
+	{
+		const tmpXlsxConfig = (pParseConfig && pParseConfig.Xlsx) || {};
+		return {
+			HasHeader: (tmpXlsxConfig.HasHeader !== false),
+			SampleRowLimit: (pParseConfig && pParseConfig.SampleRowLimit) || 25,
+		};
+	}
+
+	detect(pFileHandle, pParseConfig)
+	{
+		const tmpSettings = this._settings(pParseConfig);
+		return this._readSheetMatrix(pFileHandle, pParseConfig).then((pMatrix) =>
+		{
+			if (!pMatrix || pMatrix.length === 0) { return { Columns: [], SampleRows: [], RowCountEstimate: 0 }; }
+			const tmpHeader = tmpSettings.HasHeader
+				? pMatrix[0].map((pCell) => String(pCell).trim())
+				: pMatrix[0].map((pCell, pIndex) => `Column${pIndex + 1}`);
+			const tmpDataRows = tmpSettings.HasHeader ? pMatrix.slice(1) : pMatrix;
+			return this._buildDetection(tmpHeader, tmpDataRows, tmpSettings.SampleRowLimit);
+		});
+	}
+
+	parse(pFileHandle, pParseConfig)
+	{
+		const tmpSettings = this._settings(pParseConfig);
+		return this._readSheetMatrix(pFileHandle, pParseConfig).then((pMatrix) =>
+		{
+			if (!pMatrix || pMatrix.length === 0) { return []; }
+			const tmpHeader = tmpSettings.HasHeader
+				? pMatrix[0].map((pCell) => String(pCell).trim())
+				: pMatrix[0].map((pCell, pIndex) => `Column${pIndex + 1}`);
+			const tmpDataRows = tmpSettings.HasHeader ? pMatrix.slice(1) : pMatrix;
+			return tmpDataRows.map((pRow) =>
+			{
+				const tmpObject = {};
+				for (let c = 0; c < tmpHeader.length; c++) { tmpObject[tmpHeader[c]] = (pRow[c] !== undefined) ? pRow[c] : ''; }
+				return tmpObject;
+			});
+		});
+	}
+}
+
+module.exports = DataImportParserXlsx;

package/source/seams/DataImport-ParserProvider.js

@@ -0,0 +1,123 @@
+// DataImport-ParserProvider — the abstract file-parser seam.
+//
+// A parser turns an uploaded file handle (the pict-section-upload shape: { Name, Size, Type,
+// getText(cb), getArrayBuffer(cb) }) into (a) a DETECTION result for the validate/map UI — detected
+// columns + sample rows + an estimated row count — and (b) a full row stream for comprehension
+// generation. Hosts can register custom parsers (e.g. EBCDIC, a bespoke binary) by extending this and
+// registering the instance under a file kind. The module stays format-agnostic behind this seam.
+
+class DataImportParserProvider
+{
+	/**
+	 * @param {any} pPict @param {Record<string, any>} pOptions
+	 */
+	constructor(pPict, pOptions)
+	{
+		this.pict = pPict;
+		this.options = pOptions || {};
+	}
+
+	/** @return {string} The file kind this parser handles ('csv' | 'tsv' | 'fixedwidth' | 'xlsx' | custom). */
+	get Kind()
+	{
+		return this.options.Kind || 'base';
+	}
+
+	/**
+	 * Inspect a file: return the detected columns, a sample of rows, and an estimated total row count.
+	 * @param {Record<string, any>} pFileHandle @param {Record<string, any>} pParseConfig
+	 * @return {Promise<{Columns:Array<any>, SampleRows:Array<any>, RowCountEstimate:number, RawLines?:Array<string>}>}
+	 */
+	detect(pFileHandle, pParseConfig)
+	{
+		return Promise.reject(new Error(`pict-section-dataimport: parser [${this.Kind}] does not implement detect().`));
+	}
+
+	/**
+	 * Parse the whole file into an array of row objects (keyed by column name).
+	 * @param {Record<string, any>} pFileHandle @param {Record<string, any>} pParseConfig
+	 * @return {Promise<Array<Record<string, any>>>}
+	 */
+	parse(pFileHandle, pParseConfig)
+	{
+		return Promise.reject(new Error(`pict-section-dataimport: parser [${this.Kind}] does not implement parse().`));
+	}
+
+	/** Read a file handle's text content as a Promise. @param {Record<string, any>} pFileHandle @return {Promise<string>} */
+	_readText(pFileHandle)
+	{
+		return new Promise((resolve, reject) =>
+		{
+			if (!pFileHandle || typeof pFileHandle.getText !== 'function')
+			{
+				return reject(new Error('pict-section-dataimport: file handle has no getText().'));
+			}
+			pFileHandle.getText((pError, pText) => (pError ? reject(pError) : resolve(pText || '')));
+		});
+	}
+
+	/** Read a file handle's bytes as a Promise. @param {Record<string, any>} pFileHandle @return {Promise<ArrayBuffer>} */
+	_readArrayBuffer(pFileHandle)
+	{
+		return new Promise((resolve, reject) =>
+		{
+			if (!pFileHandle || typeof pFileHandle.getArrayBuffer !== 'function')
+			{
+				return reject(new Error('pict-section-dataimport: file handle has no getArrayBuffer().'));
+			}
+			pFileHandle.getArrayBuffer((pError, pBuffer) => (pError ? reject(pError) : resolve(pBuffer)));
+		});
+	}
+
+	/**
+	 * Cheap value-type inference for the detected-columns UI (presentational only — never coerces data).
+	 * @param {Array<any>} pValues @return {string} 'integer' | 'number' | 'boolean' | 'date' | 'string'
+	 */
+	_inferType(pValues)
+	{
+		const tmpSample = (pValues || []).filter((pValue) => pValue !== undefined && pValue !== null && String(pValue).trim() !== '');
+		if (tmpSample.length === 0) { return 'string'; }
+		let tmpAllInteger = true;
+		let tmpAllNumber = true;
+		let tmpAllBoolean = true;
+		let tmpAllDate = true;
+		for (let i = 0; i < tmpSample.length; i++)
+		{
+			const tmpValue = String(tmpSample[i]).trim();
+			if (!/^-?\d+$/.test(tmpValue)) { tmpAllInteger = false; }
+			if (!/^-?\d*\.?\d+(?:[eE][+-]?\d+)?$/.test(tmpValue)) { tmpAllNumber = false; }
+			if (!/^(true|false|yes|no|0|1)$/i.test(tmpValue)) { tmpAllBoolean = false; }
+			if (isNaN(Date.parse(tmpValue))) { tmpAllDate = false; }
+		}
+		if (tmpAllInteger) { return 'integer'; }
+		if (tmpAllNumber) { return 'number'; }
+		if (tmpAllBoolean) { return 'boolean'; }
+		if (tmpAllDate) { return 'date'; }
+		return 'string';
+	}
+
+	/**
+	 * Build the {Columns, SampleRows, RowCountEstimate} detection result from a header + data rows.
+	 * @param {Array<string>} pHeader @param {Array<Array<any>>} pDataRows @param {number} pSampleLimit
+	 * @return {{Columns:Array<any>, SampleRows:Array<any>, RowCountEstimate:number}}
+	 */
+	_buildDetection(pHeader, pDataRows, pSampleLimit)
+	{
+		const tmpLimit = pSampleLimit || 25;
+		const tmpSampleRows = [];
+		for (let i = 0; i < Math.min(pDataRows.length, tmpLimit); i++)
+		{
+			const tmpRowObject = {};
+			for (let c = 0; c < pHeader.length; c++) { tmpRowObject[pHeader[c]] = pDataRows[i][c]; }
+			tmpSampleRows.push(tmpRowObject);
+		}
+		const tmpColumns = pHeader.map((pName, pIndex) =>
+		{
+			const tmpColumnValues = pDataRows.slice(0, tmpLimit).map((pRow) => pRow[pIndex]);
+			return { Index: pIndex, SourceName: pName, InferredType: this._inferType(tmpColumnValues), SampleValues: tmpColumnValues.slice(0, 3) };
+		});
+		return { Columns: tmpColumns, SampleRows: tmpSampleRows, RowCountEstimate: pDataRows.length };
+	}
+}
+
+module.exports = DataImportParserProvider;

package/source/seams/DataImport-PushTarget.js

@@ -0,0 +1,82 @@
+// DataImport-PushTarget — the abstract push seam, plus the built-in Comprehension-POST adapter.
+//
+// push() takes the generated comprehension + a context (GUID prefixes, server URL, the entity Order,
+// an onProgress hook) and lands it somewhere, returning { Success, EntitiesPushed, Message }. The
+// POST adapter sends the whole comprehension to a /Comprehension/Push endpoint (the server owns the
+// meadow-integration engine) — so this path needs no client-side EntityProvider. The direct
+// per-record EntityProvider push adapter lives in Pict-Provider-DataImport-Meadow.js.
+
+class DataImportPushTarget
+{
+	constructor(pPict, pOptions)
+	{
+		this.pict = pPict;
+		this.options = pOptions || {};
+	}
+
+	/**
+	 * @param {Record<string, any>} pComprehension @param {Record<string, any>} pContext
+	 * @return {Promise<{Success:boolean, EntitiesPushed:Array<string>, Message:string}>}
+	 */
+	push(pComprehension, pContext)
+	{
+		return Promise.reject(new Error('pict-section-dataimport: PushTarget does not implement push().'));
+	}
+}
+
+/**
+ * Built-in adapter: POST the whole comprehension to a Comprehension/Push endpoint. The request body
+ * matches meadow-integration's Endpoint-ComprehensionPush contract:
+ *   { Comprehension, GUIDPrefix, EntityGUIDPrefix, ServerURL } -> { Success, EntitiesPushed, Message }
+ * A host can inject a PostFunction (url, body) => Promise<responseJson> for tests / custom transport;
+ * otherwise it uses fetch, falling back to the pict EntityProvider rest client.
+ */
+class DataImportPushTargetComprehension extends DataImportPushTarget
+{
+	push(pComprehension, pContext)
+	{
+		const tmpContext = pContext || {};
+		const tmpURL = this.options.URL || tmpContext.ComprehensionPushURL || '/1.0/Comprehension/Push';
+		const tmpBody = {
+			Comprehension: pComprehension,
+			GUIDPrefix: tmpContext.GUIDPrefix,
+			EntityGUIDPrefix: tmpContext.EntityGUIDPrefix,
+			ServerURL: tmpContext.ServerURL,
+		};
+		const fPost = (typeof this.options.PostFunction === 'function') ? this.options.PostFunction : this._defaultPost.bind(this);
+		return Promise.resolve(fPost(tmpURL, tmpBody)).then((pResponse) =>
+		{
+			const tmpResponse = pResponse || {};
+			return {
+				Success: (tmpResponse.Success !== undefined) ? tmpResponse.Success : true,
+				EntitiesPushed: Array.isArray(tmpResponse.EntitiesPushed) ? tmpResponse.EntitiesPushed : Object.keys(pComprehension || {}),
+				Message: tmpResponse.Message || 'Comprehension posted.',
+			};
+		});
+	}
+
+	/** Default JSON POST: fetch when available, else the pict EntityProvider rest client. */
+	_defaultPost(pURL, pBody)
+	{
+		if (typeof fetch === 'function')
+		{
+			return fetch(pURL, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(pBody) })
+				.then((pResult) => pResult.json());
+		}
+		if (this.pict && this.pict.EntityProvider && this.pict.EntityProvider.restClient && typeof this.pict.EntityProvider.restClient.postJSON === 'function')
+		{
+			return new Promise((resolve, reject) =>
+			{
+				this.pict.EntityProvider.restClient.postJSON({ url: pURL, body: pBody }, (pError, pResponse, pResponseBody) =>
+				{
+					if (pError) { return reject(pError); }
+					resolve(pResponseBody || (pResponse && pResponse.body) || {});
+				});
+			});
+		}
+		return Promise.reject(new Error('pict-section-dataimport: no fetch / rest client available to POST the comprehension.'));
+	}
+}
+
+module.exports = DataImportPushTarget;
+module.exports.DataImportPushTargetComprehension = DataImportPushTargetComprehension;