{"id":20348504,"url":"https://github.com/onebeyond/systemic-azure-bus","last_synced_at":"2025-04-12T01:15:19.634Z","repository":{"id":38196222,"uuid":"165238357","full_name":"onebeyond/systemic-azure-bus","owner":"onebeyond","description":"Systemic adapter for azure bus","archived":false,"fork":false,"pushed_at":"2024-01-03T15:40:50.000Z","size":1080,"stargazers_count":5,"open_issues_count":12,"forks_count":3,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-12T01:15:13.398Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/systemic-azure-bus","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/onebeyond.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-11T12:13:25.000Z","updated_at":"2023-07-13T07:23:09.000Z","dependencies_parsed_at":"2024-01-03T15:42:18.898Z","dependency_job_id":"873f370b-17f7-44a4-b3e1-af7cf66bfae7","html_url":"https://github.com/onebeyond/systemic-azure-bus","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onebeyond%2Fsystemic-azure-bus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onebeyond%2Fsystemic-azure-bus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onebeyond%2Fsystemic-azure-bus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onebeyond%2Fsystemic-azure-bus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onebeyond","download_url":"https://codeload.github.com/onebeyond/systemic-azure-bus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248501861,"owners_count":21114684,"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":["hacktoberfest"],"created_at":"2024-11-14T22:20:55.110Z","updated_at":"2025-04-12T01:15:19.582Z","avatar_url":"https://github.com/onebeyond.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CI](https://github.com/guidesmiths/systemic-azure-bus/actions/workflows/ci.yml/badge.svg)](https://github.com/guidesmiths/systemic-azure-bus/actions/workflows/ci.yml)\n[![CD](https://github.com/guidesmiths/systemic-azure-bus/actions/workflows/cd.yml/badge.svg)](https://github.com/guidesmiths/systemic-azure-bus/actions/workflows/cd.yml)\n[![Maintainability](https://api.codeclimate.com/v1/badges/14bd278dc0beaf8874b7/maintainability)](https://codeclimate.com/github/onebeyond/systemic-azure-bus/maintainability)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/14bd278dc0beaf8874b7/test_coverage)](https://codeclimate.com/github/onebeyond/systemic-azure-bus/test_coverage)\n\n# systemic-azure-bus\n\nSystemic Azure Bus is a [systemic component](https://github.com/guidesmiths/systemic) for the [Azure Service Bus SDK](https://github.com/Azure/azure-sdk-for-js). Its goal is to help you deal with azure bus topics and queues subscriptions and publications.\n\nThis library:\n\n* Enforces the client to use a particular, sensible configuration\n* Provides safe defaults for configuration\n* Exposes an easy interface for publication/subscription\n* Solves error handling\n* Allows clients to easily retry, retry with exponential backoff or dead letter a failed message\n* Opens/closes the connections\n\n## Configuration\n\nA typical, simple configuration looks like this:\n\n``` js\n{\n\tconnection: {\n\t\tconnectionString: process.env.AZURE_SERVICE_BUS_CONNECTION_STRING,\n\t},\n\tsubscriptions: {\n\t\ttopicSubscriptionName: {\n\t\t\ttopic: 'myTopic',\n\t\t\tsubscription: 'myTopic.action'\n\t\t},\n\t},\n\tpublications: {\n\t\ttopicPublicationName: {\n\t\t\ttopic: 'myDestinationTopic',\n\t\t\tcontentType: 'application/json', // optional - default is json\n\t\t},\n\t},\n}\n```\n\nNames that will included in the `topic` and `subscription` properties inside each publication / subscription object must match existing ones in your Azure service bus instance.\n\nAs for the properties `topicSubscriptionName` and `topicPublicationName` in this example, those are mere samples and can be fully customized based on your needs. Names you add to all objects you create inside of `subscriptions` and `publications` are the names that you'll use to reference a specific publication / subscription from within your source code. You can add as many topics as you need in each category.\n\n### Systemic API\n\n```js\nconst initBus = require('systemic-azure-bus');\nconst { start, stop } = initBus();\n...\nconst api = await start({ config }); // configuration similar to the one above\n```\n\n## Topics API\n\n### Publish\n\n#### Immediatly publishing a message\n\nIn order to be able to publish messages in the service bus, the `publish` method should be used to generate a function that can be called anytime to publish messages to a specific topic. We can immediatly publish a message by passing the message contents to the method returned by `publish` method, as illustrated in the example below:\n\n```js\n// Generate method to publish messages in a specific topic\nconst publicationId = 'topicPublicationName'; // declared in config\nconst publishInMyPublication = api.publish(publicationId);\n\n// Publish a message to be consumed as soon as possible\nawait publishInMyPublication(messageBody);\n```\n\n#### Schedule a message to be published at a specific moment in the future\n\nThe function returned by the `publish` method can optionally receive a second parameter with an options object. The option `scheduledEnqueueTimeUtc` can be used to delay the publication of a message so it's not consumed immediatly. Instead, message will be kept on the queue and published at an specific date.\n\n```js\n// Generate method to publish messages in a specific topic\nconst publicationId = 'topicPublicationName'; // declared in config\nconst publishInMyPublication = api.publish(publicationId);\n\n// Schedule a message to be published at a future date\nconst delayedPublishDate = new Date(Date.now() + 2000);\nawait publishInMyPublication(messageBody, { scheduledEnqueueTimeUtc: delayedPublishDate });\n```\n\n### Cancel scheduled messages\n\nA message planned to be published on a future date can be cancelled anytime by using the `cancelScheduledMessages` method. We can use this if our scheduled message became obsolete or it's no longer needed for whichever reason, so we prevent it from being sent to the subscribers.\n\nTo cancel a message it's necessary that we provide the id of a message, which we can obtain from the return value of the function used to publish the message.\n\n```js\n// Generate method to publish messages in a specific topic\nconst publicationId = 'topicPublicationName'; // declared in config\nconst publishInMyPublication = api.publish(publicationId);\n\n// Schedule a message to be published at a future date and store its id\nconst messageId = await publishInMyPublication(messageBody, { scheduledEnqueueTimeUtc: delayedPublishDate });\n\n// Cancel the message\nawait api.cancelScheduledMessages(publicationId, messageId);\n```\n\n### Subscribe\nWe provide a streaming API to subscribe to a topic and process messages flowing in. The example below illustrates how to use the `subscribe` method to be able to listen and process messages on a given topic.\n\n```js\nconst subscriptionId = 'topicSubscriptionName'; // declared in config\n\n// We need to define a function that will process messages received on this subscription\n// The `body` property will contain the actual contents of the message that were published to the service bus\nconst handleReceivedMessage = ({ body, userProperties }) =\u003e {\n \t// do something with message...\n};\n\n// We also need to define an error handling function that'll run in case we fail to process the message\nconst onMessageProcessingError = console.error;\n\n// Start listening to messages in the configured subscription and determine functions that'll be used to handle incoming messages\nconst subscribe = api.subscribe(onMessageProcessingError);\nsubscribe(subscriptionId, handleReceivedMessage);\n```\n\n### Get Subscription rules\nIn the case we want to retrieve the rules applied to a subscription, we can use this.\n\n```js\nlet subscriptionRules = await bus.getSubscriptionRules('topicSubscriptionName');\n```\n\n### Peek DLQ\nWhen a message goes to DLQ (Dead Letter Queue) we can peek those messages with this operation.\n\n```js\nconst subscriptionId = 'topicSubscriptionName'; // declared in config\nconst deadMessage = await api.peekDlq(subscriptionId); // retrieves only one\n```\n\n### Process DLQ\nSometimes we need to process messages in DLQ, i.e. to purge it or to republish and reprocess them. We provide a streaming API to process them.\n\n```js\n// Define function to handle messages\nconst handleReceivedMessage = ({ body, userProperties }) =\u003e {\n \t// do something with message...\n};\n\nconst subscriptionId = 'topicSubscriptionName'; // declared in config\napi.processDlq(subscriptionId, handleReceivedMessage);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonebeyond%2Fsystemic-azure-bus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonebeyond%2Fsystemic-azure-bus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonebeyond%2Fsystemic-azure-bus/lists"}