@nitra/nats 4.0.3 → 4.2.0

package/README.md

@@ -150,23 +150,19 @@ console.log('pending for group:', count2)
 ## Як це працює
 
 - **publish(subject, data):**
-
   - Публікує повідомлення у subject `${stream}.${subject}`
   - Перевіряє формат subject (має бути `project:subject`)
 
 - **ensureConsumer(spec):**
-
   - Створює consumer якщо не існує
   - Оновлює `filter_subjects` якщо вони змінились
   - Перестворює consumer якщо змінились `deliverPolicy` або `ackPolicy`
   - Автоматично створює stream якщо потрібно
 
 - **read(durableName):**
-
   - Читає одне повідомлення з черги для durable consumer
 
 - **finish():**
-
   - Підтверджує (ack) повідомлення
 
 - **getPendingCount(durableName):**
@@ -236,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,33 +1,35 @@
 {
   "name": "@nitra/nats",
+  "version": "4.2.0",
   "description": "nats helper",
-  "version": "4.0.3",
-  "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.8.1",
-    "js-yaml": "^4.1.1",
-    "nats": "^2.29.3"
+    "@nitra/pino": "^2.10.0",
+    "js-yaml": "^4.1.1"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/cli.js

@@ -39,7 +39,6 @@ function parseConsumerYaml() {
 /**
  * Валідує структуру парсеного consumer об'єкта
  * @param {object} consumer - Об'єкт consumer для валідації
- * @returns {boolean} true якщо валідація пройшла успішно
  * @throws {Error} Якщо валідація не пройшла
  */
 export function validateConsumer(consumer) {
@@ -54,7 +53,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,20 +1,27 @@
-import { jsm, stream } from './nats.js'
-import { ensureStream } from './stream.js'
+import { jsm } from './nats.js'
 import { log } from '@nitra/pino'
 
 /**
  * Створює або оновлює consumer.
- * @param {object{streamName: string, durableName: string, filterSubjects: string[], deliverPolicy: string, ackPolicy: string}} spec  - об'єкт consumer-а.
+ * @param {object} spec - об'єкт consumer-а
+ * @param {string} spec.streamName - назва stream
+ * @param {string} spec.durableName - назва consumer-а
+ * @param {string[]} spec.filterSubjects - масив subject-ів для фільтрації
+ * @param {string} spec.deliverPolicy - політика доставки
+ * @param {string} spec.ackPolicy - політика підтвердження
  * @returns {Promise<void>}
  */
 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}`)
+
   // якщо не існує consumer-а створюємо його. якщо є перевіримо чи відповідає spec(якщо ні, то перестворюємо або оновлюємо)
   if (consumer) {
     log.info(`✅ Consumer «${spec.durableName}» already exists`)
@@ -24,46 +31,96 @@ export async function ensureConsumer(spec) {
     // якщо deliver_policy або ack_policy не відповідають spec, то перестворюємо consumer
     if (deliver_policy !== spec.deliverPolicy || ack_policy !== spec.ackPolicy) {
       const tempSpec = {
+        streamName: spec.streamName,
         durableName: `temp_${spec.durableName}`,
-        filterSubjects: filter_subjects,
+        filterSubjects: spec.filterSubjects,
         deliverPolicy: deliver_policy,
         ackPolicy: ack_policy
       }
-      // create temp consumer with old filter_subjects
-      await createConsumer(streamName, tempSpec)
+      // Цей “тимчасовий consumer” потрібен як страховка на час перестворення,
+      // щоб не втратити повідомлення у стрімі з retention: 'interest'
+      await createConsumer(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 createConsumer(spec)
       // delete temp consumer
-      await jsm.consumers.delete(streamName, tempSpec.durableName)
+      await jsm.consumers.delete(tempSpec.streamName, tempSpec.durableName)
 
       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}`)
+    else if (compareArrays(spec.filterSubjects, filter_subjects)) {
+      log.info(`✅ Consumer «${spec.durableName}» - no changes`)
+    } else {
+      await jsm.consumers.update(spec.streamName, spec.durableName, {
+        filter_subjects: spec.filterSubjects
       })
 
-      log.info(`🔥 Consumer «${spec.durableName}» - updated`)
-    } else {
-      log.info(`✅ Consumer «${spec.durableName}» - no changes`)
+      log.info(`🔥 Consumer «${spec.durableName}»  filter_subjects - updated`)
     }
   } else {
-    await createConsumer(streamName, spec)
+    await createConsumer(spec)
     log.info(`🔥 Consumer «${spec.durableName}» created`)
   }
 }
 
