Skip to main content

dxMap

1. Overview​

dxMap module is part of the official system module library of dejaOS, used for in-memory key-value storage with topic-based namespaces.

This module provides a thread-safe, topic-based in-memory storage system. Each topic is a separate namespace for keys, allowing multiple JavaScript threads to safely access and modify data without conflicts.

Key Features:

  • Topic-based key-value storage with automatic namespace isolation
  • Thread-safe operations for multi-threaded environments
  • Automatic serialization/deserialization of various data types
  • Support for string, number, boolean, object, and array data types
  • Memory-efficient storage with automatic cleanup capabilities
  • Simple and intuitive API design

2. Files​

  • dxMap.js - JavaScript module wrapper
  • libvbar-m-dxmap.so - Underlying C language implementation

Ensure both files are included in the dxmodules subdirectory under your project root directory.

3. Dependencies​

  • None

4. Compatible Devices​

Compatible with all devices running dejaOS v2.0+

5. API Reference​

map.get(topicName)​

This is the core function of the module. It returns a map instance for a specific topic namespace.

  • topicName {string}: (Required) The name of the topic namespace. Must not be null or empty.
  • Returns: A map instance object with methods to manage data within the specified topic.
  • Throws: Error if the topic name is null or empty.

Map Instance Methods​

Each map instance returned by map.get(topicName) provides the following methods:

instance.put(key, value)​

Inserts or updates a key-value pair within the current topic.

  • key {string}: (Required) The key to set. Must not be null or empty.
  • value {*}: The value to associate with the key. Supported types: string, number, boolean, object, array. Functions are not supported.
  • Returns: {boolean} Returns true on success.
  • Throws: Error if the key is null or empty, or if the value is a function.
  • Special behavior: If value is null or undefined, the key will be automatically deleted.

instance.get(key)​

Retrieves the value associated with a key within the current topic.

  • key {string}: (Required) The key to retrieve. Must not be null or empty.
  • Returns: The value associated with the key, or undefined if the key does not exist.
  • Throws: Error if the key is null or empty.
  • Note: The returned value is automatically deserialized to its original type.

instance.has(key)​

Checks if a key exists within the current topic.

  • key {string}: (Required) The key to check. Must not be null or empty.
  • Returns: {boolean} true if the key exists, false otherwise.
  • Throws: Error if the key is null or empty.

instance.del(key)​

Deletes a key-value pair from the current topic.

  • key {string}: (Required) The key to delete. Must not be null or empty.
  • Returns: {boolean} true if the key was found and deleted, false otherwise.
  • Throws: Error if the key is null or empty.

instance.keys()​

Retrieves all keys within the current topic.

  • Returns: {string[]} An array of all keys for the topic. Returns an empty array if the topic is empty or does not exist.

instance.destroy()​

Destroys the entire topic, deleting all its keys and freeing associated memory.

  • Returns: {boolean} Returns true on success.
  • Warning: After calling destroy, the instance should not be used anymore.

6. Usage Examples​

import map from 'dxmodules/dxMap.js';
import * as log from 'dxmodules/dxLogger.js';

// 1. Get a map instance for the 'user' topic
log.info("\n=== User Topic ===");
const userMap = map.get('user');

// 2. Store various data types
userMap.put('name', 'John Doe');
userMap.put('age', 30);
userMap.put('isActive', true);
userMap.put('roles', ['admin', 'editor']);
userMap.put('profile', { email: 'john@example.com', lastLogin: '2024-01-01' });

// 3. Retrieve data
log.info('Name:', userMap.get('name')); // "John Doe"
log.info('Age:', userMap.get('age')); // 30
log.info('Is Active:', userMap.get('isActive')); // true
log.info('Roles:', userMap.get('roles')); // ['admin', 'editor']
log.info('Profile:', userMap.get('profile')); // { email: 'john@example.com', lastLogin: '2024-01-01' }

// 4. Check if keys exist
log.info('Has name:', userMap.has('name')); // true
log.info('Has email:', userMap.has('email')); // false

// 5. Get all keys
log.info('All keys:', userMap.keys()); // ['name', 'age', 'isActive', 'roles', 'profile']

// 6. Delete a key
userMap.del('isActive');
log.info('After deletion - has isActive:', userMap.has('isActive')); // false

// 7. Set null/undefined to delete (special behavior)
userMap.put('age', null); // This automatically deletes the 'age' key
log.info('After setting null - has age:', userMap.has('age')); // false

// 8. Create another topic for different data
log.info("\n=== Settings Topic ===");
const settingsMap = map.get('settings');
settingsMap.put('theme', 'dark');
settingsMap.put('language', 'en');
settingsMap.put('notifications', true);

log.info('Settings keys:', settingsMap.keys()); // ['theme', 'language', 'notifications']
log.info('Theme:', settingsMap.get('theme')); // "dark"

// 9. Clean up when done
settingsMap.destroy(); // Destroy the settings topic
log.info('After destroy - settings keys:', settingsMap.keys()); // []

7. Data Type Support​

The module automatically handles serialization and deserialization of the following data types:

Supported Types:​

  • String: Stored as-is
  • Number: Stored with #n# prefix (e.g., #n#42, #n#3.14)
  • Boolean: Stored with #b# prefix (e.g., #b#true, #b#false)
  • Array: Stored with #a# prefix and JSON serialization (e.g., #a#["item1","item2"])
  • Object: Stored with #o# prefix and JSON serialization (e.g., #o#{"key":"value"})

Unsupported Types:​

  • Function: Throws an error if attempted to store
  • null/undefined: Automatically deletes the key when set

8. Thread Safety​

The module is designed to be thread-safe, allowing multiple JavaScript threads to safely:

  • Access the same topic simultaneously
  • Modify data within the same topic
  • Create and destroy topics independently

Each topic operates in its own namespace, preventing key conflicts between different parts of your application.

9. Demo​

None