@thi.ng/units 0.4.45 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-04-23T07:02:19Z
+- **Last updated**: 2024-06-21T19:34:38Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,16 @@ 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.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/units@0.5.0) (2024-06-21)
+
+#### 🚀 Features
+
+- add DPI constants/presets ([5fe2f78](https://github.com/thi-ng/umbrella/commit/5fe2f78))
+
+#### 🩹 Bug fixes
+
+- update DPI constants ([0b36809](https://github.com/thi-ng/umbrella/commit/0b36809))
+
 ### [0.4.14](https://github.com/thi-ng/umbrella/tree/@thi.ng/units@0.4.14) (2023-11-09)
 
 #### ♻️ Refactoring

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 192 standalone projects, maintained as part
+> This is one of 193 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -540,6 +540,8 @@ import { convert, mul, quantity, NONE } from "@thi.ng/units";
 
 // DIN A4 paper size (also available as preset)
 const A4 = quantity([210, 297], "mm");
+// (also available as preset)
+const DPI_300 = quantity(300, "dpi");
 
 // convert paper size to inches
 convert(A4, "in");
@@ -548,15 +550,16 @@ convert(A4, "in");
 // or calculate pixel dimensions @ 300 dpi
 // the result of this product is dimensionless,
 // so we use the NONE preset as target unit...
-convert(mul(A4, quantity(300, "dpi")), NONE)
+convert(mul(A4, DPI_300), NONE)
 // [ 2480.314960629921, 3507.8740157480315 ]
 
 // alternatively, dimensionless units can be deref'd directly
-mul(A4, quantity(300, "dpi")).deref()
+mul(A4, DPI_300).deref()
 // [ 2480.314960629921, 3507.8740157480315 ]
 ```
 
-When combining different quantities, their units do not need to be the same:
+When combining different quantities, their units do not need to be the same (but
+compatible):
 
 ```ts
 import { convert, mul, quantity } from "@thi.ng/units";
@@ -570,21 +573,22 @@ convert(mul(quantity(10, "mm"), quantity(2, "in")), "cm2")
 
 The following constants are provided (more to come):
 
-| Var name                       | Unit                | Comment                   |
-|--------------------------------|---------------------|---------------------------|
-| `DIN_A0` ... `DIN_A8`          | 2d vector of `mm`   | Paper sizes<sup>(1)</sup> |
-| `EARTH_GRAVITY`                | `m/s`               |                           |
-| `EARTH_CIRCUMFERENCE`          | `m`                 |                           |
-| `EARTH_MASS`                   | `kg`                |                           |
-| `EARTH_RADIUS`                 | `m`                 |                           |
-| `GRAVITATION`                  | `kg-1·m3·s-2`       | Gravitational constant    |
-| `SPEED_OF_LIGHT`               | `m/s`               |                           |
-| `SPEED_OF_SOUND_IN_AIR`        | `m/s`               | at 20 ℃                   |
-| `SPEED_OF_SOUND_IN_WATER`      | `m/s`               | at 20 ℃                   |
-| `US_ANSI_A` ... `US_ANSI_E`    | 2d vector of `inch` | Paper sizes<sup>(1)</sup> |
-| `US_ARCH_A` ... `US_ARCH_E`    | 2d vector of `inch` | Paper sizes<sup>(1)</sup> |
-| `US_LETTER` / `US_HALF_LETTER` | 2d vector of `inch` | Paper sizes<sup>(1)</sup> |
-| `US_LEGAL` / `US_JUNIOR_LEGAL` | 2d vector of `inch` | Paper sizes<sup>(1)</sup> |
+| Var name                                     | Unit                | Comment                   |
+|----------------------------------------------|---------------------|---------------------------|
+| `DIN_A0` ... `DIN_A8`                        | 2d vector of `mm`   | Paper sizes<sup>(1)</sup> |
+| `DPI_72` / `DPI_150` / `DPI_300` / `DPI_600` | dots per inch       | Screen/print resolutions  |
+| `EARTH_GRAVITY`                              | `m/s`               |                           |
+| `EARTH_CIRCUMFERENCE`                        | `m`                 |                           |
+| `EARTH_MASS`                                 | `kg`                |                           |
+| `EARTH_RADIUS`                               | `m`                 |                           |
+| `GRAVITATION`                                | `kg-1·m3·s-2`       | Gravitational constant    |
+| `SPEED_OF_LIGHT`                             | `m/s`               |                           |
+| `SPEED_OF_SOUND_IN_AIR`                      | `m/s`               | at 20 ℃                   |
+| `SPEED_OF_SOUND_IN_WATER`                    | `m/s`               | at 20 ℃                   |
+| `US_ANSI_A` ... `US_ANSI_E`                  | 2d vector of `inch` | Paper sizes<sup>(1)</sup> |
+| `US_ARCH_A` ... `US_ARCH_E`                  | 2d vector of `inch` | Paper sizes<sup>(1)</sup> |
+| `US_LETTER` / `US_HALF_LETTER`               | 2d vector of `inch` | Paper sizes<sup>(1)</sup> |
+| `US_LEGAL` / `US_JUNIOR_LEGAL`               | 2d vector of `inch` | Paper sizes<sup>(1)</sup> |
 
 - <sup>(1)</sup> - all paper sizes are also available as landscape presets
   (using `_LANDSCAPE` as suffix).
@@ -646,7 +650,7 @@ For Node.js REPL:
 const units = await import("@thi.ng/units");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 4.77 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 4.78 KB
 
 ## Dependencies
 

package/constants/paper-sizes.d.ts

@@ -51,4 +51,8 @@ export declare const US_ARCH_E_LANDSCAPE: Quantity<number[]>;
 export declare const US_ARCH_E1_LANDSCAPE: Quantity<number[]>;
 export declare const US_ARCH_E2_LANDSCAPE: Quantity<number[]>;
 export declare const US_ARCH_E3_LANDSCAPE: Quantity<number[]>;
+export declare const DPI_72: Quantity<72>;
+export declare const DPI_150: Quantity<150>;
+export declare const DPI_300: Quantity<300>;
+export declare const DPI_600: Quantity<600>;
 //# sourceMappingURL=paper-sizes.d.ts.map

package/constants/paper-sizes.js

@@ -1,4 +1,5 @@
 import { Quantity, quantity } from "../unit.js";
+import { dpi } from "../units/density.js";
 import { inch, mm } from "../units/length.js";
 const DIN_A0 = quantity([841, 1189], mm);
 const DIN_A1 = quantity([594, 841], mm);
@@ -53,6 +54,10 @@ const US_ARCH_E_LANDSCAPE = $(US_ARCH_E);
 const US_ARCH_E1_LANDSCAPE = $(US_ARCH_E1);
 const US_ARCH_E2_LANDSCAPE = $(US_ARCH_E2);
 const US_ARCH_E3_LANDSCAPE = $(US_ARCH_E3);
+const DPI_72 = quantity(72, dpi);
+const DPI_150 = quantity(150, dpi);
+const DPI_300 = quantity(300, dpi);
+const DPI_600 = quantity(600, dpi);
 export {
   ANSI_A,
   ANSI_A_LANDSCAPE,
@@ -82,6 +87,10 @@ export {
   DIN_A7_LANDSCAPE,
   DIN_A8,
   DIN_A8_LANDSCAPE,
+  DPI_150,
+  DPI_300,
+  DPI_600,
+  DPI_72,
   US_ARCH_A,
   US_ARCH_A_LANDSCAPE,
   US_ARCH_B,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/units",
-  "version": "0.4.45",
+  "version": "0.5.0",
   "description": "Extensible SI unit creation, conversions, quantities & calculations (incl. ~170 predefined units & constants)",
   "type": "module",
   "module": "./index.js",
@@ -10,7 +10,7 @@
     "type": "git",
     "url": "https://github.com/thi-ng/umbrella.git"
   },
-  "homepage": "https://github.com/thi-ng/umbrella/tree/develop/packages/units#readme",
+  "homepage": "https://thi.ng/units",
   "funding": [
     {
       "type": "github",
@@ -36,16 +36,16 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.1",
-    "@thi.ng/checks": "^3.6.3",
-    "@thi.ng/equiv": "^2.1.57",
-    "@thi.ng/errors": "^2.5.6"
+    "@thi.ng/api": "^8.11.3",
+    "@thi.ng/checks": "^3.6.5",
+    "@thi.ng/equiv": "^2.1.59",
+    "@thi.ng/errors": "^2.5.8"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.43.0",
-    "esbuild": "^0.20.2",
-    "typedoc": "^0.25.12",
-    "typescript": "^5.4.3"
+    "@microsoft/api-extractor": "^7.47.0",
+    "esbuild": "^0.21.5",
+    "typedoc": "^0.25.13",
+    "typescript": "^5.5.2"
   },
   "keywords": [
     "acceleration",
@@ -179,5 +179,5 @@
     "status": "beta",
     "year": 2021
   },
-  "gitHead": "5dd66c18a3862a3af69a5b2f49563f7cbdd960c2\n"
+  "gitHead": "154c95cf9d6bab32174498ec3b5b5d87e42be7f9\n"
 }

package/unit.d.ts

@@ -94,29 +94,37 @@ export declare class Quantity<T extends number | number[]> implements IDeref<T>
  * dimensionless quantities). Use {@link convert} otherwise!
  *
  * @example
- * ```ts
- * import { convert, div, quantity, NONE } from "@thi.ng/units";
+ * ```ts tangle:../export/quantity.ts
+ * import { convert, div, mul, quantity, NONE } from "@thi.ng/units";
  *
  * const speedOfLight = quantity(299792458, "m/s");
  *
  * // compute wavelength of a WiFi signal in millimeters
- * convert(div(speedOfLight, quantity(2.4,"GHz")), "mm");
+ * console.log(
+ *   convert(div(speedOfLight, quantity(2.4,"GHz")), "mm")
+ * );
  * // 124.9135
  *
  * // DIN A4 paper size
  * const A4 = quantity([210, 297], "mm");
  *
  * // convert paper size to inches
- * convert(A4, "in");
+ * console.log(
+ *   convert(A4, "in")
+ * );
  * // [ 8.2677, 11.6929 ]
  *
  * // or calculate pixel dimensions @ 300 dpi
  * // the result of the product is dimensionless so we use NONE as target unit
- * convert(mul(A4, quantity(300, "dpi")), NONE)
+ * console.log(
+ *   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()
+ * console.log(
+ *   mul(A4, quantity(300, "dpi")).deref()
+ * );
  * // [ 2480.314960629921, 3507.8740157480315 ]
  * ```
  *

package/unit.js

@@ -18,8 +18,7 @@ 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}`);
+  if (UNITS[sym] && !force) illegalArgs(`attempt to override unit: ${sym}`);
   return UNITS[sym] = { ...unit2, sym, name };
 };
 const asUnit = (id) => {
@@ -31,8 +30,7 @@ const asUnit = (id) => {
     }
   }
   for (let u in UNITS) {
-    if (UNITS[u].name === id)
-      return UNITS[u];
+    if (UNITS[u].name === id) return UNITS[u];
   }
   illegalArgs(`unknown unit: ${id}`);
 };
@@ -52,11 +50,9 @@ const quantity = (value, unit2) => new Quantity(
   isNumber(value) ? mul(unit2, value) : value.map((x) => mul(unit2, x))
 );
 function mul(a, b, coherent2 = false) {
-  if (a instanceof Quantity)
-    return __combineQ(mul, a, b);
+  if (a instanceof Quantity) return __combineQ(mul, a, b);
   const $a = __ensureUnit(a);
-  if (isNumber(b))
-    return unit($a.dim, $a.scale * b, $a.offset, coherent2);
+  if (isNumber(b)) return unit($a.dim, $a.scale * b, $a.offset, coherent2);
   const $b = __ensureUnit(b);
   return unit(
     $a.dim.map((x, i) => x + $b.dim[i]),
@@ -66,8 +62,7 @@ function mul(a, b, coherent2 = false) {
   );
 }
 function div(a, b, coherent2 = false) {
-  if (a instanceof Quantity)
-    return __combineQ(div, a, b);
+  if (a instanceof Quantity) return __combineQ(div, a, b);
   const $a = __ensureUnit(a);
   if (isNumber(b)) {
     return unit($a.dim, $a.scale / b, $a.offset, coherent2);
@@ -107,8 +102,7 @@ function convert(x, a, b) {
   return (xnorm - $dest.offset) / $dest.scale;
 }
 const isConvertible = (src, dest) => {
-  if (src instanceof Quantity)
-    return isConvertible(__qunit(src), dest);
+  if (src instanceof Quantity) return isConvertible(__qunit(src), dest);
   const $src = __ensureUnit(src);
   const $dest = __ensureUnit(dest);
   return isReciprocal($src, $dest) || equivArrayLike($src.dim, $dest.dim);
@@ -121,24 +115,20 @@ const isReciprocal = (a, b) => {
   for (let i = 0; i < 7; i++) {
     const xa = $a[i];
     const xb = $b[i];
-    if (xa === 0 && xb === 0)
-      continue;
-    if (xa !== -xb)
-      return false;
+    if (xa === 0 && xb === 0) continue;
+    if (xa !== -xb) return false;
     ok = true;
   }
   return ok;
 };
 const formatSI = (u) => {
-  if (u instanceof Quantity)
-    return formatSI(__qunit(u));
+  if (u instanceof Quantity) return formatSI(__qunit(u));
   const { dim } = __ensureUnit(u);
   const SI = ["kg", "m", "s", "A", "K", "mol", "cd"];
   const acc = [];
   for (let i = 0; i < 7; i++) {
     const x = dim[i];
-    if (x !== 0)
-      acc.push(SI[i] + (x !== 1 ? x : ""));
+    if (x !== 0) acc.push(SI[i] + (x !== 1 ? x : ""));
   }
   return acc.length ? acc.join("\xB7") : "<dimensionless>";
 };