jgd-rs 0.2.1

A simple Rust library for generating realistic JSON data using declarative schema definitions
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

//! Type specifications for JGD (JSON Generator Definition) schema.
//!
//! This module contains all the type specifications that define how different types
//! of data should be generated according to the JGD schema specification. It provides
//! a comprehensive set of building blocks for creating fake JSON data generators.
//!
//! # Overview
//!
//! The type specification system is built around the [`JsonGenerator`] trait, which
//! defines a common interface for all data generators. Each type specification
//! corresponds to a different field type in the JGD schema:
//!
//! - [`NumberSpec`] - Generates random numbers (integers or floats) within a range
//! - [`ArraySpec`] - Generates arrays of elements with specified count and element types
//! - [`Entity`] - Generates complex objects with multiple fields
//! - [`Field`] - Represents individual fields within entities
//! - [`OptionalSpec`] - Wraps other specifications to make them optionally null
//! - [`Count`] - Defines how many items should be generated (fixed or range)
//!
//! # JGD Schema Compliance
//!
//! All type specifications in this module are designed to work with JGD schema
//! definitions, ensuring compatibility with the JSON Generator Definition standard.
//! The generators produce output that conforms to the expected schema structure.
//!
//! # Examples
//!
//! ```rust,ignore
//! use jgd_rs::{NumberSpec, JsonGenerator, GeneratorConfig};
//!
//! let mut config = GeneratorConfig::new("EN", Some(42));
//! let number_spec = NumberSpec::new_integer(1.0, 100.0);
//! let generated_value = number_spec.generate(&mut config, None).unwrap();
//! ```

mod array_spec;
mod count;
mod entity;
mod field;
mod jgd;
mod number_spec;
mod optional_spec;
mod utils;

// Re-export all types
pub use array_spec::ArraySpec;
pub use count::*;
pub use entity::Entity;
pub use field::Field;
pub use jgd::Jgd;
pub use number_spec::NumberSpec;
pub use optional_spec::OptionalSpec;
pub use utils::*;

use serde_json::Value;

/// Core trait for all JSON data generators in the JGD system.
///
/// This trait defines the common interface that all type specifications must implement
/// to generate JSON values according to their specific rules. Each implementation
/// should produce values that conform to the JGD schema specification.
///
/// # Design Philosophy
///
/// The `JsonGenerator` trait provides a unified way to generate JSON data from
/// different type specifications. It takes a mutable reference to a `GeneratorConfig`
/// which contains the random number generator, locale settings, and other configuration
/// needed for data generation. It also accepts an optional `LocalConfig` for
/// context-specific generation settings.
///
/// # Arguments
///
/// * `config` - A mutable reference to the generator configuration containing:
///   - Random number generator for deterministic or random generation
///   - Locale settings for locale-specific fake data
///   - Other generation context and settings
/// * `local_config` - An optional mutable reference to local configuration for
///   context-specific generation parameters
///
/// # Returns
///
/// A `Result<serde_json::Value, JgdGeneratorError>` representing the generated data
/// or an error if generation fails. The specific type of JSON value (number, string,
/// array, object, etc.) depends on the implementing type specification.
///
/// # Examples
///
/// ```rust,ignore
/// use jgd_rs::{JsonGenerator, NumberSpec, GeneratorConfig};
/// use serde_json::Value;
///
/// let mut config = GeneratorConfig::new("EN", Some(42));
/// let spec = NumberSpec::new_integer(1.0, 10.0);
///
/// let generated = spec.generate(&mut config, None).unwrap();
/// // generated will be a JSON number between 1 and 10
/// ```
///
/// # Implementation Guidelines
///
/// When implementing this trait:
/// - Ensure generated values conform to the JGD schema specification
/// - Use the provided `GeneratorConfig` for all randomization
/// - Handle edge cases gracefully (e.g., invalid ranges, empty arrays)
/// - Consider performance implications for large data generation
/// - Return appropriate errors for invalid states or parameters
pub trait JsonGenerator {
    /// Generates a JSON value according to the type specification.
    ///
    /// This method should produce a `Result<serde_json::Value, JgdGeneratorError>` that
    /// conforms to the JGD schema specification for the implementing type. The generation
    /// should use the provided configuration for randomization and locale settings.
    ///
    /// # Arguments
    ///
    /// * `config` - Mutable reference to the generator configuration
    /// * `local_config` - Optional mutable reference to local configuration for
    ///   context-specific generation parameters
    ///
    /// # Returns
    ///
    /// A `Result<serde_json::Value, JgdGeneratorError>` containing the generated data
    /// or an error if generation fails
    ///
    /// # Errors
    ///
    /// This method can return a `JgdGeneratorError` if:
    /// - Invalid parameters are provided
    /// - Generation constraints cannot be satisfied
    /// - Internal generation logic encounters an error
    fn generate(&self, config: &mut GeneratorConfig, local_config: Option<&mut LocalConfig>) -> ResultValue;
}

pub type ResultValue = Result<Value, JgdGeneratorError>;