airdcpp-extension-settings-js

Settings management module for AirDC++ JavaScript extensions.

See the example extensions and the airdcpp-create-extension starter project for actual usage examples.

Features

• Keeping the config data in sync with the API
• Loading and saving of settings on disk
• Versioning and data migrations

Usage

Constructor

SettingsManager(socket, options)

Arguments

socket (object, required)

Instance of airdcpp-apisocket used by the extension.

options (object, required)

| Name | Type | Required | Description | :--- | :--- | :--- | :--- | | extensionName | string | ✓ | Name of the extension as it's registered in the application | | configFile | string | ✓ | Full path of the config file that should be used for storing the settings | | configVersion | number | ✓ | Config data version (positive integer). See the load method for information about possible migration handling. | | definitions | array[object] | ✓ | Setting definitions (see AirDC++ Web API docs for more information)|

load

load(dataMigrationCallback)

Loads possible previously saved settings and registers them with the API.

Arguments

dataMigrationCallback (function, optional)

Function that will handle possible settings migration from older version formats. If no callback is specified, loaded settings will be used regardless of their version.

The function will be called only if the loaded settings version doesn't match with the current one. Errors should be thrown if settings could not be loaded.

Usage example

// Settings migration callback
const migrate = (loadedConfigVersion, loadedData) => {
  if (loadedConfigVersion <= 1) {
    throw `Migration for settings version ${loadedConfigVersion} is not supported`;
  }

  if (loadedConfigVersion === 2) {
    // Perform the required conversions
    return Object.keys(loadedData).reduce((reduced, key) => {
      if (key === 'message_type' && loadedData[key] === 'private') {
        // The value 'private' has been renamed to 'private_chat'
        reduced[key] = 'private_chat';
      } else {
        reduced[key] = loadedData[key];
      }

      return reduced;
    }, {})
  }

  // Return as it is
  return loadedData;
};

// Load
await settings.load(migrate);

Return value

Promise that will return after all tasks have been completed.

getValue

getValue(key)

Returns the current setting value.

Usage example

const showSpam = settings.getValue('show_spam');

setValue

setValue(key, value)

Update value of the setting.

Return value

Promise that will be resolved after the value has been updated in the API.

Usage example

try {
  await settings.setValue('show_spam', false);
} catch (err) {
  socket.logger.error(`Failed to update settings value: ${err.message}`);
}

onValuesUpdated

onValuesUpdated(callback)

Set listener for updated setting values.

The callback function will receive the updated settings value object (settingKey -> newValue) an argument (it won't contain unchanged values). The listener will also be fired during initial loading with all loaded settings.

Usage example

settings.onValuesUpdated = updatedValues => {
	if (updatedValues.hasOwnProperty('search_interval')) {
		resetSearchInterval();
	}
};