shelving 1.42.0 → 1.45.0

package/db/Database.d.ts

@@ -29,10 +29,10 @@ export declare class Database<V extends Validators<Datas> = Validators<Datas>> {
 }
 /** A documents reference within a specific database. */
 export declare class DatabaseQuery<T extends Data = Data> extends Query<T> implements Observable<Results<T>>, Validatable<Entries<T>>, Iterable<Entry<T>> {
-    readonly provider: Provider;
+    readonly db: Database;
     readonly validator: Validator<T>;
     readonly collection: string;
-    constructor(provider: Provider, validator: Validator<T>, collection: string, filters?: Filters<T>, sorts?: Sorts<T>, limit?: number | null);
+    constructor(db: Database, validator: Validator<T>, collection: string, filters?: Filters<T>, sorts?: Sorts<T>, limit?: number | null);
     /** Reference a document in this query's collection. */
     doc(id: string): DatabaseDocument<T>;
     /**
@@ -114,11 +114,11 @@ export declare class DatabaseQuery<T extends Data = Data> extends Query<T> imple
 export declare function getQueryData<T extends Data>(entries: Entries<T>, ref: DatabaseQuery<T>): Entry<T>;
 /** A document reference within a specific database. */
 export declare class DatabaseDocument<T extends Data = Data> implements Observable<Result<T>>, Validatable<T> {
-    readonly provider: Provider;
+    readonly db: Database;
     readonly validator: Validator<T>;
     readonly collection: string;
     readonly id: string;
-    constructor(provider: Provider, validator: Validator<T>, collection: string, id: string);
+    constructor(db: Database, validator: Validator<T>, collection: string, id: string);
     /** Create a query on this document's collection. */
     query(filters?: Filters<T>, sorts?: Sorts<T>, limit?: number | null): DatabaseQuery<T>;
     /** Get an 'optional' reference to this document (uses a `ModelQuery` with an `id` filter). */

package/db/Database.js

@@ -18,11 +18,11 @@ export class Database {
     }
     /** Create a query on a collection in this model. */
     query(collection, filters, sorts, limit) {
-        return new DatabaseQuery(this.provider, this.validators[collection], collection, filters, sorts, limit);
+        return new DatabaseQuery(this, this.validators[collection], collection, filters, sorts, limit);
     }
     /** Reference a document in a collection in this model. */
     doc(collection, id) {
-        return new DatabaseDocument(this.provider, this.validators[collection], collection, id);
+        return new DatabaseDocument(this, this.validators[collection], collection, id);
     }
     /**
      * Create a new document with a random ID.
@@ -38,15 +38,15 @@ export class Database {
 }
 /** A documents reference within a specific database. */
 export class DatabaseQuery extends Query {
-    constructor(provider, validator, collection, filters, sorts, limit) {
+    constructor(db, validator, collection, filters, sorts, limit) {
         super(filters, sorts, limit);
-        this.provider = provider;
+        this.db = db;
         this.validator = validator;
         this.collection = collection;
     }
     /** Reference a document in this query's collection. */
     doc(id) {
-        return new DatabaseDocument(this.provider, this.validator, this.collection, id);
+        return new DatabaseDocument(this.db, this.validator, this.collection, id);
     }
     /**
      * Create a new document with a random ID.
@@ -56,21 +56,21 @@ export class DatabaseQuery extends Query {
      * @return String ID for the created document (possibly promised).
      */
     add(data) {
-        return this.provider.add(this, data);
+        return this.db.provider.add(this, data);
     }
     /**
      * Get an iterable that yields the results of this entry.
      * @return Map containing the results.
      */
     get entries() {
-        return this.provider.getQuery(this);
+        return this.db.provider.getQuery(this);
     }
     /**
      * Get an iterable that yields the results of this entry.
      * @return Map containing the results.
      */
     get results() {
-        return callAsync(getMap, this.provider.getQuery(this));
+        return callAsync(getMap, this.db.provider.getQuery(this));
     }
     /**
      * Count the number of results of this set of documents.
@@ -84,7 +84,7 @@ export class DatabaseQuery extends Query {
      * @return `true` if a document exists or `false` otherwise (possibly promised).
      */
     get exists() {
-        return callAsync(hasItems, this.provider.getQuery(this.max(1)));
+        return callAsync(hasItems, this.db.provider.getQuery(this.max(1)));
     }
     /**
      * Get an entry for the first document matched by this query or `undefined` if this query has no results.
@@ -93,7 +93,7 @@ export class DatabaseQuery extends Query {
      * @throws RequiredError if there were no results for this query.
      */
     get result() {
-        return callAsync(getFirstItem, this.provider.getQuery(this.max(1)));
+        return callAsync(getFirstItem, this.db.provider.getQuery(this.max(1)));
     }
     /**
      * Get an entry for the first document matched by this query.
@@ -102,7 +102,7 @@ export class DatabaseQuery extends Query {
      * @throws RequiredError if there were no results for this query.
      */
     get data() {
-        return callAsync(getQueryData, this.provider.getQuery(this.max(1)), this);
+        return callAsync(getQueryData, this.db.provider.getQuery(this.max(1)), this);
     }
     /**
      * Subscribe to all matching documents.
@@ -112,7 +112,7 @@ export class DatabaseQuery extends Query {
      * @return Function that ends the subscription.
      */
     subscribe(next) {
-        return this.provider.subscribeQuery(this, new ResultsObserver(typeof next === "function" ? { next } : next));
+        return this.db.provider.subscribeQuery(this, new ResultsObserver(typeof next === "function" ? { next } : next));
     }
     /**
      * Set all matching documents to the same exact value.
@@ -121,7 +121,7 @@ export class DatabaseQuery extends Query {
      * @return Nothing (possibly promised).
      */
     set(data) {
-        return this.provider.setQuery(this, data);
+        return this.db.provider.setQuery(this, data);
     }
     /**
      * Update all matching documents with the same partial value.
@@ -130,14 +130,14 @@ export class DatabaseQuery extends Query {
      * @return Nothing (possibly promised).
      */
     update(updates) {
-        return this.provider.updateQuery(this, updates instanceof Update ? updates : new DataUpdate(updates));
+        return this.db.provider.updateQuery(this, updates instanceof Update ? updates : new DataUpdate(updates));
     }
     /**
      * Delete all matching documents.
      * @return Nothing (possibly promised).
      */
     delete() {
-        return this.provider.deleteQuery(this);
+        return this.db.provider.deleteQuery(this);
     }
     /** Iterate over the resuls (will throw `Promise` if the results are asynchronous). */
     [Symbol.iterator]() {
@@ -175,33 +175,33 @@ export function getQueryData(entries, ref) {
 }
 /** A document reference within a specific database. */
 export class DatabaseDocument {
-    constructor(provider, validator, collection, id) {
-        this.provider = provider;
+    constructor(db, validator, collection, id) {
+        this.db = db;
         this.validator = validator;
         this.collection = collection;
         this.id = id;
     }
     /** Create a query on this document's collection. */
     query(filters, sorts, limit) {
-        return new DatabaseQuery(this.provider, this.validator, this.collection, filters, sorts, limit);
+        return new DatabaseQuery(this.db, this.validator, this.collection, filters, sorts, limit);
     }
     /** Get an 'optional' reference to this document (uses a `ModelQuery` with an `id` filter). */
     get optional() {
-        return new DatabaseQuery(this.provider, this.validator, this.collection, new Filters(new EqualFilter("id", this.id)));
+        return new DatabaseQuery(this.db, this.validator, this.collection, new Filters(new EqualFilter("id", this.id)));
     }
     /**
      * Does this document exist?
      * @return `true` if a document exists or `false` otherwise (possibly promised).
      */
     get exists() {
-        return callAsync(Boolean, this.provider.get(this));
+        return callAsync(Boolean, this.db.provider.get(this));
     }
     /**
      * Get the result of this document.
      * @return Document's data, or `undefined` if the document doesn't exist (possibly promised).
      */
     get result() {
-        return this.provider.get(this);
+        return this.db.provider.get(this);
     }
     /**
      * Get the data of this document.
@@ -211,7 +211,7 @@ export class DatabaseDocument {
      * @throws RequiredError if the document's result was undefined.
      */
     get data() {
-        return callAsync(getDocumentData, this.provider.get(this), this);
+        return callAsync(getDocumentData, this.db.provider.get(this), this);
     }
     /**
      * Subscribe to the result of this document (indefinitely).
@@ -221,19 +221,19 @@ export class DatabaseDocument {
      * @return Function that ends the subscription.
      */
     subscribe(next) {
-        return this.provider.subscribe(this, typeof next === "function" ? { next } : next);
+        return this.db.provider.subscribe(this, typeof next === "function" ? { next } : next);
     }
     /** Set the complete data of this document. */
     set(data) {
-        return this.provider.set(this, data);
+        return this.db.provider.set(this, data);
     }
     /** Update this document. */
     update(updates) {
-        return this.provider.update(this, updates instanceof Update ? updates : new DataUpdate(updates));
+        return this.db.provider.update(this, updates instanceof Update ? updates : new DataUpdate(updates));
     }
     /** Delete this document. */
     delete() {
-        return this.provider.delete(this);
+        return this.db.provider.delete(this);
     }
     /** Validate data for this query reference. */
     validate(unsafeData) {

package/db/Operation.d.ts

@@ -3,6 +3,7 @@ import { ImmutableArray, Nullish, Data, Key } from "../util/index.js";
 import type { Database, DatabaseDocument, DatabaseQuery } from "./Database.js";
 /** Represent a write operation on a database. */
 export declare abstract class Operation {
+    /** Run this operation and return the result operation. */
     abstract run(db: Database): Promise<Operation>;
 }
 /** Represent a list of write operations on a database run in series. */
@@ -22,7 +23,9 @@ export declare class Operations extends Operation {
 /** Represent a add operation made to a collection in a database. */
 export declare class AddOperation<T extends Data> extends Operation {
     /** Create a new add operation on a collection. */
-    static on<X extends Data>({ collection }: DatabaseDocument | DatabaseQuery, data: X): AddOperation<X>;
+    static on<X extends Data>({ collection }: DatabaseDocument<X> | DatabaseQuery<X>, data: X): AddOperation<X>;
+    /** Run a new add operation on a collection and return the result operation. */
+    static run<X extends Data>({ collection, db }: DatabaseDocument<X> | DatabaseQuery<X>, data: X): Promise<SetOperation<X>>;
     readonly collection: string;
     readonly data: T;
     constructor(collection: string, data: T);
@@ -33,7 +36,9 @@ export declare class AddOperation<T extends Data> extends Operation {
 /** Represent a set operation made to a single document in a database. */
 export declare class SetOperation<T extends Data> extends Operation {
     /** Create a new add operation on a collection. */
-    static on<X extends Data>({ collection, id }: DatabaseDocument, data: X): SetOperation<X>;
+    static on<X extends Data>({ collection, id }: DatabaseDocument<X>, data: X): SetOperation<X>;
+    /** Run a new set operation on a collection and return the result operation. */
+    static run<X extends Data>({ collection, id, db }: DatabaseDocument<X>, data: X): Promise<SetOperation<X>>;
     readonly collection: string;
     readonly id: string;
     readonly data: T;
@@ -45,7 +50,9 @@ export declare class SetOperation<T extends Data> extends Operation {
 /** Represent an update operation made to a single document in a database. */
 export declare class UpdateOperation<T extends Data> extends Operation {
     /** Create a new update operation on a document. */
-    static on<X extends Data>({ collection, id }: DatabaseDocument<X>, updates?: PropUpdates<X>): UpdateOperation<X>;
+    static on<X extends Data>({ collection, id }: DatabaseDocument<X>, updates: PropUpdates<X>): UpdateOperation<X>;
+    /** Run a new set operation on a collection and return the result operation. */
+    static run<X extends Data>({ collection, id, db }: DatabaseDocument<X>, updates: PropUpdates<X>): Promise<UpdateOperation<X>>;
     readonly collection: string;
     readonly id: string;
     readonly updates: PropUpdates<T>;
@@ -56,8 +63,10 @@ export declare class UpdateOperation<T extends Data> extends Operation {
 }
 /** Represent a delete operation made to a single document in a database. */
 export declare class DeleteOperation extends Operation {
-    /** Create a new update operation on a document. */
-    static on({ collection, id }: DatabaseDocument): DeleteOperation;
+    /** Create a new delete operation on a document. */
+    static on<X extends Data>({ collection, id }: DatabaseDocument<X>): DeleteOperation;
+    /** Run a new delete operation on a document. */
+    static run<X extends Data>({ collection, id, db }: DatabaseDocument<X>): Promise<DeleteOperation>;
     readonly collection: string;
     readonly id: string;
     constructor(collection: string, id: string);

package/db/Operation.js

@@ -32,6 +32,10 @@ export class AddOperation extends Operation {
     static on({ collection }, data) {
         return new AddOperation(collection, data);
     }
+    /** Run a new add operation on a collection and return the result operation. */
+    static run({ collection, db }, data) {
+        return new AddOperation(collection, data).run(db);
+    }
     async run(db) {
         const id = await db.query(this.collection).add(this.data);
         return new SetOperation(this.collection, id, this.data); // When an add operation is run it returns a set operation so the operation is repeatable.
@@ -55,6 +59,10 @@ export class SetOperation extends Operation {
     static on({ collection, id }, data) {
         return new SetOperation(collection, id, data);
     }
+    /** Run a new set operation on a collection and return the result operation. */
+    static run({ collection, id, db }, data) {
+        return new SetOperation(collection, id, data).run(db);
+    }
     async run(db) {
         await db.doc(this.collection, this.id).set(this.data);
         return this;
@@ -75,9 +83,13 @@ export class UpdateOperation extends Operation {
         this.updates = updates;
     }
     /** Create a new update operation on a document. */
-    static on({ collection, id }, updates = {}) {
+    static on({ collection, id }, updates) {
         return new UpdateOperation(collection, id, updates);
     }
+    /** Run a new set operation on a collection and return the result operation. */
+    static run({ collection, id, db }, updates) {
+        return new UpdateOperation(collection, id, updates).run(db);
+    }
     async run(db) {
         await db.doc(this.collection, this.id).update(this.updates);
         return this;
@@ -96,10 +108,14 @@ export class DeleteOperation extends Operation {
         this.collection = collection;
         this.id = id;
     }
-    /** Create a new update operation on a document. */
+    /** Create a new delete operation on a document. */
     static on({ collection, id }) {
         return new DeleteOperation(collection, id);
     }
+    /** Run a new delete operation on a document. */
+    static run({ collection, id, db }) {
+        return new DeleteOperation(collection, id).run(db);
+    }
     async run(db) {
         await db.doc(this.collection, this.id).delete();
         return this;

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.42.0",
+	"version": "1.45.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -63,14 +63,14 @@
 		"@types/jest": "^27.4.0",
 		"@types/react": "^17.0.38",
 		"@types/react-dom": "^17.0.11",
-		"@typescript-eslint/eslint-plugin": "^5.8.1",
-		"@typescript-eslint/parser": "^5.8.1",
+		"@typescript-eslint/eslint-plugin": "^5.9.0",
+		"@typescript-eslint/parser": "^5.9.0",
 		"eslint": "^8.6.0",
 		"eslint-config-prettier": "^8.3.0",
-		"eslint-plugin-import": "^2.25.3",
+		"eslint-plugin-import": "^2.25.4",
 		"eslint-plugin-prettier": "^4.0.0",
-		"firebase": "^9.6.1",
-		"jest": "^27.4.5",
+		"firebase": "^9.6.2",
+		"jest": "^27.4.7",
 		"jest-ts-webcompat-resolver": "^1.0.0",
 		"prettier": "^2.5.1",
 		"react": "^17.0.2",

package/react/useDocument.js

@@ -30,13 +30,13 @@ export function useAsyncDocument(ref, maxAge = 1000) {
 function getCachedResult(ref) {
     if (!ref)
         return undefined;
-    const provider = findSourceProvider(ref.provider, CacheProvider);
+    const provider = findSourceProvider(ref.db.provider, CacheProvider);
     return provider.isCached(ref) ? provider.cache.get(ref) : NOVALUE;
 }
 /** Effect that subscribes a component to the cache for a reference. */
 function subscribeEffect(ref, maxAge, next, error) {
     if (ref) {
-        const provider = findSourceProvider(ref.provider, CacheProvider);
+        const provider = findSourceProvider(ref.db.provider, CacheProvider);
         const stopCache = provider.cache.subscribe(ref, { next, error });
         if (maxAge === true) {
             // If `maxAge` is true subscribe to the source for as long as this component is attached.

package/react/useQuery.js

@@ -30,18 +30,18 @@ export function useAsyncQuery(ref, maxAge = 1000) {
 function getCachedResults(ref) {
     if (!ref)
         return undefined;
-    const provider = findSourceProvider(ref.provider, CacheProvider);
+    const provider = findSourceProvider(ref.db.provider, CacheProvider);
     return provider.isCached(ref) ? getMap(provider.cache.getQuery(ref)) : NOVALUE;
 }
 /** Effect that subscribes a component to the cache for a reference. */
 function subscribeEffect(ref, maxAge, next, error) {
     if (ref) {
-        const provider = findSourceProvider(ref.provider, CacheProvider);
+        const provider = findSourceProvider(ref.db.provider, CacheProvider);
         const observer = new ResultsObserver({ next, error });
         const stopCache = provider.cache.subscribeQuery(ref, observer);
         if (maxAge === true) {
             // If `maxAge` is true subscribe to the source for as long as this component is attached.
-            const stopSource = ref.provider.subscribeQuery(ref, observer);
+            const stopSource = ref.db.provider.subscribeQuery(ref, observer);
             return () => {
                 stopCache();
                 stopSource();

package/update/DataUpdate.d.ts

@@ -12,10 +12,12 @@ export declare type PropUpdates<T extends Data> = {
 };
 /** Update that can be applied to a data object to update its props. */
 export declare class DataUpdate<T extends Data> extends Update<T> implements Iterable<Prop<PropUpdates<T>>>, Transformable<T, T> {
+    /** Return a data update with a specific prop marked for update. */
+    static with<X extends Data, K extends Key<X>>(key: Nullish<K>, value: X[K] | Update<X[K]>): DataUpdate<X>;
     readonly updates: PropUpdates<T>;
     constructor(props: PropUpdates<T>);
     transform(existing: T): T;
-    /** Return a new object with the specified additional transform for a prop. */
+    /** Return a data update with a specific prop marked for update. */
     with<K extends Key<T>>(key: Nullish<K>, value: T[K] | Update<T[K]>): this;
     /** Iterate over the transforms in this object. */
     [Symbol.iterator](): Iterator<Prop<PropUpdates<T>>, void>;

package/update/DataUpdate.js

@@ -6,10 +6,14 @@ export class DataUpdate extends Update {
         super();
         this.updates = props;
     }
+    /** Return a data update with a specific prop marked for update. */
+    static with(key, value) {
+        return new DataUpdate(!isNullish(key) ? { [key]: value } : {});
+    }
     transform(existing) {
         return transformProps(existing, this.updates);
     }
-    /** Return a new object with the specified additional transform for a prop. */
+    /** Return a data update with a specific prop marked for update. */
     with(key, value) {
         if (isNullish(key))
             return this;

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?
  *

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" | "milligram" | "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,64 @@
-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" },
+    "milligram": { type: "mass", base: 0.001, suffix: "mg" },
+    "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);