siderust-js 0.1.0

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

@@ -0,0 +1,70 @@
+{
+  "name": "@siderust/qtty",
+  "version": "0.1.0",
+  "description": "Strongly-typed physical quantities and unit conversions for Node.js, powered by Rust",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./index.js",
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    },
+    "./units": {
+      "require": "./units.js",
+      "import": "./units.js",
+      "types": "./units.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "napi build --release --platform",
+    "build:debug": "napi build --platform",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "test": "node --test __test__/*.test.mjs",
+    "test:coverage": "c8 --config c8.config.json node --test __test__/*.test.mjs",
+    "ci": "npm run format:check && npm run lint && npm run build:debug && npm test && npm run test:coverage",
+    "prepublishOnly": "napi build --release --platform"
+  },
+  "napi": {
+    "name": "qtty",
+    "triples": {
+      "defaults": true
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "native.cjs",
+    "lib/",
+    "units.js",
+    "units.d.ts",
+    "examples/",
+    "README.md"
+  ],
+  "keywords": [
+    "quantities",
+    "units",
+    "conversion",
+    "physics",
+    "science",
+    "astronomy",
+    "napi",
+    "rust",
+    "native"
+  ],
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Siderust/qtty"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@napi-rs/cli": "^3.5.1",
+    "c8": "^11.0.0",
+    "eslint": "^10.0.3",
+    "globals": "^17.4.0",
+    "prettier": "^3.6.2"
+  }
+}

package/qtty-js/qtty-node/units.d.ts

