sakura-utils

sakura-utils 是一个功能丰富的 JavaScript/TypeScript 工具库，提供了多种常用的工具函数，帮助开发者更高效地编写代码。

✨ 特性

• 📦 轻量级，零依赖（仅使用 decimal.js 处理数字精度）
• 🎯 类型安全，完整的 TypeScript 类型定义
• 📚 模块化设计，支持按需导入
• 🔧 丰富的工具函数，涵盖数组、日期、文件、数字、对象等多个领域
• 🚀 高性能，优化的实现方式

📦 安装

# 使用 npm
npm install sakura-utils

# 使用 yarn
yarn add sakura-utils

# 使用 pnpm
pnpm add sakura-utils

🚀 快速开始

基本使用

// 导入整个库
import * as sakuraUtils from 'sakura-utils'

// 生成随机 ID
const randomId = sakuraUtils.generateRandomId(16, 'user_')
console.log(randomId) // 输出: user_abc123def456ghi7

// 格式化日期
const date = sakuraUtils.createDate()
console.log(date.formatDate('YYYY-MM-DD HH:mm:ss')) // 输出: 2024-01-01 12:00:00

按需导入

// 导入特定模块
import { generateRandomId, createDate } from 'sakura-utils'

// 使用方法
const randomId = generateRandomId(16)
const date = createDate()

📁 模块分类

sakura-utils 包含以下功能模块：

| 模块 | 描述 | |------|------| | array | 数组操作相关方法 | | color | 颜色处理相关方法 | | date | 日期时间相关方法 | | file | 文件处理相关方法 | | function | 函数处理相关方法 | | number | 数字处理相关方法 | | object | 对象操作相关方法 | | params | URL参数相关方法 | | performance | 性能测量相关方法 | | random | 随机生成相关方法 | | string | 字符串处理相关方法 | | text | 文本处理相关方法 | | type | 类型判断相关方法 | | unit | 单位处理相关方法 | | validate | 验证相关方法 |

📚 API 文档

array 模块 - 数组操作相关方法

uniqueArray

描述: 数组去重 参数:

• array: T[] - 需要去重的数组

返回值: T[] - 去重后的数组

示例:

import { uniqueArray } from 'sakura-utils'

const arr = [1, 2, 2, 3, 4, 4, 5]
const uniqueArr = uniqueArray(arr)
console.log(uniqueArr) // 输出: [1, 2, 3, 4, 5]

uniqueDeepArray

描述: 深层数组去重 参数:

• array: any[] - 需要深层去重的数组

返回值: T[] - 深层去重后的数组

示例:

import { uniqueDeepArray } from 'sakura-utils'

const arr = [1, [2, 2], [3, [4, 4]]]
const uniqueArr = uniqueDeepArray(arr)
console.log(uniqueArr) // 输出: [1, [2], [3, [4]]]

flatArray

描述: 数组扁平化 参数:

• array: any[] - 需要扁平化的数组

返回值: T[] - 扁平化后的数组

示例:

import { flatArray } from 'sakura-utils'

const nestedArr = [1, [2, [3, [4]]]]
const flatArr = flatArray(nestedArr)
console.log(flatArr) // 输出: [1, 2, 3, 4]

uniqueFlatArray

描述: 数组扁平化并去重 参数:

• array: any[] - 需要扁平化并去重的数组

返回值: T[] - 扁平化并去重后的数组

示例:

import { uniqueFlatArray } from 'sakura-utils'

const nestedArr = [1, [2, 2], [3, [4, 4]]]
const result = uniqueFlatArray(nestedArr)
console.log(result) // 输出: [1, 2, 3, 4]

totalSum

描述: 计算数组总和 参数:

• array: any[] - 需要计算总和的数组

返回值: number - 数组元素的总和

示例:

import { totalSum } from 'sakura-utils'

const sumArr = [1, 2, 3, 4, 5]
const sum = totalSum(sumArr)
console.log(sum) // 输出: 15

randomSortArray

描述: 随机排序数组 参数:

• array: T[] - 需要随机排序的数组

返回值: T[] - 随机排序后的数组

示例:

import { randomSortArray } from 'sakura-utils'

const arr = [1, 2, 3, 4, 5]
const randomArr = randomSortArray(arr)
console.log(randomArr) // 输出: 随机排序后的数组

uniqueObjectArray

描述: 对象数组去重 参数:

• objArr: T[] - 需要去重的对象数组
• key: keyof T - 用于去重的对象键

返回值: T[] - 去重后的对象数组

示例:

import { uniqueObjectArray } from 'sakura-utils'

const users = [
    { id: 1, name: '张三' },
    { id: 2, name: '李四' },
    { id: 1, name: '张三' }
]
const uniqueUsers = uniqueObjectArray(users, 'id')
console.log(uniqueUsers) // 输出: [{ id: 1, name: '张三' }, { id: 2, name: '李四' }]

objectArrayGroup

描述: 对象数组分组 参数:

• objArr: T[] - 需要分组的对象数组
• key: keyof T - 用于分组的对象键

返回值: [M, T[]][] - 分组后的键值对数组

示例:

import { objectArrayGroup } from 'sakura-utils'

const users = [
    { id: 1, name: '张三', age: 20 },
    { id: 2, name: '李四', age: 20 },
    { id: 3, name: '王五', age: 21 }
]
const groupedUsers = objectArrayGroup(users, 'age')
console.log(groupedUsers) // 输出: [[20, [{ id: 1, name: '张三', age: 20 }, { id: 2, name: '李四', age: 20 }]], [21, [{ id: 3, name: '王五', age: 21 }]]]

