# @beesolve/iam-policy-ts 中文文档

规范地址：https://npmcn.com/package/%40beesolve/iam-policy-ts/

版本：26\.11\.7
npm 元数据更新时间：2026-11-07T07:57:57.200Z
中文译文更新时间：2026-11-07T20:47:06.849Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：2.8 MB，930 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：1 个
- 首次发布：2026-05-12T17:10:53.141Z
- 最新版本发布：2026-11-07T07:57:56.875Z
- 近 30 天下载量：2890（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：115（近 12 个月 115 个）

## 中文简介

自动生成 AWS 动作目录的 类型安全 IAM 策略助手

## 安装

```sh
npm install @beesolve/iam-policy-ts
```

也可以使用：`pnpm add @beesolve/iam-policy-ts`、`yarn add @beesolve/iam-policy-ts`、`bun add @beesolve/iam-policy-ts`

## README

# @bessolve/iam-policy-ts (英语)

有自动生成的AWS动作目录的可树可摇动,类型安全的IAM政策助手.

每个~450 AWS服务都生活在自己的模块中. 仅导入您使用的东西 —— 您的捆绑者放下其余的 。 在 TypeScript 中写入内置策略时, 全部自动完成 AWS IAM 动作 .

## 安装

```bash
npm install @beesolve/iam-policy-ts
```

## 使用量

### IAM 行动助手

每个 AWS 服务作为独立函数导出,具有全类型安全并自动完成:

```typescript
import { s3, ec2, organizations } from "@beesolve/iam-policy-ts";

s3("GetObject");              // "s3:GetObject"
ec2("RunInstances");          // "ec2:RunInstances"
organizations("ListAccounts"); // "organizations:ListAccounts"
s3("*");                      // "s3:*"
```

连字符服务前缀使用骆驼Case函数名 :

```typescript
import { accessAnalyzer, ssoDirectory } from "@beesolve/iam-policy-ts";

accessAnalyzer("ListAnalyzers");  // "access-analyzer:ListAnalyzers"
ssoDirectory("SearchUsers");      // "sso-directory:SearchUsers"
```

### 命名空间导入

如果您喜欢单一的命名空间( 类似于旧的) `iam` 对象,您可以使用命名空间导入 :

```typescript
import * as iam from "@beesolve/iam-policy-ts";

iam.s3("GetObject");              // "s3:GetObject"
iam.accessAnalyzer("ListAnalyzers"); // "access-analyzer:ListAnalyzers"
```

