rest-pipeline-js 1.0.3 → 1.0.5

package/README.md

@@ -1,253 +1,409 @@
 
-# pipeline-js
 
-Модуль для работы с REST API, пайплайнами запросов и отслеживанием прогресса. Не зависит от Vue/React, но легко интегрируется в любые проекты.
 
+## Возможности и API
 
-## Установка
 
-```
-npm i rest-pipeline-js
+### Базовый модуль (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);
+	}
+}
 ```
 
-## Быстрый старт (чистый JS)
+
+#### Пример: запуск pipeline, обработка ошибок, отслеживание выполнения и использование общего пула данных
 
 ```js
-const { createRestClient, PipelineOrchestrator } = require('pipeline-js');
+import { PipelineOrchestrator } from 'rest-pipeline-js';
+
+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);
+});
 
-// Создание REST клиента
-const client = createRestClient({ baseURL: 'https://api.example.com' });
-client.get('/endpoint').then(response => {
-  console.log(response.data);
+// Подписка на события успеха/ошибки шага
+orchestrator.on('step:step1:success', payload => {
+	console.log('Step 1 завершён успешно:', payload.data);
+});
+orchestrator.on('step:step2:error', payload => {
+	console.error('Ошибка на step2:', payload.error);
 });
 
-// Пример пайплайна
-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);
+// Подписка на все логи pipeline
+orchestrator.on('log', () => {
+	console.log('Логи:', orchestrator.getLogs());
 });
 
-// Получить текущий прогресс (snapshot)
-console.log(pipeline.getProgress());
+// Запуск 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 'pipeline-js/react';
-import { PipelineOrchestrator } from 'pipeline-js';
 
-const pipeline = new PipelineOrchestrator({ stages: [...] }, { baseURL: '...' });
-const progress = usePipelineProgress(pipeline);
-```
+#### Основные классы и функции
 
-### usePipelineRun
-```jsx
-import { usePipelineRun } from '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 'pipeline-js/react';
-const api = useRestClient({ baseURL: '...' });
-```
 
-## Vue: composition-функции для интеграции
+### createRestClient(config: HttpConfig): RestClient
+Создаёт REST-клиент с поддержкой расширенных возможностей для работы с HTTP API.
 
-### usePipelineProgress
+#### Пример
 ```js
-import { usePipelineProgress } from 'pipeline-js/vue';
-import { PipelineOrchestrator } from '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 '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 '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 '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
 
-### Конструктор
+#### Пример: использование во Vue компоненте
 
-```javascript
-new Pipeline(config)
+```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 запрос.
+### Расширение для React
 
-#### `post(url, data, config)`
-Выполняет POST запрос.
+#### Пример: использование в React компоненте
 
-#### `put(url, data, config)`
-Выполняет PUT запрос.
+```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)

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "rest-pipeline-js",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Pipeline Orchestration Utilities for JavaScript REST API Clients",
   "main": "dist/index.js",
-  "types": "src/types.ts",
+  "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc",
     "test": "echo \"No tests specified\" && exit 0"

package/react/usePipelineStepEvents.ts

