Перейти к содержимому
Поиск
Разработка

Papa Parse: CSV в браузере и Node.js — мастерская и 9 задач

Разбираем CSV по-настоящему: девять задач, редактируемые данные, предпросмотр импорта, ошибки, Worker, отмена, экспорт и Node.js CLI.

Александр Некрасов
Papa Parse: CSV в браузере и Node.js — мастерская и 9 задач — обложка

Papa Parse: превратить CSV в понятный импорт

Менеджер выгрузил каталог, партнёр прислал остатки, служба поддержки получила список заявок. Внешне файл выглядит простой таблицей: первая строка содержит названия колонок, дальше расположены значения. Но уже в первом комментарии может встретиться запятая, в названии — кавычка, а в идентификаторе — важные ведущие нули. Неправильный разбор превращает привычный обмен данными в поиск незаметно испорченных записей.

Papa Parse читает CSV и превращает его в строки или объекты JavaScript. Обратная операция создаёт CSV из данных приложения. Библиотеку можно использовать в браузерном кабинете, в Node.js CLI и в серверном конвейере импорта. Пользователь получает понятный предпросмотр, разработчик — управляемое представление данных, которое можно проверить перед записью.

Ниже находится работающая мастерская: девять задач, восемнадцать исходных вариантов, редактируемый CSV, настоящий Worker, ошибки, прогресс, отмена и скачивание результатов. Вы можете сначала сломать учебный файл, увидеть причину отказа, исправить его и повторить обработку. Полный проект позволяет перенести этот подход в свою административную панель.

Где это пригодится: каталог, CRM, миграция и отчёт

В интернет-магазине оператору нужно понять, какие товары будут обновлены и почему некоторые позиции не проходят проверку. В CRM важно сохранить внешний идентификатор клиента, показать повторные записи и не перепутать пустое значение с нулём. При переносе данных между сервисами полезно заранее увидеть названия колонок, выбранный разделитель и список отклонённых строк.

CSV также удобен для небольшого инструмента аналитика: загрузить локальную выгрузку, выбрать нужные поля и получить нормализованный отчёт. При этом разбор CSV сам по себе не выполняет объединения таблиц, сложные расчёты и работу с Parquet. Для таких задач можно продолжить знакомство в мастерской DuckDB.

Если приложение написано на PHP, полезен соседний материал про League CSV. Выбор зависит от места обработки: Papa Parse особенно удобен, когда предпросмотр должен работать прямо в браузере, а те же правила затем повторяются в Node.js. Серверная проверка всё равно остаётся обязательной перед изменением рабочих данных.

Почему split по запятой быстро перестаёт работать

Посмотрите на первый пример: название товара содержит запятую, а комментарий занимает две строки. Эти символы относятся к содержимому поля. Если сначала разделить текст по переводам строк, а затем каждую строку по запятой, одна запись станет несколькими, а колонки сдвинутся. Кавычки, которыми CSV отделяет такое значение, требуют собственного правила разбора.

Во второй записи встречается название с внутренними кавычками. При корректном чтении пользователь должен увидеть обычный текст, а не дополнительную пару символов экранирования. Ошибка здесь может не остановить программу: таблица получится непустой, но данные будут неверными. Поэтому тест с двумя простыми строками ничего не доказывает для реального импорта.

В мастерской можно менять такие поля и сразу смотреть результат. Таблица выводит значения как текст, поэтому HTML внутри комментария не превращается в разметку страницы. Номер в первом столбце показывает порядковый номер записи данных. Он не обязан совпадать с физической строкой CSV, потому что одна запись может содержать несколько переносов.

Фрагмент tests/lab.test.mjs

test('quoted comma/newline and escaped quotes remain single field',()=>{const r=go('quotes');assert.equal(r.counts.parsed,2);assert.equal(r.preview[0].note,'Первая строка\nВторая строка');assert.equal(r.preview[1].name,'Реле "Комфорт"');});

Версии, установка и локальные зависимости

При подготовке проекта 16 ноября 2026 года проверена версия Papa Parse 5.7.1. В архиве закреплены Bootstrap 5.3.9 и esbuild 0.28.2; для запуска выбран Node.js 24 LTS не ниже 24.15.0. package-lock.json сохраняет точный набор зависимостей, поэтому повторение начинается с npm ci, а не с произвольного обновления пакетов.

Готовая папка public включает браузерный код и CSS. Во время работы мастерская не обращается к внешнему CDN за библиотекой. Просмотр исходников делает отдельный запрос за статическим JSON этого же проекта; содержимое вашего CSV туда не попадает. Авторские файлы и тексты лицензий находятся в архиве.

