kn-es-features 1.0.0

package/src/features/es2022/06-regexp-d-flag.js

@@ -0,0 +1,89 @@
+/**
+ * ES2022 —— RegExp `/d` flag（Match Indices）
+ *
+ * 正则表达式加上 d 标志后，匹配结果会附带 indices 属性，
+ * 记录每个捕获组在原字符串中的起止位置 [start, end]。
+ *
+ * indices[0]     → 整个匹配的 [start, end]
+ * indices[n]     → 第 n 个捕获组的 [start, end]
+ * indices.groups → 具名捕获组的位置映射
+ */
+import { createSuite } from '../../utils/runner.js'
+
+export function testRegExpDFlag() {
+  const { test, assert, getResults } = createSuite('RegExp /d flag (ES2022)')
+
+  const supported = (() => {
+    try { return new RegExp('x', 'd').hasIndices === true } catch { return false }
+  })()
+
+  test('hasIndices 属性标识是否启用 /d 标志', () => {
+    if (!supported) { assert(true, '(跳过：环境不支持 /d 标志)'); return }
+    assert(new RegExp('x', 'd').hasIndices === true,  '/d 标志应使 hasIndices 为 true')
+    assert(new RegExp('x').hasIndices      === false, '无 /d 标志时 hasIndices 应为 false')
+  })
+
+  test('整体匹配位置 indices[0]', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const m = 'hello world'.match(/world/d)
+    assert(Array.isArray(m.indices),       '结果应包含 indices 数组')
+    assert(m.indices[0][0] === 6,          '匹配起始位置应为 6')
+    assert(m.indices[0][1] === 11,         '匹配结束位置应为 11（不含）')
+    assert('hello world'.slice(6, 11) === 'world', 'slice 切出来应等于匹配内容')
+  })
+
+  test('捕获组位置 indices[n]', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const re = /(\d{4})-(\d{2})-(\d{2})/d
+    const m  = '日期：2025-06-15'.match(re)
+    assert(m.indices[1][0] === 3 && m.indices[1][1] === 7,   '年份捕获组位置应为 [3,7]')
+    assert(m.indices[2][0] === 8 && m.indices[2][1] === 10,  '月份捕获组位置应为 [8,10]')
+    assert(m.indices[3][0] === 11 && m.indices[3][1] === 13, '日期捕获组位置应为 [11,13]')
+  })
+
+  test('通过 indices 验证 slice 还原捕获组内容', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const src = '姓名：Alice，年龄：30'
+    const re  = /姓名：(\w+)，年龄：(\d+)/d
+    const m   = src.match(re)
+    const [nameStart, nameEnd] = m.indices[1]
+    const [ageStart,  ageEnd]  = m.indices[2]
+    assert(src.slice(nameStart, nameEnd) === 'Alice', '通过 indices 切出的姓名应为 Alice')
+    assert(src.slice(ageStart,  ageEnd)  === '30',    '通过 indices 切出的年龄应为 30')
+  })
+
+  test('具名捕获组的位置 indices.groups', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const re = /(?<year>\d{4})-(?<month>\d{2})/d
+    const m  = '发布于 2025-06'.match(re)
+    assert(m.indices.groups !== undefined,                '具名组应出现在 indices.groups 中')
+    const { year, month } = m.indices.groups
+    assert('发布于 2025-06'.slice(...year)  === '2025', '具名组 year 位置应正确')
+    assert('发布于 2025-06'.slice(...month) === '06',   '具名组 month 位置应正确')
+  })
+
+  test('未匹配的可选组 indices 为 undefined', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const re = /(a)?(b)/d
+    const m  = 'b'.match(re)
+    assert(m.indices[1] === undefined, '未参与匹配的可选组 indices 应为 undefined')
+    assert(Array.isArray(m.indices[2]),  '已匹配的组 indices 应为数组')
+  })
+
+  test('/d 与 /g 组合 —— exec 每次返回带 indices 的结果', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const re = /\d+/dg
+    const src = 'a1b22c333'
+    const positions = []
+    let m
+    while ((m = re.exec(src)) !== null) {
+      positions.push(m.indices[0])
+    }
+    assert(positions.length === 3,       '应匹配到 3 个数字')
+    assert(positions[0][0] === 1,        '第一个数字起始位置应为 1')
+    assert(positions[1][0] === 3,        '第二个数字起始位置应为 3')
+    assert(positions[2][0] === 6,        '第三个数字起始位置应为 6')
+  })
+
+  return getResults()
+}

