xml-model 1.3.3 → 2.0.0-beta.2

package/dist/xml/index.d.ts

@@ -1,80 +1,6 @@
-import { XMLElement, XMLRoot } from '../types';
-/**
- * Parses an XML string into an `XMLRoot` document tree.
- *
- * @param string - A well-formed XML string.
- * @returns The root of the parsed element tree.
- */
-export declare function parse(string: string): XMLRoot;
-/**
- * Serialises an `XMLRoot` or `XMLElement` back into an XML string.
- * Delegates to xml-js's `js2xml` function.
- */
-export declare const stringify: typeof import('xml-js').js2xml;
-/**
- * Extracts the text content from an element that has a single text child node.
- *
- * @param xml - An `XMLElement` expected to contain a single text node.
- * @returns The text value, or an empty string when there are no child elements.
- * @throws {TypeError} When the element has multiple or non-text children.
- */
-export declare function getContent(xml: XMLElement): string | number | boolean;
-/**
- * Creates a minimal element structure wrapping the given text content.
- * When no tag name is provided, returns a fragment with a text child.
- * When a tag name is provided, returns a full element with the given name and optional attributes.
- *
- * @param content - The text content to wrap (defaults to empty string).
- * @param tag - Optional element tag name.
- * @param attributes - Optional attributes; only valid when `tag` is provided.
- * @throws {TypeError} When `attributes` are provided without a `tag`.
- */
-export declare function fromContent(content: string): {
-    elements: [{
-        type: "text";
-        text: string;
-    }] | [];
-};
-export declare function fromContent(content: string, tag: string, attributes?: XMLElement["attributes"]): {
-    type: "element";
-    name: string;
-    attributes?: XMLElement["attributes"];
-    elements: [{
-        type: "text";
-        text: string;
-    }] | [];
-};
-/**
- * Appends a child element to `xml`, initialising the `elements` array if needed.
- *
- * @param xml - The parent element to modify.
- * @param element - The child element to append.
- */
-export declare function addElement(xml: XMLElement, element: XMLElement): void;
-/**
- * Sets an attribute on an element, initialising the `attributes` map if needed.
- *
- * @param xml - The element to modify.
- * @param attribute - The attribute name.
- * @param value - The attribute value.
- */
-export declare function setAttribute(xml: XMLElement, attribute: string, value: string): void;
-/**
- * Removes an attribute from an element. Does nothing if the element has no attributes.
- *
- * @param xml - The element to modify.
- * @param attribute - The attribute name to remove.
- */
-export declare function deleteAttribute(xml: XMLElement, attribute: string): void;
-/** Namespace object bundling all XML utility functions. */
-declare const XML: {
-    parse: typeof parse;
-    stringify: typeof import('xml-js').js2xml;
-    fromContent: typeof fromContent;
-    getContent: typeof getContent;
-    addElement: typeof addElement;
-    setAttribute: typeof setAttribute;
-    deleteAttribute: typeof deleteAttribute;
-};
-export default XML;
+export * from './xml-js';
+export { xml } from './schema-meta';
+export type { UserCodecOptions } from './codec';
+export { registerDefault, normalizeCodecOptions } from './codec';
+export { xmlModel, type XmlModelConstructor } from './model';
 //# sourceMappingURL=index.d.ts.map

package/dist/xml/index.js

@@ -1,57 +1,4 @@
-import XMLJS from "./xml-js.js";
-function parse(string) {
-  return XMLJS.parse(string);
-}
-const stringify = XMLJS.stringify;
-function getContent(xml) {
-  if (xml.elements?.length === 1) {
-    const content = xml.elements[0];
-    if (content.type === "text") return content.text;
-  }
-  if (!xml.elements) return "";
-  throw new TypeError(`can't get text from XMLElement: ${JSON.stringify(xml)}`);
-}
-function fromContent(content = "", tag, attributes) {
-  const el = {
-    elements: content ? [{ type: "text", text: String(content) }] : []
-  };
-  if (tag) el.name = tag;
-  if (attributes) {
-    if (!el.name) throw new TypeError("please provide a name if you want to provide attributes");
-    el.attributes = attributes;
-  }
-  if (el.name) el.type = "element";
-  return el;
-}
-function addElement(xml, element) {
-  if (!xml.elements) xml.elements = [];
-  xml.elements.push(element);
-}
-function setAttribute(xml, attribute, value) {
-  if (!xml.attributes) xml.attributes = {};
-  xml.attributes[attribute] = value;
-}
-function deleteAttribute(xml, attribute) {
-  if (!xml.attributes) return;
-  delete xml.attributes[attribute];
-}
-const XML = {
-  parse,
-  stringify,
-  fromContent,
-  getContent,
-  addElement,
-  setAttribute,
-  deleteAttribute
-};
-export {
-  addElement,
-  XML as default,
-  deleteAttribute,
-  fromContent,
-  getContent,
-  parse,
-  setAttribute,
-  stringify
-};
-//# sourceMappingURL=index.js.map
+import "./xml-js.js";
+import "./schema-meta.js";
+import "./codec.js";
+import "./model.js";

