stash_disk

A stash disk storage extension

Introduction

This storage extension for stash provides a disk based storage that relies on a highly performing binary serialization of the cache items through the use of msgpack serialization format. This storage backend is particularly optimized to support stash features, like expiration and eviction, which are highly dependent on the update of control fields on the cache entries upon user operations. The main advantage is that the update of the control fields does not cause the update of the whole cache entry as some of the other storage implementations like stash_hive or stash_sembast. It relies on a file system abstraction provided by the file package

Getting Started

Add this to your pubspec.yaml (or create it):

dependencies:
    stash_disk: ^1.0.3

Run the following command to install dependencies:

pub install

Optionally use the following command to run the tests:

pub run test

Finally, to start developing import the library:

import 'package:stash_disk/stash_disk.dart';

Usage

The example bellow creates a cache with a disk storage backend that supports a maximum of 10 Task objects. In the rather simple example bellow the serialization and deserialization of the object is coded by hand but normally it relies on the usage of libraries like json_serializable. Please take a look at the documentation of stash to gather additional information and to explore the full range of capabilities of the stash library

  import 'package:stash_disk/stash_disk.dart';

  class Task {
    final int id;
    final String title;
    final bool completed;

    Task({this.id, this.title, this.completed = false});

    /// Creates a [Task] from json map
    factory Task.fromJson(Map<String, dynamic> json) => Task(
        id: json['id'] as int,
        title: json['title'] as String,
        completed: json['completed'] as bool);

    /// Creates a json map from a [Task]
    Map<String, dynamic> toJson() =>
        <String, dynamic>{'id': id, 'title': title, 'completed': completed};

    @override
    String toString() {
      return 'Task ${id}: "${title}" is ${completed ? "completed" : "not completed"}';
    }
  }

  void main() async {
  // Creates a cache on the local storage with the capacity of 10 entries
  final cache = newLocalDiskCache(
      maxEntries: 10, fromEncodable: (json) => Task.fromJson(json));

    // Adds a task with key 'task1' to the cache
    await cache.put(
        'task1', Task(id: 1, title: 'Run stash_disk example', completed: true));
    // Retrieves the value from the cache
    final value = await cache.get('task1');

    print(value);
  }

Contributing

This library is developed by best effort, in the motto of "Scratch your own itch!", meaning APIs that are meaningful for the author use cases.

If you would like to contribute with other parts of the API, feel free to make a Github pull request as I'm always looking for contributions for:

Tests
Documentation
New APIs

Features and Bugs

Please file feature requests and bugs at the issue tracker.

License

This project is licensed under the MIT License - see the LICENSE file for details