Permalink
Browse files

Updated in-memory store documentation and little fix.

  • Loading branch information...
1 parent cca2d76 commit d6e34190ddaaf246115bcea378c5e61e0eb95f7a @zefhemel zefhemel committed Jan 26, 2011
Showing with 57 additions and 6 deletions.
  1. +49 −4 README.md
  2. +8 −2 lib/persistence.store.memory.js
View
@@ -14,8 +14,9 @@ supports 4 types of data stores:
* [MySQL](http://www.mysql.com), using the
[node-mysql](http://github.com/felixge/node-mysql), node.js module
on the server.
-* In-memory, as a fallback. Keeps the database in memory and is cleaned
- upon a page refresh (or server restart).
+* In-memory, as a fallback. Keeps the database in memory and is
+ cleaned upon a page refresh (or server restart), unless saved to
+ [localStorage](http://dev.w3.org/html5/webstorage/).
There is also an experimental support for [Qt 4.7 Declarative UI
framework
@@ -94,14 +95,16 @@ Browser support
* Modern webkit browsers (Google Chrome and Safari)
* Firefox (through Google Gears)
+* Opera
* Android browser (tested on 1.6 and 2.x)
* iPhone browser (iPhone OS 3+)
* Palm WebOS (tested on 1.4.0)
+* Other browsers supporting `localStorage` (e.g. Firefox)
(The following is being worked on:)
Internet Explorer is likely not supported (untested) because it
lacks `__defineGetter__` and `__defineSetter__` support, which
-`persistence.js` uses heavily. This may change in IE 8.
+`persistence.js` uses heavily. This may change in IE 9.
Setting up
----------
@@ -121,6 +124,10 @@ web directory. You can then load them as follows:
<script src="persistence.store.sql.js" type="application/javascript"></script>
<script src="persistence.store.websql.js" type="application/javascript"></script>
+If you want to use the in-memory store (in combination with
+`localStorage`) you also need the `persistence.store.memory.js`
+included.
+
Setup your database
-------------------
@@ -136,10 +143,48 @@ in your database name (it will create it if it does not already exist,
the third is a description for you database, the last argument is the
maximum size of your database in bytes (5MB in this example).
-If you're using the in-memory store, you can configure it as follows:
+Additional notes on the in-memory store
+---------------------------------------
+
+The in-memory store is offered as a fallback for browsers that do not
+support any of the other supported stores (e.g. WebSQL or Gears). In
+principal, it only keeps data in memory, which means that navigating
+away from the page (including a reload or tab close) will result in
+the loss of all data.
+
+A way around this is using the `persistence.saveToLocalStorage` and
+`persistence.loadFromLocalStorage` functions that can save the entire
+database to the [localStorage](http://dev.w3.org/html5/webstorage/), which
+is persisted indefinitely (similar to WebSQL).
+
+If you're going to use the in-memory store, you can configure it as follows:
persistence.store.memory.config(persistence);
+Then, if desired, current data can be loaded from the localStorage using:
+
+ persistence.loadFromLocalStorage(function() {
+ alert("All data loaded!");
+ });
+
+And saved using:
+
+ persistence.saveToLocalStorage(function() {
+ alert("All data saved!");
+ });
+
+Drawbacks of the in-memory store:
+
+* Performance: All actions that are typically performed by a database
+ (sorting, filtering), are now all performed in-memory using
+ Javascript.
+* Limited database size: Loading and saving requires serialization of
+ all data from and to JSON, which gets more expensive as your dataset
+ grows. Most browsers have a maximum size of 5MB for `localStorage`.
+* Synchronous behavior: Although the API is asynchronous, all
+ persistence actions will be performed synchronously on the main
+ Javascript thread, which may make the browser less responsive.
+
Schema definition
-----------------
@@ -77,12 +77,18 @@ persistence.store.memory.config = function(persistence) {
};
persistence.transaction = function(callback) {
- callback({executeSql: function() {} });
+ setTimeout(function() {
+ callback({executeSql: function() {} });
+ }, 0);
};
persistence.loadFromLocalStorage = function(callback) {
var dump = window.localStorage.getItem('persistenceData');
- this.loadFromJson(dump, callback);
+ if(dump) {
+ this.loadFromJson(dump, callback);
+ } else {
+ callback();
+ }
};
persistence.saveToLocalStorage = function(callback) {

0 comments on commit d6e3419

Please sign in to comment.