pdk-cache-lib 1.10.0

// Copyright (c) 2026, Salesforce, Inc.,
// All rights reserved.
// For full license text, see the LICENSE.txt file

//! Cache Library
//!
//! A caching library that provides a simple [`Cache`] trait with multiple eviction strategies.
//! It is designed to be injected and configured during the policy
//! configuration phase and supports both policy-isolated and shared caches across policies.
//!
//! This library provides data storage functionality with support for:
//!
//! - FIFO eviction strategy (First-In-First-Out)
//! - LRU eviction strategy (Least Recently Used)
//! - Builder pattern via [`builder::CacheBuilder`] and [`builder::CacheBuilderInstance`]
//! - Policy-isolated caches by default; opt-in shared caches via [`builder::CacheBuilderInstance::shared()`]
//! - Configurable maximum entries per cache
//!

pub mod builder;
pub mod error;

// The user is agnostic to the implementation of the cache since the builder returns a trait object.
// this crate should have been pub(crate), too late to change it now, we just hide it from the doc.
#[doc(hidden)]
pub mod fifo_cache;

#[doc(hidden)]
pub mod lru_cache;

#[doc(hidden)]
pub mod ttl_cache;

#[cfg(test)]
mod mocks;

use self::error::CacheError;

// Re-export the eviction strategy types for easy access
pub use builder::{EvictionStrategy, LruStrategy};

/// Represents a cache. It stores each element as a new entry.
pub trait Cache {
    /// Stores value in cache with provided key. Value should be already serialized.
    ///
    /// If it already exists, stored value will be overridden with the new param value.
    /// Have in consideration that this might affect the Cache order, depending on the
    /// eviction strategy (FIFO or LRU caches).
    ///
    /// If it is not possible to store the value in cache, it results in a [`CacheError`].
    fn save(&self, key: &str, value: Vec<u8>) -> Result<(), CacheError>;

    /// Returns stored value in cache for provided key.
    ///
    /// If it exists in the cache, returns [`Some`] with bytes slice value.
    /// Otherwise, it returns [`None`].
    fn get(&self, key: &str) -> Option<Vec<u8>>;

    /// Removes an element from cache by key.
    ///
    /// Returns the deleted value if present, or [`None`] otherwise.
    fn delete(&self, key: &str) -> Option<Vec<u8>>;

    /// Clears all elements in cache.
    fn purge(&self);
}