{"id":19419073,"url":"https://github.com/launchcodedev/ws-rpc","last_synced_at":"2025-10-19T17:14:20.261Z","repository":{"id":55101631,"uuid":"290236997","full_name":"launchcodedev/ws-rpc","owner":"launchcodedev","description":"Minimal framework for strongly typed client-server WebSocket connections","archived":false,"fork":false,"pushed_at":"2021-02-10T20:27:35.000Z","size":237,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-24T14:43:02.923Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/launchcodedev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-08-25T14:26:31.000Z","updated_at":"2021-02-10T20:27:38.000Z","dependencies_parsed_at":"2022-08-14T12:00:52.013Z","dependency_job_id":null,"html_url":"https://github.com/launchcodedev/ws-rpc","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/launchcodedev/ws-rpc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchcodedev%2Fws-rpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchcodedev%2Fws-rpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchcodedev%2Fws-rpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchcodedev%2Fws-rpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/launchcodedev","download_url":"https://codeload.github.com/launchcodedev/ws-rpc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/launchcodedev%2Fws-rpc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279859650,"owners_count":26236530,"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","status":"online","status_checked_at":"2025-10-19T02:00:07.647Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-10T13:16:05.228Z","updated_at":"2025-10-19T17:14:20.231Z","avatar_url":"https://github.com/launchcodedev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Simple Websocket RPC\n\nThis package provides the minimal set of boilerplate that's normally needed when setting up a client-server websocket.\n\nIt's a really lightweight alternative to socket.io and similar systems. The\nbenefit is that it's fully type-safe, and you can read all of the source code\nin about 10 minutes.\n\nYou probably shouldn't build giant systems on this (at least, talk to us first).\nIt's meant for small communication layers between software, usually in single-tenant systems.\n\n[App Config](https://app-config.dev) uses this library internally, for it's \"secret agent\".\n\n```\nyarn add @lcdev/ws-rpc\n```\n\n## Quickstart\n\nNormally, you'd have some shared code between server and client (backend and frontend). It would look like this:\n\n```typescript\nimport { build } from '@lcdev/ws-rpc';\n\nconst common = build({ deserialize: JSON.parse, serialize: JSON.stringify })\n  // functions are client -\u003e server. input and outputs can be anything serializable.\n  .func\u003c'double', { num: number }, { doubled: number }\u003e()\n  .func\u003c'triple', { num: number }, { tripled: number }\u003e()\n  // events are bi-directional, they can be sent or received on both sides.\n  .event\u003c'single'\u003e()\n  .event\u003c'random', { rand: number }\u003e()\n  .event\u003c'scheduled', { rand: number }\u003e();\n```\n\nIn a Node.js server, we can use the common code:\n\n```typescript\nimport { common } from 'my-common-rpc';\n\ncommon\n  .server({\n    async double({ num }) {\n      return { doubled: num * 2 };\n    },\n    async triple({ num }) {\n      return { tripled: num * 3 };\n    },\n  })\n  // you can pass a host, port, a WS.Server, http(s) server\n  .listen(3000)\n  .then((server) =\u003e {\n    setTimeout(() =\u003e {\n      server.sendEvent('single');\n    }, 500);\n\n    const runRandom = () =\u003e {\n      setTimeout(() =\u003e {\n        // IMPORTANTLY, TypeScript knows the type of all events\n        server.sendEvent('random', { rand: Math.random() });\n\n        runRandom();\n      }, Math.random() * 500);\n    };\n\n    runRandom();\n\n    setInterval(() =\u003e {\n      server.sendEvent('scheduled', { rand: Math.random() });\n    }, 500);\n  })\n  .catch(console.error);\n```\n\nThen on the client side:\n\n```typescript\nimport { common } from 'my-common-rpc';\n\ncommon\n  .client()\n  .connect(3000)\n  .then((client) =\u003e {\n    client.on('single', () =\u003e {\n      console.log('received single');\n    });\n\n    client.on('random', ({ rand }) =\u003e {\n      console.log('received random', rand);\n    });\n\n    client.on('scheduled', ({ rand }) =\u003e {\n      console.log('received scheduled', rand);\n    });\n\n    // just call functions like you would call a normal function\n    // TypeScript also knows the type of all functions\n    client.double({ num: 2 }).then(({ doubled }) =\u003e console.log('doubled to', doubled));\n    client.triple({ num: 2 }).then(({ tripled }) =\u003e console.log('tripled to', tripled));\n  })\n  .catch(console.error);\n```\n\n## Features\n\n- Custom data serialization support, use BSON via `@lcdev/ws-rpc/bson` export\n- Custom client websocket library support by passing the client in `connect`\n- Custom server support by passing the server in `listen` (including node `http` and `https` servers)\n- Unix socket support, just pass `{ socket: 'filepath' }` in client \u0026 server\n- Optional validation of function data using custom validation functions in `func` and `event` builders\n- Lazy loading of modules, no special browser or server setup needed\n- Exports `setLogLevel` function to help see what's happening internally\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaunchcodedev%2Fws-rpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaunchcodedev%2Fws-rpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaunchcodedev%2Fws-rpc/lists"}