Add API to README.md (#4)

Author: lejeunerenard

README.md

@@ -6,6 +6,148 @@
 npm i bare-rpc
 ```
 
+## Usage
+
+```js
+import RPC from 'bare-rpc'
+
+const rpc = new RPC(stream, (req) => {
+  if (req.command === 42) {
+    console.log(req.data.toString()) // ping
+    req.reply('pong')
+  }
+})
+
+// On the other end
+const req = rpc.request(42)
+req.send('ping')
+
+const replyBuffer = await req.reply()
+console.log(replyBuffer.toString()) // pong
+```
+
+## API
+
+### `RPC`
+
+#### `const rpc = new RPC(stream, [onrequest])`
+
+Create an RPC instance using a duplex `stream`. `onrequest` is an optional callback run when a remote request is received. This is where processing and responding to an RPC request happens. `onrequest` receives a `RPCIncomingRequest` as an argument, for example:
+
+```js
+const rpc = new RPC(stream, (req) => {
+  if (req.command === 42) {
+    req.reply('pong')
+  }
+})
+```
+
+See [`RPCIncomingRequest`](#rpcincomingrequest) for properties and methods for processing the request.
+
+`onrequest` can also be a [`RPCCommandRouter`](#rpccommandrouter).
+
+#### `const req = rpc.request(command)`
+
+Create a request for `command`. `command` is a unique number that should be used to differentiate different requests on the remote end. Returns a `RPCOutgoingRequest`.
+
+### `RPCOutgoingRequest`
+
+#### `req.command`
+
+The command that the request was created with. A command is a unique number.
+
+#### `req.sent`
+
+A boolean for whether the request has been sent.
+
+#### `req.received`
+
+A boolean for whether the request has received a reply.
+
+#### `req.send(data, [encoding])`
+
+Send the request with the provided `data`. `data` can be a buffer or a string which will be encoded using `encoding`.
+
+`.send()` can only be called once per request.
+
+#### `const data = await req.reply([encoding])`
+
+Await the reply from the remote end to the request. `encoding` can be defined for decoding the response `data` buffer back into a string.
+
+#### `const stream = req.createRequestStream([opts])`
+
+Create a [`Writable`](https://github.com/mafintosh/streamx?tab=readme-ov-file#writable-stream) stream for sending data with the request.
+
+#### `const stream = req.createResponseStream([opts])`
+
+Create a [`Readable`](https://github.com/mafintosh/streamx?tab=readme-ov-file#readable-stream) stream for receiving data in reply to the request.
+
+### `RPCIncomingRequest`
+
+#### `req.command`
+
+The command that the request was sent as. A command is a unique number.
+
+#### `req.data`
+
+The data buffer sent with the request.
+
+#### `req.sent`
+
+A boolean for whether a reply has been sent.
+
+#### `req.received`
+
+A boolean for whether the request has been received as a stream. See [`req.createRequestStream()`](#const-stream--reqcreaterequeststream) for receiving requests as a stream.
+
+#### `req.reply(data, [encoding])`
+
+Reply to the request with the provided `data`. `data` can be a buffer or a string which will be encoded using `encoding`.
+
+#### `const stream = req.createRequestStream([opts])`
+
+Create a `Readable` stream for receiving data from the request.
+
+#### `const stream = req.createResponseStream([opts])`
+
+Create a `Writable` stream for sending data in reply to the request.
+
+### `RPCCommandRouter`
+
+An alternative way to define commands and handlers for receiving them.
+
+#### `const router = new RPC.CommandRouter()`
+
+Create a new command router. This router can then be used when creating an
+`rpc`. For example:
+
+```js
+const router = new RPC.CommandRouter()
+
+router.respond(42, (req, data) => {
+  console.log(data.toString()) // ping
+
+  return Buffer.from('pong')
+})
+
+const rpc = new RPC(stream, router)
+const req = rpc.request(42)
+req.send('ping')
+```
+
+#### `router.respond(command, [opts], async (req, data) => {})`
+
+Define a command and the handler for it. The callback for a command receives both the request (`req`) and the `data` buffer and can return a value to respond. If the request is responded to in the callback, the return value is ignored.
+
+`opts` can include:
+
+```
+{
+  requestEncoding: c.raw, // Encoding for decoding incoming request
+  responseEncoding: c.raw, // Encoding for outgoing response
+}
+```
+
 ## License
 
 Apache-2.0

index.d.ts

@@ -50,7 +50,7 @@ interface RPCOutgoingRequest {
 
   send(data: Buffer | string, encoding?: BufferEncoding): void
 
-  reply(encoding?: BufferEncoding): Promise<Buffer>
+  reply(encoding?: BufferEncoding): Promise<Buffer | string>
 
   createRequestStream(opts?: WritableOptions): RPCOutgoingStream
   createResponseStream(opts?: ReadableOptions): RPCIncomingStream