@docx4j/jsonix 3.2.0 → 3.3.0

package/jsonix.mjs

@@ -1,6 +1,8 @@
-// ES-module entry point (package.json "exports" -> "import").
-// The runtime stays a single CommonJS bundle (jsonix.js); this wrapper gives ESM consumers and
-// bundlers a static named export, which the UMD footer of jsonix.js cannot provide.
-import cjs from './jsonix.js';
-export const Jsonix = cjs.Jsonix;
-export default cjs;
+// ES-module entry for browsers and browser bundlers (package.json "exports" -> "default" -> "import").
+// No Node dependency is reachable from this file: the browser supplies DOMParser, XMLSerializer and
+// XMLHttpRequest. Node and Node bundlers take jsonix.node.mjs through the "node" condition instead.
+// (jsonix-CR-005 section 7.1)
+import factory from './jsonix-factory.js';
+const { Jsonix } = factory();
+export { Jsonix };
+export default { Jsonix };

package/jsonix.node.mjs

@@ -0,0 +1,35 @@
+// ES-module entry for Node and Node bundlers (package.json "exports" -> "node" -> "import").
+// The DOM dependency is a static import, which every bundler resolves, instead of the UMD footer's
+// runtime resolution that a bundle cannot perform. (jsonix-CR-005 section 7.1)
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import xmldom from '@xmldom/xmldom';
+import factory from './jsonix-factory.js';
+
+// xmlhttprequest is a CommonJS package that requires Node built-ins (url, http, https, child_process)
+// at load time, which an ES-module bundle cannot carry: esbuild emits "Dynamic require of 'url' is not
+// supported". It is needed only by Unmarshaller.unmarshalURL and Jsonix.DOM.load, so it is resolved
+// lazily, at first use, with a real require that bundlers leave alone. Parsing never touches it.
+// import.meta.url is empty when a bundler emits CommonJS from this file (it applies the "import"
+// condition to any `import` statement, whatever the output format); resolve from the working
+// directory then.
+const nodeRequire = (() => {
+  try {
+    return createRequire(import.meta.url);
+  } catch (e) {
+    return createRequire(process.cwd() + '/');
+  }
+})();
+const xmlhttprequest = {
+  get XMLHttpRequest() {
+    try {
+      return nodeRequire('xmlhttprequest').XMLHttpRequest;
+    } catch (e) {
+      throw new Error('Jsonix: unmarshalURL / Jsonix.DOM.load need the xmlhttprequest package, which could not be loaded: ' + e.message);
+    }
+  },
+};
+
+const { Jsonix } = factory(xmldom, xmlhttprequest, fs);
+export { Jsonix };
+export default { Jsonix };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@docx4j/jsonix",
-	"version": "3.2.0",
+	"version": "3.3.0",
 	"description": "Jsonix (JSON interfaces for XML) is a JavaScript library which allows converting between XML and JSON structures.",
 	"keywords": [
 		"json",
@@ -24,12 +24,7 @@
 	"bugs": {
 		"url": "https://github.com/plutext/jsonix/issues"
 	},
-	"licenses": [
-		{
-			"type": "(Apache-2.0 AND BSD-2-Clause)",
-			"url": "https://github.com/plutext/jsonix/raw/master/LICENSE"
-		}
-	],
+	"license": "(Apache-2.0 AND BSD-2-Clause)",
 	"author": {
 		"name": "Alexey Valikov",
 		"url": "http://github.com/highsource"
@@ -52,29 +47,37 @@
 	"module": "jsonix.mjs",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/plutext/jsonix.git"
+		"url": "git+https://github.com/plutext/jsonix.git"
 	},
 	"types": "./types/main.d.ts",
 	"exports": {
 		".": {
 			"types": "./types/main.d.ts",
-			"import": "./jsonix.mjs",
-			"require": "./jsonix.js"
+			"node": {
+				"import": "./jsonix.node.mjs",
+				"require": "./jsonix.js"
+			},
+			"default": {
+				"import": "./jsonix.mjs",
+				"require": "./jsonix.js"
+			}
 		},
 		"./jsonix.js": "./jsonix.js",
+		"./jsonix-factory.js": "./jsonix-factory.js",
 		"./package.json": "./package.json"
 	},
 	"scripts": {
 		"test": "nodeunit tests/tests.js",
 		"typecheck": "tsc -p tests/typescript/tsconfig.json && tsc -p tests/typescript/tsconfig.node16.json",
-		"test:esm": "node tests/typescript/esm-smoke.mjs"
+		"test:esm": "node tests/typescript/esm-smoke.mjs",
+		"test:bundle": "node tests/bundle/bundle-test.mjs"
 	},
 	"dependencies": {
 		"@xmldom/xmldom": "^0.9.7",
-		"amdefine": "^1.0.1",
 		"xmlhttprequest": "^1.8.0"
 	},
 	"devDependencies": {
+		"esbuild": "~0.28.2",
 		"node-static": "^0.7.11",
 		"nodeunit": "^0.11.3",
 		"typescript": "~5.6.3"

package/src/main/npm/package.json

@@ -24,12 +24,7 @@
 	"bugs": {
 		"url": "https://github.com/plutext/jsonix/issues"
 	},
-	"licenses": [
-		{
-			"type": "BSD-3-Clause",
-			"url": "https://github.com/plutext/jsonix/raw/master/LICENSE"
-		}
-	],
+	"license": "(Apache-2.0 AND BSD-2-Clause)",
 	"author": {
 		"name": "Alexey Valikov",
 		"url": "http://github.com/highsource"
@@ -47,7 +42,7 @@
 	"main": "jsonix.js",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/plutext/jsonix.git"
+		"url": "git+https://github.com/plutext/jsonix.git"
 	},
 	"scripts": {
 		"test": "nodeunit tests/tests.js"

package/types/main.d.ts

@@ -52,6 +52,54 @@ export namespace Jsonix {
     }
   }
 
+  /**
+   * DOM access as the runtime does it: @xmldom/xmldom and xmlhttprequest when injected (Node),
+   * the browser's DOMParser / XMLSerializer / XMLHttpRequest otherwise (jsonix-CR-003 part 1).
+   */
+  /**
+   * A DOM implementation a consumer can supply with `DOM.use`: any object exposing the W3C
+   * constructors, for example the `@xmldom/xmldom` module. Missing members fall through to the
+   * next option (injected xmldom, then browser globals).
+   */
+  export interface DomImplementation {
+    DOMParser?: new (options?: unknown) => { parseFromString(text: string, mimeType: string): Document };
+    XMLSerializer?: new () => { serializeToString(node: Node): string };
+    DOMImplementation?: new () => { createDocument(...args: unknown[]): Document };
+  }
+
+  export namespace DOM {
+    /**
+     * Supplies the DOM implementation to use, consulted before the xmldom injected into the
+     * runtime and before browser globals; `null` clears it (jsonix-CR-005). For workers, sandboxes
+     * and bundles the runtime cannot detect.
+     */
+    function use(implementation: DomImplementation | null): void;
+    /** The implementation in effect: the one given to `use`, else the injected xmldom, else `null` (browser globals will be tried). */
+    function getImplementation(): DomImplementation | null;
+    /** XML 1.0 section 2.11 line-ending normalisation: CR LF and bare CR become LF (jsonix-CR-004). */
+    function normalizeLineEndings10(text: string): string;
+    /** XML 1.1 section 2.11: additionally CR NEL, NEL (U+0085) and LINE SEPARATOR (U+2028) become LF. */
+    function normalizeLineEndings11(text: string): string;
+    /** True when the text starts with an XML declaration whose version is 1.1. `parse` uses it to pick the normalisation. */
+    function isXml11(text: string): boolean;
+    /** True when a DOM implementation (supplied, injected xmldom, or the browser's) is available. */
+    function isDomImplementationAvailable(): boolean;
+    /** A new, empty XML document. Takes no arguments; the runtime ignores any that are passed. */
+    function createDocument(): Document;
+    /** Serialises a node to XML text; throws if no serializer is available. */
+    function serialize(node: Node): string;
+    /**
+     * Parses XML text into a document; throws on malformed input. Line endings are normalised per the
+     * document's XML version (1.0 unless the declaration says 1.1), so raw U+0085 and U+2028 survive in
+     * XML 1.0 text (jsonix-CR-004).
+     */
+    function parse(text: string): Document;
+    /** Loads and parses the URL through the runtime's XMLHttpRequest transport (see Unmarshaller.unmarshalURL). */
+    function load(url: string, callback: (doc: Document) => void, options?: UnmarshalOptions): void;
+    /** Whether the xlink namespace work-around for older Chrome builds is needed in this environment. */
+    function isXlinkFixRequired(): boolean;
+  }
+
   /**
    * An element: what an unmarshaller returns, what a marshaller accepts, and the value of an
    * elementRef property. Generated declarations alias this per global element, for example
@@ -168,6 +216,13 @@ export namespace Jsonix {
      */
     constructor(mappings: M[], options?: ContextOptions);
 
+    /**
+     * The namespace-to-prefix table this context marshals with, copied from
+     * `options.namespacePrefixes` at construction. Read-only: derive a per-document table rather
+     * than mutating the shared context.
+     */
+    readonly namespacePrefixes: { readonly [namespaceURI: string]: string };
+
     createUnmarshaller(): Unmarshaller<RootElementOf<M>>;
     createMarshaller(): Marshaller;