@amazon/vinyl-xml

中文文档
5.0.0发布于 2026/11/16Apache-2.0TypeScriptESM + CJS构建来源已验证近 30 天下载 2671

A SAX XML parser

原始使用文档
文档目录10 节
  1. Install
  2. Overview
  3. Namespaces
  4. Merging Schemas
  5. Stringify
  6. Element Ordering
  7. Limitations
  8. Parent References
  9. Name Conflicts
  10. License

@amazon/vinyl-xml

Website npm size

A fast SAX XML parser that produces a type-safe object validated against an XSD-derived rule set. Designed for parsing large schema-heavy documents like DASH manifests with strong static typing and exact-source error reporting.

Install

npm install @amazon/vinyl-xml

Overview

To create a parser for a schema, first create the type definitions for the shape of the document.

There are many ways to do this. For the DASH 2011 schema we used CXSD (MIT Licensed); take the type definitions and discard the generated parser.

Using the type definitions we build a rule set that follows the XSD. This is a manual process; follow the XSD closely to match min/max occurrences, defaults, and required attributes.

MPDType example, following the MPDType definition:

const mpdType: XmlRules<MPDtype> = {
    ProgramInformation: elements(programInformationType),
    BaseURL: elements(baseURLType),
    Location: elements({ _content: charactersString }),
    Period: elements(periodType, { minOccurs: 1 }),
    Metrics: elements(metricsType),
    EssentialProperty: elements(descriptorType),
    SupplementalProperty: elements(descriptorType),
    UTCTiming: elements(descriptorType),
    availabilityEndTime: attrDateTime,
    availabilityStartTime: attrDateTime,
    id: attrString,
    maxSegmentDuration: attr(parseDuration, stringifyDuration),
    maxSubsegmentDuration: attr(parseDuration, stringifyDuration),
    mediaPresentationDuration: attr(parseDuration, stringifyDuration),
    minBufferTime: attr(parseDuration, stringifyDuration, { required: true }),
    minimumUpdatePeriod: attr(parseDuration, stringifyDuration),
    profiles: attr(parseProfiles, stringifyProfiles, { required: true }),
    publishTime: attrDateTime,
    suggestedPresentationDelay: attr(parseDuration, stringifyDuration),
    timeShiftBufferDepth: attr(parseDuration, stringifyDuration),
    type: attr(parsePresentationTypeType, stringify, {
        default: 'static',
    } as const),
} as const

Style note — abbreviations should be cased as they are in the XSD; this follows the exception noted in the TS style guide we follow.

XmlRules definitions are meant to be human-readable and easy for the TypeScript compiler to validate that the rule matches the type definition. Before this rule set can be used by the parser or stringifier, it must be mapped to a more performant machine-friendly version.

Map the rules using mapXmlRules:

const dashDrmRulesMapped = mapXmlRules(dashDrmRules)

XmlRules maps XML content to a typed object using four rule types:

  • attr — attributes
  • element — elements with a max occurrence of 1
  • elements — elements as an array
  • characters — text nodes (concatenated)

Attribute and characters handlers provide parse and stringify functions to serialize/deserialize the value from the XML.

From the rule set, create an XML handler for the SAX parser:

const dashManifestHandler = new ParseXmlHandlerImpl(dashDrmRulesMapped)

With the handler we can parse XML into a validated, type-safe object that matches our type definition:

export function parseDashManifest(manifest: string): DashDrmManifest {
    return parseXml(manifest, dashManifestHandler)
}

Concurrency note: A handler is stateful while parsing a document, so if multiple workers parse documents simultaneously, create one handler per worker thread.

The overall process is as follows: parseXml is given an XML string and a content handler. A content handler abstractly provides methods for opening and closing XML nodes. Based on an XSD schema, we can build a content handler XmlRules that knows how each node should be processed.

At a low level, parseXml uses StringParser to read XML content. As elements are opened and closed and attributes or text nodes are read, the corresponding content handler method is invoked. Validating against the schema rules as the document is read gives the added benefit of knowing the exact XML source location of an invalid document.

Namespaces

