{"id":18738633,"url":"https://github.com/nathanboktae/robust-websocket","last_synced_at":"2025-04-06T04:09:39.142Z","repository":{"id":25536860,"uuid":"93708830","full_name":"nathanboktae/robust-websocket","owner":"nathanboktae","description":"A robust reconnecting WebSocket client for the browser","archived":false,"fork":false,"pushed_at":"2022-07-14T04:57:25.000Z","size":41,"stargazers_count":137,"open_issues_count":5,"forks_count":21,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-14T05:40:04.529Z","etag":null,"topics":["client-side","offline","websocket-client","websockets"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nathanboktae.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-06-08T04:56:36.000Z","updated_at":"2024-04-11T17:10:04.000Z","dependencies_parsed_at":"2022-08-07T11:15:51.163Z","dependency_job_id":null,"html_url":"https://github.com/nathanboktae/robust-websocket","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathanboktae%2Frobust-websocket","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathanboktae%2Frobust-websocket/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathanboktae%2Frobust-websocket/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathanboktae%2Frobust-websocket/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nathanboktae","download_url":"https://codeload.github.com/nathanboktae/robust-websocket/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247430869,"owners_count":20937874,"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":["client-side","offline","websocket-client","websockets"],"created_at":"2024-11-07T15:29:46.913Z","updated_at":"2025-04-06T04:09:39.127Z","avatar_url":"https://github.com/nathanboktae.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# robust-websocket\n\n#### A robust, reconnecting WebSocket client for the browser\n\n[![SauceLabs Test Status](https://saucelabs.com/browser-matrix/robustwebsocket.svg)](https://saucelabs.com/u/robustwebsocket)\n\n`robust-websocket` is a wrapper around the standard [WebSocket] class that implements the same interface, but can reconnect when disconnected or the user's computer comes back online.\n\nIt is error-code aware and will not reconnect on 1008 (HTTP 400 equivalent) and 1011 (HTTP 500 equivalent) by default. This behavior is fully configurable via the `shouldConnect` (see [Usage](https://github.com/nathanboktae/robust-websocket#usage)).\n\n### Compared to [reconnecting-websocket](https://github.com/joewalnes/reconnecting-websocket)\n\n- Tests! You know it works like stated and regressions will be caught.\n- Is aware of online and offline, and won't burn up the users battery and CPU reconnected when offline, and will reconnect when it is online again.\n- Natively aware of error codes\n- Any kind of reconnect strategy is possible via functional composition\n\n## Usage\n\n[CodePen Example](https://codepen.io/nathanboktae/pen/RoLXmw)\n\nUse it as you would a normal websocket:\n\n```javascript\nvar ws = new RobustWebSocket('ws://echo.websocket.org/')\n\nws.addEventListener('open', function(event) {\n  ws.send('Hello!')\n})\n\nws.addEventListener('message', function(event) {\n  console.log('we got: ' + event.data)\n})\n```\n\nBut with an optional set of options you can specify as a 3rd parameter\n\n```javascript\nvar ws = new RobustWebSocket('ws://echo.websocket.org/', {\n   // The number of milliseconds to wait before a connection is considered to have timed out. Defaults to 4 seconds.\n   timeout: 4000,\n  // A function that given a CloseEvent or an online event (https://developer.mozilla.org/en-US/docs/Online_and_offline_events) and the `RobustWebSocket`,\n  // will return the number of milliseconds to wait to reconnect, or a non-Number to not reconnect.\n  // see below for more examples; below is the default functionality.\n  shouldReconnect: function(event, ws) {\n    if (event.code === 1008 || event.code === 1011) return\n    return [0, 3000, 10000][ws.attempts]\n  },\n  // A boolean indicating whether or not to open the connection automatically. Defaults to true, matching native [WebSocket] behavior.\n  // You can open the websocket by calling `open()` when you are ready. You can close and re-open the RobustWebSocket instance as much as you wish.\n  automaticOpen: true,\n  // A boolean indicating whether to disable subscribing to the connectivity events provided by the browser.\n  // By default RobustWebSocket instances use connectivity events to avoid triggering reconnection when the browser is offline. This flag is provided in the unlikely event of cases where this may not be desired.\n  ignoreConnectivityEvents: false\n})\n```\n\nThe URL parameter can either be a string, or a function which returns a string. This can be useful if you need the WebSocket to reconnect to a different URL than it connected to initially:\n\n```javascript\nvar ws = new RobustWebSocket((ws) =\u003e {\n  return ws.reconnects \u003e 0 ? `ws://echo.websocket.org/?reconnect=${ws.reconnects}` : `ws://echo.websocket.org/`\n});\n```\n\n#### `shouldReconnect` Examples\n\nReconnect with an exponetial backoff on all errors\n```javascript\nfunction shouldReconnect(event, ws) {\n  return Math.pow(1.5, ws.attempts) * 500\n}\n```\n\nReconnect immediately but only 20 times per RobustWebSocket instance\n```javascript\nfunction shouldReconnect(event, ws) {\n  return ws.reconnects \u003c= 20 \u0026\u0026 0\n}\n```\n\nReconnect only on some whitelisted codes, and only 3 attempts, except on online events, then connect immediately\n```javascript\nfunction shouldReconnect(event, ws) {\n  if (event.type === 'online') return 0\n  return [1006,1011,1012].indexOf(event.code) \u0026\u0026 [1000,5000,10000][ws.attempts]\n}\n```\n\nSee documentation for [CloseEvent] and [online event](https://developer.mozilla.org/en-US/docs/Online_and_offline_events), the two types of events that `shouldReconnect` will receive.\n\nTypically, websockets closed with code `1000` indicate that the socket\nclosed normally. In these cases, `robust-websocket` won't call\n`shouldReconnect` (and will not attempt to reconnect), unless you set\n`shouldReconnect.handle1000` to `true`.\n\n### Polyfills needed\n\nYou may need these polyfills to support older browsers\n\n- [Object.assign](http://kangax.github.io/compat-table/es6/#test-Object_static_methods_Object.assign) - [npm package](https://www.npmjs.com/package/object.assign) or 24-line [MDN snippet](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign)\n- [CustomEvent](http://caniuse.com/#search=CustomEvent) - [npm package](https://www.npmjs.com/package/customevent-polyfill) or 15-line [MDN snippet](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent)\n\n[WebSocket]: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket\n[CloseEvent]: https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnathanboktae%2Frobust-websocket","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnathanboktae%2Frobust-websocket","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnathanboktae%2Frobust-websocket/lists"}