@docx4j/core-ts 0.1.3 → 0.1.4

package/dist/model/customxml/xpath-fonto.d.mts

@@ -3,10 +3,32 @@ import type { BooleanConversionMode, XPathEngine, XPathValue } from './xpath.mjs
  * XPath 3.1 through FontoXPath, for the `xpath2` boolean conversion mode and for expressions
  * written in XPath 2.0 syntax. `select`, `selectValue` and the `java` and `xpath1` modes answer as
  * `DefaultXPathEngine` does; `xpath2` is the mode this engine exists for.
+ *
+ * **In a browser or any bundled application, pass the module in.** The no-argument form loads
+ * `fontoxpath` by a dynamic `import()` of the bare specifier, which Node resolves and a browser
+ * does not: there is no import map, and the `@vite-ignore` that keeps a bundler from rewriting the
+ * specifier (needed so that a bundle never carries the optional peer against the consumer's will)
+ * also keeps it from resolving it. So the application imports the module itself, where its own
+ * bundler resolves it statically, and hands it over:
+ *
+ *     import * as fontoxpath from 'fontoxpath';
+ *     import { FontoXPathEngine } from '@docx4j/core-ts/xpath-fonto';
+ *     pkg.xpathEngine = new FontoXPathEngine(fontoxpath);   // ready at once
+ *
+ * In Node, `new FontoXPathEngine()` and `await ready()` still work and still say what to install
+ * if the peer is absent. Which module is loaded, and when, is the consumer's business either way -
+ * the same principle as `pkg.xpathEngine` being settable at all (CR-005 phase A, 2026-09-26).
  */
 export declare class FontoXPathEngine implements XPathEngine {
     private module;
     private loading;
+    /**
+     * @param fontoxpath the `fontoxpath` module, imported by the caller. Omit it in Node to have
+     *   `ready()` import it; supply it in a browser or a bundle, where a bare dynamic specifier
+     *   cannot be resolved. Either the module's namespace object or its default export is accepted,
+     *   the published ESM build having no named exports under Node's interop.
+     */
+    constructor(fontoxpath?: unknown);
     get isReady(): boolean;
     ready(): Promise<void>;
     select(expression: string, context: Node, namespaces?: Record<string, string>): Node[];

package/dist/model/customxml/xpath-fonto.mjs

@@ -21,8 +21,33 @@ const ANY_TYPE = 0;
  * XPath 3.1 through FontoXPath, for the `xpath2` boolean conversion mode and for expressions
  * written in XPath 2.0 syntax. `select`, `selectValue` and the `java` and `xpath1` modes answer as
  * `DefaultXPathEngine` does; `xpath2` is the mode this engine exists for.
+ *
+ * **In a browser or any bundled application, pass the module in.** The no-argument form loads
+ * `fontoxpath` by a dynamic `import()` of the bare specifier, which Node resolves and a browser
+ * does not: there is no import map, and the `@vite-ignore` that keeps a bundler from rewriting the
+ * specifier (needed so that a bundle never carries the optional peer against the consumer's will)
+ * also keeps it from resolving it. So the application imports the module itself, where its own
+ * bundler resolves it statically, and hands it over:
+ *
+ *     import * as fontoxpath from 'fontoxpath';
+ *     import { FontoXPathEngine } from '@docx4j/core-ts/xpath-fonto';
+ *     pkg.xpathEngine = new FontoXPathEngine(fontoxpath);   // ready at once
+ *
+ * In Node, `new FontoXPathEngine()` and `await ready()` still work and still say what to install
+ * if the peer is absent. Which module is loaded, and when, is the consumer's business either way -
+ * the same principle as `pkg.xpathEngine` being settable at all (CR-005 phase A, 2026-09-26).
  */
 export class FontoXPathEngine {
+    /**
+     * @param fontoxpath the `fontoxpath` module, imported by the caller. Omit it in Node to have
+     *   `ready()` import it; supply it in a browser or a bundle, where a bare dynamic specifier
+     *   cannot be resolved. Either the module's namespace object or its default export is accepted,
+     *   the published ESM build having no named exports under Node's interop.
+     */
+    constructor(fontoxpath) {
+        if (fontoxpath !== undefined)
+            this.module = moduleOf(fontoxpath);
+    }
     get isReady() {
         return this.module !== undefined;
     }
@@ -31,15 +56,14 @@ export class FontoXPathEngine {
         if (this.isReady)
             return;
         (_a = this.loading) !== null && _a !== void 0 ? _a : (this.loading = (async () => {
-            var _a;
             const specifier = 'fontoxpath';
             try {
-                // The published ESM build has no named exports under Node's interop, only a default.
                 const loaded = await import(/* @vite-ignore */ specifier);
-                this.module = (_a = loaded.default) !== null && _a !== void 0 ? _a : loaded;
+                this.module = moduleOf(loaded);
             }
             catch (e) {
-                throw new Docx4JException("FontoXPathEngine needs the optional peer dependency 'fontoxpath' (npm install fontoxpath)", { cause: e });
+                throw new Docx4JException("FontoXPathEngine needs the optional peer dependency 'fontoxpath' (npm install fontoxpath); "
+                    + 'in a browser or a bundle, import it yourself and pass it: new FontoXPathEngine(fontoxpath)', { cause: e });
             }
         })());
         await this.loading;
@@ -107,6 +131,20 @@ export class FontoXPathEngine {
         return this.module;
     }
 }
+/**
+ * The module, whether given as a namespace object or as a default export, checked for the one
+ * function every call goes through so that the wrong module is refused where it is passed rather
+ * than at the first evaluation.
+ */
+function moduleOf(loaded) {
+    const candidate = loaded;
+    const module = typeof (candidate === null || candidate === void 0 ? void 0 : candidate.evaluateXPath) === 'function' ? candidate : candidate === null || candidate === void 0 ? void 0 : candidate.default;
+    if (!module || typeof module.evaluateXPath !== 'function') {
+        throw new Docx4JException('FontoXPathEngine was given something that is not the fontoxpath module: '
+            + "expected its evaluateXPath, as in new FontoXPathEngine(await import('fontoxpath'))");
+    }
+    return module;
+}
 /** A FontoXPath result in the four-type union `selectValue` reports. */
 function valueOf(value) {
     var _a;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docx4j/core-ts",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "docx4j-core for TypeScript: Open Packaging (docx/pptx/xlsx zip and flat OPC), typed parts and relationships, style, numbering and font resolution over @docx4j/generated-objects-ts. Node, browsers, Word add-ins.",
   "type": "module",
   "main": "./dist/index.mjs",