Configurable methods

.eslintignore

@@ -0,0 +1,5 @@
+node_modules/
+build/
+coverage/
+examples/webworker/public
+examples/websocket/public

.eslintrc

@@ -0,0 +1,29 @@
+{
+  // enable airbnb eslint from https://www.npmjs.com/package/eslint-config-airbnb
+  "extends": "airbnb",
+    "rules": {
+      "consistent-return": [0, { "treatUndefinedAsUnspecified": true }],
+      "import/no-extraneous-dependencies": ["error", {"devDependencies": true}],
+      "no-multi-assign": "off",
+      "no-console": "off",
+      "no-plusplus": "off",
+      "camelcase": "off",
+      "comma-dangle": "off",
+      "prefer-template": "off",
+      "object-curly-newline": "off",
+      "no-restricted-globals": "off", // WTF?  `self` should be fine
+      "quotes": [ "error", "single", { "allowTemplateLiterals": true}],
+      "arrow-body-style": "off",
+      "import/no-unresolved": "off",
+      "max-len": [2, 120, 2]
+    },
+    "env": {
+      "browser": true,
+      "node": true,
+      "worker": true
+    },
+    "globals": {
+      "it": "readonly",
+      "describe": "readonly"
+    }
+}

.github/workflows/workflow.yml

@@ -0,0 +1,17 @@
+name: CI
+on: push
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+        with:
+          fetch-depth: 1
+      - name: Setup Node.js
+        uses: actions/setup-node@v1
+        with:
+          node-version: 14.15.1
+      - name: Installing dependencies
+        run: npm install
+      - name: Running tests
+        run: npm test

README.md

@@ -1,20 +1,10 @@
 # rawr (a.k.a. RAWRpc)
 
