@planet-matrix/mobius-model 0.6.0 → 0.9.0

package/src/route/uri/search.ts

@@ -0,0 +1,413 @@
+/**
+ * 判断给定值是否为字符串。
+ *
+ * @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
+}
+
+/**
+ * 将单个 query 拆分为 key 和 value。
+ *
+ * @example
+ * ```
+ * // Expect: ["page", "1"]
+ * const example1 = internalSplitQueryEntry("page=1")
+ *
+ * // Expect: ["formula", "a=b"]
+ * const example2 = internalSplitQueryEntry("formula=a=b")
+ * ```
+ */
+const internalSplitQueryEntry = (query: string): [key: string, value: string] => {
+  const internalEqualSignIndex = query.indexOf("=")
+
+  if (internalEqualSignIndex === -1) {
+    const key = query
+    const value = ""
+    return [key, value]
+  }
+
+  const key = query.slice(0, internalEqualSignIndex)
+  const value = query.slice(internalEqualSignIndex + 1)
+  return [key, value]
+}
+
+/**
+ * 不带 `?` 前缀的 query 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: "page=1"
+ * const example1: QueryString = "page=1"
+ * ```
+ */
+export type QueryString = string
+
+/**
+ * 查询参数对象。
+ *
+ * @example
+ * ```
+ * // Expect: { page: "1" }
+ * const example1: QueryObject = { page: "1" }
+ * ```
+ */
+export type QueryObject = Record<string, string>
+
+/**
+ * 查询参数支持的输入或输出形态。
+ *
+ * @example
+ * ```
+ * // Expect: "page=1"
+ * const example1: QueryUnion = "page=1"
+ *
+ * // Expect: { page: "1" }
+ * const example2: QueryUnion = { page: "1" }
+ * ```
+ */
+export type QueryUnion = QueryString | QueryObject
+
+export type SearchStringLoose = string
+/**
+ * 带 `?` 前缀的 search 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: "?page=1"
+ * const example1: SearchStringStrict = "?page=1"
+ * ```
+ */
+export type SearchStringStrict = `?${string}`
+
+export type SearchUnion = QueryString | QueryObject | SearchStringLoose | SearchStringStrict
+
+/**
+ * 规范化 search 字符串，确保其带有 `?` 前缀。
+ *
+ * @example
+ * ```
+ * // Expect: "?name=cigaret"
+ * const example1 = neatenSearch("?name=cigaret")
+ *
+ * // Expect: "?name=cigaret"
+ * const example2 = neatenSearch("name=cigaret")
+ * ```
+ */
+export const neatenSearch = (target: string): SearchStringStrict => {
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+  return target.startsWith("?") ? (target as SearchStringStrict) : `?${target}`
+}
+
+/**
+ * 规范化 query 字符串，确保其不带 `?` 前缀。
+ *
+ * @example
+ * ```
+ * // Expect: "name=cigaret"
+ * const example1 = neatenQueryString("?name=cigaret")
+ *
+ * // Expect: "name=cigaret"
+ * const example2 = neatenQueryString("name=cigaret")
+ * ```
+ */
+export const neatenQueryString = (target: string): QueryString => {
+  return target.startsWith("?") ? target.slice(1) : target
+}
+
+/**
+ * 将 query 字符串解析为查询参数对象。
+ *
+ * @example
+ * ```
+ * // Expect: { name: "cigaret" }
+ * const example1 = queryStringToQueryObject("name=cigaret")
+ *
+ * // Expect: { formula: "a=b" }
+ * const example2 = queryStringToQueryObject("formula=a%3Db")
+ * ```
+ */
+export const queryStringToQueryObject = (target: QueryString): QueryObject => {
+  const queryString = neatenQueryString(target)
+  const querys = queryString.split("&")
+  const queryObject: QueryObject = {}
+
+  querys.forEach((query) => {
+    if (query !== "") {
+      const [rawKey, rawValue] = internalSplitQueryEntry(query)
+      queryObject[decodeURIComponent(rawKey)] = decodeURIComponent(rawValue)
+    }
+  })
+
+  return queryObject
+}
+
+/**
+ * 将查询参数对象序列化为 query 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: "name=cigaret"
+ * const example1 = queryObjectToQueryString({ name: "cigaret" })
+ *
+ * // Expect: "formula=a%3Db"
+ * const example2 = queryObjectToQueryString({ formula: "a=b" })
+ * ```
+ */
+export const queryObjectToQueryString = (target: QueryObject): QueryString => {
+  const queryString = Object.entries(target)
+    .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+    .join("&")
+
+  return queryString
+}
+
+/**
+ * 将 search 字符串转换为 query 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: "page=1"
+ * const example1 = searchToQueryString("?page=1")
+ * ```
+ */
+export const searchToQueryString = (target: SearchStringLoose): QueryString => {
+  return neatenQueryString(target)
+}
+
+/**
+ * 将 search 字符串解析为查询参数对象。
+ *
+ * @example
+ * ```
+ * // Expect: { page: "1", size: "20" }
+ * const example1 = searchToQueryObject("?page=1&size=20")
+ * ```
+ */
+export const searchToQueryObject = (target: SearchStringLoose): QueryObject => {
+  return queryStringToQueryObject(searchToQueryString(target))
+}
+
+/**
+ * 将 query 字符串转换为 search 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: "?page=1"
+ * const example1 = queryStringToSearch("page=1")
+ * ```
+ */
+export const queryStringToSearch = (target: QueryString): SearchStringStrict => {
+  return neatenSearch(target)
+}
+
+/**
+ * 将查询参数对象转换为 search 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: "?page=1&size=20"
+ * const example1 = queryObjectToSearch({ page: "1", size: "20" })
+ * ```
+ */
+export const queryObjectToSearch = (target: QueryObject): SearchStringStrict => {
+  return queryStringToSearch(queryObjectToQueryString(target))
+}
+
+/**
+ * 将查询参数统一转换为 search 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: "?page=1"
+ * const example1 = toSearch("page=1")
+ *
+ * // Expect: "?page=1"
+ * const example2 = toSearch({ page: "1" })
+ * ```
+ */
+export const toSearch = (target: SearchUnion): SearchStringStrict => {
+  if (internalIsString(target)) {
+    return neatenSearch(target)
+  }
+  else if (internalIsObject(target)) {
+    return queryObjectToSearch(target)
+  }
+  else {
+    throw (new TypeError("\"target\" is expected to be type of \"string\" | \"object\"."))
+  }
+}
+
+/**
+ * 将查询参数统一转换为 query 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: "page=1"
+ * const example1 = toQueryString("?page=1")
+ *
+ * // Expect: "page=1"
+ * const example2 = toQueryString({ page: "1" })
+ * ```
+ */
+export const toQueryString = (target: SearchUnion): QueryString => {
+  if (internalIsString(target)) {
+    return neatenQueryString(target)
+  }
+  else if (internalIsObject(target)) {
+    return queryObjectToQueryString(target)
+  }
+  else {
+    throw (new TypeError("\"target\" is expected to be type of \"string\" | \"object\"."))
+  }
+}
+
+/**
+ * 将查询参数统一转换为查询参数对象。
+ *
+ * @example
+ * ```
+ * // Expect: { page: "1" }
+ * const example1 = toQueryObject("?page=1")
+ *
+ * // Expect: { page: "1" }
+ * const example2 = toQueryObject({ page: "1" })
+ * ```
+ */
+export const toQueryObject = (target: SearchUnion): QueryObject => {
+  if (internalIsString(target)) {
+    return queryStringToQueryObject(target)
+  }
+  else if (internalIsObject(target)) {
+    return target
+  }
+  else {
+    throw (new TypeError("\"target\" is expected to be type of \"string\" | \"object\"."))
+  }
+}
+
+/**
+ * 宽松包含关系：查询参数的键集合是目标查询参数键集合的子集。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isSearchLooseIncludes("?a=1&b=2", ["a"])
+ *
+ * // Expect: false
+ * const example2 = isSearchLooseIncludes("?a=1&b=2", ["a", "c"])
+ * ```
+ */
+export const isSearchLooseIncludes = (search: SearchUnion, query: string | string[]): boolean => {
+  const existKeys = Object.keys(toQueryObject(search))
+  const queryKeys = internalIsString(query) ? [query] : query
+  return queryKeys.every(queryKey => existKeys.includes(queryKey))
+}
+
+/**
+ * 严格包含关系：查询参数的键集合与目标查询参数键集合完全相同。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isSearchStrictIncludes("?a=1&b=2", ["a", "b"])
+ *
+ * // Expect: false
+ * const example2 = isSearchStrictIncludes("?a=1&b=2", ["a"])
+ * ```
+ */
+export const isSearchStrictIncludes = (search: SearchUnion, query: string | string[]): boolean => {
+  const existKeys = Object.keys(toQueryObject(search)).toSorted()
+  const queryKeys = (internalIsString(query) ? [query] : query).toSorted()
+
+  if (existKeys.length !== queryKeys.length) {
+    return false
+  }
+
+  return existKeys.every((key, index) => key === queryKeys[index])
+}
+
+/**
+ * 包含关系：查询参数的键集合必须包含目标查询参数键集合，并且不能包含除目标查询参数键集合之外的其他键。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isSearchIncludes("?a=1&b=2", { a: "required", b: "optional" })
+ *
+ * // Expect: false
+ * const example2 = isSearchIncludes("?a=1&b=2", { a: "required" })
+ * ```
+ */
+export const isSearchIncludes = (search: SearchUnion, query: Record<string, "required" | "optional">): boolean => {
+  const existKeys = Object.keys(toQueryObject(search))
+  const requiredKeys = Object.entries(query).filter(([, value]) => value === "required").map(([key]) => key)
+  const optionalKeys = Object.entries(query).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
+}
+
+/**
+ * 宽松相等：查询参数的键集合是目标查询参数键集合的子集，并且对应的值相等。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isSearchLooseEqual("?a=1&b=2", "?a=1")
+ *
+ * // Expect: false
+ * const example2 = isSearchLooseEqual("?a=1&b=2", "?a=1&c=3")
+ * ```
+ */
+export const isSearchLooseEqual = (searchA: SearchUnion, searchB: SearchUnion): boolean => {
+  const queryObjectA = toQueryObject(searchA)
+  const queryObjectB = toQueryObject(searchB)
+  return Object.entries(queryObjectB).every(([key, value]) => queryObjectA[key] === value)
+}
+
+/**
+ * 严格相等：查询参数的键集合与目标查询参数键集合完全相同，并且对应的值相等。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isSearchStrictEqual("?a=1&b=2", "?b=2&a=1")
+ *
+ * // Expect: false
+ * const example2 = isSearchStrictEqual("?a=1&b=2", "?a=1")
+ * ```
+ */
+export const isSearchStrictEqual = (searchA: SearchUnion, searchB: SearchUnion): boolean => {
+  const queryObjectA = toQueryObject(searchA)
+  const queryObjectB = toQueryObject(searchB)
+  const lengthEqual = Object.keys(queryObjectA).length === Object.keys(queryObjectB).length
+  const valueEqual = Object.entries(queryObjectB).every(([key, value]) => queryObjectA[key] === value)
+  return lengthEqual && valueEqual
+}

