@yuants/utils

@yuants/utils 是 Yuan 体系内的通用工具库，聚焦于异步迭代、加密、时间/数值处理以及 RxJS 辅助算子等基础能力，供上层协议、行情与交易程序共享使用。

快速上手

import { UUID, formatTime, roundToStep, observableToAsyncIterable } from '@yuants/utils';
import { interval, take } from 'rxjs';

console.log('ID:', UUID());
console.log('现在时间:', formatTime(Date.now()));
console.log('四舍五入到 0.01:', roundToStep(1.237, 0.01));

for await (const value of observableToAsyncIterable(interval(1000).pipe(take(3)))) {
  console.log('来自 RxJS 的异步数据:', value);
}

功能模块

• 异步迭代互操作
  • observableToAsyncIterable(source)：将 RxJS Observable 转换为原生 AsyncIterable，便于 for await 模式消费。
  • subjectToNativeSubject(subject$)：把 RxJS Subject 包装成同时实现 AsyncIterable/AsyncIterator 的对象。
  • nativeSubjectToSubject(source)：从实现异步迭代协议的对象还原出 RxJS Subject，方便回到 RxJS 管道。
• 加密与编码工具
  • createKeyPair()：生成新的 ED25519 密钥对并以 Base58 编码返回。
  • fromSeed(seed)：根据 32 字节种子派生稳定的 ED25519 密钥对。
  • fromPrivateKey(privateKey)：从 Base58 编码的私钥恢复出密钥对并校验公钥一致性。
  • signMessage(message, privateKey)：使用 ED25519 私钥对消息进行签名。
  • encryptByPublicKey(data, publicKey)：使用对方的 ED25519 公钥完成一次性盒式加密。
  • decryptByPrivateKey(data, privateKey)：使用本地私钥解密由 encryptByPublicKey 生成的数据。
  • verifyMessage(message, signature, publicKey)：校验签名与消息是否匹配。
  • generateX25519KeyPair()：生成用于密钥交换的 X25519 密钥对。
  • deriveSharedKey(publicKey, privateKey)：基于双方密钥计算共享密钥（Base58）。
  • encodeBase58(data) / decodeBase58(data)：提供 Base58 编码与解码的便捷封装。
  • encrypt(data, base58_key) / decrypt(data, base58_key)：使用 AES-GCM 与 Base58 密钥对二进制数据进行对称加解密。
  • sha256(data)：计算输入数据的 SHA-256 摘要。
• 时间与数值处理
  • formatTime(time, timeZone?)：按 yyyy-MM-dd HH:mm:ss.SSSXXX 模板输出时间，并支持指定时区。
  • convertDurationToOffset(duration)：解析 RFC3339 Duration 字符串并返回毫秒偏移量。
  • roundToStep(value, step, roundFn?)：将数值化整到步长的整数倍，保持与步长一致的小数精度。
• 路径与字符串辅助
  • encodePath(...params)：将参数拼接为支持转义 / 的路径片段。
  • decodePath(path)：反向解析带转义的路径字符串为参数数组。
  • escapeRegExp(string)：转义正则表达式中的特殊字符。
• RxJS 扩展算子
  • batchGroupBy(keyFunc)：按 key 对批量数据流进行分组并自动管理组的生命周期。
  • switchMapWithComplete(fn)：行为类似 switchMap，在源流完成时会取消最后一个订阅。
  • rateLimitMap(fn, reject, rateLimitConfig?, scheduler?)：实现令牌桶速率限制，可自定义超限处理逻辑。
  • listWatch(keyFunc, consumer, comparator?)：监听列表增删改并为每个元素绑定生命周期 Observable。
  • listWatchEvent(keyFunc?, comparator?)：将列表变化转换为 [old, new] 事件序列。
• 其他工具
  • UUID()：基于 Web Crypto 提供的 crypto.randomUUID 生成随机字符串。

与其他子包的关系

• @yuants/protocol、@yuants/sql 等核心库依赖此包提供的基础能力，是整个 Yuan 体系的重要底座。
• 建议在编写新的子项目时优先复用这里的工具函数，保持行为一致并降低重复实现成本。

如需查看更详细的 API 注释，可参阅源码或构建产出的类型声明文件。