shelving 1.123.0 → 1.124.0

package/db/MemoryProvider.d.ts

@@ -40,7 +40,7 @@ export declare class MemoryTable<T extends Data> {
     /** Times data was last updated. */
     protected readonly _times: Map<string, number>;
     /** Deferred sequence of next values. */
-    readonly _changed: DeferredSequence<void>;
+    readonly next: DeferredSequence<void>;
     getItemTime(id: string): number | undefined;
     getItem(id: string): OptionalItem<T>;
     getItemSequence(id: string): AsyncIterable<OptionalItem<T>>;

package/db/MemoryProvider.js

@@ -84,7 +84,7 @@ export class MemoryTable {
     /** Times data was last updated. */
     _times = new Map();
     /** Deferred sequence of next values. */
-    _changed = new DeferredSequence();
+    next = new DeferredSequence();
     getItemTime(id) {
         return this._times.get(id);
     }
@@ -95,7 +95,7 @@ export class MemoryTable {
         let lastValue = this.getItem(id);
         yield lastValue;
         while (true) {
-            await this._changed;
+            await this.next;
             const nextValue = this.getItem(id);
             if (nextValue !== lastValue) {
                 yield nextValue;
@@ -108,7 +108,7 @@ export class MemoryTable {
         if (typeof lastTime === "number")
             yield this.getItem(id);
         while (true) {
-            await this._changed;
+            await this.next;
             const nextTime = this._times.get(id);
             if (nextTime !== lastTime) {
                 if (typeof nextTime === "number")
@@ -129,7 +129,7 @@ export class MemoryTable {
         if (this._data.get(id) !== item) {
             this._data.set(id, item);
             this._times.set(id, Date.now());
-            this._changed.resolve();
+            this.next.resolve();
         }
     }
     async *setItemSequence(id, sequence) {
@@ -147,7 +147,7 @@ export class MemoryTable {
         if (this._data.has(id)) {
             this._data.delete(id);
             this._times.set(id, Date.now());
-            this._changed.resolve();
+            this.next.resolve();
         }
     }
     getQueryTime(query) {
@@ -163,10 +163,10 @@ export class MemoryTable {
         let lastItems = this.getQuery(query);
         yield lastItems;
         while (true) {
-            await this._changed;
+            await this.next;
             const nextItems = this.getQuery(query);
             if (!isArrayEqual(lastItems, nextItems)) {
-                yield this.getQuery(query);
+                yield nextItems;
                 lastItems = nextItems;
             }
         }
@@ -177,7 +177,7 @@ export class MemoryTable {
         if (typeof lastTime === "number")
             yield this.getQuery(query);
         while (true) {
-            await this._changed;
+            await this.next;
             const nextTime = this._times.get(key);
             if (lastTime !== nextTime) {
                 if (typeof nextTime === "number")
@@ -195,7 +195,7 @@ export class MemoryTable {
         if (changed) {
             const key = _getQueryKey(query);
             this._times.set(key, Date.now());
-            this._changed.resolve();
+            this.next.resolve();
         }
     }
     updateQuery(query, updates) {
@@ -207,7 +207,7 @@ export class MemoryTable {
         if (count) {
             const key = _getQueryKey(query);
             this._times.set(key, Date.now());
-            this._changed.resolve();
+            this.next.resolve();
         }
     }
     deleteQuery(query) {
@@ -219,7 +219,7 @@ export class MemoryTable {
         if (count) {
             const key = _getQueryKey(query);
             this._times.set(key, Date.now());
-            this._changed.resolve();
+            this.next.resolve();
         }
     }
     setItems(items, query) {
@@ -228,7 +228,7 @@ export class MemoryTable {
         if (query) {
             const key = _getQueryKey(query);
             this._times.set(key, Date.now());
-            this._changed.resolve();
+            this.next.resolve();
         }
     }
     async *setItemsSequence(sequence, query) {

package/db/QueryStore.d.ts

@@ -1,12 +1,12 @@
 import type { MemoryProvider } from "./MemoryProvider.js";
 import type { AbstractProvider } from "./Provider.js";
 import type { DataKey, Database } from "../util/data.js";
-import type { Item, ItemQuery, Items, OptionalItem } from "../util/item.js";
+import type { Item, ItemQuery } from "../util/item.js";
 import type { Stop } from "../util/start.js";
+import { ArrayStore } from "../store/ArrayStore.js";
 import { BooleanStore } from "../store/BooleanStore.js";
-import { Store } from "../store/Store.js";
 /** Store a set of multiple items. */
-export declare class QueryStore<T extends Database, K extends DataKey<T>> extends Store<Items<T[K]>> implements Iterable<Item<T[K]>> {
+export declare class QueryStore<T extends Database, K extends DataKey<T>> extends ArrayStore<Item<T[K]>> {
     readonly provider: AbstractProvider<T>;
     readonly collection: K;
     readonly query: ItemQuery<T[K]>;
@@ -15,18 +15,6 @@ export declare class QueryStore<T extends Database, K extends DataKey<T>> extend
     /** Can more items be loaded after the current result. */
     get hasMore(): boolean;
     private _hasMore;
-    /** Get the first item in this store or `null` if this query has no items. */
-    get optionalFirst(): OptionalItem<T[K]>;
-    /** Get the last item in this store or `null` if this query has no items. */
-    get optionalLast(): OptionalItem<T[K]>;
-    /** Get the first item in this store. */
-    get first(): Item<T[K]>;
-    /** Get the last item in this store. */
-    get last(): Item<T[K]>;
-    /** Does the document have at least one result. */
-    get exists(): boolean;
-    /** Get the number of items matching this query. */
-    get count(): number;
     constructor(collection: K, query: ItemQuery<T[K]>, provider: AbstractProvider<T>, memory?: MemoryProvider<T>);
     /** Refresh this store from the source provider. */
     refresh(provider?: AbstractProvider<T>): void;

package/db/QueryStore.js

@@ -1,11 +1,10 @@
+import { ArrayStore } from "../store/ArrayStore.js";
 import { BooleanStore } from "../store/BooleanStore.js";
-import { Store } from "../store/Store.js";
-import { getFirstItem, getLastItem, getOptionalFirstItem, getOptionalLastItem } from "../util/array.js";
 import { NONE } from "../util/constants.js";
 import { getAfterQuery, getLimit } from "../util/query.js";
 import { runSequence } from "../util/sequence.js";
 /** Store a set of multiple items. */
-export class QueryStore extends Store {
+export class QueryStore extends ArrayStore {
     provider;
     collection;
     query;
@@ -16,30 +15,6 @@ export class QueryStore extends Store {
         return this._hasMore;
     }
     _hasMore = false;
-    /** Get the first item in this store or `null` if this query has no items. */
-    get optionalFirst() {
-        return getOptionalFirstItem(this.value);
-    }
-    /** Get the last item in this store or `null` if this query has no items. */
-    get optionalLast() {
-        return getOptionalLastItem(this.value);
-    }
-    /** Get the first item in this store. */
-    get first() {
-        return getFirstItem(this.value);
-    }
-    /** Get the last item in this store. */
-    get last() {
-        return getLastItem(this.value);
-    }
-    /** Does the document have at least one result. */
-    get exists() {
-        return !!this.value.length;
-    }
-    /** Get the number of items matching this query. */
-    get count() {
-        return this.value.length;
-    }
     constructor(collection, query, provider, memory) {
         const time = memory?.getQueryTime(collection, query);
         const items = memory?.getQuery(collection, query) || [];

package/feedback/Feedbacks.js

@@ -1,4 +1,3 @@
-import { indent } from "../util/debug.js";
 import { getProp } from "../util/object.js";
 import { mapDictionary } from "../util/transform.js";
 import { Feedback } from "./Feedback.js";
@@ -11,8 +10,8 @@ export class Feedbacks extends Feedback {
         return mapDictionary(this.feedbacks, getProp, "message");
     }
     constructor(feedbacks, value) {
-        super(`${Object.entries(feedbacks).map(_mapMessages).join("\n")}`, value);
+        const first = Object.values(feedbacks)[0];
+        super(first?.message || "Unknown error", value);
         this.feedbacks = feedbacks;
     }
 }
-const _mapMessages = ([name, { message }]) => `${name}:${indent(message)}`;

package/markup/options.d.ts

@@ -1,16 +1,20 @@
 import type { MarkupRules } from "./rule.js";
+import type { ImmutableArray } from "../util/array.js";
+import type { AbsoluteURI } from "../util/url.js";
 /** The current parsing options (represents the current state of the parsing). */
 export type MarkupOptions = {
     /** The active list of parsing rules. */
     readonly rules: MarkupRules;
     /** The initial context to start parsing in (rules may render their children with a different context). */
     readonly context: string;
-    /** Set the base URL that any relative links will be relative to (defaults to `window.location.href`, if undefined then relative links won't work). */
-    readonly url: string | undefined;
     /** Set the `rel=""` property used for any links (e.g. `rel="nofollow ugc"`). */
     readonly rel: string | undefined;
+    /** Set the base URL that any relative links will be relative to (defaults to `window.location.href`, if undefined then relative links won't work). */
+    readonly base: AbsoluteURI | undefined;
     /** Valid URL schemes/protocols for links (including trailing commas), defaults to `[`http:`, `https:`]` */
-    readonly schemes: string[];
+    readonly schemes: ImmutableArray<string>;
+    /** Valid URL hosts for links (including trailing commas) */
+    readonly hosts: ImmutableArray<string> | undefined;
 };
 /** Default options */
 export declare const MARKUP_OPTIONS: MarkupOptions;

package/markup/options.js

@@ -3,7 +3,8 @@ import { MARKUP_RULES } from "./rules.js";
 export const MARKUP_OPTIONS = {
     context: "block",
     rules: MARKUP_RULES,
-    url: undefined,
     rel: undefined,
+    base: undefined,
     schemes: ["http:", "https:"],
+    hosts: undefined,
 };

package/markup/rule.js

@@ -57,10 +57,10 @@ export class LinkRegExpMarkupRule {
     match(input, options) {
         const match = this.regexp.exec(input);
         if (match) {
-            const { schemes, url: base } = options;
+            const { schemes, base, hosts } = options;
             const { 0: { length }, index, groups: { href, title }, } = match;
             const url = getOptionalURL(href, base);
-            if (url && schemes.includes(url.protocol))
+            if (url && schemes.includes(url.protocol) && (!hosts || !hosts.includes(url.host)))
                 return { index, length, ...this.render(title?.trim() || formatURL(url), url.href, options) };
         }
     }

package/markup/rules.d.ts

@@ -61,13 +61,13 @@ export declare function renderLinkRule(title: string, href: string, { rel }: Mar
     context: string;
 };
 /**
- * Autolinked URL starts with `http:` or `https:` or `mailto:` (any scheme in `options.schemes`) and matches an unlimited number of non-space characters.
+ * Autolinked URL starts with `http:` or `https:` (any scheme in `options.schemes`) and matches an unlimited number of non-space characters.
  * - If followed by space and then text in `()` round or `[]` square brackets that will be used as the title, e.g. `http://google.com/maps (Google Maps)` or `http://google.com/maps [Google Maps]` (this syntax is from Todoist and maybe other things too).
  * - If no title is specified a cleaned up version of the URL will be used, e.g. `google.com/maps`
  * - If link is not valid (using `new URL(url)` then unparsed text will be returned.
  * - For security only schemes that appear in `options.schemes` will match (defaults to `http:` and `https:`).
  */
-export declare const URL_RULE: LinkRegExpMarkupRule;
+export declare const AUTOLINK_RULE: LinkRegExpMarkupRule;
 /**
  * Markdown-style link.
  * - Link in standard Markdown format, e.g. `[Google Maps](http://google.com/maps)`

package/markup/rules.js

@@ -149,13 +149,13 @@ export function renderLinkRule(title, href, { rel }) {
     };
 }
 /**
- * Autolinked URL starts with `http:` or `https:` or `mailto:` (any scheme in `options.schemes`) and matches an unlimited number of non-space characters.
+ * Autolinked URL starts with `http:` or `https:` (any scheme in `options.schemes`) and matches an unlimited number of non-space characters.
  * - If followed by space and then text in `()` round or `[]` square brackets that will be used as the title, e.g. `http://google.com/maps (Google Maps)` or `http://google.com/maps [Google Maps]` (this syntax is from Todoist and maybe other things too).
  * - If no title is specified a cleaned up version of the URL will be used, e.g. `google.com/maps`
  * - If link is not valid (using `new URL(url)` then unparsed text will be returned.
  * - For security only schemes that appear in `options.schemes` will match (defaults to `http:` and `https:`).
  */
-export const URL_RULE = new LinkRegExpMarkupRule(getRegExp(/(?<href>[a-z]+:[-$_@.&!*,=;/#?:%a-zA-Z0-9]+)(?: +(?:\((?<title>[^)]*?)\)))?/), //
+export const AUTOLINK_RULE = new LinkRegExpMarkupRule(getRegExp(/(?<href>[a-z]+:\S+)(?: +(?:\((?<title>[^)]*?)\)))?/), //
 renderLinkRule, ["inline", "list"]);
 /**
  * Markdown-style link.
@@ -165,7 +165,7 @@ renderLinkRule, ["inline", "list"]);
  * - If link is not valid (using `new URL(url)` then unparsed text will be returned.
  * - For security only `http://` or `https://` links will work (if invalid the unparsed text will be returned).
  */
-export const LINK_RULE = new LinkRegExpMarkupRule(getRegExp(/\[(?<title>[^\]]*?)\]\((?<href>[^)]*?)\)/), //
+export const LINK_RULE = new LinkRegExpMarkupRule(getRegExp(/\[(?<title>[^\]]*?)\] *\((?<href>[^)]*?)\)/), //
 renderLinkRule, ["inline", "list"]);
 /**
  * Inline code.
@@ -237,7 +237,7 @@ export const MARKUP_RULES = [
     FENCED_CODE_RULE,
     PARAGRAPH_RULE,
     LINK_RULE,
-    URL_RULE,
+    AUTOLINK_RULE,
     CODE_RULE,
     INLINE_RULE,
     LINEBREAK_RULE,
@@ -257,7 +257,7 @@ export const MARKUP_RULES_BLOCK = [
 /** Subset of markup rules that work in an inline context. */
 export const MARKUP_RULES_INLINE = [
     LINK_RULE,
-    URL_RULE,
+    AUTOLINK_RULE,
     CODE_RULE,
     INLINE_RULE,
     LINEBREAK_RULE,
@@ -269,7 +269,7 @@ export const MARKUP_RULES_SHORTFORM = [
     ORDERED_RULE,
     PARAGRAPH_RULE,
     LINK_RULE,
-    URL_RULE,
+    AUTOLINK_RULE,
     CODE_RULE,
     INLINE_RULE,
     LINEBREAK_RULE,

package/package.json

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

package/react/createDataContext.d.ts

@@ -6,12 +6,6 @@ import type { Optional } from "../util/optional.js";
 import { ItemStore } from "../db/ItemStore.js";
 import { QueryStore } from "../db/QueryStore.js";
 export interface DataContext<T extends Database> {
-    /** Get an `ItemStore` for the specified collection item in the current `DataProvider` context. */
-    useCacheItem<K extends DataKey<T>>(this: void, collection: K, id: string): ItemStore<T, K>;
-    useCacheItem<K extends DataKey<T>>(this: void, collection: Optional<K>, id: Optional<string>): ItemStore<T, K> | undefined;
-    /** Get an `QueryStore` for the specified collection query in the current `DataProvider` context. */
-    useCacheQuery<K extends DataKey<T>>(this: void, collection: K, query: ItemQuery<T[K]>): QueryStore<T, K>;
-    useCacheQuery<K extends DataKey<T>>(this: void, collection: Optional<K>, query: Optional<ItemQuery<T[K]>>): QueryStore<T, K> | undefined;
     /** Get an `ItemStore` for the specified collection item in the current `DataProvider` context and subscribe to any changes in it. */
     useItem<K extends DataKey<T>>(this: void, collection: K, id: string): ItemStore<T, K>;
     useItem<K extends DataKey<T>>(this: void, collection: Optional<K>, id: Optional<string>): ItemStore<T, K> | undefined;

package/react/createDataContext.js

@@ -12,21 +12,17 @@ export function createDataContext(provider) {
     const { CacheContext, useCache } = createCacheContext(); // eslint-disable-line @typescript-eslint/no-explicit-any
     // If this provider is backed by an in-memory cache, pass it to the `ItemStore` and `QueryStore` instances we create.
     const memory = getOptionalSource(CacheProvider, provider)?.memory;
-    const useCacheItem = (collection, id) => {
-        const cache = useCache();
-        const key = collection && id && `${collection}/${id}`;
-        return key ? cache.get(key) || setMapItem(cache, key, new ItemStore(collection, id, provider, memory)) : undefined;
-    };
-    const useCacheQuery = (collection, query) => {
-        const cache = useCache();
-        const key = collection && query && `${collection}?${JSON.stringify(query)}`;
-        return key ? cache.get(key) || setMapItem(cache, key, new QueryStore(collection, query, provider, memory)) : undefined;
-    };
     return {
-        useCacheItem,
-        useCacheQuery,
-        useItem: (collection, id) => useStore(useCacheItem(collection, id)),
-        useQuery: (collection, query) => useStore(useCacheQuery(collection, query)),
+        useItem: (collection, id) => {
+            const cache = useCache();
+            const key = collection && id && `${collection}/${id}`;
+            return useStore(key ? cache.get(key) || setMapItem(cache, key, new ItemStore(collection, id, provider, memory)) : undefined);
+        },
+        useQuery: (collection, query) => {
+            const cache = useCache();
+            const key = collection && query && `${collection}?${JSON.stringify(query)}`;
+            return useStore(key ? cache.get(key) || setMapItem(cache, key, new QueryStore(collection, query, provider, memory)) : undefined);
+        },
         DataContext: CacheContext,
     };
 }

package/schema/DateSchema.js

@@ -6,7 +6,7 @@ import { Schema } from "./Schema.js";
 export class DateSchema extends Schema {
     min;
     max;
-    constructor({ min = null, max = null, title = "Date", value = "now", ...options }) {
+    constructor({ min, max, title = "Date", value = "now", ...options }) {
         super({ title, value, ...options });
         this.min = getOptionalDate(min);
         this.max = getOptionalDate(max);

package/schema/LinkSchema.d.ts

@@ -1,8 +1,10 @@
 import type { StringSchemaOptions } from "./StringSchema.js";
 import type { ImmutableArray } from "../util/array.js";
+import { type AbsoluteURI, type PossibleURL } from "../util/url.js";
 import { StringSchema } from "./StringSchema.js";
 /** Allowed options for `LinkSchema` */
 export interface LinkSchemaOptions extends Omit<StringSchemaOptions, "type" | "min" | "max" | "multiline"> {
+    readonly base?: PossibleURL | undefined;
     readonly schemes?: ImmutableArray<string> | undefined;
     readonly hosts?: ImmutableArray<string> | undefined;
 }
@@ -13,9 +15,10 @@ export interface LinkSchemaOptions extends Omit<StringSchemaOptions, "type" | "m
  * - Falsy values are converted to `""` empty string.
  */
 export declare class LinkSchema extends StringSchema {
+    readonly base: AbsoluteURI | undefined;
     readonly schemes: ImmutableArray<string>;
     readonly hosts: ImmutableArray<string> | undefined;
-    constructor({ schemes, hosts, title, ...options }: LinkSchemaOptions);
+    constructor({ base, schemes, hosts, title, ...options }: LinkSchemaOptions);
     validate(unsafeValue: unknown): string;
 }
 /** Valid link, e.g. `https://www.google.com` */

package/schema/LinkSchema.js

@@ -1,5 +1,5 @@
 import { Feedback } from "../feedback/Feedback.js";
-import { getOptionalURL } from "../util/url.js";
+import { getOptionalAbsoluteURI, getOptionalURL } from "../util/url.js";
 import { OPTIONAL } from "./OptionalSchema.js";
 import { StringSchema } from "./StringSchema.js";
 /**
@@ -9,9 +9,10 @@ import { StringSchema } from "./StringSchema.js";
  * - Falsy values are converted to `""` empty string.
  */
 export class LinkSchema extends StringSchema {
+    base;
     schemes;
     hosts;
-    constructor({ schemes = ["http:", "https:"], hosts, title = "Link", ...options }) {
+    constructor({ base, schemes = ["http:", "https:"], hosts, title = "Link", ...options }) {
         super({
             title,
             ...options,
@@ -20,20 +21,21 @@ export class LinkSchema extends StringSchema {
             max: 512,
             multiline: false,
         });
+        this.base = getOptionalAbsoluteURI(base);
         this.schemes = schemes;
         this.hosts = hosts;
     }
-    // Override to clean the URL using the builtin `URL` class and check the schemes and hosts against the whitelists.
+    // Override to clean the URL using builtin helper functions and check the schemes and hosts against the whitelists.
     validate(unsafeValue) {
         const unsafeString = super.validate(unsafeValue);
-        const optionalURL = getOptionalURL(super.sanitize(unsafeString));
-        if (!optionalURL)
+        const url = getOptionalURL(super.sanitize(unsafeString), this.base);
+        if (!url)
             throw new Feedback(unsafeString ? "Invalid format" : "Required", unsafeString);
-        if (!this.schemes.includes(optionalURL.protocol))
-            throw new Feedback(`Scheme "${optionalURL.protocol}" is not allowed`, unsafeString);
-        if (this.hosts && !this.hosts.includes(optionalURL.host))
-            throw new Feedback(`Domain "${optionalURL.host}" is not allowed`, unsafeString);
-        return optionalURL.href;
+        if (!this.schemes.includes(url.protocol))
+            throw new Feedback(`Scheme "${url.protocol}" is not allowed`, unsafeString);
+        if (this.hosts && !this.hosts.includes(url.host))
+            throw new Feedback(`Domain "${url.host}" is not allowed`, unsafeString);
+        return url.href;
     }
 }
 /** Valid link, e.g. `https://www.google.com` */

package/schema/TimeSchema.js

@@ -12,7 +12,7 @@ export class TimeSchema extends Schema {
      * - Note: `<input type="time">` elements expect `step=""` to be  in _seconds_ so you need to multiply this by `1000`
      */
     step;
-    constructor({ min = null, max = null, step = 60, title = "Time", value = "now", ...options }) {
+    constructor({ min, max, step = 60, title = "Time", value = "now", ...options }) {
         super({ title, value, ...options });
         this.min = getOptionalTime(min);
         this.max = getOptionalTime(max);

package/store/ArrayStore.d.ts

@@ -1,8 +1,19 @@
 import type { ImmutableArray } from "../util/array.js";
+import type { NONE } from "../util/constants.js";
 import { Store } from "./Store.js";
 /** Store an array. */
 export declare class ArrayStore<T> extends Store<ImmutableArray<T>> implements Iterable<T> {
-    constructor(value?: ImmutableArray<T>, time?: number);
+    constructor(value?: ImmutableArray<T> | typeof NONE, time?: number);
+    /** Get the first item in this store or `null` if this query has no items. */
+    get optionalFirst(): T | undefined;
+    /** Get the last item in this store or `null` if this query has no items. */
+    get optionalLast(): T | undefined;
+    /** Get the first item in this store. */
+    get first(): T;
+    /** Get the last item in this store. */
+    get last(): T;
+    /** Does the document have at least one result. */
+    get exists(): boolean;
     /** Get the length of the current value of this store. */
     get count(): number;
     /** Add items to this array. */

package/store/ArrayStore.js

@@ -1,10 +1,30 @@
-import { omitArrayItems, toggleArrayItems, withArrayItems } from "../util/array.js";
+import { getFirstItem, getLastItem, getOptionalFirstItem, getOptionalLastItem, omitArrayItems, toggleArrayItems, withArrayItems } from "../util/array.js";
 import { Store } from "./Store.js";
 /** Store an array. */
 export class ArrayStore extends Store {
     constructor(value = [], time) {
         super(value, time);
     }
+    /** Get the first item in this store or `null` if this query has no items. */
+    get optionalFirst() {
+        return getOptionalFirstItem(this.value);
+    }
+    /** Get the last item in this store or `null` if this query has no items. */
+    get optionalLast() {
+        return getOptionalLastItem(this.value);
+    }
+    /** Get the first item in this store. */
+    get first() {
+        return getFirstItem(this.value);
+    }
+    /** Get the last item in this store. */
+    get last() {
+        return getLastItem(this.value);
+    }
+    /** Does the document have at least one result. */
+    get exists() {
+        return !!this.value.length;
+    }
     /** Get the length of the current value of this store. */
     get count() {
         return this.value.length;

package/util/date.d.ts

@@ -1,3 +1,4 @@
+import type { Optional } from "./optional.js";
 /** Things that converted to dates. */
 export type PossibleDate = Date | number | string;
 /** Is a value a date? */
@@ -5,26 +6,28 @@ export declare function isDate(value: unknown): value is Date;
 /** Assert that a value is a `Date` instance. */
 export declare function assertDate(value: unknown): asserts value is Date;
 /**
- * Convert an unknown value to a valid `Date` instance, or `null` if it couldn't be converted.
+ * Convert an unknown value to a valid `Date` instance, or return `undefined` if it couldn't be converted.
  * - Note: `Date` instances can be invalid (e.g. `new Date("blah blah").getTime()` returns `NaN`). These are detected and will always return `null`
  *
  * Conversion rules:
- * - `Date` instance returns unchanged (BUT if the date isn't valid, `null` is returned).
- * - `null` or `""` empty string or the string `"none"` returns `undefined`
- * - `undefined` returns the current date (e.g. `new Date()`).
+ * - `Date` instance returns unchanged (BUT if the date isn't valid, `undefined` is returned).
+ * - `null` or `undefined` or `""` empty string returns `undefined`
  * - The string `"now"` returns the current date (e.g. `new Date()`).
  * - The string `"today"` returns the current date at midnight (e.g. `getMidnight()`).
  * - The string `"tomorrow"` returns tomorrow's date at midnight (e.g. `addDays(getMidnight(), 1)`).
  * - The string `"yesterday"` returns yesterday's date at midnight (e.g. `addDays(getMidnight(), 1)`).
  * - Strings (e.g. `"2003-09-12"` or `"2003 feb 20:09"`) return the corresponding date (using `new Date(string)`).
  * - Numbers are return the corresponding date (using `new Date(number)`, i.e. milliseconds since 01/01/1970).
- * - Anything else is converted to `null`
+ * - Anything else returns `undefined`
  *
- * @param possible Any value that we want to parse as a valid date.
+ * @param possible Any value that we want to parse as a valid date (defaults to `undefined`).
  * @returns `Date` instance if the value could be converted to a valid date, and `null` if not.
  */
-export declare function getOptionalDate(possible?: unknown): Date | undefined;
-/** Convert a possible date to a `Date` instance, or throw `ValueError` if it couldn't be converted. */
+export declare function getOptionalDate(possible: unknown): Date | undefined;
+/**
+ * Convert a possible date to a `Date` instance, or throw `ValueError` if it couldn't be converted.
+ * @param possible Any value that we want to parse as a valid date (defaults to `"now"`).
+ */
 export declare function getDate(possible?: PossibleDate): Date;
 /** Convert an unknown value to a timestamp (milliseconds past Unix epoch), or `undefined` if it couldn't be converted. */
 export declare function getOptionalTimestamp(possible: unknown): number | undefined;
@@ -33,7 +36,7 @@ export declare function getTimestamp(possible?: PossibleDate): number;
 /** Convert an unknown value to a YMD date string like "2015-09-12", or `undefined` if it couldn't be converted. */
 export declare function getOptionalYMD(possible: unknown): string | undefined;
 /** Convert a `Date` instance to a YMD string like "2015-09-12", or throw `ValueError` if it couldn't be converted.  */
-export declare function getYMD(possible?: PossibleDate): string;
+export declare function getYMD(possible: PossibleDate): string;
 /** List of day-of-week strings. */
 export declare const DAYS: readonly ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
 /** Type listing day-of-week strings. */
@@ -76,4 +79,4 @@ export declare function isToday(target: PossibleDate, current?: PossibleDate): b
 /** Format a date in the browser locale. */
 export declare function formatDate(date: PossibleDate): string;
 /** Format an optional time as a string. */
-export declare function formatOptionalDate(date?: unknown): string | undefined;
+export declare function formatOptionalDate(date: Optional<PossibleDate>): string | undefined;

package/util/date.js

@@ -9,26 +9,25 @@ export function assertDate(value) {
         throw new ValueError(`Must be date`, value);
 }
 /**
- * Convert an unknown value to a valid `Date` instance, or `null` if it couldn't be converted.
+ * Convert an unknown value to a valid `Date` instance, or return `undefined` if it couldn't be converted.
  * - Note: `Date` instances can be invalid (e.g. `new Date("blah blah").getTime()` returns `NaN`). These are detected and will always return `null`
  *
  * Conversion rules:
- * - `Date` instance returns unchanged (BUT if the date isn't valid, `null` is returned).
- * - `null` or `""` empty string or the string `"none"` returns `undefined`
- * - `undefined` returns the current date (e.g. `new Date()`).
+ * - `Date` instance returns unchanged (BUT if the date isn't valid, `undefined` is returned).
+ * - `null` or `undefined` or `""` empty string returns `undefined`
  * - The string `"now"` returns the current date (e.g. `new Date()`).
  * - The string `"today"` returns the current date at midnight (e.g. `getMidnight()`).
  * - The string `"tomorrow"` returns tomorrow's date at midnight (e.g. `addDays(getMidnight(), 1)`).
  * - The string `"yesterday"` returns yesterday's date at midnight (e.g. `addDays(getMidnight(), 1)`).
  * - Strings (e.g. `"2003-09-12"` or `"2003 feb 20:09"`) return the corresponding date (using `new Date(string)`).
  * - Numbers are return the corresponding date (using `new Date(number)`, i.e. milliseconds since 01/01/1970).
- * - Anything else is converted to `null`
+ * - Anything else returns `undefined`
  *
- * @param possible Any value that we want to parse as a valid date.
+ * @param possible Any value that we want to parse as a valid date (defaults to `undefined`).
  * @returns `Date` instance if the value could be converted to a valid date, and `null` if not.
  */
-export function getOptionalDate(possible = "now") {
-    if (possible === null)
+export function getOptionalDate(possible) {
+    if (possible === undefined || possible === null || possible === "")
         return undefined;
     if (possible === "now")
         return new Date();
@@ -46,8 +45,11 @@ export function getOptionalDate(possible = "now") {
             return date;
     }
 }
-/** Convert a possible date to a `Date` instance, or throw `ValueError` if it couldn't be converted. */
-export function getDate(possible) {
+/**
+ * Convert a possible date to a `Date` instance, or throw `ValueError` if it couldn't be converted.
+ * @param possible Any value that we want to parse as a valid date (defaults to `"now"`).
+ */
+export function getDate(possible = "now") {
     const date = getOptionalDate(possible);
     if (!date)
         throw new ValueError(`Invalid date`, possible);

package/util/path.d.ts

@@ -1,3 +1,4 @@
+import { type Optional } from "./optional.js";
 /** Absolute path starts with `/` slash. */
 export type AbsolutePath = `/` | `/${string}`;
 /** Relative path starts with `./` or `../` */
@@ -9,23 +10,25 @@ export declare function isAbsolutePath(path: string): path is AbsolutePath;
 /** Is a string path an absolute path? */
 export declare function isRelativePath(path: string): path is RelativePath;
 /**
- * Clean a path.
- * - Runs of `//` two or more slashes are normalised to `/` single slash, e.g. `/a//b` becomes `/a/b`
- * - `\` Windows slashes are nromalised to `/` UNIX slashes.
- * - Trailing slashes are removed, e.g. `/a/b/` becomes `/a/b`
+ * Resolve a relative or absolute path and return the path, or `undefined` if not a valid path.
+ * - Uses `new URL` to do path processing, so URL strings e.g.
+ * - Returned paths are cleaned with `cleanPath()` so runs of slashes and trailing slashes are removed.
+ *
+ * @param possible Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
+ * @param base Absolute path used for resolving relative paths in `possible`
+ * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
  */
-export declare function cleanPath(path: AbsolutePath): AbsolutePath;
-export declare function cleanPath(path: string): string;
+export declare function getOptionalPath(possible: Optional<string | URL>, base?: AbsolutePath | undefined): AbsolutePath | undefined;
 /**
- * Resolve an absolute path.
- * - Uses `new URL` to do path processing, so URL strings e.g.
+ * Resolve a relative or absolute path and return the path, or throw `ValueError` if not a valid path.
+ * - Internally uses `new URL` to do path processing but shouldn't ever reveal that fact.
  * - Returned paths are cleaned with `cleanPath()` so runs of slashes and trailing slashes are removed.
  *
- * @param path Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
- * @param base Absolute path or `URL` instance used for resolving relative paths in `path`
+ * @param possible Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
+ * @param base Absolute path used for resolving relative paths in `possible`
  * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
  */
-export declare function getPath(path: string | URL, base?: AbsolutePath | URL | Location): AbsolutePath;
+export declare function getPath(possible: string, base?: AbsolutePath): AbsolutePath;
 /** Is a target path active? */
 export declare function isPathActive(target: AbsolutePath, current: AbsolutePath): boolean;
 /** Is a target path proud (i.e. is the current path, or is a child of the current path)? */

package/util/path.js

@@ -1,4 +1,5 @@
 import { ValueError } from "../error/ValueError.js";
+import { notOptional } from "./optional.js";
 /** Is a string path an absolute path? */
 export function isAbsolutePath(path) {
     return path.startsWith("/");
@@ -7,29 +8,47 @@ export function isAbsolutePath(path) {
 export function isRelativePath(path) {
     return path.startsWith("./") || path.startsWith("../");
 }
-export function cleanPath(path) {
+function _cleanPath(path) {
     return path
         .replace(/[/\\]+/g, "/") // Normalise slashes.
         .replace(/(?!^)\/$/g, ""); // Trailing slashes.
 }
 /**
- * Resolve an absolute path.
+ * Resolve a relative or absolute path and return the path, or `undefined` if not a valid path.
  * - Uses `new URL` to do path processing, so URL strings e.g.
  * - Returned paths are cleaned with `cleanPath()` so runs of slashes and trailing slashes are removed.
  *
- * @param path Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
- * @param base Absolute path or `URL` instance used for resolving relative paths in `path`
+ * @param possible Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
+ * @param base Absolute path used for resolving relative paths in `possible`
  * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
  */
-export function getPath(path, base = _LOCATION) {
-    try {
-        return cleanPath(new URL(path, `http://j.com${typeof base === "string" ? base : base.pathname}/`).pathname);
-    }
-    catch {
-        throw new ValueError("Invalid path", path);
+export function getOptionalPath(possible, base = "/") {
+    if (notOptional(possible)) {
+        try {
+            const { pathname, search, hash } = new URL(possible, `http://j.com${base}/`);
+            if (isAbsolutePath(pathname))
+                return `${_cleanPath(pathname)}${search}${hash}`;
+        }
+        catch {
+            //
+        }
     }
 }
-const _LOCATION = typeof window === "object" ? window.location : "/";
+/**
+ * Resolve a relative or absolute path and return the path, or throw `ValueError` if not a valid path.
+ * - Internally uses `new URL` to do path processing but shouldn't ever reveal that fact.
+ * - Returned paths are cleaned with `cleanPath()` so runs of slashes and trailing slashes are removed.
+ *
+ * @param possible Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
+ * @param base Absolute path used for resolving relative paths in `possible`
+ * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
+ */
+export function getPath(possible, base) {
+    const path = getOptionalPath(possible, base);
+    if (!path)
+        throw new ValueError("Invalid URL", possible);
+    return path;
+}
 /** Is a target path active? */
 export function isPathActive(target, current) {
     return target === current;

package/util/time.d.ts

@@ -1,7 +1,8 @@
+import type { Optional } from "./optional.js";
 /** Class representing a time in the day in 24 hour format in the user's current locale. */
 export declare class Time {
     /** Make a new `Time` instance from a time string. */
-    static from(possible?: unknown): Time | undefined;
+    static from(possible: unknown): Time | undefined;
     readonly time: number;
     constructor(time: number);
     /** Get the number of hours in this time. */
@@ -28,27 +29,24 @@ export declare class Time {
     valueOf(): number;
     toString(): string;
 }
-/** Regular expression that matches a time in ISO 8601 format. */
-export declare const TIME_REGEXP: RegExp;
 /** Things that converted to times. */
 export type PossibleTime = Time | Date | number | string;
 /** Is an unknown value a `Time` instance. */
 export declare function isTime(value: unknown): value is Time;
 /**
- * Convert a value to a `Time` instance or `undefined`
+ * Convert a value to a `Time` instance, or return `undefined` if it couldn't be converted.
  * - Works with possible dates, e.g. `now` or `Date` or `2022-09-12 18:32` or `19827263567`
  * - Works with time strings, e.g. `18:32` or `23:59:59.999`
+ *
+ * @param possible Any value that we want to parse as a valid time (defaults to `undefined`).
  */
 export declare function getOptionalTime(possible: unknown): Time | undefined;
-/** Convert a possible time to a `Time` instance, or throw `ValueError` if it couldn't be converted. */
+/**
+ * Convert a possible date to a `Time` instance, or throw `ValueError` if it couldn't be converted (defaults to `"now"`).
+ * @param possible Any value that we want to parse as a valid time (defaults to `"now"`).
+ */
 export declare function getTime(possible?: PossibleTime): Time;
-/** Get the time as in `hh:mm` format (hours, minutes), e.g. `13.59` */
-export declare function getShortTime(time?: PossibleTime): string;
-/** Get the time in `hh:mm:ss` format (hours, minutes seconds), e.g. `13.16.19.123` */
-export declare function getMediumTime(time?: PossibleTime): string;
-/** Get this time in `hh:mm:ss.fff` format (ISO 8601 compatible, hours, minutes, seconds, milliseconds), e.g. `13:16:19.123` */
-export declare function getLongTime(time?: PossibleTime): string;
 /** Format a time as a string based on the browser locale settings. */
 export declare function formatTime(time?: PossibleTime, precision?: 2 | 3 | 4 | 5 | 6): string;
 /** Format an optional time as a string based on the browser locale settings. */
-export declare function formatOptionalTime(time?: unknown, precision?: 2 | 3 | 4 | 5 | 6): string | undefined;
+export declare function formatOptionalTime(time: Optional<PossibleTime>, precision?: 2 | 3 | 4 | 5 | 6): string | undefined;

package/util/time.js

@@ -5,8 +5,8 @@ import { wrapNumber } from "./number.js";
 /** Class representing a time in the day in 24 hour format in the user's current locale. */
 export class Time {
     /** Make a new `Time` instance from a time string. */
-    static from(possible = "now") {
-        if (possible === null)
+    static from(possible) {
+        if (possible === undefined || possible === null || possible === "")
             return undefined;
         if (isTime(possible))
             return possible;
@@ -85,38 +85,31 @@ function _pad(num, size) {
     return num.toString(10).padStart(size, "0000");
 }
 /** Regular expression that matches a time in ISO 8601 format. */
-export const TIME_REGEXP = /([0-9]+):([0-9]+)(?::([0-9]+)(?:.([0-9]+))?)?/;
+const TIME_REGEXP = /([0-9]+):([0-9]+)(?::([0-9]+)(?:.([0-9]+))?)?/;
 /** Is an unknown value a `Time` instance. */
 export function isTime(value) {
     return value instanceof Time;
 }
 /**
- * Convert a value to a `Time` instance or `undefined`
+ * Convert a value to a `Time` instance, or return `undefined` if it couldn't be converted.
  * - Works with possible dates, e.g. `now` or `Date` or `2022-09-12 18:32` or `19827263567`
  * - Works with time strings, e.g. `18:32` or `23:59:59.999`
+ *
+ * @param possible Any value that we want to parse as a valid time (defaults to `undefined`).
  */
 export function getOptionalTime(possible) {
     return Time.from(possible);
 }
-/** Convert a possible time to a `Time` instance, or throw `ValueError` if it couldn't be converted. */
-export function getTime(possible) {
+/**
+ * Convert a possible date to a `Time` instance, or throw `ValueError` if it couldn't be converted (defaults to `"now"`).
+ * @param possible Any value that we want to parse as a valid time (defaults to `"now"`).
+ */
+export function getTime(possible = "now") {
     const time = getOptionalTime(possible);
     if (!time)
         throw new ValueError(`Invalid time`, possible);
     return time;
 }
-/** Get the time as in `hh:mm` format (hours, minutes), e.g. `13.59` */
-export function getShortTime(time) {
-    return getTime(time).long;
-}
-/** Get the time in `hh:mm:ss` format (hours, minutes seconds), e.g. `13.16.19.123` */
-export function getMediumTime(time) {
-    return getTime(time).long;
-}
-/** Get this time in `hh:mm:ss.fff` format (ISO 8601 compatible, hours, minutes, seconds, milliseconds), e.g. `13:16:19.123` */
-export function getLongTime(time) {
-    return getTime(time).long;
-}
 /** Format a time as a string based on the browser locale settings. */
 export function formatTime(time, precision = 2) {
     return getTime(time).format(precision);

package/util/units.js

@@ -211,7 +211,7 @@ export const AREA_UNITS = new UnitList({
 export const VOLUME_UNITS = new UnitList({
     // Metric.
     "milliliter": { abbr: "ml" },
-    "liter": { to: { milliliter: 1000 } },
+    "liter": { abbr: "ltr", to: { milliliter: 1000 } },
     "cubic-centimeter": { abbr: "cm³", to: { milliliter: 1 } },
     "cubic-meter": { abbr: "m³", to: { milliliter: MILLION } },
     // US.

package/util/url.d.ts

@@ -1,13 +1,42 @@
 import { type Optional } from "./optional.js";
+import { type AbsolutePath } from "./path.js";
 /** Things that can be converted to a URL instance. */
 export type PossibleURL = string | URL;
-/** Is an unknown value a URL? */
+/** Is an unknown value a URL object? */
 export declare function isURL(value: unknown): value is URL;
-/** Assert that an unknown value is a URL. */
+/** Assert that an unknown value is a URL object. */
 export declare function assertURL(value: unknown): asserts value is URL;
-/** Convert a possible URL to a URL or return `null` if conversion fails. */
-export declare function getOptionalURL(url: Optional<PossibleURL>, base?: PossibleURL | Location | undefined): URL | undefined;
+/** Convert a possible URL to a URL or return `undefined` if conversion fails. */
+export declare function getOptionalURL(possible: Optional<PossibleURL>, base?: AbsoluteURI | AbsoluteURL | undefined): URL | undefined;
 /** Convert a possible URL to a URL but throw `ValueError` if conversion fails. */
-export declare function getURL(possibleURL: PossibleURL, base?: PossibleURL): URL;
-/** Just get important part of a URL, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
-export declare function formatURL(possibleURL: PossibleURL, base?: PossibleURL): string;
+export declare function getURL(possible: PossibleURL, base?: AbsoluteURI | AbsoluteURL): URL;
+/** Just get the important part of a URL, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
+export declare function formatURL(possible: PossibleURL, base?: AbsoluteURL | AbsoluteURI): string;
+/**
+ * Absolute URL is a URL that has an absolute `href` and `pathname` properties.
+ * - e.g. `http://x.com/a/b` is an absolute URL because `.pathname` will be `/a/b`
+ * - e.g. `http://x.com` is an absolute URL because `.pathname` will be `/`
+ * - e.g. `mailto:me@gmail.com` is _not_ an absolute URL because `.pathname` will be `"me@gmail.com"` which does not start with `/` slash.
+ */
+export type AbsoluteURL = URL & {
+    href: AbsoluteURI;
+    pathname: AbsolutePath;
+};
+/** Is an unknown value an absolute URL object? */
+export declare function isAbsoluteURL(value: unknown): value is AbsoluteURL;
+/** Convert a possible URL to a URL or return `undefined` if conversion fails. */
+export declare function getOptionalAbsoluteURL(possible: Optional<PossibleURL>, base?: AbsoluteURL | AbsoluteURI): AbsoluteURL | undefined;
+/** Convert a possible URL to a URL or return `undefined` if conversion fails. */
+export declare function getAbsoluteURL(possible: Optional<PossibleURL>, base?: AbsoluteURL | AbsoluteURI): AbsoluteURL | undefined;
+/**
+ * Absolute URI string starting with e.g. `https://`
+ * - Indicates a URI with `://` e.g. `https://` and `ftp://` and `file://`
+ * - Does not allow non-heirarchical URIs like `mailto:me@gmail.com`
+ */
+export type AbsoluteURI = `${string}://${string}`;
+/** Relative URI string starts with `./` or `../` or `/` */
+export type RelativeURI = `.` | `./${string}` | `..` | `../${string}` | `/` | `/${string}`;
+/** Convert a possible URL to a absolute URI string or return `undefined` if conversion fails. */
+export declare function getOptionalAbsoluteURI(possible: Optional<PossibleURL>, base?: AbsoluteURL | AbsoluteURI): AbsoluteURI | undefined;
+/** Convert a possible URL to an absolute URI string. */
+export declare function getAbsoluteURI(possible: PossibleURL, base?: AbsoluteURL | AbsoluteURI): AbsoluteURI;

package/util/url.js

@@ -1,37 +1,66 @@
 import { ValueError } from "../error/ValueError.js";
 import { notOptional } from "./optional.js";
-/** Is an unknown value a URL? */
+import { isAbsolutePath } from "./path.js";
+/** Is an unknown value a URL object? */
 export function isURL(value) {
     return value instanceof URL;
 }
-/** Assert that an unknown value is a URL. */
+/** Assert that an unknown value is a URL object. */
 export function assertURL(value) {
     if (!isURL(value))
         throw new ValueError("Invalid URL", value);
 }
-/** Convert a possible URL to a URL or return `null` if conversion fails. */
-export function getOptionalURL(url, base = _LOCATION) {
-    if (notOptional(url)) {
-        if (isURL(url))
-            return url;
+/** Convert a possible URL to a URL or return `undefined` if conversion fails. */
+export function getOptionalURL(possible, base = _BASE) {
+    if (notOptional(possible)) {
         try {
-            return new URL(url, base); // DH: We know `Location` works in URL constructor.
+            return isURL(possible) ? possible : new URL(possible, base);
         }
         catch (e) {
             //
         }
     }
 }
-const _LOCATION = typeof window === "object" ? window.location : undefined;
+const _BASE = typeof document === "object" ? document.baseURI : undefined;
 /** Convert a possible URL to a URL but throw `ValueError` if conversion fails. */
-export function getURL(possibleURL, base) {
-    const url = getOptionalURL(possibleURL, base);
+export function getURL(possible, base) {
+    const url = getOptionalURL(possible, base);
     if (!url)
-        throw new ValueError("Invalid URL", possibleURL);
+        throw new ValueError("Invalid URL", possible);
     return url;
 }
-/** Just get important part of a URL, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
-export function formatURL(possibleURL, base) {
-    const { host, pathname } = getURL(possibleURL, base);
+/** Just get the important part of a URL, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
+export function formatURL(possible, base) {
+    const { host, pathname } = getURL(possible, base);
     return `${host}${pathname.length > 1 ? pathname : ""}`;
 }
+/** Is an unknown value an absolute URL object? */
+export function isAbsoluteURL(value) {
+    // Is an absolute URL if it's a URL and has both a protocol (e.g. `http:`) and a path starting with `/`
+    // Heirarchical URIs like `http:` and `ftp:` will always have pathname starting with `/`
+    return isURL(value) && !!value.protocol && isAbsolutePath(value.pathname);
+}
+/** Convert a possible URL to a URL or return `undefined` if conversion fails. */
+export function getOptionalAbsoluteURL(possible, base) {
+    const url = getOptionalURL(possible, base);
+    if (isAbsoluteURL(url))
+        return url;
+}
+/** Convert a possible URL to a URL or return `undefined` if conversion fails. */
+export function getAbsoluteURL(possible, base) {
+    const url = getOptionalAbsoluteURL(possible, base);
+    if (!url)
+        throw new ValueError("Invalid absolute URL", possible);
+    return url;
+}
+/** Convert a possible URL to a absolute URI string or return `undefined` if conversion fails. */
+export function getOptionalAbsoluteURI(possible, base) {
+    return getOptionalAbsoluteURL(possible, base)?.href;
+}
+/** Convert a possible URL to an absolute URI string. */
+export function getAbsoluteURI(possible, base) {
+    const link = getOptionalAbsoluteURI(possible, base);
+    if (!link)
+        throw new ValueError("Invalid link", possible);
+    return link;
+}