@amazon/vinyl-xml 1.0.0

package/dist/types/current/xml/mergeXmlRules.js

@@ -0,0 +1,89 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { plainObjectMergeRule, substitute, ValidationError, } from '@amazon/vinyl-util';
+import { XmlRuleType, } from '../xml/xmlRules';
+const locale = {
+    illegalRuleOverrideTypeError: 'Cannot override the rule {property} of type {sourceType} with a rule of type {overrideType}',
+    illegalQNameOverrideError: 'Cannot override the rule {property} with a different localPart or namespace',
+};
+/**
+ * Merges the given rules into one ruleset.
+ *
+ * @param rules
+ * @return A new XmlRules map with the merged rules.
+ */
+export function mergeXmlRules(...rules) {
+    let finalRule = rules[0];
+    for (let i = 1; i < rules.length; i++) {
+        finalRule = plainObjectMergeRule.merge(finalRule, rules[i], mergeXmlRule);
+    }
+    return finalRule;
+}
+function mergeXmlRule(sourceA, sourceB, prop) {
+    if (sourceA == null)
+        return sourceB;
+    const sourceAIsLazy = typeof sourceA === 'function';
+    const sourceBIsLazy = typeof sourceB === 'function';
+    if (sourceAIsLazy || sourceBIsLazy) {
+        return () => {
+            const a = sourceAIsLazy ? sourceA() : sourceA;
+            const b = sourceBIsLazy ? sourceB() : sourceB;
+            return mergeXmlRule(a, b, prop);
+        };
+    }
+    if (sourceA.type !== sourceB.type) {
+        throw new ValidationError(substitute(locale.illegalRuleOverrideTypeError, {
+            property: prop,
+            sourceType: sourceA.type,
+            overrideType: sourceB.type,
+        }));
+    }
+    switch (sourceA.type) {
+        case XmlRuleType.ATTRIBUTE:
+        case XmlRuleType.ELEMENT:
+        case XmlRuleType.ELEMENTS: {
+            const b = sourceB;
+            if (sourceA.namespaceUri !== b.namespaceUri ||
+                (sourceA.localPart ?? prop) !== (b.localPart ?? prop)) {
+                throw new ValidationError(substitute(locale.illegalQNameOverrideError, {
+                    property: prop,
+                }));
+            }
+            break;
+        }
+    }
+    switch (sourceA.type) {
+        case XmlRuleType.ATTRIBUTE: {
+            const b = sourceB;
+            return {
+                ...b,
+                default: b.default ?? sourceA.default,
+            };
+        }
+        case XmlRuleType.CHARACTERS:
+            return sourceB;
+        case XmlRuleType.ELEMENT: {
+            const b = sourceB;
+            return {
+                ...b,
+                required: sourceA.required || b.required,
+                rules: mergeXmlRules(sourceA.rules, b.rules),
+            };
+        }
+        case XmlRuleType.ELEMENTS: {
+            const b = sourceB;
+            const maxOccurs = sourceA.maxOccurs != null && b.maxOccurs != null
+                ? Math.min(sourceA.maxOccurs, b.maxOccurs)
+                : (sourceA.maxOccurs ?? b.maxOccurs);
+            return {
+                ...b,
+                minOccurs: Math.max(sourceA.minOccurs, b.minOccurs),
+                maxOccurs,
+                useEmptyArrays: sourceA.useEmptyArrays || b.useEmptyArrays,
+                rules: mergeXmlRules(sourceA.rules, b.rules),
+            };
+        }
+    }
+}

package/dist/types/current/xml/parseXml.d.ts

