# xml-xsd-engine — Feature Reference
> **v1.7.0** 2460 tests 0 runtime dependencies TypeScript-first MIT
> Complete feature inventory from v1.0 through v1.7.
---
## Table of Contents
| # | Feature | Since |
|---|---------|-------|
| 1 | [XML Lexer](#1-xml-lexer) | v1.0 |
| 2 | [XML Parser (DOM)](#2-xml-parser-dom) | v1.0 |
| 3 | [SAX / Event Parser](#3-sax--event-parser) | v1.0 |
| 4 | [XML Serializer](#4-xml-serializer) | v1.0 |
| 5 | [XSD Parser](#5-xsd-parser) | v1.0 |
| 6 | [Schema Model](#6-schema-model) | v1.0 |
| 7 | [Schema Compiler](#7-schema-compiler) | v1.4 |
| 8 | [Namespace Engine](#8-namespace-engine) | v1.0 |
| 9 | [Validation Pipeline](#9-validation-pipeline) | v1.4 |
| 10 | [Validation Engine](#10-validation-engine) | v1.0 |
| 11 | [Type Validator (56 types)](#11-type-validator-56-types) | v1.0 |
| 12 | [Identity Constraints](#12-identity-constraints) | v1.5 |
| 13 | [xs:assert Evaluator](#13-xsassert-evaluator) | v1.5 |
| 14 | [Schema Preflight](#14-schema-preflight) | v1.5 |
| 15 | [Error System](#15-error-system) | v1.0 |
| 16 | [Output Formatters](#16-output-formatters) | v1.0 |
| 17 | [XPath Engine](#17-xpath-engine) | v1.0 |
| 18 | [XPath 2.0 Functions](#18-xpath-20-functions) | v1.5 |
| 19 | [XPath Cache Control](#19-xpath-cache-control) | v1.7 |
| 20 | [Parse Budget and Security](#20-parse-budget-and-security) | v1.0 |
| 21 | [Schema Cache](#21-schema-cache) | v1.2 |
| 22 | [Async File I/O](#22-async-file-io) | v1.0 |
| 23 | [Streaming Parser](#23-streaming-parser) | v1.0 |
| 24 | [SAX Instrumentation](#24-sax-instrumentation) | v1.5 |
| 25 | [Batch Validation](#25-batch-validation) | v1.2 |
| 26 | [Plugin Architecture](#26-plugin-architecture) | v1.0 |
| 27 | [XML to JSON Transform](#27-xml-to-json-transform) | v1.2 |
| 28 | [JSON to XML Transform](#28-json-to-xml-transform) | v1.2 |
| 29 | [XSLT-lite Transformer](#29-xslt-lite-transformer) | v1.2 |
| 30 | [Code Generation](#30-code-generation) | v1.3 |
| 31 | [Streaming Code Generation](#31-streaming-code-generation) | v1.7 |
| 32 | [Async Schema Loader](#32-async-schema-loader) | v1.3 |
| 33 | [CLI xml-validate](#33-cli-xml-validate) | v1.0 |
| 34 | [CLI xml-format](#34-cli-xml-format) | v1.4 |
| 35 | [ESM and CJS Dual Build](#35-esm-and-cjs-dual-build) | v1.0 |
| 36 | [Platform Entry Points](#36-platform-entry-points) | v1.5 |
| 37 | [SHA-256 Utilities](#37-sha-256-utilities) | v1.5 |
| 38 | [xml:id and xml:base](#38-xmlid-and-xmlbase) | v1.5 |
| 39 | [DTD Internal Entities](#39-dtd-internal-entities) | v1.5 |
| 40 | [DFA Engine](#40-dfa-engine) | v1.7 |
| 41 | [Streaming Validator](#41-streaming-validator) | v1.7 |
| 42 | [Incremental Subtree Revalidation](#42-incremental-subtree-revalidation) | v1.7 |
| 43 | [Streaming xs:keyref Tracker](#43-streaming-xskeyref-tracker) | v1.7 |
| 44 | [Streaming Issue Generator](#44-streaming-issue-generator) | v1.7 |
| 40 | [Encoding Support](#40-encoding-support) | v1.6 |
| 41 | [Source-Mapped Errors](#41-source-mapped-errors) | v1.4 |
| 42 | [XML Diff](#42-xml-diff) | v1.6 |
| 43 | [Schema Inference](#43-schema-inference) | v1.6 |
| 44 | [Fragment and Subtree Validation](#44-fragment-and-subtree-validation) | v1.6 |
| 45 | [PSVI](#45-psvi) | v1.7 |
| 46 | [Canonical XML C14N](#46-canonical-xml-c14n) | v1.7 |
| 47 | [xs:redefine Support](#47-xsredefine-support) | v1.7 |
| 48 | [Mixed Content Fix](#48-mixed-content-fix) | v1.7 |
| 49 | [SchemaMerger](#49-schemamerger) | v1.7 |
---
## 1. XML Lexer
Source: `src/parser/XmlLexer.ts` — Exports: `XmlLexer`, `Token`, `TokenType`, `LexerOptions`
Single-pass state-machine tokenizer. No regex for structure. CRLF normalization. Line/column tracking.
Token types: `XML_DECL`, `DOCTYPE`, `COMMENT`, `PI`, `OPEN_TAG`, `ATTR_NAME`, `ATTR_VALUE`,
`TAG_END`, `TAG_SELF_CLOSE`, `CLOSE_TAG`, `TEXT`, `CDATA`, `EOF`
Security limits: `maxAttributes` (256), `maxTextLength` (10MB), `maxNodeCount` (1M)
```ts
const lexer = new XmlLexer(source);
for (const token of lexer.tokenizeStream()) {
if (token.type === 'EOF') break;
console.log(token.type, token.value, token.line, token.col);
}
```
---
## 2. XML Parser (DOM)
Source: `src/parser/XmlParser.ts` — Exports: `XmlParser`, `parseXml`, `ParseOptions`
Stack-based parser. Full DOM with namespace resolution, entity decoding, well-formedness validation.
DOM types: `XmlDocument`, `XmlElement`, `XmlText`, `XmlComment`, `XmlPI`
Key ParseOptions: `maxDepth`, `maxAttributes`, `maxTextLength`, `maxNodeCount`, `entityMap`,
`expandDtdEntities`, `encoding`, `preserveWhitespace`
```ts
const doc = parseXml('text');
doc.root?.tagName; // 'root'
doc.root?.getAttribute('id'); // '1'
doc.root?.childElements[0].textContent; // 'text'
```
---
## 3. SAX / Event Parser
Source: `src/parser/SaxParser.ts` — Exports: `SaxParser`, `SaxEvent`, `parseSax`
Push-based event parser. Zero DOM allocation. Pull-iterator via `.events()`.
Events: `startDocument`, `endDocument`, `xmlDeclaration`, `startElement`, `endElement`,
`text`, `cdata`, `comment`, `processingInstruction`, `doctype`, `error`
All events carry `line` and `col` position.
```ts
parseSax(xml, {
startElement: (e) => console.log('open', e.event.localName, e.event.namespaceURI),
text: (e) => console.log('text', e.value),
});
// Pull iterator
const parser = new SaxParser(xml);
for (const event of parser.events()) {
if (event.type === 'startElement') console.log(event.event.localName);
}
```
---
## 4. XML Serializer
Source: `src/parser/XmlSerializer.ts` — Exports: `XmlSerializer`, `serializeXml`, `SerializerOptions`
Mixed-content aware. Does not add indentation where it would change semantics.
Options: `indent` (2), `preserveMixedContent` (true), `selfClosingTags` (true), `xmlDeclaration` (false)
```ts
const xml = serializeXml(doc, { indent: 4, xmlDeclaration: true });
```
---
## 5. XSD Parser
Source: `src/xsd/XsdParser.ts` — Exports: `XsdParser`, `parseXsd`, `parseXsdAsync`, `SchemaLoader`
Parses XSD 1.0 (large subset) into a `SchemaModel`.
Supported: `xs:element`, `xs:complexType`, `xs:simpleType`, `xs:sequence`, `xs:choice`, `xs:all`,
`xs:any`, `xs:anyAttribute`, `xs:restriction`, `xs:extension`, `xs:list`, `xs:union`,
`xs:attribute`, `xs:attributeGroup`, `xs:group`, `xs:import`, `xs:include`, `xs:redefine`,
`xs:key`, `xs:unique`, `xs:keyref`, `xs:assert`, all facets
```ts
const schema = parseXsd(xsdSource, (loc) => fs.readFileSync(loc, 'utf8'));
const schema2 = await parseXsdAsync(xsdSource, async (loc) => fetch(loc).then(r => r.text()));
```
---
## 6. Schema Model
Source: `src/schema/SchemaModel.ts` — Exports: `SchemaModel` and related types
In-memory schema graph. Maps: `elements`, `complexTypes`, `simpleTypes`, `attributeGroups`,
`groups`, `substitutionGroups`. Methods: `resolveType`, `resolveElement`, `merge`.
---
## 7. Schema Compiler
Source: `src/pipeline/SchemaCompilerLite.ts` — Exports: `compileSchema`, `CompiledSchema`
Compiles `SchemaModel` into normalized `CompiledSchema`:
- Resolves all `ref=""` references
- Flattens extension inheritance chains
- Normalizes occurrence defaults
- Detects circular extensions (depth > 20 → warning)
- Pre-indexes identity constraints per element name
- Builds substitution group lookup map
```ts
const compiled = compileSchema(schema);
```
---
## 8. Namespace Engine
Source: `src/namespace/NamespaceEngine.ts` — Exports: `NamespaceEngine`
Scoped prefix-to-URI resolver. Linked scope chain: O(decls) per push, O(1) for empty scopes.
Default namespace, prefix shadowing, depth tracking.
```ts
eng.pushScope([{ prefix: 'xs', uri: 'http://www.w3.org/2001/XMLSchema' }]);
const r = eng.resolveQName('xs:string');
eng.popScope();
```
---
## 9. Validation Pipeline
Source: `src/pipeline/ValidationPipeline.ts` — Exports: `ValidationPipeline`, `runPipeline`
Formal 7-stage pipeline: `parse`, `namespace`, `schema-compile`, `structure-validate`,
`type-validate`, `identity-check`, `post-process`
Options: `mode` (strict/lax), `recover`, `collectAll`, `profile`, `onProfile`, `psvi`, `rootType`
```ts
const result = runPipeline(xmlSource, schema, { profile: true, psvi: true });
console.log(result.totalMs, result.stages);
```
---
## 10. Validation Engine
Source: `src/validator/ValidationEngine.ts` — Exports: `validate`, `validateSubtree`, `validateFragment`
Validates: element structure, sequence/choice/all ordering, occurrence counts, types, attributes,
xs:any wildcards, xsi:type, xsi:nil, abstract types, identity constraints.
```ts
const result = validate(doc, schema);
const r2 = validateSubtree(element, schema, { rootType: 'MyType' });
const r3 = validateFragment('19.99', schema);
```
---
## 11. Type Validator (56 types)
Source: `src/validator/TypeValidator.ts` — Exports: `TypeValidator`
**56** built-in XSD types across categories: string (`xs:normalizedString`, `xs:token`, `xs:Name`), numeric, float, date/time (with calendar validation — rejects `2024-02-30`), binary, boolean, anyURI, identity (`xs:ID`, `xs:IDREF`, `xs:ENTITY`, `xs:NMTOKENS`, `xs:IDREFS`, `xs:ENTITIES`), `xs:anySimpleType`, `xs:anyAtomicType`.
`xs:decimal` accepts leading-dot form (`.5`) per XSD spec.
All facets: enumeration, pattern, length, minLength, maxLength, min/maxInclusive, min/maxExclusive,
totalDigits, fractionDigits, whiteSpace.
`TypeValidator.validateDef(value, simpleDef)` *(v1.7)* — validates against an inline `SimpleTypeDefinition` directly.
---
## 12. Identity Constraints
Source: `src/validator/IdentityConstraintEngine.ts` — Exports: `IdentityConstraintEngine`
Evaluates `xs:key`, `xs:unique`, `xs:keyref` after structure and type validation.
Pre-indexed element names for O(1) skip on constraint-free elements.
XPath 1.0 selectors for `xs:selector` and `xs:field`.
---
## 13. xs:assert Evaluator
Source: `src/validator/AssertionEvaluator.ts` — Exports: `AssertionEvaluator`, `AssertionDefinition`
XPath 1.0-lite assertions on complex type instances. Deterministic evaluation order (sorted by test
expression since v1.7.0). Produces `ASSERTION_FAILED` errors with test expression in message.
---
## 14. Schema Preflight
Source: `src/validator/SchemaPreflight.ts` — Exports: `validateSchema`, `checkSchema`
Self-consistency checks: undefined type references, circular types, invalid derivations,
conflicting declarations, broken xs:keyref links, undefined ref attributes.
```ts
const issues = validateSchema(xsdSource);
const issues2 = checkSchema(model);
```
---
## 15. Error System
Source: `src/errors/XmlError.ts`, `src/validator/ValidationResult.ts`
Stable `XmlErrorCode` union. Categories: well-formedness, namespace, schema, validation, identity,
security, assertion. `ValidationIssue` carries `severity`, `message`, `path`, `line`, `col`,
`code`, `category`, `stage`. `ValidationResult` has `valid`, `errorCount`, `warningCount`,
`issues`, `summary`, `psvi?`.
---
## 16. Output Formatters
Five formats: `text` (human), `compact` (grep-friendly), `json` (tooling), `github` (annotations),
`junit` (CI). Used by both CLI and programmatic API.
---
## 17. XPath Engine
Source: `src/parser/XPathEngine.ts` — Exports: `xpath`, `compileXPath`
XPath 1.0 subset. Axes: child, descendant, descendant-or-self, parent, ancestor, ancestor-or-self,
self, attribute, following-sibling, preceding-sibling. All node tests, positional predicates,
attribute predicates, text() predicates, standard XPath 1.0 functions.
```ts
const nodes = xpath(doc, '//item[@type="book"]') as XmlElement[];
const expr = compileXPath('//price');
const prices = expr.evaluate(doc);
```
---
## 18. XPath 2.0 Functions
22 additional functions: `upper-case`, `lower-case`, `matches`, `replace`, `tokenize`,
`distinct-values`, `empty`, `exists`, `string-join`, `reverse`, `subsequence`,
`insert-before`, `remove`, `avg`, `min`, `max`, `xs:string`, `xs:integer`,
`xs:boolean`, `xs:decimal`, `encode-for-uri`, `escape-html-uri`
---
## 19. XPath Cache Control
Source: `src/parser/XPathEngine.ts` — Exports: `configureXPathCache`, `xpathCacheStats`, `xpathCacheSize`
Two-tier LRU: cold tier (512 slots) for new expressions, hot tier (128 slots) for frequent ones.
+24% throughput on first-time expressions; +4x for hot-tier hits.
```ts
configureXPathCache({ coldMax: 1024, hotMax: 256 });
const { hits, misses } = xpathCacheStats();
```
---
## 20. Parse Budget and Security
Source: `src/utils/ParseBudget.ts` — Exports: `ParseBudget`, `ParseBudgetOptions`
Limits: `maxDepth` (500), `maxAttributes` (256), `maxTextLength` (10MB), `maxNodeCount` (1M),
`maxEntityExpansion` (10,000). External entities blocked by default (XXE prevention).
Circular entity chains detected (Billion Laughs protection).
---
## 21. Schema Cache
Source: `src/cache/SchemaCache.ts` — Exports: `SchemaCache`, `globalSchemaCache`, `SchemaCacheOptions`
LRU + TTL + SHA-256 content-hash. Options: `maxSize` (100), `ttlMs` (1h), `trackContentHash` (true),
`maxVersionsPerKey` (2). API: `getOrParse`, `invalidate`, `invalidateByContent`, `clear`, `size`.
```ts
const schema = cache.getOrParse('key', xsdSource);
cache.invalidateByContent('key', updatedSource); // true if hash changed
```
---
## 22. Async File I/O
Exports: `readXmlFile`, `readXsdFile`, `validateFiles`, `validateFilesWithLoader`
`readXsdFile` auto-creates a filesystem loader for xs:import resolution relative to the XSD directory.
---
## 23. Streaming Parser
Source: `src/io/XmlStreamParser.ts` — Exports: `XmlStreamParser`, `parseXmlStream`, `parseXmlFileStream`
Node.js Transform stream. Accumulates chunks, emits `XmlDocument` on end.
Handles string and Buffer chunks. Rejects on malformed XML.
```ts
const doc = await parseXmlStream(createReadStream('data.xml'));
const doc2 = await parseXmlFileStream('data.xml');
```
---
## 24. SAX Instrumentation
Source: `src/parser/SaxInstrumentation.ts` — Exports: `SaxInstrumentation`
Wraps SaxParser with structured events, position tracking, namespace-scope callbacks.
Zero overhead when not enabled (gated by `enabled` flag).
---
## 25. Batch Validation
Source: `src/validator/BatchValidator.ts` — Exports: `BatchValidator`, `BatchReport`
Concurrent validation. Options: `concurrency`, `failFast`, `onProgress`.
Compiles schema once and reuses across all documents.
```ts
const report = await new BatchValidator('schema.xsd', { concurrency: 8 })
.validateFiles(['a.xml', 'b.xml']);
```
---
## 26. Plugin Architecture
Source: `src/plugins/PluginRegistry.ts` — Exports: `PluginRegistry`, `XmlPlugin`
Register custom type validators, entity resolvers, SAX event hooks.
```ts
PluginRegistry.registerTypeValidator('myNs:EmailType', (v) =>
v.includes('@') ? { valid: true } : { valid: false, message: 'Not an email' }
);
```
---
## 27. XML to JSON Transform
Source: `src/transform/XmlToJson.ts` — Exports: `xmlToJson`, `XmlToJsonOptions`
Options: `attributePrefix` ('@'), `textKey` ('_text'), `includeComments`, `collapseText`.
Repeated elements collapsed to arrays automatically.
---
## 28. JSON to XML Transform
Source: `src/transform/JsonToXml.ts` — Exports: `jsonToXml`, `jsonToXmlString`, `JsonToXmlOptions`
```ts
const xml = jsonToXml({ root: { item: ['a', 'b'], '@id': '1' } });
```
---
## 29. XSLT-lite Transformer
Source: `src/transform/XsltTransformer.ts` — Exports: `transformXml`, `transformDocument`, `XsltTransformer`
XSLT 1.0 subset. Instructions: `xsl:template`, `xsl:apply-templates`, `xsl:for-each`,
`xsl:value-of`, `xsl:if`, `xsl:choose`, `xsl:copy`, `xsl:copy-of`, `xsl:element`,
`xsl:attribute`, `xsl:text`, `xsl:variable`, `xsl:param`, `xsl:sort`, `xsl:number`.
Attribute Value Templates supported.
---
## 30. Code Generation
Source: `src/codegen/` — Exports: `generateTypeScript`, `generateJsonSchema`, related options/classes
XSD to TypeScript interfaces. XSD to JSON Schema Draft 7.
Options for typePrefix, exportAll, addComments, id, title, useDefinitions, allowAdditional.
```ts
const ts = generateTypeScript(schema, { typePrefix: 'I', exportAll: true });
const jsonSchema = generateJsonSchema(schema, { useDefinitions: true });
```
---
## 31. Streaming Code Generation
Exports: `generateTypeScriptStream`, `generateJsonSchemaStream`
AsyncGenerator variants yielding ~4 KB chunks. Avoids peak memory on large schemas.
```ts
for await (const chunk of generateTypeScriptStream(schema)) outputStream.write(chunk);
```
---
## 32. Async Schema Loader
Exports: `parseXsdAsync`, `AsyncSchemaLoader`
```ts
const schema = await parseXsdAsync(xsdSource,
async (loc) => fetch(loc).then(r => r.text())
);
```
---
## 33. CLI xml-validate
Formats: text, compact, json, github (Actions annotations), junit.
Flags: `--format`, `--well-formed`, `--watch`, `--code-frame`, `--lax`, `--fail-fast`, `--silent`.
Exit codes: 0 valid, 1 errors, 2 parse error, 3 file not found.
---
## 34. CLI xml-format
Pretty-print XML. Flags: `--indent`, `--declaration`, `--in-place`, `--output`.
---
## 35. ESM and CJS Dual Build
Conditional exports for `.`, `./browser`, `./deno`, `./bun`, `./async`.
`sideEffects: false` for full tree-shaking. Compatible with Vite, Webpack 5, Rollup, esbuild.
---
## 36. Platform Entry Points
`xml-xsd-engine` (Node 18+), `xml-xsd-engine/browser` (no fs/path), `xml-xsd-engine/deno`,
`xml-xsd-engine/bun`, `xml-xsd-engine/async`.
---
## 37. SHA-256 Utilities
Source: `src/utils/sha256.ts` — Exports: `sha256Hex`, `sha256Short`
Pure TypeScript SHA-256. No external dependencies. Used for schema content-hash caching.
---
## 38. xml:id and xml:base
`xml:id` indexed in `XmlDocument.xmlIds`. Duplicate IDs produce `PARSE_DUPLICATE_ID`.
`xml:base` propagated to `XmlElement.xmlBase`. `resolveXmlBase(base, ref)` resolves relative URIs.
---
## 39. DTD Internal Entities
Safe `` expansion. External entities blocked by default.
Expansion depth tracked (Billion Laughs prevention). Custom entities via `ParseOptions.entityMap`.
---
## 40. Encoding Support
`ParseOptions.encoding` overrides encoding metadata on XmlDocument. Pre-decode with TextDecoder,
pass encoding name to preserve it on the document object.
---
## 41. Source-Mapped Errors
Every ValidationIssue carries `line` and `col` from the lexer token. Threaded through DOM nodes
into all validation, namespace, schema, and identity errors.
---
## 42. XML Diff
Source: `src/utils/XmlDiff.ts` — Exports: `diffXml`, `XmlChange`, `XmlChangeType`, `XmlDiffOptions`
Change types: `added`, `removed`, `modified`, `type-change`. WeakMap fingerprint cache (+40% vs v1.6).
Reference equality fast-path. Options: `ignoreWhitespace`.
---
## 43. Schema Inference
Source: `src/utils/SchemaInference.ts` — Exports: `inferSchema`, `InferredSchema`, `InferSchemaOptions`
Infer draft XSD from XML samples. Options: `targetNamespace`, `inferSimpleTypes`, `inferRequired`,
`maxDepth`, `maxElements`. Returns `{ model, toXsdString }`.
---
## 44. Fragment and Subtree Validation
Exports: `validateFragment`, `validateSubtree`
```ts
const r1 = validateFragment('19.99', schema);
const r2 = validateSubtree(element, schema, { rootType: 'PriceType' });
```
---
## 45. PSVI
Source: `src/validator/Psvi.ts` — Exports: `PsviAnnotation`, `PsviMap`, `extractPsvi`, `makePsviAnnotation`
Per-element type annotation: `xsdType`, `normalizedValue`, `validity`, `memberType?`.
Stored in WeakMap — GC-friendly. 256-entry pool for common null-value annotations (-60% allocation).
`extractPsvi(psvi, doc, { paths? })` converts to serialisable Map.
```ts
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);
```
---
## 46. Canonical XML C14N
Source: `src/utils/XmlCanonical.ts` — Exports: `canonicalize`, `clearCanonicalCache`, `CanonicalizeOptions`
W3C C14N 1.0. Modes: inclusive (default), exclusive. Options: `withComments`, `inclusiveNamespaces`.
Rules: no declaration, expanded empty elements, sorted attributes/namespace declarations,
CDATA expanded, special chars encoded. WeakMap subtree memoization (+40% throughput).
```ts
const c14n = canonicalize(doc);
const exc = canonicalize(doc, { mode: 'exclusive', inclusiveNamespaces: ['ds'] });
clearCanonicalCache(); // after mutation
```
---
## 47. xs:redefine Support
Load + merge a base schema then override named components. Transparent to callers.
Required for UBL and ebXML schemas. Circular chains guarded by SHA-256 hash cache.
---
## 48. Mixed Content Fix
`mixed="true"` — interleaved text nodes allowed; only elements validated against content model.
`contentType: 'elementOnly'` — text produces warning (not error). Serializer indent-safe.
---
## 49. SchemaMerger
Source: `src/xsd/SchemaMerger.ts` — Exports: `SchemaMerger`
Centralizes xs:import, xs:include, xs:redefine. SHA-256 content-hash caching prevents
re-parsing identical XSD source. Shared cache across sub-parsers via constructor argument.
---
## v1.7.0 Performance Summary
| Fix | Improvement |
|-----|-------------|
| XPath two-tier LRU | +24% first-expression, +4x hot-tier |
| XmlDiff fingerprint cache | +40% diff throughput |
| Canonical XML delta saves | -O(scope) to O(decls) per element |
| PSVI object pool | -60% heap allocation |
| ValidationEngine memoization | +5% validate throughput |
| IdentityConstraintEngine pre-index | O(1) skip for constraint-free elements |
| ValidationResult counting fix | result.valid now always accurate |
---
## 40. DFA Engine
Source: `src/validator/DfaEngine.ts` — Exports: `buildDfa`, `runDfa`, `DfaModel`, `DfaRunResult`, `CompositorKind`
Content-model validation via deterministic finite automaton. One DFA per compositor kind
(sequence / choice / all). `DfaModel.particleIndex` provides O(1) element-name lookup
(avoids O(n) `Array.find` on every element). Pre-compiled into `CompiledSchema.compiledDfas`
by `SchemaCompilerLite` at compile time.
```ts
import { buildDfa, runDfa } from 'xml-xsd-engine';
const dfa = buildDfa(particles, 'sequence');
const result = runDfa(dfa, ['child1', 'child2']);
// { valid: true, unexpected: [], missing: [], tooMany: [] }
```
---
## 41. Streaming Validator
Source: `src/validator/StreamingValidator.ts` — Exports: `validateStreaming`, `validateStream`, `StreamingValidator`
SAX-driven validator — no DOM allocation. Validates structure, types, attributes, and
identity constraints in a single pass. Uses pre-compiled DFAs from `CompiledSchema.compiledDfas`.
Handles `xsi:type` runtime type substitution.
```ts
import { validateStreaming, compileSchema, parseXsd } from 'xml-xsd-engine';
const compiled = compileSchema(parseXsd(xsdSource));
const result = validateStreaming('hello', compiled);
// { valid: true, issues: [], errorCount: 0, warningCount: 0, durationMs: 1 }
```
---
## 42. Incremental Subtree Revalidation
Source: `src/validator/ValidationEngine.ts` — Exports: `revalidateSubtree`
Re-validates a single `XmlElement` subtree without processing the full document.
Intended for editor/IDE "lint on edit" integrations where only a changed region needs rechecking.
```ts
import { revalidateSubtree } from 'xml-xsd-engine';
const result = revalidateSubtree(changedElement, schema, { recover: true });
```
---
## 43. Streaming xs:keyref Tracker
Source: `src/validator/StreamingValidator.ts` — Exports: `StreamingKeyrefTracker`
Accumulates xs:key, xs:unique, and xs:keyref tuples during a SAX pass and validates
referential integrity after parsing. Element-name index built at construction time for
O(1) per-element dispatch.
```ts
import { StreamingKeyrefTracker } from 'xml-xsd-engine';
const tracker = new StreamingKeyrefTracker(schema);
// called per SAX endElement:
tracker.onElement('item', '/root/item', attrs, textContent);
// after parse:
const issues = tracker.validate(); // StreamingIssue[]
```
---
## 44. Streaming Issue Generator
Source: `src/validator/StreamingValidator.ts` — Exports: `validateStreamingGenerator`
Async generator variant of `validateStreaming`. Yields each `StreamingIssue` as produced
so callers can react (log, abort) without waiting for the full document. The generator
return value is the complete `StreamingValidationResult`.
```ts
import { validateStreamingGenerator, compileSchema, parseXsd } from 'xml-xsd-engine';
const compiled = compileSchema(parseXsd(xsdSource));
for await (const issue of validateStreamingGenerator(xmlSource, compiled)) {
console.error(`[${issue.severity}] ${issue.path}: ${issue.message}`);
}
```