V6 ESM, Types, Skip tags

docs/v6/1.GettingStarted.md

@@ -1,18 +1,30 @@
 
 
-Example with no configuration
+Example with no configuration (ESM)
 
 ```js
-const XMLParser = require("fast-xml-parser/src/v6/XMLParser")
+import { XMLParser } from "fast-xml-parser/v6";
+
 const parser = new XMLParser();
-//read xmlData your own 
-let result = parser.parse(xmlData, true);
+// read xmlData your own
+const result = parser.parse("<root>ok</root>");
+```
+
+CommonJS (via dynamic import)
+
+```js
+(async () => {
+    const { XMLParser } = await import("fast-xml-parser/v6");
+    const parser = new XMLParser();
+    const result = parser.parse("<root>ok</root>");
+    console.log(result);
+})();
 ```
 
 The default response of parse is built by `JsObjOutputBuilder`. FXP v6 comes with 2 more output builders. And you can set your custom output builder too to customize the output.
 
 ```js
-const JsObjOutputBuilder = require("fast-xml-parser/src/v6/OutputBuilders/JsObjBuilder");
+import { XMLParser, JsObjOutputBuilder } from "fast-xml-parser/v6";
 
 const parser = new XMLParser({
     OutputBuilder: new JsObjOutputBuilder()
@@ -21,4 +33,25 @@ const parser = new XMLParser({
 let result = parser.parse(xmlData, true);
 ```
 
+## Types (TypeScript)
+
+You can import types for v6 directly from the package subpath:
+
+```ts
+import type { V6ParserOptions, V6BuilderOptions } from 'fast-xml-parser/v6';
+import { XMLParser, JsObjOutputBuilder } from 'fast-xml-parser/v6';
+
+const builderOpts: V6BuilderOptions = {
+    nameFor: { text: '#text' }
+};
+
+const parserOpts: V6ParserOptions = {
+    attributes: { ignore: false, booleanType: true },
+    OutputBuilder: new JsObjOutputBuilder(builderOpts)
+};
+
+const parser = new XMLParser(parserOpts);
+const result = parser.parse('<root>1</root>');
+```
+
 

docs/v6/3.Options.md

@@ -86,34 +86,68 @@ Eg.
 
 By default `JsObjOutputBuilder` output builder is used with default options.  
 
+### TypeScript usage (recommended)
 
-Example
+Import types and classes from the v6 subpath for best DX:
+
+```ts
+import type { V6ParserOptions, V6BuilderOptions } from 'fast-xml-parser/v6';
+import { XMLParser, JsObjOutputBuilder } from 'fast-xml-parser/v6';
+
+const builderOpts: V6BuilderOptions = {
+  // onAttribute: (name, value, tagName) => ({ name, value })
+};
+
+const parserOpts: V6ParserOptions = {
+  attributes: { ignore: false, booleanType: true },
+  OutputBuilder: new JsObjOutputBuilder(builderOpts),
+};
+
+const parser = new XMLParser(parserOpts);
+const result = parser.parse('<root>1</root>');
+```
+
+If you only need types, prefer `import type` so they’re erased at compile time.
+
+### JavaScript (ESM)
 
 ```js
-const XMLParser = require("fast-xml-parse/src/v6/XMLParser");
-const JsObjOutputBuilder = require("fast-xml-parse/src/v6/OutputBuilders/JsObjBuilder");
-const JsArrBuilder = require("fast-xml-parse/src/v6/OutputBuilders/JsArrBuilder");
-const JsMinArrBuilder = require("fast-xml-parse/src/v6/OutputBuilders/JsMinArrBuilder");
+import { XMLParser, JsObjOutputBuilder, JsArrOutputBuilder, JsMinArrOutputBuilder } from 'fast-xml-parser/v6';
+import fs from 'node:fs';
 
-const xmlData = fs.readFileSync("sample.xml").toString();
+const xmlData = fs.readFileSync('sample.xml', 'utf8');
 
 const outputBuilderOptions = {
   onAttribute: (name, value, tagName) => {
-    console.log(name, value, tagName)
+    console.log(name, value, tagName);
   }
 };
 
 const parserOptions = {
   attributes: {
-      ignore: false,
-      booleanType:true
+    ignore: false,
+    booleanType: true
   },
-
   OutputBuilder: new JsObjOutputBuilder(outputBuilderOptions)
 };
 
 const parser = new XMLParser(parserOptions);
-let result = parser.parse(xmlData);
+const result = parser.parse(xmlData);
 
-console.log(JSON.stringify(result,null,4));
+console.log(JSON.stringify(result, null, 4));
+```
+
+### CommonJS (via dynamic import)
+
+```js
+(async () => {
+  const { XMLParser, JsObjOutputBuilder } = await import('fast-xml-parser/v6');
+  const xmlData = require('node:fs').readFileSync('sample.xml', 'utf8');
+  const parser = new XMLParser({
+    attributes: { ignore: false, booleanType: true },
+    OutputBuilder: new JsObjOutputBuilder()
+  });
+  const result = parser.parse(xmlData);
+  console.log(JSON.stringify(result, null, 4));
+})();
 ```