-[![NPM](https://nodei.co/npm/rawr.png?compact=true)](https://nodei.co/npm/rawr/)
-
-
-[![CircleCI](https://circleci.com/gh/iceddev/rawr.svg?style=svg)](https://circleci.com/gh/iceddev/rawr)
-
-[![Coverage Status](https://coveralls.io/repos/iceddev/rawr/badge.svg?branch=master)](https://coveralls.io/r/iceddev/rawr?branch=master)
-
-
-
-Remote Procedure Calls ([JSON-RPC](http://json-rpc.org/wiki/specification)) sent over any [EventEmitter](https://nodejs.org/dist/latest-v8.x/docs/api/events.html#events_class_eventemitter)-based transport.  [WebWorkers](/transports/worker), [WebSockets](/transports/websocket), [MQTT](/transports/mqtt), and more!
-
-![RAWRpc](https://rawgithub.com/phated/badart/master/reptar_rawr.jpg)
-
+[![NPM](https://nodei.co/npm/rawr.svg)](https://nodei.co/npm/rawr/)  ![example workflow](https://github.com/iceddev/rawr/actions/workflows/workflow.yml/badge.svg)
 
+Remote Procedure Calls ([JSON-RPC](https://www.jsonrpc.org/specification)) sent over any [EventEmitter](https://nodejs.org/dist/latest-v12.x/docs/api/events.html#events_class_eventemitter)-based transport.  [WebWorkers](/transports/worker), [WebSockets](/transports/websocket), [MQTT](/transports/mqtt), and more!
 
+![RAWRpc](rawr.jpg)
 
 ## Installation
 
@@ -23,62 +13,79 @@ Remote Procedure Calls ([JSON-RPC](http://json-rpc.org/wiki/specification)) sent
 
 ## Using rawr with a webworker
 
-Every rawr client can act as both a client and a server, and make RPC calls in either direction.
+Every rawr peer can act as both a client and a server, and make remote method calls in either direction.
 
-For example, if we want to use rawr to make calls to a webworker:
-```javascript
-import rawr from 'rawr';
-import { dom } from 'rawr/tansports/worker';
+For example, we can use methods that belong to a webworker.
 
-const myWorker = new Worker('/my-worker.js');
+#### In our worker.js file:
+```javascript
+import rawr, { transports } from 'rawr';
 
-const peer = rawr({transport: dom(myWorker)});
+// In this instantiation, we can pass in an object to 
+// `methods` that is exposed to our web page (see below)
+const peer = rawr({
+  transport: transports.worker(),
+  methods: { calculatePrimes },
+});
 
-const result = await peer.methods.doSomething('lots of data');
+function calculatePrimes(howMany) {
+  // Do something CPU intensive in this thread that
+  // would otherwise be too expensive for our web page
+  ...
+  return primes;
+}
 ```
 
-Our WebWorker code might look something like:
+#### In our web page:
 ```javascript
-import rawr from 'rawr';
-import { worker } from 'rawr/tansports/worker';
+import rawr, { transports } from 'rawr';
 
-const peer = rawr({transport: worker(), handlers: {doSomething}});
+const myWorker = new Worker('/worker.js');
+const peer = rawr({transport: transports.worker(myWorker)});
 
-function doSomething(inputData) {
-  // do some heavy lifting in this thread
-  // return a result
-}
+// Remote methods are *~automatically available~*
+const result = await peer.methods.calculatePrimes(349582);
 ```
 
+The methods are available to the rawr peer through the magic of [Proxies](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
+
+![Magic](magic.gif)
+
 ## Using rawr with a websocket
 
-We could even to this type of call to a remote server such as a websocket.
-Simply use a differnt transport:
+We could use rawr to make calls to a remote server such as a websocket.
+Simply use a different transport.
+
+#### on our web page:
 ```javascript
-import rawr from 'rawr';
-import wsTransport from 'rawr/tansports/websocket';
+import rawr, { transports } from 'rawr';
 
-const ws = new WebSocket('ws://localhost:8080');
+const socket = new WebSocket('ws://localhost:8080');
 
-ws.onopen = (event) => {
+socket.onopen = (event) => {
   // create the rawr peer
-  const peer = rawr({transport: wsTransport(ws)});
+  const peer = rawr({
+    transport: transports.websocket(socket)
+  });
 };
 ```
 
-The websocket server could even make arbitrary calls to the client!
+The websocket server could even make *arbitrary calls to the client!*
+
+#### on the server:
 ```javascript
 socketServer.on('connection', (socket) => {
-  const peer = rawr({ transport: wsTransport(socket) })
+  const peer = rawr({ 
+    transport: transports.websocket(socket) 
+  });
 
-  const val = await peer.methods.doSomethingOnClient();
-
+  const result = await peer.methods.doSomethingOnClient();
 });
 ```
 
 ## Handling Notifications
 
-Peers can also send each other notifications:
+Peers can also send each other [notifications](https://www.jsonrpc.org/specification#notification):
 
 ```javascript
 peer.notifiers.saySomething('hello');
@@ -91,3 +98,41 @@ peer.notifications.onsaySomething((words) => {
 });
 ```
 
+
+## Transports
+
+Transporst are simply [EventEmitters](https://nodejs.org/dist/latest-v12.x/docs/api/events.html#events_class_eventemitter) that do two things:
+
+They emit ([json-rpc](https://www.jsonrpc.org/specification)) objects on an `rpc` topic when receiving data.
+```javascript
+transport.emit('rpc', {jsonrpc:'2.0', id: 1, method: 'add', params: [2, 3]});
+```
+
+They send rpc objects out.
+```javascript
+transport.send({jsonrpc:'2.0', id: 1, method: 'subtract', params: [5, 4]});
+```
+
+While, websockets, mqtt, and webworkers are common, transports could be built from any form of communication you wish!
+
+
+## Custom Configuration for Method invocations
+
+if you need to pass configuration specific method invocations, you can uses the `methodsExt` property of a rawr instance.
+
+For example, if you want to specify a specific timeout for a method call you can use a configuration object as the last parameter:
+```javascript
+try {
+  const result = await peer.methodsExt.doSomething(a, b, { timeout: 100 });
+} catch(e) {
+  // method took longer than a 100 millseconds
+}
+```
+
+This also works for customizaton of the transport.
+For example, you may want to pass configuration for transferable objects to a webWorker:
+```javascript
+  const result = await peer.methodsExt.processImage({ imageBitmap, stuff }, {
+    postMessageOptions: { transfer: [imageBitmap] }
+  });
+```