@djvlc/contracts-validators 1.3.1 → 1.4.0

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 (7) hide show
  1. package/dist/index.d.mts +74 -102
  2. package/dist/index.d.ts +74 -102
  3. package/dist/index.js +276 -173
  4. package/dist/index.js.map +1 -1
  5. package/dist/index.mjs +267 -153
  6. package/dist/index.mjs.map +1 -1
  7. package/package.json +9 -12
package/dist/index.d.mts CHANGED
@@ -1,14 +1,20 @@
1
- import Ajv from 'ajv';
2
- import { PageSchema, ComponentMeta, ActionDefinition, ActionExecuteRequest, DataQueryDefinition, DataQueryRequest } from '@djvlc/contracts-types';
1
+ export { actionSpecSchema, componentMetaSchema, dataQuerySpecSchema, pageSchema } from '@djvlc/contracts-schemas';
3
2
 
4
3
  /**
5
- * @djvlc/contracts-validators - DJV 低代码平台预编译校验器包
4
+ * @djvlc/contracts-validators
6
5
  *
7
- * 提供预编译的 Ajv 校验器，避免各仓库自行编写校验逻辑导致分叉
6
+ * DJVLC 低代码平台预编译 JSON Schema 校验器
8
7
  *
9
- * @packageDocumentation
8
+ * 提供高性能的 Ajv 校验器，用于：
9
+ * - 发布期校验（Editor 发布页面时）
10
+ * - 运行时校验（Runtime 加载组件时）
11
+ * - API 校验（Platform 接收请求时）
12
+ *
13
+ * V2 版本更新：
14
+ * - 支持 PageSchema V2 Runtime Core 校验
15
+ * - 新增表达式引用校验（支持 binding 类型）
16
+ * - 优化错误信息格式
10
17
  */
11
-
12
18
  /**
13
19
  * 校验结果
14
20
  */
@@ -26,125 +32,91 @@ interface ValidationError {
26
32
  path: string;
27
33
  /** 错误消息 */
28
34
  message: string;
29
- /** 错误关键字 */
30
- keyword?: string;
31
- /** 期望值 */
32
- expected?: unknown;
33
- /** 实际值 */
34
- actual?: unknown;
35
+ /** JSON Schema 关键字 */
36
+ keyword: string;
37
+ /** 错误参数 */
38
+ params: Record<string, unknown>;
39
+ /** Schema 路径 */
40
+ schemaPath: string;
35
41
  }
36
- declare const ajv: Ajv;
37
- /**
38
- * 校验 PageSchema
39
- * @param data 待校验数据
40
- * @returns 校验结果
41
- */
42
- declare function validatePage(data: unknown): ValidationResult;
43
- /**
44
- * 校验 PageSchema，返回类型安全的结果
45
- */
46
- declare function validatePageSchema(data: unknown): ValidationResult & {
47
- data?: PageSchema;
48
- };
49
42
  /**
50
- * 断言为 PageSchema
43
+ * 校验页面 Schema（V2 Runtime Core）
51
44
  */
52
- declare function assertPageSchema(data: unknown): asserts data is PageSchema;
45
+ declare function validatePageSchema(data: unknown): ValidationResult;
53
46
  /**
54
- * 校验 ComponentMeta
55
- * @param data 待校验数据
56
- * @returns 校验结果
47
+ * 校验组件元数据
57
48
  */
58
49
  declare function validateComponentMeta(data: unknown): ValidationResult;
59
50
  /**
60
- * 断言为 ComponentMeta
61
- */
62
- declare function assertComponentMeta(data: unknown): asserts data is ComponentMeta;
63
- /**
64
- * 校验 ActionDefinition
65
- * @param data 待校验数据
66
- * @returns 校验结果
67
- */
68
- declare function validateActionDefinition(data: unknown): ValidationResult;
69
- /**
70
- * 断言为 ActionDefinition
51
+ * 校验动作规格
71
52
  */
