{"id":24558193,"url":"https://github.com/rse/apollo-client-ws","last_synced_at":"2025-04-19T09:59:16.517Z","repository":{"id":55111329,"uuid":"92544302","full_name":"rse/apollo-client-ws","owner":"rse","description":"GraphQL WebSocket Network Interface for Apollo Client","archived":false,"fork":false,"pushed_at":"2024-06-17T21:49:46.000Z","size":95,"stargazers_count":13,"open_issues_count":5,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-15T21:55:45.909Z","etag":null,"topics":["apollo","client","graphql","network","transport","websocket"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2017-05-26T19:58:46.000Z","updated_at":"2022-02-06T16:02:57.000Z","dependencies_parsed_at":"2024-06-19T00:03:26.280Z","dependency_job_id":"9e37c188-5bed-4560-a85a-375ece1e5552","html_url":"https://github.com/rse/apollo-client-ws","commit_stats":{"total_commits":159,"total_committers":1,"mean_commits":159.0,"dds":0.0,"last_synced_commit":"9a197d4ba55b7a6ba290d5b7da2fe79fa1ebbc9a"},"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fapollo-client-ws","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fapollo-client-ws/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fapollo-client-ws/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fapollo-client-ws/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rse","download_url":"https://codeload.github.com/rse/apollo-client-ws/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249670134,"owners_count":21308676,"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":["apollo","client","graphql","network","transport","websocket"],"created_at":"2025-01-23T05:47:37.090Z","updated_at":"2025-04-19T09:59:16.497Z","avatar_url":"https://github.com/rse.png","language":"JavaScript","readme":"\nApollo-Client-WS\n================\n\nGraphQL WebSocket Network Link for Apollo Client\n\n\u003cp/\u003e\n\u003cimg src=\"https://nodei.co/npm/apollo-client-ws.png?downloads=true\u0026stars=true\" alt=\"\"/\u003e\n\n\u003cp/\u003e\n\u003cimg src=\"https://david-dm.org/rse/apollo-client-ws.png\" alt=\"\"/\u003e\n\nAbout\n-----\n\nThis is a [GraphQL](http://graphql.org/)\n[WebSocket](https://html.spec.whatwg.org/multipage/comms.html#network)\nbased `ApolloLink` layer for the JavaScript GraphQL client library\n[Apollo Client](https://github.com/apollographql/apollo-client).\nIt was developed for and is intended to be used with the [HAPI](http://hapijs.com/) server\nframework and its seamless WebSocket protocol integration module\n[HAPI-Plugin-WebSocket](https://github.com/rse/hapi-plugin-websocket),\nalthough it could be used with any server speaking GraphQL over a\n[framed WebSocket](https://github.com/rse/websocket-framed) communication.\nApollo-Client-WS has deferred connection establishment, connection\nkeepalive support and can reconnect to the server automatically.\nAdditionally, beside the GraphQL request/response messages, it also\nallows the application to send/receive arbitrary messages over the\nWebSocket connection, too.\n\nInstallation\n------------\n\n```shell\n$ npm install graphql-tag apollo-client apollo-client-ws apollo-link\n```\n\nUsage\n-----\n\n```js\nconst gql                = require(\"graphql-tag\")\nconst { ApolloClient }   = require(\"apollo-client\")\nconst { ApolloClientWS } = require(\"apollo-client-ws\")\nconst { InMemoryCache }  = require(\"apollo-cache-inmemory\")\n\nconst link = new ApolloClientWS({\n    uri: \"ws://127.0.0.1:12345/api\",\n    opts: {\n        /*  (all options and their default values)  */\n        debug:             0,\n        log:               (msg) =\u003e { console.log(msg) },\n        protocols:         [],\n        compress:          false,\n        encoding:          \"json\",\n        keepalive:         0,\n        reconnectattempts: 10,\n        reconnectdelay:    2 * 1000\n    }\n})\n\nconst client = new ApolloClient({\n    link:  link,\n    cache: new InMemoryCache()\n})\n\nclient.query({ query: gql`{ ... }` })\n    .then((response) =\u003e { ...  })\n    .catch((err)     =\u003e { ...  })\n```\n\nNetwork Protocol\n----------------\n\nApollo-Client-WS on the WebSocket connection speaks\n[WebSocket-Framed](https://github.com/rse/websocket-framed),\na very simple protocol based on the following frame format:\n\n```\n[ fid: number, rid: number, type: string, data: any ]\n```\n\nIn particular, the following frames are used for the GraphQL requests\nand (their corresponding) responses:\n\n```\nrequest: [\n    fid:  number = \u003cfid\u003e,\n    rid:  number = 0,\n    type: string = \"GRAPHQL-REQUEST\",\n    data: { query: string, variables?: any, operationName?: string }\n]\n\nresponse: [\n    fid:  number = \u003cfid\u003e,\n    rid:  number = request.fid,\n    type: string = \"GRAPHQL-RESPONSE\",\n    data: { data?: any, error?: any[] }\n]\n```\n\nWhen sending a custom message via `ApolloClientWS::send(type: string, data: any)`,\nthe following frame is sent:\n\n```\nmessage: [\n    fid:  number = \u003cfid\u003e,\n    rid:  number = 0,\n    type: string = type,\n    data: any    = data\n]\n```\n\nWhen receiving such a custom frame, it is delivered via\n`ApolloClientWS::on(\"receive\", { type, data }) =\u003e { ... })`.\n\nNotice\n------\n\nThere is also the alternative module\n[Apollo-Link-WS](https://github.com/apollographql/apollo-link/tree/master/packages/apollo-link-ws)\nand its underlying\n[Subscriptions-Transport-WS](https://github.com/apollographql/subscriptions-transport-ws)\nfor [Apollo Client](https://github.com/apollographql/apollo-client). In contrast to\nthis module, Apollo-Client-WS intentionally has no direct built-in GraphQL subscription support.\nAlso, [Subscriptions-Transport-WS](https://github.com/apollographql/subscriptions-transport-ws)\nunfortunately, but by design, uses an\nopinionated way of implementing GraphQL subscriptions on the GraphQL engine side.\nThe Apollo-Client-WS instead provides plain WebSocket\ncommunication, without any additional subscription protocol, and hence\ndoes not enfore any special support for subscriptions on the server side.\n\nFor implementing a GraphQL subscription or similar add-on protocol on top\nof Apollo-Client-WS, simply use the `send` method to send non-GraphQL\nrequest messages to the server and use the `receive` event for\nreceiving non-GraphQL response messages from the server.\n\n```js\n/*  send a subscribe command  */\nlet data = [ \"foo\", 42 ]\nlink.send(\"SUBSCRIBE\", data)\n\n/*  receive a notification command  */\nlink.on(\"receive\", ({ type, data }) =\u003e {\n    if (type === \"NOTIFY\")\n        notify(...data)\n})\n```\n\nFor a more elaborate out-of-the-box solution to GraphQL query subscriptions,\ncheck out [GraphQL-IO](http://graphql-io.com). Under the hood, it already uses\n[Apollo Client](https://github.com/apollographql/apollo-client) and\n[WebSocket-Framed](https://github.com/rse/websocket-framed).\n\nLicense\n-------\n\nCopyright (c) 2017-2021 Dr. Ralf S. Engelschall (http://engelschall.com/)\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n\"Software\"), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be included\nin all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frse%2Fapollo-client-ws","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frse%2Fapollo-client-ws","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frse%2Fapollo-client-ws/lists"}