shelving 1.40.0 → 1.44.0

package/util/number.js

@@ -1,4 +1,9 @@
 import { AssertionError } from "../error/index.js";
+import { NBSP, NNBSP } from "./string.js";
+// Constants.
+export const TRILLION = 1000000000000;
+export const BILLION = 1000000000;
+export const MILLION = 1000000;
 /** Is a value a number? */
 export const isNumber = (v) => typeof v === "number";
 /**
@@ -36,29 +41,87 @@ export function getNumber(value) {
  *
  * @param num The number to round.
  * @param step The rounding to round to, e.g. `2` or `0.1` (defaults to `1`, i.e. round numbers).
- * @returns The number rounded to the step.
+ *
+ * @returns The number rounded to the specified step.
  */
-export function roundStep(num, step = 1) {
-    if (step < 0.00001)
-        throw new AssertionError("roundToStep() does not work accurately with steps smaller than 0.00001", step);
-    return Math.round(num / step) * step;
-}
+export const roundStep = (num, step = 1) => Math.round(num / step) * step;
 /**
  * Round a number to a specified set of decimal places.
- * - Doesn't include excess `0` zeroes like `num.toFixed()` and `num.toPrecision()` do.
+ * - Better than `Math.round()` because it allows a `precision` argument.
+ * - Better than `num.toFixed()` because it trims excess `0` zeroes.
  *
- * @param num The number to format.
- * @param precision Maximum of digits shown after the decimal point (defaults to 10), with zeroes trimmed.
- * @returns The number formatted as a string in the browser's current locale.
+ * @param num The number to round.
+ * @param precision Maximum number of digits shown after the decimal point (defaults to 10).
+ *
+ * @returns The number rounded to the specified precision.
  */
-export const roundNumber = (num, precision = 10) => new Intl.NumberFormat("en-US", { maximumFractionDigits: precision }).format(num);
+export const roundNumber = (num, precision = 0) => Math.round(num * 10 ** precision) / 10 ** precision;
+/**
+ * Truncate a number to a specified set of decimal places.
+ * - Better than `Math.trunc()` because it allows a `precision` argument.
+ *
+ * @param num The number to truncate.
+ * @param precision Maximum number of digits shown after the decimal point (defaults to 10).
+ *
+ * @returns The number truncated to the specified precision.
+ */
+export const truncateNumber = (num, precision = 0) => Math.trunc(num * 10 ** precision) / 10 ** precision;
 /**
  * Format a number (based on the user's browser settings).
+ *
  * @param num The number to format.
- * @param precision Maximum of digits shown after the decimal point (defaults to 10), with zeroes trimmed.
+ * @param maxPrecision Maximum number of digits shown after the decimal point (defaults to 2).
+ * @param minPrecision Minimum number of digits shown after the decimal point (defaults to 0).
+ *
  * @returns The number formatted as a string in the browser's current locale.
  */