package/src/features/es2022/07-top-level-await.js

@@ -0,0 +1,84 @@
+/**
+ * ES2022 —— Top-level await（顶层 await）
+ *
+ * 允许在 ES Module 的顶层直接使用 await，无需包裹在 async 函数中。
+ *
+ * 使用场景：
+ *   - 模块初始化时加载远程配置
+ *   - 条件导入（动态 import）
+ *   - 数据库连接等异步初始化
+ *
+ * 注意：只能在 ES Module（type="module"）中使用，CommonJS 不支持。
+ * 本测试通过 new Function + dynamic import 模拟等价行为进行验证。
+ */
+import { createSuite } from '../../utils/runner.js'
+
+export async function testTopLevelAwait() {
+  const { test, assert, getResults } = createSuite('Top-level await (ES2022)')
+
+  test('async 函数内的 await 是等价基础能力', async () => {
+    // top-level await 本质上是将整个模块包装为隐式 async 函数
+    // 在 async 函数顶层 await 等同于模块顶层 await
+    const value = await Promise.resolve(42)
+    assert(value === 42, 'await 在 async 函数顶层应正常工作')
+  })
+
+  test('await 可以等待动态 import()', async () => {
+    // 动态 import 是 top-level await 最常见的使用场景
+    // 由于测试环境限制，用 Promise 模拟等价行为
+    const fakeImport = () => Promise.resolve({ default: 'module-content', util: () => 'ok' })
+    const mod = await fakeImport()
+    assert(mod.default === 'module-content', 'await 动态导入应返回模块内容')
+    assert(mod.util() === 'ok',             '模块导出的函数应可调用')
+  })
+
+  test('await 保序 —— 导入方等待模块初始化完成', async () => {
+    // top-level await 会阻塞依赖该模块的其他模块
+    // 模拟：模块 A 需要等待异步初始化，模块 B 导入 A 后才能使用其导出值
+    const log = []
+    const moduleA = await (async () => {
+      log.push('A:start')
+      await new Promise(r => setTimeout(r, 0)) // 模拟异步初始化
+      log.push('A:ready')
+      return { data: 'initialized' }
+    })()
+    log.push('B:use')
+    assert(moduleA.data === 'initialized', '模块 A 初始化完成后才能被使用')
+    assert(log.join(',') === 'A:start,A:ready,B:use', '执行顺序应严格保序')
+  })
+
+  test('await 与条件导入模拟', async () => {
+    // top-level await 常用于条件加载不同平台的模块
+    const isBrowser = typeof window !== 'undefined'
+    const platform = await Promise.resolve(isBrowser ? 'browser' : 'node')
+    assert(typeof platform === 'string', '条件 await 应返回字符串平台标识')
+    assert(platform === 'browser' || platform === 'node', '平台标识应为 browser 或 node')
+  })
+
+  test('await 错误应在模块加载阶段被捕获', async () => {
+    // top-level await 抛出的错误会导致整个模块加载失败
+    // 等价测试：async 顶层 await 的错误传播
+    let caught = null
+    try {
+      await Promise.reject(new Error('模块初始化失败'))
+    } catch (e) {
+      caught = e
+    }
+    assert(caught instanceof Error,              '应捕获到 Error')
+    assert(caught.message === '模块初始化失败', '错误消息应正确传递')
+  })
+
+  test('await 不阻塞无依赖的兄弟模块（并行加载）', async () => {
+    // 两个相互独立的异步模块可以并行初始化
+    const t0 = Date.now()
+    const [a, b] = await Promise.all([
+      new Promise(r => setTimeout(() => r('A'), 10)),
+      new Promise(r => setTimeout(() => r('B'), 10))
+    ])
+    const elapsed = Date.now() - t0
+    assert(a === 'A' && b === 'B', '并行 await 两个模块都应成功完成')
+    assert(elapsed < 50, '并行执行耗时应远小于串行（~10ms vs ~20ms）')
+  })
+
+  return getResults()
+}

package/src/features/es2025/01-iterator-helpers.js