@@ -0,0 +1,76 @@
+import { type MutableDeep, StringReader } from '@amazon/vinyl-util';
+import type { Uri } from '../xmlns/org/w3/2001/XmlSchema';
+import type { Attributes, ParseXmlHandler } from './ParseXmlHandler';
+import type { QName } from './QName';
+import type { XmlElement } from './ParseXmlHandlerImpl';
+export declare const XMLNS = "http://www.w3.org/2000/xmlns/";
+/**
+ * Nested xml elements push current namespace information onto a stack.
+ *
+ * @private
+ */
+export interface StackElement {
+    /**
+     * The qualified name of the current element on the stack. Used to validate expected closing
+     * element.
+     */
+    readonly qName: string;
+    /**
+     * The (mutable) namespaces map for the current stack.
+     */
+    readonly namespaceMap: Namespaces;
+    /**
+     * The default namespace.
+     */
+    defaultNamespaceUri: Uri | null;
+}
+/**
+ * Parses an XML document using a partial sax-style content handler.
+ * This allows for parsing without the entire document being read into memory first.
+ *
+ * XML Documents are mapped to data structures through content handlers instead of needing an
+ * intermediate model.
+ */
+export declare function parseXml<T>(str: string, handler: ParseXmlHandler<T>): T & XmlElement<T>;
+/**
+ * @private
+ */
+export type Namespaces = Map<string, Uri | null>;
+/**
+ * Given that the cursor is at a ' or ", reads the sequence of characters until an end quote is
+ * reached.
+ * The returned unescaped string is the text within the quotes.
+ * @private
+ */
+export declare function readAttributeValue(c: StringReader): string;
+/**
+ * Reads until the end of the tag >
+ * @private
+ */
+export declare function untilTagClose(c: StringReader): void;
+/**
+ * Returns true if the char code is a valid xml name character.
+ * @see https://www.w3.org/TR/2008/REC-xml-20081126/#NT-NameChar
+ * @param charCode
+ * @private
+ */
+export declare function isNameChar(charCode: number): boolean;
+/**
+ * Reads an xml {@link QName}.
+ * The {@link QName.namespaceUri} returned will be null; it must be separately looked up.
+ *
+ * @param reader The current string reader.
+ * @private
+ */
+export declare function readQName(reader: StringReader): MutableDeep<QName>;
+/**
+ * Reads a series of xml attributes, separated by whitespace.
+ * Example: `ns1:key1="value1" key2 key3='value3'`
+ * Note: consumes all whitespace before and after attributes series.
+ *
+ * @return Returns a map of attribute `qName:string` to `Attribute` objects.
+ *
+ * @private
+ */
+export declare function xmlAttributes(reader: StringReader, stackElement: StackElement): MutableDeep<Attributes>;
+//# sourceMappingURL=parseXml.d.ts.map

package/dist/types/current/xml/parseXml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseXml.d.ts","sourceRoot":"","sources":["../../../../src/xml/parseXml.ts"],"names":[],"mappings":"AAKA,OAAO,EAIH,KAAK,WAAW,EAChB,YAAY,EACf,MAAM,oBAAoB,CAAA;AAE3B,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,+BAA+B,CAAA;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACpE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAEvD,eAAO,MAAM,KAAK,kCAAkC,CAAA;AAapD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IACzB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IAEtB;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAA;IAEjC;;OAEG;IACH,mBAAmB,EAAE,GAAG,GAAG,IAAI,CAAA;CAClC;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACtB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAC5B,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CA6HnB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,GAAG,IAAI,CAAC,CAAA;AAGhD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI,CAYnD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAkCpD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,CAAC,KAAK,CAAC,CAalE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CACzB,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,YAAY,GAC3B,WAAW,CAAC,UAAU,CAAC,CA8BzB"}

package/dist/types/current/xml/parseXml.js

