@nitra/nats 3.0.6 → 3.0.8

package/README.md

@@ -1,7 +1,7 @@
 # @nitra/nats
 
 NATS JetStream helper для Node.js.  
-Простий API для публікації, обробки та моніторингу повідомлень у черзі з автоматичним створенням stream/consumer для кожного subject.
+Простий API для публікації, обробки та моніторингу повідомлень у черзі з автоматичним створенням consumer для кожного subject або кастомного durable consumer.
 
 ---
 
@@ -20,6 +20,7 @@ npm install @nitra/nats
 Пакет використовує такі змінні середовища:
 
 - `NATS_SERVER` — адреса сервера NATS (наприклад, `nats://localhost:4222`)
+- `NATS_STREAM` — назва stream (за замовчуванням `dev`)
 
 ---
 
@@ -31,11 +32,9 @@ npm install @nitra/nats
 projectName:subjectName
 ```
 
----
-
 **Приклади:**
 
-- `myproject:jobs`
+- `myProject:jobs`
 - `service:notifications`
 
 ---
@@ -45,11 +44,18 @@ projectName:subjectName
 ```js
 import { publish } from '@nitra/nats'
 
+// Мінімальний варіант (durable_name = subject)
 await publish('project:subject', { id: 1, foo: 'bar' })
+
+// Кастомний durable consumer (наприклад, для групової обробки)
+await publish('project:subject', { id: 2 }, [
+  { durableName: 'worker-group', filterSubjects: ['project:subject', 'project:subject2'] },
+  { durableName: 'analytics', filterSubjects: ['project:subject'] }
+])
 ```
 
-- Stream і Consumer будуть створені автоматично, якщо не існують.
-- Повідомлення публікується у subject `stream.project:subject`.
+- Consumer буде створений автоматично, якщо не існує.
+- Повідомлення публікується у subject `dev.project:subject` (або `${NATS_STREAM}.project:subject`).
 
 ---
 
@@ -58,51 +64,61 @@ await publish('project:subject', { id: 1, foo: 'bar' })
 ```js
 import { read, finish } from '@nitra/nats'
 
+// Читання для стандартного durable consumer (durable_name = subject)
 const data = await read('project:subject')
 // ...обробка data...
 await finish() // підтвердження (ack) повідомлення
+
+// Читання для кастомного durable consumer
+const data2 = await read('worker-group')
+await finish()
 ```
 
 - Якщо не викликати `finish()`, повідомлення буде повернуто у чергу (`nak`) при завершенні процесу або помилці.
+- Durable consumer створюється автоматично при першій публікації.
 
 ---
 
-## Кількість непрочитаних повідомлень для subject
+## Кількість непрочитаних повідомлень для durable consumer
 
 ```js
 import { getPendingCount } from '@nitra/nats'
 
-const count = await getPendingCount('project:subject')
+const count = await getPendingCount('project:subject') // для стандартного durable
 console.log('pending:', count)
+
+const count2 = await getPendingCount('worker-group') // для кастомного durable
+console.log('pending for group:', count2)
 ```
 
 ---
 
 ## Як це працює
 
-- **publish(subject, data):**
+- **publish(subject, data, consumers?):**
 
-  - Перевіряє/створює stream і consumer для subject (один раз за процес).
-  - Публікує повідомлення у subject `stream.${subject}`.
+  - Перевіряє/створює consumer-ів (один раз за процес).
+  - Публікує повідомлення у subject `${stream}.${subject}`.
+  - Якщо передати масив consumers — створює кастомні durable consumer-и з кастомними іменами та фільтрами.
 
-- **read(subject):**
+- **read(durableName):**
 
-  - Читає одне повідомлення з черги для subject.
+  - Читає одне повідомлення з черги для durable consumer (за замовчуванням durable_name = subject).
 
 - **finish():**
 
   - Підтверджує (ack) повідомлення.
 
-- **getPendingCount(subject):**
-  - Повертає кількість непрочитаних повідомлень для consumer `durable_${subject}`.
+- **getPendingCount(durableName):**
+  - Повертає кількість непрочитаних повідомлень для durable consumer.
 
 ---
 
 ## Важливо
 
-- STREAM у NATS завжди один (`stream`), але subject динамічний.
-- Для кожного subject створюється окремий durable consumer з іменем `durable_${subject}`.
-- Пакет розрахований на single-message workflow (одне повідомлення на читання за раз, публікація - необмежена).
+- STREAM у NATS за замовчуванням `dev` (або значення змінної `NATS_STREAM`), але subject і durable consumer-и динамічні.
+- Для кожного subject або кастомного durable створюється окремий consumer з іменем `durableName`.
+- Пакет розрахований на single-message workflow (одне повідомлення на читання за раз, публікація — необмежена).
 - Для паралельної обробки або кастомних сценаріїв — дивись вихідний код та розширюй під свої задачі.
 
 ---
@@ -112,15 +128,31 @@ console.log('pending:', count)
 ```js
 import { publish, read, finish, getPendingCount } from '@nitra/nats'
 
