Struct Context

Source

pub struct Context<T = Value>where
    T: Serialize + for<'de> Deserialize<'de> + Debug,
{ /* private fields */ }

Expand description

A context that holds data for pipeline execution.

The context is a type-safe, serializable container that flows through your pipeline, allowing tasks to share data. It supports JSON serialization and provides key-value access patterns with comprehensive error handling.

§Type Parameter

T: The type of values stored in the context. Must implement Serialize, Deserialize, and Debug.

§Examples

use cloacina_workflow::Context;
use serde_json::Value;

// Create a context for JSON values
let mut context = Context::<Value>::new();

// Insert and retrieve data
context.insert("user_id", serde_json::json!(123)).unwrap();
let user_id = context.get("user_id").unwrap();

Implementations§

Source §

impl<T> Context<T>
where T: Serialize + for<'de> Deserialize<'de> + Debug,

Source

pub fn new() -> Self

Creates a new empty context.

§Examples

use cloacina_workflow::Context;

let context = Context::<i32>::new();
assert!(context.get("any_key").is_none());

Source

pub fn clone_data(&self) -> Self
where T: Clone,

Creates a clone of this context’s data.

§Performance

Time complexity: O(n) where n is the number of key-value pairs
Space complexity: O(n) for the cloned data

Source

pub fn insert( &mut self, key: impl Into<String>, value: T, ) -> Result<(), ContextError>

Inserts a value into the context.

§Arguments

key - The key to insert (can be any type that converts to String)
value - The value to store

§Returns

Ok(()) - If the insertion was successful
Err(ContextError::KeyExists) - If the key already exists

§Examples

use cloacina_workflow::{Context, ContextError};

let mut context = Context::<i32>::new();

// First insertion succeeds
assert!(context.insert("count", 42).is_ok());

// Duplicate insertion fails
assert!(matches!(context.insert("count", 43), Err(ContextError::KeyExists(_))));

Source

pub fn update( &mut self, key: impl Into<String>, value: T, ) -> Result<(), ContextError>

Updates an existing value in the context.

§Arguments

key - The key to update
value - The new value

§Returns

Ok(()) - If the update was successful
Err(ContextError::KeyNotFound) - If the key doesn’t exist

§Examples

use cloacina_workflow::{Context, ContextError};

let mut context = Context::<i32>::new();
context.insert("count", 42).unwrap();

// Update existing key
assert!(context.update("count", 100).is_ok());
assert_eq!(context.get("count"), Some(&100));

// Update non-existent key fails
assert!(matches!(context.update("missing", 1), Err(ContextError::KeyNotFound(_))));

Source

pub fn get(&self, key: &str) -> Option<&T>

Gets a reference to a value from the context.

§Arguments

key - The key to look up

§Returns

Some(&T) - If the key exists
None - If the key doesn’t exist

§Examples

use cloacina_workflow::Context;

let mut context = Context::<String>::new();
context.insert("message", "Hello".to_string()).unwrap();

assert_eq!(context.get("message"), Some(&"Hello".to_string()));
assert_eq!(context.get("missing"), None);

Source

pub fn remove(&mut self, key: &str) -> Option<T>

Removes and returns a value from the context.

§Arguments

key - The key to remove

§Returns

Some(T) - If the key existed and was removed
None - If the key didn’t exist

§Examples

use cloacina_workflow::Context;

let mut context = Context::<i32>::new();
context.insert("temp", 42).unwrap();

assert_eq!(context.remove("temp"), Some(42));
assert_eq!(context.get("temp"), None);
assert_eq!(context.remove("missing"), None);

Source

pub fn data(&self) -> &HashMap<String, T>

Gets a reference to the underlying data HashMap.

This method provides direct access to the internal data structure for advanced use cases that need to iterate over all key-value pairs.

§Returns

A reference to the HashMap containing all context data

§Examples

use cloacina_workflow::Context;

let mut context = Context::<i32>::new();
context.insert("a", 1).unwrap();
context.insert("b", 2).unwrap();

for (key, value) in context.data() {
    println!("{}: {}", key, value);
}

Source

pub fn into_data(self) -> HashMap<String, T>

Consumes the context and returns the underlying data HashMap.

§Returns

The HashMap containing all context data

Source

pub fn from_data(data: HashMap<String, T>) -> Self

Creates a Context from a HashMap.

§Arguments

data - The HashMap to use as context data

§Returns

A new Context with the provided data

Source

pub fn to_json(&self) -> Result<String, ContextError>

Serializes the context to a JSON string.

§Returns

Ok(String) - The JSON representation of the context
Err(ContextError) - If serialization fails

Source

pub fn from_json(json: String) -> Result<Self, ContextError>

Deserializes a context from a JSON string.

§Arguments

json - The JSON string to deserialize

§Returns

Ok(Context<T>) - The deserialized context
Err(ContextError) - If deserialization fails

Source §

impl Context<Value>

Typed accessors for the task context (Context<serde_json::Value>).

Task bodies operate on a Context<serde_json::Value>, so reading an input otherwise means get(...).and_then(|v| v.as_*()).ok_or_else(...)? plus a serde_json::from_value round-trip, and writing means wrapping every value in serde_json::json!(...). These helpers fold that boilerplate and return a [TaskError] so they compose with ? in a task body (CLOACI-T-0733).

This mirrors the ergonomics Python authors already get from context.get(key, default) / context.set(key, value).

Source

pub fn get_as<V>(&self, key: &str) -> Result<Option<V>, TaskError>
where V: DeserializeOwned,

Get a value by key and deserialize it into V.

Returns Ok(None) when the key is absent, Ok(Some(value)) when it is present and deserializes cleanly, and Err(TaskError::ValidationFailed) when the stored JSON does not match V (the message names the key and target type).

§Examples

use cloacina_workflow::Context;

let mut ctx = Context::new();
ctx.insert("count", serde_json::json!(7)).unwrap();
let n: Option<i64> = ctx.get_as("count").unwrap();
assert_eq!(n, Some(7));
assert_eq!(ctx.get_as::<i64>("missing").unwrap(), None);

Source

pub fn get_required<V>(&self, key: &str) -> Result<V, TaskError>
where V: DeserializeOwned,

Get a value by key, deserialize it into V, and error if the key is missing.

Err(TaskError::ValidationFailed) when the key is absent or the stored JSON does not match V.

§Examples

use cloacina_workflow::Context;

let mut ctx = Context::new();
ctx.insert("name", serde_json::json!("ada")).unwrap();
let name: String = ctx.get_required("name").unwrap();
assert_eq!(name, "ada");
assert!(ctx.get_required::<String>("missing").is_err());

Source

pub fn insert_as<V>( &mut self, key: impl Into<String>, value: V, ) -> Result<(), TaskError>
where V: Serialize,

Serialize a value and write it under key, upserting (insert or overwrite).

Folds the serde_json::json!(...) / to_value wrapping — and the “exists? update : insert” dance — that every context write otherwise repeats. Upsert semantics mirror Python’s context.set(key, value) (unlike the lower-level Context::insert, which errors on an existing key). Errors with TaskError::ValidationFailed only if the value cannot be serialized.

§Examples

use cloacina_workflow::Context;

let mut ctx = Context::new();
ctx.insert_as("total", 42u32).unwrap();
assert_eq!(ctx.get_as::<u32>("total").unwrap(), Some(42));
// Upserts — overwriting an existing key is fine.
ctx.insert_as("total", 100u32).unwrap();
assert_eq!(ctx.get_as::<u32>("total").unwrap(), Some(100));