@@ -0,0 +1,305 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { char, decodeEntities, last, StringReader, } from '@amazon/vinyl-util';
+export const XMLNS = 'http://www.w3.org/2000/xmlns/';
+const LT = char('<');
+const GT = char('>');
+const EQ = char('=');
+const SLASH = char('/');
+const COLON = char(':');
+const QMARK = char('?');
+const EXCL = char('!');
+const APOS = char("'");
+const QUOT = char('"');
+const QUOTES = new Set([APOS, QUOT]);
+/**
+ * Parses an XML document using a partial sax-style content handler.
+ * This allows for parsing without the entire document being read into memory first.
+ *
+ * XML Documents are mapped to data structures through content handlers instead of needing an
+ * intermediate model.
+ */
+export function parseXml(str, handler) {
+    const c = new StringReader(str);
+    let current = {
+        qName: '#document',
+        namespaceMap: new Map(),
+        defaultNamespaceUri: null,
+    };
+    const stack = [current];
+    /**
+     * Provides the namespace uri for the given prefix on the current stack.
+     * @param prefix
+     */
+    const namespaceLookup = (prefix) => {
+        if (!prefix)
+            return current.defaultNamespaceUri;
+        for (let i = stack.length - 1; i >= 0; i--) {
+            const map = stack[i].namespaceMap;
+            if (map.has(prefix))
+                return stack[i].namespaceMap.get(prefix);
+        }
+        return null;
+    };
+    try {
+        handler.startDocument();
+    }
+    catch (e) {
+        c.err(e.message);
+    }
+    while (c.hasNext()) {
+        const charsStart = c.untilChar(LT);
+        if (charsStart < c.position) {
+            const chars = str.substring(charsStart, c.position);
+            try {
+                handler.textNode(chars);
+            }
+            catch (e) {
+                c.err(e.message);
+            }
+        }
+        if (!c.hasNext())
+            break; // eos
+        c.next(); // <
+        if (c.charIf(SLASH)) {
+            // </ prepare for ending the element.
+            c.white();
+            const name = readQName(c);
+            if (name.qName !== current.qName)
+                c.err(`Expected </${current.qName}> but was </${name.qName}>`);
+            stack.pop();
+            current = last(stack);
+            c.white();
+            c.readChar(GT);
+            try {
+                handler.endElement();
+            }
+            catch (e) {
+                c.err(e.message);
+            }
+        }
+        else if (c.charIf(QMARK)) {
+            // <? Processing instruction
+            untilTagClose(c);
+        }
+        else if (c.charIf(EXCL)) {
+            // <! Declaration
+            if (c.charIf(0x2d /* - */)) {
+                c.readChar(0x2d);
+                // <!-- Comment
+                c.untilString('-->');
+                c.read('-->');
+            }
+            else if (c.stringIf('[CDATA[')) {
+                // <![CDATA[
+                const charsStart = c.untilString(']]>');
+                try {
+                    handler.cDataNode(str.substring(charsStart, c.position));
+                }
+                catch (e) {
+                    c.err(e.message);
+                }
+                c.read(']]>');
+            }
+            else {
+                // <! Declaration
+                untilTagClose(c);
+            }
+        }
+        else {
+            // < Prepare for beginning the element
+            // Create a new stack element, inheriting the namespaces of the parent.
+            const name = readQName(c);
+            current = {
+                qName: name.qName,
+                namespaceMap: new Map(),
+                defaultNamespaceUri: current.defaultNamespaceUri,
+            };
+            stack.push(current);
+            const attributes = xmlAttributes(c, current);
+            // The namespaces can only be looked up after all attributes are parsed;
+            // a namespace prefix may be defined after it's used on the same element.
+            name.namespaceUri = namespaceLookup(name.prefix);
+            for (const attributesKey in attributes) {
+                const value = attributes[attributesKey];
+                const name = value.name;
+                // Attributes do not inherit the default namespace.
+                if (name.prefix && !name.namespaceUri) {
+                    name.namespaceUri = namespaceLookup(name.prefix);
+                }
+            }
+            try {
+                handler.startElement(name, attributes);
+            }
+            catch (e) {
+                c.err(e.message);
+            }
+            if (c.charIf(SLASH)) {
+                c.readChar(GT);
+                stack.pop();
+                current = last(stack);
+                // Closed tag <example/>
+                try {
+                    handler.endElement();
+                }
+                catch (e) {
+                    c.err(e.message);
+                }
+            }
+            else {
+                c.readChar(GT);
+            }
+        }
+    }
+    try {
+        return handler.endDocument();
+    }
+    catch (e) {
+        return c.err(e.message);
+    }
+}
+// noinspection GrazieInspection
+/**
+ * Given that the cursor is at a ' or ", reads the sequence of characters until an end quote is
+ * reached.
+ * The returned unescaped string is the text within the quotes.
+ * @private
+ */
+export function readAttributeValue(c) {
+    const quote = c.next();
+    if (!QUOTES.has(quote))
+        c.err('Expected \' or "');
+    const value = c.substringUntil((charCode) => charCode === quote);
+    c.readChar(quote);
+    return decodeEntities(value);
+}
+/**
+ * Reads until the end of the tag >
+ * @private
+ */
+export function untilTagClose(c) {
+    while (true) {
+        c.until((c) => c === APOS || c === QUOT || c === GT);
+        const char = c.next();
+        if (QUOTES.has(char)) {
+            c.untilChar(char);
+            c.next();
+        }
+        else {
+            // >
+            break;
+        }
+    }
+}
+/**
+ * Returns true if the char code is a valid xml name character.
+ * @see https://www.w3.org/TR/2008/REC-xml-20081126/#NT-NameChar
+ * @param charCode
+ * @private
+ */
+export function isNameChar(charCode) {
+    if (charCode >= 0x61 /* a */) {
+        if (charCode >= 0xb7 /* · */) {
+            if (charCode >= 0x300) {
+                if (charCode >= 0x203f) {
+                    return charCode <= 0x2040;
+                }
+                else {
+                    return charCode <= 0x36f;
+                }
+            }
+            else {
+                return charCode === 0xb7; /* · */
+            }
+        }
+        else {
+            return charCode <= 0x7a; /* z */
+        }
+    }
+    else {
+        if (charCode >= 0x5f /* _ */) {
+            return charCode === 0x5f;
+        }
+        else {
+            if (charCode >= 0x41 /* A */) {
+                return charCode <= 0x5a; /* Z */
+            }
+            else {
+                if (charCode >= 0x2d /* - */) {
+                    if (charCode >= 0x30 /* 0 */) {
+                        return charCode <= 0x39; /* 9 */
+                    }
+                    else {
+                        return charCode <= 0x2e; /* . */
+                    }
+                }
+                else {
+                    return false;
+                }
+            }
+        }
+    }
+}
+/**
+ * Reads an xml {@link QName}.
+ * The {@link QName.namespaceUri} returned will be null; it must be separately looked up.
+ *
+ * @param reader The current string reader.
+ * @private
+ */
+export function readQName(reader) {
+    const prefixOrLocalName = reader.substringWhile(isNameChar);
+    let prefix, localPart, name;
+    if (reader.charIf(COLON)) {
+        prefix = prefixOrLocalName;
+        localPart = reader.substringWhile(isNameChar);
+        name = `${prefix}:${localPart}`;
+    }
+    else {
+        prefix = null;
+        localPart = prefixOrLocalName;
+        name = localPart;
+    }
+    return { prefix, localPart, qName: name, namespaceUri: null };
+}
+/**
+ * Reads a series of xml attributes, separated by whitespace.
+ * Example: `ns1:key1="value1" key2 key3='value3'`
+ * Note: consumes all whitespace before and after attributes series.
+ *
+ * @return Returns a map of attribute `qName:string` to `Attribute` objects.
+ *
+ * @private
+ */
+export function xmlAttributes(reader, stackElement) {
+    const attributes = {};
+    while (true) {
+        reader.white();
+        if (!isNameChar(reader.peek))
+            break;
+        const name = readQName(reader);
+        reader.white();
+        let value = '';
+        if (reader.charIf(EQ)) {
+            reader.white();
+            value = readAttributeValue(reader);
+        }
+        else {
+            // Attributes without values are valid in html, but not xml
+        }
+        if (name.prefix === 'xmlns') {
+            name.namespaceUri = XMLNS;
+            stackElement.namespaceMap.set(name.localPart, value === '' ? null : value);
+        }
+        else if (!name.prefix && name.localPart === 'xmlns') {
+            name.namespaceUri = XMLNS;
+            stackElement.defaultNamespaceUri = !value ? null : value;
+        }
+        if (attributes[name.qName] != null)
+            reader.err(`Attribute '${name.qName}' is already specified.`);
+        attributes[name.qName] = { name, value };
+    }
+    return attributes;
+}

