siderust-js 0.1.0

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

@@ -0,0 +1,21 @@
+[package]
+name = "qtty-web"
+version = "1.0.0"
+edition = "2021"
+authors = ["VPRamon <vallespuigramon@gmail.com>"]
+license = "AGPL-3.0"
+repository = "https://github.com/Siderust/qtty"
+description = "Browser/WASM bindings for qtty — physical quantities and unit conversions in the browser"
+readme = "README.md"
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+qtty-ffi = { path = "../qtty/qtty-ffi" }
+serde_json = "1.0"
+wasm-bindgen = "0.2"
+serde = { version = "1.0", features = ["derive"] }
+serde-wasm-bindgen = "0.6"
+js-sys = "0.3"
+console_error_panic_hook = "0.1"

package/qtty-js/qtty-web/index.d.ts

@@ -0,0 +1,140 @@
+/* eslint-disable */
+
+// ─── Initialisation ────────────────────────────────────────────────────────
+/**
+ * Initialise the WASM module.  Must be called (and `await`-ed) before any
+ * other function in this package.
+ *
+ * ```js
+ * import { init, Quantity } from '@siderust/qtty-web';
+ * await init();
+ * const d = new Quantity(1000, 'Meter');
+ * ```
+ */
+export function init(
+  module_or_path?: RequestInfo | URL | Response | BufferSource | WebAssembly.Module
+): Promise<void>;
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+/** Plain JSON-serializable representation of a quantity. */
+export interface QuantityJson {
+  value: number;
+  unit: string;
+}
+
+/** Plain JSON-serializable representation of a derived quantity. */
+export interface DerivedQuantityJson {
+  value: number;
+  numerator: string;
+  denominator: string;
+}
+
+/** Metadata about a single unit returned by `listUnits`. */
+export interface UnitInfo {
+  name: string;
+  symbol: string;
+  dimension: string;
+}
+
+// ─── Quantity ──────────────────────────────────────────────────────────────
+
+export class Quantity {
+  constructor(value: number, unit: string);
+  get value(): number;
+  get unit(): string;
+  get symbol(): string;
+  get dimension(): string;
+  to(unit: string): Quantity;
+  compatible(other: Quantity): boolean;
+  add(other: Quantity): Quantity;
+  sub(other: Quantity): Quantity;
+  mul(scalar: number): Quantity;
+  div(scalar: number): Quantity;
+  neg(): Quantity;
+  format(precision?: number | null): string;
+  toJson(): QuantityJson;
+  toString(): string;
+}
+
+// ─── DerivedQuantity ──────────────────────────────────────────────────────
+
+export class DerivedQuantity {
+  constructor(value: number, numerator: string, denominator: string);
+  get value(): number;
+  get numerator(): string;
+  get denominator(): string;
+  get symbol(): string;
+  to(numerator: string, denominator: string): DerivedQuantity;
+  mul(scalar: number): DerivedQuantity;
+  div(scalar: number): DerivedQuantity;
+  neg(): DerivedQuantity;
+  format(precision?: number | null): string;
+  toJson(): DerivedQuantityJson;
+  toString(): string;
+}
+
+// ─── Free functions ───────────────────────────────────────────────────────
+
+export function convert(value: number, fromUnit: string, toUnit: string): number;
+export function isCompatible(unitA: string, unitB: string): boolean;
+export function unitDimension(unit: string): string;
+export function unitSymbol(unit: string): string;
+export function isValidUnit(unit: string): boolean;
+export function ffiVersion(): number;
+export function listUnits(): UnitInfo[];
+
+// ─── Unit const map ──────────────────────────────────────────────────────────
+
+/** Union of every registered unit name. */
+export type UnitName =
+  // Length
+  | 'PlanckLength' | 'Yoctometer' | 'Zeptometer' | 'Attometer' | 'Femtometer'
+  | 'Picometer' | 'Nanometer' | 'Micrometer' | 'Millimeter' | 'Centimeter'
+  | 'Decimeter' | 'Meter' | 'Decameter' | 'Hectometer' | 'Kilometer'
+  | 'Megameter' | 'Gigameter' | 'Terameter' | 'Petameter' | 'Exameter'
+  | 'Zettameter' | 'Yottameter' | 'BohrRadius' | 'ClassicalElectronRadius'
+  | 'ElectronReducedComptonWavelength' | 'AstronomicalUnit' | 'LightYear'
+  | 'Parsec' | 'Kiloparsec' | 'Megaparsec' | 'Gigaparsec'
+  | 'Inch' | 'Foot' | 'Yard' | 'Mile' | 'Link' | 'Fathom' | 'Rod' | 'Chain'
+  | 'NauticalMile' | 'NominalLunarRadius' | 'NominalLunarDistance'
+  | 'NominalEarthPolarRadius' | 'NominalEarthRadius' | 'NominalEarthEquatorialRadius'
+  | 'EarthMeridionalCircumference' | 'EarthEquatorialCircumference'
+  | 'NominalJupiterRadius' | 'NominalSolarRadius' | 'NominalSolarDiameter'
+  // Time
+  | 'Attosecond' | 'Femtosecond' | 'Picosecond' | 'Nanosecond' | 'Microsecond'
+  | 'Millisecond' | 'Centisecond' | 'Decisecond' | 'Second' | 'Decasecond'
+  | 'Hectosecond' | 'Kilosecond' | 'Megasecond' | 'Gigasecond' | 'Terasecond'
+  | 'Minute' | 'Hour' | 'Day' | 'Week' | 'Fortnight' | 'Year' | 'Decade'
+  | 'Century' | 'Millennium' | 'JulianYear' | 'JulianCentury'
+  | 'SiderealDay' | 'SynodicMonth' | 'SiderealYear'
+  // Angle
+  | 'Milliradian' | 'Radian' | 'MicroArcsecond' | 'MilliArcsecond'
+  | 'Arcsecond' | 'Arcminute' | 'Degree' | 'Gradian' | 'Turn' | 'HourAngle'
+  // Mass
+  | 'Yoctogram' | 'Zeptogram' | 'Attogram' | 'Femtogram' | 'Picogram'
+  | 'Nanogram' | 'Microgram' | 'Milligram' | 'Centigram' | 'Decigram'
+  | 'Gram' | 'Decagram' | 'Hectogram' | 'Kilogram' | 'Megagram' | 'Gigagram'
+  | 'Teragram' | 'Petagram' | 'Exagram' | 'Zettagram' | 'Yottagram'
+  | 'Grain' | 'Ounce' | 'Pound' | 'Stone' | 'ShortTon' | 'LongTon'
+  | 'Carat' | 'Tonne' | 'AtomicMassUnit' | 'SolarMass'
+  // Power
+  | 'Yoctowatt' | 'Zeptowatt' | 'Attowatt' | 'Femtowatt' | 'Picowatt'
+  | 'Nanowatt' | 'Microwatt' | 'Milliwatt' | 'Deciwatt' | 'Watt' | 'Decawatt'
+  | 'Hectowatt' | 'Kilowatt' | 'Megawatt' | 'Gigawatt' | 'Terawatt' | 'Petawatt'
+  | 'Exawatt' | 'Zettawatt' | 'Yottawatt'
+  | 'ErgPerSecond' | 'HorsepowerMetric' | 'HorsepowerElectric' | 'SolarLuminosity';
+
+/**
+ * Const map of all registered unit names (available after `init()`).
+ *
+ * `Unit.Meter === 'Meter'` — each key equals its own name.
+ *
+ * ```ts
+ * import { init, Quantity, Unit } from '@siderust/qtty-web';
+ * await init();
+ * const d  = new Quantity(1000, Unit.Meter);
+ * const km = d.to(Unit.Kilometer);
+ * ```
+ */
+export declare const Unit: { readonly [K in UnitName]: K };