chunkArray

描述: 数组分块 参数:

• array: T[] - 需要分块的数组
• size: number - 每个块的大小

返回值: T[][] - 分块后的数组

示例:

import { chunkArray } from 'sakura-utils'

const arr = [1, 2, 3, 4, 5, 6, 7, 8, 9]
const chunkedArr = chunkArray(arr, 3)
console.log(chunkedArr) // 输出: [[1, 2, 3], [4, 5, 6], [7, 8, 9]]

differenceArray

描述: 数组差异 参数:

• array: T[] - 主数组
• arrList: T[][] - 要比较的数组列表（可选）

返回值: T[] - 主数组中存在但其他数组中不存在的元素

示例:

import { differenceArray } from 'sakura-utils'

const arr1 = [1, 2, 3, 4, 5]
const arr2 = [3, 4, 5, 6, 7]
const arr3 = [5, 6, 7, 8, 9]
const result = differenceArray(arr1, arr2, arr3)
console.log(result) // 输出: [1, 2]

intersectionArray

描述: 数组交集 参数:

• arrList: T[] - 要计算交集的数组列表

返回值: T[] - 所有数组中都存在的元素

示例:

import { intersectionArray } from 'sakura-utils'

const arr1 = [1, 2, 3, 4, 5]
const arr2 = [3, 4, 5, 6, 7]
const arr3 = [5, 6, 7, 8, 9]
const result = intersectionArray(arr1, arr2, arr3)
console.log(result) // 输出: [5]

unionArray

描述: 数组合并 参数:

• arrList: T[] - 要合并的数组列表

返回值: T[] - 合并去重后的数组

示例:

import { unionArray } from 'sakura-utils'

const arr1 = [1, 2, 3]
const arr2 = [3, 4, 5]
const arr3 = [5, 6, 7]
const result = unionArray(arr1, arr2, arr3)
console.log(result) // 输出: [1, 2, 3, 4, 5, 6, 7]

compactArray

描述: 数组过滤空值 参数:

• array: T[] - 需要过滤空值的数组

返回值: T[] - 过滤空值后的数组

示例:

import { compactArray } from 'sakura-utils'

const arr = [1, null, undefined, 2, '', false, 3, 0]
const result = compactArray(arr)
console.log(result) // 输出: [1, 2, 3]

sampleArray

描述: 数组随机抽取 参数:

• array: T[] - 需要随机抽取的数组
• count: number - 抽取的数量，默认为1（可选）

返回值: T[] - 随机抽取的元素数组

示例:

import { sampleArray } from 'sakura-utils'

const arr = [1, 2, 3, 4, 5, 6, 7, 8, 9]
const result = sampleArray(arr, 3)
console.log(result) // 输出: [3, 7, 1] (随机结果)

groupByArray

描述: 数组分组 参数:

• array: T[] - 需要分组的对象数组
• key: keyof T - 用于分组的对象键

返回值: Record<string, T[]> - 分组后的对象

示例:

import { groupByArray } from 'sakura-utils'

const users = [
    { id: 1, name: '张三', age: 20 },
    { id: 2, name: '李四', age: 20 },
    { id: 3, name: '王五', age: 21 }
]
const groupedUsers = groupByArray(users, 'age')
console.log(groupedUsers) // 输出: { '20': [{ id: 1, name: '张三', age: 20 }, { id: 2, name: '李四', age: 20 }], '21': [{ id: 3, name: '王五', age: 21 }] }

color 模块 - 颜色处理相关方法

hexToRgb

描述: 十六进制颜色转 RGB 参数:

• hex: string - 十六进制颜色值

返回值: RgbColor - RGB 颜色对象

示例:

import { hexToRgb } from 'sakura-utils'

const rgb = hexToRgb('#ff0000')
console.log(rgb) // 输出: { r: 255, g: 0, b: 0 }

rgbToHex

描述: RGB 转十六进制颜色 参数:

• r: number - 红色通道值 (0-255)
• g: number - 绿色通道值 (0-255)
• b: number - 蓝色通道值 (0-255)

返回值: string - 十六进制颜色值

示例:

import { rgbToHex } from 'sakura-utils'

const hex = rgbToHex(255, 0, 0)
console.log(hex) // 输出: '#ff0000'

hslToRgb

描述: HSL 转 RGB 参数:

• h: number - 色相 (0-360)
• s: number - 饱和度 (0-1)
• l: number - 亮度 (0-1)

返回值: RgbColor - RGB 颜色对象

示例:

import { hslToRgb } from 'sakura-utils'

const rgb = hslToRgb(0, 1, 0.5)
console.log(rgb) // 输出: { r: 255, g: 0, b: 0 }

lighten

描述: 提亮颜色 参数:

• color: string - 颜色值
• amount: number - 提亮程度 (0-1)

返回值: string - 提亮后的颜色

示例:

import { lighten } from 'sakura-utils'

const lightenedColor = lighten('#ff0000', 0.2)
console.log(lightenedColor) // 输出: 提亮后的红色

darken

描述: 变暗颜色 参数:

• color: string - 颜色值
• amount: number - 变暗程度 (0-1)

返回值: string - 变暗后的颜色

示例:

import { darken } from 'sakura-utils'

const darkenedColor = darken('#ff0000', 0.2)
console.log(darkenedColor) // 输出: 变暗后的红色

alpha

描述: 为颜色添加透明度 参数:

• color: string - 颜色值
• opacity: number - 透明度 (0-1)

返回值: string - 带透明度的颜色

示例:

