siderust-js 0.1.0

package/qtty-js/qtty/qtty-ffi/units.csv

@@ -0,0 +1,156 @@
+# FFI Unit Definitions
+# Format: discriminant,dimension,name,symbol,ratio[,rust_type]
+# Discriminant encoding: DSSCC where D=dimension (1 digit), SS=system (2 digits), CC=counter (2 digits)
+# Ratio is the conversion factor to the canonical unit for that dimension
+# Canonical units: Meter (Length), Second (Time), Radian (Angle), Gram (Mass), Watt (Power)
+# rust_type (optional 6th field): Rust quantity type path for auto-generating From/TryFrom impls
+
+# Length units (1xxxx): 100xx=SI, 110xx=Astronomical, 120xx=Imperial, 130xx=Nautical, 150xx=Nominal
+10000,Length,PlanckLength,l_P,1.616255e-35,qtty::length::PlanckLengths
+10001,Length,Yoctometer,ym,1e-24,qtty::length::Yoctometers
+10002,Length,Zeptometer,zm,1e-21,qtty::length::Zeptometers
+10003,Length,Attometer,am,1e-18,qtty::length::Attometers
+10004,Length,Femtometer,fm,1e-15,qtty::length::Femtometers
+10005,Length,Picometer,pm,1e-12,qtty::length::Picometers
+10006,Length,Nanometer,nm,1e-9,qtty::length::Nanometers
+10007,Length,Micrometer,µm,1e-6,qtty::length::Micrometers
+10008,Length,Millimeter,mm,0.001,qtty::length::Millimeters
+10009,Length,Centimeter,cm,0.01,qtty::length::Centimeters
+10010,Length,Decimeter,dm,0.1,qtty::length::Decimeters
+10011,Length,Meter,m,1.0,qtty::length::Meters
+10012,Length,Decameter,dam,10.0,qtty::length::Decameters
+10013,Length,Hectometer,hm,100.0,qtty::length::Hectometers
+10014,Length,Kilometer,km,1000.0,qtty::length::Kilometers
+10015,Length,Megameter,Mm,1e6,qtty::length::Megameters
+10016,Length,Gigameter,Gm,1e9,qtty::length::Gigameters
+10017,Length,Terameter,Tm,1e12,qtty::length::Terameters
+10018,Length,Petameter,Pm,1e15,qtty::length::Petameters
+10019,Length,Exameter,Em,1e18,qtty::length::Exameters
+10020,Length,Zettameter,Zm,1e21,qtty::length::Zettameters
+10021,Length,Yottameter,Ym,1e24,qtty::length::Yottameters
+11000,Length,BohrRadius,a₀,5.29177210903e-11,qtty::length::BohrRadii
+11001,Length,ClassicalElectronRadius,r_e,2.8179403262e-15,qtty::length::ClassicalElectronRadii
+11002,Length,ElectronReducedComptonWavelength,λ̄_e,3.8615926796e-13,qtty::length::ElectronReducedComptonWavelengths
+11003,Length,AstronomicalUnit,au,149597870700.0,qtty::length::AstronomicalUnits
+11004,Length,LightYear,ly,9460730472580800.0,qtty::length::LightYears
+11005,Length,Parsec,pc,30856775814913672.8,qtty::length::Parsecs
+11006,Length,Kiloparsec,kpc,3.085_677_581_491_367e19,qtty::length::Kiloparsecs
+11007,Length,Megaparsec,Mpc,3.085_677_581_491_367e22,qtty::length::Megaparsecs
+11008,Length,Gigaparsec,Gpc,3.085_677_581_491_367e25,qtty::length::Gigaparsecs
+12000,Length,Inch,in,0.0254,qtty::length::Inches
+12001,Length,Foot,ft,0.3048,qtty::length::Feet
+12002,Length,Yard,yd,0.9144,qtty::length::Yards
+12003,Length,Mile,mi,1609.344,qtty::length::Miles
+13000,Length,Link,lk,0.201168,qtty::length::Links
+13001,Length,Fathom,ftm,1.8288,qtty::length::Fathoms
+13002,Length,Rod,rd,5.0292,qtty::length::Rods
+13003,Length,Chain,ch,20.1168,qtty::length::Chains
+13004,Length,NauticalMile,nmi,1852.0,qtty::length::NauticalMiles
+15000,Length,NominalLunarRadius,R_☾,1.7374e6,qtty::length::nominal::LunarRadii
+15001,Length,NominalLunarDistance,LD,3.844e8,qtty::length::nominal::LunarDistances
+15002,Length,NominalEarthPolarRadius,R_⊕pol,6.3568e6,qtty::length::nominal::EarthPolarRadii
+15003,Length,NominalEarthRadius,R_⊕,6.3781e6,qtty::length::nominal::EarthRadii
+15004,Length,NominalEarthEquatorialRadius,R_⊕eq,6.3781e6,qtty::length::nominal::EarthEquatorialRadii
+15005,Length,EarthMeridionalCircumference,C_mer,40007862.917,qtty::length::EarthMeridionalCircumferences
+15006,Length,EarthEquatorialCircumference,C_eq,40075016.686,qtty::length::EarthEquatorialCircumferences
+15007,Length,NominalJupiterRadius,R_♃,7.1492e7,qtty::length::nominal::JupiterRadii
+15008,Length,NominalSolarRadius,R_☉,6.957e8,qtty::length::nominal::SolarRadiuses
+15009,Length,NominalSolarDiameter,D_☉,1.3914e9,qtty::length::nominal::SolarDiameters
+# Time units (2xxxx): 200xx=SI, 210xx=Common, 220xx=Calendar, 230xx=Astronomical
+20000,Time,Attosecond,as,1e-18,qtty::time::Attoseconds
+20001,Time,Femtosecond,fs,1e-15,qtty::time::Femtoseconds
+20002,Time,Picosecond,ps,1e-12,qtty::time::Picoseconds
+20003,Time,Nanosecond,ns,1e-9,qtty::time::Nanoseconds
+20004,Time,Microsecond,µs,1e-6,qtty::time::Microseconds
+20005,Time,Millisecond,ms,0.001,qtty::time::Milliseconds
+20006,Time,Centisecond,cs,0.01,qtty::time::Centiseconds
+20007,Time,Decisecond,ds,0.1,qtty::time::Deciseconds
+20008,Time,Second,s,1.0,qtty::time::Seconds
+20009,Time,Decasecond,das,10.0,qtty::time::Decaseconds
+20010,Time,Hectosecond,hs,100.0,qtty::time::Hectoseconds
+20011,Time,Kilosecond,ks,1000.0,qtty::time::Kiloseconds
+20012,Time,Megasecond,Ms,1e6,qtty::time::Megaseconds
+20013,Time,Gigasecond,Gs,1e9,qtty::time::Gigaseconds
+20014,Time,Terasecond,Ts,1e12,qtty::time::Teraseconds
+21000,Time,Minute,min,60.0,qtty::time::Minutes
+21001,Time,Hour,h,3600.0,qtty::time::Hours
+21002,Time,Day,d,86400.0,qtty::time::Days
+21003,Time,Week,wk,604800.0,qtty::time::Weeks
+21004,Time,Fortnight,fn,1209600.0,qtty::time::Fortnights
+22000,Time,Year,yr,31557600.0,qtty::time::Years
+22001,Time,Decade,dec,315576000.0,qtty::time::Decades
+22002,Time,Century,c,3155760000.0,qtty::time::Centuries
+22003,Time,Millennium,mill,31557600000.0,qtty::time::Millennia
+22004,Time,JulianYear,a,31557600.0,qtty::time::JulianYears
+22005,Time,JulianCentury,jc,3155760000.0,qtty::time::JulianCenturies
+23000,Time,SiderealDay,sd,86164.0905,qtty::time::SiderealDays
+23001,Time,SynodicMonth,mo_s,2551442.976,qtty::time::SynodicMonths
+23002,Time,SiderealYear,yr_s,31558149.7635456,qtty::time::SiderealYears
+# Angle units (3xxxx): 300xx=Radian, 310xx=Degree, 320xx=Other
+30000,Angle,Milliradian,mrad,0.001,qtty::angular::Milliradians
+30001,Angle,Radian,rad,1.0,qtty::angular::Radians
+31000,Angle,MicroArcsecond,µas,4.84813681109536e-12,qtty::angular::MicroArcseconds
+31001,Angle,MilliArcsecond,mas,4.84813681109536e-9,qtty::angular::MilliArcseconds
+31002,Angle,Arcsecond,″,4.84813681109536e-6,qtty::angular::Arcseconds
+31003,Angle,Arcminute,′,0.0002908882086657216,qtty::angular::Arcminutes
+31004,Angle,Degree,°,0.017453292519943295,qtty::angular::Degrees
+32000,Angle,Gradian,gon,0.015707963267948967,qtty::angular::Gradians
+32001,Angle,Turn,tr,std::f64::consts::TAU,qtty::angular::Turns
+32002,Angle,HourAngle,ʰ,0.2617993877991494,qtty::angular::HourAngles
+# Mass units (4xxxx): 400xx=SI, 410xx=Imperial, 420xx=Special
+40000,Mass,Yoctogram,yg,1e-24,qtty::mass::Yoctograms
+40001,Mass,Zeptogram,zg,1e-21,qtty::mass::Zeptograms
+40002,Mass,Attogram,ag,1e-18,qtty::mass::Attograms
+40003,Mass,Femtogram,fg,1e-15,qtty::mass::Femtograms
+40004,Mass,Picogram,pg,1e-12,qtty::mass::Picograms
+40005,Mass,Nanogram,ng,1e-9,qtty::mass::Nanograms
+40006,Mass,Microgram,µg,1e-6,qtty::mass::Micrograms
+40007,Mass,Milligram,mg,0.001,qtty::mass::Milligrams
+40008,Mass,Centigram,cg,0.01,qtty::mass::Centigrams
+40009,Mass,Decigram,dg,0.1,qtty::mass::Decigrams
+40010,Mass,Gram,g,1.0,qtty::mass::Grams
+40011,Mass,Decagram,dag,10.0,qtty::mass::Decagrams
+40012,Mass,Hectogram,hg,100.0,qtty::mass::Hectograms
+40013,Mass,Kilogram,kg,1000.0,qtty::mass::Kilograms
+40014,Mass,Megagram,Mg,1e6,qtty::mass::Megagrams
+40015,Mass,Gigagram,Gg,1e9,qtty::mass::Gigagrams
+40016,Mass,Teragram,Tg,1e12,qtty::mass::Teragrams
+40017,Mass,Petagram,Pg,1e15,qtty::mass::Petagrams
+40018,Mass,Exagram,Eg,1e18,qtty::mass::Exagrams
+40019,Mass,Zettagram,Zg,1e21,qtty::mass::Zettagrams
+40020,Mass,Yottagram,Yg,1e24,qtty::mass::Yottagrams
+41000,Mass,Grain,gr,0.06479891,qtty::mass::Grains
+41001,Mass,Ounce,oz,28.349523125,qtty::mass::Ounces
+41002,Mass,Pound,lb,453.59237,qtty::mass::Pounds
+41003,Mass,Stone,st,6350.29318,qtty::mass::Stones
+41004,Mass,ShortTon,ton,907184.74,qtty::mass::ShortTons
+41005,Mass,LongTon,ton_l,1016046.9088,qtty::mass::LongTons
+42000,Mass,Carat,ct,0.2,qtty::mass::Carats
+42001,Mass,Tonne,t,1e6,qtty::mass::Tonnes
+42002,Mass,AtomicMassUnit,u,1.66053906892e-24,qtty::mass::AtomicMassUnits
+42003,Mass,SolarMass,M_☉,1.988416e33,qtty::mass::SolarMasses
+# Power units (5xxxx): 500xx=SI, 510xx=Other
+50000,Power,Yoctowatt,yW,1e-24,qtty::power::Yoctowatts
+50001,Power,Zeptowatt,zW,1e-21,qtty::power::Zeptowatts
+50002,Power,Attowatt,aW,1e-18,qtty::power::Attowatts
+50003,Power,Femtowatt,fW,1e-15,qtty::power::Femtowatts
+50004,Power,Picowatt,pW,1e-12,qtty::power::Picowatts
+50005,Power,Nanowatt,nW,1e-9,qtty::power::Nanowatts
+50006,Power,Microwatt,µW,1e-6,qtty::power::Microwatts
+50007,Power,Milliwatt,mW,0.001,qtty::power::Milliwatts
+50008,Power,Deciwatt,dW,0.1,qtty::power::Deciwatts
+50009,Power,Watt,W,1.0,qtty::power::Watts
+50010,Power,Decawatt,daW,10.0,qtty::power::Decawatts
+50011,Power,Hectowatt,hW,100.0,qtty::power::Hectowatts
+50012,Power,Kilowatt,kW,1000.0,qtty::power::Kilowatts
+50013,Power,Megawatt,MW,1e6,qtty::power::Megawatts
+50014,Power,Gigawatt,GW,1e9,qtty::power::Gigawatts
+50015,Power,Terawatt,TW,1e12,qtty::power::Terawatts
+50016,Power,Petawatt,PW,1e15,qtty::power::Petawatts
+50017,Power,Exawatt,EW,1e18,qtty::power::Exawatts
+50018,Power,Zettawatt,ZW,1e21,qtty::power::Zettawatts
+50019,Power,Yottawatt,YW,1e24,qtty::power::Yottawatts
+51000,Power,ErgPerSecond,erg/s,1e-7
+51001,Power,HorsepowerMetric,PS,735.49875,qtty::power::HorsepowerMetrics
+51002,Power,HorsepowerElectric,hp_e,746.0,qtty::power::HorsepowerElectrics
+51003,Power,SolarLuminosity,L_☉,3.828e26,qtty::power::SolarLuminosities

