@sciexpr/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,420 @@
+/** 表达式分类 */
+declare enum ExpressionKind {
+    /** 数学公式（默认） */
+    Math = "math",
+    /** 化学分子式 */
+    Molecule = "molecule",
+    /** 化学反应方程式 */
+    ChemicalEquation = "chemical-equation",
+    /** 矩阵/数组 */
+    Matrix = "matrix",
+    /** 纯文本 */
+    Text = "text",
+    /** 混合表达式（含多种类型片段） */
+    Mixed = "mixed"
+}
+/** 源码位置（用于错误提示和高亮） */
+interface SourceLocation {
+    start: {
+        line: number;
+        column: number;
+        offset: number;
+    };
+    end: {
+        line: number;
+        column: number;
+        offset: number;
+    };
+}
+/** 所有 AST 节点的基类 */
+interface ExpressionNode {
+    /** 节点类型标识（discriminant） */
+    kind: string;
+    /** 可选的唯一标识 */
+    id?: string;
+    /** 源码位置 */
+    source?: SourceLocation;
+}
+/** 顶层表达式根节点 */
+interface ExpressionRoot extends ExpressionNode {
+    kind: 'root';
+    /** 表达式分类 */
+    type: ExpressionKind;
+    /** 子节点列表 */
+    children: ExpressionNode[];
+    /** 元数据 */
+    metadata?: ExpressionMetadata;
+}
+/** 表达式元数据 */
+interface ExpressionMetadata {
+    /** 是否为 display 模式（块级公式） */
+    displayMode?: boolean;
+    /** 表达式编号（如 \tag{...}） */
+    label?: string;
+    /** 自定义样式 */
+    style?: Record<string, string>;
+    /** 原始输入（用于调试和格式化） */
+    originalSource?: string;
+}
+/** 符号类型 */
+declare enum SymbolType {
+    Greek = "greek",
+    Operator = "operator",
+    Relation = "relation",
+    Arrow = "arrow",
+    Accent = "accent",
+    Ordinary = "ordinary",
+    Variable = "variable",
+    Number = "number"
+}
+/** 原子符号/标识符 */
+interface SymbolNode extends ExpressionNode {
+    kind: 'symbol';
+    /** 符号文本（LaTeX 命令或 Unicode 字符） */
+    value: string;
+    /** 符号分类 */
+    symbolType: SymbolType;
+}
+/** 分数 */
+interface FractionNode extends ExpressionNode {
+    kind: 'frac';
+    numerator: ExpressionNode;
+    denominator: ExpressionNode;
+}
+/** 上下标 */
+interface ScriptNode extends ExpressionNode {
+    kind: 'script';
+    base: ExpressionNode;
+    sub?: ExpressionNode;
+    super?: ExpressionNode;
+}
+/** 根式 */
+interface RadicalNode extends ExpressionNode {
+    kind: 'radical';
+    /** 根指数（如立方根为 3），省略则为平方根 */
+    index?: ExpressionNode;
+    /** 被开方数 */
+    radicand: ExpressionNode;
+}
+/** 括号/定界符 */
+interface DelimiterNode extends ExpressionNode {
+    kind: 'delimiter';
+    /** 左定界符 */
+    left: string;
+    /** 右定界符 */
+    right: string;
+    /** 包裹的内容 */
+    body: ExpressionNode;
+}
+/** 矩阵/数组 */
+interface MatrixNode extends ExpressionNode {
+    kind: 'matrix';
+    /** 矩阵元素，row-major */
+    rows: ExpressionNode[][];
+    /** 列对齐 */
+    columnAlign?: ('l' | 'c' | 'r')[];
+    /** 矩阵类型 */
+    matrixType?: 'matrix' | 'pmatrix' | 'bmatrix' | 'Bmatrix' | 'vmatrix' | 'Vmatrix';
+}
+/** 文本节点 */
+interface TextNode extends ExpressionNode {
+    kind: 'text';
+    content: string;
+}
+/** 空格节点 */
+interface SpaceNode extends ExpressionNode {
+    kind: 'space';
+    /** 空格宽度（em） */
+    width: number;
+}
+/** 重音符号 */
+interface AccentNode extends ExpressionNode {
+    kind: 'accent';
+    /** 重音类型 */
+    accentType: 'hat' | 'tilde' | 'bar' | 'dot' | 'ddot' | 'vec' | 'widehat' | 'widetilde';
+    base: ExpressionNode;
+}
+/** 求和/求积/积分等大型运算符 */
+interface LargeOpNode extends ExpressionNode {
+    kind: 'largeop';
+    /** 运算符类型 */
+    opType: 'sum' | 'prod' | 'int' | 'oint' | 'iint' | 'iiint' | 'coprod' | 'bigcup' | 'bigcap' | 'bigvee' | 'bigwedge';
+    /** 下限 */
+    lower?: ExpressionNode;
+    /** 上限 */
+    upper?: ExpressionNode;
+    /** 被积/被运算体 */
+    body?: ExpressionNode;
+}
+/** 颜色节点 */
+interface ColorNode extends ExpressionNode {
+    kind: 'color';
+    /** 颜色值 */
+    color: string;
+    body: ExpressionNode;
+}
+/** 分组节点（{...}，无渲染含义） */
+interface GroupNode extends ExpressionNode {
+    kind: 'group';
+    children: ExpressionNode[];
+}
+/** 化学元素原子 */
+interface ChemElementNode extends ExpressionNode {
+    kind: 'chem-element';
+    /** 元素符号，如 'H', 'Na', 'Cl' */
+    symbol: string;
+    /** 原子个数（下标） */
+    count?: number;
+    /** 同位素质量数（左上标） */
+    isotope?: number;
+    /** 电荷/氧化态（右上标） */
+    charge?: number;
+    chargeSign?: '+' | '-';
+}
+/** 化学键 */
+interface ChemBondNode extends ExpressionNode {
+    kind: 'chem-bond';
+    bondType: 'single' | 'double' | 'triple' | 'aromatic' | 'coordinate';
+    left: ExpressionNode;
+    right: ExpressionNode;
+}
+/** 化学反应箭头类型 */
+type ChemArrowType = '->' | '<-' | '<=>' | '<->' | '->[' | '<-[' | '<=>>' | '<<=>';
+/** 化学反应方程式 */
+interface ChemReactionNode extends ExpressionNode {
+    kind: 'chem-reaction';
+    reactants: ExpressionNode[];
+    products: ExpressionNode[];
+    /** 反应条件（加热/催化剂等） */
+    conditions?: ExpressionNode;
+    arrowType: ChemArrowType;
+}
+/** 化学基团（官能团） */
+interface ChemGroupNode extends ExpressionNode {
+    kind: 'chem-group';
+    /** 基团名称 */
+    name?: string;
+    atoms: ChemElementNode[];
+}
+/** 所有节点类型的联合 */
+type ASTNode = ExpressionRoot | SymbolNode | FractionNode | ScriptNode | RadicalNode | DelimiterNode | MatrixNode | TextNode | SpaceNode | AccentNode | LargeOpNode | ColorNode | GroupNode | ChemElementNode | ChemBondNode | ChemReactionNode | ChemGroupNode;
+/** 根据 kind 获取对应节点类型 */
+type NodeByKind<K extends ASTNode['kind']> = Extract<ASTNode, {
+    kind: K;
+}>;
+
+/** 验证器接口 */
+interface IValidator {
+    readonly id: string;
+    readonly name: string;
+    /** 验证 AST 节点 */
+    validate(node: ExpressionNode): ValidationResult;
+}
+/** 验证结果 */
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+/** 验证错误 */
+interface ValidationError {
+    message: string;
+    node?: ExpressionNode;
+    /** 错误码 */
+    code: string;
+    /** 严重程度 */
+    severity: 'error';
+}
+/** 验证警告 */
+interface ValidationWarning {
+    message: string;
+    code: string;
+    severity: 'warning';
+}
+/** 验证错误码 */
+declare enum ValidationErrorCode {
+    UNEXPECTED_NODE = "UNEXPECTED_NODE",
+    EMPTY_EXPRESSION = "EMPTY_EXPRESSION",
+    UNBALANCED_BRACE = "UNBALANCED_BRACE",
+    UNBALANCED_BRACKET = "UNBALANCED_BRACKET",
+    INVALID_SCRIPT = "INVALID_SCRIPT",
+    DIVISION_BY_ZERO = "DIVISION_BY_ZERO",
+    MATRIX_DIMENSION_MISMATCH = "MATRIX_DIMENSION_MISMATCH",
+    NEGATIVE_RADICAL = "NEGATIVE_RADICAL",
+    INVALID_ELEMENT_SYMBOL = "INVALID_ELEMENT_SYMBOL",
+    INVALID_CHEMICAL_FORMULA = "INVALID_CHEMICAL_FORMULA",
+    CHARGE_IMBALANCE = "CHARGE_IMBALANCE",
+    ELEMENT_IMBALANCE = "ELEMENT_IMBALANCE",
+    INVALID_BOND = "INVALID_BOND"
+}
+
+/** 管线上下文 */
+interface PipelineContext {
+    /** 原始输入 */
+    input: string;
+    /** 解析后的 AST */
+    ast?: ExpressionRoot;
+    /** 渲染结果 */
+    result?: string;
+    /** 自定义元数据 */
+    metadata: Map<string, unknown>;
+    /** 累积的错误 */
+    errors: PipelineError[];
+}
+/** 管线错误 */
+interface PipelineError {
+    message: string;
+    stage: string;
+    code?: string;
+}
+/** 管线阶段 */
+interface PipelineStage {
+    readonly name: string;
+    process(ctx: PipelineContext, next: () => Promise<void>): Promise<void>;
+}
+/** 管线配置选项 */
+interface PipelineOptions {
+    /** 严格模式 */
+    strict?: boolean;
+    /** 是否在第一个错误时停止 */
+    failFast?: boolean;
+    /** 自定义参数 */
+    params?: Record<string, unknown>;
+}
+
+/** 生成唯一节点 ID */
+declare function generateNodeId(): string;
+/** 重置节点 ID 计数器（主要用于测试） */
+declare function resetNodeIdCounter(): void;
+declare function createRoot(type: ExpressionKind, children: ExpressionNode[], metadata?: ExpressionMetadata): ExpressionRoot;
+declare function createSymbol(value: string, symbolType: SymbolType): SymbolNode;
+declare function createFraction(numerator: ExpressionNode, denominator: ExpressionNode): FractionNode;
+declare function createScript(base: ExpressionNode, options?: {
+    sub?: ExpressionNode;
+    super?: ExpressionNode;
+}): ScriptNode;
+declare function createRadical(radicand: ExpressionNode, index?: ExpressionNode): RadicalNode;
+declare function createDelimiter(left: string, right: string, body: ExpressionNode): DelimiterNode;
+declare function createMatrix(rows: ExpressionNode[][], options?: {
+    columnAlign?: ('l' | 'c' | 'r')[];
+    matrixType?: 'matrix' | 'pmatrix' | 'bmatrix' | 'Bmatrix' | 'vmatrix' | 'Vmatrix';
+}): MatrixNode;
+declare function createText(content: string): TextNode;
+declare function createSpace(width: number): SpaceNode;
+declare function createAccent(accentType: AccentNode['accentType'], base: ExpressionNode): AccentNode;
+declare function createLargeOp(opType: LargeOpNode['opType'], body?: ExpressionNode, options?: {
+    lower?: ExpressionNode;
+    upper?: ExpressionNode;
+}): LargeOpNode;
+declare function createColor(color: string, body: ExpressionNode): ColorNode;
+declare function createGroup(children: ExpressionNode[]): GroupNode;
+declare function createChemElement(symbol: string, options?: {
+    count?: number;
+    isotope?: number;
+    charge?: number;
+    chargeSign?: '+' | '-';
+}): ChemElementNode;
+declare function createChemBond(bondType: ChemBondNode['bondType'], left: ExpressionNode, right: ExpressionNode): ChemBondNode;
+declare function createChemReaction(reactants: ExpressionNode[], products: ExpressionNode[], arrowType: ChemArrowType, conditions?: ExpressionNode): ChemReactionNode;
+declare function createChemGroup(atoms: ChemElementNode[], name?: string): ChemGroupNode;
+/** 深度克隆节点 */
+declare function cloneNode<T extends ExpressionNode>(node: T): T;
+/** 类型守卫：检查节点是否为特定 kind */
+declare function isNodeType<K extends ExpressionNode['kind']>(node: ExpressionNode, kind: K): node is Extract<ExpressionNode, {
+    kind: K;
+}>;
+/** 获取节点下所有子节点的扁平列表 */
+declare function flattenNode(node: ExpressionNode): ExpressionNode[];
+/** 获取节点的直接子节点 */
+declare function getNodeChildren(node: ExpressionNode): ExpressionNode[];
+
+/** AST 遍历器接口（访问者模式） */
+interface ASTVisitor<T = void> {
+    visitRoot?(node: ExpressionRoot): T;
+    visitSymbol?(node: SymbolNode): T;
+    visitFraction?(node: FractionNode): T;
+    visitScript?(node: ScriptNode): T;
+    visitRadical?(node: RadicalNode): T;
+    visitDelimiter?(node: DelimiterNode): T;
+    visitMatrix?(node: MatrixNode): T;
+    visitText?(node: TextNode): T;
+    visitSpace?(node: SpaceNode): T;
+    visitAccent?(node: AccentNode): T;
+    visitLargeOp?(node: LargeOpNode): T;
+    visitColor?(node: ColorNode): T;
+    visitGroup?(node: GroupNode): T;
+    visitChemElement?(node: ChemElementNode): T;
+    visitChemBond?(node: ChemBondNode): T;
+    visitChemReaction?(node: ChemReactionNode): T;
+    visitChemGroup?(node: ChemGroupNode): T;
+    /** 默认处理（未匹配到特定 visitor 时调用） */
+    visitDefault?(node: ExpressionNode): T;
+}
+/** AST 遍历选项 */
+interface TraverseOptions {
+    /** 遍历顺序：'pre' 先访问父节点再子节点，'post' 先子节点后父节点 */
+    order?: 'pre' | 'post';
+}
+/**
+ * 遍历 AST（深度优先）
+ */
+declare function traverseAST<T = void>(node: ExpressionNode, visitor: ASTVisitor<T>, options?: TraverseOptions): T | undefined;
+/**
+ * 在 AST 中收集所有满足条件的节点
+ */
+declare function collectNodes<T extends ExpressionNode = ExpressionNode>(root: ExpressionNode, predicate: (node: ExpressionNode) => boolean): T[];
+/**
+ * 在 AST 中查找第一个满足条件的节点
+ */
+declare function findNode<T extends ExpressionNode = ExpressionNode>(root: ExpressionNode, predicate: (node: ExpressionNode) => boolean): T | undefined;
+/**
+ * 计算 AST 中节点的总数
+ */
+declare function countNodes(root: ExpressionNode): number;
+
+/**
+ * 序列化 AST 为 JSON 字符串
+ */
+declare function serializeAST(root: ExpressionRoot): string;
+/**
+ * 从 JSON 字符串反序列化为 AST
+ * @throws 如果 JSON 格式无效
+ */
+declare function deserializeAST(json: string): ExpressionRoot;
+/**
+ * 安全反序列化（不抛异常）
+ */
+declare function safeDeserializeAST(json: string): ExpressionRoot | null;
+/**
+ * AST 简化输出（压缩 JSON）
+ */
+declare function serializeASTCompact(root: ExpressionRoot): string;
+/**
+ * AST 美化输出
+ */
+declare function serializeASTPretty(root: ExpressionRoot): string;
+
+/**
+ * 表达式分类器
+ * 根据 AST 内容自动判定表达式类型
+ */
+declare class ExpressionClassifier {
+    /**
+     * 分类表达式
+     */
+    classify(root: ExpressionRoot): ExpressionKind;
+    /**
+     * 检测是否包含化学相关节点
+     */
+    hasChemistryNodes(root: ExpressionRoot): boolean;
+    /**
+     * 检测是否包含数学相关节点
+     */
+    hasMathNodes(root: ExpressionRoot): boolean;
+    /**
+     * 检测是否为 display 模式（块级公式）
+     */
+    isDisplayMode(root: ExpressionRoot): boolean;
+}
+
+export { type ASTNode, type ASTVisitor, type AccentNode, type ChemArrowType, type ChemBondNode, type ChemElementNode, type ChemGroupNode, type ChemReactionNode, type ColorNode, type DelimiterNode, ExpressionClassifier, ExpressionKind, type ExpressionMetadata, type ExpressionNode, type ExpressionRoot, type FractionNode, type GroupNode, type IValidator, type LargeOpNode, type MatrixNode, type NodeByKind, type PipelineContext, type PipelineError, type PipelineOptions, type PipelineStage, type RadicalNode, type ScriptNode, type SourceLocation, type SpaceNode, type SymbolNode, SymbolType, type TextNode, type TraverseOptions, type ValidationError, ValidationErrorCode, type ValidationResult, type ValidationWarning, cloneNode, collectNodes, countNodes, createAccent, createChemBond, createChemElement, createChemGroup, createChemReaction, createColor, createDelimiter, createFraction, createGroup, createLargeOp, createMatrix, createRadical, createRoot, createScript, createSpace, createSymbol, createText, deserializeAST, findNode, flattenNode, generateNodeId, getNodeChildren, isNodeType, resetNodeIdCounter, safeDeserializeAST, serializeAST, serializeASTCompact, serializeASTPretty, traverseAST };