import { alpha } from 'sakura-utils'

const alphaColor = alpha('#ff0000', 0.5)
console.log(alphaColor) // 输出: 'rgba(255, 0, 0, 0.5)'

randomColor

描述: 生成随机颜色 参数: 无

返回值: string - 随机十六进制颜色值

示例:

import { randomColor } from 'sakura-utils'

const randomHexColor = randomColor()
console.log(randomHexColor) // 输出: 随机十六进制颜色值

date 模块 - 日期时间相关方法

createDate

描述: 创建日期对象 参数:

• value: string | number | Date - 日期值，默认为当前时间（可选）

返回值: CreateDateData - 包含日期信息和格式化方法的对象

示例:

import { createDate } from 'sakura-utils'

const date = createDate()
console.log(date.formatDate('YYYY-MM-DD HH:mm:ss')) // 输出: 2024-01-01 12:00:00

countDownTime

描述: 倒计时格式化 参数:

• timestamp: number - 倒计时秒数
• format: string - 格式化模板，默认为 "hh:mm:ss"（可选）

返回值: string - 格式化后的倒计时字符串

示例:

import { countDownTime, ONE_DAY_TIMESTAMP } from 'sakura-utils'

const endTime = Math.floor(ONE_DAY_TIMESTAMP / 1000) // 1天的秒数
const countdown = countDownTime(endTime)
console.log(countdown) // 输出: 24:00:00

getDateDiffData

描述: 获取时间差值 参数:

• timestamp: number - 时间戳差值（秒）

返回值: DateDiffData - 包含年、月、日、时、分、秒的差值对象

示例:

import { getDateDiffData } from 'sakura-utils'

const diff = getDateDiffData(3600 * 24 * 10) // 10天的秒数
console.log(diff) // 输出: { year: 0, month: 0, day: 10, hour: 0, minute: 0, second: 0 }

formatRelativeTime

描述: 相对时间格式化 参数:

• date: Date | string | number - 日期值

返回值: string - 格式化后的相对时间字符串

示例:

import { formatRelativeTime } from 'sakura-utils'

const yesterday = new Date(Date.now() - 24 * 3600 * 1000)
console.log(formatRelativeTime(yesterday)) // 输出: '1天前'

addDays

描述: 日期-日增加 参数:

• days: number - 增加的天数，默认为1（可选）
• value: string | number | Date - 基准日期，默认为当前时间（可选）

返回值: CreateDateData - 增加天数后的日期对象

示例:

import { addDays } from 'sakura-utils'

const tomorrow = addDays(1)
console.log(tomorrow.formatDate('YYYY-MM-DD')) // 输出: 明天的日期

addMonths

描述: 日期-月份增加 参数:

• months: number - 增加的月份，默认为1（可选）
• value: string | number | Date - 基准日期，默认为当前时间（可选）

返回值: CreateDateData - 增加月份后的日期对象

示例:

import { addMonths } from 'sakura-utils'

const nextMonth = addMonths(1)
console.log(nextMonth.formatDate('YYYY-MM-DD')) // 输出: 下个月的日期

addYears

描述: 日期-年份增加 参数:

• years: number - 增加的年份，默认为1（可选）
• value: string | number | Date - 基准日期，默认为当前时间（可选）

返回值: CreateDateData - 增加年份后的日期对象

示例:

import { addYears } from 'sakura-utils'

const nextYear = addYears(1)
console.log(nextYear.formatDate('YYYY-MM-DD')) // 输出: 明年的日期

minusDays

描述: 日期-日减少 参数:

• days: number - 减少的天数，默认为1（可选）
• value: string | number | Date - 基准日期，默认为当前时间（可选）

返回值: CreateDateData - 减少天数后的日期对象

示例:

import { minusDays } from 'sakura-utils'

const yesterday = minusDays(1)
console.log(yesterday.formatDate('YYYY-MM-DD')) // 输出: 昨天的日期

minusMonths

描述: 日期-月份减少 参数:

• months: number - 减少的月份，默认为1（可选）
• value: string | number | Date - 基准日期，默认为当前时间（可选）

返回值: CreateDateData - 减少月份后的日期对象

示例:

import { minusMonths } from 'sakura-utils'

const lastMonth = minusMonths(1)
console.log(lastMonth.formatDate('YYYY-MM-DD')) // 输出: 上个月的日期

minusYears

描述: 日期-年份减少 参数:

• years: number - 减少的年份，默认为1（可选）
• value: string | number | Date - 基准日期，默认为当前时间（可选）

返回值: CreateDateData - 减少年份后的日期对象

示例:

import { minusYears } from 'sakura-utils'

const lastYear = minusYears(1)
console.log(lastYear.formatDate('YYYY-MM-DD')) // 输出: 去年的日期

isSameDay

描述: 是否是同一天 参数:

• date1: string | number | Date - 第一个日期
• date2: string | number | Date - 第二个日期

返回值: boolean - 是否是同一天

示例:

import { isSameDay } from 'sakura-utils'

const date1 = '2024-01-01'
const date2 = '2024-01-01T12:00:00'
console.log(isSameDay(date1, date2)) // 输出: true

isToday

描述: 是否是今天 参数:

• date: string | number | Date - 要检查的日期

返回值: boolean - 是否是今天

示例:

import { isToday } from 'sakura-utils'

const today = new Date()
console.log(isToday(today)) // 输出: true

isYesterday

描述: 是否是昨天 参数:

• date: string | number | Date - 要检查的日期

返回值: boolean - 是否是昨天

示例:

import { isYesterday } from 'sakura-utils'