@@ -0,0 +1,45 @@
+import { useEffect, useRef, useState } from 'react';
+import type { PipelineOrchestrator } from '../src/pipeline-orchestrator';
+
+/**
+ * React hook for subscribing to step events (success/error/progress) for a specific step
+ * @param orchestrator PipelineOrchestrator instance
+ * @param stepKey string — step key
+ * @param eventType 'success' | 'error' | 'progress'
+ * @returns last event payload (any)
+ */
+export function usePipelineStepEvent(orchestrator: PipelineOrchestrator, stepKey: string, eventType: 'success' | 'error' | 'progress') {
+  const [event, setEvent] = useState<any>(null);
+  const handlerRef = useRef<any>();
+  useEffect(() => {
+    handlerRef.current = (payload: any) => setEvent(payload);
+    const eventName = `step:${stepKey}:${eventType}`;
+    const unsubscribe = orchestrator.on(eventName, handlerRef.current);
+    return () => unsubscribe && unsubscribe();
+  }, [orchestrator, stepKey, eventType]);
+  return event;
+}
+
+/**
+ * React hook for subscribing to pipeline logs
+ * @param orchestrator PipelineOrchestrator instance
+ * @returns array of log entries (reactive)
+ */
+export function usePipelineLogs(orchestrator: PipelineOrchestrator) {
+  const [logs, setLogs] = useState(() => orchestrator.getLogs());
+  useEffect(() => {
+    const handler = () => setLogs(orchestrator.getLogs());
+    const unsubscribe = orchestrator.on('log', handler);
+    return () => unsubscribe && unsubscribe();
+  }, [orchestrator]);
+  return logs;
+}
+
+/**
+ * React hook for rerunning a pipeline step
+ * @param orchestrator PipelineOrchestrator instance
+ * @returns rerunStep function
+ */
+export function useRerunPipelineStep(orchestrator: PipelineOrchestrator) {
+  return orchestrator.rerunStep.bind(orchestrator);
+}

package/src/pipeline-orchestrator.ts

@@ -1,10 +1,32 @@
+
 import { ErrorHandler } from './error-handler';
 import { ProgressTracker } from './progress-tracker';
 import { RequestExecutor } from './request-executor';
 
 import type { PipelineConfig, PipelineResult } from './types';
 
