siderust-js 0.1.0

package/qtty-js/qtty/README.md

@@ -0,0 +1,9 @@
+# qtty workspace
+
+Workspace-level documentation now lives under the repository `doc/` tree.
+
+- User overview: [`../doc/users/rust-workspace.md`](../doc/users/rust-workspace.md)
+- Architecture: [`../doc/architecture/repository-layout.md`](../doc/architecture/repository-layout.md)
+- FFI architecture: [`../doc/architecture/qtty-ffi.md`](../doc/architecture/qtty-ffi.md)
+
+This file remains only because Cargo metadata expects a workspace README.

package/qtty-js/qtty/qtty/Cargo.toml

@@ -0,0 +1,41 @@
+[package]
+name = "qtty"
+description = "Strongly typed physical and astronomical quantities."
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+repository.workspace = true
+keywords.workspace = true
+categories.workspace = true
+readme = "README.md"
+documentation = "https://docs.rs/qtty"
+
+[features]
+default = ["std", "cross-unit-ops"]
+alloc = []
+std = ["alloc", "qtty-core/std"]
+cross-unit-ops = ["qtty-core/cross-unit-ops"]
+serde = ["qtty-core/serde"]
+
+# Scalar type support
+scalar-decimal = ["qtty-core/scalar-decimal"]
+scalar-rational = ["qtty-core/scalar-rational"]
+pyo3 = ["qtty-core/pyo3", "dep:pyo3"]
+tiberius = ["qtty-core/tiberius"]
+diesel = ["qtty-core/diesel"]
+
+[dependencies]
+qtty-core = { version = "0.4.0", path = "../qtty-core", default-features = false }
+qtty-derive = { version = "0.4.0", path = "../qtty-derive" }
+pyo3 = { version = "0.28.2", optional = true, features = ["auto-initialize"] }
+
+[dev-dependencies]
+approx = "0.5"
+proptest = "1.4"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+
+[[example]]
+name = "python_integration"
+required-features = ["pyo3"]

package/qtty-js/qtty/qtty/README.md

@@ -0,0 +1,8 @@
+# qtty crate
+
+Centralized documentation lives under the repository `doc/` tree.
+
+- Workspace overview: [`../../doc/users/rust-workspace.md`](../../doc/users/rust-workspace.md)
+- Repository layout: [`../../doc/architecture/repository-layout.md`](../../doc/architecture/repository-layout.md)
+
+This README remains as the crate metadata entrypoint.

package/qtty-js/qtty/qtty/examples/angles.rs

@@ -0,0 +1,14 @@
+//! Angle helpers example: wrapping and separation in a single unit type.
+
+use qtty::{Arcseconds, Degrees};
+
+fn main() {
+    let a = Degrees::new(370.0).wrap_signed();
+    assert_eq!(a.value(), 10.0);
+
+    let s = Degrees::new(45.0).abs_separation(Degrees::new(350.0));
+    assert_eq!(s.value(), 55.0);
+
+    let arcsec: Arcseconds = Degrees::new(1.0).to();
+    assert_eq!(arcsec.value(), 3600.0);
+}

package/qtty-js/qtty/qtty/examples/astronomy.rs

@@ -0,0 +1,17 @@
+//! Astronomy-flavored example using AU, light-years, and an orbital velocity estimate.
+
+use qtty::velocity::Velocity;
+use qtty::{AstronomicalUnits, Days, Kilometer, Kilometers, LightYears, Second, Seconds};
+
+fn main() {
+    let earth_velocity: Velocity<Kilometer, Second> = Velocity::new(29.78);
+    let time = Days::new(1.0);
+    let time_sec: Seconds = time.to();
+    let distance: Kilometers = (earth_velocity * time_sec).to();
+
+    assert!((distance.value() - 2_573_395.2).abs() < 5_000.0);
+
+    let proxima = LightYears::new(4.24);
+    let au: AstronomicalUnits = proxima.to();
+    assert!(au.value() > 200_000.0);
+}

package/qtty-js/qtty/qtty/examples/dimensional_arithmetic.rs

