Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A simple database layer for localStorage
branch: master

This branch is 1 commit ahead, 58 commits behind knadh:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
README.md
localstoragedb.js
localstoragedb.min.js

README.md

localStorageDB

a simple, tiny database layer for localStorage

Kailash Nadh, September 2011

Documentation: http://kailashnadh.name/code/localstoragedb Licensed under the MIT license.

Usage / Examples

Creating a database, table, and populating the table

// Initialise. If the database doesn't exist, it is created
var lib = new localStorageDB("library");

// Check if the database was just created. Useful for initial database setup
if( lib.isNew() ) {

    // create the "books" table
    lib.createTable("books", ["id", "title", "author", "year", "copies"]);
    
    // insert some data
    lib.insert("books", {id: "B001", title: "Phantoms in the brain", author: "Ramachandran", year: 1999, copies: 10});
    lib.insert("books", {id: "B002", title: "The tell-tale brain", author: "Ramachandran", year: 2011, copies: 10});
    lib.insert("books", {id: "B003", title: "Freakonomics", author: "Levitt and Dubner", year: 2005, copies: 10});
    lib.insert("books", {id: "B004", title: "Predictably irrational", author: "Ariely", year: 2008, copies: 10});
    lib.insert("books", {id: "B005", title: "Tesla: Man out of time", author: "Cheney", year: 2001, copies: 10});
    lib.insert("books", {id: "B006", title: "Salmon fishing in the Yemen", author: "Torday", year: 2007, copies: 10});
    lib.insert("books", {id: "B007", title: "The user illusion", author: "Norretranders", year: 1999, copies: 10});
    lib.insert("books", {id: "B008", title: "Hubble: Window of the universe", author: "Sparrow", year: 2010, copies: 10});
    
    // commit the database to localStorage
    // all create/drop/insert/update/delete operations should be committed
    lib.commit();
}

Querying

// simple select queries
lib.query("books", {year: 2011});
lib.query("books", {year: 1999, author: "Norretranders"});

// select all books
lib.query("books");

// select all books published after 2003
lib.query("books", function(row) {  // the callback function is applied to every row in the table
    if(row.year > 2003) {       // if it returns true, the row is selected
        return true;
    } else {
        return false;
    }
});

// select all books by Torday and Sparrow
lib.query("books", function(row) {
    if(row.author == "Torday" || row.author == "Sparrow") {
        return true;
    } else {
        return false;
    }
});

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.query("books", {author: "ramachandran"});

/* results
[
 {
   ID: 1,
   id: "B001",
   title: "Phantoms in the brain",
   author: "Ramachandran",
   year: 1999,
   copies: 10
 },
 {
   ID: 2,
   id: "B002",
   title: "The tell-tale brain",
   author: "Ramachandran",
   year: 2011,
   copies: 10
 }
]
*/

Updating

// change the title of books published in 1999 to "Unknown"
lib.update("books", {year: 1999}, function(row) {
    row.title = "Unknown";
    
    // the update callback function returns to the modified record
    return row;
});

// add +5 copies to all books published after 2003
lib.update("books",
    function(row) { // select condition callback
        if(row.year > 2003) {
            return true;
        } else {
            return false;
        }
    },
    function(row) { // update function
        row.year+=5;
        return row;
    }
);

Deleting

// delete all books published in 1999
lib.deleteRows("books", {year: 1999});

// delete all books published before 2005
lib.deleteRows("books", function(row) {
    if(row.year 

Methods

Method Arguments Description
localStorageDB() database_name Constructor
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
serialize() Returns the entire database as serialized JSON
tableExists() table_name Checks whether a table exists in the database
createTable() table_name, fields Creates a table
- fields is an array of string fieldnames. 'ID' is a reserved fieldname.
dropTable() table_name Deletes a table from the database
truncate() table_name Empties all records in a table and resets the internal auto increment ID to 0
rowCount() table_name Returns the number of rows in a table
insert() table_name, data Inserts a row into a table and returns its numerical ID
- data is an object literal with field-values
Every row is assigned an auto-incremented numerical ID automatically
query() table_name, query, limit Returns an array of rows (object literals) from a table matching the query.
- query is either an object literal or null. If query is not supplied, all rows are returned
- limit is the maximum number of rows to be returned
Every returned row will have it's internal auto-incremented id assigned to the variable ID
update() table_name, query, update_function Updates existing records in a table matching query, and returns the number of rows affected
- query is an object literal or a function. If query is not supplied, all rows are updated
- update_function is a function that returns an object literal with the updated values
deleteRows() table_name, query Deletes rows from a table matching query, and returns the number of rows deleted
- query is either an object literal or a function. If query is not supplied, all rows are deleted
Something went wrong with that request. Please try again.