docs/v6/4.OutputBuilders.md

@@ -6,6 +6,22 @@ All 3 available output builders are
 ### Output builders
 You can use provided output builds or your own output builder.
 
+TypeScript usage
+
+```ts
+import type { V6BuilderOptions } from 'fast-xml-parser/v6';
+import { JsObjOutputBuilder, JsArrOutputBuilder, JsMinArrOutputBuilder } from 'fast-xml-parser/v6';
+
+const opts: V6BuilderOptions = {
+    nameFor: { text: '#text' },
+    attributes: { prefix: '@_', suffix: '' }
+};
+
+const objBuilder = new JsObjOutputBuilder(opts);
+const arrBuilder = new JsArrOutputBuilder(opts);
+const minArrBuilder = new JsMinArrOutputBuilder(opts);
+```
+
 JsObjOutputBuilder
 ```js
 {

package.json

@@ -17,6 +17,13 @@
         "types": "./lib/fxp.d.cts",
         "default": "./lib/fxp.cjs"
       }
+    },
+    "./v6": {
+      "import": "./src/v6/index.js",
+      "types": "./src/v6/index.d.ts"
+    },
+    "./v6/*": {
+      "import": "./src/v6/*"
     }
   },
   "scripts": {
@@ -28,7 +35,9 @@
     "lint": "eslint src/**/*.js spec/**/*.js benchmark/**/*.js",
     "bundle": "webpack --config webpack.cjs.config.js",
     "prettier": "prettier --write src/**/*.js",
-    "checkReadiness": "publish-please --dry-run"
+    "checkReadiness": "publish-please --dry-run",
+    "publish-please": "publish-please",
+    "prepublishOnly": "publish-please guard"
   },
   "bin": {
     "fxparser": "./src/cli/cli.js"
@@ -85,6 +94,6 @@
     }
   ],
   "dependencies": {
-    "strnum": "^2.1.0"
+    "strnum": "^2.1.1"
   }
 }

spec/typings/typings-test.ts

@@ -1,12 +1,19 @@
 import {
-    XMLParser,
     XMLBuilder,
+    XMLParser,
     XMLValidator,
     type X2jOptions,
     type XmlBuilderOptions,
     type validationOptions,
 } from '../../src/fxp.js';
 
+import {
+    JsObjOutputBuilder,
+    XMLParser as V6XMLParser,
+    type V6BuilderOptions,
+    type V6ParserOptions,
+} from '../../src/v6/index.js';
+
 const parseOpts: X2jOptions = {};
 
 const XML = `
@@ -44,4 +51,21 @@ const isValid = XMLValidator.validate(built, validateOpts);
 
 console.log(!!isValid);
 