const yesterday = new Date(Date.now() - 24 * 3600 * 1000)
console.log(isYesterday(yesterday)) // 输出: true

isTomorrow

描述: 是否是明天 参数:

• date: string | number | Date - 要检查的日期

返回值: boolean - 是否是明天

示例:

import { isTomorrow } from 'sakura-utils'

const tomorrow = new Date(Date.now() + 24 * 3600 * 1000)
console.log(isTomorrow(tomorrow)) // 输出: true

getQuarter

描述: 获取季度 参数:

• date: string | number | Date - 基准日期，默认为当前时间（可选）

返回值: number - 季度（1-4）

示例:

import { getQuarter } from 'sakura-utils'

const date = '2024-04-01'
console.log(getQuarter(date)) // 输出: 2

getWeekNumber

描述: 获取当前第几周(本年) 参数:

• value: Date | string | number - 基准日期，默认为当前时间（可选）

返回值: number - 周数（1-53）

示例:

import { getWeekNumber } from 'sakura-utils'

const date = '2024-01-07'
console.log(getWeekNumber(date)) // 输出: 2

startOfWeek

描述: 获取指定日期所在周的开始日期 参数:

• value: string | number | Date - 基准日期，默认为当前时间（可选）

返回值: CreateDateData - 周开始日期对象

示例:

import { startOfWeek } from 'sakura-utils'

const date = '2024-01-15'
const weekStart = startOfWeek(date)
console.log(weekStart.formatDate('YYYY-MM-DD')) // 输出: 当周周一的日期

endOfWeek

描述: 获取指定日期所在周的结束日期 参数:

• value: string | number | Date - 基准日期，默认为当前时间（可选）

返回值: CreateDateData - 周结束日期对象

示例:

import { endOfWeek } from 'sakura-utils'

const date = '2024-01-15'
const weekEnd = endOfWeek(date)
console.log(weekEnd.formatDate('YYYY-MM-DD')) // 输出: 当周周日的日期

file 模块 - 文件处理相关方法

getFileType

描述: 获取文件类型 参数:

• value: string - 文件路径或base64字符串

返回值: string - 文件类型

示例:

import { getFileType } from 'sakura-utils'

console.log(getFileType('image.jpg')) // 输出: 'image'
console.log(getFileType('document.pdf')) // 输出: 'pdf'

getBase64FileType

描述: 获取base64文件类型 参数:

• base64: string - base64字符串

返回值: string - 文件类型

示例:

import { getBase64FileType } from 'sakura-utils'

const base64 = 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD...'
console.log(getBase64FileType(base64)) // 输出: 'image'

getBase64FileSuffix

描述: 获取base64文件后缀 参数:

• base64: string - base64字符串

返回值: string - 文件后缀

示例:

import { getBase64FileSuffix } from 'sakura-utils'

const base64 = 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD...'
console.log(getBase64FileSuffix(base64)) // 输出: 'jpg'

suffixToDotString

描述: 后缀转换为dot格式 参数:

• suffix: string[] - 文件后缀数组

返回值: string - 带dot格式的后缀字符串

示例:

import { suffixToDotString } from 'sakura-utils'

const result = suffixToDotString(['jpg', 'png', 'gif'])
console.log(result) // 输出: '.jpg,.png,.gif'

getFileDotSuffix

描述: 获取文件后缀的dot格式 参数:

• fileType: string - 文件类型，默认为*（可选）

返回值: string - 带dot格式的文件后缀字符串

示例:

import { getFileDotSuffix } from 'sakura-utils'

const imageSuffix = getFileDotSuffix('image')
console.log(imageSuffix) // 输出: '.jpg,.jpeg,.png,...'

getMultipleFileDotSuffix

描述: 获取多个文件类型的dot格式后缀 参数:

• fileTypes: string[] - 文件类型数组

返回值: string - 带dot格式的文件后缀字符串

示例:

import { getMultipleFileDotSuffix } from 'sakura-utils'

const result = getMultipleFileDotSuffix(['image', 'pdf'])
console.log(result) // 输出: '.jpg,.jpeg,.png,...,.pdf'

imageUrlToBase64

描述: 图片URL转base64 参数:

• url: string - 图片URL

返回值: Promise<string> - base64字符串

示例:

import { imageUrlToBase64 } from 'sakura-utils'

const base64 = await imageUrlToBase64('https://example.com/image.jpg')
console.log(base64) // 输出: base64字符串

base64ToBlob

描述: base64转blob 参数:

• dataURI: string - base64字符串

返回值: Blob - Blob对象

示例:

import { base64ToBlob } from 'sakura-utils'

const blob = base64ToBlob('data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD...')
console.log(blob) // 输出: Blob对象

base64ToFile

描述: base64转File对象 参数:

• base64: string - base64字符串
• suffix: string - 文件后缀，默认为png（可选）

返回值: File - File对象

示例:

import { base64ToFile } from 'sakura-utils'

const file = base64ToFile('data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD...', 'jpg')
console.log(file) // 输出: File对象

function 模块 - 函数处理相关方法

retryFun

描述: 函数重试 参数:

• fn: () => Promise<T> - 需要重试的函数
• retries: number - 重试次数，默认为 3（可选）
• delay: number - 重试间隔（毫秒），默认为 1000（可选）

返回值: Promise<T> - 函数执行结果或最终错误

示例:

import { retryFun } from 'sakura-utils'

async function fetchData() {
    // 模拟可能失败的请求
    if (Math.random() > 0.7) {
        throw new Error('请求失败')
    }
    return '请求成功'
}

