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 typed annotations to its data
15//! models. It is not a plain `HashMap` — it is a structured extensibility point
16//! with type-safe access, [`qubit_value::Value`] backing, and first-class
17//! `serde` support.
18//!
19//! ## Design Goals
20//!
21//! - **Type Safety**: Typed get/set API backed by [`qubit_value::Value`]
22//! - **Generality**: No domain-specific assumptions — usable in any Rust project
23//! - **Schema Support**: Optional [`MetadataSchema`] validation for metadata and filters
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//! - Schema type: [`MetadataSchema`] — field definitions based on [`qubit_common::DataType`]
31//! - Filter type: [`MetadataFilter`] — composable filter expressions for metadata queries
32//! - Condition type: [`Condition`] — individual comparison predicates
33//! - Error type: [`MetadataError`] — explicit failure reporting for `try_*` APIs
34//!
35//! ## Example
36//!
37//! ```rust
38//! use qubit_metadata::{Metadata, MetadataFilter};
39//!
40//! let meta = Metadata::new()
41//! .with("author", "alice")
42//! .with("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::builder()
53//! .eq("author", "alice")
54//! .and_ge("priority", 1_i64)
55//! .build();
56//! assert!(filter.matches(&meta));
57//! ```
58//!
59//! ## Author
60//!
61//! Haixing Hu
62
63#![deny(missing_docs)]
64
65mod condition;
66mod filter_match_options;
67mod metadata;
68mod metadata_error;
69mod metadata_field;
70mod metadata_filter;
71mod metadata_filter_builder;
72mod metadata_result;
73mod metadata_schema;
74mod metadata_schema_builder;
75mod missing_key_policy;
76mod number_comparison_policy;
77mod unknown_field_policy;
78
79pub use condition::Condition;
80pub use filter_match_options::FilterMatchOptions;
81pub use metadata::Metadata;
82pub use metadata_error::MetadataError;
83pub use metadata_field::MetadataField;
84pub use metadata_filter::MetadataFilter;
85pub use metadata_filter_builder::MetadataFilterBuilder;
86pub use metadata_result::MetadataResult;
87pub use metadata_schema::MetadataSchema;
88pub use metadata_schema_builder::MetadataSchemaBuilder;
89pub use missing_key_policy::MissingKeyPolicy;
90pub use number_comparison_policy::NumberComparisonPolicy;
91pub use unknown_field_policy::UnknownFieldPolicy;