Open Source Ecosystems

#localDB - A Simple localStorage Database

localDB is a simple database layer for localStorage.

##Table of Contents:

One thing to bear in mind when using localStorage is that it has a limit of 5MB before the browser warns the user.

<script type="text/javascript" src="localdb.min.js"></script>

Structure: A database is stored as a key in localStorage, this key contains a JSON encoded string of an object which is the database. The structure of the database is displayed below:

db_name |---table_name |---totalrows (variable) |---autoinc (variable) |---rows (array)

Return values: If a function fails a some point it will always return false, most functions will also output an error message into the browsers console in order to give you a description of exactly what went wrong in an attempt to help you what the problem was. Return values are noted next to each of the functions further down these docs.

var db = new localdb('dbname');

Example:

var db = new localdb('foo');

Returns: None

db.deleteDatabase('database_name');

Example:

db.deleteDatabase('foo');

Returns: Success: true Error: false with error message (console)

db.createTable('table_name');

Example:

db.createTable('users');

Returns: Success: true Error: false with error message (console)

db.dropTable('table_name');

Example:

db.dropTable('users');

Returns: Success: true Error: false with error message (console)

var meta = db.tableMeta('table_name');

Example:

var meta = db.tableMeta('users');

Returns: Success: true Error: false with error message (console)

In order to insert some data into the database you need to provide the name of the table and the data you would like to insert into the first and second parameters respectively of the insert() function as follows:

db.insert('table_name', data_object);

Example:

db.insert('users', {'username': 'johnsmith', 'firstname': 'John', 'lastname': 'Smith'});

Returns: Success: true

update(table_name, data_object, where_object)

The update() method has 3 parameters, going from first to last they are: table, data and where. The code for updating some data in the database using the update() method would look something like this:

db.update('users', {'username': 'smithy576'}, {'username': 'johnsmith'});

Returns: Success: true Error: false with error message (console)

updateById(table_name, data_object, id)

The updateById() method also has 3 parameters, going from first to last they are: table, data and id. This function is only really any use when you know the ID of the row you are trying to update. The code for updating some data using the updateById() method would look something like this:

db.updateById('users', {'username': 'smithy576'}, 1);

Returns: Success: true Error: false with error message (console)

remove(table_name, where_object)

The remove() method has 2 parameters, the first one being table and the second being where. The code for removing some data from the database using the remove() method would look something like this:

db.remove('users', {'username': 'smithy576'});

Returns: Success: true Error: false with error message (console)

removeById(table_name, id)

The removeById() method also has 2 parameters, the first one being table and the second one being id. This function is only really any use when you know the ID of the row you are trying to remove. The code for removing some data using the removeById() method would look something like this:

db.removeById('users', 1);

Returns: Success: true Error: false with error message (console)

find(table_name, where_object, limit, offset, type)

The find() method has 5 parameters, from left to right they are as follows: table_name, where, limit, offset, type. I will explain these parameters a little more below:

table_name - Simple, it's the name of the table that you want to search in where (optional) - An object containing the where criteria, check below for an example. If omitted, the search will match all rows limit (optional) - The maximum number of items you want to be returned offset (optional) - The offset of the returned results type (optional) - This is the type of search you want to run. Possible values are AND and OR. If omitted this defaults to AND.

The code for finding some data in the database using the find() method would look something like this:

Example 1:

var results = db.find('users', {'username': 'smithy576'}); English: Find all users where their username is smithy576

Example 2:

var results = db.find('users', {'username': 'smithy576', 'firstname': 'Jason'}, 1, 0, 'OR'); English: Find one user where either their username is smithy576 or their first name is Jason

Example 3:

var results = db.find('users', {'title': 'Mr', 'lastname': 'Williams'}, 5, 0, 'AND'); English: Find 5 users where their title is Mr and their last name is Williams

Returns: Success: Array Error: false with error message (console)

findById(table_name, id)

The findById() method has 2 parameters, the first one being table and the second one being id. This function is only really any use when you know the ID of the row you are trying to find. The code for finding some data using the findById() method would look something like this:

db.findById('users', 1);

Returns: Success: Array Error: false with error message (console)

var dbexists = db.dbExists('dbname');

Example:

var dbexists = db.dbExists('bar');

Returns: Success: true Error: false

var tableexists = db.tableExists('table_name');

Example:

var tableexists = db.tableExists('users');

Returns: Success: true Error: false

var json = db.exportData('table_name');

Example 1: