SAM.js

Created to connect Socket.io, AngularJS and MongoDB.

Now it is database and view framework agnostic, leaving a socket.io framework.

Browser client: samjs-client

Features

• only websockets
• plugable
• useful defaults
• multiple databases simultaniously

data modeling

• options
  source-code-based / kept-in-memory data. Used to set low-level options of the app, can only be changed by restarting. Not accessible due websockets.

• configs
  file-based / kept-in-memory data For structural data specific for your app, should be only changed sparsely by few persons.

• models
  Can be custom in-memory models or plugable database-based models. Should be used for all data which changes on regular basis.

Getting Started

npm install --save samjs
npm install --save-dev samjs-client

Simple example with koa server

samjs = require "samjs"
koa = require("koa")()
 
server = require("http").createServer(koa.callback())
 
samjs
.plugins()
.options()
.configs({name:"item"})
.models()
.startup(server)
 
server.listen(3000)
#to close
#samjs.shutdown()
 
// in browser with e.g. webpack
samjs = require("samjs-client")()
samjs.config.set("item", "value")
.then(function(){
  //success
})
.catch(function(){
  //failure
})
// some other client  
samjs.config.on("item",function(){
  //item changed
  samjs.config.get("item")
  .then(function(response){
    response == "value" // true
  })
  .catch(function(){
    //failure
  })
}

Available plugins

Name	Description
samjs-auth	adds a configs-based user management, authentification mechanismen and authorization system for configs.
samjs-files	adds a model and interface for file/folder interaction
samjs-files-auth	adds authorization for samjs-files
samjs-mongo	adds a model and interface for mongodb interaction
samjs-mongo-auth	adds authorization for samjs-mongo
samjs-auth-mongo	moves user management to mongodb. Adds groups.
samjs-mongo-isOwner	Plugin for managing user owned documents in samjs-mongo.

docs

Samjs is configured by several functions which must be called in order. Startup order:

samjs.plugins().options().configs().models().startup().io.listen(8080)

Function: plugins

takes one or more plugin objects or an array of plugin objects. Returns samjs.

samjs.plugins(require("samjs-files"),require("samjs-auth"))
// or
samjs.plugins([require("samjs-files"),require("samjs-auth")])

See plugin api for detailed information to write your own plugin

Function: options

takes a options object to overwrite the default values. Returns samjs.

// only default in core is samjs.options.config == "config.json"
// to overwrite:
samjs.options({config:"settings.json"})

Function: configs

takes one or more config objects or an array of config objects. Returns samjs.

samjs.configs({name:"paths"},{name:"users"})
// or
samjs.configs([{name:"paths"},{name:"users"}])

Props of a config object:

Name	type	default	description
name	String	-	(required) name of the config object. To access the config object after setup :samjs.configs[name]
access	Object	{read:false,write:false}	allowes to access this config value by client
test	Function	-	Function to test values for validity. Must return a promise which resolves on success and rejects on error.
isRequired	Boolean	false	includes this config object in configuration phase. (see lifecycle)
hooks	Object	-	functions to get called on specific interactions with this config object.

actions:

After setup, each config object has 3 available actions: set,get,test. Each has a server-side version: _set,_get,_test, which are not checking for authentification.

hooks:

hooks are functions which are called on specific actions. They always have to return their arguments.

Name	arguments	description
beforeCreate	options	manipulate the options object before creation
afterCreate	options	manipulate the options object after creation
beforeSet	{data, socket}	used to authenticate a set request
before_Set	{data, oldData}	used to manipulate a set request
afterSet	{data, oldData, socket}	called after a successfull set request from client
after_Set	{data, oldData}	called after each successfull set request
beforeGet	{socket}	used to authenticate a get request
after_Get	data	called after a successfull _get request
afterGet	{data, socket}	called after a successfull get request from client
beforeTest	{data, socket}	used to authenticate a test request
afterTest	{data, socket}	called after a successfull test request from client

example (how samjs-auth basically works):

samjs.configs({name:"paths", hooks: {
  beforeSet: function(obj) {
    if (obj.client.auth != null
      && obj.client.auth.user != null
      && obj.client.auth.user.username == "root") {
        return obj
    }
    throw new Error "no permission"
  }}
})

Function: models

takes one or more model objects or an array of model objects. Returns samjs.

samjs.models(model1,model2)
// or
samjs.models([model1,model2])

Props of a model object:

Name	type	default	description
name	String	-	(required) name of the model object. To access the model object after setup :samjs.models[name]
interfaces	Object or array	-	see below.
isRequired	Boolean	false	includes this model object in installation phase. (see lifecycle)
installInterface	Function	-	a socket.io interface which is used in installation phase if isRequired is true (see installInterface)
test	Function	-	a function to test if installation requirement is met, if isRequired is true
db	String	-	use a model-structure and interface from a plugin

interfaces

Interfaces can be either a array or a key-value store

// all interfaces in an array will listen one the "someModel" socket.io namespace
samjs.models({
  name: "someModel"
  value: "someValue"
  interfaces: [
    // will be in the "someModel" socket.io namespace
    function(socket){
      var model = this
      // model.name == "someModel" // true
      socket.on("get",function(request){
        if (request.token != null){
          socket.emit("get."+.request.token,{success:true, content:model.value})
        }
      })
    }
  ]
  })
// if you need to use another namespace use an object instead
samjs.models({
  name: "someModel"
  interfaces: {
    // either provide a single interface or a array of interfaces
    // will be in the "someOtherNamespace" socket.io namespace
    someOtherNamespace: function(socket){ //doSomething }
  }
  })

installInterface

samjs.models({
  name: "someModel"
  installInterface: function(socket){
    var model = this # will be bound to model instance
    # will be in the 'install' socket-io namespace, specific listeners are required
    socket.on "someModel.set", function(request) =>
      if (request.token != null && request.content != null){
        # no authentification, will be only accessible in install mode
        model.test(request.content)
        .then(function(value){model.value = value})
        .then(function(value){return {success:true, content: value}}
        .catch(function(e){return {success:false, content: e.message}}
        .then(function(response){
          socket.emit("boilerplate.set."+request.token, response)
          if(response.success){
            samjs.state.checkInstalled() # will trigger a check if installation is finished
            }
          }
        }
    # must return a dispose function
    return function(){socket.removeAllListeners("someModel.set")}
  }
})

Function: startup

takes a optional httpServer, returns samjs.

samjs.startup(someServer)
someServer.listen(8080)
// or
samjs.startup()
samjs.io.listen(8080)

Function: shutdown

returns samjs. Shuts samjs and socket.io down.

Function reset

returns samjs. Resets samjs instance. Useful for unit testing.

Lifecycle

samjs emits several events during its lifecycle:

example:

samjs.once("options",function(){console.log("options got called")})

Synchronous (configuration / after startup)

Name	Description
beforePlugins	emitted before samjs.plugins() is executed
plugins	emitted after samjs.plugins() is executed
beforeOptions	emitted before samjs.options() is executed
options	emitted after samjs.options() is executed
beforeConfigs	emitted before samjs.configs() is executed
configs	emitted after samjs.configs() is executed
beforeModels	emitted before samjs.models() is executed
models	emitted after samjs.models() is executed
beforeStartup	emitted before samjs.startup() is executed
startup	emitted after samjs.startup() is executed
beforeShutdown	emitted before samjs.shutdown() is executed
shutdown	emitted after samjs.shutdown() is executed
beforeReset	emitted before samjs.reset() is executed
reset	emitted after samjs.reset() is executed

Asynchronous (startup)

samjs.startup works like this:

Is samjs configured? (all configs with `isRequired` are set properly)
- start configuration if not
Execute all `startup` functions of all plugins
Execute all `startup` functions of all models
Is samjs installed? (all models with `isRequired` are set properly)
- start installation if not
expose all socket.io interfaces

Events:

Name	Description
beforeConfigure	emitted before configuration is set up and ready
configure	emitted after configuration is set up and ready
configured	emitted after configuration is done or when no configuration was necessary
beforeInstall	emitted before installation is set up and ready
install	emitted after installation is set up and ready
installed	emitted after installation is done or when no installation was necessary
started	emitted when samjs is properly started up

There are additional state promises which will fullfill once a state is reached:

Name	Description
onceConfigure	fullfilled once in configuration mode
onceConfigured	fullfilled once configuration is finished
onceInstall	fullfilled once in installation mode
onceInstalled	fullfilled once installation is finished
onceStarted	fullfilled once samjs is properly started up
onceConfigureOrInstall	fullfilled once in configuration or installation mode

example

samjs.state.onceStarted.then(function(){
  // do something
  })

Plugin api

see source code of samjs-plugin-boilerplate for a complete plugin api