# @dpaskhin/unique 中文文档

规范地址：https://npmcn.com/package/%40dpaskhin/unique/

版本：1\.1\.0
npm 元数据更新时间：2026-07-10T00:05:45.480Z
中文译文更新时间：2026-11-12T19:52:33.755Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：33.8 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2024-10-02T22:49:52.322Z
- 最新版本发布：2026-07-10T00:05:45.347Z
- 近 30 天下载量：5643（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 1 个）

## 中文简介

通过拒绝重复来保证独特的值.

## 安装

```sh
npm install @dpaskhin/unique
```

也可以使用：`pnpm add @dpaskhin/unique`、`yarn add @dpaskhin/unique`、`bun add @dpaskhin/unique`

## README

# @dpaskhin/ 独一无二

[![npm version](https://img.shields.io/npm/v/@dpaskhin/unique.svg)](https://www.npmjs.com/package/@dpaskhin/unique) [![bundle size](https://img.shields.io/bundlephobia/minzip/@dpaskhin/unique)](https://bundlephobia.com/package/@dpaskhin/unique) [![license](https://img.shields.io/npm/l/@dpaskhin/unique.svg)](https://github.com/dPaskhin/unique/blob/main/LICENSE)

**@dpaskhin/ 独一无二** 是用于生成独特值的 TypeScript 库。 它通过拒绝重复来保证不重复 并重试直到找到新结果。 确保非重复随机值的理想值 .

## 目录

-   [安装](https://npmcn.com/package/%40dpaskhin/unique/#readme-installation)
-   [特征](https://npmcn.com/package/%40dpaskhin/unique/#readme-features)
-   [使用量](https://npmcn.com/package/%40dpaskhin/unique/#readme-usage)
-   [API 参考](https://npmcn.com/package/%40dpaskhin/unique/#readme-api-reference)
-   [处理错误](https://npmcn.com/package/%40dpaskhin/unique/#readme-error-handling)
-   [最佳做法](https://npmcn.com/package/%40dpaskhin/unique/#readme-best-practices)
-   [许可证](https://npmcn.com/package/%40dpaskhin/unique/#readme-license)
-   [捐款](https://npmcn.com/package/%40dpaskhin/unique/#readme-contributing)

## 安装

要安装 **@dpaskhin/ 独一无二**,运行 :

```shell
npm install --save-dev @dpaskhin/unique
```

或者,如果你使用pnpm:

```shell
pnpm add --save-dev @dpaskhin/unique
```

## 特征

-   根据任何函数或平方值的输出生成独特的值.
-   支助 `custom` 存储或 `global` 存储用于独有性跟踪.
-   可配置 `retry` 财务报告和审定财务报表 `timeout` 选项.
-   `stringifier` 支持在特性检查时自定义处理复杂对象.

## 使用量

#### 基本示例

这里有一个使用 **@dpaskhin/ 独一无二**数字 :

```ts
import { unique } from '@dpaskhin/unique';

// Outputs a unique random number each time
console.log(unique(Math.random));
console.log(unique(Math.random));
console.log(unique(Math.random));
```

#### Faker.js 示例

**@dpaskhin/ 独一无二** 和图书馆合作得很好 [Faker.js (英语)](https://github.com/faker-js/faker) 用于生成唯一 随机数据.

```ts
import { unique, uniqueFactory } from '@dpaskhin/unique';
import { faker } from '@faker-js/faker';

// Outputs a unique first name each time
console.log(unique(faker.person.firstName));
console.log(unique(faker.person.firstName));
console.log(unique(faker.person.firstName));

// ----------------------------------------

const createUniqueUser = uniqueFactory(() => ({
  firstName: faker.person.firstName(),
  lastName: faker.person.lastName(),
  age: faker.number.int({ min: 18, max: 100 }),
}));

// Each output user is structurally unique
console.log(createUniqueUser());
console.log(createUniqueUser());
console.log(createUniqueUser());
```

#### 自定义存储

你可以提供自己的商店 来隔离独特的检查。 这确保了在以下范围内跟踪独特性: 你的申请.

```ts
import { unique } from '@dpaskhin/unique';

const scopedStore = new Set();

// Outputs a unique random number
console.log(unique(Math.random, [], { store: scopedStore }));
```

#### 全球存储

如果您不提供自定义商店, 图书馆会使用 **全球** 默认。 这可以有用,如果你 想要跟踪您应用程序不同部分的独特值.

```ts
import { unique, GLOBAL_STORE } from '@dpaskhin/unique';

// Use the global store for uniqueness checks
const uniqueRandomValue1 = unique(Math.random);
const uniqueRandomValue2 = unique(Math.random);

// Outputs two unique random values
console.log(uniqueRandomValue1, uniqueRandomValue2);

// Clear the global store when needed
GLOBAL_STORE.clear();
```

#### 不包括具体价值

您也可以提供排除列表,以防止特定值在独特性检查时被考虑.

```ts
import { uniqueFactory } from '@dpaskhin/unique';

const createUniqueRandom = uniqueFactory(Math.random, {
  // Prevents these values from being returned
  exclude: [0.5, 0.6],
});

// Outputs a unique random number, excluding 0.5 and 0.6
console.log(createUniqueRandom());
```

#### 复杂对象或其他非原始类型的字符串

这个 **字符串** 选项允许您处理复杂的对象,将它们转换成字符串进行独有性检查.

_默认a `JSON.stringify`\- 使用基于字符串符——它另外区分 `NaN`编号 :`Infinity`编号 :`-Infinity` 从 `null` (裸着) `JSON.stringify` 否则就会崩溃 `"null"` 并总是返回真实 字符串,甚至对数值如 `undefined` 对其中 `JSON.stringify` 自动返回 `undefined`。 。 。 ._

```ts
import { uniqueFactory } from '@dpaskhin/unique';
import { faker } from '@faker-js/faker';
import JsonMarshal from 'json-marshal';

const createUniqueUser = uniqueFactory(
  () => ({
    name: faker.person.firstName(),
    age: faker.number.int({ min: 18, max: 100 }),
  }),
  {
    // Here can be any function that takes the return value of the function provided above and converts it to a string.
    // Or just omit it to use the default stringifier described above.
    stringifier: JsonMarshal.stringify,
  }
);

const user1 = createUniqueUser();
const user2 = createUniqueUser();

// Outputs two unique users
console.log(user1, user2);
```

## API 参考

### 唯一事实( fn, 选项)

创建一个功能,确保根据所提供的函数 fn 得出独特的结果.

#### 参数

-   fn - 用于生成值的函数.
-   选项 - 可选。 包含配置选项的对象 :
    -   **存储** (Set):用于跟踪独特值的自定义商店. 默认为 a **新设置**。 。 。 .
    -   **最大存储量** (数字):在投出出出错前生成唯一值的最大重试次数. 默认为50.
    -   **最大时间** (数字):在投出一个 错误。 默认为50ms.
    -   **排除** (Array):从结果集中排除的数值列表. 这些值不会是 由唯一生成器返回.
    -   **字符串** (函数):在存储结果之前将结果字符串的函数 。 默认为 a `JSON.stringify`\- 基于 字符串( 见 [复杂对象的字符串](https://npmcn.com/package/%40dpaskhin/unique/#readme-stringifier-for-complex-objects-or-other-non-primitive-types)) (中文(简体) ).

#### 回返

一个函数以相同的签名生成基于 fn 的独特值.

#### 示例

```ts
import { uniqueFactory } from '@dpaskhin/unique';
import { faker } from '@faker-js/faker';

const createUniqueUser = uniqueFactory(() => ({
  name: faker.person.firstName(),
  age: faker.number.int({ min: 18, max: 100 }),
}));

// Outputs a unique user each time
console.log(createUniqueUser());
console.log(createUniqueUser());
console.log(createUniqueUser());
```

### 独有( fn, 参数, 选项)

通过运行 fn 和通过提供或全球商店确保独有性来生成一个独特的值.

#### 参数

-   fn - 用于生成值的函数.
-   args - 可选. 一系列要传递到 fn 的参数 .
-   选项 - 可选。 包含配置选项的对象 :
    -   **存储** (Set):用于跟踪独特值的自定义商店. 默认情况下 **全球** 已使用.
    -   **最大存储量** (数字):在投出出出错前生成唯一值的最大重试次数. 默认为50.
    -   **最大时间** (数字):在投出一个 错误。 默认为50ms.
    -   **排除** (Array):从结果集中排除的数值列表. 这些值不会是 由唯一生成器返回.
    -   **字符串** (函数):在存储结果之前将结果字符串的函数 。 默认为 a `JSON.stringify`\- 基于 字符串( 见 [复杂对象的字符串](https://npmcn.com/package/%40dpaskhin/unique/#readme-stringifier-for-complex-objects-or-other-non-primitive-types)) (中文(简体) ).

#### 回返

由 fn 生成的独特值 .

#### 示例

```ts
import { unique } from '@dpaskhin/unique';
import { faker } from '@faker-js/faker';

const uniqueEmail = unique(faker.internet.email, [
  {
    firstName: faker.person.firstName(),
    lastName: faker.person.lastName(),
  },
]);

// Outputs a unique email
console.log(uniqueEmail);
```

### 独有( 值, 选项)

通过检查所提供的或全球商店,确保纯值是独一无二的.

#### 参数

-   值 - 纯值(非功能性),以确保其独特性.
-   选项 - 可选。 包含配置选项的对象 :
    -   **存储** (Set):用于跟踪独特值的自定义商店. 默认情况下 **全球** 已使用.
    -   **排除** (Array):要排除的数值列表. 这些值不会被添加到存储或返回 .
    -   **字符串** (函数):一个在存储之前将值字符串的函数 。 默认为 a `JSON.stringify`\- 基于 字符串( 见 [复杂对象的字符串](https://npmcn.com/package/%40dpaskhin/unique/#readme-stringifier-for-complex-objects-or-other-non-primitive-types)) (中文(简体) ).

#### 回返

提供的独特价值.

#### 示例

这个超载是用来检查您已经拥有的值—— 不是随机生成的值—— 对一个商店, 例如一发子弹 从用户输入中得出 :

```ts
import { unique } from '@dpaskhin/unique';

const usedSlugs = new Set();

function toSlug(title: string) {
  return unique(title.toLowerCase().replace(/\s+/g, '-'), { store: usedSlugs });
}

console.log(toSlug('Hello World')); // 'hello-world'
toSlug('Hello World'); // throws UniqueError — slug already taken
```

### 唯一错误

所抛出的错误类 `uniqueFactory`编号 :`unique` 当无法产生独特的价值时。 扩展 `Error`。 。 。 .

#### 字段

-   **存储大小** (数字):商店在失败时所持有的数值数.
-   **会期** (数字):在放弃前曾尝试过多久(以毫秒计)的一代.
-   **重复次数** (数字):在放弃之前,生成器函数被调用多少次.

见 [处理错误](https://npmcn.com/package/%40dpaskhin/unique/#readme-error-handling) 以下为用法示例.

### 全球

模块级别 `Set` 用于 `unique()` 不提供习惯的电话 `store` 选项。 分享整个你 默认应用——见 [全球存储](https://npmcn.com/package/%40dpaskhin/unique/#readme-global-store) 上文,以及 [最佳做法](https://npmcn.com/package/%40dpaskhin/unique/#readme-best-practices) 何时 避开它.

## 处理错误

`uniqueFactory`编号 :`unique` 丢出一个 `UniqueError` 当它们不能产生独特的价值时:

-   用于基于函数的生成`uniqueFactory(fn)`, (中文(简体) ), `unique(fn, args)`这一次 `maxRetries` 或者说 `maxTime` 超过.
-   用于平价形式(`unique(value)`如果 `value` 已经在店里了.

`UniqueError` 以导出, 这样您就可以检查它, 而不是分析错误消息 :

```ts
import { unique, UniqueError } from '@dpaskhin/unique';

try {
  unique(() => Math.floor(Math.random() * 2), [], { maxRetries: 5 });
} catch (error) {
  if (error instanceof UniqueError) {
    console.error(error.message);
    console.error(error.storeSize, error.iterations, error.duration);
  }
}
```

## 最佳做法

-   在需要本地特性时避免使用全球商店,因为它可能导致出乎意料的结果 由于共享状态.
-   配置 Max Retries和超时: 根据预期的独特性和复杂性自定义最大 Retries和最大时间 的数值.
-   避免使用纯值,更喜欢生成函数来进行灵活性和再试.

## 许可证

**@dpaskhin/ 独一无二** 根据麻省理工学院的许可证颁发执照.

## 捐款

欢迎捐款! 如果你有想法或改进,请随意提交拉动请求.

## 常见问题

### @dpaskhin/unique 是什么？

通过拒绝重复来保证独特的值\.

### 如何安装 @dpaskhin/unique？

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

### @dpaskhin/unique 支持 TypeScript 吗？

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

### @dpaskhin/unique 支持 ESM 还是 CommonJS？

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

### @dpaskhin/unique 可以商用吗？

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

### @dpaskhin/unique 的下载量有多少？

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

### @dpaskhin/unique 还在维护吗？

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