@amazon/vinyl-xml 1.0.0

package/dist/types/ts3.7/xml/ParseXmlHandler.d.ts

@@ -0,0 +1,56 @@
+import { QName } from './QName';
+import { XmlElement } from '../xml/ParseXmlHandlerImpl';
+/**
+ * A handler for XML deserialization.
+ */
+export interface ParseXmlHandler<T> {
+    /**
+     * A new document has begun.
+     */
+    startDocument(): void;
+    /**
+     * A document has completed parsing, the final object is ready.
+     */
+    endDocument(): T & XmlElement<T>;
+    /**
+     * Invoked when a new element has been started, after the element's attributes have been read.
+     *
+     * @param name An object representing the element's name and namespace.
+     * @param attributes The attributes associated with the currently opening element.
+     */
+    startElement(name: QName, attributes: Attributes): void;
+    /**
+     * Invoked after an element closing tag.
+     */
+    endElement(): void;
+    /**
+     * Provides a raw substring as a text node. The given text is expected to be decoded using
+     * `decodeEntities`.
+     *
+     * @param str
+     */
+    textNode(str: string): void;
+    /**
+     * Provides a raw substring as a cdata node. This text is _not_ expected to be decoded.
+     *
+     * @param str
+     */
+    cDataNode(str: string): void;
+}
+/**
+ * An attribute map, where the keys are the fully qualified attribute names.
+ */
+export interface Attributes {
+    readonly [qName: string]: Attribute | undefined;
+}
+export interface Attribute {
+    /**
+     * This attribute's name.
+     */
+    readonly name: QName;
+    /**
+     * The unescaped attribute value.
+     */
+    readonly value: string;
+}
+//# sourceMappingURL=ParseXmlHandler.d.ts.map

package/dist/types/ts3.7/xml/ParseXmlHandlerImpl.d.ts

@@ -0,0 +1,49 @@
+import { Cloneable } from '@amazon/vinyl-util';
+import { XmlRules } from './xmlRules';
+import { MappedXmlRules } from './mappedXmlRules';
+import { Attributes, ParseXmlHandler } from './ParseXmlHandler';
+import { QName } from './QName';
+export interface ParseXmlHandlerOptions {
+    readonly validateRules: boolean;
+}
+/**
+ * A {@link ParseXmlHandler} implementation that follows {@link XmlRules}, building an object of
+ * the parameterized type.
+ */
+export declare class ParseXmlHandlerImpl<T> implements ParseXmlHandler<T> {
+    private readonly rules;
+    private stack;
+    private options;
+    private busy;
+    constructor(rules: MappedXmlRules<T>, options?: Partial<ParseXmlHandlerOptions>);
+    startDocument(): void;
+    startElement(name: QName, attributes: Attributes): void;
+    textNode(str: string): void;
+    cDataNode(str: string): void;
+    endElement(): void;
+    endDocument(): T & XmlElement<T>;
+    private validate;
+}
+/**
+ * Creates an XML content handler for the given parsing rules.
+ *
+ * @param rules
+ * @param options
+ */
+export declare function parseXmlHandler<T extends object>(rules: XmlRules<T>, options?: Partial<ParseXmlHandlerOptions>): ParseXmlHandlerImpl<T>;
+declare const parentSymbol: unique symbol;
+export interface XmlElement<T = any> extends Cloneable<T & XmlElement<T>> {
+    readonly parent: (XmlElement | null);
+    toJSON(): any;
+}
+export declare class XmlElementImpl<T> implements XmlElement<T> {
+    [prop: keyof any]: any;
+    private [parentSymbol];
+    constructor(parent?: XmlElement | null);
+    get parent(): XmlElement | null;
+    set parent(value: XmlElement | null);
+    clone(): T & XmlElementImpl<T>;
+    toJSON(): any;
+}
+export {};
+//# sourceMappingURL=ParseXmlHandlerImpl.d.ts.map

package/dist/types/ts3.7/xml/QName.d.ts

@@ -0,0 +1,33 @@
+import { Uri } from '../xmlns/org/w3/2001/XmlSchema';
+/**
+ * An XML name for an element or attribute.
+ */
+export interface QName {
+    /**
+     * The fully qualified name.
+     * This will be the prefixed name or the unprefixed name if the prefix is empty.
+     * The prefixed name will be `prefix ':' localPart`
+     */
+    readonly qName: string;
+    /**
+     * The xmlns prefix.
+     */
+    readonly prefix: string | null;
+    /**
+     * The local part of this name.
+     */
+    readonly localPart: string;
+    /**
+     * The resolved xmlns uri for the associated prefix.
+     */
+    readonly namespaceUri: Uri | null;
+}
+/**
+ * Creates a new {@link QName} object.
+ *
+ * @param localPart
+ * @param prefix
+ * @param namespaceUri
+ */
+export declare function qName(localPart: string, prefix?: string | null, namespaceUri?: Uri | null): QName;
+//# sourceMappingURL=QName.d.ts.map

