indexeddb-orm
v4.0.0-alpha.3
Published
A promise based ORM wrapper for indexedDB
Downloads
53
Maintainers
maxgauravReadme
IndexedDB ORM
An indexedDB wrapper for accessing indexedDB as a promise base api implementation.
Older Version
For older version please go to branch 2.1.0
Website
maxgaurav.github.io/indexeddb-orm
Examples coming soon to the website.
Changes/Updates/Deprecation
Read ChangeLog
Table of Contents
- Features
- Installation
- Usage
- ORM
- Query Building
Features
- 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
Installation
npm install indexeddb-orm --save
yarn add indexeddb-ormUsage
- A 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/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);ORM
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/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([...]).with(['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'
}]
}]
}]
};Query Building
Insertion of data
Create
- 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]'
});
}) Create Multiple
- 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']
}]);
}) Searching of the data
Find
- 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);
});FindOrFail
- 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);
});FindOrCreate
- 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);
});First
- 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();
});FirstOrFail
- 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();
});FirstOrCreate
- 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);
});FindIndex
- 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);
});FindIndexOrFail
- 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();
});FindIndexOrCreate
- 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();
});FindAllIndex
- 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');
});All
- 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();
});Index Searching
- 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
whereIndex
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();
});whereIndexIn
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();
});whereMultiIndexIn
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();
});whereIndexGte
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();
});whereIndexGt
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();
});whereIndexLte
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();
});whereIndexLt
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();
});whereIndexBetween
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.whereIndexBetween('email','[email protected]', '[email protected]').first();
const contacts = await models.userContacts.whereIndexBetween('userId',20, 52).all();
});Non Index Searching
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.
where
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();
});Nested Attributes
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();
});whereIn
To search for result in a multiple search values for column then pass array as a value for the search
db.connect().then(async (models) => {
const contacts = await models.userContacts.whereIn('userId',[20, 52]).where('medical.contactId', 10).all();
});whereInArray
To search for result in a multiple search values for column which contains array of values then pass array as a value for the search
db.connect().then(async (models) => {
const contacts = await models.userContacts.whereIn('phones',[20, 52]).where('medical.contactId', 10).all();
});gte
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();
});gt
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();
});lte
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();
});lt
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();
});between
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();
});Relations
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.
Adding Normal Relations
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
}, ...])Has One
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/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
*/Has Many
The has many relation maps single column of primary model containing the id reference of other table/object store matching id.
Example a user having multiple contacts. The user model query with all contacts associated.
import {RelationTypes} from './dist/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
**/Has Many Multi Entry
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 multi entry index.
import {RelationTypes} from './dist/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.
*/Has Many Through Multi Entry
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 many multi entry where child has an index of type multi entry.
Example: A address table/object store having relation to multiple users using userIds as array with multi entry index.
import {RelationTypes} from './dist/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.
*/Custom Relation Builder
- Using the with you can load custom relations defined in the ORM class.
import {Model} from './dist/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)
.with(['userProfile'])
.all();
/**
* each results object will have an userProfile property with matching result with users table
**/ Nested Relations
- You can also call for nested relation to nth level using the secondary query builder of the relation
import {RelationTypes} from './dist/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
**/ Updating of records
Save
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
});Save Index
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
});Save All Index
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
});update
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
});Deletions in table
delete
This will delete the data at the given primary id of the table.
models.users.delete(3);destroy
This will delete all the matching records according to the query created
models.users.whereIndex('email', '[email protected]').where('isAdmin', true).destroy();deleteIndex
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]');Transactional Actions
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, 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.
Usage
import {Connector} from './dist/connection/connector.js';
import {TransactionModes} from './dist/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();
}); Aggregations
Count
The count will return total number of records in the table against the result obtained by query builder object
const count = await models.users.whereIndex('email', '[email protected]').where('isAdmin', true).count();Average
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
Reduce process can be fired using the reduce function passed. If needed a 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
**/
Syncing
Sync actions allow syncing of new data and returns the updated record back. It is the best choice 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 **
Sync
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);sync
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);Sync Index
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);Sync All Index
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);