{"id":20825170,"url":"https://github.com/dcharbonnier/hydrated-ws","last_synced_at":"2025-05-07T17:28:10.873Z","repository":{"id":27033364,"uuid":"112223529","full_name":"dcharbonnier/hydrated-ws","owner":"dcharbonnier","description":"The toolbox for websockets clients, reconnecting websockets, channels muxing websockets, authentication, json-rpc over websockets","archived":false,"fork":false,"pushed_at":"2023-01-27T11:44:42.000Z","size":4029,"stargazers_count":60,"open_issues_count":15,"forks_count":5,"subscribers_count":5,"default_branch":"develop","last_synced_at":"2025-04-21T15:21:27.290Z","etag":null,"topics":["authentication","muxing","nodejs","reconnecting","typescript","websocket"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dcharbonnier.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":"2017-11-27T16:57:55.000Z","updated_at":"2024-05-16T18:37:41.000Z","dependencies_parsed_at":"2023-02-15T08:46:34.436Z","dependency_job_id":null,"html_url":"https://github.com/dcharbonnier/hydrated-ws","commit_stats":null,"previous_names":["dcharbonnier/advanced-websocket","dcharbonnier/hydraded-ws"],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcharbonnier%2Fhydrated-ws","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcharbonnier%2Fhydrated-ws/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcharbonnier%2Fhydrated-ws/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcharbonnier%2Fhydrated-ws/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dcharbonnier","download_url":"https://codeload.github.com/dcharbonnier/hydrated-ws/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252925618,"owners_count":21826194,"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":["authentication","muxing","nodejs","reconnecting","typescript","websocket"],"created_at":"2024-11-17T22:25:14.904Z","updated_at":"2025-05-07T17:28:10.835Z","avatar_url":"https://github.com/dcharbonnier.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./logo.png\"\u003e\n\u003c/p\u003e\n\n[![Gitter](https://img.shields.io/gitter/room/hydratedws/Lobby.svg?style=flat-square)](https://gitter.im/hydratedws/Lobby)\n\n[![Build Status](https://img.shields.io/travis/dcharbonnier/hydrated-ws/master.svg?style=flat-square)](https://travis-ci.org/dcharbonnier/hydrated-ws)\n[![Greenkeeper badge](https://badges.greenkeeper.io/dcharbonnier/hydrated-ws.svg)](https://greenkeeper.io/)\n[![devDependency Status](https://img.shields.io/david/dev/dcharbonnier/hydrated-ws.svg?style=flat-square)](https://david-dm.org/dcharbonnier/hydrated-ws#info=devDependencies)\n[![Codecov](https://img.shields.io/codecov/c/github/dcharbonnier/hydrated-ws/develop.svg?style=flat-square)](https://codecov.io/gh/dcharbonnier/hydrated-ws)\n[![Npm version](https://img.shields.io/npm/v/hydrated-ws.svg?style=flat-square)](https://www.npmjs.com/package/hydrated-ws)\n[![Code Climate](https://img.shields.io/codeclimate/maintainability/dcharbonnier/hydrated-ws.svg?style=flat-square)](https://codeclimate.com/github/dcharbonnier/hydrated-ws/)\n\n\nhydrated WebSocket is a collection of lightweight (no dependencies) and\nsimple components to build complex communication\npath over Websocket on the server and the browser.\n\nAll components are seen from the outside world like a WebSocket allowing\nyou to integrate is on any existing project.\n\n- [Api documentation](https://dcharbonnier.github.io/hydrated-ws/)\n\n\u003c!-- toc --\u003e\n\n- [Examples](#examples)\n    + [Waterfall](#waterfall)\n    + [Pipe](#pipe)\n    + [Dam](#dam)\n    + [Tank](#tank)\n    + [Cable](#cable)\n    + [Advanced](#advanced)\n- [Roadmap](#roadmap)\n- [FAQ](#faq)\n\n\u003c!-- tocstop --\u003e\n\nExamples\n========\n### Waterfall\n\nThe waterfall is a simple compatible WebSocket with automatic reconnect\nsupport\n\nThe retry policy ermit a full customisation of the reconnection and a\ndefault\nexponential truncated backoff policy is provides by default.\n\n```typescript\nconst ws = new Waterfall(\"wss://server\", null, {\n    connectionTimeout: 2000,\n    retryPolicy: exponentialTruncatedBackoff(100, Number.MAX_VALUE)\n});\n```\n\n### Pipe\n\nThe Pipe allow you to multiplex string channels, add a pipe on a\nWebsocket on both side and\nreceive only the messages transmitted into this pipe.\n\n```typescript\nconst ws = new WebSocket(\"wss://server\");\nconst  channelA = new Pipe(ws, \"A\");\nconst  channelB = new Pipe(ws, \"B\");\n```\n\n### Dam\n\nHas you can split your WebSockets in different Pipes it become useful\nto be able to control an open or closed status, faking a connection.\nYou can for example create a pipe to communicate and an other to\nauthenticate and change the communication status according to the\nauthentication status.\n\n\n```typescript\nconst ws = new WebSocket(\"wss://server\");\nconst  authenticatedWebSocketr = new Dam(ws);\nonLogin(() =\u003e authenticatedWebSocketr.status = \"OPEN\");\nonLogout(() =\u003e authenticatedWebSocketr.status = \"CLOSED\");\n```\n\n\n### Tank\n\nChecking if a socket is open to be able to send your message, delaying\nthose messages for when the WebSocket is open is a repetitive task.\nWrap your socket in a Tank and you can use `send` at anytime, if\nthe socket is closed, the messages will be buffered and has soon has the\nwebsocket open they will be flushed in order.\n\n```typescript\nconst ws = new Tank(new WebSocket(\"wss://server\"));\nws.send(\"I've send this message before the opening of the websocket\");\n```\n\n### Cable\n\nDoing an RPC over a websocket should be trivial, the Cable provide a\nconvenient way to register methods and to call them on both side of the\nconnection.\n\n```typescript\n// Client 1\nconst cable = new Cable(ws);\ncable.register(\"ping\", async () =\u003e {\n   return \"pong\";\n });\n cable.notify(\"hello\", {name:\"client 1\"});\n\n // Client 2\n const cable = new Cable(ws);\n cable.register(\"hello\", async ({name:string}) =\u003e {\n   console.log(`${name} said hello`);\n  });\n try {\n   const res = await cable.request(\"ping\");\n   assert.equal(res,\"pong\");\n } catch(e) {\n   if(e.code === Cable.SERVER_ERROR) {\n     console.log(\"Implementation error on the server\");\n   }\n   throw e;\n }\n ```\n### Advanced\n\nA combination that use 5 components to create an authentication channel\nwith rpc, a data channel (that can be used by any library expecting a\nregular websocket) and a robust websocket\n\n```typescript\nconst ws = new Waterfall(\"wss://server\", null, {\n    connectionTimeout: 2000,\n    retryPolicy: exponentialTruncatedBackoff(100, Number.MAX_VALUE)\n});\nconst authChannel = new Cable(new Tank(new Pipe(ws, AUTH_CHANNEL)));\nconst authFilter = new Dam(ws);\nconst shareDbChannel = new Tank(new Pipe(authFilter, SHAREDB_CHANNEL));\nconst db = new ShareDb(shareDbChannel);\n\ntry {\n    const result = await authChannel.request(\"login\", TOKEN);\n    if(result.success) {\n        authFilter.status = \"OPEN\";\n    }\n} catch {\n    // the auth failed\n}\n```\n\n\nRoadmap\n=======\n\n- [x] Browser (WebSocket API compatible)\n- [x] Nodejs with ws (WebSocket API compatible)\n- [x] Waterfall - Reconnect (exponential truncated backoff by default,\nfully configurable)\n- [x] Pipe - Multiplexing, based on a string prefix\n- [x] Dam - Simulate open / close based on your logic, open a pipe after\nhe authentication on an other one for example\n- [x] Tank - No need to monitor the state of the communication the sent\nmessages with be flushed when it open\n- [x] Cable - Json rpc2 transport\n- [ ] Split the project in different modules with yarn workspace and\nlerna\n- [ ] Fizz - Wrap your WebSocket interface for more fun with `once`,\n`on`, `Promises`\n- [ ] Bottling - A json stream with filtering\n- [x] Wormhole - Client to client connection\n- [x] Proxy\n- [ ] 100% test coverage\n- [ ] Your idea here, send an issue, provide a PR\n\n\nFAQ\n=======\n\n#### Aurelia bundler\nThe bundler will complain about many packages with a message \"Unable to load package metadata\", the solution is to ignore the ws package in the task build :\n```\nfunction writeBundles() {\n  return buildCLI.dest({\n    onRequiringModule: moduleId =\u003e\n      moduleId === \"ws\"\n        ? \"define(['ws'] , function () {return undefined;});\"\n        : void 0\n  });\n}\n```\n\n#### Webpack\nWebpack complain about the `ws` implementation of WebSocket, the errors\nare :\n`Can't resolve 'net'` and `Can't resolve 'tls'`.\n\nThe solution consist in ignoring the ws module that can't be used in a\nbrowser (and not required), the polyfill will detect the browser\nimplementation of the WebSocket and use it.\nTo ignore the module, add a rule to your webpack config file :\n\n`{test: /[\\/\\\\]node_modules[\\/\\\\]ws[\\/\\\\].+\\.js$/, use: 'null-loader'},`\n \n#### Can't resolve 'ws' \nIf you're using this module on the client side webpack will warn you\nwith this message when you pack the module, if you're using this module\non the server side you need to install `ws`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcharbonnier%2Fhydrated-ws","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdcharbonnier%2Fhydrated-ws","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcharbonnier%2Fhydrated-ws/lists"}