@nitra/nats 3.0.4

package/README.md

@@ -0,0 +1,136 @@
+# @nitra/nats
+
+NATS JetStream helper для Node.js.  
+Простий API для публікації, обробки та моніторингу повідомлень у черзі з автоматичним створенням stream/consumer для кожного subject.
+
+---
+
+## Встановлення
+
+```sh
+yarn add @nitra/nats
+# або
+npm install @nitra/nats
+```
+
+---
+
+## Налаштування змінних середовища
+
+Пакет використовує такі змінні середовища:
+
+- `NATS_SERVER` — адреса сервера NATS (наприклад, `nats://localhost:4222`)
+
+---
+
+## Формат subject
+
+Всі функції працюють із subject у форматі:
+
+```
+projectName:subjectName
+```
+
+---
+
+**Приклади:**
+
+- `myproject:jobs`
+- `service:notifications`
+
+---
+
+## Публікація повідомлення
+
+```js
+import { publish } from '@nitra/nats'
+
+await publish('project:subject', { id: 1, foo: 'bar' })
+```
+
+- Stream буде створено автоматично, якщо не існує.
+- Повідомлення публікується у subject `stream.project:subject`.
+
+---
+
+## Обробка повідомлення (worker)
+
+```js
+import { read, finish } from '@nitra/nats'
+
+const data = await read('project:subject')
+// ...обробка data...
+await finish() // підтвердження (ack) повідомлення
+```
+
+- Якщо не викликати `finish()`, повідомлення буде повернуто у чергу (`nak`) при завершенні процесу або помилці.
+- Stream і consumer створюються автоматично при першому запуску воркера для кожного subject.
+
+---
+
+## Кількість непрочитаних повідомлень для subject
+
+```js
+import { getPendingCount } from '@nitra/nats'
+
+const count = await getPendingCount('project:subject')
+console.log('pending:', count)
+```
+
+- Якщо consumer для subject ще не існує, він буде створений автоматично.
+
+---
+
+## Як це працює
+
+- **publish(subject, data):**
+
+  - Перевіряє/створює stream (один раз за процес).
+  - Публікує повідомлення у subject `stream.${subject}`.
+
+- **read(subject):**
+
+  - Перевіряє/створює stream і consumer для subject (один раз за процес).
+  - Читає одне повідомлення з черги для subject.
+
+- **finish():**
+
+  - Підтверджує (ack) повідомлення.
+
+- **getPendingCount(subject):**
+  - Повертає кількість непрочитаних повідомлень для consumer `durable_${subject}` (створює його, якщо не існує).
+
+---
+
+## Важливо
+
+- STREAM у NATS завжди один (`stream`), але subject динамічний.
+- Для кожного subject створюється окремий durable consumer з іменем `durable_${subject}`.
+- Пакет розрахований на single-message workflow (одне повідомлення на читання за раз, публікація - необмежена).
+- Для паралельної обробки або кастомних сценаріїв — дивись вихідний код та розширюй під свої задачі.
+
+---
+
+## Приклад повного workflow
+
+```js
+import { publish, read, finish, getPendingCount } from '@nitra/nats'
+
+// Публікація
+await publish('project:subject', { id: 1, prop: 'prop' })
+
+// Pending для subject
+const count = await getPendingCount('project:subject')
+console.log('pending:', count)
+
+// Читання
+const data = await read('project:subject')
+console.log('read:', data)
+await finish()
+```
+
+---
+
+## Ліцензія
+
+MIT

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@nitra/nats",
+  "description": "nats helper",
+  "version": "3.0.4",
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "keywords": [
+    "nitra",
+    "nats"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nitra/nats.git"
+  },
+  "bugs": "https://github.com/nitra/nats/issues",
+  "homepage": "https://github.com/nitra/nats",
+  "license": "MIT",
+  "dependencies": {
+    "@nitra/check-env": "^3.2.0",
+    "@nitra/isenv": "^2.0.1",
+    "@nitra/pino": "^1.5.1",
+    "nats": "^2.29.3"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/src/consumer.js

@@ -0,0 +1,21 @@
+import { jsm, AckPolicy } from './nats.js'
+
+/**
+ * Перевіряє наявність або створює durable consumer для subject.
+ * @param {string} subject - subject у форматі project:subject
+ * @returns {Promise<void>}
+ */
+export async function ensureConsumer(subject) {
+  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')
+  }
+}