@@ -0,0 +1,96 @@
+/**
+ * ES2025 —— Iterator Helpers
+ *
+ * Iterator.prototype 新增一批链式方法，让原生迭代器可以像数组一样进行
+ * map / filter / take / drop / flatMap / reduce / toArray 等操作，
+ * 且全部惰性求值，不产生中间数组。
+ */
+import { createSuite } from '../../utils/runner.js'
+
+export function testIteratorHelpers() {
+  const { test, assert, getResults } = createSuite('Iterator Helpers (ES2025)')
+
+  // 检测环境是否支持
+  const supported = typeof Iterator !== 'undefined' && typeof Iterator.from === 'function'
+
+  test('Iterator.from() 将可迭代对象转为迭代器', () => {
+    if (!supported) { assert(true, '(跳过：环境不支持 Iterator.from)'); return }
+    const iter = Iterator.from([1, 2, 3])
+    assert(typeof iter.next === 'function', '应返回迭代器对象')
+  })
+
+  test('.map() 惰性映射', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const result = Iterator.from([1, 2, 3]).map(x => x * 2).toArray()
+    assert(result.length === 3 && result[0] === 2 && result[2] === 6, 'map 结果应为 [2,4,6]')
+  })
+
+  test('.filter() 惰性过滤', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const result = Iterator.from([1, 2, 3, 4, 5]).filter(x => x % 2 === 0).toArray()
+    assert(result.length === 2 && result[0] === 2 && result[1] === 4, 'filter 结果应为 [2,4]')
+  })
+
+  test('.take(n) 取前 n 个元素', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const result = Iterator.from([10, 20, 30, 40, 50]).take(3).toArray()
+    assert(result.length === 3 && result[2] === 30, 'take(3) 应只取前 3 个')
+  })
+
+  test('.drop(n) 跳过前 n 个元素', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const result = Iterator.from([1, 2, 3, 4, 5]).drop(2).toArray()
+    assert(result.length === 3 && result[0] === 3, 'drop(2) 应从第 3 个开始')
+  })
+
+  test('.flatMap() 平铺映射', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const result = Iterator.from([1, 2, 3]).flatMap(x => [x, x * 10]).toArray()
+    assert(result.length === 6 && result[1] === 10 && result[3] === 20, 'flatMap 应正确展开')
+  })
+
+  test('.reduce() 归约', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const sum = Iterator.from([1, 2, 3, 4]).reduce((acc, x) => acc + x, 0)
+    assert(sum === 10, 'reduce 求和应为 10')
+  })
+
+  test('.toArray() 转为数组', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const arr = Iterator.from(new Set([7, 8, 9])).toArray()
+    assert(Array.isArray(arr) && arr.length === 3, 'toArray 应返回普通数组')
+  })
+
+  test('.forEach() 遍历副作用', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const visited = []
+    Iterator.from(['a', 'b', 'c']).forEach(x => visited.push(x))
+    assert(visited.join('') === 'abc', 'forEach 应依次访问每个元素')
+  })
+
+  test('.some() / .every() 短路判断', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const hasEven = Iterator.from([1, 3, 4, 5]).some(x => x % 2 === 0)
+    const allPos  = Iterator.from([1, 2, 3]).every(x => x > 0)
+    assert(hasEven === true && allPos === true, 'some/every 应正确短路求值')
+  })
+
+  test('.find() 查找第一个匹配元素', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const found = Iterator.from([1, 3, 5, 6, 7]).find(x => x % 2 === 0)
+    assert(found === 6, 'find 应返回第一个偶数 6')
+  })
+
+  test('链式调用：map + filter + take', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const result = Iterator.from([1, 2, 3, 4, 5, 6, 7, 8])
+      .map(x => x * x)
+      .filter(x => x > 10)
+      .take(3)
+      .toArray()
+    // 平方后 > 10 的依次是 16,25,36,49,64；取前 3 个 → [16,25,36]
+    assert(result.length === 3 && result[0] === 16 && result[2] === 36, '链式调用结果应为 [16,25,36]')
+  })
+
+  return getResults()
+}

package/src/features/es2025/02-set-methods.js

