@wirebench/engine 2.1.1

package/dist/soap/mime/send-pipeline.js

@@ -0,0 +1,145 @@
+/**
+ * The attachment stages of a send: what happens to the envelope on the way out, and how a
+ * `multipart/related` response is unwrapped on the way back in.
+ *
+ * Kept beside the MIME modules rather than in `send.ts` so the ordering rules live next to
+ * the code that implements them.
+ */
+import { headerValue, setHeader } from '../../http/headers.js';
+import { decodeBody, encodeBody } from '../charset.js';
+import { inlineFiles } from './inline-files.js';
+import { expandMtomResponse, prepareMtomRequest, xopContentType } from './mtom.js';
+import { DEFAULT_ROOT_CONTENT_ID, buildMultipartRelated, mediaTypeOf, parseMultipartRelated } from './multipart.js';
+import { prepareSwaRequest } from './swa.js';
+/**
+ * Substitutes every `file:` reference in the envelope with the file's base64 bytes.
+ *
+ * This is envelope *text preparation*, exactly like property expansion, so it runs before the
+ * envelope transforms rather than with the attachment packaging that follows them (see
+ * `send.ts`): a WS-Security signature must cover the bytes that actually go on the wire, and
+ * signing the literal `file:/…` text and then replacing it would produce a signature no
+ * receiver can verify.
+ *
+ * A missing file is a problem, not a failure: the reference is left verbatim and the send
+ * continues, since the server's own error is usually more informative than a client-side abort.
+ * Without a `resolveFile` there is no way to read anything, so the property is inert.
+ *
+ * @param input the (already expanded) send input
+ * @param problems collects non-fatal issues, e.g. an inline file that is missing
+ * @returns the envelope with every readable `file:` reference replaced
+ */
+export async function substituteInlineFiles(input, problems) {
+    const options = input.attachmentOptions;
+    if (options === undefined || !options.enableInlineFiles || options.resolveFile === undefined) {
+        return input.envelopeXml;
+    }
+    const inlined = await inlineFiles(input.envelopeXml, {
+        enabled: true,
+        resolveFile: options.resolveFile,
+        ...(options.resourceRoot !== undefined ? { resourceRoot: options.resourceRoot } : {}),
+    });
+    for (const problem of inlined.problems) {
+        problems.push({ code: problem.code, message: problem.message });
+    }
+    return inlined.envelopeXml;
+}
+/**
+ * Runs the request-side attachment pipeline and returns the bytes to send.
+ *
+ * The order is fixed: property expansion, inline-file substitution
+ * ({@link substituteInlineFiles}) and the envelope transforms have already happened, then
+ * MTOM claims the attachments its `cid:` references name, then everything left over rides
+ * along as SwA. Only when something is actually packaged is the `Content-Type` replaced by
+ * the multipart's — the caller's own content type (charset and all) becomes the root part's,
+ * so a request that sets one still gets what it asked for where it matters.
+ *
+ * "Disable Multiparts" short-circuits the whole stage, MTOM included: rewriting a `cid:`
+ * reference into an `xop:Include` whose part is then not sent would produce a message no
+ * server can read.
+ *
+ * @param input the (already expanded, already inlined) send input
+ * @param headers the request headers, mutated when a multipart Content-Type takes over
+ */
+export async function packageRequestBody(input, headers) {
+    const options = input.attachmentOptions;
+    if (options === undefined) {
+        return encodeBody(input.envelopeXml, input.encoding);
+    }
+    // Inline files were already substituted, before the envelope transforms — see
+    // {@link substituteInlineFiles} and the pipeline order in `send.ts`.
+    let envelopeXml = input.envelopeXml;
+    const attachments = input.attachments ?? [];
+    const parts = [];
+    let mtom = false;
+    if (!options.disableMultiparts) {
+        let remaining = attachments;
+        if (options.enableMtom || options.forceMtom) {
+            const prepared = await prepareMtomRequest(envelopeXml, attachments, {
+                force: options.forceMtom,
+                resolver: options.resolver,
+            });
+            envelopeXml = prepared.envelopeXml;
+            parts.push(...prepared.parts);
+            mtom = prepared.used;
+            remaining = attachments.filter((attachment) => !prepared.consumedIds.includes(attachment.id));
+        }
+        const swa = await prepareSwaRequest(envelopeXml, remaining, {
+            resolver: options.resolver,
+            encodeAttachments: options.encodeAttachments,
+        });
+        parts.push(...swa.parts);
+    }
+    const encoded = encodeBody(envelopeXml, input.encoding);
+    if (parts.length === 0 && !mtom) {
+        return encoded;
+    }
+    const soapContentType = headerValue(headers, 'content-type') ?? 'text/xml;charset=UTF-8';
+    const built = buildMultipartRelated({
+        root: {
+            contentType: mtom ? xopContentType(soapContentType) : soapContentType,
+            contentId: DEFAULT_ROOT_CONTENT_ID,
+            bytes: encoded,
+        },
+        parts,
+        ...(mtom ? { mtom: true } : {}),
+    });
+    setHeader(headers, 'content-type', built.contentType);
+    return built.body;
+}
+/**
+ * Reads the response body as an envelope, unwrapping a `multipart/related` response into
+ * its root part plus attachments.
+ *
+ * A response is unwrapped whether or not the request asked for attachments — a server may
+ * answer with MTOM regardless — but the two response knobs only apply when the request
+ * carried them: `expandMtomAttachments` writes each referenced part back into the envelope
+ * as base64, and `inlineResponseAttachments` decides whether those parts stay listed
+ * afterwards.
+ */
+export function readResponseBody(body, contentType, options, problems) {
+    const isMultipart = contentType !== undefined && mediaTypeOf(contentType).toLowerCase().startsWith('multipart/');
+    if (!isMultipart) {
+        const decoded = decodeBody(body, contentType);
+        if (decoded.problem !== undefined) {
+            problems.push(decoded.problem);
+        }
+        return { envelopeXml: decoded.text };
+    }
+    const parsed = parseMultipartRelated(body, contentType);
+    for (const problem of parsed.problems) {
+        problems.push({ code: 'mime-parse', message: `Response multipart: ${problem}` });
+    }
+    // A root part with no Content-Type of its own still inherits the multipart's charset.
+    const decoded = decodeBody(parsed.root.bytes, parsed.root.headers['content-type'] ?? contentType);
+    if (decoded.problem !== undefined) {
+        problems.push(decoded.problem);
+    }
+    const expanded = expandMtomResponse(parsed, {
+        inline: options?.expandMtomAttachments === true,
+        envelopeXml: decoded.text,
+    });
+    const attachments = options?.inlineResponseAttachments === true
+        ? expanded.attachments
+        : expanded.attachments.filter((attachment) => !expanded.inlinedContentIds.includes(attachment.contentId));
+    return { envelopeXml: expanded.envelopeXml, attachments };
+}

