{"id":23038446,"url":"https://github.com/tdjsnelling/dwsps","last_synced_at":"2025-04-02T23:28:58.587Z","repository":{"id":44005746,"uuid":"235351548","full_name":"tdjsnelling/dwsps","owner":"tdjsnelling","description":"Tiny distributed websocket pub/sub system","archived":false,"fork":false,"pushed_at":"2022-02-13T00:04:58.000Z","size":273,"stargazers_count":1,"open_issues_count":6,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-19T08:18:00.204Z","etag":null,"topics":["distributed","javascript","pubsub","websocket"],"latest_commit_sha":null,"homepage":"","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/tdjsnelling.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":"2020-01-21T13:41:13.000Z","updated_at":"2022-07-05T09:25:53.000Z","dependencies_parsed_at":"2022-09-26T19:53:22.554Z","dependency_job_id":null,"html_url":"https://github.com/tdjsnelling/dwsps","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdjsnelling%2Fdwsps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdjsnelling%2Fdwsps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdjsnelling%2Fdwsps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tdjsnelling%2Fdwsps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tdjsnelling","download_url":"https://codeload.github.com/tdjsnelling/dwsps/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246884763,"owners_count":20849554,"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":["distributed","javascript","pubsub","websocket"],"created_at":"2024-12-15T18:18:51.207Z","updated_at":"2025-04-02T23:28:58.572Z","avatar_url":"https://github.com/tdjsnelling.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dwsps\n\n\u003e _distributed websocket publish/subscribe_\n\n[![CircleCI](https://circleci.com/gh/tdjsnelling/dwsps.svg?style=svg\u0026circle-token=8b2de60c02024d151cb74edfef4a5b4fe456b0b1)](https://circleci.com/gh/tdjsnelling/dwsps)\n![npm](https://img.shields.io/npm/v/dwsps)\n![npm bundle size](https://img.shields.io/bundlephobia/min/dwsps)\n\n**dwsps** is a distributed nodejs pub/sub system. It uses websockets to transmit messages between client and server, and between peered servers.\n\n- [Topics](#topics)\n- [Messages](#messages)\n- [Acknowledgements](#acknowledgements)\n- [Distribution](#distribution)\n- [Usage](#usage)\n  - [Basic server example](#basic-server-example)\n  - [Basic client example](#basic-client-example)\n- [License](#license)\n\n## Topics\n\n**dwsps** uses a heirarchical topic system for client subscriptions, each level divided by a full-stop `.`. For example, a client could subscribe to the topic `news.uk`. They would then recieve messages published to `news.uk`, `news.uk.london`, `news.uk.birmingham` etc. but not from `news.fr` or `news.de`.\n\nNote: if a client is subscribed to a parent topic and a sub-topic of the parent, unsubscribing from the parent topic will _not_ also unsubscribe the client from the sub-topic. Each subscription must be unsubscribed from explicitly.\n\n## Messages\n\nMessages are JSON format and look like the following:\n\n```\n{\n  \"type\": \"publish\",\n  \"timestamp\": \"2020-01-21T17:03:13.625Z\",\n  \"topic\": \"news.uk\",\n  \"context\": \"news\",\n  \"message\": \"Hello news.uk channel!\"\n}\n```\n\n- `topic` lets a client know where the message was published to\n- `context` lets a client know _why_ they are receiving a certain message - in this instance the client is subscribed to `news`, where they received it, but not `news.uk`, where it was sent.\n- `message` can be any valid JSON data\n\n## Acknowledgements\n\nWhen a client performs an action, the server will send an acknowledgment in reply if it received the message and executed the action correctly. These can be listened for with the client `ack` event.\n\nAck messages look like this:\n\n```\n{\n  \"type\": \"ack\",\n  \"action\": \"subscribe\",\n  \"timestamp\": \"2020-01-22T15:44:04.674Z\",\n  \"topic\": \"news\"\n}\n```\n\n## Distribution\n\nMultiple **dwsps** servers can be peered with one another to create a distributed network. Once servers are peered, then a message published to one server will also be published to all servers, and delivered to their own subscribed clients respectively. Subscribed clients are not replicated between servers, instead held in memory on a per server basis.\n\nMessages that were forwarded from another server will also contain a `fromPeerServer: true` flag.\n\nNote: adding Server A as a peer of Server B will not enable 2-way communication: B will forward messages to A but not vice versa. Server B must also be added as a peer of Server A. See [example.js](./example.js) for an example of peering servers.\n\n## Usage\n\n### Basic server example\n\n```js\nconst PSServer = require('dwsps/server')\n\nconst server = new PSServer({ port: 8000 })\n\nserver.on('subscribe', (topic, client) =\u003e {\n  console.log(`${client} subscribed to ${topic}`)\n})\n```\n\n### Basic client example\n\nIn this example, an event listener is used to receive all messages from every topic the client is subscribed to.\n\n```js\nconst PSClient = require('dwsps/client')\n//            or require('dwsps')\n\nconst client = new PSClient('ws://localhost:8000')\n\n// Must wait for client to establish connection before performing actions\nclient.on('open', () =\u003e {\n  client.subscribe('news')\n  client.publish('news', 'Hello news channel!')\n  client.publish('news.uk', 'Hello news.uk channel!')\n})\n\n// Log acknowledgments from the server\nclient.on('ack', ack =\u003e {\n  console.log(ack)\n})\n\n// Log messages received by the client\nclient.on('message', message =\u003e {\n  console.log(message)\n})\n```\n\nIf you only want to take action on certain received messages, you can either:\n\n- Implement this yourself using the event listener method and parsing the message topic, or\n- Pass a callback function to the `subscribe` method which will only be called when a message is received matching that particular subscription.\n\n```js\nconst PSClient = require('dwsps/client')\n\nconst client = new PSClient('ws://localhost:8000')\n\n// Create a callback function that will be called when the client receives a\n// message matching the topic `news`.\nconst newsHandler = message =\u003e {\n  console.log(message)\n}\n\n// Must wait for client to establish connection before performing actions\nclient.on('open', () =\u003e {\n  client.subscribe('news', newsHandler)\n  client.publish('news', 'Hello news channel!')\n})\n```\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftdjsnelling%2Fdwsps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftdjsnelling%2Fdwsps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftdjsnelling%2Fdwsps/lists"}