package/dist/xml/model.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { XMLElement, StringifyOptions, XMLRoot } from './xml-js';
+import { ModelConstructor } from '../model';
+import { UserCodecOptions } from './codec';
+/**
+ * Constructor type for xmlModel classes.
+ * Extends ModelConstructor with XML-specific helpers and a typed extend().
+ */
+export type XmlModelConstructor<S extends z.ZodObject<any> = z.ZodObject<any>, Inst extends z.infer<S> = z.infer<S>> = ModelConstructor<S, Inst> & {
+    /** Returns a new instance parsed from an XML string or XMLRoot. */
+    fromXML<T extends abstract new (...args: any[]) => any>(this: T, xmlInput: string | XMLRoot | XMLElement): InstanceType<T>;
+    /** Converts an instance to an XMLRoot document tree. */
+    toXML(instance: z.infer<S>): XMLRoot;
+    /** Converts an instance to an XML string. */
+    toXMLString(instance: z.infer<S>, options?: StringifyOptions): string;
+};
+export declare function xmlModel<S extends z.ZodObject<any>>(schema: S, options?: UserCodecOptions<S>): XmlModelConstructor<S>;
+//# sourceMappingURL=model.d.ts.map

package/dist/xml/model.js

@@ -0,0 +1,33 @@
+import { model } from "../model.js";
+import XML from "./xml-js.js";
+import { root } from "./schema-meta.js";
+import { XML_STATE, decode, encode } from "./codec.js";
+import "zod";
+//#region src/xml/model.ts
+function xmlModel(schema, options) {
+	const _schema = options ? root(schema, options) : schema;
+	return class extends model(_schema) {
+		static fromXML(input) {
+			if (typeof input === "string") input = XML.parse(input);
+			if (XML.isRoot(input)) input = XML.elementFromRoot(input);
+			const schema = this.dataSchema;
+			const inputData = decode(this.dataSchema, input);
+			const xmlState = inputData[XML_STATE];
+			const parsed = schema.parse(inputData);
+			parsed[XML_STATE] = xmlState;
+			return this.fromData(parsed);
+		}
+		static toXML(instance) {
+			const data = this.toData(instance);
+			return { elements: [encode(this.dataSchema, data)] };
+		}
+		static toXMLString(instance, options = {}) {
+			const xml = this.toXML(instance);
+			return XML.stringify(xml, options);
+		}
+	};
+}
+//#endregion
+export { xmlModel };
+
+//# sourceMappingURL=model.js.map

