@coopenomics/parser 2026.2.21-alpha-4 → 2026.2.28-4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +94 -114
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -1,146 +1,126 @@
1
- # COOPARSER.
1
+ # 🔍 @coopenomics/parser
2
2
 
3
- [![npm version][npm-version-src]][npm-version-href]
4
- [![npm downloads][npm-downloads-src]][npm-downloads-href]
5
- [![bundle][bundle-src]][bundle-href]
6
- [![JSDocs][jsdocs-src]][jsdocs-href]
7
- [![License][license-src]][license-href]
3
+ Индексатор блокчейна EOSIO. Подключается к State History Plugin (SHiP) через WebSocket, в реальном времени парсит действия и дельты таблиц из блоков, сохраняет данные в MongoDB и публикует события в Redis Streams для дальнейшей обработки другими сервисами.
8
4
 
9
- Пакет производит распаковку блоков, сохраняя действия и дельты таблиц и выдавая их по API. Состоит из двух модулей: парсера и API. Парсер считывает данные из блокчейна и помещает их в базу. API получает данные по запросу и возвращает их с пагинацией.
5
+ ## Основные возможности
6
+
7
+ - Подключение к EOSIO State History Plugin по WebSocket
8
+ - Парсинг действий (actions) и дельт таблиц (table deltas) из блоков
9
+ - Сохранение индексированных данных в MongoDB
10
+ - Публикация событий в Redis Streams
11
+ - REST API для запросов с пагинацией и фильтрацией
12
+ - Обработка форков блокчейна
13
+ - Расширение кастомными обработчиками действий и дельт
14
+ - Конфигурируемые подписки на конкретные таблицы и контракты
10
15
 
11
16
  ## Установка
12
- ```
17
+
18
+ Компонент является частью монорепозитория. Установка зависимостей из корня проекта:
19
+
20
+ ```bash
13
21
  pnpm install
14
22
  ```
15
23
 
16
- ### Конфигурационный файл .env
24
+ Или только для этого компонента:
25
+
26
+ ```bash
27
+ pnpm install --filter @coopenomics/parser
17
28
  ```
18
- NODE_ENV=development
19
- - Определяет среду выполнения приложения.
20
29
 
21
- API=http://127.0.0.1:8888
22
- - Определяет URL-адрес API, к которому будет осуществляться доступ.
30
+ ## Скрипты
23
31
 
24
- SHIP=ws://127.0.0.1:8080
25
- - Определяет URL-адрес WebSocket-соединения, используемого для связи с другими узлами.
32
+ | Скрипт | Команда | Описание |
33
+ |--------|---------|----------|
34
+ | `dev` | `pnpm run dev` | Запуск в режиме разработки (nodemon) |
35
+ | `dev:test` | `pnpm run dev:test` | Режим разработки с NODE_ENV=test |
36
+ | `start` | `pnpm run start` | Запуск production (esno) |
37
+ | `build` | `pnpm run build` | Сборка библиотеки (unbuild) |
38
+ | `test` | `pnpm run test` | Запуск тестов (Vitest) |
39
+ | `lint` | `pnpm run lint` | Проверка кода (ESLint) |
40
+ | `typecheck` | `pnpm run typecheck` | Проверка типов TypeScript |
41
+ | `doc` | `pnpm run doc` | Генерация документации (TypeDoc) |
26
42
 
27
- MONGO_EXPLORER_URI=mongodb://127.0.0.1:27017/cooperative
28
- - Определяет URI-адрес MongoDB, используемый для подключения к базе данных.
43
+ Из корня монорепозитория:
29
44
 
30
- START_BLOCK=1
31
- - Определяет номер блока, с которого начинается парсинг блокчейна.
45
+ ```bash
46
+ pnpm run dev:backend # Запуск parser + controller в режиме разработки
47
+ ```
32
48
 
33
- FINISH_BLOCK=0xFFFFFFFF
34
- - Определяет номер блока, на котором заканчивается парсинг блокчейна. В данном случае, установлено значение "0xFFFFFFFF", что означает, что парсинг будет продолжаться до последнего доступного блока.
49
+ ## Конфигурация
35
50
 
36
- PORT=4000
37
- - Определяет порт, на котором будет запущен сервер приложения.
51
+ Скопируйте `.env-example` в `.env` и настройте переменные окружения:
38
52
 
39
- ACTIVATE_PARSER=0
40
- - Определяет флаг активации парсера. Если значение равно "1", парсер будет активирован.
41
- ```
53
+ - `API` — URL блокчейн-ноды
54
+ - `SHIP` — WebSocket URL State History Plugin
55
+ - `MONGO_EXPLORER_URI` — строка подключения к MongoDB
56
+ - `REDIS_HOST` / `REDIS_PORT` — подключение к Redis
57
+ - `START_BLOCK` — номер блока для начала индексации
58
+ - `PORT` — порт REST API
59
+ - `ACTIVATE_PARSER` — флаг активации парсера (`0` / `1`)
42
60
 