package/dist/types/current/xml/stringifyXml.d.ts

@@ -0,0 +1,67 @@
+import { type OptionalDeep } from '@amazon/vinyl-util';
+import type { Uri } from '../xmlns/org/w3/2001/XmlSchema';
+import type { MappedXmlRules } from './mappedXmlRules';
+import type { ReservedXmlRuleKeys } from '../xml/xmlRules';
+export interface StringifyOptions {
+    /**
+     * The indentation. Default: 4 spaces
+     */
+    readonly indent: string;
+    /**
+     * The character(s) between lines. Default: \n
+     */
+    readonly newline: string;
+    /**
+     * A map of namespace uri to prefix strings.
+     * If a namespace is not found, a prefix will be generated.
+     */
+    readonly prefixMap: ReadonlyMap<Uri, string>;
+    /**
+     * If true, will include the XML declaration at the beginning of the stringified document.
+     * `<?xml version="1.0"?>`
+     */
+    readonly includeXmlDeclaration: boolean;
+}
+export declare class XmlWriter<T> {
+    private readonly rules;
+    private readonly options;
+    private readonly usedPrefixes;
+    private readonly traversed;
+    constructor(rules: MappedXmlRules<T>, options?: Partial<StringifyOptions>);
+    stringify(object: OptionalDeep<T, ReservedXmlRuleKeys>): string;
+    private qName;
+    /**
+     * Stringifies an element.
+     *
+     * @param object
+     * @param rule
+     * @param state
+     */
+    private stringifyElement;
+    /**
+     * Stringifies an element's attributes.
+     *
+     * @param object
+     * @param attributes
+     * @return Returns the attributes string. This will include a leading space if there are any
+     * found attributes.
+     */
+    private stringifyAttributes;
+    /**
+     * Stringifies a property as a CDATA node.
+     *
+     * @param object
+     * @param charactersRule
+     */
+    private stringifyCharacters;
+    /**
+     * Stringifies an element's child elements.
+     *
+     * @param object
+     * @param elements
+     * @param state
+     */
+    private stringifyChildren;
+}
+export declare function stringifyXml<T>(object: OptionalDeep<T, ReservedXmlRuleKeys>, rules: MappedXmlRules<T>, options?: Partial<StringifyOptions>): string;
+//# sourceMappingURL=stringifyXml.d.ts.map

package/dist/types/current/xml/stringifyXml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stringifyXml.d.ts","sourceRoot":"","sources":["../../../../src/xml/stringifyXml.ts"],"names":[],"mappings":"AAKA,OAAO,EAIH,KAAK,YAAY,EAEpB,MAAM,oBAAoB,CAAA;AAE3B,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,+BAA+B,CAAA;AACxD,OAAO,KAAK,EAIR,cAAc,EACjB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAazD,MAAM,WAAW,gBAAgB;IAC7B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IAEvB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAExB;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IAE5C;;;OAGG;IACH,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAA;CAC1C;AASD,qBAAa,SAAS,CAAC,CAAC;IAMhB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAL1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;gBAGjB,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EACzC,OAAO,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC;IAQvC,SAAS,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,mBAAmB,CAAC,GAAG,MAAM;IAY/D,OAAO,CAAC,KAAK;IAcb;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IA2DxB;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IA+B3B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAU3B;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;CA0D5B;AAcD,wBAAgB,YAAY,CAAC,CAAC,EAC1B,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,mBAAmB,CAAC,EAC5C,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EACxB,OAAO,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACpC,MAAM,CAGR"}