72
- declare function assertActionDefinition(data: unknown): asserts data is ActionDefinition;
53
+ declare function validateActionSpec(data: unknown): ValidationResult;
73
54
  /**
74
- * 校验 ActionExecuteRequest
55
+ * 校验数据查询规格
75
56
  */
76
- declare function validateActionRequest(data: unknown): ValidationResult;
57
+ declare function validateDataQuerySpec(data: unknown): ValidationResult;
77
58
  /**
78
- * 断言为 ActionExecuteRequest
79
- */
80
- declare function assertActionRequest(data: unknown): asserts data is ActionExecuteRequest;
81
- /**
82
- * 校验 DataQueryDefinition
83
- * @param data 待校验数据
84
- * @returns 校验结果
85
- */
86
- declare function validateDataQueryDefinition(data: unknown): ValidationResult;
87
- /**
88
- * 断言为 DataQueryDefinition
89
- */
90
- declare function assertDataQueryDefinition(data: unknown): asserts data is DataQueryDefinition;
91
- /**
92
- * 校验 DataQueryRequest
93
- */
94
- declare function validateQueryRequest(data: unknown): ValidationResult;
95
- /**
96
- * 断言为 DataQueryRequest
97
- */
98
- declare function assertQueryRequest(data: unknown): asserts data is DataQueryRequest;
99
- /**
100
- * 检查是否为有效的 PageSchema
101
- */
102
- declare function isPageSchema(value: unknown): value is PageSchema;
103
- /**
104
- * 检查是否为有效的 ComponentMeta
59
+ * 批量校验结果
105
60
  */
106
- declare function isComponentMeta(value: unknown): value is ComponentMeta;
61
+ interface BatchValidationResult {
62
+ /** 总数 */
63
+ total: number;
64
+ /** 通过数 */
65
+ passed: number;
66
+ /** 失败数 */
67
+ failed: number;
68
+ /** 详细结果 */
69
+ results: {
70
+ index: number;
71
+ valid: boolean;
72
+ errors: ValidationError[];
73
+ }[];
74
+ }
107
75
  /**
108
- * 检查是否为有效的 ActionDefinition
76
+ * 批量校验
109
77
  */
110
- declare function isActionDefinition(value: unknown): value is ActionDefinition;
78
+ declare function batchValidate(validator: (data: unknown) => ValidationResult, items: unknown[]): BatchValidationResult;
111
79
  /**
112
- * 检查是否为有效的 DataQueryDefinition
80
+ * 校验并抛出异常
113
81
  */
114
- declare function isDataQueryDefinition(value: unknown): value is DataQueryDefinition;
82
+ declare function validateOrThrow(validator: (data: unknown) => ValidationResult, data: unknown, errorMessage?: string): void;
115
83
  /**
116
- * 检查是否为有效的 ActionExecuteRequest
84
+ * 校验组件节点树中引用的组件版本
117
85
  */
118
- declare function isActionRequest(value: unknown): value is ActionExecuteRequest;
86
+ declare function validateComponentReferences(pageSchema: unknown, availableComponents: Map<string, Set<string>>): ValidationResult;
119
87
  /**
120
- * 检查是否为有效的 DataQueryRequest
88
+ * 校验表达式引用
89
+ *
90
+ * @description
91
+ * V2 版本更新：支持 state、binding、computed 三种表达式类型的引用校验
121
92
  */
122
- declare function isQueryRequest(value: unknown): value is DataQueryRequest;
93
+ declare function validateExpressionReferences(pageSchema: unknown, availableFields: Set<string>): ValidationResult;
123
94
  /**
124
- * 批量校验结果
95
+ * 校验数据绑定配置
96
+ *
97
+ * @description
98
+ * V2 新增：校验 dataBindings 中的 targetState 是否在 state.fields 中定义
125
99
  */
126
- interface BatchValidationResult<T> {
127
- /** 全部有效 */
128
- allValid: boolean;
129
- /** 有效项数量 */
130
- validCount: number;
131
- /** 无效项数量 */
132
- invalidCount: number;
133
- /** 各项结果 */
134
- results: Array<{
135
- index: number;
136
- valid: boolean;
137
- data?: T;
138
- errors: ValidationError[];
139
- }>;
140
- }
100
+ declare function validateDataBindingReferences(pageSchema: unknown): ValidationResult;
141
101
  /**
142
- * 批量校验 PageSchema
102
+ * 校验动作引用
103
+ *
104
+ * @description
105
+ * V2 新增：校验 ActionRef 必须指定 actionDefinitionVersionId 或 builtinAction 之一
143
106
  */
