# @data-fair/lib-common-types 中文文档

规范地址：https://npmcn.com/package/%40data-fair/lib-common-types/

版本：1\.27\.0
npm 元数据更新时间：2026-10-19T15:33:12.830Z
中文译文更新时间：2026-11-13T07:09:45.288Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40data-fair/lib-common-types
原文对照：https://npmcn.com/package/%40data-fair/lib-common-types/?lang=original

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

- 包体积（解压后）：543 kB，91 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：3 个
- peer 依赖：tinycolor2 1
- 首次发布：2024-10-07T14:02:14.357Z
- 最新版本发布：2026-10-19T15:33:12.519Z
- 近 30 天下载量：2139（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：73（近 12 个月 22 个）

## 中文简介

共享计划,并在数据公平堆栈中构建类型定义.

## 安装

```sh
npm install @data-fair/lib-common-types
```

也可以使用：`pnpm add @data-fair/lib-common-types`、`yarn add @data-fair/lib-common-types`、`bun add @data-fair/lib-common-types`

## README

# @ data-fair/ lib- 常见类型

JSON 计划类型和 TypeScript 类型在数据公平堆栈(会话状态,账户,事件,通知,主题,目录和处理插件合同...)之间共享,其生成的验证器和几个帮助器在其上建起. 服务, Vue 应用程序和插件导入它,以便它们都说相同的合同.

## 安装

```sh
npm i @data-fair/lib-common-types
```

可选对等依赖 : `tinycolor2` (v1),仅需满足 `theme/index.js`。 。 。 .

## 模块