@@ -0,0 +1,83 @@
+//! Dimensional arithmetic examples.
+//!
+//! Demonstrates how the `*` and `/` operators between quantities automatically
+//! produce the correct dimensional result at compile time.
+//!
+//! Run with:
+//! ```sh
+//! cargo run -p qtty --example dimensional_arithmetic
+//! ```
+
+use qtty::area::SquareMeters;
+use qtty::length::{Kilometer, Kilometers, Meter, Meters};
+use qtty::time::{Second, Seconds};
+use qtty::velocity::Velocity;
+use qtty::volume::CubicMeters;
+use qtty::{Per, Quantity, Simplify, Unitless};
+
+fn main() {
+    // ─────────────────────────────────────────────────────────────────────
+    // 1.  Length × Length → Area
+    // ─────────────────────────────────────────────────────────────────────
+    let width = Meters::new(4.0);
+    let height = Meters::new(5.0);
+
+    // The product type is Quantity<Prod<Meter, Meter>>; convert to a named area unit:
+    let area: SquareMeters = (width * height).to();
+    println!("4 m × 5 m = {} m²", area.value());
+    assert!((area.value() - 20.0).abs() < 1e-12);
+
+    // ─────────────────────────────────────────────────────────────────────
+    // 2.  Area × Length → Volume
+    // ─────────────────────────────────────────────────────────────────────
+    let depth = Meters::new(3.0);
+    let vol: CubicMeters = (area * depth).to();
+    println!("20 m² × 3 m = {} m³", vol.value());
+    assert!((vol.value() - 60.0).abs() < 1e-12);
+
+    // ─────────────────────────────────────────────────────────────────────
+    // 3.  Length / Time → Velocity
+    // ─────────────────────────────────────────────────────────────────────
+    let distance = Kilometers::new(100.0);
+    let time = Seconds::new(3600.0);
+    let speed: Velocity<Kilometer, Second> = distance / time;
+    println!("100 km / 3600 s ≈ {:.6} km/s", speed.value());
+    assert!((speed.value() - 100.0 / 3600.0).abs() < 1e-12);
+
+    // ─────────────────────────────────────────────────────────────────────
+    // 4.  Velocity × Time → recovers Length  (via .to())
+    // ─────────────────────────────────────────────────────────────────────
+    let recovered: Kilometers = (speed * time).to();
+    println!(
+        "{:.6} km/s × 3600 s = {} km",
+        speed.value(),
+        recovered.value()
+    );
+    assert!((recovered.value() - 100.0).abs() < 1e-9);
+
+    // ─────────────────────────────────────────────────────────────────────
+    // 5.  Length / Length → dimensionless
+    // ─────────────────────────────────────────────────────────────────────
+    let a = Meters::new(10.0);
+    let b = Meters::new(4.0);
+    let ratio: Quantity<Per<Meter, Meter>> = a / b;
+    // Simplify to a plain f64 via Unitless:
+    let simplified: Quantity<Unitless> = ratio.simplify();
+    println!("10 m / 4 m = {} (dimensionless)", simplified.value());
+    assert!((simplified.value() - 2.5).abs() < 1e-12);
+
+    // ─────────────────────────────────────────────────────────────────────
+    // 6.  Mixed units: km / m keeps the composite type
+    // ─────────────────────────────────────────────────────────────────────
+    let km = Kilometers::new(1.0);
+    let m = Meters::new(500.0);
+    let mixed = km / m; // Quantity<Per<Kilometer, Meter>>
+                        // The value is 1.0/500.0 in "km per m" units:
+    println!("1 km / 500 m = {} km/m", mixed.value());
+    // But in dimensionless terms (since km/m = 1000) the real ratio is 2.0:
+    let pure: Quantity<Unitless> = mixed.to();
+    println!("  → as dimensionless = {}", pure.value());
+    assert!((pure.value() - 2.0).abs() < 1e-12);
+
+    println!("\nAll dimensional arithmetic checks passed!");
+}

package/qtty-js/qtty/qtty/examples/python_integration.rs

