stash_file 3.2.0

File storage extension for the stash caching API. Provides support to store caches in the local file system in binary format using the msgpack json format

stash_file

A stash file storage extension

Overview

This storage extension for stash provides a file 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) replacing x.x.x with the latest version of stash_file:

dependencies:
    stash_file: ^x.x.x

Run the following command to install dependencies:

dart pub get

Finally, to start developing import the library:

import 'package:stash_file/stash_file.dart';

Usage

The example bellow creates two caches with a shared file storage backend. In this rather simple example the serialization and deserialization of the object is coded by hand but it's more usual to rely on 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 'dart:io';

import 'package:stash/stash_api.dart';
import 'package:stash_file/stash_file.dart';

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

  Task({required this.id, required 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 {
  // Temporary directory
  final path = Directory.systemTemp.path;

  // Creates a store
  final store = newLocalFileStore(
      path: path, fromEncodable: (json) => Task.fromJson(json));
  // Creates a cache with a capacity of 10 from the previously created store
  final cache1 = store.cache(
      cacheName: 'cache1',
      maxEntries: 10,
      eventListenerMode: EventListenerMode.synchronous)
    ..on<CreatedEntryEvent>().listen(
        (event) => print('Key "${event.entry.key}" added to the first cache'));
  // Creates a second cache with a capacity of 10 from the previously created store
  final cache2 = store.cache(
      cacheName: 'cache2',
      maxEntries: 10,
      eventListenerMode: EventListenerMode.synchronous)
    ..on<CreatedEntryEvent>().listen(
        (event) => print('Key "${event.entry.key}" added to the second cache'));

  // Adds a task with key 'task1' to the first cache
  await cache1.put('task1',
      Task(id: 1, title: 'Run shared store example (1)', completed: true));
  // Retrieves the value from the first cache
  print(await cache1.get('task1'));

  // Adds a task with key 'task1' to the second cache
  await cache2.put('task1',
      Task(id: 2, title: 'Run shared store example (2)', completed: true));
  // Retrieves the value from the second cache
  print(await cache2.get('task1'));
}

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