@mkven/xml-parser 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,7 @@
 # @mkven/xml-parser
 
+[![npm](https://img.shields.io/npm/v/@mkven/xml-parser)](https://www.npmjs.com/package/@mkven/xml-parser)
+
 Opinionated XML parsing utilities built on top of [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser). Designed for processing XML data feeds — both as raw buffers and from ZIP archives.
 
 ## Installation
@@ -21,6 +23,14 @@ Parses XML buffers and readable streams with the following conventions:
 - **Whitespace** in attribute values is normalized (tabs, newlines, ` `, invisible Unicode → collapsed/trimmed)
 - **Malformed XML** with `><<` and `>&<` patterns is auto-escaped before parsing
 
+#### `parse<T>(data: Buffer, validationOptions?): T`
+
+Parses an XML buffer and returns the parsed object.
+
+#### `createParseReadStream<T>(stream: Readable, rowTag: string, validationOptions?): ParseReadStream<T>`
+
+Wraps a readable stream into a chunked parser that emits arrays of parsed rows matching `rowTag`. Each `"data"` event receives `T[] | null` (`null` when a chunk has no matching tags).
+
 ```typescript
 import { XmlParser } from "@mkven/xml-parser";
 
@@ -39,7 +49,19 @@ stream.on("data", async (rows: Record<string, string>[] | null) => {
 
 ### `XmlZipParser`
 
-Extends `XmlParser` with ZIP archive support. Extracts `.xml` files from ZIP and parses them.
+Extends `XmlParser` with ZIP archive support. Only `.xml` files inside the archive are processed; other entries are skipped.
+
+#### `parseFromZip(data: Buffer, validationOptions?): Array<{ name, parsedData }>`
+
+Synchronous. Extracts all XML files from a ZIP buffer via `adm-zip` and parses each one.
+
+#### `static createReadStreamsGetterFromZip(data: ReadStream): AsyncGenerator<{ name, stream }>`
+
+Static async generator. Streams ZIP entries via `unzipper`, yielding raw readable streams for each `.xml` entry. Non-XML entries are autodrained. Useful when you need the raw XML stream without parsing.
+
+#### `createParseReadStreamsGetterFromZip<T>(data: ReadStream, rowTag: string, validationOptions?): AsyncGenerator<{ name, stream: ParseReadStream<T> }>`
+
+Instance async generator. Combines the static streaming method above with `createParseReadStream`, yielding a `ParseReadStream<T>` per XML entry.
 
 ```typescript
 import { XmlZipParser } from "@mkven/xml-parser";
@@ -50,7 +72,12 @@ const parser = new XmlZipParser();
 const results = parser.parseFromZip(zipBuffer);
 // [{ name: "data.xml", parsedData: { ROOT: { ROW: [...] } } }]
 
-// Stream XML files from a ZIP ReadStream (async, via unzipper)
+// Stream raw XML entries from a ZIP (static, no parsing)
+for await (const { name, stream } of XmlZipParser.createReadStreamsGetterFromZip(readStream)) {
+  // stream is a raw Readable for each .xml file
+}
+
+// Stream and parse XML entries from a ZIP
 for await (const { name, stream } of parser.createParseReadStreamsGetterFromZip(readStream, "ticket")) {
   stream.on("data", async (rows) => { /* ... */ });
 }
@@ -58,10 +85,15 @@ for await (const { name, stream } of parser.createParseReadStreamsGetterFromZip(
 
 ### `ZipParser`
 
-Low-level static ZIP extraction utilities used internally by `XmlZipParser`.
+Low-level static utilities for ZIP extraction. Used internally by `XmlZipParser`, but exported for direct use.
+
+#### `static getEntries(data: Buffer): Array<{ name: string, data: Buffer }>`
+
+Synchronous extraction via `adm-zip`. Returns all entries with their names and data buffers.
 
-- `ZipParser.getEntries(buffer)` — sync extraction via `adm-zip`
-- `ZipParser.createReadStreamsGetterFromEntries(readStream)` — async streaming via `unzipper`
+#### `static createReadStreamsGetterFromEntries(data: ReadStream): AsyncGenerator<{ name: string, stream: Entry }>`
+
+Async generator via `unzipper`. Streams ZIP entries one by one. Directory prefixes are stripped from entry names via `basename`.
 
 ## Options
 
@@ -83,10 +115,14 @@ parser.parse(xml);
 // Multiple children: { ROOT: { ROW: [{ $id: "1" }, ...] } }   — array
 ```
 
+### `validationOptions`
+
+All parsing methods accept an optional `validationOptions` parameter (`ValidationOptions | boolean` from `fast-xml-parser`). Pass `true` to enable validation, or a `ValidationOptions` object for fine-grained control.
+
 ## Interfaces
 
 - `IXmlParser` — interface for `XmlParser` (generic `parse<T>`, `createParseReadStream<T>`)
-- `IXmlZipParser` — extends `IXmlParser` with `parseFromZip<T>` and `createParseReadStreamsGetterFromZip<T>`
+- `IXmlZipParser` — extends `IXmlParser` with `parseFromZip<T>`, `createParseReadStreamsGetterFromZip<T>`
 - `ParseReadStream<T>` — stream-like object with typed `on("data", listener)` method
 
 ## Dependencies
@@ -111,3 +147,7 @@ Uses [release-it](https://github.com/release-it/release-it) with conventional ch
 pnpm run release:dry  # preview
 pnpm run release      # bump version, update CHANGELOG.md, tag, publish to npm
 ```
+
+## License
+
+MIT

package/dist/XmlParser.d.ts

@@ -0,0 +1,15 @@
+import { type Readable } from "node:stream";
+import { type validationOptions as ValidationOptions, XMLParser } from "fast-xml-parser";
+import type { IXmlParser } from "./types.js";
+declare class XmlParser implements IXmlParser {
+    protected parser: XMLParser;
+    constructor(options?: {
+        alwaysArray?: boolean;
+    });
+    private static prepareFileContent;
+    parse(data: Buffer, validationOptions?: ValidationOptions | boolean): any;
+    createParseReadStream<T = Record<string, string>>(stream: Readable, rowTag: string, validationOptions?: ValidationOptions | boolean): {
+        on: (_event: "data", listener: (parseXmlData: T[] | null) => Promise<void>) => void;
+    };
+}
+export default XmlParser;

package/dist/XmlParser.js

@@ -0,0 +1,68 @@
+import { Transform } from "node:stream";
+import { XMLParser, } from "fast-xml-parser";
+const allVariationsOfSpaces = /(?:\s| )+/;
+const tabulationsCarriageReturnsAndEscapes = /[\t\n\r]/;
+const notUsedUnicodeStringCodes = /[\u0002\u0003\u200B\u202A\u202B]/;
+class XmlParser {
+    parser;
+    constructor(options) {
+        this.parser = new XMLParser({
+            trimValues: true,
+            numberParseOptions: {
+                skipLike: /\d/mu,
+                hex: true,
+                leadingZeros: true,
+            },
+            ignoreAttributes: false,
+            attributeNamePrefix: "$",
+            transformTagName: (tagName) => tagName.toUpperCase(),
+            ...(options?.alwaysArray && {
+                isArray: (_name, jpath, _isLeaf, isAttribute) => isAttribute === undefined && jpath.includes("."),
+            }),
+            attributeValueProcessor(_attrName, attrValue) {
+                if (attrValue === "null") {
+                    return "";
+                }
+                return attrValue
+                    .replaceAll(new RegExp(allVariationsOfSpaces, "gu"), " ")
+                    .replaceAll(new RegExp(tabulationsCarriageReturnsAndEscapes, "gu"), " ")
+                    .replaceAll(new RegExp(notUsedUnicodeStringCodes, "gu"), "")
+                    .trim();
+            },
+        });
+    }
+    static prepareFileContent(content) {
+        return content.replaceAll("><<", ">&lt;<").replaceAll(">&<", ">&#38;<");
+    }
+    parse(data, validationOptions) {
+        const prepared = XmlParser.prepareFileContent(data.toString());
+        return this.parser.parse(prepared, validationOptions);
+    }
+    createParseReadStream(stream, rowTag, validationOptions) {
+        const tagRegex = new RegExp(`<${rowTag} (\n|.)*>`, "gu");
+        return {
+            on: (_event, listener) => {
+                let remainingXmlData = "";
+                const dataTransform = new Transform({
+                    transform: async (chunk, _encoding, next) => {
+                        const chunkString = remainingXmlData + chunk;
+                        const tags = chunkString.match(tagRegex);
+                        if (!tags) {
+                            await listener(null);
+                            return next();
+                        }
+                        const xmlData = XmlParser.prepareFileContent(tags.join("\n"));
+                        const result = this.parser.parse(`<DATA>${xmlData}</DATA>`, validationOptions);
+                        remainingXmlData = chunkString.replaceAll(tagRegex, "");
+                        await listener(Array.isArray(result.DATA[rowTag.toUpperCase()])
+                            ? result.DATA[rowTag.toUpperCase()]
+                            : [result.DATA[rowTag.toUpperCase()]]);
+                        return next();
+                    },
+                });
+                stream.pipe(dataTransform);
+            },
+        };
+    }
+}
+export default XmlParser;

package/dist/XmlZipParser.d.ts

@@ -0,0 +1,21 @@
+import type { ReadStream } from "node:fs";
+import type { validationOptions as ValidationOptions } from "fast-xml-parser";
+import type { IXmlZipParser } from "./types.js";
+import XmlParser from "./XmlParser.js";
+declare class XmlZipParser extends XmlParser implements IXmlZipParser {
+    parseFromZip(data: Buffer, validationOptions?: ValidationOptions | boolean): {
+        name: string;
+        parsedData: any;
+    }[];
+    static createReadStreamsGetterFromZip(data: ReadStream): AsyncGenerator<{
+        name: string;
+        stream: import("unzipper").Entry;
+    }, void, unknown>;
+    createParseReadStreamsGetterFromZip<T = Record<string, string>>(data: ReadStream, rowTag: string, validationOptions?: ValidationOptions | boolean): AsyncGenerator<{
+        name: string;
+        stream: {
+            on: (_event: "data", listener: (parseXmlData: T[] | null) => Promise<void>) => void;
+        };
+    }, void, unknown>;
+}
+export default XmlZipParser;

package/dist/XmlZipParser.js

@@ -0,0 +1,35 @@
+import { extname } from "node:path";
+import XmlParser from "./XmlParser.js";
+import ZipParser from "./ZipParser.js";
+const XML_EXTENSION = ".xml";
+class XmlZipParser extends XmlParser {
+    parseFromZip(data, validationOptions) {
+        const entries = ZipParser.getEntries(data);
+        const xmlEntries = entries.filter((entry) => extname(entry.name) === XML_EXTENSION);
+        return xmlEntries.map((xmlEntry) => ({
+            name: xmlEntry.name,
+            parsedData: this.parse(xmlEntry.data, validationOptions),
+        }));
+    }
+    static async *createReadStreamsGetterFromZip(data) {
+        const entries = ZipParser.createReadStreamsGetterFromEntries(data);
+        for await (const entry of entries) {
+            if (extname(entry.name) === XML_EXTENSION) {
+                yield entry;
+            }
+            else {
+                entry.stream.autodrain();
+            }
+        }
+    }
+    async *createParseReadStreamsGetterFromZip(data, rowTag, validationOptions) {
+        const xmlEntries = XmlZipParser.createReadStreamsGetterFromZip(data);
+        for await (const entry of xmlEntries) {
+            yield {
+                name: entry.name,
+                stream: this.createParseReadStream(entry.stream, rowTag, validationOptions),
+            };
+        }
+    }
+}
+export default XmlZipParser;

package/dist/ZipParser.d.ts

@@ -0,0 +1,13 @@
+import type { ReadStream } from "node:fs";
+import unzipper from "unzipper";
+declare class ZipParser {
+    static createReadStreamsGetterFromEntries(data: ReadStream): AsyncGenerator<{
+        name: string;
+        stream: unzipper.Entry;
+    }, void, unknown>;
+    static getEntries(data: Buffer): {
+        name: string;
+        data: Buffer<ArrayBufferLike>;
+    }[];
+}
+export default ZipParser;

package/dist/ZipParser.js

@@ -0,0 +1,29 @@
+import { basename } from "node:path";
+import AdmZip from "adm-zip";
+import unzipper from "unzipper";
+class ZipParser {
+    static async *createReadStreamsGetterFromEntries(data) {
+        const zip = data.pipe(unzipper.Parse({ forceStream: true }));
+        data.on("close", () => zip.end());
+        for await (const entry of zip) {
+            const typedEntry = entry;
+            const fileName = entry.path;
+            yield {
+                name: basename(fileName),
+                stream: typedEntry,
+            };
+        }
+    }
+    static getEntries(data) {
+        const zip = new AdmZip(data);
+        const zipEntries = zip.getEntries();
+        return zipEntries.map((entry) => {
+            const entryData = entry.getData();
+            return {
+                name: entry.name,
+                data: entryData,
+            };
+        });
+    }
+}
+export default ZipParser;

package/dist/cjs/XmlParser.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_stream_1 = require("node:stream");
+const fast_xml_parser_1 = require("fast-xml-parser");
+const allVariationsOfSpaces = /(?:\s| )+/;
+const tabulationsCarriageReturnsAndEscapes = /[\t\n\r]/;
+const notUsedUnicodeStringCodes = /[\u0002\u0003\u200B\u202A\u202B]/;
+class XmlParser {
+    parser;
+    constructor(options) {
+        this.parser = new fast_xml_parser_1.XMLParser({
+            trimValues: true,
+            numberParseOptions: {
+                skipLike: /\d/mu,
+                hex: true,
+                leadingZeros: true,
+            },
+            ignoreAttributes: false,
+            attributeNamePrefix: "$",
+            transformTagName: (tagName) => tagName.toUpperCase(),
+            ...(options?.alwaysArray && {
+                isArray: (_name, jpath, _isLeaf, isAttribute) => isAttribute === undefined && jpath.includes("."),
+            }),
+            attributeValueProcessor(_attrName, attrValue) {
+                if (attrValue === "null") {
+                    return "";
+                }
+                return attrValue
+                    .replaceAll(new RegExp(allVariationsOfSpaces, "gu"), " ")
+                    .replaceAll(new RegExp(tabulationsCarriageReturnsAndEscapes, "gu"), " ")
+                    .replaceAll(new RegExp(notUsedUnicodeStringCodes, "gu"), "")
+                    .trim();
+            },
+        });
+    }
+    static prepareFileContent(content) {
+        return content.replaceAll("><<", ">&lt;<").replaceAll(">&<", ">&#38;<");
+    }
+    parse(data, validationOptions) {
+        const prepared = XmlParser.prepareFileContent(data.toString());
+        return this.parser.parse(prepared, validationOptions);
+    }
+    createParseReadStream(stream, rowTag, validationOptions) {
+        const tagRegex = new RegExp(`<${rowTag} (\n|.)*>`, "gu");
+        return {
+            on: (_event, listener) => {
+                let remainingXmlData = "";
+                const dataTransform = new node_stream_1.Transform({
+                    transform: async (chunk, _encoding, next) => {
+                        const chunkString = remainingXmlData + chunk;
+                        const tags = chunkString.match(tagRegex);
+                        if (!tags) {
+                            await listener(null);
+                            return next();
+                        }
+                        const xmlData = XmlParser.prepareFileContent(tags.join("\n"));
+                        const result = this.parser.parse(`<DATA>${xmlData}</DATA>`, validationOptions);
+                        remainingXmlData = chunkString.replaceAll(tagRegex, "");
+                        await listener(Array.isArray(result.DATA[rowTag.toUpperCase()])
+                            ? result.DATA[rowTag.toUpperCase()]
+                            : [result.DATA[rowTag.toUpperCase()]]);
+                        return next();
+                    },
+                });
+                stream.pipe(dataTransform);
+            },
+        };
+    }
+}
+exports.default = XmlParser;

package/dist/cjs/XmlZipParser.js

@@ -0,0 +1,40 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = require("node:path");
+const XmlParser_js_1 = __importDefault(require("./XmlParser.js"));
+const ZipParser_js_1 = __importDefault(require("./ZipParser.js"));
+const XML_EXTENSION = ".xml";
+class XmlZipParser extends XmlParser_js_1.default {
+    parseFromZip(data, validationOptions) {
+        const entries = ZipParser_js_1.default.getEntries(data);
+        const xmlEntries = entries.filter((entry) => (0, node_path_1.extname)(entry.name) === XML_EXTENSION);
+        return xmlEntries.map((xmlEntry) => ({
+            name: xmlEntry.name,
+            parsedData: this.parse(xmlEntry.data, validationOptions),
+        }));
+    }
+    static async *createReadStreamsGetterFromZip(data) {
+        const entries = ZipParser_js_1.default.createReadStreamsGetterFromEntries(data);
+        for await (const entry of entries) {
+            if ((0, node_path_1.extname)(entry.name) === XML_EXTENSION) {
+                yield entry;
+            }
+            else {
+                entry.stream.autodrain();
+            }
+        }
+    }
+    async *createParseReadStreamsGetterFromZip(data, rowTag, validationOptions) {
+        const xmlEntries = XmlZipParser.createReadStreamsGetterFromZip(data);
+        for await (const entry of xmlEntries) {
+            yield {
+                name: entry.name,
+                stream: this.createParseReadStream(entry.stream, rowTag, validationOptions),
+            };
+        }
+    }
+}
+exports.default = XmlZipParser;

package/dist/cjs/ZipParser.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = require("node:path");
+const adm_zip_1 = __importDefault(require("adm-zip"));
+const unzipper_1 = __importDefault(require("unzipper"));
+class ZipParser {
+    static async *createReadStreamsGetterFromEntries(data) {
+        const zip = data.pipe(unzipper_1.default.Parse({ forceStream: true }));
+        data.on("close", () => zip.end());
+        for await (const entry of zip) {
+            const typedEntry = entry;
+            const fileName = entry.path;
+            yield {
+                name: (0, node_path_1.basename)(fileName),
+                stream: typedEntry,
+            };
+        }
+    }
+    static getEntries(data) {
+        const zip = new adm_zip_1.default(data);
+        const zipEntries = zip.getEntries();
+        return zipEntries.map((entry) => {
+            const entryData = entry.getData();
+            return {
+                name: entry.name,
+                data: entryData,
+            };
+        });
+    }
+}
+exports.default = ZipParser;

package/dist/cjs/index.js

@@ -0,0 +1,12 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZipParser = exports.XmlZipParser = exports.XmlParser = void 0;
+var XmlParser_js_1 = require("./XmlParser.js");
+Object.defineProperty(exports, "XmlParser", { enumerable: true, get: function () { return __importDefault(XmlParser_js_1).default; } });
+var XmlZipParser_js_1 = require("./XmlZipParser.js");
+Object.defineProperty(exports, "XmlZipParser", { enumerable: true, get: function () { return __importDefault(XmlZipParser_js_1).default; } });
+var ZipParser_js_1 = require("./ZipParser.js");
+Object.defineProperty(exports, "ZipParser", { enumerable: true, get: function () { return __importDefault(ZipParser_js_1).default; } });

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { IXmlParser, IXmlZipParser, ParseReadStream, } from "./types.js";
+export { default as XmlParser } from "./XmlParser.js";
+export { default as XmlZipParser } from "./XmlZipParser.js";
+export { default as ZipParser } from "./ZipParser.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { default as XmlParser } from "./XmlParser.js";
+export { default as XmlZipParser } from "./XmlZipParser.js";
+export { default as ZipParser } from "./ZipParser.js";

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+import type { ReadStream } from "node:fs";
+import type { Readable } from "node:stream";
+import type { validationOptions as ValidationOptions } from "fast-xml-parser";
+export interface ParseReadStream<T = Record<string, string>> {
+    on: (event: "data", listener: (parseXmlData: T[] | null) => Promise<void>) => void;
+}
+export interface IXmlParser {
+    parse<T = Record<string, unknown>>(data: Buffer, validationOptions?: ValidationOptions | boolean): T;
+    createParseReadStream<T = Record<string, string>>(stream: Readable, rowTag: string, validationOptions?: ValidationOptions | boolean): ParseReadStream<T>;
+}
+export interface IXmlZipParser extends IXmlParser {
+    parseFromZip<T = Record<string, unknown>>(data: Buffer, validationOptions?: ValidationOptions | boolean): Array<{
+        name: string;
+        parsedData: T;
+    }>;
+    createParseReadStreamsGetterFromZip<T = Record<string, string>>(data: ReadStream, rowTag: string, validationOptions?: ValidationOptions | boolean): AsyncGenerator<{
+        name: string;
+        stream: ParseReadStream<T>;
+    }>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mkven/xml-parser",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Opinionated XML parsing utilities with ZIP archive support",
   "author": "Damir Manapov",
   "license": "MIT",
@@ -10,7 +10,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.js"
     }
   },
   "files": [
@@ -35,7 +36,7 @@
     "vitest": "^4.0.18"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc -p tsconfig.cjs.json",
     "lint": "biome check --write .",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",