Skip to content
Artemia is a clientside JSON document store like Lawnchair (in the way of CouchDb). It's very very (and very) inspired by Lawnchair (it copies many aspects, normal, i love Lawnchair) but has some specific features.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
js
samples
README.md

README.md

#--=>>>|:<

##What is artemia ?

Artemia is a clientside JSON document store like Lawnchair (in the way of CouchDb).

initially, it was designed to work with several adaptors :

  • local storage (Webkit)
  • session storage (Webkit)
  • global storage (Firefox)
  • sqlite storage (Webkit)

But you can find a userdata storage plug-in too (see artemia.userdata.storage.js)

It's very very (and very) inspired by Lawnchair (he copy many aspects, normal, i love Lawnchair) but has some specific features :

  • plug-in mode with module pattern
  • Only for local, session, global (and userdata) storages :some reduce function with query() method : sum(), product(), min(), max()

##How to ?

###Install it

If you want to work with local storage, or/and session storage, or/and global storage :

    <script src="../js/artemia.js"></script>
    <script src="../js/adaptors.plugins/artemia.storage.js"></script>

If you want to work with sqlite storage :

    <script src="../js/artemia.js"></script>
    <script src="../js/adaptors.plugins/artemia.sqlite.js"></script>

###Init

    /* local storage */
    var localStore = artemia.getStore({type : 'local', base : 'myfirstbase'});

    /* session storage */
    var sessionStore = artemia.getStore({type : 'session', base : 'myotherbase'});

    /* global storage */
    var globalStore = artemia.getStore({
        type : 'global',
        base : 'mybase',
        domain : window.location.hostname
    });

    /* sqlite storage */
    var dbStorage = artemia.getStore({type : 'sqlite', base : 'myDataBase'});

Remark : with FF (global storage) you have to provide 'domain' parameter, see : http://ejohn.org/blog/dom-storage/ and http://ejohn.org/blog/dom-storage-answers/ and your page has to be served by an http server (no 'file:///', but 'http://' way)

###Methods

save(document, callback) : insert or update a document

    var myBook = {
        key :"0001",
        title : "Hello",
        author : "Me",
        text : "this the doc one",
        price : 5
    }

    myStore.save(myBook, function(r) { /*callback function*/ });

    /*
        r return the object
        if you have not provided a key, artemia generates an unique key for you
        you can read it with r.key
    */

get(key, callback) : retrieve a document

    myStore.get("0001", function(r) {
        console.log(r.key, r.title);
    });

Remark : if you want to update a document, you have to get it with get() before save() it

remove(key_or_object, callback) : remove a document

    myStore.remove("0001", function(r) { /*callback function*/ });
    /* or if you have already get a document*/
    myStore.remove(document, function(r) { /*callback function*/ });

all(callback) : get all documents (return an array of objects)

    myStore.all(function(r){
        var i;
        for(i = 0; i < r.length; i += 1 ) {
            document.write(r[i].key + " " + r[i].title + " " + r[i].text + "<BR>");
        }
    });

query(map, callback) : return an array of objects, filtered by a "map" function

    /*i want all document written by "Me"*/
    var mapFunction = function(doc) {
      if (doc.author == "Me")
        return doc
    };

    myStore.query(mapFunction, function(r) {
        var i;
        for(i = 0; i < r.length; i += 1 ) {
            document.write(r[i].key + " " + r[i].title + " " + r[i].text + "<BR>");
        }
    });

drop(callback) : drop the store

    myStore.drop(function(r) { /*callback function*/ });

##Specific features : reduce functions (!!! not for sqlite storage)

    var mapFunction = function(doc){
        return doc.price;
    }

    var min = myStore.query(map).min();

    /* or */

    myStore.query(map).min(function(r) { /* r = min */ });

    /* or */

    myStore.query(map, function(r) { /* r = result set */ }).min(function(r) { /* r = min */ });

    /* and of course */

    var max = myStore.query(map).max();

    var sum = myStore.query(map).sum();

    var product = myStore.query(map).product();

###But ... If you want to do the same thing with sqlite storage :

You can do that (less pretty i know) :

    myStore.query(sumFunction,function(r){
        console.log("SUM : ", artemia.sum(r));
        console.log("PRODUCT : ", artemia.product(r));
        console.log("MIN : ", artemia.min(r));
        console.log("MAX : ", artemia.max(r));
    })

##Create an adaptor

Imagine you want to create a CoucDb adaptor you can call like this : var couchDb = artemia.getStore({type : 'couchdb', base : 'mybase'});

you have just to create a new js file like this

var artemia = (function (cyste) {

    function getCouchDBStore(baseName,storeType){

        return {
            storeType:storeType,
            storeName:baseName,
            useReduce : true, /* ie : is false for sqlite adaptor */
            isAvailable:function(){},
            get:function(){},
            remove:function(){},
            save:function(){},
            all:function(){},
            drop:function(){}
        };
    };

    /*the _UPPER_ is a convention*/
    cyste.get_COUCHDB_store = function(baseName,storeType){
        var store = getCouchDBStore(baseName,storeType);
        if(!store.isAvailable()){store=null;}
        return store;
    };

    return cyste;
}(artemia));

Remark : if type = "couchdb" you have to cretae a function named cyste.get_COUCHDB_store with "couchdb" capitalized, if type = "johndoe" : cyste.get_JOHNDOE_store, etc. ...

it's a convention (and type is always in lowercase), it allows you add plug-in without modify core artemia.js.

Be careful : it is mandatory to implement this :

    cyste.Interface = {
        storeType : '',
        storeName : '',
        useReduce : true,
        isAvailable : function () {},
        get : function () {},
        remove : function () {},
        save : function () {},
        all : function () {},
        drop : function () {}
    };

##Add a functionality

Just do this (in an other js file) :

    var artemia = (function (cyste) {

        cyste.myFunction = function() { return null; }

        return cyste;
    }(artemia));

##Minified versions

You can find :

  • artemia.min.js (Compiled Size : 1.40KB)

  • artemia.storage.min.js (Compiled Size : 1.16KB)

  • artemia.sqlite.storage.min.js (Compiled Size : 2.04KB)

  • artemia.pkg.lite.min.js = artemia + artemia.storage (Compiled Size : 2.55KB)

  • artemia.pkg.min.js = artemia + artemia.storage + artemia.sqlite.storage (Compiled Size : 4.59KB)

##TO DO

  • Write real samples, mine are very creepy
  • Improve my english (creepy too)
  • a CouchDb adaptor ?
You can’t perform that action at this time.