shelving 1.86.0 → 1.86.2

package/util/units.js

@@ -1,39 +1,40 @@
 import { ConditionError } from "../error/ConditionError.js";
 import { DAY, HOUR, MILLION, MINUTE, MONTH, NNBSP, SECOND, WEEK, YEAR } from "./constants.js";
 import { getProps } from "./object.js";
-import { getDuration } from "./date.js";
-import { ImmutableRequiredMap } from "./map.js";
-import { formatFullQuantity, formatQuantity, getPercent } from "./number.js";
+import { ImmutableMap, getMapItem } from "./map.js";
+import { cramQuantity, formatFullQuantity, formatQuantity } from "./number.js";
 /** Convert an amount using a `Conversion. */
 const _convert = (amount, conversion) => (typeof conversion === "function" ? conversion(amount) : conversion === 1 ? amount : amount * conversion);
+/** Get a `Unit` instance from a `UnitList` instance */
+const _getUnit = (list, unit) => (typeof unit === "string" ? getMapItem(list, unit) : unit);
 /** Represent a unit. */
 export class Unit {
+    /** Title for this unit (uses format `abbr (plural)`, e.g. `fl oz (US fluid ounces)`) */
+    get title() {
+        return `${this.abbr} (${this.plural})`;
+    }
     constructor(
     /** `UnitList` this unit belongs to. */
     list, 
-    /** Key for this unit, e.g. `kilometer` */
-    id, 
+    /** String key for this unit, e.g. `kilometer` */
+    key, 
     /** Props to configure this unit. */
-    { abbr = id.slice(0, 1), singular = id.replace(/-/, " "), plural = `${singular}s`, precision = null, to }) {
+    { abbr = key.slice(0, 1), singular = key.replace(/-/, " "), plural = `${singular}s`, precision = null, to }) {
         this.list = list;
-        this.id = id;
+        this.key = key;
         this.abbr = abbr;
         this.singular = singular;
         this.plural = plural;
         this.precision = precision;
         this._to = to;
     }
-    /** Title for this unit (uses format `abbr (plural)`, e.g. `fl oz (US fluid ounces)`) */
-    get title() {
-        return `${this.abbr} (${this.plural})`;
-    }
     /** Convert an amount from this unit to another unit. */
-    to(amount, id = this.list.base) {
-        return this._toUnit(amount, _getUnit(this.list, id));
+    to(amount, unit = this.list.base) {
+        return this._toUnit(amount, _getUnit(this.list, unit));
     }
     /** Convert an amount from another unit to this unit. */
-    from(amount, id = this.list.base) {
-        return _getUnit(this.list, id)._toUnit(amount, this);
+    from(amount, unit = this.list.base) {
+        return _getUnit(this.list, unit)._toUnit(amount, this);
     }
     /** Convert an amount from this unit to another unit (must specify another `Unit` instance). */
     _toUnit(amount, unit) {
@@ -42,33 +43,40 @@ export class Unit {
         if (unit === this)
             return amount;
         // Exact conversion.
-        const thisToUnit = (_a = this._to) === null || _a === void 0 ? void 0 : _a[unit.id];
+        const thisToUnit = (_a = this._to) === null || _a === void 0 ? void 0 : _a[unit.key];
         if (thisToUnit)
             return _convert(amount, thisToUnit);
         // Invert number conversion (can't do this for function conversions).
-        const unitToThis = (_b = unit._to) === null || _b === void 0 ? void 0 : _b[this.id];
+        const unitToThis = (_b = unit._to) === null || _b === void 0 ? void 0 : _b[this.key];
         if (typeof unitToThis === "number")
             return amount / unitToThis;
         // Two step conversion via base.
         const base = this.list.base;
-        const thisToBase = (_c = this._to) === null || _c === void 0 ? void 0 : _c[base.id];
+        const thisToBase = (_c = this._to) === null || _c === void 0 ? void 0 : _c[base.key];
         if (thisToBase)
             return base._toUnit(_convert(amount, thisToBase), unit);
         // Cannot convert.
-        throw new ConditionError(`Cannot convert "${this.id}" to "${unit.id}"`);
+        throw new ConditionError(`Cannot convert "${this.key}" to "${unit.key}"`);
     }
-    /** Format a number with a given unit of measure, e.g. `12 kg` or `29.5 l` */
+    /** Format an amount with a given unit of measure, e.g. `12 kg` or `29.5 l` */
     format(amount, precision = this.precision) {
         return formatQuantity(amount, this.abbr, precision);
     }
-    /** Format a number with a given unit of measure, e.g. `12 kilograms` or `29.5 liters` or `1 degree` */
+    /** Format an amount with a given unit of measure, e.g. `12 kilograms` or `29.5 liters` or `1 degree` */
     formatFull(amount, precision = this.precision) {
         return formatFullQuantity(amount, this.singular, this.plural, precision);
     }
+    /** Cram an amount with a given unit of measure, e.g. `1.25M mi` */
+    cram(amount) {
+        return cramQuantity(amount, this.abbr);
+    }
 }
-const _getUnit = (list, id) => (typeof id === "string" ? list.get(id) : id);
-/** Represent a list of units. */
-export class UnitList extends ImmutableRequiredMap {
+/**
+ * Represent a list of units.
+ * - Has a known base unit at `.base`
+ * - Cannot have additional units added after it is created.
+ */
+export class UnitList extends ImmutableMap {
     constructor(units) {
         super();
         for (const [id, props] of getProps(units)) {
@@ -78,6 +86,10 @@ export class UnitList extends ImmutableRequiredMap {
             Map.prototype.set.call(this, id, unit);
         }
     }
+    /** Convert an amount from a unit to another unit. */
+    convert(amount, sourceUnit, targetUnit) {
+        return _getUnit(this, sourceUnit).to(amount, targetUnit);
+    }
 }
 // Distance constants.
 const IN_PER_FT = 12;
@@ -206,53 +218,3 @@ export const TEMPERATURE_UNITS = new UnitList({
     fahrenheit: { abbr: "°F", singular: "degree Fahrenheit", plural: "degrees Fahrenheit", to: { celsius: n => (n - 32) * (5 / 9) } },
     kelvin: { abbr: "°K", singular: "degree Kelvin", plural: "degrees Kelvin", to: { celsius: n => n - 273.15 } },
 });
-/** Format a percentage (combines `getPercent()` and `formatUnits()` for convenience). */
-export const formatPercent = (numerator, denumerator, precision) => formatQuantity(getPercent(numerator, denumerator), "%", precision);
-/** Get the ID for a time unit based on the amount in milliseconds. */
-function _getTimeUnitIdentifier(ms) {
-    const abs = Math.abs(ms);
-    if (abs > 18 * MONTH)
-        return "year";
-    if (abs > 10 * WEEK)
-        return "month";
-    if (abs > 2 * WEEK)
-        return "week";
-    if (abs > DAY)
-        return "day";
-    if (abs > HOUR)
-        return "hour";
-    if (abs > 9949)
-        return "minute";
-    if (abs > SECOND)
-        return "second";
-    return "millisecond";
-}
-/** Format a full format of a duration of time using the most reasonable units e.g. `5 years` or `1 week` or `4 minutes` or `12 milliseconds`. */
-export function formatFullDuration(ms, precision) {
-    const unit = TIME_UNITS.get(_getTimeUnitIdentifier(ms));
-    return unit.formatFull(unit.from(ms), precision);
-}
-/** Format a description of a duration of time using the most reasonable units e.g. `5y` or `4m` or `12ms`. */
-export function formatDuration(ms, precision) {
-    const unit = TIME_UNITS.get(_getTimeUnitIdentifier(ms));
-    return unit.format(unit.from(ms), precision);
-}
-/** format when a data happens/happened. */
-function _formatWhen(formatter, target, current) {
-    const ms = getDuration(target, current);
-    const abs = Math.abs(ms);
-    const duration = formatter(ms);
-    return abs < 10 * SECOND ? "just now" : ms > 0 ? `in ${duration}` : `${duration} ago`;
-}
-/** Full when a date happens/happened, e.g. `in 10 days` or `2 hours ago` */
-export const formatFullWhen = (target, current) => _formatWhen(formatFullDuration, target, current);
-/** Compact when a date happens/happened, e.g. `in 10d` or `2h ago` or `in 1w` */
-export const formatWhen = (target, current) => _formatWhen(formatDuration, target, current);
-/** Full when a date happens, e.g. `10 days` or `2 hours` or `-1 week` */
-export const formatFullUntil = (target, current) => formatFullDuration(getDuration(target, current));
-/** Compact when a date happens, e.g. `10d` or `2h` or `-1w` */
-export const formatUntil = (target, current) => formatDuration(getDuration(target, current));
-/** Full when a date happened, e.g. `10 days` or `2 hours` or `-1 week` */
-export const formatFullAgo = (target, current) => formatFullDuration(getDuration(current, target));
-/** Compact when a date will happen, e.g. `10d` or `2h` or `-1w` */
-export const formatAgo = (target, current) => formatDuration(getDuration(current, target));

package/util/url.d.ts

@@ -1,6 +1,6 @@
 /** Things that can be converted to a URL instance. */
-export declare type PossibleURL = string | URL;
-export declare type PossibleOptionalURL = PossibleURL | null;
+export type PossibleURL = string | URL;
+export type PossibleOptionalURL = PossibleURL | null;
 /** Is an unknown value a URL? */
 export declare const isURL: (v: URL | unknown) => v is URL;
 /** Assert that an unknown value is a URL. */

package/util/validate.d.ts

@@ -17,17 +17,17 @@ export interface Validatable<T> {
     validate(unsafeValue: unknown): T;
 }
 /** Function that can validate a value. */
-export declare type Validate<T> = (unsafeValue: unknown) => T;
+export type Validate<T> = (unsafeValue: unknown) => T;
 /** Something that can validate a value. */
-export declare type Validator<T = unknown> = Validatable<T> | Validate<T>;
+export type Validator<T = unknown> = Validatable<T> | Validate<T>;
 /** Extract the type from a validator. */
-export declare type ValidatorType<X> = X extends Validator<infer Y> ? Y : never;
+export type ValidatorType<X> = X extends Validator<infer Y> ? Y : never;
 /** A set of named validators in `{ name: Validator }` format. */
-export declare type Validators<T extends Data = Data> = {
+export type Validators<T extends Data = Data> = {
     readonly [K in keyof T]: Validator<T[K]>;
 };
 /** Extract the type from a set of validators. */
-export declare type ValidatorsType<T> = {
+export type ValidatorsType<T> = {
     readonly [K in keyof T]: ValidatorType<T[K]>;
 };
 /** Validate an unknown value with a validator. */