43
- ### Конфигурация парсера
44
- В конфиге src/config.ts находится массив таблиц и действий, на которые парсер осуществит подписку.
61
+ Подробное описание переменных — в файле `.env-example`.
45
62
 
46
- ```
47
- export const subsribedTables = [
48
- { code: 'registrator', table: 'users', 'scope': 'registrator' },
49
- { code: 'soviet', table: 'participants' },
50
- ]
51
- ```
52
- - подписка будет осуществлена на изменения таблиц указанных контрактов. Параметр scope - не обязательный. Без его указания любые scope будут попадать в базу данных.
63
+ ## Тестирование
53
64
 
65
+ ```bash
66
+ pnpm --filter @coopenomics/parser run test
54
67
  ```
55
- export const subsribedActions = [
56
- { code: 'soviet', action: 'votefor' },
57
- { code: 'soviet', action: 'voteagainst' },
58
- ]
59
- ```
60
- - подписка будет осуществлена на действия указанных контрактов.
61
68
 
62
- Парсер может быть расширен любыми кастомными действиями, которые будут выполняться перед добавлением записи в базу данных. Для этого, для таблиц и действий соответственно, в папках src/ActionParser/Actions и src/DeltaParser/Deltas необходимо создать файлы с методами обработки и добавить их к src/ActionParser/Actions или src/DeltaParser/DeltaFactory.
69
+ ## REST API
63
70
 
64
- ### Запуск
65
- ```
66
- pnpm start
67
- ```
68
-
69
- ## API
71
+ | Endpoint | Описание |
72
+ |----------|----------|
73
+ | `GET /get-tables` | Дельты таблиц (с пагинацией и фильтрацией) |
74
+ | `GET /get-actions` | Действия блокчейна (с пагинацией и фильтрацией) |
75
+ | `GET /get-current-block` | Текущий номер обработанного блока |
70
76
 
71
- ### Получение таблиц
72
- Конечная точка предоставляет информацию о изменении (дельтах) таблиц между блоками.
77
+ ## Архитектура
73
78
 
74
79
  ```