@@ -0,0 +1,299 @@
+import type { Quantity } from './index.js';
+
+/**
+ * A callable unit factory with attached metadata.
+ *
+ * Call it with a numeric value to produce a `Quantity`:
+ *
+ * ```ts
+ * import { Meters, Degrees } from '@siderust/qtty/units';
+ *
+ * const d = Meters(1000);   // Quantity { value: 1000, unit: 'Meter' }
+ * const a = Degrees(180);   // Quantity { value: 180,  unit: 'Degree' }
+ * ```
+ */
+export interface UnitFactory {
+  /** Create a Quantity with this unit. */
+  (value: number): Quantity;
+  /** Unit name, e.g. `"Meter"`. */
+  readonly unit: string;
+  /** Unit symbol, e.g. `"m"`. */
+  readonly symbol: string;
+  /** Dimension name, e.g. `"Length"`. */
+  readonly dimension: string;
+}
+
+// ── Length ───────────────────────────────────────────────────────────────────
+export declare const PlanckLengths: UnitFactory;
+export declare const Yoctometers: UnitFactory;
+export declare const Zeptometers: UnitFactory;
+export declare const Attometers: UnitFactory;
+export declare const Femtometers: UnitFactory;
+export declare const Picometers: UnitFactory;
+export declare const Nanometers: UnitFactory;
+export declare const Micrometers: UnitFactory;
+export declare const Millimeters: UnitFactory;
+export declare const Centimeters: UnitFactory;
+export declare const Decimeters: UnitFactory;
+export declare const Meters: UnitFactory;
+export declare const Decameters: UnitFactory;
+export declare const Hectometers: UnitFactory;
+export declare const Kilometers: UnitFactory;
+export declare const Megameters: UnitFactory;
+export declare const Gigameters: UnitFactory;
+export declare const Terameters: UnitFactory;
+export declare const Petameters: UnitFactory;
+export declare const Inches: UnitFactory;
+export declare const Feet: UnitFactory;
+export declare const Yards: UnitFactory;
+export declare const Miles: UnitFactory;
+export declare const NauticalMiles: UnitFactory;
+export declare const AstronomicalUnits: UnitFactory;
+export declare const LightYears: UnitFactory;
+export declare const Parsecs: UnitFactory;
+export declare const Kiloparsecs: UnitFactory;
+export declare const Megaparsecs: UnitFactory;
+export declare const Gigaparsecs: UnitFactory;
+
+// ── Time ─────────────────────────────────────────────────────────────────────
+export declare const Attoseconds: UnitFactory;
+export declare const Femtoseconds: UnitFactory;
+export declare const Picoseconds: UnitFactory;
+export declare const Nanoseconds: UnitFactory;
+export declare const Microseconds: UnitFactory;
+export declare const Milliseconds: UnitFactory;
+export declare const Seconds: UnitFactory;
+export declare const Minutes: UnitFactory;
+export declare const Hours: UnitFactory;
+export declare const Days: UnitFactory;
+export declare const Weeks: UnitFactory;
+export declare const Years: UnitFactory;
+export declare const Decades: UnitFactory;
+export declare const Centuries: UnitFactory;
+export declare const Millennia: UnitFactory;
+export declare const JulianYears: UnitFactory;
+export declare const JulianCenturies: UnitFactory;
+export declare const SiderealDays: UnitFactory;
+export declare const SynodicMonths: UnitFactory;
+export declare const SiderealYears: UnitFactory;
+
+// ── Angle ────────────────────────────────────────────────────────────────────
+export declare const Milliradians: UnitFactory;
+export declare const Radians: UnitFactory;
+export declare const MicroArcseconds: UnitFactory;
+export declare const MilliArcseconds: UnitFactory;
+export declare const Arcseconds: UnitFactory;
+export declare const Arcminutes: UnitFactory;
+export declare const Degrees: UnitFactory;
+export declare const Gradians: UnitFactory;
+export declare const Turns: UnitFactory;
+export declare const HourAngles: UnitFactory;
+
+// ── Mass ─────────────────────────────────────────────────────────────────────
+export declare const Micrograms: UnitFactory;
+export declare const Milligrams: UnitFactory;
+export declare const Grams: UnitFactory;
+export declare const Kilograms: UnitFactory;
+export declare const Tonnes: UnitFactory;
+export declare const Ounces: UnitFactory;
+export declare const Pounds: UnitFactory;
+export declare const Stones: UnitFactory;
+export declare const SolarMasses: UnitFactory;
+export declare const AtomicMassUnits: UnitFactory;
+
+// ── Power ────────────────────────────────────────────────────────────────────
+export declare const Milliwatts: UnitFactory;
+export declare const Watts: UnitFactory;
+export declare const Kilowatts: UnitFactory;
+export declare const Megawatts: UnitFactory;
+export declare const Gigawatts: UnitFactory;
+export declare const Terawatts: UnitFactory;
+export declare const SolarLuminosities: UnitFactory;
+
+// ── Dynamic access ───────────────────────────────────────────────────────────
+
+/**
+ * Look up a unit factory by exact unit name.
+ *
+ * ```ts
+ * import { unit } from '@siderust/qtty/units';
+ * const km = unit('Kilometer')!(2.5);
+ * ```
+ */
+export declare function unit(name: string): UnitFactory | undefined;
+
+/**
+ * All unit factories as a read-only record indexed by unit name.
+ */
+export declare const units: Readonly<Record<string, UnitFactory>>;
+
+// ── Unit name enum ────────────────────────────────────────────────────────────
+
+/** Union of every registered unit name. Use with `Unit` for type-safe lookups. */
+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.
+ *
+ * Use instead of raw string literals to get IDE autocomplete and avoid typos:
+ *
+ * ```ts
+ * import { Unit, Quantity } from '@siderust/qtty';
+ *
+ * const d  = new Quantity(1000, Unit.Meter);
+ * const km = d.to(Unit.Kilometer);
+ * convert(1, Unit.Meter, Unit.Kilometer);
+ * ```
+ *
+ * Each key is a string literal type, so `Unit.Meter` has type `'Meter'`.
+ */
+export declare const Unit: { readonly [K in UnitName]: K };

package/qtty-js/qtty-node/units.js

