From 78631cdad826316e0a5d562fea55b2571484e615 Mon Sep 17 00:00:00 2001
From: Joey Harrington <jharrington@netflix.com>
Date: Mon, 27 Dec 2021 12:55:16 -0800
Subject: [PATCH] Document grpc-js supported channel args in readme

This moves the list of supported channel arguments from PACKAGE_COMPARISON.md into the readme, and also adds a link to the package comparison doc.

resolves #1982, resolves #1983
---
 PACKAGE-COMPARISON.md      | 21 ++-------------------
 packages/grpc-js/README.md | 22 ++++++++++++++++++++++
 2 files changed, 24 insertions(+), 19 deletions(-)

diff --git a/PACKAGE-COMPARISON.md b/PACKAGE-COMPARISON.md
index fa0ea319..f0c44419 100644
--- a/PACKAGE-COMPARISON.md
+++ b/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.
diff --git a/packages/grpc-js/README.md b/packages/grpc-js/README.md
index df44264c..4799b0f4 100644
--- a/packages/grpc-js/README.md
+++ b/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