@thi.ng/units 0.1.0

package/unit.d.ts

@@ -0,0 +1,158 @@
+import { Dimensions, MaybeUnit, NamedUnit, Prefix, Unit } from "./api.js";
+/**
+ * Cache/registry for all units defined via {@link defUnit}.
+ */
+export declare const UNITS: Record<string, NamedUnit>;
+/**
+ * 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
+ * given dimensions and can later be used for deriving prefixed versions (see
+ * {@link coherent}).
+ *
+ * @param dim
+ * @param scale
+ * @param offset
+ * @param coherent
+ */
+export declare const unit: (dim: Dimensions | number, scale: number, offset?: number, coherent?: boolean) => Unit;
+/**
+ * Syntax sugar for defining coherent SI base units. See {@link unit}.
+ *
+ * @param dim
+ */
+export declare const coherent: (dim: Dimensions | number) => Unit;
+/**
+ * Returns a new dimensionless unit (i.e. all SI dimensions are zero) with given
+ * `scale` factor.
+ *
+ * @param scale
+ * @param offset
+ * @param coherent
+ */
+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.
+ *
+ * @remarks
+ * 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 name
+ * @param unit
+ * @param force
+ */
+export declare const defUnit: (sym: string, name: string, unit: Unit, force?: boolean) => NamedUnit;
+/**
+ * Attempts to find a unit by given symbol ID/name. Throws error if unit is
+ * unknown.
+ *
+ * @param id
+ */
+export declare const asUnit: (id: string) => Unit;
+/**
+ * Creates a new re-scaled version of given unit (only coherent ones are
+ * allowed), using the scale factor associated with given standard metric prefix
+ * (see {@link PREFIXES}). If `coherent` is true (default: false), the new unit
+ * itself is considered coherent and can be prefixed later.
+ *
+ * @example
+ * ```ts
+ * // create kilometer unit from (builtin) meter
+ * const KM = prefix("k", M);
+ * ```
+ *
+ * @param id
+ * @param unit
+ * @param coherent
+ */
+export declare const prefix: (id: Prefix, unit: MaybeUnit, coherent?: boolean) => Unit;
+/**
+ * Derives a new unit as the product of the given units. If `coherent` is true
+ * (default: false), the new unit itself is considered coherent and can be
+ * prefixed later.
+ *
+ * @param a
+ * @param b
+ * @param coherent
+ */
+export declare const mul: (a: MaybeUnit, b: MaybeUnit | number, coherent?: boolean) => Unit;
+/**
+ * Derives a new unit via the division of the given units. If `coherent` is true
+ * (default: false), the new unit itself is considered coherent and can be
+ * prefixed later.
+ *
+ * @param a
+ * @param b
+ * @param coherent
+ */
+export declare const div: (a: MaybeUnit, b: MaybeUnit | number, coherent?: boolean) => Unit;
+/**
+ * Creates the reciprocal version of given unit (i.e. all SI dimensions will
+ * flip sign) and the scale factor of the new unit will be `1/scale`. If
+ * `coherent` is true (default: false), the new unit itself is considered
+ * coherent and can be prefixed later.
+ *
+ * @example
+ * ```ts
+ * const HZ = reciprocal(S, true);
+ * ```
+ *
+ * @param u
+ * @param coherent
+ */
+export declare const reciprocal: (u: MaybeUnit, coherent?: boolean) => Unit;
+/**
+ * Raises given unit to power `k`. If `coherent` is true (default: false), the
+ * new unit itself is considered coherent and can be prefixed later.
+ *
+ * ```ts
+ * // create kilometer unit from (builtin) meter
+ * const SQ_METER = pow(M, 2);
+ *
+ * // acceleration aka m/s^2
+ * const M_S2 = div(M, pow(S, 2));
+ * ```
+ *
+ * @param u
+ * @param k
+ * @param coherent
+ */
+export declare const pow: (u: MaybeUnit, k: number, coherent?: boolean) => Unit;
+/**
+ * Attempts to convert `x` from `src` unit into `dest` unit. Throws an error if
+ * units are incompatible.
+ *
+ * @remarks
+ * Units can only be converted if their SI dimensions are compatible. See
+ * {@link isConvertible}.
+ *
+ * @param x
+ * @param src
+ * @param dest
+ */
+export declare const convert: (x: number, src: MaybeUnit, dest: MaybeUnit) => number;
+/**
+ * Returns true if `src` unit is convertible to `dest`.
+ *
+ * @param src
+ * @param dest
+ */
+export declare const isConvertible: (src: MaybeUnit, dest: MaybeUnit) => boolean;
+/**
+ * Returns true, if `u` is a dimensionless unit.
+ *
+ * @param u
+ */
+export declare const isDimensionless: (u: MaybeUnit) => boolean;
+/**
+ * Returns true if the two given units are reciprocal to each other (and
+ * therefore can be used for conversion).
+ *
+ * @param a
+ * @param b
+ */
+export declare const isReciprocal: (a: MaybeUnit, b: MaybeUnit) => boolean;
+export declare const formatSI: (u: MaybeUnit) => string;
+//# sourceMappingURL=unit.d.ts.map

