https://github.com/limbus-foundation/electron-save
Electron Save Data Module
https://github.com/limbus-foundation/electron-save
electron js json nodejs savedata
Last synced: 3 months ago
JSON representation
Electron Save Data Module
- Host: GitHub
- URL: https://github.com/limbus-foundation/electron-save
- Owner: Limbus-Foundation
- License: mit
- Created: 2025-03-20T00:14:36.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-20T00:27:45.000Z (over 1 year ago)
- Last Synced: 2025-03-20T01:29:12.385Z (over 1 year ago)
- Topics: electron, js, json, nodejs, savedata
- Homepage:
- Size: 1.95 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ElectronSave
Save Electron (or any other Node.js app) data locally as JSON.
## Installation
To install ElectronSave, use npm:
```sh
npm install @limbusfoundation/electronsave
```
## Usage
Import the module and create an instance:
```javascript
const ElectronSave = require("@limbusfoundation/electronsave");
const config = new ElectronSave();
```
By default, the configuration file is stored in the user's home directory as `appConfig.json`. You can specify a custom path:
```javascript
config.setPath("/absolute/path/to/config.json");
```
### Methods
#### `setPath(newPath)`
Sets a custom path for the configuration file.
- `newPath` (string) - Must be an absolute path.
#### `getPath()`
Returns the current path of the configuration file.
#### `setEncryptionKey(key)`
Sets an encryption key for secure storage.
- `key` (string) - Must be 32 characters long.
#### `setSchema(schema)`
Sets a JSON schema for validating the configuration file data.
- `schema` (object) - JSON schema object.
#### `set(key, value)`
Saves a key-value pair in the configuration file.
- `key` (string) - The property name.
- `value` (any) - The value to store.
**Example:**
```javascript
config.set("theme", "dark");
config.set("user", { name: "John", age: 30 });
```
#### `get(key,dafaultValue)`
Retrieves a value from the configuration file.
- `key` (string) - The property name.
- `defaultValue` (any) - a value to return if the key is not found.
**Example:**
```javascript
const theme = config.get("theme", "light");
console.log(theme); // Outputs: "dark"
```
#### `delete(key)`
Removes a key from the configuration file.
- `key` (string) - The property name to delete.
**Example:**
```javascript
config.delete("theme");
```
#### `clear()`
Removes all data from the configuration file.
**Example:**
```javascript
config.clear();
```
#### `backup()`
Creates a backup of the current configuration file.
- The backup file is saved with a timestamp format: `backup-MM-DD-YYYY-HH-MM-SS.json`.
**Example:**
```javascript
config.backup(); // Saves backup to default location
```
#### `restore(timestamp)`
Restores a backup from the given timestamp.
- `timestamp` (string) - The timestamp portion of the backup filename, formatted as `MM-DD-YYYY-HH-MM-SS`.
**Example:**
```javascript
config.restore("03-20-2025-14-30-00"); // Restores from 'backup-03-20-2025-14-30-00.json'
```
#### `onChange(key, callback)`
Adds an observer for a key. The callback will be triggered when the key changes.
- `key` (string) - The property name.
- `callback` (function) - The function to call when the key changes.
**Example:**
```javascript
config.onChange("theme", (newValue) => {
console.log(`Theme changed to: ${newValue}`);
});
```
#### `mask(data)`
Encrypts the data using the AES-256-CBC algorithm.
- `data` (any) - The data to encrypt.
**Example:**
```javascript
const encrypted = config.mask({ sensitive: "data" });
```
#### `unmask(encryptedData)`
Decrypts the data using the AES-256-CBC algorithm.
- `encryptedData` (string) - The encrypted data to decrypt.
**Example:**
```javascript
const decrypted = config.unmask(encryptedData);
```
## Learn Schema Validation
### JSON Schema Validation Types
1. **Type Validations:**
- `"type": "string"`
- `"type": "number"`
- `"type": "integer"`
- `"type": "boolean"`
- `"type": "object"`
- `"type": "array"`
- `"type": "null"`
- `"type": "any"`
2. **String Validation:**
- `"minLength": ` – Minimum length of the string.
- `"maxLength": ` – Maximum length of the string.
- `"pattern": ` – The string must match the regular expression.
3. **Number Validation:**
- `"minimum": ` – Minimum value of the number.
- `"maximum": ` – Maximum value of the number.
- `"exclusiveMinimum": ` – Exclusive minimum value (greater than the specified number).
- `"exclusiveMaximum": ` – Exclusive maximum value (less than the specified number).
- `"multipleOf": ` – The number must be a multiple of the specified value.
4. **Array Validation:**
- `"minItems": ` – Minimum number of items in the array.
- `"maxItems": ` – Maximum number of items in the array.
- `"uniqueItems": true` – All items in the array must be unique.
5. **Object Validation:**
- `"properties": {}` – Define properties for objects and their types.
- `"required": []` – Specifies required properties for an object.
- `"additionalProperties": false` – Disallow properties that are not defined in `properties`.
6. **Enum Validation:**
- `"enum": [, , ...]` – The value must be one of the listed options.
7. **Conditional Validation:**
- `"if"`, `"then"`, `"else"` – Conditional validation based on the value of another property.
Example:
```json
{
"if": {
"properties": { "status": { "const": "active" } }
},
"then": {
"properties": { "activationDate": { "type": "string" } }
},
"else": {
"properties": { "activationDate": { "type": "null" } }
}
}
### `setSchema(schema)`
Defines a JSON schema to validate the configuration file data.
#### Validation process:
1. **Schema definition**: The schema specifies the structure, data types, and required fields for the configuration.
Example:
```json
{
"type": "object",
"properties": {
"theme": { "type": "string" },
"user": {
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer" }
},
"required": ["name", "age"]
}
},
"required": ["theme", "user"]
}
```
2. **Validation**: When saving data with `set(key, value)`, the data is validated against the schema. If invalid (wrong type, missing fields), it won't be saved, and an error is logged.
3. **Error handling**: If validation fails, the error details are available in `validate.errors` from the `Ajv` validator.
#### Example:
```javascript
const config = new ElectronSave();
const schema = {
type: "object",
properties: {
theme: { type: "string" }
},
required: ["theme"]
};
config.setSchema(schema);
config.set("theme", 123); // Error: "theme" must be a string
```
#### Benefits:
- Ensures data integrity by enforcing structure and type constraints.
- Prevents invalid data from being saved in the configuration file.
## Notes
- Ensure the file path set with `setPath()` is absolute.
- Backups are stored using a timestamp format.
- When restoring a backup, the existing configuration file is completely replaced with the backup content.
- Encryption key must be defined for masking/unmasking functionality.
## License
This project is licensed under the MIT License.