@n1md7/indexeddb-promise

Indexed DB wrapper with promises

Supports all browsers that support IndexedDB.

Has TypeScript support with TS-class decorators.

Demo

• Basic Example01
• Advanced Example02

Installation

$ npm install @n1md7/indexeddb-promise

$ yarn add @n1md7/indexeddb-promise

Decorators

Typescript decorators are supported.

Prerequisite:

{
  "experimentalDecorators": true
}

@Table

Class decorator for IndexedDB table. It defines the structure of the table.

Params: options - object with following properties:

• name? - string, name of the table, default is the class name
• timestamps? - boolean, if true, createdAt and updatedAt columns will be added, default is false
• initialData? - array of objects to be inserted into the table on database creation, default is empty

@Table({ name: 'Users', timestamps: true })
class User {}

@Indexed

Property decorator for IndexedDB index. It defines whether the property is indexed.

Params: options - object with following properties:

• unique? - boolean, if true, the index will be unique, default is false
• multiEntry? - boolean, if true, the index will be multi-entry, default is true

@Table()
class User {
  @Indexed({ unique: true, multiEntry: false })
  username: string;
}

@PrimaryKey

Property decorator for IndexedDB primary key. It defines whether the property is primary key.

Params: options - object with following properties:

• autoIncrement? - boolean, if true, the primary key will be auto-incremented, default is true
• unique? - boolean, if true, the primary key will be unique, default is true

@Table()
class User {
  @PrimaryKey()
  id: number;

  @Index()
  name: string;
}

Methods

Method	Description	Params
selectAll	Get the data from database	None
select	Fetch data from database with filters	Object
insert	Add data into database	Object
openCursor	Get database cursor to iterate on demand	None
selectByIndex	Select database data by indexed properties (one)	String, String
selectByIndexAll	Select database data by indexed properties (many)	String, String
selectByPk	Select database record by primary key	String \ Number
updateByPk	Update database record by primary key	Number \ Number, Object
deleteByPk	Delete database record by primary key	String \ Number

- selectAll

Params

Gets all the data from database.

Return type: Promise<Object[]>

Accept params: None

Javascript example

model.selectAll().then((data) => data);
const data = await model.selectAll();

Typescript example

model.selectAll().then((data) => {
  // In TS {data} is inferred from the model
  return data;
});
const data = await model.selectAll();

- select

Params

Gets filtered data from database.

Return type: Promise<Object[]>

Accept params: options: Object

Object properties:

{
  where?: Object | Function;
  limit?: Number;
  orderByDESC?: Boolean;
  sortBy?: String | String[];
}

JS/TS example

const options = {
  limit: 10,
  where: (dataArray) => {
    return dataArray;
  },
  orderByDESC: true,
  sortBy: 'comments', // ['comments', 'date']
};
model.select(options).then((data) => data);
const data = await model.select(options);

@where property can filter out data like

const props = {
  where: (data) => data.filter((item) => item.username === 'admin'),
};

or it can be an object, which gets data with AND(&&) comparison

const props = {
  where: {
    username: 'admin',
    password: 'admin123',
  },
};

- selectByIndex

Params

Gets the data from database with the specified indexed property.

Return type: Promise<Object|{}>

Accept params: indexName: string, valueToMatch: string

JS/TS example

model.selectByIndex('username', 'admin').then((data) => data);
const data = await model.selectByIndex('username', 'admin');

- selectByIndexAll

Params

Gets the data from database with the specified indexed property.

Return type: Promise<Array<Object|{}>>

Accept params: indexName: string, valueToMatch: string

JS/TS example

model.selectByIndexAll('username', 'admin').then((data) => data);
const data = await model.selectByIndexAll('username', 'admin');

- selectByPk

Params

Gets the data from database with the specified primary key.

Return type: Promise<Object|{}>

Accept params: primaryKey: string \ number

JS/TS example

model.selectByPk(1).then((data) => data);
const data = await model.selectByPk('admin');

- updateByPk

Params

Updates the data in database with the specified primary key.

Return type: Promise<Object|{}>

Accept params: primaryKey: string \ number, Object

JS/TS example

model.updateByPk(123, { username: 'admin' });
const data = await model.updateByPk(123, { username: 'admin' });

- deleteByPk

Params

Deletes the data in database with the specified primary key.

Return type: Promise<String|Number>

Accept params: primaryKey: string \ number

JS/TS example

model.deleteByPk(123);
const data = await model.deleteByPk(123);

note Primary key is type sensitive. If it is saved as integer then should pass as integer and vice versa

Examples

Html 01

Once you add indexed-db.min.js in your document then you will be able to access IndexedDB variable globally which contains Model. They can be extracted as following

<html>
  <head>
    <title>IndexedDB app</title>
    <script defer src="indexed-db.min.js"></script>
  </head>
  <body>
    <script>
      const Database = IndexedDB.Database;
      // Your script here
    </script>
  </body>
</html>

Html 02

Basic usage of Model

