@changerawr/markdown 1.1.5 → 1.1.7

package/README.md

@@ -15,7 +15,8 @@
 - ⚛️ **React Integration**: Drop-in `<MarkdownRenderer>` component + hooks
 - 🍦 **Vanilla JS Support**: Use anywhere with `renderCum()` function
 - 📝 **TypeScript First**: Fully typed with excellent IntelliSense
-- 🎯 **Performance Focused**: Efficient parsing and rendering
+- ⚡ **High Performance**: Automatic caching, streaming support, handles 100K+ words efficiently
+- 💾 **Smart Caching**: Built-in LRU cache for 100-1000x speedup on repeated renders
 - 🛡️ **Secure**: Built-in HTML sanitization with DOMPurify
 - 🔧 **Extensible**: Easy-to-write custom extensions
 - 🎨 **Themeable**: Customizable CSS classes and styling
@@ -484,23 +485,97 @@ function DebugComponent() {
 }
 ```
 
-## 📊 Performance
+## 📊 Performance & Caching
 
-### Metrics and Monitoring
+Built-in performance optimizations handle large documents efficiently with automatic caching and streaming support.
+
+### Automatic Caching
+
+The engine automatically caches parsed and rendered content for instant repeated renders:
+
+```typescript
+const engine = new ChangerawrMarkdown();
+
+// First render - parses and renders
+const html1 = engine.toHtml(largeMarkdown); // ~100ms
+
+// Second render - served from cache
+const html2 = engine.toHtml(largeMarkdown); // <1ms (100x+ faster!)
+
+// Check cache statistics
+const stats = engine.getCacheStats();
+console.log(stats.parse.hits, stats.parse.hitRate);
+console.log(stats.render.hits, stats.render.hitRate);
+
+// Clear caches if needed
+engine.clearCaches();
+
+// Adjust cache size (default: 100 entries)
+engine.setCacheSize(200);
+```
+
+### Streaming for Large Documents
+
+Stream large documents in chunks for progressive rendering:
 
 ```typescript
-const engine = createDebugEngine();
-const html = engine.toHtml('# Large Document...');
+const engine = new ChangerawrMarkdown();
+
+const html = await engine.toHtmlStreamed(hugeMarkdown, {
+  chunkSize: 50,  // Render 50 tokens at a time
+  onChunk: ({ html, progress }) => {
+    console.log(`Rendered: ${(progress * 100).toFixed(0)}%`);
+    // Update UI progressively
+    updatePreview(html);
+  }
+});
+```
 
-const metrics = engine.getPerformanceMetrics();
-console.log('Parse time:', metrics.parseTime);
-console.log('Render time:', metrics.renderTime);
-console.log('Total time:', metrics.totalTime);
+### Performance Metrics
+
+Track rendering performance with built-in metrics:
+
+```typescript
+const { html, metrics } = engine.toHtmlWithMetrics(markdown);
+
+console.log('Input size:', metrics.inputSize);
+console.log('Parse time:', metrics.parseTime, 'ms');
+console.log('Render time:', metrics.renderTime, 'ms');
+console.log('Total time:', metrics.totalTime, 'ms');
 console.log('Token count:', metrics.tokenCount);