-export const formatNumber = (num, precision = 10) => new Intl.NumberFormat(undefined, { maximumFractionDigits: precision }).format(num);
+export const formatNumber = (num, maxPrecision = 4, minPrecision = 0) => new Intl.NumberFormat(undefined, { maximumFractionDigits: maxPrecision, minimumFractionDigits: minPrecision }).format(num);
+/** Format a number with a short suffix (number and suffix are separated by a non-breaking narrow space). */
+export const formatQuantity = (num, suffix, maxPrecision, minPrecision) => `${formatNumber(num, maxPrecision, minPrecision)}${NNBSP}${suffix}`;
+/** Format a number with a longer full-word suffix (number and suffix are separated by a non-breaking space). */
+export function formatFullQuantity(num, singular, plural, maxPrecision, minPrecision) {
+    const qty = formatNumber(num, maxPrecision, minPrecision);
+    return `${qty}${NBSP}${qty === "1" ? singular : plural}`;
+}
+/**
+ * Cram a large whole numbers into a space efficient format, e.g. `14.7M`
+ * - Improves glanceability.
+ * - Keeps number of characters under five if possible.
+ *
+ * - Numbers over 100 trillion: `157T`
+ * - Numbers over 10 trillion: `15.7T` (includes zero e.g. `40.0T` for consistency).
+ * - Numbers over 1 trillion: `1.57T` (includes zeros e.g. `4.00T` for consistency).
+ * - Numbers over 100 billion: `157B`
+ * - Numbers over 10 billion: `15.7B` (includes zero e.g. `40.0B` for consistency).
+ * - Numbers over 1 billion: `1.57B` (includes zeros e.g. `4.00B` for consistency).
+ * - Numbers over 100 million: `157M`
+ * - Numbers over 10 million: `15.7M` (includes zero e.g. `40.0M` for consistency).
+ * - Numbers over 1 million: `1.57M` (includes zeros e.g. `4.00M` for consistency).
+ * - Numbers over 100,000: `157K`
+ * - Numbers over 10,000: `15.7K` (includes zero e.g. `14.0K` for consistency).
+ * - Smaller numbers: `1570` and `157` and `15.7` and `1.6`
+ *
+ * @param num The number to format.
+ * @param precision Maximum number of digits shown after the decimal point (defaults to 10, only used for numbers under 10,000).
+ *
+ * @returns The number formatted as a crammed string.
+ */
+export function cramNumber(num) {
+    const abs = Math.abs(num);
+    if (abs >= TRILLION)
+        return `${_significance(num / TRILLION)}T`;
+    if (abs >= BILLION)
+        return `${_significance(num / BILLION)}B`;
+    if (abs >= MILLION)
+        return `${_significance(num / MILLION)}M`;
+    if (abs >= 10000)
+        return `${_significance(num / 1000)}K`;
+    return truncateNumber(num, 2).toString();
+}
+function _significance(num) {
+    const digits = num >= 100 ? 0 : num >= 10 ? 1 : 2;
+    return truncateNumber(num, digits).toFixed(digits);
+}
 /**
  * Is a number within a specified range?
  *

package/util/string.d.ts

@@ -1,4 +1,10 @@
 import { ImmutableArray } from "./array.js";
+/** Non-breaking space. */
+export declare const NBSP = "\u00A0";
+/** Thin space. */
+export declare const THINSP = "\u2009";
+/** Non-breaking narrow space. */
+export declare const NNBSP = "\u202F";
 /** Is a value a string? */
 export declare const isString: (v: unknown) => v is string;
 /**

package/util/string.js

@@ -3,6 +3,12 @@ import { formatDate } from "./date.js";
 import { isData } from "./data.js";
 import { isArray } from "./array.js";
 import { formatNumber, isBetween } from "./number.js";
+/** Non-breaking space. */
+export const NBSP = "\xA0";
+/** Thin space. */
+export const THINSP = "\u2009";
+/** Non-breaking narrow space. */
+export const NNBSP = "\u202F";
 /** Is a value a string? */
 export const isString = (v) => typeof v === "string";
 /**

package/util/units.d.ts

@@ -1,11 +1,39 @@
+/** Valid information about a unit of measure. */
+export declare type UnitData = {
+    /** Plural name for a unit, e.g. `feet` */
+    readonly plural?: string;
+    /** Type of a unit. */
+    readonly type: UnitType;
+    /** Short suffix for this unit, e.g. `km` */
+    readonly suffix: string;
+    /** All units must specify their 'base' unit, e.g. `meter` for for distance units and `liter` for volume units. */
+    readonly base: number;
+} & {
+    [K in UnitReference]?: number;
+};
+/** Valid system of measurement reference. */
+export declare type UnitType = "percentage" | "angle" | "temperature" | "length" | "speed" | "pace" | "mass" | "time" | "volume";
+/** Valid unit of measurement reference (correspond to units allowed in `Intl.NumberFormat`, but not all). */
+export declare type UnitReference = "percent" | "degree" | "millimeter" | "centimeter" | "meter" | "kilometer" | "mile" | "yard" | "foot" | "inch" | "liter" | "milliliter" | "gallon" | "fluid-ounce" | "gram" | "kilogram" | "pound" | "stone" | "ounce" | "millisecond" | "second" | "minute" | "day" | "hour" | "week" | "month" | "year";
+/** List of units. */
+export declare const UNITS: {
+    [K in UnitReference]: UnitData;
+};
+/** Convert between two units of the same type. */
+export declare function convertUnits(num: number, from: UnitReference, to: UnitReference): number;
 /**
- * Valid distance unit names.
- * - Correspond to units allowed in `Intl.NumberFormat`
+ * Format a number with a given unit of measure, e.g. `12 kg` or `29.5 l`
+ *
+ * @param num The number to format.
+ * @param unit String reference for a unit of measure e.g. `kilometer`
+ * @param maxPrecision Number of decimal places to round the number to e.g. `2`
  */
