shelving 1.185.2 → 1.186.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.185.2",
+	"version": "1.186.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/schema/ChoiceSchema.js

@@ -26,7 +26,7 @@ export class ChoiceSchema extends Schema {
     validate(unsafeValue = this.value) {
         if (typeof unsafeValue === "string" && isOption(this.options, unsafeValue))
             return unsafeValue;
-        throw unsafeValue ? "Unknown value" : "Required";
+        throw unsafeValue ? `Unknown ${this.one}` : "Required";
     }
     // Implement iterable.
     *[Symbol.iterator]() {

package/schema/CurrencyAmountSchema.d.ts

@@ -0,0 +1,33 @@
+import { type CurrencyCode } from "../util/currency.js";
+import { NumberSchema, type NumberSchemaOptions } from "./NumberSchema.js";
+/** Allowed options for `CurrencyAmountSchema`. */
+export interface CurrencyAmountSchemaOptions extends NumberSchemaOptions {
+    readonly symbol?: string | undefined;
+    readonly currency: CurrencyCode;
+}
+/**
+ * Schema representing a numeric amount in a specific currency.
+ *
+ * - The validation step is inferred from the currency's minor units.
+ * - The default formatter renders amounts using shelving's currency helpers.
+ *
+ * @example
+ * const PRICE = new CurrencyAmountSchema({ currency: "GBP", min: 0 });
+ * PRICE.validate("12.345"); // 12.35
+ * PRICE.format(12.3); // "£12.30"
+ */
+export declare class CurrencyAmountSchema extends NumberSchema {
+    readonly currency: CurrencyCode;
+    readonly symbol: string;
+    constructor({ currency, one, title, symbol, step, format, ...options }: CurrencyAmountSchemaOptions);
+}
+/** Valid non-negative monetary amount in the a currency. */
+export declare const CURRENCY_AMOUNT: (currency: CurrencyCode) => CurrencyAmountSchema;
+export declare const USD_AMOUNT: CurrencyAmountSchema;
+export declare const GBP_AMOUNT: CurrencyAmountSchema;
+export declare const EUR_AMOUNT: CurrencyAmountSchema;
+/** Valid optional monetary amount in the default currency, or `null`. */
+export declare const NULLABLE_CURRENCY_AMOUNT: (currency: CurrencyCode) => import("./NullableSchema.js").NullableSchema<number>;
+export declare const NULLABLE_USD_AMOUNT: import("./NullableSchema.js").NullableSchema<number>;
+export declare const NULLABLE_GBP_AMOUNT: import("./NullableSchema.js").NullableSchema<number>;
+export declare const NULLABLE_EUR_AMOUNT: import("./NullableSchema.js").NullableSchema<number>;

package/schema/CurrencyAmountSchema.js

@@ -0,0 +1,41 @@
+import { getCurrencyStep, getCurrencySymbol, requireCurrencyCode } from "../util/currency.js";
+import { formatCurrency } from "../util/format.js";
+import { NULLABLE } from "./NullableSchema.js";
+import { NumberSchema } from "./NumberSchema.js";
+/**
+ * Schema representing a numeric amount in a specific currency.
+ *
+ * - The validation step is inferred from the currency's minor units.
+ * - The default formatter renders amounts using shelving's currency helpers.
+ *
+ * @example
+ * const PRICE = new CurrencyAmountSchema({ currency: "GBP", min: 0 });
+ * PRICE.validate("12.345"); // 12.35
+ * PRICE.format(12.3); // "£12.30"
+ */
+export class CurrencyAmountSchema extends NumberSchema {
+    currency;
+    symbol;
+    constructor({ currency, one = "amount", title = "Amount", symbol, step, format = (value, options) => formatCurrency(value, currency, options), ...options }) {
+        const validCurrency = requireCurrencyCode(currency, CurrencyAmountSchema);
+        super({
+            one,
+            title,
+            step: step ?? getCurrencyStep(validCurrency, CurrencyAmountSchema),
+            format,
+            ...options,
+        });
+        this.currency = validCurrency;
+        this.symbol = symbol ?? getCurrencySymbol(validCurrency, CurrencyAmountSchema);
+    }
+}
+/** Valid non-negative monetary amount in the a currency. */
+export const CURRENCY_AMOUNT = (currency) => new CurrencyAmountSchema({ currency });
+export const USD_AMOUNT = new CurrencyAmountSchema({ currency: "USD" });
+export const GBP_AMOUNT = new CurrencyAmountSchema({ currency: "GBP" });
+export const EUR_AMOUNT = new CurrencyAmountSchema({ currency: "EUR" });
+/** Valid optional monetary amount in the default currency, or `null`. */
+export const NULLABLE_CURRENCY_AMOUNT = (currency) => NULLABLE(CURRENCY_AMOUNT(currency));
+export const NULLABLE_USD_AMOUNT = NULLABLE(USD_AMOUNT);
+export const NULLABLE_GBP_AMOUNT = NULLABLE(GBP_AMOUNT);
+export const NULLABLE_EUR_AMOUNT = NULLABLE(EUR_AMOUNT);

package/schema/CurrencyCodeSchema.d.ts

@@ -0,0 +1,21 @@
+import type { ImmutableArray } from "../util/array.js";
+import { type CurrencyCode } from "../util/currency.js";
+import type { StringSchemaOptions } from "./StringSchema.js";
+import { StringSchema } from "./StringSchema.js";
+/** Options for a `CurrencyCodeSchema` */
+export interface CurrencyCodeSchemaOptions extends Omit<StringSchemaOptions, "input" | "min" | "max" | "match" | "multiline"> {
+    currencies?: ImmutableArray<CurrencyCode>;
+}
+/**
+ * Type of `StringSchema` that defines a valid currency code.
+ */
+export declare class CurrencyCodeSchema extends StringSchema {
+    readonly currencies: ImmutableArray<CurrencyCode>;
+    constructor({ one, title, currencies, ...options }: CurrencyCodeSchemaOptions);
+    sanitize(insaneString: string): string;
+    validate(value?: unknown): string;
+}
+/** Valid currency code, e.g. `GBP` */
+export declare const CURRENCY_CODE: CurrencyCodeSchema;
+/** Valid currency code, e.g. `GBP`, or `null` */
+export declare const NULLABLE_CURRENCY_CODE: import("./NullableSchema.js").NullableSchema<string>;

package/schema/CurrencyCodeSchema.js

@@ -0,0 +1,35 @@
+import { CURRENCY_CODES } from "../util/currency.js";
+import { NULLABLE } from "./NullableSchema.js";
+import { StringSchema } from "./StringSchema.js";
+/**
+ * Type of `StringSchema` that defines a valid currency code.
+ */
+export class CurrencyCodeSchema extends StringSchema {
+    currencies;
+    constructor({ one = "currency", title = "Currency", currencies = CURRENCY_CODES, ...options }) {
+        super({
+            one,
+            title,
+            ...options,
+            min: 3,
+            max: 3, // Valid currency code is 3 uppercase letters.
+            case: "upper",
+            match: /^[A-Z]{3}$/, // Valid currency code is 3 uppercase letters.
+        });
+        this.currencies = currencies;
+    }
+    sanitize(insaneString) {
+        // Strip characters that aren't A-Z (including whitespace).
+        return super.sanitize(insaneString).replace(/[^A-Z+]/g, "");
+    }
+    validate(value) {
+        const currency = super.validate(value);
+        if (!this.currencies.includes(currency))
+            throw "Unknown currency code";
+        return currency;
+    }
+}
+/** Valid currency code, e.g. `GBP` */
+export const CURRENCY_CODE = new CurrencyCodeSchema({});
+/** Valid currency code, e.g. `GBP`, or `null` */
+export const NULLABLE_CURRENCY_CODE = NULLABLE(CURRENCY_CODE);

package/schema/DateSchema.d.ts

@@ -1,4 +1,5 @@
 import type { PossibleDate } from "../util/date.js";
+import { formatDate } from "../util/format.js";
 import type { Nullish } from "../util/null.js";
 import type { SchemaOptions } from "./Schema.js";
 import { Schema } from "./Schema.js";
@@ -10,6 +11,8 @@ export interface DateSchemaOptions extends SchemaOptions {
     readonly min?: Nullish<PossibleDate>;
     readonly max?: Nullish<PossibleDate>;
     readonly input?: DateInputType | undefined;
+    /** Format the date for display in downstream UIs. */
+    readonly format?: typeof formatDate | undefined;
     /**
      * Rounding step (in milliseconds, because that's the base unit for time).
      * - E.g. `1000 * 60` will round to the nearest minute.
@@ -18,15 +21,15 @@ export interface DateSchemaOptions extends SchemaOptions {
     readonly step?: number | undefined;
 }
 export declare class DateSchema extends Schema<string> {
-    readonly value: PossibleDate;
+    readonly value: PossibleDate | undefined;
     readonly min: Date | undefined;
     readonly max: Date | undefined;
     readonly input: DateInputType;
     readonly step: number | undefined;
-    constructor({ one, min, max, value, input, step, ...options }: DateSchemaOptions);
+    format: (value: Date) => string;
+    constructor({ one, min, max, value, input, step, format, ...options }: DateSchemaOptions);
     validate(value?: unknown): string;
     stringify(value: Date): string;
-    format(value: Date): string;
 }
 /** Valid date, e.g. `2005-09-12` (required because falsy values are invalid). */
 export declare const DATE: DateSchema;

package/schema/DateSchema.js

@@ -8,30 +8,29 @@ export class DateSchema extends Schema {
     max;
     input;
     step;
-    constructor({ one = "date", min, max, value = "now", input = "date", step, ...options }) {
+    format;
+    constructor({ one = "date", min, max, value, input = "date", step, format = formatDate, ...options }) {
         super({ one, title: "Date", value, ...options });
         this.min = getDate(min);
         this.max = getDate(max);
         this.input = input;
         this.step = step;
+        this.format = format;
     }
     validate(value = this.value) {
         const date = getDate(value);
         if (!date)
-            throw value ? "Invalid date" : "Required";
-        const rounded = typeof this.step === "number" ? new Date(roundStep(date.getTime(), this.step)) : date;
-        if (this.min && rounded < this.min)
+            throw value ? `Invalid ${this.one} format` : "Required";
+        const stepped = typeof this.step === "number" ? new Date(roundStep(date.getTime(), this.step)) : date;
+        if (this.min && stepped < this.min)
             throw `Minimum ${this.format(this.min)}`;
-        if (this.max && rounded > this.max)
+        if (this.max && stepped > this.max)
             throw `Maximum ${this.format(this.max)}`;
-        return this.stringify(rounded);
+        return this.stringify(stepped);
     }
     stringify(value) {
         return requireDateString(value);
     }
-    format(value) {
-        return formatDate(value);
-    }
 }
 /** Valid date, e.g. `2005-09-12` (required because falsy values are invalid). */
 export const DATE = new DateSchema({});

package/schema/DateTimeSchema.d.ts

@@ -6,8 +6,7 @@ import { DateSchema, type DateSchemaOptions } from "./DateSchema.js";
  * - If you wish to define an _abstract_ time without a timezone, e.g. a daily alarm, use `TimeSchema` instead.
  */
 export declare class DateTimeSchema extends DateSchema {
-    constructor({ one, title, input, ...options }: DateSchemaOptions);
-    format(value: Date): string;
+    constructor({ one, title, input, format, ...options }: DateSchemaOptions);
     stringify(value: Date): string;
 }
 /** Valid datetime, e.g. `2005-09-12T08:00:00Z` (required because falsy values are invalid). */

package/schema/DateTimeSchema.js

@@ -8,11 +8,8 @@ import { NULLABLE } from "./NullableSchema.js";
  * - If you wish to define an _abstract_ time without a timezone, e.g. a daily alarm, use `TimeSchema` instead.
  */
 export class DateTimeSchema extends DateSchema {
-    constructor({ one = "time", title = "Time", input = "datetime-local", ...options }) {
-        super({ one, title, input, ...options });
-    }
-    format(value) {
-        return formatDateTime(value);
+    constructor({ one = "time", title = "Time", input = "datetime-local", format = formatDateTime, ...options }) {
+        super({ one, title, input, format, ...options });
     }
     stringify(value) {
         return value.toISOString();

package/schema/FileSchema.js

@@ -13,9 +13,9 @@ export class FileSchema extends StringSchema {
         const path = super.validate(unsafeValue);
         const extension = getFileExtension(path);
         if (!extension)
-            throw "Must be file name with extension";
+            throw `Must have extension`;
         if (this.types && !isProp(this.types, extension))
-            throw "Invalid file type";
+            throw `Invalid extension`;
         return path;
     }
 }

package/schema/NumberSchema.d.ts

@@ -1,3 +1,4 @@
+import { formatNumber } from "../util/format.js";
 import type { SchemaOptions } from "./Schema.js";
 import { Schema } from "./Schema.js";
 /** Allowed options for `NumberSchema` */
@@ -6,17 +7,20 @@ export interface NumberSchemaOptions extends SchemaOptions {
     readonly min?: number | undefined;
     readonly max?: number | undefined;
     readonly step?: number | undefined;
+    /** Format the number for display in downstream UIs. */
+    readonly format?: typeof formatNumber | undefined;
 }
 /** Schema that defines a valid number. */
 export declare class NumberSchema extends Schema<number> {
-    readonly value: number;
+    readonly value: number | undefined;
     readonly min: number;
     readonly max: number;
     readonly step: number | undefined;
-    constructor({ one, title, min, max, step, value, ...options }: NumberSchemaOptions);
-    validate(unsafeValue?: unknown): number;
+    format: (value: number) => string;
+    constructor({ one, title, min, max, step, format, value, ...options }: NumberSchemaOptions);
+    validate(value?: unknown): number;
 }
-/** Valid number, e.g. `2048.12345` or `0` zero. */
+/** Valid number, e.g. `2048.12345` or `0` zero and a default value of zero. */
 export declare const NUMBER: NumberSchema;
 /** Valid optional number, e.g. `2048.12345` or `0` zero, or `null` */
 export declare const NULLABLE_NUMBER: import("./NullableSchema.js").NullableSchema<number>;

package/schema/NumberSchema.js

@@ -7,38 +7,40 @@ export class NumberSchema extends Schema {
     min;
     max;
     step;
-    constructor({ one = "number", title = "Number", min = Number.NEGATIVE_INFINITY, max = Number.POSITIVE_INFINITY, step, value = 0, ...options }) {
+    format;
+    constructor({ one = "number", title = "Number", min = Number.NEGATIVE_INFINITY, max = Number.POSITIVE_INFINITY, step, format = formatNumber, value, ...options }) {
         super({ one, title, value, ...options });
         this.min = min;
         this.max = max;
         this.step = step;
+        this.format = format;
     }
-    validate(unsafeValue = this.value) {
-        const optionalNumber = getNumber(unsafeValue);
-        if (typeof optionalNumber !== "number")
-            throw "Must be number";
-        const roundedNumber = typeof this.step === "number" ? roundStep(optionalNumber, this.step) : optionalNumber;
-        if (roundedNumber < this.min)
-            throw !optionalNumber ? "Required" : `Minimum ${formatNumber(this.min)}`;
-        if (roundedNumber > this.max)
-            throw `Maximum ${formatNumber(this.max)}`;
-        return roundedNumber;
+    validate(value = this.value) {
+        const number = getNumber(value);
+        if (typeof number !== "number")
+            throw value ? `Must be ${this.one}` : "Required";
+        const stepped = typeof this.step === "number" ? roundStep(number, this.step) : number;
+        if (stepped < this.min)
+            throw !number ? "Required" : `Minimum ${this.format(this.min)}`;
+        if (stepped > this.max)
+            throw `Maximum ${this.format(this.max)}`;
+        return stepped;
     }
 }
-/** Valid number, e.g. `2048.12345` or `0` zero. */
+/** Valid number, e.g. `2048.12345` or `0` zero and a default value of zero. */
 export const NUMBER = new NumberSchema({ title: "Number" });
 /** Valid optional number, e.g. `2048.12345` or `0` zero, or `null` */
 export const NULLABLE_NUMBER = NULLABLE(NUMBER);
 /** Valid integer number, e.g. `2048` or `0` zero. */
-export const INTEGER = new NumberSchema({ step: 1, min: Number.MIN_SAFE_INTEGER, max: Number.MAX_SAFE_INTEGER, value: 0 });
+export const INTEGER = new NumberSchema({ step: 1, min: Number.MIN_SAFE_INTEGER, max: Number.MAX_SAFE_INTEGER });
 /** Valid positive integer number, e.g. `1,2,3` (not including zero). */
-export const POSITIVE_INTEGER = new NumberSchema({ step: 1, min: 1, max: Number.MAX_SAFE_INTEGER, value: 1 });
+export const POSITIVE_INTEGER = new NumberSchema({ step: 1, min: 1, max: Number.MAX_SAFE_INTEGER });
 /** Valid non-negative integer number, e.g. `0,1,2,3` (including zero). */
-export const NON_NEGATIVE_INTEGER = new NumberSchema({ step: 1, min: 0, max: Number.MAX_SAFE_INTEGER, value: 0 });
+export const NON_NEGATIVE_INTEGER = new NumberSchema({ step: 1, min: 0, max: Number.MAX_SAFE_INTEGER });
 /** Valid negative integer number, e.g. `-1,-2,-3` (not including zero). */
-export const NEGATIVE_INTEGER = new NumberSchema({ step: 1, min: Number.MIN_SAFE_INTEGER, max: -1, value: -1 });
+export const NEGATIVE_INTEGER = new NumberSchema({ step: 1, min: Number.MIN_SAFE_INTEGER, max: -1 });
 /** Valid non-positive integer number, e.g. `0,-1,-2,-3` (including zero). */
-export const NON_POSITIVE_INTEGER = new NumberSchema({ step: 1, min: Number.MIN_SAFE_INTEGER, max: 0, value: 0 });
+export const NON_POSITIVE_INTEGER = new NumberSchema({ step: 1, min: Number.MIN_SAFE_INTEGER, max: 0 });
 /** Valid optional integer number, e.g. `2048` or `0` zero, or `null` */
 export const NULLABLE_INTEGER = NULLABLE(INTEGER);
 /** Valid Unix timestamp (including milliseconds). */
@@ -47,7 +49,6 @@ export const TIMESTAMP = new NumberSchema({
     step: 1,
     min: Number.MIN_SAFE_INTEGER,
     max: Number.MAX_SAFE_INTEGER,
-    value: 0,
 });
 /** Valid Unix timestamp (including milliseconds). */
 export const NULLABLE_TIMESTAMP = NULLABLE_INTEGER;

package/schema/PhoneSchema.d.ts

@@ -1,12 +1,15 @@
 import type { StringSchemaOptions } from "./StringSchema.js";
 import { StringSchema } from "./StringSchema.js";
+/** Options for a `PhoneSchema` */
+export interface PhoneSchemaOptions extends Omit<StringSchemaOptions, "input" | "min" | "max" | "match" | "multiline"> {
+}
 /**
  * Type of `StringSchema` that defines a valid phone number.
  * - Multiple string formats are automatically converted to E.164 format (starting with `+` plus).
  * - Falsy values are converted to `""` empty string.
  */
 export declare class PhoneSchema extends StringSchema {
-    constructor({ one, title, ...options }: Omit<StringSchemaOptions, "input" | "min" | "max" | "match" | "multiline">);
+    constructor({ one, title, ...options }: PhoneSchemaOptions);
     sanitize(insaneString: string): string;
 }
 /** Valid phone number, e.g. `+441234567890` */

package/schema/PhoneSchema.js

@@ -1,9 +1,5 @@
 import { NULLABLE } from "./NullableSchema.js";
 import { StringSchema } from "./StringSchema.js";
-// Valid phone number is max 16 digits made up of:
-// - Country code (`+` plus character and 1-3 digits, e.g. `+44` or `+1`).
-// - Subscriber number (5-12 digits — the Solomon Islands have five-digit phone numbers apparently).
-const PHONE_REGEXP = /^\+[1-9][0-9]{0,2}[0-9]{5,12}$/;
 /**
  * Type of `StringSchema` that defines a valid phone number.
  * - Multiple string formats are automatically converted to E.164 format (starting with `+` plus).
@@ -17,8 +13,12 @@ export class PhoneSchema extends StringSchema {
             ...options,
             input: "tel",
             min: 1,
-            max: 16, // Valid phone number is 16 digits or fewer (15 numerals with a leading `+` plus).
-            match: PHONE_REGEXP,
+            // Valid phone number is 16 digits or fewer (15 numerals with a leading `+` plus).
+            max: 16,
+            // Valid phone number is max 16 digits made up of:
+            // - Country code (`+` plus character and 1-3 digits, e.g. `+44` or `+1`).
+            // - Subscriber number (5-12 digits — the Solomon Islands have five-digit phone numbers apparently).
+            match: /^\+[1-9][0-9]{0,2}[0-9]{5,12}$/,
         });
     }
     sanitize(insaneString) {

package/schema/StringSchema.d.ts

@@ -35,8 +35,8 @@ export declare class StringSchema extends Schema<string> {
     readonly multiline: boolean;
     readonly match: RegExp | undefined;
     readonly case: "upper" | "lower" | undefined;
-    constructor({ min, max, value, multiline, match, case: _case, input, ...options }: StringSchemaOptions);
-    validate(unsafeValue?: unknown): string;
+    constructor({ one, min, max, value, multiline, match, case: _case, input, ...options }: StringSchemaOptions);
+    validate(value?: unknown): string;
     /** Sanitize the string by removing unwanted characters. */
     sanitize(str: string): string;
 }

package/schema/StringSchema.js

@@ -23,8 +23,8 @@ export class StringSchema extends Schema {
     multiline;
     match;
     case;
-    constructor({ min = 0, max = Number.POSITIVE_INFINITY, value = "", multiline = false, match, case: _case, input = "text", ...options }) {
-        super({ value, ...options });
+    constructor({ one = "string", min = 0, max = Number.POSITIVE_INFINITY, value = "", multiline = false, match, case: _case, input = "text", ...options }) {
+        super({ one, value, ...options });
         this.min = min;
         this.max = max;
         this.multiline = multiline;
@@ -32,18 +32,18 @@ export class StringSchema extends Schema {
         this.case = _case;
         this.input = input;
     }
-    validate(unsafeValue = this.value) {
-        const possibleString = typeof unsafeValue === "number" ? unsafeValue.toString() : unsafeValue;
-        if (typeof possibleString !== "string")
-            throw "Must be string";
-        const saneString = this.sanitize(possibleString);
-        if (saneString.length < this.min)
-            throw possibleString.length ? `Minimum ${this.min} characters` : "Required";
-        if (saneString.length > this.max)
+    validate(value = this.value) {
+        const str = typeof value === "number" ? value.toString() : value;
+        if (typeof str !== "string")
+            throw value ? `Must be ${this.one}` : "Required";
+        const sane = this.sanitize(str);
+        if (this.match && !this.match.test(sane))
+            throw str.length ? `Invalid ${this.one}` : "Required";
+        if (sane.length < this.min)
+            throw str.length ? `Minimum ${this.min} characters` : "Required";
+        if (sane.length > this.max)
             throw `Maximum ${this.max} characters`;
-        if (this.match && !this.match.test(saneString))
-            throw saneString ? "Invalid format" : "Required";
-        return saneString;
+        return sane;
     }
     /** Sanitize the string by removing unwanted characters. */
     sanitize(str) {

package/schema/TimeSchema.d.ts

@@ -1,9 +1,8 @@
 import { DateSchema, type DateSchemaOptions } from "./DateSchema.js";
 /** Define a valid time in 24h hh:mm:ss.fff format, e.g. `23:59` or `24:00 */
 export declare class TimeSchema extends DateSchema {
-    constructor({ one, title, input, ...options }: DateSchemaOptions);
+    constructor({ one, title, input, format, ...options }: DateSchemaOptions);
     stringify(value: Date): string;
-    format(value: Date): string;
 }
 /** Valid time, e.g. `2005-09-12` (required because falsy values are invalid). */
 export declare const TIME: TimeSchema;

package/schema/TimeSchema.js

@@ -4,15 +4,12 @@ import { DateSchema } from "./DateSchema.js";
 import { NULLABLE } from "./NullableSchema.js";
 /** Define a valid time in 24h hh:mm:ss.fff format, e.g. `23:59` or `24:00 */
 export class TimeSchema extends DateSchema {
-    constructor({ one = "time", title = "Time", input = "time", ...options }) {
-        super({ one, title, input, ...options });
+    constructor({ one = "time", title = "Time", input = "time", format = formatTime, ...options }) {
+        super({ one, title, input, format, ...options });
     }
     stringify(value) {
         return requireTimeString(value);
     }
-    format(value) {
-        return formatTime(value);
-    }
 }
 /** Valid time, e.g. `2005-09-12` (required because falsy values are invalid). */
 export const TIME = new TimeSchema({});

package/schema/URISchema.js

@@ -25,9 +25,9 @@ export class URISchema extends StringSchema {
         const str = super.validate(unsafeValue);
         const uri = getURI(str);
         if (!uri)
-            throw str ? "Invalid format" : "Required";
+            throw str ? `Invalid ${this.one} format` : "Required";
         if (this.schemes && !this.schemes.includes(uri.protocol))
-            throw "Invalid URI scheme";
+            throw `Invalid ${this.one} scheme`;
         return uri.href;
     }
 }

package/schema/URLSchema.js

@@ -28,9 +28,9 @@ export class URLSchema extends StringSchema {
         const str = super.validate(unsafeValue);
         const url = getURL(str, this.base);
         if (!url)
-            throw str ? "Invalid format" : "Required";
+            throw str ? `Invalid ${this.one} format` : "Required";
         if (this.schemes && !this.schemes.includes(url.protocol))
-            throw "Invalid URL scheme";
+            throw `Invalid ${this.one} scheme`;
         return url.href;
     }
 }

package/schema/index.d.ts

@@ -4,6 +4,8 @@ export * from "./BooleanSchema.js";
 export * from "./ChoiceSchema.js";
 export * from "./ColorSchema.js";
 export * from "./CountrySchema.js";
+export * from "./CurrencyAmountSchema.js";
+export * from "./CurrencyCodeSchema.js";
 export * from "./DataSchema.js";
 export * from "./DateSchema.js";
 export * from "./DateTimeSchema.js";

package/schema/index.js

@@ -4,6 +4,8 @@ export * from "./BooleanSchema.js";
 export * from "./ChoiceSchema.js";
 export * from "./ColorSchema.js";
 export * from "./CountrySchema.js";
+export * from "./CurrencyAmountSchema.js";
+export * from "./CurrencyCodeSchema.js";
 export * from "./DataSchema.js";
 export * from "./DateSchema.js";
 export * from "./DateTimeSchema.js";

package/util/currency.d.ts

@@ -0,0 +1,28 @@
+import type { ImmutableArray } from "./array.js";
+import type { AnyCaller } from "./function.js";
+/** ISO 4217 currency code, e.g. `GBP` or `USD`. */
+export type CurrencyCode = string;
+/** Array of all supported currency codes in this runtime. */
+export declare const CURRENCY_CODES: ImmutableArray<CurrencyCode>;
+/**
+ * Require that a value is a valid ISO 4217 currency code, and return it as a `Currency` type.
+ */
+export declare function getCurrencyCode(value: string): CurrencyCode | undefined;
+/**
+ * Require that a value is a valid ISO 4217 currency code, and return it as a `Currency` type.
+ */
+export declare function requireCurrencyCode(value: string, caller?: AnyCaller): CurrencyCode;
+/**
+ * Get the display symbol used for a currency.
+ *
+ * @throws {RequiredError} If the currency code is malformed or unsupported.
+ *
+ * @example getCurrencySymbol("GBP"); // "£"
+ */
+export declare function getCurrencySymbol(currency: CurrencyCode, caller?: AnyCaller): string;
+/**
+ * Get the "step" value for a currency, i.e. the smallest fractional unit that is used for that currency.
+ * - E.g. `0.01` for USD, `0.001` for some cryptocurrencies, and `1` for JPY.
+ * @throws {RequiredError} If the currency code is malformed or unsupported.
+ */
+export declare function getCurrencyStep(currency: CurrencyCode, caller?: AnyCaller): number;

package/util/currency.js

@@ -0,0 +1,46 @@
+import { RequiredError } from "../error/RequiredError.js";
+/** Array of all supported currency codes in this runtime. */
+export const CURRENCY_CODES = Intl.supportedValuesOf("currency");
+/**
+ * Require that a value is a valid ISO 4217 currency code, and return it as a `Currency` type.
+ */
+export function getCurrencyCode(value) {
+    const currency = value.toUpperCase().trim();
+    return CURRENCY_CODES.includes(currency) ? currency : undefined;
+}
+/**
+ * Require that a value is a valid ISO 4217 currency code, and return it as a `Currency` type.
+ */
+export function requireCurrencyCode(value, caller = requireCurrencyCode) {
+    const currency = getCurrencyCode(value);
+    if (!currency)
+        throw new RequiredError("Unknown currency code", { received: value, caller });
+    return currency;
+}
+function _formatter(currency, caller) {
+    return new Intl.NumberFormat(undefined, {
+        style: "currency",
+        currency: requireCurrencyCode(currency, caller),
+        currencyDisplay: "narrowSymbol",
+    });
+}
+const _isCurrencyNumberPart = ({ type }) => type === "currency";
+/**
+ * Get the display symbol used for a currency.
+ *
+ * @throws {RequiredError} If the currency code is malformed or unsupported.
+ *
+ * @example getCurrencySymbol("GBP"); // "£"
+ */
+export function getCurrencySymbol(currency, caller = getCurrencySymbol) {
+    return _formatter(currency, caller).formatToParts(0).find(_isCurrencyNumberPart)?.value;
+}
+/**
+ * Get the "step" value for a currency, i.e. the smallest fractional unit that is used for that currency.
+ * - E.g. `0.01` for USD, `0.001` for some cryptocurrencies, and `1` for JPY.
+ * @throws {RequiredError} If the currency code is malformed or unsupported.
+ */
+export function getCurrencyStep(currency, caller = getCurrencyStep) {
+    const { minimumFractionDigits = 0 } = _formatter(currency, caller).resolvedOptions();
+    return 1 / 10 ** minimumFractionDigits;
+}

package/util/format.js

@@ -1,5 +1,6 @@
 import { isArray } from "./array.js";
 import { SECOND } from "./constants.js";
+import { requireCurrencyCode } from "./currency.js";
 import { isDate, requireDate } from "./date.js";
 import { getBestTimeUnit, getMilliseconds } from "./duration.js";
 import { getPercent } from "./number.js";
@@ -39,7 +40,7 @@ export function formatUnit(num, unit, options) {
 export function formatCurrency(amount, currency, options) {
     return Intl.NumberFormat(undefined, {
         style: "currency",
-        currency,
+        currency: requireCurrencyCode(currency, formatCurrency),
         ...options,
     }).format(amount);
 }

package/util/index.d.ts

@@ -10,6 +10,7 @@ export * from "./class.js";
 export * from "./color.js";
 export * from "./constants.js";
 export * from "./crypto.js";
+export * from "./currency.js";
 export * from "./data.js";
 export * from "./date.js";
 export * from "./debug.js";

package/util/index.js

@@ -10,6 +10,7 @@ export * from "./class.js";
 export * from "./color.js";
 export * from "./constants.js";
 export * from "./crypto.js";
+export * from "./currency.js";
 export * from "./data.js";
 export * from "./date.js";
 export * from "./debug.js";