@artzok/zp_lib 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +76 -0
  2. package/package.json +1 -1
package/README.md ADDED
@@ -0,0 +1,76 @@
1
+ # @artzok/zp_lib
2
+
3
+ TypeSpec 装饰器库。业务项目通过包名导入,使用 `ZpLib` 命名空间给 API 模型、操作和枚举添加 OpenAPI 元数据。
4
+
5
+ ## 在 TypeSpec 项目中使用
6
+
7
+ 从 npm 安装已发布的版本。项目中的 `@typespec/compiler` 和 `@typespec/openapi` 需满足本库 `peerDependencies` 声明的范围(当前均为 `^1.17.0`)。
8
+
9
+ ```sh
10
+ npm install @artzok/zp_lib
11
+ ```
12
+
13
+ 在消费项目的 `main.tsp` 中按包名导入:
14
+
15
+ ```typespec
16
+ import "@artzok/zp_lib";
17
+
18
+ using ZpLib;
19
+
20
+ @clientAvailable("自定义 App", "1.2.0")
21
+ model User {
22
+ id: string;
23
+ }
24
+
25
+ @namedEnum
26
+ enum Status {
27
+ Active: "active",
28
+ Disabled: "disabled",
29
+ }
30
+ ```
31
+
32
+ 运行 `npx tsp compile . --no-emit` 验证导入。生成 OpenAPI 文档时,使用消费项目自身的 OpenAPI emitter 配置。
33
+
34
+ | 装饰器 | 适用目标 | 行为 |
35
+ | --- | --- | --- |
36
+ | `@clientAvailable(application, version)` | 操作、模型、模型属性 | 将应用名和最低可用版本写入 `x-client-available`。应用名接受任意字符串,版本须为非空且不含空白的字符串。同一目标可声明多个应用,每个应用只能声明一次。 |
37
+ | `@namedEnum` | 枚举 | 将成员名设为成员的 summary,并写入 `x-enum-varnames`,例如 `[{"active":"Active","disabled":"Disabled"}]`。多个成员使用相同值时,映射保留第一个成员名。 |
38
+
39
+ ## 本地开发与编译
40
+
41
+ 在仓库根目录运行:
42
+
43
+ ```sh
44
+ npm ci
45
+ npm run build
46
+ ```
47
+
48
+ `src/main.tsp` 是公共入口。`src/*.tsp` 定义装饰器签名并导入同目录的 JavaScript 实现。新增装饰器时,在 `src/main.tsp` 中导入其声明文件,并保持声明和实现的命名空间一致。
49
+
50
+ `npm run build` 调用 `build:tsp`,用 TypeSpec 编译器和库检查规则检查入口,将警告视为错误。`--no-emit` 表示只做验证。npm 包通过 `package.json` 的 `files` 字段直接收录 `src/`,构建和发布都无需生成 `dist/`。
51
+
52
+ VS Code 通过 `tsconfig.json` 的 `allowJs: true` 将 `src/` 中的 JS 纳入项目,`noEmit: true` 关闭 TypeScript 输出。若看到“找不到任何输入”,先检查 `include` 是否覆盖 `src/`,以及 `allowJs` 是否开启。`npm run watch` 运行的是 `tsc --watch`;修改 `.tsp` 后用 `npm run build` 验证。
53
+
54
+ ## 打包并验证下游导入
55
+
56
+ 1. 在库根目录运行 `npm run build` 和 `npm pack --dry-run`。检查清单里包含 `src/main.tsp`、两个装饰器的 `.tsp` 和配套的 `.js` 文件。
57
+ 2. 运行 `npm pack` 生成本地压缩包。文件名以命令输出为准,例如版本 `0.1.1` 对应 `artzok-zp_lib-0.1.1.tgz`。
58
+ 3. 在独立的 TypeSpec 项目中执行 `npm install /实际路径/artzok-zp_lib-0.1.1.tgz`,使用上面的 `main.tsp` 示例运行 `npx tsp compile . --no-emit`。这一步验证的是下游实际安装的文件和包入口。
59
+
60
+ ## 发布到官方 npm
61
+
62
+ 发布目标为 `https://registry.npmjs.org/`。使用对 `@artzok` 作用域有发布权限的账号,并为本机交互发布启用双重验证(2FA)。
63
+
64
+ 1. 确认 `package.json` 的 `version` 是本次要发布的新版本。npm 上已使用过的包名与版本组合不能重复发布。如需提升补丁版本,可以运行 `npm version patch --no-git-tag-version`,同步更新包配置和锁文件。
65
+ 2. 按上一节检查并验证该版本的压缩包。
66
+ 3. 在库根目录登录、核对账号,再公开发布:
67
+
68
+ ```sh
69
+ npm login --auth-type=web --registry=https://registry.npmjs.org/
70
+ npm whoami --registry=https://registry.npmjs.org/
71
+ npm publish --access public
72
+ ```
73
+
74
+ 4. 按提示完成身份验证。发布后执行 `npm view @artzok/zp_lib version --registry=https://registry.npmjs.org/`,确认默认标签指向本次发布的版本。
75
+
76
+ 如果收到 `Two-factor authentication or granular access token with bypass 2fa enabled is required`,本机发布时检查当前账号的 2FA 设置并重新登录。如果在 CI 中使用 token 发布,需使用有目标包写入权限、且在创建时启用 **Bypass two-factor authentication** 的 granular access token。将 token 存入 CI 的 secret 管理,不要提交到仓库。详见 [npm 发布身份验证说明](https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification/)。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@artzok/zp_lib",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "type": "module",
5
5
  "tspMain": "src/main.tsp",
6
6
  "exports": {