@nitra/nats 3.1.3 → 4.0.0

package/README.md

@@ -1,14 +1,14 @@
 # @nitra/nats
 
 NATS JetStream helper для Node.js.
-Простий API для публікації, обробки та моніторингу повідомлень у черзі з автоматичним створенням consumer для кожного subject або кастомного durable consumer.
+Простий API для публікації, обробки та моніторингу повідомлень у черзі з гнучким управлінням consumer-ами через конфігурацію та CLI інструменти.
 
 ---
 
 ## Встановлення
 
 ```sh
-yarn add @nitra/nats
+bun add @nitra/nats
 # або
 npm install @nitra/nats
 ```
@@ -44,18 +44,72 @@ projectName:subjectName
 ```js
 import { publish } from '@nitra/nats'
 
-// Мінімальний варіант (durable_name = subject)
+// Публікація повідомлення
 await publish('project:subject', { id: 1, foo: 'bar' })
+await publish('service:notifications', { message: 'Hello!' })
+```
+
+- Повідомлення публікується у subject `dev.project:subject` (або `${NATS_STREAM}.project:subject`)
+- Consumer-и потрібно створювати окремо через `ensureConsumer` або CLI
+
+---
+
+## Управління Consumer-ами
+
+### Програмне створення consumer-а
+
+```js
+import { ensureConsumer } from '@nitra/nats'
+
+// Створення простого consumer-а
+await ensureConsumer({
+  streamName: 'dev',
+  durableName: 'project:subject',
+  filterSubjects: ['project:subject'],
+  deliverPolicy: 'all',
+  ackPolicy: 'explicit'
+})
+
+// Створення групового consumer-а для кількох subject-ів
+await ensureConsumer({
+  streamName: 'dev',
+  durableName: 'worker-group',
+  filterSubjects: ['project:orders', 'project:payments'],
+  deliverPolicy: 'all',
+  ackPolicy: 'explicit'
+})
+```
 
-// Кастомний durable consumer (наприклад, для групової обробки)
-await publish('project:subject', { id: 2 }, [
-  { durableName: 'worker-group', filterSubjects: ['project:subject', 'project:subject2'] },
-  { durableName: 'analytics', filterSubjects: ['project:subject'] }
-])
+### CLI для роботи з YAML конфігураціями
+
+Створіть YAML файл з конфігурацією consumer-а:
+
+```yaml
+# consumer.yaml
+apiVersion: jetstream.nats.io/v1beta2
+kind: Consumer
+metadata:
+  name: 'nats:test'
+  namespace: dev
+spec:
+  streamName: dev
+  durableName: 'nats:test'
+  filterSubjects:
+    - 'nats:subject'
+    - 'nats:subject2'
+  deliverPolicy: all
+  ackPolicy: explicit
 ```
 
-- Consumer буде створений автоматично, якщо не існує.
-- Повідомлення публікується у subject `dev.project:subject` (або `${NATS_STREAM}.project:subject`).
+Застосуйте конфігурацію:
+
+```bash
+# З змінними середовища
+NODE_ENV=development NATS_URL=nats://localhost:4222 NATS_STREAM=dev node cli.js consumer.yaml
+
+# Або через npx після публікації
+npx @nitra/nats consumer.yaml
+```
 
 ---
 
@@ -95,68 +149,124 @@ console.log('pending for group:', count2)
 
 ## Як це працює
 
-- **publish(subject, data, consumers?):**
+- **publish(subject, data):**
 
-  - Перевіряє/створює consumer-ів (один раз за процес).
-  - Публікує повідомлення у subject `${stream}.${subject}`.
-  - Якщо передати масив consumers — створює кастомні durable consumer-и з кастомними іменами та фільтрами.
+  - Публікує повідомлення у subject `${stream}.${subject}`
+  - Перевіряє формат subject (має бути `project:subject`)
+
+- **ensureConsumer(spec):**
+
+  - Створює consumer якщо не існує
+  - Оновлює `filter_subjects` якщо вони змінились
+  - Перестворює consumer якщо змінились `deliverPolicy` або `ackPolicy`
+  - Автоматично створює stream якщо потрібно
 
 - **read(durableName):**
 
-  - Читає одне повідомлення з черги для durable consumer (за замовчуванням durable_name = subject).
+  - Читає одне повідомлення з черги для durable consumer
 
 - **finish():**
 
-  - Підтверджує (ack) повідомлення.
+  - Підтверджує (ack) повідомлення
 
 - **getPendingCount(durableName):**
