Upload Scripts Helpers

Набор утилит для загрузки и обработки данных для дальнейшей обработки в Pentaho.

Установка

``bash
npm install @set2333/upload-script-helpers
`

Требования

- Node.js >= 12.0.0

Быстрый старт

`typescript
import {
EmailManager,
FileManager,
Logger,
ParserXLS,
Validator,
ApiManager,
JsonMapper
} from '@set2333/upload-script-helpers'

// Создание логгера
const logger = new Logger({
displayTypes: ['console', { type: 'file', options: { logFile: 'app.log' } }]
})

// Управление файлами
const fileManager = new FileManager({
workDirectory: './work-dir',
logger
})

// Работа с API
const apiManager = new ApiManager({
baseUrl: 'https://api.example.com',
headers: { 'Authorization': 'Bearer token' }
})

// Получение данных
const apiData = await apiManager.fetch({ page: 1, limit: 100 })

// Сохранение данных
fileManager.saveJSONFile(apiData, 'api-response.json')
`

Модули

$3

Система логирования с поддержкой консоли и файлов.

Опции:
- messageTypes - типы сообщений для логирования: ['log', 'warn', 'error']
- displayTypes - способы вывода: ['console'] или [{ type: 'file', options: { logFile: 'app.log', logDir: './logs' } }]

Методы:
- log(message: string, ...args: unknown[]) - обычное сообщение
- warn(message: string, ...args: unknown[]) - предупреждение
- error(message: string, ...args: unknown[]) - ошибка
- start(message: string) - начало процесса с временной меткой
- end(message: string) - конец процесса с временной меткой
- duration(processName: string) - длительность процесса

Пример:
`typescript
const logger = new Logger({
displayTypes: [
'console',
{ type: 'file', options: { logFile: 'app.log', logDir: './logs' } }
]
})

logger.start('Обработка данных')
logger.log('Загружаем файл...')
logger.warn('Файл большой, это может занять время')
logger.duration('Обработка данных')
logger.end('Обработка завершена')
`

$3

Управление файлами и рабочими директориями.

Опции:
- workDirectory (string) - путь к рабочей директории
- logger (ILogger | null) - логгер для вывода сообщений

Методы:
- saveJSONFile(data: unknown, fileName: string) - сохранение JSON файла
- saveAttachment(attachmentData: Buffer, fileName: string) - сохранение вложения

Пример:
`typescript
const fileManager = new FileManager({
workDirectory: './work-dir',
logger
})

// Сохранение JSON данных
const userData = { users: [{ name: 'John', age: 30 }] }
fileManager.saveJSONFile(userData, 'users.json')

// Сохранение вложения из email
const attachmentBuffer = Buffer.from('file content')
fileManager.saveAttachment(attachmentBuffer, 'document.xlsx')
`

$3

Работа с email через IMAP и SMTP.

Опции:
- credentials - данные для подключения к почтовому серверу
- searchRules - правила поиска писем
- logger - логгер для вывода сообщений

Методы:
- connect() - подключение к серверу
- disconnect() - отключение от сервера
- getEmails() - получение писем с вложениями
- sendEmail(options) - отправка письма

Пример:
`typescript
const emailManager = new EmailManager({
credentials: {
host: 'imap.gmail.com',
port: 993,
user: 'your-email@gmail.com',
pass: 'your-password',
smtpHost: 'smtp.gmail.com',
smtpPort: 587,
smtpUser: 'your-email@gmail.com',
smtpPass: 'your-password'
},
searchRules: {
since: '2024-01-01',
before: '2024-12-31',
attachmentMask: /\.xlsx$/
},
logger
})

await emailManager.connect()
const emails = await emailManager.getEmails()

for (const email of emails) {
fileManager.saveAttachment(email.buffer, email.attachment)
}

await emailManager.sendEmail({
to: 'recipient@example.com',
subject: 'Обработка завершена',
text: 'Данные успешно обработаны'
})

