update rpctransport docs (#224)

* update rpctransport docs * Update index.ts * Apply suggestions from code review * Update README.md
tatethurston · Aug 30, 2023 · a2001a3 · a2001a3
1 parent a7feb08
commit a2001a3
Show file tree

Hide file tree

Showing 20 changed files with 1,728 additions and 1,951 deletions.
diff --git a/README.md b/README.md
@@ -212,12 +212,12 @@ Clients can be configured globally, at the RPC callsite, or with [middleware](ht
 
 ##### Configuration Options
 
-| Name         | Description                                                                                                                                          | Type                   | Example                      |
-| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ---------------------------- |
-| baseURL      | The base URL for the RPC. The service path will be appended to this string.                                                                          | string                 | "https://my.server.com/"     |
-| headers      | HTTP headers to include in the RPC.                                                                                                                  | Record<string, string> | { "idempotency-key": "foo" } |
-| prefix       | A path prefix such as "/my/custom/prefix". Defaults to "/twirp", but can be set to "".                                                               | string                 | "/my/custom/prefix"          |
-| rpcTransport | The transport to use for the RPC. Defaults to `fetch`. Overrides must conform to a subset of the fetch interface defined by the `RpcTransport` type. | `RpcTransport`         | `fetch`                      |
+| Name         | Description                                                                                                                                                                                                    | Type                   | Example                      |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ---------------------------- |
+| baseURL      | The base URL for the RPC. The service path will be appended to this string.                                                                                                                                    | string                 | "https://my.server.com/"     |
+| headers      | HTTP headers to include in the RPC.                                                                                                                                                                            | Record<string, string> | { "idempotency-key": "foo" } |
+| prefix       | A path prefix such as "/my/custom/prefix". Defaults to "/twirp", but can be set to "".                                                                                                                         | string                 | "/my/custom/prefix"          |
+| rpcTransport | The transport to use for the RPC. Defaults to `fetch`, but will use `nodeHttpTransport` in Node.js environments. Overrides must conform to a subset of the fetch interface defined by the `RpcTransport` type. | `RpcTransport`         | `fetch`                      |
 
 ##### Example
 
@@ -282,15 +282,18 @@ console.log(hat);
 
 Twirp abstracts many network details from clients. Sometimes you will want more control over the underlying network request. For these cases, TwirpScript exposes `rpcTransport`.
 
-`rpcTransport` can be used to customize the `fetch` request made. For example, setting `fetch`'s [credentials](https://developer.mozilla.org/en-US/docs/Web/API/fetch#credentials) option to include (which will include cookies in cross origin requests). `rpcTransport` can be set via _global configuration_ or _call site configuration_:
+`rpcTransport` can be used to customize the network request made. `rpcTransport` can swap out the default implementation to use an [https agent](https://nodejs.org/api/https.html#https_class_https_agent), or a library like `axios`.Tthe transport only needs to implement the `RpcTransport` interface. It can also be used to "bake" in certain options, for example, setting `fetch`'s [credentials](https://developer.mozilla.org/en-US/docs/Web/API/fetch#credentials) option to `include` (which will include cookies in cross origin requests).
+
+`rpcTransport` can be set via _global configuration_ or _call site configuration_:
 
 ```ts
 import { client } from "twirpscript";
 
+// sets a custom rpcTransport for all RPC calls, globally.
 client.rpcTransport = (url, opts) =>
   fetch(url, { ...opts, credentials: "include" });
 
-// setting a custom rpcTransport for this RPC call. This transport will only be used for this RPC.
+// sets a custom rpcTransport for this RPC call. This transport will only be used for this RPC.
 const hat = await MakeHat(
   { inches: 12 },
   {
@@ -300,7 +303,7 @@ const hat = await MakeHat(
 );
 ```
 
-`rpcTransport` could also be used to replace `fetch` use entirely with something like `axios` or an [https agent](https://nodejs.org/api/https.html#https_class_https_agent).
+In Node.js environments, TwirpScript automatically uses Node's `http` or `https` client instead of fetch. You can override this behavior and use `fetch` in Node.js environments by using the global example above.
 
 #### Server
 

diff --git a/e2e/clientcompat/package.json b/e2e/clientcompat/package.json
@@ -10,7 +10,7 @@
     "twirpscript": "workspace:*"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.3",
-    "typescript": "^5.1.6"
+    "@types/jest": "^29.5.4",
+    "typescript": "^5.2.2"
   }
 }
diff --git a/e2e/protos/package.json b/e2e/protos/package.json
@@ -11,6 +11,6 @@
     "twirpscript": "workspace:*"
   },
   "devDependencies": {
-    "typescript": "^5.1.6"
+    "typescript": "^5.2.2"
   }
 }
