siderust-js 0.1.0

package/qtty-js/README.md

@@ -0,0 +1,132 @@
+# qtty-js workspace
+
+JavaScript and WebAssembly bindings for
+[qtty](./qtty/README.md), the Siderust physical quantities and unit conversion
+library.
+
+This repository is the publishable JS workspace. It contains the npm packages,
+the thin Rust transport layers for Node and Web, and the vendored `qtty`
+submodule that provides the canonical conversion registry and unit model.
+
+## Packages
+
+| Package | Target | Status | Notes |
+| --- | --- | --- | --- |
+| [`@siderust/qtty`](./qtty-node/README.md) | Node.js | `0.1.0` | Native addon built with `napi-rs`; includes `@siderust/qtty/units` factories. |
+| `@siderust/qtty-web` | Browsers / bundlers | `0.1.0` | WebAssembly build with `wasm-bindgen`; requires `await init()` before use. |
+
+The Rust crates under `qtty-node/` and `qtty-web/` are transport layers only.
+All unit metadata and conversion semantics come from the [`qtty`](./qtty)
+submodule through `qtty-ffi`.
+
+## Repository layout
+
+```text
+qtty-js/
+├── qtty/         Vendored Rust workspace (canonical units, FFI, docs)
+├── qtty-node/    Node package: @siderust/qtty
+├── qtty-web/     Browser package: @siderust/qtty-web
+└── scripts/      CI helpers for the Node package
+```
+
+## What ships in 0.1.0
+
+- A Node package with `Quantity`, `DerivedQuantity`, conversion helpers,
+  compatibility checks, JSON-friendly serialization helpers, and a typed `Unit`
+  map.
+- Node-side unit factories under `@siderust/qtty/units` for arithmetic-style
+  construction such as `Kilometers(3.2)` or `Degrees(180)`.
+- A browser/WASM package exposing the same core quantity model with explicit
+  asynchronous initialization via `init()`.
+- TypeScript declarations for both packages matching the current runtime
+  surface.
+- Node examples, tests, and CI for format, lint, build, test, and coverage.
+
+## Install
+
+### Node.js
+
+```bash
+npm install @siderust/qtty
+```
+
+```js
+const { Quantity, convert, Unit } = require('@siderust/qtty');
+
+const distance = new Quantity(1500, Unit.Meter);
+console.log(distance.to(Unit.Kilometer).value); // 1.5
+console.log(convert(2, Unit.Hour, Unit.Minute)); // 120
+```
+
+### Browser / WebAssembly
+
+```bash
+npm install @siderust/qtty-web
+```
+
+```js
+import { init, Quantity, Unit } from '@siderust/qtty-web';
+
+await init();
+
+const angle = new Quantity(180, Unit.Degree);
+console.log(angle.to(Unit.Radian).value);
+```
+
+## Development
+
+Clone the repository with submodules so the vendored Rust workspace is present:
+
+```bash
+git clone --recurse-submodules git@github.com:Siderust/qtty-js.git
+cd qtty-js
+```
+
+If you already cloned without submodules:
+
+```bash
+git submodule update --init --recursive
+```
+
+### Node package workflow
+
+```bash
+cd qtty-node
+npm ci
+npm run build:debug
+npm test
+```
+
+The repository also exposes CI helpers:
+
+```bash
+./scripts/ci.sh all
+```
+
+### Web package workflow
+
+`qtty-web` uses `wasm-pack`:
+
+```bash
+cd qtty-web
+wasm-pack build --target web --out-dir pkg --release --scope siderust
+```
+
+## Versioning notes
+
+The npm packages in this repository start at `0.1.0`, while the Rust transport
+crate inside [`qtty-node`](./qtty-node/Cargo.toml) still tracks the native layer
+version (`0.4.0`). That is intentional: the JavaScript public release line and
+the internal Rust crate line are versioned independently.
+
+## Related documentation
+
+- [`qtty-node/README.md`](./qtty-node/README.md) for the Node package API and
+  examples.
+- [`qtty/README.md`](./qtty/README.md) for the vendored Rust workspace.
+- [`qtty/CHANGELOG.md`](./qtty/CHANGELOG.md) for backend/library changes that
+  feed these bindings.
+
+## License
+
+AGPL-3.0. See [LICENSE](./LICENSE).

package/qtty-js/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "qtty-js",
+  "version": "0.1.0",
+  "description": "Typesafe unit measurments",
+  "homepage": "https://github.com/Siderust/qtty-js#readme",
+  "bugs": {
+    "url": "https://github.com/Siderust/qtty-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Siderust/qtty-js.git"
+  },
+  "license": "AGPL-3.0-or-later",
+  "author": "VPRamon",
+  "type": "commonjs",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

package/qtty-js/qtty/.github/workflows/ci.yml

