@nitra/nats 4.1.0 → 4.2.1

package/README.md

@@ -232,7 +232,7 @@ CLI підтримує роботу з YAML конфігураціями consume
 
 ```bash
 # Застосування конфігурації consumer-а з YAML файлу
-NODE_ENV=development NATS_URL=nats://localhost:4222 NATS_STREAM=dev node cli.js consumer.yaml
+NATS_URL=nats://localhost:4222 node cli.js consumer.yaml
 
 # Через npx після публікації пакету
 npx @nitra/nats consumer.yaml

package/package.json

@@ -1,34 +1,34 @@
 {
   "name": "@nitra/nats",
+  "version": "4.2.1",
   "description": "nats helper",
-  "version": "4.1.0",
-  "type": "module",
-  "files": [
-    "src"
+  "keywords": [
+    "nats",
+    "nitra"
   ],
+  "homepage": "https://github.com/nitra/nats",
+  "bugs": "https://github.com/nitra/nats/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nitra/nats.git"
+  },
   "bin": {
     "nitra-nats": "src/cli.js"
   },
+  "files": [
+    "src"
+  ],
+  "type": "module",
   "exports": {
     ".": "./src/index.js"
   },
-  "keywords": [
-    "nitra",
-    "nats"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/nitra/nats.git"
-  },
-  "bugs": "https://github.com/nitra/nats/issues",
-  "homepage": "https://github.com/nitra/nats",
-  "license": "MIT",
   "dependencies": {
     "@nats-io/jetstream": "^3.3.0",
     "@nats-io/nats-core": "^3.3.0",
     "@nats-io/transport-node": "^3.3.0",
     "@nitra/check-env": "^4.1.0",
-    "@nitra/pino": "^2.9.1",
+    "@nitra/pino": "^2.10.0",
     "js-yaml": "^4.1.1"
   },
   "engines": {

package/src/cli.js

@@ -28,7 +28,8 @@ function parseConsumerYaml() {
         durableName: data.spec?.durableName,
         filterSubjects: data.spec?.filterSubjects,
         deliverPolicy: data.spec?.deliverPolicy,
-        ackPolicy: data.spec?.ackPolicy
+        ackPolicy: data.spec?.ackPolicy,
+        ackWait: data.spec?.ackWait
       }
     }
   } catch (error) {
@@ -53,7 +54,7 @@ export function validateConsumer(consumer) {
   if (!Array.isArray(consumer.spec.filterSubjects)) throw new Error('Поле spec.filterSubjects повинно бути масивом')
 
   for (const subject of consumer.spec.filterSubjects) {
-    checkSubjectFormat(subject)
+    checkSubjectFormat(consumer.spec.streamName, `${consumer.spec.streamName}.${subject}`)
   }
 }
 

package/src/consumer.js

@@ -1,11 +1,11 @@
-import { jsm, stream } from './nats.js'
-import { ensureStream } from './stream.js'
+import { jsm } from './nats.js'
 import { log } from '@nitra/pino'
+import { nanos, millis } from '@nats-io/nats-core'
 
 /**
  * Створює або оновлює consumer.
  * @param {object} spec - об'єкт consumer-а
- * @param {string} [spec.streamName] - назва stream
+ * @param {string} spec.streamName - назва stream
  * @param {string} spec.durableName - назва consumer-а
  * @param {string[]} spec.filterSubjects - масив subject-ів для фільтрації
  * @param {string} spec.deliverPolicy - політика доставки
@@ -14,71 +14,112 @@ import { log } from '@nitra/pino'
  */
 export async function ensureConsumer(spec) {
   // створюємо stream якщо не існує
-  const streamName = spec.streamName || stream
-  await ensureStream(streamName)
+  await ensureStream(spec.streamName)
 
-  const consumerArr = (await jsm.consumers?.list(streamName)?.next()) || []
+  const consumerArr = (await jsm.consumers?.list(spec.streamName)?.next()) || []
   const consumer = consumerArr.find(ca => ca.config.durable_name === spec.durableName)
 
+  // Додаємо стрім до subject
+  // якщо не вказати, то consumer буде слухати всі повідомлення зі stream
+  spec.filterSubjects = spec.filterSubjects.map(fs => `${spec.streamName}.${fs}`)
+
+  const preparedSpec = prepareSpec(spec)
+
   // якщо не існує consumer-а створюємо його. якщо є перевіримо чи відповідає spec(якщо ні, то перестворюємо або оновлюємо)
   if (consumer) {
     log.info(`✅ Consumer «${spec.durableName}» already exists`)
 
-    const { filter_subjects, deliver_policy, ack_policy } = consumer.config
+    const { filter_subjects, deliver_policy, ack_policy, ack_wait } = consumer.config
 
     // якщо 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)
+      const tempSpec = preparedSpec
+      tempSpec.durable_name = `temp_${preparedSpec.durable_name}`
+
+      // Цей “тимчасовий consumer” потрібен як страховка на час перестворення,
+      // щоб не втратити повідомлення у стрімі з retention: 'interest'
+      await jsm.consumers.add(spec.streamName, tempSpec)
       // delete old consumer
-      await jsm.consumers.delete(streamName, spec.durableName)
+      await jsm.consumers.delete(spec.streamName, spec.durableName)
       // create new consumer
-      await createConsumer(streamName, spec)
+      await jsm.consumers.add(spec.streamName, preparedSpec)
+
       // delete temp consumer
-      await jsm.consumers.delete(streamName, tempSpec.durableName)
+      await jsm.consumers.delete(spec.streamName, tempSpec.durable_name)
 
       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()))
+      compareArrays(spec.filterSubjects, filter_subjects) &&
+      (spec.ackWait === undefined || spec.ackWait === millis(ack_wait ?? 0))
     ) {
-      await jsm.consumers.update(streamName, spec.durableName, {
-        filter_subjects: spec.filterSubjects.map(fs => `${streamName}.${fs}`)
-      })
-
-      log.info(`🔥 Consumer «${spec.durableName}» - updated`)
-    } else {
       log.info(`✅ Consumer «${spec.durableName}» - no changes`)
+    } else {
+      await jsm.consumers.update(spec.streamName, spec.durableName, preparedSpec)
+
+      log.info(`🔥 Consumer «${spec.durableName}»  filter_subjects - updated`)
     }
   } else {
-    await createConsumer(streamName, spec)
+    await jsm.consumers.add(spec.streamName, preparedSpec)
     log.info(`🔥 Consumer «${spec.durableName}» created`)
   }
 }
 
 /**
- * Створює consumer для stream
- * @param {string} streamName - назва stream
+ * Підготовляє специфікацію consumer-а для створення
  * @param {object} spec - специфікація consumer-а
- * @param {string} spec.durableName - назва consumer-а
- * @param {string[]} spec.filterSubjects - масив subject-ів для фільтрації
- * @param {string} spec.deliverPolicy - політика доставки
- * @param {string} spec.ackPolicy - політика підтвердження
- * @returns {Promise<void>}
+ * @returns {object} підготовлена специфікація
  */
-async function createConsumer(streamName, spec) {
-  await jsm.consumers.add(streamName, {
+function prepareSpec(spec) {
+  const preparedSpec = {
     durable_name: spec.durableName,
     ack_policy: spec.ackPolicy, // якщо не підтвердити повідомлення, воно буде повторно надіслано
-    filter_subjects: spec.filterSubjects.map(fs => `${streamName}.${fs}`), // якщо не вказати, то consumer буде слухати всі повідомлення зі stream
+    filter_subjects: spec.filterSubjects,
     deliver_policy: spec.deliverPolicy // 'all' - всі непрочитані повідомлення
-  })
+  }
+  if (spec.ackWait) {
+    preparedSpec.ack_wait = nanos(spec.ackWait)
+  }
+  return preparedSpec
+}
+/**
+ * Перевіряє наявність або створює JetStream stream.
+ * @param {string} streamName - назва stream
+ * @returns {Promise<void>}
+ */
+async function ensureStream(streamName) {
+  try {
+    const info = await jsm.streams.info(streamName)
+    // Перевіряємо, чи stream підтримує rollup
+
+    if (!info.config.allow_rollup_hdrs) {
+      log.warn(
+        `⚠️  Stream «${streamName}» не має увімкненого allow_rollup_hdrs. Для використання Nats-Rollup заголовка потрібно видалити stream і створити його заново з allow_rollup_hdrs: true`
+      )
+    }
+    log.info('✅ Stream already exists')
+  } catch {
+    await jsm.streams.add({
+      name: streamName,
+      subjects: [`${streamName}.>`],
+      retention: 'interest', // зберігає повідомлення поки є consumers або поки всі повідомлення не будуть прочитані
+      num_replicas: 1, // означає, що stream не реплікується — підходить для локальної розробки. Для продакшену в кластері зазвичай використовують 3 або 5.
+      storage: 'file', // 'memory'
+      allow_rollup_hdrs: true // дозволяє використання заголовка Nats-Rollup для автоматичного видалення старих повідомлень
+    })
+    log.info('✅ Stream created')
+  }
+}
+
+/**
+ * Порівнює два масиви
+ * @param {string[]} a - перший масив
+ * @param {string[]} b - другий масив
+ * @returns {boolean} - чи масиви рівні, true - рівні, false - не рівні
+ */
+const compareArrays = (a, b) => {
+  if (a.length !== b.length) return false
+  const setB = new Set(b)
+  return a.every(v => setB.has(v))
 }

package/src/index.js

@@ -1,4 +1,3 @@
 export { publish } from './publish.js'
-export { read } from './worker.js'
-export { finish } from './finish.js'
+export { read, finish } from './worker.js'
 export { getPendingCount } from './pending-count.js'

package/src/nats.js

@@ -61,7 +61,7 @@ if (env.NATS_FAKE_DATA) {
     }
   }
 } else {
-  checkEnv(['NATS_URL', 'NATS_STREAM'])
+  checkEnv(['NATS_URL'])
 
   // Connect to NATS
   nc = await connect({ servers: env.NATS_URL })
@@ -72,6 +72,3 @@ if (env.NATS_FAKE_DATA) {
   // Менеджер JetStream (для створення стрімів, конфігурацій тощо)
   jsm = await jetstreamManager(nc)
 }
-
-// Stream name
-export const stream = env.NATS_STREAM

package/src/pending-count.js

@@ -1,6 +1,7 @@
-import { jsm, stream } from './nats.js'
+import { jsm } from './nats.js'
 import { log } from '@nitra/pino'
 import { env } from 'node:process'
+import { stream } from './stream.js'
 
 /**
  * Повертає кількість непрочитаних (pending) повідомлень для durable consumer.

package/src/publish.js

@@ -1,9 +1,10 @@
 import { log } from '@nitra/pino'
 import { env } from 'node:process'
-import { js, stream } from './nats.js'
+import { js } from './nats.js'
 import { checkSubjectFormat } from './utils.js'
 import { headers } from '@nats-io/nats-core'
 import { createHash } from 'node:crypto'
+import { stream } from './stream.js'
 
 /**
  * Публікує повідомлення у JetStream для вказаного subject.
@@ -19,8 +20,8 @@ export async function publish(subject, data, options = {}) {
     return
   }
 
-  // перевіряємо чи subject відповідає формату project:subject
-  checkSubjectFormat(subject)
+  // перевіряємо чи subject відповідає формату stream.project:subject
+  checkSubjectFormat(stream, `${stream}.${subject}`)
 
   log.debug('publish:', data)
   const payload = JSON.stringify(data)

package/src/stream.js

@@ -1,31 +1,8 @@
-import { log } from '@nitra/pino'
-import { jsm, stream } from './nats.js'
+import { checkEnv } from '@nitra/check-env'
+import { env } from 'node:process'
 
-/**
- * Перевіряє наявність або створює JetStream stream.
- * @param {string} streamName - назва stream
- * @returns {Promise<void>}
- */
-export async function ensureStream(streamName = stream) {
-  try {
-    const info = await jsm.streams.info(streamName)
-    // Перевіряємо, чи stream підтримує rollup
-
-    if (!info.config.allow_rollup_hdrs) {
-      log.warn(
-        `⚠️  Stream «${streamName}» не має увімкненого allow_rollup_hdrs. Для використання Nats-Rollup заголовка потрібно видалити stream і створити його заново з allow_rollup_hdrs: true`
-      )
-    }
-    log.debug('✅ Stream already exists')
-  } catch {
-    await jsm.streams.add({
-      name: streamName,
-      subjects: [`${streamName}.>`],
-      retention: 'interest', // зберігає повідомлення поки є consumers або поки всі повідомлення не будуть прочитані
-      num_replicas: 1, // означає, що stream не реплікується — підходить для локальної розробки. Для продакшену в кластері зазвичай використовують 3 або 5.
-      storage: 'file', // 'memory'
-      allow_rollup_hdrs: true // дозволяє використання заголовка Nats-Rollup для автоматичного видалення старих повідомлень
-    })
-    log.debug('✅ Stream created')
-  }
+// якщо не задані демо дані, то перевіряємо чи задана назва stream
+if (!env.NATS_FAKE_DATA) {
+  checkEnv(['NATS_STREAM'])
 }
+export const stream = env.NATS_STREAM

package/src/utils.js

@@ -1,15 +1,22 @@
 /**
- * Перевіряє чи subject має правильний формат: projectName:subjectName
+ * Перевіряє чи subject має правильний формат: stream.project.subject
+ * @param {string} stream - назва stream
  * @param {string} subject - subject для перевірки
  * @throws {Error} - якщо subject не відповідає формату
  */
-export const checkSubjectFormat = subject => {
-  const arr = subject?.split(':')
+export const checkSubjectFormat = (stream, subject) => {
+  const arr = subject.split('.')
 
-  if (arr?.length !== 2 || !arr[0] || !arr[1]) {
-    throw new Error('subject must be in the format: projectName:subjectName')
+  if (arr?.length < 2 || !arr[0] || !arr[1]) {
+    throw new Error('subject must be in the format: stream.project:subject')
+  }
+
+  const theme = arr[1].split(':')
+  if (theme?.length < 2) {
+    throw new Error('subject must be in the format: stream.project:subject')
   }
-}
 
-// state variables
-export const state = { msg: null, isFinished: false }
+  if (arr[0] !== stream) {
+    throw new Error(`${arr[0]} - stream must be - ${stream}`)
+  }
+}

package/src/worker.js

@@ -1,35 +1,47 @@
 import { log } from '@nitra/pino'
 import { env, exit } from 'node:process'
-import { js, stream } from './nats.js'
-import { state } from './utils.js'
+import { js } from './nats.js'
+import { stream } from './stream.js'
 
 // Кешуємо результат перевірки фейкових даних
-const FAKE_DATA = env.NATS_FAKE_DATA ? JSON.parse(env.NATS_FAKE_DATA) : null
+let FAKE_DATA
+if (env.NATS_FAKE_DATA) {
+  try {
+    FAKE_DATA = JSON.parse(env.NATS_FAKE_DATA)
+  } catch (error) {
+    log.error('Failed to parse fake data', { error, data: env.NATS_FAKE_DATA })
+    throw new Error(`Invalid JSON in fake data: ${error.message}`)
+  }
+}
 
 // Флаг для відстеження чи вже зареєстровані обробники подій
-let handlersRegistered = false
+// let handlersRegistered = false
 
 /**
  * Обробник завершення процесу - відправляє повідомлення назад в чергу якщо воно не було підтверджене
  */
-const handleExit = () => {
-  if (!state.isFinished && state.msg) {
-    state.msg.nak()
-  }
-}
+// const handleExit = () => {
+//   if (!state.isFinished && state.msg) {
+//     state.msg.nak()
+//   }
+// }
 
 /**
  * Реєструє обробники подій для автоматичного NAK при завершенні процесу
  */
-function registerExitHandlers() {
-  if (handlersRegistered) return
-  handlersRegistered = true
+// function registerExitHandlers() {
+//   if (handlersRegistered) return
+//   handlersRegistered = true
 
-  // Реєструємо хук на завершення процесу. якщо не підтвердили повідомлення або помилка - відправляємо повідомлення назад в чергу
-  for (const signal of ['exit', 'SIGINT', 'uncaughtException', 'unhandledRejection']) {
-    process.once(signal, handleExit)
-  }
-}
+//   // Реєструємо хук на завершення процесу. якщо не підтвердили повідомлення або помилка - відправляємо повідомлення назад в чергу
+//   for (const signal of ['exit', 'SIGINT', 'uncaughtException', 'unhandledRejection']) {
+//     process.once(signal, handleExit)
+//   }
+// }
+
+// state variables
+// const state = { msg: null, isFinished: false }
+let msg = null
 
 /**
  * Зчитує одне повідомлення з JetStream для вказаного consumer-а.
@@ -39,33 +51,53 @@ function registerExitHandlers() {
 export async function read(consumer) {
   // якщо задані демо дані, то повертаємо їх
   if (FAKE_DATA) {
-    console.log('env.NATS_FAKE_DATA:', env.NATS_FAKE_DATA)
+    log.info('env.NATS_FAKE_DATA:', env.NATS_FAKE_DATA)
     return FAKE_DATA
   }
 
   const consumerObj = await js.consumers.get(stream, consumer)
 
   const iter = await consumerObj.fetch({ max_messages: 1, expires: 1000 })
-  for await (const msg of iter) {
-    state.msg = msg
+  for await (const msgI of iter) {
+    msg = msgI
 
     let decoded
     try {
       decoded = JSON.parse(msg.data)
     } catch (error) {
       log.error('Failed to parse message data', { error, data: msg.data })
-      msg.nak() // Повертаємо повідомлення назад в чергу при помилці парсингу
+      msg.ack() // НЕ повертаємо повідомлення назад в чергу при помилці парсингу, бо зациклиться
       throw new Error(`Invalid JSON in message: ${error.message}`)
     }
 
     log.debug('read msg', decoded)
 
     // Реєструємо обробники подій один раз
-    registerExitHandlers()
+    // registerExitHandlers()
 
+    // Оброблюємо тільки перше повідомлення
     return decoded
   }
 
   log.info(`${consumer} - no msg...`)
   exit(0) // якщо не було жодного повідомлення
 }
+
+/**
+ * Підтверджує (ack) останнє прочитане повідомлення.
+ * Якщо не викликати, повідомлення буде повернуто у чергу (nak).
+ * @returns {Promise<void>}
+ */
+export const finish = async () => {
+  // oxlint-disable-next-line require-await
+  return msg?.ack()
+}
+
+/**
+ * Повертає повідомлення назад в чергу (nak).
+ * @returns {Promise<void>}
+ */
+export const nak = async () => {
+  // oxlint-disable-next-line require-await
+  return msg?.nak()
+}

package/src/finish.js

@@ -1,13 +0,0 @@
-import { state } from './utils.js'
-
-/**
- * Підтверджує (ack) останнє прочитане повідомлення.
- * Якщо не викликати, повідомлення буде повернуто у чергу (nak).
- * @returns {Promise<void>}
- */
-export const finish = async () => {
-  if (state.msg) {
-    await state.msg.ack()
-    state.isFinished = true
-  }
-}