exacturi 1.0.0 → 1.0.1

package/src/errors.ts

@@ -1,31 +1,31 @@
 export class ExactUriError extends Error {
-    name = "ExactUriError";
+    name = "ExactUriError"
 }
 
 export function badInputError(input: any, reason: string) {
-    return new ExactUriError(`Received bad input ${input}. ${reason}`);
+    return new ExactUriError(`Received bad input ${input}. ${reason}`)
 }
 
 export function inputMustBeString(input: unknown) {
-    return badInputError(input, `Input must be a string, but was a ${typeof input}`);
+    return badInputError(input, `Input must be a string, but was a ${typeof input}`)
 }
 
 export function cantSerializeArtificialUrl(url: string) {
-    return new ExactUriError(`This URL is artificial and can't be serialized. Looks like: ${url}`);
+    return new ExactUriError(`This URL is artificial and can't be serialized. Looks like: ${url}`)
 }
 
 export function invalidCharacter(input: string, char: string, reason: string) {
-    return badInputError(input, `The character ${char} was unexpected because ${reason}.`);
+    return badInputError(input, `The character ${char} was unexpected because ${reason}.`)
 }
 
 export function portMustBeNumeric(input: string) {
-    return badInputError(input, "Port must be numeric.");
+    return badInputError(input, "Port must be numeric.")
 }
 
 export function inputMustBeUrl(input: string) {
-    return badInputError(input, "Input failed to parse.");
+    return badInputError(input, "Input failed to parse.")
 }
 
 export function cantCompareType(value: unknown) {
-    return new ExactUriError(`Can't compare this URI to a value ${value}`);
+    return new ExactUriError(`Can't compare this URI to a value ${value}`)
 }

package/src/exacturi.ts

