SharedPreferences Wrapper

A Flutter package that provides a simple wrapper for working with shared preferences. This package simplifies the process of storing and retrieving various data types, including strings, integers, doubles, booleans, lists, and maps in shared preferences.

Features

• Store and retrieve data types like strings, integers, doubles, booleans, lists, and maps in shared preferences.
• Set default values for string, bool, double, int data types.
• Easily update values within a map stored in shared preferences.
• Check for the existence of keys in shared preferences.
• Remove specific keys or clear all data from shared preferences.
• Retrieve all shared preferences as a map.
• Check if shared preferences are empty.
• Encrypt/Decrypt sensitive data stored in shared preferences.
• Add or update multiple key-value pairs in a single batch operation.
• Add or remove listeners for shared preference changes.
• Organize preferences based on specific groups or categories.
• Namespace Support: Implement namespaces for easier management of different sets of preferences.
• A fluent API for chaining multiple operations in a more readable manner.
• A caching manager that allows storing and managing data in shared preferences with expiration times.

Supported Data Types

• String
• int
• double
• bool
• String List
• Map

Installation

To use this package, add it to your pubspec.yaml file:

dependencies:
  shared_preferences_wrapper: ^your_version_here

Usage

Here's how to use the SharedPreferencesWrapper to work with shared preferences:

Using single functions to set and retrieve data

import 'package:shared_preferences_wrapper/shared_preferences_wrapper.dart';

// set a string value
await Prefs.setValue('name', 'Yung');
// retrieving a value by key
final val = await Prefs.getValue('name');
print(val); // output Yung

// setting different data types
// set an int value
await Prefs.setValue('qty', 10);
final qty = await Prefs.getValue('qty');

// set a double value
await Prefs.setValue('amount', 4.5);
final amount = await Prefs.getValue('amount');

// set a bool value
await Prefs.setValue('processed', true);
final processed = await Prefs.getValue('processed');

// set a string list
await Prefs.setValue('items', ['item 1', 'item 2']);
final items = await Prefs.getValue('items');

// set a map
await Prefs.setValue('user', {'name': 'Yung', 'lname': 'Cet'});
final user = await Prefs.getValue('user');

setValue Method

The setValue method is a versatile utility to store different types of data into your persistent storage or cache. It allows you to store String, int, double, bool, List, and Map values. Additionally, it supports an optional expiration time for cached data, so that the stored value can automatically be removed after the specified duration.

Storing Data With Expiration

// The data will expire after 7 days
await Prefs.setValue('user_name', 'John Doe', expirationDuration: Duration(days: 7));
// The data will expire after 24 hours
await Prefs.setValue('user_isLoggedIn', true, expirationDuration: Duration(hours: 24));

Setting a default value in getValue()

You can specify a default value for when a key does not exist in shared preferences instead of returning null. This can be set for any of the supported data types above.

final name = await Prefs.getValue('name', defaultValue: '');

Using Namespaces

Implementing namespace support in the shared_preferences_wrapper package can help you organize and manage different sets of preferences more effectively. This is simmiliar to groups.

// create the namespace
final userPrefs = Prefs.createNamespace('user');

// set the value in the namespace, NOTICE that the value is set in userPrefs and not 'SharedPreferencesWrapper'
await userPrefs.setValue('name', 'John Doe'); // the value can be any of the supported data types

// get the value, NOTICE that the value is retrieved in userPrefs and not 'SharedPreferencesWrapper'
String? userName = await userPrefs.getValue('name');
print('name: $userName');

// to get clear the namespace
await userPrefs.clearNamespace();

// create another namespace
final appPrefs = Prefs.createNamespace('app');
await appPrefs.setValue('dark_mode', true);

bool? mode = await appPrefs.getValue('dark_mode');
print('mode: $mode');

Method Chaining

Implement a builder for chaining multiple operations in a more readable manner.

// create the builder and chain methods together
await Prefs.getBuilder().then((builder) => {
  builder
      .addBool('is_logged_in', true)
      .addDouble('amount', 10.0)
      .addString('account', 'Prestige')
      .addInt('quantity', 100)
      .addMap('users', {'name': 'Yung','lname': 'Cet'})
      .addStringList('items', ['item 1', 'item 2'])
});

