shelving 1.48.1 → 1.49.3

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.48.1",
+	"version": "1.49.3",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -25,9 +25,9 @@
 		"./db": "./db/index.js",
 		"./error": "./error/index.js",
 		"./feedback": "./feedback/index.js",
-		"./firestore/client": "./firestore-client/index.js",
-		"./firestore/lite": "./firestore-lite/index.js",
-		"./firestore/server": "./firestore-server/index.js",
+		"./firestore/client": "./firestore/client/index.js",
+		"./firestore/lite": "./firestore/lite/index.js",
+		"./firestore/server": "./firestore/server/index.js",
 		"./markup": "./markup/index.js",
 		"./provider": "./provider/index.js",
 		"./query": "./query/index.js",

package/stream/DataState.js

@@ -1,4 +1,4 @@
-import { withProp, transformProps, NOERROR, LOADING, awaitNext, getData } from "../util/index.js";
+import { withProp, transformData, NOERROR, LOADING, awaitNext, getData } from "../util/index.js";
 import { State } from "./State.js";
 /** State that stores a data object and has additional methods to help with that. */
 export class DataState extends State {
@@ -12,7 +12,7 @@ export class DataState extends State {
     }
     /** Update several props in this object. */
     update(updates) {
-        this.next(transformProps(this.data, updates));
+        this.next(transformData(this.data, updates));
     }
 }
 /** State that stores an optional data object and has additional methods to help with that. */