retryFun(fetchData, 3, 1000)
    .then(result => console.log(result))
    .catch(error => console.error('最终失败:', error))

pollingFun

描述: 轮询函数 参数:

• fn: () => Promise<T> - 需要轮询的函数
• delay: number - 轮询间隔（毫秒），默认为 1000（可选）

返回值: PollingFunResult<T> - 包含start和stop方法的对象

示例:

import { pollingFun } from 'sakura-utils'

async function checkStatus() {
    // 模拟检查状态
    console.log('检查状态...')
    return Math.random() > 0.8; // 20% 概率成功
}

const { start, stop } = pollingFun(checkStatus, 1000)

// 开始轮询
start().then(result => {
    console.log('轮询结束，结果:', result)
})

// 5秒后停止轮询
setTimeout(() => {
    stop()
    console.log('轮询已停止')
}, 5000)

memoizeFun

描述: 函数记忆化 参数:

• fn: T extends (...args: any[]) => any - 需要记忆化的函数

返回值: T - 记忆化后的函数

示例:

import { memoizeFun } from 'sakura-utils'

// 计算斐波那契数列
const fib = memoizeFun((n: number): number => {
    if (n <= 1) return n
    return fib(n - 1) + fib(n - 2)
})

console.log(fib(10)) // 输出: 55
console.log(fib(10)) // 从缓存获取，输出: 55

number 模块 - 数字处理相关方法

numberToFixed

描述: 数字精度处理 参数:

• number: number - 需要处理的数字
• decimalPlaces: number - 小数位数，默认为 2（可选）

返回值: number - 处理后的数字

示例:

import { numberToFixed } from 'sakura-utils'

const num = 0.1 + 0.2
const fixedNum = numberToFixed(num, 2)
console.log(fixedNum) // 输出: 0.3

createZeroNumber

描述: 创建指定长度的零字符串 参数:

• length: number - 字符串长度，默认为 4（可选）

返回值: string - 指定长度的零字符串

示例:

import { createZeroNumber } from 'sakura-utils'

const zeros = createZeroNumber(5)
console.log(zeros) // 输出: '00000'

numberFillZero

描述: 数字/字符串补零 参数:

• value: number | string - 需要补零的值
• length: number - 目标长度，默认为 2（可选）
• type: "before" | "after" - 补零位置，默认为 "before"（可选）

返回值: string - 补零后的字符串

示例:

import { numberFillZero } from 'sakura-utils'

const num = 5
const filledNum = numberFillZero(num, 3)
console.log(filledNum) // 输出: '005'

clamp

描述: 数字范围限制 参数:

• number: number - 需要限制的数字
• min: number - 最小值
• max: number - 最大值

返回值: number - 限制在范围内的数字

示例:

import { clamp } from 'sakura-utils'

const num1 = clamp(15, 0, 10)
console.log(num1) // 输出: 10

const num2 = clamp(-5, 0, 10)
console.log(num2) // 输出: 0

formatBytes

描述: 字节大小格式化 参数:

• bytes: number - 字节数
• decimals: number - 小数位数，默认为 2（可选）

返回值: string - 格式化后的字节大小

示例:

import { formatBytes } from 'sakura-utils'

const size1 = formatBytes(1024)
console.log(size1) // 输出: '1.00KB'

const size2 = formatBytes(1048576, 1)
console.log(size2) // 输出: '1.0MB'

calculatePercentage

描述: 计算百分比 参数:

• part: number - 部分值
• total: number - 总值

返回值: number - 百分比值（0-100）

示例:

import { calculatePercentage } from 'sakura-utils'

const percentage = calculatePercentage(25, 100)
console.log(percentage) // 输出: 25

object 模块 - 对象操作相关方法

keysOf

描述: 获取对象所有键 参数:

• value: T - 需要获取键的对象

返回值: Array<keyof T> - 对象的所有键数组

示例:

import { keysOf } from 'sakura-utils'

const obj = { name: '张三', age: 20 }
const keys = keysOf(obj)
console.log(keys) // 输出: ['name', 'age']

valueOf

描述: 获取对象所有值 参数:

• value: T - 需要获取值的对象

返回值: any[] - 对象的所有值数组

示例:

import { valueOf } from 'sakura-utils'

const obj = { name: '张三', age: 20 }
const values = valueOf(obj)
console.log(values) // 输出: ['张三', 20]

extend

描述: 合并对象 参数:

• target: Partial<T> - 目标对象
• ...others: Partial<T>[] - 需要合并的其他对象（可选）

返回值: T - 合并后的对象

示例:

import { extend } from 'sakura-utils'

const obj1 = { name: '张三' }
const obj2 = { age: 20 }
const mergedObj = extend(obj1, obj2)
console.log(mergedObj) // 输出: { name: '张三', age: 20 }

entriesOf

描述: 对象转键值对数组 参数:

• value: T - 需要转换的对象

返回值: [string, any][] - 键值对数组

示例:

import { entriesOf } from 'sakura-utils'

const obj = { name: '张三', age: 20 }
const entries = entriesOf(obj)
console.log(entries) // 输出: [['name', '张三'], ['age', 20]]

lengthOf

描述: 获取对象/数组长度 参数:

• value: T - 需要获取长度的对象或数组

返回值: number - 对象或数组的长度

示例:

import { lengthOf } from 'sakura-utils'

const obj = { name: '张三', age: 20 }
const len = lengthOf(obj)
console.log(len) // 输出: 2

cloneDeep

描述: 深度克隆对象 参数:

• value: T - 需要克隆的对象

返回值: T - 克隆后的对象

