@planet-matrix/mobius-model 0.6.0 → 0.10.1

package/src/route/uri/hash.ts

@@ -0,0 +1,307 @@
+/**
+ * 判断给定值是否为字符串。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = internalIsString("#page=1")
+ *
+ * // Expect: false
+ * const example2 = internalIsString({ page: "1" })
+ * ```
+ */
+const internalIsString = (value: unknown): value is string => {
+  return typeof value === "string"
+}
+
+/**
+ * 判断给定值是否为普通对象。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = internalIsObject({ page: "1" })
+ *
+ * // Expect: false
+ * const example2 = internalIsObject(["page"])
+ * ```
+ */
+const internalIsObject = (value: unknown): value is Record<string, string> => {
+  return typeof value === "object" && value !== null && Array.isArray(value) === false
+}
+
+/**
+ * 将单个 hash 条目拆分为 key 和 value。
+ *
+ * @example
+ * ```
+ * // Expect: ["page", "1"]
+ * const example1 = internalSplitHashEntry("page=1")
+ *
+ * // Expect: ["formula", "a=b"]
+ * const example2 = internalSplitHashEntry("formula=a=b")
+ * ```
+ */
+const internalSplitHashEntry = (hashEntry: string): [key: string, value: string] => {
+  const internalEqualSignIndex = hashEntry.indexOf("=")
+
+  if (internalEqualSignIndex === -1) {
+    const key = hashEntry
+    const value = ""
+    return [key, value]
+  }
+
+  const key = hashEntry.slice(0, internalEqualSignIndex)
+  const value = hashEntry.slice(internalEqualSignIndex + 1)
+  return [key, value]
+}
+
+export type HashStringLoose = string
+/**
+ * 带 `#` 前缀的 hash 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: "#page=1"
+ * const example1: HashString = "#page=1"
+ * ```
+ */
+export type HashStringStrict = `#${string}`
+
+/**
+ * hash 参数对象。
+ *
+ * @example
+ * ```
+ * // Expect: { page: "1" }
+ * const example1: HashObject = { page: "1" }
+ * ```
+ */
+export type HashObject = Record<string, string>
+
+/**
+ * hash 支持的输入或输出形态。
+ *
+ * @example
+ * ```
+ * // Expect: "#page=1"
+ * const example1: HashUnion = "#page=1"
+ *
+ * // Expect: { page: "1" }
+ * const example2: HashUnion = { page: "1" }
+ * ```
+ */
+export type HashUnion = HashStringLoose | HashStringStrict | HashObject
+
+/**
+ * 规范化 hash 字符串，确保其带有 `#` 前缀。
+ *
+ * @example
+ * ```
+ * // Expect: "#name=cigaret"
+ * const example1 = neatenHash("#name=cigaret")
+ *
+ * // Expect: "#name=cigaret"
+ * const example2 = neatenHash("name=cigaret")
+ * ```
+ */
+export const neatenHash = (target: string): HashStringStrict => {
+  return target.startsWith("#") ? (target as HashStringStrict) : `#${target}`
+}
+
+/**
+ * 将 hash 字符串解析为 hash 参数对象。
+ *
+ * @example
+ * ```
+ * // Expect: { name: "cigaret" }
+ * const example1 = hashStringToHashObject("#name=cigaret")
+ *
+ * // Expect: { formula: "a=b" }
+ * const example2 = hashStringToHashObject("#formula=a%3Db")
+ * ```
+ */
+export const hashStringToHashObject = (target: HashStringLoose): HashObject => {
+  const hashString = neatenHash(target)
+  const hashEntries = hashString.slice(1).split("&")
+  const hashObject: HashObject = {}
+
+  hashEntries.forEach((hashEntry) => {
+    if (hashEntry !== "") {
+      const [rawKey, rawValue] = internalSplitHashEntry(hashEntry)
+      hashObject[decodeURIComponent(rawKey)] = decodeURIComponent(rawValue)
+    }
+  })
+
+  return hashObject
+}
+
+/**
+ * 将 hash 参数对象序列化为 hash 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: "#name=cigaret"
+ * const example1 = hashObjectToHashString({ name: "cigaret" })
+ *
+ * // Expect: "#formula=a%3Db"
+ * const example2 = hashObjectToHashString({ formula: "a=b" })
+ * ```
+ */
+export const hashObjectToHashString = (target: HashObject): HashStringStrict => {
+  const hashString = Object.entries(target)
+    .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+    .join("&")
+
+  return neatenHash(hashString)
+}
+
+/**
+ * 将 hash 统一转换为 hash 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: "#page=1"
+ * const example1 = toHashString("#page=1")
+ *
+ * // Expect: "#page=1"
+ * const example2 = toHashString({ page: "1" })
+ * ```
+ */
+export const toHashString = (target: HashUnion): HashStringStrict => {
+  if (internalIsString(target)) {
+    return neatenHash(target)
+  }
+  else if (internalIsObject(target)) {
+    return hashObjectToHashString(target)
+  }
+  else {
+    throw (new TypeError("\"target\" is expected to be type of \"string\" | \"object\"."))
+  }
+}
+
+/**
+ * 将 hash 统一转换为 hash 参数对象。
+ *
+ * @example
+ * ```
+ * // Expect: { page: "1" }
+ * const example1 = toHashObject("#page=1")
+ *
+ * // Expect: { page: "1" }
+ * const example2 = toHashObject({ page: "1" })
+ * ```
+ */
+export const toHashObject = (target: HashUnion): HashObject => {
+  if (internalIsString(target)) {
+    return hashStringToHashObject(target)
+  }
+  else if (internalIsObject(target)) {
+    return target
+  }
+  else {
+    throw (new TypeError("\"target\" is expected to be type of \"string\" | \"object\"."))
+  }
+}
+
+/**
+ * 宽松包含关系：hash 参数的键集合是目标 hash 参数键集合的子集。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isHashLooseIncludes("#a=1&b=2", ["a"])
+ *
+ * // Expect: false
+ * const example2 = isHashLooseIncludes("#a=1&b=2", ["a", "c"])
+ * ```
+ */
+export const isHashLooseIncludes = (hash: HashUnion, keys: string | string[]): boolean => {
+  const existKeys = Object.keys(toHashObject(hash))
+  const targetKeys = internalIsString(keys) ? [keys] : keys
+  return targetKeys.every(targetKey => existKeys.includes(targetKey))
+}
+
+/**
+ * 严格包含关系：hash 参数的键集合与目标 hash 参数键集合完全相同。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isHashStrictIncludes("#a=1&b=2", ["a", "b"])
+ *
+ * // Expect: false
+ * const example2 = isHashStrictIncludes("#a=1&b=2", ["a"])
+ * ```
+ */
+export const isHashStrictIncludes = (hash: HashUnion, keys: string | string[]): boolean => {
+  const existKeys = Object.keys(toHashObject(hash)).toSorted()
+  const targetKeys = (internalIsString(keys) ? [keys] : keys).toSorted()
+
+  if (existKeys.length !== targetKeys.length) {
+    return false
+  }
+
+  return existKeys.every((key, index) => key === targetKeys[index])
+}
+
+/**
+ * 包含关系：hash 参数的键集合必须包含目标 hash 参数键集合，并且不能包含除目标 hash 参数键集合之外的其他键。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isHashIncludes("#a=1&b=2", { a: "required", b: "optional" })
+ *
+ * // Expect: false
+ * const example2 = isHashIncludes("#a=1&b=2", { a: "required" })
+ * ```
+ */
+export const isHashIncludes = (hash: HashUnion, keys: Record<string, "required" | "optional">): boolean => {
+  const existKeys = Object.keys(toHashObject(hash))
+  const requiredKeys = Object.entries(keys).filter(([, value]) => value === "required").map(([key]) => key)
+  const optionalKeys = Object.entries(keys).filter(([, value]) => value === "optional").map(([key]) => key)
+
+  const requiredKeysExist = requiredKeys.every(requiredKey => existKeys.includes(requiredKey))
+  const extraKeysExist = existKeys.some(existKey => !requiredKeys.includes(existKey) && !optionalKeys.includes(existKey))
+
+  return requiredKeysExist && !extraKeysExist
+}
+
+/**
+ * 宽松相等：hash 参数的键集合是目标 hash 参数键集合的子集，并且对应的值相等。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isHashLooseEqual("#a=1&b=2", "#a=1")
+ *
+ * // Expect: false
+ * const example2 = isHashLooseEqual("#a=1&b=2", "#a=1&c=3")
+ * ```
+ */
+export const isHashLooseEqual = (hashA: HashUnion, hashB: HashUnion): boolean => {
+  const hashObjectA = toHashObject(hashA)
+  const hashObjectB = toHashObject(hashB)
+  return Object.entries(hashObjectB).every(([key, value]) => hashObjectA[key] === value)
+}
+
+/**
+ * 严格相等：hash 参数的键集合与目标 hash 参数键集合完全相同，并且对应的值相等。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isHashStrictEqual("#a=1&b=2", "#b=2&a=1")
+ *
+ * // Expect: false
+ * const example2 = isHashStrictEqual("#a=1&b=2", "#a=1")
+ * ```
+ */
+export const isHashStrictEqual = (hashA: HashUnion, hashB: HashUnion): boolean => {
+  const hashObjectA = toHashObject(hashA)
+  const hashObjectB = toHashObject(hashB)
+  const lengthEqual = Object.keys(hashObjectA).length === Object.keys(hashObjectB).length
+  const valueEqual = Object.entries(hashObjectB).every(([key, value]) => hashObjectA[key] === value)
+  return lengthEqual && valueEqual
+}

