shelving 1.168.0 → 1.168.1

package/endpoint/Endpoint.d.ts

@@ -1,15 +1,8 @@
 import { type Schema } from "../schema/Schema.js";
 import type { AnyCaller } from "../util/function.js";
+import { type RequestMethod, type RequestOptions } from "../util/http.js";
 import type { URLString } from "../util/url.js";
 import type { EndpointCallback, EndpointHandler } from "./util.js";
-/** HTTP request methods. */
-export type EndpointMethod = EndpointBodyMethod | EndpointHeadMethod;
-/** HTTP request methods that have no body. */
-export type EndpointHeadMethod = "HEAD" | "GET";
-/** HTTP request methods that have a body. */
-export type EndpointBodyMethod = "POST" | "PUT" | "PATCH" | "DELETE";
-/** Configurable options for endpoint. */
-export type EndpointOptions = Omit<RequestInit, "method" | "body">;
 /**
  * An abstract API resource definition, used to specify types for e.g. serverless functions.
  *
@@ -20,14 +13,14 @@ export type EndpointOptions = Omit<RequestInit, "method" | "body">;
  */
 export declare class Endpoint<P, R> {
     /** Endpoint method. */
-    readonly method: EndpointMethod;
+    readonly method: RequestMethod;
     /** Endpoint URL, possibly including placeholders e.g. `https://api.mysite.com/users/{id}` */
     readonly url: URLString;
     /** Payload schema. */
     readonly payload: Schema<P>;
     /** Result schema. */
     readonly result: Schema<R>;
-    constructor(method: EndpointMethod, url: URLString, payload: Schema<P>, result: Schema<R>);
+    constructor(method: RequestMethod, url: URLString, payload: Schema<P>, result: Schema<R>);
     /**
      * Return an `EndpointHandler` for this endpoint.
      *
@@ -54,7 +47,7 @@ export declare class Endpoint<P, R> {
      *
      * @throws Feedback if the payload is invalid.
      */
-    request(payload: P, options?: EndpointOptions, caller?: AnyCaller): Request;
+    request(payload: P, options?: RequestOptions, caller?: AnyCaller): Request;
     /**
      * Validate an HTTP `Response` against this endpoint.
      * @throws ResponseError if the response status is not ok (200-299)
@@ -70,7 +63,7 @@ export declare class Endpoint<P, R> {
      * @throws ResponseError if the response status is not ok (200-299)
      * @throws ResponseError if the response content is invalid.
      */
-    fetch(payload: P, options?: EndpointOptions, caller?: AnyCaller): Promise<R>;
+    fetch(payload: P, options?: RequestOptions, caller?: AnyCaller): Promise<R>;
     /** Convert to string, e.g. `GET https://a.com/user/{id}` */
     toString(): string;
 }

package/endpoint/Endpoint.js

@@ -2,9 +2,8 @@ import { ResponseError } from "../error/ResponseError.js";
 import { UNDEFINED } from "../schema/Schema.js";
 import { assertDictionary } from "../util/dictionary.js";
 import { getMessage } from "../util/error.js";
-import { getResponse, getResponseContent } from "../util/http.js";
+import { getRequest, getResponse, getResponseContent } from "../util/http.js";
 import { getPlaceholders, renderTemplate } from "../util/template.js";