Официальные точки входа — документация Papa Parse, FAQ и репозиторий проекта. Примеры ниже описывают конкретную закреплённую версию и авторскую мастерскую. После обновления зависимости повторите тесты на своих пограничных данных, особенно там, где приложение полагается на типы, заголовки и формат ошибок.

Фрагмент package.json

{
  "name": "aen-papa-parse-workshop",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT",
  "engines": {"node": ">=24.15.0"},
  "scripts": {"build":"node tools/build.mjs","test":"node --test tests/*.test.mjs","capture":"node tools/capture.mjs","serve":"node tools/serve.mjs","cli":"node tools/cli.mjs"},
  "dependencies": {"papaparse":"5.7.1","bootstrap":"5.3.9"},
  "devDependencies": {"esbuild":"0.28.2"}
}

Мини-мастерская: разберите, исправьте и скачайте

Выберите задачу и исходный вариант. У каждой задачи есть короткое объяснение пользы и действие, которое стоит выполнить. Измените CSV или настройку и нажмите «Разобрать CSV». Старый результат при редактировании очищается: его нельзя случайно принять за ответ для нового содержимого. Ошибка и отмена также не оставляют прежний успешный импорт активным.

В результате видны количество разобранных, принятых и отклонённых записей, ошибки CSV, фактический разделитель и таблица предпросмотра. Под таблицей раскрываются подробности и JSON. Отчёт можно скачать даже с замечаниями; CSV с проверенными строками доступен только после полного успешного разбора. Скачивание не означает запись в базу или отправку данных в другой сервис.

Все примеры выполняются по-настоящему в отдельном Worker браузера. Записанные результаты тестов не подставляются вместо обработки. Для работы с файлом можно выбрать кодировку; файл читается локально. Лимиты мастерской подписаны рядом с управлением: один MiB текста, десять тысяч записей, первые сто строк в таблице. Для большого экрана удобнее открыть мастерскую отдельно.

Windows: готовая страница и запуск разработки

Распакуйте проект в отдельную папку и откройте PowerShell в этом каталоге. Проверьте Node.js, затем установите зависимости из lock-файла. Сборка готовит app.js, worker.js, локальный CSS и просмотр исходников. Тесты выполняют настоящие вызовы Papa Parse, Worker Thread и CLI. Команда capture сохраняет учебные результаты для технической проверки проекта.

Для знакомства с готовой страницей достаточно npm run serve: сервер использует стандартные модули Node, а public уже лежит в архиве. Откройте адрес из консоли и остановите сервер сочетанием Ctrl+C, когда закончите. Если привычнее PHP, ту же папку можно раздать встроенным сервером PHP без изменения браузерного кода.

Порт привязан к 127.0.0.1 и предназначен для локального просмотра. При конфликте задайте другой PORT. Не завершайте неизвестный процесс только потому, что он занял удобный номер. Открытие index.html двойным щелчком не заменяет HTTP-сервер: у Worker и fetch есть ограничения для файловых адресов.

Фрагмент README.md

node --version
npm ci --ignore-scripts --no-audit --no-fund
npm run build
npm test
npm run capture
npm run serve
# Откройте http://127.0.0.1:8553/
# При занятом порте:
$env:PORT = '8653'
npm run serve

Linux: повторяем проект без переноса node_modules

На Linux используется тот же lock-файл, но зависимости устанавливаются заново. Некоторые инструменты сборки имеют платформенные части, поэтому папка node_modules с Windows не является переносимым окружением. Готовые HTML, CSS и JavaScript в public, наоборот, можно раздавать обычным веб-сервером независимо от системы сборки.

В архиве предусмотрен отдельный Linux-скрипт для контейнера. Он копирует исходники из read-only каталога в собственную временную папку, устанавливает зависимости, собирает проект, запускает тесты и сохраняет результаты в /out. Такой повтор помогает отличать ошибку приложения от особенностей локальной установки Node. Скрипт не выполняет глобальную очистку Docker и не касается других проектов.

Для реальной системы следует заранее выбрать поддерживаемую версию Node, владельца файлов и способ доставки релиза. Команды мастерской показывают воспроизводимый запуск, но не создают автоматически пользователя сервера, сертификат и безопасный доступ к базе. Эти части deployment нужно проверять отдельно на выбранном хостинге.

Фрагмент README.md

npm ci --ignore-scripts --no-audit --no-fund
npm run build
npm test
npm run capture
PORT=8653 npm run serve

Задача 1. Кавычки, запятые и многострочное поле

В первом варианте один товар имеет название «Датчик, комнатный», а его комментарий содержит перевод строки. После разбора обе особенности остаются внутри соответствующих полей. У другого товара внутренние кавычки превращаются в обычные символы названия. Вы видите результат в таблице и можете сопоставить его с исходным CSV.