package/dist/types/ts3.7/xml/XmlSchemaError.d.ts

@@ -0,0 +1,15 @@
+import { ReportableError } from '@amazon/vinyl-util';
+/**
+ * @private
+ */
+export declare const xmlSchemaErrorLocale: {
+    readonly atLeastElements: "Expected at least {expected} occurrences of {property} but was {actual}";
+    readonly atMostElements: "Expected at most {expected} occurrences of {property} but was {actual}";
+    readonly cyclicReferences: "Cyclic reference detected";
+    readonly requiredAttribute: "Attribute '{property}' is required";
+};
+export declare class XmlSchemaError extends ReportableError {
+    get [Symbol.toStringTag](): string;
+    constructor(message: string);
+}
+//# sourceMappingURL=XmlSchemaError.d.ts.map

package/dist/types/ts3.7/xml/mappedXmlRules.d.ts

@@ -0,0 +1,118 @@
+import { AnyRecord, Invariant } from '@amazon/vinyl-util';
+import { XmlRules } from './xmlRules';
+import { Uri } from '../xmlns/org/w3/2001/XmlSchema';
+/**
+ * A machine-readable representation of parse rules for random access based on qualified namespace
+ * keys.
+ *
+ * Rule keys will either be `namespaceUri:localPart` or just `localPart` for wildcard rules if
+ * namespaceUri is not defined in the handler.
+ */
+export interface MappedXmlRules<T> {
+    /**
+     * Enforces that this rule set can only be used to parse the expected type T.
+     */
+    readonly __type: Invariant<T>;
+    readonly attributes: ReadonlyMap<string, MappedAttributeRule>;
+    readonly elements: ReadonlyMap<string, MappedElementsRule>;
+    readonly characters: MappedCharactersRule | undefined;
+}
+export interface MappedAttributeRule {
+    /**
+     * The property name.
+     */
+    readonly property: keyof any;
+    /**
+     * If true, a parsing error will be thrown if the value is undefined.
+     */
+    readonly required: boolean;
+    /**
+     * If the current element has no matching attribute, default will be used.
+     */
+    readonly default: any;
+    /**
+     * Parses the attribute value.
+     */
+    readonly parse: (value: string) => any;
+    /**
+     * Converts the attribute value to a string.
+     */
+    readonly stringify: (value: any) => string;
+    /**
+     * The local part of the QName.
+     */
+    readonly localPart: string;
+    /**
+     * The namespace uri that must match.
+     */
+    readonly namespaceUri: Uri | null;
+}
+export interface MappedElementsRule {
+    /**
+     * The name of the property to set on the parent element.
+     */
+    readonly property: keyof any;
+    /**
+     * True if the parsed elements should populate into an array.
+     */
+    readonly array: boolean;
+    /**
+     * The minimum number of elements.
+     */
+    readonly minOccurs: number;
+    /**
+     * The maximum number of elements. Use null for unbounded.
+     */
+    readonly maxOccurs: number | null;
+    /**
+     * If true and there are 0 occurrences of the element, the parsed value will be an empty array
+     * instead of undefined.
+     */
+    readonly useEmptyArrays: boolean;
+    /**
+     * Returns the mappings for matched element(s).
+     */
+    readonly rules: () => MappedXmlRules<any>;
+    /**
+     * The local part of the QName.
+     */
+    readonly localPart: string;
+    /**
+     * The namespace uri that must match.
+     */
+    readonly namespaceUri: Uri | null;
+}
+export interface MappedCharactersRule {
+    readonly property: keyof any;
+    /**
+     * Parses the unescaped/processed characters.
+     * This will always be called, but characters may be an empty string if the element has no
+     * text content.
+     */
+    readonly parse: (characters: string) => any;
+    /**
+     * Converts the value to a string.
+     */
+    readonly stringify: (value: any) => string;
+}
+/**
+ * An empty rules map, used when there was no match for the started element.
+ * @private
+ */
+export declare const EmptyRules: MappedXmlRules<AnyRecord>;
+/**
+ * Creates machine-friendly content handler rules from the given {@link XmlRules}.
+ *
+ * @param rules The {@link XmlRules} to convert.
+ * @param parentNamespaceUri
+ */
+export declare function mapXmlRules<T extends object>(rules: XmlRules<T>, parentNamespaceUri?: Uri | null): MappedXmlRules<T>;
+/**
+ * Creates a rule key for mapped xml rules.
+ *
+ * @private
+ * @param localPart The {@link QName.localPart}
+ * @param namespaceUri The `namespaceUri` of the element.
+ */
+export declare function xmlRuleKey(localPart: string, namespaceUri?: Uri | null): string;
+//# sourceMappingURL=mappedXmlRules.d.ts.map