144
- declare function validatePages(items: unknown[]): BatchValidationResult<PageSchema>;
107
+ declare function validateActionReferences(pageSchema: unknown): ValidationResult;
145
108
  /**
146
- * 批量校验 ComponentMeta
147
- */
148
- declare function validateComponentMetas(items: unknown[]): BatchValidationResult<ComponentMeta>;
109
+ * 完整校验（结构 + 引用）
110
+ *
111
+ * @description
112
+ * 执行完整的页面 Schema 校验，包括：
113
+ * 1. JSON Schema 结构校验
114
+ * 2. 组件引用校验
115
+ * 3. 表达式引用校验
116
+ * 4. 数据绑定引用校验
117
+ * 5. 动作引用校验
118
+ */
119
+ declare function validatePageSchemaFull(data: unknown, availableComponents?: Map<string, Set<string>>, availableFields?: Set<string>): ValidationResult;
120
+ declare const VERSION = "2.0.0";
149
121
 
150
- export { type BatchValidationResult, type ValidationError, type ValidationResult, ajv, assertActionDefinition, assertActionRequest, assertComponentMeta, assertDataQueryDefinition, assertPageSchema, assertQueryRequest, isActionDefinition, isActionRequest, isComponentMeta, isDataQueryDefinition, isPageSchema, isQueryRequest, validateActionDefinition, validateActionRequest, validateComponentMeta, validateComponentMetas, validateDataQueryDefinition, validatePage, validatePageSchema, validatePages, validateQueryRequest };
122
+ export { type BatchValidationResult, VERSION, type ValidationError, type ValidationResult, batchValidate, validateActionReferences, validateActionSpec, validateComponentMeta, validateComponentReferences, validateDataBindingReferences, validateDataQuerySpec, validateExpressionReferences, validateOrThrow, validatePageSchema, validatePageSchemaFull };
package/dist/index.d.ts CHANGED
@@ -1,14 +1,20 @@
1
- import Ajv from 'ajv';
2
- import { PageSchema, ComponentMeta, ActionDefinition, ActionExecuteRequest, DataQueryDefinition, DataQueryRequest } from '@djvlc/contracts-types';
1
+ export { actionSpecSchema, componentMetaSchema, dataQuerySpecSchema, pageSchema } from '@djvlc/contracts-schemas';
3
2
 
4
3
  /**
5
- * @djvlc/contracts-validators - DJV 低代码平台预编译校验器包
4
+ * @djvlc/contracts-validators
6
5
  *
7
- * 提供预编译的 Ajv 校验器，避免各仓库自行编写校验逻辑导致分叉
6
+ * DJVLC 低代码平台预编译 JSON Schema 校验器
8
7
  *
9
- * @packageDocumentation
8
+ * 提供高性能的 Ajv 校验器，用于：
9
+ * - 发布期校验（Editor 发布页面时）
10
+ * - 运行时校验（Runtime 加载组件时）
11
+ * - API 校验（Platform 接收请求时）
12
+ *
13
+ * V2 版本更新：
14
+ * - 支持 PageSchema V2 Runtime Core 校验
15
+ * - 新增表达式引用校验（支持 binding 类型）
16
+ * - 优化错误信息格式
10
17
  */
11
-
12
18
  /**
13
19
  * 校验结果
14
20
  */
@@ -26,125 +32,91 @@ interface ValidationError {
26
32
  path: string;
27
33
  /** 错误消息 */
28
34
  message: string;
29
- /** 错误关键字 */
30
- keyword?: string;
31
- /** 期望值 */
32
- expected?: unknown;
33
- /** 实际值 */
34
- actual?: unknown;
35
+ /** JSON Schema 关键字 */
36
+ keyword: string;
37
+ /** 错误参数 */
38
+ params: Record<string, unknown>;
39
+ /** Schema 路径 */
40
+ schemaPath: string;
35
41
  }
