exacturi 1.0.0

package/src/exacturi.ts

@@ -0,0 +1,444 @@
+import { ExactUriError, inputMustBeString, inputMustBeUrl, portMustBeNumeric } from "./errors.js";
+import { hostnameContains } from "./utils.js";
+import {
+    ExactUri_CompoundNames,
+    ExactUri_Parts,
+    ExactUri_PathKey,
+    ExactUri_Protocol
+} from "./parts.js";
+
+/**
+ * Represents a URI and allows performing operations and inspecting it.
+ *
+ * This class is immutable.
+ */
+export class ExactUri {
+    // Lots of params needed here
+    // eslint-disable-next-line max-params
+    constructor(
+        private _protocol: ExactUri_Protocol | undefined,
+        private _hostname: string | undefined,
+        private _path: string,
+        private _query: string | undefined,
+        private _hash: string | undefined,
+        private _parsed: string | undefined,
+        private _port: string | undefined
+    ) {}
+
+    static is(other: unknown): other is ExactUri {
+        return !!(other && typeof other === "object" && other.constructor === ExactUri);
+    }
+
+    segments(): string[];
+    segments(overwrite: string[]): ExactUri;
+    segments(overwrite?: string[]) {
+        if (arguments.length === 0) {
+            return this._path.split("/");
+        }
+        const clone = this._noCopyClone();
+        clone._path = overwrite!.join("/");
+        return clone;
+    }
+
+    merge(other: string): ExactUri;
+    merge(other: ExactUri): ExactUri;
+    merge(other: ExactUri | string): ExactUri {
+        if (typeof other === "string") {
+            return this.merge(ExactUri.parse(other));
+        }
+        return this.parts({
+            hash: other._hash || this._hash,
+            hostname: other._hostname || this._hostname,
+            path: other._path || this._path,
+            port: other._port || this._port,
+            protocol: other._protocol || this._protocol,
+            query: other._query || this._query
+        });
+    }
+
+    pick(...keys: ExactUri_PathKey[]): ExactUri {
+        let result = ExactUri.empty();
+        for (const key of keys) {
+            result = result.part(key, this.part(key as ExactUri_CompoundNames));
+        }
+        return result;
+    }
+
+    parts(): ExactUri_Parts;
+    parts(overwrite: Partial<ExactUri_Parts>): ExactUri;
+    parts(overwrite?: Partial<ExactUri_Parts>): any {
+        if (arguments.length === 0) {
+            return {
+                protocol: this._protocol,
+                hostname: this._hostname,
+                port: this._port,
+                path: this._path,
+                query: this._query,
+                hash: this._hash
+            };
+        }
+        if (!overwrite) {
+            return this;
+        }
+        const clone = this._noCopyClone();
+        clone._protocol = "protocol" in overwrite ? overwrite.protocol : clone._protocol;
+        clone._hostname = "hostname" in overwrite ? overwrite.hostname : clone._hostname;
+        clone._port = "port" in overwrite ? overwrite.port : clone._port;
+        clone._path = "path" in overwrite ? (overwrite.path as any) : clone._path;
+        clone._query = "query" in overwrite ? overwrite.query : clone._query;
+        clone._hash = "hash" in overwrite ? overwrite.hash : clone._hash;
+        return clone;
+    }
+
+    part(key: ExactUri_PathKey): string | undefined;
+    part(key: ExactUri_PathKey, value: string | undefined): ExactUri;
+    part(key: ExactUri_PathKey, value?: string): any {
+        if (arguments.length === 1) {
+            const result = (this as any)[key]();
+            return result != null ? String(result) : undefined;
+        }
+        return (this as any)[key](value as any);
+    }
+
+    address(address: string | undefined | null): ExactUri;
+    address(): string | undefined;
+    address(address?: string): string | ExactUri | undefined {
+        if (arguments.length === 1) {
+            const parsed = ExactUri.parse(address!);
+            return parsed.parts({
+                protocol: this._protocol
+            });
+        }
+        return this.parts({
+            protocol: undefined
+        }).href;
+    }
+
+    resource(resource: string | undefined | null): ExactUri;
+    resource(): string | undefined;
+    resource(resource?: string): string | ExactUri | undefined {
+        if (arguments.length === 1) {
+            const parsed = ExactUri.parse(resource!);
+            return parsed.parts({
+                protocol: this._protocol,
+                hostname: this._hostname,
+                port: this._port
+            });
+        }
+        return this.parts({
+            protocol: undefined,
+            hostname: undefined,
+            port: undefined
+        }).href;
+    }
+
+    origin(origin: string | undefined | null): ExactUri;
+    origin(): string | undefined;
+    origin(origin?: string): string | ExactUri | undefined {
+        if (arguments.length === 1) {
+            const parsed = ExactUri.parse(origin!);
+            return this.parts({
+                protocol: parsed._protocol,
+                hostname: parsed._hostname,
+                port: parsed._port
+            });
+        }
+        const parts = this.parts();
+        return (
+            ExactUri.empty().parts({
+                protocol: parts.protocol,
+                hostname: parts.hostname,
+                port: parts.port
+            }).href || undefined
+        );
+    }
+
+    segment(index: number): string;
+    segment(index: number, value: string): ExactUri;
+    segment(index: number, value?: string) {
+        if (arguments.length === 0) {
+            throw new ExactUriError(`You must provide an index.`);
+        }
+        if (arguments.length === 1) {
+            return this._path.split("/")[index];
+        }
+        const segments = this.segments();
+        segments[index] = value!;
+        return this.segments(segments);
+    }
+
+    // Gets the path. It can't be nullish.
+    path(): string;
+    // Sets the path to `path`. Null is converted to `""`.
+    path(path: string | undefined | null): ExactUri;
+    path(path?: string) {
+        if (arguments.length === 0) {
+            return this._path;
+        }
+        const clone = this._noCopyClone();
+        clone._path = path ?? "";
+        return clone;
+    }
+
+    port(): number | undefined;
+    port(raw: true): string | undefined;
+    port(port: number | undefined | string | null): ExactUri;
+    port(port?: number | true | string | null) {
+        if (arguments.length === 0) {
+            return this._port != null ? Number(this._port) : undefined;
+        }
+        if (port === true) {
+            return this._port;
+        }
+        const clone = this._noCopyClone();
+        clone._port = port != null ? String(port) : undefined;
+        return clone;
+    }
+
+    // Gets the protocol.
+    protocol(): ExactUri_Protocol | undefined;
+    // Sets the protocol to `proto`.
+    protocol(proto: ExactUri_Protocol | null | undefined): ExactUri;
+    protocol(proto?: ExactUri_Protocol | null | undefined) {
+        if (arguments.length === 0) {
+            return this._protocol;
+        }
+        const clone = this._noCopyClone();
+        clone._protocol = proto ?? undefined;
+        return clone;
+    }
+
+    // Gets the hostname and port.
+    host(): string | undefined;
+    // Sets the hostname and port.
+    host(host: string | undefined | null): ExactUri;
+    host(host?: string): any {
+        if (arguments.length === 0) {
+            return (
+                ExactUri.empty().hostname(this._hostname).port(this._port).href.slice(2) ||
+                undefined
+            );
+        }
+        if (host == null) {
+            return this.hostname(null).port(null);
+        }
+        const parsed = ExactUri.parse(`//${host}`);
+        return this.hostname(parsed._hostname).port(parsed._port);
+    }
+
+    // Gets the hostname, which is the domain without the port.
+    hostname(): string | undefined;
+    // Sets the hostname to `hostname`.
+    hostname(hostname: string | undefined | null): ExactUri;
+    hostname(hostname?: string) {
+        if (arguments.length === 0) {
+            return this._hostname;
+        }
+        const clone = this._noCopyClone();
+        clone._hostname = hostname ?? undefined;
+        return clone;
+    }
+
+    // Gets the query string.
+    query(): string | undefined;
+    // Sets the query string to `query`.
+    query(query: string | null | undefined): ExactUri;
+    query(query?: string) {
+        if (arguments.length === 0) {
+            return this._query;
+        }
+        const clone = this._noCopyClone();
+        clone._query = query ?? undefined;
+        return clone;
+    }
+
+    // Gets the hash, aka the fragment, without the #.
+    hash(): string;
+    // Sets the hash of this to `hash`, and returns `this`.
+    hash(hash: string | null | undefined): ExactUri;
+    hash(hash?: string) {
+        if (arguments.length === 0) {
+            return this._hash;
+        }
+        const clone = this._noCopyClone();
+        clone._hash = hash ?? undefined;
+        return clone;
+    }
+
+    private _noCopyClone() {
+        return new ExactUri(
+            this._protocol,
+            this._hostname,
+            this._path,
+            this._query,
+            this._hash,
+            this._parsed,
+            this._port
+        );
+    }
+
+    // Does this URL have a web protocol?
+    get isWeb() {
+        return !!this._protocol && webProtocols.has(this._protocol);
+    }
+
+    /**
+     * Gets a clone of this instance.
+     */
+    clone(): ExactUri {
+        return new ExactUri(
+            this._protocol,
+            this._hostname,
+            this._path,
+            this._query,
+            this._hash,
+            this._parsed,
+            this._port
+        );
+    }
+
+    static empty() {
+        return new ExactUri(undefined, undefined, "", undefined, undefined, undefined, undefined);
+    }
+
+    // Parses `input` as a URI. Errors on bad input.
+    static parse(input: null | undefined): ExactUri;
+    static parse(input: string | ExactUri | Partial<ExactUri_Parts>): ExactUri;
+    static parse(input: any) {
+        if (input == null) {
+            return ExactUri.empty();
+        }
+        if (input instanceof ExactUri) {
+            return input;
+        }
+        if (typeof input === "object") {
+            return ExactUri.empty().parts(input);
+        }
+        if (typeof input !== "string") {
+            throw inputMustBeString(input);
+        }
+        const r = urlRegexp.exec(input);
+        if (!r) {
+            throw inputMustBeUrl(input);
+        }
+
+        const [, proto, hostname, port, path, query, fragment] = r;
+        if (port != null && (Number.isNaN(+port) || port === "")) {
+            throw portMustBeNumeric(input);
+        }
+        return new ExactUri(
+            proto?.trim(),
+            hostname?.trim(),
+            path?.trim() ?? "",
+            query?.trim(),
+            fragment?.trim(),
+            input,
+            port
+        );
+    }
+
+    /**
+     * Checks if this URI (CHILD) matches another URI (PARENT). The parent can be a string,
+     * an {@link ExactUri}, or an object describing the parts of a URI -- an {@link ExactUri_Parts}.
+     *
+     * CHILD is considered to be a child of PARENT if:
+     * 1. If PARENT has a protocol, it must equal CHILD protocol.
+     * 2. If PARENT has a hostname, it must be a parent of CHILD's hostname.
+     * 3. If PARENT has a port, it must equal CHILD's port.
+     * 4. If PARENT has a path, it must be a parent of CHILD's path.
+     * 5. If PARENT has a query, it must equal CHILD's query.
+     * 6. If PARENT has a hash, it must equal CHILD's hash.
+     * @param parent The parent URI to check against.
+     */
+    matches(parent: Partial<ExactUri_Parts> | ExactUri | string): boolean {
+        parent = ExactUri.parse(parent);
+        if (parent._protocol && parent._protocol !== this._protocol) {
+            return false;
+        }
+        if (parent._hostname && !hostnameContains(this._hostname, parent._hostname)) {
+            return false;
+        }
+
+        if (parent._port && parent._port !== this._port) {
+            return false;
+        }
+        if (parent._query && parent._query !== this._query) {
+            return false;
+        }
+        if (parent._hash && parent._hash !== this._hash) {
+            return false;
+        }
+
+        const parentSegments = parent.segments();
+        const childSegments = this.segments();
+        for (let i = 0; i < parentSegments.length; i++) {
+            if (parentSegments[i] !== childSegments[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    /**
+     * Checks if this URI equals another URI, which can be given as a string, an
+     * {@link ExactUri}, or an object describing the parts of a URI -- an {@link ExactUri_Parts}.
+     * @param other The other URI to check against.
+     */
+    equal(other: string | ExactUri | Partial<ExactUri_Parts>): boolean {
+        if (this === other) {
+            return true;
+        }
+        other = ExactUri.parse(other);
+        const myParts = this.parts();
+        const otherParts = other.parts();
+        for (const key of ["protocol", "hostname", "port", "path", "query", "hash"] as const) {
+            if (myParts[key] !== otherParts[key]) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    // An artificial URI is one that can't have been parsed from a string due to an invalid combination of components.
+    get isArtificial(): boolean {
+        return !ExactUri.parse(this._print()).equal(this);
+    }
+
+    /**
+     * Does this URL have a non-web protocol?
+     */
+    get isNonWeb() {
+        return !!this._protocol && !webProtocols.has(this._protocol);
+    }
+
+    /**
+     * Gets the full URI.
+     */
+    get href() {
+        return this._print();
+    }
+
+    private _print() {
+        let { _protocol, _hostname, _query, _hash } = this;
+        const { _port } = this;
+        _protocol = _protocol != null ? `${_protocol}:` : _protocol;
+        _hostname = _hostname != null ? `//${_hostname}` : "";
+        _query = _query != null ? `?${_query}` : "";
+        _hash = _hash != null ? `#${_hash}` : "";
+        const strPort = _port != null ? `:${_port}` : "";
+        return [_protocol, _hostname, strPort, this._path, _query, _hash].join("");
+    }
+
+    get [Symbol.toStringTag]() {
+        return this.href;
+    }
+
+    toString() {
+        return this.href;
+    }
+}
+
+const urlRegexp =
+    /^(?:([a-zA-Z][A-Za-z\d+-.]*):)?(?:\/\/([^/?#:]*)(?::([^/?#]*))?)?([^?#]*)?(?:\?([^#]*))?(?:#(.*))?$/;
+
+const webProtocols = new Set(["http", "ws", "https", "wss"]);

package/src/index.ts

@@ -0,0 +1,37 @@
+import { ExactUri } from "./exacturi.js";
+
+import { ExactUri_Parts } from "./parts.js";
+
+export { ExactUri } from "./exacturi.js";
+
+/**
+ * Creates an empty ExactUri object.
+ */
+export function exacturi(): ExactUri;
+/**
+ * Creates an ExactUri object from an {@link ExactUri_Parts} describing the parts of the URI.
+ * @param parts The parts of the URI.
+ */
+export function exacturi(parts: Partial<ExactUri_Parts>): ExactUri;
+/**
+ * Returns the same ExactUri object that was passed in.
+ * @param uri
+ */
+export function exacturi(uri: ExactUri): ExactUri;
+/**
+ * Parses a string into an ExactUri object.
+ * @param uri The string to parse.
+ */
+export function exacturi(uri: string): ExactUri;
+export function exacturi(uri?: ExactUri | string | Partial<ExactUri_Parts>): ExactUri {
+    return ExactUri.parse(uri as any);
+}
+
+/**
+ * Returns true if the given value is an ExactUri object.
+ * @param uri The value to check.
+ */
+export function isExactUri(uri: unknown): uri is ExactUri {
+    return ExactUri.is(uri);
+}
+export { ExactUri_Protocol } from "./parts.js";

package/src/parts.ts

@@ -0,0 +1,29 @@
+// Possible URL protocols.
+export type ExactUri_Protocol =
+    | "http"
+    | "https"
+    | "ws"
+    | "wss"
+    | "about"
+    | "chrome"
+    | "chrome-extension"
+    | "data"
+    | "blob"
+    | "javascript"
+    | "file"
+    | "ftp"
+    | string;
+export type ExactUri_CompoundNames = "host" | "origin" | "resource" | "address";
+export type ExactUri_PathKey = keyof ExactUri_Parts | ExactUri_CompoundNames;
+
+/**
+ * Describes the parts of a URI.
+ */
+export interface ExactUri_Parts {
+    protocol?: ExactUri_Protocol;
+    hostname?: string;
+    port?: string;
+    path: string;
+    query?: string;
+    hash?: string;
+}

package/src/utils.ts

@@ -0,0 +1,42 @@
+export function hostnameContains(child: string | undefined, parent: string) {
+    if (!child) {
+        return false;
+    }
+    const parentParts = parent.split(".").reverse();
+    const childParts = child.split(".").reverse();
+    if (parentParts.length > childParts.length) {
+        return false;
+    }
+
+    for (let i = 0; i < parentParts.length; i++) {
+        if (!parentParts[i]) {
+            continue;
+        }
+        if (childParts[i] !== parentParts[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+
+export function equal(a: any, b: any): boolean {
+    if (!a || typeof a !== "object" || !b || typeof b !== "object") {
+        return a === b;
+    }
+    const aProto = Object.getPrototypeOf(a);
+    const bProto = Object.getPrototypeOf(b);
+    if (aProto !== bProto) {
+        return false;
+    }
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length) {
+        return false;
+    }
+    for (const key of aKeys) {
+        if (a[key] !== b[key]) {
+            return false;
+        }
+    }
+    return true;
+}