示例:

import { cloneDeep } from 'sakura-utils'

const obj = { name: '张三', age: 20, hobbies: ['reading', 'coding'] }
const clonedObj = cloneDeep(obj)
console.log(clonedObj) // 输出: 克隆后的对象

objectValue

描述: 对象取值 参数:

• originData: Record<string, any> - 目标对象
• key: string - 键值，支持点号访问

返回值: T - 获取到的值

示例:

import { objectValue } from 'sakura-utils'

const obj = { name: '张三', age: 20, address: { city: '北京', street: '朝阳区' } }
const city = objectValue(obj, 'address.city')
console.log(city) // 输出: '北京'

hasOwn

描述: 检查对象是否有指定属性 参数:

• obj: T - 目标对象
• key: string - 要检查的属性名

返回值: boolean - 是否包含该属性

示例:

import { hasOwn } from 'sakura-utils'

const obj = { name: '张三', age: 20 }
console.log(hasOwn(obj, 'name')) // 输出: true
console.log(hasOwn(obj, 'gender')) // 输出: false

deepEqual

描述: 对象深比较 参数:

• obj1: any - 第一个比较对象
• obj2: any - 第二个比较对象

返回值: boolean - 两个对象是否深度相等

示例:

import { deepEqual } from 'sakura-utils'

const obj1 = { name: '张三', age: 20, address: { city: '北京' } }
const obj2 = { name: '张三', age: 20, address: { city: '北京' } }
const obj3 = { name: '李四', age: 25 }
console.log(deepEqual(obj1, obj2)) // 输出: true
console.log(deepEqual(obj1, obj3)) // 输出: false

extendHasOwn

描述: 只填充原对象有的key值 参数:

• originData: T - 原始对象
• otherData: Record<string, any> - 要合并的数据

返回值: T - 合并后的对象

示例:

import { extendHasOwn } from 'sakura-utils'

const obj1 = { name: '张三', age: 20 }
const obj2 = { age: 25, gender: '男' }
const mergedObj = extendHasOwn(obj1, obj2)
console.log(mergedObj) // 输出: { name: '张三', age: 25 }

extendHasOwns

描述: 只填充原对象有的key值（多个对象） 参数:

• originData: T - 原始对象
• ...otherData: Record<string, any>[] - 要合并的多个数据对象（可选）

返回值: T - 合并后的对象

示例:

import { extendHasOwns } from 'sakura-utils'

const obj1 = { name: '张三', age: 20 }
const obj2 = { age: 25, gender: '男' }
const obj3 = { name: '李四', city: '北京' }
const mergedObj = extendHasOwns(obj1, obj2, obj3)
console.log(mergedObj) // 输出: { name: '李四', age: 25 }

params 模块 - URL参数相关方法

objectToParamsStr

描述: 对象转URL参数字符串 参数:

• obj: Record<string, any> - 需要转换的对象

返回值: string - URL参数字符串

示例:

import { objectToParamsStr } from 'sakura-utils'

const obj = { name: '张三', age: 20, hobbies: ['reading', 'coding'] }
const paramsStr = objectToParamsStr(obj)
console.log(paramsStr) // 输出: 'name=张三&age=20&hobbies=%5B%22reading%22%2C%22coding%22%5D'

paramsStrToObject

描述: URL参数字符串转对象 参数:

• paramsStr: string - 需要转换的URL参数字符串

返回值: T - 转换后的对象

示例:

import { paramsStrToObject } from 'sakura-utils'

const url = 'https://example.com?name=张三&age=20'
const params = paramsStrToObject(url)
console.log(params) // 输出: { name: '张三', age: 20 }

getWindowsUrlParams

描述: 获取浏览器地址栏参数 参数: 无

返回值: T - 地址栏参数对象

示例:

import { getWindowsUrlParams } from 'sakura-utils'

const params = getWindowsUrlParams()
console.log(params) // 输出: 地址栏参数对象

performance 模块 - 性能测量相关方法

measurePerformance

描述: 性能测量工具函数，用于精确测量同步/异步函数的执行时间，支持日志输出和性能数据返回 参数:

• fn: () => T - 要测量的函数（同步或异步）
• options: MeasurePerformanceOptions - 配置选项（可选）

返回值: T - 函数执行结果（同步返回 T，异步返回 Promise）

示例:

import { measurePerformance } from 'sakura-utils'

// 测量同步函数
const syncResult = measurePerformance(() => {
    let sum = 0
    for (let i = 0; i < 1000000; i++) {
        sum += i
    }
    return sum
}, {
    name: '同步求和',
    log: true,
    precision: 2
})

// 测量异步函数
const asyncResult = await measurePerformance(async () => {
    // 模拟异步操作
    await new Promise(resolve => setTimeout(resolve, 1000))
    return '异步操作完成'
}, {
    name: '异步操作',
    log: true,
    onComplete: (result) => {
        console.log('性能数据:', result)
    }
})

random 模块 - 随机生成相关方法

generateRandomId

描述: 生成随机ID 参数:

• length: number - ID长度，默认为 16（可选）
• prefix: string - ID前缀，默认为 's'（可选）

返回值: string - 生成的随机ID

示例:

import { generateRandomId } from 'sakura-utils'

const randomId = generateRandomId(16, 'user_')
console.log(randomId) // 输出: 'user_abc123def456ghi7'

generateId

描述: 生成随机数字ID 参数:

• max: number - 最大值，默认为 10000（可选）

返回值: number - 生成的随机数字ID

示例:

import { generateId } from 'sakura-utils'