diff --git a/examples/authentication/package.json b/examples/authentication/package.json
@@ -12,16 +12,16 @@
     "twirpscript": "workspace:*"
   },
   "devDependencies": {
-    "@babel/core": "^7.22.9",
-    "@babel/preset-env": "^7.22.9",
-    "@babel/preset-typescript": "^7.22.5",
-    "@types/jest": "^29.5.3",
-    "@types/node": "^20.4.5",
+    "@babel/core": "^7.22.11",
+    "@babel/preset-env": "^7.22.14",
+    "@babel/preset-typescript": "^7.22.11",
+    "@types/jest": "^29.5.4",
+    "@types/node": "^20.5.7",
     "@types/react-dom": "^18.2.7",
-    "babel-jest": "^29.6.2",
-    "jest": "^29.6.2",
+    "babel-jest": "^29.6.4",
+    "jest": "^29.6.4",
     "ts-loader": "^9.4.4",
-    "typescript": "^5.1.6",
+    "typescript": "^5.2.2",
     "webpack": "^5.88.2",
     "webpack-cli": "^5.1.4"
   }

diff --git a/examples/aws-lambda/package.json b/examples/aws-lambda/package.json
@@ -13,12 +13,12 @@
     "@aws-cdk/aws-lambda": "^1.204.0",
     "@aws-cdk/core": "1.204.0",
     "@types/aws-lambda": "^8.10.119",
-    "@types/jest": "^29.5.3",
-    "@types/node": "20.4.5",
-    "aws-cdk": "^2.88.0",
-    "constructs": "^10.2.69",
+    "@types/jest": "^29.5.4",
+    "@types/node": "20.5.7",
+    "aws-cdk": "^2.93.0",
+    "constructs": "^10.2.70",
     "ts-node": "^10.9.1",
-    "typescript": "~5.1.6"
+    "typescript": "~5.2.2"
   },
   "dependencies": {
     "twirpscript": "workspace:*"

diff --git a/examples/buf/package.json b/examples/buf/package.json
@@ -8,6 +8,6 @@
     "twirpscript": "workspace:*"
   },
   "devDependencies": {
-    "typescript": "^5.1.6"
+    "typescript": "^5.2.2"
   }
 }
diff --git a/examples/config-dest/package.json b/examples/config-dest/package.json
@@ -8,6 +8,6 @@
     "twirpscript": "workspace:*"
   },
   "devDependencies": {
-    "typescript": "^5.1.6"
+    "typescript": "^5.2.2"
   }
 }
diff --git a/examples/config-exclude/package.json b/examples/config-exclude/package.json
@@ -8,6 +8,6 @@
     "twirpscript": "workspace:*"
   },
   "devDependencies": {
-    "typescript": "^5.1.6"
+    "typescript": "^5.2.2"
   }
 }
diff --git a/examples/config-json/package.json b/examples/config-json/package.json
@@ -8,6 +8,6 @@
     "twirpscript": "workspace:*"
   },
   "devDependencies": {
-    "typescript": "^5.1.6"
+    "typescript": "^5.2.2"
   }
 }
diff --git a/examples/config-only-types/package.json b/examples/config-only-types/package.json
@@ -8,6 +8,6 @@
     "twirpscript": "workspace:*"
   },
   "devDependencies": {
-    "typescript": "^5.1.6"
+    "typescript": "^5.2.2"
   }
 }
diff --git a/examples/config-root/package.json b/examples/config-root/package.json
@@ -8,6 +8,6 @@
     "twirpscript": "workspace:*"
   },
   "devDependencies": {
-    "typescript": "^5.1.6"
+    "typescript": "^5.2.2"
   }
 }
