# @arkv/shared 中文文档

规范地址：https://npmcn.com/package/%40arkv/shared/

版本：0\.8\.0
npm 元数据更新时间：2026-07-30T07:14:56.691Z
中文译文更新时间：2026-11-06T19:41:34.456Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40arkv/shared
原文对照：https://npmcn.com/package/%40arkv/shared/?lang=original
项目主页：https://github.com/petarzarkov/arkv/tree/main/packages/shared#readme
源码仓库：https://github.com/petarzarkov/arkv

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

- 包体积（解压后）：33.1 kB，58 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-02-18T15:06:17.058Z
- 最新版本发布：2026-07-30T07:14:56.356Z
- 近 30 天下载量：2680（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

@ arkv 包的共享公用事业

## 安装

```sh
npm install @arkv/shared
```

也可以使用：`pnpm add @arkv/shared`、`yarn add @arkv/shared`、`bun add @arkv/shared`

## README

# @ arkv/ 共享

零依赖性共享公用事业和类型 `@arkv` 软件包.

## 安装

```bash
bun add @arkv/shared
# or
npm install @arkv/shared
```

## 公用事业

### 阵列

```typescript
import { groupBy, unique, chunk } from '@arkv/shared';

groupBy(
  [{ type: 'fruit', name: 'apple' }, { type: 'veg', name: 'carrot' }],
  i => i.type,
);
// { fruit: [{ type: 'fruit', name: 'apple' }], veg: [{ type: 'veg', name: 'carrot' }] }

unique([1, 2, 2, 3]); // [1, 2, 3]
unique(items, i => i.id); // deduplicate by key

chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
```

### 对象

```typescript
import { pick, omit, deepClone, isPlainObject, safeEntries } from '@arkv/shared';

pick({ a: 1, b: 2, c: 3 }, ['a', 'c']); // { a: 1, c: 3 }
omit({ a: 1, b: 2, c: 3 }, ['b']);       // { a: 1, c: 3 }

const cloned = deepClone({ nested: { value: 1 } });

// Prototype-based: only object literals, `JSON.parse` output and
// `Object.create(null)` qualify.
isPlainObject({});                 // true
isPlainObject(Object.create(null)); // true
isPlainObject([]);                 // false
isPlainObject(new Error());        // false
isPlainObject(new Map());          // false
isPlainObject(new Date());         // false
isPlainObject(new MyClass());      // false

// `Object.entries` that cannot be taken down by a throwing getter.
safeEntries({ ok: 1, get boom() { throw new Error('x'); } });
// [['ok', 1], ['boom', '[Getter: threw]']]
```

### 数目

```typescript
import { clamp, randomInt } from '@arkv/shared';

clamp(15, 0, 10);  // 10
clamp(-5, 0, 10);  // 0

randomInt(1, 100);  // random integer between 1 and 100 (inclusive)
```

### 自动同步

```typescript
import { retry, debounce, sleep } from '@arkv/shared';

// Retry up to 3 times with 100ms delay between attempts
const data = await retry(() => fetchData(), 3, 100);

// Debounce a function by 300ms
const debouncedSave = debounce(save, 300);

await sleep(1000); // wait 1 second
```

### 字符串

```typescript
import { safeStringify } from '@arkv/shared';

// Handles circular references without throwing
const obj: any = { a: 1 };
obj.self = obj;
safeStringify(obj); // '{"a":1,"self":"[Circular]"}'
```

### 網址

```typescript
import { UrlHelper } from '@arkv/shared';

const url = new UrlHelper();

url.buildUrl({
  base: 'https://api.example.com/{version}',
  path: '/users/{id}',
  pathParams: { version: 'v1', id: 123 },
  queryParams: { fields: 'name', active: true },
});
// https://api.example.com/v1/users/123?fields=name&active=true

url.interpolate('/api/{version}/users/{id}', { version: 'v1', id: 42 });
// '/api/v1/users/42'
```

## 类型

```typescript
import type {
  AsyncFn,
  Prettify,
  StringTransformFn,
  ParamsType,
} from '@arkv/shared';
```

| 类型 | 说明 |
| --- | --- |
| `AsyncFn<T>` | 一般自动同步函数类型 |
| `Prettify<T>` | 扩展对象类型以进行更好的 IDE 悬空预览 |
| `StringTransformFn` | 转换字符串的函数( 例如, 应用颜色/ 样式) |
| `ParamsType` | `Record<string, string | number | boolean | undefined>` |

## API 参考

### 阵列公用事业

| 函数 | 签署 | 说明 |
| --- | --- | --- |
| `groupBy` | `(items: T[], keyFn: (item: T) => string) => Record<string, T[]>` | 按键分组数组项目 |
| `unique` | `(items: T[], keyFn?: (item: T) => unknown) => T[]` | 删除重复, 有可选密钥函数 |
| `chunk` | `(items: T[], size: number) => T[][]` | 将数组分割成指定大小的块 |

### 实物公用事业

| 函数 | 签署 | 说明 |
| --- | --- | --- |
| `pick` | `(obj: T, keys: K[]) => Pick<T, K>` | 从对象中选择指定的密钥 |
| `omit` | `(obj: T, keys: K[]) => Omit<T, K>` | 来自对象的指定密钥 |
| `deepClone` | `(value: T) => T` | 深克隆通过 `structuredClone` |
| `isPlainObject` | `(obj: unknown) => obj is Record<string, unknown>` | 只对原型是 `Object.prototype` 或者说 `null` |
| `safeEntries` | `(obj: Record<string, unknown>) => [string, unknown][]` | `Object.entries` 其中投球者得分 `'[Getter: threw]'` |

### 公用事业数目

| 函数 | 签署 | 说明 |
| --- | --- | --- |
| `clamp` | `(value: number, min: number, max: number) => number` | 分数和最大数之间的剪接 |
| `randomInt` | `(min: number, max: number) => number` | 分数和最大数之间的随机整数(包括) |

### Async公用事业

| 函数 | 签署 | 说明 |
| --- | --- | --- |
| `retry` | `(fn: () => Promise<T>, retries?: number, delayMs?: number) => Promise<T>` | 延迟重试同步函数 |
| `debounce` | `(fn: T, delayMs: number) => (...args) => void` | 创建已取消的函数 |
| `sleep` | `(ms: number) => Promise<void>` | 基于承诺的延迟 |

### 串接公用事业

| 函数 | 签署 | 说明 |
| --- | --- | --- |
| `safeStringify` | `(obj: unknown) => string` | JSON. 使用循环参考处理 |

### URL 公用事业

| 类 | 方法 | 说明 |
| --- | --- | --- |
| `UrlHelper` | `buildUrl(config)` | 以路径/ query/ 路径参数构建 URL |
| `UrlHelper` | `interpolate(template, params?)` | 替换 `{key}` 字符串中的占位符 |

## 许可证

[麻省理工学院](https://npmcn.com/package/LICENSE)

## 常见问题

### @arkv/shared 是什么？

@ arkv 包的共享公用事业

### 如何安装 @arkv/shared？

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

### @arkv/shared 支持 TypeScript 吗？

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

### @arkv/shared 支持 ESM 还是 CommonJS？

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

### @arkv/shared 可以商用吗？

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

### @arkv/shared 的下载量有多少？

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

### @arkv/shared 还在维护吗？

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