Попробуйте добавить ещё одну запятую в комментарий, затем убрать закрывающую кавычку. Успешный разбор и повреждённый документ должны отличаться не только внешним видом таблицы. Мастерская показывает ошибку и закрывает экспорт проверенных строк, пока проблема не исправлена. Так оператор не получает кнопку «готово» рядом с неоднозначными данными.

В рабочем импорте храните исходный файл до завершения проверки и связывайте отчёт с конкретным запуском. Не исправляйте кавычки автоматически заменой всех двойных символов: подобная операция может изменить законное содержимое. Сначала определите формат выгрузки и получите корректный пример от системы-источника.

Задача 2. Автоопределение и явный разделитель

Один и тот же каталог в мастерской представлен через точку с запятой и через табуляцию. Автоматическое определение удобно для первого знакомства с неизвестным файлом. После разбора фактически выбранный символ показывается рядом с результатом. Это помогает заметить ситуацию, когда несколько ожидаемых колонок превратились в одно длинное поле.

Теперь выберите запятую принудительно для варианта с точкой с запятой и включите контракт. Парсер может получить вполне допустимую структуру из одной колонки, но приложение не найдёт id, name и quantity. Отказ в этом случае связан с контрактом данных. Он объясняет, почему успешный синтаксический разбор недостаточен для применения импорта.

Для регулярной интеграции разделитель лучше согласовать заранее и передавать явно. Автоопределение полезно в пользовательском кабинете с предпросмотром, но не должно незаметно менять смысл стабильного формата. Если поставщик изменил параметры выгрузки, это повод зафиксировать новую версию контракта, а не молча принять другой набор полей.

Фрагмент src/core.mjs

export function configFor(options = {}) {
  const delimiter = options.delimiter === 'tab' ? '\t' : (options.delimiter || '');
  if (!['', ',', ';', '\t', '|'].includes(delimiter)) throw new Error('Недопустимый разделитель.');
  return {
    header: options.header !== false,
    delimiter,
    skipEmptyLines: options.greedy === false ? false : 'greedy',
    dynamicTyping: options.typing === 'all' ? true : options.typing === 'quantity' ? field => field === 'quantity' : false,
    transformHeader: options.trimHeaders ? header => header.trim() : undefined
  };
}

Задача 3. Заголовки, пробелы и дубликаты

Имена колонок становятся ключами объектов. В варианте с пробелами поле называется не id, а « id ». Для человека разница почти незаметна, для проверки это другое имя. В мастерской очистка пробелов включается отдельно. Такой переключатель позволяет увидеть исходную структуру и результат согласованной нормализации.

Повторяющиеся заголовки требуют отдельного решения. Библиотека сообщает о переименованных дубликатах, а наш адаптер блокирует готовность файла. Иначе одна колонка name могла бы восприниматься как имя клиента, другая — как имя контактного лица, хотя исходная схема никак их не различает. Автоматическое добавление суффикса не объясняет прикладное значение.

Пустые записи тоже неодинаковы: бывает пустая строка, а бывает набор разделителей и пробелов. Переключатель пропуска позволяет наблюдать их влияние на количество записей. В рабочем контракте зафиксируйте, что считается пустой записью, и не смешивайте это с отсутствием значения в обязательной колонке.

Фрагмент tests/lab.test.mjs

test('duplicate headers are observed and block export',()=>{const r=go('headers',1);assert.ok(Object.keys(r.meta.renamedHeaders).length);assert.equal(r.importReady,false);assert.ok(r.issues.some(x=>x.includes('повторяются')));});

Задача 4. Ведущие нули и выборочное преобразование

Внешний идентификатор 00125 обозначает запись в системе поставщика. Это не количество и не сумма. Превратив его в число 125, приложение теряет часть представления, которое может участвовать в сопоставлении. В мастерской три режима позволяют сравнить строки, преобразование только quantity и автоматическое преобразование всех полей.

Режим quantity полезен для конкретной схемы каталога: остаток становится числом, идентификатор остаётся строкой. Широкое преобразование всех полей специально подписано как демонстрация риска. Во втором варианте есть большое целое и логические значения; результат позволяет увидеть поведение именно закреплённой версии библиотеки, не опираясь на предположение по внешнему виду текста.

Для сумм, дат, артикулов и телефонов определяйте правила отдельно. Запятая в дробной части не должна автоматически превращаться в разделитель колонок. Дата без часового пояса не становится однозначным моментом времени. Преобразование типов — часть схемы интеграции, и его лучше проверять на положительных и отрицательных примерах.

Фрагмент tests/lab.test.mjs

