@amazon/vinyl-xml 1.0.0

package/dist/types/ts4.7/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

package/dist/types/ts4.7/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/ts4.7/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/ts4.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 { type Invariant, type Maybe, type ReadonlyDate } from '@amazon/vinyl-util';
+import type { 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/ts4.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/ts4.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