@syncmatters/script-api 1.0.8 → 1.0.10

package/lib/connection.d.ts

@@ -192,6 +192,8 @@ export interface QueryOptions {
     randomFilter?: boolean;
     /** filter for rows by row id (key) */
     idsFilter?: Array<string>;
+    /** path of the alternate key field that the idsFilter values refer to, if applicable */
+    idsFilterField?: Array<API.JsonValuePathPart>;
     /** filter for rows that relate to another object on this connection */
     relatedFilter?: QueryRelatedFilter;
     /** filter for rows that meet a specific matching rule */
@@ -239,6 +241,8 @@ export interface QueryOneOptions {
     relationshipFields?: Array<string>;
     /** filter for rows by row id (key) */
     idsFilter?: Array<string>;
+    /** path of the alternate key field that the idsFilter values refer to, if applicable */
+    idsFilterField?: Array<API.JsonValuePathPart>;
     /** filter for rows that relate to another object on this connection */
     relatedFilter?: QueryRelatedFilter;
     /** filter for rows that meet a specific matching rule */
@@ -264,7 +268,8 @@ export interface Row {
     data?: any;
     /** if filters requested files be included in the response, and the if row includes a file, the file will be here */
     file?: FileProvider | null | undefined;
-    /** if filters requested rows filter by 'related', or 'matched' to source rows the relationship details will be here */
+    /** if filters requested rows filter by 'related', or 'matched' to source rows the relationship details will be here;
+     * for idsFilter queries with an idsFilterField, srcRowId holds the requested (alternate key) value this row matched */
     relationship?: {
         relationshipId?: string;
         srcObjectId?: string;
@@ -439,6 +444,8 @@ export interface ObjectField {
     isKey?: boolean;
     /** field holds an object containing the user defined row unique identifier required for add an update operations, and an indication of the operation type */
     isUserKey?: boolean;
+    /** field holds a unique value and the connector honors it as an idsFilterField key in queries */
+    isAlternateKey?: boolean;
     /** field, and any fields below, are custom (account specific) */
     isCustom?: boolean;
     /** can this field be referenced in match rules? */

package/lib/sync.d.ts

@@ -1,4 +1,4 @@
-import { Row, QueryRelatedFilter, QueryMatchFilter, QueryCheckpointFilter, UpsertCleanOptions, UpsertCleanResponse, ObjectFieldConstraints, JsonValuePath, RowMatchRuleType, Logger, Connection } from "../index.js";
+import { Row, QueryRelatedFilter, QueryMatchFilter, QueryCheckpointFilter, UpsertCleanOptions, UpsertCleanResponse, ObjectFieldConstraints, JsonValuePath, JsonValuePathPart, RowMatchRuleType, Logger, Connection } from "../index.js";
 export type GroupRunMode = "Standard" | "SelectedIds" | "Errors";
 export type SyncOptimalBatchSizeOperation = "noFilter" | "idsFilter" | "relatedFilter" | "matchFilter" | "checkpointFilter" | "randomFilter" | "rowFilter" | "upsert" | "delete";
 export type SyncOptimalBatchSizeBatchType = "atomic" | "concurrent" | "splitInsertUpdateAtomic";
@@ -163,6 +163,9 @@ export interface SyncEndpointField {
     /** indicates this field holds an object containing the user defined unique row identifier required
      * for add and update operations, with an indication of the operation type */
     isUserDefinedId?: boolean;
+    /** indicates this field holds a unique value the connector can resolve rows by as an alternate to
+     * the row id (e.g. in lookups) */
+    isAlternateId?: boolean;
     /** indicates this field is custom */
     isCustom?: boolean;
 }
@@ -198,6 +201,8 @@ export interface SyncQueryOptions {
     randomFilter?: boolean;
     /** filter for rows by row id (key) */
     idsFilter?: Array<string>;
+    /** path of the alternate key field that the idsFilter values refer to, if applicable */
+    idsFilterField?: Array<JsonValuePathPart>;
     /** filter for rows that relate to another objects rows on this endpoint */
     relatedFilter?: QueryRelatedFilter;
     /** filter for rows that meet a specific matching rule */

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.8",
+  "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": "06c0e7d73e478f9b36cfd586c79b5d57c001924d7f7f1b7868771537b4176e27",
+  "typesContentHash": "5251aaa77076a0901c2b3221a4be5f4d9a9d9aeb572ef3e59f4952b31e9fffdf",
   "dependencies": {
     "@types/node": "*"
   }