package/dist/soap/mime/swa.d.ts

@@ -0,0 +1,45 @@
+/**
+ * SOAP with Attachments (SwA), including swaRef per WS-I Attachments Profile 1.0.
+ *
+ * SwA is the plain case: the envelope is sent untouched as the root part and every
+ * attachment rides along beside it. A `ref:swaRef`-typed element already contains the
+ * `cid:` reference the profile asks for, so — unlike MTOM — nothing in the body is
+ * rewritten; the reference simply has to name a part that is actually there.
+ */
+import type { Attachment } from '../../project/model.js';
+import type { ParsedMultipart } from './multipart.js';
+import type { AttachmentResolver, MultipartPart, ResponseAttachment } from './types.js';
+/** Knobs for {@link prepareSwaRequest}. */
+export interface SwaOptions {
+    readonly resolver: AttachmentResolver;
+    /** "Encode Attachments": base64 transfer encoding instead of binary. */
+    readonly encodeAttachments: boolean;
+    /** "Disable Multiparts": send the envelope alone and ignore every attachment. */
+    readonly disableMultiparts?: boolean;
+}
+/** What {@link prepareSwaRequest} produced. */
+export interface PreparedSwa {
+    readonly parts: readonly MultipartPart[];
+    /** False when nothing is to be sent as a multipart (no attachments, or multiparts disabled). */
+    readonly used: boolean;
+    /** Content-IDs the envelope actually references with `cid:` (swaRef and friends). */
+    readonly referencedContentIds: readonly string[];
+}
+/**
+ * Builds the SwA parts for `attachments` — every attachment MTOM did not already consume.
+ *
+ * The envelope is never modified; it is only scanned, so the caller can tell which
+ * attachments a `cid:` reference in the body actually points at (an unreferenced
+ * attachment is still sent, which is what "anonymous" MIME parts are for).
+ *
+ * @param envelopeXml the envelope as it will be sent
+ * @param attachments the attachments to package
+ * @param options the resolver plus the request's encode/disable flags
+ */
+export declare function prepareSwaRequest(envelopeXml: string, attachments: readonly Attachment[], options: SwaOptions): Promise<PreparedSwa>;
+/**
+ * Describes every non-root part of a parsed response as a {@link ResponseAttachment}.
+ *
+ * @param parsed the parsed `multipart/related` response
+ */
+export declare function collectResponseAttachments(parsed: ParsedMultipart): readonly ResponseAttachment[];