const id = generateId(1000)
console.log(id) // 输出: 42

randomCustomData

描述: 随机选择自定义数据 参数:

• customData: T[] - 自定义数据数组

返回值: T - 随机选择的数据

示例:

import { randomCustomData } from 'sakura-utils'

const fruits = ['apple', 'banana', 'orange', 'grape']
const randomFruit = randomCustomData(fruits)
console.log(randomFruit) // 输出: 随机选择的水果

text 模块 - 文本处理相关方法

computedTextSize

描述: 计算单个字符大小 参数:

• t: string - 需要计算大小的字符

返回值: number - 字符大小

示例:

import { computedTextSize } from 'sakura-utils'

const size = computedTextSize('A')
console.log(size) // 输出: 字符 'A' 的大小

computedTextsSize

描述: 计算文本总大小 参数:

• texts: string - 需要计算大小的文本
• fontSize: number - 字体大小

返回值: number - 文本总大小

示例:

import { computedTextsSize } from 'sakura-utils'

const size = computedTextsSize('Hello World', 16)
console.log(size) // 输出: 文本 'Hello World' 的总大小

type 模块 - 类型判断相关方法

isString

描述: 是否是字符串 参数:

• value: any - 需要判断的值

返回值: boolean - 是否是字符串

示例:

import { isString } from 'sakura-utils'

console.log(isString('hello')) // 输出: true
console.log(isString(123)) // 输出: false

isNumber

描述: 是否是数字 参数:

• value: any - 需要判断的值

返回值: boolean - 是否是数字

示例:

import { isNumber } from 'sakura-utils'

console.log(isNumber(123)) // 输出: true
console.log(isNumber('123')) // 输出: false

isBoolean

描述: 是否是布尔值 参数:

• value: any - 需要判断的值

返回值: boolean - 是否是布尔值

示例:

import { isBoolean } from 'sakura-utils'

console.log(isBoolean(true)) // 输出: true
console.log(isBoolean(1)) // 输出: false

isArray

描述: 是否是数组 参数:

• value: any - 需要判断的值

返回值: boolean - 是否是数组

示例:

import { isArray } from 'sakura-utils'

console.log(isArray([1, 2, 3])) // 输出: true
console.log(isArray({})) // 输出: false

isObject

描述: 是否是对象 参数:

• value: any - 需要判断的值

返回值: boolean - 是否是对象

示例:

import { isObject } from 'sakura-utils'

console.log(isObject({})) // 输出: true
console.log(isObject([1, 2, 3])) // 输出: false

isFunction

描述: 是否是函数 参数:

• value: any - 需要判断的值

返回值: boolean - 是否是函数

示例:

import { isFunction } from 'sakura-utils'

console.log(isFunction(() => {})) // 输出: true
console.log(isFunction({})) // 输出: false

isDate

描述: 是否是日期 参数:

• value: any - 需要判断的值

返回值: boolean - 是否是日期

示例:

import { isDate } from 'sakura-utils'

console.log(isDate(new Date())) // 输出: true
console.log(isDate('2024-01-01')) // 输出: false

isNull

描述: 是否是null 参数:

• value: any - 需要判断的值

返回值: boolean - 是否是null

示例:

import { isNull } from 'sakura-utils'

console.log(isNull(null)) // 输出: true
console.log(isNull(undefined)) // 输出: false

isUndefined

描述: 是否是undefined 参数:

• value: any - 需要判断的值

返回值: boolean - 是否是undefined

示例:

import { isUndefined } from 'sakura-utils'

console.log(isUndefined(undefined)) // 输出: true
console.log(isUndefined(null)) // 输出: false

isEmpty

描述: 是否为空 参数:

• value: T - 需要判断的值

返回值: boolean - 是否为空

示例:

import { isEmpty } from 'sakura-utils'

console.log(isEmpty([])) // 输出: true
console.log(isEmpty({})) // 输出: true
console.log(isEmpty('')) // 输出: true
console.log(isEmpty(0)) // 输出: false

isNotEmpty

描述: 是否不为空 参数:

• value: T - 需要判断的值

返回值: boolean - 是否不为空

示例:

import { isNotEmpty } from 'sakura-utils'

console.log(isNotEmpty([1, 2, 3])) // 输出: true
console.log(isNotEmpty({})) // 输出: false

isStringNumber

描述: 是否是字符串数字 参数:

• value: any - 需要判断的值

返回值: boolean - 是否是字符串数字

示例:

import { isStringNumber } from 'sakura-utils'

console.log(isStringNumber('123')) // 输出: true
console.log(isStringNumber('abc')) // 输出: false

isFile

描述: 是否是文件类型 参数:

• value: any - 需要判断的值

返回值: boolean - 是否是文件类型

示例:

import { isFile } from 'sakura-utils'

const file = new File(['test'], 'test.txt')
console.log(isFile(file)) // 输出: true
console.log(isFile({})) // 输出: false

isJsonObject

描述: 是否是json对象 参数:

• value: any - 需要判断的值

返回值: boolean - 是否是json对象

示例:

import { isJsonObject } from 'sakura-utils'

console.log(isJsonObject('{"name": "张三"}')) // 输出: true
console.log(isJsonObject('[]')) // 输出: false

isJsonArray

描述: 是否是json数组 参数:

• value: any - 需要判断的值

返回值: boolean - 是否是json数组

示例:

import { isJsonArray } from 'sakura-utils'

console.log(isJsonArray('[1, 2, 3]')) // 输出: true
console.log(isJsonArray('{"name": "张三"}')) // 输出: false

isSymbol

