Release v1.0.0 with docs, error handling, and workflow

Adds comprehensive documentation comments for all public APIs, improves error handling with UnsupportedError for unsupported types, and introduces an automatic publishing workflow to pub.dev via GitHub Actions. Fixes bugs where write(null) incorrectly called clear() instead of remove() in SharedPreferences and EncryptedSharedPreferences. Enhances code organization, type safety, and test coverage for unsupported types and double values.

Author: YoungMayor

.github/workflows/publish.yml

@@ -0,0 +1,14 @@
+name: Publish to pub.dev
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+*'
+
+jobs:
+  publish:
+    permissions:
+      id-token: write # Required for authentication using OIDC
+    uses: dart-lang/setup-dart/.github/workflows/publish.yml@v1
+    # with:
+    #   working-directory: path/to/package/within/repository

CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.0.0] - 2025-10-07
+
+### Added
+- Automatic publishing workflow to pub.dev via GitHub Actions
+- Comprehensive documentation comments for all public APIs
+- Better error messages with `UnsupportedError` instead of generic `Exception`
+
+### Changed
+- Fixed bug where `write(null)` was calling `clear()` instead of `remove()` in SharedPreferences
+- Fixed bug where `write(null)` was calling `clear()` instead of `remove()` in EncryptedSharedPreferences
+- Improved code organization and readability
+- Enhanced documentation with detailed examples and use cases
+- Made storage operations more explicit with better type safety
+- Updated all class and method documentation following Dart documentation conventions
+
+### Fixed
+- SharedPreferences now properly uses `remove()` for deleting specific keys instead of `clear()`
+- EncryptedSharedPreferences now properly uses `remove()` for deleting specific keys instead of `clear()`
+
+---
+
 ## [0.1.1] - Documentation update
 
 ### Added

lib/mayr_storage.dart

@@ -1 +1,43 @@
+/// A simple and unified storage solution for Flutter applications.
+///
+/// This library provides a clean, consistent API for managing different types
+/// of persistent storage in Flutter apps:
+///
+/// - **SharedPreferences** - For simple, non-sensitive data
+/// - **EncryptedSharedPreferences** - For sensitive, encrypted data
+/// - **GetStorage** - For fast, synchronous key-value storage
+///
+/// ## Quick Start
+///
+/// Initialize storage at app startup:
+/// ```dart
+/// void main() async {
+///   WidgetsFlutterBinding.ensureInitialized();
+///   await MayrStorage.init();
+///   runApp(MyApp());
+/// }
+/// ```
+///
+/// Define storage keys:
+/// ```dart
+/// class Storage {
+///   static final userToken = 'USER_TOKEN'.storage<String>();
+///   static final authToken = 'AUTH_TOKEN'.secureStorage<String>();
+///   static final cache = 'CACHE_DATA'.boxStorage<String>();
+/// }
+/// ```
+///
+/// Use storage operations:
+/// ```dart
+/// // Write
+/// await Storage.userToken.write('token123');
+///
+/// // Read
+/// final token = await Storage.userToken.read();
+///
+/// // Delete
+/// await Storage.userToken.delete();
+/// ```
+library mayr_storage;
+
 export './src/mayr_storage.dart';

lib/src/drivers/abstract/preferences_storage.dart

@@ -1,12 +1,22 @@
 part of '../../mayr_storage.dart';
 
+/// Abstract interface for preference-based storage implementations.
+///
+/// Defines the contract for storage backends that persist data asynchronously,
+/// such as SharedPreferences and EncryptedSharedPreferences.
 abstract interface class PreferencesStorage<ValueT> {
-  /// Delete stored record
+  /// Deletes the stored value by writing null.
+  ///
+  /// This is equivalent to calling write(null).
   Future<void> delete() async => write(null);
 
-  /// Read stored record
+  /// Reads the stored value.
+  ///
+  /// Returns the stored value of type [ValueT], or null if no value exists.
   Future<ValueT?> read();
 
-  /// Write record to storage
+  /// Writes a value to storage.
+  ///
+  /// If [value] is null, the stored value will be deleted.
   Future<void> write(ValueT? value);
 }

lib/src/drivers/encrypt_shared_preferences_storage.dart

@@ -1,16 +1,25 @@
 part of './../mayr_storage.dart';
 
