@isdk/mdast-plus 0.1.2 → 0.1.3

package/README.cn.md

@@ -11,7 +11,7 @@
 ## 特性
 
 - **Fluent API**: 链式调用接口 `mdast(input).use(plugin).toHTML()`。
-- **分阶段插件**: 将转换组织为 `normalize`、`compile` 和 `finalize` 阶段，支持优先级排序。
+- **分阶段插件**: 将转换组织为 `parse`, `normalize`, `compile`, `finalize` 和 `stringify` 阶段。
 - **语义化规范**:
   - **指令 (Directives)**: 规范化提示框 (Admonition) 名称并从标签中提取标题。
   - **表格跨行/跨列**: 支持 HTML 输出中的 `rowspan` 和 `colspan`。
@@ -40,6 +40,17 @@ const html = await mdast(':::warning[重要提示]\n请小心！\n:::')
 // 结果: <div title="重要提示" class="warning"><p>请小心！</p></div>
 ```
 
+### 配置输入选项
+
+您可以通过 `.from()` 的第二个参数向输入插件（如 `remark-gfm` 或 `remark-parse`）传递选项：
+
+```typescript
+// 启用单个波浪线删除线 (~text~)
+const md = await mdast('Hello ~world~')
+  .from('markdown', { remarkGfm: { singleTilde: true } })
+  .toMarkdown();
+```
+
 ### 图片尺寸
 
 ```typescript
@@ -50,8 +61,11 @@ const html = await mdast('![Cat](cat.png#=500x300)').toHTML();
 ### AST 输出
 
 ```typescript
+// 获取处理后的完整 AST (在 normalization 之后)
 const ast = await mdast('==高亮内容==').toAST();
-// 返回 mdast Root 对象
+
+// 获取原始 AST (在 parse 之后, normalization 之前)
+const rawAst = await mdast('==高亮内容==').toAST({ stage: 'parse' });
 ```
 
 ### 高级工作流
@@ -59,31 +73,49 @@ const ast = await mdast('==高亮内容==').toAST();
 ```typescript
 const { content, assets } = await mdast(myInput)
   .data({ myGlobal: 'value' })
-  .use({
-    name: 'my-plugin',
-    stage: 'compile',
-    transform: async (tree) => {
-      // 转换 AST
-    }
-  })
+  // 在 'compile' 阶段添加自定义插件
+  .useAt('compile', myPlugin, { option: 1 })
+  .priority(10) // 比默认插件更晚执行
   .to('html');
 ```
 