+// v6 typings smoke
+const v6Opts: V6ParserOptions = {
+    preserveOrder: false,
+    attributes: { ignore: false, booleanType: true, entities: true },
+};
+const v6Parser = new V6XMLParser(v6Opts);
+const v6Parsed = v6Parser.parse('<r>1</r>');
+console.log(!!v6Parsed);
+
+const v6BuilderOpts: V6BuilderOptions = {
+    nameFor: { text: '#text' },
+};
+const outBuilder = new JsObjOutputBuilder(v6BuilderOpts);
+// ensure builder has getInstance signature
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _builderInstance = outBuilder.getInstance(v6Opts);
+
 

spec/v6/test.js

@@ -1,8 +1,6 @@
-import XMLParser from "../../src/v6/XMLParser";
-import JsObjOutputBuilder from "../../src/v6/OutputBuilders/JsObjBuilder";
-import JsArrBuilder from "../../src/v6/OutputBuilders/JsArrBuilder";
-import JsMinArrBuilder from "../../src/v6/OutputBuilders/JsMinArrBuilder";
-import numberParser from "../../src/v6/valueParsers/number";
+import JsObjOutputBuilder from "../../src/v6/OutputBuilders/JsObjBuilder.js";
+import numberParser from "../../src/v6/valueParsers/number.js";
+import XMLParser from "../../src/v6/XMLParser.js";
 
 import fs from "fs";
 import path from "path";

spec/v6_esm_entry_spec.js

@@ -0,0 +1,9 @@
+import { XMLParser } from "fast-xml-parser/v6";
+
+describe("ESM v6 entry", function() {
+  it("should import and parse", function() {
+    const parser = new XMLParser();
+    const result = parser.parse("<root>1</root>");
+    expect(result).toEqual({ root: 1 });
+  });
+});

src/v6/OptionsBuilder.js

@@ -1,5 +1,5 @@
 
-import {JsObjOutputBuilder} from './OutputBuilders/JsObjBuilder.js';
+import JsObjOutputBuilder from './OutputBuilders/JsObjBuilder.js';
 
 export const defaultOptions = {
   preserveOrder: false,

src/v6/OutputBuilders/JsArrBuilder.js

@@ -1,4 +1,6 @@
-import {buildOptions,registerCommonValueParsers} from './ParserOptionsBuilder.js';
+import TagPathMatcher from '../TagPathMatcher.js';
+import BaseOutputBuilder from './BaseOutputBuilder.js';
+import { buildOptions, registerCommonValueParsers } from './ParserOptionsBuilder.js';
 
 export default class OutputBuilder{
   constructor(options){
@@ -16,7 +18,6 @@ export default class OutputBuilder{
 }
 
 const rootName = '!js_arr';
-import BaseOutputBuilder from './BaseOutputBuilder.js';
 
 class JsArrBuilder extends BaseOutputBuilder{
 
@@ -99,5 +100,3 @@ class Node{
       this[":@"] = attributes;
   }
 }
-
-module.exports = OutputBuilder;

src/v6/OutputBuilders/JsMinArrBuilder.js

@@ -1,4 +1,4 @@
-import {buildOptions,registerCommonValueParsers} from"./ParserOptionsBuilder";
+import { buildOptions, registerCommonValueParsers } from "./ParserOptionsBuilder.js";
 
 export default class OutputBuilder{
   constructor(options){
@@ -15,7 +15,8 @@ export default class OutputBuilder{
   }
 }
 
-import BaseOutputBuilder  from "./BaseOutputBuilder.js";
+import TagPathMatcher from "../TagPathMatcher.js";
+import BaseOutputBuilder from "./BaseOutputBuilder.js";
 const rootName = '^';
 
 class JsMinArrBuilder extends BaseOutputBuilder{

src/v6/OutputBuilders/JsObjBuilder.js

@@ -1,6 +1,6 @@
 
 
-import {buildOptions,registerCommonValueParsers} from './ParserOptionsBuilder.js';
+import { buildOptions, registerCommonValueParsers } from './ParserOptionsBuilder.js';
 
 export default class OutputBuilder{
   constructor(builderOptions){
@@ -17,6 +17,7 @@ export default class OutputBuilder{
   }
 }
 
+import TagPathMatcher from '../TagPathMatcher.js';
 import BaseOutputBuilder from './BaseOutputBuilder.js';
 const rootName = '^';