A universal but simple node library to implement user settings, but originally built to work with Electron.js.
- Code in your own style
- Easy to setup and use
- Synchronous functions available
- Asynchronous functions available
- Callback-based functions available
npm i node-user-settings --save
-
For now, callback-based methods naming are weird, I know. I am going to fix it in a major release; in the future.
-
You can specify an optional filename in which settings would be saved or retrieved. An optional filename isn't required and can be left blank.
-
A new preference file would be created after using the
optionalFileNameargument, with the persisted preference in it. -
Adding a sync as suffix to the promise-based functions, provides you with it's synchronous alternatives.
-
preferenceFileNameis no longer deprecated as of v1.5.0. UsepreferenceDir,fileNameandfileExtto set the file name to be used to persist settings, if you want to split the preference directory, filename and extension. -
Specifying only
preferenceFileNameinoptionsis the same as callingsettings.setDefaultPreferenceFilePath() -
Leaving
fileExtconfig option blank but setting afileName, results in a file with the.jsonfile extension. -
It is recommended that you only initialize the API once and then pass the initialized instance around using Dependency Injection. Even though you don't do this, it's still possible that the API would work as you want because Node JS automatically caches a module after requiring them. But again, I wouldn't recommend you do that!
Initialization using exported method
const settings = require("node-user-settings)([options]);In case you don't want to initialize options using exported method, initialize it this way
const settings = require("node-user-settings").defaults;Please note: You must call settings.setDefaultPreferenceFilePath() after using .defaults, else an error would be thrown
The filename (with extension) used to persist preference
The directory used to persist preference
The file name (without extension) used to persist preference
The file extension of the file used to persist preference
Example
For Non-Electron JS users 💡
// preferenceFileName is optional, it defaults to a Settings.json file
const settings = require("node-user-settings")({
preferenceFileDir: "path/to/save/preference",
preferenceFileName: "Settings.json",
fileName: "Settings",
fileExt: "json"
});// using only preferenceFileName, it is required for you to input the full path to the file
const settings = require("node-user-settings")({
preferenceFileName: "path/to/save/preference/Settings.json"
});For Electron JS Users 💡
// preferenceFileName is optional, it defaults to a Settings.json file
const { app } = require("electron");
const { join } = require("path");
const settings = require("node-user-settings")({
/* this is the recommended path to persist preference */
preferenceFileDir: join(app.getPath("userData"), "User", "Preferences"),
/* preferenceFileName is optional, it defaults to a Settings.json file */
preferenceFileName: "Settings.json",
fileName: "Settings",
fileExt: "json"
});const { app } = require("electron");
const { join } = require("path");
// using only preferenceFileName, it is required for you to input the full path to the file
const settings = require("node-user-settings")({
/* this is the recommended path to persist preference */
preferenceFileName: join(app.getPath("userData"), "User", "Preferences", "Settings.json")
});The settings variable where module was imported and stored, is what would be used to call the following methods listed below
Gets the default save path to the preference
A String. The default save path to the preference
Example
const path = settings.getDefaultPreferenceFilePath();
console.log(path);Gets the optional save path to the preference, if an optional file path was previously specified
Please note: You mostly never need to use this method at all! Never include it in production code, use only in development mode
A String. The temporary save path to the preference
Example
const tmpPath = settings.getTempPreferenceOptionalFilePath();
console.log(tmpPath);Sets the default path to the preference file
Note: This method is synchronous, and it is to be used in initialization only. Even though you tried to re-set the default save path, it would throw an error, so you should use it to explicitly set the default preference file path immediately after importing or requiring the module
The file path to persist preference
A String. The default save path to the preference
Example
const path = settings.setDefaultPreferenceFilePath("path/to/save/preference");
console.log(path);Gets a value asynchronously
The key in the preference in which it's value would be retrieved
An optional filename used to persist the settings. This can be left null
A default value to be used if that key has never been set
Promise that resolves to a string. The value which was mapped to the key specified
Example
const value = await settings.getState("key", "a-default-value" optionalFileName);
console.log(value);Sets a value asynchronously
The key in the preference in which it's value would be retrieved
The value to be set and mapped to the key
An optional filename used to persist the settings. This can be left null
Promise that resolves to a Boolean. indicating if the operation was successful or not
Example
const isSet = await settings.setState("key", "value", optionalFileName);
console.log(`Is value set: ${isSet}`);Sets multiple value simultaneously and asynchronously
A map with the key-value pair to be persisted
An optional filename used to persist the settings. This can be left null
A Promise that resolves an Array. A list of all the values that were persisted / set
Example
// the states to be persisted
const map = {
moduleName: "node-user-settings",
version: "1.0.0",
author: "noahweasley"
};
let persisted = await settings.setStates(map, optionalFileName);
console.log(`This values were set: ${Array.toString(persisted)}`);Gets multiple value simultaneously and asynchronously
An array of keys of which values would be retrieved
An optional filename used to persist the settings. This can be left null
A Promise that resolves an Array. A list of all the values that were retrieved
Example
// the states to be retrieved
let states = ["key1", "key2", "key3"];
let [value1, value2, value3] = await settings.getStates(states, optionalFileName);Asynchronously checks if a key exists
The key in the preference in which it's value would be checked for it's existence
An optional filename used to do the check. This can be left null
Promise that resolves to a Boolean. indicating if the key exists in the persisted preference
Example
let hasKey = await settings.hasKey("key", optionalFileName);
console.log(`Is this key available: ${hasKey ? `YES` : `NO`}`);Asynchronously deletes a single entry
The key in the preference in which it's value would be deleted
An optional filename used to persist the settings. This can be left null
Promise that resolves to a Boolean. indicating if the key was successfully deleted
Example
let isDeleted = await settings.deleteKey("key", optionalFileName);
console.log(`Is key deleted? ${isDeleted ? `YES` : `NO`}`);Asynchronously deletes the preference file
An optional filename in which the corresponding file would be deleted. This can be left null
Promise that resolves to a Boolean. indicating if the file was successfully deleted
Example
let isDeleted = await settings.deleteFile(optionalFileName);
console.log(`Is file deleted? ${isDeleted ? `YES` : `NO`}`);Asynchronously replaces all data in preference
A JSON object to be serialized and persisted
An optional filename used to persist the settings. This can be left null
A Boolean. indicating if it was persisted successfully
Example
const mockData = {
moduleName: "node-user-settings",
version: "1.0.0",
author: "noahweasley"
};
const isPersisted = await settings.serialize(mockData, optionalFileName);
console.log(`Is data changed ? ${isPersisted ? `YES` : `NO`}`);Asynchronously retrieves all the data in preference
An optional filename used to persist the settings. This can be left null
Promise that resolves to A String. The persisted object as it exists in preference
Example
const data = await settings.deserialize(optionalFileName);
console.log(data);Gets a value asynchronously
The key in the preference in which it's value would be retrieved
A default value to be used if that key has never been set
An optional filename used to persist the settings. This can be left null
A Node-Js qualified callback with any error that occurred as the first argument and a String as the second argument, representing the value which was mapped to the key specified
Example
settings.getState_c("key", "a-default-value", optionalFileName, function (err, value) {
if (err) console.log(err);
else console.log(value);
});Sets a value asynchronously
The key in the preference in which it's value would be set
The value to be set and mapped to the key
An optional filename used to persist the settings. This can be left null
A Node-Js qualified callback with any error that occurred as the first argument and a Boolean as the second argument, indicating if the operation was successful or not
Example
settings.setState_c("key", "value", optionalFileName, function (err, isSet) {
if (err) console.error(err);
else console.log(`Is value set: ${isSet}`);
});Sets multiple value simultaneously and asynchronously
A map with the key-value pair to be persisted
An optional filename used to persist the settings. This can be left null
A Node-Js qualified callback with any error that occurred as the first argument and an Array as the second argument, representing a list of all the values that were persisted / set
Example
// the states to be persisted
const map = {
moduleName: "node-user-settings",
version: "1.0.0",
author: "noahweasley"
};
settings.setStates_c(map, optionalFileName, function (err, persisted) {
if (err) console.error(err);
else console.log(`This values were set: ${Array.toString(persisted)}`);
});Gets multiple value simultaneously and asynchronously
An array of keys of which values would be retrieved
An optional filename used to persist the settings. This can be left null
A Node-Js qualified callback with any error that occurred as the first argument and an Array as the second argument, representing list of all the values that were retrieved
Example
// the states to be retrieved
let states = ["key1", "key2", "key3"];
settings.getStates_c(states, optionalFileName, function (err, values) {
let [value1, value2, value3] = values;
// do something with this array of values
});Asynchronously checks if a key exists
The key in the preference in which it's value would be checked for it's existence
An optional filename used to do the check. This can be left null
A Node-Js qualified callback with any error that occurred as the first argument and a Boolean as the second argument, indicating if the key exists in the persisted preference
Example
settings.hasKey_c("key", optionalFileName, function (err, hasKey) {
if (err) console.error(err);
else console.log(`Is this key available: ${hasKey ? `YES` : `NO`}`);
});Asynchronously deletes a single entry
The key in the preference in which it's value would be deleted
An optional filename used to persist the settings. This can be left null
A Node-Js qualified callback with any error that occurred as the first argument and a Boolean as the second argument, indicating if the key was successfully deleted
Example
settings.deleteKey_c("key", optionalFileName, function (err, isDeleted) {
if (err) console.error(err);
else console.log(`Is key deleted? ${isDeleted ? `YES` : `NO`}`);
});Asynchronously deletes the preference file
An optional filename in which the corresponding file would be deleted. This can be left null
A Node-Js qualified callback with any error that occurred as the first argument and a Boolean as the second argument, indicating if the file was successfully deleted
Example
settings.deleteFile_c(optionalFileName, function (err, isDeleted) {
if (err) console.error(err);
else console.log(`Is file deleted? ${isDeleted ? `YES` : `NO`}`);
});Asynchronously replaces all data in preference
A JSON object to be serialized and persisted
An optional filename used to persist the settings. This can be left null
A Node-Js qualified callback with any error that occurred as the first argument and a Boolean as the second argument, indicating if the file was successfully persisted
Example
const mockData = {
moduleName: "node-user-settings",
version: "1.0.0",
author: "noahweasley"
};
settings.serialize_c(mockData, optionalFileName, function (err, isPersisted) {
if (err) console.error(err);
else console.log(`Is data changed ? ${isPersisted ? `YES` : `NO`}`);
});Asynchronously retrieves all the data in preference
An optional filename used to persist the settings. This can be left null
A Node-Js qualified callback with any error that occurred as the first argument and a String as the second argument, representing the data that was deserialized and retrieved
Example
settings.deserialize_c(optionalFileName, function (err, data) {
if (err) console.error(err);
else console.log(data);
});Gets a value synchronously
The key in the preference in which it's value would be retrieved
The default value to be retrieved if that key has never been set
The key in the preference in which it's value would be retrieved
An optional filename used to persist the settings. This can be left null
A String. The value which was mapped to the key specified
Example
const value = settings.getStateSync("key", "a-default-value", optionalFileName);
console.log(value);Sets a value synchronously
The key in the preference in which it's value would be retrieved
The value to be set and mapped to the key
An optional filename used to persist the settings. This can be left null
A Boolean. indicating if the operation was successful or not
Example
const isSet = settings.setStateSync("key", "value", optionalFileName);
console.log(`Is value set: ${isSet}`);Sets multiple value simultaneously and synchronously
A map with the key-value pair to be persisted
An optional filename used to persist the settings. This can be left null
An Array. A list of all the values that were persisted / set
Example
// the states to be persisted
const map = {
moduleName: "node-user-settings",
version: "1.0.0",
author: "noahweasley"
};
let persisted = settings.setStatesSync(map, optionalFileName);
console.log(`This values were set: ${Array.toString(persisted)}`);Gets multiple value simultaneously and synchronously
An array of keys of which values would be retrieved
An optional filename used to persist the settings. This can be left null
An Array. A list of all the values that were retrieved
Example
// the states to be retrieved
let states = ["key1", "key2", "key3"];
let [value1, value2, value3] = settings.getStatesSync(states, optionalFileName);Synchronously checks if a key exists
The key in the preference in which it's value would be checked for it's existence
An optional filename used to do the check. This can be left null
A Boolean. indicating if the key exists in the persisted preference
Example
let hasKey = settings.hasKeySync("key", optionalFileName);
console.log(`Is this key available: ${hasKey ? `YES` : `NO`}`);Synchronously deletes a single entry
The key in the preference in which it's value would deleted
An optional filename used to persist the settings. This can be left null
A Boolean. indicating if the key was successfully deleted
Example
let isDeleted = settings.deleteKeySync("key", optionalFileName);
console.log(`Is key deleted? ${isDeleted ? `YES` : `NO`}`);Synchronously deletes the preference file
An optional filename in which the corresponding file would be deleted. This can be left null
A Boolean. indicating if the file was successfully deleted
Example
let isDeleted = settings.deleteFileSync(optionalFileName);
console.log(`Is file deleted? ${isDeleted ? `YES` : `NO`}`);Synchronously replaces all data in preference
A JSON object to be serialized and persisted
An optional filename used to persist the settings. This can be left null
Example
const mockData = {
moduleName: "node-user-settings",
version: "1.0.0",
author: "noahweasley"
};
const isPersisted = settings.serializeSync(mockData, optionalFileName);
console.log(`Is data changed ? ${isPersisted ? `YES` : `NO`}`);Synchronously retrieves all the data in preference
An optional filename used to persist the settings. This can be left null
A String. The persisted object as it exists in preference
Example
const data = settings.deserializeSync(optionalFileName);
console.log(data);Node User Settings is licensed to everyone under the MIT License