-// import { metricsBus } from '@/core/metrics/metrics-bus';
+/**
+ * Событие шага pipeline (для хуков)
+ */
+export type PipelineStepEvent = {
+  /** Индекс шага */
+  stepIndex: number;
+  /** Ключ шага */
+  stepKey: string;
+  /** Статус шага */
+  status: import('./types').PipelineStepStatus;
+  /** Данные результата (если успех) */
+  data?: any;
+  /** Ошибка (если error) */
+  error?: import('./types').ApiError;
+  /** Снимок всех результатов на момент события */
+  stageResults: Record<string, import('./types').PipelineStepResult>;
+};
+
+/**
+ * Callback для подписки на события этапов pipeline
+ */
+export type PipelineStepEventHandler = (event: PipelineStepEvent) => void | Promise<void>;
 
 export class PipelineOrchestrator {
   private progress: ProgressTracker;
@@ -12,15 +34,236 @@ export class PipelineOrchestrator {
   private executor: RequestExecutor;
   private sharedData: Record<string, unknown>;
 
+  private onStepStartHandlers: PipelineStepEventHandler[] = [];
+  private onStepFinishHandlers: PipelineStepEventHandler[] = [];
+  private onStepErrorHandlers: PipelineStepEventHandler[] = [];
+
+  /** Универсальные подписчики событий: ключ — имя события */
+  private eventHandlers: Record<string, Array<(...args: any[]) => void | Promise<void>>> = {};
+
+  /** Встроенные логи */
+  private logs: Array<{ type: string; message: string; data?: any; timestamp: Date }> = [];
+
+  private stageResults: Record<string, import('./types').PipelineStepResult> = {};
+  private stageResultsListeners: Array<(results: Record<string, import('./types').PipelineStepResult>) => void> = [];
+  private autoReset: boolean;
+  /** AbortController для отмены пайплайна */
+  private abortController: AbortController | null = null;
+
+  private config: PipelineConfig;
+
   constructor(
-    private config: PipelineConfig,
+    config: PipelineConfig,
     httpConfig: import('./types').HttpConfig,
     sharedData: Record<string, unknown> = {},
+    options: { autoReset?: boolean } = {}
   ) {
+    this.config = config;
     this.progress = new ProgressTracker(config.stages.length);
     this.errorHandler = new ErrorHandler();
     this.executor = new RequestExecutor(httpConfig);
     this.sharedData = sharedData;
+    this.autoReset = options.autoReset ?? false;
+  }
+
+  /**
+   * Подписка на изменения stageResults (реактивно)
+   */
+  subscribeStageResults(listener: (results: Record<string, import('./types').PipelineStepResult>) => void) {
+    this.stageResultsListeners.push(listener);
+    // Немедленно уведомляем нового подписчика о текущем состоянии
+    listener({ ...this.stageResults });
+    return () => {
+      this.stageResultsListeners = this.stageResultsListeners.filter(l => l !== listener);
+    };
+  }
+
+  /**
+   * Универсальная подписка на события: step:<key>, progress, log и др.
+   */
+  on(event: string, handler: (...args: any[]) => void | Promise<void>) {
+    if (!this.eventHandlers[event]) this.eventHandlers[event] = [];
+    this.eventHandlers[event].push(handler);
+    return () => {
+      this.eventHandlers[event] = this.eventHandlers[event].filter(h => h !== handler);
+    };
+  }
+
+  /**
+   * Вызов всех обработчиков события
+   */
+  private async emit(event: string, ...args: any[]) {
+    if (this.eventHandlers[event]) {
+      for (const handler of this.eventHandlers[event]) {
+        await handler(...args);
+      }
+    }
+  }
+
+  /**
+   * Получить логи пайплайна
+   */
+  getLogs() {
+    return [...this.logs];
+  }
+
+  private notifyStageResults() {
+    for (const listener of this.stageResultsListeners) {
+      listener({ ...this.stageResults });
+    }
+  }
+
+  /**
+   * Повторно выполнить только один шаг пайплайна (без полного рестарта)
+   * @param stepKey ключ шага
+   * @param options дополнительные опции (например, onStepPause, externalSignal)
+   */
+  async rerunStep(
+    stepKey: string,
+    options?: {
+      onStepPause?: (
+        stepIndex: number,
+        stepResult: unknown,
+        stageResults: Record<string, import('./types').PipelineStepResult>,
+      ) => Promise<unknown> | unknown,
+      externalSignal?: AbortSignal
+    }
+  ): Promise<import('./types').PipelineStepResult | undefined> {
+    const i = this.config.stages.findIndex(s => s.key === stepKey);
+    if (i === -1) return undefined;
+    const stage = this.config.stages[i];
+    const key = stage.key;
+    const signal = options?.externalSignal;
+    this.logs.push({ type: 'log', message: `rerunStep:${key}:start`, timestamp: new Date(), data: { stepIndex: i } });
+    await this.emit('log', { type: 'rerunStep:start', stepKey: key, stepIndex: i });
+    this.stageResults[key] = { status: 'pending' };
+    this.notifyStageResults();
+    this.progress.updateStage(i, 'loading');
+    await this.emitStepStart({ stepIndex: i, stepKey: key, status: 'loading', stageResults: { ...this.stageResults } });
+    await this.emit(`step:${key}:start`, { stepIndex: i, stepKey: key, status: 'loading', stageResults: { ...this.stageResults } });
+    try {
+      let stepResult: unknown;
+      if (typeof stage.request === 'function') {
+        stepResult = await stage.request(
+          i > 0 ? this.stageResults[this.config.stages[i-1].key]?.data : undefined,
+          this.stageResults
+        );
+      } else {
+        const res = await this.executor.execute(
+          stage.key,
+          undefined,
+          stage.retryCount,
+          stage.timeoutMs,
+        );
+        stepResult = res.data;
+      }
+      if (options?.onStepPause) {
+        stepResult = await options.onStepPause(i, stepResult, this.stageResults);
+      }
+      this.stageResults[key] = { status: 'success', data: stepResult };
+      this.notifyStageResults();
+      this.progress.updateStage(i, 'success');
+      await this.emitStepFinish({ stepIndex: i, stepKey: key, status: 'success', data: stepResult, stageResults: { ...this.stageResults } });
+      await this.emit(`step:${key}:success`, { stepIndex: i, stepKey: key, status: 'success', data: stepResult, stageResults: { ...this.stageResults } });
+      this.logs.push({ type: 'log', message: `rerunStep:${key}:success`, timestamp: new Date(), data: { stepIndex: i, data: stepResult } });
+      await this.emit('log', { type: 'rerunStep:success', stepKey: key, stepIndex: i, data: stepResult });
+      return this.stageResults[key];
+    } catch (err) {
+      let handled;
+      if (stage && typeof stage.errorHandler === 'function') {
+        handled = stage.errorHandler(err, stage.key, this.sharedData);
+      } else if (stage) {
+        handled = this.errorHandler.handle(err, stage.key);
+      } else {
+        handled = this.errorHandler.handle(err, 'unknown');
+      }
+      if (!handled && stage) {
+        handled = this.errorHandler.handle(err, stage.key);
+      }
+      const { toApiError } = await import('./rest-client.js');
+      const apiError = toApiError(handled ?? err);
+      this.stageResults[key] = { status: 'error', error: apiError };
+      this.notifyStageResults();
+      this.progress.updateStage(i, 'error');
+      await this.emitStepError({ stepIndex: i, stepKey: key, status: 'error', error: apiError, stageResults: { ...this.stageResults } });
+      await this.emit(`step:${key}:error`, { stepIndex: i, stepKey: key, status: 'error', error: apiError, stageResults: { ...this.stageResults } });
+      this.logs.push({ type: 'error', message: `rerunStep:${key}:error`, timestamp: new Date(), data: { stepIndex: i, error: apiError } });
+      await this.emit('log', { type: 'rerunStep:error', stepKey: key, stepIndex: i, error: apiError });
+      return this.stageResults[key];
+    }
+  }
+
+  /**
+   * Отменить выполнение пайплайна (вызывает ошибку AbortError)
+   */
+  abort() {
+    if (this.abortController) {
+      this.abortController.abort();
+    }
+  }
+
+  /**
+   * Проверить, был ли пайплайн отменён
+   */
+  isAborted() {
+    return this.abortController?.signal.aborted ?? false;
+  }
+
+  /**
+   * Подписка на событие начала шага
+   */
+  onStepStart(handler: PipelineStepEventHandler) {
+    this.onStepStartHandlers.push(handler);
+    return () => {
+      this.onStepStartHandlers = this.onStepStartHandlers.filter(h => h !== handler);
+    };
+  }
+
+  /**
+   * Подписка на событие успешного завершения шага
+   */
+  onStepFinish(handler: PipelineStepEventHandler) {
+    this.onStepFinishHandlers.push(handler);
+    return () => {
+      this.onStepFinishHandlers = this.onStepFinishHandlers.filter(h => h !== handler);
+    };
+  }
+
+  /**
+   * Подписка на событие ошибки шага
+   */
+  onStepError(handler: PipelineStepEventHandler) {
+    this.onStepErrorHandlers.push(handler);
+    return () => {
+      this.onStepErrorHandlers = this.onStepErrorHandlers.filter(h => h !== handler);
+    };
+  }
+
+  private async emitStepStart(event: PipelineStepEvent) {
+    for (const handler of this.onStepStartHandlers) {
+      await handler(event);
+    }
+    // Гибкая подписка на step:<key>:start
+    await this.emit(`step:${event.stepKey}:start`, event);
+    // Логирование
+    this.logs.push({ type: 'log', message: `step:${event.stepKey}:start`, timestamp: new Date(), data: event });
+    await this.emit('log', { type: 'step:start', ...event });
+  }
+  private async emitStepFinish(event: PipelineStepEvent) {
+    for (const handler of this.onStepFinishHandlers) {
+      await handler(event);
+    }
+    await this.emit(`step:${event.stepKey}:success`, event);
+    this.logs.push({ type: 'log', message: `step:${event.stepKey}:success`, timestamp: new Date(), data: event });
+    await this.emit('log', { type: 'step:success', ...event });
+  }
+  private async emitStepError(event: PipelineStepEvent) {
+    for (const handler of this.onStepErrorHandlers) {
+      await handler(event);
+    }
+    await this.emit(`step:${event.stepKey}:error`, event);
+    this.logs.push({ type: 'error', message: `step:${event.stepKey}:error`, timestamp: new Date(), data: event });
+    await this.emit('log', { type: 'step:error', ...event });
   }
 
   /**
@@ -32,6 +275,13 @@ export class PipelineOrchestrator {
     return this.progress.subscribe(listener);
   }
 
+  /**
+   * Подписка на прогресс с фильтрацией по этапу (stepKey) или общий
+   */
+  subscribeStepProgress(stepKey: string, listener: (status: import('./types').PipelineStepStatus) => void) {
+    return this.on(`step:${stepKey}:progress`, listener);
+  }
+
   /**
    * Получить текущий прогресс выполнения pipeline (snapshot, не реактивный)
    */
@@ -40,44 +290,101 @@ export class PipelineOrchestrator {
   }
 
   /**
-   * @param onStepPause
-   *   Необязательный callback, вызывается после каждого шага (до перехода к следующему).
-   *   Позволяет приостановить выполнение, запросить подтверждение пользователя или изменить результат шага.
-   *   Должен вернуть (optionally изменённый) результат шага или промис с ним.
-   *   Если не передан — пайплайн работает как раньше.
+   * Возвращает текущий снимок состояния прогресса (не реактивный).
+   * Для отслеживания изменений используйте subscribeProgress.
+   */
+  getProgressRef() {
+    return this.progress.getProgressRef();
+  }
+
+  /**
+   * Запустить выполнение пайплайна
+   * @param onStepPause callback для пользовательской паузы между шагами
+   * @param externalSignal внешний AbortSignal (опционально)
    */
   async run(
     onStepPause?: (
       stepIndex: number,
       stepResult: unknown,
-      results: unknown[],
+      stageResults: Record<string, import('./types').PipelineStepResult>,
     ) => Promise<unknown> | unknown,
-  ): Promise<PipelineResult> {
-    const results: unknown[] = [];
-    const errors: unknown[] = [];
+    externalSignal?: AbortSignal
+  ): Promise<import('./types').PipelineResult> {
+    if (this.autoReset) {
+      this.stageResults = {};
+      this.notifyStageResults();
+    }
     let success = true;
 
+    // Создаём новый AbortController для этого запуска
+    this.abortController = new AbortController();
+    const signal = externalSignal ?? this.abortController.signal;
+
     for (let i = 0; i < this.config.stages.length; i++) {
+      if (signal.aborted) {
+        // Прерываем выполнение, если был вызван abort
+        const { toApiError } = await import('./rest-client.js');
+        const apiError = toApiError({ message: 'Pipeline aborted', code: 'ABORTED' });
+        const key = this.config.stages[i]?.key || `stage${i}`;
+        this.stageResults[key] = { status: 'error', error: apiError };
+        this.notifyStageResults();
+        this.progress.updateStage(i, 'error');
+        this.logs.push({ type: 'error', message: `abort:${key}`, timestamp: new Date(), data: { stepIndex: i, error: apiError } });
+        await this.emit('log', { type: 'abort', stepKey: key, stepIndex: i, error: apiError });
+        await this.emitStepError({
+          stepIndex: i,
+          stepKey: key,
+          status: 'error',
+          error: apiError,
+          stageResults: { ...this.stageResults },
+        });
+        success = false;
+        break;
+      }
       const stage = this.config.stages[i];
-      this.progress.updateStage(i, 'in-progress');
+      const key = stage?.key || `stage${i}`;
+      this.stageResults[key] = { status: 'pending' };
+      this.notifyStageResults();
+      this.progress.updateStage(i, 'loading');
+
+      // Гибкая подписка на прогресс шага
+      await this.emit(`step:${key}:progress`, 'loading');
+
+      // emit step start
+      await this.emitStepStart({
+        stepIndex: i,
+        stepKey: key,
+        status: 'loading',
+        stageResults: { ...this.stageResults },
+      });
 
       if (!stage) {
         this.progress.updateStage(i, 'skipped');
-        results.push(undefined);
+        this.stageResults[key] = { status: 'skipped' };
+        this.notifyStageResults();
+        await this.emit(`step:${key}:progress`, 'skipped');
         continue;
       }
 
       // Проверка условия выполнения этапа
-      if (stage.condition && !stage.condition(results[i - 1], results, this.sharedData)) {
+      if (stage.condition && !stage.condition(
+        i > 0 ? this.stageResults[this.config.stages[i-1].key]?.data : undefined,
+        this.stageResults,
+        this.sharedData)) {
         this.progress.updateStage(i, 'skipped');
-        results.push(undefined);
+        this.stageResults[key] = { status: 'skipped' };
+        this.notifyStageResults();
+        await this.emit(`step:${key}:progress`, 'skipped');
         continue;
       }
       try {
         let stepResult: unknown;
         // Всегда передаём (prev, allResults) в request — best practice для pipeline
         if (typeof stage.request === 'function') {
-          stepResult = await stage.request(results[i - 1], results);
+          stepResult = await stage.request(
+            i > 0 ? this.stageResults[this.config.stages[i-1].key]?.data : undefined,
+            this.stageResults
+          );
         } else if (stage.key) {
           const res = await this.executor.execute(
             stage.key,
@@ -92,12 +399,22 @@ export class PipelineOrchestrator {
 
         // --- Пользовательская пауза/подтверждение/изменение результата ---
         if (onStepPause) {
-          stepResult = await onStepPause(i, stepResult, results);
+          stepResult = await onStepPause(i, stepResult, this.stageResults);
         }
-        results.push(stepResult);
+        this.stageResults[key] = { status: 'success', data: stepResult };
+        this.notifyStageResults();
         this.progress.updateStage(i, 'success');
+        await this.emit(`step:${key}:progress`, 'success');
+
+        // emit step finish
+        await this.emitStepFinish({
+          stepIndex: i,
+          stepKey: key,
+          status: 'success',
+          data: stepResult,
+          stageResults: { ...this.stageResults },
+        });
 
-        // ...existing code...
       } catch (err) {
         let handled;
         if (stage && typeof stage.errorHandler === 'function') {
@@ -110,13 +427,26 @@ export class PipelineOrchestrator {
         if (!handled && stage) {
           handled = this.errorHandler.handle(err, stage.key);
         }
-        errors.push(handled);
+        // Унификация: всегда ApiError
+        const { toApiError } = await import('./rest-client.js');
+        const apiError = toApiError(handled ?? err);
+        this.stageResults[key] = { status: 'error', error: apiError };
+        this.notifyStageResults();
         this.progress.updateStage(i, 'error');
+        await this.emit(`step:${key}:progress`, 'error');
+        // emit step error
+        await this.emitStepError({
+          stepIndex: i,
+          stepKey: key,
+          status: 'error',
+          error: apiError,
+          stageResults: { ...this.stageResults },
+        });
         success = false;
         break;
       }
     }
 
-    return { results, errors, success };
+    return { stageResults: { ...this.stageResults }, success };
   }
 }

package/src/progress-tracker.ts

@@ -15,6 +15,14 @@ export class ProgressTracker {
     };
   }
 
+  /**
+   * Возвращает текущий снимок состояния прогресса (не реактивный).
+   * Для отслеживания изменений используйте subscribeProgress.
+   */
+  getProgressRef() {
+    return this.progress;
+  }
+
   updateStage(stage: number, status: PipelineProgress['stageStatuses'][number]) {
     this.progress.stageStatuses[stage] = status;
     this.progress.currentStage = stage;

package/src/types.ts

@@ -72,33 +72,81 @@ export type RestRequestConfig = import('axios').AxiosRequestConfig & {
   skipRateLimit?: boolean;
   requestId?: string;
 };
-// Типы для конвейерной системы REST API
 
-export type PipelineStageConfig<Input, Output> = {
+/**
+ * Конфиг одного шага (этапа) pipeline
+ * @template Input Тип входных данных шага
+ * @template Output Тип результата шага
+ */
+export type PipelineStageConfig<Input = any, Output = any> = {
+  /** Уникальный ключ шага */
   key: string;
-  request: (input: Input, allResults?: any) => Promise<Output>;
+  /** Асинхронная функция-запрос шага */
+  request: (input: Input, allResults?: Record<string, PipelineStepResult>) => Promise<Output>;
+  /** Условие выполнения шага */
   condition?: (
     input: Input,
-    prevResults: any,
+    prevResults: Record<string, PipelineStepResult>,
     sharedData?: Record<string, any>,
   ) => boolean;
+  /** Количество попыток при ошибке */
   retryCount?: number;
+  /** Таймаут шага (мс) */
   timeoutMs?: number;
+  /** Обработчик ошибок шага */
   errorHandler?: (error: any, stageKey: string, sharedData?: Record<string, any>) => any;
 };
 
+
+/**
+ * Статус выполнения шага pipeline
+ */
+export type PipelineStepStatus = 'pending' | 'loading' | 'success' | 'error' | 'skipped';
+
+
+/**
+ * Результат выполнения шага pipeline
+ */
+export type PipelineStepResult = {
+  /** Статус шага */
+  status: PipelineStepStatus;
+  /** Данные результата (если успех) */
+  data?: any;
+  /** Ошибка (если error) */
+  error?: import('./types').ApiError;
+};
+
+
+/**
+ * Конфиг всего pipeline (массив этапов)
+ */
 export type PipelineConfig = {
-  stages: PipelineStageConfig<any, any>[];
+  stages: PipelineStageConfig[];
 };
 
+
+/**
+ * Прогресс выполнения pipeline
+ */
 export type PipelineProgress = {
   currentStage: number;
   totalStages: number;
-  stageStatuses: Array<'pending' | 'in-progress' | 'success' | 'error' | 'skipped'>;
+  stageStatuses: Array<PipelineStepStatus>;
 };
 
+
+/**
+ * Результаты всех шагов pipeline (ключ — имя шага)
+ */
+export type PipelineStageResults = Record<string, PipelineStepResult>;
+
+
+/**
+ * Итоговый результат выполнения pipeline
+ */
 export type PipelineResult = {
-  results: any[];
-  errors: any[];
+  /** Результаты по шагам */
+  stageResults: PipelineStageResults;
+  /** true, если pipeline завершился успешно */
   success: boolean;
 };

package/vue/usePipelineStepEvents.ts

@@ -0,0 +1,40 @@
+import { ref, onUnmounted } from 'vue';
+import type { PipelineOrchestrator } from '../src/pipeline-orchestrator';
+
+/**
+ * Vue composition function for subscribing to step events (success/error/progress) for a specific step
+ * @param orchestrator PipelineOrchestrator instance
+ * @param stepKey string — step key
+ * @param eventType 'success' | 'error' | 'progress'
+ * @returns Ref<any> — last event payload
+ */
+export function usePipelineStepEvent(orchestrator: PipelineOrchestrator, stepKey: string, eventType: 'success' | 'error' | 'progress') {
+  const event = ref<any>(null);
+  const eventName = `step:${stepKey}:${eventType}`;
+  const handler = (payload: any) => { event.value = payload; };
+  const unsubscribe = orchestrator.on(eventName, handler);
+  onUnmounted(() => unsubscribe && unsubscribe());
+  return event;
+}
+
+/**
+ * Vue composition function for subscribing to pipeline logs
+ * @param orchestrator PipelineOrchestrator instance
+ * @returns Ref<log[]>
+ */
+export function usePipelineLogs(orchestrator: PipelineOrchestrator) {
+  const logs = ref(orchestrator.getLogs());
+  const handler = () => { logs.value = orchestrator.getLogs(); };
+  const unsubscribe = orchestrator.on('log', handler);
+  onUnmounted(() => unsubscribe && unsubscribe());
+  return logs;
+}
+
+/**
+ * Vue composition function for rerunning a pipeline step
+ * @param orchestrator PipelineOrchestrator instance
+ * @returns rerunStep function
+ */
+export function useRerunPipelineStep(orchestrator: PipelineOrchestrator) {
+  return orchestrator.rerunStep.bind(orchestrator);
+}