@planet-matrix/mobius-model 0.4.0 → 0.6.0

package/src/css/class.ts

@@ -0,0 +1,559 @@
+/**
+ * 表示以空格分隔的 CSS 类名字串。
+ */
+export type ClassString = string
+
+/**
+ * 表示按顺序保存的 CSS 类名数组。
+ */
+export type ClassArray = string[]
+
+/**
+ * 表示以类名为键、以启用状态为值的 CSS 类名对象。
+ *
+ * 该表示允许保留值为 `false` 的键，以表达已知但当前未启用的类名状态。
+ */
+export type ClassObject = Record<string, boolean>
+
+/**
+ * 表示 CSS 类名的三种公共表达形式：字符串、数组或对象。
+ */
+export type ClassUnion = ClassString | ClassArray | ClassObject
+
+/**
+ * 规范化类名字串，使其适合作为统一的字符串表示。
+ *
+ * 该函数会将 `.` 视为分隔符，将连续空白折叠为一个空格，并移除首尾空白。
+ *
+ * @example
+ * ```
+ * // Expect: 'mobius-base mobius-theme--light'
+ * const example1 = neatenClassString('mobius-base mobius-theme--light')
+ *
+ * // Expect: 'mobius-base mobius-theme--light'
+ * const example2 = neatenClassString('.mobius-base.mobius-theme--light')
+ *
+ * // Expect: 'mobius-base mobius-theme--light'
+ * const example3 = neatenClassString('  .mobius-base   mobius-theme--light  ')
+ * ```
+ */
+export const neatenClassString = (str: string): ClassString => {
+  const classString = str.replaceAll('.', ' ').replaceAll(/\s+/g, ' ').trim()
+  return classString
+}
+
+/**
+ * 将类名字串转换为类名数组。
+ *
+ * 输入会先经过 `neatenClassString` 规范化，再按空格拆分，并移除空项。
+ *
+ * @example
+ * ```
+ * // Expect: ['mobius-base', 'mobius-theme--light']
+ * const example1 = classStringToClassArray('mobius-base mobius-theme--light')
+ *
+ * // Expect: ['mobius-base', 'mobius-theme--light']
+ * const example2 = classStringToClassArray('.mobius-base.mobius-theme--light')
+ *
+ * // Expect: ['mobius-base', 'mobius-theme--light']
+ * const example3 = classStringToClassArray('  .mobius-base   mobius-theme--light  ')
+ * ```
+ */
+export const classStringToClassArray = (str: ClassString): ClassArray => {
+  const classArray = neatenClassString(str).split(' ').filter(s => s.length !== 0)
+  return classArray
+}
+
+/**
+ * 将类名数组转换为布尔对象表示。
+ *
+ * 数组中的每个非空类名都会映射为值为 `true` 的对象键。
+ *
+ * @example
+ * ```
+ * // Expect: { 'mobius-base': true, 'mobius-theme--light': true }
+ * const example1 = classArrayToClassObject(['mobius-base', 'mobius-theme--light'])
+ *
+ * // Expect: { 'mobius-base': true }
+ * const example2 = classArrayToClassObject(['mobius-base', ''])
+ *
+ * // Expect: {}
+ * const example3 = classArrayToClassObject([])
+ * ```
+ */
+export const classArrayToClassObject = (arr: ClassArray): ClassObject => {
+  const classObject: ClassObject = {}
+  arr.filter(s => s.length !== 0).forEach(s => {
+    classObject[s] = true
+  })
+  return classObject
+}
+
+/**
+ * 将类名字串直接转换为布尔对象表示。
+ *
+ * 该函数会先把字符串拆分为类名数组，再将每个类名映射为值为 `true` 的对象键。
+ *
+ * @example
+ * ```
+ * // Expect: { 'mobius-base': true, 'mobius-theme--light': true }
+ * const example1 = classStringToClassObject('mobius-base mobius-theme--light')
+ *
+ * // Expect: { 'mobius-base': true, 'mobius-theme--light': true }
+ * const example2 = classStringToClassObject('.mobius-base.mobius-theme--light')
+ * ```
+ */
+export const classStringToClassObject = (str: ClassString): ClassObject => {
+  const classArray = classStringToClassArray(str)
+  const classObject = classArrayToClassObject(classArray)
+  return classObject
+}
+
+/**
+ * 将布尔对象表示转换为类名数组。
+ *
+ * 值为 `false` 的类名和空类名会被忽略。
+ *
+ * @example
+ * ```
+ * // Expect: ['active', 'primary']
+ * const example1 = classObjectToClassArray({ active: true, disabled: false, primary: true })
+ *
+ * // Expect: ['active']
+ * const example2 = classObjectToClassArray({ '': true, active: true, disabled: false })
+ * ```
+ */
+export const classObjectToClassArray = (obj: ClassObject): ClassArray => {
+  const classArray: string[] = []
+  Object.entries(obj)
+    .filter(([key, value]) => key.length !== 0 && value)
+    .forEach(([key, _]) => {
+      classArray.push(key)
+    })
+  return classArray
+}
+
+/**
+ * 将类名数组按空格连接为类名字串。
+ *
+ * 空字符串项会被过滤，以避免产生多余空格。
+ *
+ * @example
+ * ```
+ * // Expect: 'mobius-base mobius-theme--light'
+ * const example1 = classArrayToClassString(['mobius-base', 'mobius-theme--light'])
+ *
+ * // Expect: 'mobius-base mobius-theme--light'
+ * const example2 = classArrayToClassString(['mobius-base', '', 'mobius-theme--light'])
+ * ```
+ */
+export const classArrayToClassString = (arr: ClassArray): ClassString => {
+  const classString = arr.filter(s => s.length !== 0).join(' ')
+  return classString
+}
+
+/**
+ * 将布尔对象表示转换为类名字串。
+ *
+ * 该函数会忽略值为 `false` 的类名和空类名，并保留其余类名的迭代顺序。
+ *
+ * @example
+ * ```
+ * // Expect: 'active primary'
+ * const example1 = classObjectToClassString({ active: true, disabled: false, primary: true })
+ *
+ * // Expect: 'active'
+ * const example2 = classObjectToClassString({ '': true, active: true, disabled: false })
+ * ```
+ */
+export const classObjectToClassString = (obj: ClassObject): ClassString => {
+  const classArray = classObjectToClassArray(obj)
+  const classString = classArrayToClassString(classArray)
+  return classString
+}
+
+/**
+ * 将任意公共类名表示转换为字符串表示。
+ *
+ * 如果输入本身已经是字符串，则原样返回；数组和对象会分别经过对应的序列化流程。
+ *
+ * @example
+ * ```
+ * // Expect: '  .button   active  '
+ * const example1 = toClassString('  .button   active  ')
+ *
+ * // Expect: 'button active'
+ * const example2 = toClassString(['button', 'active'])
+ *
+ * // Expect: 'button active'
+ * const example3 = toClassString({ button: true, active: true, disabled: false })
+ * ```
+ */
+export const toClassString = (tar: ClassUnion): ClassString => {
+  if (typeof tar === 'string') {
+    return tar
+  } else if (Array.isArray(tar)) {
+    return classArrayToClassString(tar)
+  } else {
+    return classObjectToClassString(tar)
+  }
+}
+
+/**
+ * 将任意公共类名表示转换为数组表示。
+ *
+ * 如果输入本身已经是数组，则会在过滤空类名后返回一个浅拷贝，以避免调用方共享同一数组实例。
+ *
+ * @example
+ * ```
+ * // Expect: ['button', 'active']
+ * const example1 = toClassArray('button active')
+ *
+ * // Expect: ['button', 'active']
+ * const example2 = toClassArray(['button', 'active'])
+ *
+ * // Expect: ['button', 'active']
+ * const example3 = toClassArray({ button: true, disabled: false, active: true })
+ * ```
+ */
+export const toClassArray = (tar: ClassUnion): ClassArray => {
+  if (typeof tar === 'string') {
+    return classStringToClassArray(tar)
+  } else if (Array.isArray(tar)) {
+    return tar.filter(s => s.length !== 0)
+  } else {
+    return classObjectToClassArray(tar)
+  }
+}
+
+/**
+ * 将任意公共类名表示转换为对象表示。
+ *
+ * 如果输入本身已经是对象，则会在过滤空类名后返回一个浅拷贝，以避免外部直接共享内部结果。
+ *
+ * @example
+ * ```
+ * // Expect: { button: true, active: true }
+ * const example1 = toClassObject('button active')
+ *
+ * // Expect: { button: true, active: true }
+ * const example2 = toClassObject(['button', 'active'])
+ *
+ * // Expect: { button: true, active: false }
+ * const example3 = toClassObject({ button: true, active: false, '': true })
+ * ```
+ */
+export const toClassObject = (tar: ClassUnion): ClassObject => {
+  if (typeof tar === 'string') {
+    return classStringToClassObject(tar)
+  } else if (Array.isArray(tar)) {
+    return classArrayToClassObject(tar)
+  } else {
+    const classObject: ClassObject = {}
+    Object.entries(tar).forEach(([key, value]) => {
+      if (key.length !== 0) {
+        classObject[key] = value
+      }
+    })
+    return classObject
+  }
+}
+
+/**
+ * 按目标值的外部表示，将类名集合格式化为相同形态。
+ *
+ * 该函数适合在内部统一按对象进行计算后，再把结果还原为调用方原本使用的表示。
+ *
+ * @example
+ * ```
+ * // Expect: 'button active'
+ * const example1 = formatClassToTarget('', ['button', 'active'])
+ *
+ * // Expect: ['button', 'active']
+ * const example2 = formatClassToTarget([], 'button active')
+ *
+ * // Expect: { button: true, active: true }
+ * const example3 = formatClassToTarget({}, ['button', 'active'])
+ * ```
+ */
+export const formatClassToTarget = <T extends ClassUnion>(target: T, cls: ClassUnion): T => {
+  if (typeof target === 'string') {
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return toClassString(cls) as T
+  } else if (Array.isArray(target)) {
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return toClassArray(cls) as T
+  } else {
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return toClassObject(cls) as T
+  }
+}
+
+/**
+ * 为类名集合中的每一项补上指定前缀。
+ *
+ * 已经带有该前缀的类名会保持不变。
+ *
+ * @example
+ * ```
+ * // Expect: 'pm-button pm-active'
+ * const example1 = prefixClassWith('pm-', 'button active')
+ *
+ * // Expect: ['pm-button', 'pm-active']
+ * const example2 = prefixClassWith('pm-', ['button', 'pm-active'])
+ *
+ * // Expect: { 'pm-button': true, 'pm-active': true }
+ * const example3 = prefixClassWith('pm-', { button: true, 'pm-active': true })
+ * ```
+ */
+export const prefixClassWith = <T extends ClassUnion>(prefix: string, cls: T): T => {
+  if (typeof cls === 'string') {
+    const classArray = classStringToClassArray(cls).map(item =>
+      item.startsWith(prefix) ? item : `${prefix}${item}`
+    )
+    const classString = classArrayToClassString(classArray)
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return classString as T
+  } else if (Array.isArray(cls)) {
+    const classArray = cls.filter(item => item.length !== 0).map(item =>
+      item.startsWith(prefix) ? item : `${prefix}${item}`
+    )
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return classArray as T
+  } else {
+    const classObject: ClassObject = {}
+    Object.entries(cls).forEach(([key, value]) => {
+      if (key.length === 0) {
+        return
+      }
+      const _key = key.startsWith(prefix) ? key : `${prefix}${key}`
+      classObject[_key] = value === true
+    })
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return classObject as T
+  }
+}
+
+/**
+ * 从类名集合中的每一项移除指定前缀。
+ *
+ * 不带该前缀的类名会保持原样。
+ *
+ * @example
+ * ```
+ * // Expect: 'button active plain'
+ * const example1 = removePrefixOfClass('pm-', 'pm-button pm-active plain')
+ *
+ * // Expect: ['button', 'plain']
+ * const example2 = removePrefixOfClass('pm-', ['pm-button', 'plain'])
+ *
+ * // Expect: { button: true, plain: false }
+ * const example3 = removePrefixOfClass('pm-', { 'pm-button': true, plain: false, 'pm-': true })
+ * ```
+ */
+export const removePrefixOfClass = <T extends ClassUnion>(prefix: string, cls: T): T => {
+  if (typeof cls === 'string') {
+    const classArray = classStringToClassArray(cls).map(item => {
+      if (item.startsWith(prefix)) {
+        return item.slice(prefix.length)
+      }
+      return item
+    })
+    const classString = classArrayToClassString(classArray)
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return classString as T
+  } else if (Array.isArray(cls)) {
+    const classArray = cls.filter(item => item.length !== 0).map(item => {
+      if (item.startsWith(prefix)) {
+        return item.slice(prefix.length)
+      }
+      return item
+    })
+    const filteredClassArray = classArray.filter(item => item.length !== 0)
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return filteredClassArray as T
+  } else {
+    const classObject: ClassObject = {}
+    Object.entries(cls).forEach(([key, value]) => {
+      if (key.length === 0) {
+        return
+      }
+      const _key = key.startsWith(prefix) ? key.slice(prefix.length) : key
+      if (_key.length !== 0) {
+        classObject[_key] = value === true
+      }
+    })
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    return classObject as T
+  }
+}
+
+/**
+ * 向目标类名集合中加入新的类名。
+ *
+ * 当目标与新增项都包含同名类时，以新增项转换后的对象表示为准。
+ *
+ * @example
+ * ```
+ * // Expect: 'button active primary'
+ * const example1 = addClass('button', 'active primary')
+ *
+ * // Expect: ['button', 'active', 'primary']
+ * const example2 = addClass(['button'], { active: true, primary: true })
+ * ```
+ */
+export const addClass = <T extends ClassUnion>(target: T, added: ClassUnion): T => {
+  const targetClassObj = toClassObject(target)
+  const addedClassObj = toClassObject(added)
+  const resClassObj = { ...targetClassObj, ...addedClassObj }
+  const result = formatClassToTarget(target, resClassObj)
+  return result
+}
+
+/**
+ * 从目标类名集合中移除指定类名。
+ *
+ * 该函数会把待移除项标记为 `false`，再按目标形态输出结果。
+ *
+ * @example
+ * ```
+ * // Expect: 'button primary'
+ * const example1 = removeClass('button active primary', 'active')
+ *
+ * // Expect: { button: true, active: false }
+ * const example2 = removeClass({ button: true, active: true }, ['active'])
+ * ```
+ */
+export const removeClass = <T extends ClassUnion>(target: T, removed: ClassUnion): T => {
+  const targetClassObj = toClassObject(target)
+  const removedClassObj = toClassObject(removed)
+  Object.keys(removedClassObj).forEach(key => {
+    removedClassObj[key] = false
+  })
+  const resClassObj = { ...targetClassObj, ...removedClassObj }
+  const result = formatClassToTarget(target, resClassObj)
+  return result
+}
+
+/**
+ * 切换目标类名集合中指定类名的启用状态。
+ *
+ * 已存在的类名会被关闭，不存在的类名会被开启。
+ *
+ * @example
+ * ```
+ * // Expect: 'button primary'
+ * const example1 = toggleClass('button active', 'active primary')
+ *
+ * // Expect: { button: true, primary: true }
+ * const example2 = toggleClass({ button: true, active: true }, ['active', 'primary'])
+ * ```
+ */
+export const toggleClass = <T extends ClassUnion>(target: T, toggled: ClassUnion): T => {
+  const targetClassObj = toClassObject(target)
+  const toggledClassArr = toClassArray(toggled)
+  toggledClassArr.forEach((cls) => {
+    // oxlint-disable-next-line strict-boolean-expressions
+    targetClassObj[cls] = !targetClassObj[cls]
+  })
+  const result = formatClassToTarget(target, targetClassObj)
+  return result
+}
+
+/**
+ * 替换目标类名集合中的类名。
+ *
+ * `replaced` 支持三种形式：
+ * - 字符串：仅移除对应类名。
+ * - 字符串数组：逐项移除对应类名。
+ * - 元组数组：按 `[from, to]` 的形式逐项替换类名。
+ * - 对象：按键值对执行替换，值为空字符串时表示删除。
+ *
+ * @example
+ * ```
+ * // Expect: 'button selected'
+ * const example1 = replaceClass('button active', [['active', 'selected']])
+ *
+ * // Expect: ['button', 'selected']
+ * const example2 = replaceClass(['button', 'active'], { active: 'selected' })
+ *
+ * // Expect: { button: true, active: false }
+ * const example3 = replaceClass({ button: true, active: true }, 'active')
+ * ```
+ */
+export const replaceClass = <T extends ClassUnion>(
+  target: T,
+  replaced: Record<string, string> | string | string[] | Array<[string, string]>,
+): T => {
+  if (typeof replaced === 'string') {
+    return removeClass(target, replaced)
+  }
+
+  const targetClassObj = toClassObject(target)
+
+  if (Array.isArray(replaced)) {
+    for (const item of replaced) {
+      if (typeof item === 'string') {
+        const fromValue = targetClassObj[item]
+
+        if (fromValue !== undefined) {
+          // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+          delete targetClassObj[item]
+        }
+
+        continue
+      }
+
+      const [from, to] = item
+      const fromValue = targetClassObj[from]
+
+      if (fromValue !== undefined) {
+        if (to !== '') {
+          targetClassObj[to] = fromValue
+        }
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        delete targetClassObj[from]
+      }
+    }
+
+    return formatClassToTarget(target, targetClassObj)
+  }
+
+  for (const [from, rawTo] of Object.entries(replaced)) {
+    if (typeof rawTo !== 'string') {
+      continue
+    }
+
+    const fromValue = targetClassObj[from]
+
+    if (fromValue !== undefined) {
+      if (rawTo !== '') {
+        targetClassObj[rawTo] = fromValue
+      }
+      // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+      delete targetClassObj[from]
+    }
+  }
+
+  return formatClassToTarget(target, targetClassObj)
+}
+
+/**
+ * 判断目标类名集合是否完整包含另一组类名。
+ *
+ * 只有当 `contained` 中的每个类名都存在于 `target` 中时，才会返回 `true`。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = containClass('button active', 'button active primary')
+ *
+ * // Expect: false
+ * const example2 = containClass(['button', 'missing'], { button: true, active: true })
+ * ```
+ */
+export const containClass = (contained: ClassUnion, target: ClassUnion): boolean => {
+  const containedClassArr = toClassArray(contained)
+  const targetClassArr = toClassArray(target)
+  return containedClassArr.every(item => targetClassArr.includes(item))
+}