+/// Storage implementation using EncryptedSharedPreferences.
+///
+/// Provides encrypted, asynchronous storage for sensitive data.
+/// Data is encrypted at rest using AES encryption, making it suitable
+/// for storing tokens, passwords, and other confidential information.
+///
+/// Supported types: [String], [int], [double], [bool]
 class EncryptSharedPreferencesStorage<ValueT>
     extends PreferencesStorage<ValueT> {
   final String _preferenceKey;
 
+  /// Creates an encrypted storage handler for the given key.
   EncryptSharedPreferencesStorage(this._preferenceKey);
 
   @override
   Future<ValueT?> read() async {
-    EncryptedSharedPreferences securePref =
+    final EncryptedSharedPreferences securePref =
         EncryptedSharedPreferences.getInstance();
 
+    // Type-safe retrieval based on generic type
     if (ValueT == bool) {
       return securePref.getBool(_preferenceKey) as ValueT?;
     } else if (ValueT == String) {
@@ -20,27 +29,32 @@ class EncryptSharedPreferencesStorage<ValueT>
     } else if (ValueT == double) {
       return securePref.getDouble(_preferenceKey) as ValueT?;
     } else {
-      throw Exception("Unsupported type");
+      throw UnsupportedError(
+        'Type $ValueT is not supported. Only String, int, double, and bool are supported.',
+      );
     }
   }
 
   @override
   Future<void> write(ValueT? value) async {
-    EncryptedSharedPreferences securePref =
+    final EncryptedSharedPreferences securePref =
         EncryptedSharedPreferences.getInstance();
 
+    // Delete the key if value is null
     if (value == null) {
-      securePref.clear();
+      await securePref.remove(_preferenceKey);
     } else if (ValueT == bool) {
-      securePref.setBool(_preferenceKey, value as bool);
+      await securePref.setBool(_preferenceKey, value as bool);
     } else if (ValueT == String) {
-      securePref.setString(_preferenceKey, value as String);
+      await securePref.setString(_preferenceKey, value as String);
     } else if (ValueT == int) {
-      securePref.setInt(_preferenceKey, value as int);
+      await securePref.setInt(_preferenceKey, value as int);
     } else if (ValueT == double) {
-      securePref.setDouble(_preferenceKey, value as double);
+      await securePref.setDouble(_preferenceKey, value as double);
     } else {
-      throw Exception("Unsupported type");
+      throw UnsupportedError(
+        'Type $ValueT is not supported. Only String, int, double, and bool are supported.',
+      );
     }
   }
 }

lib/src/drivers/get_box_storage.dart

@@ -1,22 +1,48 @@
 part of '../mayr_storage.dart';
 
+/// Storage implementation using GetStorage.
+///
+/// Provides fast, synchronous key-value storage with support for complex types.
+/// Ideal for caching, frequently accessed data, and scenarios where
+/// synchronous access is preferred.
+///
+/// Unlike SharedPreferences, GetBoxStorage operations are synchronous
+/// and support any serializable type.
 class GetBoxStorage<ValueT> {
   final String _boxName;
 
+  /// The underlying GetStorage instance.
   late final GetStorage _box = GetStorage();
 
+  /// Creates a GetBox storage handler for the given key.
   GetBoxStorage(this._boxName);
 
-  /// Delete stored record
+  /// Deletes the stored value.
+  ///
+  /// Removes the key-value pair from storage.
   void delete() => _box.remove(_boxName);
 
-  /// Listen for updates
+  /// Listens for changes to the stored value.
+  ///
+  /// The [handler] callback will be invoked whenever the value
+  /// associated with this key changes.
+  ///
+  /// Example:
+  /// ```dart
+  /// storage.listen((newValue) {
+  ///   print('Value changed to: $newValue');
+  /// });
+  /// ```
   void listen(void Function(ValueT newValue) handler) =>
       _box.listenKey(_boxName, (newValue) => handler(newValue));
 
-  /// Read value from storage
+  /// Reads the stored value synchronously.
+  ///
+  /// Returns the stored value of type [ValueT], or null if no value exists.
   ValueT? read() => _box.read(_boxName);
 
-  /// Write value to storage
+  /// Writes a value to storage synchronously.
+  ///
+  /// If [value] is null, the stored value will be deleted.
   void write(ValueT? value) => _box.write(_boxName, value);
 }

lib/src/drivers/shared_preferences_storage.dart

@@ -1,14 +1,22 @@
 part of '../mayr_storage.dart';
 
