rest-pipeline-js 1.0.4 → 1.0.6

package/README.md

@@ -1,253 +1,412 @@
+## Утсновка
 
-# pipeline-js
+```sh
+npm i rest-pipeline-js
+```
 
-Модуль для работы с REST API, пайплайнами запросов и отслеживанием прогресса. Не зависит от Vue/React, но легко интегрируется в любые проекты.
+## Возможности и API
 
 
-## Установка
+### Базовый модуль (rest-pipeline-js)
 
+#### Пример: создание REST клиента и выполнение запроса
+
+```js
+import { createRestClient } from 'rest-pipeline-js';
+
+const client = createRestClient({
+	baseURL: 'https://api.example.com',
+	timeout: 5000,
+	headers: { Authorization: 'Bearer TOKEN' },
+});
+
+async function fetchUser(id) {
+	const res = await client.request(`/users/${id}`);
+	if (res.error) {
+		console.error(res.error);
+	} else {
+		console.log(res.data);
+	}
+}
 ```
-npm i rest-pipeline-js
-```
 
-## Быстрый старт (чистый JS)
+
+#### Пример: запуск pipeline, обработка ошибок, отслеживание выполнения и использование общего пула данных
 
 ```js
-const { createRestClient, PipelineOrchestrator } = require('rest-pipeline-js');
+import { PipelineOrchestrator } from 'rest-pipeline-js';
 