package/qtty-js/qtty-web/index.js

@@ -0,0 +1,20 @@
+/**
+ * @siderust/qtty-web — Physical quantities and unit conversions for the browser.
+ *
+ * Call `init()` (and `await` it) before using any other export.
+ *
+ * @module @siderust/qtty-web
+ */
+
+export { init, Unit } from './lib/backend.js';
+export { Quantity } from './lib/Quantity.js';
+export { DerivedQuantity } from './lib/DerivedQuantity.js';
+export {
+  convert,
+  isCompatible,
+  unitDimension,
+  unitSymbol,
+  isValidUnit,
+  ffiVersion,
+  listUnits,
+} from './lib/backend.js';

package/qtty-js/qtty-web/lib/DerivedQuantity.js

@@ -0,0 +1,58 @@
+/**
+ * @siderust/qtty-web — DerivedQuantity façade class (browser/WASM).
+ *
+ * Identical API to the Node version.
+ */
+
+import * as backend from './backend.js';
+
+export class DerivedQuantity {
+  constructor(value, numerator, denominator) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      throw new Error('DerivedQuantity value must be a finite number');
+    }
+    if (!backend.isValidUnit(numerator)) {
+      throw new Error(`Unknown numerator unit: "${numerator}"`);
+    }
+    if (!backend.isValidUnit(denominator)) {
+      throw new Error(`Unknown denominator unit: "${denominator}"`);
+    }
+    this._value = value;
+    this._numerator = numerator;
+    this._denominator = denominator;
+    this._numSymbol = backend.unitSymbol(numerator);
+    this._denSymbol = backend.unitSymbol(denominator);
+  }
+
+  get value() { return this._value; }
+  get numerator() { return this._numerator; }
+  get denominator() { return this._denominator; }
+  get symbol() { return `${this._numSymbol}/${this._denSymbol}`; }
+
+  to(numerator, denominator) {
+    const numFactor = backend.convert(1, this._numerator, numerator);
+    const denFactor = backend.convert(1, this._denominator, denominator);
+    return new DerivedQuantity(this._value * numFactor / denFactor, numerator, denominator);
+  }
+
+  mul(scalar) { return new DerivedQuantity(this._value * scalar, this._numerator, this._denominator); }
+  div(scalar) { return new DerivedQuantity(this._value / scalar, this._numerator, this._denominator); }
+  neg() { return new DerivedQuantity(-this._value, this._numerator, this._denominator); }
+
+  format(precision) {
+    const v = precision != null && precision >= 0
+      ? this._value.toFixed(precision)
+      : String(this._value);
+    return `${v} ${this.symbol}`;
+  }
+
+  toJson() {
+    return {
+      value: this._value,
+      numerator: this._numerator,
+      denominator: this._denominator,
+    };
+  }
+
+  toString() { return this.format(); }
+}

