# SyncTable : Multi-Task Key / Value in memory table

SyncTable is a in-memory Key / Value database. This module provides Key / Value based multi-task data synchronization services. This module interface is very similar to the Map object. Using this module can simplify the development of multi-task program data synchronization functions.

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

var SyncTable = require('synctable');

# Support

The following shows SyncTable module APIs available for each permissions.

# SyncTable Class

# new SyncTable(name[, emitter])

• name {String} Table name.
• emitter {EventEmitter} Value update emitter. default: undefined.
• Returns: {SyncTable} Table object.

Create a SyncTable database object, name as the database unique identifier, different tasks use the same name for the same database.

# Example

var table = new SyncTable('table1');

If the emitter exists, when the value corresponding to the key changes, the emitter will emit the key event, and the arguments are as follows:

• value {Any} The value corresponding to the key.
• tid {Integer} Which task was modified.
• net {Boolean} Is it a modification from the WebSyncTable front end.

When synctable.clear clears the database, the emitter will not emit any event, and developers can listen to the 'clear' event of the synctable object. This feature is available on EdgerOS 1.10.1 and above.

# Example

var emitter = new EventEmitter();
var table = new SyncTable('table1', emitter);

emitter.on('k1', function(value) {
  console.log('k1 new value:', value);
  // k1 new value: v1
});

table.set('k1', 'v1');

# SyncTable Object

# table.close()

Close this database instance, user must explicitly call this function to close the database, otherwise the system will not reclaim this database resource.

# table.set(key, value)

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

The set() method adds or updates an element with a specified key and a value to a SyncTable object.

# Example

table.set(0, 'bar');
table.set(1, { foo: 1 });
table.set('key1', { foo: 2 });
table.set('key2', Buffer.from([1, 2, 3]));

# table.get(key)

• key {String | Number} Key.
• Returns: {Number | String | Boolean | Object | Buffer} Value specified by key.

The get() method returns a specified element from a SyncTable object. If the value that is associated to the provided key is an object, then you will get a reference to that object, SyncTable object is a database, unlike Map object, any change made to that object will not effectively modify it inside the SyncTable object.

If the key can't be found in the SyncTable object, undefined will be returned.

# Example

table.set(0, 'bar');
console.log(table.get(0)); // 'bar'

# table.has(key)

• key {String | Number} Key.
• Returns: {Boolean} Whether there is a value corresponding to this key.

Get whether there is a value corresponding to this key.

# table.delete(key)

• key {String | Number} Key.
• 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.

The delete() method removes the specified element from a SyncTable object by key.

# Example

table.delete(1);
table.get(1); // undefined

# table.clear()

The clear() method removes all elements from a SyncTable object.

# table.forEach(callback[, thisArg])

• callback {Function} Callback.
  • value {Number | String | Boolean | Object | Buffer} Value.
  • key {String | Number} Key.
  • table {SyncTable} This table object.
• thisArg {Object} Value to use as this when executing callback. optional.

The forEach() method executes a provided function once per each key/value pair in the SyncTable object, in insertion order.

# Example

table.forEach(function(v, k) {
  console.log('k:', k, 'v:', v);
});

# table.entries()

• Returns: {Iterator} SyncTable iterator object.

The entries() method returns a new Iterator object that contains the [key, value] pairs for each element in the SyncTable object in insertion order.

# Example

table.set(1, { foo: 'x' });
table.set(2, { foo: 'y' });

var iterator = table.entries();

console.inspectEnable = true;
console.log(iterator.next().value); // [1, {foo:'x'}]
console.log(iterator.next().value); // [2, {foo:'y'}]

# table.keys()

• Returns: {Iterator} SyncTable iterator object.

The keys() method returns a new Iterator object that contains the keys for each element in the SyncTable object in insertion order.

# Example

table.set(1, { foo: 1 });
table.set(2, { foo: 2 });

var iterator = table.keys();

console.log(iterator.next().value); // 1
console.log(iterator.next().value); // 2

# table.values()

• Returns: {Iterator} SyncTable iterator object.

The values() method returns a new Iterator object that contains the values for each element in the SyncTable object in insertion order.

# Example

table.set(1, { foo: 'x' });
table.set(2, { foo: 'y' });

var iterator = table.entries();

console.log(iterator.next().value.foo); // x
console.log(iterator.next().value.foo); // y

# table.size

• {Integer}

The size accessor property returns the number of elements in a SyncTable object.

# table[Symbol.iterator]()

• Returns: {Iterator} SyncTable iterator object.

The initial value of the [Symbol.iterator] property is the same function object as the initial value of the entries method.

# SyncTable Events

The SyncTable object is used for multitasking share data. Any task can modify the shared data at any time. When the data is updated, the current task will generate related events, and users can subscribe to these events to obtain data changes.

# update

• key {String | Number} Which key's value has been changed.
• value {Number | String | Boolean | Object | Buffer} New value.
• tid {Integer} Which task modified this value.
• net {Boolean} Whether the web client updates this value.

When the data is updated, this event will be generated, and the key may be set with a new value or deleted.

# Example

table.on('update', function(key, value) {
  if (value) {
    console.log('k:', key, 'has a new value!');
  } else {
    console.log('k:', key, 'has been deleted!');
  }
});

# clear

• tid {Integer} Which task modified this value.

This event will be generated when SyncTable cleared.

# Multi-task Example

• Main task

var SyncTable = require('synctable');

var task = new Task('task.js');
var table = new SyncTable('t1');
var value = { count: 1 };

setInterval(function() {
  table.set(1, value);
  value.count++;
}, 1000);

require('iosched').forever();

• Sub task (task.js)

var SyncTable = require('synctable');

var table = new SyncTable('t1');

table.on('update', function(key) {
  var value = table.get(key);
  console.log(value.count);
});

require('iosched').forever();