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.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
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 ?