Blocks

A high-performance Rust library for block-based content editing with bidirectional conversion between JSON, Markdown, HTML, and Plain Text.

Overview

Blocks is designed as a backend engine for block-based content editors (like Notion, Editor.js, or TinyMCE). It provides a type-safe, validated block system with efficient conversions and advanced features like diff/merge, statistics, history management, and content sanitization.

Key Features

• 🔄 Bidirectional Conversions: JSON ↔ Markdown ↔ HTML ↔ Blocks
• 🛡️ Security: XSS prevention, HTML sanitization, URL validation
• ⚡ Performance: Sub-microsecond operations, zero-copy where possible
• 🧪 Tested: 173 tests (158 unit + 15 doc), property-based testing
• 🏗️ Builder Pattern: Fluent API for document creation
• 📊 Analytics: Word count, reading time, complexity scores
• 🔀 Diff & Merge: Document comparison with merge strategies
• ⏪ History: Undo/redo with operation tracking
• 💾 Caching: LRU cache with TTL for conversions
• 🔌 Extensible: Plugin system for custom processing

Quick Start

Add to your Cargo.toml:

[dependencies]
blocks = "0.1.0"

Basic Usage

use blocks::{Document, Block, BlockType};

// Create a document
let mut doc = Document::with_title("My Document".to_string());
doc.add_block(Block::new(BlockType::Text, "Hello, world!".to_string()));

// Convert to different formats
let json = doc.to_json()?;          // JSON
let markdown = doc.to_markdown()?;  // Markdown
let html = doc.to_html()?;          // HTML
let plain = doc.to_plain_text()?;   // Plain text

// Parse from formats
let doc = Document::from_json(&json)?;
let doc = Document::from_markdown(&markdown)?;
let doc = Document::from_html(&html)?;

Builder Pattern

use blocks::{DocumentBuilder, BlockBuilder};

let doc = DocumentBuilder::new("My Article")
    .with_block(BlockBuilder::header(1, "Introduction")?.build())
    .with_block(BlockBuilder::text("Welcome!").build())
    .with_block(BlockBuilder::code("fn main() {}", Some("rust".to_string())).build())
    .with_metadata("author", "John Doe")
    .build();

JSON API for Editor Backends

use blocks::{Document, Block};

// Parse JSON from frontend
let doc = Document::from_json(r#"{"title":"Doc","blocks":[...]}"#)?;

// Process and return
let response = doc.to_json_pretty()?;

// Single block operations
let block = Block::from_json(r#"{"block_type":"Text",...}"#)?;
let result = block.to_json()?;

// Batch operations
let blocks = blocks::Converter::blocks_from_json("[...]")?;

Supported Block Types

Features

Features

Core Functionality

• 14 Block Types: Text, headers, lists, code, quotes, links, images, tables, dividers, embeds, buttons, callouts, columns, details
• Type Safety: Fully typed with Rust's type system
• Validation: Comprehensive validation with detailed error messages
• Metadata: Flexible key-value metadata on blocks and documents
• UUIDs: Unique identifiers for all entities

Conversions

Security

• HTML Escaping: Automatic escaping of special characters
• XSS Prevention: Content sanitizer with normal/strict modes
• URL Validation: Safe URL checking for links and embeds
• Script Removal: Strips dangerous HTML elements and attributes

Advanced Features

• Builder API: Fluent interface for document creation
• Statistics: Word count, reading time, complexity analysis
• Diff & Merge: Compare documents, detect changes, merge strategies
• History: Undo/redo with operation tracking
• Caching: LRU cache with TTL for conversion results
• Pipeline: Composable middleware for content processing
• Plugins: Extensible system for custom validators and transformers

Performance

Examples

Document Statistics

use blocks::DocumentStats;

let stats = DocumentStats::from_document(&doc);
println!("Words: {}", stats.total_words);
println!("Reading time: {:.1} min", stats.reading_time_mins);
println!("Complexity: {}/100", stats.complexity_score);

Pipeline Processing

use blocks::{BlockPipeline, block_middlewares};

let pipeline = BlockPipeline::new()
    .add_middleware(block_middlewares::trim_content())
    .add_middleware(block_middlewares::lowercase())
    .add_middleware(block_middlewares::max_length(100));

let mut block = Block::new(BlockType::Text, "  HELLO  ".to_string());
pipeline.process(&mut block)?;

History Management

use blocks::{HistoryManager, DocumentOperation};

let mut history = HistoryManager::new(50);
history.record(DocumentOperation::AddBlock { block, index: 0 });

if let Some(op) = history.undo() {
    // Apply undo operation
}

Document Diff

use blocks::DocumentDiffer;

let diff = DocumentDiffer::diff(&doc1, &doc2);
println!("Changes: {}", diff.changes.len());

Project Structure

blocks/
├── src/
│   ├── lib.rs          # Entry point and re-exports
│   ├── block.rs        # Block types and validation
│   ├── document.rs     # Document container
│   ├── converters.rs   # Format converters (MD, HTML, JSON, PlainText)
│   ├── error.rs        # Error handling
│   ├── builders.rs     # Fluent builder API
│   ├── sanitizer.rs    # XSS prevention & sanitization
│   ├── history.rs      # Undo/redo functionality
│   ├── cache.rs        # Conversion caching
│   ├── plugins.rs      # Plugin system
│   ├── pipeline.rs     # Middleware processing
│   ├── diff.rs         # Document comparison
│   └── stats.rs        # Document statistics
├── examples/
│   ├── file_ops.rs     # File I/O operations
│   └── json_api.rs     # Backend API patterns
├── testdata/
│   ├── sample.json     # Sample JSON document
│   ├── sample.md       # Sample Markdown document
│   └── sample.html     # Sample HTML document
└── benches/
    └── conversion_bench.rs # Performance benchmarks

Dependencies

Testing

• 173 tests (158 unit + 15 doc tests)
• Property-based testing with proptest
• Roundtrip tests for format conversions
• Integration tests for end-to-end workflows
• Test data files in multiple formats

Run tests:

cargo test

Run benchmarks:

cargo bench

Generate documentation:

cargo doc --open

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for version history and changes.

Links

• Documentation
• Crates.io
• Repository
• Issues