@@ -35,7 +35,7 @@ export class ResultState extends State {
     }
     /** Update several props in this object. */
     update(updates) {
-        this.next(transformProps(this.data, updates));
+        this.next(transformData(this.data, updates));
     }
     /** Delete this result. */
     delete() {

package/update/DataUpdate.js

@@ -1,4 +1,4 @@
-import { transformProps, isNullish } from "../util/index.js";
+import { transformData, isNullish } from "../util/index.js";
 import { Update } from "./Update.js";
 /** Update that can be applied to a data object to update its props. */
 export class DataUpdate extends Update {
@@ -11,7 +11,7 @@ export class DataUpdate extends Update {
         return new DataUpdate(!isNullish(key) ? { [key]: value } : {});
     }
     transform(existing) {
-        return transformProps(existing, this.updates);
+        return transformData(existing, this.updates);
     }
     /** Return a data update with a specific prop marked for update. */
     with(key, value) {

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/function.d.ts

@@ -10,9 +10,11 @@ export declare const PASSTHROUGH: <T>(value: T) => T;
 export declare const BLACKHOLE: (...args: Arguments) => void | undefined;
 /** Function that receives a dispatched value. */
 export declare type Dispatcher<T extends Arguments = []> = (...value: T) => void;
+/** Function that receives a dispatched value. */
+export declare type AsyncDispatcher<T extends Arguments = []> = (...value: T) => void | PromiseLike<void>;
 /** Safely dispatch a value to a dispatcher function. */
-export declare function dispatch<T extends Arguments>(dispatcher: Dispatcher<T>, ...value: T): void;
+export declare function dispatch<T extends Arguments>(dispatcher: AsyncDispatcher<T>, ...value: T): void;
 /** Safely dispatch a value to a dispatcher method on an object. */
 export declare function dispatchMethod<T extends Arguments, M extends string | symbol>(obj: {
-    [K in M]: Dispatcher<T>;
+    [K in M]: AsyncDispatcher<T>;
 }, key: M, ...value: T): void;

package/util/function.js

@@ -1,3 +1,4 @@
+import { isAsync } from "./async.js";
 import { logError } from "./error.js";
 /** Is a value a function? */
 export const isFunction = (v) => typeof v === "function";
@@ -8,7 +9,9 @@ export const BLACKHOLE = () => undefined;
 /** Safely dispatch a value to a dispatcher function. */
 export function dispatch(dispatcher, ...value) {
     try {
-        dispatcher(...value);
+        const result = dispatcher(...value);
+        if (isAsync(result))
+            result.then(BLACKHOLE, logError);
     }
     catch (thrown) {
         logError(thrown);
@@ -17,7 +20,9 @@ export function dispatch(dispatcher, ...value) {
 /** Safely dispatch a value to a dispatcher method on an object. */
 export function dispatchMethod(obj, key, ...value) {
     try {
-        obj[key](...value);
+        const result = obj[key](...value);
+        if (isAsync(result))
+            result.then(BLACKHOLE, logError);
     }
     catch (thrown) {
         logError(thrown);

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;
@@ -18,7 +17,7 @@ export const isNumber = (v) => typeof v === "number";
  */
 export function toNumber(value) {
     if (typeof value === "number")
-        return Number.isFinite(value) ? value : null;
+        return !Number.isFinite(value) ? null : value === 0 ? 0 : value;
     else if (typeof value === "string")
         return toNumber(parseFloat(value.replace(NUMERIC, "")));
     else if (value instanceof Date)
@@ -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/transform.d.ts

@@ -1,4 +1,3 @@
-import type { Entry } from "./entry.js";
 import type { ArrayType, ImmutableArray } from "./array.js";
 import type { ImmutableMap } from "./map.js";
 import { ImmutableObject } from "./object.js";
@@ -35,12 +34,6 @@ export declare function yieldTransformed<I, O>(items: Iterable<I>, transformer:
 export declare function transformArray<T extends ImmutableArray>(arr: T, transformer: Transformer<ArrayType<T>, ArrayType<T>>): T;
 export declare function transformArray<I, O>(arr: Iterable<I>, transformer: (v: I) => O): ImmutableArray<O>;
 export declare function transformArray<I, O>(arr: Iterable<I>, transformer: Transformer<I, O>): ImmutableArray<O>;
-/**
- * Transform the _values_ of a set of entries using a transformer.
- * @yield Transformed entry after calling transforming the new value for each entry.
- */
-export declare function yieldTransformedValues<I, O>(entries: Iterable<Entry<I>>, transformer: (v: I) => O): Iterable<Entry<O>>;
-export declare function yieldTransformedValues<I, O>(entries: Iterable<Entry<I>>, transformer: Transformer<I, O>): Iterable<Entry<O>>;
 /**
  * Transform the _values_ of a map using a transformer.
  * @return New map after transforming its values.
@@ -65,7 +58,7 @@ export declare type PropTransformers<T extends Data> = {
  * Transform the props of a data object using a set of transformers for its props.
  * @returns New object with changed props (or the same object if no changes were made).
  */
-export declare function transformProps<T extends Data>(existing: T, transformers: PropTransformers<T>): T;
+export declare function transformData<T extends Data>(existing: T, transformers: PropTransformers<T>): T;
 /** Set of named transformers for a a map-like object. */
 export declare type EntryTransformers<T> = ImmutableObject<Transformer<T | undefined, T>>;
 /** Transform some of the entries of a map-like object using a set of named transformers. */

package/util/transform.js

@@ -16,18 +16,18 @@ export function* yieldTransformed(items, transformer) {
 export function transformArray(arr, transformer) {
     return Array.from(yieldTransformed(arr, transformer));
 }
-export function* yieldTransformedValues(entries, transformer) {
+function* _yieldTransformedValues(entries, transformer) {
     for (const [k, v] of entries)
         yield [k, transform(v, transformer)];
 }
 export function transformMap(map, transformer) {
-    return new Map(yieldTransformedValues(map, transformer));
+    return new Map(_yieldTransformedValues(map, transformer));
 }
 export function transformObject(obj, transformer) {
-    return Object.fromEntries(yieldTransformedValues(Object.entries(obj), transformer));
+    return Object.fromEntries(_yieldTransformedValues(Object.entries(obj), transformer));
 }
 /** Apply transformers to the props of a data object and yield any props that changed. */
-function* yieldTransformedProps(existing, transformers) {
+function* _yieldTransformedProps(existing, transformers) {
     for (const [k, v] of toProps(transformers))
         yield [k, transform(existing[k], v)];
 }
@@ -35,15 +35,15 @@ function* yieldTransformedProps(existing, transformers) {
  * Transform the props of a data object using a set of transformers for its props.
  * @returns New object with changed props (or the same object if no changes were made).
  */
-export function transformProps(existing, transformers) {
-    return Object.fromEntries(yieldMerged(toProps(existing), yieldTransformedProps(existing, transformers)));
+export function transformData(existing, transformers) {
+    return Object.fromEntries(yieldMerged(toProps(existing), _yieldTransformedProps(existing, transformers)));
 }
 /** Apply named transformers to the entries of a map-like object and yield any entries that changed. */
-function* yieldTransformedEntries(existing, updates) {
+function* _yieldTransformedEntries(existing, updates) {
     for (const [k, t] of Object.entries(updates))
         yield [k, transform(existing[k], t)];
 }
 /** Transform some of the entries of a map-like object using a set of named transformers. */
 export function transformEntries(existing, updates, deletes) {
-    return Object.fromEntries(yieldFiltered(yieldMerged(Object.entries(existing), yieldTransformedEntries(existing, updates)), isKeyInArray, deletes));
+    return Object.fromEntries(yieldFiltered(yieldMerged(Object.entries(existing), _yieldTransformedEntries(existing, updates)), isKeyInArray, deletes));
 }

package/util/undefined.js

@@ -1,4 +1,4 @@
-import { RequiredError } from "..";
+import { RequiredError } from "../error/index.js";
 /** Is a value undefined? */
 export const isUndefined = (v) => v === undefined;
 /** Is a value defined? */

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);

package/util/validate.d.ts

@@ -1,5 +1,5 @@
 import type { Entry } from "./entry.js";
-import { Data, Prop, Result } from "./data.js";
+import { Data, Result } from "./data.js";
 /** Object that can validate an unknown value with its `validate()` method. */
 export interface Validatable<T> {
     /**
@@ -50,14 +50,6 @@ export declare function validateItems<T>(unsafeItems: Iterable<unknown>, validat
  * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
  */
 export declare function validateValues<T>(unsafeValues: Iterable<Entry>, validator: Validator<T>): Generator<Entry<T>, void>;
-/**
- * Validate a set of object props with a set of validators.
- *
- * @yield Valid entries for each specified validator.
- * @throw InvalidFeedback if one or more entries did not validate.
- * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
- */
-export declare function validateProps<T extends Data>(unsafeData: Data, validators: Validators<T>): Generator<Prop<T>, void>;
 /**
  * Validate an entire object with a set of validators.
  * - Defined props in the object will be validated against the corresponding validator.
@@ -69,7 +61,7 @@ export declare function validateProps<T extends Data>(unsafeData: Data, validato
  */
 export declare function validateData<T extends Data>(unsafeData: Data, validators: Validators<T>): T;
 /**
- * Validate a data result.
+ * Validate a data result against a validator for that data.
  * @return Valid object or `null`
  */
 export declare function validateResult<T extends Data>(unsafeResult: unknown, validator: Validator<T>): Result<T>;

package/util/validate.js

@@ -1,5 +1,6 @@
 import { Feedback, InvalidFeedback } from "../feedback/index.js";
 import { isData, toProps } from "./data.js";
+import { isNullish } from "./null.js";
 /** Is a given value a validator? */
 export const isValidator = (v) => typeof v === "function" || (isData(v) && typeof v.validate === "function");
 /** Validate an unknown value with a validator. */
@@ -56,6 +57,18 @@ export function* validateValues(unsafeValues, validator) {
     if (invalid)
         throw new InvalidFeedback("Invalid items", details);
 }
+/**
+ * Validate an entire object with a set of validators.
+ * - Defined props in the object will be validated against the corresponding validator.
+ * - `undefined` props in the object will be set to the default value of that prop.
+ *
+ * @return Valid object.
+ * @throw InvalidFeedback if one or more entries did not validate.
+ * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
+ */
+export function validateData(unsafeData, validators) {
+    return Object.fromEntries(_yieldValidatedProps(unsafeData, validators));
+}
 /**
  * Validate a set of object props with a set of validators.
  *
@@ -63,7 +76,7 @@ export function* validateValues(unsafeValues, validator) {
  * @throw InvalidFeedback if one or more entries did not validate.
  * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
  */
-export function* validateProps(unsafeData, validators) {
+function* _yieldValidatedProps(unsafeData, validators) {
     let invalid = false;
     const details = {};
     for (const [k, validator] of toProps(validators)) {
@@ -83,21 +96,9 @@ export function* validateProps(unsafeData, validators) {
         throw new InvalidFeedback("Invalid data", details);
 }
 /**
- * Validate an entire object with a set of validators.
- * - Defined props in the object will be validated against the corresponding validator.
- * - `undefined` props in the object will be set to the default value of that prop.
- *
- * @return Valid object.
- * @throw InvalidFeedback if one or more entries did not validate.
- * - `feedback.details` will contain an entry for each invalid item (keyed by their count in the input iterable).
- */
-export function validateData(unsafeData, validators) {
-    return Object.fromEntries(validateProps(unsafeData, validators));
-}
-/**
- * Validate a data result.
+ * Validate a data result against a validator for that data.
  * @return Valid object or `null`
  */
 export function validateResult(unsafeResult, validator) {
-    return unsafeResult === null || unsafeResult === undefined ? validate(unsafeResult, validator) : null;
+    return !isNullish(unsafeResult) ? validate(unsafeResult, validator) : null;
 }