shelving 1.167.2 → 1.168.0

package/util/format.d.ts

@@ -2,7 +2,7 @@ import { type ImmutableArray } from "./array.js";
 import { type PossibleDate } from "./date.js";
 import { type Duration } from "./duration.js";
 import { type ImmutableObject } from "./object.js";
-import { type PossibleURL } from "./url.js";
+import { type PossibleURI } from "./uri.js";
 /** Options we use for number formatting. */
 export type NumberOptions = Omit<Intl.NumberFormatOptions, "style" | "unit" | "unitDisplay" | "currency" | "currencyDisplay" | "currencySign">;
 /** Format a number (based on the user's browser language settings). */
@@ -73,7 +73,7 @@ export declare function formatTime(time?: PossibleDate, options?: Intl.DateTimeF
 /** Format a datetime in the browser locale (no seconds by default). */
 export declare function formatDateTime(date: PossibleDate, options?: Intl.DateTimeFormatOptions): string;
 /** Format a URL as a user-friendly string, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
-export declare function formatURL(possible: PossibleURL, base?: PossibleURL): string;
+export declare function formatURI(possible: PossibleURI): string;
 /**
  * Convert any unknown value into a friendly string for user-facing use.
  * - Strings return the string.

package/util/format.js

@@ -5,7 +5,7 @@ import { getBestTimeUnit, getMilliseconds } from "./duration.js";
 import { getPercent } from "./number.js";
 import { isObject } from "./object.js";
 import { TIME_UNITS } from "./units.js";
-import { requireURL } from "./url.js";
+import { isURI, requireURI } from "./uri.js";
 /** Format a number (based on the user's browser language settings). */
 export function formatNumber(num, options) {
     return Intl.NumberFormat(undefined, options).format(num);
@@ -110,9 +110,9 @@ export function formatDateTime(date, options) {
     });
 }
 /** Format a URL as a user-friendly string, e.g. `http://shax.com/test?uid=129483` → `shax.com/test` */
