qubit_metadata/lib.rs
1/*******************************************************************************
2 *
3 * Copyright (c) 2025 - 2026.
4 * Haixing Hu, Qubit Co. Ltd.
5 *
6 * All rights reserved.
7 *
8 ******************************************************************************/
9//! # qubit-metadata
10//!
11//! A general-purpose, type-safe, extensible metadata model for Rust.
12//!
13//! This crate provides a [`Metadata`] type — a structured key-value store
14//! designed for any domain that needs to attach arbitrary, typed, serializable
15//! annotations to its data models. It is not a plain `HashMap` — it is a
16//! structured extensibility point with type-safe access, `serde_json::Value`
17//! backing, and first-class `serde` support.
18//!
19//! ## Design Goals
20//!
21//! - **Type Safety**: Typed get/set API backed by `serde_json::Value`
22//! - **Generality**: No domain-specific assumptions — usable in any Rust project
23//! - **Extensibility**: Acts as a structured extension point, not a stringly-typed bag
24//! - **Serialization**: First-class `serde` support for JSON interchange
25//! - **Filtering**: [`MetadataFilter`] for composable query conditions
26//!
27//! ## Features
28//!
29//! - Core type: [`Metadata`] — an ordered key-value store with typed accessors
30//! - Filter type: [`MetadataFilter`] — composable filter expressions for metadata queries
31//! - Condition type: [`Condition`] — individual comparison predicates
32//! - Error type: [`MetadataError`] — explicit failure reporting for `try_*` APIs
33//! - Type inspection: [`MetadataValueKind`] — lightweight JSON kind inspection
34//!
35//! ## Example
36//!
37//! ```rust
38//! use qubit_metadata::{Metadata, MetadataFilter};
39//!
40//! let mut meta = Metadata::new();
41//! meta.set("author", "alice");
42//! meta.set("priority", 3_i64);
43//!
44//! // Convenience API: missing key and type mismatch both collapse to None.
45//! let author: Option<String> = meta.get("author");
46//! assert_eq!(author.as_deref(), Some("alice"));
47//!
48//! // Explicit API: preserve failure reasons for diagnostics.
49//! let priority = meta.try_get::<i64>("priority").unwrap();
50//! assert_eq!(priority, 3);
51//!
52//! let filter = MetadataFilter::eq("author", "alice")
53//! .and(MetadataFilter::gte("priority", 1_i64));
54//! assert!(filter.matches(&meta));
55//! ```
56//!
57//! ## Author
58//!
59//! Haixing Hu
60
61#![deny(missing_docs)]
62
63mod error;
64mod filter;
65mod metadata;
66
67pub use error::{
68 MetadataError,
69 MetadataResult,
70 MetadataValueKind,
71};
72pub use filter::{
73 Condition,
74 MetadataFilter,
75};
76pub use metadata::Metadata;