@polyxml/node 0.23.0

package/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "polyxml-js"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+readme = "README.md"
+description = "Node.js and TypeScript native addon bindings for PolyXML"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+polyxml = { path = "../polyxml-core" }
+napi = { version = "2.16", default-features = false, features = ["napi4"] }
+napi-derive = "2.16"
+
+[build-dependencies]
+napi-build = "2.1"

package/README.md

@@ -0,0 +1,38 @@
+# PolyXML Node.js & TypeScript Bindings
+
+High-performance, polyglot streaming XML data-binding engine for Node.js and TypeScript.
+
+- Precompiled native binaries for Linux (x86_64), macOS (Apple Silicon & Intel), and Windows (x64).
+- Zero external native toolchain dependencies needed at runtime.
+- Powered by the ultra-fast Rust `polyxml-core` engine and NAPI-RS.
+
+## Installation
+
+```bash
+npm install @polyxml/node
+```
+
+## Usage
+
+```javascript
+const polyxml = require('@polyxml/node');
+
+const schema = {
+  name: 'Book',
+  fields: [
+    { name: 'id', xmlName: 'id', kind: 'attribute', scalarType: 'int' },
+    { name: 'title', xmlName: 'title', kind: 'element', scalarType: 'string' },
+    { name: 'price', xmlName: 'price', kind: 'element', scalarType: 'float' }
+  ]
+};
+
+const xml = '<Book id="42"><title>Rust in Action</title><price>39.99</price></Book>';
+const book = polyxml.deserialize(xml, schema);
+
+console.log(book);
+// { id: 42, title: 'Rust in Action', price: 39.99 }
+```
+
+## License
+
+MIT

package/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    let _ = std::panic::catch_unwind(napi_build::setup);
+}

package/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * PolyXML TypeScript Type Definitions
+ */
+
+export type FieldKind = 'attribute' | 'element' | 'text';
+
+export type ScalarType =
+  | 'string'
+  | 'int'
+  | 'float'
+  | 'bool'
+  | 'decimal'
+  | 'xml_date'
+  | 'xml_datetime'
+  | 'any';
+
+export interface FieldDefinition {
+  name: string;
+  xmlName: string;
+  kind: FieldKind;
+  scalarType: ScalarType;
+  namespace?: string | null;
+}
+
+export interface ModelSchema {
+  name: string;
+  namespace?: string | null;
+  fields: FieldDefinition[];
+}
+
+export type PolyValue =
+  | null
+  | boolean
+  | number
+  | string
+  | PolyValue[]
+  | { [key: string]: PolyValue };
+
+/**
+ * Deserialize an XML string or Uint8Array into a JavaScript object based on schema.
+ */
+export function deserialize(
+  xml: string | Uint8Array,
+  schema: ModelSchema
+): PolyValue;
+
+/**
+ * Serialize a JavaScript object into XML bytes based on schema.
+ */
+export function serialize(
+  rootName: string,
+  value: Record<string, any>,
+  schema: ModelSchema,
+  indent?: number | null,
+  namespaces?: boolean | null,
+  nsMap?: Record<string, string> | null
+): Uint8Array;
+
+/**
+ * Return the PolyXML engine version.
+ */
+export function version(): string;

package/index.js

@@ -0,0 +1,92 @@
+const { existsSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+switch (platform) {
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'polyxml.win32-x64-msvc.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./polyxml.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('polyxml-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'polyxml.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./polyxml.darwin-x64.node')
+          } else {
+            nativeBinding = require('polyxml-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'polyxml.darwin-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./polyxml.darwin-arm64.node')
+          } else {
+            nativeBinding = require('polyxml-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'polyxml.linux-x64-gnu.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./polyxml.linux-x64-gnu.node')
+          } else {
+            nativeBinding = require('polyxml-linux-x64-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  try {
+    nativeBinding = require('./polyxml.node')
+  } catch (e) {
+    if (loadError) {
+      throw loadError
+    }
+    throw new Error(`Failed to load native PolyXML addon for ${platform}-${arch}`)
+  }
+}
+
+module.exports = nativeBinding

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@polyxml/node",
+  "version": "0.23.0",
+  "description": "High-performance, polyglot XML data-binding engine built in Rust",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "node test/index.test.js"
+  },
+  "napi": {
+    "binaryName": "polyxml"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3.0.0"
+  },
+  "keywords": [
+    "xml",
+    "parser",
+    "serializer",
+    "deserializer",
+    "fast-xml",
+    "polyglot"
+  ],
+  "author": "Bailey Nguyen <bailey.tan.nguyen@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nth-bailey/PolyXML.git"
+  }
+}