package/src/finish.js

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

package/src/index.js

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

package/src/nats.js

@@ -0,0 +1,18 @@
+import { connect, JSONCodec } from 'nats'
+import { checkEnv, env } from '@nitra/check-env'
+// AckPolicy
+export { AckPolicy } from 'nats'
+
+checkEnv(['NATS_SERVER'])
+
+// Connect to NATS
+export const client = await connect({ servers: env.NATS_SERVER })
+
+// JSONCodec
+export const jc = JSONCodec()
+
+// Створюємо JetStream контекст
+export const js = client.jetstream()
+
+// Менеджер JetStream (для створення стрімів, конфігурацій тощо)
+export const jsm = await client.jetstreamManager()

package/src/pending-count.js

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

package/src/publish.js

@@ -0,0 +1,22 @@
+import { client, jc } from './nats.js'
+import { ensureStream } from './stream.js'
+
+let streamReady = new Set()
+
+/**
+ * Публікує повідомлення у JetStream для вказаного subject.
+ * Stream створюється автоматично, якщо не існує.
+ * @param {string} subject - subject у форматі project:subject
+ * @param {object} data - дані для публікації
+ * @returns {Promise<void>}
+ */
+export async function publish(subject, data) {
+  // Ensure stream if not exists
+  if (!streamReady.has(subject)) {
+    await ensureStream(subject)
+    streamReady.add(subject)
+  }
+  console.debug('publish', data)
+  // Publish message
+  return client.publish(`stream.${subject}`, jc.encode(data))
+}

package/src/stream.js

@@ -0,0 +1,25 @@
+import { jsm } from './nats.js'
+import { checkSubjectFormat } from './utils.js'
+
+/**
+ * Перевіряє наявність або створює JetStream stream.
+ * @param {string} subject - subject у форматі project:subject (для валідації)
+ * @returns {Promise<void>}
+ */
+export async function ensureStream(subject) {
+  checkSubjectFormat(subject)
+
+  try {
+    await jsm.streams.info('stream')
+    console.debug('✅ Stream already exists')
+  } catch {
+    await jsm.streams.add({
+      name: 'stream',
+      subjects: ['stream.>'],
+      retention: 'workqueue',
+      replicas: 1, // кількість реплік у кластері TODO: проговорити кількість реплік
+      storage: 'file' //'memory' TODO: проговорити які параметри потрібні для кластера
+    })
+    console.debug('✅ Stream created')
+  }
+}

package/src/utils.js

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

package/src/worker.js

@@ -0,0 +1,34 @@
+import { js, jc } from './nats.js'
+import { ensureStream } from './stream.js'
+import { ensureConsumer } from './consumer.js'
+import { state } from './utils.js'
+
+/**
+ * Зчитує одне повідомлення з JetStream для вказаного subject.
+ * Consumer створюється автоматично, якщо не існує.
+ * @param {string} subject - subject у форматі project:subject
+ * @returns {Promise<object>} - декодовані дані повідомлення
+ */
+export async function read(subject) {
+  // Ensure stream and consumer if not exists
+  await ensureStream(subject)
+  await ensureConsumer(subject)
+
+  const consumer = await js.consumers.get('stream', `durable_${subject}`)
+
+  const iter = await consumer.fetch({ max_messages: 1 })
+  for await (const msg of iter) {
+    state.msg = msg
+    console.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())
+    }
+
+    return jc.decode(msg.data)
+  }
+
+  console.debug('no msg...')
+  return {} // якщо не було жодного повідомлення
+}