Helper 工具库

一个用于平台检测、设备ID管理和时间操作的 TypeScript 工具库。

主要功能

• 平台检测 (Node.js、浏览器、Deno)
• 设备 ID 生成和管理
• 时间工具函数

使用指南

平台检测

用于检测当前代码运行的环境平台。

import { isDeno, isBrowser, isNode } from '@mgcloud/lib-utils';

// 检查当前平台
if (isNode) {
  // Node.js 环境下的代码
} else if (isBrowser) {
  // 浏览器环境下的代码
} else if (isDeno) {
  // Deno 环境下的代码
}

设备 ID 管理

设备 ID 系统用于生成和管理唯一的 10 位字符标识符，在浏览器环境中可以跨会话持久化存储。

import { deviceId, createDeviceId } from '@mgcloud/lib-utils';

// 使用默认设备 ID
console.log(deviceId); // 返回默认设备 ID

// 创建使用自定义存储键的设备 ID
const customDeviceId = createDeviceId('CUSTOM_STORAGE_KEY');
console.log(customDeviceId); // 返回使用自定义键存储的设备 ID

特性：

• 生成独特的 10 位字符 ID，使用自定义编码字典
• 在浏览器环境中使用 localStorage 持久化存储
• 支持通过不同的存储键创建多个独立的设备 ID
• 使用线程安全的单例模式实现
• 采用自定义编码字典提升可读性和唯一性

时间工具

提供异步延时功能。

import { sleep } from '@mgcloud/lib-utils';

async function example() {
  // 基础用法 - 延时 1 秒
  await sleep(1000);
  
  // 在 Node.js 环境下使用 unref 选项
  await sleep(1000, true); // 允许进程在只剩下这个操作时退出
}

API 文档

平台模块 (platform.ts)

• isDeno: boolean - 在 Deno 环境下为 true
• isBrowser: boolean - 在浏览器环境下为 true
• isNode: boolean - 在 Node.js 环境下为 true

设备 ID 模块 (device-id.ts)

• deviceId: string - 默认设备 ID 实例
• createDeviceId(key?: string): string - 创建新的设备 ID，可选择自定义存储键
• DEFAULT_DEVICEID_KEY: string - 默认存储键名 ('__MG_DEVICE_ID')
• DeviceIdManager - 设备 ID 管理器类（内部使用）
  • 使用单例模式确保每个存储键只有一个实例
  • 提供设备 ID 的生成、存储和获取功能

时间工具模块 (time-utils.ts)

• sleep(ms: number, isUnref: boolean = false): Promise<void>
  • ms: 需要延时的毫秒数
  • isUnref: 在 Node.js 环境下，如果为 true，允许进程在只剩这个操作时退出

不同平台的特定行为

浏览器环境

• 设备 ID 通过 localStorage 持久化存储
• sleep 函数使用标准的 setTimeout

Node.js 环境

• 设备 ID 仅在当前会话中有效（无持久化）
• sleep 函数支持 unref 选项
• 设备 ID 操作会输出到控制台日志

Deno 环境

• 支持基础功能
• 设备 ID 仅在当前会话中有效
• 使用标准的 setTimeout 行为

技术细节

设备 ID 生成机制

1. 使用自定义字典进行字符编码，提供更好的可读性
2. 生成固定长度为 10 位的字符串 ID
3. 使用单例模式确保线程安全
4. 支持通过不同的存储键创建多个独立的 ID 管理实例

设备 ID 存储策略

• 浏览器环境：使用 localStorage 持久化存储
• Node.js 环境：仅在内存中保存，每次重启后重新生成
• Deno 环境：仅在内存中保存，每次重启后重新生成

使用建议

1. 平台检测

   • 在编写跨平台代码时，建议先进行平台检测
   • 根据不同平台特性选择合适的功能实现

2. 设备 ID

   • 默认设备 ID 适用于大多数场景
   • 需要多个独立 ID 时，使用 createDeviceId 并指定不同的存储键
   • 注意在非浏览器环境下 ID 不会持久化存储

3. 时间工具

   • 在需要异步延时的场景使用 sleep 函数
   • 在 Node.js 环境下，如果是后台任务建议使用 unref 选项

导出方法

import {
  isDeno,
  isBrowser,
  isNode,
  sleep,
  deviceId,
  createDeviceId,
  DEVICEID_KEY,
  DEFAULT_DEVICEID_KEY,
} from '@mgcloud/lib-utils'

Source

Source