package/polyxml.linux-x64-gnu.node

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/polyxml.linux-x64-gnu.node
+size: 41468296 bytes
+sha256: 9487b870e98dc1182f36cd3ec9887a3c8b36d66f0e86f1bbdb841b8c3a8a64ca

package/src/lib.rs

@@ -0,0 +1,173 @@
+use napi::bindgen_prelude::*;
+use napi::JsUnknown;
+use napi_derive::napi;
+use std::sync::Arc;
+
+use polyxml::schema::{FieldKind, FieldSchema, ModelSchema, ScalarType, ValueType};
+use polyxml::value::PolyValue;
+
+#[napi(object)]
+pub struct JsFieldDef {
+    pub name: String,
+    pub xml_name: String,
+    pub kind: String,
+    pub scalar_type: String,
+    pub namespace: Option<String>,
+}
+
+#[napi(object)]
+pub struct JsModelSchema {
+    pub name: String,
+    pub fields: Vec<JsFieldDef>,
+    pub namespace: Option<String>,
+}
+
+fn convert_js_schema(schema: &JsModelSchema) -> Arc<ModelSchema> {
+    let mut builder = ModelSchema::builder(&schema.name);
+    if let Some(ns) = &schema.namespace {
+        builder = builder.namespace(ns);
+    }
+    for f in &schema.fields {
+        let kind = match f.kind.as_str() {
+            "attribute" => FieldKind::Attribute,
+            "text" => FieldKind::Text,
+            _ => FieldKind::Element,
+        };
+        let sc = match f.scalar_type.as_str() {
+            "int" => ScalarType::Int,
+            "float" => ScalarType::Float,
+            "bool" => ScalarType::Bool,
+            "decimal" => ScalarType::Decimal,
+            "xml_date" => ScalarType::XmlDate,
+            "xml_datetime" => ScalarType::XmlDateTime,
+            _ => ScalarType::String,
+        };
+        let mut field =
+            FieldSchema::new(&f.name, f.xml_name.as_bytes(), kind, ValueType::Scalar(sc));
+        if let Some(ns) = &f.namespace {
+            field = field.namespace(ns);
+        }
+        builder = builder.field(field);
+    }
+    builder.build()
+}
+
+fn poly_value_to_js(env: &Env, val: &PolyValue) -> Result<JsUnknown> {
+    match val {
+        PolyValue::Null => Ok(env.get_null()?.into_unknown()),
+        PolyValue::Bool(b) => Ok(env.get_boolean(*b)?.into_unknown()),
+        PolyValue::Int(i) => Ok(env.create_int64(*i)?.into_unknown()),
+        PolyValue::Float(f) => Ok(env.create_double(*f)?.into_unknown()),
+        PolyValue::String(s) => Ok(env.create_string(s)?.into_unknown()),
+        PolyValue::List(list) => {
+            let mut arr = env.create_array(list.len() as u32)?;
+            for (idx, item) in list.iter().enumerate() {
+                let js_item = poly_value_to_js(env, item)?;
+                arr.set(idx as u32, js_item)?;
+            }
+            Ok(arr.coerce_to_object()?.into_unknown())
+        }
+        PolyValue::Object(map) => {
+            let mut obj = env.create_object()?;
+            for (k, v) in map {
+                let js_val = poly_value_to_js(env, v)?;
+                obj.set(k.as_str(), js_val)?;
+            }
+            Ok(obj.into_unknown())
+        }
+        PolyValue::Record { schema, values } => {
+            let mut obj = env.create_object()?;
+            for (idx, field) in schema.fields.iter().enumerate() {
+                if let Some(Some(item)) = values.get(idx) {
+                    let js_val = poly_value_to_js(env, item)?;
+                    obj.set(field.name.as_str(), js_val)?;
+                }
+            }
+            Ok(obj.into_unknown())
+        }
+    }
+}
+
+#[napi]
+pub fn deserialize(
+    env: Env,
+    xml: Either<String, Buffer>,
+    schema: JsModelSchema,
+) -> Result<JsUnknown> {
+    let xml_bytes: &[u8] = match &xml {
+        Either::A(s) => s.as_bytes(),
+        Either::B(b) => b.as_ref(),
+    };
+
+    let model_schema = convert_js_schema(&schema);
+    let val = polyxml::deserialize(xml_bytes, model_schema)
+        .map_err(|e| Error::new(Status::GenericFailure, e.to_string()))?;
+
+    poly_value_to_js(&env, &val)
+}
+
+fn js_to_poly_value(_env: &Env, val: JsUnknown, scalar_type: &str) -> Result<PolyValue> {
+    let val_type = val.get_type()?;
+    if val_type == napi::ValueType::Null || val_type == napi::ValueType::Undefined {
+        return Ok(PolyValue::Null);
+    }
+    match scalar_type {
+        "int" => {
+            let num = val.coerce_to_number()?;
+            Ok(PolyValue::Int(num.get_int64()?))
+        }
+        "float" => {
+            let num = val.coerce_to_number()?;
+            Ok(PolyValue::Float(num.get_double()?))
+        }
+        "bool" => {
+            let b = val.coerce_to_bool()?;
+            Ok(PolyValue::Bool(b.get_value()?))
+        }
+        _ => {
+            let s = val.coerce_to_string()?;
+            let utf8 = s.into_utf8()?;
+            Ok(PolyValue::String(utf8.as_str()?.to_string()))
+        }
+    }
+}
+
+#[napi]
+pub fn serialize(
+    env: Env,
+    root_name: String,
+    value: napi::JsObject,
+    schema: JsModelSchema,
+    indent: Option<u32>,
+    namespaces: Option<bool>,
+    ns_map: Option<std::collections::HashMap<String, String>>,
+) -> Result<Buffer> {
+    use std::collections::HashMap;
+
+    let mut map = HashMap::new();
+    for f in &schema.fields {
+        if value.has_named_property(&f.name)? {
+            let prop: JsUnknown = value.get_named_property(&f.name)?;
+            let pv = js_to_poly_value(&env, prop, &f.scalar_type)?;
+            map.insert(f.name.clone(), pv);
+        }
+    }
+    let poly_val = PolyValue::Object(map);
+    let model_schema = convert_js_schema(&schema);
+    let indent_opt = indent.map(|i| i as usize);
+    let bytes = polyxml::serialize_with_options(
+        &root_name,
+        &poly_val,
+        &model_schema,
+        indent_opt,
+        namespaces,
+        ns_map.as_ref(),
+    )
+    .map_err(|e| Error::new(Status::GenericFailure, e.to_string()))?;
+    Ok(bytes.into())
+}
+
+#[napi]
+pub fn version() -> &'static str {
+    env!("CARGO_PKG_VERSION")
+}

