# NDBM : UNIX ndbm Key / Value database

This module is the encapsulation of the UNIX ndbm database. UNIX ndbm is a Key / Value database. This database has the risk of data error due to power failure and the killing of the App. It is not recommended to use it, and it can be instead by the LightKV database. Only when you need to access a database previously created with UNIX ndbm you can use this module.

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

var Ndbm = require('ndbm');

# Support

The following shows Ndbm module APIs available for each permissions.

# Ndbm Class

# new Ndbm(path[, flags[, mode[, type]]])

• path {String} Database file path.
• flags {String} Database open flags. default: 'r+'.
• mode {Integer} Database open mode. default: 0o666.
• type {Integer} Database default value type. default: Ndbm.BUFFER.
• Returns: {Object} A new ndbm object.

The arguments flags and mode has exactly the same meaning as the fs.open() function of the fs module, please refer to the fs module documentation.

type can choose from the following type:

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

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

# Example

var ndbm = new Ndbm('xxx', 'c', 0o666, Ndbm.OBJECT);

# Ndbm.open(path[, flags[, mode[, type]]])

• path {String} Database file path.
• flags {String} Database open flags. default: 'r+'.
• mode {Integer} Database open mode. default: 0o666.
• type {Integer} Database default value type. default: Ndbm.BUFFER.
• Returns: {Object} A new ndbm object.

Same as new Ndbm(), but does not throw an exception, returning undefined means opening failed.

# Example

var ndbm = Ndbm.open('xxx', 'c', 0o666, Ndbm.OBJECT);

# Ndbm Object

# ndbm.put(key, value[, insertOnly])

• key {String} Keyword.
• value {String} | {Object} | {Buffer} Value.
• insertOnly {Boolean} If the key already exists, give up overwriting. default: false.
• Returns: {Boolean} Whether the operation was successful.

Insert or rewrite a record.

# Example

ndbm.put('key1', 'value1');

Or:

ndbm.put('key1', { value: 'xxx' });

Or:

var buf = Buffer.from([1, 2, 3]);
ndbm.put('key1', buf);

# ndbm.set(key, value)

• key {String} Keyword.
• value {String} | {Object} | {Buffer} Value.
• Returns: {Boolean} Whether the operation was successful.

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

# Example

ndbm.set('key1', 'value1');

# ndbm.get(key[, type])

• key {String} Keyword.
• type {Integer} Database default value type. default: used type when constructing this object.
• Returns: {String} | {Object} | {Buffer} Value.

# Example

var ndbm = new Ndbm('xxx', 'c', 0o666, Ndbm.OBJECT);
ndbm.set('key1', { arg: 3 });
var value = ndbm.get('key1');
// value is { arg: 3 }
var value = ndbm.get('key1', Ndbm.STRING);
// value is "{"arg":3}"

# ndbm.delete(key)

• key {String} Keyword.
• Returns: {Boolean} Whether the operation was successful.

Delete a specified record by key.

# Example

ndbm.delete('Carl');

# ndbm.first()

• Returns: {String} The first insert key.

Get the first insert key.

# ndbm.next()

• Returns: {String} The next insert key.

Get the next insert key. Use this function with ndbm.first() can traverse the database.

# Example

for (var key = ndbm.first(); 
  key != undefined; key = ndbm.next()) {
  // Traverse ...
}

# ndbm.sync()

• Returns: {Boolean} Whether the operation was successful.

Write database cache data to disk. This operation is very critical. When the system suddenly loses power, it may cause cache data loss.

# ndbm.backup(path[, cover])

• path {String} Backup destination file.
• cover {Boolean} If the target exists, overwrite the original file. default: false.
• Returns: {Boolean} Whether the operation was successful.

# Example

ndbm.backup('./file.db.bak', true);

# ndbm.close()

Close the database, ndbm objects can no longer be operated after the database is closed.

# ndbm.forEach(callback[, this])

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

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

# Example

ndbm.set('Zhang.San', '29');
ndbm.set('Li.Si', '30');
ndbm.set('Wang.Wu', '31');

ndbm.forEach(function(value, key) {
  console.log(key, value);
});

# ndbm.toMap([map[, getDefaultValue]])

• map {Map} The map object to be saved data. default: undefined
• getDefaultValue {Function} Get default value. default: undefined
• Returns: {Map} A map object.

Save all the data in the database to a Map object and return. If the argument map is not specified, a new Map object will be created and returned.

# Example

var map = ndbm.toMap(); // dump data to a map object
map.forEach(function(value, key) {
  console.log(key, value);
});

