xml-event-parser 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2019-2026 Xihua Duan and contributors
+
+Includes work contributed to osm2geojson-lite by Harel Mazor.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,223 @@
-# Temporary Holding Version
+xml-event-parser
+================
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A tiny XML parser with a document tree and path-based events, produced in a
+single pass.
+
+- **Zero dependencies**, no DOM, no `node:*` imports, no `eval`.
+- **One pass, two views**: every element is available as a tree node and as an
+  `open`/`close` event keyed by its dotted path, so a consumer can convert while
+  parsing without a second traversal.
+- **Streaming**: feed `write(chunk)` from a file or socket and call `end()`.
+  Chunks may split anywhere - mid-tag, mid-attribute, inside CDATA or a comment -
+  and `retain` decides whether the parser keeps the tree, one root, or nothing,
+  so a 60 MiB document can be parsed with ~0 MiB of retained heap.
+- **Small**: 6.1 KiB minified, 2.1 KiB gzipped (ESM), streaming included.
+- **Fastest on every shape we benchmarked**: ~1.9x `txml`'s throughput on
+  OSM-style documents at ~30% less retained heap, and ahead of `txml` on
+  text/entity-heavy input too; ~1.6x `htmlparser2`'s on element callbacks. See
+  [Benchmarks](#benchmarks).
+
+```js
+import { XmlParser } from 'xml-event-parser';
+
+const parser = new XmlParser({ progressive: true });
+
+parser.on('</osm.way>', (way) => {
+    // way.tagName === 'way', way.id, way.version, way.children ...
+    console.log(way.id, way.children?.length ?? 0);
+});
+
+const roots = parser.parse(xml);
+```
+
+## Node shape
+
+```ts
+interface XmlNode {
+    tagName: string;          // element name, e.g. 'way'
+    children?: XmlNode[];     // present only when the element has child elements
+    text?: string;            // present only for text-only elements
+    [attribute: string]: any; // attributes, copied flat onto the node
+}
+```
+
+Attributes are flat rather than nested in an `attributes` object on purpose: one
+object per element keeps a parsed document small (see the heap column in
+[`bench/RESULTS.md`](bench/RESULTS.md)). Names that collide with `tagName`,
+`children` or `text` are shadowed by the element's own values; if that matters
+for your vocabulary, read attributes off the source XML instead.
+
+An element with nested tags is emitted on close **after** its children are
+attached, so `node.children` is complete inside a close listener.
+
+## Streaming
+
+```js
+import { createReadStream } from 'node:fs';
+import { XmlParser } from 'xml-event-parser';
+
+const parser = new XmlParser({ progressive: true, retain: 'none' });
+parser.on('</osm.way>', (way) => {
+    // one complete element; `way` is released after this returns
+});
+
+for await (const chunk of createReadStream('planet.osm.xml', 'utf8')) {
+    parser.write(chunk);
+}
+parser.end();
+```
+
+`write()` consumes everything complete in the buffer and keeps the rest for the
+next call, so a chunk boundary can fall inside a tag, an attribute value, a text
+run, a comment or a `]]>` terminator without changing the result: parsing a
+document whole or in 1-byte chunks produces the same tree (the suite checks every
+split point).
+
+`retain` is what makes streaming bounded:
+
+| `retain` | keeps | `end()` returns | memory |
+| --- | --- | --- | --- |
+| `'all'` (default) | the document | the roots | grows with the document |
+| `'root'` | the root being built | `[]`; a finished root is emitted and dropped | largest root |
+| `'none'` | nothing | `[]`; every element is emitted and dropped | nesting depth |
+
+Measured on a 60 MiB document (ten concatenated extracts, 327k elements):
+`retain: 'all'` holds 302 MiB, `retain: 'none'` holds ~0 MiB, both emit the same
+327k elements. Without listeners, `retain: 'none'` still parses - it just throws
+the result away.
+
+## Events
+
+| form | fires |
+| --- | --- |
+| `'<osm.way>'` | when a `<way>` inside `<osm>` opens |
+| `'</osm.way>'` | when it closes, with `children` populated |
+
+The path is the dotted chain of ancestors. Event names are only built for paths
+that have a listener, so subscribing to one path costs nothing for the elements
+you ignore. Filter inside the listener:
+
+```js
+parser.on('</osm.way>', (way) => {
+    if (!way.tags) return; // or any other predicate
+});
+```
+
+## Options
+
+| option | default | meaning |
+| --- | --- | --- |
+| `progressive` | `false` | emit events. Without it, `parse()` only builds the tree |
+| `queryParent` | `false` | track parents so `parser.getParent(node)` works (costs a `WeakMap`) |
+| `retain` | `'all'` | what survives an element: `'all'`, `'root'` or `'none'` (see [Streaming](#streaming)) |
+
+`parse(xml, parent?, dir?)` also accepts an existing node to attach the parsed
+roots to, and a dotted path prefix used when building event names.
+
+The parser is non-validating and never throws on malformed input: unterminated
+tags, comments, processing instructions and doctypes are skipped, and elements
+still open at end of input are closed so a truncated download yields the
+document parsed so far (`'<r><a>text'` returns `r` with an `a` child whose
+`text` is `'text'`).
+
+CDATA sections are content, not markup: their text is kept verbatim and is not
+entity-decoded, while text outside them is decoded (the five predefined
+entities and numeric character references).
+
+## Benchmarks
+
+Six generated shapes, each isolating one cost (per-element, per-child, text,
+nesting). Methodology, per-shape tables and caveats live in
+[`bench/RESULTS.md`](bench/RESULTS.md); rerun with `npm run bench:data && npm run bench`.
+
+Realistic Overpass-style document, 6.0 MiB, Apple M4 Pro / Node 26:
+
+| workload | xml-event-parser | txml | fast-xml-parser | sax | htmlparser2 |
+| --- | --- | --- | --- | --- | --- |
+| tree (parse + walk) | **26.0 ms, 230 MB/s** | 50.6 ms, 118 MB/s | 167.8 ms, 36 MB/s | — | — |
+| tree, retained heap | **30.0 MiB** | 42.5 MiB | 35.2 MiB | — | — |
+| element callbacks | **27.8 ms, 215 MB/s** | — | — | 100.0 ms, 60 MB/s | 44.9 ms, 133 MB/s |
+| streamed, 64 KiB chunks | **27.3 ms, 219 MB/s** | 77.4 ms, 77 MB/s | — | 103.3 ms, 58 MB/s | 50.8 ms, 118 MB/s |
+
+Notes on reading the table:
+
+- The callback and streamed rows for `xml-event-parser` use `retain: 'none'`, so
+  they do not build a document either; the tree row is the only one that holds
+  memory. `txml`'s streaming API is a Node stream (`transformStream`), measured
+  separately and asynchronously.
+- Text-heavy documents with many entities and CDATA used to be the weak shape;
+  replacing the regex decoder with a manual scan took it from 325 to 442 MB/s,
+  ahead of `txml` (382 MB/s).
+
+## Status
+
+Extracted from [osm2geojson-lite](https://github.com/tibetty/osm2geojson-lite),
+where this parser served until 2.2.0 and was then replaced by a purpose-built
+OSM scanner. The code and its original unit tests are unchanged apart from the
+public naming (`children`/`tagName`/`text` instead of `$innerNodes`/`$tag`/
+`$innerText`) and the removal of the `new Function`-based conditioned-path
+events.
+
+Not published yet. The release workflow publishes only when the repository
+variable `NPM_TRUSTED_PUBLISHER` is `true`; before that, a release is published
+locally because npm cannot configure a trusted publisher for a package that does
+not exist yet.
+
+## Development
+
+```sh
+npm ci
+npm test              # unit tests
+npm run typecheck
+npm run build         # dist/index.mjs, dist/index.cjs, dist/index.d.ts
+npm run bench:data    # generate ~27 MiB benchmark corpus (gitignored)
+npm run bench         # compare against txml / sax / htmlparser2 / fast-xml-parser
+```
+
+## Releasing
+
+`release.yml` publishes with npm trusted publishing (OIDC) and is gated on the
+repository variable `NPM_TRUSTED_PUBLISHER`, which stays unset until a trusted
+publisher exists.
+
+One-time bootstrap, because npm cannot attach a trusted publisher to a package
+that does not exist yet:
+
+1. Publish the first version locally:
+
+   ```sh
+   npm login
+   npm publish --access public
+   ```
+
+2. npmjs.com -> Packages -> `xml-event-parser` -> Settings -> **Trusted
+   publishing** -> GitHub Actions:
+
+   | field | value |
+   | --- | --- |
+   | Organization or user | `tibetty` |
+   | Repository | `xml-event-parser` |
+   | Workflow filename | `release.yml` (filename only, case-sensitive) |
+   | Environment name | leave empty |
+   | Allowed actions | tick **npm publish** |
+
+   Configurations created after September 2026 default to `npm stage publish`
+   only, so `npm publish` has to be ticked explicitly. The first publish through
+   that workflow must complete within **two days**, or the configuration expires.
+
+3. GitHub -> Settings -> Secrets and variables -> Actions -> Variables: add
+   `NPM_TRUSTED_PUBLISHER` = `true`.
+
+4. Optional hardening, once a workflow publish has succeeded: npmjs.com ->
+   package Settings -> Publishing access -> *Require two-factor authentication
+   and disallow tokens*.
+
+After that, changing `version` in `package.json` on `main` publishes through
+`release.yml`, tags `v<version>` and creates the GitHub release. npm generates
+provenance automatically only for a public repository; from a private one the
+package is published without an attestation.
+
+## License
+
+MIT. Includes work contributed to `osm2geojson-lite` by Harel Mazor.

package/dist/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e){switch(e){case`amp`:return`&`;case`lt`:return`<`;case`gt`:return`>`;case`quot`:return`"`;case`apos`:return`'`}if(e.charCodeAt(0)===35){let t=e.charCodeAt(1)===120||e.charCodeAt(1)===88?parseInt(e.slice(2),16):parseInt(e.slice(1),10);if(Number.isFinite(t)&&t>=0&&t<=1114111)return String.fromCodePoint(t)}return null}function t(t){let n=t.indexOf(`&`);if(n<0)return t;let r=t.slice(0,n);for(;n<t.length;){let i=t.indexOf(`;`,n+1);if(i<0){r+=t.slice(n);break}let a=e(t.slice(n+1,i));if(r+=a===null?t.slice(n,i+1):a,n=t.indexOf(`&`,i+1),n<0){r+=t.slice(i+1);break}r+=t.slice(i+1,n)}return r}function n(e){if(e.indexOf(`<![CDATA[`)<0)return e.indexOf(`&`)<0?e:t(e);let n=``,r=0;for(;r<e.length;){let i=e.indexOf(`<![CDATA[`,r);if(i<0){n+=t(e.slice(r));break}i>r&&(n+=t(e.slice(r,i)));let a=e.indexOf(`]]>`,i+9);if(a<0){n+=e.slice(i+9);break}n+=e.slice(i+9,a),r=a+3}return n}function r(e){return e===32||e===9||e===10||e===13}var i=class{constructor(e){this.queryParent=!1,this.progressive=!1,this.retain=`all`,this.parentMap=/* @__PURE__ */ new WeakMap,this.evtListeners={},this.openListenerCount=0,this.watchedPaths=/* @__PURE__ */ new Set,this.watchedChildren=/* @__PURE__ */ new Map,this.watchedTopLevel=/* @__PURE__ */ new Set,this.buffer=``,this.cursor=0,this.stack=[],this.roots=[],this.basePath=``,this.active=!1,e&&(this.queryParent=e.queryParent===!0,this.progressive=e.progressive===!0,e.retain&&(this.retain=e.retain))}write(e){return this.active||this.begin(void 0,void 0),e.length===0||(this.buffer.length===0?this.buffer=e:this.buffer+=e,this.consume(!1)),this}end(){if(!this.active)return[];this.consume(!0),this.finish();let e=this.roots;return this.reset(),e}parse(e,t,n){return this.begin(t,n),this.write(e),this.end()}begin(e,t){this.buffer=``,this.cursor=0,this.stack=[],this.roots=[],this.basePath=t||``,this.top=e?{node:e,fullTag:this.basePath,textStart:0}:void 0,this.rootOwner=this.top,this.parentMap=/* @__PURE__ */ new WeakMap,this.active=!0}reset(){this.buffer=``,this.cursor=0,this.stack=[],this.roots=[],this.top=void 0,this.rootOwner=void 0,this.basePath=``,this.active=!1}attach(e,t){if(this.retain===`none`)return;if(t===void 0){this.retain===`all`&&this.roots.push(e);return}let n=t.children;n?n.push(e):t.children=[e]}consume(e){let t=this.buffer,r=t.length,i=this.progressive,a=i&&this.openListenerCount>0,o=this.cursor,s=-1;for(;o<r;){let c=t.indexOf(`<`,o);if(c<0||(s=c,o=c+1,o>=r))break;let l=t.charCodeAt(o);if(l===47){let a=t.indexOf(`>`,o);if(a<0){if(!e)break;o=r;break}let l=this.stack.pop();if(o=a+1,s=-1,!l)continue;let u=l.node,d=this.stack.length?this.stack[this.stack.length-1]:this.rootOwner,f=d?d.node:void 0;!l.hasChild&&c>l.textStart&&(u.text=n(t.slice(l.textStart,c))),i&&this.watchedPaths.has(l.fullTag)&&this.emit(`</`+l.fullTag+`>`,u,f),this.attach(u,f),d&&(d.hasChild=!0),this.top=d;continue}if(l===63){let n=t.indexOf(`>`,o);if(n<0){if(!e)break;o=r;break}o=n+1,s=-1;continue}if(l===33){let n;if(t.charCodeAt(o+1)===45&&t.charCodeAt(o+2)===45?(n=t.indexOf(`-->`,o+3),n=n<0?-1:n+3):t.startsWith(`![CDATA[`,o)?(n=t.indexOf(`]]>`,o+9),n=n<0?-1:n+3):(n=t.indexOf(`>`,o),n=n<0?-1:n+1),n<0){if(!e)break;o=r;break}o=n,s=-1;continue}let u=this.parseOpenTag(t,o,r,e);if(u===null)break;o=u.end,s=-1;let d=u.node,f=u.tag,p=this.top?this.top.node:void 0;if(this.queryParent&&p&&this.parentMap.set(d,p),u.selfClose){if(i){let e=this.top?this.top.fullTag:this.basePath,t=e?this.watchedChildren.get(e):this.watchedTopLevel;if(t&&t.has(f)){let t=e?e+`.`+f:f;a&&this.emit(`<`+t+`>`,d,p),this.emit(`</`+t+`>`,d,p)}}this.attach(d,p),this.top&&(this.top.hasChild=!0);continue}let m=this.top?this.top.fullTag?this.top.fullTag+`.`+f:f:this.basePath?this.basePath+`.`+f:f;a&&this.watchedPaths.has(m)&&this.emit(`<`+m+`>`,d,p);let h={node:d,fullTag:m,textStart:o};this.stack.push(h),this.top=h}this.cursor=e?r:s>=0?s:o,e||this.compact()}parseOpenTag(e,n,i,a){let o=n;for(;o<i;){let t=e.charCodeAt(o);if(r(t)||t===47||t===62)break;o++}if(o>=i&&!a)return null;let s=e.slice(n,o),c={tagName:s},l=!1;for(;o<i;){let n=e.charCodeAt(o);for(;o<i&&r(n);)n=e.charCodeAt(++o);if(o>=i)break;if(n===62)return o++,{node:c,tag:s,selfClose:l,end:o};if(n===47){l=!0,o++;continue}let u=o;for(;o<i&&(n=e.charCodeAt(o),!(n===61||r(n)||n===62||n===47));)o++;if(o>=i&&!a)return null;let d=e.slice(u,o);for(;o<i&&r(e.charCodeAt(o));)o++;if(o>=i&&!a)return null;if(e.charCodeAt(o)===61){for(o++;o<i&&r(e.charCodeAt(o));)o++;if(o>=i&&!a)return null;let n=e.charCodeAt(o);if(n===34||n===39){o++;let r=e.indexOf(n===34?`"`:`'`,o);if(r<0){if(!a)return null;r=i}let s=e.slice(o,r);c[d]=s.indexOf(`&`)<0?s:t(s),o=r+1}}else d&&(c[d]=``)}return a?{node:c,tag:s,selfClose:l,end:o}:null}finish(){let e=this.buffer,t=e.length;for(;this.stack.length>0;){let r=this.stack.pop(),i=r.node;!r.hasChild&&t>r.textStart&&(i.text=n(e.slice(r.textStart,t)),t=r.textStart);let a=this.stack.length?this.stack[this.stack.length-1]:this.rootOwner,o=a?a.node:void 0;this.attach(i,o)}}compact(){let e=this.cursor;for(let t=this.stack.length-1;t>=0;t--){let n=this.stack[t];if(!n.hasChild){e=n.textStart;break}}if(!(e<=0)){this.buffer=this.buffer.slice(e),this.cursor-=e;for(let t=0;t<this.stack.length;t++){let n=this.stack[t];n.textStart=n.textStart>e?n.textStart-e:0}this.rootOwner&&(this.rootOwner.textStart=0)}}getParent(e){return this.queryParent?this.parentMap.get(e):null}addListener(e,t){this.$addListener(e,t)}removeListener(e,t){this.$removeListener(e,t)}on(e,t){this.addListener(e,t)}off(e,t){this.removeListener(e,t)}$addListener(e,t){let n=this.evtListeners[e];if(n?n.push(t):this.evtListeners[e]=[t],e.charCodeAt(1)!==47&&this.openListenerCount++,e.charCodeAt(0)===60){let t=e.slice(e.charCodeAt(1)===47?2:1,e.length-1);this.watchedPaths.add(t);let n=t.lastIndexOf(`.`);if(n<0)this.watchedTopLevel.add(t);else{let e=t.slice(0,n),r=this.watchedChildren.get(e);r||(r=/* @__PURE__ */ new Set,this.watchedChildren.set(e,r)),r.add(t.slice(n+1))}}}$removeListener(e,t){let n=this.evtListeners[e],r=-1;n&&(r=n.indexOf(t)),r>=0&&(n.splice(r,1),e.charCodeAt(1)!==47&&this.openListenerCount--)}emit(e,t,n){let r=this.evtListeners[e];if(r)for(let e=0;e<r.length;e++)r[e](t,n)}};exports.XmlParser=i,exports.decodeEntities=t;

package/dist/index.d.ts

@@ -0,0 +1,152 @@
+/**
+ * One parsed element.
+ *
+ * Attributes are copied onto the node as own properties (flat, so a document
+ * costs one object per element), which is why the type carries an index
+ * signature. `text` is set only for elements without child elements.
+ */
+interface XmlNode {
+  tagName: string;
+  children?: XmlNode[];
+  text?: string;
+  [attribute: string]: any;
+}
+/** Listener signature for the path-based events. */
+type XmlListener = (node: XmlNode, parent?: XmlNode) => void;
+/**
+ * Decode XML entities.
+ *
+ * A manual scan beats `String.replace` with a callback by ~2.5x on OSM-sized
+ * attribute values: no regex, no match object and no per-entity closure. The
+ * `indexOf` guard keeps entity-free values allocation-free, and unknown
+ * entities are left exactly as written.
+ */
+export declare function decodeEntities(value: string): string;
+type Retain = 'all' | 'root' | 'none';
+interface XmlParserOptions {
+  /** Emit `<path>` / `</path>` events as elements open and close. Default `false`. */
+  progressive?: boolean;
+  /** Track parents so `getParent(node)` works. Default `false`. */
+  queryParent?: boolean;
+  /**
+   * What the parser keeps after an element closes:
+   * - `'all'` (default) the whole document tree, returned by `end()`
+   * - `'root'` the root being built; a finished top-level element is emitted
+   *   and dropped, so memory is bounded by the largest root
+   * - `'none'` nothing; every element is emitted and dropped, so memory is
+   *   bounded by the nesting depth. Combine with listeners: an element
+   *   nobody listens for is parsed and discarded.
+   */
+  retain?: Retain;
+}
+export declare class XmlParser {
+  private queryParent;
+  private progressive;
+  private retain;
+  private parentMap;
+  private evtListeners;
+  /**
+   * Number of registered open-tag (`<path>`) listeners; lets the scanner skip
+   * building open-event strings for the overwhelmingly common leaf elements.
+   */
+  private openListenerCount;
+  /**
+   * Exact paths that have at least one listener, the child paths keyed by
+   * their parent path, and top-level listeners. These let the scanner skip
+   * building event strings for the many `<nd>`/`<tag>` leaves that nobody
+   * observes.
+   */
+  private watchedPaths;
+  private watchedChildren;
+  private watchedTopLevel;
+  /** Input not consumed yet: pending text plus any construct split by a chunk. */
+  private buffer;
+  /** Next position to scan in `buffer`. */
+  private cursor;
+  private stack;
+  private roots;
+  private top;
+  private rootOwner;
+  private basePath;
+  private active;
+  constructor(opts?: XmlParserOptions);
+  /**
+   * Feed a chunk of XML.
+   *
+   * Chunks may split anywhere: inside a tag, an attribute value, a comment, a
+   * CDATA section or a text run. Anything incomplete is kept and resumed on
+   * the next `write()`; call `end()` when the input is exhausted.
+   */
+  write(chunk: string): this;
+  /**
+   * Finish the document: close elements still open at the end of input and
+   * return the top-level nodes (empty for `retain: 'root' | 'none'`).
+   */
+  end(): XmlNode[];
+  /**
+   * Parse a complete XML string in one pass.
+   *
+   * Equivalent to `write(xml).end()`, and the only entry point you need
+   * unless the document arrives in pieces.
+   *
+   * @param xml - the XML source to scan.
+   * @param parent - optional pre-existing node that owns the parsed content;
+   * when supplied, top-level nodes attach to its `children` instead of being
+   * returned as roots.
+   * @param dir - optional dotted tag-path prefix applied to emitted event names.
+   * @returns the top-level nodes (empty when a `parent` owns them).
+   */
+  parse(xml: string, parent?: XmlNode, dir?: string): XmlNode[];
+  private begin;
+  private reset;
+  /**
+   * Store a closed element according to the retention mode.
+   *
+   * `parentNode === undefined` means the element is top-level (a root), which
+   * `retain: 'root'` drops after emitting it.
+   */
+  private attach;
+  /** Scan everything in `buffer` that is complete, or all of it at `end()`. */
+  private consume;
+  /**
+   * Parse one opening tag at `from` (just past `<`).
+   *
+   * Returns `null` when the tag is not complete and more input may follow; at
+   * `final` an unterminated tag is accepted as far as it goes, which is what
+   * keeps truncated documents usable.
+   */
+  private parseOpenTag;
+  /**
+   * Close elements still open at the end of input instead of dropping them:
+   * a truncated download keeps the document parsed so far.
+   */
+  private finish;
+  /**
+   * Drop consumed input.
+   *
+   * Everything before the innermost open element is dead: its text has not
+   * been read yet, and ancestors with children never read theirs. Keeping the
+   * buffer from there is what makes a streamed document cost the pending text
+   * rather than the whole file.
+   */
+  private compact;
+  /** Parent of a node parsed with `queryParent: true`, otherwise `null`. */
+  getParent(node: any): any;
+  /**
+   * Register a listener for an event.
+   *
+   * Event names are the dotted tag path, prefixed with `<` for an opening
+   * element and `</` for a closing one: `'<osm.way>'`, `'</osm.way>'`.
+   * Filter inside the listener - `if (node.tagName !== 'way') return;` - and
+   * an unobserved path costs nothing, because the scanner skips building
+   * event names nobody listens for.
+   */
+  addListener(evt: string, func: XmlListener): void;
+  removeListener(evt: string, func: XmlListener): void;
+  on(evt: string, func: XmlListener): void;
+  off(evt: string, func: XmlListener): void;
+  private $addListener;
+  private $removeListener;
+  private emit;
+}
+export type { Retain, XmlListener, XmlNode, XmlParserOptions };

package/dist/index.mjs

@@ -0,0 +1 @@
+function e(e){switch(e){case`amp`:return`&`;case`lt`:return`<`;case`gt`:return`>`;case`quot`:return`"`;case`apos`:return`'`}if(e.charCodeAt(0)===35){let t=e.charCodeAt(1)===120||e.charCodeAt(1)===88?parseInt(e.slice(2),16):parseInt(e.slice(1),10);if(Number.isFinite(t)&&t>=0&&t<=1114111)return String.fromCodePoint(t)}return null}function t(t){let n=t.indexOf(`&`);if(n<0)return t;let r=t.slice(0,n);for(;n<t.length;){let i=t.indexOf(`;`,n+1);if(i<0){r+=t.slice(n);break}let a=e(t.slice(n+1,i));if(r+=a===null?t.slice(n,i+1):a,n=t.indexOf(`&`,i+1),n<0){r+=t.slice(i+1);break}r+=t.slice(i+1,n)}return r}function n(e){if(e.indexOf(`<![CDATA[`)<0)return e.indexOf(`&`)<0?e:t(e);let n=``,r=0;for(;r<e.length;){let i=e.indexOf(`<![CDATA[`,r);if(i<0){n+=t(e.slice(r));break}i>r&&(n+=t(e.slice(r,i)));let a=e.indexOf(`]]>`,i+9);if(a<0){n+=e.slice(i+9);break}n+=e.slice(i+9,a),r=a+3}return n}function r(e){return e===32||e===9||e===10||e===13}var i=class{constructor(e){this.queryParent=!1,this.progressive=!1,this.retain=`all`,this.parentMap=/* @__PURE__ */ new WeakMap,this.evtListeners={},this.openListenerCount=0,this.watchedPaths=/* @__PURE__ */ new Set,this.watchedChildren=/* @__PURE__ */ new Map,this.watchedTopLevel=/* @__PURE__ */ new Set,this.buffer=``,this.cursor=0,this.stack=[],this.roots=[],this.basePath=``,this.active=!1,e&&(this.queryParent=e.queryParent===!0,this.progressive=e.progressive===!0,e.retain&&(this.retain=e.retain))}write(e){return this.active||this.begin(void 0,void 0),e.length===0||(this.buffer.length===0?this.buffer=e:this.buffer+=e,this.consume(!1)),this}end(){if(!this.active)return[];this.consume(!0),this.finish();let e=this.roots;return this.reset(),e}parse(e,t,n){return this.begin(t,n),this.write(e),this.end()}begin(e,t){this.buffer=``,this.cursor=0,this.stack=[],this.roots=[],this.basePath=t||``,this.top=e?{node:e,fullTag:this.basePath,textStart:0}:void 0,this.rootOwner=this.top,this.parentMap=/* @__PURE__ */ new WeakMap,this.active=!0}reset(){this.buffer=``,this.cursor=0,this.stack=[],this.roots=[],this.top=void 0,this.rootOwner=void 0,this.basePath=``,this.active=!1}attach(e,t){if(this.retain===`none`)return;if(t===void 0){this.retain===`all`&&this.roots.push(e);return}let n=t.children;n?n.push(e):t.children=[e]}consume(e){let t=this.buffer,r=t.length,i=this.progressive,a=i&&this.openListenerCount>0,o=this.cursor,s=-1;for(;o<r;){let c=t.indexOf(`<`,o);if(c<0||(s=c,o=c+1,o>=r))break;let l=t.charCodeAt(o);if(l===47){let a=t.indexOf(`>`,o);if(a<0){if(!e)break;o=r;break}let l=this.stack.pop();if(o=a+1,s=-1,!l)continue;let u=l.node,d=this.stack.length?this.stack[this.stack.length-1]:this.rootOwner,f=d?d.node:void 0;!l.hasChild&&c>l.textStart&&(u.text=n(t.slice(l.textStart,c))),i&&this.watchedPaths.has(l.fullTag)&&this.emit(`</`+l.fullTag+`>`,u,f),this.attach(u,f),d&&(d.hasChild=!0),this.top=d;continue}if(l===63){let n=t.indexOf(`>`,o);if(n<0){if(!e)break;o=r;break}o=n+1,s=-1;continue}if(l===33){let n;if(t.charCodeAt(o+1)===45&&t.charCodeAt(o+2)===45?(n=t.indexOf(`-->`,o+3),n=n<0?-1:n+3):t.startsWith(`![CDATA[`,o)?(n=t.indexOf(`]]>`,o+9),n=n<0?-1:n+3):(n=t.indexOf(`>`,o),n=n<0?-1:n+1),n<0){if(!e)break;o=r;break}o=n,s=-1;continue}let u=this.parseOpenTag(t,o,r,e);if(u===null)break;o=u.end,s=-1;let d=u.node,f=u.tag,p=this.top?this.top.node:void 0;if(this.queryParent&&p&&this.parentMap.set(d,p),u.selfClose){if(i){let e=this.top?this.top.fullTag:this.basePath,t=e?this.watchedChildren.get(e):this.watchedTopLevel;if(t&&t.has(f)){let t=e?e+`.`+f:f;a&&this.emit(`<`+t+`>`,d,p),this.emit(`</`+t+`>`,d,p)}}this.attach(d,p),this.top&&(this.top.hasChild=!0);continue}let m=this.top?this.top.fullTag?this.top.fullTag+`.`+f:f:this.basePath?this.basePath+`.`+f:f;a&&this.watchedPaths.has(m)&&this.emit(`<`+m+`>`,d,p);let h={node:d,fullTag:m,textStart:o};this.stack.push(h),this.top=h}this.cursor=e?r:s>=0?s:o,e||this.compact()}parseOpenTag(e,n,i,a){let o=n;for(;o<i;){let t=e.charCodeAt(o);if(r(t)||t===47||t===62)break;o++}if(o>=i&&!a)return null;let s=e.slice(n,o),c={tagName:s},l=!1;for(;o<i;){let n=e.charCodeAt(o);for(;o<i&&r(n);)n=e.charCodeAt(++o);if(o>=i)break;if(n===62)return o++,{node:c,tag:s,selfClose:l,end:o};if(n===47){l=!0,o++;continue}let u=o;for(;o<i&&(n=e.charCodeAt(o),!(n===61||r(n)||n===62||n===47));)o++;if(o>=i&&!a)return null;let d=e.slice(u,o);for(;o<i&&r(e.charCodeAt(o));)o++;if(o>=i&&!a)return null;if(e.charCodeAt(o)===61){for(o++;o<i&&r(e.charCodeAt(o));)o++;if(o>=i&&!a)return null;let n=e.charCodeAt(o);if(n===34||n===39){o++;let r=e.indexOf(n===34?`"`:`'`,o);if(r<0){if(!a)return null;r=i}let s=e.slice(o,r);c[d]=s.indexOf(`&`)<0?s:t(s),o=r+1}}else d&&(c[d]=``)}return a?{node:c,tag:s,selfClose:l,end:o}:null}finish(){let e=this.buffer,t=e.length;for(;this.stack.length>0;){let r=this.stack.pop(),i=r.node;!r.hasChild&&t>r.textStart&&(i.text=n(e.slice(r.textStart,t)),t=r.textStart);let a=this.stack.length?this.stack[this.stack.length-1]:this.rootOwner,o=a?a.node:void 0;this.attach(i,o)}}compact(){let e=this.cursor;for(let t=this.stack.length-1;t>=0;t--){let n=this.stack[t];if(!n.hasChild){e=n.textStart;break}}if(!(e<=0)){this.buffer=this.buffer.slice(e),this.cursor-=e;for(let t=0;t<this.stack.length;t++){let n=this.stack[t];n.textStart=n.textStart>e?n.textStart-e:0}this.rootOwner&&(this.rootOwner.textStart=0)}}getParent(e){return this.queryParent?this.parentMap.get(e):null}addListener(e,t){this.$addListener(e,t)}removeListener(e,t){this.$removeListener(e,t)}on(e,t){this.addListener(e,t)}off(e,t){this.removeListener(e,t)}$addListener(e,t){let n=this.evtListeners[e];if(n?n.push(t):this.evtListeners[e]=[t],e.charCodeAt(1)!==47&&this.openListenerCount++,e.charCodeAt(0)===60){let t=e.slice(e.charCodeAt(1)===47?2:1,e.length-1);this.watchedPaths.add(t);let n=t.lastIndexOf(`.`);if(n<0)this.watchedTopLevel.add(t);else{let e=t.slice(0,n),r=this.watchedChildren.get(e);r||(r=/* @__PURE__ */ new Set,this.watchedChildren.set(e,r)),r.add(t.slice(n+1))}}}$removeListener(e,t){let n=this.evtListeners[e],r=-1;n&&(r=n.indexOf(t)),r>=0&&(n.splice(r,1),e.charCodeAt(1)!==47&&this.openListenerCount--)}emit(e,t,n){let r=this.evtListeners[e];if(r)for(let e=0;e<r.length;e++)r[e](t,n)}};export{i as XmlParser,t as decodeEntities};

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "xml-event-parser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Tiny dependency-free XML parser with a tree and path-based events in one pass",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tibetty/xml-event-parser.git"
+  },
+  "homepage": "https://github.com/tibetty/xml-event-parser#readme",
+  "bugs": {
+    "url": "https://github.com/tibetty/xml-event-parser/issues"
+  },
+  "keywords": [
+    "xml",
+    "parser",
+    "events",
+    "tree",
+    "streaming",
+    "zero-dependency"
+  ],
+  "main": "dist/index.cjs",
+  "scripts": {
+    "build": "rolldown -c",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "bench:data": "node bench/generate.mjs",
+    "bench": "node --expose-gc bench/run.mjs",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "fast-xml-parser": "^5.12.1",
+    "htmlparser2": "^12.0.0",
+    "rolldown": "^1.3.2",
+    "rolldown-plugin-dts": "^0.30.2",
+    "sax": "^1.6.1",
+    "txml": "^6.0.3",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  },
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  }
+}