@syncmatters/script-api 1.0.9 → 1.0.10

package/lib/utilities/utilities.d.ts

@@ -12,6 +12,7 @@ import { XlsxWriter, XlsxWriterOptions } from "./xlsx-writer/xlsx-writer.js";
 import { emailCleanse } from "./www-utils/www-utils.js";
 import { emailIsPublic } from "./www-utils/www-utils.js";
 import { domainParse } from "./www-utils/www-utils.js";
+import { xmlParse } from "./xml-utils/xml-utils.js";
 import { nameParser } from "./name-parser/name-parser.js";
 import { tempDir, tempFile } from "./file-utils/file-utils.js";
 import { dateFormat, dateParse, dateTransform } from "./date-utils/date-utils.js";
@@ -87,9 +88,7 @@ export declare const utilities: {
     };
     xlsxReader: (options: XlsxReaderOptions) => XlsxReader;
     xlsxWriter: (options: XlsxWriterOptions) => XlsxWriter;
-    xmlParse: (options: {
-        string: string;
-    }) => Promise<any>;
+    xmlParse: typeof xmlParse;
     zip: {
         compress: typeof zipCompress;
         extract: typeof zipExtract;

package/lib/utilities/xml-utils/types.d.ts

@@ -0,0 +1,39 @@
+import { FileProvider } from "../file-provider/file-provider.js";
+/** Where xmlParse reads XML from; exactly one of `fileProvider` or `string`. */
+export interface XmlParseSource {
+    fileProvider?: FileProvider;
+    string?: string;
+    /** Decoding for fileProvider bytes (default `"utf8"`); ignored for string sources. */
+    encoding?: "utf8" | "utf16le" | "ucs2" | "latin1";
+}
+/**
+ * Options for xmlParse (module-internal; not re-exported from the package root).
+ * Prefer `source`; top-level `string` is deprecated.
+ * Set `emit` to stream matching elements; omit for a full-document Promise.
+ */
+export interface XmlParseOptions {
+    /**
+     * @deprecated Use `source: { string }` instead.
+     */
+    string?: string;
+    source?: XmlParseSource;
+    /**
+     * XPath subset expressions: `//Name`, `/A/B/C`, or `A/B` (local names; XML prefixes ignored).
+     * When set, xmlParse streams matching elements; omit for a full-document Promise.
+     */
+    emit?: string[];
+}
+/**
+ * One matched element from a streaming xmlParse({ source, emit }) call.
+ * Call sites normally infer this; kept here like CsvReader's row contract.
+ */
+export interface XmlParseChunk {
+    matched: string;
+    localName: string;
+    path: string[];
+    ancestors: Array<{
+        localName: string;
+        attributes: Record<string, string>;
+    }>;
+    value: any;
+}

package/lib/utilities/xml-utils/xml-fragment-recorder.d.ts

@@ -0,0 +1,11 @@
+/** Rebuild a well-formed XML fragment from sax events (saxpath-recorder style). */
+export declare class XmlFragmentRecorder {
+    #private;
+    onOpenTag(name: string, attributes: Record<string, string>, isSelfClosing: boolean): void;
+    onText(text: string): void;
+    onCdata(text: string): void;
+    /**
+     * @returns completed outer XML when the recorded root element closes; otherwise undefined
+     */
+    onCloseTag(name: string): string | undefined;
+}

package/lib/utilities/xml-utils/xml-utils.d.ts

@@ -1 +1,7 @@
-export declare function xmlParse(source: string): Promise<any>;
+import type { XmlParseChunk, XmlParseOptions } from "./types.js";
+export declare function xmlParse(options: XmlParseOptions & {
+    emit: string[];
+}): AsyncIterable<XmlParseChunk>;
+export declare function xmlParse(options: XmlParseOptions & {
+    emit?: undefined;
+}): Promise<any>;

package/lib/utilities/xml-utils/xpath-subset.d.ts

@@ -0,0 +1,26 @@
+/** Compiled emit expression — internal to xml-utils streaming. */
+export type XmlEmitMatcher = {
+    kind: "descendant";
+    localName: string;
+    raw: string;
+} | {
+    kind: "absolute";
+    steps: string[];
+    raw: string;
+} | {
+    kind: "suffix";
+    steps: string[];
+    raw: string;
+};
+/** Strip an XML prefix from a qname (`edm:EntityType` → `EntityType`). */
+export declare function localNameOf(qname: string): string;
+/**
+ * Compile one XPath-subset expression.
+ * Supported: `//Name`, `/A/B/C`, `A/B` (local names only; prefixes ignored).
+ */
+export declare function compileEmitExpression(raw: string): XmlEmitMatcher;
+export declare function compileEmitExpressions(emit: string[]): XmlEmitMatcher[];
+/** True if the current element stack (local names) matches the compiled expression. */
+export declare function matchesEmit(matcher: XmlEmitMatcher, pathLocalNames: string[]): boolean;
+/** Last path step local name for a matcher (the element that starts a potential match). */
+export declare function matcherTargetLocalName(matcher: XmlEmitMatcher): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncmatters/script-api",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "TypeScript type definitions for the SyncMatters script API (types only - scripts execute on the SyncMatters platform)",
   "types": "./index.d.ts",
   "exports": {
@@ -20,7 +20,7 @@
   "license": "MIT",
   "author": "SyncMatters",
   "homepage": "https://syncmatters.com",
-  "typesContentHash": "fbf6d9da4649e1b2922ad811c5ebb8c69b7d526bd28c77fcc3a42e0abc9eda59",
+  "typesContentHash": "5251aaa77076a0901c2b3221a4be5f4d9a9d9aeb572ef3e59f4952b31e9fffdf",
   "dependencies": {
     "@types/node": "*"
   }