NestJS Boot

外观

工具函数 ​

@maxtan/nest-core 提供了一组开箱即用的工具函数。

AES 加密 / 解密 ​

基于 AES-256-GCM 的安全加密，使用 scryptSync 派生密钥。

typescript
import { encryptAES, decryptAES } from '@maxtan/nest-core'

const key = 'my-secret-key'

// 加密
const encrypted = encryptAES('hello world', key)
// => Base64 编码的密文

// 解密
const decrypted = decryptAES(encrypted, key)
// => 'hello world'

⚠️ v2.0 使用 scryptSync 派生密钥，与 v1.12.x 及之前版本不兼容。旧密文需要重新加密。

雪花 ID ​

分布式唯一 ID 生成器，基于 Twitter Snowflake 算法。

typescript
import { generateSnowflakeId, createSnowflake } from '@maxtan/nest-core'

// 默认实例
const id = generateSnowflakeId()
// => '7234567890123456789'

// 自定义实例
const snowflake = createSnowflake({
  machineId: 1,                    // 机器 ID (0-1023)
  epoch: '2025-01-01',            // 起始时间
  randomness: 'medium'            // 序列号随机性级别
})

const customId = snowflake.generateSnowflakeId()

// 解码 ID
const decoded = snowflake.decodeId(customId)
// => { timestamp, date, machineId, sequence }

machineId 分配策略 ​

优先级方式说明
1machineId 选项显式配置（推荐）
2环境变量 SNOWFLAKE_MACHINE_ID运维配置
3MAC + PID 自动生成有小概率碰撞

随机性级别 ​

级别步进范围说明
none1完全连续
low2-16轻微随机
medium16-128中等随机
high64-512高随机性（防撞库）

随机 ID 生成 ​

typescript
import { N6, G4, Guid, generateGuid } from '@maxtan/nest-core'

N6()             // 6 位随机数字，如 '832471'
G4()             // 4 位十六进制，如 'a3f1'
Guid()           // UUID v4，如 '550e8400-e29b-41d4-a716-446655440000'
generateGuid(16) // 指定长度的十六进制字符串（长度须为 4 的倍数）

日期格式化 ​

typescript
import { formatDate } from '@maxtan/nest-core'

formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
// => '2025-06-15 14:30:00'

formatDate(new Date(), 'YYYY/MM/DD')
// => '2025/06/15'

formatDate(new Date(), 'HH:mm')
// => '14:30'

支持的格式符：

符号说明示例
YYYY四位年份2025
MM月份（补零）01-12
DD日期（补零）01-31
HH小时（补零）00-23
mm分钟（补零）00-59
ss秒（补零）00-59
S毫秒0-999
q季度1-4

空值检查 ​

typescript
import { isEmpty, isNotEmpty } from '@maxtan/nest-core'

isEmpty(null)       // true
isEmpty(undefined)  // true
isEmpty('')         // true
isEmpty('  ')       // true — 纯空白也视为空
isEmpty([])         // true
isEmpty({})         // true
isEmpty(0)          // false — 数字不视为空
isEmpty(false)      // false — 布尔不视为空

isNotEmpty('hello') // true
isNotEmpty([1, 2])  // true

对象清理 ​

递归移除对象中的无效值（null、undefined、空字符串等）。

typescript
import { cleanObject, CleanObjectPresets } from '@maxtan/nest-core'

// 默认：只移除 null 和 undefined
cleanObject({ name: 'John', age: null, email: '' })
// => { name: 'John', email: '' }

// 完整预设：移除所有无效值
cleanObject({ name: 'John', email: '', type: 'null' }, CleanObjectPresets.full)
// => { name: 'John' }

// 支持嵌套对象
cleanObject({ user: { id: 1, type: null } })
// => { user: { id: 1 } }

边界说明：

  • cleanObject 的职责是移除对象中的无效值，不负责把所有字符串统一 trim() 后再回写
  • 它不会把 ' abc ' 变成 'abc'，也不会把数组中的普通字符串元素逐项归一化
  • 如果需要字段级字符串语义，请优先使用 zStr、zStrNull、zVarCharNull、zStrArr
  • 如果业务确实需要深度 JSON 字符串归一化，建议在业务仓库按场景实现专用 helper，而不是默认放进 core

CleanObjectPresets ​

预设过滤项
defaultnull、undefined
fullnull、undefined、空字符串、'null'、'undefined'

自定义选项 ​

typescript
cleanObject(obj, {
  filterNull: true,            // 过滤 null（默认 true）
  filterUndefined: true,       // 过滤 undefined（默认 true）
  filterEmptyString: false,    // 过滤空字符串（默认 false）
  filterNullString: false,     // 过滤 'null' 字符串（默认 false）
  filterUndefinedString: false // 过滤 'undefined' 字符串（默认 false）
})

LRU 缓存 ​

带 TTL 过期检查的 LRU（最近最少使用）内存缓存。

typescript
import { LRUCache } from '@maxtan/nest-core'

// 最多 1000 项，TTL 5 分钟
const cache = new LRUCache<string, any>(1000, 5 * 60 * 1000)

cache.set('key1', { data: 'value1' })

const value = cache.get('key1') // 会更新访问顺序

cache.has('key1')   // 检查是否存在（不更新顺序）
cache.delete('key1')
cache.size          // 当前缓存大小
cache.clear()       // 清空

特性：

  • 容量满时自动淘汰最久未使用的项
  • 惰性过期检查（仅在 get / has 时检查 TTL）
  • 基于 Map 插入顺序实现

相关文档 ​