keep 0.5.2

keep: ^0.5.2 copied to clipboard

• Refactored file write operations with a robust atomicWrite utility.
• Added explicit directory checks and temporary file validation to prevent PathNotFoundException during atomic swaps.
• Improved error handling by ensuring temporary files are cleaned up on failure.
• Specialized for better stability on emulators and slow file systems.

Added #

• Uint8List Support: New kBytes and kBytesSecure factories for efficient byte array storage.
• Custom Serialization for Secure Keys: Secure factories now support optional fromStorage and toStorage mappers.

Changed #

• Performance: General optimizations for better memory efficiency and speed.
• Code Clarity: Improved internal factory logic for better readability.

Added #

• Multi-Instance Support: Multiple Keep instances can now run concurrently with independent registries and storage locations.
  • Keep constructor now requires a unique id for stable identity and folder naming.
  • Automatic folder hashing ensures storage isolation based on instance ID.
• Refined Static Key Factories: Renamed factories for brevity and consistency:
  • Keep.kInt, Keep.kIntSecure
  • Keep.kString, Keep.kStringSecure
  • Keep.kBool, Keep.kBoolSecure
  • Keep.kDouble, Keep.kDoubleSecure
  • Keep.kList, Keep.kListSecure
  • Keep.kMap, Keep.kMapSecure
  • Keep.custom, Keep.customSecure

Changed #

• Breaking: Keep constructor requires positional id: String.
• Breaking: Keep.init() no longer accepts folderName as it is now derived from id.
• Keep instances now perform automatic key binding during construction for multi-instance support.

Added #

• Version-Based Migration System: Introduced KeepCodec architecture for seamless storage format upgrades
  • KeepCodec.of(bytes) automatically selects correct codec based on version byte
  • KeepCodecV1 implements current JSON-based format with optimized header structure
  • Future-proof: Add new codecs without breaking existing data
• New binary format with version-first layout: [Version][Flags][Type][Lengths...][Data]
• KeepCodecOf wrapper for automatic codec selection and decoding
• KeepHeader class for metadata extraction without full payload parsing

Changed #

• Breaking: Binary format updated - version byte moved to first position for instant detection
• Batch encoding/decoding moved from codec interface to internal storage implementation
• Simplified codec interface to single-entry operations only

Performance #

• Header parsing now O(1) instead of O(n) due to fixed-position metadata
• Codec selection happens once at read time, not per-operation

Added #

• Added KeepStorage.readHeader() to allow reading metadata without loading full content.
• KeepCodec.parseHeader() now returns version and KeepType enum.

Changed #

• Refactored SubKeyManager to be storage-agnostic by using readHeader() instead of direct file system access.

Changed #

• Breaking: SubKeyManager.toList() now works without requiring a meta-file.
• Breaking: Storage format updated. Old data will be treated as non-existent and ignored.

Added #

• SubKeyManager.toList() now finds sub-keys even if they haven't been written yet in the current session.
• clearRemovable() can now remove all removable sub-keys, even those not accessed in the current session.

Fixed #

• Improved reliability of sub-key discovery across app restarts.

Fixed #

• Fixed a deadlock in KeepKey.remove when notifying the parent SubKeyManager.
• Fixed potential race condition in SubKeyManager.clear() by canceling active debounce timers.

Changed #

• Internalized sub-key registration methods (_register, _unregister) to simplify the public API.

Fixed #

• SubKeyManager.clear() now properly removes sub-key contents before clearing the registry.

Changed #

• Renamed internal debounce timer variables for consistency (_debounceTimer).

Changed #

• SubKeyManager.exists is now async and ensures initialization before checking.

Added #

• Added SubKeyEvent enum (added, removed, cleared) for tracking sub-key changes.
• Added stream getter to SubKeyManager for reactive sub-key monitoring.
• SubKeyManager now extends ChangeNotifier for Flutter widget integration.
• Added dispose() method to SubKeyManager for proper resource cleanup.

Changed #

• Renamed SubKeyManager.keys getter to toList() method for better API clarity.

Changed #

• Added documentation to SubKeyManager.keys getter.

Fixed #

• Fixed race condition in SubKeyManager._ensureInitialized() that could cause concurrent calls to run multiple _performLoad() operations.
• Added _ensureInitialized() call to SubKeyManager.remove() to prevent data loss.
• Errors in _performLoad() now properly complete the completer with error, preventing infinite waits.

Fixed #

• KeepType.fromByte now returns tNull instead of null for unknown bytes, preventing encoding crashes.

Changed #

• KeepKey no longer extends Stream. Use stream getter instead.
• Added exists getter to SubKeyManager.

Fixed #

• Added try-catch blocks to KeepCodec.encodeAll, decodeAll, and encodePayload methods.

Fixed #

• Internal storage now deletes corrupted files on decode failure instead of deadlocking.

Fixed #

• Added missing try-catch blocks to SubKeyManager I/O operations.
• Disabled avoid_catches_without_on_clauses lint rule for broader exception handling.

Added #

• Added memory cache for KeepKeyPlain and KeepKeySecure read operations.
• Added clear() and remove() methods to SubKeyManager.

Changed #

• Renamed KeepValueType to KeepType.
• Replaced tUnknown with tNull and added tBytes for Uint8List support.

Performance #

• Read operations now return cached values, significantly improving throughput.
• See test/stress_test.dart for benchmarks.

Changed #

• Added @mustCallSuper annotation to Keep.init() method.

Added #

• Added KeepValueType enum for type-safe binary encoding.
• Type byte now stored in binary format header.
• Added KeepValueType.parse<T>() for default type conversions.

Changed #

• Optimized sub-key registration and disk synchronization (synchronous registration, smart background sync).

Fixed #

• Resolved issues with sub-key hierarchy and traversal logic.

Changed #

• Improved global exception handling and error propagation stability.
• read methods now return null instead of throwing on corruption, ensuring graceful degradation.
• write methods now consistently fail-fast on errors.

Fixed #

• Fixed duplicate onError callbacks.

Added #

• Introduced binary format versioning and migration infrastructure (V1).
• Improved storage key hashing and internal data obfuscation.

Changed #

• Breaking: KeepKeySecure now stores raw encrypted values directly for better efficiency.
• Standardized code structure and return patterns.

Fixed #

• Fixed crash when handling empty external storage files.
• Added legacy format support during migration.

Added #

• Added Keep.custom for plain custom storage keys.

Changed #

• Renamed custom to customSecure for consistency.

Added #

• Exported KeepBuilder and KeepException.

Changed #

• Renamed useExternalStorage to useExternal.

Added #

• Added fromStorage/toStorage converters to KeepKeyPlain.
• Enhanced type safety for Keep.list and Keep.map factories.

Added #

• Providing a custom storage adapter now automatically enables useExternal.

Added #

• Support for per-key custom KeepStorage adapters.

Added #

• Added static key factories (Keep.integer, Keep.stringSecure, etc.).
• Added decimal and decimalSecure factories.

Changed #

• Keep.keys now uses internal registry for faster access.
• clearRemovable() automatically notifies listeners.

Fixed #

• Improved num to double conversion.
• Fixed boolean parsing support.

• Internal build stabilization.

• Initial release