package/qtty-js/qtty-web/lib/Quantity.js

@@ -0,0 +1,75 @@
+/**
+ * @siderust/qtty-web — Quantity façade class (browser/WASM).
+ *
+ * Identical API to the Node version.  This module uses the WASM backend
+ * for unit conversions and metadata.
+ */
+
+import * as backend from './backend.js';
+
+export class Quantity {
+  /**
+   * @param {number} value  Numeric value.
+   * @param {string} unit   Unit name, e.g. `"Meter"`, `"Kilometer"`.
+   */
+  constructor(value, unit) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      throw new Error('Quantity value must be a finite number');
+    }
+    if (!backend.isValidUnit(unit)) {
+      throw new Error(`Unknown unit: "${unit}". Use listUnits() to list valid units.`);
+    }
+    this._value = value;
+    this._unit = unit;
+    this._symbol = backend.unitSymbol(unit);
+    this._dimension = backend.unitDimension(unit);
+  }
+
+  get value() { return this._value; }
+  get unit() { return this._unit; }
+  get symbol() { return this._symbol; }
+  get dimension() { return this._dimension; }
+
+  to(targetUnit) {
+    const converted = backend.convert(this._value, this._unit, targetUnit);
+    return new Quantity(converted, targetUnit);
+  }
+
+  compatible(other) {
+    return backend.isCompatible(this._unit, other._unit);
+  }
+
+  add(other) {
+    if (!this.compatible(other)) {
+      throw new Error(
+        `Cannot add quantities with different dimensions: ${this._dimension} vs ${other._dimension}`
+      );
+    }
+    const otherInMyUnit = backend.convert(other._value, other._unit, this._unit);
+    return new Quantity(this._value + otherInMyUnit, this._unit);
+  }
+
+  sub(other) {
+    if (!this.compatible(other)) {
+      throw new Error(
+        `Cannot subtract quantities with different dimensions: ${this._dimension} vs ${other._dimension}`
+      );
+    }
+    const otherInMyUnit = backend.convert(other._value, other._unit, this._unit);
+    return new Quantity(this._value - otherInMyUnit, this._unit);
+  }
+
+  mul(scalar) { return new Quantity(this._value * scalar, this._unit); }
+  div(scalar) { return new Quantity(this._value / scalar, this._unit); }
+  neg() { return new Quantity(-this._value, this._unit); }
+
+  format(precision) {
+    const v = precision != null && precision >= 0
+      ? this._value.toFixed(precision)
+      : String(this._value);
+    return `${v} ${this._symbol}`;
+  }
+
+  toJson() { return { value: this._value, unit: this._unit }; }
+  toString() { return this.format(); }
+}

package/qtty-js/qtty-web/lib/backend.js