+/// Storage implementation using Flutter's SharedPreferences.
+///
+/// Provides asynchronous access to platform-specific persistent storage
+/// for simple data types. Suitable for user preferences and non-sensitive data.
+///
+/// Supported types: [String], [int], [double], [bool]
 class SharedPreferencesStorage<ValueT> extends PreferencesStorage<ValueT> {
   final String _preferenceKey;
 
+  /// Creates a SharedPreferences storage handler for the given key.
   SharedPreferencesStorage(this._preferenceKey);
 
   @override
   Future<ValueT?> read() async {
-    SharedPreferences sharedPref = await SharedPreferences.getInstance();
+    final SharedPreferences sharedPref = await SharedPreferences.getInstance();
 
+    // Type-safe retrieval based on generic type
     if (ValueT == bool) {
       return sharedPref.getBool(_preferenceKey) as ValueT?;
     } else if (ValueT == String) {
@@ -18,26 +26,31 @@ class SharedPreferencesStorage<ValueT> extends PreferencesStorage<ValueT> {
     } else if (ValueT == double) {
       return sharedPref.getDouble(_preferenceKey) as ValueT?;
     } else {
-      throw Exception("Unsupported type");
+      throw UnsupportedError(
+        'Type $ValueT is not supported. Only String, int, double, and bool are supported.',
+      );
     }
   }
 
   @override
   Future<void> write(ValueT? value) async {
-    SharedPreferences sharedPref = await SharedPreferences.getInstance();
+    final SharedPreferences sharedPref = await SharedPreferences.getInstance();
 
+    // Delete the key if value is null
     if (value == null) {
-      sharedPref.clear();
+      await sharedPref.remove(_preferenceKey);
     } else if (ValueT == bool) {
-      sharedPref.setBool(_preferenceKey, value as bool);
+      await sharedPref.setBool(_preferenceKey, value as bool);
     } else if (ValueT == String) {
-      sharedPref.setString(_preferenceKey, value as String);
+      await sharedPref.setString(_preferenceKey, value as String);
     } else if (ValueT == int) {
-      sharedPref.setInt(_preferenceKey, value as int);
+      await sharedPref.setInt(_preferenceKey, value as int);
     } else if (ValueT == double) {
-      sharedPref.setDouble(_preferenceKey, value as double);
+      await sharedPref.setDouble(_preferenceKey, value as double);
     } else {
-      throw Exception("Unsupported type");
+      throw UnsupportedError(
+        'Type $ValueT is not supported. Only String, int, double, and bool are supported.',
+      );
     }
   }
 }

lib/src/extension.dart

@@ -1,14 +1,48 @@
 part of './mayr_storage.dart';
 
+/// Extension on String to provide convenient storage accessors.
+///
+/// This extension allows any string to be converted into a storage handler
+/// by treating the string as a storage key.
 extension KeyStorageExtensions on String {
-  /// Get Box Storage using GetStorage internally
+  /// Creates a GetBox storage handler for the given key.
+  ///
+  /// Box storage provides synchronous, lightweight key-value storage
+  /// ideal for caching and frequently accessed data.
+  ///
+  /// Example:
+  /// ```dart
+  /// final storage = 'MY_KEY'.boxStorage<String>();
+  /// storage.write('value');
+  /// final value = storage.read();
+  /// ```
   GetBoxStorage<ValueT> boxStorage<ValueT>() => GetBoxStorage<ValueT>(this);
 
-  /// Get Secure Storage using Encrypted Shared Preferences internally
+  /// Creates a secure storage handler using Encrypted Shared Preferences.
+  ///
+  /// Secure storage encrypts data at rest, making it suitable for
+  /// sensitive information like tokens, passwords, and user credentials.
+  ///
+  /// Example:
+  /// ```dart
+  /// final storage = 'AUTH_TOKEN'.secureStorage<String>();
+  /// await storage.write('secret_token');
+  /// final token = await storage.read();
+  /// ```
   EncryptSharedPreferencesStorage<ValueT> secureStorage<ValueT>() =>
       EncryptSharedPreferencesStorage<ValueT>(this);
 
-  /// Get Shared Preferences Storage
+  /// Creates a standard Shared Preferences storage handler.
+  ///
+  /// Standard storage is suitable for non-sensitive configuration data,
+  /// user preferences, and application settings.
+  ///
+  /// Example:
+  /// ```dart
+  /// final storage = 'USER_THEME'.storage<String>();
+  /// await storage.write('dark');
+  /// final theme = await storage.read();
+  /// ```
   SharedPreferencesStorage<ValueT> storage<ValueT>() =>
       SharedPreferencesStorage<ValueT>(this);
 }

lib/src/mayr_storage.dart

@@ -8,11 +8,27 @@ part 'drivers/abstract/preferences_storage.dart';
 part './drivers/shared_preferences_storage.dart';
 part './extension.dart';
 
+/// Main entry point for MayrStorage initialization.
+///
+/// This class provides centralized initialization for all storage backends
+/// used by the package including SharedPreferences, EncryptedSharedPreferences,
+/// and GetStorage.
 class MayrStorage {
-  /// Init MayrStorage
-  static Future init() async {
+  /// Initializes all storage backends.
+  ///
+  /// This method must be called before using any storage operations,
+  /// typically in the main() function after WidgetsFlutterBinding.ensureInitialized().
+  ///
+  /// Example:
+  /// ```dart
+  /// void main() async {
+  ///   WidgetsFlutterBinding.ensureInitialized();
+  ///   await MayrStorage.init();
+  ///   runApp(MyApp());
+  /// }
+  /// ```
+  static Future<void> init() async {
     await GetStorage.init();
-
     await EncryptedSharedPreferences.initialize("testkey#1029121@");
   }
 }

pubspec.yaml

@@ -2,7 +2,7 @@ name: mayr_storage
 description: >-
   Simple and unified storage solution for Flutter apps.
   Easily manage SharedPreferences, EncryptedSharedPreferences, and GetStorage with a clean, consistent API.
-version: 0.1.1
+version: 1.0.0
 homepage: https://github.com/YoungMayor/mayr_flutter_storage
 repository: https://github.com/YoungMayor/mayr_flutter_storage
 issue_tracker: https://github.com/YoungMayor/mayr_flutter_storage/issues