If a field in the database is destroyed, you can use the getDefaultValue() function to set the default value.

# Example

var map = ndbm.toMap(function(key) {
  return 'This is default value string';
}); // dump data to a map object

You can also use a Proxy to synchronize Map with NDBM objects.

# Example

• Object Proxy:

function mapDataSync(ndbm, defval) {
  return new Proxy(ndbm.toMap(undefined, defval), {
    set: function(self, key, value) {
      self.set(key, value);
      ndbm.set(key, value);
      ndbm.sync();
    },
    get: function(self, key) {
      return self.get(key);
    },
    deleteProperty: function(self, key) {
      self.delete(key);
      ndbm.delete(key);
      ndbm.sync();
    }
  });
}

var syncMap = mapDataSync(ndbm);

syncMap['key'] = 'value';
console.log(syncMap['key']);
delete syncMap['key'];

• Method Proxy:

function mapDataSync(ndbm, defval) {
  var map = ndbm.toMap(undefined, defval);
  map.set = function(key, value) {
    var fn = Object.getPrototypeOf(map).set;
    fn.call(map, key, value);
    ndbm.set(ndbm, key, value);
    ndbm.sync();
  }
  map.delete = function(key) {
    var fn = Object.getPrototypeOf(map).delete;
    fn.call(map, key);
    ndbm.delete(ndbm, key);
    ndbm.sync();
  }
  return map;
}

var syncMap = mapDataSync(ndbm);

syncMap.set('key', 'value');
console.log(syncMap.get('key'));
syncMap.delete('key');

# ndbm.fillin(map[, insertOnly])

• map {Map} The map object to be read from.
• insertOnly {Boolean} If the key already exists, give up overwriting. default: false.

Store the contents of the specified Map object into the database, the key of all elements of the Map object must be String, the value must be Object, String or Buffer.

# Example

var map = new Map();

map.set('k1', 'v1');
map.set('k2', 'v1');
map.set('k3', 'v1');

ndbm.fillin(map);

# SafeNdbm Class

During the operation of the NDBM database, the database may be damaged due to power failure, etc., so SafeNdbm can provide as much support as possible in terms of power failure safety. The database backup speed depends on the disk speed and the size of the database file, so it is recommended not to make the database file too large.

# new SafeNdbm(path[, backup[, flags[, mode[, type]]]])

• path {String} Database file path.
• backup {String} Database backup file path. default: no need backup.
• flags {String} Database open flags. default: 'r+'.
• mode {Integer} Database open mode. default: 0o666.
• type {Integer} Database default value type. default: Ndbm.BUFFER.
• Returns: {Object} A new safe ndbm object.

Like new Ndbm(), If the backup file is specified, try to open the backup database when the database cannot be opened.

# Example

var safendbm = new SafeNdbm('xxx', 'backup', 'c', 0o666, Ndbm.OBJECT);

# SafeNdbm.open(path[, backup[, flags[, mode[, type]]]])

• path {String} Database file path.
• backup {String} Database backup file path. default: no need backup.
• flags {String} Database open flags. default: 'r+'.
• mode {Integer} Database open mode. default: 0o666.
• type {Integer} Database default value type. default: Ndbm.BUFFER.
• Returns: {Object} A new safe ndbm object.

Same as new SafeNdbm(), but does not throw an exception, returning undefined means opening failed.

# Example

var safendbm = SafeNdbm.open('xxx', 'backup', 'c', 0o666, Ndbm.OBJECT);

if (!backup.endsWith('.bak')) {
  backup = backup + '.bak';
}

fs.unlink(path + Ndbm.SUFFIX);
fs.copyFile(path + Ndbm.SUFFIX, backup);

# SafeNdbm Object

# safendbm.close()

Close the database, safendbm objects can no longer be operated after the database is closed.

# safendbm.backup([interval])

• interval {Integer} The database backup delay time in milliseconds. default: undefined

If interval is undefined, it means manual backup. backup performed when safendbm.backup() or safendbm.close() is called. If the interval parameter is valid, it means how long to delay automatic backup every time the database content changes. When the database is too large, May cause the backup time to be too long, it is not recommended to use the automatic backup function.

# safendbm.handle([defValue])

• defval {Any} Default value.
• Returns: {Map} A map object.

Copy all the contents of the database to a Map object and return it, and intercept the map.set() and map.delete() operations. If there is this operation, the relevant contents will be synchronized to the database file.

When a key does not have a value, this default value defValue is used.

# Example

var map = safendbm.handle();

map.set('key1', 'value1');

map.forEach(function(value, key) {
  console.log(key, value);
});

map.delete('key1');