# @explorins/pers-shared 中文文档

规范地址：https://npmcn.com/package/%40explorins/pers-shared/

版本：2\.1\.230
npm 元数据更新时间：2026-11-11T23:11:08.521Z
中文译文更新时间：2026-11-14T04:34:51.093Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40explorins/pers-shared
原文对照：https://npmcn.com/package/%40explorins/pers-shared/?lang=original

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

- 包体积（解压后）：3.8 MB，2291 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：nestjs-cls ^4\.4\.1
- 首次发布：2025-09-06T17:51:13.849Z
- 最新版本发布：2026-11-11T23:11:08.322Z
- 近 30 天下载量：2531（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：207（近 12 个月 173 个）

## 中文简介

PERS 应用程序共享库

## 安装

```sh
npm install @explorins/pers-shared
```

也可以使用：`pnpm add @explorins/pers-shared`、`yarn add @explorins/pers-shared`、`bun add @explorins/pers-shared`

## README

# @ explorins/ pers- supposed (英语)

## 公共合同图书馆

前端,第三方集成,API消费者的纯数据合同.

## 套装大小

-   **浏览器 Bundle**数字 : **0.44 KB (韩语)** (0.30 KB 击出)
-   **全装**数字 : **0.67 KB (韩语)** (0.38 KB 击出)
-   **常见JS**数字 : **1.53 KB (韩语)** (0.72 KB克齐普)
-   **软件包大小**: 1.2 MB(包括所有类型脚本定义)
-   **运行时间影响**: 有树摇动的 < 1 KB

## 目录

-   **DTO 数据交换** - 通过验证完成 API 数据传输对象
-   **接口** - 认证、用户、竞选、交易的脚本类型合同
-   **类型( E)** - 认证类型、错误代码、交易状态
-   **值对象** - 不可移动的数据结构(`Address`, (中文(简体) ), `StructuredError`(中文(简体) )
-   **错误分类** - 结构化域差(`AuthenticationRequiredError`页:1
-   **域名词组** - 说吧 `Domains` 为SDK事件, `ErrorDomains` 错误分类

## 关键构建配置

**银河公司问题**: 此库需要 `"moduleResolution": "node16"` 在tsconfig.json中防止与NestJS Swagger发生循环依赖性错误。 使用 `"node"` 导致斯瓦格生成失败的调试3天.

```json
{
  "compilerOptions": {
    "moduleResolution": "node16", // CRITICAL: Required for Swagger compatibility
    "target": "ES2022",
    "module": "CommonJS"
  }
}
```

## 使用量

```bash
npm install @explorins/pers-shared
```

### **后端/节点.js**

```typescript
import { 
  UserDTO, 
  TransactionStatus, 
  AuthenticationRequiredError,
  PasskeysAuthRequestDTO 
} from '@explorins/pers-shared';

// Type-safe API requests
const authRequest: PasskeysAuthRequestDTO = {
  authToken: "external_provider_jwt_token"
};

// Structured error handling
try {
  const user = await authenticate(authRequest);
} catch (error) {
  if (error instanceof AuthenticationRequiredError) {
    console.error('Authentication failed:', error.code);
  }
}
```

### **前端/浏览器(Ultra-Light)**

```typescript
// Browser-optimized import - Tree-shaken to 0.44 KB!
import { UserDTO, CampaignDTO, Address } from '@explorins/pers-shared/browser';

// React example with full type safety
interface UserBalanceProps {
  user: UserTokenBalancesDTO;
}

const UserBalance: React.FC<UserBalanceProps> = ({ user }) => (
  <div>
    <h2>{user.email}</h2>
    <p>Wallet: {user.walletAddress?.getValue()}</p>
  </div>
);
```

## 🔧 **构建系统性能( P)**

-   **双构件**: 通用JS(节点.js)+具有自动选择功能的无害环境管理(浏览器)
-   **异常树摇**: 99.9%+消除 (1.2 MB包 → 0.44 KB运行时间)
-   **0 运行时间**: 无执行间接费用的纯类型定义
-   **框架不可知论**:反应、Vue、Angular、香草JS、节点

## ️ **域名词组**

SDK事件分类和错误分类的统一域名:

```typescript
// SDK success events - business domains only
import { Domains, Domain } from '@explorins/pers-shared';

onSuccess(event: { domain: Domain }) {
  if (event.domain === Domains.TRANSACTION) { ... }
}

// SDK error handler - includes technical categories
import { ErrorDomains, ErrorDomain } from '@explorins/pers-shared';

onError(error: { domain: ErrorDomain }) {
  if (error.domain === ErrorDomains.VALIDATION) { ... }
}
```

## 🎯 **主要惠益**

-   **类型安全**: 在编译时抓取 API 集成错误
-   **开发者经验**: 全面IntelliSense和自动完成
-   **业绩**: 特殊树摇晃 (1.2 MB − 0.44 KB 运行时间)
-   **可靠性**合同符合PERS API的规格

## 常见问题

### @explorins/pers-shared 是什么？

PERS 应用程序共享库

### 如何安装 @explorins/pers-shared？

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

### @explorins/pers-shared 支持 TypeScript 吗？

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

### @explorins/pers-shared 支持 ESM 还是 CommonJS？

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

### @explorins/pers-shared 可以商用吗？

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

### @explorins/pers-shared 的下载量有多少？

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

### @explorins/pers-shared 还在维护吗？

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