Namespaces are not optional; if an XSD schema uses a namespace, the namespace must be defined in the rules.

export const dashNamespaceUri = 'urn:mpeg:dash:schema:mpd:2011'

export const dashManifestXmlRules: XmlRules<DashManifest> = {
    MPD: element(mpdType, {
        required: true,
        namespaceUri: dashNamespaceUri,
    }),
} as const

Namespaces follow correct scoping and defaulting rules — see the W3C spec.

For XmlRules, namespaces inherit the parent rule's namespace unless overridden. When using stringifyXml, defining namespace prefixes is supported but optional. If a prefix isn't specified, one is generated when the default namespace isn't used.

Merging Schemas

In many cases, an XML document has multiple XSD definitions. These can be merged using mergeXmlRules:

const dashDrmRules = mergeXmlRules(
    dashManifestXmlRules,
    createDashProtectionXmlRules(cencXmlRules),
    createDashProtectionXmlRules(playreadyXmlRules)
)

mergeXmlRules ensures the combined schema definitions are compatible. When the rules represent separate XSD schemas with different namespace URIs, there generally isn't overlap.

Stringify

XmlRules provides both deserializers and serializers, so the same mapped rule set can be used in both the content handler for parseXml and stringifyXml:

stringifyXml(xmlString, dashDrmRulesMapped)

Element Ordering

In an XML schema, order matters for xs:sequence definitions. Amazon Vinyl XmlRules maps define properties in this order. Order doesn't matter for parsing, but it does for serialization to pass schema validation. This means serialization relies on the ES6 requirement that object keys are ordered by insertion. Many ES5 browsers also follow this rule, but stringifyXml will not be to spec for browsers that don't. XML serialization is not required for playback — only deserialization.

Limitations

The parser currently ignores processing instructions and supports only the default standard XML entities.

Parent References

Parsed XML nodes have a reference to their parent elements in the non-enumerable parent attribute. References are correctly reassigned when using the clone utility and are not included by JSON.stringify. Type definitions may include a parent property; the type isn't enforced by the rule sets and is expected to correspond to the type of parent element, or simply any.

Name Conflicts

In certain edge cases, an XSD may describe element or attribute rules that cannot be mapped 1:1 with property names. Cases include:

  • The child element or attribute name is an ES6 reserved word such as public, private, get, set, etc.
  • The name is an internally reserved word: parent or clone.
  • A child element local name matches an attribute name. In these cases, choose a different property name and provide a localPart value to the rule configuration.
import { attrString } from '@amazon/vinyl-xml'

type MyType = { _parent: string }

export const myXmlRules: XmlRules<MyType> = {
    _parent: attrString({ localPart: 'parent' }),
} as const

License

Apache-2.0

版本与发布记录

@amazon/vinyl-xml 共发布 44 个版本,首次发布于 2026/05/28;过去 12 个月发布了 44 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
5.0.0latest2026/11/16今天
4.1.1-next.20261115174554next2026/11/16今天
4.1.1-next.202611151724472026/11/16今天
4.1.1-next.202611151644392026/11/16今天
4.1.1-next.202611150013552026/11/151 天前
4.1.1-next.202611131749092026/11/142 天前

其他发布通道:hotfix-chromos → 1.2.1,hotfix-close-drm-sessions → 1.2.2,next → 4.1.1-next.20261115174554。

关于 @amazon/vinyl-xml 的常见问题

@amazon/vinyl-xml 是什么?

A SAX XML parser

如何安装 @amazon/vinyl-xml?

在项目目录运行 npm install @amazon/vinyl-xml,或使用 pnpm add / yarn add / bun add。

@amazon/vinyl-xml 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@amazon/vinyl-xml 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@amazon/vinyl-xml 可以商用吗?

@amazon/vinyl-xml 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@amazon/vinyl-xml 的下载量有多少?

根据 npm 官方下载统计,@amazon/vinyl-xml 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,671 次,日均约 89 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@amazon/vinyl-xml 还在维护吗?

最新版本 5.0.0 发布于 2026/11/16(今天);至今共发布 44 个版本,其中过去 12 个月发布了 44 个;首次发布于 2026/05/28。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。