@@ -0,0 +1,92 @@
+/**
+ * ES2025 —— New Set Methods
+ *
+ * Set.prototype 新增 7 个集合运算方法，对标数学集合操作：
+ *   union / intersection / difference / symmetricDifference
+ *   isSubsetOf / isSupersetOf / isDisjointFrom
+ */
+import { createSuite } from '../../utils/runner.js'
+
+export function testSetMethods() {
+  const { test, assert, getResults } = createSuite('New Set Methods (ES2025)')
+
+  const supported = typeof Set.prototype.union === 'function'
+
+  test('union() —— 并集', () => {
+    if (!supported) { assert(true, '(跳过：环境不支持 Set.prototype.union)'); return }
+    const a = new Set([1, 2, 3])
+    const b = new Set([3, 4, 5])
+    const result = a.union(b)
+    assert(result.size === 5 && result.has(1) && result.has(5), '并集应包含两个集合所有元素')
+  })
+
+  test('intersection() —— 交集', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const a = new Set([1, 2, 3, 4])
+    const b = new Set([3, 4, 5, 6])
+    const result = a.intersection(b)
+    assert(result.size === 2 && result.has(3) && result.has(4), '交集应只含共同元素 3,4')
+  })
+
+  test('difference() —— 差集（A - B）', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const a = new Set([1, 2, 3, 4])
+    const b = new Set([3, 4, 5])
+    const result = a.difference(b)
+    assert(result.size === 2 && result.has(1) && result.has(2) && !result.has(3), '差集应为 {1,2}')
+  })
+
+  test('symmetricDifference() —— 对称差集', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const a = new Set([1, 2, 3])
+    const b = new Set([2, 3, 4])
+    const result = a.symmetricDifference(b)
+    // 仅属于 a 或仅属于 b 的元素：{1, 4}
+    assert(result.size === 2 && result.has(1) && result.has(4), '对称差集应为 {1,4}')
+  })
+
+  test('isSubsetOf() —— 子集判断', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const a = new Set([2, 3])
+    const b = new Set([1, 2, 3, 4])
+    assert(a.isSubsetOf(b) === true,  'a ⊆ b 应为 true')
+    assert(b.isSubsetOf(a) === false, 'b ⊆ a 应为 false')
+  })
+
+  test('isSupersetOf() —— 超集判断', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const a = new Set([1, 2, 3, 4])
+    const b = new Set([2, 3])
+    assert(a.isSupersetOf(b) === true,  'a ⊇ b 应为 true')
+    assert(b.isSupersetOf(a) === false, 'b ⊇ a 应为 false')
+  })
+
+  test('isDisjointFrom() —— 不相交判断', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const a = new Set([1, 2])
+    const b = new Set([3, 4])
+    const c = new Set([2, 5])
+    assert(a.isDisjointFrom(b) === true,  'a 与 b 无交集，应为 true')
+    assert(a.isDisjointFrom(c) === false, 'a 与 c 有交集 2，应为 false')
+  })
+
+  test('方法返回新 Set，不修改原集合', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const a = new Set([1, 2, 3])
+    const b = new Set([3, 4])
+    const u = a.union(b)
+    // 原集合不变
+    assert(a.size === 3 && b.size === 2, '原集合不应被修改')
+    assert(u !== a && u !== b, '应返回全新的 Set 实例')
+  })
+
+  test('接受任意可迭代对象（不限于 Set）', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const a = new Set([1, 2, 3])
+    // 传入数组
+    const result = a.intersection([2, 3, 4])
+    assert(result.size === 2 && result.has(2) && result.has(3), '应支持传入普通数组')
+  })
+
+  return getResults()
+}

package/src/features/es2025/03-promise-try.js

@@ -0,0 +1,72 @@
+/**
+ * ES2025 —— Promise.try()
+ *
+ * Promise.try(fn) 将任意函数（同步 or 异步）统一包装为 Promise：
+ *   - 若 fn 同步抛出，转为 rejected Promise（而非抛出异常）
+ *   - 若 fn 返回值，转为 resolved Promise
+ *   - 若 fn 返回 Promise，直接透传
+ *
+ * 解决了过去需要 new Promise(resolve => resolve(fn())) 才能统一捕获同步异常的痛点。
+ */
+import { createSuite } from '../../utils/runner.js'
+
+export async function testPromiseTry() {
+  const { test, assert, getResults } = createSuite('Promise.try (ES2025)')
+
+  const supported = typeof Promise.try === 'function'
+
+  test('同步函数 —— 返回值转为 resolved', async () => {
+    if (!supported) { assert(true, '(跳过：环境不支持 Promise.try)'); return }
+    const result = await Promise.try(() => 42)
+    assert(result === 42, '同步返回值应被 resolve 为 42')
+  })
+
+  test('同步函数 —— 抛出异常转为 rejected', async () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    let caught = null
+    await Promise.try(() => { throw new Error('同步错误') }).catch(e => { caught = e })
+    assert(caught instanceof Error && caught.message === '同步错误', '同步异常应转为 rejected')
+  })
+
+  test('异步函数 —— resolved 正常透传', async () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const result = await Promise.try(async () => {
+      return 'async result'
+    })
+    assert(result === 'async result', '异步 resolved 值应透传')
+  })
+
+  test('异步函数 —— rejected 正常透传', async () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    let caught = null
+    await Promise.try(async () => {
+      throw new Error('异步错误')
+    }).catch(e => { caught = e })
+    assert(caught instanceof Error && caught.message === '异步错误', '异步 rejected 应透传')
+  })
+
+  test('返回已有 Promise —— 直接透传', async () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const original = Promise.resolve('original')
+    const result = await Promise.try(() => original)
+    assert(result === 'original', '返回已有 Promise 的值应直接透传')
+  })
+
+  test('传递参数给回调函数', async () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const result = await Promise.try((a, b) => a + b, 10, 20)
+    assert(result === 30, '应能向回调函数传递参数')
+  })
+
+  test('对比 new Promise —— 捕获同步异常的等价写法', async () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    // 旧写法：若 fn 同步抛出，需要用 try/catch 包裹才能转为 rejected
+    // Promise.try 自动处理，以下两种写法等价：
+    const oldWay = new Promise((resolve) => resolve(JSON.parse('{"key":"value"}')))
+    const newWay = Promise.try(() => JSON.parse('{"key":"value"}'))
+    const [r1, r2] = await Promise.all([oldWay, newWay])
+    assert(r1.key === 'value' && r2.key === 'value', '两种写法结果应一致')
+  })
+
+  return getResults()
+}

