sfmc-dataloader 2.6.0 → 2.7.0

package/lib/config.mjs

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { log } from './log.mjs';
 
 export const FILE_MCDEV_RC = '.mcdevrc.json';
 export const FILE_MCDEV_AUTH = '.mcdev-auth.json';
@@ -39,7 +40,7 @@ export const WARN_MCDATA_SUPERSEDED =
  * @returns {{ mcdevrc: Mcdevrc, mcdevAuth: Record<string, AuthCredential> }}
  */
 export function loadProjectConfig(projectRoot, options = {}) {
-    const err = options.stderr ?? ((msg) => console.error(msg));
+    const err = options.stderr ?? ((msg) => log.error(msg));
     const rcMcdev = path.join(projectRoot, FILE_MCDEV_RC);
     const authMcdev = path.join(projectRoot, FILE_MCDEV_AUTH);
     const rcMcdata = path.join(projectRoot, FILE_MCDATA_RC);
@@ -170,9 +171,37 @@ export function buildSdkAuthObject(authCred, mid) {
  */
 export function buildSdkOptions(logger = null) {
     /** @type {import('sfmc-sdk').SdkOptions} */
-    const options = { requestAttempts: 3 };
+    const options = {
+        requestAttempts: 3,
+        retryOnConnectionError: true,
+        eventHandlers: {
+            onLoop: (_type, accumulator, context) => {
+                if (context) {
+                    log.info(
+                        `Downloading batch ${context.nextPage} of ${context.totalPages} (${context.accumulatedCount} records so far)`,
+                    );
+                } else {
+                    log.info(
+                        `Downloading next batch (currently ${accumulator?.length ?? 0} records)`,
+                    );
+                }
+            },
+            onConnectionError: (ex, remainingAttempts) => {
+                const endpointStr = ex.endpoint ? String(ex.endpoint) : '';
+                const endpointSuffix = endpointStr
+                    ? ` - ${endpointStr.split('rest.marketingcloudapis.com')[1] ?? endpointStr}`
+                    : '';
+                log.warn(
+                    `Connection problem (Code: ${ex.code}). Retrying ${remainingAttempts} time${
+                        remainingAttempts > 1 ? 's' : ''
+                    }${endpointSuffix}`,
+                );
+            },
+        },
+    };
     if (logger) {
         options.eventHandlers = {
+            ...options.eventHandlers,
             logRequest: (req) => {
                 const msg = structuredClone(req);
                 if (msg.headers?.Authorization) {

package/lib/cross-bu-import.mjs

@@ -1,5 +1,7 @@
+import { createReadStream, createWriteStream } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { finished, pipeline } from 'node:stream/promises';
 import readline from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import SDK from 'sfmc-sdk';
@@ -10,15 +12,42 @@ import {
     serializeRows,
     exportDataExtensionToFile,
 } from './export-de.mjs';
-import { formatFromExtension } from './file-resolve.mjs';
-import { importRowsForDe } from './import-de.mjs';
+import { MAX_OBJECTS_PER_BATCH } from './batch.mjs';
+import { formatFromExtension, resolveImportSet } from './file-resolve.mjs';
+import {
+    assertNonEmptyImportRowCount,
+    importRowsForDe,
+    importRowsStreamingForDe,
+    warnIfImportCountUnexpected,
+} from './import-de.mjs';
 import { pollAsyncImportCompletion } from './async-status.mjs';
-import { readRowsFromFile } from './read-rows.mjs';
+import {
+    countDataRowsFromImportPaths,
+    readRowsFromImportPaths,
+    streamRowsFromImportPaths,
+} from './read-rows.mjs';
 import { clearDataExtensionRows } from './clear-de.mjs';
 import { confirmClearBeforeImport } from './confirm-clear.mjs';
 import { dataDirectoryForBu } from './paths.mjs';
 import { buildExportBasename, filesystemSafeTimestamp, parseExportBasename } from './filename.mjs';
 import { getDeRowCount } from './row-count.mjs';
+import { log } from './log.mjs';
+
+/**
+ * Concatenates source files into a single snapshot on disk (streaming; bounded memory).
+ *
+ * @param {string} destPath
+ * @param {string[]} srcPaths
+ * @returns {Promise.<void>}
+ */
+async function concatenateFilesToPath(destPath, srcPaths) {
+    const out = createWriteStream(destPath);
+    for (const src of srcPaths) {
+        await pipeline(createReadStream(src), out, { end: false });
+    }
+    out.end();
+    await finished(out);
+}
 
 /**
  * @typedef {{ credential: string, bu: string }} CredBuTarget
@@ -111,20 +140,24 @@ export async function crossBuImport(params) {
     const filePaths = params.filePaths ?? null;
     const isFileBased = filePaths !== null && filePaths.length > 0;
 
-    // Derive DE keys: from explicit list (API mode) or from filenames (file mode)
+    // Derive DE keys: from explicit list (API mode) or from filenames (file mode, first-seen order)
+    /** @type {string[]} */
     const deKeys = isFileBased
-        ? filePaths.map((fp) => parseExportBasename(path.basename(fp)).customerKey)
+        ? (() => {
+              /** @type {string[]} */
+              const keys = [];
+              const seen = new Set();
+              for (const fp of filePaths) {
+                  const k = parseExportBasename(path.basename(fp)).customerKey;
+                  if (!seen.has(k)) {
+                      seen.add(k);
+                      keys.push(k);
+                  }
+              }
+              return keys;
+          })()
         : (params.deKeys ?? []);
 
-    // Build a lookup map from deKey → filePath for file mode
-    /** @type {Map<string, string>} */
-    const fileByDeKey = new Map();
-    if (isFileBased) {
-        for (const fp of filePaths) {
-            fileByDeKey.set(parseExportBasename(path.basename(fp)).customerKey, fp);
-        }
-    }
-
     // Validate all target BU configurations upfront
     for (const { credential, bu } of targets) {
         resolveCredentialAndMid(mcdevrc, mcdevAuth, credential, bu);
@@ -156,7 +189,7 @@ export async function crossBuImport(params) {
             const { mid, authCred } = resolveCredentialAndMid(mcdevrc, mcdevAuth, credential, bu);
             const tgtSdk = new SDK(buildSdkAuthObject(authCred, mid), buildSdkOptions(logger));
             for (const deKey of deKeys) {
-                const { path: outPath, rowCount } = await exportDataExtensionToFile(tgtSdk, {
+                const { paths: outPaths, rowCount } = await exportDataExtensionToFile(tgtSdk, {
                     projectRoot,
                     credentialName: credential,
                     buName: bu,
@@ -164,7 +197,8 @@ export async function crossBuImport(params) {
                     format,
                     useGit: false,
                 });
-                console.error(`Backup export: "${path.resolve(outPath)}" (${rowCount} rows)`);
+                const label = outPaths.map((p) => `"${path.resolve(p)}"`).join(', ');
+                log.info(`Backup export: ${label} (${rowCount} rows)`);
             }
         }
     }
@@ -176,35 +210,51 @@ export async function crossBuImport(params) {
 
     let hasError = false;
 
-    // Load rows once per DE then fan out to every target
+    // Load rows once per DE then fan out to every target (CSV/TSV file mode streams to avoid OOM)
     for (const deKey of deKeys) {
-        let rows;
+        /** @type {object[]|null} */
+        let rows = null;
+        /** @type {string[]|null} */
+        let streamingImportPaths = null;
+        /** @type {'csv'|'tsv'|'json'|null} */
+        let streamingDetectedFormat = null;
+
         if (isFileBased) {
-            const filePath = fileByDeKey.get(deKey);
-            const detectedFormat = formatFromExtension(filePath);
+            const groupPaths = filePaths.filter(
+                (fp) => parseExportBasename(path.basename(fp)).customerKey === deKey,
+            );
+            const { paths: importPaths } = await resolveImportSet(groupPaths);
+            if (importPaths.length === 0) {
+                throw new Error(`No resolvable import files for DE "${deKey}".`);
+            }
+            const detectedFormat = formatFromExtension(importPaths[0]);
             if (!detectedFormat) {
                 throw new Error(
-                    `Cannot determine format for file: ${filePath}. Use .csv, .tsv, or .json extension.`,
+                    `Cannot determine format for file: ${importPaths[0]}. Use .csv, .tsv, or .json extension.`,
                 );
             }
-            rows = await readRowsFromFile(filePath, detectedFormat);
-            if (rows.length === 0) {
-                throw new Error(
-                    `Import file contains no data rows: "${filePath}". ` +
-                        `The file may be empty, contain only a BOM, or contain only a header row. ` +
-                        `Export the DE first to obtain a template with column names, then add rows.`,
-                );
+            if (detectedFormat === 'csv' || detectedFormat === 'tsv') {
+                streamingImportPaths = importPaths;
+                streamingDetectedFormat = detectedFormat;
+            } else {
+                rows = await readRowsFromImportPaths(importPaths, detectedFormat);
+                if (rows.length === 0) {
+                    throw new Error(
+                        `Import files contain no data rows for DE "${deKey}". ` +
+                            `The files may be empty, contain only a BOM, or contain only a header row.`,
+                    );
+                }
             }
         } else {
             rows = await fetchAllRowObjects(srcSdk, deKey);
         }
 
         let snapshotColumns = [];
-        if (rows.length === 0 && format !== 'json') {
+        if (rows && rows.length === 0 && format !== 'json') {
             try {
                 snapshotColumns = await fetchDataExtensionFieldNames(srcSdk.soap, deKey);
             } catch (ex) {
-                console.error(
+                log.warn(
                     `Warning: could not retrieve field names for empty DE "${deKey}" (snapshot): ${ex.message}`,
                 );
             }
@@ -215,19 +265,21 @@ export async function crossBuImport(params) {
             const tgtSdk = new SDK(buildSdkAuthObject(authCred, mid), buildSdkOptions(logger));
 
             const countBefore = await getDeRowCount(tgtSdk, deKey);
-            console.error(
+            log.info(
                 `Row count before import: ${countBefore ?? '(unavailable)'} (${credential}/${bu} DE "${deKey}")`,
             );
 
             // Clear target before import (already confirmed above); skip if DE is empty
+            let clearedTargetDe = false;
             if (clearBeforeImport) {
                 if (countBefore === 0) {
-                    console.error(
+                    log.info(
                         `Skipping clear-data for ${credential}/${bu} DE "${deKey}" — DE is already empty.`,
                     );
                 } else {
                     await clearDataExtensionRows(tgtSdk.soap, deKey);
-                    console.warn(`Cleared data: ${credential}/${bu} DE "${deKey}"`);
+                    clearedTargetDe = true;
+                    log.warn(`Cleared data: ${credential}/${bu} DE "${deKey}"`);
                 }
             }
 
@@ -237,19 +289,46 @@ export async function crossBuImport(params) {
             const ts = filesystemSafeTimestamp();
             const basename = buildExportBasename(deKey, ts, format, false);
             const snapshotPath = path.join(dir, basename);
-            await fs.writeFile(
-                snapshotPath,
-                serializeRows(rows, format, false, snapshotColumns),
-                'utf8',
-            );
-            console.error(`Download stored: "${path.resolve(snapshotPath)}" (${rows.length} rows)`);
 
-            const { count: imported, requestIds } = await importRowsForDe(tgtSdk, {
-                deKey,
-                rows,
-                mode,
-            });
-            console.error(`Imported: ${credential}/${bu} DE ${deKey} (${imported} rows)`);
+            /** @type {{ count: number, requestIds: (string|null)[] }} */
+            let importResult;
+            if (streamingImportPaths && streamingDetectedFormat) {
+                await concatenateFilesToPath(snapshotPath, streamingImportPaths);
+                log.info(`Download stored: "${path.resolve(snapshotPath)}"`);
+                const rowCount = await countDataRowsFromImportPaths(
+                    streamingImportPaths,
+                    streamingDetectedFormat,
+                );
+                assertNonEmptyImportRowCount(rowCount, streamingImportPaths.join(', '));
+                const totalMemoryBatches = Math.max(1, Math.ceil(rowCount / MAX_OBJECTS_PER_BATCH));
+                const rowSource = streamRowsFromImportPaths(
+                    streamingImportPaths,
+                    streamingDetectedFormat,
+                );
+                importResult = await importRowsStreamingForDe(tgtSdk, {
+                    deKey,
+                    rowSource,
+                    mode,
+                    totalMemoryBatches,
+                });
+            } else {
+                await fs.writeFile(
+                    snapshotPath,
+                    serializeRows(/** @type {object[]} */ (rows), format, false, snapshotColumns),
+                    'utf8',
+                );
+                log.info(
+                    `Download stored: "${path.resolve(snapshotPath)}" (${/** @type {object[]} */ (rows).length} rows)`,
+                );
+                importResult = await importRowsForDe(tgtSdk, {
+                    deKey,
+                    rows: /** @type {object[]} */ (rows),
+                    mode,
+                });
+            }
+
+            const { count: imported, requestIds } = importResult;
+            log.info(`Imported: ${credential}/${bu} DE ${deKey} (${imported} rows)`);
 
             const importHadError = await pollAsyncImportCompletion(tgtSdk, requestIds);
             if (importHadError) {
@@ -257,24 +336,17 @@ export async function crossBuImport(params) {
             }
 
             const countAfter = await getDeRowCount(tgtSdk, deKey);
-            console.error(
+            log.info(
                 `Row count after import: ${countAfter ?? '(unavailable)'} (${credential}/${bu} DE "${deKey}")`,
             );
-            if (countAfter === null) {
-                console.error(
-                    `Could not verify import result for ${credential}/${bu} DE "${deKey}".`,
-                );
-            } else {
-                const expected =
-                    mode === 'insert' || countBefore === 0
-                        ? (countBefore ?? 0) + imported
-                        : imported;
-                if (countAfter < expected) {
-                    console.error(
-                        `Import result for ${credential}/${bu} DE "${deKey}" looks unexpected: expected at least ${expected} rows, got ${countAfter}.`,
-                    );
-                }
-            }
+            warnIfImportCountUnexpected({
+                countBefore,
+                cleared: clearedTargetDe,
+                countAfter,
+                imported,
+                mode,
+                label: `${credential}/${bu} DE "${deKey}"`,
+            });
         }
     }
 

package/lib/export-de.mjs

@@ -1,9 +1,13 @@
+import { createWriteStream } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { stringify } from 'csv-stringify/sync';
+import { finished } from 'node:stream/promises';
+import { stringify } from 'csv-stringify';
+import { stringify as stringifySync } from 'csv-stringify/sync';
 import { rowsetGetPath } from './import-routes.mjs';
 import { buildExportBasename, filesystemSafeTimestamp } from './filename.mjs';
 import { dataDirectoryForBu } from './paths.mjs';
+import { log } from './log.mjs';
 
 /**
  * @param {{rest: {getBulk: (path: string, pageSize?: number) => Promise.<any>}}} sdk
@@ -76,11 +80,11 @@ export function serializeRows(rows, format, jsonPretty, columns = []) {
     if (rows.length === 0 && columns.length > 0) {
         options.columns = columns;
     }
-    return stringify(rows, options);
+    return stringifySync(rows, options);
 }
 
 /**
- * @param {{ rest: { getBulk: (path: string, pageSize?: number) => Promise.<any> }, soap: { retrieve: Function } }} sdk
+ * @param {{ rest: object, soap: { retrieve: Function } }} sdk
  * @param {object} params
  * @param {string} params.projectRoot
  * @param {string} params.credentialName
@@ -89,7 +93,8 @@ export function serializeRows(rows, format, jsonPretty, columns = []) {
  * @param {'csv'|'tsv'|'json'} params.format
  * @param {boolean} [params.jsonPretty]
  * @param {boolean} [params.useGit]
- * @returns {Promise.<{path: string, rowCount: number}>}
+ * @param {number} [params.maxRowsPerFile] - split output into part files with at most this many data rows each
+ * @returns {Promise.<{paths: string[], rowCount: number}>}
  */
 export async function exportDataExtensionToFile(sdk, params) {
     const {
@@ -100,24 +105,199 @@ export async function exportDataExtensionToFile(sdk, params) {
         format,
         jsonPretty = false,
         useGit = false,
+        maxRowsPerFile,
     } = params;
-    const rows = await fetchAllRowObjects(sdk, deKey);
-    let columns = [];
-    if (rows.length === 0 && format !== 'json') {
+    const dir = dataDirectoryForBu(projectRoot, credentialName, buName);
+    await fs.mkdir(dir, { recursive: true });
+    const ts = filesystemSafeTimestamp();
+    const basePath = rowsetGetPath(deKey);
+    const cap =
+        typeof maxRowsPerFile === 'number' && maxRowsPerFile > 0 ? maxRowsPerFile : undefined;
+
+    /** @type {string[]} */
+    const paths = [];
+    let totalRows = 0;
+
+    if (format === 'json') {
+        let partIndex = 0;
+        /** @type {import('node:fs').WriteStream|null} */
+        let writeStream = null;
+        let rowsInPart = 0;
+        let firstInArray = true;
+
+        const closeJsonFile = async () => {
+            if (writeStream) {
+                writeStream.write('\n]\n');
+                writeStream.end();
+                await finished(writeStream);
+                writeStream = null;
+            }
+            firstInArray = true;
+            rowsInPart = 0;
+        };
+
+        const openJsonPart = async () => {
+            await closeJsonFile();
+            partIndex++;
+            const basename = cap
+                ? buildExportBasename(deKey, ts, format, useGit, partIndex)
+                : buildExportBasename(deKey, ts, format, useGit);
+            const outPath = path.join(dir, basename);
+            paths.push(outPath);
+            writeStream = createWriteStream(outPath, { encoding: 'utf8' });
+            writeStream.write('[\n');
+            firstInArray = true;
+        };
+
+        try {
+            for await (const step of sdk.rest.getBulkPages(basePath, 2500)) {
+                if (step.totalPages === undefined) {
+                    log.info(`Downloading next batch (currently ${totalRows} records)`);
+                } else {
+                    log.info(
+                        `Downloading batch ${step.page} of ${step.totalPages} (${totalRows} records so far)`,
+                    );
+                }
+                for (const item of step.pageItems) {
+                    const row = { ...item.keys, ...item.values };
+                    if (writeStream === null) {
+                        await openJsonPart();
+                    }
+                    if (cap && rowsInPart >= cap) {
+                        await openJsonPart();
+                    }
+                    if (firstInArray) {
+                        firstInArray = false;
+                    } else {
+                        writeStream.write(',\n');
+                    }
+                    const chunk = jsonPretty ? JSON.stringify(row, null, 2) : JSON.stringify(row);
+                    writeStream.write(chunk);
+                    rowsInPart++;
+                    totalRows++;
+                }
+            }
+        } catch (ex) {
+            if (ex.message !== 'Could not find an array to iterate over') {
+                throw ex;
+            }
+        }
+
+        if (writeStream) {
+            await closeJsonFile();
+        }
+
+        if (paths.length === 0) {
+            let columns = [];
+            try {
+                columns = await fetchDataExtensionFieldNames(sdk.soap, deKey);
+            } catch (ex) {
+                log.warn(
+                    `Warning: could not retrieve field names for empty DE "${deKey}": ${ex.message}`,
+                );
+            }
+            const basename = buildExportBasename(deKey, ts, format, useGit);
+            const outPath = path.join(dir, basename);
+            const body = serializeRows([], format, jsonPretty, columns);
+            await fs.writeFile(outPath, body, 'utf8');
+            paths.push(outPath);
+        }
+
+        return { paths, rowCount: totalRows };
+    }
+
+    /** @type {string[]|null} */
+    let columnNames = null;
+    let partIndex = 0;
+    /** @type {import('stream').Transform|null} */
+    let stringifier = null;
+    /** @type {import('node:fs').WriteStream|null} */
+    let writeStream = null;
+    let rowsInPart = 0;
+    let isFirstCsvFile = true;
+
+    const closeCsvPart = async () => {
+        if (stringifier && writeStream) {
+            stringifier.end();
+            await finished(writeStream);
+        }
+        stringifier = null;
+        writeStream = null;
+        rowsInPart = 0;
+    };
+
+    const openCsvPart = async () => {
+        await closeCsvPart();
+        partIndex++;
+        const basename = cap
+            ? buildExportBasename(deKey, ts, format, useGit, partIndex)
+            : buildExportBasename(deKey, ts, format, useGit);
+        const outPath = path.join(dir, basename);
+        paths.push(outPath);
+        writeStream = createWriteStream(outPath, { encoding: 'utf8' });
+        const includeHeader = isFirstCsvFile;
+        isFirstCsvFile = false;
+        stringifier = stringify({
+            header: includeHeader,
+            bom: includeHeader,
+            quoted: format === 'csv',
+            delimiter: format === 'tsv' ? '\t' : ',',
+            ...(columnNames && columnNames.length > 0 ? { columns: columnNames } : {}),
+        });
+        stringifier.pipe(writeStream);
+    };
+
+    try {
+        for await (const step of sdk.rest.getBulkPages(basePath, 2500)) {
+            if (step.totalPages === undefined) {
+                log.info(`Downloading next batch (currently ${totalRows} records)`);
+            } else {
+                log.info(
+                    `Downloading batch ${step.page} of ${step.totalPages} (${totalRows} records so far)`,
+                );
+            }
+            for (const item of step.pageItems) {
+                const row = { ...item.keys, ...item.values };
+                if (columnNames === null && Object.keys(row).length > 0) {
+                    columnNames = Object.keys(row);
+                }
+                if (writeStream === null) {
+                    await openCsvPart();
+                }
+                if (cap && rowsInPart >= cap) {
+                    await openCsvPart();
+                }
+                stringifier.write(row);
+                rowsInPart++;
+                totalRows++;
+            }
+        }
+    } catch (ex) {
+        if (ex.message !== 'Could not find an array to iterate over') {
+            throw ex;
+        }
+    }
+
+    if (writeStream) {
+        await closeCsvPart();
+    }
+
+    if (paths.length === 0) {
+        let columns = [];
         try {
             columns = await fetchDataExtensionFieldNames(sdk.soap, deKey);
         } catch (ex) {
-            console.error(
+            log.warn(
                 `Warning: could not retrieve field names for empty DE "${deKey}": ${ex.message}`,
             );
         }
+        columnNames = columns.length > 0 ? columns : null;
+        await openCsvPart();
+        stringifier.end();
+        await finished(writeStream);
+        stringifier = null;
+        writeStream = null;
     }
-    const dir = dataDirectoryForBu(projectRoot, credentialName, buName);
-    await fs.mkdir(dir, { recursive: true });
-    const ts = filesystemSafeTimestamp();
-    const basename = buildExportBasename(deKey, ts, format, useGit);
-    const outPath = path.join(dir, basename);
-    const body = serializeRows(rows, format, jsonPretty, columns);
-    await fs.writeFile(outPath, body, 'utf8');
-    return { path: outPath, rowCount: rows.length };
+
+    return { paths, rowCount: totalRows };
 }

package/lib/file-resolve.mjs

@@ -2,6 +2,77 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { parseExportBasename } from './filename.mjs';
 
+/**
+ * @typedef {{ path: string, partNumber: number|null, mtime: number }} CandidateEntry
+ */
+
+/**
+ * Group multi-part exports (`part1`, `part2`, … sharing the same key and timestamp) and pick
+ * the newest export run. Returns ordered paths (part 1, 2, …) or a single file path.
+ *
+ * @param {string[]} candidatePaths - from {@link findImportCandidates}
+ * @returns {Promise.<{ paths: string[], isMultiPart: boolean }>}
+ */
+export async function resolveImportSet(candidatePaths) {
+    /** @type {Map<string, CandidateEntry[]>} */
+    const groups = new Map();
+    for (const filePath of candidatePaths) {
+        const name = path.basename(filePath);
+        let parsed;
+        try {
+            parsed = parseExportBasename(name);
+        } catch {
+            continue;
+        }
+        const { customerKey, timestampPart, ext, partNumber } = parsed;
+        const groupKey = `${customerKey}\0${timestampPart}\0${ext}`;
+        let st;
+        try {
+            st = await fs.stat(filePath);
+        } catch {
+            continue;
+        }
+        const entry = {
+            path: filePath,
+            partNumber: partNumber === undefined ? null : partNumber,
+            mtime: st.mtimeMs,
+        };
+        const list = groups.get(groupKey);
+        if (list) {
+            list.push(entry);
+        } else {
+            groups.set(groupKey, [entry]);
+        }
+    }
+    if (groups.size === 0) {
+        return { paths: [], isMultiPart: false };
+    }
+    let bestEntries = /** @type {CandidateEntry[]|null} */ (null);
+    let bestMaxMtime = -1;
+    for (const entries of groups.values()) {
+        const maxM = Math.max(...entries.map((e) => e.mtime));
+        if (maxM > bestMaxMtime) {
+            bestMaxMtime = maxM;
+            bestEntries = entries;
+        }
+    }
+    if (!bestEntries || bestEntries.length === 0) {
+        return { paths: [], isMultiPart: false };
+    }
+    const hasParts = bestEntries.some((e) => e.partNumber !== null);
+    if (hasParts) {
+        const sorted = [...bestEntries].toSorted(
+            (a, b) => (a.partNumber ?? 0) - (b.partNumber ?? 0),
+        );
+        return {
+            paths: sorted.map((e) => e.path),
+            isMultiPart: sorted.length > 1,
+        };
+    }
+    const one = bestEntries.reduce((a, b) => (a.mtime >= b.mtime ? a : b));
+    return { paths: [one.path], isMultiPart: false };
+}
+
 /** Supported import/export file extensions */
 const SUPPORTED_EXTENSIONS = ['csv', 'tsv', 'json'];