package/unit.js

@@ -0,0 +1,252 @@
+import { isNumber } from "@thi.ng/checks/is-number";
+import { isString } from "@thi.ng/checks/is-string";
+import { equivArrayLike } from "@thi.ng/equiv";
+import { assert } from "@thi.ng/errors/assert";
+import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
+import { PREFIXES, } from "./api.js";
+/**
+ * Cache/registry for all units defined via {@link defUnit}.
+ */
+export const UNITS = {};
+/**
+ * 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
+ * given dimensions and can later be used for deriving prefixed versions (see
+ * {@link coherent}).
+ *
+ * @param dim
+ * @param scale
+ * @param offset
+ * @param coherent
+ */
+export const unit = (dim, scale, offset = 0, coherent = false) => ({
+    dim: isNumber(dim) ? __oneHot(dim) : dim,
+    scale,
+    offset,
+    coherent,
+});
+/**
+ * Syntax sugar for defining coherent SI base units. See {@link unit}.
+ *
+ * @param dim
+ */
+export const coherent = (dim) => unit(dim, 1, 0, true);
+/**
+ * Returns a new dimensionless unit (i.e. all SI dimensions are zero) with given
+ * `scale` factor.
+ *
+ * @param scale
+ * @param offset
+ * @param coherent
+ */
+export const dimensionless = (scale, offset = 0, coherent = false) => unit([0, 0, 0, 0, 0, 0, 0], scale, offset, coherent);
+/**
+ * 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.
+ *
+ * @remarks
+ * 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 name
+ * @param unit
+ * @param force
+ */
+export const defUnit = (sym, name, unit, force = false) => {
+    if (UNITS[sym] && !force)
+        illegalArgs(`attempt to override unit: ${sym}`);
+    return (UNITS[sym] = { ...unit, sym, name });
+};
+/**
+ * Attempts to find a unit by given symbol ID/name. Throws error if unit is
+ * unknown.
+ *
+ * @param id
+ */
+export const asUnit = (id) => {
+    for (let i = 0; i < id.length; i++) {
+        const pre = id.substring(0, i);
+        const unit = UNITS[id.substring(i)];
+        if (unit) {
+            return PREFIXES[pre] !== undefined
+                ? prefix(pre, unit)
+                : unit;
+        }
+    }
+    for (let u in UNITS) {
+        if (UNITS[u].name === id)
+            return UNITS[u];
+    }
+    illegalArgs(`unknown unit: ${id}`);
+};
+/**
+ * Creates a new re-scaled version of given unit (only coherent ones are
+ * allowed), using the scale factor associated with given standard metric prefix
+ * (see {@link PREFIXES}). If `coherent` is true (default: false), the new unit
+ * itself is considered coherent and can be prefixed later.
+ *
+ * @example
+ * ```ts
+ * // create kilometer unit from (builtin) meter
+ * const KM = prefix("k", M);
+ * ```
+ *
+ * @param id
+ * @param unit
+ * @param coherent
+ */
+export const prefix = (id, unit, coherent = false) => {
+    const $u = __ensureUnit(unit);
+    return $u.coherent
+        ? mul($u, PREFIXES[id], coherent)
+        : illegalArgs("unit isn't coherent");
+};
+/**
+ * Derives a new unit as the product of the given units. If `coherent` is true
+ * (default: false), the new unit itself is considered coherent and can be
+ * prefixed later.
+ *
+ * @param a
+ * @param b
+ * @param coherent
+ */
+export const mul = (a, b, coherent = false) => {
+    const $a = __ensureUnit(a);
+    if (isNumber(b)) {
+        return unit($a.dim, $a.scale * b, $a.offset, coherent);
+    }
+    const $b = __ensureUnit(b);
+    return unit($a.dim.map((x, i) => x + $b.dim[i]), $a.scale * $b.scale, 0, coherent);
+};
+/**
+ * Derives a new unit via the division of the given units. If `coherent` is true
+ * (default: false), the new unit itself is considered coherent and can be
+ * prefixed later.
+ *
+ * @param a
+ * @param b
+ * @param coherent
+ */
+export const div = (a, b, coherent = false) => {
+    const $a = __ensureUnit(a);
+    if (isNumber(b)) {
+        return unit($a.dim, $a.scale / b, $a.offset, coherent);
+    }
+    const $b = __ensureUnit(b);
+    return unit($a.dim.map((x, i) => x - $b.dim[i]), $a.scale / $b.scale, 0, coherent);
+};
+/**
+ * Creates the reciprocal version of given unit (i.e. all SI dimensions will
+ * flip sign) and the scale factor of the new unit will be `1/scale`. If
+ * `coherent` is true (default: false), the new unit itself is considered
+ * coherent and can be prefixed later.
+ *
+ * @example
+ * ```ts
+ * const HZ = reciprocal(S, true);
+ * ```
+ *
+ * @param u
+ * @param coherent
+ */
+export const reciprocal = (u, coherent = false) => div(dimensionless(1), u, coherent);
+/**
+ * Raises given unit to power `k`. If `coherent` is true (default: false), the
+ * new unit itself is considered coherent and can be prefixed later.
+ *
+ * ```ts
+ * // create kilometer unit from (builtin) meter
+ * const SQ_METER = pow(M, 2);
+ *
+ * // acceleration aka m/s^2
+ * const M_S2 = div(M, pow(S, 2));
+ * ```
+ *
+ * @param u
+ * @param k
+ * @param coherent
+ */
+export const pow = (u, k, coherent = false) => {
+    const $u = __ensureUnit(u);
+    return unit($u.dim.map((x) => x * k), $u.scale ** k, 0, coherent);
+};
+/**
+ * Attempts to convert `x` from `src` unit into `dest` unit. Throws an error if
+ * units are incompatible.
+ *
+ * @remarks
+ * Units can only be converted if their SI dimensions are compatible. See
+ * {@link isConvertible}.
+ *
+ * @param x
+ * @param src
+ * @param dest
+ */
+export const convert = (x, src, dest) => {
+    const $src = __ensureUnit(src);
+    const $dest = __ensureUnit(dest);
+    const xnorm = x * $src.scale + $src.offset;
+    if (isReciprocal($src, $dest))
+        return (1 / xnorm - $dest.offset) / $dest.scale;
+    assert(equivArrayLike($src.dim, $dest.dim), "incompatible dimensions");
+    return (xnorm - $dest.offset) / $dest.scale;
+};
+/**
+ * Returns true if `src` unit is convertible to `dest`.
+ *
+ * @param src
+ * @param dest
+ */
+export const isConvertible = (src, dest) => {
+    const $src = __ensureUnit(src);
+    const $dest = __ensureUnit(dest);
+    return isReciprocal($src, $dest) || equivArrayLike($src.dim, $dest.dim);
+};
+/**
+ * Returns true, if `u` is a dimensionless unit.
+ *
+ * @param u
+ */
+export const isDimensionless = (u) => __ensureUnit(u).dim.every((x) => x === 0);
+/**
+ * Returns true if the two given units are reciprocal to each other (and
+ * therefore can be used for conversion).
+ *
+ * @param a
+ * @param b
+ */
+export const isReciprocal = (a, b) => {
+    const { dim: $a } = __ensureUnit(a);
+    const { dim: $b } = __ensureUnit(b);
+    let ok = false;
+    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;
+        ok = true;
+    }
+    return ok;
+};
+export const formatSI = (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 : ""));
+    }
+    return acc.length ? acc.join("·") : "<dimensionless>";
+};
+/** @internal */
+const __ensureUnit = (x) => (isString(x) ? asUnit(x) : x);
+/** @internal */
+const __oneHot = (x) => {
+    const dims = new Array(7).fill(0);
+    dims[x] = 1;
+    return dims;
+};