@@ -0,0 +1,155 @@
+name: qtty CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+  checks: write
+  pull-requests: write   # needed to post PR comments
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  check:
+    name: Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - run: cargo check --all-targets
+
+  fmt:
+    name: Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt
+      - run: cargo fmt --check
+
+  clippy:
+    name: Clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - run: cargo clippy --all-targets -- -D warnings
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - run: cargo test --all-targets
+      - run: cargo test --doc
+
+  no-cross-unit-ops:
+    name: No Cross-Unit Ops
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Validate conversions and eq_unit/cmp_unit in reduced mode
+        run: cargo test -p qtty-core --test core --test no_cross_unit_ops --no-default-features --features std
+      - name: Ensure direct cross-unit operators are disabled in reduced mode
+        run: |
+          tmpdir="$(mktemp -d)"
+          cat > "$tmpdir/Cargo.toml" <<EOF
+          [package]
+          name = "no-cross-unit-ops-check"
+          version = "0.0.0"
+          edition = "2021"
+
+          [dependencies]
+          qtty-core = { path = "$PWD/qtty-core", default-features = false, features = ["std"] }
+          EOF
+          mkdir -p "$tmpdir/src"
+          cat > "$tmpdir/src/main.rs" <<'EOF'
+          use qtty_core::length::{Kilometers, Meters};
+
+          fn main() {
+              let km = Kilometers::new(1.0);
+              let m = Meters::new(500.0);
+              let _ = km > m;
+          }
+          EOF
+
+          if cargo check --manifest-path "$tmpdir/Cargo.toml"; then
+            echo "cross-unit operators unexpectedly compiled with cross-unit-ops disabled"
+            exit 1
+          fi
+
+  coverage:
+    name: Test & Coverage
+    if: ${{ github.event_name == 'push' || github.event.pull_request.draft == false }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Rust (nightly + llvm-tools)
+        uses: dtolnay/rust-toolchain@v1
+        with:
+          toolchain: nightly
+          components: llvm-tools-preview
+
+      - name: Install cargo-llvm-cov
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-llvm-cov
+
+      # Run tests once and collect coverage data (no report yet)
+      - name: Coverage (run, no report)
+        run: cargo +nightly llvm-cov --workspace --all-features --doctests --no-report
+
+      # Produce machine-readable + human-readable reports
+      - name: Coverage (Cobertura XML)
+        run: cargo +nightly llvm-cov report --cobertura --output-path coverage.xml
+
+      - name: Coverage (HTML)
+        run: cargo +nightly llvm-cov report --html --output-dir coverage_html
+
+      # Put a nice table + badge into the PR Checks "Summary" tab
+      - name: Build coverage summary (Markdown)
+        uses: irongut/CodeCoverageSummary@v1.3.0
+        with:
+          filename: coverage.xml
+          badge: true
+          format: markdown
+          output: file
+
+      - name: Publish to Job Summary
+        run: cat code-coverage-results.md >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Post coverage as PR comment
+        if: github.event_name == 'pull_request'
+        uses: mshick/add-pr-comment@v2
+        with:
+          message-path: code-coverage-results.md
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      # Gate: fail if total LINE coverage < 95% (no extra test run needed)
+      # feature_diesel.rs requires a live SQL backend and intentionally excluded from coverage
+      - name: Coverage gate (≥95% lines)
+        run: cargo +nightly llvm-cov --workspace --all-features --doctests --no-run --ignore-filename-regex "feature_diesel" --fail-under-lines 95
+
+      - name: Upload coverage HTML
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-html
+          path: coverage_html
+          retention-days: 7

package/qtty-js/qtty/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+All notable changes to the vendored Rust workspace are documented here.
+
+Documentation references live under [`../doc/developers/changelog.md`](../doc/developers/changelog.md).
+
+
+## [0.4.0] - 2026-02-26
+
+### Added
+- Implemented `Display`, `LowerExp`, and `UpperExp` delegation for `Quantity<U, S>` so standard Rust format annotations (precision, scientific notation) are respected by all unit types.
+- Exposed a new FFI function `qtty_quantity_format(qtty_quantity_t, precision, flags, buf, buf_len)` plus format flag constants `QTTY_FMT_DEFAULT`, `QTTY_FMT_LOWER_EXP`, and `QTTY_FMT_UPPER_EXP` for C consumers to format quantities from Rust with the same options as Rust's formatters.
+- Added C++ convenience: `qtty::Quantity<UnitTag>::format(int precision, uint32_t flags)` that calls the FFI formatter, and a C++20 `std::formatter` specialization to integrate with `std::format` when available.
+- Added comprehensive C++ tests covering streaming `operator<<`, `format()`, and scientific/precision formatting modes.
+
+### Changed
+- cbindgen/header generation: `qtty-ffi` build now gracefully skips automatic cbindgen expansion on stable toolchains (nightly required for macro expansion); the shipped `qtty_ffi.h` is updated to include the new formatter API and constants.
+
+### Fixed
+- Corrected `Display` implementations to delegate formatting to the inner scalar so `{:.N}`, `{:e}`, and related annotations behave as expected for `Quantity` values.
+- Adjusted C++ helpers and tests to match C++ stream precision semantics and to ensure `format()` mirrors specified precision/flags.
+
+## [0.3.1] - 2026-02-24
+
+### Added
+- New `qtty` crate feature `alloc` for heap-backed helpers in `no_std` builds. (see #10)
+- Integration compile checks for `qtty::qtty_vec!` across `std`, `no_std + alloc`, and pure `no_std` modes. (see #10)
+- New integer scalar facade modules `qtty::i8`, `qtty::i16`, and `qtty::i128`, mirroring the unit aliases available in `qtty::i32`. (see #11)
+- New `cross-unit-ops` feature in `qtty-core` and `qtty` (enabled by default) to gate generation of direct cross-unit comparison operator impls (`==`, `<`, etc.). (see #15)
+- New reduced-mode CI profile (`No Cross-Unit Ops`) plus targeted compile checks validating `eq_unit`/`cmp_unit` and ensuring direct cross-unit operators are disabled when the feature is off. (see #15)
+- Documented compile-time benchmark commands (`cargo +nightly -Z timings`) for comparing default and reduced-mode builds. (see #15)
+- FFI JSON serialization: New FFI functions for serializing and deserializing `QttyQuantity`/`QttyDerivedQuantity` to/from JSON:
+  - `qtty_quantity_to_json_value` / `qtty_quantity_from_json_value`
+  - `qtty_quantity_to_json` / `qtty_quantity_from_json`
+  - `qtty_derived_to_json` / `qtty_derived_from_json`
+
+
+## [0.3.0] - 2026-02-09
+
+### Added
+- Added support for operations with Rust built-in numeric types, improving ergonomics when combining `Quantity` values with primitive scalars.
+- Added `Iterator::sum` support for `Quantity`, including ergonomic accumulation into `f64` from iterators of `Quantity<_, f64>` (owned or borrowed items).
+- Full dimensional arithmetic support using compile-time exponent math (`Dim`, `DimMul`, `DimDiv`) powered by `typenum`.
+- New product unit type `Prod<A, B>` to represent unit multiplication (`Length * Length`, `Area * Length`, etc.).
+- New `area` unit module with metric, land, and imperial/US units (for example `SquareMeter`, `Hectare`, `Acre`).
+- New `volume` unit module with metric cubic units, liter-family units, and imperial/US units (for example `CubicMeter`, `Liter`, `UsGallon`).
+- New `qtty` example `dimensional_arithmetic` demonstrating compile-time dimensional composition and conversions.
+- `Quantity::eq_unit` and `Quantity::cmp_unit` helpers for comparing values across different units in the same dimension.
+- Cross-unit comparison operator support (`==`, `!=`, `<`, `>`, `<=`, `>=`) via `impl_unit_conversions!`, with unit conversion applied before comparison.
+- Expanded `qtty-core` comparison tests covering same-unit ordering, scalar ordering, cross-unit comparisons, NaN behavior, and integer `Eq`/`Ord` use cases.
+- `Quantity::mean` helper to compute the arithmetic midpoint between two values of the same quantity type (including integer scalar support).
+- New exported `qtty::qtty_vec!` macro for building typed quantity arrays and `Vec`s directly from scalar literals.
+
+### Changed
+- Division and multiplication now compose dimensions generically at the type level, so multiplied quantities produce `Quantity<Prod<...>>` and can be converted to named units with `.to()`.
+- Core/base dimensions are now unified under the new generic `Dim<...>` model, with backward-compatible aliases for `DivDim` and new `MulDim`.
+- Public exports now include area/volume modules and additional dimension aliases from `qtty-core` and the `qtty` facade.
+- `Quantity` ordering/equality trait implementations were refined: `PartialOrd` is now implemented explicitly (same-unit and scalar comparisons), and `Eq`/`Ord` are enabled when the scalar type supports total equality/ordering.
+- Unit display symbols were standardized to canonical scientific notation across affected units (for example `Degree` now renders as `°`, `Radian` as `rad`, and SI symbols like `km`/`μm` are used consistently).
+
+## [0.2.2] - 2026-01-13
+
+### Added
+- `qtty-core` optional `diesel` feature with `Quantity` SQL mapping, query integration, and examples.
+- `qtty-core` optional `tiberius` feature with SQL Server `ToSql`/`FromSql` support for `Quantity`.
+- `qtty-core` optional `pyo3` feature with `Quantity` conversions to/from Python floats.
+- `qtty_core::serde_with_unit` helper for serializing quantities with unit symbols.
+- New `qtty-core` tests covering core, Diesel, PyO3, Serde, and Tiberius integrations.
+
+### Changed
+- `qtty-core` internals split into feature-gated modules with updated docs and examples.
+
+## [0.2.1] - 2025-12-22
+
+### Added
+- Optional `python` feature for `qtty-ffi` that exposes `UnitId` as a PyO3 `pyclass` with pickle support, enabling Python consumers alongside C.
+- Generated unit symbol lookups and new `UnitId::symbol()` accessor for retrieving canonical unit symbols from FFI.
+- Convenience APIs on `QttyQuantity` for dimension/compatibility queries, conversions, and basic arithmetic on FFI quantities.
+- `QttyDerivedQuantity` FFI type for compound quantities (numerator/denominator) with conversion and scalar helpers (e.g., velocities).
+
+### Changed
+- `qtty-ffi` build tooling now emits symbol tables and uses the updated cbindgen (0.29.2) plus parser deps to support Python-aware builds.
+
+## [0.2.0] - 2025-12-14
+
+### Added
+- Workspace split into crates: `qtty` (facade), `qtty-core` (types + units), `qtty-derive` (proc-macro).
+- Feature flags: `std` (default) and optional `serde` for `Quantity<U>`.
+- `no_std` support in `qtty-core` (uses `libm` for floating-point math not in `core`).
+- Predefined unit modules under `qtty-core::units` (angular, time, length, mass, power, velocity, frequency, unitless).
+- **Serde with unit information**: New `qtty_core::serde_with_unit` helper module for serializing quantities with unit symbols. Use `#[serde(with = "qtty_core::serde_with_unit")]` on fields to preserve unit information in JSON/serialized data (e.g., `{"value": 100.0, "unit": "m"}`). Includes unit validation on deserialization. Default serialization remains compact (bare `f64` value).
+- **Length**: Extensive new SI-prefixed meter units (yoctometer through yottameter) and additional units (fathom, nautical mile, light year, parsec, etc.).
+- **Mass**: Full SI prefix ladder for gram (yoctogram through yottagram), additional units (ton, metric ton, tonne), and nominal astronomical masses (Earth, Jupiter, Sun).
+- **Power**: Complete SI prefix ladder for watt (yoctowatt through yottawatt), erg per second, metric horsepower, electric horsepower, and solar luminosity.
+- **Time**: Full SI submultiples (attosecond through decisecond) and multiples (decasecond through terasecond), additional civil units (fortnight, decade, millennium), Julian conventions, and astronomical mean units (sidereal day/year, synodic month).
+- **Velocity**: Generic `Velocity<Length, Time>` type for composing any length/time unit pair.
+- **Frequency**: Generic `Frequency<Angle, Time>` type for composing any angle/time unit pair.
+
+### Changed
+- Documentation rewrite for docs.rs (crate docs, READMEs, examples).
+- **Time module**: Canonical scaling unit changed from `Day` to `Second` (SI base unit). All time units now express ratios in seconds.
+- **Unit symbols**: Updated for consistency (e.g., `Second::SYMBOL` changed from `"sec"` to `"s"`).
+- **Velocity and Frequency**: Refactored to use generic parameterized types instead of specific aliases (e.g., `Velocity<Kilometer, Second>` instead of `KilometersPerSecond`).
+- Import organization in examples for improved clarity and consistency.
+- Conversion constants and ratios updated across all unit modules for accuracy and consistency.
+ - **Unitless refactor**: `Unitless` changed from a `pub type Unitless = f64` alias to a proper zero-sized marker type (`pub struct Unitless;`). The `Unit` impl for `Unitless` remains (`RATIO = 1.0`, `Dim = Dimensionless`, `SYMBOL = ""`) while removing the implicit `Unit` implementation for `f64`. API ergonomics preserved: `Quantity<Unitless>` display/From conversions/Simplify behavior unchanged. Updated docs, tests, and examples accordingly.
+
+### Deprecated
+- `define_unit!` is retained for internal use and backward compatibility; new units in `qtty-core` use `#[derive(Unit)]`.
+- Specific velocity type aliases (e.g., `MetersPerSecond`, `KilometersPerSecond`) in favor of generic `Velocity<N, D>` type.
+- Specific frequency type aliases (e.g., `RadiansPerSecond`, `DegreesPerDay`) in favor of generic `Frequency<N, D>` type.
+
+### Fixed
+- `qtty` feature flags now correctly control `qtty-core` defaults (including `no_std` builds).
+- Improved type safety and consistency across velocity and frequency unit definitions.
+
+
+## [0.0.0] - 2025-09-01
+
+- Migration from Siderust