@@ -0,0 +1,61 @@
+//! Example demonstrating how `Quantity` fields work in `#[pyclass]` structures
+//! when the `qtty-core` crate is built with the `pyo3` feature.
+
+#[cfg(feature = "pyo3")]
+use pyo3::prelude::*;
+#[cfg(feature = "pyo3")]
+use qtty::Degrees;
+
+#[cfg(feature = "pyo3")]
+#[pyclass]
+pub struct DegreeRange {
+    #[pyo3(get, set)]
+    pub min: Degrees,
+    #[pyo3(get, set)]
+    pub max: Degrees,
+}
+
+#[cfg(feature = "pyo3")]
+#[pymethods]
+impl DegreeRange {
+    #[new]
+    fn new(min: f64, max: f64) -> Self {
+        Self {
+            min: Degrees::new(min),
+            max: Degrees::new(max),
+        }
+    }
+
+    fn span(&self) -> f64 {
+        (self.max - self.min).value()
+    }
+}
+
+/// A minimal pyo3 module initializer to export `DegreeRange` when building as a Python extension.
+#[cfg(feature = "pyo3")]
+#[pymodule]
+fn qtty_examples(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_class::<DegreeRange>()?;
+    Ok(())
+}
+
+fn main() {
+    #[cfg(feature = "pyo3")]
+    {
+        Python::attach(|py| {
+            let range = DegreeRange::new(0.0, 180.0);
+            let obj = Py::new(py, range).expect("create DegreeRange");
+            let span: f64 = obj
+                .bind(py)
+                .call_method0("span")
+                .and_then(|v| v.extract())
+                .expect("call DegreeRange.span()");
+            println!("span = {span}");
+        })
+    }
+
+    #[cfg(not(feature = "pyo3"))]
+    {
+        eprintln!("This example requires `--features pyo3`.");
+    }
+}

package/qtty-js/qtty/qtty/examples/quickstart.rs

@@ -0,0 +1,15 @@
+//! Minimal end-to-end example: convert angles and compute a velocity (length / time).
+
+use qtty::velocity::Velocity;
+use qtty::{Degrees, Kilometer, Kilometers, Radian, Second, Seconds};
+
+fn main() {
+    let a = Degrees::new(180.0);
+    let r = a.to::<Radian>();
+    assert!((r.value() - core::f64::consts::PI).abs() < 1e-12);
+
+    let d = Kilometers::new(1_000.0);
+    let t = Seconds::new(100.0);
+    let v: Velocity<Kilometer, Second> = d / t;
+    assert!((v.value() - 10.0).abs() < 1e-12);
+}

package/qtty-js/qtty/qtty/examples/ratios.rs

@@ -0,0 +1,12 @@
+//! Derived-unit example: ratios and `Simplify` to recover `Unitless`.
+
+use qtty::{Meters, Seconds, Simplify, Unitless};
+
+fn main() {
+    let half = Meters::new(1.0) / Meters::new(2.0);
+    let unitless: qtty::Quantity<Unitless> = half.simplify();
+    assert!((unitless.value() - 0.5).abs() < 1e-12);
+
+    let ratio = Seconds::new(1.0) / Seconds::new(1.0);
+    assert_eq!(ratio.asin(), core::f64::consts::FRAC_PI_2);
+}

package/qtty-js/qtty/qtty/examples/serde_with_unit.rs