-// Публікація
-await publish('project:subject', { id: 1, prop: 'prop' })
+// Публікація для стандартного durable (durable_name = subject)
+await publish('project:subject', { id: 1 })
+
+// Публікація для кількох consumer-ів
+await publish('project:subject', { id: 2 }, [
+  { durableName: 'worker-group', filterSubjects: ['project:subject', 'project:subject2'] },
+  { durableName: 'analytics', filterSubjects: ['project:subject'] }
+])
 
-// Pending для subject
+// Pending для стандартного durable
 const count = await getPendingCount('project:subject')
 console.log('pending:', count)
 
-// Читання
-const data = await read('project:subject')
+// Pending для кастомного durable
+const count2 = await getPendingCount('worker-group')
+console.log('pending for group:', count2)
+
+// Читання для стандартного durable
+const { id } = await read('project:subject')
+console.log(`read. id: ${id}`)
+// Підтверджуємо, що повідомлення прочитано (якщо не викликати finish, то повідомлення буде повторно надіслано)
+await finish()
+
+// Читання для кастомного durable
+const data = await read('worker-group')
 console.log('read:', data)
 await finish()
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nitra/nats",
   "description": "nats helper",
-  "version": "3.0.6",
+  "version": "3.0.8",
   "type": "module",
   "files": [
     "src"

package/src/consumer.js

@@ -1,26 +1,48 @@
-import { jsm, AckPolicy } from './nats.js'
-import { ensureStream } from './stream.js'
+import { jsm, AckPolicy, stream } from './nats.js'
+import { checkSubjectFormat } from './utils.js'
+// import { ensureStream } from './stream.js'
+
+// Set для зберігання існуючих consumer
+const consumerReady = new Set()
 
 /**
- * Перевіряє наявність або створює durable consumer для subject.
- * Stream створюється автоматично, якщо не існує.
+ * Перевіряє наявність або створює durable consumer(а) для subject(ів).
  * @param {string} subject - subject у форматі project:subject
+ * @param {object[]} consumers - список consumer-ів. [{durableName, filterSubjects}]
  * @returns {Promise<void>}
  */
-export async function ensureConsumer(subject) {
-  // створюємо stream якщо не існує
-  await ensureStream()
-
-  try {
-    await jsm.consumers.info('stream', `durable_${subject}`)
-    console.debug('✅ Durable consumer already exists')
-  } catch {
-    await jsm.consumers.add('stream', {
-      durable_name: `durable_${subject}`,
-      ack_policy: AckPolicy.Explicit, // якщо не підтвердити повідомлення, воно буде повторно надіслано
-      filter_subject: `stream.${subject}`,
-      deliver_policy: 'all' // 'all' - всі повідомлення, 'last' - останнє повідомлення
-    })
-    console.debug('✅ Durable consumer created')
+export async function ensureConsumer(subject, consumers = [{ durableName: subject, filterSubjects: [subject] }]) {
+  if (consumers.every(c => consumerReady.has(c.durableName))) {
+    console.debug(`✅ Consumers: ${consumers.map(c => c.durableName)} already exists`)
+    return
+  }
+
+  // перевіряємо чи subject відповідає формату project:subject
+  checkSubjectFormat(subject)
+
+  // // створюємо stream якщо не існує
+  // if (!consumerReady.size) {
+  //   await ensureStream()
+  // }
+
+  const consumerArr = (await jsm.consumers?.list(stream)?.next()) || []
+  for (const c of consumers) {
+    const isExists = consumerArr.some(ca => ca.config.durable_name === c.durableName)
+
+    // якщо не існує consumer-а який слухає subject, то створюємо за замовчуванням (durable_name = subject)
+    if (isExists) {
+      console.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' - всі непрочитані повідомлення
+      })
+
+      console.debug(`🔥 Consumer «${c.durableName}» created`)
+    }
+
+    consumerReady.add(c.durableName)
   }
 }

package/src/nats.js

@@ -6,13 +6,16 @@ export { AckPolicy } from 'nats'
 checkEnv(['NATS_SERVER'])
 
 // Connect to NATS
-export const client = await connect({ servers: env.NATS_SERVER })
+const nc = await connect({ servers: env.NATS_SERVER })
 
 // JSONCodec
 export const jc = JSONCodec()
 
 // Створюємо JetStream контекст
-export const js = client.jetstream()
+export const js = nc.jetstream()
 
 // Менеджер JetStream (для створення стрімів, конфігурацій тощо)
-export const jsm = await client.jetstreamManager()
+export const jsm = await nc.jetstreamManager()
+
+// Stream name
+export const stream = process.env.NATS_STREAM || 'dev'

package/src/pending-count.js

@@ -1,19 +1,16 @@
-import { jsm } from './nats.js'
-import { checkSubjectFormat } from './utils.js'
+import { jsm, stream } from './nats.js'
 
 /**
- * Повертає кількість непрочитаних (pending) повідомлень для durable consumer, пов’язаного з subject.
- * @param {string} subject - subject у форматі project:subject
+ * Повертає кількість непрочитаних (pending) повідомлень для durable consumer.
+ * @param {string} consumer - durable_name для consumer(за замовчуванням durable_name = subject)
  * @returns {Promise<number>} - кількість непрочитаних повідомлень
  */
-export async function getPendingCount(subject) {
-  checkSubjectFormat(subject)
-
+export async function getPendingCount(consumer) {
   try {
-    const info = await jsm.consumers.info('stream', `durable_${subject}`)
-    return info.num_pending
+    const info = await jsm.consumers.info(stream, consumer)
+    return info.num_pending + info.num_ack_pending
   } catch {
-    console.error('consumer not found for subject:', subject)
+    console.error(`consumer ${consumer} not found`)
     return 0
   }
 }

package/src/publish.js

@@ -1,24 +1,19 @@
-import { client, jc } from './nats.js'
+import { jc, js, stream } from './nats.js'
 import { ensureConsumer } from './consumer.js'
-import { checkSubjectFormat } from './utils.js'
-
-const consumerReady = new Set()
 
 /**
  * Публікує повідомлення у JetStream для вказаного subject.
- * Stream і Consumer створюються автоматично, якщо не існують.
+ * 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) {
-  // Ensure stream and consumer if not exists
-  if (!consumerReady.has(subject)) {
-    checkSubjectFormat(subject)
-    await ensureConsumer(subject)
-    consumerReady.add(subject)
-  }
-  console.debug('publish', data)
+export async function publish(subject, data, consumers) {
+  // Ensure consumer if not exists
+  await ensureConsumer(subject, consumers)
+
+  console.debug('publish:', data)
   // Publish message
-  return client.publish(`stream.${subject}`, jc.encode(data))
+  return js.publish(`${stream}.${subject}`, jc.encode(data))
 }

package/src/stream.js

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

package/src/worker.js

@@ -1,23 +1,15 @@
-import { js, jc } from './nats.js'
-import { state, checkSubjectFormat } from './utils.js'
+import { js, jc, stream } from './nats.js'
+import { state } from './utils.js'
 
 /**
- * Зчитує одне повідомлення з JetStream для вказаного subject.
- * @param {string} subject - subject у форматі project:subject
+ * Зчитує одне повідомлення з JetStream для вказаного consumer-а.
+ * @param {string} consumer - durable_name для consumer(за замовчуванням durable_name = subject)
  * @returns {Promise<object>} - декодовані дані повідомлення
  */
-export async function read(subject) {
-  checkSubjectFormat(subject)
+export async function read(consumer) {
+  const consumerObj = await js.consumers.get(stream, consumer)
 
-  let consumer
-  try {
-    consumer = await js.consumers.get('stream', `durable_${subject}`)
-  } catch {
-    console.error('consumer not found for subject:', subject)
-    return {}
-  }
-
-  const iter = await consumer.fetch({ max_messages: 1 })
+  const iter = await consumerObj.fetch({ max_messages: 1, expires: 1000 })
   for await (const msg of iter) {
     state.msg = msg
     console.debug('read msg', jc.decode(msg.data))