All of features follows IndexedDB mechanism. (w3c, MDN)

BoxDB

The class for IndexedDB and object stores management.

1

const db = new BoxDB(databaseName, version);

Parameters

  • databaseName: string
    • Name of the database
  • version: number
    • Version to open the database with

Properties

Methods

BoxDB.Types

The BoxDB.Types is a set of defined data types.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

BoxDB.Types;

// Properties
BoxDB.Types.BOOLEAN;
BoxDB.Types.NUMBER;
BoxDB.Types.STRING;
BoxDB.Types.DATE;
BoxDB.Types.ARRAY;
BoxDB.Types.OBJECT;
BoxDB.Types.REGEXP;
BoxDB.Types.FILE;
BoxDB.Types.BLOB;
BoxDB.Types.ANY;

Properties

  • BoxDB.Types.BOOLEAN: for Boolean value
  • BoxDB.Types.NUMBER: for Number value
  • BoxDB.Types.STRING: for String value
  • BoxDB.Types.DATE: for Date value
  • BoxDB.Types.ARRAY: for Array value
  • BoxDB.Types.OBJECT: for Object value
  • BoxDB.Types.REGEXP: for RegExp value
  • BoxDB.Types.FILE: for File value
  • BoxDB.Types.BLOB: for Blob value
  • BoxDB.Types.ANY: for any value (Skip type checking)

BoxDB.Range

The BoxDB.Range is a set of IDBKeyRange.

1
2
3
4
5

// Properties
BoxDB.Range.equal(x);
BoxDB.Range.upper(x[, open]);
BoxDB.Range.lower(x[, open]);
BoxDB.Range.bound(x, y[, lowerOpen, upperOpen]);

Methods

BoxDB.Order

The BoxDB.Order is a set of IDBCursor.direction.

1
2
3
4
5
6

BoxDB.Order;

BoxDB.Order.ASC; // 'next'
BoxDB.Order.ASC_UNIQUE; // 'nextunique'
BoxDB.Order.DESC; // 'prev'
BoxDB.Order.DESC_UNIQUE; // 'prevunique'
  • BoxDB.Order.ASC: for using IDBCursor with next direction
  • BoxDB.Order.ASC_UNIQUE: for using IDBCursor with nextunique direction
  • BoxDB.Order.DESC: for using IDBCursor with prev direction
  • BoxDB.Order.DESC_UNIQUE: for using IDBCursor with prevunique direction

BoxDB.interrupt()

The interrupt() method of the BoxDB interface returns a TransactionTask to abort transaction.

1
2
3
4

const abortTask = BoxDB.interrupt(); // TransactionTask

// Usage
db.transaction(Task_1, Task_2, abortTask, Task_3);

BoxDB.create()

The create() method of the BoxDB interface returns new Box.

1

db.create(name, schema[, options]);

Parameters

  • storeName: string
    • Name of the object store
  • schema: BoxSchema
    • Data schema of the data to store
  • options: BoxOption (optional)
    • Object store options

Return value

BoxDB.open()

The open() method of the BoxDB interface open IndexedDB and create/update/delete object store based on created boxes.

1

await db.open();

Return value

BoxDB.transaction()

The BoxDB.transaction() method takes an list of TransactionTask as an input, and perform tasks sequentially in one transaction.

Most important, if an error occurs during transaction, rolled back to the previous state.

1
2
3
4
5
6
7
8

// ACID guaranteed
db.transaction(
  task_1,
  task_2,
  task_3,
  ...,
  task_n
);

Parameters

Return value

  • Promise<void>

BoxSchema

The BoxSchema is an object that for data model. It’s includes field name with data type, and detailed options(key/index).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

interface BoxSchema {
  [field: string]: ConfiguredType | DataType;
}

// BoxDB.Types
export enum DataType {
  BOOLEAN = '1',
  NUMBER = '2',
  STRING = '3',
  DATE = '4',
  ARRAY = '5',
  OBJECT = '6',
  REGEXP = '7',
  FILE = '8',
  BLOB = '9',
  ANY = '0',
}

