| 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 | If you need a feature from the `grpc` package that is not provided by the `@grpc/grpc-js`, please file a feature request with that information.
|
| 29 |
|
| 30 | This library does not directly handle `.proto` files. To use `.proto` files with this library we recommend using the `@grpc/proto-loader` package.
|
| 31 |
|
| 32 | ## Migrating from [`grpc`](https://www.npmjs.com/package/grpc)
|
| 33 |
|
| 34 | `@grpc/grpc-js` is almost a drop-in replacement for `grpc`, but you may need to make a few code changes to use it:
|
| 35 |
|
| 36 | - 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`.
|
| 37 | - 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`.
|
| 38 | - If you have a server and you are using `Server#bind` to bind ports, you will need to use `Server#bindAsync` instead.
|
| 39 | - If you are using any channel options supported in `grpc` but not supported in `@grpc/grpc-js`, you may need to adjust your code to handle the different behavior. Refer to [the list of supported options](#supported-channel-options) below.
|
| 40 | - Refer to the [detailed package comparison](https://github.com/grpc/grpc-node/blob/master/PACKAGE-COMPARISON.md) for more details on the differences between `grpc` and `@grpc/grpc-js`.
|
| 41 |
|
| 42 | ## Supported Channel Options
|
| 43 | Many channel arguments supported in `grpc` are not supported in `@grpc/grpc-js`. The channel arguments supported by `@grpc/grpc-js` are:
|
| 44 | - `grpc.ssl_target_name_override`
|
| 45 | - `grpc.primary_user_agent`
|
| 46 | - `grpc.secondary_user_agent`
|
| 47 | - `grpc.default_authority`
|
| 48 | - `grpc.keepalive_time_ms`
|
| 49 | - `grpc.keepalive_timeout_ms`
|
| 50 | - `grpc.keepalive_permit_without_calls`
|
| 51 | - `grpc.service_config`
|
| 52 | - `grpc.max_concurrent_streams`
|
| 53 | - `grpc.initial_reconnect_backoff_ms`
|
| 54 | - `grpc.max_reconnect_backoff_ms`
|
| 55 | - `grpc.use_local_subchannel_pool`
|
| 56 | - `grpc.max_send_message_length`
|
| 57 | - `grpc.max_receive_message_length`
|
| 58 | - `grpc.enable_http_proxy`
|
| 59 | - `grpc.default_compression_algorithm`
|
| 60 | - `grpc.enable_channelz`
|
| 61 | - `grpc.dns_min_time_between_resolutions_ms`
|
| 62 | - `grpc.enable_retries`
|
| 63 | - `grpc.per_rpc_retry_buffer_size`
|
| 64 | - `grpc.retry_buffer_size`
|
| 65 | - `grpc.service_config_disable_resolution`
|
| 66 | - `grpc-node.max_session_memory`
|
| 67 | - `channelOverride`
|
| 68 | - `channelFactoryOverride`
|
| 69 |
|
| 70 | ## Some Notes on API Guarantees
|
| 71 |
|
| 72 | The public API of this library follows semantic versioning, with some caveats:
|
| 73 |
|
| 74 | - Some methods are prefixed with an underscore. These methods are internal and should not be considered part of the public API.
|
| 75 | - The class `Call` is only exposed due to limitations of TypeScript. It should not be considered part of the public API.
|
| 76 | - 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.
|
| 77 | - The `grpc.experimental` namespace contains APIs that have not stabilized. Any API in that namespace may break in any minor version update.
|