From b1b7d2fa705bc59f91f3c6a55693d4125d1b9995 Mon Sep 17 00:00:00 2001
From: Aiden McClelland <me@drbonez.dev>
Date: Wed, 18 Mar 2026 23:47:17 -0600
Subject: [PATCH] feat: add xml file helper to SDK

---
 sdk/package/lib/util/fileHelper.ts | 39 ++++++++++++++++++
 sdk/package/package-lock.json      | 63 ++++++++++++++++++++++++++++++
 sdk/package/package.json           |  1 +
 3 files changed, 103 insertions(+)

diff --git a/sdk/package/lib/util/fileHelper.ts b/sdk/package/lib/util/fileHelper.ts
index 1bcde0c90..44012b9ba 100644
--- a/sdk/package/lib/util/fileHelper.ts
+++ b/sdk/package/lib/util/fileHelper.ts
@@ -2,6 +2,12 @@ import { z } from 'zod'
 import * as YAML from 'yaml'
 import * as TOML from '@iarna/toml'
 import * as INI from 'ini'
+import {
+  XMLParser,
+  XMLBuilder,
+  type X2jOptions,
+  type XmlBuilderOptions,
+} from 'fast-xml-parser'
 import * as T from '../../../base/lib/types'
 import * as fs from 'node:fs/promises'
 import { asError, deepEqual } from '../../../base/lib/util'
@@ -618,6 +624,39 @@ export class FileHelper<A> {
       transformers,
     )
   }
+
+  /**
+   * Create a File Helper for an .xml file.
+   *
+   * Supports optional parser/builder options from `fast-xml-parser`.
+   */
+  static xml<A extends Record<string, unknown>>(
+    path: ToPath,
+    shape: Validator<Record<string, unknown>, A>,
+    options?: { parser?: X2jOptions; builder?: XmlBuilderOptions },
+  ): FileHelper<A>
+  static xml<A extends Transformed, Transformed = Record<string, unknown>>(
+    path: ToPath,
+    shape: Validator<Transformed, A>,
+    options: { parser?: X2jOptions; builder?: XmlBuilderOptions },
+    transformers: Transformers<Record<string, unknown>, Transformed, A>,
+  ): FileHelper<A>
+  static xml<A extends Transformed, Transformed = Record<string, unknown>>(
+    path: ToPath,
+    shape: Validator<Transformed, A>,
+    options?: { parser?: X2jOptions; builder?: XmlBuilderOptions },
+    transformers?: Transformers<Record<string, unknown>, Transformed, A>,
+  ): FileHelper<A> {
+    const parser = new XMLParser(options?.parser)
+    const builder = new XMLBuilder(options?.builder)
+    return FileHelper.rawTransformed<A, Record<string, unknown>, Transformed>(
+      path,
+      (inData) => builder.build(inData),
+      (inString) => parser.parse(inString),
+      (data) => shape.parse(data),
+      transformers,
+    )
+  }
 }
 
 export default FileHelper
diff --git a/sdk/package/package-lock.json b/sdk/package/package-lock.json
index 2e49b06f3..6582cae3e 100644
--- a/sdk/package/package-lock.json
+++ b/sdk/package/package-lock.json
@@ -14,6 +14,7 @@
         "@noble/hashes": "^1.7.2",
         "@types/ini": "^4.1.1",
         "deep-equality-data-structures": "^2.0.0",
+        "fast-xml-parser": "^5.5.6",
         "ini": "^5.0.0",
         "isomorphic-fetch": "^3.0.0",
         "mime": "^4.0.7",
@@ -2517,6 +2518,41 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/fast-xml-builder": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/fast-xml-builder/-/fast-xml-builder-1.1.4.tgz",
+      "integrity": "sha512-f2jhpN4Eccy0/Uz9csxh3Nu6q4ErKxf0XIsasomfOihuSUa3/xw6w8dnOtCDgEItQFJG8KyXPzQXzcODDrrbOg==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/NaturalIntelligence"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "path-expression-matcher": "^1.1.3"
+      }
+    },
+    "node_modules/fast-xml-parser": {
+      "version": "5.5.6",
+      "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.5.6.tgz",
+      "integrity": "sha512-3+fdZyBRVg29n4rXP0joHthhcHdPUHaIC16cuyyd1iLsuaO6Vea36MPrxgAzbZna8lhvZeRL8Bc9GP56/J9xEw==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/NaturalIntelligence"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "fast-xml-builder": "^1.1.4",
+        "path-expression-matcher": "^1.1.3",
+        "strnum": "^2.1.2"
+      },
+      "bin": {
+        "fxparser": "src/cli/cli.js"
+      }
+    },
     "node_modules/fastq": {
       "version": "1.17.1",
       "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.17.1.tgz",
@@ -4129,6 +4165,21 @@
         "node": ">=8"
       }
     },
+    "node_modules/path-expression-matcher": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/path-expression-matcher/-/path-expression-matcher-1.1.3.tgz",
+      "integrity": "sha512-qdVgY8KXmVdJZRSS1JdEPOKPdTiEK/pi0RkcT2sw1RhXxohdujUlJFPuS1TSkevZ9vzd3ZlL7ULl1MHGTApKzQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/NaturalIntelligence"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
     "node_modules/path-is-absolute": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
@@ -4643,6 +4694,18 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/strnum": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/strnum/-/strnum-2.2.0.tgz",
+      "integrity": "sha512-Y7Bj8XyJxnPAORMZj/xltsfo55uOiyHcU2tnAVzHUnSJR/KsEX+9RoDeXEnsXtl/CX4fAcrt64gZ13aGaWPeBg==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/NaturalIntelligence"
+        }
+      ],
+      "license": "MIT"
+    },
     "node_modules/supports-color": {
       "version": "7.2.0",
       "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
diff --git a/sdk/package/package.json b/sdk/package/package.json
index 64dbf2d21..855389278 100644
--- a/sdk/package/package.json
+++ b/sdk/package/package.json
@@ -36,6 +36,7 @@
     "@noble/hashes": "^1.7.2",
     "@types/ini": "^4.1.1",
     "deep-equality-data-structures": "^2.0.0",
+    "fast-xml-parser": "^5.5.6",
     "ini": "^5.0.0",
     "isomorphic-fetch": "^3.0.0",
     "mime": "^4.0.7",