siderust-js 0.1.0

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

@@ -0,0 +1,125 @@
+/**
+ * serialization.mjs — JSON serialization of quantities.
+ *
+ * Demonstrates:
+ *  - `quantity.toJson()`  → plain object `{ value, unit }`
+ *  - `JSON.stringify()`   → JSON string
+ *  - Restoring a quantity from a JSON object via `new Quantity(...)`
+ *  - `derivedQuantity.toJson()` → `{ value, numerator, denominator }`
+ *  - A practical "API payload" round-trip pattern
+ *
+ * Run: node examples/serialization.mjs
+ */
+
+import { Quantity, DerivedQuantity } from '../index.js';
+
+const line = (label = '') =>
+  console.log(
+    label ? `─── ${label} ${`─`.repeat(Math.max(0, 52 - label.length))}` : `─`.repeat(56),
+  );
+
+// ─── Quantity → plain object → JSON string ───────────────────────────────
+line('Quantity.toJson()');
+
+const distance = new Quantity(42_195, 'Meter'); // marathon distance
+const time = new Quantity(2.01389, 'Hour'); // world-record approx
+const mass = new Quantity(70, 'Kilogram');
+
+for (const q of [distance, time, mass]) {
+  const plain = q.toJson(); // { value, unit }
+  const json = JSON.stringify(plain);
+  console.log(`  ${String(q).padEnd(22)} → ${json}`);
+}
+
+// ─── JSON string → Quantity (round-trip) ─────────────────────────────────
+line('Round-trip: JSON → Quantity');
+
+const marathonJson = JSON.stringify(distance.toJson()); // "{"value":42195,"unit":"Meter"}"
+const parsed = JSON.parse(marathonJson); // { value: 42195, unit: 'Meter' }
+const restored = new Quantity(parsed.value, parsed.unit);
+
+console.log(`  original  : ${distance}`);
+console.log(`  JSON text : ${marathonJson}`);
+console.log(`  restored  : ${restored}`);
+console.log(`  equal     : ${Math.abs(restored.value - distance.value) < 1e-9}`);
+
+// ─── DerivedQuantity → JSON ───────────────────────────────────────────────
+line('DerivedQuantity.toJson()');
+
+const soundSpeed = new DerivedQuantity(343, 'Meter', 'Second'); // air at 20 °C
+const earthVelocity = new DerivedQuantity(29.783, 'Kilometer', 'Second');
+const lightSpeed = new DerivedQuantity(299_792.458, 'Kilometer', 'Second');
+
+for (const dq of [soundSpeed, earthVelocity, lightSpeed]) {
+  const plain = dq.toJson(); // { value, numerator, denominator }
+  const json = JSON.stringify(plain);
+  console.log(`  ${String(dq).padEnd(28)} → ${json}`);
+}
+
+// ─── DerivedQuantity round-trip ────────────────────────────────────────────
+line('Round-trip: JSON → DerivedQuantity');
+
+const velJson = JSON.stringify(earthVelocity.toJson());
+const velObj = JSON.parse(velJson);
+const velRt = new DerivedQuantity(velObj.value, velObj.numerator, velObj.denominator);
+
+console.log(`  original   : ${earthVelocity}`);
+console.log(`  JSON text  : ${velJson}`);
+console.log(`  restored   : ${velRt}`);
+console.log(`  in km/h    : ${velRt.to('Kilometer', 'Hour').format(2)}`);
+
+// ─── API payload pattern ──────────────────────────────────────────────────
+line('API payload: serialize / deserialize');
+
+/**
+ * Simulated server response with a list of physical measurements.
+ */
+const serverPayload = JSON.stringify([
+  { value: 1.496e11, unit: 'Meter' }, // 1 AU
+  { value: 9.461e15, unit: 'Meter' }, // 1 light-year
+  { value: 3.086e16, unit: 'Meter' }, // 1 parsec
+]);
+
+const measurements = JSON.parse(serverPayload).map(({ value, unit }) => new Quantity(value, unit));
+
+const names = ['1 AU', '1 ly', '1 pc'];
+console.log('  Distances received from API:');
+for (const [name, q] of names.map((n, i) => [n, measurements[i]])) {
+  const km = q.to('Kilometer');
+  console.log(
+    `    ${name.padEnd(5)} = ${q.value.toExponential(3)} m = ${km.value.toExponential(3)} km`,
+  );
+}
+
+// ─── Derived payload ──────────────────────────────────────────────────────
+line('Derived API payload');
+
+const derivedPayload = JSON.stringify([
+  { value: 11.2, numerator: 'Kilometer', denominator: 'Second' }, // Earth escape velocity
+  { value: 617.7, numerator: 'Kilometer', denominator: 'Second' }, // Solar escape velocity
+]);
+
+const velocities = JSON.parse(derivedPayload).map(
+  ({ value, numerator, denominator }) => new DerivedQuantity(value, numerator, denominator),
+);
+
+const velNames = ['Earth escape', 'Solar escape'];
+for (const [name, v] of velNames.map((n, i) => [n, velocities[i]])) {
+  const kmh = v.to('Kilometer', 'Hour');
+  console.log(`  ${name.padEnd(14)}: ${String(v).padEnd(16)} = ${kmh.format(0)}`);
+}
+
+// ─── listUnits introspection via JSON ─────────────────────────────────────
+line('JSON catalog of available units');
+
+import { listUnits } from '../index.js';
+const allUnits = listUnits();
+const byDim = {};
+for (const u of allUnits) {
+  (byDim[u.dimension] ??= []).push(u.name);
+}
+for (const [dim, names_] of Object.entries(byDim).sort()) {
+  console.log(
+    `  ${dim.padEnd(10)} (${names_.length}): ${names_.slice(0, 5).join(', ')}${names_.length > 5 ? ', …' : ''}`,
+  );
+}

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