@@ -0,0 +1,234 @@
+//! Example demonstrating the serde_with_unit helper module.
+//!
+//! This shows how to use #[serde(with = "qtty_core::serde_with_unit")] to preserve
+//! unit information in serialized data on a per-field basis.
+//!
+//! Run with: cargo run --example serde_with_unit --features serde
+
+#[cfg(feature = "serde")]
+fn main() {
+    use qtty::{Kilometers, Meters, Seconds};
+    use serde::{Deserialize, Serialize};
+    use serde_json;
+
+    println!("=== Using serde_with_unit Helper ===\n");
+
+    // =========================================================================
+    // Example 1: Basic Usage - Mixed Serialization
+    // =========================================================================
+    println!("1. Basic Usage - Per-Field Control:\n");
+
+    #[derive(Serialize, Deserialize, Debug)]
+    struct SensorData {
+        // This field will serialize WITH unit information
+        #[serde(with = "qtty_core::serde_with_unit")]
+        max_range: Meters,
+
+        // This field uses default (compact) serialization
+        current_distance: Meters,
+
+        // Another field with unit info
+        #[serde(with = "qtty_core::serde_with_unit")]
+        timestamp: Seconds,
+    }
+
+    let data = SensorData {
+        max_range: Meters::new(100.0),
+        current_distance: Meters::new(42.5),
+        timestamp: Seconds::new(1702562400.0),
+    };
+
+    let json = serde_json::to_string_pretty(&data).unwrap();
+    println!("Serialized:\n{}\n", json);
+
+    // Deserialize back
+    let restored: SensorData = serde_json::from_str(&json).unwrap();
+    println!("Deserialized successfully!");
+    println!("  max_range: {}", restored.max_range);
+    println!("  current_distance: {}", restored.current_distance);
+    println!("  timestamp: {}\n", restored.timestamp);
+
+    // =========================================================================
+    // Example 2: External API Response
+    // =========================================================================
+    println!("2. Self-Documenting API Response:\n");
+
+    #[derive(Serialize, Deserialize, Debug)]
+    struct WeatherReport {
+        station_id: String,
+
+        #[serde(with = "qtty_core::serde_with_unit")]
+        temperature_celsius: Meters, // Using Meters as example
+
+        #[serde(with = "qtty_core::serde_with_unit")]
+        wind_speed: Meters,
+
+        #[serde(with = "qtty_core::serde_with_unit")]
+        visibility: Kilometers,
+    }
+
+    let report = WeatherReport {
+        station_id: "KJFK".to_string(),
+        temperature_celsius: Meters::new(22.0),
+        wind_speed: Meters::new(5.5),
+        visibility: Kilometers::new(10.0),
+    };
+
+    let json = serde_json::to_string_pretty(&report).unwrap();
+    println!("Weather API Response:\n{}\n", json);
+
+    // =========================================================================
+    // Example 3: Configuration File
+    // =========================================================================
+    println!("3. Configuration File Format:\n");
+
+    #[derive(Serialize, Deserialize, Debug)]
+    struct RobotConfig {
+        name: String,
+
+        // Document the units in config files
+        #[serde(with = "qtty_core::serde_with_unit")]
+        max_speed: Meters,
+
+        #[serde(with = "qtty_core::serde_with_unit")]
+        safe_distance: Meters,
+
+        #[serde(with = "qtty_core::serde_with_unit")]
+        timeout: Seconds,
+
+        // Internal value doesn't need unit documentation
+        calibration_offset: Meters,
+    }
+
+    let config = RobotConfig {
+        name: "R2D2".to_string(),
+        max_speed: Meters::new(2.5),
+        safe_distance: Meters::new(0.5),
+        timeout: Seconds::new(30.0),
+        calibration_offset: Meters::new(0.001),
+    };
+
+    let json = serde_json::to_string_pretty(&config).unwrap();
+    println!("Robot Configuration:\n{}\n", json);
+
+    // =========================================================================
+    // Example 4: Unit Validation on Deserialization
+    // =========================================================================
+    println!("4. Unit Validation:\n");
+
+    // Valid JSON with unit info
+    #[derive(Serialize, Deserialize, Debug)]
+    struct SingleValue {
+        #[serde(with = "qtty_core::serde_with_unit")]
+        distance: Meters,
+    }
+
+    let valid_json = r#"{"distance": {"value": 100.0, "unit": "m"}}"#;
+    let data: SingleValue =
+        serde_json::from_str(valid_json).expect("Should deserialize with matching unit");
+    println!("✓ Valid JSON with correct unit: {}", data.distance);
+
+    // Missing unit field (backwards compatible)
+    let no_unit_json = r#"{"distance": {"value": 50.0}}"#;
+    let data2: SingleValue =
+        serde_json::from_str(no_unit_json).expect("Should work without unit field");
+    println!("✓ Valid JSON without unit field: {}", data2.distance);
+
+    // Wrong unit (will fail validation)
+    let invalid_json = r#"{"distance": {"value": 100.0, "unit": "kg"}}"#;
+    match serde_json::from_str::<SingleValue>(invalid_json) {
+        Ok(_) => println!("✗ Unexpected success with wrong unit"),
+        Err(e) => println!("✓ Correctly rejected wrong unit: {}", e),
+    }
+    println!();
+
+    // =========================================================================
+    // Example 5: Collections with Mixed Serialization
+    // =========================================================================
+    println!("5. Collections:\n");
+
+    #[derive(Serialize, Deserialize, Debug)]
+    struct Measurement {
+        id: u32,
+
+        #[serde(with = "qtty_core::serde_with_unit")]
+        value: Meters,
+    }
+
+    let measurements = vec![
+        Measurement {
+            id: 1,
+            value: Meters::new(10.0),
+        },
+        Measurement {
+            id: 2,
+            value: Meters::new(20.0),
+        },
+        Measurement {
+            id: 3,
+            value: Meters::new(30.0),
+        },
+    ];
+
+    let json = serde_json::to_string_pretty(&measurements).unwrap();
+    println!("Measurement Array:\n{}\n", json);
+
+    // =========================================================================
+    // Example 6: Nested Structures
+    // =========================================================================
+    println!("6. Nested Structures:\n");
+
+    #[derive(Serialize, Deserialize, Debug)]
+    struct Location {
+        name: String,
+        coordinates: Coordinates,
+    }
+
+    #[derive(Serialize, Deserialize, Debug)]
+    struct Coordinates {
+        #[serde(with = "qtty_core::serde_with_unit")]
+        x: Meters,
+
+        #[serde(with = "qtty_core::serde_with_unit")]
+        y: Meters,
+
+        #[serde(with = "qtty_core::serde_with_unit")]
+        z: Meters,
+    }
+
+    let location = Location {
+        name: "Observatory".to_string(),
+        coordinates: Coordinates {
+            x: Meters::new(100.0),
+            y: Meters::new(200.0),
+            z: Meters::new(50.0),
+        },
+    };
+
+    let json = serde_json::to_string_pretty(&location).unwrap();
+    println!("Nested structure:\n{}\n", json);
+
+    // =========================================================================
+    // Summary
+    // =========================================================================
+    println!("=== Summary ===\n");
+    println!("✓ Use #[serde(with = \"qtty_core::serde_with_unit\")] for:");
+    println!("  • External/public APIs");
+    println!("  • Configuration files");
+    println!("  • Self-documenting data");
+    println!("  • When consumers might not know the units");
+    println!();
+    println!("✓ Use default serialization (no attribute) for:");
+    println!("  • Internal APIs");
+    println!("  • Performance-critical code");
+    println!("  • Large datasets");
+    println!("  • When types provide sufficient documentation");
+    println!();
+    println!("✓ Mix both in the same struct as needed!");
+}
+
+#[cfg(not(feature = "serde"))]
+fn main() {
+    println!("This example requires the 'serde' feature.");
+    println!("Run with: cargo run --example serde_with_unit --features serde");
+}