package/dist/soap/mime/swa.js

@@ -0,0 +1,62 @@
+/**
+ * SOAP with Attachments (SwA), including swaRef per WS-I Attachments Profile 1.0.
+ *
+ * SwA is the plain case: the envelope is sent untouched as the root part and every
+ * attachment rides along beside it. A `ref:swaRef`-typed element already contains the
+ * `cid:` reference the profile asks for, so — unlike MTOM — nothing in the body is
+ * rewritten; the reference simply has to name a part that is actually there.
+ */
+import { findCidReferences } from './cid-scan.js';
+/** The Content-ID an attachment goes out with: its own, or its id as a fallback. */
+function contentIdOf(attachment) {
+    return attachment.contentId.length > 0 ? attachment.contentId : `${attachment.id}@wirebench`;
+}
+/**
+ * Builds the SwA parts for `attachments` — every attachment MTOM did not already consume.
+ *
+ * The envelope is never modified; it is only scanned, so the caller can tell which
+ * attachments a `cid:` reference in the body actually points at (an unreferenced
+ * attachment is still sent, which is what "anonymous" MIME parts are for).
+ *
+ * @param envelopeXml the envelope as it will be sent
+ * @param attachments the attachments to package
+ * @param options the resolver plus the request's encode/disable flags
+ */
+export async function prepareSwaRequest(envelopeXml, attachments, options) {
+    if (options.disableMultiparts === true || attachments.length === 0) {
+        return { parts: [], used: false, referencedContentIds: [] };
+    }
+    const referenced = new Set(findCidReferences(envelopeXml).references.map((reference) => reference.cid));
+    const parts = [];
+    const referencedContentIds = [];
+    for (const attachment of attachments) {
+        const contentId = contentIdOf(attachment);
+        if (referenced.has(contentId) || referenced.has(attachment.id)) {
+            referencedContentIds.push(contentId);
+        }
+        parts.push({
+            contentId,
+            contentType: attachment.contentType,
+            bytes: await options.resolver(attachment),
+            transferEncoding: options.encodeAttachments ? 'base64' : 'binary',
+            ...(attachment.name.length > 0 ? { fileName: attachment.name } : {}),
+            ...(attachment.part !== undefined && attachment.part.length > 0 ? { partName: attachment.part } : {}),
+        });
+    }
+    return { parts, used: parts.length > 0, referencedContentIds };
+}
+/**
+ * Describes every non-root part of a parsed response as a {@link ResponseAttachment}.
+ *
+ * @param parsed the parsed `multipart/related` response
+ */
+export function collectResponseAttachments(parsed) {
+    return parsed.parts.map((part) => ({
+        contentId: part.contentId ?? '',
+        contentType: part.contentType,
+        size: part.bytes.length,
+        bytes: part.bytes,
+        ...(part.fileName !== undefined ? { name: part.fileName } : {}),
+        ...(part.transferEncoding !== undefined ? { transferEncoding: part.transferEncoding } : {}),
+    }));
+}