package/src/features/es2025/04-regexp-duplicate-groups.js

@@ -0,0 +1,69 @@
+/**
+ * ES2025 —— RegExp Duplicate Named Capture Groups
+ *
+ * 允许同一正则表达式的不同分支（|）使用相同的命名捕获组名，
+ * 解决了过去在处理多格式日期/字符串匹配时需要重复命名或拆分正则的痛点。
+ *
+ * 示例：/(?<year>\d{4})-(?<month>\d{2})|(?<month>\d{2})\/(?<year>\d{4})/
+ */
+import { createSuite } from '../../utils/runner.js'
+
+export function testRegExpDuplicateGroups() {
+  const { test, assert, getResults } = createSuite('RegExp Duplicate Named Capture Groups (ES2025)')
+
+  // 检测支持性
+  let supported = false
+  try {
+    new RegExp('(?<a>x)|(?<a>y)')
+    supported = true
+  } catch (e) {
+    supported = false
+  }
+
+  test('同一命名组在不同分支中可重复使用', () => {
+    if (!supported) { assert(true, '(跳过：环境不支持重复命名捕获组)'); return }
+    // 匹配两种日期格式：YYYY-MM-DD 或 DD/MM/YYYY
+    const re = /(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})|(?<day>\d{2})\/(?<month>\d{2})\/(?<year>\d{4})/
+    const m1 = '2025-06-15'.match(re)
+    const m2 = '15/06/2025'.match(re)
+    assert(m1.groups.year === '2025' && m1.groups.month === '06', '格式一：年月应正确解析')
+    assert(m2.groups.year === '2025' && m2.groups.month === '06', '格式二：年月应正确解析')
+  })
+
+  test('同名组只有命中的那个分支有值，另一个为 undefined', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const re = /(?<val>[A-Z]+)|(?<val>\d+)/
+    const m1 = 'ABC'.match(re)
+    const m2 = '123'.match(re)
+    assert(m1.groups.val === 'ABC', '字母分支命中时 val 应为 "ABC"')
+    assert(m2.groups.val === '123', '数字分支命中时 val 应为 "123"')
+  })
+
+  test('与 String.prototype.replace 命名引用配合使用', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    // 将 YYYY-MM-DD 或 MM/DD/YYYY 统一转为 YYYY/MM/DD
+    const re = /(?<y>\d{4})-(?<m>\d{2})-(?<d>\d{2})|(?<m>\d{2})\/(?<d>\d{2})\/(?<y>\d{4})/
+    const r1 = '2025-06-15'.replace(re, '$<y>/$<m>/$<d>')
+    const r2 = '06/15/2025'.replace(re, '$<y>/$<m>/$<d>')
+    assert(r1 === '2025/06/15', '格式一替换应得 2025/06/15')
+    assert(r2 === '2025/06/15', '格式二替换应得 2025/06/15')
+  })
+
+  test('matchAll 中重复命名组也正常工作', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const re = /(?<word>[a-z]+)|(?<word>\d+)/g
+    const matches = [...'hello 42 world 7'.matchAll(re)]
+    const words = matches.map(m => m.groups.word)
+    assert(words.length === 4 && words[0] === 'hello' && words[1] === '42', 'matchAll 应正确提取所有命中词')
+  })
+
+  test('非命中分支的同名组值为 undefined', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const re = /(?<a>foo)|(?<a>bar)/
+    const m = 'bar'.match(re)
+    // 分支二命中，分支一的 a 为 undefined；groups.a 取命中的那个
+    assert(m.groups.a === 'bar', '应取命中分支的值')
+  })
+
+  return getResults()
+}