test('selective typing preserves ID and types quantity',()=>{const r=go('types');assert.equal(r.preview[0].id,'00125');assert.equal(r.preview[0].quantity,12);});
test('all-field dynamic typing demonstrates leading-zero loss',()=>{const r=go('types',0,{typing:'all'});assert.equal(r.preview[0].id,125);assert.ok(r.warnings.length);});

Задача 5. Контракт импорта и понятные причины отказа

Учебный контракт требует id из пяти цифр, непустое name и целое quantity от нуля до ста тысяч. В плохом варианте есть пустое название, отрицательный остаток, повтор идентификатора и неверный формат ключа. Мастерская показывает не только общее число ошибок, но и причину для каждой отклонённой записи.

Принятые значения нормализуются в новый объект с явно выбранными полями. Произвольные дополнительные колонки не переносятся автоматически в прикладную модель. Это полезная граница: разборщик знает формат CSV, а контракт решает, какие данные разрешено передать следующему этапу. В более сложном приложении правила можно вынести в отдельную схему, например по подходу из мастерской Zod.

Исправьте строки так, чтобы весь файл прошёл проверку. Кнопка экспорта станет доступна после повторного запуска. Здесь выбран строгий режим: одна проблема блокирует выдачу файла как полностью готового. Для частичного импорта потребуется другое явно согласованное поведение, включая отчёт о пропущенных записях.

Фрагмент src/core.mjs

if (contract && options.header !== false) {
      if (typeof row.id !== 'string' || !/^\d{5}$/.test(row.id)) reasons.push('id должен быть строкой из пяти цифр.');
      if (typeof row.name !== 'string' || !row.name.trim()) reasons.push('name не должен быть пустым.');
      const quantity = typeof row.quantity === 'number' ? row.quantity : /^\d+$/.test(row.quantity ?? '') ? Number(row.quantity) : NaN;
      if (!Number.isSafeInteger(quantity) || quantity < 0 || quantity > 100000) reasons.push('quantity: целое число от 0 до 100000.');
      if (typeof row.id === 'string' && seen.has(row.id)) reasons.push('id повторяется внутри файла.');
      if (typeof row.id === 'string') seen.add(row.id);
      if (!reasons.length) row = {id:row.id,name:row.name.trim(),quantity};
    }

Повтор ID: локальная проверка и проверка базы

В мастерской Set обнаруживает повтор идентификатора внутри текущего файла. Это помогает поймать две строки, которые претендуют на одну позицию. Однако файл может содержать ID, уже существующий в базе, и тогда потребуется правило обновления: заменить запись, объединить отдельные поля или отклонить операцию.

Нужно также учитывать область данных. Один внешний ID может быть допустим у разных поставщиков или организаций. Значит, ключ сопоставления состоит не только из текста id, но и из доверенного контекста импорта. Этот контекст должен приходить из серверной сессии и разрешений, а не из произвольной колонки пользовательского CSV.

Для регулярной загрузки полезен идентификатор самого запуска. Если оператор повторно нажал кнопку после обрыва связи, сервер должен понимать, применяется ли тот же пакет ещё раз. Проверка CSV, уникальность строк и идемпотентность операции решают разные задачи. Небольшой учебный контракт делает границы заметными, но не заменяет проектирование изменений в базе.

Задача 6. Лишнее поле, недостающее поле и кавычки

В шестой задаче одна запись содержит лишнее значение, а другая не содержит quantity. При включённых заголовках такие расхождения попадают в ошибки CSV. Наш адаптер связывает их с порядковыми номерами записей, помечает соответствующие строки как отклонённые и сохраняет сведения в JSON-отчёте.

Другой вариант содержит незакрытую кавычку. Здесь нельзя уверенно считать найденные данные завершённым импортом: границы поля повреждены. Поэтому ошибка кавычек дополнительно отражается в общих замечаниях. Таблица остаётся инструментом диагностики, а не подтверждением, что все показанные значения можно записать.

В интерфейсе поддержки лучше показывать и понятное объяснение, и технический код ошибки. Оператору нужен следующий шаг: проверить количество полей, закрыть кавычку, выбрать правильный разделитель. Разработчику полезны исходный документ и стабильный код для теста. Не заменяйте все случаи одной фразой «не удалось загрузить» — она не помогает исправить файл.

Фрагмент tests/lab.test.mjs

test('mismatched field counts are linked to record positions',()=>{const r=go('errors');assert.equal(r.counts.errors,2);assert.deepEqual(r.rejected.map(x=>x.record),[1,2]);assert.equal(r.counts.accepted,1);assert.equal(r.importReady,false);});
test('unclosed quotes block complete-file acceptance',()=>{const r=go('errors',1);assert.ok(r.errors.some(x=>x.code==='MissingQuotes'));assert.equal(r.importReady,false);});