package/volume.d.ts

@@ -0,0 +1,15 @@
+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 l: import("./api.js").NamedUnit;
+export declare const cl: import("./api.js").NamedUnit;
+export declare const ml: import("./api.js").NamedUnit;
+export declare const gal: import("./api.js").NamedUnit;
+export declare const pt: import("./api.js").NamedUnit;
+export declare const floz: import("./api.js").NamedUnit;
+export declare const us_gal: import("./api.js").NamedUnit;
+export declare const us_pt: import("./api.js").NamedUnit;
+export declare const us_cup: import("./api.js").NamedUnit;
+export declare const us_floz: import("./api.js").NamedUnit;
+//# sourceMappingURL=volume.d.ts.map

package/volume.js

@@ -0,0 +1,16 @@
+import { cm, km, m, mm } from "./length.js";
+import { defUnit, mul, pow, prefix } from "./unit.js";
+export const m3 = defUnit("m3", "cubic meter", pow(m, 3));
+export const mm3 = defUnit("mm3", "cubic millimeter", pow(mm, 3));
+export const cm3 = defUnit("cm3", "cubic centimeter", pow(cm, 3));
+export const km3 = defUnit("km3", "cubic kilometer", pow(km, 3));
+export const l = defUnit("l", "liter", mul(m3, 1e-3, true));
+export const cl = defUnit("cl", "centiliter", prefix("c", l));
+export const ml = defUnit("ml", "milliliter", prefix("m", l));
+export const gal = defUnit("gal", "imperial gallon", mul(l, 4.54609));
+export const pt = defUnit("pt", "imperial pint", mul(gal, 1 / 8));
+export const floz = defUnit("fl oz", "imperial fluid ounce", mul(gal, 1 / 160));
+export const us_gal = defUnit("us gal", "us gallon", mul(l, 3.785411784));
+export const us_pt = defUnit("us pt", "us pint", mul(us_gal, 1 / 8));
+export const us_cup = defUnit("us cup", "us cup", mul(us_gal, 1 / 16));
+export const us_floz = defUnit("us fl oz", "us fluid ounce", mul(us_gal, 1 / 128));