@@ -0,0 +1,74 @@
+/**
+ * unit_factories.mjs — Arithmetic-style construction with unit factories.
+ *
+ * Unit factories let you write Degrees(180) instead of new Quantity(180, 'Degree'),
+ * giving a concise, readable style that reads like "180 Degrees".
+ *
+ * Run: node examples/unit_factories.mjs
+ */
+
+import {
+  Meters,
+  Kilometers,
+  LightYears,
+  Hours,
+  Degrees,
+  Kilograms,
+  Kilowatts,
+  unit,
+  units,
+} from '../units.js';
+
+console.log('─── Unit factories (Degrees(180) ≡ new Quantity(180, "Degree")) ───');
+
+const angle = Degrees(180); // same as: new Quantity(180, 'Degree')
+const dist = Kilometers(2.5); // same as: new Quantity(2.5, 'Kilometer')
+const time = Hours(1.5); // same as: new Quantity(1.5, 'Hour')
+const mass = Kilograms(70); // same as: new Quantity(70,  'Kilogram')
+const power = Kilowatts(100); // same as: new Quantity(100, 'Kilowatt')
+
+console.log(`  Degrees(180)     → ${angle}`);
+console.log(`  Kilometers(2.5)  → ${dist}`);
+console.log(`  Hours(1.5)       → ${time}`);
+console.log(`  Kilograms(70)    → ${mass}`);
+console.log(`  Kilowatts(100)   → ${power}`);
+
+console.log('\n─── Factory metadata ──────────────────────────────────────────────');
+console.log(`  Meters.unit      = ${Meters.unit}`); // Meter
+console.log(`  Meters.symbol    = ${Meters.symbol}`); // m
+console.log(`  Meters.dimension = ${Meters.dimension}`); // Length
+console.log(`  Degrees.symbol   = ${Degrees.symbol}`); // °
+
+console.log('\n─── Convert using factories ───────────────────────────────────────');
+
+const rad = Degrees(180).to('Radian');
+console.log(`  Degrees(180) → ${rad.format(6)}`); // 3.141593 rad
+
+const inMeters = Kilometers(2.5).to('Meter');
+console.log(`  Kilometers(2.5) → ${inMeters}`); // 2500 m
+
+const inMiles = Kilometers(1.609344).to('Mile');
+console.log(`  Kilometers(1.609344) → ${inMiles.format(4)}`); // 1.0000 mi
+
+const inParsecs = LightYears(3.26156).to('Parsec');
+console.log(`  LightYears(3.26156) → ${inParsecs.format(4)}`); // 1.0000 pc
+
+const inSeconds = Hours(2).to('Second');
+console.log(`  Hours(2) → ${inSeconds}`); // 7200 s
+
+const inPounds = Kilograms(1).to('Pound');
+console.log(`  Kilograms(1) → ${inPounds.format(6)}`); // 2.204623 lb
+
+console.log('\n─── Dynamic lookup with unit() ────────────────────────────────────');
+const factory = unit('SolarMass');
+if (factory) {
+  const sun = factory(1);
+  console.log(`  unit('SolarMass')(1) → ${sun}`); // 1 M_☉
+  console.log(`  Dimension: ${sun.dimension}`); // Mass
+}
+
+console.log('\n─── Browse all units for a dimension ──────────────────────────────');
+const lengthUnits = Object.values(units)
+  .filter((f) => f.dimension === 'Length')
+  .map((f) => `${f.unit} (${f.symbol})`);
+console.log(`  Length units (${lengthUnits.length}): ${lengthUnits.slice(0, 8).join(', ')}, …`);

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

