stash_file

Description:

stash file

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 tems through the use of msgpack serialization format. This storage backend is particularly optimized to support cache 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. This storage extension 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
copied to clipboard
Run the following command to install dependencies:
dart pub get
copied to clipboard
Finally, to start developing import the followin libraries:
import 'package:stash/stash_api.dart';
import 'package:stash_file/stash_file.dart';
copied to clipboard
Usage #
Vault #
The example bellow creates a vault with a 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.
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 = await newFileLocalVaultStore(path: path);

// Creates a vault from the previously created store
final vault = await store.vault<Task>(
name: 'vault',
fromEncodable: (json) => Task.fromJson(json),
eventListenerMode: EventListenerMode.synchronous)
..on<VaultEntryCreatedEvent<Task>>().listen(
(event) => print('Key "${event.entry.key}" added to the vault'));

// Adds a task with key 'task1' to the vault
await vault.put(
'task1', Task(id: 1, title: 'Run vault store example', completed: true));
// Retrieves the value from the vault
print(await vault.get('task1'));
}
copied to clipboard
Cache #
The example bellow creates a cache with a 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.
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 = await newFileLocalCacheStore(path: path);

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

// Adds a task with key 'task1' to the cache
await cache.put(
'task1', Task(id: 1, title: 'Run cache store example', completed: true));
// Retrieves the value from the cache
print(await cache.get('task1'));
}
copied to clipboard
Additional Features #
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
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