shelving 1.48.1 → 1.49.0

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.48.1",
+	"version": "1.49.0",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",

package/util/date.d.ts

@@ -1,17 +1,3 @@
-/** One second in millseconds. */
-export declare const SECOND = 1000;
-/** One minute in millseconds. */
-export declare const MINUTE: number;
-/** One hour in millseconds. */
-export declare const HOUR: number;
-/** One day in millseconds. */
-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? */
 export declare const isDate: (v: unknown) => v is Date;
 /** Value that can possibly be converted to a `Date` instance. */
@@ -77,9 +63,9 @@ export declare const getWeeksUntil: (target: PossibleDate, current?: PossibleDat
 /** Count the number of weeks ago a date was. */
 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;
+export declare const formatFullDuration: (ms: number, maxPrecision?: number | undefined, minPrecision?: number | undefined) => 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;
+export declare const formatDuration: (ms: number, maxPrecision?: number | undefined, minPrecision?: number | undefined) => string;
 /**
  * Return full description of the gap between two dates, e.g. `in 10 days` or `2 hours ago`
  *
@@ -87,13 +73,6 @@ export declare function formatDuration(ms: number): string;
  * @param current Today's date (or a different date to measure from).
  */
 export declare function formatFullWhen(target: PossibleDate, current?: PossibleDate): string;
-/**
- * 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 const formatFullUntil: (target: PossibleDate, current?: PossibleDate | undefined) => string;
 /**
  * Return full description of when a date will happen, e.g. `10 days` or `2 hours` or `-1 week`
  *

package/util/date.js

@@ -1,19 +1,5 @@
 import { AssertionError } from "../error/index.js";
-import { formatFullQuantity, formatQuantity } from "./number.js";
-/** One second in millseconds. */
-export const SECOND = 1000;
-/** One minute in millseconds. */
-export const MINUTE = 60 * SECOND;
-/** One hour in millseconds. */
-export const HOUR = 60 * MINUTE;
-/** One day in millseconds. */
-export const DAY = 24 * HOUR;
-/** One week in millseconds. */
-export const WEEK = 7 * DAY;
-/** One month in millseconds. */
-export const MONTH = 30 * DAY;
-/** One year in millseconds. */
-export const YEAR = 365 * DAY;
+import { DAY, HOUR, MINUTE, MONTH, SECOND, WEEK, YEAR, formatUnits, formatFullUnits } from "./units.js";
 /** Is a value a date? */
 export const isDate = (v) => v instanceof Date;
 /**
@@ -124,40 +110,26 @@ export const getDaysAgo = (target, current) => 0 - getDaysUntil(target, current)
 export const getWeeksUntil = (target, current) => Math.floor(getDaysUntil(target, current) / 7);
 /** Count the number of weeks ago a date was. */
 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) {
+function _formatDuration(formatter, ms, maxPrecision = 0, minPrecision) {
     const abs = Math.abs(ms);
     if (abs <= 99 * SECOND)
-        return formatFullQuantity(ms, "second", "seconds", 0); // Up to 99 seconds, e.g. '22 seconds ago'
+        return formatter(ms, "second", maxPrecision, minPrecision); // 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'
+        return formatter(ms / MINUTE, "minute", maxPrecision, minPrecision); // 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'
+        return formatter(ms / HOUR, "hour", maxPrecision, minPrecision); // 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'
+        return formatter(ms / DAY, "day", maxPrecision, minPrecision); // 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'
+        return formatter(ms / WEEK, "week", maxPrecision, minPrecision); // 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 formatter(ms / MONTH, "month", maxPrecision, minPrecision); // Up to 18 months — show months, e.g. '6 months ago'
+    return formatter(ms / YEAR, "year", maxPrecision, minPrecision); // Above 18 months — show years, e.g. '2 years ago'
 }
+/** 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 const formatFullDuration = (ms, maxPrecision, minPrecision) => _formatDuration(formatFullUnits, ms, maxPrecision, minPrecision);
 /** 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'
-}
+export const formatDuration = (ms, maxPrecision, minPrecision) => _formatDuration(formatUnits, ms, maxPrecision, minPrecision);
 /**
  * Return full description of the gap between two dates, e.g. `in 10 days` or `2 hours ago`
  *
@@ -170,13 +142,6 @@ export function formatFullWhen(target, current) {
     const duration = formatFullDuration(abs);
     return abs < 10 * SECOND ? "just now" : ms > 0 ? `in ${duration}` : `${duration} ago`;
 }
-/**
- * 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 const formatFullUntil = (target, current) => formatFullDuration(getDuration(target, current));
 /**
  * Return full description of when a date will happen, e.g. `10 days` or `2 hours` or `-1 week`
  *

package/util/number.d.ts

@@ -59,9 +59,9 @@ export declare const truncateNumber: (num: number, precision?: number) => number
  * @returns The number formatted as a string in the browser's current locale.
  */
 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). */
