@artzok/zp_lib 0.0.0-stage → 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.
- package/README.md +75 -2
- package/package.json +39 -4
- package/src/client-available.js +79 -0
- package/src/client-available.tsp +18 -0
- package/src/main.tsp +2 -0
- package/src/named-enum.js +22 -0
- package/src/named-enum.tsp +13 -0
package/README.md
CHANGED
|
@@ -1,3 +1,76 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @artzok/zp_lib
|
|
2
2
|
|
|
3
|
-
|
|
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,41 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@artzok/zp_lib",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"tspMain": "src/main.tsp",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": {
|
|
8
|
+
"typespec": "./src/main.tsp"
|
|
9
|
+
}
|
|
10
|
+
},
|
|
11
|
+
"peerDependencies": {
|
|
12
|
+
"@typespec/compiler": "^1.17.0",
|
|
13
|
+
"@typespec/openapi": "^1.17.0"
|
|
14
|
+
},
|
|
15
|
+
"devDependencies": {
|
|
16
|
+
"@types/node": "latest",
|
|
17
|
+
"typescript-eslint": "^8.49.0",
|
|
18
|
+
"@typespec/compiler": "^1.17.0",
|
|
19
|
+
"@typespec/openapi": "^1.17.0",
|
|
20
|
+
"@typespec/library-linter": "latest",
|
|
21
|
+
"eslint": "^9.15.0",
|
|
22
|
+
"prettier": "^3.3.3",
|
|
23
|
+
"typescript": "^5.3.3"
|
|
24
|
+
},
|
|
25
|
+
"scripts": {
|
|
26
|
+
"build": "npm run build:tsp",
|
|
27
|
+
"watch": "tsc --watch",
|
|
28
|
+
"build:tsp": "tsp compile . --warn-as-error --import @typespec/library-linter --no-emit",
|
|
29
|
+
"lint": "eslint src/ test/ --report-unused-disable-directives --max-warnings=0",
|
|
30
|
+
"lint:fix": "eslint . --report-unused-disable-directives --fix",
|
|
31
|
+
"format": "prettier . --write",
|
|
32
|
+
"format:check": "prettier --check ."
|
|
33
|
+
},
|
|
34
|
+
"packageManager": "npm@12.2.3+sha512.a2f98d4517bbe89bdca7513a88e78f43a1fd66be1730eaea81f69e18d86d46f3f75d29762e8fdaf42d4de7f8d194b2ebb2a09e9bfa268067591e96796baca7d5",
|
|
35
|
+
"files": [
|
|
36
|
+
"src"
|
|
37
|
+
],
|
|
38
|
+
"publishConfig": {
|
|
39
|
+
"registry": "https://registry.npmjs.org/"
|
|
40
|
+
}
|
|
41
|
+
}
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import { createTypeSpecLibrary, paramMessage } from "@typespec/compiler";
|
|
2
|
+
import { getExtensions, setExtension } from "@typespec/openapi";
|
|
3
|
+
|
|
4
|
+
export const namespace = "ZpLib";
|
|
5
|
+
|
|
6
|
+
export const $lib = createTypeSpecLibrary({
|
|
7
|
+
name: "sawa-client-available",
|
|
8
|
+
diagnostics: {
|
|
9
|
+
"invalid-version": {
|
|
10
|
+
severity: "error",
|
|
11
|
+
messages: { default: "客户端版本必须是非空且不包含空白的字符串。" },
|
|
12
|
+
},
|
|
13
|
+
"duplicate-application": {
|
|
14
|
+
severity: "error",
|
|
15
|
+
messages: {
|
|
16
|
+
default: paramMessage`同一目标不能重复声明应用 ${"application"} 的可用版本。`,
|
|
17
|
+
},
|
|
18
|
+
},
|
|
19
|
+
},
|
|
20
|
+
state: {
|
|
21
|
+
availability: { description: "各目标的客户端最低可用版本。" },
|
|
22
|
+
},
|
|
23
|
+
});
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* @param {import('@typespec/compiler').Program} program
|
|
27
|
+
* @param {import('@typespec/compiler').Type} target
|
|
28
|
+
* @returns {Readonly<Partial<Record<string, string>>> | undefined}
|
|
29
|
+
*/
|
|
30
|
+
export function getClientAvailability(program, target) {
|
|
31
|
+
return program.stateMap($lib.stateKeys.availability).get(target);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** Add visible Redoc badges after all decorators (including @extension) run.
|
|
35
|
+
* @param {import('@typespec/compiler').Program} program
|
|
36
|
+
*/
|
|
37
|
+
// 用来在文档中生成标记
|
|
38
|
+
// export function $onValidate(program) {
|
|
39
|
+
// for (const [target, availability] of program.stateMap($lib.stateKeys.availability)) {
|
|
40
|
+
// const existingBadges = getExtensions(program, target).get("x-badges") ?? [];
|
|
41
|
+
// const badges = Object.entries(availability).map(([application, version]) => ({
|
|
42
|
+
// name: `${application} ≥ ${version}`,
|
|
43
|
+
// color: application.startsWith("iOS") ? "blue" : "green",
|
|
44
|
+
// position: "after",
|
|
45
|
+
// }));
|
|
46
|
+
// setExtension(program, target, "x-badges", [...existingBadges, ...badges]);
|
|
47
|
+
// }
|
|
48
|
+
// }
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* @param {import('@typespec/compiler').DecoratorContext} context
|
|
52
|
+
* @param {import('@typespec/compiler').Operation | import('@typespec/compiler').Model | import('@typespec/compiler').ModelProperty} target
|
|
53
|
+
* @param {string} application
|
|
54
|
+
* @param {string} version
|
|
55
|
+
*/
|
|
56
|
+
export function $clientAvailable(context, target, application, version) {
|
|
57
|
+
if (version.length === 0 || /\s/u.test(version)) {
|
|
58
|
+
$lib.reportDiagnostic(context.program, {
|
|
59
|
+
code: "invalid-version", target: context.getArgumentTarget(1),
|
|
60
|
+
});
|
|
61
|
+
return;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
const current = getClientAvailability(context.program, target) ?? {};
|
|
65
|
+
if (Object.hasOwn(current, application)) {
|
|
66
|
+
$lib.reportDiagnostic(context.program, {
|
|
67
|
+
code: "duplicate-application", target: context.decoratorTarget,
|
|
68
|
+
format: { application },
|
|
69
|
+
});
|
|
70
|
+
return;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
// Decorators execute in reverse source order. Sort keys for stable output.
|
|
74
|
+
const availability = Object.freeze(Object.fromEntries(
|
|
75
|
+
Object.entries({ ...current, [application]: version }).sort(([a], [b]) => a.localeCompare(b)),
|
|
76
|
+
));
|
|
77
|
+
context.program.stateMap($lib.stateKeys.availability).set(target, availability);
|
|
78
|
+
setExtension(context.program, target, "x-client-available", availability);
|
|
79
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import "@typespec/openapi";
|
|
2
|
+
import "./client-available.js";
|
|
3
|
+
|
|
4
|
+
using TypeSpec.Reflection;
|
|
5
|
+
|
|
6
|
+
namespace ZpLib {
|
|
7
|
+
/**
|
|
8
|
+
* 记录 operation、模型或字段从哪个客户端版本开始可用。
|
|
9
|
+
* 可重复标注不同应用,同一目标上的应用不能重复;生成 x-client-available 和文档可见的版本徽章。
|
|
10
|
+
* @param application 客户端应用标识,可以是任意字符串。
|
|
11
|
+
* @param version 该目标首次可用的客户端版本。
|
|
12
|
+
*/
|
|
13
|
+
extern dec clientAvailable(
|
|
14
|
+
target: Operation | Model | ModelProperty,
|
|
15
|
+
application: valueof string,
|
|
16
|
+
version: valueof string
|
|
17
|
+
);
|
|
18
|
+
}
|
package/src/main.tsp
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { $summary } from "@typespec/compiler";
|
|
2
|
+
import { setExtension } from "@typespec/openapi";
|
|
3
|
+
|
|
4
|
+
export const namespace = "ZpLib";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* @param {import('@typespec/compiler').DecoratorContext} context
|
|
8
|
+
* @param {import('@typespec/compiler').Enum} target
|
|
9
|
+
*/
|
|
10
|
+
export function $namedEnum(context, target) {
|
|
11
|
+
// The OpenAPI emitter removes duplicate values while preserving source order.
|
|
12
|
+
const namesByValue = new Map();
|
|
13
|
+
for (const member of target.members.values()) {
|
|
14
|
+
const value = member.value ?? member.name;
|
|
15
|
+
// Redoc uses the title as the variant label and may omit the const value.
|
|
16
|
+
context.call($summary, member, `${member.name}`);
|
|
17
|
+
if (!namesByValue.has(value)) {
|
|
18
|
+
namesByValue.set(value, member.name);
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
setExtension(context.program, target, "x-enum-varnames", [Object.fromEntries(namesByValue)]);
|
|
22
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import "@typespec/openapi";
|
|
2
|
+
import "./named-enum.js";
|
|
3
|
+
|
|
4
|
+
using TypeSpec.Reflection;
|
|
5
|
+
|
|
6
|
+
namespace ZpLib {
|
|
7
|
+
/**
|
|
8
|
+
* 将枚举成员名作为标题;成员值与 `@doc` 描述分别保留,供文档按“值|变量名|描述”展示。
|
|
9
|
+
* 配合 enum-strategy: annotated,生成包含 const(枚举值)、title 和 description(`@doc`)的 oneOf 成员。
|
|
10
|
+
* x-enum-varnames 使用 [{ "枚举值": "成员名", ... }] 格式,重复值保留第一个成员名。
|
|
11
|
+
*/
|
|
12
|
+
extern dec namedEnum(target: Enum);
|
|
13
|
+
}
|