-// Создание REST клиента
-const client = createRestClient({ baseURL: 'https://api.example.com' });
-client.get('/endpoint').then(response => {
-  console.log(response.data);
+const pipelineConfig = {
+	steps: [
+		{
+			key: 'step1',
+			command: '/api/step1',
+			method: 'POST',
+			// Можно добавить кастомные параметры шага
+		},
+		{
+			key: 'step2',
+			command: '/api/step2',
+			method: 'POST',
+			dependsOn: ['step1'], // step2 выполнится только после step1
+		},
+	],
+};
+
+const httpConfig = {
+	baseURL: 'https://api.example.com',
+	timeout: 7000,
+	headers: { Authorization: 'Bearer TOKEN' },
+	retry: { attempts: 2, delayMs: 1000 },
+	cache: { enabled: true, ttlMs: 60000 },
+	rateLimit: { maxConcurrent: 2 },
+	metrics: {
+		onRequestStart: info => console.log('Start:', info),
+		onRequestEnd: info => console.log('End:', info),
+	},
+};
+
+// Общий пул данных между шагами
+const sharedData = { sessionId: 'abc123' };
+
+const orchestrator = new PipelineOrchestrator(pipelineConfig, httpConfig, sharedData, { autoReset: true });
+
+// Отслеживание прогресса
+orchestrator.subscribeProgress(progress => {
+	console.log('Текущий шаг:', progress.currentStage, 'Статусы:', progress.stageStatuses);
 });
 
-// Пример пайплайна
-const pipeline = new PipelineOrchestrator({
-  stages: [
-    {
-      key: 'getUser',
-      request: async () => client.get('/user'),
-    },
-    {
-      key: 'getPosts',
-      request: async (_, results) => client.get(`/posts?userId=${results[0].data.id}`),
-    },
-  ],
-}, { baseURL: 'https://api.example.com' });
-
-// Подписка на прогресс
-const unsubscribe = pipeline.subscribeProgress(progress => {
-  console.log('Pipeline progress:', progress);
+// Подписка на события успеха/ошибки шага
+orchestrator.on('step:step1:success', payload => {
+	console.log('Step 1 завершён успешно:', payload.data);
+});
+orchestrator.on('step:step2:error', payload => {
+	console.error('Ошибка на step2:', payload.error);
 });
 
-// Получить текущий прогресс (snapshot)
-console.log(pipeline.getProgress());
+// Подписка на все логи pipeline
+orchestrator.on('log', () => {
+	console.log('Логи:', orchestrator.getLogs());
+});
+
+// Запуск pipeline с передачей параметров
+orchestrator.run({ foo: 'bar' })
+	.then(result => {
+		console.log('Pipeline завершён. Итог:', result);
+		// Доступ к результатам всех шагов:
+		console.log('Результаты шагов:', result.stageResults);
+	})
+	.catch(err => {
+		// Глобальная обработка ошибок pipeline
+		console.error('Pipeline error:', err);
+	});
+
+// Повторный запуск шага (например, после ошибки)
+// orchestrator.rerunStep('step2');
 ```
 
+---
 
+---
 
-## React: хуки для интеграции
+Модуль предоставляет универсальный механизм для построения и управления REST API pipeline с поддержкой прогресса, обработки ошибок, подписки на события и расширяемости.
 
-### usePipelineProgress
-```jsx
-import { usePipelineProgress } from 'rest-pipeline-js/react';
-import { PipelineOrchestrator } from 'rest-pipeline-js';
 
-const pipeline = new PipelineOrchestrator({ stages: [...] }, { baseURL: '...' });
-const progress = usePipelineProgress(pipeline);
-```
+#### Основные классы и функции
 
-### usePipelineRun
-```jsx
-import { usePipelineRun } from 'rest-pipeline-js/react';
-const [run, { running, result, error }] = usePipelineRun(pipeline);
-
-// В компоненте:
-<button onClick={() => run()}>Старт</button>
-{running && <span>Выполняется...</span>}
-{result && <pre>{JSON.stringify(result)}</pre>}
-{error && <span style={{color:'red'}}>{String(error)}</span>}
-```
+---
 
-### useRestClient
-```jsx
-import { useRestClient } from 'rest-pipeline-js/react';
-const api = useRestClient({ baseURL: '...' });
-```
 
-## Vue: composition-функции для интеграции
+### createRestClient(config: HttpConfig): RestClient
+Создаёт REST-клиент с поддержкой расширенных возможностей для работы с HTTP API.
 
-### usePipelineProgress
+#### Пример
 ```js
-import { usePipelineProgress } from 'rest-pipeline-js/vue';
-import { PipelineOrchestrator } from 'rest-pipeline-js';
+import { createRestClient } from 'rest-pipeline-js';
+
+const client = createRestClient({
+	baseURL: 'https://api.example.com',
+	timeout: 5000,
+	headers: { Authorization: 'Bearer TOKEN' },
+	retry: { attempts: 2 },
+	cache: { enabled: true, ttlMs: 60000 },
+});
 
-const pipeline = new PipelineOrchestrator({ stages: [...] }, { baseURL: '...' });
-const progress = usePipelineProgress(pipeline);
+async function getUser(id) {
+	const res = await client.request(`/users/${id}`);
+	if (res.error) {
+		console.error('Ошибка:', res.error);
+	} else {
+		console.log('Пользователь:', res.data);
+	}
+}
 ```
 
-### usePipelineRun
+
+---
+
+
+### RequestExecutor
+Обёртка для выполнения REST-запросов с поддержкой автоматического retry и таймаута.
+
+#### Пример
 ```js
-import { usePipelineRun } from 'rest-pipeline-js/vue';
-const { run, running, result, error } = usePipelineRun(pipeline);
+import { RequestExecutor } from 'rest-pipeline-js';
+
+const executor = new RequestExecutor({ baseURL: 'https://api.example.com' });
+
+async function fetchData() {
+	try {
+		const res = await executor.execute('/data', { method: 'GET' }, 3, 3000);
+		if (res.error) {
+			console.error('Ошибка:', res.error);
+		} else {
+			console.log('Данные:', res.data);
+		}
+	} catch (err) {
+		console.error('Критическая ошибка:', err);
+	}
+}
 ```
 
-### useRestClient
+
+---
+
+
+
+### PipelineOrchestrator
+Основной класс для построения и управления конвейером (pipeline) из последовательных шагов.
+
+#### Основные методы и параметры
+
+- **constructor(pipelineConfig, httpConfig, sharedData?, options?)** — создание экземпляра:
+	- `pipelineConfig` — массив шагов (steps), их параметры, условия, обработчики
+	- `httpConfig` — настройки HTTP клиента
+	- `sharedData` — общий пул данных между шагами
+	- `options.autoReset` — сбрасывать ли состояние после завершения
+
+- **run(onStepPause?, externalSignal?)** — запуск конвейера
+	- `onStepPause(stepIndex, stepResult, stageResults)` — callback для паузы/подтверждения/модификации результата между шагами (можно реализовать задержку, диалог, логику)
+	- `externalSignal` — внешний AbortSignal для отмены
+	- Возвращает: `{ stageResults, success }`
+
+- **rerunStep(stepKey, options?)** — повторно выполнить один шаг
+	- `onStepPause` и `externalSignal` аналогично run
+	- Возвращает результат шага
+
+- **subscribeProgress(listener)** — подписка на прогресс выполнения (listener получает PipelineProgress)
+- **subscribeStageResults(listener)** — подписка на изменения результатов всех шагов
+- **subscribeStepProgress(stepKey, listener)** — подписка на прогресс конкретного шага
+- **on(eventName, handler)** — универсальная подписка на события:
+	- `step:<stepKey>:start|success|error|progress` — события по шагам
+	- `log` — новые логи
+	- любые кастомные события
+- **onStepStart/Finish/Error(handler)** — подписка на начало/успех/ошибку шага (PipelineStepEvent)
+- **getProgress()** — получить текущий прогресс (snapshot)
+- **getProgressRef()** — получить ссылку на объект прогресса (для реактивности)
+- **getLogs()** — получить массив логов pipeline
+- **abort()** — отменить выполнение пайплайна
+- **isAborted()** — проверить, был ли пайплайн отменён
+
+#### Важные параметры шага (stage):
+- `key` — уникальный ключ шага
+- `command` — команда/endpoint для запроса
+- `method` — HTTP-метод
+- `dependsOn` — массив ключей шагов, от которых зависит этот шаг
+- `condition(prev, allResults, sharedData)` — функция-условие для выполнения шага
+- `request(prev, allResults)` — кастомная функция запроса (альтернатива command)
+- `retryCount`, `timeoutMs` — индивидуальные настройки повтора и таймаута
+- `errorHandler(error, key, sharedData)` — обработчик ошибок шага
+
+#### Пример
 ```js
-import { useRestClient } from 'rest-pipeline-js/vue';
-const api = useRestClient({ baseURL: '...' });
+import { PipelineOrchestrator } from 'rest-pipeline-js';
+
+const pipelineConfig = {
+	steps: [
+		{ key: 'first', command: '/api/first', method: 'POST' },
+		{ key: 'second', command: '/api/second', method: 'POST', dependsOn: ['first'] },
+	],
+};
+const httpConfig = { baseURL: 'https://api.example.com' };
+const sharedData = { sessionId: 'abc' };
+const orchestrator = new PipelineOrchestrator(pipelineConfig, httpConfig, sharedData);
+
+orchestrator.subscribeProgress(progress => {
+	console.log('Прогресс:', progress);
+});
+
+orchestrator.on('step:first:success', payload => {
+	console.log('Первый шаг выполнен:', payload.data);
+});
+
+// Пауза 1 секунда между шагами
+orchestrator.run(async (i, result) => { await new Promise(r => setTimeout(r, 1000)); return result; })
+	.then(result => console.log('Pipeline завершён:', result))
+	.catch(err => console.error('Ошибка pipeline:', err));
 ```
 
-## Использование в Vue 3
 
+---
+
+
+### ProgressTracker
+Внутренний класс для отслеживания прогресса pipeline.
+
+#### Пример
 ```js
-import { createRestClient, PipelineOrchestrator } from 'rest-pipeline-js';
-import { ref, onUnmounted } from 'vue';
-
-const client = createRestClient({ baseURL: 'https://api.example.com' });
-const pipeline = new PipelineOrchestrator({
-  stages: [
-    // ...
-  ],
-}, { baseURL: 'https://api.example.com' });
-
-const progress = ref(pipeline.getProgress());
-const unsubscribe = pipeline.subscribeProgress(p => {
-  progress.value = p;
+import { ProgressTracker } from 'rest-pipeline-js';
+
+const tracker = new ProgressTracker(3); // 3 шага
+tracker.subscribe(progress => {
+	console.log('Текущий прогресс:', progress);
 });
-onUnmounted(unsubscribe);
+tracker.updateStage(1, 'success');
+console.log(tracker.getProgress());
 ```
 
-## Основные API
 
-### RestClient
-- `createRestClient(config)` — создать клиента (axios-like API: get, post, request и др.)
+---
 
-### PipelineOrchestrator
-- `new PipelineOrchestrator(pipelineConfig, httpConfig)` — создать пайплайн
-- `subscribeProgress(listener)` — подписка на прогресс, возвращает функцию отписки
-- `getProgress()` — получить текущий прогресс (snapshot)
-
-### ProgressTracker (внутренний)
-- Реактивность реализована через подписки (observer pattern), не зависит от Vue/React
-
-## Структура
-- src/rest-client.ts — основной REST клиент
-- src/types.ts — типы
-- src/request-executor.ts — выполнение запросов
-- src/error-handler.ts — обработка ошибок
-- src/progress-tracker.ts — отслеживание прогресса
-- src/pipeline-orchestrator.ts — оркестрация пайплайна
-
-### POST запрос
-
-```javascript
-api.post('/users', {
-  name: 'John Doe',
-  email: 'john@example.com'
-})
-  .then(response => {
-    console.log('User created:', response.data);
-  })
-  .catch(error => {
-    console.error('Error:', error);
-  });
-```
 
-### Использование с async/await
-
-```javascript
-async function getUsers() {
-  try {
-    const response = await api.get('/users');
-    return response.data;
-  } catch (error) {
-    console.error('Error fetching users:', error);
-    throw error;
-  }
-}
+### ErrorHandler
+Класс для обработки ошибок шагов pipeline.
+
+#### Пример
+```js
+import { ErrorHandler } from 'rest-pipeline-js';
+
+const handler = new ErrorHandler();
+const error = handler.handle(new Error('fail'), 'step1');
+console.log(error); // { type: 'unknown', error: [Error], stageKey: 'step1' }
 ```
 
-## API
+#### Типы и интерфейсы:
+
+- **HttpConfig** — конфигурация REST клиента (baseURL, timeout, headers, retry, cache, rateLimit, metrics)
+- **ApiError** — описание ошибки API
+- **ApiResponse<T>** — ответ API (данные, ошибка, статус)
+- **PipelineConfig, PipelineResult, PipelineStepEvent, PipelineStepStatus** — описание pipeline и шагов
+
+---
+
 
-### Конструктор
+### Расширение для Vue
 
-```javascript
-new Pipeline(config)
+#### Пример: использование во Vue компоненте
+
+```js
+<script setup>
+import { ref } from 'vue';
+import { PipelineOrchestrator } from 'rest-pipeline-js';
+import { usePipelineProgress, usePipelineRun } from 'rest-pipeline-js/vue';
+
+const pipelineConfig = { steps: [/* ... */] };
+const httpConfig = { baseURL: 'https://api.example.com' };
+const orchestrator = new PipelineOrchestrator(pipelineConfig, httpConfig);
+
+const progress = usePipelineProgress(orchestrator);
+const { run, running, result, error } = usePipelineRun(orchestrator);
+</script>
+
+<template>
+	<div>
+		<div>Текущий шаг: {{ progress.value.currentStage }}</div>
+		<button @click="run()" :disabled="running">Старт</button>
+		<div v-if="result">Готово: {{ result }}</div>
+		<div v-if="error">Ошибка: {{ error.message }}</div>
+	</div>
+</template>
 ```
 
-**Параметры:**
-- `config` (Object) - Объект конфигурации
-  - `baseURL` (String) - Базовый URL для всех запросов
-  - `timeout` (Number) - Таймаут запроса в миллисекундах
-  - `headers` (Object) - Заголовки по умолчанию
+---
+
+Экспортируются composition-функции для интеграции rest-pipeline-js с Vue 3:
+
+- **usePipelineProgress(orchestrator)** — реактивный прогресс pipeline (Ref<PipelineProgress>)
+- **usePipelineRun(orchestrator)** — запуск pipeline и реактивные статусы (run, running, result, error)
+- **usePipelineStepEvent(orchestrator, stepKey, eventType)** — подписка на события шага (успех, ошибка, прогресс)
+- **usePipelineLogs(orchestrator)** — реактивные логи pipeline
+- **useRerunPipelineStep(orchestrator)** — функция для повторного запуска шага
+- **useRestClient(config)** — реактивный REST клиент (computed)
 
-### Методы
+---
 
-#### `get(url, config)`
-Выполняет GET запрос.
 
-#### `post(url, data, config)`
-Выполняет POST запрос.
+### Расширение для React
 
-#### `put(url, data, config)`
-Выполняет PUT запрос.
+#### Пример: использование в React компоненте
+
+```jsx
+import React from 'react';
+import { PipelineOrchestrator } from 'rest-pipeline-js';
+import { usePipelineProgress, usePipelineRun } from 'rest-pipeline-js/react';
+
+const pipelineConfig = { steps: [/* ... */] };
+const httpConfig = { baseURL: 'https://api.example.com' };
+const orchestrator = new PipelineOrchestrator(pipelineConfig, httpConfig);
+
+export function PipelineComponent() {
+	const progress = usePipelineProgress(orchestrator);
+	const [run, { running, result, error }] = usePipelineRun(orchestrator);
+
+	return (
+		<div>
+			<div>Текущий шаг: {progress.currentStage}</div>
+			<button onClick={() => run()} disabled={running}>Старт</button>
+			{result && <div>Готово: {JSON.stringify(result)}</div>}
+			{error && <div>Ошибка: {error.message}</div>}
+		</div>
+	);
+}
+```
 
-#### `delete(url, config)`
-Выполняет DELETE запрос.
+---
 
-#### `patch(url, data, config)`
-Выполняет PATCH запрос.
+Экспортируются хуки для интеграции rest-pipeline-js с React:
 
-## Особенности
+- **usePipelineProgress(orchestrator)** — подписка на прогресс pipeline (PipelineProgress)
+- **usePipelineRun(orchestrator)** — запуск pipeline и статусы ([run, { running, result, error }])
+- **usePipelineStepEvent(orchestrator, stepKey, eventType)** — подписка на события шага (success/error/progress)
+- **usePipelineLogs(orchestrator)** — подписка на логи pipeline
+- **useRerunPipelineStep(orchestrator)** — функция для повторного запуска шага
+- **useRestClient(config)** — мемоизированный REST клиент
 
-- ✅ Поддержка Promise и async/await
-- ✅ Автоматическая обработка JSON
-- ✅ Настраиваемые заголовки
-- ✅ Обработка ошибок
-- ✅ Поддержка таймаутов
-- ✅ Легковесная библиотека без лишних зависимостей
+---
 
 ## Требования
 
-- Node.js >= 12.0.0
-- Современный браузер с поддержкой ES6
+- Node.js >= 14.0.0
+- Современный браузер с поддержкой ES2020
+
+---
 
-## Разработка
+## Разработка и вклад
 
 ```bash
 # Клонировать репозиторий
 git clone https://github.com/macrulezru/pipeline-js.git
-
-# Установить зависимости
+cd pipeline-js
 npm install
-
-# Запустить тесты
 npm test
-
-# Запустить линтер
 npm run lint
 ```
 
-## Вклад в проект
-
-Мы приветствуем вклад в развитие проекта! Пожалуйста:
-
-1. Форкните репозиторий
-2. Создайте ветку для вашей функции (`git checkout -b feature/amazing-feature`)
-3. Закоммитьте изменения (`git commit -m 'Add some amazing feature'`)
-4. Запушьте ветку (`git push origin feature/amazing-feature`)
-5. Откройте Pull Request
+---
 
 ## Лицензия
 
 MIT
 
+---
+
 ## Автор
 
-Git [macrulezru](https://github.com/macrulezru)
-Сайт [macrulez.ru](https://macrulez.ru/)
+GitHub: [macrulezru](https://github.com/macrulezru)
+Сайт: [macrulez.ru](https://macrulez.ru/)
+
+---
 
 ## Поддержка
 
-Если у вас возникли вопросы или проблемы, пожалуйста, создайте [issue](https://github.com/macrulezru/pipeline-js/issues) в репозитории.
+Вопросы и баги — через [issue](https://github.com/macrulezru/pipeline-js/issues)