diff --git a/examples/javascript-fullstack/package.json b/examples/javascript-fullstack/package.json
@@ -12,13 +12,13 @@
     "twirpscript": "workspace:*"
   },
   "devDependencies": {
-    "@babel/core": "^7.22.9",
-    "@babel/preset-env": "^7.22.9",
+    "@babel/core": "^7.22.11",
+    "@babel/preset-env": "^7.22.14",
     "@babel/preset-react": "^7.22.5",
-    "babel-jest": "^29.6.2",
+    "babel-jest": "^29.6.4",
     "babel-loader": "^9.1.3",
-    "jest": "^29.6.2",
-    "typescript": "^5.1.6",
+    "jest": "^29.6.4",
+    "typescript": "^5.2.2",
     "webpack": "^5.88.2",
     "webpack-cli": "^5.1.4"
   }

diff --git a/examples/nextjs/package.json b/examples/nextjs/package.json
@@ -10,17 +10,17 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "next": "13.4.12",
+    "next": "13.4.19",
     "react": "18.2.0",
     "react-dom": "18.2.0",
     "twirpscript": "workspace:*"
   },
   "devDependencies": {
-    "@types/node": "20.4.5",
-    "@types/react": "18.2.17",
+    "@types/node": "20.5.7",
+    "@types/react": "18.2.21",
     "@types/react-dom": "18.2.7",
-    "eslint": "8.45.0",
-    "eslint-config-next": "13.4.12",
-    "typescript": "5.1.6"
+    "eslint": "8.48.0",
+    "eslint-config-next": "13.4.19",
+    "typescript": "5.2.2"
   }
 }
diff --git a/examples/server-to-server/package.json b/examples/server-to-server/package.json
@@ -10,13 +10,13 @@
     "twirpscript": "workspace:*"
   },
   "devDependencies": {
-    "@babel/core": "^7.22.9",
-    "@babel/preset-env": "^7.22.9",
-    "@babel/preset-typescript": "^7.22.5",
-    "@types/jest": "^29.5.3",
-    "@types/node": "^20.4.5",
-    "babel-jest": "^29.6.2",
-    "jest": "^29.6.2",
-    "typescript": "^5.1.6"
+    "@babel/core": "^7.22.11",
+    "@babel/preset-env": "^7.22.14",
+    "@babel/preset-typescript": "^7.22.11",
+    "@types/jest": "^29.5.4",
+    "@types/node": "^20.5.7",
+    "babel-jest": "^29.6.4",
+    "jest": "^29.6.4",
+    "typescript": "^5.2.2"
   }
 }
diff --git a/examples/typescript-fullstack/package.json b/examples/typescript-fullstack/package.json
@@ -12,16 +12,16 @@
     "twirpscript": "workspace:*"
   },
   "devDependencies": {
-    "@babel/core": "^7.22.9",
-    "@babel/preset-env": "^7.22.9",
-    "@babel/preset-typescript": "^7.22.5",
-    "@types/jest": "^29.5.3",
-    "@types/node": "^20.4.5",
+    "@babel/core": "^7.22.11",
+    "@babel/preset-env": "^7.22.14",
+    "@babel/preset-typescript": "^7.22.11",
+    "@types/jest": "^29.5.4",
+    "@types/node": "^20.5.7",
     "@types/react-dom": "^18.2.7",
-    "babel-jest": "^29.6.2",
-    "jest": "^29.6.2",
+    "babel-jest": "^29.6.4",
+    "jest": "^29.6.4",
     "ts-loader": "^9.4.4",
-    "typescript": "^5.1.6",
+    "typescript": "^5.2.2",
     "webpack": "^5.88.2",
     "webpack-cli": "^5.1.4"
   }

diff --git a/package.json b/package.json
@@ -25,27 +25,27 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@babel/preset-env": "^7.22.9",
-    "@babel/preset-typescript": "^7.22.5",
+    "@babel/preset-env": "^7.22.14",
+    "@babel/preset-typescript": "^7.22.11",
     "@types/google-protobuf": "^3.15.6",