+### 插件行为
+
+`mdast-plus` 内部使用 [unified](https://github.com/unifiedjs/unified)。如果您多次添加同一个插件函数，最后的配置将**覆盖**之前的配置。
+
+```typescript
+// 插件将只执行一次，且选项为: 2
+pipeline.use(myPlugin, { option: 1 });
+pipeline.use(myPlugin, { option: 2 });
+```
+
+若要多次运行相同的插件逻辑（例如用于不同目的），请提供不同的函数引用：
+
+```typescript
+// 插件将执行两次
+pipeline.use(myPlugin, { option: 1 });
+pipeline.use(myPlugin.bind({}), { option: 2 });
+```
+
 ### 任意格式支持
 
 您可以注册自定义的输入或输出格式：
 
 ```typescript
-import { FluentProcessor, mdast } from '@isdk/mdast-plus';
+import { MdastPipeline, mdast, PipelineStage } from '@isdk/mdast-plus';
 
 // 注册自定义输出格式
-FluentProcessor.registerFormat('reverse', {
-  stringify: (p) => {
-    p.Compiler = (tree) => {
-      // 您的自定义序列化逻辑
-      return '...';
-    };
-  }
+MdastPipeline.register({
+  id: 'reverse',
+  output: [{
+    plugin: function() {
+      this.Compiler = (tree) => {
+        // 您的自定义序列化逻辑
+        return '...';
+      };
+    },
+    stage: PipelineStage.stringify
+  }]
 });
 
 const result = await mdast('Hello').to('reverse');
@@ -95,9 +127,11 @@ const result = await mdast('Hello').to('reverse');
 
 插件根据它们的 `stage` (阶段) 和 `order` (顺序) 执行：
 
-1.  **normalize** (order 0-100): 清理并规范化树。
-2.  **compile** (order 0-100): 高级语义转换。
-3.  **finalize** (order 0-100): 输出前的最后准备。
+1.  **parse** (0): 输入解析 (例如 `remark-parse`)。
+2.  **normalize** (100): 清理并规范化树。
+3.  **compile** (200): 高级语义转换。
+4.  **finalize** (300): 输出前的最后准备 (例如 `rehype-sanitize`)。
+5.  **stringify** (400): 输出生成。
 
 ## 内置核心插件
 

package/README.md

@@ -11,7 +11,7 @@ English | [简体中文](./README.cn.md) | [GitHub](https://github.com/isdk/mdas
 ## Features
 
 - **Fluent API**: Chainable interface `mdast(input).use(plugin).toHTML()`.
-- **Staged Plugins**: Organize transformations into `normalize`, `compile`, and `finalize` stages with priority ordering.
+- **Staged Plugins**: Organize transformations into `parse`, `normalize`, `compile`, `finalize`, and `stringify` stages.
 - **Semantic Normalization**:
   - **Directives**: Canonicalizes admonition names and extracts titles from labels.
   - **Table Spans**: Support for `rowspan` and `colspan` in HTML output.
@@ -40,6 +40,17 @@ const html = await mdast(':::warning[Special Note]\nBe careful!\n:::')
 // Result: <div title="Special Note" class="warning"><p>Be careful!</p></div>
 ```
 
+### Configure Input Options
+
+You can pass options to input plugins (like `remark-gfm` or `remark-parse`) using the second argument of `.from()`:
+
+```typescript
+// Enable single tilde strikethrough (~text~)
+const md = await mdast('Hello ~world~')
+  .from('markdown', { remarkGfm: { singleTilde: true } })
+  .toMarkdown();
+```
+
 ### Image Sizing
 
 ```typescript
@@ -50,8 +61,11 @@ const html = await mdast('![Cat](cat.png#=500x300)').toHTML();
 ### AST Output
 
 ```typescript
+// Get the fully processed AST (after normalization)
 const ast = await mdast('==Highlighted==').toAST();
-// Returns the mdast Root object
+
+// Get the raw AST (after parsing, before normalization)
+const rawAst = await mdast('==Highlighted==').toAST({ stage: 'parse' });
 ```
 
 ### Advanced Pipeline
@@ -59,31 +73,49 @@ const ast = await mdast('==Highlighted==').toAST();
 ```typescript
 const { content, assets } = await mdast(myInput)
   .data({ myGlobal: 'value' })
-  .use({
-    name: 'my-plugin',
-    stage: 'compile',
-    transform: async (tree) => {
-      // transform the AST
-    }
-  })
+  // Add a custom plugin at the 'compile' stage
+  .useAt('compile', myPlugin, { option: 1 })
+  .priority(10) // Run later than default plugins
   .to('html');
 ```
 
+### Plugin Behavior
+
+`mdast-plus` uses [unified](https://github.com/unifiedjs/unified) internally. If you add the same plugin function multiple times, the last configuration **overrides** the previous ones.
+
+```typescript
+// The plugin will run ONCE with option: 2
+pipeline.use(myPlugin, { option: 1 });
+pipeline.use(myPlugin, { option: 2 });
+```
+
+To run the same plugin logic multiple times (e.g., for different purposes), provide a distinct function reference:
+
+```typescript
+// The plugin will run TWICE
+pipeline.use(myPlugin, { option: 1 });
+pipeline.use(myPlugin.bind({}), { option: 2 });
+```
+
 ### Arbitrary Formats
 
 You can register custom input or output formats:
 
 ```typescript
-import { FluentProcessor, mdast } from '@isdk/mdast-plus';
+import { MdastPipeline, mdast, PipelineStage } from '@isdk/mdast-plus';
 
 // Register a custom output format
-FluentProcessor.registerFormat('reverse', {
-  stringify: (p) => {
-    p.Compiler = (tree) => {
-      // your custom stringification logic
-      return '...';
-    };
-  }
+MdastPipeline.register({
+  id: 'reverse',
+  output: [{
+    plugin: function() {
+      this.Compiler = (tree) => {
+        // your custom stringification logic
+        return '...';
+      };
+    },
+    stage: PipelineStage.stringify
+  }]
 });
 
 const result = await mdast('Hello').to('reverse');
@@ -95,9 +127,11 @@ const result = await mdast('Hello').to('reverse');
 
 Plugins are executed based on their `stage` and `order`:
 
-1.  **normalize** (order 0-100): Cleanup and canonicalize the tree.
-2.  **compile** (order 0-100): High-level semantic transformations.
-3.  **finalize** (order 0-100): Final preparation before output.
+1.  **parse** (0): Input parsing (e.g., `remark-parse`).
+2.  **normalize** (100): Cleanup and canonicalize the tree.
+3.  **compile** (200): High-level semantic transformations.
+4.  **finalize** (300): Final preparation before output (e.g. `rehype-sanitize`).
+5.  **stringify** (400): Output generation.
 
 ## Core Plugins Included
 

package/dist/index.d.mts

@@ -1,3 +1,6 @@
+import { Plugin, Processor } from 'unified';
+import { VFileCompatible, VFile } from 'vfile';
+
 // ## Interfaces
 
 /**
@@ -1141,81 +1144,88 @@ interface Properties {
 }
 
 /**
- * Stages for mdast-plus pipeline processing.
- */
-type Stage = 'normalize' | 'compile' | 'finalize';
+ * PipelineStage defines the execution order of plugins in the processing pipeline.
+ * Plugins are sorted and executed in ascending order based on these stage values.
+ */
+declare enum PipelineStage {
+    /** Initial stage for parsing raw input (e.g., string to AST). */
+    parse = 0,
+    /** Normalization stage for cleaning up and canonicalizing the AST (e.g., GFM, Directives). */
+    normalize = 100,
+    /** Transformation stage for semantic changes and custom high-level logic. */
+    compile = 200,
+    /** Finalization stage for preparing the AST for output (e.g., Sanitize, bridge to HAST). */
+    finalize = 300,
+    /** Final stage for serializing the AST to the target format result. */
+    stringify = 400
+}
+/** The default stage assigned to a plugin if none is specified. */
+declare const DefaultPipelineStage = PipelineStage.compile;
+/** String names corresponding to the PipelineStage levels. */
+type PipelineStageName = keyof typeof PipelineStage;
 /**
- * Definition for an mdast plugin.
+ * Configuration for a plugin within the mdast-plus pipeline.
+ * It wraps a standard unified plugin with execution metadata.
  */
 interface MdastPlugin {
-    /** Plugin name */
-    name: string;
-    /** Processing stage the plugin belongs to */
-    stage?: Stage;
-    /** Execution order within the stage (lower numbers run first) */
+    /**
+     * Optional name for the plugin.
+     * Used for identification in overrides and logging.
+     * If not provided, defaults to the plugin function's name.
+     */
+    name?: string;
+    /** The standard unified plugin (attacher) function. */
+    plugin: Plugin<any[], any, any>;
+    /**
+     * Arguments passed to the plugin.
+     * MUST be an array of arguments (e.g., [optionsObject]).
+     */
+    options?: any[];
+    /** The stage in which this plugin should run. */
+    stage?: PipelineStage | PipelineStageName;
+    /** Execution priority within the same stage. Lower values run earlier. */
     order?: number;
-    /** Transformation function */
-    transform: (tree: Root, ctx: any) => Promise<void> | void;
 }
 /**
- * Definition for an mdast format (parser/stringifier).
- */
-interface MdastFormatDefinition {
-    /** Function to register parser plugins */
-    parse?: (processor: any) => void;
-    /** Function to register stringifier plugins */
-    stringify?: (processor: any) => void;
-}
-/**
- * Represents an asset (e.g., image) extracted during processing.
- */
-interface MdastAsset {
-    /** Relative path or identifier for the asset */
-    path: string;
-    /** MIME type of the asset */
-    contentType: string;
-    /** Raw content as bytes */
-    bytes: Uint8Array;
-}
-/**
- * Result of a conversion process.
- * @template T - The type of the main content (default: string)
- */
-interface ConvertResult<T = string> {
-    /** The converted content */
-    content: T;
-    /** Extracted assets */
-    assets: MdastAsset[];
+ * Defines a document format, encompassing its input (parsing) and output (serialization) strategies.
+ */
+interface MdastFormat {
+    /** Unique identifier for the format (e.g., 'markdown', 'html'). */
+    id: string;
+    /** Human-readable title. */
+    title?: string;
+    /** File extensions associated with this format. */
+    extensions?: string[];
+    /** MIME types associated with this format. */
+    mediaTypes?: string[];
+    /** Plugins used for reading this format into a standard AST (Parser + Normalizer). */
+    input?: MdastPlugin[];
+    /** Plugins used for serializing the AST into this format (Finalizer + Stringifier). */
+    output?: MdastPlugin[];
 }
 /**
- * Original metadata for a node.
+ * Metadata capturing the origin of a node during conversion.
  */
 interface MdastDataOrigin {
-    /** Source format */
+    /** The original source format. */
     format: 'docx' | 'notion' | 'html' | 'markdown' | 'latex' | string;
-    /** Raw data from the source */
+    /** The raw content from the source before conversion. */
     raw?: unknown;
-    /** Hash of the source content */
+    /** Hash used for caching or change detection. */
     hash?: string;
     [k: string]: unknown;
 }
-/**
- * mdast node for highlighted text (mark).
- */
+/** Represents a highlighted text (mark) node in mdast. */
 interface MdastMark extends Parent$1 {
     type: 'mark';
     children: PhrasingContent[];
 }
-/**
- * mdast node for subscript text.
- */
+/** Represents a subscript text node in mdast. */
 interface MdastSub extends Parent$1 {
     type: 'sub';
     children: PhrasingContent[];
 }
-/**
- * mdast node for superscript text.
- */
+/** Represents a superscript text node in mdast. */
 interface MdastSup extends Parent$1 {
     type: 'sup';
     children: PhrasingContent[];
@@ -1249,128 +1259,172 @@ declare module 'mdast' {
         sup: MdastSup;
     }
 }
+
 /**
- * Interface for reading input into an mdast tree.
- * @template I - Input type
+ * Base implementation of the fluent mdast processing pipeline.
+ * Manages the plugin registry and the execution queue.
  */
-interface MdastReader<I> {
+declare class MdastBasePipeline {
+    private static readonly registry;
     /**
-     * Reads input and returns an mdast Root node.
-     * @param input - The input to read
+     * Registers a global document format.
+     * @param format - The format definition to register.
      */
-    read(input: I): Promise<Root>;
-}
-/**
- * Interface for transforming an mdast tree.
- */
-interface MdastTransformer {
+    static register(format: MdastFormat): void;
     /**
-     * Transforms the given mdast tree.
-     * @param tree - The Root node to transform
+     * Retrieves a registered format by its ID.
+     * @param id - The format identifier.
+     * @returns The format definition or undefined if not found.
      */
-    transform(tree: Root): Promise<{
-        tree: Root;
-        assets?: MdastAsset[];
-    }>;
-}
-/**
- * Interface for writing an mdast tree to an output format.
- * @template Output - Output type (default: string)
- */
-interface MdastWriter<Output = string> {
+    static getFormat(id: string): MdastFormat | undefined;
+    protected input: VFileCompatible;
+    protected queue: MdastPlugin[];
     /**
-     * Writes the mdast tree to the target output.
-     * @param tree - The Root node to write
-     * @param assets - Optional assets to include
+     * Initializes a new pipeline instance with the given input.
+     * @param input - Content to process (string, Buffer, VFile, or AST Node).
      */
-    write(tree: Root, assets?: MdastAsset[]): Promise<ConvertResult<Output>>;
-}
-
-/**
- * Fluent processor for mdast transformations.
- * Allows chaining configuration and finally converting to a target format.
- */
-declare class FluentProcessor {
-    /** Map of registered format definitions */
-    static formats: Record<string, MdastFormatDefinition>;
+    constructor(input: VFileCompatible);
     /**
-     * Registers a new format definition.
-     * @param name - The name of the format (e.g., 'docx')
-     * @param definition - The format definition containing parse/stringify logic
+     * Instance-level access to the global format registry.
      */
-    static registerFormat(name: string, definition: MdastFormatDefinition): void;
-    private processor;
-    private input;
-    private inputFormat;
-    private plugins;
-    private globalData;
+    getFormat(id: string): MdastFormat | undefined;
     /**
-     * Creates a new FluentProcessor instance.
-     * @param input - The input content (string or mdast tree)
+     * Resolves a format identifier or object to a valid MdastFormat.
+     * @private
      */
-    constructor(input: any);
+    private resolveFormat;
     /**
-     * Specifies the input format.
-     * @param format - The input format name (default: 'markdown')
+     * Normalizes a plugin entry for runtime execution.
+     * @protected
      */
-    from(format: string): this;
+    protected toRuntimeEntry(entry: MdastPlugin, defaultStage: PipelineStage, overrides?: Record<string, any>): MdastPlugin & {
+        stage: PipelineStage;
+    };
     /**
-     * Adds a plugin to the processing pipeline.
-     * @param plugin - The mdast plugin to use
+     * Ensures that input plugins (parser, normalizers) are present in the queue.
+     * Adds implicit plugins if no parser is detected.
+     * @protected
      */
-    use(plugin: MdastPlugin): this;
+    protected ensureInputPlugins(queue: MdastPlugin[], overrides?: Record<string, any>, maxStage?: PipelineStage): void;
     /**
-     * Merges global data into the processor.
-     * @param data - Key-value pairs to store in global data
+     * Configures the input format and adds its associated plugins to the pipeline.
+     * @param fmt - Format ID or definition.
+     * @param overrides - Optional map to override plugin options by plugin name.
+     * @returns The pipeline instance for chaining.
      */
-    data(data: Record<string, any>): this;
+    from(fmt: string | MdastFormat, overrides?: Record<string, any>): this;
     /**
-     * Converts the input content to the specified format.
-     * @param format - The output format name
-     * @returns A promise resolving to the conversion result (content and assets)
+     * Processes the pipeline and serializes the result into the specified format.
+     * @param fmt - Target format ID or definition.
+     * @param overrides - Optional map to override plugin options.
+     * @returns A promise resolving to a VFile containing the result.
      */
-    to(format: string): Promise<ConvertResult>;
+    to(fmt: string | MdastFormat, overrides?: Record<string, any>): Promise<VFile>;
+    /**
+     * Adds a plugin to the pipeline's compile stage.
+     * @param plugin - The unified plugin function.
+     * @param options - Arguments for the plugin.
+     * @returns The pipeline instance for chaining.
+     */
+    use(plugin: any, ...options: any[]): this;
+    /**
+     * Adds a plugin to the pipeline at a specific stage.
+     * @param stage - The stage name or numeric value.
+     * @param plugin - The unified plugin function.
+     * @param options - Arguments for the plugin.
+     * @returns The pipeline instance for chaining.
+     */
+    useAt(stage: PipelineStageName, plugin: any, ...options: any[]): this;
+    /**
+     * Sets the priority order for the most recently added plugin.
+     * Plugins with lower order run earlier within the same stage.
+     * @param order - Numeric priority.
+     * @returns The pipeline instance for chaining.
+     */
+    priority(order: number): this;
+    /**
+     * Assembles a unified processor based on the sorted plugin queue.
+     * @protected
+     */
+    protected assembleProcessor(queue: MdastPlugin[]): Processor;
+}
+/**
+ * Extended pipeline with convenience methods for common formats.
+ */
+declare class MdastPipeline extends MdastBasePipeline {
     /**
-     * Helper to convert content to Markdown.
-     * @returns A promise resolving to the Markdown string
+     * Finalizes the pipeline and returns the result as a Markdown string.
      */
     toMarkdown(): Promise<string>;
     /**
-     * Helper to convert content to HTML.
-     * @returns A promise resolving to the HTML string
+     * Finalizes the pipeline and returns a VFile containing the Markdown result.
      */
-    toHTML(): Promise<string>;
+    toMarkdownVFile(): Promise<VFile>;
+    /**
+     * Finalizes the pipeline and returns the result as an HTML string.
+     */
+    toHtml(): Promise<string>;
+    /**
+     * Finalizes the pipeline and returns a VFile containing the HTML result.
+     */
+    toHtmlVFile(): Promise<VFile>;
     /**
-     * Helper to get the processed mdast tree.
-     * @returns A promise resolving to the mdast Root node
+     * Finalizes the pipeline and returns the resulting AST (Root node).
+     * @param options - Configuration for the extraction.
+     * @param options.stage - Run the pipeline up to this stage only.
+     * @param options.overrides - Map for plugin option overrides.
      */
-    toAST(): Promise<Root>;
+    toAst(options?: {
+        stage?: PipelineStageName;
+        overrides?: Record<string, any>;
+    }): Promise<Root>;
+    /** Alias for toHtml() */
+    toHTML(): Promise<string>;
+    /** Alias for toAst() */
+    toAST(options?: {
+        stage?: PipelineStageName;
+        overrides?: Record<string, any>;
+    }): Promise<Root>;
 }
 /**
  * Entry point for the fluent mdast-plus API.
  * @param input - The input content (string or mdast tree)
  * @returns A FluentProcessor instance
  */
-declare function mdast(input: any): FluentProcessor;
+declare function mdast(input: VFileCompatible): MdastPipeline;
 
 /**
- * Common remark configuration for Markdown.
+ * Markdown format definition.
+ *
+ * Supports GFM, Directives, Math, and Frontmatter.
+ * Provides a bidirectional mapping between Markdown strings and mdast-plus ASTs.
  */
-declare function markdownCommon(this: any): void;
+declare const markdownFormat: MdastFormat;
+
 /**
- * Markdown format definition for FluentProcessor.
- * Handles both parsing (Markdown -> MDAST) and stringifying (MDAST -> Markdown).
+ * HTML format definition.
+ *
+ * Provides a bidirectional mapping between HTML strings and mdast-plus ASTs.
+ * Includes built-in sanitization and support for table spans and image dimensions.
  */
-declare const markdownFormat: MdastFormatDefinition;
+declare const htmlFormat: MdastFormat;
 
 /**
- * Standard compiler/stringifier for HTML.
+ * Pass-through compiler that returns the AST as-is.
+ * Essential for unified processes that should output an object (the AST)
+ * instead of a serialized string.
+ */
+declare function astCompiler(this: any): void;
+/**
+ * Parser for stringified JSON AST input.
+ * Allows the pipeline to accept a JSON string and treat it as a unist tree.
  */
-declare function htmlStringify(this: any): void;
+declare function jsonParser(this: any): void;
 /**
- * HTML format definition for FluentProcessor.
- * Handles both parsing (HTML -> MDAST) and stringifying (MDAST -> HTML).
+ * AST (MDAST) format definition.
+ * Supports reading from JSON strings and provides full normalization
+ * through the standard mdast-plus plugin set.
  */
-declare const htmlFormat: MdastFormatDefinition;
+declare const astFormat: MdastFormat;
 
-export { type ConvertResult, FluentProcessor, type MdastAsset, type MdastDataOrigin, type MdastFormatDefinition, type MdastMark, type MdastPlugin, type MdastReader, type MdastSub, type MdastSup, type MdastTransformer, type MdastWriter, type Stage, htmlFormat, htmlStringify, markdownCommon, markdownFormat, mdast };
+export { DefaultPipelineStage, MdastBasePipeline, type MdastDataOrigin, type MdastFormat, type MdastMark, MdastPipeline, type MdastPlugin, type MdastSub, type MdastSup, PipelineStage, type PipelineStageName, astCompiler, astFormat, htmlFormat, jsonParser, markdownFormat, mdast };