localStorageDB 2.3.2
localStorageDB is a simple layer over localStorage (and sessionStorage) that provides a set of functions to store structured data like databases and tables. It provides basic insert/update/delete/query capabilities. localStorageDB has no dependencies, and is not based on WebSQL. Underneath it all, the structured data is stored as serialized JSON in localStorage or sessionStorage.
- Kailash Nadh
- v 2.3.2 Mar 2018 Contribution: Ken Kohler
- v 2.3.1 Mar 2015
- v 2.3.0 Feb 2014 Contribution: Christian Kellner (http://orange-coding.net)
- v 2.2 Jan 2014 Contribution: Andy Hawkins (http://a904guy.com)
- v 2.1 Nov 2013
- v 2.0 Jun 2013
- v 1.9 Nov 2012
- Documentation: http://nadh.in/code/localstoragedb
- Licensed: MIT license
Installation
NPM
npm install localstoragedb
Yarn
yarn install localstoragedb
Bower
bower install localstoragedb
Run Test Cases
bower install # install mocha and chai for running test cases
open test/local_storage_db_test.html in Browser to check the result
Supported Browsers
Browsers need to support "Local Storage" in order to make localeStorageDB working.
- IE 8<
- Firefox 31<
- Chrome 31<
- Safari 7<
- iOS Safari 7.1<
- Android Browser 4.1<
- Chrome for Android 42<
Usage / Examples
Creating a database, table, and populating the table
// Initialise. If the database doesn't exist, it is createdvar lib = "library" localStorage; // Check if the database was just created. Useful for initial database setupif lib // create the "books" table lib; // insert some data lib; lib; lib; lib; lib; lib; lib; lib; // commit the database to localStorage // all create/drop/insert/update/delete operations should be committed lib;
Creating and populating a table in one go
// rows for pre-population
var rows = [
{code: "B001", title: "Phantoms in the brain", author: "Ramachandran", year: 1999, copies: 10},
{code: "B002", title: "The tell-tale brain", author: "Ramachandran", year: 2011, copies: 10},
{code: "B003", title: "Freakonomics", author: "Levitt and Dubner", year: 2005, copies: 10},
{code: "B004", title: "Predictably irrational", author: "Ariely", year: 2008, copies: 10},
{code: "B005", title: "Tesla: Man out of time", author: "Cheney", year: 2001, copies: 10},
{code: "B006", title: "Salmon fishing in the Yemen", author: "Torday", year: 2007, copies: 10},
{code: "B007", title: "The user illusion", author: "Norretranders", year: 1999, copies: 10},
{code: "B008", title: "Hubble: Window of the universe", author: "Sparrow", year: 2010, copies: 10}
];
// create the table and insert records in one go
lib.createTableWithData("books", rows);
lib.commit();
Altering
// If database already exists, and want to alter existing tablesif! lib lib; lib; // commit the deletions to localStorage // Multiple columns can also added at onceif! lib && lib lib; lib; // commit the deletions to localStorage
Querying
query()
is deprecated. Use queryAll()
instead.
// simple select querieslib;lib; // select all bookslib; // select all books published after 2003lib; // select all books by Torday and Sparrowlib;
Sorting
// select 5 rows sorted in ascending order by authorlib; // select all rows first sorted in ascending order by author, and then, in descending, by yearlib; lib; // or using query()'s positional arguments, which is a little messy (DEPRECATED)lib;
Distinct records
lib;
Example results from a query
// query results are returned as arrays of object literals// an ID field with the internal auto-incremented id of the row is also included// thus, ID is a reserved field name lib; /* results[ { ID: 1, code: "B001", title: "Phantoms in the brain", author: "Ramachandran", year: 1999, copies: 10 }, { ID: 2, code: "B002", title: "The tell-tale brain", author: "Ramachandran", year: 2011, copies: 10 }]*/
Updating
// change the title of books published in 1999 to "Unknown"lib; // add +5 copies to all books published after 2003lib;
Insert or Update conditionally
// if there's a book with code B003, update it, or insert it as a new rowlib; lib;
Deleting
// delete all books published in 1999lib; // delete all books published before 2005lib; lib; // commit the deletions to localStorage
Methods
Method | Arguments | Description |
---|---|---|
localStorageDB() | database_name, storage_engine | Constructor - storage_engine can either be localStorage (default) or sessionStorage |
isNew() | Returns true if a database was created at the time of initialisation with the constructor | |
drop() | Deletes a database, and purges it from localStorage | |
tableCount() | Returns the number of tables in a database | |
commit() | Commits the database to localStorage. Returns true if successful, and false otherwise (highly unlikely) | |
serialize() | Returns the entire database as serialized JSON |
Storing complex objects
While the library is meant for storing fundamental types (strings, numbers, bools), it is possible to store object literals and arrays as column values, with certain caveats. Some comparison queries, distinct etc. may not work. In addition, if you retrieve a stored array in a query result and modify its values in place, these changes will persist throughout further queries until the page is refreshed. This is because localStorageDB loads and unserializes data and keeps it in memory in a global pool until the page is refreshed, and arrays and objects returned in results are passed by reference.
If you really need to store arrays and objects, you should implement a deep-copy function through which you pass the results before manipulation.