# xml2o

> Helps you convert XML into an object for easy reading.

Latest version **0.4.14** (published 2026-08-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install xml2o
pnpm add xml2o
yarn add xml2o
bun add xml2o
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.4.14 |
| Published | 2026-08-03 |
| First published | 2017-03-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 39.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 3 |
| Author | izatop@gmail.com |
| Maintainers | izatop |
| Keywords | sax, simple-xml, xml, xml-reader, xml-to-js |

## Links

- npm: https://www.npmjs.com/package/xml2o
- Repository: https://github.com/izatop/xml2o
- Homepage: https://github.com/izatop/xml2o#readme
- Issues: https://github.com/izatop/xml2o/issues
- npm.io page: https://npm.io/package/xml2o

## Dependencies (1)

- [sax](https://npm.io/package/sax.md) ^1.6.1

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 0.4.14 (latest) — 2026-08-03
- 0.4.13 — 2023-06-01
- 0.4.12 — 2023-06-01
- 0.4.11 — 2023-06-01
- 0.4.10 — 2023-06-01
- 0.4.9 — 2023-06-01
- 0.4.8 — 2023-06-01
- 0.4.7 — 2023-06-01
- 0.4.6 — 2023-06-01
- 0.4.5 — 2023-06-01
- 0.4.4 — 2023-06-01
- 0.4.3 — 2023-06-01
- 0.4.1 — 2023-06-01
- 0.4.0 — 2023-01-11
- 0.3.3 — 2020-03-19
- … 8 more at https://npm.io/package/xml2o/versions

## README

# xml2o

Convert XML into lightweight, queryable JavaScript objects without a DOM.

## Installation

Install `xml2o` with your package manager:

```bash
npm install xml2o
```

```bash
bun add xml2o
```

```bash
yarn add xml2o
```

## Usage

`convertString` and `convertStream` parse asynchronously and return a
`Promise<Node>`.

### ESM

```typescript
import { convertString } from "xml2o";

const root = await convertString('<root><item id="1">value</item></root>');
console.log(root.query("item")[0]?.text); // value
```

### CommonJS

```javascript
const { convertString } = require("xml2o");

async function readXml() {
    const root = await convertString('<root><item id="1">value</item></root>');
    console.log(root.query("item")[0]?.getAttribute("id")); // 1
}

readXml();
```

### Streams

Pass a Node.js readable stream to `convertStream`:

```typescript
import { createReadStream } from "node:fs";
import { convertStream } from "xml2o";

const root = await convertStream(createReadStream("/path/to/file.xml"));
```

Invalid XML rejects the returned promise, so handle conversion errors with
`try`/`catch` or `.catch()`:

```typescript
try {
    await convertString("<root><item></root>");
} catch (error) {
    console.error("Could not parse XML", error);
}
```

## API

### `convertString(xml)`

Parses an XML string and resolves to the root `Node`.

### `convertStream(stream)`

Parses a readable stream and resolves to the root `Node`.

### `Node`

A `Node` is an array of its child nodes. It exposes the element's `name`,
`local` name, `prefix`, namespace `uri`, `parent`, and `root`. Its `text`
property concatenates text and CDATA received for the node and its direct child
elements.

Use attribute helpers to read attributes:

```typescript
const item = root.query("item")[0];

item?.getAttribute("id"); // "1"
item?.hasAttribute("id"); // true
item?.getAttributeNode("id"); // Attribute | undefined
item?.getAttributes(); // { id: "1" }
```

`getAttribute`, `getAttributeNode`, and `hasAttribute` accept an optional
namespace URI as their second argument. `getAttributes(uri)` returns attributes
in that namespace; without an argument it returns non-namespaced attributes.

Use `query(path, uri?)` to find child elements by their local name. Paths have
these forms:

| Path            | Meaning                                               |
| --------------- | ----------------------------------------------------- |
| `"item"`        | Find every descendant `item` node.                    |
| `"group/item"`  | Find an `item` below a matching `group` at any depth. |
| `"/group/item"` | Follow the path from the current node.                |
| `"/"`           | Return the current node.                              |

Pass a namespace URI as the second argument to restrict matches:

```typescript
const namespacedItems = root.query("item", "urn:example");
const code = namespacedItems[0]?.getAttribute("code", "urn:example");
```

### `Attribute`

An `Attribute` exposes its `name`, `local` name, `prefix`, namespace `uri`, and
string `value`. Calling `attribute.toString()` returns its value.

## Development

This project uses Bun for development:

```bash
bun install
bun run security
bun test
bun run build
bun run check
```

## License

MIT

---
_Source: https://npm.io/package/xml2o · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._