This documentation is also available at http://sofa.amateurinmotion.com
Sofa is full featured and easy to use CouchDB model persistence library for Ember.js.
It makes it easy to map CouchDB documents to application models, query and persist them, manage queriable to-one, to-many relationships and relationship inverses, create and load document attachments. Also create, drop databases, authenticate users by using CouchDB sessions, create and update design documents (javascript and mango views).
This is is one of the easiest ways to start coding your Ember.js app which persists data in the cloud. All you need is CouchDB running somewhere. You can also deploy Ember.js app itself as an CouchApp in the same CouchDB database and, with simple CouchDB and optionally nginx configuration, serve it to your users.
Both CouchDB 1.6 and 2.0 are supported.
While Sofa has already most of commonly required features implemented, there is quite a few things in the roadmap like:
- collection and relationship pagination, search, filtering support
- local PouchDB support
- document changes listener for local PouchDB and remote CouchDB instances
- per-database model name to document type mapping, embedded models and so on
- Portfolio – Photography portfolio app (which showcases model inheritance, attachments, relationships, queries, collections)
ember install ember-cli-sofaThis section will guide you through sofa configuration and most common features.
Let's start with setting it up.
Be sure to remove
ember-dataaddon from yourpackage.jsonas Ember Data also registersstoreservice and those two will clash. Or just name your sofa service differently.
Easiest way to start using sofa is to create a store service by extending Store:
// services/store.js
import { Store } from 'sofa';
export default Store.extend({
databaseOptionsForIdentifier(identifier) {
let url = 'http://127.0.0.1:5984';
if(identifier === 'main') {
return { url, name: 'great-app' };
}
}
});The only required override is databaseOptionsForIdentifier which is used to determine CouchDB url and database name for given database identifier. This is done because this way actual database url and name is detached from database identifier which is used throughout the application and can be easily changed based on environment and deployment configuration.
Now we have a service, let's declare a global store variable and try it out in the console:
// instance-initializers/sofa-develop.js
export default {
name: 'sofa:develop',
initialize(app) {
window.store = app.lookup('service:store');
window.log = console.log.bind(console);
window.err = err => console.error(err.toJSON ? err.toJSON() : err.stack);
}
};Let's start by logging in as an CouchDB _admin. This might come in handy if database does not exist. Open your browser's console and type this thing in:
store.get('db.main.couch.documents.session').save('<admin>', '<password>').then(log, err)
// → {ok: true, name: ...}Now let's make sure that main database exists:
store.get('db.main.documents.database').info().then(log, err)
// depending if database actually exists:
// → {db_name: "great-app", ... }
// → {error: "not_found", reason: "Database does not exist.", status: 404}So, if database doesn't exist, we can easily create it by calling create():
store.get('db.main.documents.database').create().then(log, err)
// → {ok: true}Good, now that we have created the database and it's time to start filling it up with some random documents.
For now reason, let's save a doc:
store.get('db.main.documents').save({
_id: 'first',
message: 'To whom it may concern: It is springtime. It is late afternoon.',
author: 'Kurt Vonnegut'
}).then(log, err)
// → {ok: true, id: "first", rev: "1-8ed895a12ea8c1389116bcbaff0b7262"}Load the same doc:
store.get('db.main.documents').load('first').then(log, err)
// → {
// _id: "first",
// _rev: "1-8ed895a12ea8c1389116bcbaff0b7262",
// message: "To whom it may concern: It is springtime. It is late afternoon.",
// author: "Kurt Vonnegut"
// }And delete it:
store.get('db.main.documents').delete('first', '1-8ed895a12ea8c1389116bcbaff0b7262').then(log, err)
// → {ok: true, id: "first", rev: "2-39d1e13f087a31499c222f8c4657fdb1"}Easy enough, right? See JSON.* sections below for overview about raw CouchDB JSON API wrappers.
But now it's time to create a model class and let sofa manage all the document saving, loading, querying details.
In previous section we where playing with a document which had message and author, let's reimplement the same by using two models: Message and Author.
// models/message.js
import { Model, attr, belongsTo } from 'sofa';
export default Model.extend({
text: attr('string'),
author: belongsTo('author', { inverse: 'messages' }),
});// models/author.js
import { Model, attr, hasMany } from 'sofa';
export default Model.extend({
fullName: attr('string'),
messages: hasMany('message', { inverse: 'author', query: 'author-messages' }),
});// queries/author-messages.js
import Ember from 'ember';
import { Query } from 'sofa';
const {
computed
} = Ember;
export default Query.extend({
find: computed('model.docId', function() {
let author = this.get('model.docId');
// mango
// return { selector: { author } } };
// ddoc
return { ddoc: 'message', view: 'by-author', key: author };
}),
});// sofa/databases/main.js
/* global emit */
import Ember from 'ember';
import { Database } from 'sofa';
const {
RSVP: { all, resolve }
} = Ember;
const message = {
views: {
'by-author': {
map(doc) {
if(doc.type !== 'message') {
return;
}
emit(doc.author, null);
}
}
}
};
export default Database.extend({
loginIfNeeded(name, password) {
if(!name) {
return resolve();
}
let session = this.get('couch.session');
session.setProperties({ name, password });
return session.save();
},
// provide `_admin` name and password if needed
insertDesignDocuments(name, password) {
return this.loginIfNeeded(name, password).then(() => {
let design = this.get('documents.design');
return all([
design.save('message', message)
]);
});
}
});store.get('db.main').insertDesignDocuments('duck', 'secret duck').then(log, err);
// → [ {ok: true, id: "_design/message", rev: "1-58d85750a59785112252278496836757", saved: true} ]Note: we will be saving documents with CouchDB auto-generated _id which may differ
db = store.get('db.main');
author = db.model('author', { fullName: 'Kurt Vonnegut' });
author.getProperties('id', 'isNew', 'isDirty')
// → {id: undefined, isNew: true, isDirty: true}
author.save();
author.getProperties('id', 'isNew', 'isDirty')
// → {id: "930c5583a5c3693a71cd3d6aba1b32c7", isNew: false, isDirty: false}
message = db.model('message', { author, text: 'To whom it may concern: It is springtime. It is late afternoon.' });
author.get('messages.firstObject') === message;
// → true
message.save();
message.getProperties('id', 'isNew', 'isDirty')
// → {id: "930c5583a5c3693a71cd3d6aba1b34a4", isNew: false, isDirty: false}And reload the browser so there is no cached models in sofa store
db = store.get('db.main');
db.load('author', '930c5583a5c3693a71cd3d6aba1b32c7').then(author => window.author = author)
author.get('messages.isLoaded') // this kicks off the query load
// → false
// XHR finished loading: GET "http://127.0.0.1:5984/great-app/_design/message/_view/by-author?key=%22930c5…
author.get('messages.isLoaded')
// → true
message = author.get('messages.firstObject')
message.get('text')
// → "To whom it may concern: It is springtime. It is late afternoon."
message.get('author') === author
// → true- isNew
- isLoading
- isLoaded
- isDirty
- isSaving
- isDeleted
- isError
- error
...
...
let main = store.get('db.main');- isLoading
- isLoaded
- isDirty
- isSaving
- isError
- error
- isLoading
- isLoaded
- isDirty
- isSaving
- isError
- error