shelving 1.172.0 → 1.173.1

package/endpoint/Endpoint.d.ts

@@ -1,4 +1,5 @@
 import { type Schema } from "../schema/Schema.js";
+import { type Data } from "../util/data.js";
 import type { AnyCaller } from "../util/function.js";
 import { type RequestMethod, type RequestOptions } from "../util/http.js";
 import type { URLString } from "../util/url.js";
@@ -40,7 +41,10 @@ export declare class Endpoint<P, R> {
     handle(callback: EndpointCallback<P, R>, unsafePayload: unknown, request: Request, caller?: AnyCaller): Promise<Response>;
     /**
      * Render the URL for this endpoint with the given payload.
-     * - URL mioght contain `{placeholder}` values that are replaced with values from the payload.
+     * - URL might contain `{placeholder}` values that are replaced with values from the payload.
+     *
+     * @returns Rendered URL with `{placeholders}` rendered with values from `payload`
+     * @throws {RequiredError} if `{placeholders}` are set in the URL but `payload` is not a data object.
      */
     renderURL(payload: P, caller?: AnyCaller): string;
     /**
@@ -75,12 +79,23 @@ export declare class Endpoint<P, R> {
 export type PayloadType<X extends Endpoint<unknown, unknown>> = X extends Endpoint<infer Y, unknown> ? Y : never;
 /** Extract the result type from a `Endpoint`. */
 export type EndpointType<X extends Endpoint<unknown, unknown>> = X extends Endpoint<unknown, infer Y> ? Y : never;
+/**
+ * Represent a HEAD request to a specified URL, with validated payload and return types.
+ * "The HEAD method requests a representation of the specified resource. Requests using HEAD should only retrieve data and should not contain a request content."
+ *
+ * - Because HEAD requests have no body payload can only be a data object (where props get sent as `{placeholders}` or `?query` params in the URL).
+ */
+export declare function HEAD<P extends Data, R>(url: URLString, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
+export declare function HEAD<P extends Data>(url: URLString, payload: Schema<P>): Endpoint<P, undefined>;
+export declare function HEAD<R>(url: URLString, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
 /**
  * Represent a GET request to a specified URL, with validated payload and return types.
  * "The GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should not contain a request content."
+ *
+ * - Because GET requests have no body payload can only be a data object (where props get sent as `{placeholders}` or `?query` params in the URL).
  */
-export declare function GET<P, R>(url: URLString, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
-export declare function GET<P>(url: URLString, payload: Schema<P>): Endpoint<P, undefined>;
+export declare function GET<P extends Data, R>(url: URLString, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
+export declare function GET<P extends Data>(url: URLString, payload: Schema<P>): Endpoint<P, undefined>;
 export declare function GET<R>(url: URLString, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
 /**
  * Represent a POST request to a specified URL, with validated payload and return types.

package/endpoint/Endpoint.js

@@ -1,10 +1,10 @@
 import { ResponseError } from "../error/ResponseError.js";
 import { ValueError } from "../error/ValueError.js";
 import { UNDEFINED } from "../schema/Schema.js";
-import { assertDictionary } from "../util/dictionary.js";
+import { isData } from "../util/data.js";
 import { getMessage } from "../util/error.js";
 import { getRequest, getResponse, getResponseContent } from "../util/http.js";
-import { getPlaceholders, renderTemplate } from "../util/template.js";
+import { renderTemplate } from "../util/template.js";
 /**
  * An abstract API resource definition, used to specify types for e.g. serverless functions.
  *
@@ -68,18 +68,13 @@ export class Endpoint {
     }
     /**
      * Render the URL for this endpoint with the given payload.
-     * - URL mioght contain `{placeholder}` values that are replaced with values from the payload.
+     * - URL might contain `{placeholder}` values that are replaced with values from the payload.
+     *
+     * @returns Rendered URL with `{placeholders}` rendered with values from `payload`
+     * @throws {RequiredError} if `{placeholders}` are set in the URL but `payload` is not a data object.
      */
     renderURL(payload, caller = this.renderURL) {
-        const { url } = this;
-        // URL has `{placeholders}` to render.
-        const placeholders = getPlaceholders(url);
-        if (placeholders.length) {
-            assertDictionary(payload, caller);
-            return renderTemplate(url, payload, caller);
-        }
-        // URL has no `{placeholders}`
-        return url;
+        return renderTemplate(this.url, isData(payload) ? payload : {}, caller); // Empty object in `renderTemplate()` will throw intended `RequiredError` for missing `{placeholder}`
     }
     /**
      * Get an HTTP `Request` object for this endpoint.
@@ -132,6 +127,9 @@ export class Endpoint {
         return `${this.method} ${this.url}`;
     }
 }
+export function HEAD(url, payload = UNDEFINED, result = UNDEFINED) {
+    return new Endpoint("HEAD", url, payload, result);
+}
 export function GET(url, payload = UNDEFINED, result = UNDEFINED) {
     return new Endpoint("GET", url, payload, result);
 }

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.172.0",
+	"version": "1.173.1",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/dhoulb/shelving.git"

package/schema/AddressSchema.d.ts

@@ -0,0 +1,13 @@
+import type { AddressData } from "../util/geo.js";
+import { DataSchema, type DataSchemaOptions } from "./DataSchema.js";
+/** Allowed options for `AddressSchema` */
+export interface AddressSchemaOptions extends Omit<DataSchemaOptions<AddressData>, "props"> {
+}
+/** Schema that validates a postal address. */
+export declare class AddressSchema extends DataSchema<AddressData> {
+    constructor({ one, title, ...options }?: AddressSchemaOptions);
+}
+/** Valid postal address data. */
+export declare const ADDRESS: AddressSchema;
+/** Valid postal address data, or `null` */
+export declare const NULLABLE_ADDRESS: import("./NullableSchema.js").NullableSchema<AddressData>;

package/schema/AddressSchema.js

@@ -0,0 +1,22 @@
+import { COUNTRY } from "./CountrySchema.js";
+import { DataSchema } from "./DataSchema.js";
+import { NULLABLE } from "./NullableSchema.js";
+import { StringSchema } from "./StringSchema.js";
+const ADDRESS_PROPS = {
+    address1: new StringSchema({ title: "Address 1", max: 60, min: 1 }),
+    address2: new StringSchema({ title: "Address 2", max: 60, min: 0 }),
+    city: new StringSchema({ title: "City", min: 1, max: 60 }),
+    state: new StringSchema({ title: "State", min: 1, max: 60 }),
+    postcode: new StringSchema({ title: "Postcode", min: 1, max: 12, case: "upper" }),
+    country: COUNTRY,
+};
+/** Schema that validates a postal address. */
+export class AddressSchema extends DataSchema {
+    constructor({ one = "address", title = "Address", ...options } = {}) {
+        super({ one, title, props: ADDRESS_PROPS, ...options });
+    }
+}
+/** Valid postal address data. */
+export const ADDRESS = new AddressSchema({});
+/** Valid postal address data, or `null` */
+export const NULLABLE_ADDRESS = NULLABLE(ADDRESS);

package/schema/CountrySchema.d.ts

@@ -0,0 +1,17 @@
+import { type Country } from "../util/geo.js";
+import { ChoiceSchema, type ChoiceSchemaOptions } from "./ChoiceSchema.js";
+/** Allowed options for `CountrySchema` */
+export interface CountrySchemaOptions extends Omit<ChoiceSchemaOptions<Country>, "options" | "value"> {
+    /** Country value, or `"detect"` to resolve from browser language. */
+    readonly value?: Country | "detect";
+}
+/** Schema that validates an ISO country code. */
+export declare class CountrySchema extends ChoiceSchema<Country> {
+    readonly defaultValue: Country | "detect";
+    constructor({ one, title, value, ...options }?: CountrySchemaOptions);
+    validate(unsafeValue?: unknown): Country;
+}
+/** Valid country code, e.g. `GB` (required because falsy values are invalid). */
+export declare const COUNTRY: CountrySchema;
+/** Valid country code, e.g. `GB`, or `null` */
+export declare const NULLABLE_COUNTRY: import("./NullableSchema.js").NullableSchema<"AF" | "AX" | "AL" | "DZ" | "AS" | "AD" | "AO" | "AI" | "AQ" | "AG" | "AR" | "AM" | "AW" | "AU" | "AT" | "AZ" | "BS" | "BH" | "BD" | "BB" | "BY" | "BE" | "BZ" | "BJ" | "BM" | "BT" | "BO" | "BA" | "BW" | "BV" | "BR" | "IO" | "BN" | "BG" | "BF" | "BI" | "KH" | "CM" | "CA" | "CV" | "KY" | "CF" | "TD" | "CL" | "CN" | "CX" | "CC" | "CO" | "KM" | "CG" | "CD" | "CK" | "CR" | "CI" | "HR" | "CU" | "CY" | "CZ" | "DK" | "DJ" | "DM" | "DO" | "EC" | "EG" | "SV" | "GQ" | "ER" | "EE" | "ET" | "FK" | "FO" | "FJ" | "FI" | "FR" | "GF" | "PF" | "TF" | "GA" | "GM" | "GE" | "DE" | "GH" | "GI" | "GR" | "GL" | "GD" | "GP" | "GU" | "GT" | "GG" | "GN" | "GW" | "GY" | "HT" | "HM" | "VA" | "HN" | "HK" | "HU" | "IS" | "IN" | "ID" | "IR" | "IQ" | "IE" | "IM" | "IL" | "IT" | "JM" | "JP" | "JE" | "JO" | "KZ" | "KE" | "KI" | "KR" | "KP" | "KW" | "KG" | "LA" | "LV" | "LB" | "LS" | "LR" | "LY" | "LI" | "LT" | "LU" | "MO" | "MK" | "MG" | "MW" | "MY" | "MV" | "ML" | "MT" | "MH" | "MQ" | "MR" | "MU" | "YT" | "MX" | "FM" | "MD" | "MC" | "MN" | "ME" | "MS" | "MA" | "MZ" | "MM" | "NA" | "NR" | "NP" | "NL" | "AN" | "NC" | "NZ" | "NI" | "NE" | "NG" | "NU" | "NF" | "MP" | "NO" | "OM" | "PK" | "PW" | "PS" | "PA" | "PG" | "PY" | "PE" | "PH" | "PN" | "PL" | "PT" | "PR" | "QA" | "RE" | "RO" | "RU" | "RW" | "BL" | "SH" | "KN" | "LC" | "MF" | "PM" | "VC" | "WS" | "SM" | "ST" | "SA" | "SN" | "RS" | "SC" | "SL" | "SG" | "SK" | "SI" | "SB" | "SO" | "ZA" | "GS" | "ES" | "LK" | "SD" | "SR" | "SJ" | "SZ" | "SE" | "CH" | "SY" | "TW" | "TJ" | "TZ" | "TH" | "TL" | "TG" | "TK" | "TO" | "TT" | "TN" | "TR" | "TM" | "TC" | "TV" | "UG" | "UA" | "AE" | "GB" | "US" | "UM" | "UY" | "UZ" | "VU" | "VE" | "VN" | "VG" | "VI" | "WF" | "EH" | "YE" | "ZM" | "ZW">;

package/schema/CountrySchema.js

@@ -0,0 +1,26 @@
+import { COUNTRIES, getCountry } from "../util/geo.js";
+import { isProp } from "../util/object.js";
+import { ChoiceSchema } from "./ChoiceSchema.js";
+import { NULLABLE } from "./NullableSchema.js";
+/** Schema that validates an ISO country code. */
+export class CountrySchema extends ChoiceSchema {
+    defaultValue;
+    constructor({ one = "country", title = "Country", value = "detect", ...options } = {}) {
+        super({ one, title, options: COUNTRIES, value: value === "detect" ? "GB" : value, ...options });
+        this.defaultValue = value;
+    }
+    validate(unsafeValue = this.defaultValue) {
+        const country = getCountry(unsafeValue);
+        if (country)
+            return super.validate(country);
+        if (unsafeValue === undefined || unsafeValue === null || unsafeValue === "" || unsafeValue === "detect")
+            throw "Required";
+        if (typeof unsafeValue === "string" && isProp(COUNTRIES, unsafeValue.toUpperCase()))
+            return super.validate(unsafeValue.toUpperCase());
+        return super.validate(unsafeValue);
+    }
+}
+/** Valid country code, e.g. `GB` (required because falsy values are invalid). */
+export const COUNTRY = new CountrySchema({});
+/** Valid country code, e.g. `GB`, or `null` */
+export const NULLABLE_COUNTRY = NULLABLE(COUNTRY);

package/schema/DataSchema.d.ts

@@ -6,7 +6,6 @@ import type { SchemaOptions, Schemas } from "./Schema.js";
 import { Schema } from "./Schema.js";
 /** Allowed options for `PropsSchema` (a schema that has props). */
 export interface DataSchemaOptions<T extends Data> extends SchemaOptions {
-    readonly id?: Schema<string>;
     readonly props: Schemas<T>;
     readonly value?: Partial<T> | undefined;
 }

package/schema/index.d.ts

@@ -1,7 +1,9 @@
+export * from "./AddressSchema.js";
 export * from "./ArraySchema.js";
 export * from "./BooleanSchema.js";
 export * from "./ChoiceSchema.js";
 export * from "./ColorSchema.js";
+export * from "./CountrySchema.js";
 export * from "./DataSchema.js";
 export * from "./DateSchema.js";
 export * from "./DateTimeSchema.js";

package/schema/index.js

@@ -1,7 +1,9 @@
+export * from "./AddressSchema.js";
 export * from "./ArraySchema.js";
 export * from "./BooleanSchema.js";
 export * from "./ChoiceSchema.js";
 export * from "./ColorSchema.js";
+export * from "./CountrySchema.js";
 export * from "./DataSchema.js";
 export * from "./DateSchema.js";
 export * from "./DateTimeSchema.js";

package/util/geo.d.ts

@@ -0,0 +1,271 @@
+import type { AnyCaller } from "./function.js";
+/** List of countries by two-letter ISO code. */
+export declare const COUNTRIES: {
+    readonly AF: "Afghanistan";
+    readonly AX: "Aland Islands";
+    readonly AL: "Albania";
+    readonly DZ: "Algeria";
+    readonly AS: "American Samoa";
+    readonly AD: "Andorra";
+    readonly AO: "Angola";
+    readonly AI: "Anguilla";
+    readonly AQ: "Antarctica";
+    readonly AG: "Antigua and Barbuda";
+    readonly AR: "Argentina";
+    readonly AM: "Armenia";
+    readonly AW: "Aruba";
+    readonly AU: "Australia";
+    readonly AT: "Austria";
+    readonly AZ: "Azerbaijan";
+    readonly BS: "Bahamas";
+    readonly BH: "Bahrain";
+    readonly BD: "Bangladesh";
+    readonly BB: "Barbados";
+    readonly BY: "Belarus";
+    readonly BE: "Belgium";
+    readonly BZ: "Belize";
+    readonly BJ: "Benin";
+    readonly BM: "Bermuda";
+    readonly BT: "Bhutan";
+    readonly BO: "Bolivia";
+    readonly BA: "Bosnia and Herzegovina";
+    readonly BW: "Botswana";
+    readonly BV: "Bouvet Island";
+    readonly BR: "Brazil";
+    readonly IO: "British Indian Ocean Territory";
+    readonly BN: "Brunei Darussalam";
+    readonly BG: "Bulgaria";
+    readonly BF: "Burkina Faso";
+    readonly BI: "Burundi";
+    readonly KH: "Cambodia";
+    readonly CM: "Cameroon";
+    readonly CA: "Canada";
+    readonly CV: "Cape Verde";
+    readonly KY: "Cayman Islands";
+    readonly CF: "Central African Republic";
+    readonly TD: "Chad";
+    readonly CL: "Chile";
+    readonly CN: "China";
+    readonly CX: "Christmas Island";
+    readonly CC: "Cocos (Keeling) Islands";
+    readonly CO: "Colombia";
+    readonly KM: "Comoros";
+    readonly CG: "Congo";
+    readonly CD: "Congo, Democratic Republic";
+    readonly CK: "Cook Islands";
+    readonly CR: "Costa Rica";
+    readonly CI: "Cote D'Ivoire";
+    readonly HR: "Croatia";
+    readonly CU: "Cuba";
+    readonly CY: "Cyprus";
+    readonly CZ: "Czech Republic";
+    readonly DK: "Denmark";
+    readonly DJ: "Djibouti";
+    readonly DM: "Dominica";
+    readonly DO: "Dominican Republic";
+    readonly EC: "Ecuador";
+    readonly EG: "Egypt";
+    readonly SV: "El Salvador";
+    readonly GQ: "Equatorial Guinea";
+    readonly ER: "Eritrea";
+    readonly EE: "Estonia";
+    readonly ET: "Ethiopia";
+    readonly FK: "Falkland Islands";
+    readonly FO: "Faroe Islands";
+    readonly FJ: "Fiji";
+    readonly FI: "Finland";
+    readonly FR: "France";
+    readonly GF: "French Guiana";
+    readonly PF: "French Polynesia";
+    readonly TF: "French Southern Territories";
+    readonly GA: "Gabon";
+    readonly GM: "Gambia";
+    readonly GE: "Georgia";
+    readonly DE: "Germany";
+    readonly GH: "Ghana";
+    readonly GI: "Gibraltar";
+    readonly GR: "Greece";
+    readonly GL: "Greenland";
+    readonly GD: "Grenada";
+    readonly GP: "Guadeloupe";
+    readonly GU: "Guam";
+    readonly GT: "Guatemala";
+    readonly GG: "Guernsey";
+    readonly GN: "Guinea";
+    readonly GW: "Guinea-Bissau";
+    readonly GY: "Guyana";
+    readonly HT: "Haiti";
+    readonly HM: "Heard Island & Mcdonald Islands";
+    readonly VA: "Holy See (Vatican City State)";
+    readonly HN: "Honduras";
+    readonly HK: "Hong Kong";
+    readonly HU: "Hungary";
+    readonly IS: "Iceland";
+    readonly IN: "India";
+    readonly ID: "Indonesia";
+    readonly IR: "Iran, Islamic Republic Of";
+    readonly IQ: "Iraq";
+    readonly IE: "Ireland";
+    readonly IM: "Isle of Man";
+    readonly IL: "Israel";
+    readonly IT: "Italy";
+    readonly JM: "Jamaica";
+    readonly JP: "Japan";
+    readonly JE: "Jersey";
+    readonly JO: "Jordan";
+    readonly KZ: "Kazakhstan";
+    readonly KE: "Kenya";
+    readonly KI: "Kiribati";
+    readonly KR: "Korea";
+    readonly KP: "North Korea";
+    readonly KW: "Kuwait";
+    readonly KG: "Kyrgyzstan";
+    readonly LA: "Lao People's Democratic Republic";
+    readonly LV: "Latvia";
+    readonly LB: "Lebanon";
+    readonly LS: "Lesotho";
+    readonly LR: "Liberia";
+    readonly LY: "Libyan Arab Jamahiriya";
+    readonly LI: "Liechtenstein";
+    readonly LT: "Lithuania";
+    readonly LU: "Luxembourg";
+    readonly MO: "Macao";
+    readonly MK: "Macedonia";
+    readonly MG: "Madagascar";
+    readonly MW: "Malawi";
+    readonly MY: "Malaysia";
+    readonly MV: "Maldives";
+    readonly ML: "Mali";
+    readonly MT: "Malta";
+    readonly MH: "Marshall Islands";
+    readonly MQ: "Martinique";
+    readonly MR: "Mauritania";
+    readonly MU: "Mauritius";
+    readonly YT: "Mayotte";
+    readonly MX: "Mexico";
+    readonly FM: "Micronesia, Federated States Of";
+    readonly MD: "Moldova";
+    readonly MC: "Monaco";
+    readonly MN: "Mongolia";
+    readonly ME: "Montenegro";
+    readonly MS: "Montserrat";
+    readonly MA: "Morocco";
+    readonly MZ: "Mozambique";
+    readonly MM: "Myanmar";
+    readonly NA: "Namibia";
+    readonly NR: "Nauru";
+    readonly NP: "Nepal";
+    readonly NL: "Netherlands";
+    readonly AN: "Netherlands Antilles";
+    readonly NC: "New Caledonia";
+    readonly NZ: "New Zealand";
+    readonly NI: "Nicaragua";
+    readonly NE: "Niger";
+    readonly NG: "Nigeria";
+    readonly NU: "Niue";
+    readonly NF: "Norfolk Island";
+    readonly MP: "Northern Mariana Islands";
+    readonly NO: "Norway";
+    readonly OM: "Oman";
+    readonly PK: "Pakistan";
+    readonly PW: "Palau";
+    readonly PS: "Palestinian Territory, Occupied";
+    readonly PA: "Panama";
+    readonly PG: "Papua New Guinea";
+    readonly PY: "Paraguay";
+    readonly PE: "Peru";
+    readonly PH: "Philippines";
+    readonly PN: "Pitcairn";
+    readonly PL: "Poland";
+    readonly PT: "Portugal";
+    readonly PR: "Puerto Rico";
+    readonly QA: "Qatar";
+    readonly RE: "Reunion";
+    readonly RO: "Romania";
+    readonly RU: "Russian Federation";
+    readonly RW: "Rwanda";
+    readonly BL: "Saint Barthelemy";
+    readonly SH: "Saint Helena";
+    readonly KN: "Saint Kitts and Nevis";
+    readonly LC: "Saint Lucia";
+    readonly MF: "Saint Martin";
+    readonly PM: "Saint Pierre and Miquelon";
+    readonly VC: "Saint Vincent and Grenadines";
+    readonly WS: "Samoa";
+    readonly SM: "San Marino";
+    readonly ST: "Sao Tome and Principe";
+    readonly SA: "Saudi Arabia";
+    readonly SN: "Senegal";
+    readonly RS: "Serbia";
+    readonly SC: "Seychelles";
+    readonly SL: "Sierra Leone";
+    readonly SG: "Singapore";
+    readonly SK: "Slovakia";
+    readonly SI: "Slovenia";
+    readonly SB: "Solomon Islands";
+    readonly SO: "Somalia";
+    readonly ZA: "South Africa";
+    readonly GS: "South Georgia and Sandwich Isl.";
+    readonly ES: "Spain";
+    readonly LK: "Sri Lanka";
+    readonly SD: "Sudan";
+    readonly SR: "Suriname";
+    readonly SJ: "Svalbard and Jan Mayen";
+    readonly SZ: "Swaziland";
+    readonly SE: "Sweden";
+    readonly CH: "Switzerland";
+    readonly SY: "Syrian Arab Republic";
+    readonly TW: "Taiwan";
+    readonly TJ: "Tajikistan";
+    readonly TZ: "Tanzania";
+    readonly TH: "Thailand";
+    readonly TL: "Timor-Leste";
+    readonly TG: "Togo";
+    readonly TK: "Tokelau";
+    readonly TO: "Tonga";
+    readonly TT: "Trinidad and Tobago";
+    readonly TN: "Tunisia";
+    readonly TR: "Turkey";
+    readonly TM: "Turkmenistan";
+    readonly TC: "Turks and Caicos Islands";
+    readonly TV: "Tuvalu";
+    readonly UG: "Uganda";
+    readonly UA: "Ukraine";
+    readonly AE: "United Arab Emirates";
+    readonly GB: "United Kingdom";
+    readonly US: "United States";
+    readonly UM: "United States Outlying Islands";
+    readonly UY: "Uruguay";
+    readonly UZ: "Uzbekistan";
+    readonly VU: "Vanuatu";
+    readonly VE: "Venezuela";
+    readonly VN: "Vietnam";
+    readonly VG: "Virgin Islands, British";
+    readonly VI: "Virgin Islands, U.S.";
+    readonly WF: "Wallis and Futuna";
+    readonly EH: "Western Sahara";
+    readonly YE: "Yemen";
+    readonly ZM: "Zambia";
+    readonly ZW: "Zimbabwe";
+};
+/** Country code string. */
+export type Country = keyof typeof COUNTRIES;
+/** Things that can possibly be a country. */
+export type PossibleCountry = Country | "detect";
+/** Parse a country string, or detect a browser country from `navigator.language`. */
+export declare function getCountry(value?: unknown): Country | undefined;
+/** Parse a country string, or detect a browser country from `navigator.language`, or throw `RequiredError` */
+export declare function requireCountry(value?: unknown, caller?: AnyCaller): Country;
+/** Format a country code into its full country name. */
+export declare function formatCountry(country: string): string;
+/** Valid shape for physical address data. */
+export type AddressData = {
+    readonly address1: string;
+    readonly address2: string;
+    readonly city: string;
+    readonly state: string;
+    readonly postcode: string;
+    readonly country: Country;
+};
+/** Format address data into a single multiline string. */
+export declare function formatAddress({ address1, address2, city, state, postcode, country }: AddressData): string;

package/util/geo.js

@@ -0,0 +1,282 @@
+import { RequiredError } from "../error/RequiredError.js";
+import { isProp } from "./object.js";
+/** List of countries by two-letter ISO code. */
+export const COUNTRIES = {
+    AF: "Afghanistan",
+    AX: "Aland Islands",
+    AL: "Albania",
+    DZ: "Algeria",
+    AS: "American Samoa",
+    AD: "Andorra",
+    AO: "Angola",
+    AI: "Anguilla",
+    AQ: "Antarctica",
+    AG: "Antigua and Barbuda",
+    AR: "Argentina",
+    AM: "Armenia",
+    AW: "Aruba",
+    AU: "Australia",
+    AT: "Austria",
+    AZ: "Azerbaijan",
+    BS: "Bahamas",
+    BH: "Bahrain",
+    BD: "Bangladesh",
+    BB: "Barbados",
+    BY: "Belarus",
+    BE: "Belgium",
+    BZ: "Belize",
+    BJ: "Benin",
+    BM: "Bermuda",
+    BT: "Bhutan",
+    BO: "Bolivia",
+    BA: "Bosnia and Herzegovina",
+    BW: "Botswana",
+    BV: "Bouvet Island",
+    BR: "Brazil",
+    IO: "British Indian Ocean Territory",
+    BN: "Brunei Darussalam",
+    BG: "Bulgaria",
+    BF: "Burkina Faso",
+    BI: "Burundi",
+    KH: "Cambodia",
+    CM: "Cameroon",
+    CA: "Canada",
+    CV: "Cape Verde",
+    KY: "Cayman Islands",
+    CF: "Central African Republic",
+    TD: "Chad",
+    CL: "Chile",
+    CN: "China",
+    CX: "Christmas Island",
+    CC: "Cocos (Keeling) Islands",
+    CO: "Colombia",
+    KM: "Comoros",
+    CG: "Congo",
+    CD: "Congo, Democratic Republic",
+    CK: "Cook Islands",
+    CR: "Costa Rica",
+    CI: "Cote D'Ivoire",
+    HR: "Croatia",
+    CU: "Cuba",
+    CY: "Cyprus",
+    CZ: "Czech Republic",
+    DK: "Denmark",
+    DJ: "Djibouti",
+    DM: "Dominica",
+    DO: "Dominican Republic",
+    EC: "Ecuador",
+    EG: "Egypt",
+    SV: "El Salvador",
+    GQ: "Equatorial Guinea",
+    ER: "Eritrea",
+    EE: "Estonia",
+    ET: "Ethiopia",
+    FK: "Falkland Islands",
+    FO: "Faroe Islands",
+    FJ: "Fiji",
+    FI: "Finland",
+    FR: "France",
+    GF: "French Guiana",
+    PF: "French Polynesia",
+    TF: "French Southern Territories",
+    GA: "Gabon",
+    GM: "Gambia",
+    GE: "Georgia",
+    DE: "Germany",
+    GH: "Ghana",
+    GI: "Gibraltar",
+    GR: "Greece",
+    GL: "Greenland",
+    GD: "Grenada",
+    GP: "Guadeloupe",
+    GU: "Guam",
+    GT: "Guatemala",
+    GG: "Guernsey",
+    GN: "Guinea",
+    GW: "Guinea-Bissau",
+    GY: "Guyana",
+    HT: "Haiti",
+    HM: "Heard Island & Mcdonald Islands",
+    VA: "Holy See (Vatican City State)",
+    HN: "Honduras",
+    HK: "Hong Kong",
+    HU: "Hungary",
+    IS: "Iceland",
+    IN: "India",
+    ID: "Indonesia",
+    IR: "Iran, Islamic Republic Of",
+    IQ: "Iraq",
+    IE: "Ireland",
+    IM: "Isle of Man",
+    IL: "Israel",
+    IT: "Italy",
+    JM: "Jamaica",
+    JP: "Japan",
+    JE: "Jersey",
+    JO: "Jordan",
+    KZ: "Kazakhstan",
+    KE: "Kenya",
+    KI: "Kiribati",
+    KR: "Korea",
+    KP: "North Korea",
+    KW: "Kuwait",
+    KG: "Kyrgyzstan",
+    LA: "Lao People's Democratic Republic",
+    LV: "Latvia",
+    LB: "Lebanon",
+    LS: "Lesotho",
+    LR: "Liberia",
+    LY: "Libyan Arab Jamahiriya",
+    LI: "Liechtenstein",
+    LT: "Lithuania",
+    LU: "Luxembourg",
+    MO: "Macao",
+    MK: "Macedonia",
+    MG: "Madagascar",
+    MW: "Malawi",
+    MY: "Malaysia",
+    MV: "Maldives",
+    ML: "Mali",
+    MT: "Malta",
+    MH: "Marshall Islands",
+    MQ: "Martinique",
+    MR: "Mauritania",
+    MU: "Mauritius",
+    YT: "Mayotte",
+    MX: "Mexico",
+    FM: "Micronesia, Federated States Of",
+    MD: "Moldova",
+    MC: "Monaco",
+    MN: "Mongolia",
+    ME: "Montenegro",
+    MS: "Montserrat",
+    MA: "Morocco",
+    MZ: "Mozambique",
+    MM: "Myanmar",
+    NA: "Namibia",
+    NR: "Nauru",
+    NP: "Nepal",
+    NL: "Netherlands",
+    AN: "Netherlands Antilles",
+    NC: "New Caledonia",
+    NZ: "New Zealand",
+    NI: "Nicaragua",
+    NE: "Niger",
+    NG: "Nigeria",
+    NU: "Niue",
+    NF: "Norfolk Island",
+    MP: "Northern Mariana Islands",
+    NO: "Norway",
+    OM: "Oman",
+    PK: "Pakistan",
+    PW: "Palau",
+    PS: "Palestinian Territory, Occupied",
+    PA: "Panama",
+    PG: "Papua New Guinea",
+    PY: "Paraguay",
+    PE: "Peru",
+    PH: "Philippines",
+    PN: "Pitcairn",
+    PL: "Poland",
+    PT: "Portugal",
+    PR: "Puerto Rico",
+    QA: "Qatar",
+    RE: "Reunion",
+    RO: "Romania",
+    RU: "Russian Federation",
+    RW: "Rwanda",
+    BL: "Saint Barthelemy",
+    SH: "Saint Helena",
+    KN: "Saint Kitts and Nevis",
+    LC: "Saint Lucia",
+    MF: "Saint Martin",
+    PM: "Saint Pierre and Miquelon",
+    VC: "Saint Vincent and Grenadines",
+    WS: "Samoa",
+    SM: "San Marino",
+    ST: "Sao Tome and Principe",
+    SA: "Saudi Arabia",
+    SN: "Senegal",
+    RS: "Serbia",
+    SC: "Seychelles",
+    SL: "Sierra Leone",
+    SG: "Singapore",
+    SK: "Slovakia",
+    SI: "Slovenia",
+    SB: "Solomon Islands",
+    SO: "Somalia",
+    ZA: "South Africa",
+    GS: "South Georgia and Sandwich Isl.",
+    ES: "Spain",
+    LK: "Sri Lanka",
+    SD: "Sudan",
+    SR: "Suriname",
+    SJ: "Svalbard and Jan Mayen",
+    SZ: "Swaziland",
+    SE: "Sweden",
+    CH: "Switzerland",
+    SY: "Syrian Arab Republic",
+    TW: "Taiwan",
+    TJ: "Tajikistan",
+    TZ: "Tanzania",
+    TH: "Thailand",
+    TL: "Timor-Leste",
+    TG: "Togo",
+    TK: "Tokelau",
+    TO: "Tonga",
+    TT: "Trinidad and Tobago",
+    TN: "Tunisia",
+    TR: "Turkey",
+    TM: "Turkmenistan",
+    TC: "Turks and Caicos Islands",
+    TV: "Tuvalu",
+    UG: "Uganda",
+    UA: "Ukraine",
+    AE: "United Arab Emirates",
+    GB: "United Kingdom",
+    US: "United States",
+    UM: "United States Outlying Islands",
+    UY: "Uruguay",
+    UZ: "Uzbekistan",
+    VU: "Vanuatu",
+    VE: "Venezuela",
+    VN: "Vietnam",
+    VG: "Virgin Islands, British",
+    VI: "Virgin Islands, U.S.",
+    WF: "Wallis and Futuna",
+    EH: "Western Sahara",
+    YE: "Yemen",
+    ZM: "Zambia",
+    ZW: "Zimbabwe",
+};
+/** Parse a country string, or detect a browser country from `navigator.language`. */
+export function getCountry(value = "detect") {
+    if (value === "detect") {
+        if (typeof navigator === "object") {
+            const code = navigator?.language?.slice(-2).toUpperCase();
+            if (code && isProp(COUNTRIES, code))
+                return code;
+        }
+    }
+    else if (typeof value === "string") {
+        const code = value.toUpperCase();
+        if (code && isProp(COUNTRIES, code))
+            return code;
+    }
+}
+/** Parse a country string, or detect a browser country from `navigator.language`, or throw `RequiredError` */
+export function requireCountry(value, caller = requireCountry) {
+    const country = getCountry(value);
+    if (!country)
+        throw new RequiredError("Must be country", { received: value, caller });
+    return country;
+}
+/** Format a country code into its full country name. */
+export function formatCountry(country) {
+    const code = country.toUpperCase();
+    return isProp(COUNTRIES, code) ? COUNTRIES[code] : country;
+}
+/** Format address data into a single multiline string. */
+export function formatAddress({ address1, address2, city, state, postcode, country }) {
+    return `${address1}\n${address2 ? `${address2}\n` : ""}${city}\n${state}\n${postcode}\n${formatCountry(country)}`;
+}

package/util/http.d.ts

@@ -1,6 +1,6 @@
 import { RequestError } from "../error/RequestError.js";
 import { ResponseError } from "../error/ResponseError.js";
-import { type ImmutableDictionary } from "./dictionary.js";
+import { type Data } from "./data.js";
 import type { AnyCaller } from "./function.js";
 import type { URLString } from "./url.js";
 /** A handler function takes a `Request` and returns a `Response` (possibly asynchronously). */
@@ -62,12 +62,12 @@ export type RequestOptions = Omit<RequestInit, "method" | "body">;
 /**
  * Create a `Request` instance for a method/url and payload.
  *
- * - If `{placeholders}` are set in the URL, they are replaced by values from payload (will throw if `payload` is not a dictionary object).
+ * - If `{placeholders}` are set in the URL, they are replaced by values from payload (will throw if `payload` is not a data object).
  * - If the method is `HEAD` or `GET`, the payload is sent as `?query` parameters in the URL.
  * - If the method is anything else, the payload is sent in the body (plain text string, `FormData` object, or JSON for any other).
  *
- * @throws ValueError if this is a `HEAD` or `GET` request but `body` is not a dictionary object.
- * @throws ValueError if `{placeholders}` are set in the URL but `body` is not a dictionary object.
+ * @throws {RequiredError} if this is a `HEAD` or `GET` request but `payload` is not a data object.
+ * @throws {RequiredError} if `{placeholders}` are set in the URL but `payload` is not a data object.
  */
-export declare function getRequest(method: RequestHeadMethod, url: URLString, payload: ImmutableDictionary<unknown>, options?: RequestOptions, caller?: AnyCaller): Request;
+export declare function getRequest(method: RequestHeadMethod, url: URLString, payload: Data, options?: RequestOptions, caller?: AnyCaller): Request;
 export declare function getRequest(method: RequestMethod, url: URLString, payload: unknown, options?: RequestOptions, caller?: AnyCaller): Request;

package/util/http.js

@@ -1,9 +1,12 @@
 import { RequestError } from "../error/RequestError.js";
+import { RequiredError } from "../error/RequiredError.js";
 import { ResponseError } from "../error/ResponseError.js";
-import { assertDictionary } from "./dictionary.js";
+import { isData } from "./data.js";
 import { isError } from "./error.js";
+import { isNullish } from "./null.js";
+import { omitProps } from "./object.js";
 import { getPlaceholders, renderTemplate } from "./template.js";
-import { omitURIParams, withURIParams } from "./uri.js";
+import { withURIParams } from "./uri.js";
 export async function _getMessageJSON(message, MessageError, caller) {
     const trimmed = (await message.text()).trim();
     if (!trimmed.length)
@@ -115,58 +118,40 @@ export function getErrorResponse(reason, debug = false) {
     return new Response(undefined, { status });
 }
 export function getRequest(method, url, payload, options = {}, caller = getRequest) {
-    // This is a head request, so ensure the payload is a dictionary object.
-    if (method === "GET" || method === "HEAD") {
-        assertDictionary(payload, caller);
-        return getHeadRequest(method, url, payload, options, caller);
-    }
-    // This is a normal body request.
-    return getBodyRequest(method, url, payload, options, caller);
-}
-/**
- * Create a body-less request to a URL.
- * - Any `{placeholders}` in the URL will be rendered with values from `params`, and won't be set in `?query` parameters in the URL.
- */
-function getHeadRequest(method, url, params, options = {}, caller = getHeadRequest) {
+    // Render any `{placeholders}` in the URL string.
     const placeholders = getPlaceholders(url);
-    // URL has `{placeholders}` to render, so rendere those to the URL and add all other params as `?query` params.
     if (placeholders.length) {
-        const rendered = omitURIParams(withURIParams(renderTemplate(url, params, caller), params, caller), ...placeholders);
-        return new Request(rendered, { ...options, method });
+        if (!isData(payload))
+            throw new RequiredError("Payload for request with URL {placeholders} must be data object", { received: payload, caller });
+        url = renderTemplate(url, payload, caller);
+        payload = omitProps(payload, ...placeholders);
     }
-    // URL has no `{placeholders}`, so add all payload params to the URL.
-    return new Request(withURIParams(url, params, caller), { ...options, method });
-}
-/**
- * Create a body request to a URL.
- * - Any `{placeholders}` in the URL will be rendered with values from `data`, and won't be set in the request body.
- * - The payload is sent in the body (either as JSON, string, or `FormData`).
- *
- * @throws ValueError if `{placeholders}` are set in the URL but `body` is not a dictionary object.
- */
-function getBodyRequest(method, url, body, options = {}, caller = getBodyRequest) {
-    const placeholders = getPlaceholders(url);
-    // If `{placeholders}` are set in the URL then body must be a dictionary object and is sent as JSON.
-    if (placeholders.length) {
-        assertDictionary(body, caller);
-        return getJSONRequest(method, renderTemplate(url, body, caller), body, options);
+    // This is a body-less request, so ensure the payload is a data object and set the `?query=params` in the URL.
+    if (method === "GET" || method === "HEAD") {
+        if (!isData(payload))
+            throw new RequiredError(`Payload for ${method} request must be data object`, { received: payload, caller });
+        url = withURIParams(url, payload).href;
+        payload = undefined;
     }
-    // `FormData` instances pass through unaltered and will set their own `Content-Type` with complex boundary information.
-    if (body instanceof FormData)
-        return getFormDataRequest(method, url, body, options);
-    if (typeof body === "string")
-        return getTextRequest(method, url, body, options);
-    return getJSONRequest(method, url, body, options); // JSON is the default.
-}
-/** Create a `FormData` request to a URL. */
-function getFormDataRequest(method, url, body, options = {}) {
-    return new Request(url, { ...options, method, body });
-}
-/** Create a plain text request to a URL. */
-function getTextRequest(method, url, body, { headers, ...options } = {}) {
-    return new Request(url, { ...options, headers: { ...headers, "Content-Type": "text/plain" }, method, body });
-}
-/** Create a JSON request to a URL. */
-function getJSONRequest(method, url, body, { headers, ...options } = {}) {
-    return new Request(url, { ...options, headers: { ...headers, "Content-Type": "application/json" }, method, body: JSON.stringify(body) });
+    // `null` or `undefined` payloads send no body.
+    if (isNullish(payload))
+        return new Request(url, { ...options, method, body: null });
+    // `FormData` instances in body pass through unaltered and will set their own `Content-Type` with complex boundary information
+    if (payload instanceof FormData)
+        return new Request(url, { ...options, method, body: payload });
+    // Strings are sent as plain text.
+    if (typeof payload === "string")
+        return new Request(url, {
+            ...options,
+            headers: { ...options.headers, "Content-Type": "text/plain" },
+            method,
+            body: payload,
+        });
+    // JSON is the default.
+    return new Request(url, {
+        ...options,
+        headers: { ...options.headers, "Content-Type": "application/json" },
+        method,
+        body: JSON.stringify(payload),
+    });
 }

package/util/index.d.ts

@@ -26,6 +26,7 @@ export * from "./filter.js";
 export * from "./focus.js";
 export * from "./format.js";
 export * from "./function.js";
+export * from "./geo.js";
 export * from "./hash.js";
 export * from "./http.js";
 export * from "./hydrate.js";

package/util/index.js

@@ -26,6 +26,7 @@ export * from "./filter.js";
 export * from "./focus.js";
 export * from "./format.js";
 export * from "./function.js";
+export * from "./geo.js";
 export * from "./hash.js";
 export * from "./http.js";
 export * from "./hydrate.js";

package/util/template.d.ts

@@ -13,13 +13,15 @@ import { type NotString, type PossibleString } from "./string.js";
 export type TemplateValues = PossibleString | ImmutableArray<unknown> | ImmutableDictionary<unknown> | ((placeholder: string) => string);
 /** The output of matching a template is a dictionary in `{ myPlaceholder: "value" }` format. */
 export type TemplateMatches = ImmutableDictionary<string>;
+/** List of `{placeholders}` found in a template string. */
+export type TemplatePlaceholders = ImmutableArray<string>;
 /**
  * Get list of placeholders named in a template string.
  *
  * @param template The template including template placeholders, e.g. `:name-${country}/{city}`
  * @returns Array of clean string names of found placeholders, e.g. `["name", "country", "city"]`
  */
-export declare function getPlaceholders(template: string): readonly string[];
+export declare function getPlaceholders(template: string): TemplatePlaceholders;
 /**
  * Match a template against a target string.
  * - Turn ":year-:month" and "2016-06..." etc into `{ year: "2016"... }`