Remove Proxy API as default API

Author: timonson

README.md

@@ -1,177 +1,178 @@
 # gentle_rpc
 
-JSON-RPC 2.0 library with WebSockets and HTTP support for
+JSON-RPC 2.0 library with HTTP and WebSockets support for
 [deno](https://github.com/denoland/deno) and the browser.
 
 ## Server
 
 ### respond
 
-Takes the arguments `methods`, `req` and `options`. You can set options for an
-additional server argument, protocol, headers and public error stacks.
+Takes `Methods`, `ServerRequest` and `Options`.
 
 ```typescript
-import { serve } from "https://deno.land/std@0.97.0/http/server.ts";
-import { respond } from "https://deno.land/x/gentle_rpc/mod.ts";
+import { serve } from "https://deno.land/std@0.97.0/http/server.ts"
+import { respond } from "https://deno.land/x/gentle_rpc/mod.ts"
 
-const server = serve("0.0.0.0:8000");
+const server = serve("0.0.0.0:8000")
 const rpcMethods = {
-  sayHello: (w: [string]) => `Hello ${w}`,
+  sayHello: ([w]: [string]) => `Hello ${w}`,
   callNamedParameters: ({ a, b, c }: { a: number; b: number; c: string }) =>
     `${c} ${a * b}`,
   animalsMakeNoise: (noise: string[]) =>
     noise.map((el) => el.toUpperCase()).join(" "),
-};
+}
 
-console.log("listening on 0.0.0.0:8000");
+console.log("listening on 0.0.0.0:8000")
 
 for await (const req of server) {
   // HTTP:
-  await respond(rpcMethods, req);
+  respond(rpcMethods, req)
   // WebSockets:
-  await respond(rpcMethods, req, { proto: "ws" });
+  respond(rpcMethods, req, { proto: "ws" })
 }
 ```
 
-#### custom errors
+#### CustomError
 
 Throw a `CustomError` to send a server-defined error response.
 
 ```typescript
-import { CustomError, respond } from "https://deno.land/x/gentle_rpc/mod.ts";
+import { CustomError, respond } from "https://deno.land/x/gentle_rpc/mod.ts"
 
 //..
-await respond({
-  throwError: () => {
-    throw new CustomError(
-      -32000, // the JSON-RPC error code. Note, must be -32000 to -32099
-      "An error occurred", // the error message, a short sentence
-      { details: "..." }, // optional additional details, can be an object, primitive, etc (any)
-    );
+await respond(
+  {
+    throwError: () => {
+      throw new CustomError(
+        -32040, // the JSON-RPC error code. Note, must be -32040 to -32099
+        "An error occurred", // the error message, a short sentence
+        { details: "..." } // optional additional details, can be any `JsonValue`
+      )
+    },
   },
-}, req);
+  req
+)
 //..
 ```
 
 ## Client
 
 #### createRemote
 
-Takes a `resource` for HTTP or a `WebSocket` for WebSockets and returns a
-TypeScript `Proxy` or `Promise<Proxy>` which we will call `remote` from now on.
+Takes a `Resource` for HTTP or a `WebSocket` for WebSockets and returns
+`Remote`.
 
 ```typescript
-import { createRemote } from "https://deno.land/x/gentle_rpc/mod.ts";
+import { createRemote } from "https://deno.land/x/gentle_rpc/mod.ts"
 // Or import directly into the browser with:
-import { createRemote } from "https://cdn.jsdelivr.net/gh/timonson/gentle_rpc@v2.8/client/dist/remote.js";
+import { createRemote } from "https://cdn.jsdelivr.net/gh/timonson/gentle_rpc@v2.8/client/dist/remote.js"
 
 // HTTP:
-const remote = createRemote("http://0.0.0.0:8000");
+const remote = createRemote("http://0.0.0.0:8000")
 
 // WebSocket:
-const remote = await createRemote(new WebSocket("ws://0.0.0.0:8000"));
+const remote = await createRemote(new WebSocket("ws://0.0.0.0:8000"))
 ```
 
 ### HTTP
 
-#### remote
+#### call
 
-All `remote` methods take an `Array<JsonValue>` or `Record<string, JsonValue>`
-object and return `Promise<JsonValue | undefined>`.
+Takes a string and an `Array<JsonValue>` or `Record<string, JsonValue>` object
+and returns `Promise<JsonValue>`.
 
 ```typescript
-const greeting = await remote.sayHello(["World"]);
+const greeting = await remote.call("sayHello", ["World"])
 // Hello World
 
-const namedParams = await remote.callNamedParameters({
+const namedParams = await remote.call("callNamedParameters", {
   a: 5,
   b: 10,
   c: "result:",
-});
+})
 // result: 50
 ```
 
 ##### notification
 
+Using the option `{ isNotification: true }` will retun `Promise<undefined>`.
+
 ```typescript
-const notification = await remote.sayHello.notify(["World"]);
+const notification = await remote.call("sayHello", ["World"], {
+  isNotification: true,
+})
 // undefined
 ```
 
-##### auth
+##### jwt
 
-This method will set the `Authorization` header to `` `Bearer ${jwt}` ``.
+Adding a jwt to the optional property `jwt` will set the `Authorization` header
+to `` `Bearer ${jwt}` ``.
 
 ```typescript
-const greeting = await remote.sayHello.auth(jwt)(["World"]);
-// Hello World
+const user = await remote.call("login", undefined, { jwt })
+// Bob
 ```
 
-##### batch
+#### batch
 
 ```typescript
-const noise1 = await remote.animalsMakeNoise.batch([
-  ["miaaow"],
-  ["wuuuufu", "wuuuufu"],
-  ["iaaaiaia", "iaaaiaia", "iaaaiaia"],
-  ["fiiiiire"],
-]);
-// [ "MIAAOW", "WUUUUFU WUUUUFU", "IAAAIAIA IAAAIAIA IAAAIAIA", "FIIIIIRE" ]
+const noise1 = await remote.batch([
+  {
+    animalsMakeNoise: [
+      ["miaaow"],
+      ["wuuuufu", "wuuuufu"],
+      ["iaaaiaia", "iaaaiaia", "iaaaiaia"],
+      ["fiiiiire"],
+    ],
+    sayHello: [["World"], undefined, ["World"]],
+  },
+])
+// [ "MIAAOW", "WUUUUFU WUUUUFU", "IAAAIAIA IAAAIAIA IAAAIAIA", "FIIIIIRE", "Hello World", "Hello ", "Hello World" ]
 ```
 
-##### batch with different methods
-
-Takes either a `batchObject` or a `batchArray` as argument and returns a
-promise.
+The following example uses the object keys `cat`, `dog`, `donkey`, `dragon` as
+RPC _request object ids_ under the hood. The returned _RPC result_ values will
+be assigned to these keys.
 
 ```typescript
-await remote.batch({
+let noise2 = await remote.batch({
   cat: ["sayHello", ["miaaow"]],
   dog: ["animalsMakeNoise", ["wuuuufu"]],
   donkey: ["sayHello"],
   dragon: ["animalsMakeNoise", ["fiiiiire", "fiiiiire"]],
-});
+})
 // { cat: "Hello miaaow", dog: "WUUUUFU", donkey: "Hello ", dragon: "FIIIIIRE FIIIIIRE" }
 ```
 
-The example above uses the object keys `cat`, `dog`, `donkey`, `dragon` as RPC
-_request object ids_ under the hood. The returned _RPC result_ values will be
-assigned to these keys.
-
-For other use cases you might prefer the following example:
-
-```typescript
-await remote.batch([
-  "animalsMakeNoise",
-  ["miaaow"],
-  ["wuuuufu", "wuuuufu"],
-  ["iaaaiaia", "iaaaiaia", "iaaaiaia"],
-  ["fiiiiire"],
-]);
-// [ "MIAAOW", "WUUUUFU WUUUUFU", "IAAAIAIA IAAAIAIA IAAAIAIA", "FIIIIIRE" ]
-```
-
 ### WebSockets
 
 The support for WebSockets is still experimental and has not been fully tested
 yet.
 
-#### remote
+#### call
 
-All `remote` methods take an `Array<JsonValue>` or `Record<string, JsonValue>`
-object and return `Promise<JsonValue | undefined>`.
+Takes a string and an `Array<JsonValue>` or `Record<string, JsonValue>` object
+and returns `Promise<JsonValue | undefined>`.
 
 ```typescript
-const noise = await remote.animalsMakeNoise(["wuufff"]);
-console.log(noise);
+const noise = await remote.call("callNamedParameters", {
+  a: 10,
+  b: 20,
+  c: "The result is:",
+})
+// The result is: 200
+
+const notification = await remote.call("sayHello", ["World"], true)
+// undefined
 
-remote.socket.close();
+remote.socket.close()
 ```
 
 ##### notification
 
 ```typescript
-const notification = await remote.animalsMakeNoise.notify(["wuufff"]);
+const notification = await remote.animalsMakeNoise.notify(["wuufff"])
 ```
 
 ##### messaging between multiple clients
@@ -185,41 +186,61 @@ Other clients can _listen to_ and _emit_ messages by _subscribing_ to the same
 method.
 
 ```typescript
-// First client
-export async function run(iter: AsyncGenerator<unknown>) {
+const firstClient = await createRemote(new WebSocket("ws://0.0.0.0:8000"))
+const secondClient = await createRemote(new WebSocket("ws://0.0.0.0:8000"))
+
+async function run(iter: AsyncGenerator<unknown>) {
   try {
     for await (let x of iter) {
-      console.log(x);
+      console.log(x)
     }
   } catch (err) {
-    console.log(err.message, err.code);
+    console.log(err.message, err.code, err.data)
   }
 }
 
-const greeting = remote.sayHello.subscribe();
-run(greeting.generator);
-greeting.emit(["first"]);
+const greeting = firstClient.subscribe("sayHello")
+const second = secondClient.subscribe("sayHello")
+
+run(greeting.generator)
+run(second.generator)
+greeting.emit({ w: "first" })
+second.emitBatch([{ w: "second" }, { w: "third" }])
+// Hello first
 // Hello first
 // Hello second
+// Hello second
+// Hello third
 // Hello third
 ```
 
+## Proxy API
+
+Optionally, you can import _syntactical sugar_ and use a more friendly API
+supported by `Proxy` objects.
+
 ```typescript
-// Second client
-const greeting = remote.sayHello.subscribe();
-run(greeting.generator);
-greeting.emitBatch([["second"], ["third"]]);
-// Hello first
-// Hello second
-// Hello third
+import { createRemote, HttpProxy, httpProxyHandler } from "../../mod.ts"
+
+const remote = new Proxy<HttpProxy>(
+  createRemote("http://0.0.0.0:8000"),
+  httpProxyHandler
+)
 
-// You can optionally unsubscribe:
-greeting.unsubscribe();
+let greeting = await remote.sayHello(["World"])
+// Hello World
+
+const namedParams = await remote.callNamedParameters({
+  a: 5,
+  b: 10,
+  c: "result:",
+})
+// result: 50
 ```
 
 ## Examples and Tests
 
-Checkout the
+Please checkout the
 [examples](https://github.com/timonson/gentle_rpc/tree/master/examples) and
 [tests](https://github.com/timonson/gentle_rpc/tree/master/tests) folders for
 more detailed examples.

client/creation.ts

@@ -1,9 +1,9 @@
-import { generate as generateV4Uuid } from "./deps.ts";
-
 import type { RpcBatchRequest, RpcRequest } from "../json_rpc_types.ts";
+import type { BatchArrayInput, BatchObjectInput } from "./http.ts";
 
-export type BatchArrayInput = [string, ...RpcRequest["params"][]];
-export type BatchObjectInput = Record<string, [string, RpcRequest["params"]?]>;
+function generateId() {
+  return window.crypto.getRandomValues(new Uint32Array(1))[0].toString(16);
+}
 
 export function createRequest({
   method,
@@ -21,7 +21,7 @@ export function createRequest({
     method,
   };
   params && (rpcRequest.params = params);
-  id = isNotification ? undefined : id !== undefined ? id : generateV4Uuid();
+  id = isNotification ? undefined : id !== undefined ? id : generateId();
   id !== undefined && (rpcRequest.id = id);
   return rpcRequest;
 }
@@ -31,15 +31,11 @@ export function createRequestBatch(
   isNotification = false,
 ): RpcBatchRequest {
   return Array.isArray(batchObj)
-    ? batchObj
-      .map((el, _, array) =>
-        createRequest({
-          method: array[0] as string,
-          params: el as RpcRequest["params"],
-          isNotification,
-        })
+    ? batchObj.map((el) =>
+      Object.entries(el).map(([method, arr]) =>
+        arr.map((params) => createRequest({ method, params, isNotification }))
       )
-      .slice(1)
+    ).flat(2)
     : Object.entries(batchObj).map(([key, value]) =>
       createRequest({
         method: value[0],