-  - Повертає кількість непрочитаних повідомлень для durable consumer.
+  - Повертає кількість непрочитаних повідомлень для durable consumer
 
 ---
 
 ## Важливо
 
-- STREAM у NATS за замовчуванням `dev` (або значення змінної `NATS_STREAM`), але subject і durable consumer-и динамічні.
-- Для кожного subject або кастомного durable створюється окремий consumer з іменем `durableName`.
-- Пакет розрахований на single-message workflow (одне повідомлення на читання за раз, публікація — необмежена).
-- Для паралельної обробки або кастомних сценаріїв — дивись вихідний код та розширюй під свої задачі.
+- STREAM у NATS за замовчуванням `dev` (або значення змінної `NATS_STREAM`)
+- Consumer-и потрібно створювати **явно** через `ensureConsumer` або CLI
+- Subject має відповідати формату `project:subject`
+- Пакет розрахований на single-message workflow (одне повідомлення на читання за раз)
+- `ensureConsumer` розумно оновлює конфігурацію без втрати повідомлень
+- CLI підтримує YAML конфігурації для декларативного управління consumer-ами
 
 ---
 
 ## Приклад повного workflow
 
 ```js
-import { publish, read, finish, getPendingCount } from '@nitra/nats'
+import { publish, ensureConsumer, read, finish, getPendingCount } from '@nitra/nats'
+
+// 1. Створення consumer-ів
+await ensureConsumer({
+  streamName: 'dev',
+  durableName: 'project:subject',
+  filterSubjects: ['project:subject'],
+  deliverPolicy: 'all',
+  ackPolicy: 'explicit'
+})
+
+await ensureConsumer({
+  streamName: 'dev',
+  durableName: 'worker-group',
+  filterSubjects: ['project:subject', 'project:orders'],
+  deliverPolicy: 'all',
+  ackPolicy: 'explicit'
+})
+
+// 2. Публікація повідомлень
+await publish('project:subject', { id: 1, action: 'create' })
+await publish('project:orders', { orderId: 123, amount: 100 })
+
+// 3. Перевірка pending повідомлень
+const count1 = await getPendingCount('project:subject')
+const count2 = await getPendingCount('worker-group')
+console.log(`pending: ${count1}, worker-group: ${count2}`)
 
-// Публікація для стандартного durable (durable_name = subject)
-await publish('project:subject', { id: 1 })
+// 4. Обробка повідомлень
+const data1 = await read('project:subject')
+console.log('received:', data1)
+await finish()
 
-// Публікація для кількох consumer-ів
-await publish('project:subject', { id: 2 }, [
-  { durableName: 'worker-group', filterSubjects: ['project:subject', 'project:subject2'] },
-  { durableName: 'analytics', filterSubjects: ['project:subject'] }
-])
+const data2 = await read('worker-group')
+console.log('group received:', data2)
+await finish()
+```
 
-// Pending для стандартного durable
-const count = await getPendingCount('project:subject')
-console.log('pending:', count)
+---
 
-// Pending для кастомного durable
-const count2 = await getPendingCount('worker-group')
-console.log('pending for group:', count2)
+## CLI Інструмент
 
-// Читання для стандартного durable
-const { id } = await read('project:subject')
-console.log(`read. id: ${id}`)
-// Підтверджуємо, що повідомлення прочитано (якщо не викликати finish, то повідомлення буде повторно надіслано)
-await finish()
+CLI підтримує роботу з YAML конфігураціями consumer-ів у форматі JetStream Consumer API.
 
-// Читання для кастомного durable
-const data = await read('worker-group')
-console.log('read:', data)
-await finish()
+### Використання
+
+```bash
+# Застосування конфігурації consumer-а з YAML файлу
+NODE_ENV=development NATS_URL=nats://localhost:4222 NATS_STREAM=dev node cli.js consumer.yaml
+
+# Через npx після публікації пакету
+npx @nitra/nats consumer.yaml
 ```
 
+### Формат YAML конфігурації
+
+```yaml
+apiVersion: jetstream.nats.io/v1beta2
+kind: Consumer
+metadata:
+  name: my-consumer
+  namespace: dev
+spec:
+  streamName: dev
+  durableName: my-consumer
+  filterSubjects:
+    - project:orders
+    - project:payments
+  deliverPolicy: all
+  ackPolicy: explicit
+```
+
+CLI автоматично:
+
+- Створить consumer якщо не існує
+- Оновить filter_subjects якщо вони змінились
+- Перестворить consumer якщо змінились deliverPolicy або ackPolicy
+- Створить stream якщо потрібно
+
 ---
 
 ## Ліцензія

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@nitra/nats",
   "description": "nats helper",
