@thi.ng/units 1.3.1 → 1.4.0

package/README.md

@@ -45,6 +45,10 @@
   - [Quantities](#quantities)
     - [Constants](#constants)
 - [Domain-specific language](#domain-specific-language)
+- [CLI usage](#cli-usage)
+  - [Unit calculator](#unit-calculator)
+  - [Unit conversion](#unit-conversion)
+  - [List units](#list-units)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -54,7 +58,7 @@
 
 ## About
 
-Extensible SI unit creation, conversions, quantities & calculations (incl. Lisp-like DSL and ~170 predefined units & constants).
+Extensible SI unit creation, conversions, quantities & calculations, CLI calculator (incl. Lisp-like DSL and ~170 predefined units & constants).
 
 All unit definitions, quantities & conversions are based on the SI unit system &
 concepts described here:
@@ -656,6 +660,70 @@ console.log($eval(`(kg (* 200mm 300mm 0.5in glass))`));
 // 1.905
 ```
 
+## CLI usage
+
+Since v1.4.0 a small CLI is included with the following commands:
+
+```bash
+npx @thi.ng/units
+
+#  █ █   █           │
+# ██ █               │
+#  █ █ █ █   █ █ █ █ │ @thi.ng/units v1.4.0
+#  █ █ █ █ █ █ █ █ █ │ Unit converter & calculator
+#                  █ │
+#                █ █ │
+#
+# Available commands:
+#
+# calc    : Unit calculator (S-expression)
+# convert : Unit conversion (x srcunit destunit)
+# list    : List known units (optionally filtered by given pattern)
+```
+
+### Unit calculator
+
+The `calc` command takes a [DSL S-expression](#domain-specific-language) and
+prints the result (the expression should be wrapped in single quotes):
+
+```bash
+# calculate the weight of a A4 sheet of paper with 320 grams per square meter
+npx @thi.ng/units calc '(g (* 320gsm (area din_a4)))'
+
+# 19.958399999999997
+```
+
+### Unit conversion
+
+The `convert` command takes a quantity, source unit and destination unit, and
+prints the result:
+
+```bash
+# convert 40 degree celsius to fahrenheit
+npx @thi.ng/units convert 40 celsius fahrenheit
+
+# 103.99999999999993
+```
+
+### List units
+
+The `list` command prints out all known units, incl. aliases and full name for
+each unit. THe output can be filtered via optionally given pattern (regexp):
+
+```bash
+# list all units matching `gram`
+npx @thi.ng/units list gram
+
+# symbol    aliases                         name
+# ------------------------------------------------------------------------
+# g         gram                            gram
+# g/m2      gsm, gram_per_square_meter      gram per square meter
+# kg        kilogram                        kilogram
+# kg/m3     kilogram_per_cubic_meter        kilogram per cubic meter
+# mg        milligram                       milligram
+# µg        microgram                       microgram
+```
+
 ## Status
 
 **BETA** - possibly breaking changes forthcoming
@@ -688,15 +756,18 @@ For Node.js REPL:
 const units = await import("@thi.ng/units");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 5.74 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 5.93 KB
 
 ## Dependencies
 
 - [@thi.ng/api](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/api)
+- [@thi.ng/args](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/args)
 - [@thi.ng/checks](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/checks)
+- [@thi.ng/compare](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/compare)
 - [@thi.ng/equiv](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/equiv)
 - [@thi.ng/errors](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/errors)
 - [@thi.ng/sexpr](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/sexpr)
+- [@thi.ng/strings](https://codeberg.org/thi.ng/umbrella/src/branch/develop/packages/strings)
 
 Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)
 

package/bin/units

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+# https://stackoverflow.com/a/246128/294515
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+DIR="$(dirname $DIR)"
+
+# prefer using bun
+if [ -x "$(command -v bun)" ]; then
+  CMD=bun
+else
+  CMD=node
+fi
+
+/usr/bin/env $CMD "$DIR/cli.js" "$DIR" "$@"

package/cli.d.ts

@@ -0,0 +1,4 @@
+import "./units/index.js";
+export interface CLIOpts {
+}
+//# sourceMappingURL=cli.d.ts.map

package/cli.js

@@ -0,0 +1,62 @@
+import { cliApp, THING_HEADER } from "@thi.ng/args";
+import { compareByKey } from "@thi.ng/compare/keys";
+import { defFormat } from "@thi.ng/strings/format";
+import { padRight } from "@thi.ng/strings/pad-right";
+import { $eval } from "./dsl.js";
+import { ALIASES, UNITS } from "./unit.js";
+import "./units/index.js";
+cliApp({
+  name: "units",
+  start: 3,
+  opts: {},
+  commands: {
+    list: {
+      desc: "List known units (optionally filtered by given pattern)",
+      opts: {},
+      inputs: [0, 1],
+      fn: async ({ inputs }) => {
+        const re = inputs.length ? new RegExp(inputs[0]) : null;
+        const fmt = defFormat([
+          padRight(10),
+          padRight(32),
+          (x) => x
+        ]);
+        console.log(
+          fmt("symbol", "aliases", "name"),
+          "\n" + "-".repeat(72)
+        );
+        for (let [sym, aliases] of Object.entries(ALIASES).sort(
+          compareByKey(0)
+        )) {
+          if (re && !(re.test(UNITS[sym].name) || [...aliases, sym].some((x) => re.test(x))))
+            continue;
+          console.log(fmt(sym, aliases.join(", "), UNITS[sym].name));
+        }
+      }
+    },
+    convert: {
+      desc: "Unit conversion (x srcunit destunit)",
+      opts: {},
+      inputs: 3,
+      fn: async ({ inputs }) => {
+        console.log($eval(`(${inputs[2]} ${inputs[0]}${inputs[1]})`));
+      }
+    },
+    calc: {
+      desc: "Unit calculator (S-expression)",
+      opts: {},
+      inputs: 1,
+      fn: async ({ inputs }) => {
+        console.log($eval(inputs[0]));
+      }
+    }
+  },
+  ctx: async (ctx) => ctx,
+  usage: {
+    prefix: THING_HEADER(
+      "@thi.ng/units",
+      "1.4.0",
+      "Unit converter & calculator"
+    ) + "\n"
+  }
+});

package/package.json

@@ -1,10 +1,11 @@
 {
 	"name": "@thi.ng/units",
-	"version": "1.3.1",
-	"description": "Extensible SI unit creation, conversions, quantities & calculations (incl. Lisp-like DSL and ~170 predefined units & constants)",
+	"version": "1.4.0",
+	"description": "Extensible SI unit creation, conversions, quantities & calculations, CLI calculator (incl. Lisp-like DSL and ~170 predefined units & constants)",
 	"type": "module",
 	"module": "./index.js",
 	"typings": "./index.d.ts",
+	"bin": "bin/units",
 	"sideEffects": false,
 	"repository": {
 		"type": "git",
@@ -40,16 +41,19 @@
 		"tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
 	},
 	"dependencies": {
-		"@thi.ng/api": "^8.12.21",
-		"@thi.ng/checks": "^3.9.1",
-		"@thi.ng/equiv": "^2.1.110",
-		"@thi.ng/errors": "^2.6.10",
-		"@thi.ng/sexpr": "^1.1.31"
+		"@thi.ng/api": "^8.12.22",
+		"@thi.ng/args": "^3.2.20",
+		"@thi.ng/checks": "^3.9.2",
+		"@thi.ng/compare": "^2.5.10",
+		"@thi.ng/equiv": "^2.1.111",
+		"@thi.ng/errors": "^2.6.11",
+		"@thi.ng/sexpr": "^1.1.32",
+		"@thi.ng/strings": "^3.12.4"
 	},
 	"devDependencies": {
 		"esbuild": "^0.28.0",
-		"typedoc": "^0.28.18",
-		"typescript": "^5.9.3"
+		"typedoc": "^0.28.19",
+		"typescript": "^6.0.3"
 	},
 	"keywords": [
 		"acceleration",
@@ -59,6 +63,7 @@
 		"bytes",
 		"calculation",
 		"capacitance",
+		"cli",
 		"conversion",
 		"current",
 		"dsl",
@@ -106,6 +111,9 @@
 		"./api": {
 			"default": "./api.js"
 		},
+		"./cli": {
+			"default": "./cli.js"
+		},
 		"./constants/densities": {
 			"default": "./constants/densities.js"
 		},
@@ -189,5 +197,5 @@
 		"status": "beta",
 		"year": 2021
 	},
-	"gitHead": "dcaa4e2beb427e434a68cba1259a9bf9983a569a"
+	"gitHead": "983c49325b676db85989505c240b976db73fa8a8"
 }

package/unit.d.ts

@@ -4,6 +4,12 @@ import { type Dimensions, type MaybeUnit, type NamedUnit, type Prefix, type Unit
  * Cache/registry for all units defined via {@link defUnit}.
  */
 export declare const UNITS: Record<string, NamedUnit>;
+/**
+ * Cache/registry of all unit symbols defined via {@link defUnit}. The keys of
+ * this object are the canonical symbols of each unit. The values are string
+ * arrays of known aliases.
+ */
+export declare const ALIASES: Record<string, string[]>;
 /**
  * Defines a "raw" (anonymous) unit using given dimension(s), scale factor, zero
  * offset and `coherent` flag indicating if the unit is the coherent one for
@@ -32,19 +38,24 @@ export declare const coherent: (dim: Dimensions | number) => Unit;
  */
 export declare const dimensionless: (scale: number, offset?: number, coherent?: boolean) => Unit;
 /**
- * Takes a unit symbol, full unit name and pre-defined {@link Unit} impl and
- * registers it in the {@link UNITS} cache for further lookups by symbol name.
+ * Takes one or multiple unit symbols, full unit name and pre-defined
+ * {@link Unit} impl, then registers unit in the {@link UNITS} cache for further
+ * lookups by given symbol names.
  *
  * @remarks
+ * Since v1.4.0, the unit is also registered under a modified lowercased version
+ * of `name`, where all spaces are being replaced by `_`. All registered aliases
+ * will be stored in {@link ALIASES}.
+ *
  * By default throws an error if attempting to register a unit with an existing
  * symbol. If `force` is true, the existing unit will be overwritten.
  *
- * @param sym
+ * @param syms
  * @param name
  * @param unit
  * @param force
  */
-export declare const defUnit: (sym: string, name: string, unit: Unit, force?: boolean) => NamedUnit;
+export declare const defUnit: (syms: string | string[], name: string, unit: Unit, force?: boolean) => NamedUnit;
 /**
  * Attempts to find a unit by given symbol ID/name. Throws error if unit is
  * unknown.

package/unit.js

@@ -9,6 +9,7 @@ import {
   PREFIXES
 } from "./api.js";
 const UNITS = {};
+const ALIASES = {};
 const unit = (dim, scale, offset = 0, coherent2 = false) => ({
   dim: isNumber(dim) ? __oneHot(dim) : dim,
   scale,
@@ -17,9 +18,20 @@ const unit = (dim, scale, offset = 0, coherent2 = false) => ({
 });
 const coherent = (dim) => unit(dim, 1, 0, true);
 const dimensionless = (scale, offset = 0, coherent2 = false) => unit(NONE.dim, scale, offset, coherent2);
-const defUnit = (sym, name, unit2, force = false) => {
-  if (UNITS[sym] && !force) illegalArgs(`attempt to override unit: ${sym}`);
-  return UNITS[sym] = { ...unit2, sym, name };
+const defUnit = (syms, name, unit2, force = false) => {
+  const $syms = isArray(syms) ? syms : [syms];
+  assert($syms.length > 0, `require at least one unit symbol`);
+  const $name = name.toLowerCase().replaceAll(" ", "_");
+  if (!$syms.includes($name)) $syms.push($name);
+  const canonical = $syms[0];
+  ALIASES[canonical] = [];
+  for (let sym of $syms) {
+    if (UNITS[sym] && !force)
+      illegalArgs(`attempt to override unit: ${sym}`);
+    UNITS[sym] = { ...unit2, sym, name };
+    if (sym !== canonical) ALIASES[canonical].push(sym);
+  }
+  return UNITS[canonical];
 };
 const asUnit = (id) => {
   for (let i = 0; i < id.length; i++) {
@@ -163,6 +175,7 @@ const __combineQ = (op, a, b) => {
   );
 };
 export {
+  ALIASES,
   Quantity,
   UNITS,
   add,

package/units/area.js

@@ -1,9 +1,9 @@
 import { cm, ft, inch, km, m, mi, mm } from "./length.js";
 import { defUnit, mul, pow } from "../unit.js";
-const m2 = defUnit("m2", "square meter", pow(m, 2));
-const mm2 = defUnit("mm2", "square millimeter", pow(mm, 2));
-const cm2 = defUnit("cm2", "square centimeter", pow(cm, 2));
-const km2 = defUnit("km2", "square kilometer", pow(km, 2));
+const m2 = defUnit(["m2", "sqm"], "square meter", pow(m, 2));
+const mm2 = defUnit(["mm2", "sqmm"], "square millimeter", pow(mm, 2));
+const cm2 = defUnit(["cm2", "sqcm"], "square centimeter", pow(cm, 2));
+const km2 = defUnit(["km2", "sqkm"], "square kilometer", pow(km, 2));
 const ha = defUnit("ha", "hectar", mul(m2, 1e4));
 const ac = defUnit("ac", "acre", mul(m2, 4046.86));
 const sqin = defUnit("sqin", "square inch", pow(inch, 2));

package/units/density.d.ts

@@ -1,8 +1,4 @@
 export declare const g_m2: import("../api.js").NamedUnit;
-/**
- * Alias for {@link g_m2}
- */
-export declare const gsm: import("../api.js").NamedUnit;
 export declare const kg_m3: import("../api.js").NamedUnit;
 export declare const dpi: import("../api.js").NamedUnit;
 //# sourceMappingURL=density.d.ts.map

package/units/density.js

@@ -3,13 +3,15 @@ import { m2 } from "./area.js";
 import { inch } from "./length.js";
 import { g, kg } from "./mass.js";
 import { m3 } from "./volume.js";
-const g_m2 = defUnit("g/m2", "gram per square meter", div(g, m2));
-const gsm = defUnit("gsm", "gram per square meter", div(g, m2));
+const g_m2 = defUnit(
+  ["g/m2", "gsm"],
+  "gram per square meter",
+  div(g, m2)
+);
 const kg_m3 = defUnit("kg/m3", "kilogram per cubic meter", div(kg, m3));
 const dpi = defUnit("dpi", "dots per inch", reciprocal(inch));
 export {
   dpi,
   g_m2,
-  gsm,
   kg_m3
 };

package/units/electric.js

@@ -4,7 +4,7 @@ import { h, s } from "./time.js";
 import { coherent, defUnit, div, mul, prefix } from "../unit.js";
 const A = defUnit("A", "ampere", coherent(3));
 const mA = defUnit("mA", "milliampere", prefix("m", A));
-const mAh = defUnit("mAh", "milliampere-hour", mul(mA, h));
+const mAh = defUnit("mAh", "milliampere hour", mul(mA, h));
 const C = defUnit("C", "coulomb", mul(A, s, true));
 const V = defUnit("V", "volt", div(J, C, true));
 const mV = defUnit("mV", "millivolt", prefix("m", V));

package/units/force.d.ts

@@ -1,2 +1,3 @@
 export declare const N: import("../api.js").NamedUnit;
+export declare const kN: import("../api.js").NamedUnit;
 //# sourceMappingURL=force.d.ts.map

package/units/force.js

@@ -1,7 +1,9 @@
+import { defUnit, mul, prefix } from "../unit.js";
 import { m_s2 } from "./accel.js";
 import { kg } from "./mass.js";
-import { defUnit, mul } from "../unit.js";
 const N = defUnit("N", "newton", mul(kg, m_s2, true));
+const kN = defUnit("kN", "kilonewton", prefix("k", N));
 export {
-  N
+  N,
+  kN
 };

package/units/power.js

@@ -7,8 +7,8 @@ const kW = defUnit("kW", "kilowatt", prefix("k", W));
 const MW = defUnit("MW", "megawatt", prefix("M", W));
 const GW = defUnit("GW", "gigawatt", prefix("G", W));
 const TW = defUnit("TW", "terawatt", prefix("T", W));
-const Wh = defUnit("Wh", "watt-hour", mul(W, h, true));
-const kWh = defUnit("kWh", "kilowatt-hour", prefix("k", Wh));
+const Wh = defUnit("Wh", "watt hour", mul(W, h, true));
+const kWh = defUnit("kWh", "kilowatt hour", prefix("k", Wh));
 export {
   GW,
   MW,

package/units/temperature.js

@@ -1,9 +1,9 @@
 import { coherent, defUnit, unit } from "../unit.js";
 const K = defUnit("K", "kelvin", coherent(4));
-const celsius = defUnit("\u2103", "degree celsius", unit(4, 1, 273.15));
+const celsius = defUnit("\u2103", "celsius", unit(4, 1, 273.15));
 const fahrenheit = defUnit(
   "\u2109",
-  "degree fahrenheit",
+  "fahrenheit",
   unit(4, 1 / 1.8, 459.67 / 1.8)
 );
 export {

package/units/time.js

@@ -5,10 +5,10 @@ const \u00B5s = defUnit("\xB5s", "microsecond", prefix("\xB5", s));
 const ns = defUnit("ns", "nanosecond", prefix("n", s));
 const min = defUnit("min", "minute", mul(s, 60));
 const h = defUnit("h", "hour", mul(min, 60));
-const d = defUnit("day", "day", mul(h, 24));
-const week = defUnit("week", "week", mul(d, 7));
-const month = defUnit("month", "month", mul(d, 30));
-const year = defUnit("year", "year", mul(d, 365.25));
+const d = defUnit("d", "day", mul(h, 24));
+const week = defUnit("w", "week", mul(d, 7));
+const month = defUnit("mo", "month", mul(d, 30));
+const year = defUnit("y", "year", mul(d, 365.25));
 export {
   d,
   h,

package/units/volume.d.ts

@@ -2,6 +2,9 @@ export declare const m3: import("../api.js").NamedUnit;
 export declare const mm3: import("../api.js").NamedUnit;
 export declare const cm3: import("../api.js").NamedUnit;
 export declare const km3: import("../api.js").NamedUnit;
+export declare const cuin: import("../api.js").NamedUnit;
+export declare const cuft: import("../api.js").NamedUnit;
+export declare const cumi: import("../api.js").NamedUnit;
 export declare const l: import("../api.js").NamedUnit;
 export declare const cl: import("../api.js").NamedUnit;
 export declare const ml: import("../api.js").NamedUnit;

package/units/volume.js

@@ -1,9 +1,12 @@
-import { cm, km, m, mm } from "./length.js";
 import { defUnit, mul, pow, prefix } from "../unit.js";
+import { cm, ft, inch, km, m, mi, mm } from "./length.js";
 const m3 = defUnit("m3", "cubic meter", pow(m, 3));
 const mm3 = defUnit("mm3", "cubic millimeter", pow(mm, 3));
 const cm3 = defUnit("cm3", "cubic centimeter", pow(cm, 3));
 const km3 = defUnit("km3", "cubic kilometer", pow(km, 3));
+const cuin = defUnit("cuin", "cubic inch", pow(inch, 3));
+const cuft = defUnit("cuft", "cubic foot", pow(ft, 3));
+const cumi = defUnit("cumi", "cubic mile", pow(mi, 3));
 const l = defUnit("l", "liter", mul(m3, 1e-3, true));
 const cl = defUnit("cl", "centiliter", prefix("c", l));
 const ml = defUnit("ml", "milliliter", prefix("m", l));
@@ -11,17 +14,20 @@ const drop = defUnit("drop", "drop", mul(ml, 1 / 20));
 const gal = defUnit("gal", "imperial gallon", mul(l, 4.54609));
 const pt = defUnit("pt", "imperial pint", mul(gal, 1 / 8));
 const floz = defUnit("fl_oz", "imperial fluid ounce", mul(gal, 1 / 160));
-const us_gal = defUnit("us_gal", "us gallon", mul(l, 3.785411784));
-const us_pt = defUnit("us_pt", "us pint", mul(us_gal, 1 / 8));
-const us_cup = defUnit("us_cup", "us cup", mul(us_gal, 1 / 16));
+const us_gal = defUnit("us_gal", "US gallon", mul(l, 3.785411784));
+const us_pt = defUnit("us_pt", "US pint", mul(us_gal, 1 / 8));
+const us_cup = defUnit("us_cup", "US cup", mul(us_gal, 1 / 16));
 const us_floz = defUnit(
   "us_fl_oz",
-  "us fluid ounce",
+  "US fluid ounce",
   mul(us_gal, 1 / 128)
 );
 export {
   cl,
   cm3,
+  cuft,
+  cuin,
+  cumi,
   drop,
   floz,
   gal,

package/api.d.ts

@@ -1,101 +0,0 @@
-export interface Unit {
-    /**
-     * SI base dimension vector ({@link Dimensions})
-     */
-    dim: Dimensions;
-    /**
-     * Scaling factor relative to the coherent unit
-     */
-    scale: number;
-    /**
-     * Zero offset value
-     */
-    offset: number;
-    /**
-     * True, if this unit is coherent.
-     *
-     * @remarks
-     * Reference:
-     * - https://en.wikipedia.org/wiki/Coherence_(units_of_measurement)
-     */
-    coherent: boolean;
-}
-export interface NamedUnit extends Unit {
-    /**
-     * Symbol under which this unit can be looked up with via {@link asUnit} and
-     * others.
-     */
-    sym: string;
-    /**
-     * This unit's human readable description/name.
-     */
-    name: string;
-}
-export type MaybeUnit = Unit | string;
-/**
- * Vector of the 7 basic SI unit dimensions.
- *
- * @remarks
- * In order:
- *
- * - 0 = mass
- * - 1 = length
- * - 2 = time
- * - 3 = current
- * - 4 = temperature
- * - 5 = amount of substance
- * - 6 = luminous intensity
- *
- * Note: For dimensionless units, all dimensions are zero.
- *
- * Reference:
- * https://en.wikipedia.org/wiki/SI_base_unit
- */
-export type Dimensions = [
-    number,
-    number,
-    number,
-    number,
-    number,
-    number,
-    number
-];
-/**
- * A known metric prefix.
- */
-export type Prefix = keyof typeof PREFIXES;
-/**
- * @remarks
- * Reference:
- * https://en.wikipedia.org/wiki/Metric_prefix
- */
-export declare const PREFIXES: {
-    Q: number;
-    R: number;
-    Y: number;
-    Z: number;
-    E: number;
-    P: number;
-    T: number;
-    G: number;
-    M: number;
-    k: number;
-    h: number;
-    d: number;
-    c: number;
-    m: number;
-    µ: number;
-    n: number;
-    p: number;
-    f: number;
-    a: number;
-    z: number;
-    y: number;
-    r: number;
-    q: number;
-};
-/**
- * Dimensionless unit preset.
- */
-export declare const NONE: Unit;
-//# sourceMappingURL=api.d.ts.map