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 samjsnpm install --save-dev samjs-client
Simple example with koa server
samjs = require "samjs"koa = server = samjspluginsoptions server#to close#samjs // in browser with e.g. webpacksamjs = samjsconfig// some other client samjsconfig
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:
samjspluginsoptionsio
Function: plugins
takes one or more plugin objects or an array of plugin objects. Returns samjs
.
samjsplugins// orsamjsplugins
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:samjsoptionsconfig:"settings.json"
Function: configs
takes one or more config objects or an array of config objects. Returns samjs
.
samjs// orsamjs
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
Function: models
takes one or more model objects or an array of model objects. Returns samjs
.
samjs// orsamjs
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 namespacesamjs// if you need to use another namespace use an object insteadsamjs
installInterface
samjs
Function: startup
takes a optional httpServer
, returns samjs
.
samjssomeServer// orsamjssamjsio
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
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
samjsstateonceStarted
Plugin api
see source code of samjs-plugin-boilerplate for a complete plugin api