@@ -0,0 +1,80 @@
+/**
+ * @siderust/qtty-web — Internal WASM backend abstraction.
+ *
+ * Loads the wasm-bindgen generated module and re-exports the primitive
+ * free functions that the shared JS façade classes need.
+ *
+ * @module @siderust/qtty-web/lib/backend
+ * @private
+ */
+
+let wasm = null;
+
+/**
+ * Initialise the WASM module. Must be called before any other function.
+ * @param {RequestInfo | URL | Response | BufferSource | WebAssembly.Module} [module_or_path]
+ */
+export async function init(module_or_path) {
+  const mod = await import('../pkg/qtty_web.js');
+  await mod.default(module_or_path);
+  wasm = mod;
+}
+
+export function ensureInit() {
+  if (!wasm) {
+    throw new Error('@siderust/qtty-web: call init() before using any function');
+  }
+}
+
+export function convert(value, fromUnit, toUnit) {
+  ensureInit();
+  return wasm.convert(value, fromUnit, toUnit);
+}
+
+export function isCompatible(unitA, unitB) {
+  ensureInit();
+  return wasm.isCompatible(unitA, unitB);
+}
+
+export function unitDimension(unit) {
+  ensureInit();
+  return wasm.unitDimension(unit);
+}
+
+export function unitSymbol(unit) {
+  ensureInit();
+  return wasm.unitSymbol(unit);
+}
+
+export function isValidUnit(unit) {
+  ensureInit();
+  return wasm.isValidUnit(unit);
+}
+
+export function listUnits() {
+  ensureInit();
+  return wasm.listUnits();
+}
+
+export function ffiVersion() {
+  ensureInit();
+  return wasm.ffiVersion();
+}
+
+/**
+ * Const map of all registered unit names.  Available after `init()`.
+ * `Unit.Meter === 'Meter'` — every key equals its own name.
+ * @type {Readonly<{[key: string]: string}>}
+ */
+export const Unit = new Proxy(Object.freeze({}), {
+  get(_, prop) {
+    if (typeof prop !== 'string') return undefined;
+    ensureInit();
+    return prop;
+  },
+  has(_, prop) {
+    if (typeof prop !== 'string') return false;
+    ensureInit();
+    return wasm.isValidUnit(prop);
+  },
+});

package/qtty-js/qtty-web/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@siderust/qtty-web",
+  "version": "0.1.0",
+  "description": "Strongly-typed physical quantities and unit conversions for the browser — powered by Rust + WebAssembly",
+  "type": "module",
+  "module": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "scripts": {
+    "build": "wasm-pack build --target web --out-dir pkg --release --scope siderust",
+    "build:dev": "wasm-pack build --target web --out-dir pkg --dev --scope siderust",
+    "build:bundler": "wasm-pack build --target bundler --out-dir pkg --release --scope siderust",
+    "clean": "rm -rf pkg/"
+  },
+  "files": [
+    "pkg/qtty_web_bg.wasm",
+    "pkg/qtty_web.js",
+    "pkg/qtty_web.d.ts",
+    "lib/",
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "quantities",
+    "units",
+    "conversion",
+    "physics",
+    "science",
+    "wasm",
+    "webassembly",
+    "browser",
+    "rust"
+  ],
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Siderust/qtty"
+  }
+}

package/qtty-js/qtty-web/src/lib.rs

