@zugferd/xsd-validator 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 N-API for Rust
+
+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,198 @@
-# Temporary Holding Version
+# @zugferd/xsd-validator
 
-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.
+[![CI](https://github.com/jslno/xsd-validator/actions/workflows/CI.yml/badge.svg)](https://github.com/jslno/xsd-validator/actions/workflows/CI.yml)
+[![npm version](https://img.shields.io/npm/v/@zugferd/xsd-validator.svg)](https://www.npmjs.com/package/@zugferd/xsd-validator)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node](https://img.shields.io/node/v/@zugferd/xsd-validator.svg)](package.json)
+
+Fast, self-contained **XML Schema (XSD) validation for Node.js**, implemented as a native addon in Rust with a statically vendored [libxml2](https://gitlab.gnome.org/GNOME/libxml2).
+
+It compiles an XSD once — recursively resolving `xs:include`, `xs:import`, `xs:redefine`, and `xs:override` through a loader you provide — then validates XML documents synchronously against the compiled schema. It works with any XSD, and is particularly suited to e-invoicing formats such as ZUGFeRD/Factur-X, XRechnung, and UN/CEFACT Cross Industry Invoice (CII).
+
+## Why use this
+
+- **No system dependencies.** libxml2 is compiled in and statically linked, so validation behaves consistently across platforms without installing libxml2 or a build toolchain at runtime.
+- **Prebuilt native binaries.** macOS (x64/arm64), Linux (x64/arm64 GNU), and Windows (x64/arm64) binaries are published as optional dependencies and selected automatically at install time.
+- **Async, schema-aware loading.** `XsdValidator.create()` accepts a sync or async loader for external schema references. The loader runs on the Node.js side — never from a libxml2 C callback — and is called once per unique dependency during compilation.
+- **Safe concurrency.** Multiple validators can be created concurrently; each schema compile uses its own in-memory virtual filesystem.
+- **Compile once, validate many.** Schema compilation is the expensive step. Reuse the resulting `XsdValidator` for fast, synchronous validation of many documents.
+- **Useful diagnostics.** Failures report libxml2 messages including file, line, and error details.
+- **Network access disabled.** XML and schema parsing use libxml2's `XML_PARSE_NONET`, so validation never fetches remote resources.
+
+## Installation
+
+```bash
+npm install @zugferd/xsd-validator
+# or
+pnpm add @zugferd/xsd-validator
+```
+
+Requires Node.js `>=18.17.0 <19 || >=20.3.0 <21 || >=21.1.0` (Node.js LTS recommended). The matching prebuilt binary for your platform is installed automatically; no Rust, CMake, or C compiler is needed.
+
+## Usage
+
+### Validate an XML document
+
+```ts
+import { XsdValidator } from '@zugferd/xsd-validator'
+
+const ROOT_XSD = `<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+           targetNamespace="urn:example"
+           xmlns="urn:example"
+           elementFormDefault="qualified">
+  <xs:element name="Person">
+    <xs:complexType>
+      <xs:sequence>
+        <xs:element name="name" type="xs:string"/>
+        <xs:element name="age" type="xs:positiveInteger"/>
+      </xs:sequence>
+    </xs:complexType>
+  </xs:element>
+</xs:schema>`
+
+const validator = await XsdValidator.create(ROOT_XSD)
+
+const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<Person xmlns="urn:example">
+  <name>Ada</name>
+  <age>36</age>
+</Person>`
+
+console.log(validator.validate(xml)) // true
+```
+
+### Load multi-file schemas
+
+Provide a loader when the root XSD references other files. Paths are resolved relative to the schema that references them (e.g. an `xs:include` of `common/types.xsd` inside the root yields `common/types.xsd`; nested includes may yield paths such as `common/base.xsd`).
+
+```ts
+import { readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { XsdValidator } from '@zugferd/xsd-validator'
+
+const schemaDir = '/path/to/schemas'
+const rootXsd = await readFile(join(schemaDir, 'CrossIndustryInvoice_100pD22B.xsd'), 'utf8')
+
+const validator = await XsdValidator.create(rootXsd, async (filename) => {
+  return readFile(join(schemaDir, filename), 'utf8')
+})
+
+const invoice = await readFile('/path/to/invoice.xml', 'utf8')
+console.log(validator.validate(invoice))
+```
+
+The loader may also be synchronous, and it is only invoked during `XsdValidator.create()` — never during validation.
+
+### Get detailed validation errors
+
+```ts
+try {
+  validator.validateOrThrow(invoice)
+  console.log('valid')
+} catch (error) {
+  // Multi-line libxml2 diagnostics, e.g. "root.xsd:12: Element 'age': ..."
+  console.error(error.message)
+}
+```
+
+### Batch validation
+
+```ts
+const documents = await Promise.all(files.map(async (file) => ({ file, xml: await readFile(file, 'utf8') })))
+
+const valid = documents.filter(({ xml }) => validator.validate(xml))
+```
+
+## API
+
+Types are bundled in [`index.d.ts`](index.d.ts).
+
+| API                                     | Description                                                                                                                                                                                                                           |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `XsdValidator.create(rootXsd, loader?)` | Compiles a root XSD. `loader(filename)` returns the text of each referenced schema and may be sync or async. Returns `Promise<XsdValidator>`. Rejects if references exist without a loader, a loader fails, or the schema is invalid. |
+| `validator.validate(xml)`               | Returns `true` when the document is well-formed and schema-valid, `false` otherwise. Throws only on internal failures.                                                                                                                |
+| `validator.validateOrThrow(xml)`        | Returns `true` on success; throws an `Error` with libxml2 diagnostics for malformed or invalid XML.                                                                                                                                   |
+| `shutdownLibxml()`                      | Optional process-level libxml2 teardown. Normally unnecessary — let the process exit normally, and do not call while validators are still in use.                                                                                     |
+
+### Behavior notes
+
+- `validate()` returns `false` for both malformed XML and schema violations. Use `validateOrThrow()` when you need to distinguish and report the reason.
+- If the root XSD has no external references, omit the loader. If references exist and no loader is supplied, `create()` rejects.
+- Absolute `schemaLocation` values are passed to your loader as-is; libxml2 will not fetch them over the network.
+- A validator holds its compiled schema and schema sources in memory for its lifetime. Discard it when no longer needed.
+
+## Development
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) 18.17+ and [pnpm](https://pnpm.io/) (`corepack enable`)
+- [Rust](https://www.rust-lang.org/tools/install) stable toolchain
+- [CMake](https://cmake.org/) and a C/C++ toolchain (MSVC Build Tools on Windows)
+- Git submodules initialized (libxml2 is vendored as a submodule)
+
+### Setup
+
+```bash
+git clone --recursive https://github.com/jslno/xsd-validator.git
+cd xsd-validator
+# If you cloned without --recursive:
+git submodule update --init --recursive
+
+corepack enable
+pnpm install
+pnpm build
+pnpm test
+```
+
+### Scripts
+
+| Script             | Description                                                                      |
+| ------------------ | -------------------------------------------------------------------------------- |
+| `pnpm build`       | Build the release native addon with napi-rs                                      |
+| `pnpm build:debug` | Build a debug native addon                                                       |
+| `pnpm test`        | Run the [AVA](https://github.com/avajs/ava) test suite                           |
+| `pnpm bench`       | Run [tinybench](https://github.com/tinylibs/tinybench) benchmarks                |
+| `pnpm lint`        | Lint JavaScript/TypeScript with [oxlint](https://oxc.rs/docs/guide/usage/linter) |
+| `pnpm format`      | Format with Prettier, `cargo fmt`, and Taplo                                     |
+
+### Project layout
+
+| Path                                           | Purpose                                                        |
+| ---------------------------------------------- | -------------------------------------------------------------- |
+| [`src/lib.rs`](src/lib.rs)                     | napi-rs bindings and validator lifecycle                       |
+| [`src/resolver.rs`](src/resolver.rs)           | Recursive schema resolution and in-memory virtual filesystem   |
+| [`src/error.rs`](src/error.rs)                 | libxml2 error collection and JavaScript error conversion       |
+| [`native/schema_refs.c`](native/schema_refs.c) | Helper that walks XSD nodes to collect schema references       |
+| [`build.rs`](build.rs)                         | Builds the vendored libxml2 and links the native helper        |
+| [`vendor/libxml2`](vendor/libxml2)             | libxml2 git submodule                                          |
+| [`__test__`](__test__)                         | AVA tests, XRechnung fixtures, and CII schemas                 |
+| [`benchmark/bench.ts`](benchmark/bench.ts)     | Validation benchmarks                                          |
+| `npm/`                                         | Per-platform npm package manifests generated during publishing |
+
+### Continuous integration
+
+[`.github/workflows/CI.yml`](.github/workflows/CI.yml) runs linting plus a build/test matrix for macOS, Linux, and Windows on x64 and arm64. Releases are published from version tags via [`publish.yml`](.github/workflows/publish.yml).
+
+## Contributing
+
+Contributions are welcome. To propose a change:
+
+1. Open an issue describing the bug or feature if one does not already exist.
+2. Fork the repository and create a topic branch.
+3. Add or update tests under [`__test__`](__test__), and include a fixture for new behavior where practical.
+4. Run `pnpm test`, `pnpm lint`, and `pnpm format` before opening a pull request.
+5. Submit the pull request with a clear description and link the related issue.
+
+Please keep pull requests focused and avoid committing build artifacts.
+
+## Getting help
+
+- **Bugs and feature requests:** [GitHub Issues](https://github.com/jslno/xsd-validator/issues)
+- **Source and releases:** [github.com/jslno/xsd-validator](https://github.com/jslno/xsd-validator)
+- **Native addon tooling:** [napi.rs](https://napi.rs/)
+- **Schema engine:** [libxml2](https://gitlab.gnome.org/GNOME/libxml2)
+
+## License
+
+[MIT](LICENSE)

package/index.d.ts

@@ -0,0 +1,47 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+
+/**
+ * Which binding artifact the generated loader actually loaded: `'native'` for
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
+ * can point the loader at a WASI artifact this package does not build itself.
+ */
+export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
+
+/**
+ * Compiles an XSD (with recursively resolved includes/imports) and validates XML
+ * documents against the resulting schema.
+ */
+export declare class XsdValidator {
+  /**
+   * Create a validator from a root XSD string and an optional schema loader.
+   *
+   * The loader is invoked only during this call, on the Node/Tokio side, to
+   * fetch `xs:include` / `xs:import` targets. It is never invoked from a
+   * libxml2 C callback thread. Omit the loader when the root XSD has no
+   * external references.
+   */
+  static create(rootXsd: string, loader?: (filename: string) => string | Promise<string>): Promise<XsdValidator>
+  /**
+   * Validate an XML document string against the compiled schema.
+   *
+   * Returns `true` when the document is well-formed and schema-valid.
+   * Returns `false` when the document is invalid. Throws only on internal
+   * failures (e.g. unable to allocate a validation context).
+   */
+  validate(xml: string): boolean
+  /**
+   * Validate and, on failure, throw a JavaScript exception containing libxml2
+   * diagnostics. On success returns `true`.
+   */
+  validateOrThrow(xml: string): boolean
+}
+
+/**
+ * Process-level teardown for libxml2 globals.
+ *
+ * Prefer letting the Node process exit normally. Only call this when you are
+ * certain no `XsdValidator` instances remain alive.
+ */
+export declare function shutdownLibxml(): void

package/index.js

@@ -0,0 +1,839 @@
+/* eslint-disable */
+// @ts-nocheck
+/* auto-generated by NAPI-RS */
+
+const { readFileSync } = require('fs')
+let nativeBinding = null
+// Which artifact actually loaded. The WASI fallback chain overwrites it with
+// the flavor it resolved; the late native retry below leaves it alone because
+// it only runs while no WASI candidate has been loaded. The take-over check
+// after the load-failure block can also set it.
+let __napiLoadedBindingTarget = 'native'
+// What this loader's own `requireNative()` calls returned. The check after
+// the load-failure block compares it with `nativeBinding` to tell a binding
+// this loader loaded from one that code outside it put in its place.
+let __napiRequiredNativeBinding = null
+const loadErrors = []
+
+const isMusl = () => {
+  let musl = false
+  if (process.platform === 'linux') {
+    musl = isMuslFromFilesystem()
+    if (musl === null) {
+      musl = isMuslFromReport()
+    }
+    if (musl === null) {
+      musl = isMuslFromChildProcess()
+    }
+  }
+  return musl
+}
+
+const isFileMusl = (f) => f.includes('libc.musl-') || f.includes('ld-musl-')
+
+const isMuslFromFilesystem = () => {
+  try {
+    return readFileSync('/usr/bin/ldd', 'utf-8').includes('musl')
+  } catch {
+    return null
+  }
+}
+
+const isMuslFromReport = () => {
+  let report = null
+  if (process.report && typeof process.report.getReport === 'function') {
+    process.report.excludeNetwork = true
+    report = process.report.getReport()
+  }
+  if (!report) {
+    return null
+  }
+  if (report.header && report.header.glibcVersionRuntime) {
+    return false
+  }
+  if (Array.isArray(report.sharedObjects)) {
+    if (report.sharedObjects.some(isFileMusl)) {
+      return true
+    }
+  }
+  return false
+}
+
+const isMuslFromChildProcess = () => {
+  try {
+    return require('child_process').execSync('ldd --version', { encoding: 'utf8' }).includes('musl')
+  } catch (e) {
+    // If we reach this case, we don't know if the system is musl or not, so is better to just fallback to false
+    return false
+  }
+}
+
+function requireNative() {
+  if (process.env.NAPI_RS_NATIVE_LIBRARY_PATH) {
+    try {
+      const overrideBinding = require(process.env.NAPI_RS_NATIVE_LIBRARY_PATH)
+      // The override may be a generated WASI loader, which already reports its
+      // own flavor. Adopt it: `module.exports` aliases this object, so claiming
+      // 'native' would both misreport the artifact and overwrite the loader's
+      // marker through the alias.
+      __napiLoadedBindingTarget =
+        overrideBinding && typeof overrideBinding.__napiBindingTarget === 'string'
+          ? overrideBinding.__napiBindingTarget
+          : 'native'
+      return overrideBinding
+    } catch (err) {
+      loadErrors.push(err)
+    }
+  } else if (process.platform === 'android') {
+    if (process.arch === 'arm64') {
+      try {
+        return require('./xsd-validator.android-arm64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@zugferd/xsd-validator-android-arm64')
+        const bindingPackageVersion = require('@zugferd/xsd-validator-android-arm64/package.json').version
+        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'arm') {
+      try {
+        return require('./xsd-validator.android-arm-eabi.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@zugferd/xsd-validator-android-arm-eabi')
+        const bindingPackageVersion = require('@zugferd/xsd-validator-android-arm-eabi/package.json').version
+        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on Android ${process.arch}`))
+    }
+  } else if (process.platform === 'win32') {
+    if (process.arch === 'x64') {
+      if ((process.config && process.config.variables && process.config.variables.shlib_suffix === 'dll.a') || (process.config && process.config.variables && process.config.variables.node_target_type === 'shared_library')) {
+        try {
+          return require('./xsd-validator.win32-x64-gnu.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@zugferd/xsd-validator-win32-x64-gnu')
+          const bindingPackageVersion = require('@zugferd/xsd-validator-win32-x64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./xsd-validator.win32-x64-msvc.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@zugferd/xsd-validator-win32-x64-msvc')
+          const bindingPackageVersion = require('@zugferd/xsd-validator-win32-x64-msvc/package.json').version
+          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'ia32') {
+      try {
+        return require('./xsd-validator.win32-ia32-msvc.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@zugferd/xsd-validator-win32-ia32-msvc')
+        const bindingPackageVersion = require('@zugferd/xsd-validator-win32-ia32-msvc/package.json').version
+        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'arm64') {
+      try {
+        return require('./xsd-validator.win32-arm64-msvc.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@zugferd/xsd-validator-win32-arm64-msvc')
+        const bindingPackageVersion = require('@zugferd/xsd-validator-win32-arm64-msvc/package.json').version
+        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on Windows: ${process.arch}`))
+    }
+  } else if (process.platform === 'darwin') {
+    try {
+      return require('./xsd-validator.darwin-universal.node')
+    } catch (e) {
+      loadErrors.push(e)
+    }
+    try {
+      const binding = require('@zugferd/xsd-validator-darwin-universal')
+      const bindingPackageVersion = require('@zugferd/xsd-validator-darwin-universal/package.json').version
+      if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      }
+      return binding
+    } catch (e) {
+      loadErrors.push(e)
+    }
+    if (process.arch === 'x64') {
+      try {
+        return require('./xsd-validator.darwin-x64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@zugferd/xsd-validator-darwin-x64')
+        const bindingPackageVersion = require('@zugferd/xsd-validator-darwin-x64/package.json').version
+        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'arm64') {
+      try {
+        return require('./xsd-validator.darwin-arm64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@zugferd/xsd-validator-darwin-arm64')
+        const bindingPackageVersion = require('@zugferd/xsd-validator-darwin-arm64/package.json').version
+        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on macOS: ${process.arch}`))
+    }
+  } else if (process.platform === 'freebsd') {
+    if (process.arch === 'x64') {
+      try {
+        return require('./xsd-validator.freebsd-x64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@zugferd/xsd-validator-freebsd-x64')
+        const bindingPackageVersion = require('@zugferd/xsd-validator-freebsd-x64/package.json').version
+        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'arm64') {
+      try {
+        return require('./xsd-validator.freebsd-arm64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@zugferd/xsd-validator-freebsd-arm64')
+        const bindingPackageVersion = require('@zugferd/xsd-validator-freebsd-arm64/package.json').version
+        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'ppc64') {
+      try {
+        return require('./xsd-validator.freebsd-ppc64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@zugferd/xsd-validator-freebsd-ppc64')
+        const bindingPackageVersion = require('@zugferd/xsd-validator-freebsd-ppc64/package.json').version
+        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on FreeBSD: ${process.arch}`))
+    }
+  } else if (process.platform === 'linux') {
+    if (process.arch === 'x64') {
+      if (isMusl()) {
+        try {
+          return require('./xsd-validator.linux-x64-musl.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@zugferd/xsd-validator-linux-x64-musl')
+          const bindingPackageVersion = require('@zugferd/xsd-validator-linux-x64-musl/package.json').version
+          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./xsd-validator.linux-x64-gnu.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@zugferd/xsd-validator-linux-x64-gnu')
+          const bindingPackageVersion = require('@zugferd/xsd-validator-linux-x64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'arm64') {
+      if (isMusl()) {
+        try {
+          return require('./xsd-validator.linux-arm64-musl.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@zugferd/xsd-validator-linux-arm64-musl')
+          const bindingPackageVersion = require('@zugferd/xsd-validator-linux-arm64-musl/package.json').version
+          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./xsd-validator.linux-arm64-gnu.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@zugferd/xsd-validator-linux-arm64-gnu')
+          const bindingPackageVersion = require('@zugferd/xsd-validator-linux-arm64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'arm') {
+      if (isMusl()) {
+        try {
+          return require('./xsd-validator.linux-arm-musleabihf.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@zugferd/xsd-validator-linux-arm-musleabihf')
+          const bindingPackageVersion = require('@zugferd/xsd-validator-linux-arm-musleabihf/package.json').version
+          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./xsd-validator.linux-arm-gnueabihf.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@zugferd/xsd-validator-linux-arm-gnueabihf')
+          const bindingPackageVersion = require('@zugferd/xsd-validator-linux-arm-gnueabihf/package.json').version
+          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'loong64') {
+      if (isMusl()) {
+        try {
+          return require('./xsd-validator.linux-loong64-musl.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@zugferd/xsd-validator-linux-loong64-musl')
+          const bindingPackageVersion = require('@zugferd/xsd-validator-linux-loong64-musl/package.json').version
+          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./xsd-validator.linux-loong64-gnu.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@zugferd/xsd-validator-linux-loong64-gnu')
+          const bindingPackageVersion = require('@zugferd/xsd-validator-linux-loong64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'riscv64') {
+      if (isMusl()) {
+        try {
+          return require('./xsd-validator.linux-riscv64-musl.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@zugferd/xsd-validator-linux-riscv64-musl')
+          const bindingPackageVersion = require('@zugferd/xsd-validator-linux-riscv64-musl/package.json').version
+          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./xsd-validator.linux-riscv64-gnu.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@zugferd/xsd-validator-linux-riscv64-gnu')
+          const bindingPackageVersion = require('@zugferd/xsd-validator-linux-riscv64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'ppc64') {
+      try {
+        return require('./xsd-validator.linux-ppc64-gnu.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@zugferd/xsd-validator-linux-ppc64-gnu')
+        const bindingPackageVersion = require('@zugferd/xsd-validator-linux-ppc64-gnu/package.json').version
+        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 's390x') {
+      try {
+        return require('./xsd-validator.linux-s390x-gnu.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@zugferd/xsd-validator-linux-s390x-gnu')
+        const bindingPackageVersion = require('@zugferd/xsd-validator-linux-s390x-gnu/package.json').version
+        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on Linux: ${process.arch}`))
+    }
+  } else if (process.platform === 'openharmony') {
+    if (process.arch === 'arm64') {
+      try {
+        return require('./xsd-validator.openharmony-arm64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@zugferd/xsd-validator-openharmony-arm64')
+        const bindingPackageVersion = require('@zugferd/xsd-validator-openharmony-arm64/package.json').version
+        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'x64') {
+      try {
+        return require('./xsd-validator.openharmony-x64.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@zugferd/xsd-validator-openharmony-x64')
+        const bindingPackageVersion = require('@zugferd/xsd-validator-openharmony-x64/package.json').version
+        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else if (process.arch === 'arm') {
+      try {
+        return require('./xsd-validator.openharmony-arm.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      try {
+        const binding = require('@zugferd/xsd-validator-openharmony-arm')
+        const bindingPackageVersion = require('@zugferd/xsd-validator-openharmony-arm/package.json').version
+        if (bindingPackageVersion !== '0.1.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+    } else {
+      loadErrors.push(new Error(`Unsupported architecture on OpenHarmony: ${process.arch}`))
+    }
+  } else {
+    loadErrors.push(new Error(`Unsupported OS: ${process.platform}, architecture: ${process.arch}`))
+  }
+}
+
+function createLoadErrorChain(errors) {
+  return errors.reduce((previous, current) => {
+    let message
+    try {
+      message =
+        current && typeof current.message === 'string'
+          ? current.message
+          : String(current)
+    } catch {
+      message = 'Unknown error'
+    }
+    const error = new Error(message)
+    error.cause = previous
+    return error
+  }, null)
+}
+
+// NAPI_RS_FORCE_WASI is a tri-state flag:
+//   unset / any other value → native binding preferred, WASI is only a fallback
+//   'true'                   → prefer WASI, but retain native as a lazy fallback
+//   'error'                  → require WASI without initializing a native fallback
+// Treating any non-empty string as truthy (the historical behavior) meant
+// NAPI_RS_FORCE_WASI=false, NAPI_RS_FORCE_WASI=0, etc. inadvertently triggered
+// the WASI path, causing ENOENT for packages shipped without a .wasi.cjs file.
+//
+// NAPI_RS_WASI_FLAVOR selects one exact generated flavor and implies strict
+// WASI loading. It never crosses into another flavor or falls back to native.
+const __napiWasiFlavors = ['wasm32-wasi']
+const __napiWasiFlavor = process.env.NAPI_RS_WASI_FLAVOR
+const __napiWasiFlavorRequested =
+  typeof __napiWasiFlavor === 'string' && __napiWasiFlavor.length > 0
+if (
+  __napiWasiFlavorRequested &&
+  __napiWasiFlavors.indexOf(__napiWasiFlavor) === -1
+) {
+  throw new Error(
+    'Unsupported WASI flavor "' +
+      __napiWasiFlavor +
+      '". Available flavors: ' +
+      __napiWasiFlavors.join(', '),
+  )
+}
+const forceWasiError = process.env.NAPI_RS_FORCE_WASI === 'error'
+const forceWasi =
+  process.env.NAPI_RS_FORCE_WASI === 'true' ||
+  forceWasiError ||
+  __napiWasiFlavorRequested
+
+if (!forceWasi) {
+  nativeBinding = requireNative()
+  __napiRequiredNativeBinding = nativeBinding
+}
+
+if (!nativeBinding || forceWasi) {
+  let wasiBinding = null
+  let wasiBindingLoaded = false
+  const wasiBindingErrors = []
+  const __napiWasiResolveCandidate = (specifier, isPackage, localArtifacts) => {
+    try {
+      require.resolve(specifier)
+    } catch (resolveError) {
+      if (!resolveError || resolveError.code !== 'MODULE_NOT_FOUND') {
+        throw resolveError
+      }
+      if (isPackage) {
+        try {
+          require.resolve(specifier + '/package.json')
+        } catch (packageError) {
+          if (packageError && packageError.code === 'MODULE_NOT_FOUND') {
+            return resolveError
+          }
+          // An exports restriction proves the package exists even when its
+          // package.json is not public. Preserve the root resolution failure.
+          throw resolveError
+        }
+        // The package exists but its main/export target is broken.
+        throw resolveError
+      }
+      return resolveError
+    }
+    if (localArtifacts) {
+      let artifactError = null
+      for (let i = 0; i < localArtifacts.length; i++) {
+        try {
+          require.resolve(localArtifacts[i])
+          return null
+        } catch (resolveError) {
+          if (!resolveError || resolveError.code !== 'MODULE_NOT_FOUND') {
+            throw resolveError
+          }
+          artifactError = resolveError
+        }
+      }
+      return artifactError
+    }
+    return null
+  }
+  if (!wasiBindingLoaded && (!__napiWasiFlavorRequested || __napiWasiFlavor === 'wasm32-wasi')) {
+    let candidateError = null
+    let candidateFailed = false
+    try {
+      candidateError = __napiWasiResolveCandidate('./xsd-validator.wasi.cjs', false, ['./xsd-validator.wasm32-wasi.debug.wasm', './xsd-validator.wasm32-wasi.wasm'])
+      candidateFailed = candidateError !== null
+      if (!candidateFailed) {
+        wasiBinding = require('./xsd-validator.wasi.cjs')
+        nativeBinding = wasiBinding
+        __napiLoadedBindingTarget = 'wasm32-wasi'
+        wasiBindingLoaded = true
+      }
+    } catch (err) {
+      candidateError = err
+      candidateFailed = true
+    }
+    if (candidateFailed) {
+      wasiBindingErrors.push(candidateError)
+      loadErrors.push(candidateError)
+    }
+  }
+  if (!wasiBindingLoaded && (!__napiWasiFlavorRequested || __napiWasiFlavor === 'wasm32-wasi')) {
+    let candidateError = null
+    let candidateFailed = false
+    try {
+      candidateError = __napiWasiResolveCandidate('@zugferd/xsd-validator-wasm32-wasi', true, undefined)
+      candidateFailed = candidateError !== null
+      if (!candidateFailed) {
+        if (process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          const bindingPackageVersion = require('@zugferd/xsd-validator-wasm32-wasi/package.json').version
+          if (bindingPackageVersion !== '0.1.0') {
+            throw new Error(`WASI binding package version mismatch, expected 0.1.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+        }
+        wasiBinding = require('@zugferd/xsd-validator-wasm32-wasi')
+        nativeBinding = wasiBinding
+        __napiLoadedBindingTarget = 'wasm32-wasi'
+        wasiBindingLoaded = true
+      }
+    } catch (err) {
+      candidateError = err
+      candidateFailed = true
+    }
+    if (candidateFailed) {
+      wasiBindingErrors.push(candidateError)
+      loadErrors.push(candidateError)
+    }
+  }
+  if (
+    !wasiBindingLoaded &&
+    forceWasi &&
+    !forceWasiError &&
+    !__napiWasiFlavorRequested
+  ) {
+    nativeBinding = requireNative()
+    __napiRequiredNativeBinding = nativeBinding
+  }
+  if ((forceWasiError || __napiWasiFlavorRequested) && !wasiBindingLoaded) {
+    const error = new Error(
+      __napiWasiFlavorRequested
+        ? 'WASI binding for flavor "' + __napiWasiFlavor + '" not found'
+        : 'WASI binding not found and NAPI_RS_FORCE_WASI is set to error',
+    )
+    error.cause = createLoadErrorChain(wasiBindingErrors)
+    throw error
+  }
+}
+
+if (!nativeBinding) {
+  if (loadErrors.length > 0) {
+    const error = new Error(
+      `Cannot find native binding. ` +
+        `npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). ` +
+        'Please try `npm i` again after removing both package-lock.json and node_modules directory.',
+    )
+    // assign instead of the `new Error(message, { cause })` options form,
+    // which Node < 16.9 silently ignores
+    error.cause = createLoadErrorChain(loadErrors)
+    throw error
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+// A package can patch its own fallback in front of the load-failure check
+// above, e.g. a WebContainer download through `napi-postinstall/fallback`.
+// That fallback swaps `nativeBinding` for a generated WASI loader, which has
+// already stamped its own flavor, while the target above still says 'native'.
+// Take that flavor over, or the CommonJS stamp throws a conflict and the ESM
+// export reports the wrong artifact. Three limits keep the conflict check:
+// - only a binding this loader did not load itself, so a native addon whose
+//   `#[napi(module_exports)]` hook claims the name is still rejected;
+// - only an own data property, read through its descriptor, so no addon
+//   getter runs here, and it must read back the same, as the stamp reads it;
+// - only a flavor in `__napiWasiFlavors`, the ones this loader's own WASI
+//   chain can report ('wasm32-wasi' for a package without a WASI target).
+// This is metadata and never fails a load: a throwing Proxy trap keeps 'native'.
+if (
+  __napiLoadedBindingTarget === 'native' &&
+  nativeBinding !== __napiRequiredNativeBinding
+) {
+  try {
+    const __napiBindingTargetDescriptor = Object.getOwnPropertyDescriptor(
+      nativeBinding,
+      '__napiBindingTarget',
+    )
+    if (
+      __napiBindingTargetDescriptor &&
+      __napiWasiFlavors.indexOf(__napiBindingTargetDescriptor.value) !== -1 &&
+      nativeBinding.__napiBindingTarget === __napiBindingTargetDescriptor.value
+    ) {
+      __napiLoadedBindingTarget = __napiBindingTargetDescriptor.value
+    }
+  } catch {
+    // keep 'native'
+  }
+}
+
+function __napiStampBindingTarget(exportsObject, target) {
+  if (
+    Object.prototype.hasOwnProperty.call(exportsObject, '__napiBindingTarget')
+  ) {
+    if (exportsObject.__napiBindingTarget === target) {
+      // Already ours: the root entry aliases the object it loaded, so a WASI
+      // fallback candidate — or a `NAPI_RS_NATIVE_LIBRARY_PATH` override that
+      // is a generated loader — arrives already stamped with this same value.
+      return target
+    }
+    const error = new Error(
+      '`__napiBindingTarget` is reserved by the generated binding loader, but the loaded binding already exports it. Rename the export, e.g. #[napi(js_name = "...")].',
+    )
+    error.code = 'ERR_NAPI_BINDING_TARGET_CONFLICT'
+    throw error
+  }
+  if (!Object.isExtensible(exportsObject)) {
+    // A `#[napi(module_exports)]` hook may seal or freeze this object
+    // (`Object::seal` / `Object::freeze`). Reporting the artifact is metadata,
+    // never a reason to fail an otherwise successful load, so the stamp is
+    // skipped. What a consumer still sees then follows the entry point: the
+    // browser and deferred loaders declare `__napiBindingTarget` at module
+    // level and go on reporting it, while the CommonJS entries hand back this
+    // very object as `module.exports`, so there the value is absent.
+    return target
+  }
+  try {
+    // [[Define]], not [[Set]]: an ordinary assignment walks the prototype
+    // chain, so an inherited accessor could swallow the value or throw and
+    // fail an otherwise successful load. The descriptor is what a successful
+    // assignment would have produced.
+    Object.defineProperty(exportsObject, '__napiBindingTarget', {
+      configurable: true,
+      enumerable: true,
+      value: target,
+      writable: true,
+    })
+  } catch {
+    // Same rule as the non-extensible skip above: reporting the artifact is
+    // metadata, never a reason to fail an otherwise successful load. An exotic
+    // object (a Proxy whose defineProperty trap refuses) is skipped, not
+    // thrown over.
+  }
+  // The CommonJS loaders assign this return value so `cjs-module-lexer` — and
+  // therefore Node's CJS -> ESM named export detection — can see
+  // `__napiBindingTarget` statically.
+  return target
+}
+// Stamp before the alias, not after. The guard only reads `nativeBinding`
+// (`hasOwnProperty` plus a comparison), which is safe against any addon
+// accessor; an assignment is not, because a `#[napi(module_exports)]` hook can
+// expose a getter reporting this very value and a setter that throws. So the
+// assignment lands on the loader's own `module.exports`, still the original
+// object here, and the alias below replaces it.
+//
+// The assignment is what keeps the marker a statically visible CommonJS export:
+// `cjs-module-lexer` is Node's CJS -> ESM named export detection, it cannot see
+// a bare call, and the later `module.exports = nativeBinding` does not undo the
+// detection. The assignment itself always succeeds — its target is this
+// loader's own, still extensible `module.exports` — and the alias below then
+// discards the value it wrote. What a consumer reads is whatever the guard put
+// on `nativeBinding`, so on a frozen binding, where the guard skips, the
+// linked import resolves to `undefined`.
+module.exports.__napiBindingTarget = __napiStampBindingTarget(nativeBinding, __napiLoadedBindingTarget)
+module.exports = nativeBinding
+module.exports.XsdValidator = nativeBinding.XsdValidator
+module.exports.shutdownLibxml = nativeBinding.shutdownLibxml

package/package.json

@@ -1,6 +1,116 @@
 {
   "name": "@zugferd/xsd-validator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Node.js native addon for XSD validation via vendored libxml2",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "repository": {
+    "url": "git+ssh://git@github.com/jslno/xsd-validator.git",
+    "type": "git"
+  },
+  "license": "MIT",
+  "keywords": [
+    "napi-rs",
+    "NAPI",
+    "N-API",
+    "Rust",
+    "node-addon",
+    "node-addon-api"
+  ],
+  "files": [
+    "index.d.ts",
+    "index.js"
+  ],
+  "napi": {
+    "binaryName": "xsd-validator",
+    "targets": [
+      "aarch64-apple-darwin",
+      "aarch64-unknown-linux-gnu",
+      "aarch64-pc-windows-msvc",
+      "x86_64-apple-darwin",
+      "x86_64-pc-windows-msvc",
+      "x86_64-unknown-linux-gnu"
+    ]
+  },
+  "engines": {
+    "node": ">= 18.17.0 < 19 || >= 20.3.0 < 21 || >= 21.1.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "artifacts": "napi artifacts",
+    "bench": "node --import @oxc-node/core/register benchmark/bench.ts",
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "format": "run-p format:prettier format:rs format:toml",
+    "format:prettier": "prettier . -w",
+    "format:toml": "taplo format",
+    "format:rs": "cargo fmt",
+    "lint": "oxlint",
+    "prepublishOnly": "napi prepublish -t npm",
+    "test": "ava",
+    "version": "napi version"
+  },
+  "devDependencies": {
+    "@emnapi/core": "^1.11.3",
+    "@emnapi/runtime": "^1.11.3",
+    "@napi-rs/cli": "^3.10.12",
+    "@napi-rs/wasm-runtime": "^1.2.7",
+    "@oxc-node/core": "^0.1.7",
+    "@taplo/cli": "^0.7.0",
+    "@tybys/wasm-util": "^0.10.4",
+    "ava": "^8.3.0",
+    "chalk": "^5.6.2",
+    "emnapi": "^1.11.3",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.6.0",
+    "npm-run-all2": "^9.0.4",
+    "oxlint": "^1.91.0",
+    "prettier": "^3.9.10",
+    "tinybench": "^6.2.3",
+    "typescript": "^7.0.2"
+  },
+  "lint-staged": {
+    "*.@(js|ts|tsx)": [
+      "oxlint --fix"
+    ],
+    "*.@(js|ts|tsx|yml|yaml|md|json)": [
+      "prettier --write"
+    ],
+    "*.toml": [
+      "taplo format"
+    ]
+  },
+  "ava": {
+    "extensions": [
+      "ts"
+    ],
+    "timeout": "2m",
+    "workerThreads": false,
+    "environmentVariables": {
+      "TS_NODE_PROJECT": "./tsconfig.json"
+    },
+    "nodeArguments": [
+      "--import",
+      "@oxc-node/core/register"
+    ]
+  },
+  "prettier": {
+    "printWidth": 120,
+    "semi": false,
+    "trailingComma": "all",
+    "singleQuote": true,
+    "arrowParens": "always"
+  },
+  "packageManager": "pnpm@12.16.1",
+  "optionalDependencies": {
+    "@zugferd/xsd-validator-darwin-arm64": "0.1.0",
+    "@zugferd/xsd-validator-linux-arm64-gnu": "0.1.0",
+    "@zugferd/xsd-validator-win32-arm64-msvc": "0.1.0",
+    "@zugferd/xsd-validator-darwin-x64": "0.1.0",
+    "@zugferd/xsd-validator-win32-x64-msvc": "0.1.0",
+    "@zugferd/xsd-validator-linux-x64-gnu": "0.1.0"
+  }
+}