shelving 1.167.2 → 1.168.1

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;

package/util/link.js

@@ -1,44 +0,0 @@
-import { RequiredError } from "../error/RequiredError.js";
-import { getURL, isURL } from "./url.js";
-/** Default whitelist for URL schemes. */
-const SCHEMES = ["http:", "https:"];
-/**
- * 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 function isLinkURL(value, schemes = SCHEMES, hosts) {
-    return isURL(value) && schemes.includes(value.protocol) && (!hosts || hosts.includes(value.host));
-}
-/**
- * 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 function getLinkURL(value, base, schemes = SCHEMES, hosts) {
-    const url = getURL(value, base);
-    if (isLinkURL(url, schemes, hosts))
-        return url;
-}
-/**
- * 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 function requireLinkURL(value, base, schemes, hosts, caller = requireLinkURL) {
-    const url = getLinkURL(value, base, schemes, hosts);
-    if (!url)
-        throw new RequiredError("Invalid link", { received: value, base, schemes, hosts, caller });
-    return url;
-}
-/**
- * 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 function getLink(value, base, schemes = SCHEMES, hosts) {
-    return getLinkURL(value, base, schemes, hosts)?.href;
-}
-/**
- * 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 function requireLink(value, base, schemes, hosts, caller = requireLink) {
-    return requireLinkURL(value, base, schemes, hosts, caller).href;
-}