-export function formatURL(possible, base) {
-    const { host, pathname } = requireURL(possible, base, formatURL);
-    return `${host}${pathname.length > 1 ? pathname : ""}`;
+export function formatURI(possible) {
+    const { host, pathname } = requireURI(possible, formatURI);
+    return `${host}${pathname !== "/" ? pathname : ""}`;
 }
 /**
  * Convert any unknown value into a friendly string for user-facing use.
@@ -146,6 +146,8 @@ export function formatValue(value) {
         return formatArray(value);
     if (isObject(value))
         return formatObject(value);
+    if (isURI(value))
+        return formatURI(value);
     return "Unknown";
 }
 /**

package/util/index.d.ts

@@ -34,7 +34,6 @@ export * from "./iterate.js";
 export * from "./jsx.js";
 export * from "./jwt.js";
 export * from "./lazy.js";
-export * from "./link.js";
 export * from "./map.js";
 export * from "./merge.js";
 export * from "./null.js";
@@ -56,6 +55,7 @@ export * from "./transform.js";
 export * from "./undefined.js";
 export * from "./units.js";
 export * from "./update.js";
+export * from "./uri.js";
 export * from "./url.js";
 export * from "./uuid.js";
 export * from "./validate.js";

package/util/index.js

@@ -34,7 +34,6 @@ export * from "./iterate.js";
 export * from "./jsx.js";
 export * from "./jwt.js";
 export * from "./lazy.js";
-export * from "./link.js";
 export * from "./map.js";
 export * from "./merge.js";
 export * from "./null.js";
@@ -56,6 +55,7 @@ export * from "./transform.js";
 export * from "./undefined.js";
 export * from "./units.js";
 export * from "./update.js";
+export * from "./uri.js";
 export * from "./url.js";
 export * from "./uuid.js";
 export * from "./validate.js";

package/util/uri.d.ts

@@ -0,0 +1,94 @@
+import type { ImmutableArray } from "./array.js";
+import { type ImmutableDictionary } from "./dictionary.js";
+import type { AnyCaller } from "./function.js";
+import { type Nullish } from "./null.js";
+import type { URL, URLString } from "./url.js";
+/**
+ * Valid URI string is anything following `protocol:resource` format, e.g. `urn:isbn:0451450523` or `http://example.com/path/to/resource`
+ *
+ * URI and URL differences:
+ * - According to RFC 3986, URLs are a subset of URIs that have a hierarchical path component, e.g. `http://example.com/path`.
+ * - The `//` at the start of a URL indicates that it has a hierarchical path component, so this makes it a URL.
+ * - The absence of `//` indicates a non-hierarchical URI.
+ * - URLs can be considered as "hierarchical URIs".
+ * - All URLs are also URIs, but not all URIs are URLs.
+ */
+export type URIString = `${string}:${string}`;
+/**
+ * Object that describes a valid URI, e.g. `urn:isbn:0451450523` or `http://example.com/path/to/resource`
+ * - Improves the builtin Javascript `URL` class to more accurately type its properties.
+ *
+ * URI and URL differences:
+ * - According to RFC 3986, URLs are a subset of URIs that have a hierarchical path component, e.g. `http://example.com/path`.
+ * - The `//` at the start of a URL indicates that it has a hierarchical path component, so this makes it a URL.
+ * - The absence of `//` indicates a non-hierarchical URI.
+ * - URLs can be considered as "hierarchical URIs".
+ * - All URLs are also URIs, but not all URIs are URLs.
+ *
+ * Javascript URL problems:
+ * - Javascript `URL` instance can actually represent any kind of URI (not just URLs).
+ * - It's more "correct" terminology to use `URI` to refer to what the Javascript `URL` class represents.
+ * - You can tell the difference because a URL will have a non-empty `host` property, whereas URIs will never have a `host` (it will be `""` empty string).
+ */
+export interface URI extends globalThis.URL {
+    protocol: URIScheme;
+    href: URIString;
+}
+/**
+ * Construct a correctly-typed `URI` object.
+ * - This is a more correctly typed version of the builtin Javascript `URI` constructor.
+ * - Requires a URI string, URI object, or path as input, and optionally a base URI.
+ * - If a path is provided as input, a base URI _must_ also be provided.
+ * - The returned type is
+ */
+export interface URIConstructor {
+    new (input: URIString | URI): URI;
+}
+export declare const URI: URIConstructor;
+/** Values that can be converted to a URI instance. */
+export type PossibleURI = string | globalThis.URL;
+/** Is an unknown value a URI object? */
+export declare function isURI(value: unknown): value is URI;
+/** Assert that an unknown value is a URI object. */
+export declare function assertURI(value: unknown, caller?: AnyCaller): asserts value is URI;
+/** Convert a possible URI to a URI, or return `undefined` if conversion fails. */
+export declare function getURI(possible: Nullish<PossibleURI>): URI | undefined;
+/** Convert a possible URI to a URI, or throw `RequiredError` if conversion fails. */
+export declare function requireURI(possible: PossibleURI, caller?: AnyCaller): URI;
+/** Convert a possible URI to a URI string, or return `undefined` if conversion fails. */
+export declare function getURIString(possible: Nullish<PossibleURI>): URIString | undefined;
+/** Convert a possible URI to a URI string, or throw `RequiredError` if conversion fails. */
+export declare function requireURIString(possible: PossibleURI, caller?: AnyCaller): URIString | undefined;
+/** Type for a set of named URL parameters. */
+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. */
+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;
+/** Get a single named param from a URI. */
+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.
+ */
+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.
+ */
+export declare function withURIParams(url: URL | URLString, params: PossibleURIParams, caller?: AnyCaller): URL;
+export declare function withURIParams(url: PossibleURI, params: PossibleURIParams, caller?: AnyCaller): URI;
+/** Return a URI without one or more params (or same URI if no changes were made). */
+export declare function omitURIParams(url: URL | URLString, ...keys: string[]): URL;
+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;
+/** A single schema for a URL. */
+export type URIScheme = `${string}:`;
+/** List of allowed URI schemes. */
+export type URISchemes = ImmutableArray<URIScheme>;
+/** Valid HTTP schemes for a URI. */
+export declare const HTTP_SCHEMES: URISchemes;

package/util/uri.js

@@ -0,0 +1,119 @@
+import { RequiredError } from "../error/RequiredError.js";
+import { ValueError } from "../error/ValueError.js";
+import { getDictionaryItems, isDictionary } from "./dictionary.js";
+import { notNullish } from "./null.js";
+import { getString, isString } from "./string.js";
+export const URI = globalThis.URL;
+/** Is an unknown value a URI object? */
+export function isURI(value) {
+    return value instanceof URI;
+}
+/** Assert that an unknown value is a URI object. */
+export function assertURI(value, caller = assertURI) {
+    if (!isURI(value))
+        throw new RequiredError("Invalid URI", { received: value, caller });
+}
+/** Convert a possible URI to a URI, or return `undefined` if conversion fails. */
+export function getURI(possible) {
+    if (notNullish(possible)) {
+        if (isURI(possible))
+            return possible;
+        try {
+            return new globalThis.URL(possible);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/** Convert a possible URI to a URI, or throw `RequiredError` if conversion fails. */
+export function requireURI(possible, caller = requireURI) {
+    const url = getURI(possible);
+    assertURI(url, caller);
+    return url;
+}
+/** Convert a possible URI to a URI string, or return `undefined` if conversion fails. */
+export function getURIString(possible) {
+    return getURI(possible)?.href;
+}
+/** Convert a possible URI to a URI string, or throw `RequiredError` if conversion fails. */
+export function requireURIString(possible, caller = requireURIString) {
+    return requireURI(possible, caller).href;
+}
+/**
+ * Get a set of entries for a set of possible URI params.
+ *
+ * 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.
+ * 2. So when converting this to a simple data object, only one value per key can be represented, but it needs to be the _first_ one.
+ * 3. Since we're looping through anyway, we also take the time to convert values to strings, so we can accept a wider range of input types.
+ */
+function* getURIEntries(input, caller = getURIParams) {
+    if (input instanceof URLSearchParams) {
+        yield* input;
+    }
+    else if (isString(input) || input instanceof globalThis.URL) {
+        yield* requireURI(input, caller).searchParams;
+    }
+    else {
+        const done = [];
+        for (const [key, value] of getDictionaryItems(input)) {
+            if (done.includes(key))
+                continue;
+            done.push(key);
+            const str = getString(value);
+            if (str === undefined)
+                throw new ValueError(`URI param "${key}" must be string`, { received: value, caller });
+            yield [key, str];
+        }
+    }
+}
+/** Get a set of params for a URI as a dictionary. */
+export function getURIParams(input, caller = getURIParams) {
+    const output = {};
+    for (const [key, str] of getURIEntries(input, caller))
+        output[key] = str;
+    return output;
+}
+/** Get a single named param from a URI. */
+export function getURIParam(input, key) {
+    if (input instanceof URLSearchParams)
+        return input.get(key) || undefined;
+    if (isDictionary(input))
+        return getString(input[key]);
+    return getURIParams(input)[key];
+}
+/** Get a single named param from a URI. */
+export function requireURIParam(input, key, caller = requireURIParam) {
+    const value = getURIParam(input, key);
+    if (value === undefined)
+        throw new RequiredError(`URI param "${key}" is required`, { received: input, caller });
+    return value;
+}
+export function withURIParam(url, key, value, caller = withURIParam) {
+    const input = requireURI(url, caller);
+    const output = new URI(input);
+    const str = getString(value);
+    if (str === undefined)
+        throw new ValueError(`URI param "${key}" must be string`, { received: value, caller });
+    output.searchParams.set(key, str);
+    return input.href === output.href ? input : output;
+}
+export function withURIParams(url, params, caller = withURIParams) {
+    const input = requireURI(url, caller);
+    const output = new URI(input);
+    for (const [key, str] of getURIEntries(params, caller))
+        output.searchParams.set(key, str);
+    return input.href === output.href ? input : output;
+}
+export function omitURIParams(url, ...keys) {
+    const input = requireURI(url, omitURIParams);
+    const output = new URI(input);
+    for (const key of keys)
+        output.searchParams.delete(key);
+    return input.href === output.href ? input : output;
+}
+/** Return a URI without a param (or same URI if no changes were made). */
+export const omitURIParam = omitURIParams;
+/** Valid HTTP schemes for a URI. */
+export const HTTP_SCHEMES = ["http:", "https:"];

package/util/url.d.ts

@@ -1,46 +1,56 @@
-import type { DictionaryItem, ImmutableDictionary } from "./dictionary.js";
 import type { AnyCaller } from "./function.js";
 import { type Nullish } from "./null.js";
-/** Values that can be converted to a URL instance. */
-export type PossibleURL = string | 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 object. */
-export declare function assertURL(value: unknown, caller?: AnyCaller): asserts value is URL;
-/** Convert a possible URL to a URL, or return `undefined` if conversion fails. */
-export declare function getURL(possible: Nullish<PossibleURL>, base?: PossibleURL | undefined): URL | undefined;
-/** Convert a possible URL to a URL, or throw `RequiredError` if conversion fails. */
-export declare function requireURL(possible: PossibleURL, base?: PossibleURL, caller?: AnyCaller): URL;
-/** Type for a set of named URL parameters. */
-export type URLParams = ImmutableDictionary<string>;
-/** Type for things that can be converted to named URL parameters. */
-export type PossibleURLParams = PossibleURL | URLSearchParams | ImmutableDictionary<unknown>;
+import type { AbsolutePath, Path } from "./path.js";
+import type { URI } from "./uri.js";
+/**
+ * A URL string has a protocol and a `//`.
+ * - The `//` at the start of a URL indicates that it has a hierarchical path component, so this makes it a URL.
+ * - URLs have a concept of "absolute" or "relative" URLs, since they have a path.
+ */
+export type URLString = `${string}://${string}`;
 /**
- * Get a set of entries for a set of possible URL params.
+ * Object that describes a valid URL, e.g. `http://example.com/path/to/resource`
+ * - Improves the builtin Javascript `URL` class to more accurately type its properties.
  *
- * 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.
- * 2. So when converting this to a simple data object, only one value per key can be represented, but it needs to be the _first_ one.
- * 3. Since we're looping through anyway, we also take the time to convert values to strings, so we can accept a wider range of input types.
+ * URI and URL differences:
+ * - According to RFC 3986, URLs are a subset of URIs that have a hierarchical path component, e.g. `http://example.com/path`.
+ * - The `//` at the start of a URL indicates that it has a hierarchical path component, so this makes it a URL.
+ * - The absence of `//` indicates a non-hierarchical URI.
+ * - URLs can be considered as "hierarchical URIs".
+ * - All URLs are also URIs, but not all URIs are URLs.
+ *
+ * Javascript URL problems:
+ * - Javascript `URL` instance can actually represent any kind of URI (not just URLs).
+ * - It's more "correct" terminology to use `URI` to refer to what the Javascript `URL` class represents.
+ * - You can tell the difference because a URL will have a non-empty `host` property, whereas URIs will never have a `host` (it will be `""` empty string).
  */
-export declare function getURLEntries(input: PossibleURLParams, caller?: AnyCaller): Iterable<DictionaryItem<string>>;
-/** Get a set of params for a URL as a dictionary. */
-export declare function getURLParams(input: PossibleURLParams, caller?: AnyCaller): URLParams;
-/** Get a single named param from a URL. */
-export declare function getURLParam(input: PossibleURLParams, key: string): string | undefined;
-/** Get a single named param from a URL. */
-export declare function requireURLParam(input: PossibleURLParams, key: string, caller?: AnyCaller): string;
+export interface URL extends URI {
+    href: URLString;
+    origin: URLString;
+    pathname: AbsolutePath;
+}
 /**
- * Return a URL with a new param set (or same URL if no changes were made).
- * - Throws `ValueError` if the value could not be converted to a string.
+ * Construct a correctly-typed `URL` object.
+ * - This is a more correctly typed version of the builtin Javascript `URL` constructor.
+ * - Requires a URL string, URL object, or path as input, and optionally a base URL.
+ * - If a path is provided as input, a base URL _must_ also be provided.
+ * - The returned type is
  */
-export declare function withURLParam(url: PossibleURL, key: string, value: unknown, caller?: AnyCaller): URL;
+export interface URLConstructor {
+    new (input: URLString | URL, base?: URLString | URL): URL;
+    new (input: URLString | URL | Path, base: URLString | URL): URL;
+}
+export declare const URL: URLConstructor;
+/** Values that can be converted to a URL instance. */
+export type PossibleURL = string | globalThis.URL;
 /**
- * Return a URL with several new params set (or same URL if no changes were made).
- * - Throws `ValueError` if any of the values could not be converted to strings.
+ * Is an unknown value a URL object?
+ * - Must be a `URL` instance and its origin must start with `scheme://`
  */
-export declare function withURLParams(url: PossibleURL, params: PossibleURLParams, caller?: AnyCaller): URL;
-/** Return a URL without one or more params (or same URL if no changes were made). */
-export declare function omitURLParams(url: PossibleURL, ...keys: string[]): URL;
-/** Return a URL without a param (or same URL if no changes were made). */
-export declare const omitURLParam: (url: PossibleURL, key: string) => URL;
+export declare function isURL(value: unknown): value is URL;
+/** Assert that an unknown value is a URL object. */
+export declare function assertURL(value: unknown, caller?: AnyCaller): asserts value is URL;
+/** Convert a possible URL to a URL, or return `undefined` if conversion fails. */
+export declare function getURL(possible: Nullish<PossibleURL>, base?: PossibleURL | undefined): URL | undefined;
+/** Convert a possible URL to a URL, or throw `RequiredError` if conversion fails. */
+export declare function requireURL(possible: PossibleURL, base?: PossibleURL | undefined, caller?: AnyCaller): URL;

package/util/url.js

@@ -1,11 +1,15 @@
 import { RequiredError } from "../error/RequiredError.js";
-import { ValueError } from "../error/ValueError.js";
-import { getDictionaryItems, isDictionary } from "./dictionary.js";
 import { notNullish } from "./null.js";
-import { getString, isString } from "./string.js";
-/** Is an unknown value a URL object? */
+export const URL = globalThis.URL;
+/**
+ * Is an unknown value a URL object?
+ * - Must be a `URL` instance and its origin must start with `scheme://`
+ */
 export function isURL(value) {
-    return value instanceof URL;
+    return value instanceof globalThis.URL && _isValidURL(value);
+}
+function _isValidURL(url) {
+    return url.href.startsWith(`${url.protocol}//`);
 }
 /** Assert that an unknown value is a URL object. */
 export function assertURL(value, caller = assertURL) {
@@ -15,13 +19,19 @@ export function assertURL(value, caller = assertURL) {
 /** Convert a possible URL to a URL, or return `undefined` if conversion fails. */
 export function getURL(possible, base = _BASE) {
     if (notNullish(possible)) {
-        if (isURL(possible))
-            return possible;
-        try {
-            return new URL(possible, base);
+        if (possible instanceof globalThis.URL) {
+            if (_isValidURL(possible))
+                return possible;
         }
-        catch {
-            return undefined;
+        else {
+            try {
+                const url = new globalThis.URL(possible, base);
+                if (_isValidURL(url))
+                    return url;
+            }
+            catch {
+                //
+            }
         }
     }
 }
@@ -32,87 +42,3 @@ export function requireURL(possible, base, caller = requireURL) {
     assertURL(url, caller);
     return url;
 }
-/**
- * Get a set of entries for a set of possible URL params.
- *
- * 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.
- * 2. So when converting this to a simple data object, only one value per key can be represented, but it needs to be the _first_ one.
- * 3. Since we're looping through anyway, we also take the time to convert values to strings, so we can accept a wider range of input types.
- */
-export function* getURLEntries(input, caller = getURLParams) {
-    if (input instanceof URLSearchParams) {
-        yield* input;
-    }
-    else if (isString(input) || isURL(input)) {
-        yield* requireURL(input, undefined, caller).searchParams;
-    }
-    else {
-        const done = [];
-        for (const [key, value] of getDictionaryItems(input)) {
-            if (done.includes(key))
-                continue;
-            done.push(key);
-            const str = getString(value);
-            if (str === undefined)
-                throw new ValueError(`URL param "${key}" must be string`, { received: value, caller });
-            yield [key, str];
-        }
-    }
-}
-/** Get a set of params for a URL as a dictionary. */
-export function getURLParams(input, caller = getURLParams) {
-    const output = {};
-    for (const [key, str] of getURLEntries(input, caller))
-        output[key] = str;
-    return output;
-}
-/** Get a single named param from a URL. */
-export function getURLParam(input, key) {
-    if (input instanceof URLSearchParams)
-        return input.get(key) || undefined;
-    if (isDictionary(input))
-        return getString(input[key]);
-    return getURLParams(input)[key];
-}
-/** Get a single named param from a URL. */
-export function requireURLParam(input, key, caller = requireURLParam) {
-    const value = getURLParam(input, key);
-    if (value === undefined)
-        throw new RequiredError(`URL param "${key}" is required`, { received: input, caller });
-    return value;
-}
-/**
- * Return a URL with a new param set (or same URL if no changes were made).
- * - Throws `ValueError` if the value could not be converted to a string.
- */
-export function withURLParam(url, key, value, caller = withURLParam) {
-    const input = requireURL(url);
-    const output = new URL(input);
-    const str = getString(value);
-    if (str === undefined)
-        throw new ValueError(`URL param "${key}" must be string`, { received: value, caller });
-    output.searchParams.set(key, str);
-    return input.href === output.href ? input : output;
-}
-/**
- * Return a URL with several new params set (or same URL if no changes were made).
- * - Throws `ValueError` if any of the values could not be converted to strings.
- */
-export function withURLParams(url, params, caller = withURLParams) {
-    const input = requireURL(url);
-    const output = new URL(input);
-    for (const [key, str] of getURLEntries(params, caller))
-        output.searchParams.set(key, str);
-    return input.href === output.href ? input : output;
-}
-/** Return a URL without one or more params (or same URL if no changes were made). */
-export function omitURLParams(url, ...keys) {
-    const input = requireURL(url);
-    const output = new URL(input);
-    for (const key of keys)
-        output.searchParams.delete(key);
-    return input.href === output.href ? input : output;
-}
-/** Return a URL without a param (or same URL if no changes were made). */
-export const omitURLParam = omitURLParams;

package/schema/LinkSchema.d.ts

@@ -1,27 +0,0 @@
-import type { ImmutableArray } from "../util/array.js";
-import { type AbsoluteLink } from "../util/link.js";
-import type { StringSchemaOptions } from "./StringSchema.js";
-import { StringSchema } from "./StringSchema.js";
-/** Allowed options for `LinkSchema` */
-export interface LinkSchemaOptions extends Omit<StringSchemaOptions, "input" | "min" | "max" | "multiline"> {
-    readonly base?: AbsoluteLink | undefined;
-    readonly schemes?: ImmutableArray<string> | undefined;
-    readonly hosts?: ImmutableArray<string> | undefined;
-}
-/**
- * Type of `StringSchema` that defines a valid URL link.
- * - 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 declare class LinkSchema extends StringSchema {
-    readonly base: AbsoluteLink | undefined;
-    readonly schemes: ImmutableArray<string> | undefined;
-    readonly hosts: ImmutableArray<string> | undefined;
-    constructor({ one, title, base, schemes, hosts, ...options }: LinkSchemaOptions);
-    validate(unsafeValue: unknown): AbsoluteLink;
-}
-/** Valid link, e.g. `https://www.google.com` */
-export declare const LINK: LinkSchema;
-/** Valid link, e.g. `https://www.google.com`, or `null` */
-export declare const NULLABLE_LINK: import("./NullableSchema.js").NullableSchema<`${string}:${string}`>;

package/util/link.d.ts

@@ -1,71 +0,0 @@
-import type { ImmutableArray } from "./array.js";
-import type { AnyCaller } from "./function.js";
-import type { Nullish } from "./null.js";
-import type { Path } from "./path.js";
-import { type PossibleURL } from "./url.js";
-/**
- * URL string with a `scheme:` at the start and a path component, e.g. `https://` or `file://`
- * - The `//` in a URI indicates that type of URI has a path heirarchy indicated by the first `/` after the `://`
- * - If the URI has no explicit `/path` component it will always be assumed to be `/`
- * - Some URIs are non-heirarchical, e.g. `mailto:me@gmail.com`
- */
-export type AbsoluteLink = `${string}:${string}`;
-/**
- * Relative link starts with `./` or `../` or `/`
- * @example "/a/b/c"
- * @example "./d/e/f"
- * @example "../g/h/i"
- */
-export type RelativeLink = Path;
-/**
- * Either an absolute URL string or a relative URL string.
- * @example "http://www.google.com"
- * @example "/a/b/c"
- * @example "./d/e/f"
- * @example "../g/h/i"
- */
-export type Link = AbsoluteLink | RelativeLink;
-/**
- * List of allowed schemes for a link.
- * @example ["http:", "https:", "mailto:"]
- */
-export type LinkSchemes = ImmutableArray<string>;
-/**
- * List of allowed hosts for a link.
- * @example ["google.com", "www.google.com"]
- */
-export type LinkHosts = ImmutableArray<string>;
-/**
- * Absolute URL is a URL that has an `href` that is a `Link` element and a `pathname` that is an `AbsolutePath` property.
- * - e.g. `http://x.com/a/b` is a link URL because `.pathname` will be `/a/b`
- * - e.g. `http://x.com` is a link 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 AbsoluteLinkURL = URL & {
-    href: AbsoluteLink;
-};
-/**
- * Is an unknown value a link URL?
- * - A valid link URL is a `URL` instance with a scheme matching the `schemes` array, and `host` matching the optional `hosts` array.
- */
-export declare function isLinkURL(value: unknown, schemes?: LinkSchemes, hosts?: LinkHosts): value is AbsoluteLinkURL;
-/**
- * Convert a possible URL to a link URL, or return `undefined` if conversion fails.
- * - A valid link URL is a `URL` instance with a scheme matching the `schemes` array, and `host` matching the optional `hosts` array.
- */
-export declare function getLinkURL(value: Nullish<PossibleURL>, base?: AbsoluteLinkURL | AbsoluteLink, schemes?: LinkSchemes, hosts?: LinkHosts): AbsoluteLinkURL | undefined;
-/**
- * Convert a possible URL to a link URL, or throw `RequiredError` if conversion fails.
- * - A valid link URL is a `URL` instance with a scheme matching the `schemes` array, and `host` matching the optional `hosts` array.
- */
-export declare function requireLinkURL(value: PossibleURL, base?: AbsoluteLinkURL | AbsoluteLink, schemes?: LinkSchemes, hosts?: LinkHosts, caller?: AnyCaller): AbsoluteLinkURL;
-/**
- * Convert a possible URL to an link URL string, or return `undefined` if conversion fails.
- * - A valid link URL string is an absolute URL string with a scheme matching the `schemes` array, and `host` matching the optional `hosts` array.
- */
-export declare function getLink(value: Nullish<PossibleURL>, base?: AbsoluteLinkURL | AbsoluteLink, schemes?: LinkSchemes, hosts?: LinkHosts): AbsoluteLink | undefined;
-/**
- * Convert a possible URL to an link URL string, or throw `RequiredError` if conversion fails.
- * - A valid link URL string is an absolute URL string with a scheme matching the `schemes` array, and `host` matching the optional `hosts` array.
- */
-export declare function requireLink(value: PossibleURL, base?: AbsoluteLinkURL | AbsoluteLink, schemes?: LinkSchemes, hosts?: LinkHosts, caller?: AnyCaller): AbsoluteLink;