shelving 1.168.2 → 1.170.2

package/README.md

@@ -37,7 +37,7 @@ Shelving does not include code for CommonJS `require()` imports, so using it in
 
 ## Modules
 
-Shelving is created from small individual modules which can be imported individually (using e.g. `import { addProp } from "shelving/object`). Modules marked with `✅` are also re-exported from the main `"shelving"` module.
+Shelving is created from small individual modules which can be imported individually (using e.g. `import { addProp } from "shelving/util/object`). Modules marked with `✅` are also re-exported from the main `"shelving"` module.
 
 @todo Write these docs!
 

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,8 +11,11 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.168.2",
-	"repository": "https://github.com/dhoulb/shelving",
+	"version": "1.170.2",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/dhoulb/shelving.git"
+	},
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
 	"type": "module",

package/store/URLStore.d.ts

@@ -25,14 +25,18 @@ export declare class URLStore extends Store<URL> {
     getParam(key: string): string | undefined;
     /** Require a single param in this URL, or throw `RequiredError` if it could not be found. */
     requireParam(key: string): string | undefined;
-    /** Update a single param in this URL. */
-    setParam(key: string, value: unknown): void;
-    /** Update several params in this URL. */
+    /** Set all params in this URL (all current params are cleared). */
     setParams(params: PossibleURIParams): void;
+    /** Set a single named param in this URL. */
+    setParam(key: string, value: unknown): void;
+    /** Update several params in this URL (merged with current params). */
+    updateParams(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. */
     deleteParams(key: string, ...keys: string[]): void;
+    /** Clear all params from this URL. */
+    clearParams(): void;
     /** Return the current URL with an additional param. */
     withParam(key: string, value: unknown): URL;
     /** Return the current URL with an additional param. */
@@ -41,5 +45,6 @@ export declare class URLStore extends Store<URL> {
     omitParams(...keys: string[]): URL;
     /** Return the current URL with an additional param. */
     omitParam(key: string): URL;
+    equal(a: URL, b: URL): boolean;
     toString(): string;
 }

package/store/URLStore.js

@@ -1,5 +1,5 @@
 import { getGetter, getSetter } from "../util/class.js";
-import { getURIParam, getURIParams, omitURIParams, requireURIParam, withURIParam, withURIParams, } from "../util/uri.js";
+import { clearURIParams, getURIParam, getURIParams, omitURIParams, requireURIParam, withURIParam, withURIParams, } from "../util/uri.js";
 import { getURL, requireURL } from "../util/url.js";
 import { Store } from "./Store.js";
 /** Store a URL, e.g. `https://top.com/a/b/c` */
@@ -62,13 +62,17 @@ export class URLStore extends Store {
     requireParam(key) {
         return requireURIParam(this.value.searchParams, key, getSetter(this, "requireParam"));
     }
-    /** Update a single param in this URL. */
+    /** Set all params in this URL (all current params are cleared). */
+    setParams(params) {
+        this.value = withURIParams(clearURIParams(this.value, this.setParams), params, this.setParams);
+    }
+    /** Set a single named param in this URL. */
     setParam(key, value) {
-        this.value = withURIParam(this.value, key, value, this.setParams);
+        this.value = withURIParam(this.value, key, value, this.setParam);
     }
-    /** Update several params in this URL. */
-    setParams(params) {
-        this.value = withURIParams(this.value, params, this.setParams);
+    /** Update several params in this URL (merged with current params). */
+    updateParams(params) {
+        this.value = withURIParams(this.value, params, this.updateParams);
     }
     /** Delete one or more params in this URL. */
     deleteParam(key, ...keys) {
@@ -78,6 +82,10 @@ export class URLStore extends Store {
     deleteParams(key, ...keys) {
         this.value = omitURIParams(this.value, key, ...keys);
     }
+    /** Clear all params from this URL. */
+    clearParams() {
+        this.value = clearURIParams(this.value, this.clearParams);
+    }
     /** Return the current URL with an additional param. */
     withParam(key, value) {
         return withURIParam(this.value, key, value, this.withParam);
@@ -94,6 +102,10 @@ export class URLStore extends Store {
     omitParam(key) {
         return omitURIParams(this.value, key);
     }
+    // Override `equal()` to just compare the hrefs.
+    equal(a, b) {
+        return a.href === b.href;
+    }
     toString() {
         return this.href;
     }

package/util/uri.d.ts

@@ -63,7 +63,10 @@ export declare function requireURIString(possible: PossibleURI, caller?: AnyCall
 export type URIParams = ImmutableDictionary<string>;
 /** Type for things that can be converted to named URI parameters. */
 export type PossibleURIParams = PossibleURI | URLSearchParams | ImmutableDictionary<unknown>;
-/** Get a set of params for a URI as a dictionary. */
+/**
+ * Get a set of params for a URI as a dictionary.
+ * - Any params with `undefined` value will be ignored.
+ */
 export declare function getURIParams(input: PossibleURIParams, caller?: AnyCaller): URIParams;
 /** Get a single named param from a URI. */
 export declare function getURIParam(input: PossibleURIParams, key: string): string | undefined;
@@ -71,13 +74,17 @@ export declare function getURIParam(input: PossibleURIParams, key: string): stri
 export declare function requireURIParam(input: PossibleURIParams, key: string, caller?: AnyCaller): string;
 /**
  * Return a URI with a new param set (or same URI if no changes were made).
- * - Throws `ValueError` if the value could not be converted to a string.
+ * - Any params with `undefined` value will be ignored.
+ *
+ * @throws `ValueError` if the value could not be converted to a string.
  */
 export declare function withURIParam(url: URL | URLString, key: string, value: unknown, caller?: AnyCaller): URL;
 export declare function withURIParam(url: PossibleURI, key: string, value: unknown, caller?: AnyCaller): URI;
 /**
  * Return a URI with several new params set (or same URI if no changes were made).
- * - Throws `ValueError` if any of the values could not be converted to strings.
+ * - Param with `undefined` value will be ignored.
+ *
+ * @throws `ValueError` if any of the values could not be converted to strings.
  */
 export declare function withURIParams(url: URL | URLString, params: PossibleURIParams, caller?: AnyCaller): URL;
 export declare function withURIParams(url: PossibleURI, params: PossibleURIParams, caller?: AnyCaller): URI;
@@ -86,6 +93,9 @@ export declare function omitURIParams(url: URL | URLString, ...keys: string[]):
 export declare function omitURIParams(url: PossibleURI, ...keys: string[]): URI;
 /** Return a URI without a param (or same URI if no changes were made). */
 export declare const omitURIParam: (url: PossibleURI, key: string) => URI;
+/** Return a URI with no search params (or same URI if no changes were made). */
+export declare function clearURIParams(url: URL | URLString, caller?: AnyCaller): URL;
+export declare function clearURIParams(url: PossibleURI, caller?: AnyCaller): URI;
 /** A single schema for a URL. */
 export type URIScheme = `${string}:`;
 /** List of allowed URI schemes. */

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);
@@ -42,6 +43,7 @@ export function requireURIString(possible, caller = requireURIString) {
 }
 /**
  * Get a set of entries for a set of possible URI params.
+ *- Any params with `undefined` value will be ignored.
  *
  * Note: Not as simple as just converting with `Object.fromEntries()`:
  * 1. When `URLSearchParams` contains multiple values for the same key, calling `params.get()` will return the _first_ value.
@@ -58,6 +60,8 @@ function* getURIEntries(input, caller = getURIParams) {
     else {
         const done = [];
         for (const [key, value] of getDictionaryItems(input)) {
+            if (value === undefined)
+                continue; // Skip undefined.
             if (done.includes(key))
                 continue;
             done.push(key);
@@ -68,7 +72,10 @@ function* getURIEntries(input, caller = getURIParams) {
         }
     }
 }
-/** Get a set of params for a URI as a dictionary. */
+/**
+ * Get a set of params for a URI as a dictionary.
+ * - Any params with `undefined` value will be ignored.
+ */
 export function getURIParams(input, caller = getURIParams) {
     const output = {};
     for (const [key, str] of getURIEntries(input, caller))
@@ -92,6 +99,8 @@ export function requireURIParam(input, key, caller = requireURIParam) {
 }
 export function withURIParam(url, key, value, caller = withURIParam) {
     const input = requireURI(url, caller);
+    if (value === undefined)
+        return input; // Ignore undefined.
     const output = new URI(input);
     const str = getString(value);
     if (str === undefined)
@@ -115,5 +124,13 @@ export function omitURIParams(url, ...keys) {
 }
 /** Return a URI without a param (or same URI if no changes were made). */
 export const omitURIParam = omitURIParams;
+export function clearURIParams(url, caller = clearURIParams) {
+    const input = requireURI(url, caller);
+    if (!input.search.length)
+        return input;
+    const output = new URI(input);
+    output.search = "";
+    return output;
+}
 /** Valid HTTP schemes for a URI. */
 export const HTTP_SCHEMES = ["http:", "https:"];

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;
     }
 }