package/src/css/index.ts

@@ -0,0 +1 @@
+export * from "./class.ts"

package/src/encoding/README.md

@@ -0,0 +1,92 @@
+# Encoding
+
+## Description
+
+Encoding 模块提供面向文本编码与解码（encoding and decoding）的基础能力，当前重点覆盖 UTF-8 字符串与 Base64 字符串之间的稳定转换、合法性判断与断言语义。
+
+它关注的是“表示如何被明确切换”，而不是更高层的协议字段含义、消息封装规则或业务语义解释。
+
+## For Understanding
+
+理解 Encoding 模块时，应把它看作 I/O 边界上的表示层模型。它要解决的问题不是“某段数据在业务上代表什么”，而是“某段文本当前以什么编码形式存在，以及如何在不同表示之间明确切换”。
+
+当前模块边界相对克制：
+
+- 它主要处理 UTF-8 文本与 Base64 字符串之间的转换。
+- 它明确区分“判断输入是否合法”“对非法输入抛错”“执行表示切换”这几类语义。
+- 它允许在不同运行时使用不同底层实现，例如 `Buffer`、`btoa`、`atob`，但这些实现差异不应泄漏成公共语义差异。
+
+这意味着 Encoding 不应承载压缩、加密、哈希、二进制协议、业务报文结构或传输层容错逻辑。那些能力可能会用到编码，但并不属于编码语义本身。
+
+## For Using
+
+当应用需要在纯文本与适合传输、存储或嵌入的编码字符串之间做明确转换时，可以使用这个模块。它尤其适合放在请求边界、文件边界、剪贴板边界、消息边界等“表示切换”明确发生的地方。
+
+当前公共能力大致可以按以下几类理解：
+
+- 合法性判断：用于判断一个字符串是否为合法 Base64 表示。
+- 断言入口：用于在进入后续流程前显式拒绝非法 Base64 输入。
+- 编码转换：用于把 UTF-8 字符串转换为 Base64。
+- 解码转换：用于把合法 Base64 转回 UTF-8 字符串。
+
+如果你的问题已经涉及二进制块处理、协议帧解析、密码学、压缩格式或业务级 payload 建模，应在其它模块中继续分层，而不要把这些问题直接叠加到 Encoding 上。
+
+## For Contributing
+
+贡献 Encoding 模块时，应优先判断新增能力是否仍然表达“表示切换”这一稳定问题域，而不是借编码名义引入更高层的数据处理逻辑。这个模块应长期保持边界清楚、行为可预期，而不是不断膨胀成杂项数据工具箱。
+
+在扩展时，应优先遵守以下边界：
+
+- 只承载编码表示本身的判断、断言、编码与解码语义。
+- 不把协议字段解释、业务 payload 处理、压缩、加密或摘要计算直接写入模块公共能力。
+- 不让不同运行时的底层 API 差异泄漏成不一致的公共语义。
+- 对输入合法性的要求应明确，不要把模糊行为留给调用方自行猜测。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/encoding/internal.ts`；若当前没有必要，不必为了形式强行拆分。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+- 设计实现时，应优先保证输入表示、输出表示和异常语义都直接可理解，而不是追求某个特定运行时下的最短实现路径。
+
+### 导出策略要求
+
+- 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的编码语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
+
+### 测试要求
+
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
+- 模块的单元测试文件目录是 `./tests/unit/encoding`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/encoding/<sub-module-name>`。
+- 测试应重点覆盖合法 Base64 判断、非法输入断言、UTF-8 文本往返转换，以及不同运行时实现下仍应保持一致的公共语义。