Задача 7. Настоящий Worker и отзывчивый интерфейс

Большой набор из пяти тысяч учебных товаров разбирается в отдельном Worker. Основная страница получает сообщения о прогрессе и итоговый результат, а пользователь может продолжать взаимодействовать с интерфейсом. Используется настоящий Papa Parse с пошаговым callback; заранее подготовленная таблица не подменяет разбор.

Важная деталь реализации: это собственный Worker, внутри которого библиотека работает без опции worker:true. Поэтому локальные pause и resume доступны обработчику. Каждые двести записей он приостанавливает parser, отправляет прогресс и отдаёт управление циклу событий. Учебная пауза добавляет тридцать миллисекунд, чтобы отмену можно было спокойно попробовать.

Показатель прогресса вычисляется по cursor относительно длины текста в JavaScript. Это приблизительная доля обработанного строкового входа, а не байты сетевой загрузки. Для своего сервиса полезно разделять этапы: чтение файла, разбор, проверка, применение в базе. Один индикатор не должен создавать впечатление, что все эти операции уже выполнены.

Фрагмент src/worker.mjs

export function processJob(message,send,schedule=setTimeout) {
 const {id,text,options={}}=message; let count=0; const session=createSession(options);
 try {
  assertInput(text);
  Papa.parse(text,{...configFor(options),step(result,parser){
   count++;
   if(!session.add(result.data,result.errors,result.meta)){parser.abort();return;}
   if(count%200===0){
    const cursor=result.meta.cursor;
    parser.pause();
    send({type:'progress',id,rows:count,ratio:Math.min(0.99,cursor/text.length)});
    schedule(()=>parser.resume(),options.teachingPause?30:0);
   }
  },complete(){send({type:'done',id,result:session.finish()});}});
 }catch(error){send({type:'error',id,error:error.message});}
}

Отмена, устаревший ответ и время выполнения

Кнопка отмены завершает Worker. Частично обработанные записи не становятся доступным итоговым импортом. После нового запуска создаётся новый номер задания; сообщения предыдущей операции не могут обновить текущий экран. Такой подход полезен, когда человек быстро меняет параметры, загружает другой файл или начинает обработку повторно.

Дополнительно задан бюджет мастерской в пятнадцать секунд. Он включает учебную задержку и служит ограничением самого демонстрационного приложения. Это не обещание, что Papa Parse всегда обработает определённый объём за такое время. На результат влияют устройство, структура CSV, число колонок, копирование данных и отрисовка таблицы.

На сервере отмена требует отдельной модели: закрытие вкладки не обязательно отменяет уже запущенную задачу. Для фонового импорта нужны статус задания, допустимые точки остановки и понятное поведение транзакции. В браузерной мастерской ситуация проще: никакие внешние изменения ещё не начались, поэтому завершение Worker не оставляет наполовину обновлённую базу.

Фрагмент src/node-runner.mjs

export function runJob(text,options={}, {signal,onProgress=()=>{},timeoutMs=10000}={}) {
 return new Promise((resolve,reject)=>{
  const worker=new Worker(new URL('./node-worker.mjs',import.meta.url));
  let finished=false;
  const finish=(error,result)=>{if(finished)return;finished=true;clearTimeout(timer);signal?.removeEventListener('abort',abort);worker.terminate();error?reject(error):resolve(result);};
  const abort=()=>finish(new Error('Обработка отменена.'));
  const timer=setTimeout(()=>finish(new Error('Превышено время обработки.')),timeoutMs);
  worker.on('error',error=>finish(error));
  worker.on('message',message=>{if(message.type==='progress')onProgress(message);if(message.type==='done')finish(null,message.result);if(message.type==='error')finish(new Error(message.error));});
  signal?.addEventListener('abort',abort,{once:true});
  if(signal?.aborted){abort();return;}
  worker.postMessage({id:1,text,options});
 });
}

Потоковая обработка и память: не одно и то же

Пошаговый callback позволяет получать записи постепенно, однако приложение всё ещё может складывать их в большой массив. В нашем проекте так и сделано в пределах явного ограничения: принятые и отклонённые строки сохраняются для скачиваемого отчёта. Поэтому мастерская не объявляется решением для файлов произвольного размера.

Лимит в десять тысяч записей проверяется отдельно от размера текста. При превышении обработка останавливается, результат помечается неполным, экспорт готового CSV блокируется. Таблица показывает максимум сто записей, чтобы тысячи DOM-строк не перегружали интерфейс. Число показанных строк и общее количество видны рядом.

В промышленном конвейере можно валидировать порции, писать промежуточные результаты во временное хранилище и освобождать память. Но такой подход требует стратегии отката, ограниченной очереди и согласованного отчёта. Нельзя одновременно сохранять все строки в память и обещать постоянное потребление памяти только потому, что используется слово streaming.