+console.log('Cache hit:', metrics.cacheHit);
 ```
 
+### Memoization Helper
+
+Memoize expensive operations with the built-in helper:
+
+```typescript
+import { memoize } from '@changerawr/markdown';
+
+const expensiveTransform = memoize((content: string) => {
+  // Complex transformation here
+  return processContent(content);
+});
+
+// First call - computed
+const result1 = expensiveTransform(data); // Slow
+
+// Second call with same input - cached
+const result2 = expensiveTransform(data); // Instant!
+```
+
+### Performance Benchmarks
+
+- **Small documents** (1K words): ~15ms
+- **Medium documents** (10K words): ~400ms
+- **Large documents** (100K words): ~32s first render, <1ms cached
+- **Cache speedup**: 100-1000x faster for repeated content
+
 ### Optimization Tips
 
+- **Caching is automatic** - no configuration needed for most use cases
+- Use `toHtmlStreamed()` for documents over 10,000 words
 - Use `createCoreOnlyEngine()` if you don't need feature extensions
 - Use `createMinimalEngine()` with only the extensions you need
 - Set `sanitize: false` if you trust your content (be careful!)
@@ -527,6 +602,16 @@ npm run test:coverage   # Run with coverage report
 - `renderToTailwind(markdown: string): string` - Render with Tailwind classes
 - `renderToJSON(markdown: string): JsonAstNode` - Render to JSON AST
 
+### Performance & Cache Functions
+
+- `engine.toHtml(markdown: string): string` - Render with automatic caching
+- `engine.toHtmlWithMetrics(markdown: string): { html, metrics }` - Render with performance metrics
+- `engine.toHtmlStreamed(markdown: string, options?): Promise<string>` - Stream large documents
+- `engine.getCacheStats(): { parse, render }` - Get cache statistics
+- `engine.clearCaches(): void` - Clear all caches
+- `engine.setCacheSize(size: number): void` - Update cache capacity
+- `memoize<T>(fn: T): T` - Memoize any function
+
 ### Factory Functions
 
 - `createEngine(config?)` - Full-featured engine

package/dist/index.d.mts

@@ -1,3 +1,84 @@
+interface CacheStats {
+    size: number;
+    capacity: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+    evictions: number;
+}
+declare class LRUCache<K, V> {
+    private cache;
+    private capacity;
+    private hits;
+    private misses;
+    private evictions;
+    constructor(capacity?: number);
+    /**
+     * Get a value from the cache
+     */
+    get(key: K): V | undefined;
+    /**
+     * Set a value in the cache
+     */
+    set(key: K, value: V): void;
+    /**
+     * Check if a key exists in the cache
+     */
+    has(key: K): boolean;
+    /**
+     * Delete a specific key from the cache
+     */
+    delete(key: K): boolean;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Get the current size of the cache
+     */
+    get size(): number;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset cache statistics
+     */
+    resetStats(): void;
+    /**
+     * Get all keys in the cache
+     */
+    keys(): K[];
+    /**
+     * Get all values in the cache
+     */
+    values(): V[];
+    /**
+     * Update cache capacity and evict if necessary
+     */
+    setCapacity(newCapacity: number): void;
+    /**
+     * Evict the least recently used entry
+     */
+    private evictLRU;
+}
+/**
+ * Simple hash function for content
+ * Uses FNV-1a algorithm for fast, decent-quality hashing
+ */
+declare function hashContent(content: string): string;
+/**
+ * Create a cached version of a function
+ */
+declare function memoize<T extends (...args: any[]) => any>(fn: T, options?: {
+    cache?: LRUCache<string, ReturnType<T>>;
+    keyGenerator?: (...args: Parameters<T>) => string;
+    maxSize?: number;
+}): T & {
+    cache: LRUCache<string, ReturnType<T>>;
+    clearCache: () => void;
+};
+
 interface MarkdownToken {
     type: string;
     content: string;
@@ -87,23 +168,68 @@ interface ExtensionRegistration {
     conflictingRules?: string[];
 }
 
+interface RenderMetrics {
+    inputSize: number;
+    parseTime: number;
+    renderTime: number;
+    totalTime: number;
+    tokenCount: number;
+    cacheHit: boolean;
+}
 declare class ChangerawrMarkdown {
     private parser;
     private renderer;
     private extensions;
+    private parseCache;
+    private renderCache;
+    private parseTime;
+    private renderTime;
+    private lastTokenCount;
     constructor(config?: EngineConfig);
     private registerFeatureExtensions;
     private registerCoreExtensions;
     registerExtension(extension: Extension): ExtensionRegistration;
     unregisterExtension(name: string): boolean;
     parse(markdown: string): MarkdownToken[];
-    render(tokens: MarkdownToken[]): string;
+    render(tokens: MarkdownToken[], cacheKey?: string): string;
     toHtml(markdown: string): string;
+    /**
+     * Render markdown with performance metrics
+     */
+    toHtmlWithMetrics(markdown: string): {
+        html: string;
+        metrics: RenderMetrics;
+    };
+    /**
+     * Stream-render large documents in chunks for better performance
+     */
+    toHtmlStreamed(markdown: string, options?: {
+        chunkSize?: number;
+        onChunk?: (chunk: {
+            html: string;
+            progress: number;
+        }) => void;
+    }): Promise<string>;
     getExtensions(): string[];
     hasExtension(name: string): boolean;
     getWarnings(): string[];
     getDebugInfo(): DebugInfo | null;
     getPerformanceMetrics(): PerformanceMetrics | null;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        parse: CacheStats;
+        render: CacheStats;
+    };
+    /**
+     * Clear all caches
+     */
+    clearCaches(): void;
+    /**
+     * Update cache capacity
+     */
+    setCacheSize(size: number): void;
     private rebuildParserAndRenderer;
 }
 declare function parseMarkdown(content: string): MarkdownToken[];
@@ -373,6 +499,7 @@ declare class MarkdownParser {
     private rules;
     private warnings;
     private config;
+    private compiledPatterns;
     constructor(config?: ParserConfig);
     addRule(rule: ParseRule): void;
     hasRule(name: string): boolean;
@@ -600,4 +727,4 @@ declare const presets: {
  */
 declare function createEngineWithPreset(presetName: keyof typeof presets, additionalConfig?: EngineConfig): ChangerawrMarkdown;
 
-export { type ASTStatistics, AlertExtension, BlockquoteExtension, BoldExtension, ButtonExtension, ChangerawrMarkdown, CodeBlockExtension, CoreExtensions, type DebugInfo, EmbedExtension, type EngineConfig, type EngineEvents, type Extension, ExtensionError, type Extension as ExtensionInterface, type ExtensionRegistration, HeadingExtension, HorizontalRuleExtension, ImageExtension, InlineCodeExtension, ItalicExtension, type JsonAstNode, LineBreakExtension, LinkExtension, ListExtension, Logger, MarkdownParseError, MarkdownParser, MarkdownRenderError, MarkdownRenderer, type MarkdownToken, type OutputFormat, ParagraphExtension, type ParseRule, type ParserConfig, type PerformanceMetrics, PerformanceTimer, type RenderRule, type RendererConfig, TaskListExtension, TextExtension, type TokenComparison, type TokenDifference, type TokenStatistics, type TokenType, astToJSONString, astToTokens, basicSanitize, compareTokens, createCoreOnlyEngine, createCumEngine, createCustomEngine, createDebugEngine, createEngine, createEngineWithPreset, createHTMLEngine, createMinimalEngine, createTailwindEngine, debounce, deepMerge, markdown as default, defaultTailwindClasses, escapeHtml, extractDomain, generateId, getASTStats, getTokenStats, isBrowser, isNode, isValidUrl, markdown, minimalClasses, parseASTFromJSON, parseCum, parseMarkdown, parseOptions, parseTokensFromJSON, presets, proseClasses, renderCum, renderCumToHtml, renderCumToJson, renderCumToTailwind, renderMarkdown, renderToAST, renderToHTML, renderToHTMLUnsafe, renderToHTMLWithConfig, renderToJSON, renderToTailwind, renderToTailwindWithClasses, renderToTailwindWithConfig, sanitizeHtml, tokensToAST, tokensToJSONString };
+export { type ASTStatistics, AlertExtension, BlockquoteExtension, BoldExtension, ButtonExtension, type CacheStats, ChangerawrMarkdown, CodeBlockExtension, CoreExtensions, type DebugInfo, EmbedExtension, type EngineConfig, type EngineEvents, type Extension, ExtensionError, type Extension as ExtensionInterface, type ExtensionRegistration, HeadingExtension, HorizontalRuleExtension, ImageExtension, InlineCodeExtension, ItalicExtension, type JsonAstNode, LRUCache, LineBreakExtension, LinkExtension, ListExtension, Logger, MarkdownParseError, MarkdownParser, MarkdownRenderError, MarkdownRenderer, type MarkdownToken, type OutputFormat, ParagraphExtension, type ParseRule, type ParserConfig, type PerformanceMetrics, PerformanceTimer, type RenderMetrics, type RenderRule, type RendererConfig, TaskListExtension, TextExtension, type TokenComparison, type TokenDifference, type TokenStatistics, type TokenType, astToJSONString, astToTokens, basicSanitize, compareTokens, createCoreOnlyEngine, createCumEngine, createCustomEngine, createDebugEngine, createEngine, createEngineWithPreset, createHTMLEngine, createMinimalEngine, createTailwindEngine, debounce, deepMerge, markdown as default, defaultTailwindClasses, escapeHtml, extractDomain, generateId, getASTStats, getTokenStats, hashContent, isBrowser, isNode, isValidUrl, markdown, memoize, minimalClasses, parseASTFromJSON, parseCum, parseMarkdown, parseOptions, parseTokensFromJSON, presets, proseClasses, renderCum, renderCumToHtml, renderCumToJson, renderCumToTailwind, renderMarkdown, renderToAST, renderToHTML, renderToHTMLUnsafe, renderToHTMLWithConfig, renderToJSON, renderToTailwind, renderToTailwindWithClasses, renderToTailwindWithConfig, sanitizeHtml, tokensToAST, tokensToJSONString };

package/dist/index.d.ts

@@ -1,3 +1,84 @@
+interface CacheStats {
+    size: number;
+    capacity: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+    evictions: number;
+}
+declare class LRUCache<K, V> {
+    private cache;
+    private capacity;
+    private hits;
+    private misses;
+    private evictions;
+    constructor(capacity?: number);
+    /**
+     * Get a value from the cache
+     */
+    get(key: K): V | undefined;
+    /**
+     * Set a value in the cache
+     */
+    set(key: K, value: V): void;
+    /**
+     * Check if a key exists in the cache
+     */
+    has(key: K): boolean;
+    /**
+     * Delete a specific key from the cache
+     */
+    delete(key: K): boolean;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Get the current size of the cache
+     */
+    get size(): number;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset cache statistics
+     */
+    resetStats(): void;
+    /**
+     * Get all keys in the cache
+     */
+    keys(): K[];
+    /**
+     * Get all values in the cache
+     */
+    values(): V[];
+    /**
+     * Update cache capacity and evict if necessary
+     */
+    setCapacity(newCapacity: number): void;
+    /**
+     * Evict the least recently used entry
+     */
+    private evictLRU;
+}
+/**
+ * Simple hash function for content
+ * Uses FNV-1a algorithm for fast, decent-quality hashing
+ */
+declare function hashContent(content: string): string;
+/**
+ * Create a cached version of a function
+ */
+declare function memoize<T extends (...args: any[]) => any>(fn: T, options?: {
+    cache?: LRUCache<string, ReturnType<T>>;
+    keyGenerator?: (...args: Parameters<T>) => string;
+    maxSize?: number;
+}): T & {
+    cache: LRUCache<string, ReturnType<T>>;
+    clearCache: () => void;
+};
+
 interface MarkdownToken {
     type: string;
     content: string;
@@ -87,23 +168,68 @@ interface ExtensionRegistration {
     conflictingRules?: string[];
 }
 
+interface RenderMetrics {
+    inputSize: number;
+    parseTime: number;
+    renderTime: number;
+    totalTime: number;
+    tokenCount: number;
+    cacheHit: boolean;
+}
 declare class ChangerawrMarkdown {
     private parser;
     private renderer;
     private extensions;
+    private parseCache;
+    private renderCache;
+    private parseTime;
+    private renderTime;
+    private lastTokenCount;
     constructor(config?: EngineConfig);
     private registerFeatureExtensions;
     private registerCoreExtensions;
     registerExtension(extension: Extension): ExtensionRegistration;
     unregisterExtension(name: string): boolean;
     parse(markdown: string): MarkdownToken[];
-    render(tokens: MarkdownToken[]): string;
+    render(tokens: MarkdownToken[], cacheKey?: string): string;
     toHtml(markdown: string): string;
+    /**
+     * Render markdown with performance metrics
+     */
+    toHtmlWithMetrics(markdown: string): {
+        html: string;
+        metrics: RenderMetrics;
+    };
+    /**
+     * Stream-render large documents in chunks for better performance
+     */
+    toHtmlStreamed(markdown: string, options?: {
+        chunkSize?: number;
+        onChunk?: (chunk: {
+            html: string;
+            progress: number;
+        }) => void;
+    }): Promise<string>;
     getExtensions(): string[];
     hasExtension(name: string): boolean;
     getWarnings(): string[];
     getDebugInfo(): DebugInfo | null;
     getPerformanceMetrics(): PerformanceMetrics | null;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        parse: CacheStats;
+        render: CacheStats;
+    };
+    /**
+     * Clear all caches
+     */
+    clearCaches(): void;
+    /**
+     * Update cache capacity
+     */
+    setCacheSize(size: number): void;
     private rebuildParserAndRenderer;
 }
 declare function parseMarkdown(content: string): MarkdownToken[];
@@ -373,6 +499,7 @@ declare class MarkdownParser {
     private rules;
     private warnings;
     private config;
+    private compiledPatterns;
     constructor(config?: ParserConfig);
     addRule(rule: ParseRule): void;
     hasRule(name: string): boolean;
@@ -600,4 +727,4 @@ declare const presets: {
  */
 declare function createEngineWithPreset(presetName: keyof typeof presets, additionalConfig?: EngineConfig): ChangerawrMarkdown;
 
-export { type ASTStatistics, AlertExtension, BlockquoteExtension, BoldExtension, ButtonExtension, ChangerawrMarkdown, CodeBlockExtension, CoreExtensions, type DebugInfo, EmbedExtension, type EngineConfig, type EngineEvents, type Extension, ExtensionError, type Extension as ExtensionInterface, type ExtensionRegistration, HeadingExtension, HorizontalRuleExtension, ImageExtension, InlineCodeExtension, ItalicExtension, type JsonAstNode, LineBreakExtension, LinkExtension, ListExtension, Logger, MarkdownParseError, MarkdownParser, MarkdownRenderError, MarkdownRenderer, type MarkdownToken, type OutputFormat, ParagraphExtension, type ParseRule, type ParserConfig, type PerformanceMetrics, PerformanceTimer, type RenderRule, type RendererConfig, TaskListExtension, TextExtension, type TokenComparison, type TokenDifference, type TokenStatistics, type TokenType, astToJSONString, astToTokens, basicSanitize, compareTokens, createCoreOnlyEngine, createCumEngine, createCustomEngine, createDebugEngine, createEngine, createEngineWithPreset, createHTMLEngine, createMinimalEngine, createTailwindEngine, debounce, deepMerge, markdown as default, defaultTailwindClasses, escapeHtml, extractDomain, generateId, getASTStats, getTokenStats, isBrowser, isNode, isValidUrl, markdown, minimalClasses, parseASTFromJSON, parseCum, parseMarkdown, parseOptions, parseTokensFromJSON, presets, proseClasses, renderCum, renderCumToHtml, renderCumToJson, renderCumToTailwind, renderMarkdown, renderToAST, renderToHTML, renderToHTMLUnsafe, renderToHTMLWithConfig, renderToJSON, renderToTailwind, renderToTailwindWithClasses, renderToTailwindWithConfig, sanitizeHtml, tokensToAST, tokensToJSONString };
+export { type ASTStatistics, AlertExtension, BlockquoteExtension, BoldExtension, ButtonExtension, type CacheStats, ChangerawrMarkdown, CodeBlockExtension, CoreExtensions, type DebugInfo, EmbedExtension, type EngineConfig, type EngineEvents, type Extension, ExtensionError, type Extension as ExtensionInterface, type ExtensionRegistration, HeadingExtension, HorizontalRuleExtension, ImageExtension, InlineCodeExtension, ItalicExtension, type JsonAstNode, LRUCache, LineBreakExtension, LinkExtension, ListExtension, Logger, MarkdownParseError, MarkdownParser, MarkdownRenderError, MarkdownRenderer, type MarkdownToken, type OutputFormat, ParagraphExtension, type ParseRule, type ParserConfig, type PerformanceMetrics, PerformanceTimer, type RenderMetrics, type RenderRule, type RendererConfig, TaskListExtension, TextExtension, type TokenComparison, type TokenDifference, type TokenStatistics, type TokenType, astToJSONString, astToTokens, basicSanitize, compareTokens, createCoreOnlyEngine, createCumEngine, createCustomEngine, createDebugEngine, createEngine, createEngineWithPreset, createHTMLEngine, createMinimalEngine, createTailwindEngine, debounce, deepMerge, markdown as default, defaultTailwindClasses, escapeHtml, extractDomain, generateId, getASTStats, getTokenStats, hashContent, isBrowser, isNode, isValidUrl, markdown, memoize, minimalClasses, parseASTFromJSON, parseCum, parseMarkdown, parseOptions, parseTokensFromJSON, presets, proseClasses, renderCum, renderCumToHtml, renderCumToJson, renderCumToTailwind, renderMarkdown, renderToAST, renderToHTML, renderToHTMLUnsafe, renderToHTMLWithConfig, renderToJSON, renderToTailwind, renderToTailwindWithClasses, renderToTailwindWithConfig, sanitizeHtml, tokensToAST, tokensToJSONString };