# index-db-orm

> a library for easy connection and work with client-side data base

Latest version **0.9.0** (published 2022-07-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install index-db-orm
pnpm add index-db-orm
yarn add index-db-orm
bun add index-db-orm
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.9.0 |
| Published | 2022-07-15 |
| First published | 2022-07-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 633.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 21 |
| Author | Amin Adineh Ahari |
| Maintainers | a.adine |
| Keywords | index db, orm, js, promise |

## Links

- npm: https://www.npmjs.com/package/index-db-orm
- Repository: https://github.com/AminAdinehAhari/index-db-orm
- Homepage: https://github.com/AminAdinehAhari/index-db-orm#readme
- Issues: https://github.com/AminAdinehAhari/index-db-orm/issues
- npm.io page: https://npm.io/package/index-db-orm

## Dependencies (2)

- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.17.8
- [fake-indexeddb](https://npm.io/package/fake-indexeddb.md) ^3.1.7

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.9.0 (latest) — 2022-07-15
- 0.1.3 — 2022-07-07
- 0.1.1 — 2022-07-06
- 0.1.0 — 2022-07-06

## README

# index-db-orm

<!-- BEGIN LATEST BADGE -->
[![npm](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AminAdinehAhari/0be9f6ac374b7c312b8f08c2322100ec/raw/index-db-orm_npm_badge_main_v0.9.0.json)](https://www.npmjs.com/package/index-db-orm/v/0.9.0) [![download](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AminAdinehAhari/0be9f6ac374b7c312b8f08c2322100ec/raw/index-db-orm_download_badge_main_v0.9.0.json)](https://unpkg.com/index-db-orm@0.9.0/dist/indexDbOrm.js) [![download compress](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AminAdinehAhari/0be9f6ac374b7c312b8f08c2322100ec/raw/index-db-orm_download_min_badge_main_v0.9.0.json)](https://unpkg.com/index-db-orm@0.9.0/dist/indexDbOrm.min.js) [![code coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AminAdinehAhari/0be9f6ac374b7c312b8f08c2322100ec/raw/index-db-orm_test_coverage_badge_main_v0.9.0.json)](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AminAdinehAhari/0be9f6ac374b7c312b8f08c2322100ec/raw/index-db-orm_test_coverage_badge_main_v0.9.0.json) [![build status](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AminAdinehAhari/0be9f6ac374b7c312b8f08c2322100ec/raw/index-db-orm_ci_badge_main_v0.9.0.json)](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AminAdinehAhari/0be9f6ac374b7c312b8f08c2322100ec/raw/index-db-orm_ci_badge_main_v0.9.0.json) [![version](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AminAdinehAhari/0be9f6ac374b7c312b8f08c2322100ec/raw/index-db-orm_version_badge_main_v0.9.0.json)](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AminAdinehAhari/0be9f6ac374b7c312b8f08c2322100ec/raw/index-db-orm_version_badge_main_v0.9.0.json) [![product build](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AminAdinehAhari/0be9f6ac374b7c312b8f08c2322100ec/raw/index-db-orm_build_badge_main_v0.9.0.json)](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AminAdinehAhari/0be9f6ac374b7c312b8f08c2322100ec/raw/index-db-orm_build_badge_main_v0.9.0.json) [![develop build](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AminAdinehAhari/0be9f6ac374b7c312b8f08c2322100ec/raw/index-db-orm_develop_badge_main_v0.9.0.json)](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AminAdinehAhari/0be9f6ac374b7c312b8f08c2322100ec/raw/index-db-orm_develop_badge_main_v0.9.0.json) [![license](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AminAdinehAhari/0be9f6ac374b7c312b8f08c2322100ec/raw/index-db-orm_license_badge_main_v0.9.0.json)](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/AminAdinehAhari/0be9f6ac374b7c312b8f08c2322100ec/raw/index-db-orm_license_badge_main_v0.9.0.json)
<!-- END LATEST BADGE -->

Promise based using indexDb for the browser.


## Features

- Supports the [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) API
- Supports test mode
- Simple syntax

## Browser Support

![Chrome](https://raw.githubusercontent.com/alrra/browser-logos/main/src/chrome/chrome_48x48.png) | ![Firefox](https://raw.githubusercontent.com/alrra/browser-logos/main/src/firefox/firefox_48x48.png) | ![Safari](https://raw.githubusercontent.com/alrra/browser-logos/main/src/safari/safari_48x48.png) | ![Opera](https://raw.githubusercontent.com/alrra/browser-logos/main/src/opera/opera_48x48.png) | ![Edge](https://raw.githubusercontent.com/alrra/browser-logos/main/src/edge/edge_48x48.png) | ![IE](https://raw.githubusercontent.com/alrra/browser-logos/master/src/archive/internet-explorer_9-11/internet-explorer_9-11_48x48.png) |
--- | --- | --- | --- | --- | --- |
Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | No |


## Installing

Using npm:

```bash
$ npm install index-db-orm
```

Using yarn:

```bash
$ yarn add index-db-orm
```

## Example

[DEMO EXAMPLE](https://aminadinehahari.github.io/index-db-orm/)

### note: CommonJS usage

```js
const ormClass = require('index-db-orm').default;

```
build dataBase and stores

```js
const ormClass = require('index-db-orm').default;

const orm = new ormClass();

orm.addDB({
        name: 'database1',
        stores: [
            {
                name: 'db1store1',
                indexes: [
                    {name: 'name', keyPath: 'name', option: {unique: false}},
                    {name: 'key', keyPath: 'key', option: {unique: true}},
                    {name: 'multiIndex', keyPath: ['name', 'key'], option: {unique: false}},
                ]
            },
            {
                name: 'db1store2',
                indexes: [
                    {name: 'name', keyPath: 'name', option: {unique: false}},
                ]
            },
        ]
    })
    .addDB({
        name: 'database2',
        stores: [
            {name: 'db2store1', indexes: []},
            {name: 'db2store2', keyPath: 'userId', indexes: []},
        ]
    })
    .build()
    .then(function (res) {
        console.log('on ready');
    })
    .catch(function (err) {
        console.error(err);
    });

    // Want to use async/await? Add the `async` keyword to your outer function/method.

    async function build() {
        try{
            const buildRes = orm
            .addDB({ ... })
            // .....
            .build()

             console.log('on ready');
        }catch(error){
            console.error(err);
        }
    }

```

> **NOTE:** `async/await` is part of ECMAScript 2017 and is not supported in Internet
> Explorer and older browsers, so use with caution.

after build, can use crud operator.

Performing a `Insert` request

```js
orm.insert('database1', 'db1store1', {
    'name': 'test name',
    'key': 'key 1',
    // add other key, value 
}).then(function (res) {
    console.log('on insert complete');
})
.catch(function (err) {
    console.error(err);
});

// Want to use directive mode
// orm.<db name>.<store name>.insert(data) <promise>

orm.database1.db1store1.insert({
    'name': 'test name',
    'key': 'key 1',
    // add other key, value 
}).then(function (res) {
    console.log('on insert complete');
})
.catch(function (err) {
    console.error(err);
});
```

Performing a `Update` request

```js
orm.update('database1', 'db1store1', {
    '__pk': '<row key>',
    'name': 'test name',
    'key': 'key 1',
    // add other key, value 
}).then(function (res) {
    console.log('on update complete');
})
.catch(function (err) {
    console.error(err);
});

// Want to use directive mode
// orm.<db name>.<store name>.update(data) <promise>

orm.database1.db1store1.update({
    '__pk': '<row key>',
    'name': 'test name',
    'key': 'key 1',
    // add other key, value 
}).then(function (res) {
    console.log('on update complete');
})
.catch(function (err) {
    console.error(err);
});
```

Performing a `Delete` request

```js
orm.delete('database1', 'db1store1', '<row key>')
.then(function (res) {
    console.log('on delete complete');
})
.catch(function (err) {
    console.error(err);
});

// Want to use directive mode
// orm.<db name>.<store name>.delete(pk) <promise>

orm.database1.db1store1.delete('<row key>')
.then(function (res) {
    console.log('on delete complete');
})
.catch(function (err) {
    console.error(err);
});
```

Performing a `Find` request

```js
orm.find('database1', 'db1store1','<row key>')
.then(function (res) {
    console.log('on find row complete');
})
.catch(function (err) {
    console.error(err);
});

// Want to use directive mode
// orm.<db name>.<store name>.find(<row key>) <promise>

orm.database1.db1store1.find('<row key>')
.then(function (res) {
    console.log('on find row complete');
})
.catch(function (err) {
    console.error(err);
});

```

Performing a `Select all` request

```js
orm.all('database1', 'db1store1')
.then(function (res) {
    console.log('on all select complete');
})
.catch(function (err) {
    console.error(err);
});

// Want to use directive mode
// orm.<db name>.<store name>.all() <promise>

orm.database1.db1store1.all()
.then(function (res) {
    console.log('on all select complete');
})
.catch(function (err) {
    console.error(err);
});

```

Performing a `Select as paginate` request

```js
orm.paginate('database1', 'db1store1',1,10)
.then(function (res) {
    console.log('on paginate select complete');
})
.catch(function (err) {
    console.error(err);
});

// Want to use directive mode
// orm.<db name>.<store name>.paginate(<?page number>,<?limit row>) <promise>

orm.database1.db1store1.paginate(1,10)
.then(function (res) {
    console.log('on paginate select complete');
})
.catch(function (err) {
    console.error(err);
});

```

Performing a `Where` request

```js
orm.where('database1', 'db1store1','name','=','test name').all()
.then(function (res) {
    console.log('on where complete select');
})
.catch(function (err) {
    console.error(err);
});

// Want to use directive mode
// orm.<db name>.<store name>.paginate(<?page number>,<?limit row>) <promise>

orm.database1.db1store1.where('name','=','test name').all()
.then(function (res) {
    console.log('on where complete select');
})
.catch(function (err) {
    console.error(err);
});

```

As can use `more where` request too

```js
orm.where('database1', 'db1store1','name','=','test name')
    .where('database1', 'db1store1','key','=','key 1')
    .all()
    .then(function (res) {
        console.log('on where complete select');
    })
    .catch(function (err) {
        console.error(err);
    });

// Want to use directive mode
// orm.<db name>.<store name>.paginate(<?page number>,<?limit row>) <promise>

orm.database1.db1store1.where('name','=','test name')
    .where('database1', 'db1store1','key','=','key 1').all()
    .then(function (res) {
        console.log('on where complete select');
    })
    .catch(function (err) {
        console.error(err);
    });

```

## ORM API

### Use
For use orm, must be create a instance of class.
instance of class as two mode `product` (default) , `test`.
in test mode using of [fake-indexeddb](https://www.npmjs.com/package/fake-indexeddb) for test.

```js
const ormClass = require('index-db-orm').default;

const orm = new ormClass('product'); // product mode
const orm = new ormClass('test'); // test mode
```

### Build DataBase and Stores
After created instance, must be mapping of database and stores to instance.

```js
orm
    .addDB({
        name: 'dbName', // {string} dbName
        stores: [
            {
                name: "storeName1", // {string} storeName
                indexes: [
                    {
                        name: 'indexName',  // {string} indexName 
                        keyPath: 'keyPath', // {string, array<string>} keyPath 
                        option: {
                            unique: false
                        } // {Object}  indexOption , default {unique: false}
                    },
                    // add more index
                ]
            },
            // add more store
        ],
        onRebuild: function(){

        }, // {function} onRebuild , event run when database need updated
    })
    // add more DB
    .build()
    .then((response)=>{
        console.log('build db complete!!!')
    })
    .catch((error)=>{
        console.error('build error')
    })
```

also you can use `onRebuild` as 

```js
orm.onRebuildDB("dataBaseName", function () {
  console.log("rebuild event )))))))))))))))))))))");
})
```

### DataBase API

| method name           | input           | output                | description |
| :------------         |   :---          | :--------              | :--------   |
| `getAllDatabases`     |                 | `promise <array>`      | return all database list        |
| `getDataBase`         | `{string} name` | `promise <object>`     | return a database info by name  |
| `getDataBaseVersion`  | `{string} name` | `promise <number>`     | return a database version by name  |
| `removeAllDataBase`   |                 | `promise <orm>`        | remove all database            |
| `removeDataBase`      | `{string} name` | `promise <orm>`        | remvoe database by name            |
| `onRebuildDB`         | `{string} name` , `{function} event`     | `orm`        | set event, active this event when database will updated            |

### Store API

| method name      | input                                    | output               | description |
| :------------    |   :---                                   | :--------              | :--------   |
| `clearStore`     | `{string} dbName` , `{string} storeName` | `promise <boolean>`    | clear store by name   |
| `insert`         | `{string} dbName` , `{string} storeName` , `{object} data` | `promise <object>`    | insert data to store, `promise <object>` include __pk key   |
| `update`         | `{string} dbName` , `{string} storeName` , `{object} data` | `promise <object>`    | store update, `data` must include __pk key   |
| `delete`         | `{string} dbName` , `{string} storeName` , `{string,number} __pk` | `promise <boolean>`    | delete data from store   |
| `find`           | `{string} dbName` , `{string} storeName` , `{string,number,array} vlaue` , `?{string} searchPk(=null)` | `promise <boolean>`    | find row in store by pk. `searchPk` must be include one of store indexes name   |
| `all`            | `{string} dbName` , `{string} storeName` | `promise <array>`    |  return all row as array  |
| `paginate`       | `{string} dbName` , `{string} storeName` , `?{number} page (= 1)` , `?{number} total (= 20)` | `promise <array>`    |  return row as paginate mode  |
| `count`          | `{string} dbName` , `{string} storeName` , `?{object} query (= null)` | `promise <numer>`    |  return count row  |
| `where`          | `{string} dbName` , `{string} storeName` , `{string} conditionIndex` , `{string} conditionOperator` , `{number, string, array} conditionValues` | `object{build()}`    |  return all row by condition. `conditionIndex` must be include one of store indexes name. `conditionOperator` must include one of `=` , `>` , `>=` , `<=` , `<` ,  `between` , `betweenInclude` , `like` , `%like` , `like%` , `%like%` , `match` |
| `where().all()`| `{string} operation` | `promise <array>`  | `operation` include one of `and` , `or` |
| `onInsert`       | `{string} dbName` , `{string} storeName` ,  `{function} event`  | `{string, number} eventKey`    | set event, active this event when insert data to store   |
| `onUpdate`       | `{string} dbName` , `{string} storeName` ,  `{function} event`  | `{string, number} eventKey`    | set event, active this event when update row of store   |
| `onDelete`       | `{string} dbName` , `{string} storeName` ,  `{function} event`  | `{string, number} eventKey`    | set event, active this event when delete row from store   |
| `unbindInsert`   | `{string} dbName` , `{string} storeName` ,  `{string, number} keyEvent`  | `{object} orm`    | remove `onInsert` event    |
| `unbindUpdate`   | `{string} dbName` , `{string} storeName` ,  `{string, number} keyEvent`  | `{object} orm`    | remove `onUpdate` event    |
| `unbindDelete`   | `{string} dbName` , `{string} storeName` ,  `{string, number} keyEvent`  | `{object} orm`    | remove `onDelete` event    |
| `unbindAllInsert`| `{string} dbName` , `{string} storeName`   | `{object} orm`    | remove `onInsert` all event    |
| `unbindAllUpdate`| `{string} dbName` , `{string} storeName`   | `{object} orm`    | remove `onUpdate` all event    |
| `unbindAllDelete`| `{string} dbName` , `{string} storeName`   | `{object} orm`    | remove `onDelete` all event    |


### Direct Call Store API
| directive Call   | method    |
| :------------    | :---      |
| `orm.<dbName>.<storeName>`.`insert(data)` | `orm.insert(dbName,storeName,data)` |
| `orm.<dbName>.<storeName>`.`update(data)` | `orm.update(dbName,storeName,data)` |
| `orm.<dbName>.<storeName>`.`delete(__pk)` | `orm.delete(dbName,storeName,__pk)` |
| `orm.<dbName>.<storeName>`.`find(value, searchPk)` | `orm.find(dbName,storeName,value, searchPk)` |
| `orm.<dbName>.<storeName>`.`all()` | `orm.all(dbName,storeName)` |
| `orm.<dbName>.<storeName>`.`count()` | `orm.count(dbName,storeName)` |
| `orm.<dbName>.<storeName>`.`paginate(page, total)` | `orm.paginate(dbName,storeName,page, total)` |
| `orm.<dbName>.<storeName>`.`orm.where(conditionIndex,conditionOperator,conditionValues)` | `orm.where(dbName,storeName,conditionIndex,conditionOperator,conditionValues)` |
| `orm.<dbName>.<storeName>`.`orm.where..where...all(operation)` | `orm.where()..where()...build(operation)` |
| `orm.<dbName>.<storeName>`.`onInsert(event)` | `orm.onInsert(dbName,storeName,event)` |
| `orm.<dbName>.<storeName>`.`onUpdate(event)` | `orm.onUpdate(dbName,storeName,event)` |
| `orm.<dbName>.<storeName>`.`onDelete(event)` | `orm.onDelete(dbName,storeName,event)` |
| `orm.<dbName>.<storeName>`.`unbindInsert(keyEvent)` | `orm.unbindInsert(dbName,storeName,keyEvent)` |
| `orm.<dbName>.<storeName>`.`unbindUpdate(keyEvent)` | `orm.unbindUpdate(dbName,storeName,keyEvent)` |
| `orm.<dbName>.<storeName>`.`unbindDelete(keyEvent)` | `orm.unbindDelete(dbName,storeName,keyEvent)` |
| `orm.<dbName>.<storeName>`.`unbindAllInsert()` | `orm.unbindAllInsert(dbName,storeName)` |
| `orm.<dbName>.<storeName>`.`unbindAllUpdate()` | `orm.unbindAllUpdate(dbName,storeName)` |
| `orm.<dbName>.<storeName>`.`unbindAllDelete()` | `orm.unbindAllDelete(dbName,storeName)` |

## Promises

index-db-orm depends on a native ES6 Promise implementation to be [supported](https://caniuse.com/promises).
If your environment doesn't support ES6 Promises, you can [polyfill](https://github.com/jakearchibald/es6-promise).


## License

[MIT](LICENSE)

---
_Source: https://npm.io/package/index-db-orm · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._