vas

simple composable data services using muxrpc

npm install --save vas

for a user interface complement, see inu

example

var vas = require('./')
var pull = vas.pull
var values = require('object-values')

var service = {
  name: 'things',
  manifest: {
    all: 'source',
    get: 'async'
  },
  methods: function (server, config) {
    return { all, get }

    function all () {
      const things = values(config.data)
      return pull.values(things)
    }

    function get (id, cb) {
      cb(null, config.data[id])
    }
  },
  permissions: function (server, config) {
    return { get }

    function get (id) {
      if (id === 'nobody') {
        return new Error('nobody is not an id')
      }
    }
  }
}

// could also attach db connection, file descriptors, etc.
var config = {
  data: {
    1: 'human',
    2: 'computer',
    3: 'JavaScript'
  }
}

var port = 6000
var url = `ws://localhost:${port}`
var server = vas.listen(service, config, { port })
var client = vas.connect(service, config, { url })

client.things.get(1, (err, value) => {
  if(err) throw err
  console.log('get', value)
  // get human
})

pull(
  client.things.all(),
  pull.drain(v => console.log('all', v))
)
// all human
// all computer
// all JavaScript

setTimeout(function () {
  server.close()
  client.close()
}, 1000)

for a more complete example, see ./example.

usage

a vas service is a definition for a duplex stream that could respond to requests.

a vas service is defined by an object with the following keys:

• name: a string name
• version (optional): a string semantic version
• manifest: an object muxrpc manifest
• methods: a methods(server, config) pure function that returns an object of method functions to pass into muxrpc
• permissions: a permissions(server, config) pure function that returns an object of permission functions which correspond to methods. each permission function accepts the same arguments as the method and can return an optional new Error(...) if the method should not be called.
• services: any recursive sub-services

many vas services can refer to a single service or an Array of services

vas = require('vas')

the top-level vas module is a grab bag of all vas/* modules.

you can also require each module separately like require('vas/createServer').

server = vas.createServer(services, config)

a vas server is an instantiation of a service that responds to requests.

createServer returns an object that corresponds to the (recursive) services and respective methods returned by methods.

server.createStream()

returns a duplex pull stream using muxrpc

client = vas.createClient(services, config)

a vas client is a composition of manifests to makes requests.

createClient returns an object that corresponds to the (rescursive) services and respective methods in manifest.

client.createStream()

returns a duplex pull stream using muxrpc

vas.listen(services, config, options)

creates a server with createServer(services, config), then

listens to a port and begins to handle requests from clients using pull-ws-server

options is an object with the following (optional) keys:

• port: port to open WebSocket server
• onListen: function to call once server is listening

vas.connect(client, config, options)

creates a client with createClient(services, config), then

connects the client to a server over websockets using pull-ws-server

options is an object with the following (optional) keys:

• url: string or object to refer to WebSocket server
• onConnect: function to call once client is connected

TODO vas.command(services, config, options, argv)

run a command on a server as a command-line interface using muxrpcli

options are either those passed to vas.listen or vas.connect, depending on if argv[0] === 'server'

argv is expected to be process.argv.

inspiration

• big
• feathers
• secret-stack

license

The Apache License

Copyright © 2016 Michael Williams

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.