85 lines
2.9 KiB
Dart
85 lines
2.9 KiB
Dart
|
import 'exceptions.dart';
|
||
|
|
|
||
|
|
/// Interface for caching libraries.
|
||
|
|
///
|
||
|
|
/// The key of the cache item must be a string with max length 64 characters,
|
||
|
|
/// containing only A-Z, a-z, 0-9, _, and .
|
||
|
|
abstract class CacheInterface {
|
||
|
|
/// Fetches a value from the cache.
|
||
|
|
///
|
||
|
|
/// [key] The unique key of this item in the cache.
|
||
|
|
/// [defaultValue] Default value to return if the key does not exist.
|
||
|
|
///
|
||
|
|
/// Returns the value of the item from the cache, or [defaultValue] if not found.
|
||
|
|
///
|
||
|
|
/// Throws [InvalidArgumentException] if the [key] is not a legal value.
|
||
|
|
dynamic get(String key, [dynamic defaultValue]);
|
||
|
|
|
||
|
|
/// Persists data in the cache, uniquely referenced by a key.
|
||
|
|
///
|
||
|
|
/// [key] The key of the item to store.
|
||
|
|
/// [value] The value of the item to store. Must be serializable.
|
||
|
|
/// [ttl] Optional. The TTL value of this item.
|
||
|
|
///
|
||
|
|
/// Returns true on success and false on failure.
|
||
|
|
///
|
||
|
|
/// Throws [InvalidArgumentException] if the [key] is not a legal value.
|
||
|
|
bool set(String key, dynamic value, [Duration? ttl]);
|
||
|
|
|
||
|
|
/// Delete an item from the cache by its unique key.
|
||
|
|
///
|
||
|
|
/// [key] The unique cache key of the item to delete.
|
||
|
|
///
|
||
|
|
/// Returns true if the item was successfully removed.
|
||
|
|
/// Returns false if there was an error.
|
||
|
|
///
|
||
|
|
/// Throws [InvalidArgumentException] if the [key] is not a legal value.
|
||
|
|
bool delete(String key);
|
||
|
|
|
||
|
|
/// Wipes clean the entire cache's keys.
|
||
|
|
///
|
||
|
|
/// Returns true on success and false on failure.
|
||
|
|
bool clear();
|
||
|
|
|
||
|
|
/// Obtains multiple cache items by their unique keys.
|
||
|
|
///
|
||
|
|
/// [keys] A list of keys that can be obtained in a single operation.
|
||
|
|
///
|
||
|
|
/// Returns a Map of key => value pairs. Cache keys that do not exist or are
|
||
|
|
/// stale will have a null value.
|
||
|
|
///
|
||
|
|
/// Throws [InvalidArgumentException] if any of the [keys] are not legal values.
|
||
|
|
Map<String, dynamic> getMultiple(Iterable<String> keys,
|
||
|
|
[dynamic defaultValue]);
|
||
|
|
|
||
|
|
/// Persists a set of key => value pairs in the cache.
|
||
|
|
///
|
||
|
|
/// [values] A map of key => value pairs for a multiple-set operation.
|
||
|
|
/// [ttl] Optional. The TTL value of this item.
|
||
|
|
///
|
||
|
|
/// Returns true on success and false on failure.
|
||
|
|
///
|
||
|
|
/// Throws [InvalidArgumentException] if any of the [values] keys are not
|
||
|
|
/// legal values.
|
||
|
|
bool setMultiple(Map<String, dynamic> values, [Duration? ttl]);
|
||
|
|
|
||
|
|
/// Deletes multiple cache items in a single operation.
|
||
|
|
///
|
||
|
|
/// [keys] A list of keys to be deleted.
|
||
|
|
///
|
||
|
|
/// Returns true if the items were successfully removed.
|
||
|
|
/// Returns false if there was an error.
|
||
|
|
///
|
||
|
|
/// Throws [InvalidArgumentException] if any of the [keys] are not legal values.
|
||
|
|
bool deleteMultiple(Iterable<String> keys);
|
||
|
|
|
||
|
|
/// Determines whether an item is present in the cache.
|
||
|
|
///
|
||
|
|
/// [key] The cache item key.
|
||
|
|
///
|
||
|
|
/// Returns true if cache item exists, false otherwise.
|
||
|
|
///
|
||
|
|
/// Throws [InvalidArgumentException] if the [key] is not a legal value.
|
||
|
|
bool has(String key);
|
||
|
|
}
|