-    "@types/jest": "^29.5.3",
-    "@types/node": "^20.4.5",
-    "@types/prettier": "^2.7.3",
-    "@types/react": "^18.2.17",
-    "@typescript-eslint/eslint-plugin": "^6.2.0",
-    "@typescript-eslint/parser": "^6.2.0",
+    "@types/jest": "^29.5.4",
+    "@types/node": "^20.5.7",
+    "@types/prettier": "^3.0.0",
+    "@types/react": "^18.2.21",
+    "@typescript-eslint/eslint-plugin": "^6.5.0",
+    "@typescript-eslint/parser": "^6.5.0",
     "babel-loader": "^9.1.3",
     "codecov": "^3.8.3",
-    "esbuild": "^0.18.17",
-    "eslint": "^8.45.0",
-    "eslint-config-prettier": "^8.9.0",
+    "esbuild": "^0.19.2",
+    "eslint": "^8.48.0",
+    "eslint-config-prettier": "^9.0.0",
     "google-protobuf": "^3.21.2",
     "husky": "^8.0.3",
-    "jest": "^29.6.2",
-    "prettier": "^3.0.0",
+    "jest": "^29.6.4",
+    "prettier": "^3.0.3",
     "prettier-package-json": "^2.8.0",
     "protoscript": "0.0.18",
-    "typescript": "^5.1.6"
+    "typescript": "^5.2.2"
   },
   "packageManager": "[email protected]"
 }
diff --git a/packages/twirpscript/src/node/index.ts b/packages/twirpscript/src/node/index.ts
@@ -1,14 +1,28 @@
-import { RpcTransport } from "../index.js";
 import * as http from "http";
 import * as https from "https";
+import {
+  RpcTransportOpts,
+  RpcTransportResponse,
+} from "../runtime/client/index.js";
 
-export const nodeHttpTransport: RpcTransport = (url, options) => {
+type NodeHTTPTransport = (
+  url: string,
+  options: RpcTransportOpts & Omit<http.RequestOptions, "method">,
+) => Promise<RpcTransportResponse>;
+
+/**
+ * Transport for Node.js environments.
+ *
+ * This overrides `fetch` as the default transport (client.rpcTransport) when TwirpScript
+ * is imported into a Node.js environment.
+ */
+export const nodeHttpTransport: NodeHTTPTransport = (url, options) => {
   const request = url.startsWith("https") ? https.request : http.request;
   return new Promise((resolve, reject) => {
     const chunks: Buffer[] = [];
     const req = request(
       url,
-      { method: options.method, headers: options.headers },
+      { ...options, method: options.method, headers: options.headers },
       (res) => {
         const onResolve = () => {
           const statusCode = res.statusCode ?? 500;

diff --git a/packages/twirpscript/src/runtime/client/index.ts b/packages/twirpscript/src/runtime/client/index.ts
@@ -30,7 +30,7 @@ interface MiddlewareConfig {
    */
   headers: Record<string, string>;
   /**
-   * The transport to use for the RPC. Defaults to `fetch`. Overrides must conform to a subset of the fetch interface defined by the `RpcTransport` type.
+   * The transport to use for the RPC. Defaults to `fetch`, but will use `nodeHttpTransport` in Node.js environments. Overrides must conform to a subset of the fetch interface defined by the `RpcTransport` type.
    */
   rpcTransport: RpcTransport;
 }
@@ -84,7 +84,7 @@ interface Client extends ClientConfiguration {
    */
   off: (...args: Parameters<TwirpClientEvent<MiddlewareConfig>["off"]>) => this;
   /**
-   * The transport to use for the RPC. Defaults to `fetch`. Overrides must conform to a subset of the fetch interface defined by the `RpcTransport` type.
+   * The transport to use for the RPC. Defaults to `fetch`, but will use `nodeHttpTransport` in Node.js environments. Overrides must conform to a subset of the fetch interface defined by the `RpcTransport` type.
    */
   rpcTransport: RpcTransport;
 }

diff --git a/packages/twirpscript/tsconfig.json b/packages/twirpscript/tsconfig.json
@@ -3,6 +3,7 @@
   "compilerOptions": {
     "rootDir": "./src",
     "outDir": "./dist",
-    "moduleResolution": "Node16"
+    "moduleResolution": "NodeNext",
+    "module": "NodeNext"
   }
 }