package/src/socket/README.md

@@ -0,0 +1,105 @@
+# Socket
+
+## Description
+
+Socket 模块提供围绕双向数据通道（bidirectional data channel）的基础建模能力，用于在客户端与服务端之间组织一类可持续存在、可观测、可发送、可关闭、并带有稳定生命周期语义的数据连接。
+
+Socket 本质上首先是数据通道，而不是某个特定业务协议的实现容器。无论是业务消息，还是心跳、初始化消息等机制性消息，从这个模块的边界来看都属于“通道中流动的数据”；它们可以在行为上被区别对待，但不应在模块级类型边界里被人为拆成两套完全不同的体系。
+
+## For Understanding
+
+理解 Socket 模块时，最重要的前提不是“WebSocket 怎么用”，而是“一个稳定的数据通道模型该对外承诺什么”。这个模块试图表达的，并不是原生 API 的逐项映射，而是以下几类更稳定的公共语义：
+
+- 连接生命周期应被建模为可以推断和观察的状态，而不是依赖零散事件时序去猜测。
+- 通道 ready 语义应明确：只有在传输已打开且当前端点已具备可工作的身份条件后，业务消息和初始消息才应真正发送。
+- 心跳属于通道运行机制的一部分，但仍然是消息流中的数据，不要求固定包结构，也不应把客户端与服务端的方向差异实现成两套长期分叉的运行时。
+- 对外事件应尽量表达稳定状态转移，而不是传播实现过程中的偶然中间态或重复噪音。
+
+因此，这个模块更适合被理解为“围绕数据通道生命周期、消息流转与连接保活机制的统一模型层”，而不是简单的 WebSocket 工具封装。这里有几个关键理解边界需要守住。
+
+第一，客户端和服务端虽然在方向上不同，但它们共享的是同一种问题域：如何让一个通道稳定地进入可工作状态、如何让消息在这个状态下流转、以及如何在通道不再可靠时完成清理。因此，心跳运行时应尽量收束为一套共享实现，用配置表达主动与被动方向差异，而不是把方向差异扩大成重复类层次。
+
+第二，心跳不应要求固定消息形状。这个模块允许使用者通过消息处理器定义“什么是 ping、什么是 pong、如何匹配响应”，统一运行时只负责调度、保留轮次状态、按规则匹配与在超时后做出关闭决策。也就是说，模块公共边界关注的是心跳行为模型，而不是某个预设协议字段。
+
+第三，公共事件的语义必须稳定。比如服务端的 `connect` 应在对应 `SocketUnit` 已经进入可观察、可工作的 started 状态后再发出；客户端的状态事件也应以真实状态迁移为准，而不是在重复消息流量下不断重新广播同一个 `OPEN`。如果公共事件失去这类稳定性，接入者就会被迫去猜内部实现细节，从而破坏模块边界。
+
+第四，这个模块关心的是“通道模型”，不是完整协议栈。它不负责定义认证协商、业务指令格式、重连策略编排、分布式会话一致性或消息持久化语义；这些都可以建立在 Socket 之上，但不应反过来改写 Socket 模块自身的父边界。
+
+## For Using
+
+从使用角度看，Socket 模块大致可以理解为四类能力。
+
+- 通道生命周期能力：用 `SocketUnit` 与更高层的 `Socket` 表达连接的创建、关闭、重建、ready 判定与状态观察，让上层不必直接围绕原生事件时序写分散逻辑。
+- 消息通道能力：统一处理业务消息、初始消息与机制性消息的发送边界。对于调用方来说，只需要关心“当前是否 ready 以及消息何时真正出站”，而不是在每处都手动判断底层传输状态。
+- 心跳保活能力：通过统一心跳运行时支持主动 ping、被动 pong、超时统计、消息匹配与诊断快照。客户端与服务端在方向上可不同，但都应接入同一套共享的心跳建模方式。
+- 服务端承载能力：通过服务端 `Socket` 与 `WebSocketServer` 包装类，管理多连接接入、稳定的连接事件时机，以及可直接用于本地开发和测试的服务地址发现结果。
+
+实际接入时，更合理的思路通常不是先盯着某个方法名，而是先判断你的问题是否确实属于“数据通道模型”边界。例如，如果你需要：
+
+- 在 ready 之前先缓存待发送动作，等连接真正具备工作条件后再统一发送；
+- 把连接状态变化暴露成稳定事件，而不是围绕原生事件做重复判定；
+- 用业务自定义消息结构实现心跳，而不是被迫接受某种固定心跳包格式；
+- 在服务端统一管理多条连接，并对外暴露稳定的 `connect / close / message` 事件面；
+
+那么这个模块就是合适的边界。
+
+相反，如果你的目标主要是定义一套业务协议、管理复杂重连退避、实现会话恢复、做消息落盘或做跨节点广播，这些通常已经超出 Socket 模块本身，应该在更上层的协议、编排或基础设施边界中处理。
+
+## For Contributing
+
+为 Socket 模块继续贡献时，应优先维护这几个不能退让的设计精神，而不是只追求局部功能可用。
+
+- Socket 首先是数据通道模型，文档与实现都不应把它收窄成某个具体业务协议的包装层。
+- 机制性消息与业务消息都属于通道中的数据；心跳可以有自己的行为分支，但不应被提升为一套强绑定消息格式。
+- 心跳运行时应保持单一共享实现，客户端与服务端的方向差异应通过配置、处理器或薄适配层表达，而不是重新复制一套长期分叉的运行时代码。
+- 生命周期事件必须表达稳定状态转移。若某个公开事件只是内部实现顺序的偶然产物，或会在同一状态下重复噪音式触发，就应优先调整实现语义，而不是把不稳定性转嫁给调用方。
+- 服务端连接与客户端连接在语义上应尽量对齐：错误必须被显式观测并进入确定性的清理路径，关闭路径必须保持幂等，ready 相关副作用应由明确的状态转移驱动。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/socket/internal.ts`。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+- 与 socket 相关的实现应优先围绕生命周期状态、ready 语义、消息流转、连接级错误处理、心跳匹配与关闭策略组织，避免把协议专属细节或业务会话策略直接下沉为模块长期公共语义。
+
+### 导出策略要求
+
+- 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的通道语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
+
+### 测试要求
+
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
+- 模块的单元测试文件目录是 `./tests/unit/socket`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/socket/<sub-module-name>`。
+- 对这个模块来说，测试应优先覆盖 ready 状态转移、消息排队与释放、服务端连接事件时机、错误与关闭路径的幂等性、心跳消息匹配顺序、超时关闭阈值，以及服务地址发现结果在本地环境中的可用性。

package/src/socket/client/index.ts

@@ -0,0 +1,2 @@
+export * from "./socket.ts"
+export * from "./socket-unit.ts"