rest-pipeline-js 1.0.0

package/README.md

@@ -0,0 +1,259 @@
+
+# pipeline-js
+
+Модуль для работы с REST API, пайплайнами запросов и отслеживанием прогресса. Не зависит от Vue/React, но легко интегрируется в любые проекты.
+
+
+## Установка
+
+### Через NPM (после публикации)
+```
+npm install pipeline-js
+```
+
+### Из GitHub (актуально сейчас)
+```
+npm install git+https://github.com/macrulezru/pipeline-js.git
+```
+
+## Быстрый старт (чистый JS)
+
+```js
+const { createRestClient, PipelineOrchestrator } = require('pipeline-js');
+
+// Создание REST клиента
+const client = createRestClient({ baseURL: 'https://api.example.com' });
+client.get('/endpoint').then(response => {
+  console.log(response.data);
+});
+
+// Пример пайплайна
+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);
+});
+
+// Получить текущий прогресс (snapshot)
+console.log(pipeline.getProgress());
+```
+
+
+
+## React: хуки для интеграции
+
+### 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-функции для интеграции
+
+### usePipelineProgress
+```js
+import { usePipelineProgress } from 'pipeline-js/vue';
+import { PipelineOrchestrator } from 'pipeline-js';
+
+const pipeline = new PipelineOrchestrator({ stages: [...] }, { baseURL: '...' });
+const progress = usePipelineProgress(pipeline);
+```
+
+### usePipelineRun
+```js
+import { usePipelineRun } from 'pipeline-js/vue';
+const { run, running, result, error } = usePipelineRun(pipeline);
+```
+
+### useRestClient
+```js
+import { useRestClient } from 'pipeline-js/vue';
+const api = useRestClient({ baseURL: '...' });
+```
+
+## Использование в Vue 3
+
+```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;
+});
+onUnmounted(unsubscribe);
+```
+
+## Основные 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;
+  }
+}
+```
+
+## API
+
+### Конструктор
+
+```javascript
+new Pipeline(config)
+```
+
+**Параметры:**
+- `config` (Object) - Объект конфигурации
+  - `baseURL` (String) - Базовый URL для всех запросов
+  - `timeout` (Number) - Таймаут запроса в миллисекундах
+  - `headers` (Object) - Заголовки по умолчанию
+
+### Методы
+
+#### `get(url, config)`
+Выполняет GET запрос.
+
+#### `post(url, data, config)`
+Выполняет POST запрос.
+
+#### `put(url, data, config)`
+Выполняет PUT запрос.
+
+#### `delete(url, config)`
+Выполняет DELETE запрос.
+
+#### `patch(url, data, config)`
+Выполняет PATCH запрос.
+
+## Особенности
+
+- ✅ Поддержка Promise и async/await
+- ✅ Автоматическая обработка JSON
+- ✅ Настраиваемые заголовки
+- ✅ Обработка ошибок
+- ✅ Поддержка таймаутов
+- ✅ Легковесная библиотека без лишних зависимостей
+
+## Требования
+
+- Node.js >= 12.0.0
+- Современный браузер с поддержкой ES6
+
+## Разработка
+
+```bash
+# Клонировать репозиторий
+git clone https://github.com/macrulezru/pipeline-js.git
+
+# Установить зависимости
+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/)
+
+## Поддержка
+
+Если у вас возникли вопросы или проблемы, пожалуйста, создайте [issue](https://github.com/macrulezru/pipeline-js/issues) в репозитории.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "rest-pipeline-js",
+  "version": "1.0.0",
+  "description": "JS функционал для работы с REST API запросами.",
+  "main": "src/rest-client.js",
+  "types": "src/types.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "echo \"No tests specified\" && exit 0"
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "keywords": [
+    "rest",
+    "api",
+    "client",
+    "pipeline"
+  ],
+  "author": "macrulez",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/macrulezru/pipeline-js"
+  },
+  "homepage": "https://github.com/macrulezru/pipeline-js#readme",
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "axios": "^1.13.2"
+  }
+}

package/react/index.ts

@@ -0,0 +1,3 @@
+export * from './usePipelineProgress';
+export * from './usePipelineRun';
+export * from './useRestClient';

package/react/usePipelineProgress.ts

@@ -0,0 +1,19 @@
+import { useEffect, useState } from 'react';
+import type { PipelineOrchestrator } from '../src/pipeline-orchestrator';
+import type { PipelineProgress } from '../src/types';
+
+/**
+ * React hook for subscribing to pipeline progress
+ * @param orchestrator PipelineOrchestrator instance
+ * @returns PipelineProgress (reactive)
+ */
+export function usePipelineProgress(orchestrator: PipelineOrchestrator) {
+  const [progress, setProgress] = useState<PipelineProgress>(orchestrator.getProgress());
+
+  useEffect(() => {
+    const unsubscribe = orchestrator.subscribeProgress(setProgress);
+    return () => unsubscribe();
+  }, [orchestrator]);
+
+  return progress;
+}