-  "version": "3.1.3",
+  "version": "4.0.0",
   "type": "module",
   "files": [
     "src"
   ],
+  "bin": {
+    "nitra-nats": "./src/cli.js"
+  },
   "exports": {
     ".": "./src/index.js"
   },
@@ -21,8 +24,9 @@
   "homepage": "https://github.com/nitra/nats",
   "license": "MIT",
   "dependencies": {
-    "@nitra/check-env": "^4.0.0",
-    "@nitra/pino": "^2.3.0",
+    "@nitra/check-env": "^4.1.0",
+    "@nitra/pino": "^2.7.4",
+    "js-yaml": "^4.1.1",
     "nats": "^2.29.3"
   },
   "engines": {

package/src/cli.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import fs from 'fs'
+import path from 'path'
+import { exit } from 'node:process'
+import yaml from 'js-yaml'
+import { ensureConsumer } from './consumer.js'
+import { checkSubjectFormat } from './utils.js'
+
+function parseConsumerYaml() {
+  try {
+    const filePath = path.resolve(process.cwd(), process.argv[2])
+    const fileContents = fs.readFileSync(filePath, 'utf8')
+    const data = yaml.load(fileContents)
+
+    return {
+      apiVersion: data.apiVersion,
+      kind: data.kind,
+      metadata: {
+        name: data.metadata?.name,
+        namespace: data.metadata?.namespace
+      },
+      spec: {
+        streamName: data.spec?.streamName,
+        durableName: data.spec?.durableName,
+        filterSubjects: data.spec?.filterSubjects,
+        deliverPolicy: data.spec?.deliverPolicy,
+        ackPolicy: data.spec?.ackPolicy
+      }
+    }
+  } catch (error) {
+    throw new Error(`Помилка парсингу YAML файлу: ${error.message}`)
+  }
+}
+
+/**
+ * Валідує структуру парсеного consumer об'єкта
+ * @param {Object} consumer - Об'єкт consumer для валідації
+ * @returns {boolean} true якщо валідація пройшла успішно
+ * @throws {Error} Якщо валідація не пройшла
+ */
+export function validateConsumer(consumer) {
+  if (!consumer.apiVersion) throw new Error('Відсутнє поле apiVersion')
+  if (!consumer.kind) throw new Error('Відсутнє поле kind')
+  if (!consumer.metadata?.name) throw new Error('Відсутнє поле metadata.name')
+
+  for (const field of ['streamName', 'durableName', 'filterSubjects', 'deliverPolicy', 'ackPolicy']) {
+    if (!consumer.spec?.[field]) throw new Error(`Відсутнє поле spec.${field}`)
+  }
+
+  if (!Array.isArray(consumer.spec.filterSubjects)) throw new Error('Поле spec.filterSubjects повинно бути масивом')
+
+  for (const subject of consumer.spec.filterSubjects) {
+    checkSubjectFormat(subject)
+  }
+}
+
+// Приклад використання
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    const consumer = parseConsumerYaml()
+
+    validateConsumer(consumer)
+
+    await ensureConsumer(consumer.spec)
+    exit(0)
+  } catch (error) {
+    console.error('Помилка:', error.message)
+    exit(1)
+  }
+}

package/src/consumer.js

@@ -1,49 +1,69 @@
-import { jsm, AckPolicy, stream } from './nats.js'
-import { checkSubjectFormat } from './utils.js'
+import { jsm, stream } from './nats.js'
+import { ensureStream } from './stream.js'
 import { log } from '@nitra/pino'
-// import { ensureStream } from './stream.js'
-
-// Set для зберігання існуючих consumer
-const consumerReady = new Set()
 
 /**
- * Перевіряє наявність або створює durable consumer(а) для subject(ів).
- * @param {string} subject - subject у форматі project:subject
- * @param {object[]} consumers - список consumer-ів. [{durableName, filterSubjects}]
+ * Створює або оновлює consumer.
+ * @param {object{streamName: string, durableName: string, filterSubjects: string[], deliverPolicy: string, ackPolicy: string}} spec  - об'єкт consumer-а.
  * @returns {Promise<void>}
  */
