Add a typed RPC client

Author: blakeembrey

README.md

@@ -18,36 +18,83 @@ npm install io-ts fp-ts --save
 
 ## Usage
 
+This package makes no assumptions about the transportation layer, for client or server.
+
+### Methods
+
+The methods definition uses [`io-ts`](https://github.com/gcanti/io-ts) to encode and decode requests or responses.
+
 ```ts
-import { createHandler } from "@borderlesslabs/json-rpc";
 import * as t from "io-ts";
 
-const rpc = createRpc(
-  {
-    hello: {
-      // `request` is required, even when empty.
-      request: t.type({}),
-      response: t.string
-    },
-    echo: {
-      // Specify `request` parameters as keys of the object.
-      request: t.type({ arg: t.string }),
-      response: t.string
-    }
+const methods = {
+  hello: {
+    // `request` is required, even when empty.
+    request: t.type({}),
+    response: t.string
   },
-  {
-    hello: _ => "Hello World!",
-    echo: ({ arg }) => arg
+  echo: {
+    // Specify `request` parameters as keys of the object.
+    request: t.type({ arg: t.string }),
+    response: t.string
   }
-);
+};
+```
 
-const res = await rpc({
+### Server
+
+The server takes the methods and a dictionary of matching resolvers.
+
+```ts
+import { createClient } from "@borderlesslabs/json-rpc";
+
+const server = createServer(methods, {
+  hello: _ => "Hello World!",
+  echo: ({ arg }) => arg
+});
+
+const res = await server({
   jsonrpc: "2.0",
   id: "test",
   method: "hello"
 }); //=> { jsonrpc: "2.0", id: "test", result: "Hello World!" }
 ```
 
+### Client
+
+The client takes the methods and a function to `send` the JSON-RPC request.
+
+```ts
+import { createClient } from "@borderlesslabs/json-rpc";
+
+const client = createClient(methods, async x => {
+  const res = await fetch("...", {
+    body: JSON.stringify(x),
+    headers: {
+      "Content-Type": "application/json"
+    }
+  });
+
+  return res.json();
+});
+
+const result = await client({
+  method: "hello",
+  params: {}
+}); //=> "Hello World!"
+
+const results = await client.batch(
+  {
+    method: "hello",
+    params: {}
+  },
+  {
+    method: "echo",
+    params: { arg: "Test" }
+  }
+); //=> ["Hello World!", "Test"]
+```
+
 ## License
 
 MIT

package-lock.json

@@ -96,5 +96,8 @@
   "peerDependencies": {
     "io-ts": "^2.0.4",
     "fp-ts": "^2.4.0"
+  },
+  "dependencies": {
+    "make-error": "^1.3.5"
   }
 }

package.json

@@ -1,24 +1,25 @@
 import * as t from "io-ts";
-import { createRpc, parse } from "./index";
-import { isLeft, isRight } from "fp-ts/lib/Either";
+import { createServer, parse, createClient } from "./index";
+import { isLeft, isRight, either } from "fp-ts/lib/Either";
 
 describe("json rpc", () => {
-  const rpc = createRpc(
-    {
-      hello: {
-        request: t.type({}),
-        response: t.string
-      },
-      echo: {
-        request: t.type({ arg: t.string }),
-        response: t.string
-      }
+  const methods = {
+    hello: {
+      request: t.type({}),
+      response: t.string
     },
-    {
-      hello: _ => "Hello World!",
-      echo: ({ arg }) => arg
+    echo: {
+      request: t.type({ arg: t.string }),
+      response: t.string
     }
-  );
+  };
+
+  const server = createServer(methods, {
+    hello: _ => "Hello World!",
+    echo: ({ arg }) => arg
+  });
+
+  const client = createClient(methods, x => server(x, undefined));
 
   describe("parse", () => {
     it("should parse json", () => {
@@ -42,10 +43,10 @@ describe("json rpc", () => {
     });
   });
 
-  describe("rpc", () => {
+  describe("server", () => {
     describe("object", () => {
       it("should respond", async () => {
-        const res = await rpc({
+        const res = await server({
           jsonrpc: "2.0",
           id: "test",
           method: "hello"
@@ -59,7 +60,7 @@ describe("json rpc", () => {
       });
 
       it("should not respond to notification", async () => {
-        const res = await rpc({
+        const res = await server({
           jsonrpc: "2.0",
           method: "hello"
         });
@@ -68,7 +69,7 @@ describe("json rpc", () => {
       });
 
       it("should accept an array of parameters", async () => {
-        const res = await rpc({
+        const res = await server({
           jsonrpc: "2.0",
           id: "test",
           method: "echo",
@@ -83,7 +84,7 @@ describe("json rpc", () => {
       });
 
       it("should accept an object of parameters", async () => {
-        const res = await rpc({
+        const res = await server({
           jsonrpc: "2.0",
           id: "test",
           method: "echo",
@@ -100,7 +101,7 @@ describe("json rpc", () => {
 
     describe("array", () => {
       it("should respond", async () => {
-        const res = await rpc([
+        const res = await server([
           {
             jsonrpc: "2.0",
             id: 1,
@@ -130,7 +131,7 @@ describe("json rpc", () => {
 
     describe("invalid", () => {
       it("should fail on malformed request", async () => {
-        const res = await rpc(123);
+        const res = await server(123);
 
         expect(res).toEqual({
           jsonrpc: "2.0",
@@ -143,7 +144,7 @@ describe("json rpc", () => {
       });
 
       it("should fail on malformed request object", async () => {
-        const res = await rpc({});
+        const res = await server({});
 
         expect(res).toEqual({
           jsonrpc: "2.0",
@@ -156,7 +157,7 @@ describe("json rpc", () => {
       });
 
       it("should fail on empty batch request", async () => {
-        const res = await rpc([]);
+        const res = await server([]);
 
         expect(res).toEqual({
           jsonrpc: "2.0",
@@ -169,7 +170,7 @@ describe("json rpc", () => {
       });
 
       it("should fail on invalid request rpc id", async () => {
-        const res = await rpc({
+        const res = await server({
           jsonrpc: "2.0",
           id: {}
         });
@@ -185,7 +186,7 @@ describe("json rpc", () => {
       });
 
       it("should fail on fractional numeric request rpc id", async () => {
-        const res = await rpc({
+        const res = await server({
           jsonrpc: "2.0",
           id: 123.5
         });
@@ -201,7 +202,7 @@ describe("json rpc", () => {
       });
 
       it("should fail on method not found", async () => {
-        const res = await rpc({
+        const res = await server({
           jsonrpc: "2.0",
           id: "test",
           method: "missing"
@@ -218,7 +219,7 @@ describe("json rpc", () => {
       });
 
       it("should fail on missing parameters", async () => {
-        const res = await rpc({
+        const res = await server({
           jsonrpc: "2.0",
           id: "test",
           method: "echo"
@@ -236,7 +237,7 @@ describe("json rpc", () => {
       });
 
       it("should fail on invalid parameters", async () => {
-        const res = await rpc({
+        const res = await server({
           jsonrpc: "2.0",
           id: "test",
           method: "echo",
@@ -254,7 +255,7 @@ describe("json rpc", () => {
       });
 
       it("should fail on invalid parameters", async () => {
-        const res = await rpc({
+        const res = await server({
           jsonrpc: "2.0",
           id: "test",
           method: "echo",
@@ -272,4 +273,54 @@ describe("json rpc", () => {
       });
     });
   });
+
+  describe("client", () => {
+    describe("request", () => {
+      it("should make a request", async () => {
+        const result = await client({ method: "hello", params: {} });
+
+        expect(result).toEqual("Hello World!");
+      });
+
+      it("should make a notification request", async () => {
+        const result = await client({
+          method: "hello",
+          params: {},
+          async: true
+        });
+
+        expect(result).toEqual(undefined);
+      });
+    });
+
+    describe("batch", () => {
+      it("should make a batch request", async () => {
+        const result = await client.batch(
+          { method: "hello", params: {} },
+          { method: "echo", params: { arg: "test" } }
+        );
+
+        expect(result).toEqual(["Hello World!", "test"]);
+      });
+
+      it("should make a batch notification request", async () => {
+        const result = await client.batch(
+          { method: "hello", params: {}, async: true },
+          { method: "echo", params: { arg: "test" }, async: true }
+        );
+
+        expect(result).toEqual([undefined, undefined]);
+      });
+
+      it("should handle mixed batch responses", async () => {
+        const result = await client.batch(
+          { method: "hello", params: {}, async: true },
+          { method: "echo", params: { arg: "test" } },
+          { method: "hello", params: {}, async: true }
+        );
+
+        expect(result).toEqual([undefined, "test", undefined]);
+      });
+    });
+  });
 });