描述: 是否是symbol类型 参数:

• value: any - 需要判断的值

返回值: boolean - 是否是symbol类型

示例:

import { isSymbol } from 'sakura-utils'

console.log(isSymbol(Symbol('test'))) // 输出: true
console.log(isSymbol('test')) // 输出: false

isMap

描述: 是否为Map 参数:

• value: any - 需要判断的值

返回值: boolean - 是否为Map

示例:

import { isMap } from 'sakura-utils'

const map = new Map()
console.log(isMap(map)) // 输出: true
console.log(isMap({})) // 输出: false

isSet

描述: 是否是Set类型 参数:

• value: any - 需要判断的值

返回值: boolean - 是否是Set类型

示例:

import { isSet } from 'sakura-utils'

const set = new Set()
console.log(isSet(set)) // 输出: true
console.log(isSet([])) // 输出: false

isPromise

描述: 是否是Promise 参数:

• value: any - 需要判断的值

返回值: boolean - 是否是Promise

示例:

import { isPromise } from 'sakura-utils'

console.log(isPromise(new Promise(() => {}))) // 输出: true
console.log(isPromise(() => {})) // 输出: false

unit 模块 - 单位处理相关方法

addUnit

描述: 添加单位 参数:

• value: number | string | (string | number)[] - 需要添加单位的值
• unit: string - 单位，默认为 'px'（可选）

返回值: string - 添加单位后的值

示例:

import { addUnit } from 'sakura-utils'

console.log(addUnit(10)) // 输出: '10px'
console.log(addUnit('100%')) // 输出: '100%'
console.log(addUnit([10, 20])) // 输出: '10px 20px'

validate 模块 - 验证相关方法

isPhone

描述: 是否是手机号 参数:

• value: ValidateValue - 需要验证的值

返回值: boolean - 是否是手机号

示例:

import { isPhone } from 'sakura-utils'

console.log(isPhone('13800138000')) // 输出: true
console.log(isPhone('12345678901')) // 输出: false

isIdCard

描述: 是否是身份证号 参数:

• value: ValidateValue - 需要验证的值

返回值: boolean - 是否是身份证号

示例:

import { isIdCard } from 'sakura-utils'

console.log(isIdCard('110101199001011234')) // 输出: true
console.log(isIdCard('123456789012345678')) // 输出: false

isEmail

描述: 是否是邮箱 参数:

• value: ValidateValue - 需要验证的值

返回值: boolean - 是否是邮箱

示例:

import { isEmail } from 'sakura-utils'

console.log(isEmail('[email protected]')) // 输出: true
console.log(isEmail('testexample.com')) // 输出: false

isUrl

描述: 是否是URL 参数:

• url: ValidateValue - 需要验证的值

返回值: boolean - 是否是URL

示例:

import { isUrl } from 'sakura-utils'

console.log(isUrl('https://example.com')) // 输出: true
console.log(isUrl('example.com')) // 输出: false

isIp

描述: 是否是IP地址 参数:

• value: ValidateValue - 需要验证的值

返回值: boolean - 是否是IP地址

示例:

import { isIp } from 'sakura-utils'

console.log(isIp('192.168.1.1')) // 输出: true
console.log(isIp('256.256.256.256')) // 输出: false

📖 使用示例

数组操作

import { uniqueArray, flatArray, totalSum } from 'sakura-utils'

// 数组去重
const arr = [1, 2, 2, 3, 4, 4, 5]
const uniqueArr = uniqueArray(arr)
console.log(uniqueArr) // 输出: [1, 2, 3, 4, 5]

// 数组扁平化
const nestedArr = [1, [2, [3, [4]]]]
const flatArr = flatArray(nestedArr)
console.log(flatArr) // 输出: [1, 2, 3, 4]

// 计算数组总和
const sumArr = [1, 2, 3, 4, 5]
const sum = totalSum(sumArr)
console.log(sum) // 输出: 15

日期时间

import { createDate, countDownTime, ONE_DAY_TIMESTAMP } from 'sakura-utils'

// 创建日期对象
const date = createDate()
console.log(date.formatDate('YYYY-MM-DD HH:mm:ss')) // 输出当前日期时间

// 倒计时
const endTime = Date.now() + ONE_DAY_TIMESTAMP // 1天后
const countdown = countDownTime(Math.floor(ONE_DAY_TIMESTAMP / 1000))
console.log(countdown) // 输出: 24:00:00

随机生成

import { generateRandomId, randomCustomData } from 'sakura-utils'

// 生成随机 ID
const randomId = generateRandomId(16, 'user_')
console.log(randomId) // 输出: user_abc123def456ghi7

// 随机选择数据
const data = ['apple', 'banana', 'orange', 'grape']
const randomItem = randomCustomData(data)
console.log(randomItem) // 随机输出数组中的一个元素

URL 参数处理

import { objectToParamsStr, paramsStrToObject } from 'sakura-utils'

// 对象转 URL 参数
const obj = { name: '张三', age: 20, hobbies: ['reading', 'coding'] }
const paramsStr = objectToParamsStr(obj)
console.log(paramsStr) // 输出: name=张三&age=20&hobbies=%5B%22reading%22%2C%22coding%22%5D

// URL 参数转对象
const url = 'https://example.com?name=张三&age=20'
const params = paramsStrToObject(url)
console.log(params) // 输出: { name: '张三', age: 20 }

🤝 贡献指南

欢迎贡献代码和改进！请按照以下步骤进行：

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情

📞 联系我们

如有问题或建议，欢迎提交 Issue 或 Pull Request。

Happy Coding! 🌸