@scalar/workspace-store 0.66.0 → 0.67.1

package/dist/request-example/xml/get-xml-example.js

@@ -0,0 +1,352 @@
+import { unescapeJsonPointer } from '@scalar/helpers/json/unescape-json-pointer';
+import { isObject } from '@scalar/helpers/object/is-object';
+import { isDynamicRef, pushDynamicScope, resolveDynamicRef } from '../../helpers/dynamic-ref.js';
+import { getResolvedRef, mergeSiblingReferences } from '../../helpers/get-resolved-ref.js';
+import { EXAMPLE_EVALUATION, } from '../builder/helpers/example-evaluation.js';
+import { getExampleFromSchema, selectExampleComposition, } from '../builder/helpers/get-example-from-schema.js';
+import { matchXmlPropertyPattern } from './match-xml-property-pattern.js';
+import { writeXml } from './write-xml.js';
+const xsi = 'http://www.w3.org/2001/XMLSchema-instance';
+/** Keep failures visible even when a consumer only reads the XML string. */
+const reportXmlResult = (result, options) => {
+    for (const diagnostic of result.diagnostics) {
+        if (options.onDiagnostic) {
+            options.onDiagnostic(diagnostic);
+        }
+        else if (diagnostic.severity === 'error') {
+            console.warn('Unable to generate an XML example:', diagnostic);
+        }
+    }
+    return result;
+};
+/** Generate XML using the same value evaluator and selected branches as JSON examples. */
+export const getXmlExampleFromSchema = (schema, options = {}) => {
+    const capture = { stack: [] };
+    const value = getExampleFromSchema(schema, { ...options, [EXAMPLE_EVALUATION]: capture }, { schemaPath: options.schemaPath });
+    return reportXmlResult(buildXmlExample(value, schema, options, capture.root), options);
+};
+/** Serialize schema-ready example data. Serialized XML strings bypass this function at the media boundary. */
+export const serializeXmlExample = (value, schema, options = {}) => reportXmlResult(buildXmlExample(value, schema, options), options);
+const buildXmlExample = (value, input, options, evaluation) => {
+    const diagnostics = [];
+    const report = (severity, code, message, path) => {
+        diagnostics.push({ severity, code, message, path });
+    };
+    const componentNameFromRef = (reference, path) => {
+        const name = reference?.match(/\/schemas\/([^/]+)$/)?.[1];
+        if (name === undefined) {
+            return undefined;
+        }
+        try {
+            return unescapeJsonPointer(name);
+        }
+        catch {
+            report('error', 'invalid-reference', 'The component reference contains invalid URI escaping.', path);
+            return undefined;
+        }
+    };
+    const mergeXml = (base, next, path) => {
+        if (!base) {
+            return next;
+        }
+        if (!next) {
+            return base;
+        }
+        for (const key of ['name', 'namespace', 'prefix', 'nodeType', 'attribute', 'wrapped']) {
+            if (base[key] !== undefined && next[key] !== undefined && base[key] !== next[key]) {
+                report('error', 'composition-xml-conflict', `Composition members disagree on xml.${key}.`, path);
+            }
+        }
+        return { ...base, ...next };
+    };
+    const version32 = options.openapiVersion !== undefined && /^3\.[2-9](?:\.|$)/.test(options.openapiVersion);
+    const validateXmlMetadata = (xml, path) => {
+        if (xml.namespace !== undefined && !/^[A-Za-z][A-Za-z0-9+.-]*:/.test(xml.namespace)) {
+            report('error', 'relative-namespace', 'XML namespaces must be non-relative IRIs.', path);
+        }
+        if (xml.nodeType !== undefined && (xml.attribute !== undefined || xml.wrapped !== undefined)) {
+            report('error', 'conflicting-node-type', 'xml.nodeType cannot be combined with xml.attribute or xml.wrapped.', path);
+        }
+        if (xml.nodeType && options.openapiVersion && !/^3\.[2-9](?:\.|$)/.test(options.openapiVersion)) {
+            report('warning', 'xml-version', 'xml.nodeType requires OpenAPI 3.2.', path);
+        }
+    };
+    // Flatten composition contributions, keeping the evaluator's property provenance and branch choices.
+    const shape = (source, context, seen = new Set()) => {
+        if (!source || typeof source !== 'object' || seen.has(source) || seen.size > 50) {
+            return { schema: {}, scope: context.scope, evaluations: [] };
+        }
+        seen.add(source);
+        if (!context.evaluation && '$ref' in source && !('$ref-value' in source && source['$ref-value'] !== undefined)) {
+            report('error', 'unresolved-reference', 'Resolve schema references before generating XML.', context.path);
+        }
+        if (version32 && '$ref-value' in source && source['$ref-value']) {
+            return { schema: source, scope: context.scope, evaluations: context.evaluation?.children ?? [] };
+        }
+        let schema = getResolvedRef(source, mergeSiblingReferences);
+        if (isDynamicRef(schema)) {
+            const bound = resolveDynamicRef(schema.$dynamicRef, context.scope);
+            if (bound) {
+                return shape(bound, context, seen);
+            }
+        }
+        const scope = pushDynamicScope(context.scope, schema);
+        const evaluations = [...(context.evaluation?.children ?? [])];
+        const contributions = context.evaluation?.children.filter((child) => child.path.length === context.path.length ||
+            (child.name === undefined &&
+                child.path.length === context.path.length + 1 &&
+                /^\d+$/.test(child.path.at(-1) ?? ''))) ?? [];
+        const members = [];
+        const selectedSource = selectExampleComposition(schema, context.path, options, context.path.at(-1) === 'items');
+        // Captured evaluations can retain a reference name after resolution. Check the
+        // original selected members so unresolved references do not become null examples.
+        for (const member of selectedSource ? [selectedSource] : (schema.allOf ?? [])) {
+            if (member && '$ref' in member && !('$ref-value' in member && member['$ref-value'] !== undefined)) {
+                report('error', 'unresolved-reference', 'Resolve schema references before generating XML.', context.path);
+                return { schema, scope, evaluations };
+            }
+        }
+        if (version32 && selectedSource) {
+            members.push({ schema: selectedSource, path: context.path, evaluation: contributions[0] });
+        }
+        else if (contributions.length && !(version32 && schema.allOf)) {
+            members.push(...contributions.map((child) => ({ schema: child.schema, path: child.path, evaluation: child })));
+        }
+        else {
+            const selected = selectExampleComposition(schema, context.path, options, context.path.at(-1) === 'items');
+            if (selected) {
+                members.push({ schema: selected, path: context.path });
+            }
+            else if (schema.allOf) {
+                let choice = 0;
+                for (const member of schema.allOf) {
+                    const resolved = getResolvedRef(member, mergeSiblingReferences);
+                    const isChoice = resolved && (resolved.oneOf || resolved.anyOf);
+                    members.push({
+                        schema: member,
+                        path: isChoice ? [...context.path, String(choice++)] : context.path,
+                    });
+                }
+            }
+        }
+        for (const member of members) {
+            const contribution = shape(member.schema, { ...context, scope, path: member.path, evaluation: member.evaluation }, new Set(seen));
+            const properties = 'properties' in schema ? schema.properties : undefined;
+            const extra = 'properties' in contribution.schema ? contribution.schema.properties : undefined;
+            const xml = mergeXml(schema.xml, contribution.schema.xml, context.path);
+            const combinedProperties = { ...properties, ...extra };
+            for (const key of Object.keys(properties ?? {})) {
+                if (properties?.[key] && extra?.[key]) {
+                    combinedProperties[key] = { allOf: [properties[key], extra[key]] };
+                }
+            }
+            schema = {
+                ...schema,
+                ...contribution.schema,
+                ...(properties || extra ? { properties: combinedProperties } : {}),
+                xml,
+            };
+            evaluations.push(...contribution.evaluations);
+        }
+        return { schema, scope, evaluations };
+    };
+    const active = new Set();
+    let count = 0;
+    const map = (data, source, inheritedName, context, parentAttributes) => {
+        // Mapping receives original property/item schemas, before evaluator resolution can erase targets.
+        if (source && '$ref' in source && !('$ref-value' in source && source['$ref-value'] !== undefined)) {
+            report('error', 'unresolved-reference', 'Resolve schema references before generating XML.', context.path);
+            return [];
+        }
+        if (data === undefined) {
+            return [];
+        }
+        if (++count > 10000 || context.depth > 50) {
+            report('error', 'limit-exceeded', 'The XML example exceeds the node or depth limit.', context.path);
+            return [];
+        }
+        // In 3.2 a reference site and its target can describe different XML nodes.
+        // Resolving them into one object would erase an explicit wrapper or a transparent target.
+        const referenceTarget = source && '$ref-value' in source ? source['$ref-value'] : undefined;
+        const dynamicTarget = isDynamicRef(source) ? resolveDynamicRef(source.$dynamicRef, context.scope) : undefined;
+        const target = referenceTarget ?? dynamicTarget;
+        if (version32 && target && typeof target === 'object') {
+            const localXml = source.xml ?? {};
+            validateXmlMetadata(localXml, context.path);
+            const localKind = localXml.nodeType ?? (localXml.attribute ? 'attribute' : 'none');
+            const referenceName = '$ref' in source && typeof source.$ref === 'string'
+                ? componentNameFromRef(source.$ref, context.path)
+                : undefined;
+            const attributes = localKind === 'none' ? parentAttributes : [];
+            const children = map(data, target, referenceName ?? inheritedName, {
+                ...context,
+                depth: context.depth + 1,
+                scope: pushDynamicScope(context.scope, source),
+                evaluation: dynamicTarget ? context.evaluation?.children[0] : context.evaluation,
+            }, attributes);
+            if (localKind === 'none') {
+                return children;
+            }
+            if (localKind !== 'element') {
+                report('error', 'reference-node-type', 'A reference wrapper must be an element or a transparent node.', context.path);
+                return [];
+            }
+            return [
+                {
+                    type: 'element',
+                    name: localXml.name ?? inheritedName ?? 'root',
+                    namespace: localXml.namespace,
+                    prefix: localXml.prefix,
+                    attributes,
+                    children,
+                },
+            ];
+        }
+        const { schema, scope, evaluations } = shape(source, context);
+        if (version32 && '$ref-value' in schema && schema['$ref-value']) {
+            return map(data, schema, inheritedName, { ...context, scope, evaluation: undefined, depth: context.depth + 1 }, parentAttributes);
+        }
+        if (schema.deprecated ||
+            (options.mode === 'write' && schema.readOnly) ||
+            (options.mode === 'read' && schema.writeOnly)) {
+            return [];
+        }
+        const xml = schema.xml ?? {};
+        validateXmlMetadata(xml, context.path);
+        const kind = xml.nodeType ?? (xml.attribute ? 'attribute' : Array.isArray(data) && !xml.wrapped ? 'none' : 'element');
+        const selectedComponentName = context.depth === 0 && '$ref' in schema && typeof schema.$ref === 'string'
+            ? componentNameFromRef(schema.$ref, context.path)
+            : undefined;
+        const nodeName = kind === 'none' || kind === 'text' || kind === 'cdata'
+            ? inheritedName
+            : (xml.name ?? inheritedName ?? selectedComponentName);
+        const name = { name: nodeName ?? 'root', namespace: xml.namespace, prefix: xml.prefix };
+        if (kind === 'attribute') {
+            if (data === null) {
+                report('warning', 'null-attribute', 'A null XML attribute is omitted.', context.path);
+            }
+            else if (typeof data === 'object') {
+                report('error', 'attribute-value', 'An XML attribute requires a primitive value.', context.path);
+            }
+            else {
+                parentAttributes.push({ ...name, value: String(data) });
+            }
+            return [];
+        }
+        if (kind === 'text' || kind === 'cdata') {
+            if (data !== null && typeof data !== 'object') {
+                return [{ type: kind, value: String(data) }];
+            }
+            report('error', 'text-value', 'XML text and CDATA require a non-null primitive value.', context.path);
+            return [];
+        }
+        if (typeof data === 'object' && data !== null) {
+            if (active.has(data)) {
+                report('error', 'circular-value', 'The supplied XML example contains a circular value.', context.path);
+                return [];
+            }
+            active.add(data);
+        }
+        const attributes = kind === 'none' ? parentAttributes : [];
+        const children = [];
+        if (data === null) {
+            if (kind === 'none') {
+                report('error', 'null-fragment', 'A null value cannot be represented by an XML fragment.', context.path);
+            }
+            else {
+                attributes.push({ name: 'nil', prefix: 'xsi', namespace: xsi, value: 'true' });
+            }
+        }
+        else if (Array.isArray(data)) {
+            const prefixes = 'prefixItems' in schema ? schema.prefixItems : undefined;
+            const itemSchema = 'items' in schema && typeof schema.items === 'object' ? schema.items : {};
+            for (let index = 0; index < data.length; index++) {
+                if (count > 10000) {
+                    break;
+                }
+                const itemPath = prefixes?.[index]
+                    ? [...context.path, 'prefixItems', String(index)]
+                    : [...context.path, 'items'];
+                const itemEvaluations = evaluations.filter((child) => child.path.join('.') === itemPath.join('.'));
+                const itemEvaluation = itemEvaluations.length === data.length ? itemEvaluations[index] : itemEvaluations[0];
+                children.push(...map(data[index], (prefixes?.[index] ?? itemSchema), inheritedName ?? nodeName, {
+                    path: itemPath,
+                    scope: itemEvaluation?.dynamicScope ?? scope,
+                    evaluation: itemEvaluation,
+                    depth: context.depth + 1,
+                }, attributes));
+            }
+        }
+        else if (isObject(data)) {
+            const properties = 'properties' in schema ? schema.properties : undefined;
+            const evaluationByName = new Map(evaluations.map((child) => [child.name ?? child.path.at(-1), child]));
+            for (const [key, childValue] of Object.entries(data)) {
+                if (count > 10000) {
+                    break;
+                }
+                const childEvaluation = evaluationByName.get(key);
+                const additional = 'additionalProperties' in schema && typeof schema.additionalProperties === 'object'
+                    ? schema.additionalProperties
+                    : undefined;
+                const property = properties?.[key];
+                const patterns = 'patternProperties' in schema ? schema.patternProperties : undefined;
+                const matchingPatterns = Object.entries(patterns ?? {}).flatMap(([pattern, patternSchema]) => {
+                    const matches = matchXmlPropertyPattern(pattern, key);
+                    if (matches === undefined) {
+                        report('error', 'unsupported-pattern', 'Property patterns must use the bounded XML matching subset.', [
+                            ...context.path,
+                            key,
+                        ]);
+                    }
+                    return matches ? [patternSchema] : [];
+                });
+                const propertySchemas = [...(property ? [property] : []), ...matchingPatterns];
+                const childSchema = (propertySchemas.length > 1
+                    ? { allOf: propertySchemas }
+                    : (propertySchemas[0] ?? childEvaluation?.schema ?? additional ?? {}));
+                const resolved = getResolvedRef(childSchema, mergeSiblingReferences);
+                if (resolved?.deprecated ||
+                    (options.mode === 'write' && resolved?.readOnly) ||
+                    (options.mode === 'read' && resolved?.writeOnly)) {
+                    continue;
+                }
+                children.push(...map(childValue, childSchema, key, {
+                    path: [...context.path, key],
+                    scope: childEvaluation?.dynamicScope ?? scope,
+                    evaluation: childEvaluation,
+                    depth: context.depth + 1,
+                }, attributes));
+            }
+        }
+        else {
+            children.push({ type: 'text', value: String(data) });
+        }
+        if (typeof data === 'object' && data !== null) {
+            active.delete(data);
+        }
+        return kind === 'none' ? children : [{ type: 'element', ...name, attributes, children }];
+    };
+    const reference = input && '$ref' in input && typeof input.$ref === 'string' ? input.$ref : undefined;
+    const componentName = componentNameFromRef(reference, options.schemaPath ?? []);
+    const rootName = options.rootName ?? componentName;
+    const rootAttributes = [];
+    const nodes = map(value, input, rootName, { path: options.schemaPath ?? [], scope: [], evaluation, depth: 0 }, rootAttributes);
+    if (rootAttributes.length) {
+        report('error', 'root-attribute', 'An XML attribute requires a parent element.', []);
+    }
+    if (!rootName &&
+        nodes.length === 1 &&
+        nodes[0]?.type === 'element' &&
+        nodes[0].name === 'root' &&
+        !input.xml?.name) {
+        report('warning', 'root-name-fallback', 'No XML root name was supplied; using root.', []);
+    }
+    if (diagnostics.some((diagnostic) => diagnostic.severity === 'error')) {
+        return { xml: undefined, diagnostics };
+    }
+    if (value === undefined) {
+        return { xml: undefined, diagnostics };
+    }
+    const result = writeXml(nodes, options);
+    return { xml: result.xml, diagnostics: [...diagnostics, ...result.diagnostics] };
+};

