{"id":20485269,"url":"https://github.com/runnable/hermes","last_synced_at":"2025-04-13T14:53:15.111Z","repository":{"id":30203233,"uuid":"33754161","full_name":"Runnable/hermes","owner":"Runnable","description":"Runnable job queuing system interface abstraction for runnable's services","archived":false,"fork":false,"pushed_at":"2017-05-26T15:32:35.000Z","size":141,"stargazers_count":3,"open_issues_count":57,"forks_count":1,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-11T02:44:26.408Z","etag":null,"topics":[],"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/Runnable.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-10T22:48:44.000Z","updated_at":"2022-05-08T10:39:13.000Z","dependencies_parsed_at":"2022-08-28T23:22:23.788Z","dependency_job_id":null,"html_url":"https://github.com/Runnable/hermes","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Runnable%2Fhermes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Runnable%2Fhermes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Runnable%2Fhermes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Runnable%2Fhermes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Runnable","download_url":"https://codeload.github.com/Runnable/hermes/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248732509,"owners_count":21152851,"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":[],"created_at":"2024-11-15T16:29:07.102Z","updated_at":"2025-04-13T14:53:15.090Z","avatar_url":"https://github.com/Runnable.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Hermes\n======\n\nSimplified abstraction interface to [amqp.node](https://github.com/squaremo/amqp.node)\n\n[![Build Status](https://travis-ci.org/Runnable/hermes.svg)](https://travis-ci.org/Runnable/hermes)\n[![Code Climate](https://codeclimate.com/github/Runnable/hermes/badges/gpa.svg)](https://codeclimate.com/github/runnable/hermes)\n[![Test Coverage](https://codeclimate.com/github/Runnable/hermes/badges/coverage.svg)](https://codeclimate.com/github/runnable/hermes)\n[![Dependency Status](https://david-dm.org/Runnable/hermes.svg)](https://david-dm.org/runnable/hermes)\n[![devDependency Status](https://david-dm.org/Runnable/hermes/dev-status.svg)](https://david-dm.org/runnable/hermes#info=devDependencies)\n\n[![NPM](https://nodei.co/npm/runnable-hermes.png?compact=true)](https://nodei.co/npm/runnable-hermes/)\n[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/Runnable/hermes?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge)\n\nPublish \u0026 subscribe to RabbitMQ queues with simplified publish \u0026 subscribe interface\nmethods.\n\n- Connects to RabbitMQ server, establishes a channel, asserts defined queues\n  - Queues will be created as `durabale` queues, not `transient`. `persistent` messages will be saved to disk and survivie broker restarts. [Queue Durability](https://www.rabbitmq.com/tutorials/amqp-concepts.html#queue-durability)\n- Automatically buffers publish \u0026 subscribe calls until connection is established. (No need to wait for connection to be established before using `publish` or `subscribe` methods from your application.)\n- Tracks references to subscribe callbacks and provides functionality to stop receiving jobs for one or all task queues. (Very similar to EventEmitter unsubscribe functionality)\n- Automatically encodes objects/strings as buffers on publish and decodes to JS Object literals for subscribe callbacks\n- Provides subscribe callback with simplified `done` method to send ack message to RabbitMQ and remove tasks from queue\n\nUSAGE\n-----\n```js\n/**\n * Hermes attempts to connect to RabbitMQ upon instantiation,\n * throws if connection fails.\n * If using Events, Hermes will throw if binding or asserting failed\n * during connections\n */\nvar hermes = require('runnable-hermes').hermesSingletonFactory({\n  name: 'service name',\n  hostname: 'localhost',\n  port: '5672',\n  username: 'guest',\n  password: 'guest',\n  heartbeat: 10, // default 0 (no timeout)\n  persistent: true, // default true (messages will survive a broker restart event)\n  prefetch: 10 // sets the consumer prefetch for the channel (default to not being applied)\n  queues: [ // queues to self-register with RabbitMQ on connect\n    'task-queue-1',\n    'task-queue-2'\n  ],\n  publishedEvents: [ // publish to fanout exchange\n    'task-queue-3',\n    'task-queue-4'\n  ],\n  subscribedEvents: [ // read from fanout exchanges\n    'task-queue-5',\n    'task-queue-6'\n  ]\n}).connect();\n\nvar jobCallback = function (data, done) { //data automatically decoded into object or string\n  // perform operation w/ data\n  done(); // remove job from RabbitMQ queue\n};\n\n/**\n * Hermes will auto-queue subscribe \u0026 publish calls if\n * connection to RabbitMQ has not yet been established\n *\n * Will throw if first argument is not a string representing\n * a valid RabbitMQ queue as defined in `queues`,\n * `publishedEvents`, or `subscribedEvents` options\n * passed to the constructor\n *\n * @param {String} queue name\n * @param {Function} queue consumer callback\n */\nhermes.subscribe('valid-queue-name', jobCallback);\n\n/**\n * Insert job into queue w/ associated job data.\n *\n * @param {String} queue name\n * @param {Object|String} task data (automatically encoded as Buffer for transmisison to RabbitMQ, will be automatically decoded in subscribe)\n */\nhermes.publish('valid-queue-name', {foo: 'bar'});\n\n/**\n * Remove bounded functions from queue events (abstracts AMQP cancel \u0026 consumerTags)\n *\n * @param {String} queue name\n * @param {Function} reference to queue consumer callback used as argument to `hermes.subscribe`\n * @param {Function} callback, invoked when queue consumer callback is no longer consuming from queue\n */\nhermes.unsubscribe('valid-queue-name', jobCallback, function (err) {\n  // invoked when worker removed from RabbitMQ\n});\n// also, you can optionally remove all workers in a queue by providing null instead of a reference to a single queue consumer callback\nhermes.unsubscribe('valid-queue-name', null, function (err) {});\n\n/**\n * Disconnecting \u0026 reconnecting\n */\nhermes.close(cb);\nhermes.connect(cb);\n\n/**\n * Fetch an array of valid queues\n * @returns Array\u003cString\u003e\n */\nvar queues = hermes.getQueues();\n\n/**\n * Hermes class extends events.EventEmitter and emits the following events:\n *   - 'publish'\n *   - 'subscribe'\n *   - 'unsubscribe'\n *   - 'error'\n *   - 'ready'\n * Examples:\n */\nhermes\n  .connect()\n  .on('ready', function () {\n  console.log('hermes connected to RabbitMQ \u0026 queues asserted');\n});\n\nhermes.on('publish', function (queueName, data) {\n  console.log('hermes publish action', queueName, data);\n});\nhermes.publish('valid-queue-name', {foo: 'bar'});\n\nhermes.on('subscribe', function (queueName, handlerFn) {\n  // Event listener recieves queueName and reference to assigned handler function\n  console.log('hermes subscribe action', queueName, handlerFn);\n});\nhermes.subscribe('valid-queue-name', subscribeCallback);\n\nhermes.unsubscribe('valid-queue-name', null, unsubscribeAllCallback);\nhermes.on('unsubscribe', function (queueName, handlerFn) {\n  // Invoked once per task-handler callback that is unsubscribed\n  // Event listener recieves queueName and reference to assigned handler function\n  console.log('hermes unsubscribe action', queueName, handlerFn);\n});\n```\n\nTESTS\n-----\n - Tests \u0026 coverage are run using Lab\n```\n$ npm test\n$ npm run test-cov # will auto open Google Chrome\n```\n\nLICENSE\n-------\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunnable%2Fhermes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frunnable%2Fhermes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunnable%2Fhermes/lists"}