-export declare type Unit = "millimeter" | "centimeter" | "meter" | "kilometer" | "mile" | "yard" | "foot" | "inch";
-/** Convert between two distance units. */
-export declare const convertUnits: (num: number, from: Unit, to: Unit) => number;
-/** Detect which type of distance unit has been typed, e.g. mile or kilometer. */
-export declare const detectUnit: (str: string, defaultUnit: Unit) => Unit | false;
-/** Format a distance. */
-export declare const formatUnit: (num: number, unit?: Unit, precision?: number) => string;
+export declare const formatUnits: (num: number, unit: UnitReference, maxPrecision?: number | undefined, minPrecision?: number | undefined) => string;
+/**
+ * Format a number with a given unit of measure, e.g. `12 kilograms` or `29.5 liters` or `1 degree`
+ *
+ * @param num The number to format.
+ * @param unit String reference for a unit of measure e.g. `kilometer`
+ * @param maxPrecision Number of decimal places to round the number to e.g. `2`
+ */
+export declare const formatFullUnits: (num: number, unit: UnitReference, maxPrecision?: number | undefined, minPrecision?: number | undefined) => string;

package/util/units.js

@@ -1,92 +1,63 @@
-import { formatNumber } from "./number.js";
-/** Conversion table for distance unit. */
-const unitsData = {
-    millimeter: {
-        meter: 0.001,
-        regex: /(\d|\b)(millimeters?|millimetres?|mms?)\b/i,
-        short: "mm",
-    },
-    centimeter: {
-        meter: 0.01,
-        regex: /(\d|\b)(centimeters?|centimetres?|cms?)\b/i,
-        short: "cm",
-    },
-    meter: {
-        meter: 1,
-        centimeter: 100,
-        millimeter: 1000,
-        regex: /(\d|\b)(metres?|meters?|m)\b/i,
-        short: "m",
-    },
-    kilometer: {
-        meter: 1000,
-        centimeter: 100000,
-        millimeter: 1000000,
-        regex: /(\d|\b)(kilometres?|kilometers?|kms?|k)\b/i,
-        short: "km",
-        precision: 2,
-        m: "mile", // e.g. `10m` means miles.
-    },
-    mile: {
-        meter: 1609.344,
-        yard: 1760,
-        foot: 5280,
-        inch: 63360,
-        regex: /(\d|\b)(miles?|mi|m)\b/i,
-        short: "mi",
-        precision: 2,
-        m: "mile", // e.g. `10m` means miles.
-    },
-    yard: {
-        meter: 0.9144,
-        inch: 36,
-        foot: 3,
-        regex: /(\d|\b)(yards?|yds?|y)\b/i,
-        short: "yd",
-    },
-    foot: {
-        meter: 0.3048,
-        inch: 12,
-        regex: /(\d|\b)(feets?|foots?|fts?|f)\b/i,
-        short: "ft",
-    },
-    inch: {
-        meter: 0.0254,
-        regex: /(\d|\b)(inches|inch|in)\b/i,
-        short: "in",
-    },
+import { AssertionError } from "../error/index.js";
+import { DAY, HOUR, MINUTE, MONTH, SECOND, WEEK, YEAR } from "./date.js";
+import { formatFullQuantity, formatQuantity } from "./number.js";
+import { NNBSP } from "./string.js";
+/** List of units. */
+export const UNITS = {
+    "percent": { type: "percentage", base: 1, suffix: "%" },
+    "degree": { type: "angle", base: 1, suffix: "deg" },
+    "millimeter": { type: "length", base: 0.001, suffix: "mm" },
+    "centimeter": { type: "length", base: 0.01, suffix: "cm" },
+    "meter": { type: "length", base: 1, centimeter: 100, millimeter: 1000, suffix: "m" },
+    "kilometer": { type: "length", base: 1000, centimeter: 100000, millimeter: 1000000, suffix: "km" },
+    "inch": { type: "length", base: 0.0254, suffix: "in" },
+    "foot": { type: "length", base: 0.3048, inch: 12, suffix: "ft", plural: "feet" },
+    "yard": { type: "length", base: 0.9144, inch: 36, foot: 3, suffix: "yd" },
+    "mile": { type: "length", base: 1609.344, yard: 1760, foot: 5280, inch: 63360, suffix: "mi" },
+    "milliliter": { type: "volume", base: 1, suffix: "ml" },
+    "liter": { type: "volume", base: 1000, suffix: "l" },
+    "fluid-ounce": { type: "volume", base: 29.5735295625, gallon: 128, suffix: `fl${NNBSP}oz` },
+    "gallon": { type: "volume", base: 3785.411784, suffix: "gal" },
+    "gram": { type: "mass", base: 1, suffix: "g" },
+    "kilogram": { type: "mass", base: 1000, suffix: "kg" },
+    "ounce": { type: "mass", base: 28.349523125, pound: 0.0625, suffix: "oz" },
+    "pound": { type: "mass", base: 453.59237, ounce: 16, suffix: "lb" },
+    "stone": { type: "mass", base: 6350.29318, pound: 14, ounce: 224, suffix: "st", plural: "stone" },
+    "millisecond": { type: "time", base: 1, suffix: "ms" },
+    "second": { type: "time", base: SECOND, suffix: "s" },
+    "minute": { type: "time", base: MINUTE, suffix: "m" },
+    "hour": { type: "time", base: HOUR, suffix: "h" },
+    "day": { type: "time", base: DAY, suffix: "d" },
+    "week": { type: "time", base: WEEK, suffix: "w" },
+    "month": { type: "time", base: MONTH, suffix: "m" },
+    "year": { type: "time", base: YEAR, suffix: "y" },
 };
-/** Convert between two distance units. */
-export const convertUnits = (num, from, to) => {
+/** Convert between two units of the same type. */
+export function convertUnits(num, from, to) {
     if (from === to)
         return num;
-    const d = unitsData[from];
-    const t = d[to];
-    if (t)
-        return num * t;
-    return (num * d.meter) / unitsData[to].meter;
-};
-/** Detect which type of distance unit has been typed, e.g. mile or kilometer. */
-export const detectUnit = (str, defaultUnit) => {
-    if (str.match(/^[0-9.,\s]+$/))
-        return defaultUnit; // Purely numeric number uses default unit.
-    if (str.match(unitsData.kilometer.regex))
-        return "kilometer";
-    if (str.match(unitsData.centimeter.regex))
-        return "centimeter";
-    if (str.match(/(\d|\b)m\b/i))
-        return unitsData[defaultUnit].m || "meter"; // e.g. `10m` could mean meter or mile.
-    if (str.match(unitsData.meter.regex))
-        return "meter";
-    if (str.match(unitsData.mile.regex))
-        return "mile";
-    if (str.match(unitsData.yard.regex))
-        return "yard";
-    if (str.match(unitsData.foot.regex))
-        return "foot";
-    if (str.match(unitsData.inch.regex))
-        return "inch";
-    return false; // Cannot figure out unit.
-};
-/** Format a distance. */
-export const formatUnit = (num, unit = "meter", precision = unitsData[unit].precision || 0) => `${formatNumber(num, precision)} ${unitsData[unit].short}`;
+    const fromData = UNITS[from];
+    const exact = fromData[to]; // Get the exact conversion if possible (e.g. 5280 feet in a mile).
+    if (typeof exact === "number")
+        return num * exact;
+    const toData = UNITS[to];
+    if (fromData.type !== toData.type)
+        throw new AssertionError(`Target unit must be ${fromData.type}`, toData.type);
+    return (num * fromData.base) / toData.base;
+}
+/**
+ * Format a number with a given unit of measure, e.g. `12 kg` or `29.5 l`
+ *
+ * @param num The number to format.
+ * @param unit String reference for a unit of measure e.g. `kilometer`
+ * @param maxPrecision Number of decimal places to round the number to e.g. `2`
+ */
+export const formatUnits = (num, unit, maxPrecision, minPrecision) => formatQuantity(num, UNITS[unit].suffix, maxPrecision, minPrecision);
+/**
+ * Format a number with a given unit of measure, e.g. `12 kilograms` or `29.5 liters` or `1 degree`
+ *
+ * @param num The number to format.
+ * @param unit String reference for a unit of measure e.g. `kilometer`
+ * @param maxPrecision Number of decimal places to round the number to e.g. `2`
+ */
+export const formatFullUnits = (num, unit, maxPrecision, minPrecision) => formatFullQuantity(num, unit, UNITS[unit].plural || `${unit}s`, maxPrecision, minPrecision);

package/db/Write.d.ts

@@ -1,50 +0,0 @@
-import { PropUpdates, Update } from "../update/index.js";
-import { ImmutableArray, Data, Transformable, Key, Nullish } from "../util/index.js";
-import type { Database, DatabaseDocument } from "./Database.js";
-/** Represent a write made to a database. */
-export declare abstract class Write implements Transformable<Database, void | PromiseLike<void>> {
-    abstract transform(db: Database): void | PromiseLike<void>;
-}
-/**
- * Represent a list of writes made to a database.
- * - Sets of writes are predictable and repeatable, so unpredictable operations like `create()` and query operations are not supported.
- * - Every write must be applied to a specific database document in a specific collection and are applied in the specified order.
- */
-export declare class Writes extends Write {
-    readonly writes: ImmutableArray<Write>;
-    constructor(...writes: Write[]);
-    transform(db: Database): Promise<void>;
-}
-/** Represent a write made to a single document in a database. */
-export declare abstract class DocumentWrite<T extends Data> extends Write {
-    readonly collection: string;
-    readonly id: string;
-    constructor({ collection, id }: DatabaseDocument<T>);
-}
-/** Represent a set operation made to a single document in a database. */
-export declare class DocumentSet<T extends Data> extends DocumentWrite<T> {
-    readonly data: T;
-    constructor(ref: DatabaseDocument<T>, data: T);
-    transform(db: Database): Promise<void>;
-    /** Set one of the props on this set operation to a different value. */
-    set<K extends Key<T>>(key: Nullish<K>, value: T[K]): this;
-}
-/** Represent an update operation made to a single document in a database. */
-export declare class DocumentUpdate<T extends Data> extends DocumentWrite<T> {
-    readonly updates: PropUpdates<T>;
-    constructor(ref: DatabaseDocument<T>, updates: PropUpdates<T>);
-    transform(db: Database): Promise<void>;
-    /** update one of the props on this set operation to a different value. */
-    update<K extends Key<T>>(key: Nullish<K>, value: T[K] | Update<T[K]>): this;
-}
-/** Represent a delete operation made to a single document in a database. */
-export declare class DocumentDelete<T extends Data> extends DocumentWrite<T> {
-    transform(db: Database): Promise<void>;
-}
-/** Set of hydrations for all change classes. */
-export declare const WRITE_HYDRATIONS: {
-    Writes: typeof Writes;
-    DocumentSet: typeof DocumentSet;
-    DocumentUpdate: typeof DocumentUpdate;
-    DocumentDelete: typeof DocumentDelete;
-};

package/db/Write.js

@@ -1,73 +0,0 @@
-import { transform, isNullish } from "../util/index.js";
-/** Represent a write made to a database. */
-export class Write {
-}
-/**
- * Represent a list of writes made to a database.
- * - Sets of writes are predictable and repeatable, so unpredictable operations like `create()` and query operations are not supported.
- * - Every write must be applied to a specific database document in a specific collection and are applied in the specified order.
- */
-export class Writes extends Write {
-    constructor(...writes) {
-        super();
-        this.writes = writes;
-    }
-    async transform(db) {
-        for (const writes of this.writes)
-            await transform(db, writes);
-    }
-}
-/** Represent a write made to a single document in a database. */
-export class DocumentWrite extends Write {
-    constructor({ collection, id }) {
-        super();
-        this.collection = collection;
-        this.id = id;
-    }
-}
-/** Represent a set operation made to a single document in a database. */
-export class DocumentSet extends DocumentWrite {
-    constructor(ref, data) {
-        super(ref);
-        this.data = data;
-    }
-    async transform(db) {
-        await db.doc(this.collection, this.id).set(this.data);
-    }
-    /** Set one of the props on this set operation to a different value. */
-    set(key, value) {
-        if (isNullish(key))
-            return this;
-        return { __proto__: Object.getPrototypeOf(this), ...this, data: { ...this.data, [key]: value } };
-    }
-}
-/** Represent an update operation made to a single document in a database. */
-export class DocumentUpdate extends DocumentWrite {
-    constructor(ref, updates) {
-        super(ref);
-        this.updates = updates;
-    }
-    async transform(db) {
-        await db.doc(this.collection, this.id).update(this.updates);
-    }
-    /** update one of the props on this set operation to a different value. */
-    update(key, value) {
-        if (isNullish(key))
-            return this;
-        return { __proto__: Object.getPrototypeOf(this), ...this, updates: { ...this.updates, [key]: value } };
-    }
-}
-/** Represent a delete operation made to a single document in a database. */
-export class DocumentDelete extends DocumentWrite {
-    async transform(db) {
-        await db.doc(this.collection, this.id).delete();
-    }
-}
-/** Set of hydrations for all change classes. */
-export const WRITE_HYDRATIONS = {
-    Writes,
-    DocumentSet,
-    DocumentUpdate,
-    DocumentDelete,
-};
-WRITE_HYDRATIONS;