# @gaubee/util 中文文档

规范地址：https://npmcn.com/package/%40gaubee/util/

版本：0\.35\.2
npm 元数据更新时间：2025-11-10T07:53:05.121Z
中文译文更新时间：2026-11-16T00:07:54.815Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gaubee/util
原文对照：https://npmcn.com/package/%40gaubee/util/?lang=original
项目主页：https://github.com/gaubee/std/tree/main/util
源码仓库：https://github.com/gaubee/std

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：393 kB，197 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2024-10-09T10:00:57.197Z
- 最新版本发布：2025-11-10T07:53:04.883Z
- 近 30 天下载量：2012（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：59（近 12 个月 0 个）

## 中文简介

一些常见的pure-js工具函数，适用于任何场景

## 安装

```sh
npm install @gaubee/util
```

也可以使用：`pnpm add @gaubee/util`、`yarn add @gaubee/util`、`bun add @gaubee/util`

## README

# @gaubee/util

## 简介

1.  个人项目经验，涵盖大量常用函数集合，建议与 deno 的 [`@std/*`](https://jsr.io/@std) 互为补充。
    
    > 这个库中与 @std 系列有一些交集，交集的部分通常是我个人觉得我自己的实现更好：
    > 
    > -   可能是性能上更好
    > -   可能是使用体验上更易用好用
    > -   可能是条件边界覆盖更全。
    
2.  这个库不会包含垫片相关的，只要在 esnext 范畴内我都会使用，所以请自行处理垫片相关的问题

## 使用 How to use

**install:**

```bash
npm install @gaubee/util
pnpm install @gaubee/util
yarn install @gaubee/util
deno add @gaubee/util
bun add @gaubee/util
```

**usage:**

> 注意，本项目没有副作用了，对 [Tree-Shaking](https://rollupjs.org/introduction/#tree-shaking) 支持良好，你可以直接 import 一整个包，最终 bundle 的时候，只会包含你实际使用的部分。

```ts
import { delay } from "@gaubee/util";
```

### 简介

1.  个人项目经验，涵盖大量常用函数集合，建议与 deno 的 [`@std/*`](https://jsr.io/@std) 互为补充。
    
    > 这个库中与 @std 系列有一些交集，交集的部分通常是我个人觉得我自己的实现更好：
    > 
    > -   可能是性能上更好
    > -   可能是使用体验上更易用好用
    > -   可能是条件边界覆盖更全。
    
2.  这个库通常不会包含垫片相关的，只要在 esnext 范畴内我都会使用，所以请自行处理垫片相关的问题
    
    > 例如 Promise.withResolvers
    

## API

-   参考链接：[jsr-docs 文档](https://jsr.io/@gaubee/util/doc)
-   参考链接：[deepwiki-docs 文档](https://deepwiki.com/Gaubee/std/3-package:-@gaubeeutil)

### @gaubee/util/abort

-   `abort_signal_merge`:
    -   `(..._signals: (AbortSignal | undefined | null)[]) => AbortSignal | undefined`
    -   将 N 个 AbortSignal 合并成 0/1 个

### @gaubee/util/array

-   `arr_set_next`:
    -   `(arr: Array<T>, item: T) => void`
    -   在数组末尾追加元素
-   `sparse_arr_get_first`:
    -   `<T>(arr: ArrayLike<T>) => T`
    -   取数组第一个元素（跳过稀疏部分），不存在则抛出异常
-   `sparse_arr_get_first_or_null`:
    -   `<T>(arr: ArrayLike<T>) => T | undefined`
    -   取数组第一个元素（跳过稀疏部分），不存在则返回 undefined
-   `sparse_arr_get_first_or_default`:
    -   `<T, R>(arr: ArrayLike<T>, defaultValue: () => R) => T | R`
    -   取数组第一个元素（跳过稀疏部分），不存在则返回默认值
-   `arr_get_first`:
    -   `<T>(arr: ArrayLike<T>) => T`
    -   取数组第一个元素（下标 0），不存在则抛出异常
-   `arr_get_first_or_null`:
    -   `<T>(arr: ArrayLike<T>) => T | undefined`
    -   取数组第一个元素（下标 0），不存在则返回 undefined
-   `arr_get_first_or_default`:
    -   `<T, R>(arr: ArrayLike<T>, defaultValue: () => R) => T | R`
    -   取数组第一个元素（下标 0），不存在则返回默认值
-   `sparse_arr_get_last`:
    -   `<T>(arr: ArrayLike<T>) => T`
    -   取数组最后一个元素（跳过稀疏部分），不存在则抛出异常
-   `sparse_arr_get_last_or_null`:
    -   `<T>(arr: ArrayLike<T>) => T | undefined`
    -   取数组最后一个元素（跳过稀疏部分），不存在则返回 undefined
-   `sparse_arr_get_last_or_default`:
    -   `<T, R>(arr: ArrayLike<T>, defaultValue: () => R) => T | R`
    -   取数组最后一个元素（跳过稀疏部分），不存在则返回默认值
-   `arr_get_last`:
    -   `<T>(arr: ArrayLike<T>) => T`
    -   取数组最后一个元素（下标 length-1），不存在则抛出异常
-   `arr_get_last_or_null`:
    -   `<T>(arr: ArrayLike<T>) => T | undefined`
    -   取数组最后一个元素（下标 length-1），不存在则返回 undefined
-   `arr_get_last_or_default`:
    -   `<T, R>(arr: ArrayLike<T>, defaultValue: () => R) => T | R`
    -   取数组最后一个元素（下标 length-1），不存在则返回默认值
-   `arr_remove_first`:
    -   `<T>(arr: T[], value: T) => number`
    -   移除数组中指定的第一个匹配项，返回移除的索引，未找到返回 -1

### @gaubee/util/bigint

-   `bigint_gcd`:
    -   `(left: bigint, right: bigint) => bigint`
    -   计算两个 bigint 的最大公约数 (GCD)

### @gaubee/util/date

-   `date_clone`:
    -   `(date: Date) => Date`
    -   克隆 Date 对象
-   `Duration`:
    -   `type Duration = { year: number; month: number; day: number; minutes: number; seconds: number; milliseconds: number; }`
    -   人类可读的时间对象类型
-   `date_add_duration`:
    -   `(date: Date, duration: Partial<Duration>) => Date`
    -   向 Date 对象添加时间段
-   `date_to_duration`:
    -   `(date: Date) => Duration`
    -   将 Date 对象转换为 Duration 对象
-   `date_set_duration`:
    -   `(date: Date, duration: Partial<Duration>) => Date`
    -   设置 Date 对象的指定时间部分
-   `FormatifyDate`:
    -   `type FormatifyDate = { ... }`
    -   用于格式化的日期信息对象类型
-   `date_formatify`:
    -   `(date: string | number | Date) => FormatifyDate`
    -   将日期转换为易于格式化的信息对象
-   `date_format`:
    -   `(format: string, date: string | number | Date) => string`
    -   根据指定模板格式化日期

### @gaubee/util/debounce

-   `func_debounce`:
    -   `<T extends Func>(fn: T, wait: number | Timmer = 0, options: { before?: boolean }) => DebouncedFunction<T>`
    -   创建一个防抖函数，延迟执行提供的函数直到等待时间过去。包含 `isPending`, `cancel`, `source`, `flush` 方法。
    -   `DebouncedFunction`: 带有额外控制方法的函数类型

## 常见问题

### @gaubee/util 是什么？

一些常见的pure-js工具函数，适用于任何场景

### 如何安装 @gaubee/util？

在项目目录运行 npm install @gaubee/util，或使用 pnpm add / yarn add / bun add。

### @gaubee/util 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gaubee/util 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @gaubee/util 可以商用吗？

@gaubee/util 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gaubee/util 的下载量有多少？

根据 npm 官方下载统计，@gaubee/util 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,012 次，日均约 67 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gaubee/util 还在维护吗？

最新版本 0\.35\.2 发布于 2025/11/10（1 年前）；至今共发布 59 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/10/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