@@ -1,11 +1,11 @@
-import { ExactUriError, inputMustBeString, inputMustBeUrl, portMustBeNumeric } from "./errors.js";
-import { hostnameContains } from "./utils.js";
+import { ExactUriError, inputMustBeString, inputMustBeUrl, portMustBeNumeric } from "./errors.js"
 import {
     ExactUri_CompoundNames,
     ExactUri_Parts,
     ExactUri_PathKey,
     ExactUri_Protocol
-} from "./parts.js";
+} from "./parts.js"
+import { hostnameContains } from "./utils.js"
 
 /**
  * Represents a URI and allows performing operations and inspecting it.
@@ -26,25 +26,25 @@ export class ExactUri {
     ) {}
 
     static is(other: unknown): other is ExactUri {
-        return !!(other && typeof other === "object" && other.constructor === ExactUri);
+        return !!(other && typeof other === "object" && other.constructor === ExactUri)
     }
 
-    segments(): string[];
-    segments(overwrite: string[]): ExactUri;
+    segments(): string[]
+    segments(overwrite: string[]): ExactUri
     segments(overwrite?: string[]) {
         if (arguments.length === 0) {
-            return this._path.split("/");
+            return this._path.split("/")
         }
-        const clone = this._noCopyClone();
-        clone._path = overwrite!.join("/");
-        return clone;
+        const clone = this._noCopyClone()
+        clone._path = overwrite!.join("/")
+        return clone
     }
 
-    merge(other: string): ExactUri;
-    merge(other: ExactUri): ExactUri;
+    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.merge(ExactUri.parse(other))
         }
         return this.parts({
             hash: other._hash || this._hash,
@@ -53,19 +53,19 @@ export class ExactUri {
             port: other._port || this._port,
             protocol: other._protocol || this._protocol,
             query: other._query || this._query
-        });
+        })
     }
 
     pick(...keys: ExactUri_PathKey[]): ExactUri {
-        let result = ExactUri.empty();
+        let result = ExactUri.empty()
         for (const key of keys) {
-            result = result.part(key, this.part(key as ExactUri_CompoundNames));
+            result = result.part(key, this.part(key as ExactUri_CompoundNames))
         }
-        return result;
+        return result
     }
 
-    parts(): ExactUri_Parts;
-    parts(overwrite: Partial<ExactUri_Parts>): ExactUri;
+    parts(): ExactUri_Parts
+    parts(overwrite: Partial<ExactUri_Parts>): ExactUri
     parts(overwrite?: Partial<ExactUri_Parts>): any {
         if (arguments.length === 0) {
             return {
@@ -75,194 +75,194 @@ export class ExactUri {
                 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;
+            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): 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;
+            const result = (this as any)[key]()
+            return result != null ? String(result) : undefined
         }
-        return (this as any)[key](value as any);
+        return (this as any)[key](value as any)
     }
 
-    address(address: string | undefined | null): ExactUri;
-    address(): string | undefined;
+    address(address: string | undefined | null): ExactUri
+    address(): string | undefined
     address(address?: string): string | ExactUri | undefined {
         if (arguments.length === 1) {
-            const parsed = ExactUri.parse(address!);
+            const parsed = ExactUri.parse(address!)
             return parsed.parts({
                 protocol: this._protocol
-            });
+            })
         }
         return this.parts({
             protocol: undefined
-        }).href;
+        }).href
     }
 
-    resource(resource: string | undefined | null): ExactUri;
-    resource(): string | undefined;
+    resource(resource: string | undefined | null): ExactUri
+    resource(): string | undefined
     resource(resource?: string): string | ExactUri | undefined {
         if (arguments.length === 1) {
-            const parsed = ExactUri.parse(resource!);
+            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;
+        }).href
     }
 
-    origin(origin: string | undefined | null): ExactUri;
-    origin(): string | undefined;
+    origin(origin: string | undefined | null): ExactUri
+    origin(): string | undefined
     origin(origin?: string): string | ExactUri | undefined {
         if (arguments.length === 1) {
-            const parsed = ExactUri.parse(origin!);
+            const parsed = ExactUri.parse(origin!)
             return this.parts({
                 protocol: parsed._protocol,
                 hostname: parsed._hostname,
                 port: parsed._port
-            });
+            })
         }
-        const parts = this.parts();
+        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): string
+    segment(index: number, value: string): ExactUri
     segment(index: number, value?: string) {
         if (arguments.length === 0) {
-            throw new ExactUriError(`You must provide an index.`);
+            throw new ExactUriError(`You must provide an index.`)
         }
         if (arguments.length === 1) {
-            return this._path.split("/")[index];
+            return this._path.split("/")[index]
         }
-        const segments = this.segments();
-        segments[index] = value!;
-        return this.segments(segments);
+        const segments = this.segments()
+        segments[index] = value!
+        return this.segments(segments)
     }
 
     // Gets the path. It can't be nullish.
-    path(): string;
+    path(): string
     // Sets the path to `path`. Null is converted to `""`.
-    path(path: string | undefined | null): ExactUri;
+    path(path: string | undefined | null): ExactUri
     path(path?: string) {
         if (arguments.length === 0) {
-            return this._path;
+            return this._path
         }
-        const clone = this._noCopyClone();
-        clone._path = path ?? "";
-        return clone;
+        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(): 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;
+            return this._port != null ? Number(this._port) : undefined
         }
         if (port === true) {
-            return this._port;
+            return this._port
         }
-        const clone = this._noCopyClone();
-        clone._port = port != null ? String(port) : undefined;
-        return clone;
+        const clone = this._noCopyClone()
+        clone._port = port != null ? String(port) : undefined
+        return clone
     }
 
     // Gets the protocol.
-    protocol(): ExactUri_Protocol | undefined;
+    protocol(): ExactUri_Protocol | undefined
     // Sets the protocol to `proto`.
-    protocol(proto: ExactUri_Protocol | null | undefined): ExactUri;
+    protocol(proto: ExactUri_Protocol | null | undefined): ExactUri
     protocol(proto?: ExactUri_Protocol | null | undefined) {
         if (arguments.length === 0) {
-            return this._protocol;
+            return this._protocol
         }
-        const clone = this._noCopyClone();
-        clone._protocol = proto ?? undefined;
-        return clone;
+        const clone = this._noCopyClone()
+        clone._protocol = proto ?? undefined
+        return clone
     }
 
     // Gets the hostname and port.
-    host(): string | undefined;
+    host(): string | undefined
     // Sets the hostname and port.
-    host(host: string | undefined | null): ExactUri;
+    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);
+            return this.hostname(null).port(null)
         }
-        const parsed = ExactUri.parse(`//${host}`);
-        return this.hostname(parsed._hostname).port(parsed._port);
+        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;
+    hostname(): string | undefined
     // Sets the hostname to `hostname`.
-    hostname(hostname: string | undefined | null): ExactUri;
+    hostname(hostname: string | undefined | null): ExactUri
     hostname(hostname?: string) {
         if (arguments.length === 0) {
-            return this._hostname;
+            return this._hostname
         }
-        const clone = this._noCopyClone();
-        clone._hostname = hostname ?? undefined;
-        return clone;
+        const clone = this._noCopyClone()
+        clone._hostname = hostname ?? undefined
+        return clone
     }
 
     // Gets the query string.
-    query(): string | undefined;
+    query(): string | undefined
     // Sets the query string to `query`.
-    query(query: string | null | undefined): ExactUri;
+    query(query: string | null | undefined): ExactUri
     query(query?: string) {
         if (arguments.length === 0) {
-            return this._query;
+            return this._query
         }
-        const clone = this._noCopyClone();
-        clone._query = query ?? undefined;
-        return clone;
+        const clone = this._noCopyClone()
+        clone._query = query ?? undefined
+        return clone
     }
 
     // Gets the hash, aka the fragment, without the #.
-    hash(): string;
+    hash(): string
     // Sets the hash of this to `hash`, and returns `this`.
-    hash(hash: string | null | undefined): ExactUri;
+    hash(hash: string | null | undefined): ExactUri
     hash(hash?: string) {
         if (arguments.length === 0) {
-            return this._hash;
+            return this._hash
         }
-        const clone = this._noCopyClone();
-        clone._hash = hash ?? undefined;
-        return clone;
+        const clone = this._noCopyClone()
+        clone._hash = hash ?? undefined
+        return clone
     }
 
     private _noCopyClone() {
@@ -274,17 +274,15 @@ export class ExactUri {
             this._hash,
             this._parsed,
             this._port
-        );
+        )
     }
 
     // Does this URL have a web protocol?
     get isWeb() {
-        return !!this._protocol && webProtocols.has(this._protocol);
+        return !!this._protocol && webProtocols.has(this._protocol)
     }
 
-    /**
-     * Gets a clone of this instance.
-     */
+    /** Gets a clone of this instance. */
     clone(): ExactUri {
         return new ExactUri(
             this._protocol,
@@ -294,37 +292,37 @@ export class ExactUri {
             this._hash,
             this._parsed,
             this._port
-        );
+        )
     }
 
     static empty() {
-        return new ExactUri(undefined, undefined, "", undefined, undefined, undefined, undefined);
+        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: null | undefined): ExactUri
+    static parse(input: string | ExactUri | Partial<ExactUri_Parts>): ExactUri
     static parse(input: any) {
         if (input == null) {
-            return ExactUri.empty();
+            return ExactUri.empty()
         }
         if (input instanceof ExactUri) {
-            return input;
+            return input
         }
         if (typeof input === "object") {
-            return ExactUri.empty().parts(input);
+            return ExactUri.empty().parts(input)
         }
         if (typeof input !== "string") {
-            throw inputMustBeString(input);
+            throw inputMustBeString(input)
         }
-        const r = urlRegexp.exec(input);
+        const r = urlRegexp.exec(input)
         if (!r) {
-            throw inputMustBeUrl(input);
+            throw inputMustBeUrl(input)
         }
 
-        const [, proto, hostname, port, path, query, fragment] = r;
+        const [, proto, hostname, port, path, query, fragment] = r
         if (port != null && (Number.isNaN(+port) || port === "")) {
-            throw portMustBeNumeric(input);
+            throw portMustBeNumeric(input)
         }
         return new ExactUri(
             proto?.trim(),
@@ -334,111 +332,110 @@ export class ExactUri {
             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}.
+     * 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);
+        parent = ExactUri.parse(parent)
         if (parent._protocol && parent._protocol !== this._protocol) {
-            return false;
+            return false
         }
         if (parent._hostname && !hostnameContains(this._hostname, parent._hostname)) {
-            return false;
+            return false
         }
 
         if (parent._port && parent._port !== this._port) {
-            return false;
+            return false
         }
         if (parent._query && parent._query !== this._query) {
-            return false;
+            return false
         }
         if (parent._hash && parent._hash !== this._hash) {
-            return false;
+            return false
         }
 
-        const parentSegments = parent.segments();
-        const childSegments = this.segments();
+        const parentSegments = parent.segments()
+        const childSegments = this.segments()
         for (let i = 0; i < parentSegments.length; i++) {
             if (parentSegments[i] !== childSegments[i]) {
-                return false;
+                return false
             }
         }
-        return true;
+        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}.
+     * 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;
+            return true
         }