package/src/route/uri/index.ts

@@ -0,0 +1,7 @@
+export * from "./pathname.ts"
+export * from "./search.ts"
+export * from "./hash.ts"
+
+// @see https://developer.mozilla.org/en-US/docs/Glossary/URI
+// @see https://developer.mozilla.org/zh-CN/docs/Web/API/Location
+// @see https://github.com/medialize/URI

package/src/route/uri/pathname.ts

@@ -0,0 +1,376 @@
+
+/**
+ * 判断给定值是否为字符串。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = internalIsString("/app/page")
+ *
+ * // Expect: false
+ * const example2 = internalIsString(["app", "page"])
+ * ```
+ */
+const internalIsString = (value: unknown): value is string => {
+  return typeof value === "string"
+}
+
+/**
+ * 判断给定值是否为数组。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = internalIsArray(["app", "page"])
+ *
+ * // Expect: false
+ * const example2 = internalIsArray("/app/page")
+ * ```
+ */
+const internalIsArray = (value: unknown): value is unknown[] => {
+  return Array.isArray(value)
+}
+
+/**
+ * 判断给定值是否为真值。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = internalIsTruthy("page")
+ *
+ * // Expect: false
+ * const example2 = internalIsTruthy("")
+ * ```
+ */
+const internalIsTruthy = (value: unknown): boolean => {
+  return Boolean(value)
+}
+
+/**
+ * 以字符串形式表示的 pathname。
+ *
+ * @example
+ * ```
+ * // Expect: "/app/page"
+ * const example1: PathnameString = "/app/page"
+ * ```
+ */
+export type PathnameString = string
+
+/**
+ * 以路径段数组形式表示的 pathname。
+ *
+ * @example
+ * ```
+ * // Expect: ["", "app", "page"]
+ * const example1: PathnameArray = ["", "app", "page"]
+ * ```
+ */
+export type PathnameArray = string[]
+
+/**
+ * pathname 支持的输入或输出形态。
+ *
+ * @example
+ * ```
+ * // Expect: "/app/page"
+ * const example1: PathnameUnion = "/app/page"
+ *
+ * // Expect: ["", "app", "page"]
+ * const example2: PathnameUnion = ["", "app", "page"]
+ * ```
+ */
+export type PathnameUnion = PathnameString | PathnameArray
+
+/**
+ * 移除数组中相邻且重复的字符串。
+ *
+ * @example
+ * ```
+ * // Expect: ["", "app", "page", ""]
+ * const example1 = removeConsecutiveRepetition(["", "", "app", "app", "page", ""])
+ * ```
+ */
+export const removeConsecutiveRepetition = (targetStrings: string[]): string[] => {
+  return targetStrings.filter((item: string, index: number, array: string[]) => {
+    return array[index - 1] !== undefined ? item !== array[index - 1] : true
+  })
+}
+
+/**
+ * 仅对指定目标值移除相邻重复项。
+ *
+ * @example
+ * ```
+ * // Expect: ["", "app", "/", "page", "page"]
+ * const example1 = removeConsecutiveRepetitionOf(["", "", "app", "/", "/", "page", "page"], ["", "/"])
+ * ```
+ */
+export const removeConsecutiveRepetitionOf = (target: string[], ofList: string[]): string[] => {
+  return target.filter((item: string, index: number, array: string[]) => {
+    return (array[index - 1] !== undefined && ofList.includes(item)) ? item !== array[index - 1] : true
+  })
+}
+
+/**
+ * 移除不在例外名单中的相邻重复项。
+ *
+ * @example
+ * ```
+ * // Expect: ["", "", "app", "page", "", ""]
+ * const example1 = removeConsecutiveRepetitionExcept(["", "", "app", "app", "page", "page", "", ""], [""])
+ * ```
+ */
+export const removeConsecutiveRepetitionExcept = (target: string[], exceptList: string[]): string[] => {
+  return target.filter((item: string, index: number, array: string[]) => {
+    return (array[index - 1] !== undefined && !exceptList.includes(item)) ? item !== array[index - 1] : true
+  })
+}
+
+/**
+ * 移除相邻重复的空字符串。
+ *
+ * @example
+ * ```
+ * // Expect: ["", "app", "", "page", ""]
+ * const example1 = removeConsecutiveRepetitionOfEmpty(["", "", "app", "", "", "page", ""])
+ * ```
+ */
+export const removeConsecutiveRepetitionOfEmpty = (target: string[]): string[] => {
+  return removeConsecutiveRepetitionOf(target, [""])
+}
+
+/**
+ * 移除相邻重复的斜杠字符。
+ *
+ * @example
+ * ```
+ * // Expect: ["/", "a", "/", "b"]
+ * const example1 = removeConsecutiveRepetitionOfSlash(["/", "/", "a", "/", "/", "/", "b"])
+ * ```
+ */
+export const removeConsecutiveRepetitionOfSlash = (target: string[]): string[] => {
+  return removeConsecutiveRepetitionOf(target, ["/"])
+}
+
+/**
+ * 移除路径数组内部的空字符串，但保留首尾位置的空字符串。
+ *
+ * @example
+ * ```
+ * // Expect: ["", "app", "page", ""]
+ * const example1 = removeInnerEmptyStringInArray(["", "app", "", "page", ""])
+ * ```
+ */
+export const removeInnerEmptyStringInArray = (target: string[]): string[] => {
+  return target.filter((item, index, arr) => (index === 0 || index === arr.length - 1) ? true : item !== "")
+}
+
+/**
+ * 保证根路径至少保留为 `["", ""]` 的最小结构。
+ *
+ * @example
+ * ```
+ * // Expect: ["", ""]
+ * const example1 = keepMinimumPathArray([""])
+ *
+ * // Expect: ["", "app"]
+ * const example2 = keepMinimumPathArray(["", "app"])
+ * ```
+ */
+export const keepMinimumPathArray = (target: string[]): string[] => {
+  return target.length === 1 && target[0] === "" ? ["", ""] : target
+}
+
+/**
+ * 规范化 pathname，使其具备稳定的根前缀和重复分隔符语义。
+ *
+ * @example
+ * ```
+ * // Expect: ["", "app", "page", ""]
+ * const example1 = neatenPathname(["app", "", "page", ""])
+ *
+ * // Expect: "/app/page/"
+ * const example2 = neatenPathname("//app//page//")
+ * ```
+ */
+export const neatenPathname = (pathname: PathnameUnion): typeof pathname => {
+  if (internalIsArray(pathname)) {
+    // 第一步：补上根路径前缀，使数组形式始终从空字符串起始。
+    const _0 = ["", ...pathname]
+
+    // 第二步：折叠连续的空字符串，避免重复分隔段。
+    const _1 = removeConsecutiveRepetitionOfEmpty(_0)
+
+    // 第三步：确保根路径仍至少保留 `['', '']` 的最小表达。
+    const _2 = keepMinimumPathArray(_1)
+
+    // 第四步：移除中间无意义的空路径段，同时保留首尾语义。
+    const _3 = removeInnerEmptyStringInArray(_2)
+
+    return _3
+  }
+  else if (internalIsString(pathname)) {
+    // 第一步：拆成字符数组，便于统一处理连续斜杠。
+    // oxlint-disable-next-line typescript/no-misused-spread
+    const _0 = [...pathname]
+
+    // 第二步：补上根路径斜杠，确保字符串形式总是绝对路径语义。
+    const _1 = ["/", ..._0]
+
+    // 第三步：折叠连续斜杠，避免出现多余分隔符。
+    const _2 = removeConsecutiveRepetitionOfSlash(_1)
+
+    // 第四步：回到标准字符串，再按路径段拆分做后续清理。
+    const _3 = _2.join("")
+    const _4 = _3.split("/")
+
+    // 第五步：折叠空路径段，并保留根与尾部斜杠语义。
+    const _5 = removeConsecutiveRepetitionOfEmpty(_4)
+    const _6 = keepMinimumPathArray(_5)
+
+    // 第六步：重新拼回字符串形式，得到稳定输出。
+    const _7 = _6.join("/")
+
+    return _7
+  }
+  else {
+    throw (new TypeError("\"pathname\" must be string or array."))
+  }
+}
+
+/**
+ * 将 pathname 转换为路径段数组形式。
+ *
+ * @example
+ * ```
+ * // Expect: ["", "app", "page"]
+ * const example1 = toPathnameArray("app/page")
+ *
+ * // Expect: ["", "app", "page", ""]
+ * const example2 = toPathnameArray(["", "app", "", "page", ""])
+ * ```
+ */
+export const toPathnameArray = (pathname: PathnameUnion): PathnameArray => {
+  const neatedPathname = neatenPathname(pathname)
+  if (internalIsArray(neatedPathname)) {
+    return neatedPathname
+  } if (internalIsString(neatedPathname)) {
+    return neatedPathname.split("/")
+  }
+  else {
+    throw (new TypeError("\"pathname\" must be string or array."))
+  }
+}
+
+/**
+ * 将 pathname 转换为标准字符串形式。
+ *
+ * @example
+ * ```
+ * // Expect: "/app/page"
+ * const example1 = toPathnameString(["app", "page"])
+ *
+ * // Expect: "/app/page/"
+ * const example2 = toPathnameString("//app//page//")
+ * ```
+ */
+export const toPathnameString = (pathname: PathnameUnion): PathnameString => {
+  const neatedPathname = neatenPathname(pathname)
+  if (internalIsString(neatedPathname)) {
+    return neatedPathname
+  } if (internalIsArray(neatedPathname)) {
+    return neatedPathname.join("/")
+  }
+  else {
+    throw (new TypeError("\"pathname\" must be string or array."))
+  }
+}
+
+export const isPathnameLooseIncludes = (pathname: PathnameUnion, pieces: string | string[]): boolean => {
+  const pathnameArray = toPathnameArray(pathname)
+  const piecesArray = internalIsArray(pieces) ? pieces : [pieces]
+  return piecesArray.every(piece => pathnameArray.includes(piece))
+}
+
+export const isPathnameStrictIncludes = (pathname: PathnameUnion, pieces: string | string[]): boolean => {
+  const pathnameString = toPathnameString(pathname)
+  const piecesString = toPathnameString(pieces)
+  return pathnameString.includes(piecesString)
+}
+
+export const isPathnameIncludes = (mode: "strict" | "loose", pathname: PathnameUnion, pieces: string | string[]): boolean => {
+  switch (mode) {
+    case "strict": {
+      return isPathnameStrictIncludes(pathname, pieces)
+    }
+    case "loose": {
+      return isPathnameLooseIncludes(pathname, pieces)
+    }
+    default: {
+      throw (new TypeError("\"mode\" must be \"strict\" or \"loose\"."))
+    }
+  }
+}
+
+/**
+ * 以严格模式比较两个 pathname 是否相等。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isPathnameStrictEqual("/app/page", "/app/page")
+ *
+ * // Expect: false
+ * const example2 = isPathnameStrictEqual("/app/page", "/app/page/")
+ * ```
+ */
+export const isPathnameStrictEqual = (pathname1: PathnameUnion, pathname2: PathnameUnion): boolean => {
+  return toPathnameString(pathname1) === toPathnameString(pathname2)
+}
+
+/**
+ * 以宽松模式比较两个 pathname 是否相等，并忽略尾部斜杠差异。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isPathnameLooseEqual("/app/page", "/app/page")
+ *
+ * // Expect: true
+ * const example2 = isPathnameLooseEqual("/app/page", "/app/page/")
+ * ```
+ */
+export const isPathnameLooseEqual = (pathname1: PathnameUnion, pathname2: PathnameUnion): boolean => {
+  const preCook = (pathname: PathnameUnion): string => {
+    return toPathnameArray(pathname).filter(str => internalIsTruthy(str)).join("/")
+  }
+  return preCook(pathname1) === preCook(pathname2)
+}
+
+/**
+ * 根据指定模式比较两个 pathname 是否相等。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isPathnameEqual("strict", "/app/page", ["", "app", "page"])
+ *
+ * // Expect: true
+ * const example2 = isPathnameEqual("loose", "/app/page", "/app/page/")
+ * ```
+ */
+export const isPathnameEqual = (mode: "strict" | "loose", pathname1: PathnameUnion, pathname2: PathnameUnion): boolean => {
+  switch (mode) {
+    case "strict": {
+      return isPathnameStrictEqual(pathname1, pathname2)
+    }
+    case "loose": {
+      return isPathnameLooseEqual(pathname1, pathname2)
+    }
+    default: {
+      throw (new TypeError("\"mode\" must be \"strict\" or \"loose\"."))
+    }
+  }
+}