@@ -0,0 +1,210 @@
+/**
+ * @siderust/qtty — Unit factory constants.
+ *
+ * Every export is a **callable unit factory**: call it with a number to produce
+ * a `Quantity` for that unit.
+ *
+ * ```js
+ * import { Meters, Kilometers, Degrees, Kilograms } from '@siderust/qtty/units';
+ *
+ * const d  = Meters(1000);       // Quantity { value: 1000, unit: 'Meter' }
+ * const a  = Degrees(180);       // Quantity { value: 180,  unit: 'Degree' }
+ * const km = d.to('Kilometer');  // Quantity { value: 1,    unit: 'Kilometer' }
+ * ```
+ *
+ * Arithmetic shorthand — because JavaScript has no operator overloading, use
+ * the factory call instead of multiplication:
+ *
+ *   `Degrees(180)`    ≡  `new Quantity(180, 'Degree')`
+ *   `Kilometers(2.5)` ≡  `new Quantity(2.5, 'Kilometer')`
+ *
+ * Every factory also exposes the unit metadata as properties:
+ *
+ * ```js
+ * Meters.unit      // 'Meter'
+ * Meters.symbol    // 'm'
+ * Meters.dimension // 'Length'
+ * ```
+ */
+
+'use strict';
+
+const { Quantity } = require('./lib/Quantity.js');
+const { listUnits } = require('./lib/backend.js');
+
+/**
+ * Creates a unit factory function for the given unit name.
+ *
+ * @param {string} unitName
+ * @param {string} symbol
+ * @param {string} dimension
+ * @returns {UnitFactory}
+ */
+function makeFactory(unitName, symbol, dimension) {
+  /**
+   * @param {number} value
+   * @returns {import('./index.js').Quantity}
+   */
+  function factory(value) {
+    return new Quantity(value, unitName);
+  }
+
+  factory.unit = unitName;
+  factory.symbol = symbol;
+  factory.dimension = dimension;
+  factory.toString = () => unitName;
+  factory[Symbol.toStringTag] = `Unit(${unitName})`;
+
+  return factory;
+}
+
+// Build factories for every registered unit.
+const _all = listUnits();
+
+/**
+ * All unit factories indexed by unit name.
+ * @type {Record<string, UnitFactory>}
+ */
+const byName = Object.create(null);
+
+for (const { name, symbol, dimension } of _all) {
+  byName[name] = makeFactory(name, symbol, dimension);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Named exports — common units for ergonomic imports
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Length
+exports.PlanckLengths = byName['PlanckLength'];
+exports.Yoctometers = byName['Yoctometer'];
+exports.Zeptometers = byName['Zeptometer'];
+exports.Attometers = byName['Attometer'];
+exports.Femtometers = byName['Femtometer'];
+exports.Picometers = byName['Picometer'];
+exports.Nanometers = byName['Nanometer'];
+exports.Micrometers = byName['Micrometer'];
+exports.Millimeters = byName['Millimeter'];
+exports.Centimeters = byName['Centimeter'];
+exports.Decimeters = byName['Decimeter'];
+exports.Meters = byName['Meter'];
+exports.Decameters = byName['Decameter'];
+exports.Hectometers = byName['Hectometer'];
+exports.Kilometers = byName['Kilometer'];
+exports.Megameters = byName['Megameter'];
+exports.Gigameters = byName['Gigameter'];
+exports.Terameters = byName['Terameter'];
+exports.Petameters = byName['Petameter'];
+exports.Inches = byName['Inch'];
+exports.Feet = byName['Foot'];
+exports.Yards = byName['Yard'];
+exports.Miles = byName['Mile'];
+exports.NauticalMiles = byName['NauticalMile'];
+exports.AstronomicalUnits = byName['AstronomicalUnit'];
+exports.LightYears = byName['LightYear'];
+exports.Parsecs = byName['Parsec'];
+exports.Kiloparsecs = byName['Kiloparsec'];
+exports.Megaparsecs = byName['Megaparsec'];
+exports.Gigaparsecs = byName['Gigaparsec'];
+
+// Time
+exports.Attoseconds = byName['Attosecond'];
+exports.Femtoseconds = byName['Femtosecond'];
+exports.Picoseconds = byName['Picosecond'];
+exports.Nanoseconds = byName['Nanosecond'];
+exports.Microseconds = byName['Microsecond'];
+exports.Milliseconds = byName['Millisecond'];
+exports.Seconds = byName['Second'];
+exports.Minutes = byName['Minute'];
+exports.Hours = byName['Hour'];
+exports.Days = byName['Day'];
+exports.Weeks = byName['Week'];
+exports.Years = byName['Year'];
+exports.Decades = byName['Decade'];
+exports.Centuries = byName['Century'];
+exports.Millennia = byName['Millennium'];
+exports.JulianYears = byName['JulianYear'];
+exports.JulianCenturies = byName['JulianCentury'];
+exports.SiderealDays = byName['SiderealDay'];
+exports.SynodicMonths = byName['SynodicMonth'];
+exports.SiderealYears = byName['SiderealYear'];
+
+// Angle
+exports.Milliradians = byName['Milliradian'];
+exports.Radians = byName['Radian'];
+exports.MicroArcseconds = byName['MicroArcsecond'];
+exports.MilliArcseconds = byName['MilliArcsecond'];
+exports.Arcseconds = byName['Arcsecond'];
+exports.Arcminutes = byName['Arcminute'];
+exports.Degrees = byName['Degree'];
+exports.Gradians = byName['Gradian'];
+exports.Turns = byName['Turn'];
+exports.HourAngles = byName['HourAngle'];
+
+// Mass
+exports.Micrograms = byName['Microgram'];
+exports.Milligrams = byName['Milligram'];
+exports.Grams = byName['Gram'];
+exports.Kilograms = byName['Kilogram'];
+exports.Tonnes = byName['Tonne'];
+exports.Ounces = byName['Ounce'];
+exports.Pounds = byName['Pound'];
+exports.Stones = byName['Stone'];
+exports.SolarMasses = byName['SolarMass'];
+exports.AtomicMassUnits = byName['AtomicMassUnit'];
+
+// Power
+exports.Milliwatts = byName['Milliwatt'];
+exports.Watts = byName['Watt'];
+exports.Kilowatts = byName['Kilowatt'];
+exports.Megawatts = byName['Megawatt'];
+exports.Gigawatts = byName['Gigawatt'];
+exports.Terawatts = byName['Terawatt'];
+exports.SolarLuminosities = byName['SolarLuminosity'];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Dynamic access helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Look up a unit factory by exact unit name.
+ *
+ * ```js
+ * import { unit } from '@siderust/qtty/units';
+ * const km = unit('Kilometer')(2.5);
+ * ```
+ *
+ * @param {string} name - Unit name, e.g. `'Kilometer'`.
+ * @returns {UnitFactory | undefined}
+ */
+exports.unit = (name) => byName[name];
+
+/**
+ * All unit factories as an object indexed by unit name.
+ * @type {Readonly<Record<string, UnitFactory>>}
+ */
+exports.units = Object.freeze({ ...byName });
+
+/**
+ * Const map of all registered unit names.
+ *
+ * Use instead of raw string literals to get IDE autocomplete and avoid typos:
+ *
+ * ```js
+ * import { Unit } from '@siderust/qtty/units';
+ *
+ * const d  = new Quantity(1000, Unit.Meter);
+ * const km = d.to(Unit.Kilometer);
+ * convert(1, Unit.Meter, Unit.Kilometer);
+ * ```
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+exports.Unit = Object.freeze(Object.fromEntries(_all.map((u) => [u.name, u.name])));
+
+/**
+ * @typedef {object} UnitFactory
+ * @property {string} unit      - Unit name.
+ * @property {string} symbol    - Unit symbol.
+ * @property {string} dimension - Dimension name.
+ */