@anov/cic-standard-sdk 0.0.10 → 0.0.12

package/dist/sdk/generators/common.d.ts

@@ -1,40 +1,85 @@
 /**
  * 生成器通用工具与类型
- * 说明：统一 Result/Options 定义与常用规范化工具（uuid/url/数组/数值）。
- * 原则：严格模式默认不做隐式容错；仅在 defaults 显式提供时才补齐默认值。
+ * 原则：
+ * 1. 严格模式默认不做隐式容错
+ * 2. 仅在 defaults 显式提供时才补齐默认值
+ * 3. 校验错误必须可定位、可去重、可排序
+ * 4. 校验 discriminated union 类型时，discriminator 字段必须为必填字段
  */
-export type Result<T> = {
-    ok: boolean;
+type Ok<T> = {
+    ok: true;
     value?: T;
-    errors?: FormattedError[];
 };
+type Err = {
+    ok: false;
+    errors: FormattedError[];
+};
+/**
+ * 校验结果
+ * - ok: 校验成功，value 为校验后的值
+ * - err: 校验失败，errors 为校验错误列表
+ */
+export type Result<T> = Ok<T> | Err;
 export type CreateOptions<T = any> = {
     defaults?: Partial<T>;
     generateId?: boolean;
     strict?: boolean;
 };
+/**
+ * 格式化校验错误
+ * - path：错误路径，如 `$.name`
+ * - message：错误描述
+ * - keyword：校验关键字，如 `required`
+ * - params：校验参数，如 `{ missingProperty: 'name' }`
+ */
 export type FormattedError = {
     path: string;
     message: string;
     keyword?: string;
     params?: Record<string, any>;
 };
-/** 将值规范为数组 */
-export declare const ensureArray: <T>(v: any) => T[];
+/**
+ * AJV校验器接口
+ * - 校验函数：接收未知值，返回是否校验通过
+ * - errors：校验失败时的错误列表
+ */
+export interface Validator<T = any> {
+    (data: unknown): data is T;
+    errors?: any[];
+}
+/** 将值规范为数组（仅接受数组，其它视为缺失） */
+export declare const ensureArray: <T>(v: unknown) => T[];
 /** 判断为有限正数 */
-export declare const isPositive: (n: any) => boolean;
-/** 生成 uuid */
-export declare const uuid: () => any;
-export declare const formatAjvErrors: (errs: any[]) => FormattedError[];
-/** 仅对缺失字段应用默认值（浅合并）；不覆盖已有值 */
-export declare const applyDefaults: <T>(target: any, defaults?: Partial<T>) => any;
+export declare const isPositive: (n: unknown) => n is number;
+/** 生成 UUID */
+export declare const uuid: () => string;
+/**
+ * 格式化 AJV 校验错误
+ * - 转换为标准格式
+ * - 去重
+ * - 排序
+ */
+export declare const formatAjvErrors: (errs?: any[]) => FormattedError[];
+/** 仅对缺失字段应用默认值（浅合并） */
+export declare const applyDefaults: <T>(target: any, defaults?: Partial<T>) => T;
 /** 在已格式化错误上追加路径前缀 */
 export declare const prefixErrors: (prefix: string, errors?: FormattedError[]) => FormattedError[];
-/** 安全解析 JSON 文本，统一错误输出（中文） */
+/** 安全解析 JSON 文本 */
 export declare const safeParseJSON: (text: string) => Result<any>;
-/** 生成缺失必填字段的聚焦错误列表 */
+/** 缺失必填字段错误 */
 export declare const missingRequiredErrors: (keys: string[]) => FormattedError[];
-/** 通用判别联合校验（按 discriminant 路由分支） */
-export declare const validateDiscriminated: (input: any, baseValidator: any, branchValidators: Record<string, any>, key: string) => Result<null>;
-/** 通用判别联合创建（规范化+分支校验+聚焦错误） */
-export declare const createDiscriminated: <T>(input: unknown, options: CreateOptions | undefined, normalize: (x: any, o?: CreateOptions) => any, baseValidator: any, branchValidators: Record<string, any>, key: string, missingKeys?: string[]) => Result<T>;
+/**
+ * 校验 discriminated union 类型
+ * - 校验 discriminator 字段
+ * - 根据 discriminator 调用相应 validator
+ * - 格式化 AJV 校验错误
+ */
+export declare const validateDiscriminated: (input: unknown, base: Validator, branches: Record<string, Validator>, key: string) => Result<null>;
+/**
+ * 创建 discriminated union 类型
+ * - 校验 discriminator 字段
+ * - 根据 discriminator 调用相应 validator
+ * - 格式化 AJV 校验错误
+ */
+export declare const createDiscriminated: <T>(input: unknown, options: CreateOptions | undefined, normalize: (x: unknown, o?: CreateOptions) => any, base: Validator, branches: Record<string, Validator>, key: string, missingKeys?: string[]) => Result<T>;
+export {};

package/dist/types/variables.d.ts

@@ -1,47 +1,45 @@
 /** 变量类型枚举，限定变量的基础类型：字符串、数字、布尔、数组、对象和函数。 */
 export type VariableType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'function';
+export interface VariableBase {
+    description?: string;
+    extensions?: Record<string, unknown>;
+}
 /** 字符串变量，包含当前值与默认值，可选描述。 */
-export interface StringVariable {
+export interface StringVariable extends VariableBase {
     type: 'string';
     value: string;
     default: string;
-    description?: string;
 }
 /** 数字变量，包含当前值与默认值，可选描述。 */
-export interface NumberVariable {
+export interface NumberVariable extends VariableBase {
     type: 'number';
     value: number;
     default: number;
-    description?: string;
 }
 /** 布尔变量，包含当前值与默认值，可选描述。 */
-export interface BooleanVariable {
+export interface BooleanVariable extends VariableBase {
     type: 'boolean';
     value: boolean;
     default: boolean;
-    description?: string;
 }
 /** 数组变量，元素类型不做限制，包含当前值与默认值，可选描述。 */
-export interface ArrayVariable {
+export interface ArrayVariable extends VariableBase {
     type: 'array';
     value: unknown[];
     default: unknown[];
-    description?: string;
 }
 /** 函数变量，以字符串保存函数实现；支持 `args` 指定入参名列表。 */
-export interface FunctionVariable {
+export interface FunctionVariable extends VariableBase {
     type: 'function';
     value: string;
     default: string;
-    description?: string;
     args?: string[];
 }
 /** 对象变量，键到变量的映射；支持递归嵌套。 */
-export interface ObjectVariable {
+export interface ObjectVariable extends VariableBase {
     type: 'object';
     value: Record<string, Variable>;
     default: Record<string, Variable>;
-    description?: string;
 }
 /** 变量联合类型，涵盖五类变量定义。 */
 export type Variable = StringVariable | NumberVariable | BooleanVariable | ArrayVariable | FunctionVariable | ObjectVariable;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anov/cic-standard-sdk",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "CIC Standard SDK with TypeScript support",
   "main": "dist/cic-sdk.cjs.js",
   "module": "dist/cic-sdk.es.js",