Фрагмент src/core.mjs

export function createSession(options = {}) {
  const rows = [], errors = []; let meta = {}, rowCount = 0, limitReached = false;
  return {
    add(data, rowErrors, nextMeta) {
      meta = nextMeta || meta;
      for (const error of rowErrors || []) errors.push({type:error.type,code:error.code,message:error.message,row:error.row ?? rowCount});
      rowCount++;
      if (rowCount > MAX_ROWS) { limitReached = true; return false; }
      rows.push(data); return true;
    },
    finish() { return assemble(rows, errors, meta, options, {rowCount,limitReached}); }
  };
}

Задача 8. Экспорт CSV и формулы в таблицах

Восьмая задача содержит вымышленные значения, начинающиеся со знаков, которые табличные программы могут интерпретировать как формулу. Встроенный экспорт использует escapeFormulae и добавляет защитный апостроф. Раскрываемый предпросмотр позволяет увидеть изменённый текст до скачивания. Исходные данные в редакторе при этом сохраняются.

Это осознанное изменение представления значения. Если CSV предназначен для машинного обмена, партнёр должен понимать, нужен ли ему апостроф. Если файл будут открывать люди в таблицах, требуется согласованная политика безопасного экспорта и проверка целевой программы. Одна настройка библиотеки не определяет поведение всех последующих импортов и пересохранений.

Обратная сборка также корректно оформляет запятые, кавычки и переносы внутри полей. В проекте выбран разделитель «точка с запятой», CRLF и UTF-8 BOM. Эти параметры удобны для демонстрации, но формат выгрузки стоит согласовать с получателем. Дата, десятичный разделитель и кодировка остаются отдельными решениями.

Фрагмент src/core.mjs

export function exportCSV(rows, {delimiter=';',bom=true} = {}) {
  if (!Array.isArray(rows) || !rows.length) throw new Error('Нет строк для экспорта.');
  if (![';',',','\t'].includes(delimiter)) throw new Error('Недопустимый разделитель экспорта.');
  const csv=Papa.unparse(rows,{delimiter,newline:'\r\n',escapeFormulae:true});
  return (bom?'\ufeff':'')+csv;
}

Задача 9. UTF-8, Windows-1251 и BOM

Встроенный редактор уже содержит JavaScript-строку, поэтому переключатель кодировки не меняет её символы. Кодировка применяется при чтении выбранного файла: байты декодируются в текст, затем этот текст передаётся разборщику. Для упражнения приложены одинаковые учебные каталоги в UTF-8 и Windows-1251.

Попробуйте открыть файл Windows-1251 как UTF-8. Строгое декодирование откажется принимать некорректную последовательность вместо того, чтобы молча показать испорченные символы. Выберите правильный вариант, и текст появится в редакторе. После этого можно выполнять обычный разбор с теми же правилами колонок и значений.

BOM и переносы строк — другие особенности представления. Второй вариант задачи содержит UTF-8 BOM и CRLF; тест сравнивает его прикладные строки с обычным LF-вариантом. Для незнакомого файла не угадывайте кодировку по расширению. Уточните экспорт системы-источника и сохраните исходные байты, если требуется воспроизводимая диагностика.

Фрагмент src/core.mjs

export function decodeBytes(bytes, encoding='utf-8') {
  if (!['utf-8','windows-1251'].includes(encoding)) throw new Error('Кодировка не поддерживается в мастерской.');
  if (bytes.byteLength>MAX_BYTES) throw new Error('Лимит мастерской: файл до 1 MiB.');
  return new TextDecoder(encoding,{fatal:true}).decode(bytes);
}

Node.js CLI: отчёт до изменения базы

CLI принимает путь CSV, новый путь JSON-отчёта и необязательную кодировку. Он проверяет размер файла, декодирует байты и запускает тот же контракт через Node Worker Thread. Выходной JSON сохраняет результаты, поэтому его можно использовать в собственной процедуре согласования импорта или технической диагностике.

Коды завершения различаются: ноль означает успешную проверку контракта, два — созданный отчёт с ошибками данных, один — проблему чтения, декодирования, лимита или записи. Это полезно для shell-скрипта и CI: непригодный файл не должен выглядеть успешным заданием только потому, что программа смогла напечатать JSON.

Программа не перезаписывает существующий отчёт и запрещает совпадение входного и выходного пути. Для каждого запуска задавайте новое имя. CLI не принимает удалённый URL, не загружает CSV в базу и не делает HTTP-запросов с пользовательским документом. Он решает конкретную задачу проверки локального файла.

Фрагмент README.md

