{"id":20354351,"url":"https://github.com/hemerajs/hemera-nats-streaming","last_synced_at":"2025-04-12T02:33:12.585Z","repository":{"id":57262754,"uuid":"116398688","full_name":"hemerajs/hemera-nats-streaming","owner":"hemerajs","description":"Use nats-streaming with Hemera","archived":false,"fork":false,"pushed_at":"2019-02-20T19:54:19.000Z","size":170,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-12T02:32:12.983Z","etag":null,"topics":["bridge","hemera","nats-streaming","queue"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hemerajs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-05T15:24:43.000Z","updated_at":"2020-05-05T00:25:28.000Z","dependencies_parsed_at":"2022-09-01T04:32:00.013Z","dependency_job_id":null,"html_url":"https://github.com/hemerajs/hemera-nats-streaming","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hemerajs%2Fhemera-nats-streaming","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hemerajs%2Fhemera-nats-streaming/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hemerajs%2Fhemera-nats-streaming/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hemerajs%2Fhemera-nats-streaming/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hemerajs","download_url":"https://codeload.github.com/hemerajs/hemera-nats-streaming/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248506931,"owners_count":21115510,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bridge","hemera","nats-streaming","queue"],"created_at":"2024-11-14T23:08:19.813Z","updated_at":"2025-04-12T02:33:12.567Z","avatar_url":"https://github.com/hemerajs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hemera-nats-streaming package\n\n[![Build Status](https://travis-ci.org/hemerajs/hemera-nats-streaming.svg?branch=master)](https://travis-ci.org/hemerajs/hemera-nats-streaming)\n[![npm](https://img.shields.io/npm/v/hemera-nats-streaming.svg?maxAge=3600)](https://www.npmjs.com/package/hemera-nats-streaming)\n[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](#badge)\n\nThis is a plugin to use [NATS-Streaming](http://nats.io/) with Hemera.\nWe use the official [Node-nats-streaming](https://github.com/nats-io/node-nats-streaming) client.\nSince nats-streaming based on NATS Server you are able to run both technologies with one NATS-streaming-server.\n\n1.  [Download](http://nats.io/download/nats-io/nats-streaming-server/) and start nats-streaming-server\n2.  Start hemera and use this plugin to initialize a connection to the streaming server\n3.  You can now use hemera and nats-streaming with one server!\n\n## Install\n\n```\nnpm i hemera-nats-streaming --save\n```\n\n## Usage\n\n```js\nconst hemera = new Hemera(nats, {\n  logLevel: 'debug'\n})\nhemera.use(hemeraNatsStreaming, {\n  clusterId: 'test-cluster',\n  clientId: 'test-client',\n  options: {} // NATS/STAN options\n})\n```\n\n## Subscribe\n\nCreate a new NATS-Streaming subscription on the given subject. Under the hood all messages are forwarded to the hemera subscriber with request-reply semantics. If you create a subscription on subject `news` you will receive all messages on topic `natss.news` in hemera.\n\n```js\n  hemera.natss.add({\n    subject: 'news'\n    queue: 'news.workers', // (optional) nats-streaming queue group\n    options: {}, // (optional) nats-streaming transport options\n    pattern: {} // (optional) the pattern which arrive hemera\n})\n```\n\nReturns the [subscription](https://github.com/nats-io/node-nats-streaming/blob/7e66cf4c047742b82280a7ccb60295f449ed3b7a/lib/stan.js#L574) object of nats-streaming client.\n\n### Available options:\n\n- startWithLastReceived `(boolean)` Subscribe starting with the most recently published value\n- deliverAllAvailable `(boolean)` Receive all stored values in order\n- startAtSequence: `(integer)` Receive all messages starting at a specific sequence number\n- startTime: `(Date)` Subscribe starting at a specific time\n- startAtTimeDelta `(integer)`\n- durableName `(string)` Create a durable subscription\n- maxInFlight `(integer)` The maximum number of outstanding acknowledgements\n- manualAckMode: (`boolean`, default: `true`)\n- ackWait (`integer`, default: `30000` ms) If an acknowledgement is not received within the configured timeout interval, NATS Streaming will attempt redelivery of the message.\n\n## Publish in hemera\n\nPublish a message to NATS-Streaming server.\n\n```js\nhemera.act({\n  topic: 'natss',\n  cmd: 'publish',\n  subject: 'news',\n  data: { foo: 'bar' }\n})\n```\n\n## Subscribe in hemera\n\nCreate a NATS subscription to listen on NATS-Streaming events.\n\n```js\nhemera.add(\n  {\n    topic: 'natss.news'\n  },\n  async () =\u003e {\n    //... throw or resolve to represent the operation state\n  }\n)\n```\n\n## Plugin decorators\n\n- hemera.natss.add\n- hemera.natss.ParseError\n\n## FAQ\n\n- [`Why you don't implement nats-streaming in hemera?`](#why-you-dont-implement-nats-streaming-in-hemera)\n- [`Why we need NATS-Streaming?`](#why-we-need-nats-streaming)\n- [`What's the difference when I use NATS-Streaming directly?`](#whats-the-difference-when-I-use-nats-streaming-directly)\n\n### Why you don't implement nats-streaming in hemera?\n\nThey use the same server but the purpose is quite different with hemera we want to provide a simple toolkit without any delivery guarantee. NATS-streaming was created to fill this gap with a mimimalistic protocol extension. We can use this feature while creating a simple bridge to nats-streaming. It will create a minimal roundtrip overhead but it's tolerable. The greatest fact is that we can run both technologies side by side with one nats-streaming-server.\n\n### Why we need NATS-Streaming?\n\nUsually we would use a queue like RabbitMQ to ensure reliable message delivery but maintaining RabbitMQ as well as writing or finding a reliable driver is hard. The authors of NATS-Streaming and NATS know this and that's the reason why they made it as easy as possible.\n\n### What's the difference when I use NATS-Streaming directly?\n\nThat's good question. In NATS-Streaming there aren't request/reply semantic. If you publish something it doesn't mean that the requestor has received it but it will guarantee that the messages are persistent and replayed in the way you defined it.\n\n## Caveats\n\n- The Hemera proxy subscription can only encode/decode JSON at the moment.\n- Messages from NATS-Streaming are forwarded to a Hemera subscriber. We can only support (request / reply), (queue-group) semantic (no fanout) to ensure message acknowledgement.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhemerajs%2Fhemera-nats-streaming","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhemerajs%2Fhemera-nats-streaming","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhemerajs%2Fhemera-nats-streaming/lists"}