<html>
  <head>
    <title>IndexedDB app</title>
    <script src="indexed-db.min.js"></script>
  </head>
  <body>
    <script>
      const db = new IndexedDB.Database({
        databaseVersion: 1,
        databaseName: 'MyNewDatabase',
        tables: [
          {
            name: 'MyNewTable',
            primaryKey: {
              name: 'id',
              autoIncrement: false,
              unique: true,
            },
            initData: [],
            indexes: {
              username: { unique: false, autoIncrement: false },
              password: { unique: false, autoIncrement: false },
            },
          },
        ],
      });
      await db.connect();
      // Add a new record
      const model = db.useModel('MyNewTable');
      model
        .insert({
          id: Math.random() * 10,
          username: 'admin',
          password: 'nimda',
          createdAt: new Date(),
          updatedAt: new Date(),
        })
        .then(function() {
          console.info('Yay, you have saved the data.');
        })
        .catch(function(error) {
          console.error(error);
        });

      // Get all results from the database
      model.selectAll().then(function(results) {
        console.log(...results);
      });
    </script>
  </body>
</html>

Javascript

const IndexedDB = require('@n1md7/indexeddb-promise');
const { Database } = IndexedDB;
// or
import { Database } from '@n1md7/indexeddb-promise';

TypeScript 01

import { Database } from '@n1md7/indexeddb-promise';

interface Users {
  id?: number;
  username: string;
  password: string;
}

enum Priority {
  LOW = 'LOW',
  MEDIUM = 'MEDIUM',
  HIGH = 'HIGH',
}

interface ToDos {
  id?: number;
  userId: number;
  title: string;
  description: string;
  done: boolean;
  priority: Priority;
}

const database = new Database({
  version: 1,
  name: 'Todo-list',
  tables: [
    {
      name: 'users',
      primaryKey: {
        name: 'id',
        autoIncrement: true,
        unique: true,
      },
      indexes: {
        username: {
          unique: false,
        },
      },
      timestamps: true,
    },
    {
      name: 'todos',
      primaryKey: {
        name: 'id',
        autoIncrement: true,
        unique: true,
      },
      indexes: {
        userId: {
          unique: true,
        },
      },
      timestamps: true,
    },
  ],
});

(async () => {
  await database.connect();
  const users = database.useModel<Users>('users');
  const user = await users.insert({
    username: 'admin',
    password: 'admin',
  });
  const todos = database.useModel<ToDos>('todos');
  await todos.insert({
    userId: user.id,
    title: 'Todo 1',
    description: 'Description 1',
    done: false,
    priority: Priority.LOW,
  });
})();

TypeScript decorators 02

import { Table, PrimaryKey, Indexed, Database } from '@n1md7/indexeddb-promise';

@Table({ name: '__Name__', timestamps: true })
class SomeTable {
  @PrimaryKey({ autoIncrement: true, unique: true })
  id: number;

  @Indexed({ unique: true, multiEntry: false })
  username: string;

  @Indexed({ unique: false })
  age: number;

  otherData: string;
}

const anotherDb = new Database({
  version: 1,
  name: 'Other-DB',
  tables: [SomeTable],
});
await anotherDb.connect();
const model = anotherDb.useModel(SomeTable);

(async () => {
  await model
    .insert({
      username: 'John',
      age: 20,
      otherData: 'Some data',
    })
    .catch((error) => console.error(error));

  model.selectAll().then((results) => {
    if (results) {
      results.forEach((result) => {
        // result is inferred to be SomeTable
        console.log(result.username);
      });
    }
  });
})();

TypeScript decorators 02

import { Database, Indexed, PrimaryKey, Table } from '@n1md7/indexeddb-promise';

@Table({ timestamps: true })
class User {
  @PrimaryKey({ autoIncrement: true, unique: true })
  id: number;

  @Indexed({ unique: true, multiEntry: false })
  username: string;

  @Indexed()
  password: string;

  toString() {
    return `#${this.id} ${this.username}`;
  }
}

@Table()
class Info {
  @PrimaryKey({ autoIncrement: true, unique: true })
  id: number;

  @Indexed()
  userId: number;

  name: {
    first: string,
    last: string,
  };

  age: number;

  occupation: string;

  toString() {
    return `${this.name.first} ${this.name.last} ${this.age} years old - ${this.occupation}`;
  }
}

const store = new Database({
  version: 1,
  name: 'Store',
  tables: [User, Info],
});

await store.connect();

const userModel = store.useModel(User);
const infoModel = store.useModel(Info);

(async () => {
  const savedUser = await userModel.insert({
    username: 'admin',
    password: 'admin',
  });

  await infoModel.insert({
    userId: savedUser.id,
    name: {
      first: 'John',
      last: 'Doe',
    },
    age: 27,
    occupation: 'Web Developer',
  });
})().catch(console.log);

(async () => {
  const user = await userModel.selectByIndex('username', 'admin');
  if (!user) throw new Error('User not found');

  const info = await infoModel.select({ where: { userId: user.id } });
  if (!info) throw new Error('Info not found');

  console.log(user.toString() + ' - ' + info.toString());
})().catch(console.log);