node tools/cli.mjs fixtures/catalog.csv report.json
node tools/cli.mjs fixtures/windows-1251.csv report-1251.json windows-1251
node tools/cli.mjs fixtures/invalid.csv report-invalid.json

Почему отчёт записывается с flag wx

На первом запуске удобно назвать результат report.json, но повторная команда с тем же именем может незаметно заменить важную диагностику. В мастерской используется эксклюзивное создание файла. Существующий отчёт остаётся нетронутым, а программа возвращает ошибку. Это позволяет однозначно связать результат с одним выполнением.

Для сервисного импорта имя должен генерировать сервер: например, по внутреннему идентификатору задания. Пользовательское имя CSV нельзя напрямую использовать как путь в каталоге отчётов. Также не стоит отдавать клиенту возможность читать произвольный report.json другого пользователя. Правила доступа должны связывать запуск с организацией и инициатором.

Уникальный файл не заменяет журнал изменений в базе. Когда появится этап применения, сохраняйте количество обновлённых и отклонённых записей, ключ операции и понятный статус. В логах достаточно диагностических идентификаторов и кодов; полный список клиентов или персональные поля обычно не нужны для ответа на вопрос, почему импорт завершился ошибкой.

Фрагмент tools/cli.mjs

else try{
 if(resolve(input)===resolve(output))throw new Error('Выберите отдельный путь отчёта; исходник сохраняется.');
 if((await stat(input)).size>MAX_BYTES)throw new Error('Файл превышает 1 MiB.');
 const text=decodeBytes(await readFile(input),encoding);
 const result=await runJob(text,{header:true,typing:'quantity',contract:true});
 await writeFile(output,JSON.stringify(result,null,2)+'\n',{flag:'wx'});
 console.log(JSON.stringify({report:output,counts:result.counts,importReady:result.importReady}));
 if(!result.importReady)process.exitCode=2;
}catch(error){console.error(error.message);process.exitCode=1;}

Docker: изолированный запуск CLI

Dockerfile устанавливает production-зависимости из lock-файла, копирует исходники и запускает CLI под пользователем node. Для демонстрации ему не требуется сетевой доступ во время обработки: учебный файл находится внутри образа, а результат записывается в отдельный bind mount. Установка пакетов при сборке — другой этап и требует доступа к реестру.

Каталог результата должен быть доступен пользователю контейнера на запись. На Linux это связано с UID и владельцем файлов; произвольное chmod 777 не является обязательным решением. Выберите пользователя запуска и права под свою среду. В Windows поведение bind mount зависит от Docker Desktop и его доступа к файловой системе.

Если Docker только осваивается, начните с материала про Docker Compose. Наш образ — небольшой проверяющий инструмент, а не готовый сервис загрузки файлов. Не подключайте к учебному контейнеру рабочие секреты, целую домашнюю папку и каталоги, которые ему не нужны.

Фрагмент Dockerfile

FROM node:24.22.2-bookworm-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev --ignore-scripts --no-audit --no-fund
COPY src ./src
COPY tools ./tools
COPY fixtures ./fixtures
USER node
ENTRYPOINT ["node", "tools/cli.mjs"]

Linux/VPS: разместить мастерскую через Nginx

Готовую папку public можно разместить как статический сайт. Постоянный процесс Node для самой страницы не требуется: Nginx отдаёт HTML, JavaScript, CSS, fixtures и JSON исходников. При таком размещении разбор пользовательского CSV по-прежнему выполняется в браузере. Ссылка на скачиваемый ZIP должна указывать на реально доступный архив проекта.

В примере ниже указан отдельный учебный virtual host. На настоящем сервере замените домен и пути, настройте HTTPS привычным способом, проверьте конфигурацию перед reload. У JavaScript должен быть правильный Content-Type; Worker загружается с того же origin. Если применяется CSP, разрешения для script и worker нужно согласовать с размещением файлов.

Подробнее ежедневные настройки разобраны в мастерской Nginx. Статический сайт и серверный импорт — разные компоненты: публикация страницы не даёт браузеру права писать в базу, читать произвольные файлы VPS или запускать команды Node.

Фрагмент VPS.md

server {
    listen 80;
    server_name csv.example.test;
    root /srv/papa-lab/current/public;
    index index.html;

    include /etc/nginx/mime.types;
    add_header X-Content-Type-Options nosniff always;

    location / {
        try_files $uri $uri/ =404;
    }
}

Linux/VPS: запуск проверки под отдельным пользователем

Для локального файла на сервере можно использовать CLI из каталога релиза. Рабочая выгрузка хранится вне public, отчёты — в закрытом каталоге, а процесс имеет права только на нужные пути. В архиве есть пример systemd oneshot с отдельным пользователем, ограничением файловой системы и закрытой маской создаваемых файлов.

