shelving 1.168.1 → 1.169.0

package/endpoint/Endpoint.d.ts

@@ -33,8 +33,11 @@ export declare class Endpoint<P, R> {
      * @param callback The endpoint callback function that implements the logic for this endpoint by receiving the payload and returning the response.
      * @param unsafePayload The payload to pass into the callback (will be validated against this endpoint's payload schema).
      * @param request The entire HTTP request that is being handled (payload was possibly extracted from this somehow).
+     *
+     * @throws `Feedback` if the payload is invalid.
+     * @throws `ValueError` if `callback()` returns an invalid result.
      */
-    handle(callback: EndpointCallback<P, R>, unsafePayload: unknown, request: Request): Promise<Response>;
+    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.
@@ -45,13 +48,14 @@ export declare class Endpoint<P, R> {
      * - Validates a payload against this endpoints payload schema
      * - Return an HTTP `Request` that will send it the valid payload to this endpoint.
      *
-     * @throws Feedback if the payload is invalid.
+     * @throws `Feedback` if the payload is invalid.
      */
     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)
-     * @throws ResponseError if the response content is invalid.
+     *
+     * @throws `ResponseError` if the response status is not ok (200-299)
+     * @throws `ResponseError` if the response content is invalid.
      */
     response(response: Response, caller?: AnyCaller): Promise<R>;
     /**
@@ -59,9 +63,9 @@ export declare class Endpoint<P, R> {
      * - Validate the `payload` against this endpoint's payload schema.
      * - Validate the returned response against this endpoint's result schema.
      *
-     * @throws Feedback if the payload is invalid.
-     * @throws ResponseError if the response status is not ok (200-299)
-     * @throws ResponseError if the response content is invalid.
+     * @throws `Feedback` if the payload is invalid.
+     * @throws `ResponseError` if the response status is not ok (200-299)
+     * @throws `ResponseError` if the response content is invalid.
      */
     fetch(payload: P, options?: RequestOptions, caller?: AnyCaller): Promise<R>;
     /** Convert to string, e.g. `GET https://a.com/user/{id}` */

package/endpoint/Endpoint.js

@@ -1,10 +1,11 @@
 import { ResponseError } from "../error/ResponseError.js";
+import { ValueError } from "../error/ValueError.js";
+import { Feedback } from "../feedback/Feedback.js";
 import { UNDEFINED } from "../schema/Schema.js";
 import { assertDictionary } from "../util/dictionary.js";
 import { getMessage } from "../util/error.js";
 import { getRequest, getResponse, getResponseContent } from "../util/http.js";
 import { getPlaceholders, renderTemplate } from "../util/template.js";
-import { getValid } from "../util/validate.js";
 /**
  * An abstract API resource definition, used to specify types for e.g. serverless functions.
  *
@@ -42,16 +43,29 @@ export class Endpoint {
      * @param callback The endpoint callback function that implements the logic for this endpoint by receiving the payload and returning the response.
      * @param unsafePayload The payload to pass into the callback (will be validated against this endpoint's payload schema).
      * @param request The entire HTTP request that is being handled (payload was possibly extracted from this somehow).
+     *
+     * @throws `Feedback` if the payload is invalid.
+     * @throws `ValueError` if `callback()` returns an invalid result.
      */
-    async handle(callback, unsafePayload, request) {
+    async handle(callback, unsafePayload, request, caller = this.handle) {
         // Validate the payload against this endpoint's payload type.
         const payload = this.payload.validate(unsafePayload);
         // Call the callback with the validated payload to get the result.
         const unsafeResult = await callback(payload, request);
-        // Validate the result against this endpoint's result type.
-        const result = getValid(unsafeResult, this.result);
-        // Convert the result to a `Response` object.
-        return getResponse(result);
+        try {
+            // Convert the result to a `Response` object.
+            return getResponse(this.result.validate(unsafeResult));
+        }
+        catch (thrown) {
+            if (thrown instanceof Feedback)
+                throw new ValueError(`Invalid result for ${this.toString()}:\n${thrown.message}`, {
+                    endpoint: this,
+                    callback,
+                    cause: thrown,
+                    caller,
+                });
+            throw thrown;
+        }
     }
     /**
      * Render the URL for this endpoint with the given payload.
@@ -73,15 +87,16 @@ export class Endpoint {
      * - Validates a payload against this endpoints payload schema
      * - Return an HTTP `Request` that will send it the valid payload to this endpoint.
      *
-     * @throws Feedback if the payload is invalid.
+     * @throws `Feedback` if the payload is invalid.
      */
     request(payload, options = {}, caller = this.request) {
         return getRequest(this.method, this.url, this.payload.validate(payload), options, caller);
     }
     /**
      * Validate an HTTP `Response` against this endpoint.
-     * @throws ResponseError if the response status is not ok (200-299)
-     * @throws ResponseError if the response content is invalid.
+     *
+     * @throws `ResponseError` if the response status is not ok (200-299)
+     * @throws `ResponseError` if the response content is invalid.
      */
     async response(response, caller = this.response) {
         // Get the response.
@@ -89,18 +104,30 @@ export class Endpoint {
         const content = await getResponseContent(response, caller);
         // Throw `ResponseError` if the API returns status outside the 200-299 range.
         if (!ok)
-            throw new ResponseError(getMessage(content) ?? `Error ${status}`, { cause: Response, caller });
+            throw new ResponseError(getMessage(content) ?? `Error ${status}`, { code: status, cause: response, caller });
         // Validate the success response.
-        return getValid(content, this.result, ResponseError, caller);
+        try {
+            return this.result.validate(content);
+        }
+        catch (thrown) {
+            if (thrown instanceof Feedback)
+                throw new ResponseError(`Invalid result for ${this.toString()}:\n${thrown.message}`, {
+                    endpoint: this,
+                    code: 422,
+                    cause: thrown,
+                    caller,
+                });
+            throw thrown;
+        }
     }
     /**
      * Perform a fetch to this endpoint.
      * - Validate the `payload` against this endpoint's payload schema.
      * - Validate the returned response against this endpoint's result schema.
      *
-     * @throws Feedback if the payload is invalid.
-     * @throws ResponseError if the response status is not ok (200-299)
-     * @throws ResponseError if the response content is invalid.
+     * @throws `Feedback` if the payload is invalid.
+     * @throws `ResponseError` if the response status is not ok (200-299)
+     * @throws `ResponseError` if the response content is invalid.
      */
     async fetch(payload, options = {}, caller = this.fetch) {
         const response = await fetch(this.request(payload, options, caller));

package/endpoint/util.js

@@ -46,5 +46,5 @@ async function handleEndpoint(endpoint, callback, params, request, caller = hand
     // - If the content is anything else (e.g. string, number, array), return it directly (but you'll have no way to access the other params).
     const payload = content === undefined ? params : isPlainObject(content) ? { ...content, ...params } : content;
     // Call `endpoint.handle()` with the payload and request.
-    return endpoint.handle(callback, payload, request);
+    return endpoint.handle(callback, payload, request, caller);
 }

package/error/RequestError.d.ts

@@ -1,27 +1,28 @@
 import { BaseError, type BaseErrorOptions } from "./BaseError.js";
-/** Error thrown when a request isn't well-formed. */
+/** Options for `RequestError`. */
+interface RequestErrorOptions extends BaseErrorOptions {
+    readonly code?: number;
+}
+/** Throw when a request isn't well-formed or is unacceptable in some way. */
 export declare class RequestError extends BaseError {
-    /** The corresponding HTTP status code for this error, in the range `400-499` */
+    /** HTTP status code for this error, in the range `400-499` */
     readonly code: number;
-    constructor(message?: string, options?: BaseErrorOptions);
+    constructor(message?: string, options?: RequestErrorOptions);
 }
-/** Thrown if an operation failed because the user is not logged in, or the login information is not well-formed. */
+/** Throw if an operation failed because the user is not logged in, or the login information is not well-formed. */
 export declare class UnauthorizedError extends RequestError {
-    readonly code: number;
-    constructor(message?: string, options?: BaseErrorOptions);
+    constructor(message?: string, options?: RequestErrorOptions);
 }
-/** Thrown if the requested content is not found. */
+/** Throw if the requested content is not found. */
 export declare class NotFoundError extends RequestError {
-    readonly code: number;
-    constructor(message?: string, options?: BaseErrorOptions);
+    constructor(message?: string, options?: RequestErrorOptions);
 }
-/** Error thrown when a request is is valid and well-formed, but its actual data is not. */
+/** Throw when a request is valid and well-formed, but its actual data is not. */
 export declare class UnprocessableError extends RequestError {
-    readonly code: number;
-    constructor(message?: string, options?: BaseErrorOptions);
+    constructor(message?: string, options?: RequestErrorOptions);
 }
-/** Thrown if an operation failed because the user is logged in, but does not have sufficient privileges to access this content. */
+/** Throw if an operation failed because the user is logged in, but does not have sufficient privileges to access this content. */
 export declare class ForbiddenError extends RequestError {
-    readonly code: number;
-    constructor(message?: string, options?: BaseErrorOptions);
+    constructor(message?: string, options?: RequestErrorOptions);
 }
+export {};

package/error/RequestError.js

@@ -1,42 +1,39 @@
 import { BaseError } from "./BaseError.js";
-/** Error thrown when a request isn't well-formed. */
+/** Throw when a request isn't well-formed or is unacceptable in some way. */
 export class RequestError extends BaseError {
-    /** The corresponding HTTP status code for this error, in the range `400-499` */
-    code = 400;
+    /** HTTP status code for this error, in the range `400-499` */
+    code;
     constructor(message, options) {
         super(message, { caller: RequestError, ...options });
+        this.code = options?.code ?? 400;
     }
 }
 RequestError.prototype.name = "RequestError";
-/** Thrown if an operation failed because the user is not logged in, or the login information is not well-formed. */
+/** Throw if an operation failed because the user is not logged in, or the login information is not well-formed. */
 export class UnauthorizedError extends RequestError {
-    code = 401;
     constructor(message, options) {
-        super(message, { caller: UnauthorizedError, ...options });
+        super(message, { caller: UnauthorizedError, code: 401, ...options });
     }
 }
 UnauthorizedError.prototype.name = "UnauthorizedError";
-/** Thrown if the requested content is not found. */
+/** Throw if the requested content is not found. */
 export class NotFoundError extends RequestError {
-    code = 404;
     constructor(message, options) {
-        super(message, { caller: NotFoundError, ...options });
+        super(message, { caller: NotFoundError, code: 404, ...options });
     }
 }
 NotFoundError.prototype.name = "NotFoundError";
-/** Error thrown when a request is is valid and well-formed, but its actual data is not. */
+/** Throw when a request is valid and well-formed, but its actual data is not. */
 export class UnprocessableError extends RequestError {
-    code = 422;
     constructor(message, options) {
-        super(message, { caller: UnprocessableError, ...options });
+        super(message, { caller: UnprocessableError, code: 422, ...options });
     }
 }
 UnprocessableError.prototype.name = "UnprocessableError";
-/** Thrown if an operation failed because the user is logged in, but does not have sufficient privileges to access this content. */
+/** Throw if an operation failed because the user is logged in, but does not have sufficient privileges to access this content. */
 export class ForbiddenError extends RequestError {
-    code = 403;
     constructor(message, options) {
-        super(message, { caller: ForbiddenError, ...options });
+        super(message, { caller: ForbiddenError, code: 403, ...options });
     }
 }
 ForbiddenError.prototype.name = "ForbiddenError";

package/error/ResponseError.d.ts

@@ -1,5 +1,12 @@
 import { BaseError, type BaseErrorOptions } from "./BaseError.js";
-/** Error thrown when an HTTP response isn't well-formed. */
+/** Options for `ResponseError`. */
+interface ResponseErrorOptions extends BaseErrorOptions {
+    readonly code?: number;
+}
+/** Error thrown when a received HTTP response isn't OK. */
 export declare class ResponseError extends BaseError {
-    constructor(message?: string, options?: BaseErrorOptions);
+    /** HTTP status code for the response. */
+    readonly code: number;
+    constructor(message?: string, options?: ResponseErrorOptions);
 }
+export {};

package/error/ResponseError.js

@@ -1,8 +1,11 @@
 import { BaseError } from "./BaseError.js";
-/** Error thrown when an HTTP response isn't well-formed. */
+/** Error thrown when a received HTTP response isn't OK. */
 export class ResponseError extends BaseError {
+    /** HTTP status code for the response. */
+    code;
     constructor(message = ResponseError.prototype.message, options) {
         super(message, { caller: ResponseError, ...options });
+        this.code = options?.code ?? 400;
     }
 }
 ResponseError.prototype.name = "ResponseError";

package/package.json

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

package/store/URLStore.d.ts

@@ -1,6 +1,5 @@
-import type { Data } from "../util/data.js";
-import { type PossibleURIParams, type URIParams } from "../util/uri.js";
-import { type PossibleURL, type URL } from "../util/url.js";
+import { type PossibleURIParams, type URIParams, type URIScheme } from "../util/uri.js";
+import { type PossibleURL, type URL, type URLString } from "../util/url.js";
 import { Store } from "./Store.js";
 /** Store a URL, e.g. `https://top.com/a/b/c` */
 export declare class URLStore extends Store<URL> {
@@ -8,10 +7,10 @@ export declare class URLStore extends Store<URL> {
     constructor(url: PossibleURL, base?: PossibleURL);
     set value(url: PossibleURL);
     get value(): URL;
-    get href(): string;
-    set href(href: string);
-    get origin(): string;
-    get protocol(): string;
+    get href(): URLString;
+    set href(href: URLString);
+    get origin(): URLString;
+    get protocol(): URIScheme;
     get username(): string;
     get password(): string;
     get hostname(): string;
@@ -29,7 +28,7 @@ export declare class URLStore extends Store<URL> {
     /** Update a single param in this URL. */
     setParam(key: string, value: unknown): void;
     /** Update several params in this URL. */
-    setParams(params: Data): void;
+    setParams(params: PossibleURIParams): void;
     /** Delete one or more params in this URL. */
     deleteParam(key: string, ...keys: string[]): void;
     /** Delete one or more params in this URL. */

package/util/uri.js

@@ -19,13 +19,14 @@ export function getURI(possible) {
         if (isURI(possible))
             return possible;
         try {
-            return new globalThis.URL(possible);
+            return new globalThis.URL(possible, _BASE);
         }
         catch {
             return undefined;
         }
     }
 }
+const _BASE = typeof document === "object" ? document.baseURI : undefined;
 /** Convert a possible URI to a URI, or throw `RequiredError` if conversion fails. */
 export function requireURI(possible, caller = requireURI) {
     const url = getURI(possible);

package/util/validate.d.ts

@@ -1,6 +1,4 @@
-import type { BaseError, BaseErrorOptions } from "../error/BaseError.js";
 import type { ImmutableArray, PossibleArray } from "./array.js";
-import type { Constructor } from "./class.js";
 import type { Data } from "./data.js";
 import type { ImmutableDictionary } from "./dictionary.js";
 import type { AnyCaller } from "./function.js";
@@ -28,8 +26,10 @@ export type Validators<T extends Data = Data> = {
 export type ValidatorsType<T> = {
     readonly [K in keyof T]: ValidatorType<T[K]>;
 };
-/** Get value that validates against a given `Validator`, or throw `ValueError` */
-export declare function getValid<T>(value: unknown, validator: Validator<T>, ErrorConstructor?: Constructor<BaseError, [string, BaseErrorOptions]>, caller?: AnyCaller): T;
+/** Require a valid value for a given validator, or return `undefined` if the value could not be validated. */
+export declare function getValid<T>(value: unknown, validator: Validator<T>): T | undefined;
+/** Require a valid value for a given validator, or throw `RequiredError` if the value could not be validated. */
+export declare function requireValid<T>(value: unknown, validator: Validator<T>, caller?: AnyCaller): T;
 /**
  * Validate an iterable set of items with a validator.
  *

package/util/validate.js

@@ -1,20 +1,29 @@
-import { ValueError } from "../error/ValueError.js";
+import { RequiredError } from "../error/RequiredError.js";
 import { Feedback, ValueFeedback } from "../feedback/Feedback.js";
 import { isArray } from "./array.js";
 import { getDataProps } from "./data.js";
 import { getDictionaryItems } from "./dictionary.js";
 import { getNamedMessage } from "./error.js";
 import { isIterable } from "./iterate.js";
-/** Get value that validates against a given `Validator`, or throw `ValueError` */
-export function getValid(value, validator, ErrorConstructor = ValueError, caller = getValid) {
+/** Require a valid value for a given validator, or return `undefined` if the value could not be validated. */
+export function getValid(value, validator) {
     try {
         return validator.validate(value);
     }
     catch (thrown) {
-        if (thrown instanceof Feedback) {
-            const { message, ...rest } = thrown;
-            throw new ErrorConstructor(message, { ...rest, cause: thrown, caller });
-        }
+        if (thrown instanceof Feedback)
+            return undefined;
+        throw thrown;
+    }
+}
+/** Require a valid value for a given validator, or throw `RequiredError` if the value could not be validated. */
+export function requireValid(value, validator, caller = requireValid) {
+    try {
+        return validator.validate(value);
+    }
+    catch (thrown) {
+        if (thrown instanceof Feedback)
+            throw new RequiredError(thrown.message, { cause: thrown, caller });
         throw thrown;
     }
 }