@amazon/vinyl-xml 1.0.0

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

@@ -0,0 +1,207 @@
+/*
+* A set of utilities for easily writing schema-based rule definitions to be used with the
+* `parseXml` parser.
+*
+* @module
+*/
+import { Invariant, Maybe, ReadonlyDate } from '@amazon/vinyl-util';
+import { Uri } from '../xmlns/org/w3/2001/XmlSchema';
+export declare enum XmlRuleType {
+    CHARACTERS = "characters",
+    ATTRIBUTE = "attribute",
+    ELEMENT = "element",
+    ELEMENTS = "elements"
+}
+/**
+ * Reserved keys that may not be used in XmlRules.
+ *
+ * If a schema uses a reserved word, set `localPart` in the rule options to associate.
+ */
+export type ReservedXmlRuleKeys = 'parent' | 'clone' | 'toJSON';
+/**
+ * A schema for XML serialization and deserialization.
+ *
+ * The parser values may be lazy, represented as a function that returns a property parser.
+ * @typeParam T The object type these parsing rules model.
+ */
+export type XmlRules<T extends object> = {
+    readonly [P in Exclude<keyof T, ReservedXmlRuleKeys>]-?: XmlRule<T[P]> | LazyXmlRule<T[P]>;
+};
+/**
+ * A union of the supported parsing types.
+ */
+export type XmlRule<T> = AttributeRule<T> | CharactersRule<T> | ElementsRule<T & (readonly object[] | undefined)> | ElementRule<T & (object | undefined)>;
+/**
+ * A function that returns a property handler.
+ * Useful when there are recursive rules.
+ */
+export type LazyXmlRule<T> = () => XmlRule<T>;
+export interface NamespacedRuleOptions {
+    /**
+     * Matches the `QName.localPart` of the element. If undefined, this will match against
+     * the property name from {@link XmlRules}.
+     */
+    readonly localPart?: string | undefined;
+    /**
+     * Matches the `namespaceUri` of the element or attribute.
+     *
+     * If null, this will only match against a null namespace.
+     * If undefined, this will default to the namespace of the parent element for elements, or
+     * null for attributes.
+     *
+     * Note that attributes do not inherit default namespaces as elements do.
+     */
+    readonly namespaceUri?: Maybe<Uri>;
+}
+/**
+ * A rule definition for a list of elements.
+ */
+export interface ElementsRule<T extends readonly object[] | undefined> extends Required<ElementsRuleOptions> {
+    readonly type: XmlRuleType.ELEMENTS;
+    /**
+     * Prevents rule from losing nullable type information.
+     */
+    readonly __invariant?: Invariant<T>;
+    /**
+     * Returns the schema for matched elements.
+     * These rules will be applied per element, collecting into an array.
+     */
+    readonly rules: XmlRules<NonNullable<T>[number]>;
+}
+export interface ElementsRuleOptions extends NamespacedRuleOptions {
+    /**
+     * 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;
+}
+/**
+ * A rule definition for a single element.
+ */
+export interface ElementRule<T extends object | undefined> extends Required<ElementRuleOptions> {
+    /**
+     * Prevents rule from losing nullable type information.
+     */
+    readonly __invariant?: Invariant<T>;
+    readonly type: XmlRuleType.ELEMENT;
+    /**
+     * Returns the schema for the matched element.
+     */
+    readonly rules: XmlRules<NonNullable<T>>;
+}
+export interface ElementRuleOptions extends NamespacedRuleOptions {
+    /**
+     * If true, a parsing error will be thrown if the value is undefined.
+     */
+    readonly required?: boolean;
+}
+/**
+ * A rule definition for an attribute.
+ */
+export interface AttributeRule<T> extends Required<AttributeRuleOptions<T>> {
+    readonly type: XmlRuleType.ATTRIBUTE;
+    /**
+     * Parses the attribute value.
+     */
+    readonly parse: (value: string) => T;
+    /**
+     * Stringifies the value.
+     */
+    readonly stringify: (value: NonNullable<T>) => string;
+}
+export interface AttributeRuleOptions<T> extends NamespacedRuleOptions {
+    /**
+     * 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?: T | undefined;
+    /**
+     * Matches the `namespaceUri` of the attribute.
+     *
+     * If null, this will only match against a null namespace.
+     *
+     * Note that attributes do not inherit default namespaces as elements do.
+     */
+    readonly namespaceUri?: Uri | null;
+}
+/**
+ * A rule definition for an element's text content.
+ */
+export interface CharactersRule<T> {
+    readonly type: XmlRuleType.CHARACTERS;
+    /**
+     * 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) => T;
+    /**
+     * Stringifies the value.
+     */
+    readonly stringify: (value: NonNullable<T>) => string;
+}
+export interface RequiredElementRuleOptions extends ElementRuleOptions {
+    readonly required: true;
+}
+export declare function element<T extends object>(rules: XmlRules<T>, options: RequiredElementRuleOptions): ElementRule<T>;
+export declare function element<T extends object | undefined>(rules: XmlRules<NonNullable<T>>, options?: ElementRuleOptions): ElementRule<T | undefined>;
+/**
+ * Elements options that guarantee that there is a non-null array.
+ * For minOccurs types greater than 10, a type cast is required.
+ */
+export type RequiredElementsOptions = (ElementsRuleOptions & {
+    readonly useEmptyArrays: true;
+}) | (ElementsRuleOptions & {
+    readonly minOccurs: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
+});
+export declare function elements<T extends object>(rules: XmlRules<T>, options: RequiredElementsOptions): ElementsRule<readonly T[]>;
+export declare function elements<T extends object>(rules: XmlRules<T>, options?: ElementsRuleOptions): ElementsRule<readonly T[] | undefined>;
+/**
+ * Parses the text content of the current element via the given parse and stringify functions.
+ *
+ * Does not currently support mixing text and element nodes.
+ * E.g. the XML `<note>Dear <name>John</name>, I regret to inform you...</note>` could not be
+ * serialized or deserialized using xml rule mappings.
+ *
+ * @param parse The string passed to this parser is the processed text content of the current
+ * element.
+ * @param stringify Serializes the value.
+ *
+ * @see processCharacters
+ */
+export declare function characters<T>(parse: (str: string) => T, stringify: (value: T) => string): CharactersRule<T>;
+/**
+ * Handles the processed text content without any modification.
+ *
+ * @see characters
+ */
+export declare const charactersString: CharactersRule<string>;
+export type RequiredAttributeOptions<T> = AttributeRuleOptions<T> & ({
+    required: true;
+} | {
+    default: T;
+});
+export declare function attr<T>(parse: (value: string) => T, stringify: (value: T) => string, options: RequiredAttributeOptions<T>): AttributeRule<T>;
+export declare function attr<T>(parse: (value: string) => T, stringify: (value: NonNullable<T>) => string, options?: AttributeRuleOptions<T>): AttributeRule<T | undefined>;
+export declare function attrString(options: RequiredAttributeOptions<string>): AttributeRule<string>;
+export declare function attrString(options?: AttributeRuleOptions<string>): AttributeRule<string | undefined>;
+export declare function attrInt(options: RequiredAttributeOptions<number>): AttributeRule<number>;
+export declare function attrInt(options?: AttributeRuleOptions<number>): AttributeRule<number | undefined>;
+export declare function attrFloat(options: RequiredAttributeOptions<number>): AttributeRule<number>;
+export declare function attrFloat(options?: AttributeRuleOptions<number>): AttributeRule<number | undefined>;
+export declare function attrBoolean(options: RequiredAttributeOptions<boolean>): AttributeRule<boolean>;
+export declare function attrBoolean(options?: AttributeRuleOptions<boolean>): AttributeRule<boolean | undefined>;
+export declare function attrDateTime(options: RequiredAttributeOptions<Date>): AttributeRule<ReadonlyDate>;
+export declare function attrDateTime(options?: AttributeRuleOptions<ReadonlyDate>): AttributeRule<ReadonlyDate | undefined>;
+//# sourceMappingURL=xmlRules.d.ts.map

package/dist/types/ts3.7/xmlns/org/w3/1999/xlink.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A subset of types defined in xlink xml schema needed for dash parsing.
+ * Source: https://www.w3.org/TR/xlink/
+ * @module
+ */
+export type actuateType = 'onLoad' | 'onRequest';
+//# sourceMappingURL=xlink.d.ts.map

package/dist/types/ts3.7/xmlns/org/w3/2001/XmlSchema.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A subset of types defined in 2001 XmlSchema needed for dash parsing.
+ * Source: https://www.w3.org/2001/XmlSchema.xsd
+ *
+ * @module
+ */
+/**
+ * A Uniform Resource Identifier Reference
+ */
+export type Uri = string;
+export interface Base64BinaryType {
+    _content: string;
+}
+export interface UriType {
+    _content: Uri;
+}
+//# sourceMappingURL=XmlSchema.d.ts.map

package/dist/types/ts4.1/index.d.ts

@@ -0,0 +1,14 @@
+/** Auto-generated from build scripts */
+export * from './xmlns/org/w3/2001/XmlSchema';
+export * from './xmlns/org/w3/1999/xlink';
+export * from './xml/xmlRules';
+export * from './xml/stringifyXml';
+export * from './xml/parseXml';
+export * from './xml/mergeXmlRules';
+export * from './xml/mappedXmlRules';
+export * from './xml/XmlSchemaError';
+export * from './xml/QName';
+export * from './xml/ParseXmlHandlerImpl';
+export * from './xml/ParseXmlHandler';
+export * from './xlink/actuateValidator';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/ts4.1/xlink/actuateValidator.d.ts

@@ -0,0 +1,3 @@
+import type { actuateType } from '../xmlns/org/w3/1999/xlink';
+export declare function assertActuateEnum(str: string): actuateType;
+//# sourceMappingURL=actuateValidator.d.ts.map

package/dist/types/ts4.1/xml/ParseXmlHandler.d.ts

@@ -0,0 +1,56 @@
+import type { QName } from './QName';
+import type { 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/ts4.1/xml/ParseXmlHandlerImpl.d.ts

@@ -0,0 +1,49 @@
+import type { Cloneable } from '@amazon/vinyl-util';
+import type { XmlRules } from './xmlRules';
+import type { MappedXmlRules } from './mappedXmlRules';
+import type { Attributes, ParseXmlHandler } from './ParseXmlHandler';
+import type { 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/ts4.1/xml/QName.d.ts

@@ -0,0 +1,33 @@
+import type { 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/ts4.1/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/ts4.1/xml/mappedXmlRules.d.ts

@@ -0,0 +1,118 @@
+import type { AnyRecord, Invariant } from '@amazon/vinyl-util';
+import type { XmlRules } from './xmlRules';
+import type { 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/ts4.1/xml/mergeXmlRules.d.ts

@@ -0,0 +1,118 @@
+import type { Fun } from '@amazon/vinyl-util';
+import type { 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[] ? MergedTupleOrArray<T> : T extends Fun ? T : T extends object ? {
+    [P in keyof T]: Merged<T[P]>;
+} : 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
+] ? [
+    Merged<V0>
+] : T extends [
+    infer V0,
+    infer V1
+] ? [
+    Merged<V0>,
+    Merged<V1>
+] : T extends [
+    infer V0,
+    infer V1,
+    infer V2
+] ? [
+    Merged<V0>,
+    Merged<V1>,
+    Merged<V2>
+] : T extends [
+    infer V0,
+    infer V1,
+    infer V2,
+    infer V3
+] ? [
+    Merged<V0>,
+    Merged<V1>,
+    Merged<V2>,
+    Merged<V3>
+] : T extends [
+    infer V0,
+    infer V1,
+    infer V2,
+    infer V3,
+    infer V4
+] ? [
+    Merged<V0>,
+    Merged<V1>,
+    Merged<V2>,
+    Merged<V3>,
+    Merged<V4>
+] : T extends any[] ? Array<Merged<T[number]>> : T extends readonly [
+    infer V0
+] ? readonly [
+    Merged<V0>
+] : T extends readonly [
+    infer V0,
+    infer V1
+] ? readonly [
+    Merged<V0>,
+    Merged<V1>
+] : T extends readonly [
+    infer V0,
+    infer V1,
+    infer V2
+] ? readonly [
+    Merged<V0>,
+    Merged<V1>,
+    Merged<V2>
+] : T extends readonly [
+    infer V0,
+    infer V1,
+    infer V2,
+    infer V3
+] ? readonly [
+    Merged<V0>,
+    Merged<V1>,
+    Merged<V2>,
+    Merged<V3>
+] : T extends readonly [
+    infer V0,
+    infer V1,
+    infer V2,
+    infer V3,
+    infer V4
+] ? readonly [
+    Merged<V0>,
+    Merged<V1>,
+    Merged<V2>,
+    Merged<V3>,
+    Merged<V4>
+] : ReadonlyArray<Merged<T[number]>>;
+/**
+ * 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