await emailManager.disconnect()
`

$3

Парсинг Excel файлов (.xlsx).

Опции:
- data - Buffer с данными Excel файла
- fileName - имя файла
- usedSheet - название листа для парсинга
- logger - логгер для вывода сообщений

Методы:
- getColumnNames() - получение названий колонок
- parse(options) - парсинг данных в объекты

Пример:
`typescript
const parser = new ParserXLS({
data: excelBuffer,
fileName: 'data.xlsx',
usedSheet: 'Sheet1',
logger
})

// Получение названий колонок
const columns = parser.getColumnNames()
console.log('Колонки:', columns)

// Парсинг данных
const parsedData = await parser.parse({
fieldNames: ['name', 'age', 'email', null], // null игнорирует колонку
initDataRow: (fileName) => ({
source: fileName,
processed: false
})
})

console.log('Данные:', parsedData)
`

$3

Валидация Excel файлов перед обработкой.

Опции:
- validationRules - массив правил валидации
- usedSheet - название листа для валидации
- logger - логгер для вывода сообщений

Типы правил:
- sheetExists - проверка существования листа
- sheetHasData - проверка наличия данных
- columnHasName - проверка названия колонки
- columnHasType - проверка типа данных в колонке

Пример:
`typescript
const validator = new Validator({
validationRules: [
{ type: 'sheetExists' },
{ type: 'sheetHasData' },
{ type: 'columnHasName', options: [0, 'Name'] },
{ type: 'columnHasType', options: [1, 'number'] }
],
usedSheet: 'Sheet1',
logger
})

const errors = await validator.validate(excelBuffer)
if (errors) {
console.error('Ошибки валидации:', errors)
} else {
console.log('Файл прошел валидацию')
}
`

$3

Работа с HTTP API.

Опции:
- baseUrl - базовый URL API
- headers - заголовки запросов
- method - HTTP метод (по умолчанию GET)
- logger - логгер для вывода сообщений

Методы:
- fetch(params?) - выполнение HTTP запроса

Пример:
`typescript
const apiManager = new ApiManager({
baseUrl: 'https://api.example.com',
headers: {
'Authorization': 'Bearer your-token',
'Content-Type': 'application/json'
},
method: 'GET',
logger
})

// GET запрос с параметрами
const data = await apiManager.fetch({
page: 1,
limit: 100,
search: 'test'
})

// POST запрос (изменяем метод)
apiManager['method'] = 'POST'
const result = await apiManager.fetch({ name: 'New Item' })
`

$3

Преобразование JSON данных.

Опции:
- nameRules - правила переименования полей
- valueRules - правила преобразования значений
- excludeRules - поля для исключения
- dataExpansion - функция для расширения данных

Методы:
- map(data) - преобразование данных

Пример:
`typescript
const jsonMapper = new JsonMapper({
nameRules: {
'user_name': 'name',
'user_age': 'age'
},
valueRules: {
'age': (value) => Number(value),
'email': (value) => String(value).toLowerCase()
},
excludeRules: ['password', 'secret'],
dataExpansion: (data) => ({
...data,
processedAt: new Date().toISOString()
})
})

const originalData = {
user_name: 'John',
user_age: '30',
email: 'JOHN@EXAMPLE.COM',
password: 'secret123'
}

const mappedData = jsonMapper.map(originalData)
console.log(mappedData)
// { name: 'John', age: 30, email: 'john@example.com', processedAt: '2024-01-01T12:00:00.000Z' }
`

Полный пример использования

Пример скрипта, который получает данные из email, валидирует Excel файлы, парсит их и сохраняет результат:

`typescript
import {
EmailManager,
FileManager,
Logger,
ParserXLS,
Validator,
JsonMapper
} from '@set2333/upload-script-helpers'

