shelving 1.167.2 → 1.168.1

package/{api → endpoint}/Endpoint.d.ts

@@ -1,15 +1,8 @@
 import { type Schema } from "../schema/Schema.js";
 import type { AnyCaller } from "../util/function.js";
-import type { AbsoluteLink } from "../util/link.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: AbsoluteLink;
+    readonly url: URLString;
     /** Payload schema. */
     readonly payload: Schema<P>;
     /** Result schema. */
     readonly result: Schema<R>;
-    constructor(method: EndpointMethod, url: AbsoluteLink, 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;
 }
@@ -82,34 +75,34 @@ export type EndpointType<X extends Endpoint<unknown, unknown>> = X extends Endpo
  * 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."
  */
-export declare function GET<P, R>(url: AbsoluteLink, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
-export declare function GET<P>(url: AbsoluteLink, payload: Schema<P>): Endpoint<P, undefined>;
-export declare function GET<R>(url: AbsoluteLink, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
+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<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.
  * "The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server.
  */
-export declare function POST<P, R>(url: AbsoluteLink, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
-export declare function POST<P>(url: AbsoluteLink, payload: Schema<P>): Endpoint<P, undefined>;
-export declare function POST<R>(url: AbsoluteLink, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
+export declare function POST<P, R>(url: URLString, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
+export declare function POST<P>(url: URLString, payload: Schema<P>): Endpoint<P, undefined>;
+export declare function POST<R>(url: URLString, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
 /**
  * Represent a PUT request to a specified URL, with validated payload and return types.
  * "The PUT method replaces all current representations of the target resource with the request content."
  */
-export declare function PUT<P, R>(url: AbsoluteLink, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
-export declare function PUT<P>(url: AbsoluteLink, payload: Schema<P>): Endpoint<P, undefined>;
-export declare function PUT<R>(url: AbsoluteLink, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
+export declare function PUT<P, R>(url: URLString, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
+export declare function PUT<P>(url: URLString, payload: Schema<P>): Endpoint<P, undefined>;
+export declare function PUT<R>(url: URLString, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
 /**
  * Represent a PATCH request to a specified URL, with validated payload and return types.
  * "The PATCH method applies partial modifications to a resource."
  */
-export declare function PATCH<P, R>(url: AbsoluteLink, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
-export declare function PATCH<P>(url: AbsoluteLink, payload: Schema<P>): Endpoint<P, undefined>;
-export declare function PATCH<R>(url: AbsoluteLink, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
+export declare function PATCH<P, R>(url: URLString, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
+export declare function PATCH<P>(url: URLString, payload: Schema<P>): Endpoint<P, undefined>;
+export declare function PATCH<R>(url: URLString, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
 /**
  * Represent a DELETE request to a specified URL, with validated payload and return types.
  * "The DELETE method deletes the specified resource."
  */
-export declare function DELETE<P, R>(url: AbsoluteLink, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
-export declare function DELETE<P>(url: AbsoluteLink, payload: Schema<P>): Endpoint<P, undefined>;
-export declare function DELETE<R>(url: AbsoluteLink, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;
+export declare function DELETE<P, R>(url: URLString, payload?: Schema<P>, result?: Schema<R>): Endpoint<P, R>;
+export declare function DELETE<P>(url: URLString, payload: Schema<P>): Endpoint<P, undefined>;
+export declare function DELETE<R>(url: URLString, payload: undefined, result: Schema<R>): Endpoint<undefined, R>;

package/{api → 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 { omitURLParams, withURLParams } from "../util/url.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 = omitURLParams(withURLParams(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(withURLParams(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/{api → endpoint}/util.js

@@ -15,10 +15,9 @@ import { getURL } from "../util/url.js";
  */
 export function handleEndpoints(request, endpoints, caller = handleEndpoints) {
     // Parse the URL of the request.
-    const requestUrl = request.url;
-    const url = getURL(requestUrl);
+    const url = getURL(request.url);
     if (!url)
-        throw new RequestError("Invalid request URL", { received: requestUrl, caller });
+        throw new RequestError("Invalid request URL", { received: request.url, caller });
     const { origin, pathname, searchParams } = url;
     // Iterate over the handlers and return the first one that matches the request.
     for (const { endpoint, callback } of endpoints) {
@@ -33,15 +32,15 @@ export function handleEndpoints(request, endpoints, caller = handleEndpoints) {
         // Make a simple dictionary object from the `{placeholder}` path params and the `?a=123` query params from the URL.
         const combinedParams = searchParams.size ? { ...getDictionary(searchParams), ...pathParams } : pathParams;
         // Get the response by calling the callback.
-        return handleEndpoint(endpoint, callback, combinedParams, request);
+        return handleEndpoint(endpoint, callback, combinedParams, request, caller);
     }
     // No handler matched the request.
-    throw new NotFoundError("No matching endpoint", { received: requestUrl, caller });
+    throw new NotFoundError("No matching endpoint", { received: request.url, caller });
 }
 /** Handle an individual call to an endpoint callback. */
-async function handleEndpoint(endpoint, callback, params, request) {
+async function handleEndpoint(endpoint, callback, params, request, caller = handleEndpoint) {
     // Extract a data object from the request body and validate it against the endpoint's payload type.
-    const content = await getRequestContent(request, handleEndpoints);
+    const content = await getRequestContent(request, caller);
     // If content is undefined, it means the request has no body, so params are the only payload.
     // - If the content is a plain object, merge if with the params.
     // - 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).

package/index.d.ts

@@ -3,8 +3,8 @@
  * - Modules that use peer dependencies, like `shelving/react` and `shelving/firebase/client`
  * - Modules that are for internal use, like `shelving/test`
  */
-export * from "./api/index.js";
 export * from "./db/index.js";
+export * from "./endpoint/index.js";
 export * from "./error/index.js";
 export * from "./feedback/index.js";
 export * from "./markup/index.js";

package/index.js

@@ -3,8 +3,8 @@
  * - Modules that use peer dependencies, like `shelving/react` and `shelving/firebase/client`
  * - Modules that are for internal use, like `shelving/test`
  */
-export * from "./api/index.js";
 export * from "./db/index.js";
+export * from "./endpoint/index.js";
 export * from "./error/index.js";
 export * from "./feedback/index.js";
 // export * from "./firestore/client/index.js"; // Not exported.

package/markup/rule/link.js

@@ -1,16 +1,16 @@
-import { formatURL } from "../../util/format.js";
-import { getLink } from "../../util/link.js";
+import { formatURI } from "../../util/format.js";
 import { getRegExp } from "../../util/regexp.js";
+import { getURI, HTTP_SCHEMES } from "../../util/uri.js";
 import { getURL } from "../../util/url.js";
 import { renderMarkup } from "../render.js";
 import { REACT_ELEMENT_TYPE } from "../util/internal.js";
 import { getMarkupRule } from "../util/rule.js";
 /** Render `<a href="">` if the link is a valid one, or `<a>` (with no `href`) if it isn't. */
 function renderLinkMarkupRule({ groups: { title, href: unsafeHref } }, options, key) {
-    const { base, schemes, hosts, rel } = options;
-    const url = getURL(unsafeHref, base);
-    const href = getLink(url, base, schemes, hosts);
-    const children = title ? renderMarkup(title, options, "link") : url ? formatURL(url) : "";
+    const { base, schemes = HTTP_SCHEMES, rel } = options;
+    const uri = getURL(unsafeHref, base) ?? getURI(unsafeHref);
+    const href = uri && schemes.includes(uri.protocol) ? uri.href : undefined;
+    const children = title ? renderMarkup(title, options, "link") : uri ? formatURI(uri) : "";
     return {
         key,
         $$typeof: REACT_ELEMENT_TYPE,

package/markup/util/options.d.ts

@@ -1,4 +1,5 @@
-import type { AbsoluteLink, LinkHosts, LinkSchemes } from "../../util/link.js";
+import type { URISchemes } from "../../util/uri.js";
+import type { URLString } from "../../util/url.js";
 import type { MarkupRules } from "./rule.js";
 /** The current parsing options (represents the current state of the parsing). */
 export type MarkupOptions = {
@@ -10,19 +11,14 @@ export type MarkupOptions = {
      */
     readonly rel?: string | undefined;
     /**
-     * Set the base URL that any relative links will be relative to
+     * Set the base URL that any relative URLs will be relative to
      * @default `window.location.href` in browser environments, and `undefined` in server environments.
      */
-    readonly base?: AbsoluteLink | undefined;
+    readonly base?: URLString | undefined;
     /**
-     * Valid URL schemes/protocols for links.
+     * Valid URI schemes/protocols for URLs and URIs.
      * @example ["http:", "https:"]
      * @default ["http:", "https:"]
      */
-    readonly schemes?: LinkSchemes | undefined;
-    /**
-     * Valid URL hosts for links.
-     * @example ["google.com", "www.google.com"]
-     */
-    readonly hosts?: LinkHosts | undefined;
+    readonly schemes?: URISchemes | undefined;
 };

package/package.json

@@ -11,7 +11,7 @@
 		"state-management",
 		"query-builder"
 	],
-	"version": "1.167.2",
+	"version": "1.168.1",
 	"repository": "https://github.com/dhoulb/shelving",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"license": "0BSD",
@@ -57,11 +57,11 @@
 		"build:test:unit": "bun test ./dist/**/*.test.js --bail"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.2.6",
+		"@biomejs/biome": "^2.3.8",
 		"@google-cloud/firestore": "^7.11.6",
-		"@types/bun": "^1.3.0",
-		"@types/react": "^19.2.2",
-		"@types/react-dom": "^19.2.2",
+		"@types/bun": "^1.3.3",
+		"@types/react": "^19.2.7",
+		"@types/react-dom": "^19.2.3",
 		"firebase": "^11.10.0",
 		"react": "^19.2.0",
 		"react-dom": "^19.2.0",

package/schema/URISchema.d.ts

@@ -0,0 +1,21 @@
+import { type URISchemes, type URIString } from "../util/uri.js";
+import type { StringSchemaOptions } from "./StringSchema.js";
+import { StringSchema } from "./StringSchema.js";
+/** Allowed options for `URISchema` */
+export interface URISchemaOptions extends Omit<StringSchemaOptions, "input" | "min" | "max" | "multiline"> {
+    readonly schemes?: URISchemes | undefined;
+}
+/**
+ * Type of `StringSchema` that defines a valid URI string.
+ * - Checks URI scheme against a whitelist (always).
+ * - URIs are limited to 512 characters, but generally these won't be data: URIs so this is a reasonable limit.
+ */
+export declare class URISchema extends StringSchema {
+    readonly schemes: URISchemes;
+    constructor({ one, title, schemes, ...options }: URISchemaOptions);
+    validate(unsafeValue: unknown): URIString;
+}
+/** Valid URI string, e.g. `https://www.google.com` */
+export declare const URI_SCHEMA: URISchema;
+/** Valid URI string, e.g. `https://www.google.com`, or `null` */
+export declare const NULLABLE_URI_SCHEMA: import("./NullableSchema.js").NullableSchema<`${string}:${string}`>;

package/schema/URISchema.js

@@ -0,0 +1,38 @@
+import { ValueFeedback } from "../feedback/Feedback.js";
+import { getURI, HTTP_SCHEMES } from "../util/uri.js";
+import { NULLABLE } from "./NullableSchema.js";
+import { StringSchema } from "./StringSchema.js";
+/**
+ * Type of `StringSchema` that defines a valid URI string.
+ * - Checks URI scheme against a whitelist (always).
+ * - URIs are limited to 512 characters, but generally these won't be data: URIs so this is a reasonable limit.
+ */
+export class URISchema extends StringSchema {
+    schemes;
+    constructor({ one = "URI", title = "URI", schemes = HTTP_SCHEMES, ...options }) {
+        super({
+            one,
+            title,
+            ...options,
+            input: "url",
+            min: 1,
+            max: 512,
+            multiline: false,
+        });
+        this.schemes = schemes;
+    }
+    // Override to validate the URI and check the schemes and hosts against the whitelists.
+    validate(unsafeValue) {
+        const str = super.validate(unsafeValue);
+        const uri = getURI(str);
+        if (!uri)
+            throw new ValueFeedback(str ? "Invalid format" : "Required", str);
+        if (this.schemes && !this.schemes.includes(uri.protocol))
+            throw new ValueFeedback("Invalid URI scheme", str);
+        return uri.href;
+    }
+}
+/** Valid URI string, e.g. `https://www.google.com` */
+export const URI_SCHEMA = new URISchema({});
+/** Valid URI string, e.g. `https://www.google.com`, or `null` */
+export const NULLABLE_URI_SCHEMA = NULLABLE(URI_SCHEMA);

package/schema/URLSchema.d.ts

@@ -0,0 +1,24 @@
+import { type URISchemes } from "../util/uri.js";
+import { type URLString } from "../util/url.js";
+import type { StringSchemaOptions } from "./StringSchema.js";
+import { StringSchema } from "./StringSchema.js";
+/** Allowed options for `URLSchema` */
+export interface URLSchemaOptions extends Omit<StringSchemaOptions, "input" | "min" | "max" | "multiline"> {
+    readonly base?: URL | URLString | undefined;
+    readonly schemes?: URISchemes | undefined;
+}
+/**
+ * Type of `StringSchema` that defines a valid URL string.
+ * - Checks URL scheme against a whitelist (always), and checks URL domain against a whitelist (optional).
+ * - URLs are limited to 512 characters, but generally these won't be data: URIs so this is a reasonable limit.
+ */
+export declare class URLSchema extends StringSchema {
+    readonly base: URLString | undefined;
+    readonly schemes: URISchemes;
+    constructor({ one, title, base, schemes, ...options }: URLSchemaOptions);
+    validate(unsafeValue: unknown): URLString;
+}
+/** Valid URL string, e.g. `https://www.google.com` */
+export declare const URL_SCHEMA: URLSchema;
+/** Valid URL string, e.g. `https://www.google.com`, or `null` */
+export declare const NULLABLE_URL_SCHEMA: import("./NullableSchema.js").NullableSchema<`${string}://${string}`>;

package/schema/{LinkSchema.js → URLSchema.js}

@@ -1,18 +1,17 @@
 import { ValueFeedback } from "../feedback/Feedback.js";
-import { getLinkURL } from "../util/link.js";
+import { HTTP_SCHEMES } from "../util/uri.js";
+import { getURL } from "../util/url.js";
 import { NULLABLE } from "./NullableSchema.js";
 import { StringSchema } from "./StringSchema.js";
 /**
- * Type of `StringSchema` that defines a valid URL link.
+ * Type of `StringSchema` that defines a valid URL string.
  * - Checks URL scheme against a whitelist (always), and checks URL domain against a whitelist (optional).
  * - URLs are limited to 512 characters, but generally these won't be data: URIs so this is a reasonable limit.
- * - Falsy values are converted to `""` empty string.
  */
-export class LinkSchema extends StringSchema {
+export class URLSchema extends StringSchema {
     base;
     schemes;
-    hosts;
-    constructor({ one = "link", title = "Link", base, schemes, hosts, ...options }) {
+    constructor({ one = "URL", title = "URL", base, schemes = HTTP_SCHEMES, ...options }) {
         super({
             one,
             title,
@@ -22,20 +21,21 @@ export class LinkSchema extends StringSchema {
             max: 512,
             multiline: false,
         });
-        this.base = base;
+        this.base = getURL(base)?.href;
         this.schemes = schemes;
-        this.hosts = hosts;
     }
-    // Override to clean the URL using builtin helper functions and check the schemes and hosts against the whitelists.
+    // Override to validate the URL and check the schemes and hosts against the whitelists.
     validate(unsafeValue) {
         const str = super.validate(unsafeValue);
-        const url = getLinkURL(str, this.base, this.schemes, this.hosts);
+        const url = getURL(str, this.base);
         if (!url)
             throw new ValueFeedback(str ? "Invalid format" : "Required", str);
+        if (this.schemes && !this.schemes.includes(url.protocol))
+            throw new ValueFeedback("Invalid URL scheme", str);
         return url.href;
     }
 }
-/** Valid link, e.g. `https://www.google.com` */
-export const LINK = new LinkSchema({});
-/** Valid link, e.g. `https://www.google.com`, or `null` */
-export const NULLABLE_LINK = NULLABLE(LINK);
+/** Valid URL string, e.g. `https://www.google.com` */
+export const URL_SCHEMA = new URLSchema({});
+/** Valid URL string, e.g. `https://www.google.com`, or `null` */
+export const NULLABLE_URL_SCHEMA = NULLABLE(URL_SCHEMA);

package/schema/index.d.ts

@@ -10,7 +10,6 @@ export * from "./EmailSchema.js";
 export * from "./EntitySchema.js";
 export * from "./FileSchema.js";
 export * from "./KeySchema.js";
-export * from "./LinkSchema.js";
 export * from "./NullableSchema.js";
 export * from "./NumberSchema.js";
 export * from "./OptionalSchema.js";
@@ -21,4 +20,6 @@ export * from "./SlugSchema.js";
 export * from "./StringSchema.js";
 export * from "./ThroughSchema.js";
 export * from "./TimeSchema.js";
+export * from "./URISchema.js";
+export * from "./URLSchema.js";
 export * from "./UUIDSchema.js";

package/schema/index.js

@@ -1,4 +1,3 @@
-// Field schemas.
 export * from "./ArraySchema.js";
 export * from "./BooleanSchema.js";
 export * from "./ChoiceSchema.js";
@@ -11,7 +10,6 @@ export * from "./EmailSchema.js";
 export * from "./EntitySchema.js";
 export * from "./FileSchema.js";
 export * from "./KeySchema.js";
-export * from "./LinkSchema.js";
 export * from "./NullableSchema.js";
 export * from "./NumberSchema.js";
 export * from "./OptionalSchema.js";
@@ -20,7 +18,8 @@ export * from "./RequiredSchema.js";
 export * from "./Schema.js";
 export * from "./SlugSchema.js";
 export * from "./StringSchema.js";
-// Utility schemas.
 export * from "./ThroughSchema.js";
 export * from "./TimeSchema.js";
+export * from "./URISchema.js";
+export * from "./URLSchema.js";
 export * from "./UUIDSchema.js";

package/store/EndpointStore.d.ts

@@ -0,0 +1,24 @@
+import type { Endpoint } from "../endpoint/Endpoint.js";
+import { NONE } from "../util/constants.js";
+import { Store } from "./Store.js";
+/**
+ * Store object that loads a result from an API endpoint and manages its state.
+ *
+ * @todo Needs support for `EndpointOptions` to set headers etc.
+ */
+export declare class EndpointStore<P, R> extends Store<R> {
+    static CANCELLED: symbol;
+    readonly endpoint: Endpoint<P, R>;
+    private _payload;
+    private _abort;
+    get payload(): P;
+    set payload(next: P);
+    /** Maximum age data can be before a fetch is triggered (defaults to 5 minutes). */
+    maxAge: number;
+    get value(): R;
+    set value(value: R | typeof NONE);
+    constructor(endpoint: Endpoint<P, R>, payload: P);
+    refetch(): Promise<void>;
+    /** Call the API now to fetch the data. */
+    private _call;
+}

package/store/EndpointStore.js

@@ -0,0 +1,74 @@
+import { MINUTE, NONE } from "../util/constants.js";
+import { isDeepEqual } from "../util/equal.js";
+import { Store } from "./Store.js";
+/**
+ * Store object that loads a result from an API endpoint and manages its state.
+ *
+ * @todo Needs support for `EndpointOptions` to set headers etc.
+ */
+export class EndpointStore extends Store {
+    static CANCELLED = Symbol("CANCELLED");
+    endpoint;
+    _payload;
+    _abort = undefined;
+    get payload() {
+        return this._payload;
+    }
+    set payload(next) {
+        const current = this._payload;
+        // Did the payload actually change?
+        if (!isDeepEqual(current, next)) {
+            this._payload = next;
+            // If there's already a fetch in progress, cancel it.
+            if (this._abort) {
+                this._abort.abort(EndpointStore.CANCELLED);
+                this._abort = undefined;
+            }
+            // Trigger a fetch.
+            this._call();
+        }
+    }
+    /** Maximum age data can be before a fetch is triggered (defaults to 5 minutes). */
+    maxAge = 5 * MINUTE;
+    // Override to possibly trigger a fetch when value is read.
+    get value() {
+        // Queue `this.call()` if...
+        // 1. Value is still loading.
+        // 2. Value is stale (older than maxAge).
+        if (this.loading || this.age > this.maxAge)
+            if (!this.reason)
+                this._call();
+        return super.value;
+    }
+    set value(value) {
+        super.value = value;
+    }
+    constructor(endpoint, payload) {
+        super(NONE);
+        this.endpoint = endpoint;
+        this.payload = payload;
+    }
+    refetch() {
+        return this._call();
+    }
+    /** Call the API now to fetch the data. */
+    async _call() {
+        if (this._abort)
+            return; // Already fetching.
+        this.reason = undefined; // Optimistically clear any error.
+        try {
+            this._abort = new AbortController();
+            const value = await this.endpoint.fetch(this._payload, { signal: this._abort.signal });
+            this.value = value;
+        }
+        catch (thrown) {
+            console.error(thrown);
+            if (thrown === EndpointStore.CANCELLED)
+                return; // Cancelled on purpose.
+            this.reason = thrown;
+        }
+        finally {
+            this._abort = undefined;
+        }
+    }
+}

package/store/URLStore.d.ts

@@ -1,5 +1,6 @@
 import type { Data } from "../util/data.js";
-import { type PossibleURL, type PossibleURLParams, type URLParams } from "../util/url.js";
+import { type PossibleURIParams, type URIParams } from "../util/uri.js";
+import { type PossibleURL, type URL } 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> {
@@ -20,7 +21,7 @@ export declare class URLStore extends Store<URL> {
     /** Get the URL params as a string. */
     get search(): string;
     /** Get the URL params as a dictionary. */
-    get params(): URLParams;
+    get params(): URIParams;
     /** Return a single param in this URL, or `undefined` if it could not be found. */
     getParam(key: string): string | undefined;
     /** Require a single param in this URL, or throw `RequiredError` if it could not be found. */
@@ -36,7 +37,7 @@ export declare class URLStore extends Store<URL> {
     /** Return the current URL with an additional param. */
     withParam(key: string, value: unknown): URL;
     /** Return the current URL with an additional param. */
-    withParams(params: PossibleURLParams): URL;
+    withParams(params: PossibleURIParams): URL;
     /** Return the current URL with an additional param. */
     omitParams(...keys: string[]): URL;
     /** Return the current URL with an additional param. */