Cheiron

Small basic model (observable) class for Node.js and the browser.

How to include

Node.js / Browserify

In your shell:

$ npm install --save cheiron

In your javascript:

var Cheiron = require('cheiron')

Browser ("classic" way)

Just add a script tag with either cheiron.js or cheiron.min.js from this repos root directory. This makes the Cheiron variable globally available.

typeof window.Cheiron
// --> 'function'

API

Cheiron#constructor([<data>[, <context>]])

Creates a new instance. data will be used as the initial data, all observers will be invoked in context. Both data and context are optional.

If data does not contain a field _id, it will automatically be set to and ID with the pattern xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx (GUID) where x represents one of '0' to '9' or 'a' to 'f' and y represents one of '8', '9', 'a' or 'b'.

var model = new Cheiron({
  name: '[Betelgeusian]',
  planet: 'Betelgeuse'
}, obj)

console.log(model.get('_id'))
// --> (something like) da93fac1-a469-47f9-98c9-b1d7f41f4be9

/*
var model = new Cheiron()

var model = new Cheiron({
  name: 'Arthur Dent',
  planet: 'Magrathea'
})

var model = new Cheiron({}, obj)
*/

Cheiron#get(<key>)

Simply returns the value of key, if key has no value then undefined.

console.log(model.get('planet'))
// --> 'Betelgeuse'

Cheiron#has(<key>)

Returns false if key is undefined/not defined, else true.

console.log(model.has('name'))
// --> true

Cheiron#keys()

Returns an array of all set keys.

console.log(model.keys())
// --> [ 'name', 'planet' ]

Cheiron#events

An instance of reg4in/reeal.

// will be fired every time the model changes
model.events.on('change', callback)

model.events.on('change:name', function (value, key, old) {
  console.log(key + ' has been changed from ' + old + ' to ' + value)
  console.log(this === obj)
})

model.events.off('change', callback)

Cheiron#set(<key>, <value>[, <silent>])

Triggers events: change, change:<key> (if silent is falsy)

Sets key to value if value is actually different from the current value, executes all bound observers.

If value is of type function, it will be invoked with the current value as the first and the key as the second argument. You should note that the function will be executed only when you set the value, not everytime you query it.

model.set('name', 'Ford')
// --> 'name has been changed from [Betelgeusian] to Ford'
// --> true

model.set('name', function (name, key) {
  return name + ' Prefect'
})
// --> 'name has been changed from Ford to Ford Prefect'
// --> true

model.set('name', 'Arthur Dent', true)
// [does not invoke listeners]

Cheiron#setAll(<object>[, <silent>])

Calls Cheiron#set for every key-value pair of object and passes on silent.

var earth = new Cheiron({
  name: 'Earth'
})

earth.setAll({
  radius: 6370000,
  type: 'Actually a very big computer'
})

Cheiron#unset(<key>[, silent])

Triggers events: change, change:<key> (if silent is falsy)

Removes key from the internal data object.

model.unset('name')

model.unset('name', true)

Testing/Building

Installing development dependencies

$ npm install

Running tests

$ npm test

Building for the browser

$ npm run build
$ # for building on file change
$ npm run watch

License

MIT license, see LICENSE.