在现代捆绑机(建造、滚出、Vite、Webpack5)中,树摇可以输入命名空间。 他们静态地分析你访问命名空间的属性,然后放下其余的属性. 此模式与 [维利博特](https://valibot.dev/guides/installation/) (单位:千美元)`import * as v from 'valibot'`) (中文(简体) ).

### 子路径导入( Tree- Shaking)

对于最佳捆绑大小,仅通过子路径导出导入所需的服务 :

```typescript
// Import only what you need — optimal for tree-shaking
import { s3 } from "@beesolve/iam-policy-ts/s3";
import { accessAnalyzer } from "@beesolve/iam-policy-ts/access-analyzer";

s3("GetObject");                  // "s3:GetObject"
accessAnalyzer("ListAnalyzers");  // "access-analyzer:ListAnalyzers"
```

每个服务都有自己的子路径,匹配AWS服务前缀(保留了连字符).

### 政策验证

有两个验证模式:

**允许( 默认)** ——仅验证结构形状(字段类型,允许键). 匹配 AWS 在 JSON 级别上接受的,而不执行诸如 Action/ Not Action 专属等语法规则 .

```typescript
import {
  isIamPolicyDocument,
  assertIamPolicyDocument,
  iamPolicyDocumentSchema,
} from "@beesolve/iam-policy-ts";

// Type guard
if (isIamPolicyDocument(unknownValue)) {
  // unknownValue is typed as IamPolicyDocument
}

// Assertion (throws on invalid input)
const policy = assertIamPolicyDocument(jsonInput);
```

**严格** 此外,还执行IAM语法规则:

-   一定有一个 `Action` 或者说 `NotAction`
-   无法同时拥有 `Resource` 财务报告和审定财务报表 `NotResource`

```typescript
import {
  isIamPolicyDocumentStrict,
  assertIamPolicyDocumentStrict,
  iamPolicyDocumentStrictSchema,
} from "@beesolve/iam-policy-ts";

// Rejects policies with both Action and NotAction, etc.
if (isIamPolicyDocumentStrict(unknownValue)) {
  // Passes strict grammar checks
}
```

### 作为类型脚本的渲染策略

```typescript
import { policyToTypescript } from "@beesolve/iam-policy-ts";

const ts = policyToTypescript({
  Version: "2012-10-17",
  Statement: [{
    Effect: "Allow",
    Action: ["s3:GetObject", "s3:ListBucket"],
    Resource: "*",
  }],
});

// Output uses per-service functions for known actions:
// {
//   Version: "2012-10-17",
//   Statement: [
//     {
//       Effect: "Allow",
//       Action: [
//         s3("GetObject"),
//         s3("ListBucket")
//       ],
//       Resource: "*"
//     }
//   ]
// }
```

### 访问原始目录

完整的动作目录可以从主条目或通过专用的子路径获取:

```typescript
// From main entry
import {
  iamActionCatalog,
  iamActionCatalogSourceSha256,
  iamActionCatalogActionCount,
} from "@beesolve/iam-policy-ts";

// Or via dedicated subpath (avoids pulling in all service functions)
import {
  iamActionCatalog,
  iamActionCatalogSourceSha256,
  iamActionCatalogActionCount,
} from "@beesolve/iam-policy-ts/_meta";

// iamActionCatalog is a typed const object:
// { s3: ["AbortMultipartUpload", ...], kms: ["CancelKeyDeletion", ...], ... }

console.log(`${iamActionCatalogActionCount} actions across ${Object.keys(iamActionCatalog).length} services`);
```

## 迁移指南(出自v25/v26)

此版本引入了突破性更改: 单体 `iam` 帮助对象和 `iamAction()` 函数已被删除,从而有利于允许树摇动的每个服务函数导入.

### 删除了导出

| 删除导出 | 替换 |
| --- | --- |
| `iam` (运行时对象) | 服务职能(例如, `s3`, (中文(简体) ), `ec2`, (中文(简体) ), `accessAnalyzer`(中文(简体) ) |
| `iamAction(prefix, action)` | 服务职能(例如, `s3("GetObject")`(中文(简体) ) |
| `IamHelperObject` (类型) | 删除——不需要替换 |

### 移徙实例

**在此之前:**

```typescript
import { iam, iamAction } from "@beesolve/iam-policy-ts";

iam.s3("GetObject");                        // "s3:GetObject"
iam["access-analyzer"]("ListAnalyzers");    // "access-analyzer:ListAnalyzers"
iamAction("s3", "GetObject");               // "s3:GetObject"
```

**之后:**

```typescript
import { s3, accessAnalyzer } from "@beesolve/iam-policy-ts";

s3("GetObject");                  // "s3:GetObject"
accessAnalyzer("ListAnalyzers");  // "access-analyzer:ListAnalyzers"
```

### 快速引用

| 旧模式 | 新图案 |
| --- | --- |
| `iam.s3("GetObject")` | `s3("GetObject")` |
| `iam.ec2("RunInstances")` | `ec2("RunInstances")` |
| `iam["access-analyzer"]("ListAnalyzers")` | `accessAnalyzer("ListAnalyzers")` |
| `iam["acm-pca"]("IssueCertificate")` | `acmPca("IssueCertificate")` |
| `iamAction("s3", "GetObject")` | `s3("GetObject")` |

### 渲染输出更改

这个 `policyToTypescript` 函数现在发出每个服务功能的调用,而不是 `iam.*` 属性访问 :

| 在此之前 | 之后 |
| --- | --- |
| `iam.s3("GetObject")` | `s3("GetObject")` |
| `iam["access-analyzer"]("ListAnalyzers")` | `accessAnalyzer("ListAnalyzers")` |

## 更新目录

该目录由每日2:00 UTC运行的GitHub Action工作流程自动更新. 它从 AWS 获取最新的 IAM 动作数据,如果检测到变化,则承诺更新并发布新版本到 npm.

您也可以运行 `npm run generate` 本地生成目录 `src/catalog/`。 。 。 .

资料来源: [https://awspolicygen.s3.amazonaws.com/js/politics.js 页面存档备份,存于互联网档案馆](https://awspolicygen.s3.amazonaws.com/js/policies.js)

## 版本

此软件包使用基于日期的版本 `YY.M.D` 格式(例如, `25.7.14`) (中文(简体) ). 只有在上游AWS IAM动作目录发生变化时,才自动发布新版本. 该版本反映了协调世界时该目录被捕获的日期.

## 类型

所有IAM政策类型都导出:

-   `IamPolicyDocument` 编号 : `IamPolicyDocumentStrict`
-   `IamPolicyStatement` 编号 : `IamPolicyStatementStrict`
-   `IamPolicyPrincipal`
-   `IamPolicyPrincipalMap`
-   `IamPolicyConditionBlock`
-   `IamPolicyStringList`
-   `IamPolicyScalar`
-   `IamPolicyScalarList`
-   `IamPolicyVersion`

也提供每类服务:

-   `S3Action`, (中文(简体) ), `Ec2Action`, (中文(简体) ), `AccessAnalyzerAction`——每个服务机构有效行动的工会类型
-   `s3Actions`, (中文(简体) ), `ec2Actions`, (中文(简体) ), `accessAnalyzerActions`等——一连串动作名

## 财务问题

### 这是否证实在AWS中确实存在IAM动作?

没有。 计划验证( A)`isIamPolicyDocument`, (中文(简体) ), `assertIamPolicyDocument`等)只检查结构形状——正确字段类型,允许键,非空字符串. 它无法证实动作字符串像 `"s3:GetObject"` 对应于真实的 AWS 动作。 每个服务功能从目录中提供编译时间自动完成,但计划层被有意与它脱钩.

### 宽容与严格验证有何区别??

允许(默认)验证JSON结构:正确类型,无未知密钥,非空值. 它反映了AWS在API级别上接受的内容.

严格额外执行IAM语法规则:一个语句必须完全具有其中之一 `Action` 或者说 `NotAction`,而且不能两者兼有 `Resource` 财务报告和审定财务报表 `NotResource`。在部署前要抓住逻辑错误时,请使用严格模式.

### 我能用通配符动作吗 `s3:*`? 吗?

对 每项服务职能接受 `"*"` 作为有效动作名称 :

```ts
s3("*")  // "s3:*"
```

方案层还接受任何非空字符串 `Action`编号 :`NotAction`,所以通配符喜欢 `"s3:Get*"` 通过验证.

### 动作目录多久更新一次??

每日GitHub Action工作流程于协调世界时02:00运行. 它从中获取最新数据 [AWS 政策生成器](https://awspolicygen.s3.amazonaws.com/js/policies.js),如果目录已更改,则将更新并发布新版本为npm。 无所变化时不创建放行.

### 动作目录的来源是什么??

该目录来源于 `https://awspolicygen.s3.amazonaws.com/js/policies.js` 与AWS政策生成器控制台相同的源头. 源文件的SHA-256散列记录在 `iamActionCatalogSourceSha256` 为可复制.

### 此软件包是否在运行时进行网络调用 ?

没有。 该目录在构建时生成并被作为静态TypeScript const对象发运. 有零运行时间网络呼叫.

### 这是否与 CDK / Pulumi / SST / Terraform CDK 有关?

对 帮助者产生平庸的字符串( E)`"s3:GetObject"`)和计数函数接受/返回平原对象。 它们在您构建的 IAM 策略 JSON 在 TypeScript — CDK 内置策略, Pulumi 政策文件, SST 权限, 或 Terraform CDK 构造中整合 .

### 支持什么节点.js和TypeScript版本?

节点.js 24+和 TypeScript 6+. 一揽子措施仅限无害环境管理(`"type": "module"`) (中文(简体) ).

### 树能摇动吗?

对 每个AWS服务都在自己的模块(~450文件)中. 软件包声明 `"sideEffects": false` 并提供每条服务的子路径出口.

**职业:**

-   导入 2 - 3 服务, 您的捆绑只包含这些 —— 而不是完整的 ~ 18K 动作目录
-   Subpath的进口给捆绑者提供了尽可能最强的信号(不需要进行管子分析)
-   与Esbuild、Rollup、Webpack、Vite以及任何支持的捆绑商合作 `package.json` `"exports"`
-   零运行时间高程 — 每个服务功能是返回模板文字的一行

**条件/限制:**

-   包中的~450个源文件(在磁盘上安装更大的尺寸,尽管npm压缩效果良好)
-   TypeScript 语言服务器可能因文件计数而较慢于第一个打开的索引
-   枪管导入( E)`import { s3 } from "@beesolve/iam-policy-ts"`)再出口所有服务——刷树取决于您捆绑者是否有能力再出口未使用的产品

**当摇倒树木时:**

-   esbuild, Rollup, Vite——这些手提筒再出口和命名空间的进口情况良好;它们甚至会减少未使用的服务 `import * as iam`
-   `import * as iam from "@beesolve/iam-policy-ts"` 现代捆绑商静态地分析财产进入(`iam.s3`, (中文(简体) ), `iam.ec2`)并仅包括
-   亚次路径进口( 4)`@beesolve/iam-policy-ts/s3`——保证与任何捆绑机合作,因为只有一个模块被装入
-   任何环境 `"sideEffects": false` 受到尊重

**当摇树可能不起作用时:**

-   没有捆绑器的节点(Node.js)——所有模块都可以使用,但运行时没有去除死码(因为这是一个 dev-time/building-time的担心)
-   更古老的网络包装版本( < 5),加上桶口进口——可能拉入整个桶口. 使用子路径导入来做工作 .
-   如果您导入 `iamActionCatalog` 从主条目中——包含完整的目录对象(~18K动作). 使用 `@beesolve/iam-policy-ts/_meta` 来隔离它.
-   动态访问模式 `const fn = services[prefix]` 失败静态分析——坚持命名的进口或静态 `iam.s3(...)` 财产访问
-   将命名空间物体绕行(`doSomething(iam)`)——捆绑者无法追踪被调用者内部访问哪些属性

对于最大树摇动,使用子路径导入:

```ts
import { s3 } from "@beesolve/iam-policy-ts/s3";
```

### 如何重新生成本地目录?

```bash
npm run generate
```

这个运行 `scripts/generate-catalog.ts`,获取最新的 AWS 源,并生成每个服务文件 `src/catalog/`。 。 。 .

### 我应该使用主入口还是子通道进口?

这取决于你的设置:

| 假设 | 建议 |
| --- | --- |
| 重建/ Vite/ 滚动 | 主入口是好的——这些树摇筒再出口 |
| 网页包装 5 | 主入口通常有用,但亚道比较安全 |
| 网页包 4 或 4 以上 | 使用子路径导入 |
| 节点.js( 无捆绑) | 无所谓了,没有去除死法 |
| Lambda/ 边缘函数( 大小敏感) | 用于保证最小尺寸的子路径进口 |

如果怀疑,次路径进口总是最安全的选择。 他们完全绕过枪管分析.

## 许可证

麻省理工学院

## 常见问题

### @beesolve/iam-policy-ts 是什么？

自动生成 AWS 动作目录的 类型安全 IAM 策略助手

### 如何安装 @beesolve/iam-policy-ts？

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

### @beesolve/iam-policy-ts 支持 TypeScript 吗？

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

### @beesolve/iam-policy-ts 支持 ESM 还是 CommonJS？

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

### @beesolve/iam-policy-ts 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @beesolve/iam-policy-ts 可以商用吗？

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

### @beesolve/iam-policy-ts 的下载量有多少？

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

### @beesolve/iam-policy-ts 还在维护吗？

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