Question about ConvertOptions and where is list of what they are

[jasonkhanlar]

Is your feature request related to a problem? Please describe.

• https://oozcitak.github.io/xmlbuilder2/builder-functions.html#convert
  • Settings related to value conversions
    • convert - An object defining converter strings. Default converter strings are described below.
      • text - when prepended to a JS object key, converts its value to a text node. Defaults to '#'.

Describe the solution you'd like
I would like to use the "convert" option like this (or at least this is what I tried first and it didn't seem to work:

let json = xmlbuilder2.convert(xml, { convert: { text: '#text' }, format: 'object' });

so then I tried:

let json = xmlbuilder2.convert({ convert: { text: '#text' }, format: 'object' }, xml);

and that didn't work either, but then reading the documentation I found what appears to be a working solution:

let json = xmlbuilder2.convert({ convert: { text: '#text' } }, xml, { format: 'object' });

and also swapping argument 1 and argument 3 positions didn't work as well, which suggest that of all 4 notations of argument input, builderOptions must always come first, and the builderOptions and convertOptions cannot be referenced/passed combined as a single options argument). Also I just discovered that clicking on each of the 4 different input types listed, it expands to show more details. This seems kind of hidden or otherwise not obvious. Perhaps a [+] symbol at beginning of the lines might help to signal that they are expandable for further details. Also, I tried searching documentation for the details, list of "convert options" to learn more about them, similarly as available with the "builder options" and I can't find any comparable information detailing what "convert options" there are. Maybe this -> https://oozcitak.github.io/xmlbuilder2/serialization.html#serialization-settings ? Or maybe https://oozcitak.github.io/xmlbuilder2/object-conversion.html ? I see "Builder Options" linked to a "Builder Functions" page: https://oozcitak.github.io/xmlbuilder2/builder-functions.html#builder-options but I can't find any "Convert Functions" page. Also another idea I just thought of, a single options argument that has two children option containers, one for BuilderOptions, and the other for ConvertOptions. Something like: { builderOptions: { ... }, convertOptions: { ... } } and to let it be any argument position.

Describe alternatives you've considered
I found a working solution to my initial problem, which satisfies my usage, however, it wasn't immediately easy-to-realize.

[jasonkhanlar]

Aha! I glanced through the actual code, and the convert function in lib/builder/BuilderFunctions.js definitely suggests that the "Serialization Settings" are the "Convert Options" https://oozcitak.github.io/xmlbuilder2/serialization.html#serialization-settings

Therefore:

ConvertOptions:

• allowEmptyTags
• format
• group
• headless
• indent
• indentTextOnlyNodes
• newline
• offset
• prettyPrint
• spaceBeforeSlash
• verbose
• wellFormed
• width

BuilderOptions:

• convert
• defaultNamespace
• encoding
• ignoreConverters
• invalidCharReplacement
• keepNullAttributes
• keepNullNodes
• parser
• standalone
• version

and it appears that not a single option name overlaps, as I was thinking would be the case. Therefore, wouldn't it be sufficient to combine the options into a single options argument input so that it can be easier to let the variety of user input types to all just work out of the box? and let the JavaScript library figure out which option is for which process?