# Quick Start

> Get productive with `xml-xsd-engine` in 5 minutes.
> Node.js >= 18 required. 0 runtime dependencies.

---

## Install

```bash
npm install xml-xsd-engine
```

---

## 1. Parse XML

```ts
import { parseXml } from 'xml-xsd-engine';

const doc = parseXml('<catalog><book id="1"><title>Dune</title></book></catalog>');
console.log(doc.root?.tagName);                               // 'catalog'
console.log(doc.root?.childElements[0].getAttribute('id'));   // '1'
console.log(doc.root?.childElements[0].childElements[0].textContent); // 'Dune'
```

---

## 2. Parse XSD and Validate

```ts
import { parseXsd, validate } from 'xml-xsd-engine';

const xsd = `
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="catalog">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="book" maxOccurs="unbounded">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="title" type="xs:string"/>
            </xs:sequence>
            <xs:attribute name="id" type="xs:string" use="required"/>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>`;

const schema = parseXsd(xsd);
const result = validate(doc, schema);

console.log(result.valid);   // true
console.log(result.issues);  // []
```

---

## 3. File-based Validation

```ts
import { validateFiles } from 'xml-xsd-engine';

const result = await validateFiles('catalog.xml', 'catalog.xsd');
console.log(result.valid, result.errorCount);
```

---

## 4. Validation Pipeline (full control)

```ts
import { parseXsd, runPipeline } from 'xml-xsd-engine';

const schema = parseXsd(xsdSource);
const result = runPipeline(xmlSource, schema, {
  mode:    'strict',    // or 'lax'
  recover: true,        // collect all errors, don't stop at first
  profile: true,        // per-stage timing
  psvi:    true,        // Post-Schema-Validation Infoset
});

console.log(result.success, result.totalMs);
for (const stage of result.stages) {
  console.log(stage.name, stage.durationMs, 'ms', stage.issues.length, 'issues');
}
```

---

## 5. XPath Queries

```ts
import { xpath, compileXPath } from 'xml-xsd-engine';

// Ad-hoc query
const books = xpath(doc, '//book[@id="1"]');

// Compiled (reuse for performance)
const titleExpr = compileXPath('//book/title');
const titles = titleExpr.evaluate(doc);
```

---

## 6. Batch Validation

```ts
import { BatchValidator } from 'xml-xsd-engine';

const report = await new BatchValidator('schema.xsd', { concurrency: 4 })
  .validateFiles(['a.xml', 'b.xml', 'c.xml']);

console.log(report.passed, '/', report.total, 'passed in', report.durationMs, 'ms');
```

---

## 7. Code Generation

```ts
import { parseXsd, generateTypeScript, generateJsonSchema } from 'xml-xsd-engine';

const schema = parseXsd(xsdSource);

// TypeScript interfaces
const ts = generateTypeScript(schema, { typePrefix: 'I', exportAll: true });

// JSON Schema Draft 7
const jsonSchema = generateJsonSchema(schema, { useDefinitions: true });
```

---

## 8. PSVI — Typed Validation Output

```ts
import { validate, extractPsvi } from 'xml-xsd-engine';

const result = validate(doc, schema, { psvi: true });
const annotated = extractPsvi(result.psvi!, doc);

for (const [path, ann] of annotated) {
  console.log(path, ann.xsdType, ann.validity, ann.normalizedValue);
}
```

---

## 9. Canonical XML

```ts
import { canonicalize } from 'xml-xsd-engine';

const c14n = canonicalize(doc);                          // inclusive C14N 1.0
const exc  = canonicalize(doc, { mode: 'exclusive' });  // exclusive (WS-Security)
```

---

## 10. CLI

```bash
# Validate
xml-validate catalog.xml catalog.xsd

# Well-formedness only
xml-validate --well-formed catalog.xml

# Streaming mode — no DOM (v1.7)
xml-validate --streaming large-file.xml schema.xsd

# Watch mode
xml-validate --watch catalog.xml catalog.xsd

# JSON output for tooling
xml-validate catalog.xml catalog.xsd --format json

# Pretty-print
xml-format catalog.xml --indent 4
```

---

## 11. Streaming Validation *(v1.7)*

Validate without building a DOM — constant memory, suitable for large files:

```ts
import { validateStreaming, compileSchema, parseXsd } from 'xml-xsd-engine';

const compiled = compileSchema(parseXsd(xsdSource));
const result = validateStreaming(xmlSource, compiled);

console.log(result.valid);        // boolean
console.log(result.errorCount);   // number
console.log(result.durationMs);   // number in ms
result.issues.forEach(i => console.log(i.severity, i.path, i.message));
```

For **real-time issue streaming** (react to each issue as produced):

```ts
import { validateStreamingGenerator } from 'xml-xsd-engine';

for await (const issue of validateStreamingGenerator(xmlSource, compiled)) {
  console.error(`[${issue.severity}] ${issue.path}: ${issue.message}`);
}
```

For **Node.js Readable streams** (large files from disk):

```ts
import { validateStream } from 'xml-xsd-engine';
import { createReadStream } from 'fs';

const result = await validateStream(createReadStream('large.xml'), compiled);
console.log(result.valid);
```

---

## 12. Incremental Subtree Revalidation *(v1.7)*

Re-validate only a changed element subtree without reprocessing the full document:

```ts
import { revalidateSubtree } from 'xml-xsd-engine';

// After a DOM mutation (e.g. in an editor extension):
const result = revalidateSubtree(changedElement, schema, { recover: true });
console.log(result.valid, result.errors);
```

---

## Error Handling

```ts
import { XmlError } from 'xml-xsd-engine';

try {
  const doc = parseXml('<unclosed>');
} catch (e) {
  if (e instanceof XmlError) {
    console.log(e.code);    // 'PARSE_UNCLOSED_TAG'
    console.log(e.line);    // line number
    console.log(e.col);     // column number
  }
}
```

---

## Next Steps

- [GUIDE.md](./GUIDE.md) — detailed recipes for every feature
- [API.md](./API.md) — complete export reference
- [FEATURES.md](./FEATURES.md) — full feature inventory
- [CLI.md](./CLI.md) — complete CLI reference
- [COMPATIBILITY.md](./COMPATIBILITY.md) — streaming vs. DOM feature matrix