shelving 1.40.0 → 1.44.0

package/update/DataUpdate.js

@@ -10,7 +10,7 @@ export class DataUpdate extends Update {
         return transformProps(existing, this.updates);
     }
     /** Return a new object with the specified additional transform for a prop. */
-    update(key, value) {
+    with(key, value) {
         if (isNullish(key))
             return this;
         return { __proto__: Object.getPrototypeOf(this), ...this, updates: { ...this.updates, [key]: value } };

package/update/ObjectUpdate.d.ts

@@ -5,17 +5,17 @@ export declare type EntryUpdates<T> = ImmutableObject<T | Update<T>>;
 /** Update that can be applied to a map-like object to add/remove/update its entries. */
 export declare class ObjectUpdate<T> extends Update<ImmutableObject<T>> implements Iterable<Entry<T | Update<T> | undefined>> {
     /** Return an object update with a specific entry marked for update. */
-    static update<X>(key: string | undefined | null, value: X | Update<X>): ObjectUpdate<X>;
+    static with<X>(key: string | undefined | null, value: X | Update<X>): ObjectUpdate<X>;
     /** Return an object update with a specific entry marked for deletion. */
-    static delete<X>(key: string | undefined | null): ObjectUpdate<X>;
+    static without<X>(key: string | undefined | null): ObjectUpdate<X>;
     readonly updates: EntryUpdates<T>;
     readonly deletes: ImmutableArray<string>;
     constructor(updates?: EntryUpdates<T>, deletes?: ImmutableArray<string>);
     transform(existing: unknown): ImmutableObject<T>;
     /** Return an object update with a specific entry marked for update. */
-    update(key: Nullish<string>, value: T | Update<T>): this;
+    with(key: Nullish<string>, value: T | Update<T>): this;
     /** Return an object update with a specific entry marked for deletion. */
-    delete(key: Nullish<string>): this;
+    without(key: Nullish<string>): this;
     /**
      * Iterate over the changes in this object.
      * - Updates are yielded first, then deletes.

package/update/ObjectUpdate.js

@@ -8,11 +8,11 @@ export class ObjectUpdate extends Update {
         this.deletes = deletes;
     }
     /** Return an object update with a specific entry marked for update. */
-    static update(key, value) {
+    static with(key, value) {
         return new ObjectUpdate(isNullish(key) ? {} : { [key]: value });
     }
     /** Return an object update with a specific entry marked for deletion. */
-    static delete(key) {
+    static without(key) {
         return new ObjectUpdate({}, isNullish(key) ? [] : [key]);
     }
     transform(existing) {
@@ -20,13 +20,13 @@ export class ObjectUpdate extends Update {
         return transformEntries(existingObject, this.updates, this.deletes);
     }
     /** Return an object update with a specific entry marked for update. */
-    update(key, value) {
+    with(key, value) {
         if (isNullish(key))
             return this;
         return { __proto__: Object.getPrototypeOf(this), ...this, sets: { ...this.updates, [key]: value } };
     }
     /** Return an object update with a specific entry marked for deletion. */
-    delete(key) {
+    without(key) {
         if (isNullish(key))
             return this;
         return { __proto__: Object.getPrototypeOf(this), ...this, deletes: [...this.deletes, key] };

package/util/async.d.ts

@@ -1,6 +1,7 @@
+import type { ImmutableArray } from "./array.js";
+import type { Arguments, Dispatcher } from "./function.js";
 import { DONE } from "./constants.js";
 import { Handler } from "./error.js";
-import type { Arguments, Dispatcher } from "./function.js";
 /**
  * Throw the value if it's an async (promised) value.
  * @returns Synchronous (not promised) value.
@@ -9,9 +10,32 @@ import type { Arguments, Dispatcher } from "./function.js";
 export declare function throwAsync<T>(asyncValue: T | PromiseLike<T>): T;
 /** Is a value an async (promised) value. */
 export declare const isAsync: <T>(v: T | PromiseLike<T>) => v is PromiseLike<T>;
-/** Call a function with a set of values *BUT* if the first value is asynchronous wait for it to resolve first before calling the function. */
-export declare const callAsync: <I, O, A extends Arguments = []>(callback: (v: I, ...a: A) => O, value: I | PromiseLike<I>, ...args: A) => O | PromiseLike<O>;
-export declare const _awaitCallAsync: <I, O, A extends Arguments>(callback: (v: I, ...a: A) => O, value: PromiseLike<I>, args: A) => Promise<O>;
+/**
+ * Call a callback with an item.
+ * - If neither `callback` or `item` are async then the value returned will be synchronous.
+ *
+ * @param callback The sync or async function to call.
+ * @param item The first argument for `callback` (if this value is async it will be awaited before `callback` is called).
+ * @param ...args Additional arguments for `callback`
+ */
+export declare const callAsync: <I, O, A extends Arguments = []>(callback: (v: I, ...a: A) => O | PromiseLike<O>, item: I | PromiseLike<I>, ...args: A) => O | PromiseLike<O>;
+export declare const _awaitCallAsync: <I, O, A extends Arguments>(callback: (v: I, ...a: A) => O | PromiseLike<O>, item: PromiseLike<I>, args: A) => Promise<O>;
+/**
+ * Call a callback for a set of items in series.
+ *
+ * @param callback The sync or async function to call for each item.
+ * @param items The set of first arguments for `callback` (if this value is async it will be awaited before `callback` is called).
+ * @param ...args Additional arguments for `callback`
+ */
+export declare function callAsyncSeries<I, O, A extends Arguments = []>(callback: (item: I, ...a: A) => O | PromiseLike<O>, items: Iterable<I | PromiseLike<I>>, ...args: A): Promise<ImmutableArray<O>>;
+/**
+ * Call a callback for a set of items in parallel.
+ *
+ * @param callback The sync or async function to call for each item.
+ * @param items The set of first arguments for `callback` (if this value is async it will be awaited before `callback` is called).
+ * @param ...args Additional arguments for `callback`
+ */
+export declare function callAsyncParallel<I, O, A extends Arguments = []>(callback: (item: I, ...a: A) => O | PromiseLike<O>, items: Iterable<I | PromiseLike<I>>, ...args: A): Promise<ImmutableArray<O>>;
 /** Type of `Promise` with its `resolve()` and `reject()` methods exposed publicly. */
 export declare class Deferred<T> extends Promise<T> {
     static get [Symbol.species](): PromiseConstructor;

package/util/async.js

@@ -11,9 +11,42 @@ export function throwAsync(asyncValue) {
 }
 /** Is a value an async (promised) value. */
 export const isAsync = (v) => typeof v === "object" && v !== null && typeof v.then === "function";
-/** Call a function with a set of values *BUT* if the first value is asynchronous wait for it to resolve first before calling the function. */
-export const callAsync = (callback, value, ...args) => (isAsync(value) ? _awaitCallAsync(callback, value, args) : callback(value, ...args));
-export const _awaitCallAsync = async (callback, value, args) => callback(await value, ...args);
+/**
+ * Call a callback with an item.
+ * - If neither `callback` or `item` are async then the value returned will be synchronous.
+ *
+ * @param callback The sync or async function to call.
+ * @param item The first argument for `callback` (if this value is async it will be awaited before `callback` is called).
+ * @param ...args Additional arguments for `callback`
+ */
+export const callAsync = (callback, item, ...args) => isAsync(item) ? _awaitCallAsync(callback, item, args) : callback(item, ...args);
+export const _awaitCallAsync = async (callback, item, args) => callback(await item, ...args);
+/**
+ * Call a callback for a set of items in series.
+ *
+ * @param callback The sync or async function to call for each item.
+ * @param items The set of first arguments for `callback` (if this value is async it will be awaited before `callback` is called).
+ * @param ...args Additional arguments for `callback`
+ */
+export async function callAsyncSeries(callback, items, ...args) {
+    const outputs = [];
+    for (const item of items)
+        outputs.push(await callback(await item, ...args));
+    return outputs;
+}
+/**
+ * Call a callback for a set of items in parallel.
+ *
+ * @param callback The sync or async function to call for each item.
+ * @param items The set of first arguments for `callback` (if this value is async it will be awaited before `callback` is called).
+ * @param ...args Additional arguments for `callback`
+ */
+export async function callAsyncParallel(callback, items, ...args) {
+    const outputs = [];
+    for (const item of await Promise.all(items))
+        outputs.push(callback(item, ...args));
+    return Promise.all(outputs);
+}
 // Internal way for us to save `resolve()` and `reject()` from a new Promise used by `Deferred` and `ExtendablePromise`
 let resolve; // eslint-disable-line @typescript-eslint/no-explicit-any
 let reject;

package/util/date.d.ts

@@ -1,3 +1,5 @@
+/** One second in millseconds. */
+export declare const SECOND = 1000;
 /** One minute in millseconds. */
 export declare const MINUTE: number;
 /** One hour in millseconds. */
@@ -6,6 +8,8 @@ export declare const HOUR: number;
 export declare const DAY: number;
 /** One week in millseconds. */
 export declare const WEEK: number;
+/** One month in millseconds. */
+export declare const MONTH: number;
 /** One year in millseconds. */
 export declare const YEAR: number;
 /** Is a value a date? */
@@ -53,46 +57,73 @@ export declare function getMonday(target?: PossibleDate): Date;
 export declare function addDays(change: number, target?: PossibleDate): Date;
 /** Return a new date that increase or decreases the number of hours based on an input date. */
 export declare function addHours(change: number, target?: PossibleDate): Date;
+/**
+ * Get the duration (in milliseconds) between two dates.
+ *
+ * @param target The date when the thing will happen or did happen.
+ * @param current Today's date (or a different date to measure from).
+ */
+export declare const getDuration: (target?: PossibleDate | undefined, current?: PossibleDate | undefined) => number;
 /** Count the number of seconds until a date. */
-export declare const secondsUntil: (target: PossibleDate, current?: PossibleDate | undefined) => number;
+export declare const getSecondsUntil: (target: PossibleDate, current?: PossibleDate | undefined) => number;
 /** Count the number of days ago a date was. */
-export declare const secondsAgo: (target: PossibleDate, current?: PossibleDate | undefined) => number;
+export declare const getSecondsAgo: (target: PossibleDate, current?: PossibleDate | undefined) => number;
 /** Count the number of days until a date. */
-export declare const daysUntil: (target: PossibleDate, current?: PossibleDate | undefined) => number;
+export declare const getDaysUntil: (target: PossibleDate, current?: PossibleDate | undefined) => number;
 /** Count the number of days ago a date was. */
-export declare const daysAgo: (target: PossibleDate, current?: PossibleDate | undefined) => number;
+export declare const getDaysAgo: (target: PossibleDate, current?: PossibleDate | undefined) => number;
 /** Count the number of weeks until a date. */
-export declare const weeksUntil: (target: PossibleDate, current?: PossibleDate | undefined) => number;
+export declare const getWeeksUntil: (target: PossibleDate, current?: PossibleDate | undefined) => number;
 /** Count the number of weeks ago a date was. */
-export declare const weeksAgo: (target: PossibleDate, current?: PossibleDate | undefined) => number;
-/** Return a friendly gap between two dates, e.g. `in 10 days` or `16 hours ago` or `yesterday` */
-export declare function formatWhen(target: PossibleDate, current?: PossibleDate): string;
+export declare const getWeeksAgo: (target: PossibleDate, current?: PossibleDate | undefined) => number;
+/** Format a full description of a duration of time using the most reasonable units e.g. `5 years` or `1 week` or `4 minutes` or `12 milliseconds`. */
+export declare function formatFullDuration(ms: number): string;
+/** Format a description of a duration of time using the most reasonable units e.g. `5y` or `4m` or `12ms`. */
+export declare function formatDuration(ms: number): string;
 /**
- * Return when a date happened, e.g. `10 days` or `2 hours` or `-1 week`
- * @param target The date when the thing will happen.
+ * Return full description of the gap between two dates, e.g. `in 10 days` or `2 hours ago`
+ *
+ * @param target The date when the thing will happen or did happen.
  * @param current Today's date (or a different date to measure from).
  */
-export declare function formatUntil(target: PossibleDate, current?: PossibleDate): string;
+export declare function formatFullWhen(target: PossibleDate, current?: PossibleDate): string;
 /**
- * Return a compact version of when a date happened, e.g. `10d` or `2h` or `-1w`
+ * Return full description of when a date happened, e.g. `10 days` or `2 hours` or `-1 week`
+ *
  * @param target The date when the thing will happen.
  * @param current Today's date (or a different date to measure from).
  */
-export declare function formatShortUntil(target: PossibleDate, current?: PossibleDate): string;
+export declare const formatFullUntil: (target: PossibleDate, current?: PossibleDate | undefined) => string;
 /**
- * Return when a date will happen, e.g. `10 days` or `2 hours` or `-1 week`
+ * Return full description of when a date will happen, e.g. `10 days` or `2 hours` or `-1 week`
+ *
  * @param target The date when the thing happened.
  * @param current Today's date (or a different date to measure from).
  */
-export declare function formatAgo(target: PossibleDate, current?: PossibleDate): string;
+export declare const formatFullAgo: (target: PossibleDate, current?: PossibleDate | undefined) => string;
 /**
- * Return a compact version of when a date will happen, e.g. `10d` or `2h` or `-1w`
+ * Compact how long until a date happens, e.g. `in 10d` or `2h ago` or `in 1w`
+ *
+ * @param target The date when the thing will happen.
+ * @param current Today's date (or a different date to measure from).
+ */
+export declare function formatWhen(target: PossibleDate, current?: PossibleDate): string;
+/**
+ * Return short description of when a date happened, e.g. `10d` or `2h` or `-1w`
+ *
+ * @param target The date when the thing will happen.
+ * @param current Today's date (or a different date to measure from).
+ */
+export declare const formatUntil: (target: PossibleDate, current?: PossibleDate | undefined) => string;
+/**
+ * Return short description of when a date will happen, e.g. `10d` or `2h` or `-1w`
+ *
  * @param target The date when the thing happened.
  * @param current Today's date (or a different date to measure from).
  */
-export declare function formatShortAgo(target: PossibleDate, current?: PossibleDate): string;
+export declare const formatAgo: (target: PossibleDate, current?: PossibleDate | undefined) => string;
 /** Format a date in the browser locale. */
-export declare function formatDate(date: PossibleDate, options?: Intl.DateTimeFormatOptions): string;
+export declare const formatDate: (date: PossibleDate) => string;
 /** Is a date in the past? */
 export declare const isPast: (target: PossibleDate, current?: PossibleDate | undefined) => boolean;
 /** Is a date in the future? */

package/util/date.js

@@ -1,15 +1,19 @@
 import { AssertionError } from "../error/index.js";
-import { formatNumber } from "./number.js";
+import { formatFullQuantity, formatQuantity } from "./number.js";
+/** One second in millseconds. */
+export const SECOND = 1000;
 /** One minute in millseconds. */
-export const MINUTE = 60 * 1000;
+export const MINUTE = 60 * SECOND;
 /** One hour in millseconds. */
-export const HOUR = MINUTE * 60;
+export const HOUR = 60 * MINUTE;
 /** One day in millseconds. */
-export const DAY = HOUR * 24;
+export const DAY = 24 * HOUR;
 /** One week in millseconds. */
-export const WEEK = DAY * 7;
+export const WEEK = 7 * DAY;
+/** One month in millseconds. */
+export const MONTH = 30 * DAY;
 /** One year in millseconds. */
-export const YEAR = DAY * 365;
+export const YEAR = 365 * DAY;
 /** Is a value a date? */
 export const isDate = (v) => v instanceof Date;
 /**
@@ -101,111 +105,114 @@ export function addHours(change, target) {
     date.setHours(date.getHours() + change);
     return date;
 }
+/**
+ * Get the duration (in milliseconds) between two dates.
+ *
+ * @param target The date when the thing will happen or did happen.
+ * @param current Today's date (or a different date to measure from).
+ */
+export const getDuration = (target, current) => getDate(target).getTime() - getDate(current).getTime();
 /** Count the number of seconds until a date. */
-export const secondsUntil = (target, current) => Math.round(getDate(target).getTime() - getDate(current).getTime()) / 1000;
+export const getSecondsUntil = (target, current) => getDuration(target, current) / 1000;
 /** Count the number of days ago a date was. */
-export const secondsAgo = (target, current) => 0 - secondsUntil(target, current);
+export const getSecondsAgo = (target, current) => 0 - getSecondsUntil(target, current);
 /** Count the number of days until a date. */
-export const daysUntil = (target, current) => Math.round((getMidnight(target).getTime() - getMidnight(current).getTime()) / 86400000);
+export const getDaysUntil = (target, current) => Math.round((getMidnight(target).getTime() - getMidnight(current).getTime()) / 86400000);
 /** Count the number of days ago a date was. */
-export const daysAgo = (target, current) => 0 - daysUntil(target, current);
+export const getDaysAgo = (target, current) => 0 - getDaysUntil(target, current);
 /** Count the number of weeks until a date. */
-export const weeksUntil = (target, current) => Math.floor(daysUntil(target, current) / 7);
+export const getWeeksUntil = (target, current) => Math.floor(getDaysUntil(target, current) / 7);
 /** Count the number of weeks ago a date was. */
-export const weeksAgo = (target, current) => 0 - weeksUntil(target, current);
-/**
- * Get information about the difference between two dates.
- * - Used by `formatWhen()` and `formatAgo()` etc
- * @returns Tuple in `[amount, units]` format, e.g. `[3, "days"]` or `[-16, "hours"]` or `[1, "week"]`
- */
-function diffDates(target, current) {
-    const seconds = (getDate(target).getTime() - getDate(current).getTime()) / 1000;
-    const abs = Math.abs(seconds);
-    // Up to 99 seconds, e.g. '22 seconds ago'
-    if (abs < 99) {
-        const num = Math.round(seconds);
-        return [num, num === 1 ? "second" : "seconds"];
-    }
-    // Up to one hour  — show minutes, e.g. '18 minutes ago'
-    if (abs < 3600) {
-        const num = Math.round(seconds / 60);
-        return [num, num === 1 ? "minute" : "minutes"];
-    }
-    // Up to 24 hours — show hours, e.g. '23 hours ago'
-    if (abs < 86400) {
-        const num = Math.round(seconds / 3600);
-        return [num, num === 1 ? "hour" : "hours"];
-    }
-    // Up to 2 weeks — show days, e.g. '13 days ago'
-    if (abs < 1209600) {
-        const num = Math.round(seconds / 86400);
-        return [num, num === 1 ? "day" : "days"];
-    }
-    // Up to 2 months — show weeks, e.g. '6 weeks ago'
-    if (abs < 5184000) {
-        const num = Math.round(seconds / 604800);
-        return [num, num === 1 ? "week" : "weeks"];
-    }
-    // Up to 18 months — show months, e.g. '6 months ago'
-    if (abs < 46656000) {
-        const num = Math.round(seconds / 2592000);
-        return [num, num === 1 ? "month" : "months"];
-    }
-    // Above 18 months — show years, e.g. '2 years ago'
-    return [Math.round(seconds / 31536000), "year"];
+export const getWeeksAgo = (target, current) => 0 - getWeeksUntil(target, current);
+/** Format a full description 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) {
+    const abs = Math.abs(ms);
+    if (abs <= 99 * SECOND)
+        return formatFullQuantity(ms, "second", "seconds", 0); // Up to 99 seconds, e.g. '22 seconds ago'
+    if (abs <= HOUR)
+        return formatFullQuantity(ms / MINUTE, "minute", "minutes", 0); // Up to one hour  — show minutes, e.g. '18 minutes ago'
+    if (abs <= DAY)
+        return formatFullQuantity(ms / HOUR, "hour", "hours", 0); // Up to one day — show hours, e.g. '23 hours ago'
+    if (abs <= 2 * WEEK)
+        return formatFullQuantity(ms / DAY, "day", "days", 0); // Up to 2 weeks — show days, e.g. '13 days ago'
+    if (abs <= 10 * WEEK)
+        return formatFullQuantity(ms / WEEK, "week", "weeks", 0); // Up to 2 months — show weeks, e.g. '6 weeks ago'
+    if (abs <= 18 * MONTH)
+        return formatFullQuantity(ms / MONTH, "month", "months", 0); // Up to 18 months — show months, e.g. '6 months ago'
+    return formatFullQuantity(ms / YEAR, "year", "years", 0); // Above 18 months — show years, e.g. '2 years ago'
 }
-/** Return a friendly gap between two dates, e.g. `in 10 days` or `16 hours ago` or `yesterday` */
-export function formatWhen(target, current) {
-    const [amount, unit] = diffDates(target, current);
-    // Special case for rough equality.
-    if (unit === "second" && amount > -30 && amount < 30)
-        return "just now";
-    // Return either `in 22 days` or `1 hour ago`
-    const future = amount >= 0;
-    const abs = Math.abs(amount);
-    const str = formatNumber(abs);
-    return future ? `in ${str} ${unit}` : `${str} ${unit} ago`;
+/** Format a description of a duration of time using the most reasonable units e.g. `5y` or `4m` or `12ms`. */
+export function formatDuration(ms) {
+    const abs = Math.abs(ms);
+    if (abs <= 99 * SECOND)
+        return formatQuantity(ms, "s", 0); // Up to 99 seconds, e.g. '22 seconds ago'
+    if (abs <= HOUR)
+        return formatQuantity(ms / MINUTE, "m", 0); // Up to one hour  — show minutes, e.g. '18 minutes ago'
+    if (abs <= DAY)
+        return formatQuantity(ms / HOUR, "h", 0); // Up to one day — show hours, e.g. '23 hours ago'
+    if (abs <= 2 * WEEK)
+        return formatQuantity(ms / DAY, "d", 0); // Up to 2 weeks — show days, e.g. '13 days ago'
+    if (abs <= 10 * WEEK)
+        return formatQuantity(ms / WEEK, "w", 0); // Up to 2 months — show weeks, e.g. '6 weeks ago'
+    if (abs <= 18 * MONTH)
+        return formatQuantity(ms / MONTH, "m", 0); // Up to 18 months — show months, e.g. '6 months ago'
+    return formatQuantity(ms / YEAR, "y", 0); // Above 18 months — show years, e.g. '2 years ago'
 }
 /**
- * Return when a date happened, e.g. `10 days` or `2 hours` or `-1 week`
- * @param target The date when the thing will happen.
+ * Return full description of the gap between two dates, e.g. `in 10 days` or `2 hours ago`
+ *
+ * @param target The date when the thing will happen or did happen.
  * @param current Today's date (or a different date to measure from).
  */
-export function formatUntil(target, current) {
-    const [amount, units] = diffDates(target, current);
-    return `${formatNumber(amount)} ${units}`;
+export function formatFullWhen(target, current) {
+    const ms = getDuration(target, current);
+    const abs = Math.abs(ms);
+    const duration = formatFullDuration(abs);
+    return abs < 10 * SECOND ? "just now" : ms > 0 ? `in ${duration}` : `${duration} ago`;
 }
 /**
- * Return a compact version of when a date happened, e.g. `10d` or `2h` or `-1w`
+ * Return full description of when a date happened, e.g. `10 days` or `2 hours` or `-1 week`
+ *
  * @param target The date when the thing will happen.
  * @param current Today's date (or a different date to measure from).
  */
-export function formatShortUntil(target, current) {
-    const [amount, units] = diffDates(target, current);
-    return `${formatNumber(amount)}${units.substr(0, 1)}`;
-}
+export const formatFullUntil = (target, current) => formatFullDuration(getDuration(target, current));
 /**
- * Return when a date will happen, e.g. `10 days` or `2 hours` or `-1 week`
+ * Return full description of when a date will happen, e.g. `10 days` or `2 hours` or `-1 week`
+ *
  * @param target The date when the thing happened.
  * @param current Today's date (or a different date to measure from).
  */
-export function formatAgo(target, current) {
-    const [amount, units] = diffDates(current, target);
-    return `${formatNumber(amount)} ${units}`;
+export const formatFullAgo = (target, current) => formatFullDuration(getDuration(current, target));
+/**
+ * Compact how long until a date happens, e.g. `in 10d` or `2h ago` or `in 1w`
+ *
+ * @param target The date when the thing will happen.
+ * @param current Today's date (or a different date to measure from).
+ */
+export function formatWhen(target, current) {
+    const ms = getDuration(target, current);
+    const abs = Math.abs(ms);
+    const duration = formatDuration(abs);
+    return abs < 10 * SECOND ? "just now" : ms > 0 ? `in ${duration}` : `${duration} ago`;
 }
 /**
- * Return a compact version of when a date will happen, e.g. `10d` or `2h` or `-1w`
+ * Return short description of when a date happened, e.g. `10d` or `2h` or `-1w`
+ *
+ * @param target The date when the thing will happen.
+ * @param current Today's date (or a different date to measure from).
+ */
+export const formatUntil = (target, current) => formatDuration(getDuration(target, current));
+/**
+ * Return short description of when a date will happen, e.g. `10d` or `2h` or `-1w`
+ *
  * @param target The date when the thing happened.
  * @param current Today's date (or a different date to measure from).
  */
-export function formatShortAgo(target, current) {
-    const [amount, units] = diffDates(current, target);
-    return `${formatNumber(amount)}${units.substr(0, 1)}`;
-}
+export const formatAgo = (target, current) => formatDuration(getDuration(current, target));
 /** Format a date in the browser locale. */
-export function formatDate(date, options) {
-    return new Intl.DateTimeFormat(undefined, options).format(getDate(date));
-}
+export const formatDate = (date) => _formatter.format(getDate(date));
+const _formatter = new Intl.DateTimeFormat(undefined, {});
 /** Is a date in the past? */
 export const isPast = (target, current) => getDate(target) < getDate(current);
 /** Is a date in the future? */

package/util/number.d.ts

@@ -1,3 +1,6 @@
+export declare const TRILLION = 1000000000000;
+export declare const BILLION = 1000000000;
+export declare const MILLION = 1000000;
 /** Is a value a number? */
 export declare const isNumber: (v: unknown) => v is number;
 /**
@@ -21,25 +24,69 @@ export declare function getNumber(value: unknown): number;
  *
  * @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 declare function roundStep(num: number, step?: number): number;
+export declare const roundStep: (num: number, step?: number) => number;
 /**
  * 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 declare const roundNumber: (num: number, precision?: number) => number;
+/**
+ * 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 declare const roundNumber: (num: number, precision?: number) => string;
+export declare const truncateNumber: (num: number, precision?: number) => number;
 /**
  * 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 declare const formatNumber: (num: number, precision?: number) => string;
+export declare const formatNumber: (num: number, maxPrecision?: number, minPrecision?: number) => string;
+/** Format a number with a short suffix (number and suffix are separated by a non-breaking narrow space). */
+export declare const formatQuantity: (num: number, suffix: string, maxPrecision?: number | undefined, minPrecision?: number | undefined) => string;
+/** Format a number with a longer full-word suffix (number and suffix are separated by a non-breaking space). */
+export declare function formatFullQuantity(num: number, singular: string, plural: string, maxPrecision?: number, minPrecision?: number): string;
+/**
+ * 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 declare function cramNumber(num: number): string;
 /**
  * Is a number within a specified range?
  *