package/dist/soap/mime/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared types for the MIME layer: what goes into a `multipart/related` body,
+ * what comes back out of one, and how an {@link Attachment}'s bytes are obtained.
+ *
+ * The engine never reads an attachment from disk on its own: the send path is
+ * handed an {@link AttachmentResolver} so the desktop main process (which owns the
+ * project directory and its cache) decides where bytes come from. See
+ * `project/attachments-cache.ts` for the file-backed implementation.
+ */
+import type { Attachment } from '../../project/model.js';
+/** Resolves one attachment's bytes. Rejects when the attachment cannot be read. */
+export type AttachmentResolver = (attachment: Attachment) => Promise<Uint8Array>;
+/** Content transfer encodings this layer writes or understands. */
+export type TransferEncoding = 'binary' | 'base64' | '8bit' | '7bit' | 'quoted-printable';
+/**
+ * Transfer encodings {@link buildMultipartRelated} can actually produce: `quoted-printable`
+ * is understood on parse but this layer never writes it, so it is left out of the build-side
+ * type rather than silently passed through as if it were `binary`.
+ */
+export type BuildTransferEncoding = 'binary' | 'base64' | '8bit' | '7bit';
+/** One part to write into a `multipart/related` body. */
+export interface MultipartPart {
+    /** Content-ID without the angle brackets; they are added on the wire. */
+    readonly contentId: string;
+    readonly contentType: string;
+    readonly bytes: Uint8Array;
+    /** Defaults to `binary`; `base64` re-encodes the bytes and wraps at 76 columns. */
+    readonly transferEncoding?: BuildTransferEncoding;
+    /** File name for `Content-Disposition: attachment; filename="..."`. */
+    readonly fileName?: string;
+    /** WSDL `mime:part` name for `Content-Disposition: attachment; name="..."`. */
+    readonly partName?: string;
+}
+/** The root (SOAP envelope) part of a `multipart/related` body. */
+export interface MultipartRoot {
+    readonly contentType: string;
+    /** Content-ID without the angle brackets; defaults to `rootpart@wirebench`. */
+    readonly contentId?: string;
+    readonly bytes: Uint8Array;
+}
+/** One part read back out of a `multipart/related` body. */
+export interface MimePart {
+    /** Header names lower-cased, values unfolded and trimmed; duplicates keep the first. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Content-ID with the angle brackets stripped, when the part carried one. */
+    readonly contentId?: string;
+    /** `application/octet-stream` when the part declared no `Content-Type`. */
+    readonly contentType: string;
+    readonly transferEncoding?: TransferEncoding;
+    /** Part body, decoded when the transfer encoding was `base64`/`quoted-printable`. */
+    readonly bytes: Uint8Array;
+    /** Part body exactly as it appeared on the wire, still encoded. */
+    readonly raw: Uint8Array;
+    /** `filename` from `Content-Disposition`, or the last segment of `Content-Location`. */
+    readonly fileName?: string;
+    /** `name` from `Content-Disposition`. */
+    readonly partName?: string;
+}
+/** One attachment received on a response. */
+export interface ResponseAttachment {
+    /** Content-ID without the angle brackets; empty when the part carried none. */
+    readonly contentId: string;
+    readonly contentType: string;
+    readonly size: number;
+    readonly bytes: Uint8Array;
+    /** File name, when the part declared one. */
+    readonly name?: string;
+    readonly transferEncoding?: TransferEncoding;
+}

package/dist/soap/mime/types.js

