shelving 1.173.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.173.0",
+	"version": "1.173.1",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/dhoulb/shelving.git"

package/schema/AddressSchema.d.ts

@@ -1,4 +1,4 @@
-import type { AddressData } from "../util/address.js";
+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"> {

package/schema/CountrySchema.d.ts

@@ -1,4 +1,4 @@
-import { type Country } from "../util/country.js";
+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"> {

package/schema/CountrySchema.js

@@ -1,4 +1,4 @@
-import { COUNTRIES, getCountry } from "../util/country.js";
+import { COUNTRIES, getCountry } from "../util/geo.js";
 import { isProp } from "../util/object.js";
 import { ChoiceSchema } from "./ChoiceSchema.js";
 import { NULLABLE } from "./NullableSchema.js";

package/util/{country.d.ts → geo.d.ts}

@@ -258,3 +258,14 @@ export declare function getCountry(value?: unknown): Country | undefined;
 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/{country.js → geo.js}

@@ -276,3 +276,7 @@ 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

@@ -1,4 +1,3 @@
-export * from "./address.js";
 export * from "./ansi.js";
 export * from "./array.js";
 export * from "./async.js";
@@ -10,7 +9,6 @@ export * from "./callback.js";
 export * from "./class.js";
 export * from "./color.js";
 export * from "./constants.js";
-export * from "./country.js";
 export * from "./crypto.js";
 export * from "./data.js";
 export * from "./date.js";
@@ -28,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

@@ -1,4 +1,3 @@
-export * from "./address.js";
 export * from "./ansi.js";
 export * from "./array.js";
 export * from "./async.js";
@@ -10,7 +9,6 @@ export * from "./callback.js";
 export * from "./class.js";
 export * from "./color.js";
 export * from "./constants.js";
-export * from "./country.js";
 export * from "./crypto.js";
 export * from "./data.js";
 export * from "./date.js";
@@ -28,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"... }`

package/util/address.d.ts

@@ -1,12 +0,0 @@
-import { type Country } from "./country.js";
-/** Valid shape for postal 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 lines into a printable string. */
-export declare function formatAddress({ address1, address2, city, state, postcode, country }: AddressData): string;

package/util/address.js

@@ -1,5 +0,0 @@
-import { formatCountry } from "./country.js";
-/** Format address lines into a printable string. */
-export function formatAddress({ address1, address2, city, state, postcode, country }) {
-    return `${address1}\n${address2 ? `${address2}\n` : ""}${city}\n${state}\n${postcode}\n${formatCountry(country)}`;
-}