package/dist/xml/schema-meta.d.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import { UserCodecOptions, PropertyDecodingContext, PropertyEncodingContext } from './codec';
+import { XMLElement } from './xml-js';
+declare module "zod" {
+    interface GlobalMeta {
+        "@@xml-model"?: Record<string, unknown>;
+    }
+}
+type UserRootOptions<S extends z.ZodType = z.ZodType> = {
+    tagname?: string | UserCodecOptions<S>["tagname"];
+    decode?: UserCodecOptions<S>["decode"];
+    encode?: UserCodecOptions<S>["encode"];
+};
+type UserPropOptions = {
+    tagname?: string | UserCodecOptions["propertyTagname"];
+    inline?: boolean;
+    match?: RegExp | ((el: XMLElement) => boolean);
+    decode?: (ctx: PropertyDecodingContext) => Partial<Record<string, unknown>> | undefined;
+    encode?: (ctx: PropertyEncodingContext) => XMLElement | undefined;
+};
+export declare function root<S extends z.ZodType>(schema: S, options: UserRootOptions<S>): S;
+export declare function root(options: UserRootOptions): z.GlobalMeta;
+/**
+ * Annotate a field schema with XML child-element options.
+ *
+ * **`xml.prop()` with no options is a no-op.** The codec already iterates all
+ * ZodObject fields and defaults the tag name to `kebabCase(fieldKey)`. Wrap a
+ * schema in `xml.prop()` only when you need to customise at least one of:
+ * `tagname`, `inline`, `match`, `decode`, or `encode`.
+ *
+ * @example
+ * // ✅ Needed — custom tagname
+ * xml.prop(z.string(), { tagname: "pub-date" })
+ *
+ * // ✅ Needed — inline (children promoted to parent)
+ * xml.prop(z.array(ItemSchema), { inline: true })
+ *
+ * // ⚠️  Redundant — equivalent to plain z.string()
+ * xml.prop(z.string())
+ */
+export declare function prop<PS extends z.ZodType>(schema: PS, options: UserPropOptions): PS;
+export declare function prop(options: UserPropOptions): z.GlobalMeta;
+type AttributePropOptions = {
+    name?: string;
+};
+export declare function attr<PS extends z.ZodType>(schema: PS, options?: AttributePropOptions): PS;
+export declare function attr(options?: AttributePropOptions): z.GlobalMeta;
+/** Namespace object for XML metadata helpers. */
+export declare const xml: {
+    root: typeof root;
+    prop: typeof prop;
+    attr: typeof attr;
+};
+export declare function getOwnUserOptions<S extends z.ZodType>(schema: S): UserCodecOptions<S>;
+export declare function getUserOptions<S extends z.ZodType>(schema: S): UserCodecOptions<S>;
+export {};
+//# sourceMappingURL=schema-meta.d.ts.map

package/dist/xml/schema-meta.js

@@ -0,0 +1,88 @@
+import { getParentSchema, isZodType } from "../util/zod.js";
+import "zod";
+//#region src/xml/schema-meta.ts
+var metaKey = "@@xml-model";
+/** Merge `partial` into the schema's existing meta (shallow spread, no overwrite). */
+function setMeta(schema, partial) {
+	const existing = schema.meta()?.[metaKey] ?? {};
+	return schema.meta({ [metaKey]: {
+		...existing,
+		...partial
+	} });
+}
+function normalizePropOptions(options) {
+	if (!options) return {};
+	const partial = {};
+	if (options.tagname !== void 0) partial.propertyTagname = options.tagname;
+	if (options.inline !== void 0) partial.inlineProperty = options.inline;
+	if (options.match !== void 0) partial.propertyMatch = options.match;
+	if (options.decode !== void 0) {
+		const userDecode = options.decode;
+		partial.decodeAsProperty = function(ctx) {
+			const res = userDecode(ctx);
+			if (typeof res !== "undefined") Object.assign(ctx.result, res);
+		};
+	}
+	if (options.encode !== void 0) {
+		const userEncode = options.encode;
+		partial.encodeAsProperty = function(ctx) {
+			const { property } = ctx;
+			const res = userEncode(ctx);
+			if (typeof res === "undefined") return;
+			if (property.options.inlineProperty) ctx.result.elements.push(...res.elements);
+			else {
+				res.name = property.tagname;
+				ctx.result.elements.push(res);
+			}
+		};
+	}
+	return partial;
+}
+function root(optionsOrSchema, options) {
+	if (isZodType(optionsOrSchema)) return setMeta(optionsOrSchema, options ?? {});
+	else return { [metaKey]: optionsOrSchema };
+}
+function prop(optionsOrSchema, options) {
+	if (isZodType(optionsOrSchema)) return setMeta(optionsOrSchema, normalizePropOptions(options));
+	else return { [metaKey]: normalizePropOptions(optionsOrSchema) };
+}
+function attr(optionsOrSchema, options) {
+	const opts = isZodType(optionsOrSchema) ? options ?? {} : optionsOrSchema ?? {};
+	const partial = {
+		decodeAsProperty(ctx) {
+			const { name, options: propOptions } = ctx.property;
+			const attrName = opts.name ?? name;
+			const attrValue = ctx.xml?.attributes[attrName];
+			ctx.result[name] = propOptions.schema.parse(attrValue);
+		},
+		encodeAsProperty(ctx) {
+			const { value, name } = ctx.property;
+			const attrName = opts.name ?? name;
+			ctx.result.attributes[attrName] = value.toString();
+		}
+	};
+	if (isZodType(optionsOrSchema)) return setMeta(optionsOrSchema, partial);
+	else return { [metaKey]: partial };
+}
+/** Namespace object for XML metadata helpers. */
+var xml = {
+	root,
+	prop,
+	attr
+};
+function getOwnUserOptions(schema) {
+	return schema.meta()?.[metaKey] ?? {};
+}
+function getUserOptions(schema) {
+	const own = getOwnUserOptions(schema);
+	const parentSchema = getParentSchema(schema);
+	if (!parentSchema) return own;
+	return {
+		...getUserOptions(parentSchema),
+		...own
+	};
+}
+//#endregion
+export { getUserOptions, root, xml };
+
+//# sourceMappingURL=schema-meta.js.map

