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

$3

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

const xml =
Original Value
;

const api = new XMLAPI(xml);
`

$3

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

`typescript
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:

Updated Value

*/
`

$3

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

$3

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.

`typescript
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.

`bash
pnpm install
pnpm test
pnpm docs:gen-api
``

License

MIT