fmap

Description:

fmap

fmap #
A simple and efficient approach to caching or persistent blob storage. Map-like
object for accessing data stored on the filesystem.
var fmap = Fmap(directory);

fmap['keyA'] = 'my string'; // saved string into a file
fmap['keyB'] = 777; // saved int into a file
fmap['keyC'] = [0x12, 0x34, 0x56]; // saved three-bytes into a file

print(fmap['keyA']); // read from file
copied to clipboard
Fmap implements a Map, so it can be used the same way.
print('Count of items: ${fmap.length}');

for (var entry in fmap.entries) {
print('Item ${entry.key}: ${entry.value}');
}
copied to clipboard
Entries are stored in separate files. Therefore, reading/writing an entry is
about as fast as reading/writing a file with a known exact name. But unlike
direct file access, Fmap has no restrictions on the content of String keys,
it takes care of finding unique file names, resolving hash collisions, and
serialization.
Creating #
For persistent data storage
var fmap = Fmap(Directory('/path/to/my_precious_data'));
copied to clipboard
To cache data in the system temporary directory
var fmap = Fmap.temp(); // will be placed into {temp}/fmap dir
copied to clipboard
To cache data in a specific subdirectory of the system temporary directory
var images = Fmap.temp(subdir: 'images_cache'); // {temp}/images_cache
var jsons = Fmap.temp(subdir: 'jsons_cache'); // {temp}/jsons_cache
copied to clipboard
If all the storage items have the same type, you can set the type with generics
var strings1 = Fmap<String>(directory);
var strings2 = Fmap.temp<String>();
copied to clipboard
Types #
The collection allows you to store only values of certain types.
Supported types are String, List<int>, List<String>, int, double
and bool.
var fmap = Fmap(directory);
fmap['string'] = 'abcd';
fmap['int'] = 5;
fmap['double'] = 5.0;
fmap['bool'] = true;
copied to clipboard
Bytes #
Any List<int> is treated as list of bytes.
fmap['blob1'] = [0x12, 0x34, 0x56]; // List<int>
fmap['blob2'] = utf8.encode('my string'); // List<int>
fmap['blob3'] = myFile.readAsBytesSync(); // Uint8List implements List<int>
copied to clipboard
Since numbers are bytes, each int inside a list is truncated to the range
0..255.
fmap['blob4'] = [1, 10, -1, 777]; // saves 1, 10, 255, 9
copied to clipboard
Lists of bytes always return Uint8List when read.
Uint8List bytes = fmap['blob4']; // was List<int>, now Uint8List
copied to clipboard
String lists #
Lists of strings, when stored, can be specified by any object that implements
Iterable <String>, not necessarily a List.
fmap['saved_list'] = ['ordered', 'strings', 'in', 'list'];
fmap['saved_iterable'] = {'unordered', 'strings', 'in', 'a', 'set'};
copied to clipboard
However, when read, they will definitely return as List<String>.
List<String> a = fmap['saved_list'];
List<String> b = fmap['saved_iterable'];
copied to clipboard
Entry ~ file #
Keep in mind that each entry is saved in a separate file. Therefore, storing a
lot of atomic values like double associated with different keys may not be
very practical. Conversely, saving large objects such as String, List<int>,
or List<String> is efficient. It's almost like writing directly to files, but
without restrictions on key names.
Purging #
If the storage has become too large, you can delete the oldest data.
// leave only the newest 16 megabytes
fmap.purge(16*1024*1024);
copied to clipboard
Which elements are removed depends on the policy argument passed to the
constructor.
var fmap = Fmap(dir, policy: Policy.fifo);
copied to clipboard
Two policies are supported: FIFO and LRU. By default, this is FIFO.
If you want the purge method to purge storage with LRU policy, you must
not only create Fmap(policy: Policy.lru) before purging but always
create the object this way. It will force Fmap to update the last-used
timestamps every time an entry is read.
When you do not specify this argument, the timestamps are only updated on
writes, but not on reads.
Compatibility #
The library is unit-tested on Linux, Windows, and macOS. Mobile systems such as
Android and iOS have the same kernels as their desktop relatives.