36
- declare const ajv: Ajv;
37
- /**
38
- * 校验 PageSchema
39
- * @param data 待校验数据
40
- * @returns 校验结果
41
- */
42
- declare function validatePage(data: unknown): ValidationResult;
43
- /**
44
- * 校验 PageSchema，返回类型安全的结果
45
- */
46
- declare function validatePageSchema(data: unknown): ValidationResult & {
47
- data?: PageSchema;
48
- };
49
42
  /**
50
- * 断言为 PageSchema
43
+ * 校验页面 Schema（V2 Runtime Core）
51
44
  */
52
- declare function assertPageSchema(data: unknown): asserts data is PageSchema;
45
+ declare function validatePageSchema(data: unknown): ValidationResult;
53
46
  /**
54
- * 校验 ComponentMeta
55
- * @param data 待校验数据
56
- * @returns 校验结果
47
+ * 校验组件元数据
57
48
  */
58
49
  declare function validateComponentMeta(data: unknown): ValidationResult;
59
50
  /**
60
- * 断言为 ComponentMeta
61
- */
62
- declare function assertComponentMeta(data: unknown): asserts data is ComponentMeta;
63
- /**
64
- * 校验 ActionDefinition
65
- * @param data 待校验数据
66
- * @returns 校验结果
67
- */
68
- declare function validateActionDefinition(data: unknown): ValidationResult;
69
- /**
70
- * 断言为 ActionDefinition
51
+ * 校验动作规格
71
52
  */
72
- declare function assertActionDefinition(data: unknown): asserts data is ActionDefinition;
53
+ declare function validateActionSpec(data: unknown): ValidationResult;
73
54
  /**
74
- * 校验 ActionExecuteRequest
55
+ * 校验数据查询规格
75
56
  */
76
- declare function validateActionRequest(data: unknown): ValidationResult;
57
+ declare function validateDataQuerySpec(data: unknown): ValidationResult;
77
58
  /**
78
- * 断言为 ActionExecuteRequest
79
- */
80
- declare function assertActionRequest(data: unknown): asserts data is ActionExecuteRequest;
81
- /**
82
- * 校验 DataQueryDefinition
83
- * @param data 待校验数据
84
- * @returns 校验结果
85
- */
86
- declare function validateDataQueryDefinition(data: unknown): ValidationResult;
87
- /**
88
- * 断言为 DataQueryDefinition
89
- */
90
- declare function assertDataQueryDefinition(data: unknown): asserts data is DataQueryDefinition;
91
- /**
92
- * 校验 DataQueryRequest
93
- */
94
- declare function validateQueryRequest(data: unknown): ValidationResult;
95
- /**
96
- * 断言为 DataQueryRequest
97
- */
98
- declare function assertQueryRequest(data: unknown): asserts data is DataQueryRequest;
99
- /**
100
- * 检查是否为有效的 PageSchema
101
- */
102
- declare function isPageSchema(value: unknown): value is PageSchema;
103
- /**
104
- * 检查是否为有效的 ComponentMeta
59
+ * 批量校验结果
105
60
  */
106
- declare function isComponentMeta(value: unknown): value is ComponentMeta;
61
+ interface BatchValidationResult {
62
+ /** 总数 */
63
+ total: number;
64
+ /** 通过数 */
65
+ passed: number;
66
+ /** 失败数 */
67
+ failed: number;
68
+ /** 详细结果 */
69
+ results: {
70
+ index: number;
71
+ valid: boolean;
72
+ errors: ValidationError[];
73
+ }[];
74
+ }
107
75
  /**
108
- * 检查是否为有效的 ActionDefinition
76
+ * 批量校验
109
77
  */
110
- declare function isActionDefinition(value: unknown): value is ActionDefinition;
78
+ declare function batchValidate(validator: (data: unknown) => ValidationResult, items: unknown[]): BatchValidationResult;
111
79
  /**
112
- * 检查是否为有效的 DataQueryDefinition
80
+ * 校验并抛出异常
113
81
  */