@@ -0,0 +1,10 @@
+/**
+ * Shared types for the MIME layer: what goes into a `multipart/related` body,
+ * what comes back out of one, and how an {@link Attachment}'s bytes are obtained.
+ *
+ * The engine never reads an attachment from disk on its own: the send path is
+ * handed an {@link AttachmentResolver} so the desktop main process (which owns the
+ * project directory and its cache) decides where bytes come from. See
+ * `project/attachments-cache.ts` for the file-backed implementation.
+ */
+export {};

package/dist/soap/namespace-scope.d.ts

@@ -0,0 +1,32 @@
+/**
+ * One namespace/prefix table shared by every fragment of a single envelope.
+ *
+ * The sample generator declares namespaces on each fragment's own root; an
+ * envelope reads much better with every declaration hoisted onto
+ * `soapenv:Envelope` instead. Sharing one scope across all fragments is what
+ * makes that safe: a namespace gets the same prefix everywhere, so hoisting
+ * cannot change any name's meaning.
+ */
+/** Assigns one prefix per namespace URI and records which ones were actually used. */
+export declare class NamespaceScope {
+    private readonly byUri;
+    private readonly taken;
+    private readonly used;
+    /**
+     * @param seedUris namespaces to name up-front, so mnemonics are assigned in a
+     *   stable order rather than in whatever order fragments happen to use them
+     * @param overrides caller-supplied namespace URI → prefix, which always wins
+     */
+    constructor(seedUris: readonly string[], overrides?: Readonly<Record<string, string>>);
+    private assign;
+    /** Namespace URI → prefix for every namespace named so far; the generator's `prefixes` map. */
+    prefixes(): Record<string, string>;
+    /** The prefix for `uri`, allocating one if needed, and marks it as used. The empty namespace has none. */
+    use(uri: string): string;
+    /** Records the prefix → URI bindings a generated fragment declared on its own root. */
+    markUsed(namespaces: Readonly<Record<string, string>>): void;
+    /** Prefix → URI for every namespace actually used, in first-use order: the envelope's declarations. */
+    declarations(): Record<string, string>;
+    /** True when `prefix` is declared on the envelope bound to `uri`. */
+    declares(prefix: string, uri: string): boolean;
+}

package/dist/soap/namespace-scope.js

@@ -0,0 +1,85 @@
+/**
+ * One namespace/prefix table shared by every fragment of a single envelope.
+ *
+ * The sample generator declares namespaces on each fragment's own root; an
+ * envelope reads much better with every declaration hoisted onto
+ * `soapenv:Envelope` instead. Sharing one scope across all fragments is what
+ * makes that safe: a namespace gets the same prefix everywhere, so hoisting
+ * cannot change any name's meaning.
+ */
+import { NS } from '../xml/namespaces.js';
+import { prefixForNamespace, RESERVED_PREFIXES } from './prefixes.js';
+/** Prefixes the envelope pins regardless of what a mnemonic would suggest. */
+const PINNED = [
+    [NS.XSD, 'xsd'],
+    [NS.XSI, 'xsi'],
+    [NS.SOAP11_ENC, 'soapenc'],
+];
+/** Assigns one prefix per namespace URI and records which ones were actually used. */
+export class NamespaceScope {
+    byUri = new Map();
+    taken = new Set(RESERVED_PREFIXES);
+    used = new Map();
+    /**
+     * @param seedUris namespaces to name up-front, so mnemonics are assigned in a
+     *   stable order rather than in whatever order fragments happen to use them
+     * @param overrides caller-supplied namespace URI → prefix, which always wins
+     */
+    constructor(seedUris, overrides = {}) {
+        const overridden = new Set();
+        for (const [uri, prefix] of Object.entries(overrides)) {
+            this.byUri.set(uri, prefix);
+            this.taken.add(prefix);
+            overridden.add(prefix);
+        }
+        // Pinned prefixes are reserved *for* these namespaces, so `taken` (which
+        // holds every reserved prefix) must not block them — only an explicit
+        // caller override can.
+        for (const [uri, prefix] of PINNED) {
+            if (!this.byUri.has(uri) && !overridden.has(prefix)) {
+                this.assign(uri, prefix);
+            }
+        }
+        for (const uri of seedUris) {
+            if (uri !== '' && !this.byUri.has(uri)) {
+                this.assign(uri, prefixForNamespace(uri, this.taken));
+            }
+        }
+    }
+    assign(uri, prefix) {
+        this.byUri.set(uri, prefix);
+        this.taken.add(prefix);
+    }
+    /** Namespace URI → prefix for every namespace named so far; the generator's `prefixes` map. */
+    prefixes() {
+        return Object.fromEntries(this.byUri);
+    }
+    /** The prefix for `uri`, allocating one if needed, and marks it as used. The empty namespace has none. */
+    use(uri) {
+        if (uri === '') {
+            return '';
+        }
+        let prefix = this.byUri.get(uri);
+        if (prefix === undefined) {
+            prefix = prefixForNamespace(uri, this.taken);
+            this.assign(uri, prefix);
+        }
+        this.used.set(prefix, uri);
+        return prefix;
+    }
+    /** Records the prefix → URI bindings a generated fragment declared on its own root. */
+    markUsed(namespaces) {
+        for (const [prefix, uri] of Object.entries(namespaces)) {
+            this.assign(uri, prefix);
+            this.used.set(prefix, uri);
+        }
+    }
+    /** Prefix → URI for every namespace actually used, in first-use order: the envelope's declarations. */
+    declarations() {
+        return Object.fromEntries(this.used);
+    }
+    /** True when `prefix` is declared on the envelope bound to `uri`. */
+    declares(prefix, uri) {
+        return this.used.get(prefix) === uri;
+    }
+}

