Caplet.js
Caplet is a tiny (11kb) modeling library.
Caplet is the M in "MVC". It works independently from any other library, and can easily be used with your existing framework/view layer such as AngularJS, ReactJS, RactiveJS, or PaperclipJS (shameless plug).
Caplet doesn't make any assumptions about your code. It just gives organization to your model relationships in a sane way. It also gives you a relatively higher level of encapsulation for your data, while also encouraging you, but not forcefuly, to follow design patterns that scale quite well.
Caplet has been an evolution of many libraries in the past, which have been used in a few pretty large applications (30k-ish loc). The first version came about sometime around 2013 as mojo-models, and has since been further generalized for all intensive purposes.
The newer, hip version of Caplet has been designed for React, and pairs wells with the Hierarchial nature of React-based applications.
Caplet can be a great companion to Flux. It also serves as a Flux alternative if you enjoy the good 'ol (and well proven when done right) MVC approach (Caplet (M) + React (VC)).
Why?
- Scales. Concepts have been used in various apps consisting of ~30k LOC.
- Simple. You just have models & collections. Nothing else to learn.
- Familiar. Caplet isn't too inventive. If you're familiar with Symfony, Mongoose, or Ember, then Caplet shouldn't be tough to learn.
- Obvious. It's easier to reconcile how your application should be structured if the only thing you have to deal with are
models&collections. - Encapsulated. Caplet was design to encourage you to focus how your models & collections relate to one other versus how they relate to other parts of your application - this includes views, and even the API. This allows you to:
- Re-use your models for other applications - web/desktop/server-side.
- Maintain your model structure even if the API changes.
- Write your front-end in parallel with your API.
- Lightweight. Caplet is small (11 KB minified).
- Testable. Run 'em in the browser, in node, wherever you want.
Installation
npm install caplet
Examples
Extensions
- meshlet - mesh + caplet mixin
-
mesh - streamable data store library
- socket.io - realtime data
- http - HTTP (API) adapter
- local storage local storage db
- loki - loki in-memory db
Basic Example
var Caplet = require("caplet");
var React = require("react");
/**
*/
var TodoModel = Caplet.createModelClass({
});
/**
*/
var TodoCollection = Caplet.createCollectionClass({
modelClass: TodoModel,
create: function(properties) {
var todo = this.createModel(properties);
this.push(todo);
return todo;
}
});
/**
*/
var TodoComponent = React.createClass({
mixins: [Caplet.watchModelsMixin],
render: function() {
return <li><a href="#" onClick={this.props.todo.dispose.bind(this.props.todo)}>x</a> {this.props.todo.text}</li>
}
});
/**
*/
var TodosComponent = React.createClass({
mixins: [Caplet.watchModelsMixin],
handleKeyDown: function(event) {
if (event.keyCode !== 13) return;
this.props.todos.create({ text: this.refs.todoText.getDOMNode().value });
},
render: function() {
return <div>
<input type="text" ref="todoText" onKeyDown={this.handleKeyDown} />
<ul>{ this.props.todos.map(function(todo) {
return <TodoComponent todo={todo} />;
})}</ul>
</div>
}
});
/**
*/
React.render(<TodosComponent todos={ TodoCollection({
data: [{ text: "drive car" }, { text: "wash car" }]
})} />, document.body);API
Model Caplet.createModelClass(properties)
creates a new model class
-
properties- prototype properties to set on the new class-
mixins- array of mixins to add - adds to the prototype of class
-
Model()
creates a new model
var model = new Model(); // this is valid
var model = Model(); // you can also omit the "new" keywordModel.initialize()
called when the model is instantiated
var Model = Caplet.createModelClass({
initialize: function() {
// initialize stuff here
}
});
Model(); // initialize() calledModel.fromData(data)
called when the data property is set. This method deserializes data and sets the returned object as properties on the model.
Note that
uidshould be set for an existing model
var Address = Caplet.createModelClass({
// impl here
});
var Person = Caplet.createModelClass({
fromData: function(data) {
return {
uid : data._id,
firstName : data.firstName,
lastName : data.lastName,
address : Address({ data: data.address })
};
}
});
var person = Person({
data: {
_id : "dbId",
firstName : "Jeff",
lastName : "Gordon",
address : {
city : "San Francisco",
state : "CA",
zip : 94114
}
}
});
console.log(person.firstName); // Jeff
console.log(person.lastName); // Gordon
console.log(person.address); // [object Address]
console.log(person.data); // data propModel.toData()
Serializes the model back into data.
var Person = Caplet.createModelClass({
toData: function(data) {
return {
_id : this.uid,
firstName : this.firstName,
lastName : this.lastName,
address : this.address ? this.address.toData() : void 0
};
}
});Model.onDataChange(newData, oldData)
called when the data property changes
Model.toJSON()
calls toData()
Model.get(property)
returns a property
Model.set(property, value)
sets a property value
Model.data
unserialized data on the model
Model.setProperties(properties)
sets multiple property values
disposable Model.watch(listener)
watches the model for any changes
var m = new Caplet.Model({ name: "Oprah" });
m.watch(function() {
console.log("changed!");
});
m.set("name", "Ryan"); // triggers watcherModel.dispose()
disposes the model - also removes it from a collection if it is in one
Collection Caplet.createCollectionClass(properties)
creates a new collection class
-
properties- prototype properties to set on the new class-
mixins- array of mixins to add - adds to the prototype of class
-
Collection()
creates a new collection
var collection = new Collection();
var collection = Collection();Collection.initialize()
called when the collection is created
Collection.fromData(data)
deserializes properties on the collection. This is already set, but you can easily override it.
var People = Caplet.createCollectionClass({
fromData: function(data) {
return {
anotherProp: "blah",
source: data.source.map(function(data) {
return this.createModel({ data: data });
}.bind(this))
};
}
});Collection.onDataChange(newData, oldData)
called when the data property changes
Collection.modelClass
The model class to instantiate for each data item
var Person = Caplet.createModelClass();
var People = Caplet.createCollectionClass({
modelClass: Person
});
var people = People({ data: [{ name: "Ben"}, { name: "Carmen" }]});
console.log(people.at(0)); // [object Person]Collection.source
the source of the collection
Collection.onChange()
override this if you want to listen for any changes on the collection
var Todo = Caplet.createModelClass({
toggleComplete: function() {
this.set("complete", !this.complete);
}
});
var Todos = Caplet.createCollectionClass({
modelClass: Todo,
getInitialProperties: function() {
return {
allComplete: this._isAllComplete();
}
},
onChange: function() {
this.setProperties(this.getInitialProperties());
},
_isAllComplete: function() {
for (var i = this.length; i--;) if (!this.at(i).complete) return false;
return true;
}
});
var todos = Todos({
data: [
{ text: "wash car" },
{ text: "buy groceries", "complete": true }
]
});
console.log(todos.allComplete); // false
todos.at(0).set("complete", true);
console.log(todos.allComplete); // trueCollection.at(index)
returns a model at the given index
Collection.filter(fn)
filters the collection
Collection.push(model)
pushes a model onto the collection
Collection.unshift(model)
unshifts a mdoel
Collection.splice(index, numToRemove[, ...replace])
Removes / replaces items in the collection
Collection.map(fn)
maps & returns values
Collection.source
source of the collection (array of models)
Collection.data
raw unserialized data
Helpers
Caplet.setVirtuals(target, virtuals)
Sets virtual properties which get called on demand
var People = Caplet.createCollectionClass({
load: function() {
Caplet.load(this, function(next) {
$.get(this.person ? "/people/" + this.person.uid + "/friends" : "/people", next);
})
}
});
var Person = Caplet.createModelClass({
initialize: function() {
Caplet.setVirtuals(this, {
friends: function(onLoad) {
People({ person: this }).load(onLoad);
}
})
}
});
var person = Person({ uid: "personId" });
person.watch(function() {
console.log(person.get("people")); // should be defined
});
person.get("people"); // trigger virtual property
Caplet.watchProperty(target, property, listener)
watches a property on the model or collection
Caplet.load(target, load, onLoad)
var Person = Caplet.createModelClass({
load: function(onLoad) {
Caplet.load(this, function(onLoad) {
$.get("/people/" + this.uid, onLoad);
}, onLoad);
}
})Caplet.watchModelsMixin
React mixin which automatically watches properties on a component & triggers a re-render if anything changes