114
- declare function isDataQueryDefinition(value: unknown): value is DataQueryDefinition;
82
+ declare function validateOrThrow(validator: (data: unknown) => ValidationResult, data: unknown, errorMessage?: string): void;
115
83
  /**
116
- * 检查是否为有效的 ActionExecuteRequest
84
+ * 校验组件节点树中引用的组件版本
117
85
  */
118
- declare function isActionRequest(value: unknown): value is ActionExecuteRequest;
86
+ declare function validateComponentReferences(pageSchema: unknown, availableComponents: Map<string, Set<string>>): ValidationResult;
119
87
  /**
120
- * 检查是否为有效的 DataQueryRequest
88
+ * 校验表达式引用
89
+ *
90
+ * @description
91
+ * V2 版本更新：支持 state、binding、computed 三种表达式类型的引用校验
121
92
  */
122
- declare function isQueryRequest(value: unknown): value is DataQueryRequest;
93
+ declare function validateExpressionReferences(pageSchema: unknown, availableFields: Set<string>): ValidationResult;
123
94
  /**
124
- * 批量校验结果
95
+ * 校验数据绑定配置
96
+ *
97
+ * @description
98
+ * V2 新增：校验 dataBindings 中的 targetState 是否在 state.fields 中定义
125
99
  */
126
- interface BatchValidationResult<T> {
127
- /** 全部有效 */
128
- allValid: boolean;
129
- /** 有效项数量 */
130
- validCount: number;
131
- /** 无效项数量 */
132
- invalidCount: number;
133
- /** 各项结果 */
134
- results: Array<{
135
- index: number;
136
- valid: boolean;
137
- data?: T;
138
- errors: ValidationError[];
139
- }>;
140
- }
100
+ declare function validateDataBindingReferences(pageSchema: unknown): ValidationResult;
141
101
  /**
142
- * 批量校验 PageSchema
102
+ * 校验动作引用
103
+ *
104
+ * @description
105
+ * V2 新增：校验 ActionRef 必须指定 actionDefinitionVersionId 或 builtinAction 之一
143
106
  */
144
- declare function validatePages(items: unknown[]): BatchValidationResult<PageSchema>;
107
+ declare function validateActionReferences(pageSchema: unknown): ValidationResult;
145
108
  /**
146
- * 批量校验 ComponentMeta
147
- */
148
- declare function validateComponentMetas(items: unknown[]): BatchValidationResult<ComponentMeta>;
109
+ * 完整校验（结构 + 引用）
110
+ *
111
+ * @description
112
+ * 执行完整的页面 Schema 校验，包括：
113
+ * 1. JSON Schema 结构校验
114
+ * 2. 组件引用校验
115
+ * 3. 表达式引用校验
116
+ * 4. 数据绑定引用校验
117
+ * 5. 动作引用校验
118
+ */
119
+ declare function validatePageSchemaFull(data: unknown, availableComponents?: Map<string, Set<string>>, availableFields?: Set<string>): ValidationResult;
120
+ declare const VERSION = "2.0.0";
149
121
 
150
- export { type BatchValidationResult, type ValidationError, type ValidationResult, ajv, assertActionDefinition, assertActionRequest, assertComponentMeta, assertDataQueryDefinition, assertPageSchema, assertQueryRequest, isActionDefinition, isActionRequest, isComponentMeta, isDataQueryDefinition, isPageSchema, isQueryRequest, validateActionDefinition, validateActionRequest, validateComponentMeta, validateComponentMetas, validateDataQueryDefinition, validatePage, validatePageSchema, validatePages, validateQueryRequest };
122
+ export { type BatchValidationResult, VERSION, type ValidationError, type ValidationResult, batchValidate, validateActionReferences, validateActionSpec, validateComponentMeta, validateComponentReferences, validateDataBindingReferences, validateDataQuerySpec, validateExpressionReferences, validateOrThrow, validatePageSchema, validatePageSchemaFull };