@thi.ng/units 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-03-14T13:27:19Z
+- **Last updated**: 2023-03-15T14:55:07Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,22 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/units@0.2.0) (2023-03-15)
+
+#### 🚀 Features
+
+- add support for quantities ([94ded3e](https://github.com/thi-ng/umbrella/commit/94ded3e))
+  - add quantity()
+  - update various ops & predicates as polymorphic fns
+  - fix asUnit()
+  - update docs
+- restructure /src, add quantities/constants ([1374162](https://github.com/thi-ng/umbrella/commit/1374162))
+  - add /src/constants:
+    - velocities
+    - DIN paper sizes
+  - move all unit presets to /src/units
+  - update pkg exports
+
 ## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/units@0.1.0) (2023-03-14)
 
 #### 🚀 Features

package/README.md

@@ -35,6 +35,8 @@ This project is part of the
     - [Using standard metric prefixes](#using-standard-metric-prefixes)
     - [Unit combinators](#unit-combinators)
   - [Unit conversions](#unit-conversions)
+  - [Quantities](#quantities)
+    - [Constants](#constants)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -44,10 +46,10 @@ This project is part of the
 
 ## About
 
-Extensible SI unit creation, conversions & calculations (~150 units predefined).
+Extensible SI unit creation, conversions, quantities & calculations (incl. ~170 predefined units & constants).
 
-All unit definitions & conversions are based on the SI unit system & concepts
-described here:
+All unit definitions, quantities & conversions are based on the SI unit system &
+concepts described here:
 
 - https://en.wikipedia.org/wiki/International_System_of_Units
 - https://en.wikipedia.org/wiki/SI_base_unit
@@ -55,6 +57,11 @@ described here:
 - https://en.wikipedia.org/wiki/Coherence_(units_of_measurement)
 - https://en.wikipedia.org/wiki/Metric_prefix
 
+The overall conversion approach is inspired & partially based on:
+
+- [Frink](https://frinklang.org/)
+- [@g7s/unit](https://github.com/g7s/unit)
+
 ### Unit definitions
 
 Each unit is defined via a 7-dimensional vector representing individual
@@ -111,8 +118,9 @@ units](https://en.wikipedia.org/wiki/SI_derived_unit)):
 
 > Ω = kg⋅m<sup>2</sup>⋅s<sup>−3</sup>⋅A<sup>−2</sup>
 
-Btw. The [`formatSI()`]() function can be used to format a unit's dimension
-vector:
+Btw. The
+[`formatSI()`](https://docs.thi.ng/umbrella/units/functions/formatSI.html)
+function can be used to format a unit's dimension vector:
 
 ```ts
 formatSI(div(V, A));
@@ -385,9 +393,9 @@ https://en.wikipedia.org/wiki/Parts-per_notation
 
 #### Using standard metric prefixes
 
-Existing [coherent units]() can be
-[prefixed](https://docs.thi.ng/umbrella/units/functions/prefix-1.html) to produce
-derived versions:
+Existing coherent units can be
+[prefixed](https://docs.thi.ng/umbrella/units/functions/prefix-1.html) to
+produce derived versions:
 
 ```ts
 // define micrometer (also available as preset)
@@ -402,7 +410,7 @@ prefix("k", Hz);
 #### Unit combinators
 
 The following combinators can be used to derive scaled and/or more complex units
-in multiple SI dimensions:
+(or [quantities](#quantities)) in multiple SI dimensions:
 
 - [`div(a, b)`](https://docs.thi.ng/umbrella/units/functions/div.html): derives
   a new unit via the division of the given units
@@ -433,9 +441,12 @@ const Hz = reciprocal(s);
 
 ### Unit conversions
 
-Only units with compatible (incl. reciprocal) dimensions can be converted,
-otherwise an error will be thrown. All dimensionless units can be converted
-to other dimensionless units (even if it would be semantic nonsense).
+Units (and [quantities](#quantities)) can be converted using
+[`convert()`](https://docs.thi.ng/umbrella/units/functions/convert.html). Only
+units with compatible (incl. reciprocal) dimensions can be converted, otherwise
+an error will be thrown. On the other hand, all _dimensionless_ units can be
+converted to other _dimensionless_ units (even if it would be semantic
+nonsense).
 
 Units can be specified in various ways:
 
@@ -467,6 +478,68 @@ convert(10, "arcsec", "rad") * R;
 // 308.87479623488537
 ```
 
+### Quantities
+
+The library also supports defining quantities, i.e. certain finite amounts of a
+given unit. These can be a number or vector-based and can be used for
+calculations & conversions using the above mentioned polymorphic functions:
+`div()`, `mul()`, `reciprocal()` and `convert()`.
+
+Quantities are created via
+ [`quantity()`](https://docs.thi.ng/umbrella/units/functions/quantity-1.html)
+ which acts a factory function for a thin `Quantity` class wrapper. The latter
+ also implements the standard
+ [`IDeref`](https://docs.thi.ng/umbrella/api/interfaces/IDeref.html) interface
+ to obtain the unwrapped amount (though it only should be used for dimensionless
+ quantities). Use [`convert()`](#unit-conversions) otherwise!
+
+ ```ts
+// (also available as preset)
+const speedOfLight = quantity(299792458, "m/s");
+
+// compute wavelength of a WiFi signal in millimeters
+convert(div(speedOfLight, quantity(2.4,"GHz")), "mm");
+// 124.9135
+```
+
+```ts
+// DIN A4 paper size (also available as preset)
+const A4 = quantity([210, 297], "mm");
+
+// convert paper size to inches
+convert(A4, "in");
+// [ 8.2677, 11.6929 ]
+
+// or calculate pixel dimensions @ 300 dpi
+// the result of the product is dimensionless
+// so we use the NONE preset as target unit...
+convert(mul(A4, quantity(300, "dpi")), NONE)
+// [ 2480.314960629921, 3507.8740157480315 ]
+
+// alternatively dimensionless units can be deref'd directly
+mul(A4, quantity(300, "dpi")).deref()
+// [ 2480.314960629921, 3507.8740157480315 ]
+```
+
+When combining different quantities, their units do not need to be the same:
+
+```ts
+// compute 10 mm x 2 inch and convert to square centimeter
+convert(mul(quantity(10, "mm"), quantity(2, "in")), "cm2")
+// 5.08
+```
+
+#### Constants
+
+The following constants are provided (more to come):
+
+| Var name                  | Unit           |
+|---------------------------|----------------|
+| `DIN_A0` ... `DIN_A8`     | `["mm", "mm"]` |
+| `SPEED_OF_LIGHT`          | `"m/s"`        |
+| `SPEED_OF_SOUND_IN_AIR`   | `"m/s"`        |
+| `SPEED_OF_SOUND_IN_WATER` | `"m/s"`        |
+
 ## Status
 
 **BETA** - possibly breaking changes forthcoming
@@ -493,10 +566,11 @@ For Node.js REPL:
 const units = await import("@thi.ng/units");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 3.57 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 4.05 KB
 
 ## Dependencies
 
+- [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
 - [@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)

package/api.d.ts

@@ -94,4 +94,8 @@ export declare const PREFIXES: {
     r: number;
     q: number;
 };
+/**
+ * Dimensionless unit preset.
+ */
+export declare const NONE: Unit;
 //# sourceMappingURL=api.d.ts.map

package/api.js

@@ -28,3 +28,12 @@ export const PREFIXES = {
     r: 1e-27,
     q: 1e-30,
 };
+/**
+ * Dimensionless unit preset.
+ */
+export const NONE = {
+    dim: [0, 0, 0, 0, 0, 0, 0],
+    scale: 1,
+    offset: 0,
+    coherent: false,
+};

package/constants/din-sizes.d.ts

@@ -0,0 +1,10 @@
+export declare const DIN_A0: import("../unit.js").Quantity<number[]>;
+export declare const DIN_A1: import("../unit.js").Quantity<number[]>;
+export declare const DIN_A2: import("../unit.js").Quantity<number[]>;
+export declare const DIN_A3: import("../unit.js").Quantity<number[]>;
+export declare const DIN_A4: import("../unit.js").Quantity<number[]>;
+export declare const DIN_A5: import("../unit.js").Quantity<number[]>;
+export declare const DIN_A6: import("../unit.js").Quantity<number[]>;
+export declare const DIN_A7: import("../unit.js").Quantity<number[]>;
+export declare const DIN_A8: import("../unit.js").Quantity<number[]>;
+//# sourceMappingURL=din-sizes.d.ts.map

package/constants/din-sizes.js

@@ -0,0 +1,11 @@
+import { mm } from "../units/length.js";
+import { quantity } from "../unit.js";
+export const DIN_A0 = quantity([841, 1189], mm);
+export const DIN_A1 = quantity([594, 841], mm);
+export const DIN_A2 = quantity([420, 594], mm);
+export const DIN_A3 = quantity([297, 420], mm);
+export const DIN_A4 = quantity([210, 297], mm);
+export const DIN_A5 = quantity([148, 210], mm);
+export const DIN_A6 = quantity([105, 148], mm);
+export const DIN_A7 = quantity([74, 105], mm);
+export const DIN_A8 = quantity([52, 74], mm);

package/constants/din.d.ts

@@ -0,0 +1,10 @@
+export declare const DIN_A0: import("../unit.js").Value<number[]>;
+export declare const DIN_A1: import("../unit.js").Value<number[]>;
+export declare const DIN_A2: import("../unit.js").Value<number[]>;
+export declare const DIN_A3: import("../unit.js").Value<number[]>;
+export declare const DIN_A4: import("../unit.js").Value<number[]>;
+export declare const DIN_A5: import("../unit.js").Value<number[]>;
+export declare const DIN_A6: import("../unit.js").Value<number[]>;
+export declare const DIN_A7: import("../unit.js").Value<number[]>;
+export declare const DIN_A8: import("../unit.js").Value<number[]>;
+//# sourceMappingURL=din.d.ts.map

package/constants/din.js

@@ -0,0 +1,11 @@
+import { mm } from "../length.js";
+import { value } from "../unit.js";
+export const DIN_A0 = value([841, 1189], mm);
+export const DIN_A1 = value([594, 841], mm);
+export const DIN_A2 = value([420, 594], mm);
+export const DIN_A3 = value([297, 420], mm);
+export const DIN_A4 = value([210, 297], mm);
+export const DIN_A5 = value([148, 210], mm);
+export const DIN_A6 = value([105, 148], mm);
+export const DIN_A7 = value([74, 105], mm);
+export const DIN_A8 = value([52, 74], mm);

package/constants/velocities.d.ts

@@ -0,0 +1,10 @@
+export declare const SPEED_OF_LIGHT: import("../unit.js").Quantity<299792458>;
+/**
+ * At 20 degree celsius
+ */
+export declare const SPEED_OF_SOUND_IN_AIR: import("../unit.js").Quantity<343.14>;
+/**
+ * At 20 degree celsius
+ */
+export declare const SPEED_OF_SOUND_IN_WATER: import("../unit.js").Quantity<1482>;
+//# sourceMappingURL=velocities.d.ts.map

package/constants/velocities.js

@@ -0,0 +1,11 @@
+import { quantity } from "../unit.js";
+import { m_s } from "../units/velocity.js";
+export const SPEED_OF_LIGHT = quantity(299792458, m_s);
+/**
+ * At 20 degree celsius
+ */
+export const SPEED_OF_SOUND_IN_AIR = quantity(343.14, m_s);
+/**
+ * At 20 degree celsius
+ */
+export const SPEED_OF_SOUND_IN_WATER = quantity(1482, m_s);

package/index.d.ts

@@ -1,22 +1,25 @@
 export * from "./api.js";
 export * from "./unit.js";
-export * from "./accel.js";
-export * from "./angle.js";
-export * from "./area.js";
-export * from "./data.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 "./speed.js";
-export * from "./substance.js";
-export * from "./temperature.js";
-export * from "./time.js";
-export * from "./volume.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/din-sizes.js";
+export * from "./constants/velocities.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,21 +1,24 @@
 export * from "./api.js";
 export * from "./unit.js";
-export * from "./accel.js";
-export * from "./angle.js";
-export * from "./area.js";
-export * from "./data.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 "./speed.js";
-export * from "./substance.js";
-export * from "./temperature.js";
-export * from "./time.js";
-export * from "./volume.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/din-sizes.js";
+export * from "./constants/velocities.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/units",
-  "version": "0.1.0",
-  "description": "Extensible SI unit creation, conversions & calculations (~150 units predefined)",
+  "version": "0.2.0",
+  "description": "Extensible SI unit creation, conversions, quantities & calculations (incl. ~170 predefined units & constants)",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -34,6 +34,7 @@
     "test": "testament test"
   },
   "dependencies": {
+    "@thi.ng/api": "^8.7.4",
     "@thi.ng/checks": "^3.3.10",
     "@thi.ng/equiv": "^2.1.20",
     "@thi.ng/errors": "^2.2.13"
@@ -52,23 +53,27 @@
     "area",
     "bits",
     "bytes",
+    "calculation",
     "capacitance",
     "current",
     "voltage",
     "resistance",
-    "converter",
+    "conversion",
     "energy",
     "force",
     "frequency",
     "length",
     "mass",
+    "math",
     "power",
     "si",
     "speed",
+    "symbolic",
     "temperature",
     "time",
     "typescript",
     "units",
+    "velocity",
     "volume"
   ],
   "publishConfig": {
@@ -83,76 +88,90 @@
   },
   "files": [
     "./*.js",
-    "./*.d.ts"
+    "./*.d.ts",
+    "constants",
+    "units"
   ],
   "exports": {
     ".": {
       "default": "./index.js"
     },
-    "./accel": {
-      "default": "./accel.js"
-    },
-    "./angle": {
-      "default": "./angle.js"
-    },
     "./api": {
       "default": "./api.js"
     },
-    "./area": {
-      "default": "./area.js"
+    "./constants/din-sizes": {
+      "default": "./constants/din-sizes.js"
     },
-    "./data": {
-      "default": "./data.js"
+    "./constants/velocities": {
+      "default": "./constants/velocities.js"
     },
-    "./electric": {
-      "default": "./electric.js"
+    "./unit": {
+      "default": "./unit.js"
     },
-    "./energy": {
-      "default": "./energy.js"
+    "./units/accel": {
+      "default": "./units/accel.js"
     },
-    "./force": {
-      "default": "./force.js"
+    "./units/angle": {
+      "default": "./units/angle.js"
     },
-    "./frequency": {
-      "default": "./frequency.js"
+    "./units/area": {
+      "default": "./units/area.js"
     },
-    "./length": {
-      "default": "./length.js"
+    "./units/data": {
+      "default": "./units/data.js"
     },
-    "./luminous": {
-      "default": "./luminous.js"
+    "./units/density": {
+      "default": "./units/density.js"
     },
-    "./mass": {
-      "default": "./mass.js"
+    "./units/electric": {
+      "default": "./units/electric.js"
     },
-    "./power": {
-      "default": "./power.js"
+    "./units/energy": {
+      "default": "./units/energy.js"
     },
-    "./pressure": {
-      "default": "./pressure.js"
+    "./units/force": {
+      "default": "./units/force.js"
     },
-    "./speed": {
-      "default": "./speed.js"
+    "./units/frequency": {
+      "default": "./units/frequency.js"
     },
-    "./substance": {
-      "default": "./substance.js"
+    "./units/length": {
+      "default": "./units/length.js"
     },
-    "./temperature": {
-      "default": "./temperature.js"
+    "./units/luminous": {
+      "default": "./units/luminous.js"
     },
-    "./time": {
-      "default": "./time.js"
+    "./units/mass": {
+      "default": "./units/mass.js"
     },
-    "./unit": {
-      "default": "./unit.js"
+    "./units/parts": {
+      "default": "./units/parts.js"
+    },
+    "./units/power": {
+      "default": "./units/power.js"
+    },
+    "./units/pressure": {
+      "default": "./units/pressure.js"
+    },
+    "./units/substance": {
+      "default": "./units/substance.js"
+    },
+    "./units/temperature": {
+      "default": "./units/temperature.js"
+    },
+    "./units/time": {
+      "default": "./units/time.js"
+    },
+    "./units/velocity": {
+      "default": "./units/velocity.js"
     },
-    "./volume": {
-      "default": "./volume.js"
+    "./units/volume": {
+      "default": "./units/volume.js"
     }
   },
   "thi.ng": {
     "status": "beta",
     "year": 2021
   },
-  "gitHead": "cc46c097a3a173fb1ef41f57a858d03037063141\n"
+  "gitHead": "ded6c346ccabc8bf647b848738878bdae8e05d55\n"
 }