package/dist/types/ts3.7/xml/mergeXmlRules.d.ts

@@ -0,0 +1,118 @@
+import { Fun } from '@amazon/vinyl-util';
+import { XmlRules } from '../xml/xmlRules';
+/**
+ * Recursively merges array types so that S[] & T[] becomes (S & T)[]
+ * When two array elements parsing rules are merged, the result is an array with intersected
+ * element types.
+ */
+export type Merged<T> = T extends readonly any[] ? any : T extends Fun ? T : T extends object ? {
+    [P in keyof T]: any;
+} : T;
+/**
+ * `[S0, T0] & [S1, T1]` cannot be converted to `[S0 & S1, T0 & T1]`, but we can at least preserve
+ * the tuple when not intersected.
+ *
+ * Intersected tuples become arrays. E.g. `[S0, T0] & [S1, T1]` becomes `Array<S0 | S1 | T0 | T1>`
+ */
+export type MergedTupleOrArray<T extends readonly any[]> = T extends [
+    infer V0
+] ? [
+    any
+] : T extends [
+    infer V0,
+    infer V1
+] ? [
+    any,
+    any
+] : T extends [
+    infer V0,
+    infer V1,
+    infer V2
+] ? [
+    any,
+    any,
+    any
+] : T extends [
+    infer V0,
+    infer V1,
+    infer V2,
+    infer V3
+] ? [
+    any,
+    any,
+    any,
+    any
+] : T extends [
+    infer V0,
+    infer V1,
+    infer V2,
+    infer V3,
+    infer V4
+] ? [
+    any,
+    any,
+    any,
+    any,
+    any
+] : T extends any[] ? Array<any> : T extends readonly [
+    infer V0
+] ? readonly [
+    any
+] : T extends readonly [
+    infer V0,
+    infer V1
+] ? readonly [
+    any,
+    any
+] : T extends readonly [
+    infer V0,
+    infer V1,
+    infer V2
+] ? readonly [
+    any,
+    any,
+    any
+] : T extends readonly [
+    infer V0,
+    infer V1,
+    infer V2,
+    infer V3
+] ? readonly [
+    any,
+    any,
+    any,
+    any
+] : T extends readonly [
+    infer V0,
+    infer V1,
+    infer V2,
+    infer V3,
+    infer V4
+] ? readonly [
+    any,
+    any,
+    any,
+    any,
+    any
+] : ReadonlyArray<any>;
+/**
+ * Merges the given two xml rule sets into one.
+ */
+export declare function mergeXmlRules<A extends object, B extends object>(a: XmlRules<A>, b: XmlRules<B>): XmlRules<Merged<A & B>>;
+/**
+ * Merges the given three xml rule sets into one.
+ */
+export declare function mergeXmlRules<A extends object, B extends object, C extends object>(a: XmlRules<A>, b: XmlRules<B>, c: XmlRules<C>): XmlRules<Merged<A & B & C>>;
+/**
+ * Merges the given four xml rule sets into one.
+ */
+export declare function mergeXmlRules<A extends object, B extends object, C extends object, D extends object>(a: XmlRules<A>, b: XmlRules<B>, c: XmlRules<C>, d: XmlRules<D>): XmlRules<Merged<A & B & C & D>>;
+/**
+ * Merges the given five xml rule sets into one.
+ */
+export declare function mergeXmlRules<A extends object, B extends object, C extends object, D extends object, E extends object>(a: XmlRules<A>, b: XmlRules<B>, c: XmlRules<C>, d: XmlRules<D>, e: XmlRules<E>): XmlRules<Merged<A & B & C & D & E>>;
+/**
+ * Merges the given six xml rule sets into one.
+ */
+export declare function mergeXmlRules<A extends object, B extends object, C extends object, D extends object, E extends object, F extends object>(a: XmlRules<A>, b: XmlRules<B>, c: XmlRules<C>, d: XmlRules<D>, e: XmlRules<E>, f: XmlRules<F>): XmlRules<Merged<A & B & C & D & E & F>>;
+//# sourceMappingURL=mergeXmlRules.d.ts.map

package/dist/types/ts3.7/xml/parseXml.d.ts

@@ -0,0 +1,76 @@
+import { MutableDeep, StringReader } from '@amazon/vinyl-util';
+import { Uri } from '../xmlns/org/w3/2001/XmlSchema';
+import { Attributes, ParseXmlHandler } from './ParseXmlHandler';
+import { QName } from './QName';
+import { 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/ts3.7/xml/stringifyXml.d.ts

@@ -0,0 +1,67 @@
+import { OptionalDeep } from '@amazon/vinyl-util';
+import { Uri } from '../xmlns/org/w3/2001/XmlSchema';
+import { MappedXmlRules } from './mappedXmlRules';
+import { 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