package/dist/xml/xml-js.d.ts

@@ -1,7 +1,284 @@
-import { xml2js as parse, js2xml as stringify } from 'xml-js';
-declare const _default: {
+import { z } from 'zod';
+export declare const ZXMLElementNode: z.ZodObject<{
+    type: z.ZodLiteral<"element">;
+    name: z.ZodString;
+    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    elements: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject</*elided*/ any, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"comment">;
+        comment: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strip>], "type">>>;
+}, z.core.$strip>;
+export type XMLElementNode = z.infer<typeof ZXMLElementNode>;
+export declare const ZXMLCommentNode: z.ZodObject<{
+    type: z.ZodLiteral<"comment">;
+    comment: z.ZodString;
+}, z.core.$strip>;
+export type XMLCommentNode = z.infer<typeof ZXMLCommentNode>;
+export declare const ZXMLTextNode: z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strip>;
+export type XMLTextNode = z.infer<typeof ZXMLTextNode>;
+export type XMLNode = XMLElementNode | XMLCommentNode | XMLTextNode;
+export declare const ZXMLNode: z.ZodDiscriminatedUnion<[
+    typeof ZXMLElementNode,
+    typeof ZXMLCommentNode,
+    typeof ZXMLTextNode
+], "type">;
+/**
+ * A single node in the xml-js element tree.
+ * Used as the internal representation for all XML parsing and serialization.
+ */
+export type XMLElement = XMLElementNode;
+export declare const ZXMLRoot: z.ZodObject<{
+    elements: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"element">;
+        name: z.ZodString;
+        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        elements: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject</*elided*/ any, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"comment">;
+            comment: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, z.core.$strip>], "type">>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"comment">;
+        comment: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strip>], "type">>;
+}, z.core.$strip>;
+/** The root of an xml-js document: a wrapper object whose `elements` array holds top-level nodes.
+ *
+ * **the `elements` array contains AT MOST one node with type `element`**
+ */
+export type XMLRoot = {
+    elements: XMLNode[];
+};
+type EmptyObj = Record<PropertyKey, never>;
+export type XMLVoid = EmptyObj;
+type IgnoreOptions = {
+    /** Whether to ignore the XML declaration (`<?xml?>`). @default false */
+    ignoreDeclaration?: boolean;
+    /** Whether to ignore processing instructions (`<?go there?>`). @default false */
+    ignoreInstruction?: boolean;
+    /** Whether to ignore element attributes. @default false */
+    ignoreAttributes?: boolean;
+    /** Whether to ignore comments (`<!-- -->`). @default false */
+    ignoreComment?: boolean;
+    /** Whether to ignore CData sections (`<![CDATA[ ]]>`). @default false */
+    ignoreCdata?: boolean;
+    /** Whether to ignore DOCTYPE declarations. @default false */
+    ignoreDoctype?: boolean;
+    /** Whether to ignore text content inside elements. @default false */
+    ignoreText?: boolean;
+};
+type ChangingKeyNames = {
+    /** Override the key name used for the declaration property. @default "declaration" */
+    declarationKey?: string;
+    /** Override the key name used for processing instructions. @default "instruction" */
+    instructionKey?: string;
+    /** Override the key name used for element attributes. @default "attributes" */
+    attributesKey?: string;
+    /** Override the key name used for text content. @default "text" */
+    textKey?: string;
+    /** Override the key name used for CData sections. @default "cdata" */
+    cdataKey?: string;
+    /** Override the key name used for DOCTYPE. @default "doctype" */
+    doctypeKey?: string;
+    /** Override the key name used for comments. @default "comment" */
+    commentKey?: string;
+    /** Override the key name used for the parent back-reference (when `addParent` is enabled). @default "parent" */
+    parentKey?: string;
+    /** Override the key name used for node type. @default "type" */
+    typeKey?: string;
+    /** Override the key name used for element name. @default "name" */
+    nameKey?: string;
+    /** Override the key name used for child elements array. @default "elements" */
+    elementsKey?: string;
+};
+/** Options for parsing XML into a JS object tree. */
+export type ParseOptions = IgnoreOptions & ChangingKeyNames & {
+    /** Whether to trim whitespace surrounding text content. @default false */
+    trim?: boolean;
+    /**
+     * Whether to replace `&`, `<`, `>` with their XML entities in text nodes.
+     * @deprecated See https://github.com/nashwaan/xml-js/issues/26
+     * @default false
+     */
+    sanitize?: boolean;
+    /** Whether to coerce numeric and boolean text values to their native JS types. @default false */
+    nativeType?: boolean;
+    /**
+     * Whether to add a `parent` property on each element pointing back to its parent.
+     * Useful for upward traversal but creates circular references.
+     * @default false
+     */
+    addParent?: boolean;
+    /**
+     * Whether to always wrap sub-elements in an array, even when there is only one.
+     * Pass an array of element names to restrict this behaviour to those names only.
+     * Only applicable in compact mode.
+     * @default false
+     */
+    alwaysArray?: boolean | Array<string>;
+    /**
+     * Whether to always emit an `elements` array even on empty elements.
+     * `<a></a>` becomes `{ elements: [{ type: "element", name: "a", elements: [] }] }`
+     * instead of `{ elements: [{ type: "element", name: "a" }] }`.
+     * Only applicable in non-compact mode.
+     * @default false
+     */
+    alwaysChildren?: boolean;
+    /**
+     * Whether to parse the contents of processing instructions as attributes.
+     * `<?go to="there"?>` becomes `{ go: { attributes: { to: "there" } } }`
+     * instead of `{ go: 'to="there"' }`.
+     * @default false
+     */
+    instructionHasAttributes?: boolean;
+    /** Whether to preserve whitespace-only text nodes that appear between elements. @default false */
+    captureSpacesBetweenElements?: boolean;
+    /** Custom processing hook called for each DOCTYPE value. */
+    doctypeFn?: (value: string, parentElement: object) => void;
+    /** Custom processing hook called for each processing instruction value. */
+    instructionFn?: (instructionValue: string, instructionName: string, parentElement: string) => void;
+    /** Custom processing hook called for each CData section. */
+    cdataFn?: (value: string, parentElement: object) => void;
+    /** Custom processing hook called for each comment. */
+    commentFn?: (value: string, parentElement: object) => void;
+    /** Custom processing hook called for each text node. */
+    textFn?: (value: string, parentElement: object) => void;
+    /** Custom processing hook called for each processing instruction name. */
+    instructionNameFn?: (instructionName: string, instructionValue: string, parentElement: string) => void;
+    /** Custom processing hook called for each element name. */
+    elementNameFn?: (value: string, parentElement: object) => void;
+    /** Custom processing hook called for each attribute name. */
+    attributeNameFn?: (attributeName: string, attributeValue: string, parentElement: string) => void;
+    /** Custom processing hook called for each attribute value. */
+    attributeValueFn?: (attributeValue: string, attributeName: string, parentElement: string) => void;
+    /** Custom processing hook called for the whole attributes object of an element. */
+    attributesFn?: (value: string, parentElement: string) => void;
+};
+declare function parse(xml: string, options?: ParseOptions): XMLRoot;
+/** Options for serializing a JS object tree back to XML. */
+export type StringifyOptions = IgnoreOptions & ChangingKeyNames & {
+    /** Number of spaces (or a string like `'\t'`) to use for indenting XML output. @default 0 */
+    spaces?: number | string;
+    /** Whether to indent text nodes onto their own line when `spaces` is set. @default false */
+    indentText?: boolean;
+    /** Whether to write CData sections on a new indented line. @default false */
+    indentCdata?: boolean;
+    /** Whether to print each attribute on its own indented line (when `spaces` is set). @default false */
+    indentAttributes?: boolean;
+    /** Whether to indent processing instructions onto their own line. @default false */
+    indentInstruction?: boolean;
+    /** Whether to emit empty elements as full tag pairs (`<a></a>`) instead of self-closing (`<a/>`). @default false */
+    fullTagEmptyElement?: boolean;
+    /** Whether to omit quotes around attribute values that are native JS types (numbers, booleans). @default false */
+    noQuotesForNativeAttributes?: boolean;
+    /** Custom processing hook called for each DOCTYPE value. */
+    doctypeFn?: (value: string, currentElementName: string, currentElementObj: object) => void;
+    /** Custom processing hook called for each processing instruction value. */
+    instructionFn?: (instructionValue: string, instructionName: string, currentElementName: string, currentElementObj: object) => void;
+    /** Custom processing hook called for each CData section. */
+    cdataFn?: (value: string, currentElementName: string, currentElementObj: object) => void;
+    /** Custom processing hook called for each comment. */
+    commentFn?: (value: string, currentElementName: string, currentElementObj: object) => void;
+    /** Custom processing hook called for each text node. */
+    textFn?: (value: string, currentElementName: string, currentElementObj: object) => void;
+    /** Custom processing hook called for each processing instruction name. */
+    instructionNameFn?: (instructionName: string, instructionValue: string, currentElementName: string, currentElementObj: object) => void;
+    /** Custom processing hook called for each element name. */
+    elementNameFn?: (value: string, currentElementName: string, currentElementObj: object) => void;
+    /** Custom processing hook called for each attribute name. */
+    attributeNameFn?: (attributeName: string, attributeValue: string, currentElementName: string, currentElementObj: object) => void;
+    /** Custom processing hook called for each attribute value. */
+    attributeValueFn?: (attributeValue: string, attributeName: string, currentElementName: string, currentElementObj: object) => void;
+    /** Custom processing hook called for the whole attributes object of an element. */
+    attributesFn?: (value: string, currentElementName: string, currentElementObj: object) => void;
+    /**
+     * Per-element override for `fullTagEmptyElement`.
+     * Return `true` to emit a full tag pair for the given element, `false` for self-closing.
+     */
+    fullTagEmptyElementFn?: (currentElementName: string, currentElementObj: object) => void;
+};
+declare function stringify(xml: XMLRoot, options?: StringifyOptions): string;
+declare function isRoot(xml: object): xml is XMLRoot;
+declare function elementFromRoot(root: XMLRoot): XMLElementNode | undefined;
+declare function isEmpty(xml: object): xml is XMLVoid;
+/**
+ * Extracts the text content from an element that has a single text child node.
+ *
+ * @param xml - An `XMLElement` expected to contain a single text node.
+ * @returns The text value, or an empty string when there are no child elements.
+ * @throws {TypeError} When the element has multiple or non-text children.
+ */
+declare function getContent(xml: XMLElement): string;
+/**
+ * Creates a minimal element structure wrapping the given text content.
+ * When no tag name is provided, returns a fragment with a text child.
+ * When a tag name is provided, returns a full element with the given name and optional attributes.
+ *
+ * @param content - The text content to wrap (defaults to empty string).
+ * @param tag - Optional element tag name.
+ * @param attributes - Optional attributes; only valid when `tag` is provided.
+ * @throws {TypeError} When `attributes` are provided without a `tag`.
+ */
+declare function fromContent(content: string): {
+    elements: [{
+        type: "text";
+        text: string;
+    }] | [];
+};
+declare function fromContent(content: string, tag: string, attributes?: XMLElement["attributes"]): {
+    type: "element";
+    name: string;
+    attributes?: XMLElement["attributes"];
+    elements: [{
+        type: "text";
+        text: string;
+    }] | [];
+};
+/**
+ * Appends a child element to `xml`, initialising the `elements` array if needed.
+ *
+ * @param xml - The parent element to modify.
+ * @param element - The child element to append.
+ */
+declare function addElement(xml: XMLElement, element: XMLElement): void;
+/**
+ * Sets an attribute on an element, initialising the `attributes` map if needed.
+ *
+ * @param xml - The element to modify.
+ * @param attribute - The attribute name.
+ * @param value - The attribute value.
+ */
+declare function setAttribute(xml: XMLElement, attribute: string, value: string): void;
+/**
+ * Removes an attribute from an element. Does nothing if the element has no attributes.
+ *
+ * @param xml - The element to modify.
+ * @param attribute - The attribute name to remove.
+ */
+declare function deleteAttribute(xml: XMLElement, attribute: string): void;
+/** Namespace object bundling all XML utility functions. */
+export declare const XML: {
     parse: typeof parse;
     stringify: typeof stringify;
+    isRoot: typeof isRoot;
+    elementFromRoot: typeof elementFromRoot;
+    isEmpty: typeof isEmpty;
+    fromContent: typeof fromContent;
+    getContent: typeof getContent;
+    addElement: typeof addElement;
+    setAttribute: typeof setAttribute;
+    deleteAttribute: typeof deleteAttribute;
 };
-export default _default;
+export default XML;
 //# sourceMappingURL=xml-js.d.ts.map