An indexedDB wrapper for accessing indexedDB as a promise base api implementation.
The new version of indexedb-orm now uses typescript for its primary language.
For older version please go to branch orm-dev
maxgaurav.github.io/indexeddb-orm
Examples coming soon to the website.
- Features
- Installation
- Usage
- Query Building
- Create structure of database with indexes and versioning
- Get model instances and query builder for both indexed columns and non indexed columns
- Run queries on WebWorker
- Create relation between multiple tables
npm install indexeddb-orm --save
- An setting parameter needs to be created for database structure handling. Models will be populated using the table names provided.
- Use the idb function and pass base configuration with database structure.
let settings = {
name : 'nameOfDatabase',
version : 1, //version of database
migrations : [{
name : 'users', //name of table
primary : 'id', //auto increment field (default id)
columns : [{
name : 'email', //other indexes in the database
attributes : { //other keyPath configurations for the index
unique : true
}
},{
name : 'userContacts',
columns : [{
name : 'phone',
attributes : {
multiEntry: true
}
},{
name : 'contactId', //name of the index
index : 'medical.contactId' //if provided then indexing value will be this
},{
name : 'userId'
}]
}]
}]
};
let db = idb(settings);- By default usage of web worker is not enabled but if you want to use it then set useWebWorker property in config as true and set the property pathToWebWorker as the location of worker.js from dist folder
let db = idb(settings, true, '/absolute/path/to/worker.js');- Inserting content to database using create.
- Inserting content will automatically add a updatedAt and createdAt entry with timestamp
db.connect(function(models) {
models.users.create({
email : 'test@test.com'
}).then(function(result) {
}).catch(function(error){
//do something
})
}) - Allows insertion of multiple content in a table
db.connect(function(models) {
models.usersContacts.create([{
userId : 1,
firstName : 'TestFirst',
lastName : 'TestLast',
medical : {
contactId : 10,
hospitalId : 11
}
},{
userId : 2,
firstName : 'Test2First',
lastName : 'Test2Last',
medical : {
contactId : 20,
hospitalId : 111
},
phone : ['111111111', '22222222222']
}]).then(function(results) {
/**
* Will return an array of results
**/
}).catch(function(error){
//do something
});
}) - Can search for direct id value using the find operation and will return result if exists else will throw an error
db.connect().then(function(models) {
models.users.find(1).then(function(result){
});
});- Will search for first occurrence in the table and return the value else return null
db.connect().then(function(models) {
models.users.first().then(function(result){
});
});- Will search for all matching occurrence in the table and return the value else return blank array
db.connect().then(function(models) {
models.users.get().then(function(results){
});
});- Direct search on indexes are possible but only one index search builder is allowed. This is due to limitation of indexedDB itself.
- If you attempt to write another index query then the previous one will be overridden
Direct search on index. First parameter as the index name and second parameter as the index value
db.connect().then(function(models) {
models.users.whereIndex('email','test@test.com').first().then(function(result){
});
models.userContacts.whereIndex('userId',1).get().then(function(results){
});
});Multiple search of index in the given range of values provided as array
db.connect().then(function(models) {
models.users.whereIndexIn('email',['test@test.com','test1@test.com']).first().then(function(result){
});
models.userContacts.whereIndexIn('userId',[2,54,1,5]).get().then(function(results){
});
});Search of index values against the point greater or equal to the given value. It is case sensitive
db.connect().then(function(models) {
models.users.whereIndexGte('email','test@test.com').first().then(function(result){
});
models.userContacts.whereIndexGte('userId',20).get().then(function(results){
});
});Search of index values against the point greater only to the given value. It is case sensitive.
db.connect().then(function(models) {
models.users.whereIndexGt('email','test@test.com').first().then(function(result){
});
models.userContacts.whereIndexGt('userId',20).get().then(function(results){
});
});Search of index values against the point less than or equal to the given value. It is case sensitive
db.connect().then(function(models) {
models.users.whereIndexLte('email','test@test.com').first().then(function(result){
});
models.userContacts.whereIndexLte('userId',20).get().then(function(results){
});
});Search of index values against the point less than only to the given value. It is case sensitive.
db.connect().then(function(models) {
models.users.whereIndexLt('email','test@test.com').first().then(function(result){
});
models.userContacts.whereIndexLt('userId',20).get().then(function(results){
});
});Search of index values betweent the given lower and upper bound values. It is case sensitive for string values.
db.connect().then(function(models) {
models.users.whereIndexBetween('email','test@test.com', 'zest@test.com').first().then(function(result){
});
models.userContacts.whereIndexBetween('userId',20, 52).get().then(function(results){
});
});There will be some columns where indexes are not there you can combine index search queries with non index search queries and build an adequate query to filter the data. Since only single indexed query can be fired once you can use these query builder option to fire other point searches on remaining indexes. Non index searches are performance heavy operation so be careful of such searches. If needed then make non indexed columns as indexed.
Add a simple where clause to the query builder before or after the indexed builder to add condition. You can add multiple of these in succession.
db.connect().then(function(models) {
models.users.where('isAdmin', true).whereIndexBetween('email','test@test.com', 'zest@test.com').where('isAdmin', false).first().then(function(result){
});
models.userContacts.whereIndexBetween('userId',20, 52).where('id', 10).get().then(function(results){
});
});To search for a value under a nested attribute you can pass a dot notation value to the query builder column name.
db.connect().then(function(models) {
models.userContacts.whereIndexBetween('userId',20, 52).where('medical.contactId', 10).get().then(function(results){
});
});To search for result in a multiple search values for column then pass array as an value for the search
db.connect().then(function(models) {
models.userContacts.whereIn('userId',[20, 52]).where('medical.contactId', 10).get().then(function(results){
});
});Search of values against the point greater or equal to the given value. It is case sensitive
db.connect().then(function(models) {
models.users.gte('email','test@test.com').first().then(function(result){
});
models.userContacts.gte('userId',20).get().then(function(results){
});
});Search of values against the point greater only to the given value. It is case sensitive.
db.connect().then(function(models) {
models.users.gt('email','test@test.com').first().then(function(result){
});
models.userContacts.gt('userId',20).get().then(function(results){
});
});Search of values against the point less than or equal to the given value. It is case sensitive
db.connect().then(function(models) {
models.users.lte('email','test@test.com').first().then(function(result){
});
models.userContacts.lte('userId',20).get().then(function(results){
});
});Search of values against the point less than only to the given value. It is case sensitive.
db.connect().then(function(models) {
models.users.lt('email','test@test.com').first().then(function(result){
});
models.userContacts.lt('userId',20).get().then(function(results){
});
});Search of index values betweent the given lower and upper bound values. It is case sensitive for string values.
db.connect().then(function(models) {
models.users.whereIndexBetween('email','test@test.com', 'zest@test.com').first().then(function(result){
});
models.userContacts.whereIndexBetween('userId',20, 52).get().then(function(results){
});
});- Data from different tables can be fetched with association with current table using relations. There are two relations hasone and hasmany.
models.users.whereIndexIn('id',[1,2,10,11])
.where('isAdmin', true)
.relation('userContacts',models.users.RELATIONS.hasMany, 'id', 'userId')
.get().then(function(results) {
/**
* each results object will have an userContacts property with matching result with users table
**/
});- You also refine the relationship using the final parameter by passing a function which will receive a builder function and can build using the common non indexed query builder functions.
models.users.whereIndexIn('id',[1,2,10,11])
.where('isAdmin', true)
.relation('userContacts',models.users.RELATIONS.hasMany, 'id', 'userId', function(builder) {
//refined search for relation
return builder.whereIn('id', [1,2,3]).where('medical.contactId', 10);
})
.get().then(function(results) {
/**
* each results object will have an userContacts property with mathcing result with users table
**/
});- You can also call for nested relation to nth level using the secondry query builder of the relation
models.users.whereIndexIn('id',[1,2,10,11])
.where('isAdmin', true)
.relation('userContacts',models.users.RELATIONS.hasMany, 'id', 'userId', function(builder) {
//refined search for relation
return builder.whereIn('id', [1,2,3])
.where('medical.contactId', 10)
.relation('contacts', models.users.RELATIONS.hasOne,'contactId', 'id');
})
.get().then(function(results) {
/**
* each results object will have an userContacts property with mathcing result with users table
**/
});This will update the data at the given primary id of the table with content provided. The whole content will not be replaced but only the properties provided. Primary key ,updatedAt and createdAt values will be ignored even if provided
models.users.save(1, {
isAdmin : false
}).then(function(result) {
/**
* result with value true will be returned
**/
});This will update the data with matching values according to the query builder given of the table with content provided. The whole content will not be replaced but only the properties provided. Primary key ,updatedAt and createdAt values will be ignored even if provided
models.users.whereIndex('email', 'test@test.com').where('isAdmin', true).update({
isAdmin : false
}).then(function(result) {
/**
* result with value true will be returned
**/
});This will destroy the data at the given primary id of the table.
models.users.destroyId(3).then(function(result) {
/**
* result with value true will be returned
**/
});This will update the data with matching values according to the query builder given of the table with content provided. The whole content will not be replaced but only the properties provided. Primary key ,updatedAt and createdAt values will be ignored even if provided
models.users.whereIndex('email', 'test@test.com').where('isAdmin', true).destroy().then(function(result) {
/**
* result with value true will be returned
**/
});Sometimes it is needed to work in a single transaction and commit the content once or fail throughout. For this purpose one can use the transaction functionality in the system.
Open a transaction in any of the model and pass a list of models you want to open transaction in. All transaction are in read write.
NOTE: If external content is needed then best pass it through the passableData parameter as in worker the data will available without any problem;
If any of the builder would have a relation call then also add it to models listing as transaction is explicit to the listing provided.
Calling transaction.abort() will cause the transaction to fail.
let db = new idb(config);
models = await db.connect();
let user = await models.users.openTransaction([models.userContacts, models.users], async (transaction, models, passableData) => {
//some model actions
let result = await models.userConcats.first();
if(result._id !== 45) {
//if needed
transaction.abort();
}
let content = {
email : passableData.email,
content: result
};
return models.users.create(content);
}, {
data: 'attribute'
});
The count will return total number of records in the table against the result obtained by query builer object
models.users.whereIndex('email', 'test@test.com').where('isAdmin', true).count().then(function(result) {
/**
* result with total number of records in the table
**/
});Aggregate of the result at the given column will be provided. If the column contains non numeric value then it will be treated as a ZERO value
models.users.whereIndex('email', 'test@test.com').where('isAdmin', true).average('id').then(function(result) {
/**
* result with total number of records in the table
**/
});
models.users.whereIndex('userId', 10).where('firstName', 'Test').average('medical.contactId').then(function(result) {
/**
* result with aggregate of the nested column provided
**/
});Reduce process can be fired using the reduce function passed. If needed an default value can be passed as a second parameter
models.users.whereIndex('email', 'test@test.com').where('isAdmin', true).reduce(function(result, carry){
return carry + result.id
}, 0).then(function(result) {
/**
* result with total number of records in the table
**/
});