@nitra/nats 4.0.2 → 4.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @nitra/nats
 
-NATS JetStream helper для Node.js
+NATS JetStream helper для Node.js.1
 Простий API для публікації, обробки та моніторингу повідомлень у черзі з гнучким управлінням consumer-ами через конфігурацію та CLI інструменти.
 
 ---
@@ -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):**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nitra/nats",
   "description": "nats helper",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "type": "module",
   "files": [
     "src"
@@ -24,10 +24,12 @@
   "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.9.1",
+    "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) {

package/src/consumer.js

@@ -4,7 +4,12 @@ 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) {
@@ -59,6 +64,16 @@ export async function ensureConsumer(spec) {
   }
 }
 
+/**
+ * Створює consumer для stream
+ * @param {string} streamName - назва stream
+ * @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>}
+ */
 async function createConsumer(streamName, spec) {
   await jsm.consumers.add(streamName, {
     durable_name: spec.durableName,

package/src/nats.js

@@ -1,18 +1,63 @@
 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 {
@@ -20,16 +65,13 @@ if (env.NATS_FAKE_DATA) {
 
   // Connect to NATS
   nc = await connect({ servers: env.NATS_URL })
-}
-
-// JSONCodec
-export const jc = JSONCodec()
 
-// Створюємо JetStream контекст
-export const js = nc.jetstream()
+  // Створюємо JetStream контекст
+  js = jetstream(nc)
 
-// Менеджер JetStream (для створення стрімів, конфігурацій тощо)
-export const jsm = await nc.jetstreamManager()
+  // Менеджер JetStream (для створення стрімів, конфігурацій тощо)
+  jsm = await jetstreamManager(nc)
+}
 
 // Stream name
 export const stream = env.NATS_STREAM

package/src/publish.js

@@ -1,16 +1,19 @@
 import { log } from '@nitra/pino'
 import { env } from 'node:process'
-import { jc, js, stream } from './nats.js'
+import { js, stream } from './nats.js'
 import { checkSubjectFormat } from './utils.js'
+import { headers } from '@nats-io/nats-core'
+import { createHash } from 'node:crypto'
 
 /**
  * Публікує повідомлення у 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
@@ -20,6 +23,34 @@ export async function publish(subject, data) {
   checkSubjectFormat(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

@@ -3,20 +3,28 @@ import { jsm, stream } from './nats.js'
 
 /**
  * Перевіряє наявність або створює JetStream stream.
- * @param streamName
+ * @param {string} streamName - назва stream
  * @returns {Promise<void>}
  */
 export async function ensureStream(streamName = stream) {
   try {
-    await jsm.streams.info(streamName)
+    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 або поки всі повідомлення не будуть прочитані
-      replicas: 1, // кількість реплік у кластері TODO: проговорити кількість реплік
-      storage: 'file' //'memory' TODO: проговорити які параметри потрібні для кластера
+      num_replicas: 1, // означає, що stream не реплікується — підходить для локальної розробки. Для продакшену в кластері зазвичай використовують 3 або 5.
+      storage: 'file', // 'memory'
+      allow_rollup_hdrs: true // дозволяє використання заголовка Nats-Rollup для автоматичного видалення старих повідомлень
     })
     log.debug('✅ Stream created')
   }

package/src/worker.js

@@ -1,8 +1,36 @@
 import { log } from '@nitra/pino'
 import { env, exit } from 'node:process'
-import { jc, js, stream } from './nats.js'
+import { js, stream } from './nats.js'
 import { state } from './utils.js'
 
+// Кешуємо результат перевірки фейкових даних
+const FAKE_DATA = env.NATS_FAKE_DATA ? JSON.parse(env.NATS_FAKE_DATA) : null
+
+// Флаг для відстеження чи вже зареєстровані обробники подій
+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)
+  }
+}
+
 /**
  * Зчитує одне повідомлення з JetStream для вказаного consumer-а.
  * @param {string} consumer - durable_name для consumer(за замовчуванням durable_name = subject)
@@ -10,9 +38,9 @@ import { state } from './utils.js'
  */
 export async function read(consumer) {
   // якщо задані демо дані, то повертаємо їх
-  if (env.NATS_FAKE_DATA) {
+  if (FAKE_DATA) {
     console.log('env.NATS_FAKE_DATA:', env.NATS_FAKE_DATA)
-    return JSON.parse(env.NATS_FAKE_DATA)
+    return FAKE_DATA
   }
 
   const consumerObj = await js.consumers.get(stream, consumer)
@@ -20,14 +48,22 @@ export async function read(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 (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.nak() // Повертаємо повідомлення назад в чергу при помилці парсингу
+      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...`)