async function processEmailAttachments() {
const logger = new Logger({
displayTypes: ['console', { type: 'file', options: { logFile: 'process.log' } }]
})

const fileManager = new FileManager({
workDirectory: './processed-data',
logger
})

const emailManager = new EmailManager({
credentials: {
host: 'imap.gmail.com',
port: 993,
user: process.env.EMAIL_USER!,
pass: process.env.EMAIL_PASS!,
smtpHost: 'smtp.gmail.com',
smtpPort: 587,
smtpUser: process.env.EMAIL_USER!,
smtpPass: process.env.EMAIL_PASS!
},
searchRules: {
since: '2024-01-01',
before: '2024-12-31',
attachmentMask: /\.xlsx$/
},
logger
})

const validator = new Validator({
validationRules: [
{ type: 'sheetExists' },
{ type: 'sheetHasData' },
{ type: 'columnHasName', options: [0, 'Name'] },
{ type: 'columnHasType', options: [1, 'number'] }
],
usedSheet: 'Data',
logger
})

const jsonMapper = new JsonMapper({
nameRules: {
'Name': 'name',
'Age': 'age',
'Email': 'email'
},
valueRules: {
'age': (value) => Number(value),
'email': (value) => String(value).toLowerCase()
},
dataExpansion: (data) => ({
...data,
processedAt: new Date().toISOString(),
source: 'email-attachment'
})
})

try {
logger.start('Обработка email вложений')

await emailManager.connect()
const emails = await emailManager.getEmails()

logger.log(Найдено писем с вложениями: ${emails.length})

for (const email of emails) {
logger.log(Обрабатываем файл: ${email.attachment})

// Валидация файла
const validationErrors = await validator.validate(email.buffer)
if (validationErrors) {
logger.error(Файл ${email.attachment} не прошел валидацию:, validationErrors)
continue
}

// Парсинг Excel файла
const parser = new ParserXLS({
data: email.buffer,
fileName: email.attachment,
usedSheet: 'Data',
logger
})

const parsedData = await parser.parse({
fieldNames: ['name', 'age', 'email']
})

// Преобразование данных
const mappedData = parsedData.map(row => jsonMapper.map(row))

// Сохранение результата
const resultFileName = processed_${email.attachment.replace('.xlsx', '.json')}
fileManager.saveJSONFile(mappedData, resultFileName)

logger.log(Файл ${email.attachment} успешно обработан)
}

await emailManager.sendEmail({
to: 'admin@example.com',
subject: 'Обработка завершена',
text: Обработано файлов: ${emails.length}
})

await emailManager.disconnect()
logger.end('Обработка email вложений')

} catch (error) {
logger.error('Ошибка при обработке:', error)
throw error
}
}

// Запуск скрипта
processEmailAttachments().catch(console.error)
`

Готовый к использованию пакет

Пакет поставляется уже скомпилированным и готовым к использованию:
- dist/index.js - CommonJS версия (минифицированная)
- dist/index.mjs - ES модули версия (минифицированная)
- dist/index.d.ts - TypeScript типы

Разработка

`bash


Установка зависимостей

npm install

Сборка

npm run build

Разработка с отслеживанием изменений

npm run dev

Проверка типов

npm run typecheck

Запуск тестов

npm test

Запуск тестов один раз

npm run test:run

Проверка линтера

npm run lint

Автоисправление ошибок линтера

npm run lint:fix

Запуск pre-commit проверок

npm run pre-commit

Запуск pre-publish проверок

npm run pre-publish
`

Git хуки

Проект использует Husky для автоматических проверок:

$3

Автоматически запускается перед каждым коммитом:
- Исправляет ошибки ESLint в измененных файлах
- Проверяет типы TypeScript
- Запускает lint-staged

$3

Автоматически запускается перед публикацией:
- Проверяет код линтером
- Проверяет типы TypeScript
- Запускает все тесты
- Собирает проект

Хуки настроены в .husky/ директории и автоматически устанавливаются при npm install.

Публикация

`bash


Публикация с поднятием patch версии (1.0.0 -> 1.0.1)

npm run publish:patch

Публикация с поднятием minor версии (1.0.0 -> 1.1.0)

npm run publish:minor

Публикация с поднятием major версии (1.0.0 -> 2.0.0)

npm run publish:major
`

Скрипт автоматически:
- Поднимает версию в package.json
- Собирает проект
- Публикует в npm

> Примечание: Git команды убраны из скрипта. Версию нужно обновлять в git вручную.

Поддерживаемые форматы

- CommonJS (require)
- ES модули (import`)
- TypeScript типы