shelving 1.185.3 → 1.186.1

package/package.json

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

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.
@@ -23,10 +26,10 @@ export declare class DateSchema extends Schema<string> {
     readonly max: Date | undefined;
     readonly input: DateInputType;
     readonly step: number | undefined;
-    constructor({ one, min, max, value, input, step, ...options }: DateSchemaOptions);
+    format: typeof formatDate;
+    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,12 +8,14 @@ export class DateSchema extends Schema {
     max;
     input;
     step;
-    constructor({ one = "date", min, max, value, 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);
@@ -29,9 +31,6 @@ export class DateSchema extends Schema {
     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/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,6 +7,8 @@ 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> {
@@ -13,7 +16,8 @@ export declare class NumberSchema extends Schema<number> {
     readonly min: number;
     readonly max: number;
     readonly step: number | undefined;
-    constructor({ one, title, min, max, step, value, ...options }: NumberSchemaOptions);
+    format: typeof formatNumber;
+    constructor({ one, title, min, max, step, format, value, ...options }: NumberSchemaOptions);
     validate(value?: unknown): number;
 }
 /** Valid number, e.g. `2048.12345` or `0` zero and a default value of zero. */

package/schema/NumberSchema.js

@@ -7,11 +7,13 @@ export class NumberSchema extends Schema {
     min;
     max;
     step;
-    constructor({ one = "number", title = "Number", min = Number.NEGATIVE_INFINITY, max = Number.POSITIVE_INFINITY, step, value, ...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(value = this.value) {
         const number = getNumber(value);
@@ -19,9 +21,9 @@ export class NumberSchema extends Schema {
             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 ${formatNumber(this.min)}`;
+            throw !number ? "Required" : `Minimum ${this.format(this.min)}`;
         if (stepped > this.max)
-            throw `Maximum ${formatNumber(this.max)}`;
+            throw `Maximum ${this.format(this.max)}`;
         return stepped;
     }
 }

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/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/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";