package/dist/soap/prefixes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Deterministic, readable namespace prefixes for generated SOAP envelopes.
+ *
+ * The established convention names a namespace after a short mnemonic taken from its URI
+ * (`http://tempuri.org/` → `tem`), which reads far better in a hand-edited
+ * request than `ns1`. This module reproduces that convention from the URI
+ * alone, without ever colliding with the prefixes the envelope reserves.
+ */
+/** Prefixes an envelope always owns; a mnemonic never takes one of these. */
+export declare const RESERVED_PREFIXES: readonly string[];
+/**
+ * Derives a short, readable prefix for `uri` that is not already in `taken`.
+ *
+ * The mnemonic is the first three letters of the URI's most meaningful token
+ * (`http://tempuri.org/` → `tem`, `http://www.dataaccess.com/webservicesserver/`
+ * → `web`, `urn:wb:common` → `com`). A mnemonic that is empty, or that would
+ * collide with a reserved or already-taken prefix, is disambiguated with a
+ * numeric suffix (`web`, `web1`, `web2`, …). `ns1`, `ns2`, … is the fallback
+ * when no mnemonic can be derived at all.
+ *
+ * Pure and deterministic: the same URI and `taken` set always yield the same
+ * prefix. The returned prefix is **not** added to `taken`; callers own that.
+ */
+export declare function prefixForNamespace(uri: string, taken: ReadonlySet<string>): string;

package/dist/soap/prefixes.js