package/react/usePipelineRun.ts

@@ -0,0 +1,33 @@
+import { useCallback, useState } from 'react';
+import type { PipelineOrchestrator } from '../src/pipeline-orchestrator';
+import type { PipelineResult } from '../src/types';
+
+/**
+ * React hook to run pipeline and track status/result
+ * @param orchestrator PipelineOrchestrator instance
+ * @returns [run, { running, result, error }]
+ */
+export function usePipelineRun(orchestrator: PipelineOrchestrator) {
+  const [running, setRunning] = useState(false);
+  const [result, setResult] = useState<PipelineResult | null>(null);
+  const [error, setError] = useState<any>(null);
+
+  const run = useCallback(async (...args: any[]) => {
+    setRunning(true);
+    setError(null);
+    setResult(null);
+    try {
+      // Предполагается, что у orchestrator есть метод run
+      const res = await (orchestrator as any).run(...args);
+      setResult(res);
+      return res;
+    } catch (e) {
+      setError(e);
+      throw e;
+    } finally {
+      setRunning(false);
+    }
+  }, [orchestrator]);
+
+  return [run, { running, result, error }] as const;
+}

package/react/useRestClient.ts

@@ -0,0 +1,12 @@
+import { useMemo } from 'react';
+import { createRestClient } from '../src/rest-client';
+import type { HttpConfig } from '../src/types';
+
+/**
+ * React hook for memoized REST client
+ * @param config HttpConfig
+ * @returns RestClient instance
+ */
+export function useRestClient(config: HttpConfig) {
+  return useMemo(() => createRestClient(config), [JSON.stringify(config)]);
+}

package/src/README.md

