JavaScript to XML Parser

Common errors

• TypeError: js2xmlparser is not a function

  cause Attempting to call the module directly as a function after v2.0.0, e.g., `js2xmlparser(root, data, options)`.
  fix Use the `parse` method: `js2xmlparser.parse(root, data, options)` (CommonJS) or `import { parse } from 'js2xmlparser'; parse(root, data, options);` (ESM).

• ReferenceError: require is not defined

  cause Attempting to use `require()` in an ES module context (e.g., in a file where `"type": "module"` is set in `package.json` or a `.mjs` file) without proper transpilation or configuration.
  fix Switch to ES module imports: `import { parse } from 'js2xmlparser';` or ensure your environment is configured for CommonJS modules (e.g., `"type": "commonjs"` in `package.json` or use `.cjs` file extension for Node.js).

• The XML output contains unexpected self-closing tags or indentation for multi-line strings.

  cause Behavioral changes in XML output formatting introduced in v4.0.0, where self-closing tags are default and multi-line strings are no longer indented by default.
  fix Adjust options passed to the `parse` method. For example, use `{ selfClosing: false, pretty: { indent: ' ' } }` to override these defaults and regain specific formatting.

Warnings

• breaking The primary API for parsing changed significantly in v2.0.0. Direct invocation of the module (`js2xmlparser(root, data, options)`) was removed.
  Fix: Migrate all calls to `js2xmlparser.parse(root, data, options)` or `parse(root, data, options)` if using named imports.
• breaking Output formatting for multi-line strings and self-closing tags changed in v4.0.0. Multi-line strings are no longer indented by default, and self-closing tags are now the default unless specified otherwise.
  Fix: Review existing XML output expectations and adjust options as needed (e.g., `selfClosing: false` to disable self-closing tags where not desired, or configure `pretty` options for indentation).
• gotcha To define XML attributes and mixed content, specific object properties (`@` for attributes, `#` for mixed content) are used. This requires structuring JavaScript objects specifically for `js2xmlparser`'s conversion logic, which might not be intuitive for standard JSON-to-XML transformations.
  Fix: Familiarize yourself with the object structure conventions (`@` for attributes, `#` for mixed content) described in the documentation to correctly represent desired XML structures.
• breaking The module was entirely re-written in TypeScript in v2.0.0. While providing types, this could introduce subtle changes in behavior or stricter type checking compared to previous JavaScript versions, potentially affecting existing codebases during migration.
  Fix: Ensure your project is configured for TypeScript if leveraging its types, and review compilation errors that may arise from stricter type enforcement. Test thoroughly after upgrading.
• gotcha As of v5.0.0, type handlers can now be used with bare text and attribute values, but the documentation clarifies they cannot be used with aliases. This might affect custom type handler implementations or assumptions.
  Fix: Verify custom `typeHandlers` to ensure they align with the updated behavior and documentation, especially regarding usage with bare text/attribute values and the restriction with aliases.

Install

• npm install js2xmlparser npm
• yarn add js2xmlparser yarn
• pnpm add js2xmlparser pnpm

Imports

• parse
  wrong:

  const js2xmlparser = require('js2xmlparser'); js2xmlparser(root, data, options);

  correct:

  import { parse } from 'js2xmlparser';

  Since v2.0.0, the primary parsing function is a named export `parse` when using ES modules or accessed via `js2xmlparser.parse` from a CommonJS import. Direct invocation of the module `js2xmlparser(...)` was removed in v2.0.0.
• js2xmlparser (CommonJS)
  wrong:

  import * as js2xmlparser from 'js2xmlparser';

  correct:

  const js2xmlparser = require('js2xmlparser');

  For CommonJS environments, `require` is used. The `parse` method is then called as `js2xmlparser.parse(root, data, options)`. While `import * as` is valid ESM, the CJS pattern is explicit for older Node.js projects.
• Options interface
  wrong:

  import { Options } from 'js2xmlparser';

  correct:

  import type { Options } from 'js2xmlparser';

  Type definitions, including the `Options` interface, are exported by the package. Use `import type` for type-only imports to prevent potential bundling or runtime issues, especially since v4.0.2 exports these interfaces.

Quickstart

Demonstrates parsing a complex JavaScript object into XML, showcasing attribute handling, nested objects, array elements, and mixed content using the `parse` function.

import { parse } from 'js2xmlparser';

const obj = {
    "@": {
        type: "natural"
    },
    firstName: "John",
    lastName: "Smith",
    dateOfBirth: new Date(1964, 7, 26),
    address: {
        "@": {
            type: "home"
        },
        streetAddress: "3212 22nd St",
        city: "Chicago",
        state: "Illinois",
        zip: 10000
    },
    phone: [
        {
            "@": {
                type: "home"
            },
            "#": "123-555-4567"
        },
        {
            "@": {
                type: "cell"
            },
            "#": "890-555-1234"
        },
        {
            "@": {
                type: "work"
            },
            "#": "567-555-8901"
        }
    ],
    email: "john@smith.com"
};

const xmlOutput = parse("person", obj);
console.log(xmlOutput);