fmap 0.3.0

File-based key-value collection. Good for caching and blob storage.

fmap

Fmap is a file-based key-value collection. Good for caching and blob storage.

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

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}'); 
}

Creating

For permanent data storage

var fmap = Fmap(Directory('/path/to/mydata'));

To cache temporary data in the system temporary directory

var fmap = Fmap.temp(); // will be placed into <temp>/fmap dir

To cache temporary data in a specific subdirectory of the system temporary directory

var blobs = Fmap.temp(subdir: 'blobsCache'); // <temp>/blobsCache
var texts = Fmap.temp(subdir: 'textsCache'); // <temp>/textsCache

If all the storage items have the same type, you can specify it with generics

var strings1 = Fmap<String>(directory);
var strings2 = Fmap.temp<String>();

Types

The object is intended primarily for storing values of type String and Uint8List (blobs).

var objects = Fmap(directory);
fmap['myJson'] = httpGet('http://somewhere'); // String
fmap['blob'] = myFile.readAsBytesSync(); // Uint8List

Any List<int> will also be treated as list of bytes.

fmap['blob2'] = [0x12, 0x34, 0x56];
fmap['blob3'] = utf8.encode('my string'); // List<int>

When saving, each int inside a list will be truncated to the range 0..255.

fmap['blob3'] = [1, 10, -1, 777]; // saves 1, 10, 255, 9 

In addition to strings and bytes, you can also store simple values of the int, double, and bool types. But keep in mind that each value is saved in a separate file. Therefore, storing a lot of small values like int may not be the most efficient approach.

fmap['int'] = 5;
fmap['double'] = 5.0; 
fmap['bool'] = true;

Purging

If the storage has become too large, you can delete the oldest data.

// leave only the freshest 16 Mb
fmap.purgeSync(16*1024*1024);

Which elements are removed depends on the policy argument passed to the constructor.

final fmap = Fmap(dir, policy: Policy.fifo);

Two policies are supported: FIFO and LRU. By default, this is FIFO.

If you want the purgeSync 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 item is read.

When you do not specify this argument, the timestamps are only updated on writes, but not on reads.