75
-
76
- let params = {
77
- page: 1,
78
- limit: 10,
79
- filter: { } - любые параметры фильтрации таблицы, включая данные в полях
80
- };
81
-
82
- axios.get('http://localhost:4000/get-tables', { params })
83
- .then(response => {
84
- console.log(response.data);
85
- // {
86
- // results: array,
87
- // page: number,
88
- // limit: number
89
- // };
90
- })
80
+ src/
81
+ ├── index.ts # Точка входа
82
+ ├── config.ts # Подписки на таблицы и действия
83
+ ├── ActionParser/ # Парсер действий блокчейна
84
+ │ ├── Parser/ # Ядро парсера действий
85
+ │ ├── Actions/ # Кастомные обработчики действий
86
+ │ └── Factory/ # Фабрика создания обработчиков
87
+ ├── DeltaParser/ # Парсер дельт таблиц
88
+ │ ├── Parser/ # Ядро парсера дельт
89
+ │ ├── Deltas/ # Кастомные обработчики дельт
90
+ │ └── Factory/ # Фабрика создания обработчиков
91
+ ├── BlockParser/ # Парсер блоков
92
+ │ └── Parser/ # Обработка блоков целиком
93
+ ├── ForkParser/ # Обработка форков блокчейна
94
+ │ ├── Parser/ # Ядро обработки форков
95
+ │ ├── Forks/ # Кастомные обработчики форков
96
+ │ └── Factory/ # Фабрика создания обработчиков
97
+ ├── Database/ # Подключение к MongoDB
98
+ ├── Initializer/ # Инициализация и настройка
99
+ ├── Reader/ # Чтение данных из SHiP (WebSocket)
100
+ ├── RedisNotifier/ # Публикация в Redis Streams
101
+ ├── Types/ # Типы и интерфейсы
102
+ └── Utils/ # Вспомогательные утилиты
91
103
  ```
92
104
 
93
- ### Получение действий
94
- Конечная точка предоставляет информацию о действиях, произошедших между блоками.
105
+ ### Конвейер обработки
95
106
 
96
- ```
97
- let params = {
98
- page: 1,
99
- limit: 10,
100
- filter: { } // любые параметры фильтрации действий, включая данные в полях
101
- };
102
-
103
- axios.get('http://localhost:4000/get-actions', { params })
104
- .then(response => {
105
- console.log(response.data);
106
- // {
107
- // results: array,
108
- // page: number,
109
- // limit: number
110
- // };
111
- })
112
- .catch(error => {
113
- console.error(error);
114
- });
115
- ```
107
+ 1. **Reader** подключается к SHiP по WebSocket и получает блоки
108
+ 2. **BlockParser** извлекает actions и deltas из каждого блока
109
+ 3. **ActionParser** обрабатывает действия через зарегистрированные обработчики
110
+ 4. **DeltaParser** обрабатывает дельты таблиц через соответствующие обработчики
111
+ 5. **ForkParser** следит за форками и корректирует данные
112
+ 6. Результаты сохраняются в **MongoDB** и публикуются в **Redis Streams**
116
113
 
117
- ### Получение текущего блока
118
- Конечная точка предоставляет информацию о текущем блоке. Эта информация используется при формировании кооперативных документов.
114
+ ## Ключевые зависимости
119
115
 
120
- ```
121
- axios.get('http://localhost:4000/get-current-block')
122
- .then(response => {
123
- console.log(response.data);
124
- // number
125
- })
126
- .catch(error => {
127
- console.error(error);
128
- });
129
- ```
116
+ - **@blockmatic/eosio-ship-reader** — библиотека чтения SHiP
117
+ - **eosjs** — взаимодействие с блокчейном EOSIO
118
+ - **mongodb** — хранилище индексированных данных
119
+ - **ioredis** — публикация событий в Redis Streams
120
+ - **express** — REST API
121
+ - **ws** — WebSocket-клиент
122
+ - **unbuild** — сборка библиотеки
130
123
 
131
124
  ## Лицензия
132
125
 
133
- [MIT](./LICENSE) License © 2024-PRESENT [CBS VOSKHOD](https://github.com/copenomics)
134
-
135
- <!-- Badges -->
136
-
137
- [npm-version-src]: https://img.shields.io/npm/v/cooparser?style=flat&colorA=080f12&colorB=1fa669
138
- [npm-version-href]: https://npmjs.com/package/cooparser
139
- [npm-downloads-src]: https://img.shields.io/npm/dm/cooparser?style=flat&colorA=080f12&colorB=1fa669
140
- [npm-downloads-href]: https://npmjs.com/package/cooparser
141
- [bundle-src]: https://img.shields.io/bundlephobia/minzip/cooparser?style=flat&colorA=080f12&colorB=1fa669&label=minzip
142
- [bundle-href]: https://bundlephobia.com/result?p=cooparser
143
- [license-src]: https://img.shields.io/github/license/copenomics/cooparser.svg?style=flat&colorA=080f12&colorB=1fa669
144
- [license-href]: https://github.com/copenomics/cooparser/blob/main/LICENSE
145
- [jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
146
- [jsdocs-href]: https://www.jsdocs.io/package/cooparser
126
+ [BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.ru)
package/package.json CHANGED
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "name": "@coopenomics/parser",
3
3
  "type": "module",
4
- "version": "2026.2.21-alpha-4",
4
+ "version": "2026.2.28-4",
5
5
  "private": false,
6
6
  "packageManager": "pnpm@9.0.6",
7
- "description": "",
7
+ "description": "Индексатор блокчейна через State History Plugin",
8
8
  "author": "Alex Ant <dacom.dark.sun@gmail.com>",
9
9
  "license": "MIT",
10
10
  "homepage": "https://github.com/copenomics/cooparser#readme",
@@ -40,13 +40,13 @@
40
40
  "deploy-testnet": "git checkout testnet && git merge main && git push origin testnet && git checkout main",
41
41
  "deploy-production": "git checkout production && git merge testnet && git push origin production && git checkout main",
42
42
  "build": "unbuild",
43
- "dev": "concurrently -n 'PARSER' -c 'bgBlue.white' \"nodemon --watch src --ext ts,js,env --exec 'esno' src/index.ts\"",
44
- "dev:test": "NODE_ENV=test concurrently -n 'PARSER' -c 'bgBlue.white' \"nodemon --watch src --ext ts,js,env --exec 'esno' src/index.ts\"",
43
+ "dev": "nodemon --watch src --ext ts,js,env --exec 'esno' src/index.ts",
44
+ "dev:test": "NODE_ENV=test nodemon --watch src --ext ts,js,env --exec 'esno' src/index.ts",
45
45
  "lint": "eslint .",
46
46
  "prepublishOnly": "nr build",
47
47
  "release": "bumpp && npm publish",
48
48
  "start": "esno src/index.ts",
49
- "test": "vitest",
49
+ "test": "vitest run",
50
50
  "typecheck": "tsc --noEmit",
51
51
  "doc": "typedoc"
52
52
  },
@@ -54,7 +54,7 @@
54
54
  "@blockmatic/eosio-ship-reader": "^1.2.0",
55
55
  "@types/express": "^4.17.21",
56
56
  "@types/ws": "^8.5.13",
57
- "cooptypes": "2026.2.21-alpha-4",
57
+ "cooptypes": "2026.2.28-4",
58
58
  "dotenv": "^16.4.5",
59
59
  "dotenv-expand": "^11.0.6",
60
60
  "eosjs": "^22.1.0",
@@ -87,5 +87,5 @@
87
87
  "vite": "^5.2.10",
88
88
  "vitest": "^1.5.2"
89
89
  },
90
- "gitHead": "4f06bb40f891a2a472fc5e4de124ab4595f32f2f"
90
+ "gitHead": "509471c97df322a4cad2c52d286c361844f49cc5"
91
91
  }