@thi.ng/units 1.0.33 → 1.1.0

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 210 standalone projects, maintained as part
+> This is one of 212 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -43,6 +43,7 @@
   - [Unit conversions](#unit-conversions)
   - [Quantities](#quantities)
     - [Constants](#constants)
+- [Domain-specific language](#domain-specific-language)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -52,7 +53,7 @@
 
 ## About
 
-Extensible SI unit creation, conversions, quantities & calculations (incl. ~170 predefined units & constants).
+Extensible SI unit creation, conversions, quantities & calculations (incl. List-like DSL and ~170 predefined units & constants).
 
 All unit definitions, quantities & conversions are based on the SI unit system &
 concepts described here:
@@ -618,6 +619,42 @@ Densities of selected materials:
 | `WATER`      | `kg/m3` |
 | `WOOD`       | `kg/m3` |
 
+## Domain-specific language
+
+The package includes a minimal Lisp-like formula expression language to compute,
+combine or convert quantities in a more concise style than the default JS API
+provided by this package.
+
+The minimal domain specific language defined here only includes the following
+functions (all following basic Lisp syntax, also see examples below):
+
+- Math operators: `+`, `-`, `*`, `/` to combine two or more quantities (all quantities MUST be compatible)
+- `area`: Computes the area of a given 2D quantity (e.g. `(area DIN_A4)` computes the area of a sheet of paper)
+- `volume`: Computes the volume of a given 3D quantity
+- `width`: Returns the 1st dimension quantity of a 2D/3D quantity (e.g. `(width DIN_A4)` = 210mm)
+- `height`: Returns the 2nd dimension quantity of a 2D/3D quantity
+- `depth`: Returns the 3rd dimension quantity of a 3D quantity
+
+Any other symbol is interpreted as quantity or pre-defined registered unit or
+constant (see readme). Quantities always have to be given without whitespace,
+i.e. `100mm` vs. `100 mm`.
+
+ ```ts
+import { $eval } from "@thi.ng/units";
+
+// compute weight in grams of A4 paper with 320 grams per square meter
+console.log($eval(`(g (* (area din_a4) 320gsm))`));
+// 19.9584
+
+// compute weight in kg of 1/2 inch thick 200x300mm glass plate
+console.log($eval(`(kg (* 200mm 300mm 0.5in 2500kg/m3))`));
+// 1.905
+
+// same as previous but using the `glass` density preset
+console.log($eval(`(kg (* 200mm 300mm 0.5in glass))`));
+// 1.905
+```
+
 ## Status
 
 **BETA** - possibly breaking changes forthcoming
@@ -650,7 +687,7 @@ For Node.js REPL:
 const units = await import("@thi.ng/units");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 4.79 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 5.65 KB
 
 ## Dependencies
 
@@ -658,6 +695,7 @@ Package sizes (brotli'd, pre-treeshake): ESM: 4.79 KB
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
 - [@thi.ng/equiv](https://github.com/thi-ng/umbrella/tree/develop/packages/equiv)
 - [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
+- [@thi.ng/sexpr](https://github.com/thi-ng/umbrella/tree/develop/packages/sexpr)
 
 Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)
 

package/constants/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./densities.js";
+export * from "./earth.js";
+export * from "./paper-sizes.js";
+export * from "./velocities.js";
+//# sourceMappingURL=index.d.ts.map

package/constants/index.js

@@ -0,0 +1,4 @@
+export * from "./densities.js";
+export * from "./earth.js";
+export * from "./paper-sizes.js";
+export * from "./velocities.js";

package/dsl.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Parses & evaluates given Lisp-like formula expression to compute, combine or
+ * convert units in a more concise style than the default JS API provided by
+ * this package.
+ *
+ * @remarks
+ * The minimal domain specific language defined here only includes the following
+ * functions (all following basic Lisp syntax, also see examples below):
+ *
+ * - Math operators: `+`, `-`, `*`, `/` to combine two or more quantities (all
+ *   quantities MUST be compatible)
+ * - `area`: Computes the area of a given 2D quantity (e.g. `(area DIN_A4)`
+ *   computes the area of a sheet of paper)
+ * - `volume`: Computes the volume of a given 3D quantity
+ * - `width`: Returns the 1st dimension quantity of a 2D/3D quantity (e.g.
+ *   `(width DIN_A4)` = 210mm)
+ * - `height`: Returns the 2nd dimension quantity of a 2D/3D quantity
+ * - `depth`: Returns the 3rd dimension quantity of a 3D quantity
+ *
+ * Any other symbol is interpreted as quantity or pre-defined registered unit or
+ * constant (see readme).
+ *
+ * @example
+ * ```ts tangle:../export/eval.ts
+ * import { $eval } from "@thi.ng/units";
+ *
+ * // compute weight in grams of A4 paper with 320 grams per square meter
+ * console.log($eval(`(g (* (area DIN_A4) 320gsm))`));
+ * // 19.9584
+ *
+ * // compute weight in kg of 1/2 inch thick 200x300mm glass plate
+ * console.log($eval(`(kg (* 200mm 300mm 0.5in 2500kg/m3))`));
+ * // 1.905
+ *
+ * // same as previous but using the `glass` density preset
+ * console.log($eval(`(kg (* 200mm 300mm 0.5in glass))`));
+ * // 1.905
+ * ```
+ *
+ * @param src
+ */
+export declare const $eval: (src: string) => any;
+//# sourceMappingURL=dsl.d.ts.map

package/dsl.js

@@ -0,0 +1,58 @@
+import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
+import { parse } from "@thi.ng/sexpr/parse";
+import { runtime } from "@thi.ng/sexpr/runtime";
+import * as CONST from "./constants/index.js";
+import {
+  add,
+  asUnit,
+  convert,
+  div,
+  mul,
+  quantity,
+  Quantity,
+  reciprocal,
+  sub
+} from "./unit.js";
+const __mathOp = (fn, fn1) => (first, ...args) => {
+  return args.length > 0 ? (
+    // use a reduction for 2+ args
+    args.reduce((acc, x) => fn(acc, x), first)
+  ) : (
+    // apply special case unary function
+    fn1(first)
+  );
+};
+const ENV = {
+  "+": __mathOp(add, (x) => x),
+  "-": __mathOp(sub, (x) => sub(quantity(0, x.value), x)),
+  "*": __mathOp(mul, (x) => x),
+  "/": __mathOp(div, reciprocal),
+  area: (src) => {
+    const [w, h] = src.value.map((x) => quantity(1, x));
+    return mul(w, h);
+  },
+  volume: (src) => {
+    const [w, h, d] = src.value.map((x) => quantity(1, x));
+    return mul(mul(w, h), d);
+  },
+  width: (src) => quantity(1, src.value[0]),
+  height: (src) => quantity(1, src.value[1]),
+  depth: (src) => quantity(1, src.value[2])
+};
+const interpret = runtime({
+  expr: ({ children: [x, ...args] }) => {
+    const name = x.value;
+    const $args = args.map((a) => interpret(a, null));
+    return ENV[name]?.apply(null, $args) ?? convert($args[0], asUnit(name));
+  },
+  sym: ({ value }) => {
+    const match = /^[-+]?[0-9.]+(e[+-]?\d+)?/.exec(value);
+    return match ? quantity(+match[0], asUnit(value.substring(match[0].length))) : CONST[value.toUpperCase()] ?? asUnit(value);
+  },
+  str: () => illegalArgs("string value"),
+  num: (x) => x.value
+});
+const $eval = (src) => parse(src).children.reduce((_, x) => interpret(x, null), null);
+export {
+  $eval
+};

package/index.d.ts

@@ -1,27 +1,6 @@
 export * from "./api.js";
+export * from "./dsl.js";
 export * from "./unit.js";
-export * from "./units/accel.js";
-export * from "./units/angle.js";
-export * from "./units/area.js";
-export * from "./units/data.js";
-export * from "./units/density.js";
-export * from "./units/electric.js";
-export * from "./units/energy.js";
-export * from "./units/force.js";
-export * from "./units/frequency.js";
-export * from "./units/length.js";
-export * from "./units/luminous.js";
-export * from "./units/mass.js";
-export * from "./units/parts.js";
-export * from "./units/power.js";
-export * from "./units/pressure.js";
-export * from "./units/substance.js";
-export * from "./units/temperature.js";
-export * from "./units/time.js";
-export * from "./units/velocity.js";
-export * from "./units/volume.js";
-export * from "./constants/densities.js";
-export * from "./constants/earth.js";
-export * from "./constants/paper-sizes.js";
-export * from "./constants/velocities.js";
+export * from "./constants/index.js";
+export * from "./units/index.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,26 +1,5 @@
 export * from "./api.js";
+export * from "./dsl.js";
 export * from "./unit.js";
-export * from "./units/accel.js";
-export * from "./units/angle.js";
-export * from "./units/area.js";
-export * from "./units/data.js";
-export * from "./units/density.js";
-export * from "./units/electric.js";
-export * from "./units/energy.js";
-export * from "./units/force.js";
-export * from "./units/frequency.js";
-export * from "./units/length.js";
-export * from "./units/luminous.js";
-export * from "./units/mass.js";
-export * from "./units/parts.js";
-export * from "./units/power.js";
-export * from "./units/pressure.js";
-export * from "./units/substance.js";
-export * from "./units/temperature.js";
-export * from "./units/time.js";
-export * from "./units/velocity.js";
-export * from "./units/volume.js";
-export * from "./constants/densities.js";
-export * from "./constants/earth.js";
-export * from "./constants/paper-sizes.js";
-export * from "./constants/velocities.js";
+export * from "./constants/index.js";
+export * from "./units/index.js";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@thi.ng/units",
-	"version": "1.0.33",
-	"description": "Extensible SI unit creation, conversions, quantities & calculations (incl. ~170 predefined units & constants)",
+	"version": "1.1.0",
+	"description": "Extensible SI unit creation, conversions, quantities & calculations (incl. List-like DSL and ~170 predefined units & constants)",
 	"type": "module",
 	"module": "./index.js",
 	"typings": "./index.d.ts",
@@ -39,10 +39,11 @@
 		"tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
 	},
 	"dependencies": {
-		"@thi.ng/api": "^8.12.9",
-		"@thi.ng/checks": "^3.7.25",
-		"@thi.ng/equiv": "^2.1.99",
-		"@thi.ng/errors": "^2.5.49"
+		"@thi.ng/api": "^8.12.11",
+		"@thi.ng/checks": "^3.8.1",
+		"@thi.ng/equiv": "^2.1.101",
+		"@thi.ng/errors": "^2.6.0",
+		"@thi.ng/sexpr": "^1.1.18"
 	},
 	"devDependencies": {
 		"esbuild": "^0.27.0",
@@ -59,14 +60,17 @@
 		"capacitance",
 		"conversion",
 		"current",
+		"dsl",
 		"energy",
 		"force",
 		"frequency",
 		"length",
+		"lisp",
 		"mass",
 		"math",
 		"power",
 		"resistance",
+		"s-expression",
 		"si",
 		"speed",
 		"symbolic",
@@ -113,6 +117,9 @@
 		"./constants/velocities": {
 			"default": "./constants/velocities.js"
 		},
+		"./dsl": {
+			"default": "./dsl.js"
+		},
 		"./unit": {
 			"default": "./unit.js"
 		},
@@ -181,5 +188,5 @@
 		"status": "beta",
 		"year": 2021
 	},
-	"gitHead": "fdca77cabf47dd23a9ab17a5ca13e3060075c12c\n"
+	"gitHead": "e7a21b9d2a188fa04d4c893d8531c40fbc0f4c06\n"
 }

package/unit.d.ts

@@ -133,6 +133,50 @@ export declare class Quantity<T extends number | number[]> implements IDeref<T>
  * @param unit
  */
 export declare const quantity: <T extends number | number[]>(value: T, unit: MaybeUnit) => Quantity<T>;
+/**
+ * Polymorphic function to sum to compatible quantities. Throws an error if `a`
+ * and `b` are incompatible.
+ *
+ * @example
+ * ```ts tangle:../export/add.ts
+ * import { add, convert, quantity } from "@thi.ng/units";
+ *
+ * const a = quantity(10, "mm");
+ * const b = quantity(1, "in");
+ *
+ * console.log(convert(add(a, b), "mm"));
+ * // 35.4
+ * ```
+ *
+ * @param a
+ * @param b
+ */
+export declare function add(a: Quantity<number>, b: Quantity<number>): Quantity<number>;
+export declare function add(a: Quantity<number>, b: Quantity<number[]>): Quantity<number[]>;
+export declare function add(a: Quantity<number[]>, b: Quantity<number>): Quantity<number[]>;
+export declare function add(a: Quantity<number[]>, b: Quantity<number[]>): Quantity<number[]>;
+/**
+ * Polymorphic function to subtract to compatible quantities. Throws an error if
+ * `a` and `b` are incompatible.
+ *
+ * @example
+ * ```ts tangle:../export/sub.ts
+ * import { sub, convert, quantity } from "@thi.ng/units";
+ *
+ * const a = quantity(10, "mm");
+ * const b = quantity(1, "in");
+ *
+ * console.log(convert(sub(a, b), "mm"));
+ * // -15.4
+ * ```
+ *
+ * @param a
+ * @param b
+ */
+export declare function sub(a: Quantity<number>, b: Quantity<number>): Quantity<number>;
+export declare function sub(a: Quantity<number>, b: Quantity<number[]>): Quantity<number[]>;
+export declare function sub(a: Quantity<number[]>, b: Quantity<number>): Quantity<number[]>;
+export declare function sub(a: Quantity<number[]>, b: Quantity<number[]>): Quantity<number[]>;
 /**
  * Polymorphic function. Derives a new quantity or unit as the product of the
  * given quantities/units.

package/unit.js

@@ -29,7 +29,7 @@ const asUnit = (id) => {
       return PREFIXES[pre] !== void 0 ? prefix(pre, unit2) : !pre ? unit2 : illegalArgs(`unknown unit: ${id}`);
     }
   }
-  for (let u in UNITS) {
+  for (const u in UNITS) {
     if (UNITS[u].name === id) return UNITS[u];
   }
   illegalArgs(`unknown unit: ${id}`);
@@ -49,6 +49,20 @@ class Quantity {
 const quantity = (value, unit2) => new Quantity(
   isNumber(value) ? mul(unit2, value) : value.map((x) => mul(unit2, x))
 );
+function add(a, b) {
+  const $unit = unit(__qunit(a).dim, 1, 0, true);
+  const valA = convert(a, $unit);
+  const valB = convert(b, $unit);
+  const val = isArray(valA) ? isArray(valB) ? valA.map((x, i) => x + valB[i]) : valA.map((x) => x + valB) : isArray(valB) ? valB.map((x) => x + valA) : valA + valB;
+  return quantity(val, $unit);
+}
+function sub(a, b) {
+  const $unit = unit(__qunit(a).dim, 1, 0, true);
+  const valA = convert(a, $unit);
+  const valB = convert(b, $unit);
+  const val = isArray(valA) ? isArray(valB) ? valA.map((x, i) => x - valB[i]) : valA.map((x) => x - valB) : isArray(valB) ? valB.map((x) => x - valA) : valA - valB;
+  return quantity(val, $unit);
+}
 function mul(a, b, coherent2 = false) {
   if (a instanceof Quantity) return __combineQ(mul, a, b);
   const $a = __ensureUnit(a);
@@ -134,7 +148,7 @@ const formatSI = (u) => {
 };
 const __ensureUnit = (x) => isString(x) ? asUnit(x) : x;
 const __oneHot = (x) => {
-  const dims = new Array(7).fill(0);
+  const dims = [0, 0, 0, 0, 0, 0, 0];
   dims[x] = 1;
   return dims;
 };
@@ -150,6 +164,7 @@ const __combineQ = (op, a, b) => {
 export {
   Quantity,
   UNITS,
+  add,
   asUnit,
   coherent,
   convert,
@@ -165,5 +180,6 @@ export {
   prefix,
   quantity,
   reciprocal,
+  sub,
   unit
 };

package/units/density.d.ts

@@ -1,3 +1,8 @@
+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

@@ -1,10 +1,15 @@
-import { inch } from "./length.js";
-import { kg } from "./mass.js";
 import { defUnit, div, reciprocal } from "../unit.js";
+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 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/index.d.ts

@@ -0,0 +1,21 @@
+export * from "./accel.js";
+export * from "./angle.js";
+export * from "./area.js";
+export * from "./data.js";
+export * from "./density.js";
+export * from "./electric.js";
+export * from "./energy.js";
+export * from "./force.js";
+export * from "./frequency.js";
+export * from "./length.js";
+export * from "./luminous.js";
+export * from "./mass.js";
+export * from "./parts.js";
+export * from "./power.js";
+export * from "./pressure.js";
+export * from "./substance.js";
+export * from "./temperature.js";
+export * from "./time.js";
+export * from "./velocity.js";
+export * from "./volume.js";
+//# sourceMappingURL=index.d.ts.map

package/units/index.js

@@ -0,0 +1,20 @@
+export * from "./accel.js";
+export * from "./angle.js";
+export * from "./area.js";
+export * from "./data.js";
+export * from "./density.js";
+export * from "./electric.js";
+export * from "./energy.js";
+export * from "./force.js";
+export * from "./frequency.js";
+export * from "./length.js";
+export * from "./luminous.js";
+export * from "./mass.js";
+export * from "./parts.js";
+export * from "./power.js";
+export * from "./pressure.js";
+export * from "./substance.js";
+export * from "./temperature.js";
+export * from "./time.js";
+export * from "./velocity.js";
+export * from "./volume.js";