Improve client usage documentation

CHANGELOG.md

@@ -4,8 +4,14 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### [v0.1.1](https://github.com/bas081/furver/compare/v0.1.1...v0.1.1)
+
+- Improve client usage documentation [`89628e9`](https://github.com/bas081/furver/commit/89628e9bd70831a47370aac1dbb5ce2f52f06284)
+
 #### [v0.1.1](https://github.com/bas081/furver/compare/v0.1.0...v0.1.1)
 
+> 21 May 2023
+
 - Fix client and add playground with client bundle [`d2d974f`](https://github.com/bas081/furver/commit/d2d974f036047a145e1ece1746948d9f6232f5b9)
 - Fix server run example [`5e0f43b`](https://github.com/bas081/furver/commit/5e0f43b41668b4c7ced8de80e03de3c2729e773c)
 

CONTRIBUTING.md

@@ -7,7 +7,7 @@ Lists projects dependencies and the versions.
 ```bash bash
 npm --version  # Dependency management
 node --version # Testing and implementation
-bash --version # For usage examples
+bash --version | head -n 1 # For usage examples
 
 # Examples on how to use server
 curl --version | head -n 1 | cut -f -2 -d ' '
@@ -16,11 +16,6 @@ curl --version | head -n 1 | cut -f -2 -d ' '
 9.6.6
 v20.2.0
 GNU bash, version 5.0.17(1)-release (x86_64-pc-linux-gnu)
-Copyright (C) 2019 Free Software Foundation, Inc.
-License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
-
-This is free software; you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
 curl 7.68.0
 ```
 
@@ -41,14 +36,14 @@ git add package-lock.json
 ```
 ```
 
-removed 32 packages, and audited 371 packages in 1s
+removed 1 package, and audited 371 packages in 1s
 
 31 packages are looking for funding
   run `npm fund` for details
 
 found 0 vulnerabilities
 
-up to date, audited 3 packages in 1s
+up to date, audited 3 packages in 922ms
 
 found 0 vulnerabilities
 
@@ -76,7 +71,7 @@ npm t -- -R classic
 > furver@0.1.1 test
 > tap *.test.mjs --no-cov -R classic
 
-cli.test.mjs .......................................... 4/4 1s
+cli.test.mjs .......................................... 4/4 2s
 client.test.mjs ..................................... 12/12
 debounce.test.mjs ..................................... 3/3
 lisp.test.mjs ....................................... 10/10
@@ -89,6 +84,17 @@ total ............................................... 43/43
   ok
 ```
 
+## Audit
+
+Check if package is free of vulnerabilities.
+
+```bash bash
+npm audit
+```
+```
+found 0 vulnerabilities
+```
+
 ## Formatting
 
 ```bash bash
@@ -110,7 +116,7 @@ git add ./client.min.js
 ```
 ```
 
-added 32 packages, removed 1 package, and audited 403 packages in 6s
+added 32 packages, removed 1 package, and audited 403 packages in 11s
 
 38 packages are looking for funding
   run `npm fund` for details

CONTRIBUTING.mz

@@ -7,7 +7,7 @@ Lists projects dependencies and the versions.
 ```bash bash
 npm --version  # Dependency management
 node --version # Testing and implementation
-bash --version # For usage examples
+bash --version | head -n 1 # For usage examples
 
 # Examples on how to use server
 curl --version | head -n 1 | cut -f -2 -d ' '
@@ -40,6 +40,14 @@ npm t -- -R classic
 # npx c8 npm t
 ```
 
+## Audit
+
+Check if package is free of vulnerabilities.
+
+```bash bash
+npm audit
+```
+
 ## Formatting
 
 ```bash bash

README.md

@@ -1,18 +1,25 @@
 # Furver
 
-Turn any JavaScript module into a JSON web API with a built-in client and
-Lisp-like language for complex server-side operations.
+Furver is a minimal RPC solution that uses JSON and Node.js. Turn any
+JavaScript module into into a simple to use client API that is easy to learn
+while also expressive enought for advanced use-cases.
 
 [![NPM](https://img.shields.io/npm/v/furver?color=blue&style=flat-square)](https://www.npmjs.com/package/furver)
 [![NPM Downloads](https://img.shields.io/npm/dm/furver?style=flat-square)](https://www.npmjs.com/package/furver)
 [![Vulnerabilities](https://img.shields.io/snyk/vulnerabilities/npm/furver?style=flat-square)](https://snyk.io/vuln/npm:furver)
 [![Standard Code Style](https://img.shields.io/badge/code_style-standard-brightgreen.svg?style=flat-square)](https://standardjs.com)
 [![License](https://img.shields.io/npm/l/furver?color=brightgreen&style=flat-square)](./LICENSE)
 
+<details><summary>Table of Contents</summary>
+
 <!-- toc -->
 
+- [Features](#features)
 - [Server](#server)
 - [Client](#client)
+  * [JavaScript](#javascript)
+  * [REPL](#repl)
+  * [Browser](#browser)
 - [Lisp](#lisp)
 - [CLI](#cli)
 - [Changelog](#changelog)
@@ -21,54 +28,103 @@ Lisp-like language for complex server-side operations.
 
 <!-- tocstop -->
 
+</details>
+
+## Features
+
+- No boilerplate.
+- Makes it easy to quickly iterate.
+- Supports bulk requests with an intuitive client js API.
+- Parallel operations out of the box.
+- Covers both simple and complicated use-cases.
+
 ## Server
 
-To use Furver, simply spin up a server.
+You can start a server by pointing to a module. This can be a npm package or
+another file on the filesystem.
 
 ```bash
-npx furver server ./example/api.mjs
+npm install ramda # A utility library.
+npx furver server --port 3000 ramda ./example/api.mjs
 ```
 
-This command will convert the specified JavaScript module into a JSON web API
-that also hosts the schema of the module.
+Defining multiple modules will result in the modules being merged into a single
+API. The function of the most right module will take precedence when the
+modules have conflicting function names.
 
-Furver includes a client that fetches the schema and creates an API that
-corresponds to the functions in the module.
+You can now perform requests using a furver client.
 
 [Read more about the Furver server.](./server.md)
 
 ## Client
 
-- It allows the API to be consumed as if it is defined in the current process.
-- The client automatically handles bulk requests, combining sequential calls
-  into a single request.
-- Works both in the browser and node.
-- Supports receiving messages.
+Now that we have a server running we can use the client to perform requests
+using either the client functions or a simple JSON Lisp.
+
+Here an working example of the JavaScript client.
+
+### JavaScript
 
 ```js node
 (async function() {
-
   const { default: FurverClient } = await import('./client.mjs')
 
+  // Fetches the schema and installs the schema methods on the api.
   const api = await FurverClient({endpoint: `http://localhost:${process.env.PORT}`})
 
+  // These function calls result in a single request that is run in parallel on
+  // the server.
   console.log(await Promise.all([
     api.identity('hello world'),
     api.timestamp(),
     api.version()
   ]))
 
+  // We can write the same query using the JSON Lisp
+  console.log(await api.call([[['identity', 'hello world'], ['timestamp'], ['version']]]))
+
+  // Those are many quotes, we can reduce it by using the function reference.
+  const { identity, timestamp, version } = api
+  console.log(await api.call([[[identity, 'hello world'], [timestamp], [version]]]))
 })()
 ```
 ```
-[ 'hello world', 1684642200161, '0.1.1' ]
+[ 'hello world', 1684716244609, '0.1.1' ]
+[ 'hello world', 1684716244614, '0.1.1' ]
+[ 'hello world', 1684716244618, '0.1.1' ]
+```
+
+All three ways are equivalent and valid ways of writing a furver Lisp program
+that is run server-side.
+
+This client is compatible with the browser and Node.js.
+
+### REPL
+
+You can also start talking with a Furver server using the cli.
+
+```bash
+furver client --port 3000
+```
+
+This will start a prompt that takes valid JavaScript or a Lisp expression.
+
+```bash
+> identity('hello')
+"hello"
+> ['identity', 'world']
+"world"
+> [identity, 'goodbye']
+"goodbye"
 ```
 
-By default the server hosts a bundled version of the client at `/client.min.js`.
-Using this file is optional.
+### Browser
+
+By default the server hosts a browser friendly bundled version of the client at
+`/client.min.js`.
 
 You can try this client in the playground by starting a furver server and
-opening `/playground` in your browser.
+opening `http://localhost:3000/playground` in your browser.
 
 [Read more about the client.](./client.md)
 
@@ -80,12 +136,21 @@ in a single request:
 
 ```javascript node
 (async function() {
-
   const { default: FurverClient } = await import('./client.mjs')
 
   const api = await FurverClient({endpoint: `http://localhost:${process.env.PORT}`})
 
-  const createAndGetInvoice = ['invoiceById', ['createInvoice', {
+  const { invoiceById, createInvoice } = api
+
+  // You could do this which results in two http requests:
+
+  console.log(await invoiceById(await createInvoice({
+    amount: 42, customerId: 1
+  })))
+
+  // or you can perform the same action within a single request:
+
+  const createAndGetInvoice = [invoiceById, [createInvoice, {
     amount: 42, customerId: 1
   }]]
 
@@ -94,8 +159,14 @@ in a single request:
 ```
 ```
 { amount: 42, customerId: 1 }
+{ amount: 42, customerId: 1 }
 ```
 
+The client waits a very short while and checks if multiple api methods have
+been called. When that is the case it will combine those calls into a single
+http request. That is not the case when using `await` before calling the next
+function that depends on the return value of the previous function.
+
 [Read more about the bare bones Furver lisp.](./lisp.md)