-import { omitURIParams, withURIParams } from "../util/uri.js";
 import { getValid } from "../util/validate.js";
 /**
  * An abstract API resource definition, used to specify types for e.g. serverless functions.
@@ -77,7 +76,7 @@ export class Endpoint {
      * @throws Feedback if the payload is invalid.
      */
     request(payload, options = {}, caller = this.request) {
-        return createRequest(this.method, this.url, this.payload.validate(payload), options, caller);
+        return getRequest(this.method, this.url, this.payload.validate(payload), options, caller);
     }
     /**
      * Validate an HTTP `Response` against this endpoint.
@@ -127,69 +126,3 @@ export function PATCH(url, payload = UNDEFINED, result = UNDEFINED) {
 export function DELETE(url, payload = UNDEFINED, result = UNDEFINED) {
     return new Endpoint("DELETE", url, payload, result);
 }
-/**
- * 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 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 (either as JSON, string, or `FormData`).
- *
- * @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.
- */
-function createRequest(method, url, payload, options = {}, caller = createRequest) {
-    // This is a head request, so ensure the payload is a dictionary object.
-    if (method === "GET" || method === "HEAD") {
-        assertDictionary(payload, caller);
-        return createHeadRequest(method, url, payload, options, caller);
-    }
-    // This is a normal body request.
-    return createBodyRequest(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 createHeadRequest(method, url, params, options = {}, caller = createHeadRequest) {
-    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 });
-    }
-    // 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 createBodyRequest(method, url, body, options = {}, caller = createBodyRequest) {
-    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 createJSONRequest(method, url, body, options);
-    }
-    // `FormData` instances pass through unaltered and will set their own `Content-Type` with complex boundary information.
-    if (body instanceof FormData)
-        return createFormDataRequest(method, url, body, options);
-    if (typeof body === "string")
-        return createTextRequest(method, url, body, options);
-    return createJSONRequest(method, url, body, options); // JSON is the default.
-}
-/** Create a `FormData` request to a URL. */
-function createFormDataRequest(method, url, body, options = {}) {
-    return new Request(url, { ...options, method, body });
-}
-/** Create a plain text request to a URL. */
-function createTextRequest(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 createJSONRequest(method, url, body, { headers, ...options } = {}) {
-    return new Request(url, { ...options, headers: { ...headers, "Content-Type": "application/json" }, method, body: JSON.stringify(body) });
-}

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.168.0",
+	"version": "1.168.1",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",

package/util/http.d.ts

@@ -1,6 +1,8 @@
 import { RequestError } from "../error/RequestError.js";
 import { ResponseError } from "../error/ResponseError.js";
+import { type ImmutableDictionary } from "./dictionary.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). */
 export type RequestHandler = (request: Request) => Response | Promise<Response>;
 export declare function _getMessageJSON(message: Request | Response, MessageError: typeof RequestError | typeof ResponseError, caller: AnyCaller): Promise<unknown>;
@@ -49,3 +51,23 @@ export declare function getResponse(value: unknown): Response;
  * @param debug If `true` include the error message in the response (for debugging), or `false` to return generic error codes (for security).
  */
 export declare function getErrorResponse(reason: unknown, debug?: boolean): Response;
+/** HTTP request methods. */
+export type RequestMethod = RequestBodyMethod | RequestHeadMethod;
+/** HTTP request methods that have no body. */
+export type RequestHeadMethod = "HEAD" | "GET";
+/** HTTP request methods that have a body. */
+export type RequestBodyMethod = "POST" | "PUT" | "PATCH" | "DELETE";
+/** Configurable options for endpoint. */
+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 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.
+ */
+export declare function getRequest(method: RequestHeadMethod, url: URLString, payload: ImmutableDictionary<unknown>, 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,7 +1,10 @@
 import { RequestError } from "../error/RequestError.js";
 import { ResponseError } from "../error/ResponseError.js";
 import { Feedback } from "../feedback/Feedback.js";
+import { assertDictionary } from "./dictionary.js";
 import { isError } from "./error.js";
+import { getPlaceholders, renderTemplate } from "./template.js";
+import { omitURIParams, withURIParams } from "./uri.js";
 export async function _getMessageJSON(message, MessageError, caller) {
     const trimmed = (await message.text()).trim();
     if (!trimmed.length)
@@ -112,3 +115,59 @@ export function getErrorResponse(reason, debug = false) {
     // Otherwise return a generic error message with no details.
     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) {
+    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 });
+    }
+    // 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);
+    }
+    // `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) });
+}