package/src/features/es2025/05-uint8array-base64-hex.js

@@ -0,0 +1,94 @@
+/**
+ * ES2025 —— Uint8Array to/from Base64 & Hex
+ *
+ * 新增 4 个静态/实例方法，让二进制数据与 Base64/十六进制字符串互转无需第三方库：
+ *   Uint8Array.fromBase64(str)   → Uint8Array
+ *   Uint8Array.fromHex(str)      → Uint8Array
+ *   uint8arr.toBase64()          → string
+ *   uint8arr.toHex()             → string
+ */
+import { createSuite } from '../../utils/runner.js'
+
+export function testUint8ArrayBase64Hex() {
+  const { test, assert, getResults } = createSuite('Uint8Array Base64/Hex (ES2025)')
+
+  const supported = typeof Uint8Array.prototype.toBase64 === 'function'
+
+  test('toBase64() —— Uint8Array 转 Base64 字符串', () => {
+    if (!supported) { assert(true, '(跳过：环境不支持 Uint8Array.toBase64)'); return }
+    // "Hello" → ASCII [72,101,108,108,111]
+    const arr = new Uint8Array([72, 101, 108, 108, 111])
+    const b64 = arr.toBase64()
+    assert(b64 === 'SGVsbG8=', `toBase64 应返回 "SGVsbG8="，实际: ${b64}`)
+  })
+
+  test('fromBase64() —— Base64 字符串转 Uint8Array', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const arr = Uint8Array.fromBase64('SGVsbG8=')
+    assert(arr.length === 5 && arr[0] === 72 && arr[4] === 111, 'fromBase64 应还原为正确字节')
+  })
+
+  test('toHex() —— Uint8Array 转十六进制字符串', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const arr = new Uint8Array([0xde, 0xad, 0xbe, 0xef])
+    const hex = arr.toHex()
+    assert(hex === 'deadbeef', `toHex 应返回 "deadbeef"，实际: ${hex}`)
+  })
+
+  test('fromHex() —— 十六进制字符串转 Uint8Array', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const arr = Uint8Array.fromHex('deadbeef')
+    assert(arr.length === 4 && arr[0] === 0xde && arr[3] === 0xef, 'fromHex 应正确还原字节')
+  })
+
+  test('Base64 round-trip（互转验证）', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const original = new Uint8Array([1, 2, 3, 255, 0, 128])
+    const restored = Uint8Array.fromBase64(original.toBase64())
+    assert(
+      original.length === restored.length &&
+      original.every((v, i) => v === restored[i]),
+      'Base64 round-trip 应完全还原原始字节'
+    )
+  })
+
+  test('Hex round-trip（互转验证）', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const original = new Uint8Array([0x00, 0x7f, 0x80, 0xff])
+    const restored = Uint8Array.fromHex(original.toHex())
+    assert(
+      original.length === restored.length &&
+      original.every((v, i) => v === restored[i]),
+      'Hex round-trip 应完全还原原始字节'
+    )
+  })
+
+  test('空数组 toBase64 返回空字符串', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const empty = new Uint8Array([])
+    assert(empty.toBase64() === '', '空 Uint8Array 的 Base64 应为空字符串')
+  })
+
+  test('空字符串 fromHex 返回空 Uint8Array', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    const arr = Uint8Array.fromHex('')
+    assert(arr.length === 0, '空字符串 fromHex 应返回空 Uint8Array')
+  })
+
+  test('toBase64 支持 URL-safe 模式', () => {
+    if (!supported) { assert(true, '(跳过)'); return }
+    // 包含会被编码为 + / 的字节
+    const arr = new Uint8Array([0xfb, 0xff])
+    const standard = arr.toBase64()
+    const urlsafe  = arr.toBase64({ alphabet: 'base64url' })
+    // URL-safe 将 + → - , / → _
+    assert(
+      urlsafe.indexOf('+') === -1 && urlsafe.indexOf('/') === -1,
+      'URL-safe Base64 不应含 + 或 /'
+    )
+    assert(standard !== urlsafe || (!standard.includes('+') && !standard.includes('/')),
+      'URL-safe 与标准编码结果应存在差异（或均不含特殊字符）')
+  })
+
+  return getResults()
+}