package/qtty-js/qtty/qtty/examples/serialization.rs

@@ -0,0 +1,141 @@
+//! Examples of serializing and deserializing quantities.
+//!
+//! This example demonstrates how to use serde to serialize and deserialize
+//! physical quantities to/from JSON and other formats.
+//!
+//! To run this example with serde support:
+//! ```bash
+//! cargo run --example serialization --features serde
+//! ```
+
+#[cfg(feature = "serde")]
+fn main() {
+    use qtty::velocity::Velocity;
+    use qtty::{Kilograms, Kilometers, Meter, Meters, Second, Seconds, Watts};
+    use serde::{Deserialize, Serialize};
+    use serde_json;
+
+    println!("=== Quantity Serialization Examples ===\n");
+
+    // Example 1: Basic serialization to JSON
+    println!("1. Basic JSON Serialization:");
+    let distance = Meters::new(42.5);
+    let json = serde_json::to_string(&distance).unwrap();
+    println!("   Distance: {} → JSON: {}", distance, json);
+
+    let time = Seconds::new(std::f64::consts::PI);
+    let json = serde_json::to_string(&time).unwrap();
+    println!("   Time: {} → JSON: {}", time, json);
+
+    let mass = Kilograms::new(100.0);
+    let json = serde_json::to_string(&mass).unwrap();
+    println!("   Mass: {} → JSON: {}", mass, json);
+    println!();
+
+    // Example 2: Deserialization from JSON
+    println!("2. JSON Deserialization:");
+    let json_distance = "42.5";
+    let distance = serde_json::from_str::<Meters>(json_distance).unwrap();
+    println!("   JSON: {} → {}", json_distance, distance);
+
+    let json_time = "3.14";
+    let time = serde_json::from_str::<Seconds>(json_time).unwrap();
+    println!("   JSON: {} → {}", json_time, time);
+    println!();
+
+    // Example 3: Round-trip serialization
+    println!("3. Round-trip Serialization:");
+    let original_distance = Meters::new(299792458.0);
+    let original_time = Seconds::new(1.0);
+    let original: Velocity<Meter, Second> = original_distance / original_time;
+    let json = serde_json::to_string(&original).unwrap();
+    let restored = serde_json::from_str::<Velocity<Meter, Second>>(&json).unwrap();
+    println!("   Original: {}", original);
+    println!("   JSON: {}", json);
+    println!("   Restored: {}", restored);
+    println!(
+        "   Equal: {}",
+        (original.value() - restored.value()).abs() < 1e-6
+    );
+    println!();
+
+    // Example 4: Serializing structs containing quantities
+    #[derive(Serialize, Deserialize, Debug)]
+    struct Measurement {
+        distance: Meters,
+        time: Seconds,
+        mass: Kilograms,
+    }
+
+    println!("4. Serializing Structs with Quantities:");
+    let measurement = Measurement {
+        distance: Meters::new(100.0),
+        time: Seconds::new(9.58),
+        mass: Kilograms::new(75.0),
+    };
+
+    let json = serde_json::to_string_pretty(&measurement).unwrap();
+    println!("   Struct to JSON:\n{}", json);
+
+    let restored: Measurement = serde_json::from_str(&json).unwrap();
+    println!("   Restored: {:?}", restored);
+    println!();
+
+    // Example 5: Serializing collections of quantities
+    println!("5. Serializing Collections:");
+    let distances = vec![Meters::new(10.0), Meters::new(20.0), Meters::new(30.0)];
+    let json = serde_json::to_string(&distances).unwrap();
+    println!("   Vec of distances → JSON: {}", json);
+
+    let restored: Vec<Meters> = serde_json::from_str(&json).unwrap();
+    println!("   Restored: {:?}", restored);
+    println!();
+
+    // Example 6: Using pretty printing
+    println!("6. Pretty-printed JSON:");
+    #[derive(Serialize, Deserialize)]
+    struct Experiment {
+        name: String,
+        height: Meters,
+        duration: Seconds,
+        velocity: Velocity<Meter, Second>,
+    }
+
+    let experiment = Experiment {
+        name: "Free Fall Test".to_string(),
+        height: Meters::new(100.0),
+        duration: Seconds::new(4.52),
+        velocity: Meters::new(44.3) / Seconds::new(1.0),
+    };
+
+    let json = serde_json::to_string_pretty(&experiment).unwrap();
+    println!("{}", json);
+    println!();
+
+    // Example 7: Handling conversion before serialization
+    println!("7. Converting Units Before Serialization:");
+    let distance_km = Kilometers::new(5.0);
+    // Convert to base unit (meter) before serializing
+    let distance_m = distance_km.to::<Meter>();
+    let json = serde_json::to_string(&distance_m).unwrap();
+    println!("   {} → {} → JSON: {}", distance_km, distance_m, json);
+    println!();
+
+    // Example 8: Derived quantities
+    println!("8. Serializing Derived Quantities:");
+    let power = Watts::new(1500.0);
+    let json = serde_json::to_string(&power).unwrap();
+    println!("   Power: {} → JSON: {}", power, json);
+
+    println!("=== Important Notes ===");
+    println!("• Quantities serialize as bare f64 values (the numeric value only)");
+    println!("• Unit information is NOT preserved in serialization");
+    println!("• You must specify the correct unit type when deserializing");
+    println!("• Always use the base SI unit for consistency when serializing");
+}
+
+#[cfg(not(feature = "serde"))]
+fn main() {
+    println!("This example requires the 'serde' feature.");
+    println!("Run with: cargo run --example serialization --features serde");
+}