// to get the value above, you can use the specific method for the data type or getValue()
final is_logged_in =
          await Prefs.getValue('is_logged_in');
      print('is_logged_in: $is_logged_in');

Checking if a key exists

Checks if a key exists in shared preferences

bool? exists = await Prefs.keyExists('key');
if (exists){
  print('key exists');
}else{
  print('key does not exist');
}

Clearing all preferences

This clears all the stored shared preferences

await Prefs.clearAll();

Checking if shared preferences are empty

bool? isEmpty = await Prefs.isSharedPreferencesEmpty();
if (isEmpty){
  print('shared preferences are not empty');
}else{
  print('shared preferences are empty');
}

Removing a key

await Prefs.removeAtKey('key');

Retrieving all preferences stored

This returns all preferences stored

Map<String, dynamic> allPreferences = await Prefs.getAllSharedPreferences();
print(allPreferences);

Working with Maps

Storing a map

await Prefs.addMap('mapKey', {
      'name': 'Yung',
      'age': 30,
      'isStudent': true,
    });

Retrieving a map

Map<String, dynamic>? value = await Prefs.getMap('mapKey');
print(value);

Retrieve a value from the map on a specific key

dynamic value = await Prefs.getMapKey('mapKey', 'name');
print('value'); // output: Yung

Updating a map

You can update an existing map by adding new items to it

await Prefs.updateMap('mapKey', {'surname': 'Cet'});

The updated map now looks like this

{
  'name': 'Yung',
  'age': 30,
  'isStudent': true,
  'surname': 'Cet'  // new item added
}

Updating a value inside a map with a specific key

You can update a value inside a map for a specific key

// this updates the age value to 40
await Prefs.updateMapKey('mapKey', 'age', 40);

Checking if a key inside a map exists

final value = await Prefs.mapContainsKey('mapKey', 'mapKeyToCheck');
if (value){
  print('key exists');
}else{
  print('key does not exist');
}

Removing a key inside a map

await Prefs.removeMapKey('mapKey', 'mapKeyToRemove');

Single Batch Operation

Add or update multiple key-value pairs in a single batch operation

// Adding multiple preferences at once
Map<String, dynamic> dataToAdd = {
  'key1': 'value1',
  'key2': 42,
  'key3': true,
  'key4': ['item1', 'item2'],
  'key5': {'nestedKey': 'nestedValue'},
  // Add more key-value pairs as needed
};

await Prefs.addBatch(dataToAdd);

// access the batch data normally as you would, 
//take note of the data type stored to call the correct corresponding method
bool boolValue = await Prefs.getValue('key3');
int intValue = await Prefs.getValue('key2');

// Updating existing preferences in batch
Map<String, dynamic> dataToUpdate = {
  'key3': false,
  'key2': 100,
  // Update other keys as needed
};
await Prefs.updateBatch(dataToUpdate);

Working with Listeners

Listeners serve as the intermediaries that facilitate communication between different parts of a system, allowing components to react and respond to changes without direct coupling between them.

There are two ways to add listeners.

1. Using addListener() method

// define a function to handle the preference change
void handleChangeListener() {
  print("Listener triggered!");
}

@override
  void initState() {
    WidgetsBinding.instance?.addPostFrameCallback((_) async {
      // Registering Listeners with callback function for when a shared preference changes
      Prefs.addListener('key', handleChangeListener);
    });
}

You can also define a callback function inline as below, however, if you're planning on removing the listener at some point it is better to define a callback function as shown above to ensure that the function signatures are the same.

Prefs.addListener('key', () {
  print("Preference with key changed!");
});

Removing a listener from addListener()

// define a function to handle the preference change
void handleChangeListener() {
  print("Listener triggered!");
}

@override
  void initState() {
    WidgetsBinding.instance?.addPostFrameCallback((_) async {
      Prefs.removeListener('key', handleChangeListener);
    });
}

2. Using addObserver() method

// Function to observe changes
Function(String, dynamic) handleObserverChanges = (String key, dynamic newValue) {
  print("Observer triggered with data: key=$key value=$newValue");
};

@override
  void initState() {
    WidgetsBinding.instance?.addPostFrameCallback((_) async {
        // Add an observer
      Prefs.addObserver('observer', handleObserverChanges);
    });
}

