{"id":18619871,"url":"https://github.com/dizys/orpc","last_synced_at":"2025-06-22T02:35:55.117Z","repository":{"id":33509290,"uuid":"159032408","full_name":"dizys/orpc","owner":"dizys","description":"The type-safe Node.js and browser RPC library built on top of socket.io. Empowered with SOA governance and load balancing.","archived":false,"fork":false,"pushed_at":"2023-03-04T04:11:15.000Z","size":277,"stargazers_count":10,"open_issues_count":6,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-05-13T19:09:57.526Z","etag":null,"topics":["nodejs","rpc","socket-io","typesafe","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/dizys.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-11-25T13:05:31.000Z","updated_at":"2025-05-03T04:45:55.000Z","dependencies_parsed_at":"2025-04-11T02:41:33.370Z","dependency_job_id":"7f248151-3a64-4668-a84e-8e7ce3365725","html_url":"https://github.com/dizys/orpc","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/dizys/orpc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dizys%2Forpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dizys%2Forpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dizys%2Forpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dizys%2Forpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dizys","download_url":"https://codeload.github.com/dizys/orpc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dizys%2Forpc/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261225638,"owners_count":23127178,"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":["nodejs","rpc","socket-io","typesafe","typescript"],"created_at":"2024-11-07T04:03:43.363Z","updated_at":"2025-06-22T02:35:50.099Z","avatar_url":"https://github.com/dizys.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![NPM Package](https://badge.fury.io/js/orpc.svg)](https://www.npmjs.com/package/orpc) [![Build Status](https://travis-ci.org/dizys/orpc.svg?branch=master)](https://travis-ci.org/dizys/orpc)\n\n# orpc\n\nThe type-safe Node.js and browser RPC library built on top of socket.io. Empowered with SOA governance and load balancing.\n\n## Installation\n\n```sh\nyarn add orpc\n```\n\n## Quick Start\n\n`shared.ts`\n\n```ts\nexport interface HelloServicePrototype extends ServicePrototype {\n  say(name: string): string;\n}\n\nexport interface MyRPCSchema extends RPCSchema {\n  hello: HelloServicePrototype;\n}\n```\n\n`server.ts`\n\n```ts\nclass HelloService implements HelloServicePrototype {\n  say(name: string): string {\n    return `Hello, ${name}!`;\n  }\n}\n\nlet myRPC: MyRPCSchema = {\n  hello: new HelloService(),\n};\n\nconst server = new RPCServer(myRPC);\n\nserver.start(8013);\n```\n\n`client.ts`\n\n```ts\nlet rpc = createClient\u003cMyRPCSchema\u003e('http://localhost:8013/');\n\nlet result = await rpc.hello.say('dizy'); // Type-safe\n\nconsole.log(result); // 'Hello, dizy!'\n```\n\n## Core Concepts\n\n\u003e `ServicePrototype` and `RPCSchema` should be shared between client and server. `Service` should be implemented only on server.\n\n### Service Prototype\n\nA service prototype is an interface that defines the signature of the methods provided in the service. This is shared between both server and client side, so it will help type both our server implementation and client usage.\n\n```ts\ninterface FileServicePrototype extends ServicePrototype {\n  list(dir: string): Promise\u003cFileInfo[]\u003e;\n  upload(file: Buffer, saveToDir: string): Promise\u003cvoid\u003e;\n  download(path: string): Promise\u003cBuffer\u003e;\n  delete(path: string): Promise\u003cboolean\u003e;\n  rename(oldPath: string, newPath: string): Promise\u003cboolean\u003e;\n}\n```\n\n### RPC Schema\n\nIn order to run multiple services on one single server, we build RPC schema to assemble these services into one bigger type. This is also shared between client and server.\n\n```ts\ninterface MyRPCSchema extends RPCSchema {\n  file: FileServicePrototype;\n  system: SystemServicePrototype;\n  blog: BlogServicePrototype;\n}\n```\n\n### Service\n\nService is implemented in a form of `Class`. And it could be considered as a collection of methods ready to be remotely called. It is expected to implement the corresponding `ServerPrototype` on server.\n\n```ts\nclass FileService implements FileServicePrototype{\n  async list(dir: string): Promise\u003cFileInfo[]\u003e{\n    let files = await //...implementation\n\n    return files;\n  }\n\n  //...\n}\n```\n\n### Gateway\n\n`Gateway` is a reverse proxy that takes clients' calls and sends them to one of the known servers, then gets results and feed them back to clients. To clients, a `Gateway` behaves exactly like a `RPCServer`, except its performance compete with several servers combined. `Gateway` is especially useful for high-cpu-usage services. Also, `Gateway` supports SOA governance and load balancing, so it can make sure services are highly-available and calls are well-balanced in terms of distribution to servers.\n\n```ts\nlet config = {\n  servers: [\n    {url: 'http://localhost:8021/', weight: 10},\n    {url: 'http://localhost:8022/', weight: 3},\n    {url: 'http://localhost:8023/', weight: 4},\n  ], // Servers' info\n  loadBalancer: smoothWRRLoadBalancer, // built-in Smooth-Weighted-Round-Robin LoadBalancer\n  log: {debug: true}, // Turn on debug mode\n};\n\nlet gateway = new Gateway(config);\n\ngateway.start(8014);\n```\n\n## APIs\n\n### RPCServer\n\n- `constructor (rpcSchema?: SchemaImplement\u003cSchema\u003e)`\n- methods:\n\n  - `start(port?: number, hostname?: string): void`\n\n    `port` defaults to `80`, `hostname` defaults to `'localhost'`\n\n  - `stop(): void`\n\n  - `register(name: string, service: object): void`\n\n  - `register(name: string, service: ServiceConstructor, initializeForEachClient?: boolean): void`\n\n    Dynamically register new service. `initializeForEachClient` defaults to `false`\n\n  - `unregister(name: string): boolean`\n\n    Dynamically cancel registered service.\n\n### createClient()\n\n- parameters:\n\n  - `url`?: string\n\n    Defaults to `'http://localhost/'`\n\n- returns:\n\n  - `RPCClient\u003cRPCSchema\u003e`\n\n- usages:\n\n  ```ts\n  let rpc = createClient\u003cMyRPCSchema\u003e(8080);\n\n  let result = await rpc.myService.methodA(...args);\n  ```\n\n### RPCClient\n\n`RPCClient` should always be created by `createClient`. That way, service and schema type information will be attached to it.\n\n- `constructor (url?: string)`\n- methods:\n\n  - `open(): void`\n\n    Open connection. Automatically called when created.\n\n  - `close(): void`\n\n  - `call(service: string, data: CallData): Promise\u003cany\u003e`\n\n  - `call(service: string, method: string, params: any[], options: CallOptions): Promise\u003cany\u003e`\n\n    Call remote service method.\n\n### Gateway\n\n#### GatewayConfig\n\n```ts\nlet config: GatewayConfig = {\n  servers: [\n    {url: 'http://localhost:8015', weight: 10},\n    {url: 'http://localhost:8016', weight: 4},\n    {url: 'http://localhost:8017', weight: 6},\n  ], // Servers' info\n  loadBalancer: smoothWRRLoadBalancer, // Optional: defaults to `evenLoadBalancer`.\n  downgrade: true, // Optional: defaults to `true`.\n  downgradeAtAnyError: false, // Whether any error thrown by server will cause its downgrade. Optional: defaults to `false`.\n  downgradeTolerantTime: 3, // How many tolerant times to fail before the server is downgraded to `0` weight. Optional: defaults to `3`.\n  downgradeDeadSleepTime: 5, // A many times can a `0` weight server be offered a chance to revive. Optional: defaults to `5`.\n  log: {\n    enable: true,\n    debug: true,\n  }, // Optional: Defaults to `{enable: true, debug: false}`\n};\n```\n\n#### Gateway\n\n- `constructor(config: GatewayConfig)`\n- methods:\n\n  - `start(port?: number, hostname?: string): void`\n\n    Start gateway server. `port` defaults to `80`, `hostname` defaults to `'localhost'`\n\n  - `stop(): void`\n\n  - `reloadConfig(config: GatewayConfig): void`\n\n- usage:\n\n  see [Core Concepts](#Core-Concepts)\n\n## License\n\nMIT, see the [LICENSE](/LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdizys%2Forpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdizys%2Forpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdizys%2Forpc/lists"}