+/** Format a number with a short suffix. */
 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). */
+/** Format a number with a longer full-word suffix. */
 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`
@@ -103,6 +103,13 @@ export declare const isBetween: (num: number, start: number, end: number) => boo
  * @param end The end of the range, e.g. `20`
  */
 export declare const getBetween: (num: number, start: number, end: number) => number;
+/**
+ * Get a number as a percentage of another number.
+ *
+ * @param numerator Number representing the amount of progress.
+ * @param denumerator The number representing the whole amount.
+ */
+export declare const getPercent: (numerator: number, denumerator: number) => number;
 /** Sum an iterable set of numbers and return the total. */
 export declare function sumNumbers(nums: Iterable<number>): number;
 /** Find the number that's closest to a target in an iterable set of numbers. */

package/util/number.js

@@ -1,5 +1,4 @@
 import { AssertionError } from "../error/index.js";
-import { NBSP, NNBSP } from "./string.js";
 // Constants.
 export const TRILLION = 1000000000000;
 export const BILLION = 1000000000;
@@ -76,12 +75,12 @@ export const truncateNumber = (num, precision = 0) => Math.trunc(num * 10 ** pre
  * @returns The number formatted as a string in the browser's current locale.
  */
 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). */
+/** Format a number with a short suffix. */
+export const formatQuantity = (num, suffix, maxPrecision, minPrecision) => `${formatNumber(num, maxPrecision, minPrecision)}${suffix}`;
+/** Format a number with a longer full-word suffix. */
 export function formatFullQuantity(num, singular, plural, maxPrecision, minPrecision) {
     const qty = formatNumber(num, maxPrecision, minPrecision);
-    return `${qty}${NBSP}${qty === "1" ? singular : plural}`;
+    return `${qty} ${qty === "1" ? singular : plural}`;
 }
 /**
  * Cram a large whole numbers into a space efficient format, e.g. `14.7M`
@@ -138,6 +137,13 @@ export const isBetween = (num, start, end) => num >= start && num <= end;
  * @param end The end of the range, e.g. `20`
  */
 export const getBetween = (num, start, end) => Math.max(start, Math.min(end, num));
+/**
+ * Get a number as a percentage of another number.
+ *
+ * @param numerator Number representing the amount of progress.
+ * @param denumerator The number representing the whole amount.
+ */
+export const getPercent = (numerator, denumerator) => Math.max(0, Math.min(100, (100 / denumerator) * numerator));
 /** Sum an iterable set of numbers and return the total. */
 export function sumNumbers(nums) {
     let sum = 0;

package/util/units.d.ts

@@ -1,9 +1,25 @@
+/** One second in millseconds. */
+export declare const SECOND = 1000;
+/** One minute in millseconds. */
+export declare const MINUTE: number;
+/** One hour in millseconds. */
+export declare const HOUR: number;
+/** One day in millseconds. */
+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;
 /** 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;
+    /** Singular name for a unit, e.g. `foot` (only needed if different from reference). */
+    readonly singular?: string;
+    /** Plural name for a unit, e.g. `feet` */
+    readonly plural?: string;
     /** 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. */
@@ -14,7 +30,7 @@ export declare type UnitData = {
 /** 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";
+export declare type UnitReference = "percent" | "permille" | "permyriad" | "ppm" | "percentage-point" | "basis-point" | "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;

package/util/units.js

@@ -1,37 +1,55 @@
 import { AssertionError } from "../error/index.js";
-import { DAY, HOUR, MINUTE, MONTH, SECOND, WEEK, YEAR } from "./date.js";
-import { formatFullQuantity, formatQuantity } from "./number.js";
+import { formatFullQuantity, formatQuantity, MILLION } from "./number.js";
 import { NNBSP } from "./string.js";
+/** One second in millseconds. */
+export const SECOND = 1000;
+/** One minute in millseconds. */
+export const MINUTE = 60 * SECOND;
+/** One hour in millseconds. */
+export const HOUR = 60 * MINUTE;
+/** One day in millseconds. */
+export const DAY = 24 * HOUR;
+/** One week in millseconds. */
+export const WEEK = 7 * DAY;
+/** One month in millseconds. */
+export const MONTH = 30 * DAY;
+/** One year in millseconds. */
+export const YEAR = 365 * DAY;
 /** List of units. */
 export const UNITS = {
     "percent": { type: "percentage", base: 1, suffix: "%" },
-    "degree": { type: "angle", base: 1, suffix: "deg" },
-    "millimeter": { type: "length", base: 1, suffix: "mm" },
-    "centimeter": { type: "length", base: 10, suffix: "cm" },
-    "meter": { type: "length", base: 1000, centimeter: 100, millimeter: 1000, suffix: "m" },
-    "kilometer": { type: "length", base: 1000000, centimeter: 100000, millimeter: 1000000, suffix: "km" },
-    "inch": { type: "length", base: 25.4, suffix: "in" },
-    "foot": { type: "length", base: 304.8, inch: 12, suffix: "ft", plural: "feet" },
-    "yard": { type: "length", base: 914.4, inch: 36, foot: 3, suffix: "yd" },
-    "mile": { type: "length", base: 1609344, 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: 1, suffix: "mg" },
-    "gram": { type: "mass", base: 1000, suffix: "g" },
-    "kilogram": { type: "mass", base: 1000000, suffix: "kg" },
-    "ounce": { type: "mass", base: 28349.523125, pound: 0.0625, suffix: "oz" },
-    "pound": { type: "mass", base: 453592.37, ounce: 16, suffix: "lb" },
-    "stone": { type: "mass", base: 6350293.18, 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" },
+    "permille": { type: "percentage", base: 10, suffix: `${NNBSP}‰` },
+    "permyriad": { type: "percentage", base: 100, suffix: `${NNBSP}‱` },
+    "ppm": { type: "percentage", base: MILLION, suffix: `${NNBSP}ppm`, singular: "part per million", plural: "parts per million" },
+    "percentage-point": { type: "percentage", base: 1, suffix: `${NNBSP}pp`, singular: "percentage point", plural: "percentage points" },
+    "basis-point": { type: "percentage", base: 10000, suffix: `${NNBSP}bp`, singular: "basis point", plural: "basis points" },
+    "degree": { type: "angle", base: 1, suffix: `${NNBSP}deg` },
+    "millimeter": { type: "length", base: 1, suffix: `${NNBSP}mm` },
+    "centimeter": { type: "length", base: 10, suffix: `${NNBSP}cm` },
+    "meter": { type: "length", base: 1000, centimeter: 100, millimeter: 1000, suffix: `${NNBSP}m` },
+    "kilometer": { type: "length", base: 1000000, centimeter: 100000, millimeter: 1000000, suffix: `${NNBSP}km` },
+    "inch": { type: "length", base: 25.4, suffix: `${NNBSP}in` },
+    "foot": { type: "length", base: 304.8, inch: 12, suffix: `${NNBSP}ft`, plural: "feet" },
+    "yard": { type: "length", base: 914.4, inch: 36, foot: 3, suffix: `${NNBSP}yd` },
+    "mile": { type: "length", base: 1609344, yard: 1760, foot: 5280, inch: 63360, suffix: `${NNBSP}mi` },
+    "milliliter": { type: "volume", base: 1, suffix: `${NNBSP}ml` },
+    "liter": { type: "volume", base: 1000, suffix: `${NNBSP}l` },
+    "fluid-ounce": { type: "volume", base: 29.5735295625, gallon: 128, suffix: `${NNBSP}fl${NNBSP}oz`, singular: "fluid ounce", plural: "fluid ounces" },
+    "gallon": { type: "volume", base: 3785.411784, suffix: `${NNBSP}gal` },
+    "milligram": { type: "mass", base: 1, suffix: `${NNBSP}mg` },
+    "gram": { type: "mass", base: 1000, suffix: `${NNBSP}g` },
+    "kilogram": { type: "mass", base: 1000000, suffix: `${NNBSP}kg` },
+    "ounce": { type: "mass", base: 28349.523125, pound: 0.0625, suffix: `${NNBSP}oz` },
+    "pound": { type: "mass", base: 453592.37, ounce: 16, suffix: `${NNBSP}lb` },
+    "stone": { type: "mass", base: 6350293.18, pound: 14, ounce: 224, suffix: `${NNBSP}st`, plural: "stone" },
+    "millisecond": { type: "time", base: 1, suffix: `${NNBSP}ms` },
+    "second": { type: "time", base: SECOND, suffix: `${NNBSP}s` },
+    "minute": { type: "time", base: MINUTE, suffix: `${NNBSP}m` },
+    "hour": { type: "time", base: HOUR, suffix: `${NNBSP}h` },
+    "day": { type: "time", base: DAY, suffix: `${NNBSP}d` },
+    "week": { type: "time", base: WEEK, suffix: `${NNBSP}w` },
+    "month": { type: "time", base: MONTH, suffix: `${NNBSP}m` },
+    "year": { type: "time", base: YEAR, suffix: `${NNBSP}y` },
 };
 /** Convert between two units of the same type. */
 export function convertUnits(num, from, to) {
@@ -61,4 +79,4 @@ export const formatUnits = (num, unit, maxPrecision, minPrecision) => formatQuan
  * @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);
+export const formatFullUnits = (num, unit, maxPrecision, minPrecision) => formatFullQuantity(num, UNITS[unit].singular || unit, UNITS[unit].plural || `${unit}s`, maxPrecision, minPrecision);