Removing listeners from addObserver()

Prefs.removeObserver('observer', handleObserverChanges);

Grouping Preferences

Organize preferences based on specific groups or categories

// Add preferences to a specific group
await Prefs.addToGroup('UserSettings', 'username', 'JohnDoe');
await Prefs.addToGroup('UserSettings', 'email', 'john@example.com');

await Prefs.addToGroup('AppSettings', 'darkMode', true);
await Prefs.addToGroup('AppSettings', 'language', 'English');

// Retrieve preferences from a specific group
Map<String, dynamic>? userSettings = await Prefs.getGroup('UserSettings');
Map<String, dynamic>? appSettings = await Prefs.getGroup('AppSettings');
print('userSettings: $userSettings');
print('appSettings: $appSettings');

Please refer to the example code provided in the package repository for more usage examples.

Caching Data

SharedPreferencesWrapper allows caching of data with automatic expiration times. The cached data is stored for a specific duration and is automatically removed once the data expires. The data cached can be any of the supported data listed above.

// data expires after 1 hour
await Prefs.cacheData('sessionToken', '123abc', Duration(hours: 1));

// get cached data
var data = await Prefs.getCachedData('sessionToken');

// manually clear the cached data
await Prefs.clearCache('sessionToken');

Methods

• addString(String key, String value): Adds a string to shared preferences.
• addInt(String key, int value): Adds an int to shared preferences.
• addDouble(String key, double value): Adds a double to shared preferences.
• addBool(String key, bool value): Adds a bool to shared preferences.
• addStringList(String key, List: Adds a list of strings to shared preferences.
• addMap(String key, Map<String, dynamic> value): Adds a map to shared preferences.
• getString(String key): Gets a string from shared preferences.
• getBool(String key): Gets a bool from shared preferences.
• getInt(String key): Gets an int from shared preferences.
• getDouble(String key): Gets a double from shared preferences.
• getStringList(String key): Gets a list of strings from shared preferences.
• getMap(String key): Gets a map from shared preferences.
• getMapKey(String key, String mapKey): Gets a key-value pair from a map in shared preferences.
• updateMapKey(String key, String mapKey, dynamic value): Updates a key-value pair in a map in shared preferences.
• updateMap(String key, Map<String, dynamic> newMap): Updates a map in shared preferences.
• mapContainsKey(String key, String mapKey): Checks if a key exists in a map in shared preferences.
• removeMapKey(String key, String mapKey): Removes a key-value pair from a map in shared preferences.
• keyExists(String key): Checks if a key exists in shared preferences.
• removeAtKey(String key): Removes a key from shared preferences.
• clearAll(): Clears all shared preferences.
• getAllSharedPreferences(): Gets all shared preferences.
• isSharedPreferencesEmpty(): Checks if shared preferences is empty.
• addListener(String key, void Function() listener): Adds listeners for shared preference changes.
• removeListener(String key, VoidCallback listener): Removes listeners for shared preference changes.
• addObserver(String key, Function(String, dynamic) callback): Add observers for shared preference changes.
• removeObserver(String key, Function(String, dynamic) callback): Remove observers for shared preference changes.
• addBatch(Map<String, dynamic> data): Add multiple key-value pairs in a single batch operation.
• updateBatch(Map<String, dynamic> data): Update multiple key-value pairs in a single batch.
• addToGroup(String groupName, String key, dynamic value) Organize preferences based on specific groups or categories.
• getGroup(String groupName) Get preferences based on specific groups or categories.
• setValue(String key, dynamic value, {Duration expirationDuration}) Sets a value in SharedPreferences.
• set(String key, dynamic value, {Duration expirationDuration}) Sets a value in SharedPreferences.
• getValue(String key, {dynamic defaultValue}) Retrieves a value from SharedPreferences.
• get(String key, {dynamic defaultValue}) Retrieves a value from SharedPreferences.
• getBuilder() Chains methods together.
• createNamespace(String namespace) Create a namespace.
• clearNamespace() Clears the namespace.
• removeWhereKeyStartsWith(String keyPrefix) Removes preferences where key starts with the given prefix.

Contributing

If you have ideas or improvements for this package, we welcome contributions. Please open an issue or create a pull request on our GitHub repository.

License

This package is available under the MIT License.