type ConfiguredType = {
  type: DataType;
  key?: boolean;
  index?: boolean;
  unique?: boolean;
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// Example
const schema = {
  // Method 1. Define field in detail
  name: {
    type: BoxDB.Types.STRING,
    index: true,
    unique: true,
  },
  // Method 2. Only type (No key, No index)
  age: BoxDB.Types.NUMBER,
};

Options

  • type: BoxDB.Types
    • Type of this property (used by type checking)
  • key: boolean (optional)
    • Set this property as in-line key
    • Can be set in-line key only once each object store
      • If you want change, create new box after drop ( re-create box with force option)
  • index: boolean (optional)
    • Create or delete index for this property
    • If you want search values on this field via index, should set to true
  • unique: boolean (optional)

BoxOption

Box creation options

1
2
3
4

interface BoxOption {
  autoIncrement?: boolean;
  force?: boolean;
}
  • autoIncrement: boolean (default: false)
  • force: boolean (default: false)
    • Force update when versionchange event
    • WARNING: This option will be drop exist object store before create

BoxData

Data of based on BoxSchema.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// Sample box
const User = db.create('user', {
  _id: {
    type: BoxDB.Types.NUMBER,
    key: true,
  }
  name: {
    type: BoxDB.Types.STRING,
    index: true,
  }
  age: BoxDB.Types.NUMBER,
  email: {
    type: BoxDB.Types.STRING,
    index: true,
    unique: true
  }
});

// BoxData will be inferenced like this
type BoxData = {
  _id: number
  name: string,
  age: number,
  email: string
}

OptionalBoxData

1

type OptionalBoxData<S extends Schema> = Partial<BoxData<S>>;

BoxRange

The BoxRange is an object for query with value or IDBKeyRange.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// Find age = 10 (should `age` field is defined to index)
const range_1 = {
  value: 10,
  index: 'age',
};

// Find in-line-key(_id) < 5
const range_2 = {
  value: BoxDB.Range.lower(5),
};

Box.find(range_1);
Box.find(range_2);

Properties

  • value: BoxDB.Range or IDBValidKey value
  • index: string (optional)
    • Indexed field name in schema (index: true option)
    • If you don’t serve index name, follows in-line key as default.

FilterFunction

The FilterFunction is a function to evaluate each record. This function receives BoxData and returns a boolean value.

1
2
3
4
5

const predicate_1 = (data) => data.age === 10;
const predicate_2 = (data) => !data.name === 'UNKNOWN';
const predicate_3 = (data) => true;

Box.find(null, predicate_1, predicate_2, predicate_3);

Box

A Box is an abstraction that represents a object store. and also can generate data in a defined form (schema).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

const User = db.create('user', {
  _id: {
    type: BoxDB.Types.NUMBER,
    key: true,
  }
  name: {
    type: BoxDB.Types.STRING,
    index: true,
  }
  age: BoxDB.Types.NUMBER,
  email: BoxDB.Types.STRING
});

// (1) Create empty data
const u1 = new User();
u1.name // string

// (2) Create data with initial data
const u2 = new User({
  _id: 0,
  name: 'Jack',
  age: 12
});

// Model methods for single transaction
User.get(key);
User.put(value, key);
User.delete(key);
User.count();
User.clear();
User.find(range, ...predicate).get(order, limit);
User.find(range, ...predicate).update(updateValue);
User.find(range, ...predicate).delete();

// Returns TransactionTask for BoxDB.transaction()
User.$get(key);
User.$put(key, value);
User.$delete(key);
User.$find(range, ...predicate).update(updateValue);
User.$find(range, ...predicate).delete();

Parameters

  • storeName: string
    • Name of the object store
  • schema: BoxSchema
    • Data schema of the data to store
  • options: BoxOption (optional)
    • Object store options

Methods

  • Box.getName(): Returns object store name
  • Box.getVersion(): Returns target database version
  • Box.add(value, key): Add record to object store
  • Box.get(key): Get record from object store
  • Box.put(value[, key]): Put record to object store
  • Box.delete(key): Delete record from object store
  • Box.count(key): Get records count
  • Box.clear(): Drop the object store
  • Box.find(range, …predicate): Returns BoxCursorHandler, Transaction by IDBCursor
    • find().get(): Get records
    • find().update(updateValue): Update records
    • find().delete(): Delete records
  • Box.$add(): Returns TransactionTask that add record.
  • Box.$put(): Returns TransactionTask that update record.
  • Box.$delete(): Returns TransactionTask that delete record.
  • Box.$find(): Returns TransactionCursorHandler.

Box.getName()

The getName() methods returns current object store name

1

Box.getName();

Return value

  • string

Box.getVersion()

The getVersion() methods returns version of database

1

Box.getVersion();

Return value

  • number

Box.add()

The add() method of the Box interface stores the data in the target object store.

1
2

Box.add(value[, key]);
Box.add({ id: 1, name: 'Tom', age: 15 });

Parameters

  • value: BoxData
    • The data to be stored.
  • key: IDBValidKey (optional)
    • The key to use to identify the record. (default: null)
    • Using this parameter when box defined with autoIncrement option.

Return value

  • Promise<IDBValidKey>
    • Returns added record’s key (both in/out-of-line key)

Box.get()

The get() method of the Box interface returns an specific record data from object store

1

Box.get(key);

Parameters

  • key: IDBValidKey
    • The key or key range that identifies the record to be retrieved.

Return value

Box.put()

The put() method of the Box interface updates a given record in a database, or inserts a new record if the given item does not already exist.

1

Box.put(value[, key]);

Parameters

  • value: BoxData
    • The data you wish to update.
  • key: IDBValidKey (optional)
    • The key that identifies the record to be updated.
    • Using this parameter when box defined with autoIncrement option.

Return value

  • Promise<void>

Box.delete()

The delete() method of the Box interface deletes target record

1

Box.delete(key);

Parameters

  • key: IDBValidKey
    • The key that identifies the record to be deleted.

Return value

  • Promise<void>

Box.find()

The find() method of the Box interface selects all records that are retrieved by BoxRange and passed the provided FilterFunction.

Parameters

Return value

Box.count()

The BoxMode.count() method returns all records count in object store.

1

Box.count();

Return value

  • Promise<number>

Box.clear()

The BoxMode.clear() method clears all of data in object store.

1

Box.clear();

Return value

  • Promise<void>

Box.$add()

The $add() of the Box interface returns TransactionTask to add record.

$ Prefixed methods returns TransactionTask

1
2

Box.$add(value[, key]);
Box.$add({ id: 2, name: 'Carl', age: 12 });

Parameters

  • value: BoxData
    • The data to be stored.
  • key: IDBValidKey (optional)
    • The key to use to identify the record. (default: null)
    • Using this parameter when box defined with autoIncrement option.

Return value

Box.$put()

The $put() of the Box interface returns a TransactionTask to update or insert record.

1

Box.$put(value[, key]);

Parameters

  • value: BoxData
    • The data you wish to update.
  • key: IDBValidKey (optional)
    • The key that identifies the record to be updated.
    • Using this parameter when box defined with autoIncrement option.

Return value

Box.$delete()

The $delete() of the Box interface returns a TransactionTask to delete record.

1

Box.$delete(key);

Parameters

  • key: IDBValidKey (optional)
    • The key that identifies the record to be deleted.
    • Using this parameter when box defined with autoIncrement option.

Return value

Box.$find()

The find() method of the Box interface selects all records that are retrieved by BoxRange and passed the provided FilterFunction.

Different from find(), $find() returns TransactionCursorHandler.

1

Box.$find(range, ...predicate);

Parameters

Return value

BoxCursorHandler

The BoxCursorHandler interface uses IDBCursor to control data.

1
2
3

Box.find(...).get(order, limit);
Box.find(...).update(updateValue);
Box.find(...).delete();

Methods

BoxCursorHandler.get()

The get() method of the BoxCursorHandler interface returns a filtered list of record data from object store.

1

Box.find(...).get(order, limit);

Parameters

  • order: BoxDB.Order (optional)
    • Default: BoxDB.Order.ASC
    • Uses in open IDBCursor
    • Ordering based on specified index (default: in-line key)
  • limit: number (optional)
    • Default: unlimited

Return value

BoxCursorHandler.update()

The update() method of the BoxCursorHandler interface updates filtered records data from object store.

1

Box.find(...).update(updateValue);

Parameters

Return value

  • Promise<void>

BoxCursorHandler.delete()

The delete() method of the BoxCursorHandler interface deletes filtered records data from object store.

1

Box.find(...).delete();

Return value

  • Promise<void>

TransactionCursorHandler

1
2

Box.$find(...).update(updateValue);
Box.$find(...).delete();

Methods

TransactionCursorHandler.update()

The TransactionCursorHandler.update() interface behaves the same as BoxCursorHandler.update(), but returns TransactionTask.

1
2

// Do nothing (only returns TransactionTask)
const task = Box.$find(...).update(updateValue);

Parameters

Return value

TransactionCursorHandler.delete()

The TransactionCursorHandler.delete() interface behaves the same as BoxCursorHandler.delete(), but returns TransactionTask.

1
2

// Do nothing (only returns TransactionTask)
const task_1 = Box.$find(...).delete();

Return value

TransactionTask

The TransactionTask is a value object for using in transaction(). It can be created with $ prefixed methods like $get(), $delete().