1 | # Pure JavaScript gRPC Client
|
2 |
|
3 | ## Installation
|
4 |
|
5 | Node 12 is recommended. The exact set of compatible Node versions can be found in the `engines` field of the `package.json` file.
|
6 |
|
7 | ```sh
|
8 | npm install @grpc/grpc-js
|
9 | ```
|
10 |
|
11 | ## Documentation
|
12 |
|
13 | Documentation specifically for the `@grpc/grpc-js` package is currently not available. However, [documentation is available for the `grpc` package](https://grpc.github.io/grpc/node/grpc.html), and the two packages contain mostly the same interface. There are a few notable differences, however, and these differences are noted in the "Migrating from grpc" section below.
|
14 |
|
15 | ## Features
|
16 |
|
17 | - Clients
|
18 | - Automatic reconnection
|
19 | - Servers
|
20 | - Streaming
|
21 | - Metadata
|
22 | - Partial compression support: clients can decompress response messages
|
23 | - Pick first and round robin load balancing policies
|
24 | - Client Interceptors
|
25 | - Connection Keepalives
|
26 | - HTTP Connect support (proxies)
|
27 |
|
28 | This library does not directly handle `.proto` files. To use `.proto` files with this library we recommend using the `@grpc/proto-loader` package.
|
29 |
|
30 | ## Migrating from [`grpc`](https://www.npmjs.com/package/grpc)
|
31 |
|
32 | `@grpc/grpc-js` is almost a drop-in replacement for `grpc`, but you may need to make a few code changes to use it:
|
33 |
|
34 | - If you are currently loading `.proto` files using `grpc.load`, that function is not available in this library. You should instead load your `.proto` files using `@grpc/proto-loader` and load the resulting package definition objects into `@grpc/grpc-js` using `grpc.loadPackageDefinition`.
|
35 | - If you are currently loading packages generated by `grpc-tools`, you should instead generate your files using the `generate_package_definition` option in `grpc-tools`, then load the object exported by the generated file into `@grpc/grpc-js` using `grpc.loadPackageDefinition`.
|
36 | - If you have a server and you are using `Server#bind` to bind ports, you will need to use `Server#bindAsync` instead.
|
37 |
|
38 | ## Some Notes on API Guarantees
|
39 |
|
40 | The public API of this library follows semantic versioning, with some caveats:
|
41 |
|
42 | - Some methods are prefixed with an underscore. These methods are internal and should not be considered part of the public API.
|
43 | - The class `Call` is only exposed due to limitations of TypeScript. It should not be considered part of the public API.
|
44 | - In general, any API that is exposed by this library but is not exposed by the `grpc` library is likely an error and should not be considered part of the public API.
|
45 | - The `grpc.experimental` namespace contains APIs that have not stabilized. Any API in that namespace may break in any minor version update.
|