-async function createConsumer(streamName, spec) {
-  await jsm.consumers.add(streamName, {
+/**
+ * Створює consumer для stream
+ * @param {object} spec - специфікація consumer-а
+ * @param {string} spec.streamName - назва stream
+ * @param {string} spec.durableName - назва consumer-а
+ * @param {string[]} spec.filterSubjects - масив subject-ів для фільтрації
+ * @param {string} spec.deliverPolicy - політика доставки
+ * @param {string} spec.ackPolicy - політика підтвердження
+ * @returns {Promise<void>}
+ */
+async function createConsumer(spec) {
+  await jsm.consumers.add(spec.streamName, {
     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' - всі непрочитані повідомлення
   })
 }
+
+/**
+ * Перевіряє наявність або створює 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

@@ -1,35 +1,74 @@
 import { checkEnv } from '@nitra/check-env'
-import { connect, JSONCodec } from 'nats'
+import { connect } from '@nats-io/transport-node'
+import { jetstream, jetstreamManager } from '@nats-io/jetstream'
 import { env } from 'node:process'
 
 // AckPolicy
-// export { AckPolicy } from 'nats'
+// export { AckPolicy } from '@nats-io/jetstream'
 
 let nc
 
+// Експортуємо JetStream контекст
+export let js
+// Експортуємо менеджер JetStream
+export let jsm
+
 // якщо задані демо дані, то використовуємо фейковий NATS
 if (env.NATS_FAKE_DATA) {
-  nc = {
-    jetstream: () => {},
-    jetstreamManager: async () => {
-      {}
+  // Створюємо фейкові об'єкти для js та jsm
+  js = {
+    publish: () => Promise.resolve(),
+    consumers: {
+      get: () => {
+        return {
+          fetch: () => {
+            return {
+              [Symbol.asyncIterator]: async function* () {
+                yield
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+  jsm = {
+    streams: {
+      info: () => {
+        return {
+          config: {
+            allow_rollup_hdrs: true
+          }
+        }
+      },
+      add: () => Promise.resolve()
+    },
+    consumers: {
+      info: () => {
+        return {
+          num_pending: 0,
+          num_ack_pending: 0
+        }
+      },
+      list: () => {
+        return {
+          next: () => []
+        }
+      },
+      delete: () => Promise.resolve(),
+      update: () => Promise.resolve(),
+      add: () => Promise.resolve()
     }
   }
 } else {
-  checkEnv(['NATS_URL', 'NATS_STREAM'])
+  checkEnv(['NATS_URL'])
 
   // Connect to NATS
   nc = await connect({ servers: env.NATS_URL })
-}
 
-// JSONCodec
-export const jc = JSONCodec()
+  // Створюємо JetStream контекст
+  js = jetstream(nc)
 
-// Створюємо JetStream контекст
-export const js = nc.jetstream()
-
-// Менеджер JetStream (для створення стрімів, конфігурацій тощо)
-export const jsm = await nc.jetstreamManager()
-
-// Stream name
-export const stream = env.NATS_STREAM
+  // Менеджер JetStream (для створення стрімів, конфігурацій тощо)
+  jsm = await jetstreamManager(nc)
+}

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,25 +1,57 @@
 import { log } from '@nitra/pino'
 import { env } from 'node:process'
-import { jc, 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.
  * @param {string} subject - subject у форматі project:subject
  * @param {object} data - дані для публікації
+ * @param {object} options - опції публікації
  * @returns {Promise<void>}
  */
 //   oxlint-disable-next-line require-await
-export async function publish(subject, data) {
+export async function publish(subject, data, options = {}) {
   // якщо задані демо дані, то ігноримо запис
   if (env.NATS_FAKE_DATA) {
     return
   }
 
-  // перевіряємо чи subject відповідає формату project:subject
-  checkSubjectFormat(subject)
+  // перевіряємо чи subject відповідає формату stream.project:subject
+  checkSubjectFormat(stream, `${stream}.${subject}`)
 
   log.debug('publish:', data)
+  const payload = JSON.stringify(data)
+  let suffix = ''
+
+  // якщо не задано опції, то використовуємо default опції
+  if (Object.keys(options).length === 0) {
+    // headers always have their names turned into a canonical mime header key
+    // header names can be any printable ASCII character with the  exception of `:`.
+    // header values can be any ASCII character except `\r` or `\n`.
+    // see https://www.ietf.org/rfc/rfc822.txt
+    const h = headers()
+    h.set('Nats-Rollup', 'sub')
+    options.headers = h
+
+    suffix = `.${hash(payload)}`
+  }
+  // log.debug('options:', options)
+  // log.debug('suffix:', suffix)
+
   // Publish message
-  return js.publish(`${stream}.${subject}`, jc.encode(data))
+  return js.publish(`${stream}.${subject}${suffix}`, payload, options || {})
+}
+
+/**
+ * Створює MD5 хеш з тексту та повертає його в форматі base64url.
+ * Використовується для дедуплікації повідомлень через суфікс у subject.
+ * @param {string} text - текст для хешування
+ * @returns {string} - хеш у форматі base64url
+ */
+function hash(text) {
+  return createHash('md5').update(text, 'utf8').digest('base64url')
 }

package/src/stream.js

@@ -1,23 +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 streamName
- * @returns {Promise<void>}
- */
-export async function ensureStream(streamName = stream) {
-  try {
-    await jsm.streams.info(streamName)
-    log.debug('✅ Stream already exists')
-  } catch {
-    await jsm.streams.add({
-      name: streamName,
-      subjects: [`${streamName}.>`],
-      retention: 'interest', // зберігає повідомлення поки є consumers або поки всі повідомлення не будуть прочитані
-      replicas: 1, // кількість реплік у кластері TODO: проговорити кількість реплік
-      storage: 'file' //'memory' TODO: проговорити які параметри потрібні для кластера
-    })
-    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,7 +1,47 @@
 import { log } from '@nitra/pino'
 import { env, exit } from 'node:process'
-import { jc, js, stream } from './nats.js'
-import { state } from './utils.js'
+import { js } from './nats.js'
+import { stream } from './stream.js'
+
+// Кешуємо результат перевірки фейкових даних
+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
+
+/**
+ * Обробник завершення процесу - відправляє повідомлення назад в чергу якщо воно не було підтверджене
+ */
+// const handleExit = () => {
+//   if (!state.isFinished && state.msg) {
+//     state.msg.nak()
+//   }
+// }
+
+/**
+ * Реєструє обробники подій для автоматичного NAK при завершенні процесу
+ */
+// function registerExitHandlers() {
+//   if (handlersRegistered) return
+//   handlersRegistered = true
+
+//   // Реєструємо хук на завершення процесу. якщо не підтвердили повідомлення або помилка - відправляємо повідомлення назад в чергу
+//   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-а.
@@ -10,26 +50,54 @@ import { state } from './utils.js'
  */
 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)
+  if (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
-    log.debug('read msg', jc.decode(msg.data))
+  for await (const msgI of iter) {
+    msg = msgI
 
-    // Реєструємо хук на завершення процесу. якщо не підтвердили повідомлення або помилка - відправляємо повідомлення назад в чергу
-    for (const signal of ['exit', 'SIGINT', 'uncaughtException', 'unhandledRejection']) {
-      process.once(signal, () => !state.isFinished && state.msg && state.msg.nak())
+    let decoded
+    try {
+      decoded = JSON.parse(msg.data)
+    } catch (error) {
+      log.error('Failed to parse message data', { error, data: msg.data })
+      msg.ack() // НЕ повертаємо повідомлення назад в чергу при помилці парсингу, бо зациклиться
+      throw new Error(`Invalid JSON in message: ${error.message}`)
     }
 
-    return jc.decode(msg.data)
+    log.debug('read msg', decoded)
+
+    // Реєструємо обробники подій один раз
+    // 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
-  }
-}