Retain is a browser (CJS) and node Javascript model with plugins support.
Installation
$ npm install retain
Motivation
There are many Javascripts models out there, but the majority of them are deeply coupled inside a framework, thus making it impossible hard to use them in another project/environment.
Example
var retain = ;var Movies = ;Movievar goodfellas = Movies // Creates a Movie instance
Initialize
Retain can be initialized in two ways:
-
Creating a new Retain instance
var retain = ;var Movies = ; -
Extending the Retain constructor function.
var Retain = Retain;var Movies = {};Moviesprototype = ;
For Coffeescript lovers, you can extend Retain like this:
retain = require "retain"
API
First, you will have to set the Model properties with its type (for validation purpose)
Movie
This way, each model instance will have these properties to be setted and validated.
API methods
Each method have an option to update the data remotelly passing a callback as parameter.
Creates a local record.
var fightClub = Movie;
Creates a local and remote record.
var fightClub = Movie;
NEW
The new
method is responsible for creating new model instances:
Creates a local record.
var fightClub = Movie;
Creates a local and remote record.
var fightClub = Movie;
You can also set the newly record parameters:
Creates a local record called 'Fight Club'.
var fightClub = Movie;
Creates a local and remote record called 'Fight Club'.
var fightClub = Movie;
SET
The set
method is responsible for setting and updating the model properties.
Sets the record properties locally.
fightClub;
Sets the record properties locally and remotelly.
fightClub
GET
The get
method is responsible for retrieving the property value (from the local record)
Get a record property value.
fightClub // Fight Club
ALL
The all
method fetchs all the model collection locally or remotelly.
Get all the records locally.
var movies = Movieall // [fightClub]
Get all the records remotelly and updates/overwrites the local collection.
var movies = Movieall{ifrecords// Records retrieved remotelly}
FIND
The find
method is responsible for retrieving a record, searching by id
or cid
.
Search by id
only if the data were retrieved from a remote location at least once, otherwise, search by cid
, which is basically, the record index
at the local array.
Search for a record locally by ID or CID.
movie = Movie; // Returns fightClub reference.
Search for a record remotelly by ID or CID
movie = Movie;
SEARCH
The search
method searchs for records by the specified properties.
Search for a record named 'Pulp Fiction'.
pulp = Movie; // Returns an array containing all thefound records
Search remotelly for a record named 'Pulp Fiction'.
movie = Movie;
REMOVE
The remove
method will delete the instance, locally or/and remotelly.
Deletes a record locally.
fightClub;
Deletes a record remotelly.
fightClub;
SAVE
The save
method will sync the local record with the remote storages.
Sync the local record with the remote storages.
var moon = Moviemoon;moon;
Events
Retain uses the Happens library for the event system.
You can bind a callback function to a Retain instance event using the happens
signature.
var godfather = Movie;godfather
Change
Fired when an instance property changes.
New
Fired when a new instance is created.
Remove
Fired when an instance is deleted.
Error
Fired when a plugin couldn't fetch the data.
API Docs.
Plugins
By default, Retain saves the data in memory (which gets removed after a browser refresh). In order to save the data in other locations such as localStorage
or database
, you should use one the avaliable plugins.
★ List of avaliable plugins:
Example
var retain = ;var retainAjax = ;var Movies = ;Movies;Movies;
Now, whenever the data is modified, it will be saved remotelly.
Creating a plugin
Retain use promises internally to transfer the data between the plugins.
To create a plugin, it is necessary to implement each of the following Retain methods.
- new
- all
- set
- find
- search
- remove