# LightKV : Light transaction Key/Value database

This module is a transactional (ACID) Key / Value database. This database consumes a lot of memory cache when in use, it is recommended not to exceed 100,000 records.

User can use the following code to import the LightKV module.

var LightKV = require('lightkv');

# Support

The following shows LightKV module APIs available for each permissions.

# LightKV Class

# new LightKV(fileName[, flags[, type]])

• fileName {String} Database file name.
• flags {String} Open flags. default: 'c+'.
• type {Integer} Database default value type. default: LightKV.BUFFER.
• Returns: {Object} Database object.

Open a database using the specified method. flags can be:

When fileName is ':memory:', it means creating an anonymous in-memory database.

type can choose from the following type:

• LightKV.STRING {Integer} The data stored in the database is a String.
• LightKV.OBJECT {Integer} The data stored in the database is a Object.
• LightKV.BUFFER {Integer} The data stored in the database is a Buffer.

Open or create a new LightKV database. If the type parameter exists, the kv.get() function will use this type to get the corresponding content by default.

# Example

var kv = new LightKV('xxx', 'c+', LightKV.OBJECT);

# LightKV Object

# kv.close()

Close the database, the iterator that is in use after the database is closed will no longer be able to use.

# kv.has(key)

• key {String} | {Number} Keyword.
• Returns: {Boolean} Whether the value of the specified key exists.

Get whether the value of the specified key exists.

# kv.set(key, value)

• key {String} | {Number} Keyword.
• value {String} | {Object} | {Buffer} Value.

Insert or rewrite a record. If there is value with the same key before, the previous value will be overwritten.

# kv.get(key[, type])

• key {String} | {Number} Keyword.
• type {Integer} Database default value type. default: used type when constructing this object.
• Returns: {String} | {Object} | {Buffer} Value. If the value specified by key does not exist, return undefined.

# Example

kv.set('k1', { foo: 'bar1' });
kv.set('k2', { foo: 'bar2' });

if (kv.has('k1')) {
  console.log(kv.get('k1').foo);
}
if (kv.has('k2')) {
  console.log(kv.get('k2').foo);
}

# kv.delete(key)

• key {String} | {Number} Keyword.
• Returns: {Boolean} Return true if there is a record and deleted, otherwise return false. EdgerOS 1.4.2 and later versions add this return value.

Delete a specified record by key.

# kv.begin()

Begin a write-transaction on this database. If a write-transaction has already been opened, this function is a no-op.

When the write-transaction is not opened, all set() operations will be automatically commit. When the write-transaction is opened, all set() will be commit at commit() or discarded at rollback().

# kv.commit()

Commit all changes to the database.

# kv.rollback()

Rollback a write-transaction on this database. If a write-transaction is open, then all changes made within the transaction are reverted and the current write-transaction is closed.

# Example

kv.begin();
kv.set('hanhui', { foo: 'bar1' });
kv.set('liping', { foo: 'bar2' });
kv.commit(); // Commit hanhui and liping key's value

kv.begin();
kv.set('hanhui', { foo: 'bar3' });
kv.set('liping', { foo: 'bar4' });
kv.rollback(); // Reverted.

# kv.keys()

• Returns: {Iterator} Iterator object.

The keys() method returns a new Iterator object that contains the keys for each element in this database.

# Example

var kv = new LightKV('xxx', 'c+', LightKV.STRING);

kv.set('0', 'foo');
kv.set('1', 'bar');

const it = kv.keys();

console.log(it.next().value);
// expected output: "0"

console.log(it.next().value);
// expected output: "1"

# kv.values()

• Returns: {Iterator} Iterator object.

The values() method returns a new Iterator object that contains the values for each element in this database.

# Example

var kv = new LightKV('xxx', 'c+', LightKV.STRING);

kv.set('0', 'foo');
kv.set('1', 'bar');

const it = kv.values();

console.log(it.next().value);
// expected output: "foo"

console.log(it.next().value);
// expected output: "bar"

# kv.entries()

• Returns: {Iterator} Iterator object.

The entries() method returns a new Iterator object that contains the [key, value] pairs for each element in this database. In this particular case, this iterator object is also an iterable, so the for-of loop can be used. When the protocol [Symbol.iterator] is used, it returns a function that, when invoked, returns this iterator itself.

# Example

var kv = new LightKV('xxx', 'c+', LightKV.STRING);

kv.set('0', 'foo');
kv.set('1', 'bar');

const it = kv.entries();

console.log(it.next().value);
// expected output: ['0', "foo"]

console.log(it.next().value);
// expected output: ['1', "bar"]

# kv[Symbol.iterator]()

• Returns: {Iterator} Iterator object.

The [Symbol.iterator] method returns a new Iterator object that contains the values for each element in this database.

# Example

var kv = new LightKV('xxx', 'c+', LightKV.STRING);

kv.set('0', 'foo');
kv.set('1', 'bar');

for (var value of kv) {
  console.log(value);
}
// expected output: "foo", "bar"

# kv.forEach(callback[, thisArg])

• callback {Function} Iterative callback function.
  • value {String} | {Object} | {Buffer} Value.
  • key {String} | {Number} Keyword.
  • kv {Object} This database object.
• thisArg {Object} The this object bound when the callback function is called. default: no binding.

Traversing the database, similar to other objects *.forEach() calls.

# kv.toMap()

• Returns: {Map} Map object.

Store all the contents of the database in a Map object.

# kv.fillin(map)

• map {Map} Map object.

Fill all the contents of the map object into the database.