package/dist/request-example/xml/match-xml-property-pattern.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Match the bounded, non-branching subset needed by common property prefixes and character classes.
+ * JavaScript regexes cannot be interrupted, so arbitrary schema expressions must not run on the UI
+ * thread or mock-server event loop. Unsupported expressions are reported rather than guessed.
+ * With groups, alternation, backreferences, and multiple quantifiers excluded, repetitions
+ * cannot interact to create exponential backtracking. The single quantified atom may
+ * still backtrack or restart matching, so both pattern and input lengths are bounded.
+ */
+export declare const matchXmlPropertyPattern: (pattern: string, name: string) => boolean | undefined;
+//# sourceMappingURL=match-xml-property-pattern.d.ts.map

package/dist/request-example/xml/match-xml-property-pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match-xml-property-pattern.d.ts","sourceRoot":"","sources":["../../../src/request-example/xml/match-xml-property-pattern.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,MAAM,EAAE,MAAM,MAAM,KAAG,OAAO,GAAG,SAsCjF,CAAA"}

package/dist/request-example/xml/match-xml-property-pattern.js

@@ -0,0 +1,48 @@
+/**
+ * Match the bounded, non-branching subset needed by common property prefixes and character classes.
+ * JavaScript regexes cannot be interrupted, so arbitrary schema expressions must not run on the UI
+ * thread or mock-server event loop. Unsupported expressions are reported rather than guessed.
+ * With groups, alternation, backreferences, and multiple quantifiers excluded, repetitions
+ * cannot interact to create exponential backtracking. The single quantified atom may
+ * still backtrack or restart matching, so both pattern and input lengths are bounded.
+ */
+export const matchXmlPropertyPattern = (pattern, name) => {
+    if (pattern.length > 256 || name.length > 256) {
+        return undefined;
+    }
+    let inClass = false;
+    let repetitions = 0;
+    for (let index = 0; index < pattern.length; index++) {
+        const character = pattern[index];
+        if (character === '\\') {
+            const escaped = pattern[++index];
+            if (!escaped || (!inClass && /[1-9k]/.test(escaped))) {
+                return undefined;
+            }
+            continue;
+        }
+        if (character === '[' && !inClass) {
+            inClass = true;
+            continue;
+        }
+        if (character === ']' && inClass) {
+            inClass = false;
+            continue;
+        }
+        if (inClass) {
+            continue;
+        }
+        if ('(){}|'.includes(character ?? '')) {
+            return undefined;
+        }
+        if ('*+?'.includes(character ?? '') && ++repetitions > 1) {
+            return undefined;
+        }
+    }
+    try {
+        return new RegExp(pattern).test(name);
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/request-example/xml/serialize-xml-part.d.ts

@@ -1,9 +1,8 @@
-import type { SchemaObject } from '../../schemas/v3.2/strict/openapi-document.js';
+import { type SchemaObject } from '../../schemas/v3.2/strict/openapi-document.js';
 /**
- * Serialize structured XML part data through a single request boundary.
- * TODO: Delegate to the schema-aware XML serializer when it is integrated.
- * Preserve the legacy root-name contract at this boundary.
- * Already serialized XML strings bypass this adapter in the multipart builder.
+ * Serialize structured XML part data through the shared schema-aware writer.
+ * A part must contain a complete XML document, so mapping errors reject serialization.
+ * Already serialized strings bypass this boundary in request builders.
  */
 export declare const serializeXmlPart: (value: Record<string, unknown>, schema?: SchemaObject) => string;
 //# sourceMappingURL=serialize-xml-part.d.ts.map

package/dist/request-example/xml/serialize-xml-part.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialize-xml-part.d.ts","sourceRoot":"","sources":["../../../src/request-example/xml/serialize-xml-part.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAA;AAE1E;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,YAAY,KAAG,MAGxF,CAAA"}
+{"version":3,"file":"serialize-xml-part.d.ts","sourceRoot":"","sources":["../../../src/request-example/xml/serialize-xml-part.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,YAAY,EAAsB,MAAM,wCAAwC,CAAA;AAI9F;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,YAAY,KAAG,MASxF,CAAA"}

package/dist/request-example/xml/serialize-xml-part.js

@@ -1,12 +1,18 @@
-import { json2xml } from '@scalar/helpers/file/json2xml';
-import { unpackProxyObject } from '../../helpers/unpack-proxy.js';
+import { coerceValue } from '../../schemas/typebox-coerce.js';
+import { SchemaObjectSchema } from '../../schemas/v3.2/strict/openapi-document.js';
+import { serializeXmlExample } from './get-xml-example.js';
 /**
- * Serialize structured XML part data through a single request boundary.
- * TODO: Delegate to the schema-aware XML serializer when it is integrated.
- * Preserve the legacy root-name contract at this boundary.
- * Already serialized XML strings bypass this adapter in the multipart builder.
+ * Serialize structured XML part data through the shared schema-aware writer.
+ * A part must contain a complete XML document, so mapping errors reject serialization.
+ * Already serialized strings bypass this boundary in request builders.
  */
 export const serializeXmlPart = (value, schema) => {
-    const rootName = schema?.xml?.name ?? 'root';
-    return json2xml({ [rootName]: unpackProxyObject(value) });
+    const result = serializeXmlExample(value, schema ?? coerceValue(SchemaObjectSchema, {}), {
+        mode: 'write',
+        rootName: 'root',
+    });
+    if (result.xml === undefined) {
+        throw new Error(`Unable to serialize XML part: ${result.diagnostics.map(({ code }) => code).join(', ')}`);
+    }
+    return result.xml;
 };

package/dist/request-example/xml/write-xml.d.ts

@@ -0,0 +1,9 @@
+import type { XmlExampleResult, XmlNode } from './xml-node.js';
+/** Formatting is restricted to element-only content, where it cannot change text values. */
+export type WriteXmlOptions = {
+    format?: boolean;
+    xmlDeclaration?: boolean;
+};
+/** Serialize an XML document, validating names, characters, and namespace bindings. */
+export declare const writeXml: (nodes: XmlNode[], options?: WriteXmlOptions) => XmlExampleResult;
+//# sourceMappingURL=write-xml.d.ts.map

package/dist/request-example/xml/write-xml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-xml.d.ts","sourceRoot":"","sources":["../../../src/request-example/xml/write-xml.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,gBAAgB,EAAW,OAAO,EAAE,MAAM,YAAY,CAAA;AAUnF,4FAA4F;AAC5F,MAAM,MAAM,eAAe,GAAG;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAAE,CAAA;AAE5E,uFAAuF;AACvF,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,EAAE,EAAE,UAAS,eAAoB,KAAG,gBA4H1E,CAAA"}

package/dist/request-example/xml/write-xml.js

@@ -0,0 +1,119 @@
+const XML_NAMESPACE = 'http://www.w3.org/XML/1998/namespace';
+const XMLNS_NAMESPACE = 'http://www.w3.org/2000/xmlns/';
+// XML 1.0 (fifth edition) NCName: a QName's prefix and local part cannot contain colons.
+const NAME_START = 'A-Z_a-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u02FF\\u0370-\\u037D\\u037F-\\u1FFF\\u200C-\\u200D\\u2070-\\u218F\\u2C00-\\u2FEF\\u3001-\\uD7FF\\uF900-\\uFDCF\\uFDF0-\\uFFFD\\u{10000}-\\u{EFFFF}';
+const namePattern = new RegExp(`^[${NAME_START}][${NAME_START}\\-.0-9\\u00B7\\u0300-\\u036F\\u203F-\\u2040]*$`, 'u');
+const invalidCharacter = /[^\u0009\u000A\u000D\u0020-\uD7FF\uE000-\uFFFD\u{10000}-\u{10FFFF}]/u;
+/** Serialize an XML document, validating names, characters, and namespace bindings. */
+export const writeXml = (nodes, options = {}) => {
+    const diagnostics = [];
+    const fail = (code, message, path) => {
+        diagnostics.push({ severity: 'error', code, message, path });
+    };
+    const escape = (value, attribute, path) => {
+        if (invalidCharacter.test(value)) {
+            fail('invalid-character', 'The value contains a character XML 1.0 cannot represent.', path);
+        }
+        const escaped = value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/\r/g, '&#13;');
+        // XML parsers normalize literal whitespace in attributes, so encode it explicitly.
+        return attribute ? escaped.replace(/"/g, '&quot;').replace(/\n/g, '&#10;').replace(/\t/g, '&#9;') : escaped;
+    };
+    let generatedPrefix = 0;
+    let count = 0;
+    const render = (node, inherited, depth, path, pretty) => {
+        if (++count > 10000 || depth > 100) {
+            fail('limit-exceeded', 'The XML example exceeds the node or depth limit.', path);
+            return '';
+        }
+        if (node.type !== 'element') {
+            if (node.type === 'text') {
+                return escape(node.value, false, path);
+            }
+            if (invalidCharacter.test(node.value)) {
+                fail('invalid-character', 'The CDATA contains a character XML 1.0 cannot represent.', path);
+            }
+            // Carriage returns must be outside CDATA to survive XML line-ending normalization.
+            return `<![CDATA[${node.value.replace(/]]>/g, ']]]]><![CDATA[>').replace(/\r/g, ']]>&#13;<![CDATA[')}]]>`;
+        }
+        const bindings = new Map(inherited);
+        const declarations = new Map();
+        const usedPrefixes = new Map();
+        const explicitPrefixes = new Set([node.prefix, ...node.attributes.map((attribute) => attribute.prefix)]);
+        const qualify = (input, attribute) => {
+            if (!namePattern.test(input.name) || (input.prefix !== undefined && !namePattern.test(input.prefix))) {
+                fail('invalid-name', `Invalid XML name: ${input.prefix ? `${input.prefix}:` : ''}${input.name}`, path);
+            }
+            let prefix = input.prefix ?? '';
+            const namespace = input.namespace ?? (prefix ? bindings.get(prefix) : attribute ? '' : bindings.get('')) ?? '';
+            if (prefix === 'xmlns' || namespace === XMLNS_NAMESPACE || (attribute && !prefix && input.name === 'xmlns')) {
+                fail('reserved-namespace', 'Namespace declarations must be expressed through XML namespace metadata.', path);
+            }
+            if (namespace === XML_NAMESPACE && !prefix) {
+                prefix = 'xml';
+            }
+            if ((prefix === 'xml') !== (namespace === XML_NAMESPACE)) {
+                fail('reserved-namespace', 'The xml prefix is reserved for the XML namespace.', path);
+            }
+            if (prefix && !namespace) {
+                fail('unbound-prefix', `The prefix ${prefix} has no namespace binding.`, path);
+            }
+            if (attribute && namespace && !prefix) {
+                prefix = [...bindings].find(([candidate, uri]) => candidate !== '' && uri === namespace)?.[0] ?? '';
+                if (!prefix) {
+                    do {
+                        prefix = `ns${++generatedPrefix}`;
+                    } while (bindings.has(prefix) || explicitPrefixes.has(prefix));
+                }
+            }
+            if (!attribute || prefix) {
+                if (usedPrefixes.has(prefix) && usedPrefixes.get(prefix) !== namespace) {
+                    fail('namespace-conflict', `The prefix ${prefix || '(default)'} is assigned incompatible namespaces on one element.`, path);
+                }
+                usedPrefixes.set(prefix, namespace);
+                if ((bindings.get(prefix) ?? '') !== namespace) {
+                    declarations.set(prefix, namespace);
+                    bindings.set(prefix, namespace);
+                }
+            }
+            return { name: prefix ? `${prefix}:${input.name}` : input.name, namespace };
+        };
+        const element = qualify(node, false);
+        const attributeNames = new Set();
+        const attributes = node.attributes
+            .map((attribute) => {
+            const qualified = qualify(attribute, true);
+            const key = `${qualified.namespace}\0${attribute.name}`;
+            if (attributeNames.has(key)) {
+                fail('duplicate-attribute', `Duplicate XML attribute: ${qualified.name}`, path);
+            }
+            attributeNames.add(key);
+            return ` ${qualified.name}="${escape(attribute.value, true, path)}"`;
+        })
+            .join('');
+        const namespaces = [...declarations]
+            .map(([prefix, uri]) => ` xmlns${prefix ? `:${prefix}` : ''}="${escape(uri, true, path)}"`)
+            .join('');
+        const opening = `<${element.name}${namespaces}${attributes}`;
+        if (node.children.length === 0) {
+            return `${opening}/>`;
+        }
+        const indentChildren = pretty && node.children.every((child) => child.type === 'element');
+        const children = node.children.map((child, index) => render(child, bindings, depth + 1, [...path, String(index)], pretty));
+        if (indentChildren) {
+            return `${opening}>\n${children.map((child) => `${'  '.repeat(depth + 1)}${child}`).join('\n')}\n${'  '.repeat(depth)}</${element.name}>`;
+        }
+        return `${opening}>${children.join('')}</${element.name}>`;
+    };
+    if (nodes.length !== 1 || nodes[0]?.type !== 'element') {
+        fail('invalid-root', 'An XML document must contain exactly one root element.', []);
+        return { xml: undefined, diagnostics };
+    }
+    const body = render(nodes[0], new Map([['xml', XML_NAMESPACE]]), 0, [], options.format !== false);
+    const declaration = options.xmlDeclaration === false
+        ? ''
+        : `<?xml version="1.0" encoding="UTF-8"?>${options.format === false ? '' : '\n'}`;
+    return {
+        xml: diagnostics.some((diagnostic) => diagnostic.severity === 'error') ? undefined : declaration + body,
+        diagnostics,
+    };
+};

package/dist/request-example/xml/xml-node.d.ts

@@ -0,0 +1,32 @@
+/** A qualified XML name. Namespace bindings are assigned by the writer. */
+export type XmlName = {
+    name: string;
+    namespace?: string;
+    prefix?: string;
+};
+/** Attributes are separate from children so element and attribute names cannot collide. */
+export type XmlAttribute = XmlName & {
+    value: string;
+};
+/** An ordered XML tree, including mixed content and repeated sibling names. */
+export type XmlNode = (XmlName & {
+    type: 'element';
+    attributes: XmlAttribute[];
+    children: XmlNode[];
+}) | {
+    type: 'text' | 'cdata';
+    value: string;
+};
+/** Actionable mapping errors and recoverable omissions, without console side effects. */
+export type XmlDiagnostic = {
+    severity: 'warning' | 'error';
+    code: string;
+    message: string;
+    path: string[];
+};
+/** An error never carries a partial or malformed XML document. */
+export type XmlExampleResult = {
+    xml: string | undefined;
+    diagnostics: XmlDiagnostic[];
+};
+//# sourceMappingURL=xml-node.d.ts.map

package/dist/request-example/xml/xml-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml-node.d.ts","sourceRoot":"","sources":["../../../src/request-example/xml/xml-node.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,2FAA2F;AAC3F,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtD,+EAA+E;AAC/E,MAAM,MAAM,OAAO,GACf,CAAC,OAAO,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,YAAY,EAAE,CAAC;IAAC,QAAQ,EAAE,OAAO,EAAE,CAAA;CAAE,CAAC,GAChF;IAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAE7C,yFAAyF;AACzF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAA;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,EAAE,CAAA;CACf,CAAA;AAED,kEAAkE;AAClE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IACvB,WAAW,EAAE,aAAa,EAAE,CAAA;CAC7B,CAAA"}

package/dist/request-example/xml/xml-node.js

@@ -0,0 +1 @@
+export {};