Struct keyv::Keyv

pub struct Keyv { /* private fields */ }

Async Key-Value Store Interface

Provides an asynchronous interface to a key-value store. This implementation allows for setting, getting, removing, and clearing key-value pairs in a datastore with an optional Time-to-Live (TTL) for keys.

The Keyv struct is generic over any implementation of the Store trait, thus can be backed by various storage engines.

Examples

Create a new instance with in-memory store

let keyv = Keyv::default();

Set and get a value

let keyv = Keyv::default();

keyv.set("array", vec!["hola", "test"]).await.unwrap();

match keyv.get("array").await.unwrap() {
    Some(array) => {
        let array: Vec<String> = serde_json::from_value(array).unwrap();
        assert_eq!(array, vec!["hola".to_string(), "test".to_string()])
    }
    None => assert!(false),
}

keyv.set("string", "life long").await.unwrap();
match keyv.get("string").await.unwrap() {
    Some(string) => {
        let string: String = serde_json::from_value(string).unwrap();
        assert_eq!(string, "life long");
    }
    None => assert!(false),
}

Implementations

impl Keyv

pub async fn try_new<S: Store + 'static>(store: S) -> Result<Self, KeyvError>

Attempts to create a new Keyv instance with a custom store.

This function will attempt to initialize the provided store. If the initialization is successful, a new Keyv instance is returned.

Arguments

• store - A custom store implementing the Store trait.

Errors

Returns KeyvError if the store fails to initialize.

Examples

Inmemory

let store = InMemoryStore::new();
let keyv = Keyv::try_new(store).await.unwrap();

Postgres

let store = PostgresStoreBuilder::new()
    .uri("postgresql://postgres:postgres@localhost:5432")
    .table_name("custom_table_name")
    .build()
    .await.unwrap();
  
let keyv = Keyv::try_new(store).await.unwrap();

pub async fn set<T: Serialize>( &self, key: &str, value: T ) -> Result<(), KeyvError>

Sets a value for a given key without a TTL.

Arguments

• key - The key under which the value is stored.
• value - The value to store. Must implement Serialize.

Errors

Returns KeyvError if the operation fails.

Examples

let keyv = Keyv::default();
keyv.set("key", "hello world").await.unwrap();

pub async fn set_with_ttl<T: Serialize>( &self, key: &str, value: T, ttl: u64 ) -> Result<(), KeyvError>

Sets a value for a given key with an expiry TTL (Time-To-Live).

Arguments

• key - A string slice that holds the key.
• value - The value to be stored, which must implement Serialize.
• ttl - The time-to-live (in seconds) for the key-value pair.

Returns

Returns an Ok result on successful insertion, or a KeyvError on failure.

Examples

let keyv = Keyv::default();
keyv.set_with_ttl("temp_key", "temp_value", 3600).await.unwrap(); // Expires in 1 hour

pub async fn get(&self, key: &str) -> Result<Option<Value>, KeyvError>

Retrieves a value based on a key.

Arguments

• key - A string slice that holds the key to retrieve the value for.

Returns

Returns an Ok result with Option<Value> on success, where None indicates the key does not exist, or a KeyvError on failure.

Examples

let keyv = Keyv::default();

keyv.set("array", vec!["hola", "test"]).await.unwrap();

match keyv.get("array").await.unwrap() {
    Some(array) => {
        let array: Vec<String> = serde_json::from_value(array).unwrap();
        assert_eq!(array, vec!["hola".to_string(), "test".to_string()])
    }
    None => assert!(false),
}

keyv.set("string", "life long").await.unwrap();
match keyv.get("string").await.unwrap() {
    Some(string) => {
        let string: String = serde_json::from_value(string).unwrap();
        assert_eq!(string, "life long");
    }
    None => assert!(false),
}

pub async fn remove(&self, key: &str) -> Result<(), KeyvError>

Removes a specified key from the store.

Arguments

• key - A string slice that represents the key to be removed.

Returns

Returns an Ok result if the key has been successfully removed, or a KeyvError on failure.

Examples

let keyv = Keyv::default();
keyv.remove("my_key").await.unwrap(); // Removes "my_key" from the store

pub async fn remove_many<T: AsRef<str> + Sync>( &self, keys: &[T] ) -> Result<(), KeyvError>

Removes multiple keys from the store in one operation.

Arguments

• keys - A slice of strings or string-like objects that represent the keys to be removed.

Returns

Returns an Ok result if the keys have been successfully removed, or a KeyvError on failure.

Examples

let keyv = Keyv::default();
keyv.remove_many(&["key1", "key2"]).await.unwrap(); // Removes "key1" and "key2"

pub async fn clear(&self) -> Result<(), KeyvError>

Clears the entire store, removing all key-value pairs.

Returns

Returns an Ok result if the store has been successfully cleared, or a KeyvError on failure.

Examples

let keyv = Keyv::default();
keyv.clear().await.unwrap(); // Clears the entire store

Trait Implementations

impl Default for Keyv

fn default() -> Self

Returns the “default value” for a type.