@@ -0,0 +1,70 @@
+/**
+ * Deterministic, readable namespace prefixes for generated SOAP envelopes.
+ *
+ * The established convention names a namespace after a short mnemonic taken from its URI
+ * (`http://tempuri.org/` → `tem`), which reads far better in a hand-edited
+ * request than `ns1`. This module reproduces that convention from the URI
+ * alone, without ever colliding with the prefixes the envelope reserves.
+ */
+/** Prefixes an envelope always owns; a mnemonic never takes one of these. */
+export const RESERVED_PREFIXES = ['soapenv', 'soapenc', 'xsi', 'xsd', 'xs', 'xml', 'xmlns'];
+/** The mnemonic length: three letters, per the convention. */
+const MNEMONIC_LENGTH = 3;
+/**
+ * Picks the "most meaningful" token of a namespace URI: the last non-empty
+ * path segment of an http(s) URL, else the URL's host without a leading
+ * `www.`, else the last non-empty `:`-separated token of a URN.
+ */
+function meaningfulToken(uri) {
+    const trimmed = uri.trim();
+    const schemeSplit = trimmed.indexOf('://');
+    if (schemeSplit === -1) {
+        // A URN (or anything else without an authority): `urn:wb:common` → `common`.
+        const parts = trimmed.split(':').filter((part) => part.length > 0);
+        return parts.length === 0 ? '' : (parts[parts.length - 1] ?? '');
+    }
+    const rest = trimmed.slice(schemeSplit + 3);
+    const slash = rest.indexOf('/');
+    const host = slash === -1 ? rest : rest.slice(0, slash);
+    const path = slash === -1 ? '' : rest.slice(slash + 1);
+    const segments = path.split('/').filter((segment) => segment.length > 0);
+    if (segments.length > 0) {
+        return segments[segments.length - 1] ?? '';
+    }
+    const hostLabels = host.replace(/^www\./i, '').split('.');
+    return hostLabels[0] ?? '';
+}
+/** Reduces a token to letters and digits, keeping only its first dotted part. */
+function mnemonicOf(token) {
+    const firstPart = token.split('.')[0] ?? '';
+    const letters = firstPart.toLowerCase().replace(/[^a-z0-9]/g, '');
+    // A prefix is an NCName, so it can never start with a digit; a token with
+    // nothing but digits left yields no mnemonic at all.
+    return letters.replace(/^[0-9]+/, '').slice(0, MNEMONIC_LENGTH);
+}
+/**
+ * Derives a short, readable prefix for `uri` that is not already in `taken`.
+ *
+ * The mnemonic is the first three letters of the URI's most meaningful token
+ * (`http://tempuri.org/` → `tem`, `http://www.dataaccess.com/webservicesserver/`
+ * → `web`, `urn:wb:common` → `com`). A mnemonic that is empty, or that would
+ * collide with a reserved or already-taken prefix, is disambiguated with a
+ * numeric suffix (`web`, `web1`, `web2`, …). `ns1`, `ns2`, … is the fallback
+ * when no mnemonic can be derived at all.
+ *
+ * Pure and deterministic: the same URI and `taken` set always yield the same
+ * prefix. The returned prefix is **not** added to `taken`; callers own that.
+ */
+export function prefixForNamespace(uri, taken) {
+    const base = mnemonicOf(meaningfulToken(uri));
+    if (base.length > 0 && !taken.has(base) && !RESERVED_PREFIXES.includes(base)) {
+        return base;
+    }
+    const stem = base.length > 0 ? base : 'ns';
+    for (let counter = 1;; counter += 1) {
+        const candidate = `${stem}${counter}`;
+        if (!taken.has(candidate) && !RESERVED_PREFIXES.includes(candidate)) {
+            return candidate;
+        }
+    }
+}

package/dist/soap/recreate.d.ts

@@ -0,0 +1,28 @@
+/**
+ * "Recreate Request": merge a freshly generated envelope
+ * (the source of structure) with an existing edited envelope (the source of
+ * values), by matching elements on a root-relative path of
+ * `localName[siblingIndex]` steps rather than by DOM identity.
+ */
+/** Options for {@link recreateRequest}. */
+export interface RecreateOptions {
+    /** Copy matching leaf values (text and attributes) from the current envelope. */
+    readonly keepValues: boolean;
+    /** Keep the current `<soapenv:Header>` content verbatim instead of the generated one. */
+    readonly keepHeaders: boolean;
+}
+/** Result of {@link recreateRequest}. */
+export interface RecreateResult {
+    readonly xml: string;
+    /** Leaf values copied from the current envelope. */
+    readonly kept: number;
+    /** Elements present only in the generated structure. */
+    readonly added: number;
+    /** Elements present in the current envelope but absent from the generated one. */
+    readonly removed: number;
+}
+/**
+ * Merges `generatedXml` (structure) with `currentXml` (values), per the
+ * "Recreate Request" semantics.
+ */
+export declare function recreateRequest(currentXml: string, generatedXml: string, options: RecreateOptions): RecreateResult;