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

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: ^0.0.3+1

Usage #

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

Using single functions to set and retrieve data #

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

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

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

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

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

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

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 of any of the supported data types above.

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

Using specific functions based on data type #

import 'package:shared_preferences_wrapper/shared_preferences_wrapper.dart';

// storing values
// note: refer to the methods section for methods that store other data types
await SharedPreferencesWrapper.addString('key', 'value'); // storing strings
await SharedPreferencesWrapper.addInt('int', 100);    // storing int
await SharedPreferencesWrapper.addDouble('double', 10.0);   // storing double
await SharedPreferencesWrapper.addBool('bool', true);   // storing bool
await SharedPreferencesWrapper.addStringList('list', ['item 1', 'item 2', 'item 3']);   // storing lists
await SharedPreferencesWrapper.addMap('map', {'key': 'value'});   // storing map

// Retrieve a string from shared preferences
// note: refer to the methods section for methods that store other data types
String? retrievedValue = await SharedPreferencesWrapper.getString('key');
int? intValue = await SharedPreferencesWrapper.getInt('int');
double? value = await SharedPreferencesWrapper.getDouble('key');
bool? value = await SharedPreferencesWrapper.getBool('key');
List<String> value = await SharedPreferencesWrapper.getStringList('key');
Map<String, dynamic>? value = await SharedPreferencesWrapper.getMap('key');

Setting default values #

You can set default values that should be returned instead of null for string, int, bool, double data types.

// returns empty string instead of null
String? stringValue = await SharedPreferencesWrapper.getString('myKey', defaultValue: '');

// returns 0 instead of null
int? intValue = await SharedPreferencesWrapper.getInt('myKey', defaultValue: 0);

// returns 0.0 instead of null
double? doubleValue = await SharedPreferencesWrapper.getDouble('myKey', defaultValue: 0.0);

// returns false instead of null
bool? boolValue = await SharedPreferencesWrapper.getBool('myKey', defaultValue: false);

Checking if a key exists #

Checks if a key exists in shared preferences

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

Clearing all preferences #

This clears all the stored shared preferences

await SharedPreferencesWrapper.clearAll();

Checking if shared preferences are empty #

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

Removing a key #

await SharedPreferencesWrapper.removeAtKey('key');

Retrieving all preferences stored #

This returns all preferences stored

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

Working with Maps #

Storing a map #

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

Retrieving a map #

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

Retrieve a value from the map on a specific key #

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

Updating a map #

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

await SharedPreferencesWrapper.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 SharedPreferencesWrapper.updateMapKey('mapKey', 'age', 40);

Checking if a key inside a map exists #

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

Removing a key inside a map #

await SharedPreferencesWrapper.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 SharedPreferencesWrapper.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 SharedPreferencesWrapper.getBool('key3');
int intValue = await SharedPreferencesWrapper.getInt('key2');

// Updating existing preferences in batch
Map<String, dynamic> dataToUpdate = {
  'key3': false,
  'key2': 100,
  // Update other keys as needed
};
await SharedPreferencesWrapper.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.

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
      SharedPreferencesWrapper.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.

SharedPreferencesWrapper.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 {
      SharedPreferencesWrapper.removeListener('key', handleChangeListener);
    });
}

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
      SharedPreferencesWrapper.addObserver('observer', handleObserverChanges);
    });
}

Removing listeners from addObserver()

SharedPreferencesWrapper.removeObserver('observer', handleObserverChanges);