Merge pull request #1996 from josephharrington/patch-1

Document grpc-js supported channel args in readme

PACKAGE-COMPARISON.md

@@ -28,22 +28,5 @@ Supported Electron Versions | All | >= 3
 Supported Platforms | Linux, Windows, MacOS | All
 Supported Architectures | x86, x86-64, ARM7+ | All
 
-In addition, all channel arguments defined in [this header file](https://github.com/grpc/grpc/blob/master/include/grpc/impl/codegen/grpc_types.h) are handled by the `grpc` library. Of those, the following are handled by the `@grpc/grpc-js` library:
-
- - `grpc.ssl_target_name_override`
- - `grpc.primary_user_agent`
- - `grpc.secondary_user_agent`
- - `grpc.default_authority`
- - `grpc.keepalive_time_ms`
- - `grpc.keepalive_timeout_ms`
- - `grpc.keepalive_permit_without_calls`
- - `grpc.service_config`
- - `grpc.max_concurrent_streams`
- - `grpc.initial_reconnect_backoff_ms`
- - `grpc.max_reconnect_backoff_ms`
- - `grpc.use_local_subchannel_pool`
- - `grpc.max_send_message_length`
- - `grpc.max_receive_message_length`
- - `grpc.enable_http_proxy`
- - `channelOverride`
- - `channelFactoryOverride`
+In addition, all channel arguments defined in [this header file](https://github.com/grpc/grpc/blob/master/include/grpc/impl/codegen/grpc_types.h) are handled by the `grpc` library.
+Of those, a subset are handled by the `@grpc/grpc-js` library. See [the README](https://github.com/grpc/grpc-node/blob/master/packages/grpc-js/README.md#supported-channel-options) for `@grpc/grpc-js` for the list of supported channel options.

packages/grpc-js/README.md

@@ -36,6 +36,28 @@ This library does not directly handle `.proto` files. To use `.proto` files with
 - 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`.
 - 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`.
 - If you have a server and you are using `Server#bind` to bind ports, you will need to use `Server#bindAsync` instead.
+- 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.
+- 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`.
+
+## Supported Channel Options
+Many channel arguments supported in `grpc` are not supported in `@grpc/grpc-js`. The channel arguments supported by `@grpc/grpc-js` are:
+  - `grpc.ssl_target_name_override`
+  - `grpc.primary_user_agent`
+  - `grpc.secondary_user_agent`
+  - `grpc.default_authority`
+  - `grpc.keepalive_time_ms`
+  - `grpc.keepalive_timeout_ms`
+  - `grpc.keepalive_permit_without_calls`
+  - `grpc.service_config`
+  - `grpc.max_concurrent_streams`
+  - `grpc.initial_reconnect_backoff_ms`
+  - `grpc.max_reconnect_backoff_ms`
+  - `grpc.use_local_subchannel_pool`
+  - `grpc.max_send_message_length`
+  - `grpc.max_receive_message_length`
+  - `grpc.enable_http_proxy`
+  - `channelOverride`
+  - `channelFactoryOverride`
 
 ## Some Notes on API Guarantees