qubit_metadata/
metadata.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026 Haixing Hu.
4 *
5 *    SPDX-License-Identifier: Apache-2.0
6 *
7 *    Licensed under the Apache License, Version 2.0.
8 *
9 ******************************************************************************/
10//! Provides the [`Metadata`] type — a structured, ordered, typed key-value store.
11
12use std::collections::BTreeMap;
13
14use qubit_datatype::{
15    DataType,
16    DataTypeOf,
17};
18use qubit_value::Value;
19use serde::{
20    Deserialize,
21    Serialize,
22};
23
24use crate::{
25    FromMetadataValue,
26    IntoMetadataValue,
27    MetadataError,
28    MetadataResult,
29    MetadataSchema,
30};
31
32/// A structured, ordered, typed key-value store for metadata fields.
33///
34/// `Metadata` stores values as [`qubit_value::Value`], preserving concrete Rust
35/// scalar types such as `i64`, `u32`, `f64`, `String`, and `bool`.  This avoids
36/// the ambiguity of a single JSON number type while still allowing callers to
37/// store explicit [`Value::Json`] values when they really need JSON payloads.
38///
39/// Use [`Metadata::with`] for fluent construction and [`Metadata::set`] when
40/// mutating an existing object.
41#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
42pub struct Metadata(BTreeMap<String, Value>);
43
44impl Metadata {
45    /// Creates an empty metadata object.
46    #[inline]
47    #[must_use]
48    pub fn new() -> Self {
49        Self(BTreeMap::new())
50    }
51
52    /// Returns `true` if there are no entries.
53    #[inline]
54    #[must_use]
55    pub fn is_empty(&self) -> bool {
56        self.0.is_empty()
57    }
58
59    /// Returns the number of key-value pairs.
60    #[inline]
61    #[must_use]
62    pub fn len(&self) -> usize {
63        self.0.len()
64    }
65
66    /// Returns `true` if the given key exists.
67    #[inline]
68    #[must_use]
69    pub fn contains_key(&self, key: &str) -> bool {
70        self.0.contains_key(key)
71    }
72
73    /// Retrieves the value associated with `key` and converts it to `T`.
74    ///
75    /// This convenience method returns `None` when the key is absent or when the
76    /// stored [`Value`] cannot be converted to `T`.
77    #[inline]
78    pub fn get<T>(&self, key: &str) -> Option<T>
79    where
80        T: DataTypeOf + FromMetadataValue,
81    {
82        self.try_get(key).ok()
83    }
84
85    /// Retrieves the value associated with `key` and converts it to `T`.
86    ///
87    /// # Errors
88    ///
89    /// Returns [`MetadataError::MissingKey`] when the key is absent, or
90    /// [`MetadataError::TypeMismatch`] when the stored value cannot be converted
91    /// to the requested type.
92    pub fn try_get<T>(&self, key: &str) -> MetadataResult<T>
93    where
94        T: DataTypeOf + FromMetadataValue,
95    {
96        let value = self
97            .0
98            .get(key)
99            .ok_or_else(|| MetadataError::MissingKey(key.to_string()))?;
100        T::from_metadata_value(value).map_err(|error| MetadataError::conversion_error(key, T::DATA_TYPE, value, error))
101    }
102
103    /// Returns a reference to the stored [`Value`] for `key`, or `None` if absent.
104    #[inline]
105    #[must_use]
106    pub fn get_raw(&self, key: &str) -> Option<&Value> {
107        self.0.get(key)
108    }
109
110    /// Returns the concrete data type of the value stored under `key`.
111    #[inline]
112    #[must_use]
113    pub fn data_type(&self, key: &str) -> Option<DataType> {
114        self.0.get(key).map(Value::data_type)
115    }
116
117    /// Retrieves and converts the value associated with `key`, or returns
118    /// `default` if lookup or conversion fails.
119    #[inline]
120    #[must_use]
121    pub fn get_or<T>(&self, key: &str, default: T) -> T
122    where
123        T: DataTypeOf + FromMetadataValue,
124    {
125        self.try_get(key).unwrap_or(default)
126    }
127
128    /// Inserts a typed value under `key` and returns the previous value if present.
129    #[inline]
130    pub fn set<T>(&mut self, key: &str, value: T) -> Option<Value>
131    where
132        T: IntoMetadataValue,
133    {
134        self.0.insert(key.to_string(), value.into_metadata_value())
135    }
136
137    /// Inserts a typed value after validating it against `schema`.
138    ///
139    /// # Errors
140    ///
141    /// Returns [`MetadataError::UnknownField`] when `key` is rejected by the
142    /// schema, or [`MetadataError::TypeMismatch`] when the constructed value's
143    /// concrete type does not match the schema field type.
144    #[inline]
145    pub fn set_checked<T>(&mut self, schema: &MetadataSchema, key: &str, value: T) -> MetadataResult<Option<Value>>
146    where
147        T: IntoMetadataValue,
148    {
149        let value = value.into_metadata_value();
150        schema.validate_entry(key, &value)?;
151        Ok(self.set_raw(key, value))
152    }
153
154    /// Returns a new metadata object with a typed value validated and inserted.
155    ///
156    /// # Errors
157    ///
158    /// Returns [`MetadataError::UnknownField`] when `key` is rejected by the
159    /// schema, or [`MetadataError::TypeMismatch`] when the constructed value's
160    /// concrete type does not match the schema field type.
161    #[inline]
162    pub fn with_checked<T>(mut self, schema: &MetadataSchema, key: &str, value: T) -> MetadataResult<Self>
163    where
164        T: IntoMetadataValue,
165    {
166        self.set_checked(schema, key, value)?;
167        Ok(self)
168    }
169
170    /// Returns a new metadata object with `key` set to `value`.
171    #[inline]
172    #[must_use]
173    pub fn with<T>(mut self, key: &str, value: T) -> Self
174    where
175        T: IntoMetadataValue,
176    {
177        self.set(key, value);
178        self
179    }
180
181    /// Inserts a raw [`Value`] directly and returns the previous value if present.
182    #[inline]
183    pub fn set_raw(&mut self, key: &str, value: Value) -> Option<Value> {
184        self.0.insert(key.to_string(), value)
185    }
186
187    /// Returns a new metadata object with a raw [`Value`] inserted.
188    #[inline]
189    #[must_use]
190    pub fn with_raw(mut self, key: &str, value: Value) -> Self {
191        self.set_raw(key, value);
192        self
193    }
194
195    /// Removes the entry for `key` and returns the stored [`Value`] if it existed.
196    #[inline]
197    pub fn remove(&mut self, key: &str) -> Option<Value> {
198        self.0.remove(key)
199    }
200
201    /// Removes all entries.
202    #[inline]
203    pub fn clear(&mut self) {
204        self.0.clear();
205    }
206
207    /// Returns an iterator over `(&str, &Value)` pairs in key-sorted order.
208    #[inline]
209    pub fn iter(&self) -> impl Iterator<Item = (&str, &Value)> {
210        self.0.iter().map(|(key, value)| (key.as_str(), value))
211    }
212
213    /// Returns an iterator over the keys in sorted order.
214    #[inline]
215    pub fn keys(&self) -> impl Iterator<Item = &str> {
216        self.0.keys().map(String::as_str)
217    }
218
219    /// Returns an iterator over the values in key-sorted order.
220    #[inline]
221    pub fn values(&self) -> impl Iterator<Item = &Value> {
222        self.0.values()
223    }
224
225    /// Merges all entries from `other` into `self`, overwriting existing keys.
226    pub fn merge(&mut self, other: Metadata) {
227        for (key, value) in other.0 {
228            self.0.insert(key, value);
229        }
230    }
231
232    /// Returns a new `Metadata` that contains entries from `self` and `other`.
233    ///
234    /// Entries from `other` take precedence on key conflicts.
235    #[must_use]
236    pub fn merged(&self, other: &Metadata) -> Metadata {
237        let mut result = self.clone();
238        for (key, value) in &other.0 {
239            result.0.insert(key.clone(), value.clone());
240        }
241        result
242    }
243
244    /// Retains only the entries for which `predicate` returns `true`.
245    #[inline]
246    pub fn retain<F>(&mut self, mut predicate: F)
247    where
248        F: FnMut(&str, &Value) -> bool,
249    {
250        self.0.retain(|key, value| predicate(key.as_str(), value));
251    }
252
253    /// Converts this metadata object into its underlying map.
254    #[inline]
255    #[must_use]
256    pub fn into_inner(self) -> BTreeMap<String, Value> {
257        self.0
258    }
259}
260
261impl From<BTreeMap<String, Value>> for Metadata {
262    #[inline]
263    fn from(map: BTreeMap<String, Value>) -> Self {
264        Self(map)
265    }
266}
267
268impl From<Metadata> for BTreeMap<String, Value> {
269    #[inline]
270    fn from(meta: Metadata) -> Self {
271        meta.0
272    }
273}
274
275impl FromIterator<(String, Value)> for Metadata {
276    #[inline]
277    fn from_iter<I: IntoIterator<Item = (String, Value)>>(iter: I) -> Self {
278        Self(iter.into_iter().collect())
279    }
280}
281
282impl IntoIterator for Metadata {
283    type IntoIter = std::collections::btree_map::IntoIter<String, Value>;
284    type Item = (String, Value);
285
286    #[inline]
287    fn into_iter(self) -> Self::IntoIter {
288        self.0.into_iter()
289    }
290}
291
292impl<'a> IntoIterator for &'a Metadata {
293    type IntoIter = std::collections::btree_map::Iter<'a, String, Value>;
294    type Item = (&'a String, &'a Value);
295
296    #[inline]
297    fn into_iter(self) -> Self::IntoIter {
298        self.0.iter()
299    }
300}
301
302impl Extend<(String, Value)> for Metadata {
303    #[inline]
304    fn extend<I: IntoIterator<Item = (String, Value)>>(&mut self, iter: I) {
305        self.0.extend(iter);
306    }
307}
qubit_metadata/metadata.rs

qubit_metadata/
metadata.rs
