https://github.com/bas080/furver
Convert any node module into a programmable, parallelized and bulk HTTP JSON API.
https://github.com/bas080/furver
bulk-api cli javascript json json-api lisp-language node nodejs rpc rpc-client rpc-server
Last synced: 9 months ago
JSON representation
Convert any node module into a programmable, parallelized and bulk HTTP JSON API.
- Host: GitHub
- URL: https://github.com/bas080/furver
- Owner: bas080
- License: mit
- Created: 2023-06-08T21:09:00.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2023-09-14T00:12:44.000Z (over 2 years ago)
- Last Synced: 2024-03-15T11:04:54.693Z (almost 2 years ago)
- Topics: bulk-api, cli, javascript, json, json-api, lisp-language, node, nodejs, rpc, rpc-client, rpc-server
- Language: JavaScript
- Homepage:
- Size: 477 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Furver
[DEPRECATED: I HAVE STARTED A NEW PROJECT NAMED SendScript. It is a much
simpler package with a more expressive dsl for client usage.][sendscript]
Furver is a minimal RPC solution that uses JSON and Node.js. Turn any
JavaScript module into a simple to use client API that is easy to learn
while also expressive enough for advanced use-cases.
[](https://www.npmjs.com/package/furver)
[](https://www.npmjs.com/package/furver)
[](https://standardjs.com)
[](./LICENSE)
Table of Contents
- [Features](#features)
- [Getting Started](#getting-started)
* [Installation](#installation)
* [Define a module](#define-a-module)
* [Start the server](#start-the-server)
* [Request using curl](#request-using-curl)
* [Request using the furver client](#request-using-the-furver-client)
- [Server](#server)
- [Client](#client)
* [Use in your code](#use-in-your-code)
* [Client REPL](#client-repl)
* [Browser](#browser)
- [Lisp](#lisp)
- [CLI](#cli)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [License](#license)
## Features
- Low code.
- 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.
## Getting Started
Covers the basic use case of defining a module, starting a server and
performing requests with and without the client.
### Installation
```bash
npm install furver -g
```
### Define a module
```javascript
// ./example/getting-started.mjs
const items = []
export default {
push (x) {
return items.push(x)
},
items () {
return items
},
ping () {
return 'pong'
}
}
```
### Start the server
Port 5000 for the following examples.
```bash
furver server ./example/getting-started.mjs --port 5000
```
Now for the http clients.
### Request using curl
```bash
curl http://localhost:5000 -d '["ping"]'
```
```
"pong"
```
Let's add some numbers to our `items` array.
```bash
curl http://localhost:5000 -d '["array", ["push", 1], ["push", 2], ["push", 3], ["items"]]'
```
```
[1,2,3,[1,2,3]]
```
Also support requests with `GET` method:
```bash
curl -G "http://localhost:$PORT" --data-urlencode body='["inc", 42]'
```
```
43
```
> We use the `-G` and `--data-urlencode` to perform a GET request with properly
> encoded JSON in the body query param.
### Request using the furver client
Now let's use the furver client module and `api.push` some letters.
```javascript
import client from './client.mjs'
const api = await client({
endpoint: 'http://localhost:5000'
})
console.log(await Promise.all([
api.push('a'),
api.call(['push', 'b']),
api.call([['ref', 'push'], 'c']),
api.call([api.push, 'd'])
]))
console.log(await api.items())
```
```
[ 4, 5, 6, 7 ]
[
1, 2, 3, 'a',
'b', 'c', 'd'
]
```
These are all equivalent ways of calling the push function in the server
module. Read more about the [client](./client.md) and [lisp](./lisp.md) if you
want to learn more.
## Server
You can start a server by pointing to a module. This can be a npm package or
another file on the filesystem.
```bash
npm install ramda # A utility library.
npx furver server --port 3000 ramda ./example/api.mjs
```
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.
You can now perform requests using a furver client.
[Read more about the Furver server.](./server.md)
## Client
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.
### Use in your code
```javascript
(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(['array', ['identity', 'hello world'], ['timestamp'], ['version']]))
// Those are many quotes, we can reduce it by using the function reference.
const { identity, timestamp, version, array } = api
console.log(await api.call([array, [identity, 'hello world'], [timestamp], [version]]))
})()
```
```javascript
[ 'hello world', 1694650272974, '1.2.1' ]
[ 'hello world', 1694650272979, '1.2.1' ]
[ 'hello world', 1694650272982, '1.2.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.
### Client REPL
You can also start talking with a Furver server using the cli.
```bash
furver repl --url http://localhost:3000
```
This will start a prompt that takes valid JavaScript or a Lisp expression.
```bash
> identity('hello')
"hello"
> ['identity', 'world']
"world"
> [identity, 'goodbye']
"goodbye"
```
### Browser
By default the server hosts a browser friendly bundled version of the client at
`/client.min.js`. This script registers the `furver` global variable.
You can try this client in the playground by starting a furver server and
opening `http://localhost:3000/playground` in your browser.
[Read more about the client.](./client.md)
## Lisp
Furver's Lisp-like language allows developers to perform complex aggregations
and operations in a single request. It builds ontop of JSON by using arrays for
its s-expressions.
[Read more about the furver lisp.](./lisp.md)
## CLI
The goal of Furver's cli is to provide you with all the tools to use, test and
debug Furver servers.
```bash
furver --help
```
```
furver
Commands:
furver server start server
furver repl [modules..] start a local server or client repl
furver client start client repl. Use repl --url instead
[deprecated]
furver schema [modules..] print schema of api
Options:
--help Show help [boolean]
--version Show version number [boolean]
--url [string]
--modules Name or path to modules [array]
-v, --verbose [boolean]
-p, --port [number] [default: "8999"]
```
[Read more about the Furver CLI.](./cli.md)
## Changelog
See the [CHANGELOG.md](./CHANGELOG.md) for a list of changes over time.
## Contributing
Want to contribute? The [CONTRIBUTING.md](./CONTRIBUTING.md) might help you get
started quicker.
## License
See the [LICENSE.txt](./LICENSE.txt) file for details.
[sendscript]:https://github.com/bas080/sendscript