@@ -0,0 +1,111 @@
+//! Browser/WASM bindings for `qtty` physical quantities — free-function backend.
+//!
+//! This crate provides the same set of primitive free functions as the Node
+//! backend (`qtty-node`) but using `wasm-bindgen` instead of `napi-rs`.
+//! The public JS façade classes (`Quantity`, `DerivedQuantity`) are shared
+//! across both backends.
+
+use qtty_ffi::registry;
+use qtty_ffi::{DimensionId, UnitId};
+use wasm_bindgen::prelude::*;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+fn parse_unit(name: &str) -> Result<UnitId, JsValue> {
+    let json = format!("\"{}\"", name);
+    serde_json::from_str::<UnitId>(&json)
+        .map_err(|_| JsValue::from_str(&format!("Unknown unit: \"{name}\"")))
+}
+
+fn dimension_to_string(dim: DimensionId) -> &'static str {
+    match dim {
+        DimensionId::Length => "Length",
+        DimensionId::Time => "Time",
+        DimensionId::Angle => "Angle",
+        DimensionId::Mass => "Mass",
+        DimensionId::Power => "Power",
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Free functions (backend primitives for the JS façade)
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[wasm_bindgen]
+pub fn convert(value: f64, from_unit: &str, to_unit: &str) -> Result<f64, JsValue> {
+    let src = parse_unit(from_unit)?;
+    let dst = parse_unit(to_unit)?;
+    registry::convert_value(value, src, dst)
+        .map_err(|code| JsValue::from_str(&format!("Conversion error (code {})", code)))
+}
+
+#[wasm_bindgen(js_name = "isCompatible")]
+pub fn is_compatible(unit_a: &str, unit_b: &str) -> Result<bool, JsValue> {
+    let a = parse_unit(unit_a)?;
+    let b = parse_unit(unit_b)?;
+    Ok(registry::compatible(a, b))
+}
+
+#[wasm_bindgen(js_name = "unitDimension")]
+pub fn unit_dimension(unit: &str) -> Result<String, JsValue> {
+    let id = parse_unit(unit)?;
+    registry::dimension(id)
+        .map(|d| dimension_to_string(d).to_string())
+        .ok_or_else(|| JsValue::from_str(&format!("Unknown unit: \"{unit}\"")))
+}
+
+#[wasm_bindgen(js_name = "unitSymbol")]
+pub fn unit_symbol(unit: &str) -> Result<String, JsValue> {
+    let id = parse_unit(unit)?;
+    if registry::meta(id).is_none() {
+        return Err(JsValue::from_str(&format!("Unknown unit: \"{unit}\"")));
+    }
+    Ok(id.symbol().to_string())
+}
+
+#[wasm_bindgen(js_name = "isValidUnit")]
+pub fn is_valid_unit(unit: &str) -> bool {
+    parse_unit(unit)
+        .ok()
+        .and_then(|id| registry::meta(id))
+        .is_some()
+}
+
+#[wasm_bindgen(js_name = "ffiVersion")]
+pub fn ffi_version() -> u32 {
+    qtty_ffi::qtty_ffi_version()
+}
+
+#[wasm_bindgen(js_name = "listUnits")]
+pub fn list_units() -> JsValue {
+    let ranges: &[(u32, u32)] = &[
+        (10000, 16000),
+        (20000, 24000),
+        (30000, 33000),
+        (40000, 43000),
+        (50000, 52000),
+    ];
+
+    let arr = js_sys::Array::new();
+    for &(start, end) in ranges {
+        for discriminant in start..end {
+            if let Some(id) = UnitId::from_u32(discriminant) {
+                if let Some(meta) = registry::meta(id) {
+                    let obj = js_sys::Object::new();
+                    js_sys::Reflect::set(&obj, &"name".into(), &id.name().into()).unwrap();
+                    js_sys::Reflect::set(&obj, &"symbol".into(), &id.symbol().into()).unwrap();
+                    js_sys::Reflect::set(
+                        &obj,
+                        &"dimension".into(),
+                        &dimension_to_string(meta.dim).into(),
+                    )
+                    .unwrap();
+                    arr.push(&obj);
+                }
+            }
+        }
+    }
+    arr.into()
+}

package/qtty-js/scripts/ci.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PACKAGE_DIR="$ROOT_DIR/qtty-node"
+STEP="${1:-all}"
+
+run_install() {
+  cd "$PACKAGE_DIR"
+  npm ci
+}
+
+run_format() {
+  cd "$PACKAGE_DIR"
+  npm run format:check
+}
+
+run_lint() {
+  cd "$PACKAGE_DIR"
+  npm run lint
+}
+
+run_build() {
+  cd "$PACKAGE_DIR"
+  if [[ "${BUILD_MODE:-debug}" == "release" ]]; then
+    npm run build
+  else
+    npm run build:debug
+  fi
+}
+
+run_test() {
+  cd "$PACKAGE_DIR"
+  npm test
+}
+
+run_coverage() {
+  cd "$PACKAGE_DIR"
+  npm run test:coverage
+}
+
+case "$STEP" in
+  install)
+    run_install
+    ;;
+  format)
+    run_format
+    ;;
+  lint)
+    run_lint
+    ;;
+  build)
+    run_build
+    ;;
+  test)
+    run_test
+    ;;
+  coverage)
+    run_coverage
+    ;;
+  all)
+    run_install
+    run_format
+    run_lint
+    run_build
+    run_test
+    run_coverage
+    ;;
+  *)
+    echo "Usage: $0 [install|format|lint|build|test|coverage|all]" >&2
+    exit 1
+    ;;
+esac