Пример использует конкретное имя отчёта для одного демонстрационного запуска. Повтор с тем же путём завершится ошибкой, поскольку файл уже существует. Для расписания потребуется управляющий скрипт с уникальными ID, политикой хранения и защитой от параллельного применения одного пакета. Отметка exit2 должна приводить к разбору замечаний, а не к автоматическому продолжению импорта.

Не делайте входной каталог доступным как часть сайта. Файл может содержать контакты, цены и внутренние идентификаторы, даже если расширение выглядит безобидно. Срок хранения исходников и отчётов нужно выбрать по потребностям приложения. Для диагностики полезнее контролируемая история запусков, чем бесконечный общий каталог без владельца и правил очистки.

Фрагмент VPS.md

[Unit]
Description=Validate one synthetic CSV import

[Service]
Type=oneshot
User=csvcheck
Group=csvcheck
WorkingDirectory=/srv/import-checker/current
ExecStart=/usr/bin/node tools/cli.mjs /srv/import-data/inbox/catalog.csv /srv/import-data/reports/check-001.json
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadOnlyPaths=/srv/import-data/inbox
ReadWritePaths=/srv/import-data/reports
UMask=0077

Как превратить предпросмотр в рабочий импорт

Начните с явной последовательности действий. Сервер принимает ограниченный файл от авторизованного пользователя, декодирует его, разбирает CSV и повторяет проверку контракта. Затем сравнивает данные с текущей базой и показывает предполагаемые изменения: какие записи появятся, какие обновятся, какие останутся без изменений.

Применение должно иметь отдельные правила. Для небольшого набора подойдёт транзакция: либо пакет принят целиком, либо изменения откатились. Для большого объёма можно использовать батчи, но тогда нужно объяснить частичный успех, повторную обработку и восстановление после сбоя. Кнопка браузерного предпросмотра не решает эти вопросы за сервер.

Хороший интерфейс сохраняет контекст: имя файла, время проверки, число строк, выбранную схему и понятные причины отказа. Когда данные исправлены, пользователь запускает новую проверку. Если структура источника изменилась, система должна заметить это через контракт, а не незаметно записать значения в случайные колонки.

Что проверяют тесты и где заканчивается их доказательство

На Windows с Node 24.19.0 и в Linux-контейнере с Node 24.22.2 прошли по двадцать четыре содержательных теста. Они проверяют кавычки и многострочные поля, разделители, заголовки, ведущие нули, большой числовой текст, контракт, ошибки, формулы при экспорте, две кодировки, BOM, ограничения и полноту результатов. Отдельные тесты действительно создают Node Worker, наблюдают прогресс, отменяют обработку и проверяют бюджет времени.

CLI запускается отдельным процессом: проверяются успешный и отклонённый файл, защита исходника и отказ перезаписывать отчёт. Все восемнадцать вариантов выполнены в настоящих Worker Thread на обеих ОС; результаты, хеши исходников и готовых браузерных сборок совпали. Capture сохраняет результаты и хеши исходников, чтобы было понятно, какие именно файлы исполнялись. Это технические данные проверки, а не источник ответов публичной мастерской.

Реальное отображение страницы, мобильная ширина, кнопки, загрузка файла и скачивания проверяются отдельно в браузере. Unit tests не удостоверяют внешний вид и не превращаются в испытание физического телефона. Аналогично инструкции VPS и локальное выполнение не означают, что был настроен и проверен конкретный production-сервер.

Фрагмент README.md

npm ci --ignore-scripts --no-audit --no-fund
npm run build
npm test
npm run capture

Исходники и полезный следующий шаг

Архив содержит исходные модули, готовую мастерскую, фикстуры, CLI, тесты, lock-файл, Dockerfile и инструкции Windows/Linux. Встроенный просмотр позволяет выбрать файл, раскрыть код и скачать его отдельно. Лицензии находятся рядом, а названия и данные примеров вымышлены. Вы можете изменить контракт под свой каталог и сразу закрепить новое поведение тестом.

Начните с небольшого реального по структуре, но обезличенного образца. Опишите обязательные колонки, типы, пустые значения, уникальность ключа и допустимый диапазон чисел. Рядом добавьте несколько плохих вариантов: дубли заголовков, повреждённые кавычки, неверный разделитель, повтор ID и неподходящую кодировку. Такой набор помогает поддерживать интеграцию после изменений у поставщика.

Практический результат — предсказуемая граница между внешней таблицей и данными приложения. Человек видит, что произойдёт с файлом и что нужно исправить. Разработчик получает проверяемый модуль, который можно запускать в браузере, консоли и серверном процессе, не смешивая чтение CSV с правами доступа и изменением базы.