@thi.ng/units 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-03-15T14:55:07Z
+- **Last updated**: 2023-03-16T11:22:27Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,12 @@ 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.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/units@0.3.0) (2023-03-16)
+
+#### 🚀 Features
+
+- add more quantities/constants ([27cd71e](https://github.com/thi-ng/umbrella/commit/27cd71e))
+
 ## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/units@0.2.0) (2023-03-15)
 
 #### 🚀 Features

package/README.md

@@ -16,6 +16,7 @@ This project is part of the
     - [Angle](#angle)
     - [Area](#area)
     - [Data](#data)
+    - [Density](#density)
     - [Electric current](#electric-current)
     - [Energy](#energy)
     - [Force](#force)
@@ -88,7 +89,7 @@ For example, here's how we can define kilograms and meters:
 
 ```ts
 // kilogram, SI dimension 0
-const KG = coherent(1);
+const KG = coherent(0);
 // { dim: [ 1, 0, 0, 0, 0, 0, 0 ], scale: 1, offset: 0, coherent: true }
 
 // meters, SI dimension 1
@@ -193,6 +194,13 @@ The following units are provided as "builtins", here grouped by dimension:
 | `PiB`     | `PiB`         | pebibyte (1024)   |
 | `EiB`     | `EiB`         | exbibyte (1024)   |
 
+#### Density
+
+| Unit     | Variable name | Description   |
+|----------|---------------|---------------|
+| `kg/m3`  | `kg_m3`       | density       |
+| `1/inch` | `dpi`         | dots per inch |
+
 #### Electric current
 
 | Unit  | Variable name | Description       |
@@ -296,15 +304,15 @@ The following units are provided as "builtins", here grouped by dimension:
 
 https://en.wikipedia.org/wiki/Parts-per_notation
 
-| Unit name | Variable name | Description                    |
-|-----------|---------------|--------------------------------|
-| `%`       | `percent`     | part per hundred               |
-| `‰`       | `permille`    | part per thousand              |
-| `‱`       | `permyriad`   | part per ten thousand          |
-| `pcm`     | `pcm`         | part per cent hundred thousand |
-| `ppm`     | `ppm`         | part per million               |
-| `ppb`     | `ppb`         | part per billion               |
-| `ppt`     | `ppt`         | part per trillion              |
+| Unit name | Variable name | Description               |
+|-----------|---------------|---------------------------|
+| `%`       | `percent`     | part per hundred          |
+| `‰`       | `permille`    | part per thousand         |
+| `‱`       | `permyriad`   | part per ten thousand     |
+| `pcm`     | `pcm`         | part per hundred thousand |
+| `ppm`     | `ppm`         | part per million          |
+| `ppb`     | `ppb`         | part per billion          |
+| `ppt`     | `ppt`         | part per trillion         |
 
 #### Power
 
@@ -472,7 +480,9 @@ Another example using dimensionless units (here angles, arc second ⇒ radian) t
 compute the distance of 10 arcsec on the earth surface (in meters):
 
 ```ts
-const R = 6371000; // earth radius in meters
+// earth radius in meters
+// (also available as quantity EARTH_RADIUS, see section below)
+const R = 6371000;
 
 convert(10, "arcsec", "rad") * R;
 // 308.87479623488537
@@ -487,7 +497,7 @@ calculations & conversions using the above mentioned polymorphic functions:
 
 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
+ which acts as 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
@@ -502,6 +512,8 @@ convert(div(speedOfLight, quantity(2.4,"GHz")), "mm");
 // 124.9135
 ```
 
+Some examples using vector quantities:
+
 ```ts
 // DIN A4 paper size (also available as preset)
 const A4 = quantity([210, 297], "mm");
@@ -511,12 +523,12 @@ convert(A4, "in");
 // [ 8.2677, 11.6929 ]
 
 // or calculate pixel dimensions @ 300 dpi
-// the result of the product is dimensionless
+// the result of this 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
+// alternatively, dimensionless units can be deref'd directly
 mul(A4, quantity(300, "dpi")).deref()
 // [ 2480.314960629921, 3507.8740157480315 ]
 ```
@@ -533,12 +545,42 @@ convert(mul(quantity(10, "mm"), quantity(2, "in")), "cm2")
 
 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"`        |
+| Var name                  | Unit              | Comment                |
+|---------------------------|-------------------|------------------------|
+| `DIN_A0` ... `DIN_A8`     | 2d vector of `mm` | Paper sizes            |
+| `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 ℃                |
+
+Densities of selected materials:
+
+| Var name     | Unit    |
+|--------------|---------|
+| `AIR`        | `kg/m3` |
+| `ALUMINIUM`  | `kg/m3` |
+| `CONCRETE`   | `kg/m3` |
+| `COPPER`     | `kg/m3` |
+| `DIAMOND`    | `kg/m3` |
+| `GLASS`      | `kg/m3` |
+| `GOLD`       | `kg/m3` |
+| `ICE`        | `kg/m3` |
+| `IRON`       | `kg/m3` |
+| `NYLON`      | `kg/m3` |
+| `PLASTIC`    | `kg/m3` |
+| `PLATINUM`   | `kg/m3` |
+| `SAND`       | `kg/m3` |
+| `SALT_WATER` | `kg/m3` |
+| `SILICON`    | `kg/m3` |
+| `SILVER`     | `kg/m3` |
+| `STEEL`      | `kg/m3` |
+| `TITANIUM`   | `kg/m3` |
+| `WATER`      | `kg/m3` |
+| `WOOD`       | `kg/m3` |
 
 ## Status
 
@@ -566,7 +608,7 @@ For Node.js REPL:
 const units = await import("@thi.ng/units");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 4.05 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 4.37 KB
 
 ## Dependencies
 

package/constants/densities.d.ts

@@ -0,0 +1,25 @@
+export declare const AIR: import("../unit.js").Quantity<1.2>;
+export declare const ALUMINIUM: import("../unit.js").Quantity<2700>;
+export declare const ALUMINUM: import("../unit.js").Quantity<2700>;
+export declare const CONCRETE: import("../unit.js").Quantity<2400>;
+export declare const COPPER: import("../unit.js").Quantity<8940>;
+export declare const DIAMOND: import("../unit.js").Quantity<3500>;
+export declare const GLASS: import("../unit.js").Quantity<2500>;
+export declare const GOLD: import("../unit.js").Quantity<19320>;
+export declare const ICE: import("../unit.js").Quantity<916.7>;
+export declare const IRON: import("../unit.js").Quantity<7870>;
+export declare const NYLON: import("../unit.js").Quantity<1150>;
+export declare const PLASTIC: import("../unit.js").Quantity<1175>;
+export declare const PLATINUM: import("../unit.js").Quantity<21450>;
+export declare const SAND: import("../unit.js").Quantity<1600>;
+export declare const SALT_WATER: import("../unit.js").Quantity<1030>;
+export declare const SILICON: import("../unit.js").Quantity<2330>;
+export declare const SILVER: import("../unit.js").Quantity<10500>;
+export declare const STEEL: import("../unit.js").Quantity<7850>;
+export declare const TITANIUM: import("../unit.js").Quantity<4540>;
+/**
+ * Fresh water @ 4 degree celsius (max. density)
+ */
+export declare const WATER: import("../unit.js").Quantity<1000>;
+export declare const WOOD: import("../unit.js").Quantity<700>;
+//# sourceMappingURL=densities.d.ts.map

package/constants/densities.js

@@ -0,0 +1,28 @@
+import { quantity } from "../unit.js";
+import { kg_m3 } from "../units/density.js";
+// https://en.wikipedia.org/wiki/Density#Various_materials
+export const AIR = quantity(1.2, kg_m3);
+export const ALUMINIUM = quantity(2700, kg_m3);
+// for americans...
+export const ALUMINUM = ALUMINIUM;
+export const CONCRETE = quantity(2400, kg_m3);
+export const COPPER = quantity(8940, kg_m3);
+export const DIAMOND = quantity(3500, kg_m3);
+export const GLASS = quantity(2500, kg_m3);
+export const GOLD = quantity(19320, kg_m3);
+export const ICE = quantity(916.7, kg_m3);
+export const IRON = quantity(7870, kg_m3);
+export const NYLON = quantity(1150, kg_m3);
+export const PLASTIC = quantity(1175, kg_m3);
+export const PLATINUM = quantity(21450, kg_m3);
+export const SAND = quantity(1600, kg_m3);
+export const SALT_WATER = quantity(1030, kg_m3);
+export const SILICON = quantity(2330, kg_m3);
+export const SILVER = quantity(10500, kg_m3);
+export const STEEL = quantity(7850, kg_m3);
+export const TITANIUM = quantity(4540, kg_m3);
+/**
+ * Fresh water @ 4 degree celsius (max. density)
+ */
+export const WATER = quantity(1000, kg_m3);
+export const WOOD = quantity(700, kg_m3);

package/constants/din-sizes.js

@@ -1,5 +1,6 @@
 import { mm } from "../units/length.js";
 import { quantity } from "../unit.js";
+// https://en.wikipedia.org/wiki/ISO_216x
 export const DIN_A0 = quantity([841, 1189], mm);
 export const DIN_A1 = quantity([594, 841], mm);
 export const DIN_A2 = quantity([420, 594], mm);

package/constants/earth.d.ts

@@ -0,0 +1,33 @@
+/**
+ * https://en.wikipedia.org/wiki/Earth_radius
+ */
+export declare const EARTH_RADIUS: import("../unit.js").Quantity<6371000>;
+/**
+ * At equator
+ *
+ * @remarks
+ * Reference:
+ * - https://en.wikipedia.org/wiki/Earth%27s_circumference
+ */
+export declare const EARTH_CIRCUMFERENCE: import("../unit.js").Quantity<40075017>;
+/**
+ * Using equatorial mean as alternative to {@link g0}.
+ *
+ * @remarks
+ * Reference:
+ * - https://en.wikipedia.org/wiki/Gravity_of_Earth
+ */
+export declare const EARTH_GRAVITY: import("../unit.js").Quantity<9.78033>;
+/**
+ * https://nssdc.gsfc.nasa.gov/planetary/factsheet/earthfact.html
+ */
+export declare const EARTH_MASS: import("../unit.js").Quantity<5.9722e+24>;
+/**
+ * Gravitational constant (kg-1·m3·s-2)
+ *
+ * @remarks
+ * Reference:
+ * - https://en.wikipedia.org/wiki/Gravitational_constant
+ */
+export declare const GRAVITATION: import("../unit.js").Quantity<6.6743e-11>;
+//# sourceMappingURL=earth.d.ts.map

package/constants/earth.js

@@ -0,0 +1,35 @@
+import { quantity, unit } from "../unit.js";
+import { m_s2 } from "../units/accel.js";
+import { m } from "../units/length.js";
+/**
+ * https://en.wikipedia.org/wiki/Earth_radius
+ */
+export const EARTH_RADIUS = quantity(6371000, m);
+/**
+ * At equator
+ *
+ * @remarks
+ * Reference:
+ * - https://en.wikipedia.org/wiki/Earth%27s_circumference
+ */
+export const EARTH_CIRCUMFERENCE = quantity(40075017, m);
+/**
+ * Using equatorial mean as alternative to {@link g0}.
+ *
+ * @remarks
+ * Reference:
+ * - https://en.wikipedia.org/wiki/Gravity_of_Earth
+ */
+export const EARTH_GRAVITY = quantity(9.78033, m_s2);
+/**
+ * https://nssdc.gsfc.nasa.gov/planetary/factsheet/earthfact.html
+ */
+export const EARTH_MASS = quantity(5.9722e24, "kg");
+/**
+ * Gravitational constant (kg-1·m3·s-2)
+ *
+ * @remarks
+ * Reference:
+ * - https://en.wikipedia.org/wiki/Gravitational_constant
+ */
+export const GRAVITATION = quantity(6.6743e-11, unit([-1, 3, -2, 0, 0, 0, 0], 1));

package/constants/velocities.d.ts

@@ -1,3 +1,6 @@
+/**
+ * https://en.wikipedia.org/wiki/Speed_of_light
+ */
 export declare const SPEED_OF_LIGHT: import("../unit.js").Quantity<299792458>;
 /**
  * At 20 degree celsius

package/constants/velocities.js

@@ -1,5 +1,8 @@
 import { quantity } from "../unit.js";
 import { m_s } from "../units/velocity.js";
+/**
+ * https://en.wikipedia.org/wiki/Speed_of_light
+ */
 export const SPEED_OF_LIGHT = quantity(299792458, m_s);
 /**
  * At 20 degree celsius

package/index.d.ts

@@ -20,6 +20,8 @@ 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/din-sizes.js";
+export * from "./constants/earth.js";
 export * from "./constants/velocities.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -20,5 +20,7 @@ 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/din-sizes.js";
+export * from "./constants/earth.js";
 export * from "./constants/velocities.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/units",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Extensible SI unit creation, conversions, quantities & calculations (incl. ~170 predefined units & constants)",
   "type": "module",
   "module": "./index.js",
@@ -99,9 +99,15 @@
     "./api": {
       "default": "./api.js"
     },
+    "./constants/densities": {
+      "default": "./constants/densities.js"
+    },
     "./constants/din-sizes": {
       "default": "./constants/din-sizes.js"
     },
+    "./constants/earth": {
+      "default": "./constants/earth.js"
+    },
     "./constants/velocities": {
       "default": "./constants/velocities.js"
     },
@@ -173,5 +179,5 @@
     "status": "beta",
     "year": 2021
   },
-  "gitHead": "ded6c346ccabc8bf647b848738878bdae8e05d55\n"
+  "gitHead": "f493d89d81d450ca67adf4f574b08840cba87807\n"
 }