每个目录模块都会导出其生成的类型(和 `validate` 编号 : `assertValid` 编号 : `returnValid` 从 `index.js`作为默认导出 `schema.js`。 。 。 .

| 导入路径 | 说明 |
| --- | --- |
| `@data-fair/lib-common-types/session/index.js` | `SessionState`, (中文(简体) ), `SessionStateAuthenticated`, (中文(简体) ), `User`, (中文(简体) ), `Account`...类型、验证符和 `isAuthenticated`, (中文(简体) ), `assertAuthenticated`, (中文(简体) ), `assertAdminMode`, (中文(简体) ), `getAccountRole`, (中文(简体) ), `assertAccountRole`, (中文(简体) ), `isValidAccountType`, (中文(简体) ), `assertValidAccountType` 帮手. |
| `@data-fair/lib-common-types/account/index.js` | `Account` (资源拥有者)和 `AccountKeys` 类型,验证符. |
| `@data-fair/lib-common-types/access-ref/index.js` | `AccessRef` 允许目标类型、验证符、, `matchAccessRef(session, accessRef)` 财务报告和审定财务报表 `mongoFilterAccessRef(session)`。 。 。 . |
| `@data-fair/lib-common-types/application/index.js` | `Application`, (中文(简体) ), `Dataset` 财务报告和审定财务报表 `Field` 类型,如数据公平应用程序所示. |
| `@data-fair/lib-common-types/event/index.js` | `Event` 类型(活动服务). |
| `@data-fair/lib-common-types/notification/index.js` | `Notification` 类型,验证符. |
| `@data-fair/lib-common-types/theme/index.js` | `Theme` 编号 : `Colors` 类型, `defaultTheme`, (中文(简体) ), `fillTheme`,颜色对比帮助器(`getReadableColor`, (中文(简体) ), `getOnColor`, (中文(简体) ), `getColorsWarnings`, (中文(简体) ), `getSiteColorsWarnings`(......) (中文(简体) ). |
| `@data-fair/lib-common-types/catalog/index.js` | 这个 `CatalogPlugin` 合同目录插件及其上下文类型. |
| `@data-fair/lib-common-types/processings.js` | 这个 `PrepareFunction`, (中文(简体) ), `RunFunction`, (中文(简体) ), `ProcessingContext` 财务报告和审定财务报表 `LogFunctions` 类型处理插件. |
| `@data-fair/lib-common-types/ws.js` | `Message` 类型. |
| `@data-fair/lib-common-types/scopes.js` | `defineScopes` (a) 服务范围词汇:每级接受范围、说明、全球范围), `globalScopes`, (中文(简体) ), `oauth2SecurityScheme`。 。 。 . |

## 使用量

### 会议

会话状态通常通过会话中间软件获得: `@data-fair/lib-express` 或者说 `useSession` 联 合 国 `@data-fair/lib-vue`;此包提供了其类型和检查。 见 [数据-公平会议技能](https://github.com/data-fair/lib/tree/main/skills/data-fair-session)。 。 。 .

```ts
import { type SessionState, assertAccountRole } from '@data-fair/lib-common-types/session/index.js'

// throws httpError(401) if not authenticated, httpError(403) if the active account does not have the role
assertAccountRole(sessionState, resource.owner, 'admin')
```

`getAccountRole(sessionState, account, { allAccounts?, acceptDepAsRoot? })` 返回角色而不是抛出( e)`'admin'` 在管理模式中,为了用户自己的账户, `null` (如果无).

### 参考共享计划

与 [`@data-fair/lib-types-builder`](https://www.npmjs.com/package/@data-fair/lib-types-builder) 能够 `$ref` 共同的计谋 `$id` (单位:千美元)`https://github.com/data-fair/lib/<name>`:

```js
owner: { $ref: 'https://github.com/data-fair/lib/account' },
topic: { $ref: 'https://github.com/data-fair/lib/event#/$defs/topicRef' }
```

### 插件

```ts
import type { PrepareFunction, RunFunction, ProcessingContext } from '@data-fair/lib-common-types/processings.js'
import type { CatalogPlugin } from '@data-fair/lib-common-types/catalog/index.js'
```

见 [数据处理技能](https://github.com/data-fair/lib/tree/main/skills/data-fair-processing)。 。 。 .

### 范围

一个服务宣布其范围家族一次;匹配 `session/index.js` (单位:千美元)`hasScope`准确的或赤裸的伞, 从来没有前缀)保持不变.

```ts
import { defineScopes, oauth2SecurityScheme, oauth2Alternatives } from '@data-fair/lib-common-types/scopes.js'

const scopes = defineScopes({
  notifications: {
    tiers: ['read', 'write'],
    descriptions: {
      umbrella: { fr: 'Tous les droits sur les notifications', en: 'All notification scopes' },
      read: { fr: 'Lire ses notifications', en: 'Read own notifications' },
      write: { fr: 'Gérer ses abonnements', en: 'Manage own subscriptions' }
    }
  }
})

// notifications:write notifications all:write all:admin
requireScope(scopes.acceptedScopes('notifications', 'write'))

// the oauth2 scheme of the service's OpenAPI document
oauth2SecurityScheme(scopes, { directoryUrl, locale: 'fr' })

// an operation's security: [{ sdCookie: [] }, { oauth2: ['notifications:write'] }, { oauth2: ['notifications'] }, ...]
const security = [{ sdCookie: [] }, ...oauth2Alternatives(scopes.acceptedScopes('notifications', 'write'))]
```

-   `acceptedScopes(family, tier)`: 家庭申报的级别在或以上 `tier`伞,然后 `all:<tier>` 和更高层次的全球范围。 家庭不申报投球.
-   `familyScopes(family)`:每个能达到家庭某层的瞄准镜, 对于一个粗糙的门.
-   `scopeDescriptions(locale)`:对每个申报范围的说明 `all:*` 包括这些.
-   `oauth2Alternatives(accepted)`:每个接受范围有一个OpenAPI安全选项. 单人 `{ oauth2: [a, b] }` 意味着一个象征 既需要。 真是个 `all:*` 范围补助金从 列出它的操作,数据公平平台文档依赖于此表单.
-   全球级范围及其描述在此拥有(`globalScopes`),每项服务都相同. `all` 作为姓氏保留.

## 常见问题

### @data-fair/lib-common-types 是什么？

共享计划,并在数据公平堆栈中构建类型定义\.

### 如何安装 @data-fair/lib-common-types？

在项目目录运行 npm install @data-fair/lib-common-types，或使用 pnpm add / yarn add / bun add。

### @data-fair/lib-common-types 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/data-fair\_\_lib-common-types 是否存在。

### @data-fair/lib-common-types 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @data-fair/lib-common-types 可以商用吗？

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

### @data-fair/lib-common-types 的下载量有多少？

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

### @data-fair/lib-common-types 还在维护吗？

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