@@ -0,0 +1,271 @@
+# Pipeline Framework (src/core/pipeline)
+
+## Описание
+
+Механизм pipeline — это универсальная, расширяемая и типобезопасная система для построения цепочек асинхронных операций (пайплайнов) с поддержкой сложных сценариев обработки данных, HTTP-запросов, прогресса, ошибок и метрик.
+
+Pipeline позволяет описывать последовательность этапов (stages), каждый из которых может выполнять запрос к API, обработку данных, валидацию, агрегацию и т.д. Каждый этап может зависеть от результатов предыдущих, иметь собственные условия выполнения, обработчики ошибок и параметры таймаута/повторов.
+
+## Основные компоненты
+
+- **PipelineOrchestrator** — основной исполнитель пайплайна. Управляет прогрессом, выполняет этапы, обрабатывает ошибки, поддерживает реактивность.
+- **PipelineConfig** — декларативное описание этапов пайплайна (массив stages с ключами, функциями-запросами, условиями, retry, timeout и т.д.).
+- **RequestExecutor** — унифицированный HTTP-клиент с поддержкой retry, таймаутов, метрик, кэширования, rate-limit и отмены запросов.
+- **ProgressTracker** — реактивный трекер прогресса выполнения пайплайна.
+- **ErrorHandler** — централизованная обработка ошибок этапов.
+- **Типы (types.ts)** — строгая типизация всех этапов, конфигов, результатов, ошибок и прогресса.
+- **rest-client.ts** — низкоуровневый HTTP-клиент с интеграцией метрик, кэша, rate-limit и отмены.
+
+## Принципы работы
+
+1. **Декларативность**: pipeline описывается как массив этапов с ключами, функциями-запросами и условиями.
+2. **Гибкость**: каждый этап может быть асинхронным, иметь свои retry, timeout, обработчик ошибок, условие выполнения.
+3. **Реактивность**: прогресс пайплайна и результаты доступны как реактивные ссылки (ref/computed).
+4. **Единый HTTP-стек**: все запросы проходят через RequestExecutor/rest-client, что обеспечивает метрики, кэш, rate-limit, отмену, обработку ошибок и единый стиль логирования.
+5. **Типобезопасность**: строгая типизация входов/выходов этапов, результатов, ошибок.
+6. **Интеграция с метриками**: все запросы автоматически логируются в metricsBus и доступны для UI/отладки.
+
+## Преимущества pipeline-механизма
+
+- **Единая точка управления логикой и запросами**: все сценарии (от простых до сложных) реализуются через один механизм.
+- **Минимум дублирования**: повторное использование этапов, обработчиков, конфигов.
+- **Простота тестирования**: каждый этап — чистая функция, легко мокается и тестируется.
+- **Гибкая обработка ошибок**: можно задать обработчик на каждый этап или глобально.
+- **Реактивный прогресс**: удобно для UI (progress bar, stepper, отмена, повтор).
+- **Автоматические метрики**: прозрачный сбор статистики по всем запросам и этапам.
+- **Лёгкая интеграция с Vue/Pinia**: pipeline легко встраивается в компоненты и сторы.
+- **Расширяемость**: можно добавлять новые типы этапов, плагины, обработчики, интеграции.
+- **Безопасность и контроль**: строгая типизация, централизованный контроль ошибок и состояния.
+
+## Пример использования
+
+```ts
+import { PipelineOrchestrator } from './pipeline-orchestrator';
+import { RequestExecutor } from './request-executor';
+import type { PipelineConfig } from './types';
+
+const httpConfig = { ... };
+const executor = new RequestExecutor(httpConfig);
+
+const pipelineConfig: PipelineConfig = {
+  stages: [
+    {
+      key: 'step1',
+      request: async () => await executor.execute('endpoint1'),
+      retryCount: 2,
+      timeoutMs: 10000,
+    },
+    {
+      key: 'step2',
+      request: async (prev) => await executor.execute(`endpoint2/${prev.id}`),
+      condition: prev => !!prev,
+    },
+    // ...
+  ],
+};
+
+const orchestrator = new PipelineOrchestrator(pipelineConfig, httpConfig);
+const progress = orchestrator.getProgressRef();
+const result = await orchestrator.run();
+```
+
+## Рекомендации по использованию
+
+- Используйте pipeline для любых цепочек запросов, где важна последовательность, прогресс, обработка ошибок, метрики.
+- Для одиночных запросов используйте RequestExecutor напрямую — это даст метрики и унификацию.
+- Все новые сценарии API/логики реализуйте через pipeline для единообразия и прозрачности.
+
+---
+
+**Pipeline — это современный, масштабируемый и прозрачный способ построения сложных сценариев работы с API и асинхронными процессами.**
+
+# Pipeline (Конвейерная система) для REST API
+
+Модуль для построения декларативных и динамических цепочек HTTP-запросов с передачей данных между этапами, обработкой ошибок, условиями, пользовательскими паузами и полной типобезопасностью.
+
+---
+
+## Архитектура и назначение
+
+- **PipelineOrchestrator** — управляет последовательностью этапов, передачей данных, прогрессом и ошибками.
+- **PipelineConfig** — декларативное описание этапов (шагов) pipeline.
+- **PipelineStageConfig** — описание отдельного шага: request, key, condition, retry, timeout, errorHandler.
+- **RequestExecutor** — универсальный исполнитель HTTP-запросов (используется, если не задан кастомный request).
+- **ProgressTracker** — отслеживает статус каждого этапа.
+- **ErrorHandler** — глобальная и локальная обработка ошибок.
+
+---
+
+## Основные возможности
+
+- Последовательное выполнение шагов с передачей результата между ними
+- Кастомные request-функции для любого шага (можно реализовать любую логику)
+- Автоматическая или условная передача данных между этапами
+- Условное выполнение этапов (condition)
+- Retry-логика и таймауты на каждом этапе
+- Локальная и глобальная обработка ошибок
+- Пользовательские паузы между шагами (onStepPause)
+- Типобезопасность (TS generics)
+- Использование sharedData для глобального состояния
+
+---
+
+## Пример: Динамический pipeline с передачей данных
+
+````ts
+import { PipelineOrchestrator } from './pipeline-orchestrator';
+import type { PipelineConfig } from './types';
+
+# Pipeline (src/core/pipeline)
+
+Механизм pipeline — это универсальная, расширяемая и типобезопасная система для построения цепочек асинхронных операций (пайплайнов) с поддержкой сложных сценариев обработки данных, HTTP-запросов, прогресса, ошибок и метрик.
+
+---
+
+## Архитектура и ключевые компоненты
+
+- **PipelineOrchestrator** — управляет последовательностью этапов, передачей данных, прогрессом и ошибками.
+- **PipelineConfig** — декларативное описание этапов (шагов) pipeline.
+- **PipelineStageConfig** — описание отдельного шага: request, key, condition, retry, timeout, errorHandler.
+- **RequestExecutor** — универсальный исполнитель HTTP-запросов (используется, если не задан кастомный request).
+- **ProgressTracker** — отслеживает статус каждого этапа, реактивный прогресс для UI.
+- **ErrorHandler** — глобальная и локальная обработка ошибок.
+- **Типы (types.ts)** — строгая типизация всех этапов, конфигов, результатов, ошибок и прогресса.
+- **rest-client.ts** — низкоуровневый HTTP-клиент с интеграцией метрик, кэша, rate-limit и отмены.
+
+---
+
+## Преимущества pipeline-механизма
+
+- **Единая точка управления логикой и запросами**: все сценарии (от простых до сложных) реализуются через один механизм.
+- **Минимум дублирования**: повторное использование этапов, обработчиков, конфигов.
+- **Простота тестирования**: каждый этап — чистая функция, легко мокается и тестируется.
+- **Гибкая обработка ошибок**: можно задать обработчик на каждый этап или глобально.
+- **Реактивный прогресс**: удобно для UI (progress bar, stepper, отмена, повтор).
+- **Автоматические метрики**: прозрачный сбор статистики по всем запросам и этапам.
+- **Лёгкая интеграция с Vue/Pinia**: pipeline легко встраивается в компоненты и сторы.
+- **Расширяемость**: можно добавлять новые типы этапов, плагины, обработчики, интеграции.
+- **Безопасность и контроль**: строгая типизация, централизованный контроль ошибок и состояния.
+
+---
+
+## Основные возможности
+
+- Последовательное выполнение шагов с передачей результата между ними
+- Кастомные request-функции для любого шага (можно реализовать любую логику)
+- Автоматическая или условная передача данных между этапами
+- Условное выполнение этапов (condition)
+- Retry-логика и таймауты на каждом этапе
+- Локальная и глобальная обработка ошибок
+- Пользовательские паузы между шагами (onStepPause)
+- Типобезопасность (TS generics)
+- Использование sharedData для глобального состояния
+
+---
+
+## Пример: Динамический pipeline с передачей данных
+
+```ts
+import { PipelineOrchestrator } from './pipeline-orchestrator';
+import type { PipelineConfig } from './types';
+
+const httpConfig = {
+  baseURL: 'https://api.macrulez.ru/v1/fly',
+  timeout: 10000,
+  headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+};
+
+const pipelineConfig: PipelineConfig = {
+  stages: [
+    {
+      // Первый шаг: получить список точек
+      request: async () => {
+        const resp = await fetch(`${httpConfig.baseURL}/points`, {
+          headers: httpConfig.headers,
+        });
+        const data = await resp.json();
+        const { points } = data;
+        if (!Array.isArray(points) || points.length === 0) return null;
+        const cityObj = points[Math.floor(Math.random() * points.length)];
+        const from = cityObj.point_code;
+        const departures = cityObj.departure_to?.split(',').filter(Boolean);
+        if (!departures || departures.length === 0) return null;
+        const to = departures[Math.floor(Math.random() * departures.length)];
+        return { points, from, to };
+      },
+    },
+    {
+      // Второй шаг: получить availability по from/to из первого шага
+      request: async prev => {
+        if (!prev?.from || !prev?.to) return null;
+        const url = `${httpConfig.baseURL}/availability/${prev.from}/${prev.to}`;
+        const resp = await fetch(url, { headers: httpConfig.headers });
+        return await resp.json();
+      },
+      condition: prev => !!prev?.from && !!prev?.to,
+    },
+  ],
+};
+
+const orchestrator = new PipelineOrchestrator(pipelineConfig, httpConfig);
+orchestrator.run().then(result => {
+  console.log('Результаты:', result.results);
+});
+````
+
+---
+
+## Описание этапа (PipelineStageConfig)
+
+- `request: (prevResult) => Promise<result>` — основная функция шага. Получает результат предыдущего шага.
+- `key: string` — (опционально) идентификатор/маршрут для универсального executor (если не используется кастомный request).
+- `condition: (prev, all, shared) => boolean` — (опционально) условие выполнения шага.
+- `retryCount: number` — (опционально) количество повторов при ошибке.
+- `timeoutMs: number` — (опционально) таймаут шага.
+- `errorHandler: (err, key, shared) => any` — (опционально) локальная обработка ошибок.
+
+---
+
+## Как работает orchestrator
+
+1. Идёт по всем stages по порядку.
+2. Для каждого шага:
+   - Если есть condition и оно false — шаг пропускается.
+   - Если есть кастомный request — вызывается он (и получает результат предыдущего шага).
+   - Если request не задан, но есть key — используется универсальный executor (rest-клиент).
+   - Результат шага передаётся в следующий шаг.
+   - Ошибки обрабатываются локально (errorHandler) или глобально.
+   - Если задан onStepPause — выполнение приостанавливается для пользовательского подтверждения/редактирования результата.
+3. После завершения возвращает { results, errors, success }.
+
+---
+
+## Best practices
+
+- Для динамических шагов всегда используйте кастомный request.
+- key нужен только для универсального executor или для идентификации шага.
+- Для сложных сценариев используйте sharedData для глобального состояния.
+- Всегда обрабатывайте ошибки либо локально (errorHandler), либо глобально.
+- Для UI-интеграции используйте ProgressTracker.
+
+---
+
+## Визуализация прогресса
+
+```ts
+const progress = orchestrator.progress.getProgress();
+// progress.currentStage, progress.stageStatuses
+```
+
+---
+
+## Зависимости
+
+- Использует rest-client.ts для HTTP-запросов (axios)
+- Не требует сторонних библиотек
+
+---
+
+**Pipeline — современный, масштабируемый и прозрачный способ построения сложных сценариев работы с API и асинхронными процессами.**
+
+**Вопросы и доработки:** Для интеграции с UI или расширения логики — обращайтесь к разработчику модуля.

package/src/error-handler.ts

@@ -0,0 +1,6 @@
+export class ErrorHandler {
+  handle(error: any, stageKey: string) {
+    // TODO: реализовать классификацию и обработку ошибок
+    return { type: 'unknown', error, stageKey };
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+// Barrel file for pipeline-js module
+export * from './rest-client';
+export * from './types';
+export * from './request-executor';
+export * from './error-handler';
+export * from './progress-tracker';
+export * from './pipeline-orchestrator';

package/src/pipeline-orchestrator.ts

@@ -0,0 +1,122 @@
+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';
+
+export class PipelineOrchestrator {
+  private progress: ProgressTracker;
+  private errorHandler: ErrorHandler;
+  private executor: RequestExecutor;
+  private sharedData: Record<string, unknown>;
+
+  constructor(
+    private config: PipelineConfig,
+    httpConfig: import('./types').HttpConfig,
+    sharedData: Record<string, unknown> = {},
+  ) {
+    this.progress = new ProgressTracker(config.stages.length);
+    this.errorHandler = new ErrorHandler();
+    this.executor = new RequestExecutor(httpConfig);
+    this.sharedData = sharedData;
+  }
+
+  /**
+   * Подписаться на изменения прогресса выполнения pipeline
+   * @param listener функция-обработчик изменений
+   * @returns функция для отписки
+   */
+  subscribeProgress(listener: (progress: import('./types').PipelineProgress) => void) {
+    return this.progress.subscribe(listener);
+  }
+
+  /**
+   * Получить текущий прогресс выполнения pipeline (snapshot, не реактивный)
+   */
+  getProgress() {
+    return this.progress.getProgress();
+  }
+
+  /**
+   * @param onStepPause
+   *   Необязательный callback, вызывается после каждого шага (до перехода к следующему).
+   *   Позволяет приостановить выполнение, запросить подтверждение пользователя или изменить результат шага.
+   *   Должен вернуть (optionally изменённый) результат шага или промис с ним.
+   *   Если не передан — пайплайн работает как раньше.
+   */
+  async run(
+    onStepPause?: (
+      stepIndex: number,
+      stepResult: unknown,
+      results: unknown[],
+    ) => Promise<unknown> | unknown,
+  ): Promise<PipelineResult> {
+    const results: unknown[] = [];
+    const errors: unknown[] = [];
+    let success = true;
+
+    for (let i = 0; i < this.config.stages.length; i++) {
+      const stage = this.config.stages[i];
+      this.progress.updateStage(i, 'in-progress');
+
+      if (!stage) {
+        this.progress.updateStage(i, 'skipped');
+        results.push(undefined);
+        continue;
+      }
+
+      // Проверка условия выполнения этапа
+      if (stage.condition && !stage.condition(results[i - 1], results, this.sharedData)) {
+        this.progress.updateStage(i, 'skipped');
+        results.push(undefined);
+        continue;
+      }
+      try {
+        let stepResult: unknown;
+        // Всегда передаём (prev, allResults) в request — best practice для pipeline
+        if (typeof stage.request === 'function') {
+          stepResult = await stage.request(results[i - 1], results);
+        } else if (stage.key) {
+          const res = await this.executor.execute(
+            stage.key,
+            undefined,
+            stage.retryCount,
+            stage.timeoutMs,
+          );
+          stepResult = res.data;
+        } else {
+          stepResult = undefined;
+        }
+
+        // --- Пользовательская пауза/подтверждение/изменение результата ---
+        if (onStepPause) {
+          stepResult = await onStepPause(i, stepResult, results);
+        }
+        results.push(stepResult);
+        this.progress.updateStage(i, 'success');
+
+        // ...existing code...
+      } 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);
+        }
+        errors.push(handled);
+        this.progress.updateStage(i, 'error');
+        success = false;
+        break;
+      }
+    }
+
+    return { results, errors, success };
+  }
+}

package/src/progress-tracker.ts

@@ -0,0 +1,42 @@
+
+import type { PipelineProgress } from './types';
+
+type ProgressListener = (progress: PipelineProgress) => void;
+
+export class ProgressTracker {
+  private progress: PipelineProgress;
+  private listeners: ProgressListener[] = [];
+
+  constructor(totalStages: number) {
+    this.progress = {
+      currentStage: 0,
+      totalStages,
+      stageStatuses: Array(totalStages).fill('pending'),
+    };
+  }
+
+  updateStage(stage: number, status: PipelineProgress['stageStatuses'][number]) {
+    this.progress.stageStatuses[stage] = status;
+    this.progress.currentStage = stage;
+    this.notify();
+  }
+
+  getProgress() {
+    return { ...this.progress };
+  }
+
+  subscribe(listener: ProgressListener) {
+    this.listeners.push(listener);
+    // Немедленно уведомляем нового подписчика о текущем состоянии
+    listener({ ...this.progress });
+    return () => {
+      this.listeners = this.listeners.filter(l => l !== listener);
+    };
+  }
+
+  private notify() {
+    for (const listener of this.listeners) {
+      listener({ ...this.progress });
+    }
+  }
+}

package/src/request-executor.ts

@@ -0,0 +1,40 @@
+import { getRestClient } from './rest-client';
+
+import type { RestRequestConfig, HttpConfig, ApiResponse } from './types';
+
+export class RequestExecutor {
+  private client;
+
+  constructor(httpConfig: HttpConfig) {
+    this.client = getRestClient(httpConfig);
+  }
+
+  /**
+   * Выполнение одного запроса с поддержкой retry и таймаута
+   */
+  async execute<T = any>(
+    command: string,
+    reqConfig?: RestRequestConfig,
+    retryCount = 0,
+    timeoutMs = 10000,
+  ): Promise<ApiResponse<T>> {
+    let attempt = 0;
+    let lastError: any = null;
+    while (attempt <= retryCount) {
+      try {
+        const result = await Promise.race([
+          this.client.request<T>(command, reqConfig),
+          new Promise((_, reject) =>
+            setTimeout(() => reject(new Error('Timeout')), timeoutMs),
+          ),
+        ]);
+        return result as ApiResponse<T>;
+      } catch (err) {
+        lastError = err;
+        attempt++;
+        if (attempt > retryCount) throw lastError;
+      }
+    }
+    throw lastError;
+  }
+}

package/src/rest-client.ts

@@ -0,0 +1,178 @@
+import axios from 'axios';
+
+import type { HttpConfig, ApiError, ApiResponse, RestRequestConfig } from './types';
+import type { AxiosInstance, AxiosResponse } from 'axios';
+
+type RestClient = ReturnType<typeof createRestClient>;
+
+export function toApiError(error: unknown): ApiError {
+  if (axios.isCancel(error)) {
+    return {
+      message: 'Запрос был отменен',
+      code: 'REQUEST_CANCELLED',
+    };
+  }
+  if (axios.isAxiosError(error)) {
+    const axiosError = error;
+    return {
+      message: axiosError.message,
+      code: axiosError.code,
+      status: axiosError.response?.status,
+      timestamp: new Date(),
+    };
+  }
+  if (error instanceof Error) {
+    return {
+      message: error.message,
+      timestamp: new Date(),
+    };
+  }
+  return {
+    message: 'Произошла неизвестная ошибка',
+    timestamp: new Date(),
+  };
+}
+
+const restClientCache: Map<string, RestClient> = new Map();
+
+export function createRestClient(config: HttpConfig) {
+  const httpClient: AxiosInstance = axios.create({
+    baseURL: config.baseURL,
+    timeout: config.timeout,
+    headers: config.headers,
+    withCredentials: config.withCredentials,
+  });
+  // ...реализация rate limit, cache, interceptors, request, etc. (скопировать из rest.ts при необходимости)
+  // Для краткости: реализуйте полный функционал по мере необходимости.
+  async function request<T = unknown>(
+    command: string,
+    req?: RestRequestConfig,
+  ): Promise<ApiResponse<T>> {
+    const reqId = req?.requestId ?? Math.random().toString(36).slice(2);
+    const methodUpper = (req?.method ?? 'GET').toUpperCase();
+    const fullUrl = `${config.baseURL}${command}`;
+    config.metrics?.onRequestStart?.({
+      id: reqId,
+      method: methodUpper,
+      url: fullUrl,
+      timestamp: Date.now(),
+      requestBody: req?.data,
+      requestParams: req?.params,
+      requestHeaders: req?.headers as Record<string, string>,
+    });
+    const startTs = Date.now();
+    try {
+      const response: AxiosResponse<T> = await httpClient.request<T>({
+        url: command,
+        ...req,
+      });
+      const payload: ApiResponse<T> = {
+        data: response.data,
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers as Record<string, string>,
+      };
+      const duration = Date.now() - startTs;
+      // --- вычисление размера ответа ---
+      let responseBytes: number | undefined = undefined;
+      const headers = response.headers as Record<string, string>;
+      const contentLengthHeader =
+        headers['content-length'] || headers['Content-Length'] || undefined;
+      const parsedLength = contentLengthHeader ? Number(contentLengthHeader) : undefined;
+      if (Number.isFinite(parsedLength) && parsedLength !== 0) {
+        responseBytes = parsedLength;
+      } else {
+        try {
+          const raw = response.data;
+          if (typeof raw === 'string') {
+            responseBytes = new TextEncoder().encode(raw).length;
+          } else if (raw !== undefined) {
+            const str = JSON.stringify(raw);
+            responseBytes = new TextEncoder().encode(str).length;
+          }
+        } catch {
+          // ignore sizing errors
+        }
+      }
+      config.metrics?.onRequestEnd?.({
+        id: reqId,
+        durationMs: duration,
+        status: response.status,
+        bytes: responseBytes,
+        responseBody: response.data,
+        responseHeaders: response.headers as Record<string, string>,
+      });
+      return payload;
+    } catch (error) {
+      const duration = Date.now() - startTs;
+      config.metrics?.onRequestEnd?.({
+        id: reqId,
+        durationMs: duration,
+        error: toApiError(error),
+      });
+      throw error;
+    }
+  }
+  // --- Реализация cancellableRequest ---
+  const cancelTokenSources: Map<string, any> = new Map();
+  function cancelRequest(key: string): void {
+    const source = cancelTokenSources.get(key);
+    if (source) {
+      source.cancel(`Запрос отменен по ключу: ${key}`);
+      cancelTokenSources.delete(key);
+    }
+  }
+  async function cancellableRequest<T = unknown>(
+    key: string,
+    command: string,
+    config?: any,
+  ): Promise<ApiResponse<T>> {
+    cancelRequest(key);
+    const axios = await import('axios');
+    const source = axios.default.CancelToken.source();
+    cancelTokenSources.set(key, source);
+    try {
+      return await request<T>(command, {
+        ...config,
+        cancelToken: source.token,
+      });
+    } finally {
+      cancelTokenSources.delete(key);
+    }
+  }
+  return {
+    request,
+    get: <T = unknown>(command: string, config?: Omit<RestRequestConfig, 'method'>) =>
+      request<T>(command, { ...config, method: 'GET' }),
+    post: <T = unknown>(
+      command: string,
+      data?: unknown,
+      config?: Omit<RestRequestConfig, 'method' | 'data'>,
+    ) => request<T>(command, { ...config, method: 'POST', data }),
+    put: <T = unknown>(
+      command: string,
+      data?: unknown,
+      config?: Omit<RestRequestConfig, 'method' | 'data'>,
+    ) => request<T>(command, { ...config, method: 'PUT', data }),
+    delete: <T = unknown>(command: string, config?: Omit<RestRequestConfig, 'method'>) =>
+      request<T>(command, { ...config, method: 'DELETE' }),
+    cancellableRequest,
+    cancelRequest,
+  };
+}
+
+export function getRestClient(config: HttpConfig): RestClient {
+  const key = JSON.stringify({
+    baseURL: config.baseURL,
+    timeout: config.timeout,
+    withCredentials: config.withCredentials,
+    headers: config.headers ?? {},
+    retry: config.retry ?? {},
+    metrics: !!config.metrics,
+  });
+  const cachedClient = restClientCache.get(key);
+  if (cachedClient) return cachedClient;
+  const client = createRestClient(config);
+  restClientCache.set(key, client);
+  return client;
+}

package/src/types.ts

@@ -0,0 +1,104 @@
+// --- Типы для HTTP и REST ---
+export interface RetryConfig {
+  attempts: number;
+  delayMs: number;
+  backoffMultiplier: number;
+  retriableStatus?: number[];
+}
+
+export type RetryOptions = Partial<RetryConfig>;
+
+export interface CacheConfig {
+  enabled: boolean;
+  ttlMs: number;
+}
+
+export interface RateLimitConfig {
+  maxConcurrent?: number;
+  maxRequestsPerInterval?: number;
+  intervalMs?: number;
+}
+
+export interface MetricsHandler {
+  onRequestStart?: (info: {
+    id: string;
+    method?: string;
+    url?: string;
+    timestamp: number;
+    requestBody?: unknown;
+    requestParams?: unknown;
+    requestHeaders?: Record<string, string>;
+  }) => void;
+  onRequestEnd?: (info: {
+    id: string;
+    durationMs: number;
+    status?: number;
+    error?: ApiError;
+    bytes?: number;
+    responseBody?: unknown;
+    responseHeaders?: Record<string, string>;
+  }) => void;
+}
+
+export interface HttpConfig {
+  baseURL: string;
+  timeout?: number;
+  headers?: Record<string, string>;
+  withCredentials?: boolean;
+  retry?: RetryOptions;
+  cache?: CacheConfig;
+  rateLimit?: RateLimitConfig;
+  metrics?: MetricsHandler;
+}
+
+export interface ApiError {
+  message: string;
+  code?: string | number;
+  status?: number;
+  timestamp?: Date;
+}
+
+export interface ApiResponse<T = unknown> {
+  data: T;
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+}
+
+export type RestRequestConfig = import('axios').AxiosRequestConfig & {
+  useCache?: boolean;
+  cacheTtlMs?: number;
+  cacheKey?: string;
+  skipRateLimit?: boolean;
+  requestId?: string;
+};
+// Типы для конвейерной системы REST API
+
+export type PipelineStageConfig<Input, Output> = {
+  key: string;
+  request: (input: Input, allResults?: any) => Promise<Output>;
+  condition?: (
+    input: Input,
+    prevResults: any,
+    sharedData?: Record<string, any>,
+  ) => boolean;
+  retryCount?: number;
+  timeoutMs?: number;
+  errorHandler?: (error: any, stageKey: string, sharedData?: Record<string, any>) => any;
+};
+
+export type PipelineConfig = {
+  stages: PipelineStageConfig<any, any>[];
+};
+
+export type PipelineProgress = {
+  currentStage: number;
+  totalStages: number;
+  stageStatuses: Array<'pending' | 'in-progress' | 'success' | 'error' | 'skipped'>;
+};
+
+export type PipelineResult = {
+  results: any[];
+  errors: any[];
+  success: boolean;
+};

package/tsconfig.json

@@ -0,0 +1,13 @@
+// TypeScript configuration for building the module
+{
+  "compilerOptions": {
+    "target": "ES2019",
+    "module": "commonjs",
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}

package/vue/index.ts

@@ -0,0 +1,3 @@
+export * from './usePipelineProgress';
+export * from './usePipelineRun';
+export * from './useRestClient';

package/vue/usePipelineProgress.ts

@@ -0,0 +1,17 @@
+import { ref, onUnmounted } from 'vue';
+import type { PipelineOrchestrator } from '../src/pipeline-orchestrator';
+import type { PipelineProgress } from '../src/types';
+
+/**
+ * Vue composition function for subscribing to pipeline progress
+ * @param orchestrator PipelineOrchestrator instance
+ * @returns Ref<PipelineProgress>
+ */
+export function usePipelineProgress(orchestrator: PipelineOrchestrator) {
+  const progress = ref<PipelineProgress>(orchestrator.getProgress());
+  const unsubscribe = orchestrator.subscribeProgress(p => {
+    progress.value = p;
+  });
+  onUnmounted(unsubscribe);
+  return progress;
+}

package/vue/usePipelineRun.ts

@@ -0,0 +1,33 @@
+import { ref } from 'vue';
+import type { PipelineOrchestrator } from '../src/pipeline-orchestrator';
+import type { PipelineResult } from '../src/types';
+
+/**
+ * Vue composition function to run pipeline and track status/result
+ * @param orchestrator PipelineOrchestrator instance
+ * @returns { run, running, result, error }
+ */
+export function usePipelineRun(orchestrator: PipelineOrchestrator) {
+  const running = ref(false);
+  const result = ref<PipelineResult | null>(null);
+  const error = ref<any>(null);
+
+  async function run(...args: any[]) {
+    running.value = true;
+    error.value = null;
+    result.value = null;
+    try {
+      // Предполагается, что у orchestrator есть метод run
+      const res = await (orchestrator as any).run(...args);
+      result.value = res;
+      return res;
+    } catch (e) {
+      error.value = e;
+      throw e;
+    } finally {
+      running.value = false;
+    }
+  }
+
+  return { run, running, result, error };
+}

package/vue/useRestClient.ts

@@ -0,0 +1,12 @@
+import { computed } from 'vue';
+import { createRestClient } from '../src/rest-client';
+import type { HttpConfig } from '../src/types';
+
+/**
+ * Vue composition function for memoized REST client
+ * @param config HttpConfig
+ * @returns RestClient instance
+ */
+export function useRestClient(config: HttpConfig) {
+  return computed(() => createRestClient(config));
+}