Common/Storage/
GetStorageItem.rs

1// File: Common/Source/Storage/GetStorageItem.rs
2// Role: Defines the `GetStorageItem` ActionEffect.
3// Responsibilities:
4//   - Provide a declarative effect for retrieving a single item from Memento
5//     storage.
6//   - This effect abstracts the "what" (get a storage item) from the "how" (the
7//     StorageProvider implementation).
8//
9// NOTE: This effect is part of a legacy, per-key storage model. The newer,
10
11// high-performance storage model in Cocoon uses a batch-oriented approach
12// (`GetAllStorage`, `SetAllStorage`), making this effect obsolete for that
13// use case. It is kept for potential other uses or until fully deprecated.
14
15//! # GetStorageItem Effect
16//!
17//! Defines the `ActionEffect` for retrieving an item from Memento-style
18//! storage.
19
20use std::sync::Arc;
21
22use serde_json::Value;
23
24use super::StorageProvider::StorageProvider;
25use crate::{Effect::ActionEffect::ActionEffect, Error::CommonError::CommonError};
26
27/// Creates an effect that, when executed, will retrieve an item from either
28/// global or workspace-scoped Memento storage.
29///
30/// It uses the `StorageProvider` capability from the environment to perform the
31/// actual data retrieval from the host's persistent storage.
32///
33/// # Parameters
34/// * `TargetObjectValue`: A `serde_json::Value` expected to be an object with
35///   the following fields:
36///     - `Scope` (boolean, optional): `true` for global scope, `false` or
37///       absent for workspace scope.
38///     - `Key` (string, required): The key of the item to retrieve.
39///
40/// # Returns
41/// An `ActionEffect` that resolves with an `Option<Value>`, containing the
42/// retrieved value or `None` if the key does not exist.
43pub fn GetStorageItem(TargetObjectValue:Value) -> ActionEffect<Arc<dyn StorageProvider>, CommonError, Option<Value>> {
44	ActionEffect::New(Arc::new(move |Provider:Arc<dyn StorageProvider>| {
45		let TargetObjectClone = TargetObjectValue.clone();
46
47		Box::pin(async move {
48			let IsGlobal = TargetObjectClone.get("Scope").and_then(Value::as_bool).unwrap_or(false);
49
50			let KeyString = TargetObjectClone
51				.get("Key")
52				.and_then(Value::as_str)
53				.ok_or_else(|| {
54					CommonError::InvalidArgument {
55						ArgumentName:"TargetObject.Key".to_string(),
56
57						Reason:"Expected a 'Key' string field in TargetObject.".to_string(),
58					}
59				})?
60				.to_string();
61
62			Provider.GetStorageValue(IsGlobal, &KeyString).await
63		})
64	}))
65}
Common/Storage/GetStorageItem.rs

Common/Storage/
GetStorageItem.rs