@@ -0,0 +1,219 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/** 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
+}
+/**
+ * Converts a numeric value from one unit to another.
+ *
+ * This is a convenience function when you only need the converted number.
+ *
+ * ```js
+ * const { convert } = require('@siderust/qtty');
+ * const km = convert(1000, 'Meter', 'Kilometer'); // 1.0
+ * ```
+ *
+ * @param value    - The numeric value.
+ * @param fromUnit - Source unit name.
+ * @param toUnit   - Target unit name.
+ * @returns The converted value.
+ * @throws If units are unknown or have different dimensions.
+ */
+export declare function convert(value: number, fromUnit: string, toUnit: string): number
+/**
+ * Checks whether two unit names refer to compatible units (same dimension).
+ *
+ * ```js
+ * const { isCompatible } = require('@siderust/qtty');
+ * isCompatible('Meter', 'Kilometer'); // true
+ * isCompatible('Meter', 'Second');    // false
+ * ```
+ */
+export declare function isCompatible(unitA: string, unitB: string): boolean
+/**
+ * Returns the dimension name for a unit, e.g. `"Length"`, `"Time"`.
+ *
+ * ```js
+ * const { unitDimension } = require('@siderust/qtty');
+ * unitDimension('Meter');  // "Length"
+ * unitDimension('Second'); // "Time"
+ * ```
+ */
+export declare function unitDimension(unit: string): string
+/**
+ * Returns the symbol for a unit, e.g. `"m"`, `"km"`, `"s"`.
+ *
+ * ```js
+ * const { unitSymbol } = require('@siderust/qtty');
+ * unitSymbol('Meter');     // "m"
+ * unitSymbol('Kilometer'); // "km"
+ * ```
+ */
+export declare function unitSymbol(unit: string): string
+/**
+ * Checks whether a unit name is valid (recognized by the registry).
+ *
+ * ```js
+ * const { isValidUnit } = require('@siderust/qtty');
+ * isValidUnit('Meter');   // true
+ * isValidUnit('Foobar');  // false
+ * ```
+ */
+export declare function isValidUnit(unit: string): boolean
+/** Returns the FFI ABI version number. */
+export declare function ffiVersion(): number
+/** Metadata about a single unit returned by `listUnits`. */
+export interface UnitInfo {
+  /** Unit name, e.g. `"Meter"`. */
+  name: string
+  /** Unit symbol, e.g. `"m"`. */
+  symbol: string
+  /** Dimension name, e.g. `"Length"`. */
+  dimension: string
+}
+/**
+ * Returns an array of all registered units with their name, symbol, and dimension.
+ *
+ * This is useful for building dynamic UIs, documenting available units,
+ * or generating unit factory collections at runtime.
+ *
+ * ```js
+ * const { listUnits } = require('@siderust/qtty');
+ * const units = listUnits();
+ * units.filter(u => u.dimension === 'Length').map(u => u.name);
+ * ```
+ */
+export declare function listUnits(): Array<UnitInfo>
+/**
+ * A physical quantity: a numeric value paired with a unit.
+ *
+ * Create quantities with `new Quantity(value, unit)` and convert between
+ * compatible units with `.to(unit)`.
+ *
+ * ```js
+ * const { Quantity } = require('@siderust/qtty');
+ *
+ * const distance = new Quantity(1000, 'Meter');
+ * const km = distance.to('Kilometer');
+ * console.log(km.value); // 1.0
+ * console.log(km.unit);  // "Kilometer"
+ * ```
+ */
+export declare class Quantity {
+  /**
+   * Creates a new quantity with the given value and unit name.
+   *
+   * @param value - The numeric value.
+   * @param unit  - Unit name, e.g. `"Meter"`, `"Kilometer"`, `"Second"`.
+   * @throws If the unit name is not recognized.
+   */
+  constructor(value: number, unit: string)
+  /** The numeric value of this quantity. */
+  get value(): number
+  /** The unit name, e.g. `"Meter"`. */
+  get unit(): string
+  /** The unit symbol, e.g. `"m"`, `"km"`, `"s"`. */
+  get symbol(): string
+  /** The physical dimension of this quantity, e.g. `"Length"`, `"Time"`. */
+  get dimension(): string
+  /**
+   * Converts this quantity to a different unit.
+   *
+   * @param unit - Target unit name, e.g. `"Kilometer"`.
+   * @returns A new `Quantity` in the target unit.
+   * @throws If the target unit is unknown or has a different dimension.
+   */
+  to(unit: string): Quantity
+  /** Checks whether this quantity is compatible (same dimension) with another. */
+  compatible(other: Quantity): boolean
+  /**
+   * Adds another quantity to this one. Both must share the same dimension.
+   * The result uses this quantity's unit.
+   *
+   * @throws If the quantities have different dimensions.
+   */
+  add(other: Quantity): Quantity
+  /**
+   * Subtracts another quantity from this one. Both must share the same dimension.
+   * The result uses this quantity's unit.
+   *
+   * @throws If the quantities have different dimensions.
+   */
+  sub(other: Quantity): Quantity
+  /** Multiplies this quantity by a scalar. */
+  mul(scalar: number): Quantity
+  /** Divides this quantity by a scalar. */
+  div(scalar: number): Quantity
+  /** Negates the quantity. */
+  neg(): Quantity
+  /**
+   * Formats the quantity as a human-readable string, e.g. `"1000 m"`.
+   *
+   * @param precision - Number of decimal digits (omit for default).
+   */
+  format(precision?: number | undefined | null): string
+  /** Returns the quantity as a plain object `{ value, unit }` suitable for JSON. */
+  toJson(): QuantityJson
+  /** Returns `"<value> <symbol>"`, e.g. `"1000 m"`. */
+  toString(): string
+}
+/**
+ * A derived (compound) quantity like velocity (m/s) or angular velocity (rad/s).
+ *
+ * ```js
+ * const { DerivedQuantity } = require('@siderust/qtty');
+ *
+ * const velocity = new DerivedQuantity(100, 'Meter', 'Second');
+ * const kmh = velocity.to('Kilometer', 'Hour');
+ * console.log(kmh.value); // 360
+ * ```
+ */
+export declare class DerivedQuantity {
+  /**
+   * Creates a new derived quantity.
+   *
+   * @param value       - The numeric value.
+   * @param numerator   - Numerator unit name, e.g. `"Meter"`.
+   * @param denominator - Denominator unit name, e.g. `"Second"`.
+   */
+  constructor(value: number, numerator: string, denominator: string)
+  /** The numeric value. */
+  get value(): number
+  /** The numerator unit name. */
+  get numerator(): string
+  /** The denominator unit name. */
+  get denominator(): string
+  /** The compound symbol, e.g. `"m/s"`. */
+  get symbol(): string
+  /**
+   * Converts this derived quantity to different units.
+   *
+   * @param numerator   - Target numerator unit.
+   * @param denominator - Target denominator unit.
+   * @throws If the dimensions are incompatible.
+   */
+  to(numerator: string, denominator: string): DerivedQuantity
+  /** Multiplies by a scalar. */
+  mul(scalar: number): DerivedQuantity
+  /** Divides by a scalar. */
+  div(scalar: number): DerivedQuantity
+  /** Negates the value. */
+  neg(): DerivedQuantity
+  /** Formats as `"<value> <num_symbol>/<den_symbol>"`. */
+  format(precision?: number | undefined | null): string
+  /** Returns the derived quantity as a plain object. */
+  toJson(): DerivedQuantityJson
+  /** Returns `"<value> <num_symbol>/<den_symbol>"`. */
+  toString(): string
+}