# Compatibility Reference

> Runtime support matrix, module formats, TypeScript requirements, and sub-path exports for `xml-xsd-engine` v1.7.0.

---

## Runtime Support

| Runtime | Minimum version | Entry point | Streaming validation |
|---------|----------------|-------------|---------------------|
| Node.js | 18.0.0 | `xml-xsd-engine` | ✅ Full support |
| Deno | 1.37+ | `xml-xsd-engine/deno` | ✅ Full support |
| Bun | 1.0+ | `xml-xsd-engine/bun` | ✅ Full support |
| Chrome / Edge | 90+ | `xml-xsd-engine/browser` | ✅ (string input only) |
| Firefox | 88+ | `xml-xsd-engine/browser` | ✅ (string input only) |
| Safari | 14+ | `xml-xsd-engine/browser` | ✅ (string input only) |

Browser entry point excludes `fs`, `path`, and all file I/O exports.  
`validateStream(stream, ...)` requires Node.js / Deno / Bun (Readable stream).  
`validateStreaming(xml, ...)` and `validateStreamingGenerator(xml, ...)` work in all environments.

---

## Module Formats

| Format | Path | Bundlers |
|--------|------|---------|
| ESM | `dist/esm/index.js` | Vite, Webpack 5, Rollup, esbuild |
| CJS | `dist/cjs/index.js` | Node.js require, Jest |
| Types | `dist/types/index.d.ts` | TypeScript |

`sideEffects: false` is set for full tree-shaking.

---

## TypeScript

| Requirement | Detail |
|-------------|--------|
| Minimum version | TypeScript 4.7 (for `package.json` exports field) |
| Recommended | TypeScript 5.x |
| `tsconfig` | `moduleResolution: "bundler"` or `"node16"` for best results |
| Strict mode | All types are strict-compatible |
| Async generators | `"lib": ["ES2018"]` or higher required for `validateStreamingGenerator` |

---

## Sub-path Exports

| Import | Use case |
|--------|---------|
| `xml-xsd-engine` | Node.js 18+, full feature set |
| `xml-xsd-engine/browser` | Browsers, Deno, Bun — no `fs`/`path` |
| `xml-xsd-engine/deno` | Deno-native file I/O |
| `xml-xsd-engine/bun` | Bun-native file I/O |
| `xml-xsd-engine/async` | Async-only API surface |

---

## v1.7.0 New Exports

| Symbol | Description |
|--------|-------------|
| `extractPsvi` | Convert PSVI Map to path→annotation Map |
| `SchemaMerger` | Standalone xs:import/include/redefine merge class |
| `configureXPathCache` | Tune two-tier XPath LRU at runtime |
| `xpathCacheStats` | Inspect XPath cache state |
| `xpathCacheSize` | Current compiled-expression count |
| `clearCanonicalCache` | Invalidate Canonical XML subtree memo |
| `generateJsonSchemaStream` | Streaming JSON Schema generation |
| `generateTypeScriptStream` | Streaming TypeScript generation |
| `makePsviAnnotation` | PSVI annotation factory |
| `PsviAnnotation` | PSVI annotation type |
| `PsviMap` | `Map<XmlElement, PsviAnnotation>` |
| `CanonicalizeOptions` | Options for `canonicalize` |
| `CanonicalizeMode` | `'inclusive' \| 'exclusive'` |
| `validateStreaming` | SAX-based streaming validation |
| `validateStream` | Node.js Readable stream validation |
| `validateStreamingGenerator` | Async generator yielding `StreamingIssue` |
| `StreamingValidator` | Class-based streaming validation |
| `StreamingKeyrefTracker` | Streaming xs:key/unique/keyref tracker |
| `StreamingValidationOptions` | Options for streaming validation |
| `StreamingValidationResult` | Result type for streaming validation |
| `StreamingIssue` | Per-issue type (severity, path, message, code) |
| `buildDfa` | Build a DFA from a particle list |
| `runDfa` | Run a DFA over a list of element names |
| `DfaModel` | DFA model with `particleIndex` for O(1) lookup |
| `DfaRunResult` | `{ valid, unexpected[], missing[], tooMany[] }` |
| `CompositorKind` | `'sequence' \| 'choice' \| 'all'` |
| `revalidateSubtree` | Incremental subtree revalidation (G38) |
| `SchemaCache.get(key)` | Direct cache retrieval |
| `SchemaCache.has(key)` | Boolean presence check |
| `SchemaCacheOptions.statFast` | `fs.stat` fast path for `getOrLoad` |
| `CompiledSchema.compiledDfas` | Pre-compiled DFA per complex type |
| `DfaModel.particleIndex` | O(1) element-name → particle index |

---

## XSD 1.0 Compliance (v1.7.0)

| Area | Status | Notes |
|------|--------|-------|
| Element declarations | ~90% | |
| Complex types | ~85% | |
| Simple types + facets | **~98%** | 56 built-in types; xs:decimal `.5` form; xs:date calendar |
| xs:sequence / xs:choice / xs:all | **~95%** | DFA-based; O(1) lookup via `particleIndex` |
| xs:extension / xs:restriction | ~80% | |
| xs:import / xs:include / xs:redefine | ~90% | Full xs:redefine support added v1.7 |
| xs:key / xs:unique | ~90% | |
| xs:keyref | **~80%** | Streaming-aware (SAX pass); DOM full evaluation |
| xs:assert (XPath 1.0) | ~75% | DOM mode only; not available in streaming |
| Substitution groups | ~60% | |
| Abstract types | ~80% | |
| xsi:type runtime substitution | **~80%** | Streaming validator handles xsi:type override |
| Wildcards (xs:any, xs:anyAttribute) | ~85% | |
| Namespace-qualified matching | ~75% | |
| elementFormDefault / attributeFormDefault | ~60% | |
| **Overall estimate** | **~75%** | Up from ~72% in v1.7.0 |

XSD 1.1 compliance: ~15% (xs:assert subset only).  
XPath 1.0 compliance: ~85%.  
XPath 2.0 function coverage: 22 of ~100 functions.

---

## Streaming vs. DOM Validation Feature Matrix

| Feature | DOM (`validate`) | Streaming (`validateStreaming`) |
|---------|-----------------|--------------------------------|
| Structure validation | ✅ | ✅ |
| Simple type checking (56 types) | ✅ | ✅ |
| Complex type content model (DFA) | ✅ | ✅ |
| Attribute validation | ✅ | ✅ |
| xs:key / xs:unique | ✅ | ✅ (via StreamingKeyrefTracker) |
| xs:keyref | ✅ | ✅ (single-document scope) |
| xs:assert (XPath) | ✅ | ❌ |
| PSVI annotations | ✅ | ❌ |
| XPath queries on result | ✅ | ❌ |
| xsi:type substitution | ✅ | ✅ |
| Async generator issues | ❌ | ✅ (`validateStreamingGenerator`) |
| Memory usage | O(document) | O(depth) |
| Large files (>10 MB) | ⚠️ possible OOM | ✅ constant memory |