package/test/index.test.js

@@ -0,0 +1,92 @@
+const test = require('node:test');
+const assert = require('node:assert');
+
+test('PolyXML JavaScript bindings', (t) => {
+  let polyxml;
+  try {
+    polyxml = require('../index.js');
+  } catch (err) {
+    // If native addon not yet compiled locally, skip with notice
+    t.diagnostic('Native addon not compiled in current environment; skipping live execution test.');
+    return;
+  }
+
+  assert.strictEqual(typeof polyxml.version(), 'string');
+
+  const schema = {
+    name: 'Sensor',
+    fields: [
+      { name: 'id', xmlName: 'id', kind: 'attribute', scalarType: 'int' },
+      { name: 'name', xmlName: 'name', kind: 'element', scalarType: 'string' },
+      { name: 'reading', xmlName: 'reading', kind: 'element', scalarType: 'float' },
+      { name: 'calibrated', xmlName: 'calibrated', kind: 'element', scalarType: 'bool' },
+    ],
+  };
+
+  const xml = '<Sensor id="101"><name>Barometric Altimeter</name><reading>1013.25</reading><calibrated>true</calibrated></Sensor>';
+  const val = polyxml.deserialize(xml, schema);
+
+  assert.strictEqual(val.id, 101);
+  assert.strictEqual(val.name, 'Barometric Altimeter');
+  assert.strictEqual(val.reading, 1013.25);
+  assert.strictEqual(val.calibrated, true);
+
+  // Test serialization
+  const outBytes = polyxml.serialize('Sensor', val, schema, 2);
+  assert.ok(outBytes instanceof Uint8Array || Buffer.isBuffer(outBytes));
+  const outXml = Buffer.from(outBytes).toString('utf-8');
+  assert.ok(outXml.includes('id="101"'));
+  assert.ok(outXml.includes('<name>Barometric Altimeter</name>'));
+  assert.ok(outXml.includes('<reading>1013.25</reading>'));
+  assert.ok(outXml.includes('<calibrated>true</calibrated>'));
+
+  // Test namespaced schema & serialization
+  const orderSchema = {
+    name: 'Order',
+    namespace: 'https://example.com/orders',
+    fields: [
+      { name: 'id', xmlName: 'id', kind: 'attribute', scalarType: 'int' },
+      { name: 'item', xmlName: 'item', kind: 'element', scalarType: 'string', namespace: 'https://example.com/items' },
+    ],
+  };
+
+  const orderXml = '<ns0:Order xmlns:ns0="https://example.com/orders" xmlns:ns1="https://example.com/items" id="777"><ns1:item>NodeGadget</ns1:item></ns0:Order>';
+  const orderVal = polyxml.deserialize(orderXml, orderSchema);
+  assert.strictEqual(orderVal.id, 777);
+  assert.strictEqual(orderVal.item, 'NodeGadget');
+
+  const orderOut = polyxml.serialize('Order', orderVal, orderSchema, 0, true, {
+    ord: 'https://example.com/orders',
+    itm: 'https://example.com/items',
+  });
+  const orderOutStr = Buffer.from(orderOut).toString('utf-8');
+  assert.ok(orderOutStr.includes('xmlns:ord="https://example.com/orders"'));
+  assert.ok(orderOutStr.includes('xmlns:itm="https://example.com/items"'));
+  assert.ok(orderOutStr.includes('<ord:Order'));
+  assert.ok(orderOutStr.includes('<itm:item>NodeGadget</itm:item>'));
+
+  // Test real-world fixture conformance: atom_feed.xml
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const atomPath = path.resolve(__dirname, '../../../tests/fixtures/atom_feed.xml');
+  if (fs.existsSync(atomPath)) {
+    const atomXml = fs.readFileSync(atomPath, 'utf-8');
+    const atomSchema = {
+      name: 'feed',
+      namespace: 'http://www.w3.org/2005/Atom',
+      fields: [
+        { name: 'title', xmlName: 'title', kind: 'element', scalarType: 'string' },
+        { name: 'id', xmlName: 'id', kind: 'element', scalarType: 'string' },
+      ],
+    };
+    const atomVal = polyxml.deserialize(atomXml, atomSchema);
+    assert.strictEqual(atomVal.title, 'PolyXML Engineering Updates');
+
+    const atomOut = polyxml.serialize('feed', atomVal, atomSchema, 2, true, {
+      '': 'http://www.w3.org/2005/Atom',
+    });
+    const atomOutStr = Buffer.from(atomOut).toString('utf-8');
+    assert.ok(atomOutStr.includes('xmlns="http://www.w3.org/2005/Atom"'));
+    assert.ok(atomOutStr.includes('<title>PolyXML Engineering Updates</title>'));
+  }
+});