package/qtty-js/qtty/qtty-ffi/units.csv.md

@@ -0,0 +1,3 @@
+# qtty-ffi unit registry
+
+Canonical unit-registry notes now live in [`../../doc/developers/unit-registry.md`](../../doc/developers/unit-registry.md).

package/qtty-js/qtty-node/.prettierignore

@@ -0,0 +1,6 @@
+coverage
+node_modules
+target
+*.node
+index.d.ts
+index.js

package/qtty-js/qtty-node/.prettierrc.json

@@ -0,0 +1,6 @@
+{
+  "printWidth": 100,
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all"
+}

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

@@ -0,0 +1,250 @@
+# @siderust/qtty
+
+Strongly-typed physical quantities and unit conversions for Node.js, powered by
+Rust.
+
+`@siderust/qtty` gives you compile-time safe, zero-overhead unit conversions in
+JavaScript and TypeScript by delegating all math to the Rust `qtty` library via
+a native Node addon built with [napi-rs](https://napi.rs).
+
+## Installation
+
+```bash
+npm install @siderust/qtty
+```
+
+The package ships a prebuilt native addon. If a prebuilt binary is not available
+for your platform you will need a Rust toolchain (`rustup`) and the napi-rs CLI:
+
+```bash
+npm install -g @napi-rs/cli
+cd node_modules/@siderust/qtty && napi build --release --platform
+```
+
+## Quick start
+
+```js
+const { Quantity, DerivedQuantity, convert } = require('@siderust/qtty');
+
+// Create a quantity and convert
+const distance = new Quantity(1000, 'Meter');
+const km = distance.to('Kilometer');
+console.log(km.value); // 1
+console.log(km.unit); // "Kilometer"
+
+// Arithmetic with automatic unit conversion
+const a = new Quantity(1, 'Kilometer');
+const b = new Quantity(500, 'Meter');
+const total = a.add(b); // 1.5 km
+const doubled = total.mul(2); // 3.0 km
+
+// Derived (compound) quantities
+const velocity = new DerivedQuantity(100, 'Meter', 'Second');
+const kmh = velocity.to('Kilometer', 'Hour');
+console.log(kmh.value); // 360
+
+// One-shot value conversion
+const hours = convert(7200, 'Second', 'Hour'); // 2
+```
+
+## Unit factories — arithmetic-style construction
+
+Import named unit factory functions to create quantities without typing
+`new Quantity(…)`. Each factory is callable and reads like an expression:
+
+```js
+// Both lines produce the same Quantity:
+const a = Degrees(180); // factory style
+const b = new Quantity(180, 'Degree'); // class style
+
+// Works for any dimension:
+const dist = Kilometers(1000);
+const mass = Kilograms(70);
+const time = Hours(24);
+const power = Kilowatts(3.5);
+```
+
+Because JavaScript has no operator overloading, `180 * Degrees` cannot
+return a `Quantity` — write `Degrees(180)` instead.
+
+```js
+import {
+  Meters, Kilometers, Miles, AstronomicalUnits, LightYears, Parsecs,
+  Seconds, Minutes, Hours, Days, Years, JulianYears,
+  Degrees, Radians, Arcseconds,
+  Grams, Kilograms, SolarMasses,
+  Watts, Kilowatts, SolarLuminosities,
+} from '@siderust/qtty/units';
+
+// Factory metadata
+console.log(Meters.unit);      // 'Meter'
+console.log(Meters.symbol);    // 'm'
+console.log(Meters.dimension); // 'Length'
+
+// Convert straight from the factory call
+const rad = Degrees(180).to('Radian');   // π rad
+const pc  = LightYears(1).to('Parsec'); // 0.3066 pc
+
+// Chain arithmetic
+const total = Kilometers(1).add(Meters(500));  // 1.5 km
+const speed = Meters(100).div(1).to('Kilometer').mul(3600); // naive example
+
+// Dynamic lookup by name
+import { unit, units } from '@siderust/qtty/units';
+const factory = unit('SolarMass');  // UnitFactory | undefined
+const sun = factory!(1);            // Quantity { value: 1, unit: 'SolarMass' }
+
+// All factories as a record
+const lengthNames = Object.values(units)
+  .filter(f => f.dimension === 'Length')
+  .map(f => f.unit);
+```
+
+## TypeScript
+
+Full type information is provided out of the box:
+
+```ts
+import { Quantity, convert, isCompatible } from '@siderust/qtty';
+import { Degrees, Kilometers, Hours, type UnitFactory } from '@siderust/qtty/units';
+
+// Using the class
+const q: Quantity = new Quantity(180, 'Degree');
+const rad: Quantity = q.to('Radian');
+console.log(rad.value); // 3.141592653589793
+
+// Using factories
+const angle: Quantity = Degrees(180); // identical result
+const speed: Quantity = Kilometers(100).div(Hours(1).value);
+
+// Type of a factory
+const f: UnitFactory = Degrees;
+console.log(f.unit); // 'Degree'
+console.log(f.symbol); // '°'
+console.log(f.dimension); // 'Angle'
+
+const ok: boolean = isCompatible('Meter', 'Kilometer'); // true
+```
+
+## API
+
+### `Quantity`
+
+| Member                      | Description                                            |
+| --------------------------- | ------------------------------------------------------ |
+| `new Quantity(value, unit)` | Create a quantity. Unit is a string like `"Meter"`.    |
+| `.value`                    | The numeric value (getter).                            |
+| `.unit`                     | The unit name (getter).                                |
+| `.symbol`                   | The unit symbol, e.g. `"m"` (getter).                  |
+| `.dimension`                | The dimension name, e.g. `"Length"` (getter).          |
+| `.to(unit)`                 | Convert to another unit. Throws on dimension mismatch. |
+| `.add(other)`               | Add another quantity (same dimension).                 |
+| `.sub(other)`               | Subtract another quantity (same dimension).            |
+| `.mul(scalar)`              | Multiply by a number.                                  |
+| `.div(scalar)`              | Divide by a number.                                    |
+| `.neg()`                    | Negate.                                                |
+| `.compatible(other)`        | Check dimension compatibility.                         |
+| `.format(precision?)`       | Format as string, e.g. `"1000 m"`.                     |
+| `.toJson()`                 | Return `{ value, unit }` plain object.                 |
+| `.toString()`               | Same as `.format()`.                                   |
+
+### `DerivedQuantity`
+
+| Member                                     | Description                                 |
+| ------------------------------------------ | ------------------------------------------- |
+| `new DerivedQuantity(value, num, den)`     | Create a compound quantity (e.g. m/s).      |
+| `.value`                                   | Numeric value.                              |
+| `.numerator` / `.denominator`              | Unit names.                                 |
+| `.symbol`                                  | Compound symbol, e.g. `"m/s"`.              |
+| `.to(num, den)`                            | Convert to different units.                 |
+| `.mul(scalar)` / `.div(scalar)` / `.neg()` | Arithmetic.                                 |
+| `.format(precision?)` / `.toString()`      | Formatting.                                 |
+| `.toJson()`                                | Return `{ value, numerator, denominator }`. |
+
+### Free functions
+
+| Function                     | Description                                                     |
+| ---------------------------- | --------------------------------------------------------------- |
+| `convert(value, from, to)`   | Convert a bare number between units.                            |
+| `isCompatible(unitA, unitB)` | Check if two units share a dimension.                           |
+| `unitDimension(unit)`        | Get the dimension name for a unit.                              |
+| `unitSymbol(unit)`           | Get the symbol for a unit.                                      |
+| `isValidUnit(unit)`          | Check if a unit name is recognized.                             |
+| `listUnits()`                | Return all registered units as `{ name, symbol, dimension }[]`. |
+| `ffiVersion()`               | FFI ABI version number.                                         |
+
+### `@siderust/qtty/units` — unit factories
+
+Every named export is a `UnitFactory`: call it with a number to get a `Quantity`.
+
+```ts
+import { Degrees, Kilometers, Kilograms, Watts } from '@siderust/qtty/units';
+
+Degrees(180); // Quantity(180, 'Degree')
+Kilometers(2.5); // Quantity(2.5, 'Kilometer')
+Kilograms(70); // Quantity(70,  'Kilogram')
+Watts(1500); // Quantity(1500, 'Watt')
+```
+
+Use `unit(name)` for dynamic lookup and `units` for the full registry.
+
+### Supported dimensions and units
+
+| Dimension  | Example units                                                              |
+| ---------- | -------------------------------------------------------------------------- |
+| **Length** | `Meter`, `Kilometer`, `Mile`, `AstronomicalUnit`, `Parsec`, `LightYear`, … |
+| **Time**   | `Second`, `Minute`, `Hour`, `Day`, `Year`, `JulianCentury`, …              |
+| **Angle**  | `Radian`, `Degree`, `Arcminute`, `Arcsecond`, `HourAngle`, …               |
+| **Mass**   | `Gram`, `Kilogram`, `Pound`, `SolarMass`, `AtomicMassUnit`, …              |
+| **Power**  | `Watt`, `Kilowatt`, `Megawatt`, `SolarLuminosity`, …                       |
+
+Use `isValidUnit(name)` to check at runtime, or see the
+[units.csv](../qtty/qtty-ffi/units.csv) for the full list.
+
+## Examples
+
+Runnable examples are in the [examples/](examples/) folder:
+
+| File                                              | What it shows                                                           |
+| ------------------------------------------------- | ----------------------------------------------------------------------- |
+| [quickstart.mjs](examples/quickstart.mjs)         | Construction, conversion, `convert()`, `isCompatible()`                 |
+| [unit_factories.mjs](examples/unit_factories.mjs) | Factory-style construction, metadata, dynamic `unit()`/`units`          |
+| [arithmetic.mjs](examples/arithmetic.mjs)         | `.add()`, `.sub()`, `.mul()`, `.div()`, velocity with `DerivedQuantity` |
+| [astronomy.mjs](examples/astronomy.mjs)           | Parsec/ly/AU scales, angular measures, solar units                      |
+
+```bash
+node examples/quickstart.mjs
+node examples/unit_factories.mjs
+node examples/arithmetic.mjs
+node examples/astronomy.mjs
+```
+
+## Building from source
+
+```bash
+# Prerequisites: Rust toolchain
+npm install
+npx napi build --release --platform
+npm test
+```
+
+## Architecture
+
+```
+┌──────────────┐     napi-rs     ┌──────────────┐     path dep     ┌───────────┐
+│  JavaScript  │ ◄─────────────► │  qtty-node   │ ◄──────────────► │  qtty-ffi │
+│  / TypeScript│    native addon │  (Rust crate) │    registry &    │  registry │
+└──────────────┘                 └──────────────┘    conversion     └───────────┘
+                                                                         │
+                                                                    ┌────┴────┐
+                                                                    │  qtty   │
+                                                                    │ (core)  │
+                                                                    └─────────┘
+```
+
+All conversion math lives in Rust. The Node layer is a thin wrapper that
+translates between JavaScript strings/numbers and Rust types.
+
+## License
+
+AGPL-3.0 — see [LICENSE](../LICENSE).

package/qtty-js/qtty-node/c8.config.json

@@ -0,0 +1,11 @@
+{
+  "all": true,
+  "include": ["units.js"],
+  "exclude": ["coverage/**"],
+  "reporter": ["text-summary", "lcov", "cobertura", "html"],
+  "check-coverage": true,
+  "lines": 90,
+  "functions": 90,
+  "branches": 85,
+  "statements": 90
+}

package/qtty-js/qtty-node/eslint.config.js

@@ -0,0 +1,31 @@
+const js = require('@eslint/js');
+const globals = require('globals');
+
+const baseRules = {
+  ...js.configs.recommended.rules,
+  'no-console': 'off',
+};
+
+module.exports = [
+  {
+    ignores: ['coverage/**', 'node_modules/**', 'target/**', '*.d.ts', '*.node', 'index.js'],
+  },
+  {
+    files: ['**/*.js'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'commonjs',
+      globals: globals.node,
+    },
+    rules: baseRules,
+  },
+  {
+    files: ['**/*.mjs'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: globals.node,
+    },
+    rules: baseRules,
+  },
+];

package/qtty-js/qtty-node/examples/arithmetic.mjs

@@ -0,0 +1,64 @@
+/**
+ * arithmetic.mjs — Arithmetic operations on quantities.
+ *
+ * Run: node examples/arithmetic.mjs
+ */
+
+import { Meters, Kilometers, Kilograms, Grams } from '../units.js';
+import { DerivedQuantity } from '../index.js';
+
+console.log('─── Scalar arithmetic ──────────────────────────────────────────────');
+
+const base = Meters(100);
+console.log(`  Meters(100).mul(3)  = ${base.mul(3)}`); // 300 m
+console.log(`  Meters(100).div(4)  = ${base.div(4)}`); // 25 m
+console.log(`  Meters(100).neg()   = ${base.neg()}`); // -100 m
+
+console.log('\n─── Quantity addition and subtraction ──────────────────────────────');
+
+// Add two lengths, each in different units — result is in the left unit.
+const a = Kilometers(1);
+const b = Meters(500);
+console.log(`  Kilometers(1) + Meters(500)  = ${a.add(b)}`); // 1.5 km
+console.log(`  Kilometers(1) - Meters(500)  = ${a.sub(b)}`); // 0.5 km
+
+// Add with explicit conversion
+const totalInMeters = Kilometers(1).to('Meter').add(Meters(500));
+console.log(`  In Meters: ${totalInMeters}`); // 1500 m
+
+console.log('\n─── Chaining conversions and arithmetic ────────────────────────────');
+
+// Trip: 3 legs in mixed units, total in km
+const leg1 = Meters(800);
+const leg2 = Kilometers(1.2);
+const leg3 = Meters(400);
+
+const total = leg1.to('Kilometer').add(leg2).add(leg3.to('Kilometer'));
+console.log(`  Total trip: ${total.format(3)}`); // 2.400 km
+console.log(`  In meters:  ${total.to('Meter')}`); // 2400 m
+console.log(`  In miles:   ${total.to('Mile').format(4)}`); // 1.4913 mi
+
+console.log('\n─── Derived quantities (velocity = distance / time) ────────────────');
+
+// 100 m/s converted to km/h
+const velocity = new DerivedQuantity(100, 'Meter', 'Second');
+const kmh = velocity.to('Kilometer', 'Hour');
+console.log(`  100 m/s → ${kmh.format(1)}`); // 360.0 km/h
+
+// Scaling
+const doubled = kmh.mul(2);
+console.log(`  360 km/h × 2 = ${doubled}`); // 720 km/h
+
+// Back to SI
+const back = kmh.to('Meter', 'Second');
+console.log(`  360 km/h → ${back.format(6)}`); // 100.000000 m/s
+
+console.log('\n─── Mass arithmetic ─────────────────────────────────────────────────');
+
+const kg = Kilograms(5);
+const g = Grams(500);
+const combined = kg.add(g); // 5.5 kg
+console.log(`  5 kg + 500 g = ${combined.format(2)}`);
+
+const perItem = combined.div(10);
+console.log(`  Per 10 items: ${perItem.format(3)}`); // 0.550 kg

package/qtty-js/qtty-node/examples/astronomy.mjs

@@ -0,0 +1,90 @@
+/**
+ * astronomy.mjs — Astronomy-oriented unit conversions.
+ *
+ * Demonstrates the wide range of astronomical units available.
+ *
+ * Run: node examples/astronomy.mjs
+ */
+
+import {
+  AstronomicalUnits,
+  LightYears,
+  Parsecs,
+  Kiloparsecs,
+  Gigaparsecs,
+  Degrees,
+  MilliArcseconds,
+  HourAngles,
+  JulianYears,
+  SiderealYears,
+  SolarMasses,
+  Kilograms,
+  SolarLuminosities,
+} from '../units.js';
+
+console.log('─── Distance scales ────────────────────────────────────────────────');
+
+const oneAU = AstronomicalUnits(1);
+console.log(`  1 AU = ${oneAU.to('Kilometer').value.toExponential(4)} km`);
+console.log(`  1 AU = ${oneAU.to('LightYear').value.toExponential(4)} ly`);
+console.log(`  1 AU = ${oneAU.to('Parsec').value.toExponential(4)} pc`);
+
+const oneLY = LightYears(1);
+console.log(`  1 ly = ${oneLY.to('AstronomicalUnit').format(2)}`);
+console.log(`  1 ly = ${oneLY.to('Parsec').format(6)}`);
+
+const onePc = Parsecs(1);
+console.log(`  1 pc = ${onePc.to('LightYear').format(4)}`); // 3.2616 ly
+console.log(`  1 pc = ${onePc.to('AstronomicalUnit').value.toExponential(4)} AU`);
+
+// Cosmological distances
+const andromeda = Kiloparsecs(778);
+console.log(`\n  Andromeda Galaxy: ${andromeda.to('Megaparsec').format(3)}`);
+console.log(`  Andromeda Galaxy: ${andromeda.to('LightYear').value.toExponential(3)} ly`);
+
+const hubbleHorizon = Gigaparsecs(14);
+console.log(`  Hubble horizon  : ${hubbleHorizon.value} Gpc`);
+
+console.log('\n─── Angular measurements ────────────────────────────────────────────');
+
+const arcOne = Degrees(1);
+console.log(`  1° = ${arcOne.to('Arcminute').value} ′`);
+console.log(`  1° = ${arcOne.to('Arcsecond').value} ″`);
+console.log(`  1° = ${arcOne.to('Radian').format(8)}`);
+
+// Parallax of Proxima Centauri: 768.5 mas
+const proxParallax = MilliArcseconds(768.5);
+const proxParallaxArcsec = proxParallax.to('Arcsecond');
+// Distance in parsecs = 1 / parallax_in_arcsec
+const proxDistPc = Parsecs(1 / proxParallaxArcsec.value);
+console.log(`\n  Proxima Centauri parallax: ${proxParallax} = ${proxParallaxArcsec.format(4)}`);
+console.log(`  Distance: ${proxDistPc.format(4)} = ${proxDistPc.to('LightYear').format(4)}`);
+
+// Hour angles (right ascension)
+const ra = HourAngles(6.75); // RA of Betelgeuse
+console.log(`\n  Betelgeuse RA: ${ra} = ${ra.to('Degree').format(4)}`);
+
+console.log('\n─── Time scales ─────────────────────────────────────────────────────');
+
+const oneYear = JulianYears(1);
+console.log(`  1 Julian year = ${oneYear.to('Day').format(4)}`);
+console.log(`  1 Julian year = ${oneYear.to('Second').value.toExponential(4)} s`);
+
+const oneSiderealYear = SiderealYears(1);
+console.log(`  1 Sidereal year = ${oneSiderealYear.to('Day').format(6)}`);
+const diff = SiderealYears(1).to('Second').sub(JulianYears(1).to('Second'));
+console.log(`  Sidereal − Julian year = ${diff.format(2)}`);
+
+console.log('\n─── Masses ──────────────────────────────────────────────────────────');
+
+const oneSolar = SolarMasses(1);
+console.log(`  1 M_☉ = ${oneSolar.to('Kilogram').value.toExponential(4)} kg`);
+
+const earthMass = Kilograms(5.972e24);
+console.log(`  Earth = ${earthMass.to('SolarMass').value.toExponential(4)} M_☉`);
+
+console.log('\n─── Luminosity ──────────────────────────────────────────────────────');
+
+const oneSolarLum = SolarLuminosities(1);
+console.log(`  1 L_☉ = ${oneSolarLum.to('Watt').value.toExponential(4)} W`);
+console.log(`  1 L_☉ = ${oneSolarLum.to('Megawatt').value.toExponential(4)} MW`);

package/qtty-js/qtty-node/examples/quickstart.mjs

@@ -0,0 +1,36 @@
+/**
+ * quickstart.mjs — Basic quantity creation and conversion.
+ *
+ * Run: node examples/quickstart.mjs
+ */
+
+import { Quantity, convert, isCompatible } from '../index.js';
+
+console.log('─── Construction ───────────────────────────────────────────');
+
+const distance = new Quantity(1000, 'Meter');
+console.log(`Created: ${distance}`); // 1000 m
+console.log(`value:   ${distance.value}`); // 1000
+console.log(`unit:    ${distance.unit}`); // Meter
+console.log(`symbol:  ${distance.symbol}`); // m
+console.log(`dim:     ${distance.dimension}`); // Length
+
+console.log('\n─── Conversions ────────────────────────────────────────────');
+
+const km = distance.to('Kilometer');
+console.log(`1000 m  → ${km}`); // 1 km
+
+const ft = distance.to('Foot');
+console.log(`1000 m  → ${ft.format(2)}`); // 3280.84 ft
+
+const mi = distance.to('Mile');
+console.log(`1000 m  → ${mi.format(4)}`); // 0.6214 mi
+
+console.log('\n─── Free convert() ─────────────────────────────────────────');
+
+console.log(`7200 s  → ${convert(7200, 'Second', 'Hour')} h`); // 2
+console.log(`180 deg → ${convert(180, 'Degree', 'Radian').toFixed(6)} rad`); // 3.141593
+
+console.log('\n─── Compatibility check ────────────────────────────────────');
+console.log(`Meter ↔ Kilometer? ${isCompatible('Meter', 'Kilometer')}`); // true
+console.log(`Meter ↔ Second?    ${isCompatible('Meter', 'Second')}`); // false