-export async function ensureConsumer(subject, consumers = [{ durableName: subject, filterSubjects: [subject] }]) {
-  if (consumers.every(c => consumerReady.has(c.durableName))) {
-    log.debug(`✅ Consumers: ${consumers.map(c => c.durableName)} already exists`)
-    return
-  }
+export async function ensureConsumer(spec) {
+  // створюємо stream якщо не існує
+  const streamName = spec.streamName || stream
+  await ensureStream(streamName)
 
-  // перевіряємо чи subject відповідає формату project:subject
-  checkSubjectFormat(subject)
+  const consumerArr = (await jsm.consumers?.list(streamName)?.next()) || []
+  const consumer = consumerArr.find(ca => ca.config.durable_name === spec.durableName)
 
-  // // створюємо stream якщо не існує
-  // if (!consumerReady.size) {
-  //   await ensureStream()
-  // }
+  // якщо не існує consumer-а створюємо його. якщо є перевіримо чи відповідає spec(якщо ні, то перестворюємо або оновлюємо)
+  if (consumer) {
+    log.info(`✅ Consumer «${spec.durableName}» already exists`)
 
-  const consumerArr = (await jsm.consumers?.list(stream)?.next()) || []
-  for (const c of consumers) {
-    const isExists = consumerArr.some(ca => ca.config.durable_name === c.durableName)
+    const { filter_subjects, deliver_policy, ack_policy } = consumer.config
 
-    // якщо не існує consumer-а який слухає subject, то створюємо за замовчуванням (durable_name = subject)
-    if (isExists) {
-      log.debug(`✅ Consumer «${c.durableName}» already exists`)
-    } else {
-      await jsm.consumers.add(stream, {
-        durable_name: c.durableName,
-        ack_policy: AckPolicy.Explicit, // якщо не підтвердити повідомлення, воно буде повторно надіслано
-        filter_subjects: c.filterSubjects.map(fs => `${stream}.${fs}`), // якщо не вказати, то consumer буде слухати всі повідомлення зі stream
-        deliver_policy: 'all' // 'all' - всі непрочитані повідомлення
-      })
+    // якщо deliver_policy або ack_policy не відповідають spec, то перестворюємо consumer
+    if (deliver_policy !== spec.deliverPolicy || ack_policy !== spec.ackPolicy) {
+      const tempSpec = {
+        durableName: `temp_${spec.durableName}`,
+        filterSubjects: filter_subjects,
+        deliverPolicy: deliver_policy,
+        ackPolicy: ack_policy
+      }
+      // create temp consumer with old filter_subjects
+      await createConsumer(streamName, tempSpec)
+      // delete old consumer
+      await jsm.consumers.delete(streamName, spec.durableName)
+      // create new consumer
+      await createConsumer(streamName, spec)
+      // delete temp consumer
+      await jsm.consumers.delete(streamName, tempSpec.durableName)
 
-      log.debug(`🔥 Consumer «${c.durableName}» created`)
+      log.info(`🔥 Consumer «${spec.durableName}» - recreated`)
     }
+    // якщо filter_subjects не відповідають spec, то оновлюємо consumer
+    else if (
+      spec.filterSubjects.some(fs => !filter_subjects.includes(`${streamName}.${fs}`)) ||
+      filter_subjects.some(fs => !spec.filterSubjects.includes(fs.split('.').pop()))
+    ) {
+      await jsm.consumers.update(streamName, spec.durableName, {
+        filter_subjects: spec.filterSubjects.map(fs => `${streamName}.${fs}`)
+      })
 
-    consumerReady.add(c.durableName)
+      log.info(`🔥 Consumer «${spec.durableName}» - updated`)
+    } else {
+      log.info(`✅ Consumer «${spec.durableName}» - no changes`)
+    }
+  } else {
+    await createConsumer(streamName, spec)
+    log.info(`🔥 Consumer «${spec.durableName}» created`)
   }
 }
+
+async function createConsumer(streamName, spec) {
+  await jsm.consumers.add(streamName, {
+    durable_name: spec.durableName,
+    ack_policy: spec.ackPolicy, // якщо не підтвердити повідомлення, воно буде повторно надіслано
+    filter_subjects: spec.filterSubjects.map(fs => `${streamName}.${fs}`), // якщо не вказати, то consumer буде слухати всі повідомлення зі stream
+    deliver_policy: spec.deliverPolicy // 'all' - всі непрочитані повідомлення
+  })
+}

package/src/nats.js

@@ -1,13 +1,26 @@
-import { checkEnv, env } from '@nitra/check-env'
+import { checkEnv } from '@nitra/check-env'
 import { connect, JSONCodec } from 'nats'
-
-checkEnv(['NATS_URL', 'NATS_STREAM'])
+import { env } from 'node:process'
 
 // AckPolicy
-export { AckPolicy } from 'nats'
+// export { AckPolicy } from 'nats'
+
+let nc
+
+// якщо задані демо дані, то використовуємо фейковий NATS
+if (env.NATS_FAKE_DATA) {
+  nc = {
+    jetstream: () => {},
+    jetstreamManager: async () => {
+      Promise.resolve()
+    }
+  }
+} else {
+  checkEnv(['NATS_URL', 'NATS_STREAM'])
 
-// Connect to NATS
-const nc = await connect({ servers: env.NATS_URL })
+  // Connect to NATS
+  nc = await connect({ servers: env.NATS_URL })
+}
 
 // JSONCodec
 export const jc = JSONCodec()

package/src/pending-count.js

@@ -1,5 +1,6 @@
 import { jsm, stream } from './nats.js'
 import { log } from '@nitra/pino'
+import { env } from 'node:process'
 
 /**
  * Повертає кількість непрочитаних (pending) повідомлень для durable consumer.
@@ -7,6 +8,11 @@ import { log } from '@nitra/pino'
  * @returns {Promise<number>} - кількість непрочитаних повідомлень
  */
 export async function getPendingCount(consumer) {
+  // якщо задані демо дані, то завжди повертаємо 0
+  if (env.NATS_FAKE_DATA) {
+    return 0
+  }
+
   try {
     const info = await jsm.consumers.info(stream, consumer)
     return info.num_pending + info.num_ack_pending

package/src/publish.js

@@ -1,18 +1,22 @@
 import { jc, js, stream } from './nats.js'
-import { ensureConsumer } from './consumer.js'
+import { checkSubjectFormat } from './utils.js'
 import { log } from '@nitra/pino'
+import { env } from 'node:process'
 
 /**
  * Публікує повідомлення у JetStream для вказаного subject.
- * Consumer створюється автоматично, якщо не існує.
  * @param {string} subject - subject у форматі project:subject
  * @param {object} data - дані для публікації
- * @param {object[]} [consumers] - список consumer-ів які потрібно створити. [{durableName, filterSubject}] (необов'язково)
  * @returns {Promise<void>}
  */
-export async function publish(subject, data, consumers) {
-  // Ensure consumer if not exists
-  await ensureConsumer(subject, consumers)
+export async function publish(subject, data) {
+  // якщо задані демо дані, то ігноримо запис
+  if (env.NATS_FAKE_DATA) {
+    return Promise.resolve()
+  }
+
+  // перевіряємо чи subject відповідає формату project:subject
+  checkSubjectFormat(subject)
 
   log.debug('publish:', data)
   // Publish message

package/src/stream.js

@@ -5,14 +5,14 @@ import { log } from '@nitra/pino'
  * Перевіряє наявність або створює JetStream stream.
  * @returns {Promise<void>}
  */
-export async function ensureStream() {
+export async function ensureStream(streamName = stream) {
   try {
-    await jsm.streams.info(stream)
+    await jsm.streams.info(streamName)
     log.debug('✅ Stream already exists')
   } catch {
     await jsm.streams.add({
-      name: stream,
-      subjects: [`${stream}.>`],
+      name: streamName,
+      subjects: [`${streamName}.>`],
       retention: 'interest', // зберігає повідомлення поки є consumers або поки всі повідомлення не будуть прочитані
       replicas: 1, // кількість реплік у кластері TODO: проговорити кількість реплік
       storage: 'file' //'memory' TODO: проговорити які параметри потрібні для кластера

package/src/worker.js

@@ -2,6 +2,7 @@ import { js, jc, stream } from './nats.js'
 import { state } from './utils.js'
 import { exit } from 'node:process'
 import { log } from '@nitra/pino'
+import { env } from 'node:process'
 
 /**
  * Зчитує одне повідомлення з JetStream для вказаного consumer-а.
@@ -9,6 +10,12 @@ import { log } from '@nitra/pino'
  * @returns {Promise<object>} - декодовані дані повідомлення
  */
 export async function read(consumer) {
+  // якщо задані демо дані, то повертаємо їх
+  if (env.NATS_FAKE_DATA) {
+    console.log('env.NATS_FAKE_DATA:', env.NATS_FAKE_DATA)
+    return JSON.parse(env.NATS_FAKE_DATA)
+  }
+
   const consumerObj = await js.consumers.get(stream, consumer)
 
   const iter = await consumerObj.fetch({ max_messages: 1, expires: 1000 })