-        other = ExactUri.parse(other);
-        const myParts = this.parts();
-        const otherParts = other.parts();
+        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 false
             }
         }
-        return true;
+        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);
+        return !ExactUri.parse(this._print()).equal(this)
     }
 
-    /**
-     * Does this URL have a non-web protocol?
-     */
+    /** Does this URL have a non-web protocol? */
     get isNonWeb() {
-        return !!this._protocol && !webProtocols.has(this._protocol);
+        return !!this._protocol && !webProtocols.has(this._protocol)
     }
 
-    /**
-     * Gets the full URI.
-     */
+    /** Gets the full URI. */
     get href() {
-        return this._print();
+        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("");
+        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;
+        return this.href
     }
 
     toString() {
-        return this.href;
+        return this.href
     }
 }
 
 const urlRegexp =
-    /^(?:([a-zA-Z][A-Za-z\d+-.]*):)?(?:\/\/([^/?#:]*)(?::([^/?#]*))?)?([^?#]*)?(?:\?([^#]*))?(?:#(.*))?$/;
+    /^(?:([a-zA-Z][A-Za-z\d+-.]*):)?(?:\/\/([^/?#:]*)(?::([^/?#]*))?)?([^?#]*)?(?:\?([^#]*))?(?:#(.*))?$/
 
-const webProtocols = new Set(["http", "ws", "https", "wss"]);
+const webProtocols = new Set(["http", "ws", "https", "wss"])

package/src/index.ts

@@ -1,37 +1,39 @@
-import { ExactUri } from "./exacturi.js";
+import { ExactUri } from "./exacturi.js"
 
-import { ExactUri_Parts } from "./parts.js";
+import { ExactUri_Parts } from "./parts.js"
 
-export { ExactUri } from "./exacturi.js";
+export { ExactUri } from "./exacturi.js"
+export { ExactUri_Protocol } from "./parts.js"
 
-/**
- * Creates an empty ExactUri object.
- */
-export function exacturi(): ExactUri;
+/** 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;
+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;
+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: string): ExactUri
 export function exacturi(uri?: ExactUri | string | Partial<ExactUri_Parts>): ExactUri {
-    return ExactUri.parse(uri as any);
+    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);
+    return ExactUri.is(uri)
 }
-export { ExactUri_Protocol } from "./parts.js";