# @gdp-ts/core 中文文档

规范地址：https://npmcn.com/package/%40gdp-ts/core/

版本：0\.1\.0
npm 元数据更新时间：2026-10-05T13:31:08.620Z
中文译文更新时间：2026-11-16T01:15:29.483Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gdp-ts/core
原文对照：https://npmcn.com/package/%40gdp-ts/core/?lang=original
项目主页：https://github.com/rauchg/gdp-ts#readme
源码仓库：https://github.com/rauchg/gdp-ts

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

- 包体积（解压后）：61.2 kB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：typescript \>=5\.4，eslint \>=9，oxlint \>=1\.86
- 首次发布：2026-10-05T13:31:07.684Z
- 最新版本发布：2026-10-05T13:31:08.275Z
- 近 30 天下载量：1792498（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）

## 中文简介

TypeScript的出走证明的"幽灵":授权(和其他检查),其结果类型检查者可以看到.

## 安装

```sh
npm install @gdp-ts/core
```

也可以使用：`pnpm add @gdp-ts/core`、`yarn add @gdp-ts/core`、`bun add @gdp-ts/core`

## README

![A pixel-art ghost carrying a TypeScript document with a green checkmark](https://npmcn.com/package/%40gdp-ts/core/.github/assets/logo.png)

# 常规

一个小 [库+线条](https://npmcn.com/package/%40gdp-ts/core/#readme-the-package) 财务报告和审定财务报表 [人工智能技能](https://skills.sh/rauchg/gdp-ts/gdp-ts) 执行情况 [离开的鬼魂](https://npmcn.com/package/%40gdp-ts/core/#readme-credits) 用于 TypeScript,一种在编译(类型检查)时使 API 合同更加安全的验证系统.

`gdp-ts` 制定一整套授权(_“ 此用户能否读取此资源 ”_)或应享权利(_此用户是否为此资源付费_ 通过在编译时捕捉到这些虫子,在可忽略不计的运行时间上,人类和编码代理非常难以引入.

## 特征

-   **可递增采用**:与任何TS代码库和任何运行时间一起工作,不会改变你如何做I/O或效果.
-   **易燃滑轮**:详尽证明的多少取决于每个代码库的斟酌/风险承受能力,以及 [技术](https://npmcn.com/package/%40gdp-ts/core/#readme-the-skill) 捆绑 [咨询](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/references/where-to-stop.md)。 。 。 .
-   **~零运行时间 :**: 没有额外的查询或依赖。 唯一的运行时间成本是很小的 包裹在你检查的身份证上 安全来自类型检查器.
-   **输入检查的成本**:每个经授权的呼叫站点在冷的TypeScript 7检查时大约0.3 ms. 成本随着使用频率的增长而增加,而不是随着代码库大小的提高([基准](https://npmcn.com/package/%40gdp-ts/core/bench/README.md)) (中文(简体) ).

## 安装

```bash
$ npx skills add rauchg/gdp-ts
$ pnpm add @gdp-ts/core
```

需要 TypeScript 5.4 或更新 .

## 问题

许多像这样的代码库特征代码:

```js
async function handler(req, res) {
  await assertProjectAdmin(req.user.id, req.params.projectId); // throws 403
  await setPasswordProtection(req.params.projectId, req.body.password); // nothing connects this to the line above
  res.sendStatus(204);
}
```

看上去不错,除了: 它只需要

-   开发者滑倒并错过第一个 `await`
-   关于谁可以"更改密码保护"以更改(例如,只有所有者)的业务规则,和一个继续运行旧支票的呼叫站点

...为了安全/商业灾难的发生.

## 解决办法

我们改变上面的签名 从什么 **任何人都可以从任何地方打电话**数字 :

```ts
function setPasswordProtection(projectId: ProjectId, password: string): Promise<void>;
```

...强迫打电话的人 **现有证据(证据)** 他们可以做,也可以做计划

```ts
function setPasswordProtection<U, P>(
  project: Named<P, ProjectId>,
  password: string,
  _proofs: { admin: UserIsProjectAdmin<U, P>; plan: PlanIncludesPasswordProtection<P> },
): Promise<void>;
```

技能要注意引导代理人和人类走向这种更安全的模式,并远离 _[布尔失明](https://existentialtype.wordpress.com/2011/03/15/boolean-blindness/)_ 问题.

## 如何运作

**1️⃣ 名称值.** `name(x, k)` 给一个运行时间值 一个只编译时间的名称 `N`。每次呼叫 `name` 创建不同的 `N`,以及 `N` 仅存在于召回中。 例如,单独命名的wwo项目代号现在可以被编译器区分,尽管两者都是 `string`数字 :

```ts
// app.ts
import { name } from "@gdp-ts/core";
import { disablePasswordProtection } from "@/data/projects";
import { ProjectId } from "@/lib/ids";
import { userIsProjectAdmin } from "@/proofs/user-is-project-admin";
import { app, authenticated, HttpError } from "@/lib/server"; // your Express app, auth middleware, error type

app.delete(
  "/projects/:id/password-protection",
  authenticated((viewer, req, res) => // authenticated() resolves the logged-in user
    name(viewer.id, ProjectId(req.params.id), async (user, project) => {
      const admin = await userIsProjectAdmin(user, project);
      if (!admin) throw new HttpError(403, "Only Owners and Members can change this");
      await disablePasswordProtection(project, admin);
      res.sendStatus(204);
    }),
  ),
);
```

**2 证明姓名的事实.** 一个小 _信任模块_ 检查并返回 a `Proof<"UserIsProjectAdmin", [U, P]>`,或 `null`只有那个模块才能铸造出证据 跑步时,证据是被冻结的 `{ kind }` 对象.

```ts
// proofs/user-is-project-admin.ts  (trusted: the only place that can mint this proof)
import { defineProof, type Named, type Proof } from "@gdp-ts/core";
import { db } from "@/lib/db";
import type { ProjectId, UserId } from "@/lib/ids";

const UserIsProjectAdmin = defineProof("UserIsProjectAdmin"); // not exported
export interface UserIsProjectAdmin<U, P> extends Proof<"UserIsProjectAdmin", [U, P]> {}

export async function userIsProjectAdmin<U, P>(
  user: Named<U, UserId>,
  project: Named<P, ProjectId>,
): Promise<UserIsProjectAdmin<U, P> | null> {
  const role = await db.roleInProjectTeam(user.value, project.value);
  return role === "owner" || role === "member" ? UserIsProjectAdmin.prove(user, project) : null;
}
```

**3 要求证明.** 敏感功能需要证明他们的确切论点。 用错误的证据召唤他们, 一个不同值的证据, 一个原始的ID, 或者没有证据是一个编译错误 QQ

```ts
// data/projects.ts  (sensitive: demands exact proofs)
import type { Named } from "@gdp-ts/core";
import { db } from "@/lib/db";
import type { ProjectId } from "@/lib/ids";
import type { UserIsProjectAdmin } from "@/proofs/user-is-project-admin";

export function disablePasswordProtection<U, P>(
  project: Named<P, ProjectId>,
  _proof: UserIsProjectAdmin<U, P>,
): Promise<void> {
  return db.writePasswordProtection(project.value, null);
}
```

TL; 大卫:

-   中间软件只认证。 检查发生在路由体, 就在需要结果的地方 `disablePasswordProtection` 没有它就不会编译.
-   因为数据层 _需求_ 一个证明,而不是执行检查,可以安全地导出:一个路由,一个服务器动作或者一个工作可以调用它,而他们都无法跳过检查.
-   **证据是 _幽灵_**: 他们在运行时无所事事, 在编译时无所事事 时间. [我们靠林克](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/references/recipe.md#6-turn-on-the-lint-preset) 防止"取食"(例如: `{} as UserIsProjectAdmin<U, P>`) (中文(简体) ).

## 包裹

[`@gdp-ts/core`](https://www.npmjs.com/package/@gdp-ts/core) 在npm舰上两件事:

-   **图书馆** (单位:千美元)`@gdp-ts/core`: `name()`, (中文(简体) ), `defineProof()`, (中文(简体) ), `Named` 财务报告和审定财务报表 `Proof`,没有依赖关系.
-   **电线** (单位:千美元)`@gdp-ts/core/lint/eslint`, (中文(简体) ), `@gdp-ts/core/lint/oxlint`:用于ESLint和Oxlint的预设,可以捕捉类型检查器无法捕捉的东西,例如用 `as` 或在外边铸造 `proofs/` (单位:千美元)[设置](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/references/recipe.md#6-turn-on-the-lint-preset)) (中文(简体) ).

## 技术

`npx skills add rauchg/gdp-ts` 安装指导编码代理的技能 通过应用代码库中的模式。 这是普通的马克下,所以它 作为人类参考手册的双倍:

-   [**工作流程**](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/SKILL.md#workflow): 增加或更改授权时应遵循的清单.
-   [**食谱**](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/references/recipe.md):从有品牌的标识到出出彩规则,分六步走.
    1.  [标出身份](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/references/recipe.md#1-brand-your-ids)
    2.  [每个事实一个信任的模块, in `proofs/`](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/references/recipe.md#2-one-trusted-module-per-fact-in-proofs)
    3.  [政策是工会](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/references/recipe.md#3-policies-are-unions)
    4.  [敏感函数需要证明](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/references/recipe.md#4-sensitive-functions-demand-proofs)
    5.  [处理器中的名称和证明](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/references/recipe.md#5-name-and-prove-in-the-handler-turn-null-into-a-response)
    6.  [打开预设线](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/references/recipe.md#6-turn-on-the-lint-preset)
-   [**模式**](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/references/patterns.md):免费削弱,带出证据的证明,再用证明,与授权无关的事实.
-   [**读取错误**](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/references/errors.md):编译器捕获到什么,以及每个消息的含义.
-   [**这不能保证**](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/references/limits.md): 伪造的证明, stale 证明,以及TypeScript的其他限制.
-   [**在哪里停下来**](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/references/where-to-stop.md):"易"作"易"作"易"作"易"作"易"作".
-   [**API 密码**](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/SKILL.md#api): 万事俱备 `gdp-ts` 出口.

## 实例

三个都使用同一个域名, 以Vercel的域名为模式 [密码保护](https://vercel.com/docs/deployment-protection/methods-to-protect-deployments/password-protection):团队管理员在一个项目上设置了密码,访客必须输入它才能打开项目受保护的URL.

-   [**`basic`**](https://npmcn.com/package/%40gdp-ts/core/examples/basic)从这里开始。 没有框架和内存数据,既涵盖团队一方(可能看到并改变设置),也涵盖访客一方(密码和信使),被印成情景. 包括 `mistakes.ts`,一个汇编错误的文件 测试套件保持诚实.
-   [**`express-basic`**](https://npmcn.com/package/%40gdp-ts/core/examples/express-basic):球队侧过HTTP并有快车5号. 只认证的中端软件,命名和证明的路由,以及阻止被伪造的gdp-ts ESLint预设.
-   [**`express-drizzle`**](https://npmcn.com/package/%40gdp-ts/core/examples/express-drizzle):在Postgres(PGlite)的进程中与Drizzle并列的两侧. 由 SQL 支持的证明加入,一个需要证明的数据层, cookie 范围到一个 URL, HTTP 测试, Oxlint 预设在 TypeScript 7上.

## 与其他解决办法的关系

-   **政策引擎** (CASL、Oso、Cerbos、许可证、OpenFGA、桑给巴尔式服务): _决定_ 是否一个主题可以对资源采取行动. `gdp-ts` 而不是:它确保决定到达取决于它的函数,关于正确的值。 你可以同时使用:在证明函数内调用引擎并返回证明. 见 [`examples/express-drizzle`](https://npmcn.com/package/%40gdp-ts/core/examples/express-drizzle) 对于"在证明功能之外" 与平原SQL的相像.
-   **品牌/名义类型** (单位:千美元)`ts-brand`效果 `Brand`,手工滚动 `string & { __brand }`:一个品牌说什么 _类型_ 价值的东西是。 A 类 `name()` 帮助我们陈述 _哪个_ 它的价值是。 标识使用品牌( U)[食谱步骤1](https://npmcn.com/package/%40gdp-ts/core/skills/gdp-ts/references/recipe.md#1-brand-your-ids))并取名于上.
-   **验证库** (Zod, valibot, ArkType):他们证明了事实: _形状_ 在边缘的数据. `gdp-ts` 证明事实 _关系_ 在特定值之间(这个符号,这个 URL),这是没有计划可以知道的.
-   **哈斯凯尔 `gdp`**, (中文(简体) ), **锈 `departed` 编号 : `mononym` 编号 : `gdp_rs`**:在语言中具有更强类型保证的同一种思想. `gdp-ts` 切实落实这些想法.

## 以前的艺术和信用

-   马特·努南, [`justified-containers`](https://hackage.haskell.org/package/justified-containers) (2017) (中文(简体) )
-   马特·努南, [离开的鬼魂](https://kataskeue.com/gdp.pdf) 财务报告和审定财务报表 [`gdp`](https://hackage.haskell.org/package/gdp) (2018) (中文(简体) )
-   奥利·查尔斯, [谁授权这些幽灵?](https://blog.ocharles.org.uk/posts/2019-08-09-who-authorized-these-ghosts.html) (2019年)是这个项目的一大灵感.
-   与Malte Ubl商谈我们大型的TypeScript monorepo的缩放安全,与数百名活跃的工程师+他们的代理商.

## 许可证

麻省理工学院

## 常见问题

### @gdp-ts/core 是什么？

TypeScript的出走证明的"幽灵":授权\(和其他检查\),其结果类型检查者可以看到\.

### 如何安装 @gdp-ts/core？

在项目目录运行 npm install @gdp-ts/core，或使用 pnpm add / yarn add / bun add。

### @gdp-ts/core 支持 TypeScript 吗？

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

### @gdp-ts/core 支持 ESM 还是 CommonJS？

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

### @gdp-ts/core 可以商用吗？

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

### @gdp-ts/core 的下载量有多少？

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

### @gdp-ts/core 还在维护吗？

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

