@adviser/cement 0.0.0-jsr-t1 → 0.0.0-smoke-ci

package/src/uri.ts

@@ -1,24 +1,166 @@
+import type { DeepWritable } from "ts-essentials";
 import { exception2Result, Result } from "./result.js";
+import { getParamsResult, KeysParam } from "./utils/get-params-result.js";
+import { relativePath } from "./utils/relative-path.js";
+import { StripCommand, stripper } from "./utils/stripper.js";
+// import { param } from "./types.js";
 
 type NullOrUndef = null | undefined;
 
+type OneKey<K extends string, V = string> = Record<K, V>;
+
+export interface IsURIResult {
+  readonly isURI: boolean;
+  readonly uri?: URI;
+}
+
+/** @xdeprecated use param from get-params-result */
+// export const key = param;
+
+/*
+  if KeyParam is a Object
+     if the right side is a string, it is the default value
+     if the right side is a !string | REQUIRED, it is required
+*/
+
+// type ReturnType<T extends (...args: KeysParam) => unknown> = T extends (...args: KeysParam) => infer R ? R : unknown;
+
+// function fetchData<T extends (...args: any[]) => Promise<any>>(fn: T): ReturnType<T> {
+//   return fn();
+// }
+// type ReturnObject<T extends KeysParam> = {
+//   [K in keyof T]: string;
+// };
+
+export interface URIInterface<R extends URIInterface<R>> {
+  readonly getParams: Iterable<[string, string]>;
+
+  hasParam(key: string): boolean;
+  getParam<T extends string | undefined>(key: string | OneKey<string>, def?: T): T extends string ? string : string | undefined;
+  getParamResult(key: string, msgFn?: (key: string) => string): Result<string>;
+  getParamsResult(...keys: KeysParam): Result<Record<string, string>>;
+  match(other: CoerceURI): MatchResult;
+  clone(): R;
+  asURL(): URL;
+  toString(): string;
+  toJSON(): string;
+  asObj(...strips: StripCommand[]): Partial<HostURIObject | PathURIObject>;
+}
+
+export interface MatchResult {
+  readonly score: number;
+  readonly protocol: boolean;
+  readonly hostname: boolean;
+  readonly port: boolean;
+  readonly pathname: boolean;
+  readonly pathParts: string[];
+  readonly params: Record<string, string>;
+}
+
+function match(iref: CoerceURI, ioth: CoerceURI): MatchResult {
+  const mr: DeepWritable<MatchResult> = {
+    score: 0,
+    protocol: false,
+    hostname: false,
+    port: false,
+    pathname: false,
+    pathParts: [],
+    params: {},
+  };
+  const ref = URI.from(iref);
+  const oth = URI.from(ioth);
+  if (ref.protocol === oth.protocol) {
+    mr.score += 1;
+    mr.protocol = true;
+  }
+  try {
+    const refH = ref.hostname;
+    const refP = ref.port;
+    if (refH === oth.hostname) {
+      mr.score += 1;
+      mr.hostname = true;
+    }
+    if (refP.length && refP === oth.port) {
+      mr.score += 1;
+      mr.port = true;
+    }
+  } catch (e) {
+    // ignore
+  }
+  if (ref.pathname.length && ref.pathname !== "/") {
+    const pref = ref.pathname.split("/").filter((p) => p.length);
+    const poth = oth.pathname.split("/").filter((p) => p.length);
+    for (let i = 0; i < pref.length && i < poth.length; i++) {
+      if (poth[i] === pref[i]) {
+        mr.score += 1;
+        mr.pathname = true;
+        mr.pathParts.push(pref[i]);
+      }
+    }
+  }
+  for (const [key, value] of ref.getParams) {
+    if (oth.getParam(key) === value) {
+      mr.score += 1;
+      mr.params[key] = value;
+    }
+  }
+  return mr;
+}
+
+function coerceKey(key: string | OneKey<string>, def?: string): { key: string; def?: string } {
+  if (typeof key === "object") {
+    const keys = Object.keys(key);
+    if (keys.length !== 1) {
+      throw new Error(`Invalid key: ${JSON.stringify(key)}`);
+    }
+    return { key: keys[0], def: key[keys[0]] };
+  }
+  return { key, def: def };
+}
+
+function resolveHash(hash: string): { getParam: (k: string) => string | undefined } {
+  const searchParams = new URLSearchParams(hash.replace(/^#/, ""));
+  return {
+    getParam: (k): string | undefined => {
+      const ret = searchParams.get(k);
+      return ret === null ? undefined : ret;
+    },
+  };
+}
+
+export interface URIObject {
+  readonly style: "host" | "path";
+  readonly protocol: string;
+  readonly pathname: string;
+  readonly searchParams: Record<string, string>;
+}
+
+export interface PathURIObject extends URIObject {
+  readonly style: "path";
+}
+
+export interface HostURIObject extends URIObject {
+  readonly style: "host";
+  readonly hostname: string;
+  readonly port: string;
+}
+
 function falsy2undef<T>(value: T | NullOrUndef): T | undefined {
   return value === undefined || value === null ? undefined : value;
 }
 
 function ensureURLWithDefaultProto(url: string | URL, defaultProtocol: string): MutableURL {
   if (!url) {
-    return new MutableURL(`${defaultProtocol}//`);
+    return MutableURL.fromThrow(`${defaultProtocol}//`);
   }
   if (typeof url === "string") {
     try {
-      return new MutableURL(url);
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      return MutableURL.fromThrow(url);
     } catch (e) {
-      return new MutableURL(`${defaultProtocol}//${url}`);
+      return MutableURL.fromThrow(`${defaultProtocol}//${url}`);
     }
   } else {
-    return new MutableURL(url.toString());
+    return MutableURL.fromThrow(url.toString());
   }
 }
 
@@ -34,6 +176,10 @@ export function isURL(value: unknown): value is URL {
 
 // due to that the System URL class is has a strange behavior
 // on different platforms, we need to implement our own URL class
+const customInspectSymbol = Symbol.for("nodejs.util.inspect.custom");
+
+const urlRegex = /^([a-z][a-z0-9_-]*):\/\/[^:]*$/i;
+
 export class MutableURL extends URL {
   private readonly _sysURL: URL;
   // private readonly _urlStr: string;
@@ -42,12 +188,23 @@ export class MutableURL extends URL {
   private _pathname: string;
   private _hasHostpart: boolean;
 
-  readonly hash: string;
+  // override readonly hash: string;
+
+  static fromThrow(urlStr: string): MutableURL {
+    return new MutableURL(urlStr);
+  }
 
-  constructor(urlStr: string) {
+  static from(urlStr: string): Result<MutableURL> {
+    if (urlRegex.test(urlStr)) {
+      return exception2Result(() => new MutableURL(urlStr));
+    }
+    return Result.Err(`Invalid URL: ${urlStr}`);
+  }
+
+  private constructor(urlStr: string) {
     super("defect://does.not.exist");
     const partedURL = urlStr.split(":");
-    this._hasHostpart = protocols.has(partedURL[0]);
+    this._hasHostpart = hasHostPartProtocols.has(partedURL[0]);
     let hostPartUrl = ["http", ...partedURL.slice(1)].join(":");
     if (!this._hasHostpart) {
       const pathname = hostPartUrl.replace(/http:\/\/[/]*/, "").replace(/[#?].*$/, "");
@@ -66,80 +223,104 @@ export class MutableURL extends URL {
     } else {
       this._pathname = urlStr.replace(new RegExp(`^${this._protocol}//`), "").replace(/[#?].*$/, "");
     }
-    this.hash = this._sysURL.hash;
+    // this.hash = this._sysURL.hash;
+  }
+
+  override toJSON(): string {
+    throw new Error("toJSON: Method not implemented.");
+  }
+
+  [customInspectSymbol](): string {
+    // make node inspect to show the URL and not crash if URI is not http/https/file
+    return this.toString();
   }
 
   clone(): MutableURL {
     return new MutableURL(this.toString());
   }
 
-  get host(): string {
+  override get host(): string {
     if (!this._hasHostpart) {
       throw new Error(
-        `you can use hostname only if protocol is ${this.toString()} ${JSON.stringify(Array.from(protocols.keys()))}`,
+        `you can use hostname only if protocol is ${this.toString()} ${JSON.stringify(Array.from(hasHostPartProtocols.keys()))}`,
       );
     }
     return this._sysURL.host;
   }
 
-  get port(): string {
+  override get port(): string {
     if (!this._hasHostpart) {
-      throw new Error(`you can use hostname only if protocol is ${JSON.stringify(Array.from(protocols.keys()))}`);
+      throw new Error(`you can use hostname only if protocol is ${JSON.stringify(Array.from(hasHostPartProtocols.keys()))}`);
     }
     return this._sysURL.port;
   }
 
-  set port(p: string) {
+  override set port(p: string) {
     if (!this._hasHostpart) {
-      throw new Error(`you can use port only if protocol is ${JSON.stringify(Array.from(protocols.keys()))}`);
+      throw new Error(`you can use port only if protocol is ${JSON.stringify(Array.from(hasHostPartProtocols.keys()))}`);
     }
     this._sysURL.port = p;
   }
 
-  get hostname(): string {
+  override get hostname(): string {
     if (!this._hasHostpart) {
-      throw new Error(`you can use hostname only if protocol is ${JSON.stringify(Array.from(protocols.keys()))}`);
+      throw new Error(`you can use hostname only if protocol is ${JSON.stringify(Array.from(hasHostPartProtocols.keys()))}`);
     }
     return this._sysURL.hostname;
   }
 
-  set hostname(h: string) {
+  override set hostname(h: string) {
     if (!this._hasHostpart) {
-      throw new Error(`you can use hostname only if protocol is ${JSON.stringify(Array.from(protocols.keys()))}`);
+      throw new Error(`you can use hostname only if protocol is ${JSON.stringify(Array.from(hasHostPartProtocols.keys()))}`);
     }
     this._sysURL.hostname = h;
   }
 
-  set pathname(p: string) {
+  override set pathname(p: string) {
     this._pathname = p;
   }
 
-  get pathname(): string {
+  override get pathname(): string {
     return this._pathname;
   }
 
-  get protocol(): string {
+  override get protocol(): string {
     return this._protocol;
   }
 
-  set protocol(p: string) {
+  override set protocol(p: string) {
     if (!p.endsWith(":")) {
       p = `${p}:`;
     }
     this._protocol = p;
   }
 
-  get searchParams(): URLSearchParams {
+  override get hash(): string {
+    return this._sysURL.hash;
+  }
+
+  override set hash(h: string) {
+    this._sysURL.hash = h;
+  }
+
+  override get searchParams(): URLSearchParams {
     return this._sysURL.searchParams;
   }
 
-  toString(): string {
+  override get search(): string {
     let search = "";
     if (this._sysURL.searchParams.size) {
-      for (const [key, value] of Array.from(this._sysURL.searchParams.entries()).sort((a, b) => a[0].localeCompare(b[0]))) {
+      for (const [key, value] of Array.from(URLSearchParamsEntries(this._sysURL.searchParams)).sort((a, b) =>
+        a[0].localeCompare(b[0]),
+      )) {
         search += `${!search.length ? "?" : "&"}${key}=${encodeURIComponent(value)}`;
       }
     }
+    return search;
+  }
+
+  override toString(): string {
+    const search = this.search;
     let hostpart = "";
     if (this._hasHostpart) {
       hostpart = this._sysURL.hostname;
@@ -150,23 +331,23 @@ export class MutableURL extends URL {
         hostpart += "/";
       }
     }
-    return `${this._protocol}//${hostpart}${this._pathname}${search}`;
+    return `${this._protocol}//${hostpart}${this._pathname}${search}${this.hash}`;
   }
 }
 
 function from<T>(fac: (url: MutableURL) => T, strURLUri: CoerceURI | undefined, defaultProtocol: string): T {
   switch (typeof falsy2undef(strURLUri)) {
     case "undefined":
-      return fac(new MutableURL(`${defaultProtocol}///`));
+      return fac(MutableURL.fromThrow(`${defaultProtocol}///`));
     case "string":
       return fac(ensureURLWithDefaultProto(strURLUri as string, defaultProtocol));
     case "object":
       if (BuildURI.is(strURLUri)) {
-        return fac(new MutableURL(strURLUri._url.toString()));
+        return fac(MutableURL.fromThrow(strURLUri._url.toString()));
       } else if (URI.is(strURLUri)) {
-        return fac(new MutableURL(strURLUri._url.toString()));
+        return fac(MutableURL.fromThrow(strURLUri._url.toString()));
       } else if (isURL(strURLUri)) {
-        return fac(new MutableURL(strURLUri.toString()));
+        return fac(MutableURL.fromThrow(strURLUri.toString()));
       }
       throw new Error(`unknown object type: ${strURLUri}`);
     default:
@@ -174,7 +355,72 @@ function from<T>(fac: (url: MutableURL) => T, strURLUri: CoerceURI | undefined,
   }
 }
 
-export class BuildURI {
+function getParamResult(
+  key: string,
+  val: string | undefined,
+  msgFn: (key: string) => string = (key) => {
+    return `missing parameter: ${key}`;
+  },
+): Result<string> {
+  if (val === undefined) {
+    return Result.Err(msgFn(key));
+  }
+  return Result.Ok(val);
+}
+
+// there are deno which does not have URLSearchParams.entries() in types
+function* URLSearchParamsEntries(src: URLSearchParams): IterableIterator<[string, string]> {
+  const entries: [string, string][] = [];
+  src.forEach((v, k) => {
+    entries.push([k, v]);
+  });
+  for (const [key, value] of entries) {
+    yield [key, value];
+  }
+}
+
+function setParams(
+  src: string,
+  val: Record<string, string | number | boolean | Date | null | undefined>,
+  mode: "reset" | "merge" = "reset",
+  out: URLSearchParams = new URLSearchParams(""),
+): string {
+  let preset: Record<string, string>;
+  switch (mode) {
+    case "reset":
+      preset = {};
+      break;
+    case "merge":
+    default:
+      preset = Object.fromEntries(URLSearchParamsEntries(new URLSearchParams(src)));
+      break;
+  }
+  // const out = new URLSearchParams("");
+  for (const [key, value] of Object.entries({ ...preset, ...val }).sort((a, b) => a[0].localeCompare(b[0]))) {
+    switch (typeof value) {
+      case "string":
+        out.set(key, value);
+        break;
+      case "number":
+        out.set(key, value.toString());
+        break;
+      case "boolean":
+        out.set(key, value ? "true" : "false");
+        break;
+      default:
+        if (value instanceof Date) {
+          out.set(key, value.toISOString());
+        } else {
+          // eslint-disable-next-line no-console
+          console.error(`unsupported type: ${typeof value} ignore key: ${key}`);
+        }
+        break;
+    }
+  }
+  return out.toString();
+}
+
+export class BuildURI implements URIInterface<BuildURI> {
   _url: MutableURL; // pathname needs this
   private constructor(url: MutableURL) {
     this._url = url;
@@ -190,6 +436,10 @@ export class BuildURI {
     return from((url) => new BuildURI(url), strURLUri, defaultProtocol);
   }
 
+  match(other: CoerceURI): MatchResult {
+    return match(this.URI(), URI.from(other));
+  }
+
   port(p: string): BuildURI {
     this._url.port = p;
     return this;
@@ -200,55 +450,99 @@ export class BuildURI {
     return this;
   }
 
-  // password(p: string) {
-  //   this._url.password = p;
-  //   return this;
-  // }
+  protocol(p: string): BuildURI {
+    if (!p.endsWith(":")) {
+      p = `${p}:`;
+    }
+    this._url.protocol = p;
+    return this;
+  }
 
-  // port(p: string) {
-  //   this._url.port = p;
-  //   return this;
-  // }
+  pathname(p: string): BuildURI {
+    this._url.pathname = p;
+    return this;
+  }
 
-  // username(u: string) {
-  //   this._url.username = u;
-  //   return this;
-  // }
+  hash(h: string): BuildURI {
+    this._url.hash = h;
+    return this;
+  }
 
-  // search(s: string) {
-  //   this._url.search = s;
-  //   return this;
-  // }
+  // could pass a relative path or a full URL
+  // if relative path, it will be appended to the current path
+  resolve(p: CoerceURI): BuildURI {
+    if (!p) {
+      return this;
+    }
+    if (typeof p === "string") {
+      // relative path
+      if (!p.match(/^[a-zA-Z0-9]+:/)) {
+        if (p.startsWith("/")) {
+          this.pathname(p);
+          return this;
+        }
+        return this.appendRelative(p);
+      }
+    }
+    this._url = MutableURL.fromThrow(p.toString());
+    return this;
+  }
 
-  protocol(p: string): BuildURI {
-    this._url.protocol = p;
-    // if (!p.endsWith(":")) {
-    //   p = `${p}:`;
+  appendRelative(p: CoerceURI): BuildURI {
+    const appendUrl = URI.from(p);
+    const pathname = "./" + appendUrl.pathname;
+    const basePath = this._url.pathname;
+    /*
+     * cases
+     *  pathname "" basePAth "" -> ""
+     *  pathname "/" basePath "" -> "/"
+     *  pathname "" basePath "/" -> "/"
+     *  pathname "/" basePath "/" -> "/"
+     *  pathname "ab" basePath "" -> "/ab"
+     *  pathname "ab" basePath "/" -> "/ab"
+     *  pathname "ab" basePath "/ab/" -> "/ab/ab"
+     *  pathname "/ab/" basePath "/ab/" -> "/ab/ab/"
+     */
+    this.pathname(relativePath(basePath, pathname));
+    // if (pathname.startsWith("/")) {
+    //   pathname = pathname.replace(/^\//, "");
+    // }
+    // if (basePath.length > 0) {
+    //   basePath = basePath.replace(/\/$/, "");
     // }
-    // const mySrc = this._url.toString();
-    // const myDst = mySrc.replace(new RegExp(`^${this._url.protocol}`), `${p}`);
-    // this._url = new URL(myDst);
+    // this.pathname(basePath + "/" + pathname);
+    for (const [key, value] of appendUrl.getParams) {
+      this.setParam(key, value);
+    }
     return this;
   }
 
-  pathname(p: string): BuildURI {
-    // const myp = this.URI().pathname;
-    // const mySrc = this._url.toString();
-    // const myDst = mySrc.replace(new RegExp(`^${this._url.protocol}//${myp}`), `${this._url.protocol}//${p}`);
-    // this._url = new URL(myDst);
-    this._url.pathname = p;
+  cleanParams(...remove: (string | string[])[]): BuildURI {
+    const keys = new Set(remove.flat());
+    for (const [key] of Array.from(URLSearchParamsEntries(this._url.searchParams))) {
+      if (keys.size === 0 || keys.has(key)) {
+        this._url.searchParams.delete(key);
+      }
+    }
     return this;
   }
 
-  // hash(h: string) {
-  //   this._url.hash = h;
-  //   return this;
-  // }
+  searchParams(
+    val: Record<string, string | number | boolean | Date | null | undefined>,
+    mode: "reset" | "merge" = "reset",
+  ): BuildURI {
+    // this._url.searchParams = setParams(this._url.hash.replace(/^#/, ''), val, mode);
+    setParams(this._url.search, val, mode, this._url.searchParams);
+    return this;
+  }
 
-  // host(h: string) {
-  //   this._url.host = h;
-  //   return this;
-  // }
+  hashParams(
+    val: Record<string, string | number | boolean | Date | null | undefined>,
+    mode: "reset" | "merge" = "reset",
+  ): BuildURI {
+    this._url.hash = setParams(this._url.hash.replace(/^#/, ""), val, mode);
+    return this;
+  }
 
   delParam(key: string): BuildURI {
     this._url.searchParams.delete(key);
@@ -271,8 +565,29 @@ export class BuildURI {
     return this._url.searchParams.has(key);
   }
 
-  getParam(key: string): string | undefined {
-    return falsy2undef(this._url.searchParams.get(key));
+  get getParams(): Iterable<[string, string]> {
+    return URLSearchParamsEntries(this._url.searchParams);
+  }
+
+  getParam<T extends string | undefined>(key: string | OneKey<string>, def?: T): T extends string ? string : string | undefined {
+    const { key: k, def: d } = coerceKey(key, def);
+    let val = this._url.searchParams.get(k);
+    if (!falsy2undef(val) && d) {
+      val = d;
+    }
+    return falsy2undef(val) as T extends string ? string : string | undefined;
+  }
+
+  getParamResult(key: string, msgFn?: (key: string) => string): Result<string> {
+    return getParamResult(key, this.getParam(key), msgFn);
+  }
+
+  getParamsResult(...keys: KeysParam): Result<Record<string, string>> {
+    return getParamsResult(keys, this);
+  }
+
+  getHashParams(...keys: KeysParam): Result<Record<string, string>> {
+    return getParamsResult(keys, resolveHash(this._url.hash));
   }
 
   toString(): string {
@@ -283,6 +598,26 @@ export class BuildURI {
     return this.toString();
   }
 
+  asURL(): URL {
+    return this.URI().asURL();
+  }
+
+  asObj(...strips: StripCommand[]): Partial<HostURIObject | PathURIObject> {
+    return this.URI().asObj(...strips);
+  }
+
+  clone(): BuildURI {
+    return BuildURI.from(this.toString());
+  }
+
+  get onlyHostAndSchema(): string {
+    return this.clone().pathname("").cleanParams().hash("").toString();
+  }
+
+  get withoutHostAndSchema(): string {
+    return this._url.pathname + this._url.search + this._url.hash;
+  }
+
   URI(): URI {
     return URI.from(this._url);
   }
@@ -290,18 +625,42 @@ export class BuildURI {
 
 export type CoerceURI = string | URI | MutableURL | URL | BuildURI | NullOrUndef;
 
-export const protocols: Set<string> = new Set<string>(["http", "https", "ws", "wss"]);
+export function isCoerceURI(value: unknown): value is CoerceURI {
+  if (!value) {
+    return false;
+  }
+  if (isURL(value)) {
+    // includes MutableURL
+    return true;
+  }
+  if (URI.is(value)) {
+    return true;
+  }
+  if (BuildURI.is(value)) {
+    return true;
+  }
+  if (typeof value === "string") {
+    return true;
+  }
+  return false;
+}
+
+export const hasHostPartProtocols: Set<string> = new Set<string>(["http", "https", "ws", "wss"]);
 
 // non mutable URL Implementation
-export class URI {
+export class URI implements URIInterface<URI> {
   static protocolHasHostpart(protocol: string): () => void {
     protocol = protocol.replace(/:$/, "");
-    protocols.add(protocol);
+    hasHostPartProtocols.add(protocol);
     return () => {
-      protocols.delete(protocol);
+      hasHostPartProtocols.delete(protocol);
     };
   }
 
+  match(other: CoerceURI): MatchResult {
+    return match(this, other);
+  }
+
   // if no protocol is provided, default to file:
   static merge(into: CoerceURI, from: CoerceURI, defaultProtocol = "file:"): URI {
     const intoUrl = BuildURI.from(into, defaultProtocol);
@@ -350,6 +709,14 @@ export class URI {
     return this._url.hostname;
   }
 
+  get onlyHostAndSchema(): string {
+    return this.build().pathname("").cleanParams().hash("").toString();
+  }
+
+  get withoutHostAndSchema(): string {
+    return this._url.pathname + this._url.search + this._url.hash;
+  }
+
   // get password(): string {
   //   return this._url.password;
   // }
@@ -366,9 +733,9 @@ export class URI {
   //   return this._url.username;
   // }
 
-  // get search(): string {
-  //   return this._url.search;
-  // }
+  get search(): string {
+    return this._url.search;
+  }
 
   get protocol(): string {
     return this._url.protocol;
@@ -382,23 +749,45 @@ export class URI {
     //   .replace(/\?.*$/, "");
   }
 
-  // get hash(): string {
-  //   return this._url.hash;
-  // }
+  get hash(): string {
+    return this._url.hash;
+  }
 
   // get host(): string {
   //   return this._url.host;
   // }
 
   get getParams(): Iterable<[string, string]> {
-    return this._url.searchParams.entries();
+    return URLSearchParamsEntries(this._url.searchParams);
+  }
+
+  get getHashes(): Iterable<[string, string]> {
+    return URLSearchParamsEntries(new URLSearchParams(this._url.hash.slice("#".length)));
   }
 
   hasParam(key: string): boolean {
     return this._url.searchParams.has(key);
   }
-  getParam(key: string): string | undefined {
-    return falsy2undef(this._url.searchParams.get(key));
+
+  getParam<T extends string | undefined>(key: string | OneKey<string>, def?: T): T extends string ? string : string | undefined {
+    const { key: k, def: d } = coerceKey(key, def);
+    let val = this._url.searchParams.get(k);
+    if (!falsy2undef(val) && d) {
+      val = d;
+    }
+    return falsy2undef(val) as T extends string ? string : string | undefined;
+  }
+
+  getParamResult(key: string, msgFn?: (key: string) => string): Result<string> {
+    return getParamResult(key, this.getParam(key), msgFn);
+  }
+
+  getParamsResult(...keys: KeysParam): Result<Record<string, string>> {
+    return getParamsResult(keys, this);
+  }
+
+  getHashParams(...keys: KeysParam): Result<Record<string, string>> {
+    return getParamsResult(keys, resolveHash(this._url.hash));
   }
 
   clone(): URI {
@@ -418,4 +807,21 @@ export class URI {
   toJSON(): string {
     return this.toString();
   }
+  asObj(...strips: StripCommand[]): Partial<HostURIObject | PathURIObject> {
+    const pathURI: PathURIObject = {
+      style: "path",
+      protocol: this.protocol,
+      pathname: this.pathname,
+      searchParams: Object.fromEntries(this.getParams),
+    };
+    if (hasHostPartProtocols.has(this.protocol.replace(/:$/, ""))) {
+      return stripper(strips, {
+        ...pathURI,
+        style: "host",
+        hostname: this.hostname,
+        port: this.port,
+      }) as Partial<HostURIObject>;
+    }
+    return stripper(strips, pathURI) as Partial<PathURIObject>;
+  }
 }