XML API

An XML synchronization engine that maintains full fidelity between source code and the Document Object Model (DOM).

This project provides a foundational XML parser and manipulation API designed for WYSIWYG editors and Integrated Development Environments (IDEs). It features a DOM-compatible interface that bidirectionally synchronizes intuitive application edits and source code modifications, all while preserving details like whitespace and indentation.

Key Features

• Full Fidelity: Edits preserve all whitespace, indentation, and comments automatically in unmodified parts of the code.
• Bidirectional Sync: Instantly synchronizes changes between the source code and the in-memory model, ensuring consistent state across operations.
• DOM Compatibility: Provides a familiar interface (Element, Document, setAttribute, etc.) for intuitive application development.
• Incremental Updates: High performance through incremental parsing and minimal text patching.

Architecture

The system is built on a robust synchronization engine orchestrated by the XMLAPI:

1. SyncEngine: The core engine that manages state via Transactions and orchestrates updates.

2. CST (Concrete Syntax Tree): Captures the exact physical structure of the source code, including formatting.

3. Model: The authoritative internal representation that maintains object identity, coordinates synchronization, and provides a semantic view for traversal.

Additionally, a DOM-compatible Interface wraps the Model for familiar application development.

Basic Usage

Initialization

import { XMLAPI } from '@miy2/xml-api';

const xml = `<root>
  <item id="1">Original Value</item>
</root>`;

const api = new XMLAPI(xml);

Manipulating via DOM API (Recommended)

You can use standard DOM methods to manipulate the XML. These changes are automatically reflected back to the source code with minimal patches.

const doc = api.getDocument(); // Returns a DOM-like Document
const item = doc.querySelector('item');

if (item) {
  item.setAttribute('status', 'active');
  item.textContent = 'Updated Value';
}

console.log(api.source);
/* 
Output:
<root>
  <item id="1" status="active">Updated Value</item>
</root>
*/

Low-level Incremental Updates

// Update the source code directly at specific offsets
api.updateSource(14, 28, "New Content");

Schema Projection (New in v0.9.1)

Create a filtered view of the document that adheres to a specific schema (e.g. XHTML). The view preserves the underlying model's full fidelity (including comments and custom tags) while presenting a simplified DOM for editing.

const api = new XMLAPI(source);
const view = api.createView({
  // Only show 'p' and 'div' elements
  filter: (node) => 
    node.getType() === 'Element' && 
    ['p', 'div'].includes((node as ModelElement).tagName)
});

const root = view.getRoot(); // Returns a filtered DOM-like element
const p = view.getDocument().createElement('p');
p.textContent = "New Paragraph";
root.appendChild(p); // Updates source automatically with smart formatting

Documentation

• Getting Started: Installation and detailed usage.
• Architecture: Deep dive into the system design.
• Core Concepts: Understanding Fidelity and the Layered model.
• API Reference: Auto-generated API documentation.

Development

This project uses pnpm.

pnpm install
pnpm test
pnpm docs:gen-api

License

MIT