An indexedDB wrapper for accessing indexedDB as a promise base api implementation.
For older version please go to branch 2.1.0
maxgaurav.github.io/indexeddb-orm
Examples coming soon to the website.
Read ChangeLog
- Features
- Installation
- Usage
- ORM
- Query Building
- Create structure of database with indexes and version
- Get model instances and query builder for both indexed columns and non indexed columns
- Create relation between multiple tables
- Create custom ORM class to be used over default Model instances to provide custom relations
npm install indexeddb-orm --save
yarn add indexeddb-orm
- 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.
import {Connector} from './dist/es2015/connection/connector.js';
const 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'
}]
}]
}]
};
// if using normal script
const idb = idb(settings);
// if using module scripts
const db = new Connector(settings);You can create you own custom class extending the Model class allowing you to create scoped queries, custom relations within the class and much more. Following is an example on how to use and create orm classes.
import {Model} from './dist/es2015/models/model.js';
class UserProfiles extends Model{
static TableName = 'userProfile';
user = () => {
return this.hasOne(Users, 'id', 'userId')
}
}
class Users extends Model {
static TableName = 'users';
userProfile = () => {
// the third and fourth parameter are optional;
// by default the function name would be used as parent models attribute.
return this.hasOne(UserProfiles, 'userId', '_id', 'userProfile')
.where('name', 'newName').with([...]).withCustom(['user']);
}
}
const settings = {
name : 'nameOfDatabase',
version : 1, //version of database
migrations : [{
name : 'users', //name of table
primary : 'id', //auto increment field (default id)
ormClass: Users,
columns : [{
name : 'email', //other indexes in the database
attributes : { //other keyPath configurations for the index
unique : true
}
},{
name : 'userProfiles', //name of table
primary : 'id', //auto increment field (default id)
ormClass: UserProfiles,
columns : [{
name : 'userId', //other indexes in the database
},{
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'
}]
}]
}]
};- Inserting content to database using create.
- Inserting content will automatically add a updatedAt and createdAt entry with timestamp
db.connect(async (models) => {
const record = await models.users.create({
email : '[email protected]'
});
}) - Allows insertion of multiple content in a table
db.connect(async (models) => {
const results = await models.usersContacts.createMultiple([{
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']
}]);
}) - Can search for direct id value using the find operation and will return result if exists else will return null
db.connect().then(async (models) => {
const record = models.users.find(1);
});- Will search for direct id(primary key) value and will return value or throw NotFound error.
db.connect().then(async (models) => {
const record = await models.users.findOrFail(1);
});- Will find the value at primary key and if no record is found then will create a new record and return it.
const data = {};
db.connect().then(async (models) => {
const record = await models.users.firstOrCreate(data);
});- Will search for first occurrence in the table and return the value else return null
db.connect().then(async (models) => {
const record = await models.users.first();
});- Will search for first occurrence in the table and return the value else throws NotFound error
db.connect().then(async (models) => {
const record = await models.users.firstOrFail();
});- Will search for first occurrence in the table and return the value else creates new record
const data = {};
db.connect().then(async (models) => {
const record = await models.users.firstOrCreate(data);
});- Will return the first matching value of the index else will return null
const value = 'something';
db.connect().then(async (models) => {
const record = await models.users.findIndex('indexName', value);
});- Will search for first occurrence in the table and return the value else throws NotFound error.
db.connect().then(async (models) => {
const record = await models.users.first();
});- Will search for first occurrence in the table and return the value else will create a new entry in database and return it.
db.connect().then(async (models) => {
const record = await models.users.first();
});- Will search for all matching indexes and return array of results. If no result is found then an empty array is returned.
db.connect().then(async (models) => {
const record = await models.users.findAllIndex('indexName', 'value');
});- Will search for all matching occurrence in the table and return the value else return blank array
db.connect().then(async (models) => {
const records = await models.users.all();
});- 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(async (models) => {
const user = await models.users.whereIndex('email','[email protected]').first();
const contacts = await models.userContacts.whereIndex('userId',1).all();
});Multiple search of index in the given range of values provided as array
db.connect().then(async (models) => {
const user = await models.users.whereIndexIn('email',['[email protected]','[email protected]']);
const contacts = await models.userContacts.whereIndexIn('userId',[2,54,1,5]).all();
});Searching of index which whose index type is multi entry thus allowing searching of array content
db.connect().then(async (models) => {
const user = await models.users.whereIndexIn('email',['[email protected]','[email protected]']);
const contacts = await models.userContacts.whereMultiIndexIn('phone',['12345','233343',13455,52222]).all();
});Search of index values against the point greater or equal to the given value. It is case sensitive
db.connect().then(async (models) => {
const user = await models.users.whereIndexGte('email','[email protected]').first();
const contacts = await models.userContacts.whereIndexGte('userId',20).all();
});Search of index values against the point greater only to the given value. It is case sensitive.
db.connect().then(async (models) => {
const user = await models.users.whereIndexGt('email','[email protected]').first();
const contacts = await models.userContacts.whereIndexGt('userId',20).all();
});Search of index values against the point less than or equal to the given value. It is case sensitive
db.connect().then(async (models) => {
const user = await models.users.whereIndexLte('email','[email protected]').first();
const contacts = await models.userContacts.whereIndexLte('userId',20).all();
});Search of index values against the point less than only to the given value. It is case sensitive.
db.connect().then(async (models) => {
const user = await models.users.whereIndexLt('email','[email protected]').first();
const contacts = await models.userContacts.whereIndexLt('userId',20).all();
});Search of index values betweent the given lower and upper bound values. It is case sensitive for string values.
db.connect().then(async (models) => {
const user = await models.users.whereIndexBetween('email','[email protected]', '[email protected]').first();
const contacts = await models.userContacts.whereIndexBetween('userId',20, 52).all();
});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(async (models) => {
const user = await models.users.where('isAdmin', true).whereIndexBetween('email','[email protected]', '[email protected]').where('isAdmin', false).first();
const contacts = await models.userContacts.whereIndexBetween('userId',20, 52).where('id', 10).all();
});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(async (models) => {
const contacts = await models.userContacts.whereIndexBetween('userId',20, 52).where('medical.contactId', 10).all();
});To search for result in a multiple search values for column then pass array as an value for the search
db.connect().then(async (models) => {
const contacts = await models.userContacts.whereIn('userId',[20, 52]).where('medical.contactId', 10).all();
});To search for result in a multiple search values for column which contains array of values then pass array as an value for the search
db.connect().then(async (models) => {
const contacts = await models.userContacts.whereIn('phones',[20, 52]).where('medical.contactId', 10).all();
});Search of values against the point greater or equal to the given value. It is case sensitive
db.connect().then(async (models) => {
const user = await models.users.gte('email','[email protected]').first();
const contacts = await models.userContacts.gte('userId',20).all();
});Search of values against the point greater only to the given value. It is case sensitive.
db.connect().then(async (models) => {
const user = await models.users.gt('email','[email protected]').first();
const contacts = await models.userContacts.gt('userId',20).all();
});Search of values against the point less than or equal to the given value. It is case sensitive
db.connect().then(async (models) => {
const user = await models.users.lte('email','[email protected]').first();
const contacts = await models.userContacts.lte('userId',20).all();
});Search of values against the point less than only to the given value. It is case sensitive.
db.connect().then(async (models) => {
const user = await models.users.lt('email','[email protected]').first();
const contacts = await models.userContacts.lt('userId',20).all();
});Search of index values between the given lower and upper bound values. It is case sensitive for string values.
db.connect().then(async (models) => {
const user = await models.users.between('email','[email protected]', '[email protected]').first();
const contacts = await models.userContacts.between('userId',20, 52).all();
});Data from different tables can be fetched with association with current table using relations. The system supports following relations
- Has One
- Has Many
- Has Many Multi-Entry
- Has Many Through Multi-Entry
The relation builder is used to add a relation to the model for it to fetch. The first value is the name of model, followed by the relation type, then the local key of relation model, then local key of calling model and finally a callback to filter the values of relation model further which contains builder reference of relation model. The builder reference can also be used to fetch nested relations with same strategy.
Relations can be added through function call with by passing array of relations. The with function can be called multiple times. If duplicate models are found then previous one is replaced by new one. If you want to have multiple relations on same model then create a custom ORM instance and then create your custom relations.
models.userProfiles.with([{
model: models.users, // You can also pass object store name as string but its strongly recommended to use model instance
type: RelationTypes.HasOne,
foreignKey: 'id',
localKey: 'userId',
attributeName: 'overriddenRelationName' // if relation needs to be attached as a different property
}, ...])The has one relation maps a single column of primary model containing the id reference of other table/object store directly. The matching relation will be single object instance mapped to table name property. If no matching relation is found then the item will be empty.
Example a user instance having one user contact. The user contact fetching the user model using relation.
import {RelationTypes} from './dist/es2015/models/model.interface.js';
const profiles = await models.userProfiles.with([{
model: models.users,
type: RelationTypes.HasOne,
localKey: 'id', // the local key is optional and should be provided if mapping is not directly to primary key
foreignKey: 'userId'
}])
.all();
/**
* each profile object will contain a matching users object as users property
*/The has many relation maps single column of primary model containing the id reference of other table/object store with with matching id.
Example a user having multiple contacts. The user model query with all contacts associated.
import {RelationTypes} from './dist/es2015/models/model.interface.js';
const users = await models.users.whereIndexIn('id',[1,2,10,11])
.where('isAdmin', true)
.with([{model: model.userProfiles , type: RelationTypes.HasMany, foreignKey: 'userId'}])
.all();
/**
* each results object will have an userContacts property with matching result with users table
**/The has many multi entry relation works just like has many but the primary model column value is an array set as multi-entry index.
Example a address table/object store having relation to multiple users using userIds as array with mutli entry index.
import {RelationTypes} from './dist/es2015/models/model.interface.js';
const addresses = await models.addresss.with([{
model: model.users,
type: RelationTypes.HasManyMultiEntry,
localKey: 'id',
foreignKey: 'userIds'
}]).all();
/**
* each address object will have an users property which will be an array of matching users.
*/The has many through multi entry relation is used when the parent model which is setting the relation has the index as multi entry. This is reverse of has manu multi entry where child has index as multi.
Example a address table/object store having relation to multiple users using userIds as array with mutli entry index.
import {RelationTypes} from './dist/es2015/models/model.interface.js';
const addresses = await models.addresss.with([{
model: model.users,
type: RelationTypes.HasManyThroughMultiEntry,
localKey: 'id',
foreignKey: 'userIds'
}]).all();
/**
* each address object will have an users property which will be an array of matching users.
*/- Using the withCustom you can load custom relations defined in the ORM class.
import {Model} from './dist/es2015/models/model.js';
class UserProfile extends Model {
static TableName = 'userProfiles';
}
class User extends Model {
static TableName = 'users';
userProfile = ()=> {
return this.hasOne(UserProfile, 'userId');
}
}
const users = await models.users.whereIndexIn('id',[1,2,10,11])
.where('isAdmin', true)
.withCustom(['userProfile'])
.all();
/**
* each results object will have an userProfile property with matching result with users table
**/ - You can also call for nested relation to nth level using the secondry query builder of the relation
import {RelationTypes} from './dist/es2015/models/model.interface.js';
const users = await models.users.whereIndexIn('id',[1,2,10,11])
.where('isAdmin', true)
.with([{
model: models.userContacts,
type: RelationTypes.HasMany,
localKey: 'id',
foreignKey: 'userId',
func: (builder) => {
//refined search for relation
return builder.whereIn('id', [1,2,3])
.where('medical.contactId', 10)
.relation('contacts', models.users.RELATIONS.hasOne,'contactId', 'id');
}
}])
.all();
/**
* each results object will have an userContacts property with matching 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 by default. To prevent deep merging you can optionally pass third parameter as false.
Primary key ,updatedAt and createdAt values will be ignored even if provided
models.users.save(1, {
isAdmin : false
});This will update the data at the given index of the table with content provided for first matching index. The whole content will not be replaced but only the properties provided by default. To prevent deep merging you can optionally pass third parameter as false.
Primary key ,updatedAt and createdAt values will be ignored even if provided
models.users.saveIndex('indexName', 1, {
isAdmin : false
});This will update the data at the given index of the table with content provided for all matching index. The whole content will not be replaced but only the properties provided by default. To prevent deep merging you can optionally pass third parameter as false.
Primary key ,updatedAt and createdAt values will be ignored even if provided
models.users.saveIndex('indexName', 1, {
isAdmin : false
});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 by default. To prevent deep merging you can optionally pass third parameter as false.
Primary key ,updatedAt and createdAt values will be ignored even if provided
models.users.whereIndex('email', '[email protected]').where('isAdmin', true).update({
isAdmin : false
});This will delete the data at the given primary id of the table.
models.users.delete(3);This will delete all the matching records according to the query created
models.users.whereIndex('email', '[email protected]').where('isAdmin', true).destroy();This will delete all the matching records on the index only. You can optionally pass the third param to indicate that the index is a multi-entry index so that the search is correct.
models.users.deleteIndex('email', '[email protected]');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 it will return entire list of models in transaction mode. Transaction mode is required to be set.
Calling transaction.abort() will cause the transaction to fail.
import {Connector} from './dist/es2015/connection/connector.js';
import {TransactionModes} from './dist/es2015/models/model.interface.js';
let db = new Connector(config);
// Creating transaction through database
db.connect().then(async (models) => {
const {transaction, transactionModels} = db.openTransaction(TransactionModes.Write);
transactionModels.users.create({email: '[email protected]'});
transaction.abort();
});
// Creating transaction through models
db.connect().then(async (models) => {
const {transaction, transactionModels} = models.users.openTransaction(TransactionModes.Write);
transactionModels.users.create({email: '[email protected]'});
transaction.abort();
}); The count will return total number of records in the table against the result obtained by query builer object
const count = await models.users.whereIndex('email', '[email protected]').where('isAdmin', true).count();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
const average = await models.users.whereIndex('email', '[email protected]').where('isAdmin', true).average('id')
const nestedAverage = await models.users.whereIndex('userId', 10).where('firstName', 'Test').average('medical.contactId');Reduce process can be fired using the reduce function passed. If needed an default value can be passed as a second parameter
const result = await models.users.whereIndex('email', '[email protected]').where('isAdmin', true).reduce((result, carry) => carry + result.id, 0);
/**
* result with total number of records in the table
**/Sync actions allow syncing of new data and returns the updated record back. It is best choice to use when you want to map a record through an API or other service.
All Syncing actions can update the syncOn column if SyncColumn in migration of table schema is set to true. You can override the default column name using SyncColumnName attribute. column name using **
The sync action syncs at the primary key. By default it deep merges the data passed on but by providing the third parameter as false you can completely replace the data.
const updatedDataReceivedFromApi = {};
await models.users.sync(10, updatedDataReceivedFromApi);The sync action syncs at the primary key. By default it deep merges the data passed on but by providing the third parameter as false you can completely replace the data.
const updatedDataReceivedFromApi = {};
await models.users.sync(10, updatedDataReceivedFromApi);The syncIndex action syncs at the index value at first matching record. By default it deep merges the data passed on but by providing the third parameter as false you can completely replace the data.
const updatedDataReceivedFromApi = {};
await models.users.syncIndex('indexName', 10, updatedDataReceivedFromApi);The syncIndex action syncs at the index value for all matching record. By default it deep merges the data passed on but by providing the third parameter as false you can completely replace the data.
const updatedDataReceivedFromApi = {};
await models.users.syncAllIndex('indexName', 10, updatedDataReceivedFromApi);