/** * 表示DPML文档中的单个节点 * 使用不可变设计,所有属性只读 */ interface DPMLNode { /** 节点标签名 */ readonly tagName: string; /** 节点属性集合 */ readonly attributes: Map; /** 子节点集合 */ readonly children: DPMLNode[]; /** 节点文本内容 */ readonly content: string; /** 父节点引用 */ readonly parent: DPMLNode | null; /** 源代码位置信息 */ readonly sourceLocation?: SourceLocation; } /** * 源码定位信息 */ interface SourceLocation { /** 开始行号 */ startLine: number; /** 开始列号 */ startColumn: number; /** 结束行号 */ endLine: number; /** 结束列号 */ endColumn: number; /** 源文件名 */ fileName?: string; } /** * DPML文档类型 * 表示完整DPML文档的纯数据结构 */ interface DPMLDocument { /** 文档根节点 */ readonly rootNode: DPMLNode; /** 节点ID索引,用于快速访问 */ readonly nodesById?: Map; /** 文档元数据 */ readonly metadata: DocumentMetadata; } /** * 文档元数据类型 */ interface DocumentMetadata { /** 文档标题 */ title?: string; /** 文档描述 */ description?: string; /** 创建时间 */ createdAt?: Date; /** 最后修改时间 */ modifiedAt?: Date; /** 来源文件名 */ sourceFileName?: string; /** 用户自定义元数据 */ custom?: Record; } /** * 解析选项配置类型 * 支持错误处理和验证行为配置 */ interface ParseOptions { /** 是否在错误时立即抛出 */ throwOnError?: boolean; /** 源文件名,用于错误报告 */ fileName?: string; /** 底层XML解析器选项 */ xmlParserOptions?: XMLParserOptions; /** 后处理器选项 */ postProcessorOptions?: Record; /** 内存优化选项,用于处理大文件 */ memoryOptimization?: MemoryOptimizationOptions; } /** * XML解析器选项 */ interface XMLParserOptions { /** 是否保留空白字符 */ preserveWhitespace?: boolean; /** 是否解析注释 */ parseComments?: boolean; /** 是否启用命名空间支持 */ enableNamespaces?: boolean; /** 最大嵌套层级 */ maxDepth?: number; /** 是否验证节点引用完整性 */ validateReferences?: boolean; /** 是否解析CDATA部分 */ parseCDATA?: boolean; /** 是否使用流式处理(用于大文件) */ useStreaming?: boolean; } /** * 内存优化选项 */ interface MemoryOptimizationOptions { /** 是否启用内存优化 */ enabled?: boolean; /** 大文件阈值(字节数),超过此值将应用优化 */ largeFileThreshold?: number; /** 是否使用流式处理 */ useStreaming?: boolean; /** 批处理大小 */ batchSize?: number; } /** * 解析错误代码枚举 */ declare enum ParseErrorCode { UNKNOWN_ERROR = "PARSE_UNKNOWN_ERROR", INVALID_CONTENT = "PARSE_INVALID_CONTENT", XML_SYNTAX_ERROR = "PARSE_XML_SYNTAX_ERROR", XML_INVALID_TAG = "PARSE_XML_INVALID_TAG", XML_MISSING_CLOSING_TAG = "PARSE_XML_MISSING_CLOSING_TAG", XML_INVALID_ATTRIBUTE = "PARSE_XML_INVALID_ATTRIBUTE", DPML_INVALID_STRUCTURE = "PARSE_DPML_INVALID_STRUCTURE", DPML_INVALID_TAG = "PARSE_DPML_INVALID_TAG", DPML_INVALID_ATTRIBUTE = "PARSE_DPML_INVALID_ATTRIBUTE", DPML_MISSING_REQUIRED_TAG = "PARSE_DPML_MISSING_REQUIRED_TAG", DPML_MISSING_REQUIRED_ATTRIBUTE = "PARSE_DPML_MISSING_REQUIRED_ATTRIBUTE" } /** * 基础解析错误类 * 所有解析错误的基类 */ declare class ParseError extends Error { /** * 错误代码 */ readonly code: ParseErrorCode; /** * 错误位置信息 */ readonly position?: SourceLocation; /** * 源代码片段 */ readonly source?: string; /** * 原始错误 */ readonly cause?: unknown; /** * 创建解析错误实例 * @param message 错误消息 * @param code 错误代码 * @param position 位置信息 * @param source 源代码片段 * @param cause 原始错误 */ constructor(message: string, code?: ParseErrorCode, position?: SourceLocation, source?: string, cause?: unknown); /** * 格式化错误信息,包含位置和上下文 * @returns 格式化的错误信息 */ formatMessage(): string; /** * 重写toString方法,提供更详细的错误信息 * @returns 格式化的错误字符串 */ toString(): string; } /** * XML解析错误类 * 处理XML解析过程中的错误 */ declare class XMLParseError extends ParseError { /** * 错误上下文片段 * 包含错误位置附近的内容 */ contextFragment?: string; /** * 创建XML解析错误实例 * @param message 错误消息 * @param code 错误代码 * @param position 位置信息 * @param source 源代码片段 * @param cause 原始错误 */ constructor(message: string, code?: ParseErrorCode, position?: SourceLocation, source?: string, cause?: unknown); /** * 从原始XML解析错误创建XMLParseError * @param error 原始错误 * @param content XML内容 * @param fileName 文件名 * @returns XML解析错误 */ static fromError(error: unknown, content?: string, fileName?: string): XMLParseError; /** * 从错误消息中提取位置信息 * @param message 错误消息 * @param fileName 文件名 * @returns 源码位置信息或undefined */ private static extractPositionFromMessage; /** * 从内容中提取源代码片段 * @param content 完整内容 * @param line 行号 * @param column 列号 * @returns 源代码片段 */ private static extractSourceSnippet; /** * 格式化错误信息,包含位置和上下文 * @returns 格式化的错误信息 */ formatMessage(): string; } /** * DPML解析错误类 * 处理DPML特定的解析错误 */ declare class DPMLParseError extends ParseError { /** * 创建DPML解析错误实例 * @param message 错误消息 * @param code 错误代码 * @param position 位置信息 * @param source 源代码片段 * @param cause 原始错误 */ constructor(message: string, code?: ParseErrorCode, position?: SourceLocation, source?: string, cause?: unknown); /** * 创建缺少必需标签的错误 * @param tagName 标签名 * @param position 位置信息 * @returns DPML解析错误 */ static createMissingRequiredTagError(tagName: string, position?: SourceLocation): DPMLParseError; /** * 创建缺少必需属性的错误 * @param attributeName 属性名 * @param tagName 标签名 * @param position 位置信息 * @returns DPML解析错误 */ static createMissingRequiredAttributeError(attributeName: string, tagName: string, position?: SourceLocation): DPMLParseError; /** * 创建无效标签错误 * @param tagName 标签名 * @param position 位置信息 * @returns DPML解析错误 */ static createInvalidTagError(tagName: string, position?: SourceLocation): DPMLParseError; /** * 创建无效属性错误 * @param attributeName 属性名 * @param tagName 标签名 * @param position 位置信息 * @returns DPML解析错误 */ static createInvalidAttributeError(attributeName: string, tagName: string, position?: SourceLocation): DPMLParseError; } /** * 解析结果接口 * 用于非抛出错误模式下的返回结构 */ interface ParseResult { /** * 解析是否成功 */ success: boolean; /** * 解析结果数据 * 仅在success为true时存在 */ data?: T; /** * 解析错误 * 仅在success为false时存在 */ error?: ParseError; /** * 警告信息 * 可能在success为true时也存在 */ warnings?: ParseError[]; } /** * 定义用户友好的Schema接口,不包含内部实现细节。 * 应用开发者使用这些接口定义DPML文档的结构。 */ /** * 表示元素的属性定义。 */ interface AttributeSchema { /** * 属性的名称。 */ name: string; /** * 属性值的预期类型 (例如:'string', 'number', 'boolean')。 * 如果未指定,可能表示任何类型或需要根据上下文推断。 */ type?: string; /** * 指示此属性是否为必需。 * @default false */ required?: boolean; /** * 如果属性值是枚举类型,则定义允许的值列表。 */ enum?: string[]; /** * 属性值应匹配的正则表达式模式。 */ pattern?: string; /** * 属性的默认值。 */ default?: string; } /** * 表示元素内容的定义。 */ interface ContentSchema { /** * 内容的类型,可以是'text'(纯文本)或'mixed'(混合内容)。 */ type: "text" | "mixed"; /** * 指示内容是否为必需。 * @default false */ required?: boolean; /** * 内容应匹配的正则表达式模式。 */ pattern?: string; } /** * 表示对另一个已定义类型的引用。 */ interface TypeReference { /** * 引用的类型名称。 * 这通常对应于DocumentSchema的types数组中定义的ElementSchema的element属性。 */ $ref: string; } /** * 表示元素可能包含的子元素集合。 */ interface ChildrenSchema { /** * 允许作为子元素的元素列表。 * 每个元素可以是直接的ElementSchema定义,也可以是对其他类型的引用。 */ elements: (ElementSchema | TypeReference)[]; /** * 指示子元素的顺序是否重要。 * @default false */ orderImportant?: boolean; /** * 子元素的最小数量。 */ min?: number; /** * 子元素的最大数量。 */ max?: number; } /** * 表示元素(Element)的结构定义。 */ interface ElementSchema { /** * 元素的名称(标签名)。 */ element: string; /** * 定义此元素允许或要求的属性。 */ attributes?: AttributeSchema[]; /** * 定义此元素允许的内容模型。 */ content?: ContentSchema; /** * 定义此元素允许的子元素。 */ children?: ChildrenSchema; } /** * 表示文档(Document)级别的结构定义。 */ interface DocumentSchema { /** * 定义文档的根元素。 * 可以是直接的元素定义、类型引用或表示纯文本根的字符串。 */ root: ElementSchema | TypeReference | string; /** * 定义可在本文档内部复用的类型(通常是ElementSchema)。 * 这些类型可以通过TypeReference($ref)在root或其他ElementSchema的children中引用。 */ types?: ElementSchema[]; /** * 定义适用于文档内所有元素的全局属性。 */ globalAttributes?: AttributeSchema[]; /** * 定义文档可能使用的命名空间。 */ namespaces?: string[]; } /** * Schema类型的联合类型,用于简化API参数类型定义。 */ type Schema = DocumentSchema | ElementSchema; /** * 表示 Schema 验证过程中遇到的错误。 * @template T 可选的泛型,用于携带额外的错误详情。 */ interface SchemaError { /** * 错误描述信息,应清晰易懂。 */ message: string; /** * 错误代码,用于程序化识别错误类型。 */ code: string; /** * 错误在 Schema 对象中发生的路径。 * 例如: "elements[0].attributes[1].name" */ path: string; /** * 可选的额外错误详情。 */ details?: T; } /** * 表示经过处理(验证)后的 Schema 定义结果。 * @template T 原始 Schema 对象的类型。 */ interface ProcessedSchema { /** * 用户提供的原始 Schema 对象。 */ schema: T; /** * 指示 Schema 定义是否有效(是否通过了所有验证规则)。 */ isValid: boolean; /** * 如果 Schema 无效 (isValid 为 false),则包含一个或多个 SchemaError 对象。 * 如果 Schema 有效,则此属性为 undefined。 */ errors?: SchemaError[]; } /** * 引用映射接口 * 提供文档中ID到节点的映射关系 */ interface ReferenceMap { /** * ID到节点的映射 */ readonly idMap: ReadonlyMap; } /** * 处理错误接口 * 表示文档处理过程中的错误信息 */ interface ProcessingError { /** * 错误代码 */ readonly code: string; /** * 错误消息 */ readonly message: string; /** * 文档路径 */ readonly path: string; /** * 源代码位置信息 */ readonly source: SourceLocation; /** * 错误的严重程度 */ readonly severity: "error"; } /** * 处理警告接口 * 表示文档处理过程中的警告信息 */ interface ProcessingWarning { /** * 警告代码 */ readonly code: string; /** * 警告消息 */ readonly message: string; /** * 文档路径 */ readonly path: string; /** * 源代码位置信息 */ readonly source: SourceLocation; /** * 警告的严重程度 */ readonly severity: "warning"; } /** * 验证结果接口 * 包含文档验证结果的详细信息 */ interface ValidationResult { /** * 是否通过验证 */ readonly isValid: boolean; /** * 验证过程中发现的错误 */ readonly errors: ReadonlyArray; /** * 验证过程中发现的警告 */ readonly warnings: ReadonlyArray; } /** * 处理结果接口,包含解析和处理后的数据 */ interface ProcessingResult { /** * DPML文档对象 */ document: DPMLDocument; /** * 文档有效性标志 */ isValid: boolean; /** * 文档引用关系映射 */ references?: ReferenceMap; /** * 文档schema信息 */ schema?: unknown; /** * 验证结果详情 */ validation?: ValidationResult; } /** * 处理上下文接口 * 提供处理过程中的核心上下文信息 */ interface ProcessingContext { /** * 正在处理的DPML文档 */ readonly document: DPMLDocument; /** * 用于验证的已处理Schema */ readonly schema: ProcessedSchema; } /** * 转换上下文类,负责在转换过程中维护状态 * 提供类型安全的数据访问方法 */ declare class TransformContext { /** * 存储上下文数据的内部Map */ private data; /** * 原始处理结果引用 */ private processingResult; /** * 创建上下文实例 * @param processingResult 原始处理结果 * @param initialData 可选的初始数据 */ constructor(processingResult: ProcessingResult, initialData?: Record); /** * 类型安全的数据存储 * @template T 值的类型 * @param key 存储键 * @param value 存储值 */ set(key: string, value: T): void; /** * 类型安全的数据获取 * @template T 期望的返回类型 * @param key 获取键 * @returns 获取的值,若不存在则返回undefined */ get(key: string): T | undefined; /** * 检查键是否存在 * @param key 检查键 * @returns 是否存在 */ has(key: string): boolean; /** * 获取原始文档 * @returns 文档对象 */ getDocument(): DPMLDocument; /** * 获取引用关系 * @returns 引用映射 */ getReferences(): ReferenceMap | undefined; /** * 获取验证结果 * @returns 验证结果对象 */ getValidation(): ValidationResult; /** * 检查文档有效性 * @returns 是否有效 */ isDocumentValid(): boolean; /** * 获取所有结果 * @returns 所有存储的数据 */ getAllResults(): Record; } /** * Transformer接口定义,所有转换器实现此接口 * 支持泛型输入输出类型,确保类型安全 * @template TInput 输入数据类型 * @template TOutput 输出数据类型 */ interface Transformer< TInput, TOutput > { /** * 转换器名称,用于标识 */ name: string; /** * 转换器描述,说明功能(可选) */ description?: string; /** * 执行转换的核心方法 * @param input 输入数据,类型为TInput * @param context 转换上下文 * @returns 转换后的输出,类型为TOutput */ transform(input: TInput, context: TransformContext): TOutput; } /** * 转换选项接口,配置转换过程 */ interface TransformOptions { /** * 初始上下文数据 * 在转换开始前注入到上下文中 */ context?: Record; /** * 结果模式选择 * - 'full': 返回完整结果,包括transformers、merged和raw * - 'merged': 仅返回merged部分 * - 'raw': 仅返回raw部分 */ resultMode?: "full" | "merged" | "raw"; /** * 包含的转换器 * 如果提供,只有指定的转换器结果会被包含在最终结果中 */ include?: string[]; /** * 排除的转换器 * 如果提供,指定的转换器结果会被排除在最终结果外 */ exclude?: string[]; } /** * 转换结果接口,定义转换输出的标准结构 * 支持泛型指定结果类型 */ interface TransformResult { /** * 各转换器的结果映射 * 键为转换器名称,值为对应转换器的输出 */ transformers: Record; /** * 合并后的结果 * 类型为用户指定的泛型参数T */ merged: T; /** * 原始未处理的结果 * 通常是最后一个转换器的直接输出 */ raw?: unknown; /** * 转换过程中的警告 */ warnings?: TransformWarning[]; /** * 转换元数据信息 */ metadata: TransformMetadata; } /** * 转换警告接口 */ interface TransformWarning { /** * 警告代码 */ code: string; /** * 警告消息 */ message: string; /** * 相关转换器 */ transformer?: string; /** * 警告严重程度 */ severity: "low" | "medium" | "high"; } /** * 转换元数据接口 */ interface TransformMetadata { /** * 参与转换的转换器名称列表 */ transformers: string[]; /** * 转换选项 */ options: TransformOptions; /** * 转换时间戳 */ timestamp: number; /** * 执行时间(毫秒) */ executionTime?: number; } /** * 映射规则接口,用于结构映射 * 支持泛型定义输入值和输出值类型 */ interface MappingRule< TValue, TResult > { /** * CSS选择器,定位元素 */ selector: string; /** * 目标属性路径 * 描述映射结果在目标对象中的位置 * 例如:"parameters.temperature" */ targetPath: string; /** * 可选值转换函数 * 对提取的值进行转换处理 * @param value 从选择器提取的原始值 * @returns 转换后的值 */ transform?: (value: TValue) => TResult; } /** * 收集配置接口,用于聚合转换器 */ interface CollectorConfig { /** * CSS选择器,定位要收集的元素 */ selector: string; /** * 分组字段 * 如果提供,结果将按此字段分组 * 通常是属性名或可以从元素提取的值 */ groupBy?: string; /** * 排序字段 * 如果提供,结果将按此字段排序 * 通常是属性名或可以从元素提取的值 */ sortBy?: string; } /** * 关系配置接口,用于关系处理转换器 */ interface RelationConfig { /** * 源选择器或属性 * 定义关系的源端点 */ source: string; /** * 目标选择器或属性 * 定义关系的目标端点 */ target: string; /** * 关系类型 * 可选的关系类型描述 */ type?: string; } /** * 语义提取器接口,用于语义提取转换器 * 支持泛型元素处理和结果类型 */ interface SemanticExtractor< TElement, TResult > { /** * 提取器名称,用于标识 */ name: string; /** * CSS选择器,定位要处理的元素 */ selector: string; /** * 处理函数,处理提取的元素 * @param elements 提取的元素数组 * @returns 处理结果 */ processor: (elements: TElement[]) => TResult; } /** * 转换器定义器接口,提供创建各种类型转换器的能力 */ interface TransformerDefiner { /** * 定义结构映射转换器 * @param name 转换器名称 * @param rules 映射规则数组 * @returns 结构映射转换器实例 */ defineStructuralMapper< TInput, TOutput >(name: string, rules: Array>): Transformer; /** * 定义聚合转换器 * @param name 转换器名称 * @param config 收集配置 * @returns 聚合转换器实例 */ defineAggregator< TInput, TOutput >(name: string, config: CollectorConfig): Transformer; /** * 定义模板转换器 * @param name 转换器名称 * @param template 模板字符串或函数 * @param preprocessor 可选的数据预处理函数 * @returns 模板转换器实例 */ defineTemplateTransformer(name: string, template: string | ((data: unknown) => string), preprocessor?: (input: TInput) => unknown): Transformer; /** * 定义关系处理转换器 * @param name 转换器名称 * @param nodeSelector 节点选择器 * @param config 关系配置 * @returns 关系处理转换器实例 */ defineRelationProcessor< TInput, TOutput >(name: string, nodeSelector: string, config: RelationConfig): Transformer; /** * 定义语义提取转换器 * @param name 转换器名称 * @param extractors 提取器数组 * @returns 语义提取转换器实例 */ defineSemanticExtractor< TInput, TOutput >(name: string, extractors: Array>): Transformer; /** * 定义结果收集转换器 * @param name 转换器名称 * @param transformerNames 可选的转换器名称数组,用于选择性收集 * @returns 结果收集转换器实例 */ defineResultCollector(name: string, transformerNames?: string[]): Transformer; } /** * 解析服务模块 * 解析DPML内容字符串,协调适配器和错误处理 * * @param content DPML内容字符串 * @param options 解析选项 * @returns 解析后的DPML文档 */ declare function parse(content: string, options?: ParseOptions): T | ParseResult; /** * 异步解析DPML内容 * * @param content DPML内容字符串 * @param options 解析选项 * @returns 解析后的DPML文档Promise */ declare function parseAsync(content: string, options?: ParseOptions): Promise>; /** * 处理文档 * 基于提供的Schema验证文档,并提供验证结果和引用信息 * * @param document - 要处理的DPML文档 * @param schema - 用于验证的已处理Schema * @returns 处理结果,包含验证信息和引用映射 * * @example * const result = processDocument(document, schema); * if (result.validation.isValid) { * // 文档有效,可以继续处理 * } else { * // 处理验证错误 * result.validation.errors.forEach(error => console.error(error.message)); * } */ declare function processDocument(document: DPMLDocument, schema: ProcessedSchema): T; /** * Schema 模块服务层。 * 负责协调 Schema 处理流程,例如创建 Schema 业务类实例并调用其方法。 * @param schema 用户提供的原始 Schema 对象。 * @returns 处理后的 Schema 结果。 * @template T 原始 Schema 对象的类型,默认为UserSchema。 * @template R 处理结果的类型,默认为 ProcessedSchema。 * 注意:这是一个骨架函数,具体逻辑将在后续任务中实现。 */ declare function processSchema< T extends object = Schema, R extends ProcessedSchema = ProcessedSchema >(schema: T): R; /** * 执行转换过程,返回结果 * @param processingResult 处理结果 * @param options 转换选项 * @returns 转换结果,类型由泛型参数T指定 */ declare function transform(processingResult: ProcessingResult, options?: TransformOptions): TransformResult; /** * 注册自定义转换器 * @param transformer 要注册的转换器 */ declare function registerTransformer< TInput, TOutput >(transformer: Transformer): void; export { transform, registerTransformer, processSchema, processDocument, parseAsync, parse, XMLParserOptions, XMLParseError, ValidationResult, TypeReference, TransformerDefiner, Transformer, TransformWarning, TransformResult, TransformOptions, TransformMetadata, TransformContext, SourceLocation, SemanticExtractor, SchemaError, Schema, RelationConfig, ReferenceMap, ProcessingWarning, ProcessingResult, ProcessingError, ProcessingContext, ProcessedSchema, ParseResult, ParseOptions, ParseErrorCode, ParseError, MemoryOptimizationOptions, MappingRule, ElementSchema, DocumentSchema, DocumentMetadata, DPMLParseError, DPMLNode, DPMLDocument, ContentSchema, CollectorConfig, ChildrenSchema, AttributeSchema };