xml-model 2.0.0-beta.5 → 2.0.0-beta.7

package/dist/index.js

@@ -1,7 +1,7 @@
 import { DATA, isModel, model } from "./model.js";
 import XML, { ZXMLCommentNode, ZXMLElementNode, ZXMLNode, ZXMLRoot, ZXMLTextNode } from "./xml/xml-js.js";
 import { xml } from "./xml/schema-meta.js";
-import { normalizeCodecOptions, registerDefault } from "./xml/codec.js";
-import { XMLBase, XMLBaseWithSource, xmlModel } from "./xml/model.js";
+import { XMLCodecError, normalizeCodecOptions, registerDefault, xmlStateSchema } from "./xml/codec.js";
+import { xmlModel } from "./xml/model.js";
 import "./xml/index.js";
-export { DATA, XML, XMLBase, XMLBaseWithSource, ZXMLCommentNode, ZXMLElementNode, ZXMLNode, ZXMLRoot, ZXMLTextNode, isModel, model, normalizeCodecOptions, registerDefault, xml, xmlModel };
+export { DATA, XML, XMLCodecError, ZXMLCommentNode, ZXMLElementNode, ZXMLNode, ZXMLRoot, ZXMLTextNode, isModel, model, normalizeCodecOptions, registerDefault, xml, xmlModel, xmlStateSchema };

package/dist/xml/codec.d.ts

@@ -1,10 +1,15 @@
 import { z } from 'zod';
 import { XMLElement } from './xml-js';
+export declare class XMLCodecError extends Error {
+    readonly path: readonly (string | number)[];
+    readonly rawMessage: string;
+    constructor(rawMessage: string, path?: readonly (string | number)[], options?: ErrorOptions);
+}
 export declare function assertSingleElement(xml: XMLElement[]): asserts xml is [XMLElement];
 export declare function assertSingleRoot(xml: XMLElement[]): asserts xml is [XMLElement & {
     elements: XMLElement[];
 }];
-type PropKey<S extends z.ZodObject> = keyof z.input<S> & keyof z.output<S> & string;
+type PropKey<S extends z.ZodObject> = keyof z.input<S> & string;
 export interface CodecOptions<S extends z.ZodType> {
     schema: S;
     tagname(ctx: RootEncodingContext<S>): string;
@@ -46,7 +51,7 @@ export interface RootDecodingContext<S extends z.ZodType> {
 }
 export interface RootEncodingContext<S extends z.ZodType> {
     options: CodecOptions<S>;
-    data: z.output<S>;
+    data: z.input<S>;
 }
 export interface PropertyDecodingContext<S extends z.ZodObject = z.ZodObject, K extends PropKey<S> = PropKey<S>> extends RootDecodingContext<S> {
     property: {
@@ -63,7 +68,7 @@ export interface PropertyEncodingContext<S extends z.ZodObject = z.ZodObject, K
         name: K;
         options: CodecOptions<z.ZodType>;
         tagname: string;
-        value: z.output<S>[K];
+        value: z.input<S>[K];
     };
     result: XMLElement;
 }
@@ -75,29 +80,27 @@ export interface XMLState {
     /** Present when xmlStateSchema({ source: true }) is used: the original XMLElement. */
     source?: XMLElement;
 }
-/**
- * String key used to store XML round-trip state on decoded data objects.
- * Using a string (rather than a Symbol) allows Zod's schema.parse() to
- * preserve it naturally when the key is included in the schema via xmlStateSchema().
- */
-export declare const XML_STATE_KEY: "__xml_state";
 /**
  * Schema for the XML round-trip state field.
  *
- * Include in your base model schema under `XML_STATE_KEY` to preserve element ordering
- * and unknown elements through Zod's `schema.parse()` for nested model instances.
+ * Add a field with this schema to any `xmlModel` ZodObject to opt in to:
+ * - **Element ordering** — elements are re-emitted in source order, not schema order.
+ * - **Unknown elements** — unrecognised elements are passed through verbatim on re-encode.
  *
- * Pass `{ source: true }` to also record the original `XMLElement` on each instance.
+ * The field can be named anything; the codec detects it automatically.
+ * Pass `{ source: true }` to additionally store the original `XMLElement` on the instance.
  *
  * @example
- * class XMLBase extends xmlModel(z.object({
- *   [XML_STATE_KEY]: xmlStateSchema(),
- * }), { tagname: "base" }) {}
+ * class Device extends xmlModel(z.object({
+ *   _xmlState: xmlStateSchema(),
+ *   name: z.string(),
+ * }), { tagname: "device" }) {}
  *
  * // With source recording:
- * class XMLBase extends xmlModel(z.object({
- *   [XML_STATE_KEY]: xmlStateSchema({ source: true }),
- * }), { tagname: "base" }) {}
+ * class Device extends xmlModel(z.object({
+ *   _xmlState: xmlStateSchema({ source: true }),
+ *   name: z.string(),
+ * }), { tagname: "device" }) {}
  */
 export declare function xmlStateSchema(): z.ZodOptional<z.ZodCustom<XMLState>>;
 export declare function xmlStateSchema(options: {
@@ -106,7 +109,7 @@ export declare function xmlStateSchema(options: {
     source: XMLElement;
 }>>;
 export declare function decode<S extends z.ZodType>(schema: S, xml: XMLElement): z.input<S>;
-export declare function encode<S extends z.ZodType>(schema: S, data: z.output<S>): XMLElement;
+export declare function encode<S extends z.ZodType>(schema: S, data: z.input<S>): XMLElement;
 type DefaultResolver<S extends z.ZodType = z.ZodType> = (schema: S) => CodecOptions<S> | void;
 export declare function registerDefault(resolve: DefaultResolver): void;
 export declare function xmlCodec<S extends z.ZodType>(schema: S): z.ZodCodec<z.ZodString, S>;

package/dist/xml/codec.js

@@ -1,9 +1,24 @@
 import XML from "./xml-js.js";
 import { isZodType } from "../util/zod.js";
-import { getUserOptions, prop } from "./schema-meta.js";
 import { kebabCase } from "../util/kebab-case.js";
+import { getUserOptions, prop } from "./schema-meta.js";
 import { z } from "zod";
 //#region src/xml/codec.ts
+var XMLCodecError = class extends Error {
+	path;
+	rawMessage;
+	constructor(rawMessage, path = [], options) {
+		super(path.length ? `[${path.join(".")}] ${rawMessage}` : rawMessage, options);
+		this.name = "XMLCodecError";
+		this.path = path;
+		this.rawMessage = rawMessage;
+	}
+};
+function rethrow(e, segment) {
+	const cause = e instanceof XMLCodecError ? e.cause : e;
+	const path = e instanceof XMLCodecError ? [segment, ...e.path] : [segment];
+	throw new XMLCodecError(e instanceof XMLCodecError ? e.rawMessage : e instanceof Error ? e.message : String(e), path, { cause });
+}
 function assertSingleElement(xml) {
 	if (xml.length !== 1) throw new Error(`Expected single XML element, got ${xml.length}`);
 }
@@ -68,19 +83,17 @@ function resolveCodecOptions(schema) {
 	cache.set(schema, options);
 	return options;
 }
-/**
-* String key used to store XML round-trip state on decoded data objects.
-* Using a string (rather than a Symbol) allows Zod's schema.parse() to
-* preserve it naturally when the key is included in the schema via xmlStateSchema().
-*/
-var XML_STATE_KEY = "__xml_state";
+/** Tracks all schemas created by `xmlStateSchema()` for fast detection at setup time. */
+var xmlStateSchemas = /* @__PURE__ */ new WeakSet();
 function xmlStateSchema(options) {
-	return prop(z.custom().optional(), {
+	const result = prop(z.custom().optional(), {
 		decode: options?.source ? (ctx, _next) => {
-			(ctx.result[XML_STATE_KEY] ??= {}).source = ctx.xml;
+			(ctx.result[ctx.property.name] ??= {}).source = ctx.xml;
 		} : () => {},
 		encode: () => {}
 	});
+	xmlStateSchemas.add(result);
+	return result;
 }
 function resolvePropertiesCodecOptions(schema) {
 	const shape = schema.def.shape;
@@ -88,6 +101,16 @@ function resolvePropertiesCodecOptions(schema) {
 	for (const [prop, fieldSchema] of Object.entries(shape)) options[prop] = resolveCodecOptions(fieldSchema);
 	return options;
 }
+/**
+* Scans a ZodObject shape for a field created with `xmlStateSchema()`.
+* Returns the field key if found, `undefined` if absent.
+* Throws if more than one such field is present (not supported).
+*/
+function findXmlStateKey(shape) {
+	const keys = Object.keys(shape).filter((k) => xmlStateSchemas.has(shape[k]));
+	if (keys.length > 1) throw new Error(`Only one xmlStateSchema field is allowed per object schema, found: ${keys.join(", ")}`);
+	return keys[0];
+}
 function decode(schema, xml) {
 	const options = resolveCodecOptions(schema);
 	return options.decode({
@@ -190,30 +213,23 @@ registerDefault((schema) => {
 	}
 	if (schema instanceof z.ZodCodec) {
 		const inSchema = schema.def.in;
-		const outSchema = schema.def.out;
 		if (!isZodType(inSchema)) throw new Error(`Expected schema.def.in to be a ZodType, got ${inSchema}`);
-		if (!isZodType(outSchema)) throw new Error(`Expected schema.def.out to be a ZodType, got ${outSchema}`);
 		const inputCodecOptions = resolveCodecOptions(inSchema);
 		return normalizeCodecOptions(schema, {
 			decode({ xml }) {
-				const input = inputCodecOptions.decode({
+				return inputCodecOptions.decode({
 					options: inputCodecOptions,
 					xml
 				});
-				return schema.def.transform(input, {
-					value: input,
-					issues: []
-				});
 			},
 			encode(ctx) {
-				const data = outSchema.encode(ctx.data);
 				const innerOpts = ctx.options.tagname !== inputCodecOptions.tagname ? {
 					...inputCodecOptions,
 					tagname: ctx.options.tagname
 				} : inputCodecOptions;
 				return innerOpts.encode({
 					options: innerOpts,
-					data
+					data: ctx.data
 				});
 			}
 		});
@@ -260,10 +276,12 @@ registerDefault((schema) => {
 registerDefault((schema) => {
 	if (schema instanceof z.ZodObject) {
 		const options = resolvePropertiesCodecOptions(schema);
+		const stateKey = findXmlStateKey(schema.def.shape);
 		return normalizeCodecOptions(schema, {
 			decode(ctx) {
-				const sequence = [];
-				const result = { [XML_STATE_KEY]: { sequence } };
+				const sequence = stateKey ? [] : void 0;
+				const result = {};
+				if (stateKey) result[stateKey] = { sequence };
 				const propContexts = Object.fromEntries(Object.entries(options).map(([name, propOpts]) => {
 					return [name, {
 						name,
@@ -287,19 +305,19 @@ registerDefault((schema) => {
 						}
 					}
 					if (!matches.length) {
-						sequence.push(el);
+						if (sequence) sequence.push(el);
 						continue;
 					} else if (matches.length === 1) {
 						const propName = matches[0];
 						if (seenProperties.has(propName)) {
 							if (!options[propName].inlineProperty) throw new Error("Matching multiple elements for a single property is only supported when `inlineProperty` is true");
 						} else {
-							sequence.push(propName);
+							if (sequence) sequence.push(propName);
 							seenProperties.add(propName);
 						}
 					} else throw new Error(`Same element was matched by multiple properties: ${matches.join(", ")}`);
 				}
-				for (const propName in options) if (!seenProperties.has(propName)) sequence.push(propName);
+				for (const propName in options) if (!seenProperties.has(propName) && sequence) sequence.push(propName);
 				for (const prop in options) {
 					const o = options[prop];
 					const propCtx = propContexts[prop];
@@ -311,12 +329,16 @@ registerDefault((schema) => {
 							propCtx.xml = matches[0];
 						}
 					}
-					o.decodeAsProperty({
-						options: ctx.options,
-						xml: ctx.xml,
-						property: propCtx,
-						result
-					});
+					try {
+						o.decodeAsProperty({
+							options: ctx.options,
+							xml: ctx.xml,
+							property: propCtx,
+							result
+						});
+					} catch (e) {
+						rethrow(e, prop);
+					}
 				}
 				return result;
 			},
@@ -328,31 +350,156 @@ registerDefault((schema) => {
 					attributes: {},
 					elements: []
 				};
-				const sequence = data["__xml_state"]?.sequence ?? Object.keys(options);
-				for (const item of sequence) if (typeof item === "string") {
+				const iterOrder = (stateKey ? data[stateKey]?.sequence : void 0) ?? Object.keys(options);
+				for (const item of iterOrder) if (typeof item === "string") {
 					const o = options[item];
 					if (!o) throw new Error(`Failed to resolve property options for sequence item ${item}`);
-					o.encodeAsProperty({
-						options: ctx.options,
-						data,
-						property: {
-							name: item,
-							options: o,
-							tagname: o.propertyTagname({
+					try {
+						o.encodeAsProperty({
+							options: ctx.options,
+							data,
+							property: {
 								name: item,
-								options: o
-							}),
-							value: data[item]
-						},
-						result
-					});
+								options: o,
+								tagname: o.propertyTagname({
+									name: item,
+									options: o
+								}),
+								value: data[item]
+							},
+							result
+						});
+					} catch (e) {
+						rethrow(e, item);
+					}
 				} else result.elements.push(item);
 				return result;
 			}
 		});
 	}
 });
+/**
+* Recursively extracts the set of literal values from a schema,
+* unwrapping ZodCodec, ZodOptional, etc. as needed.
+*/
+function getLiteralValues(schema) {
+	if (schema instanceof z.ZodLiteral) return schema.def.values;
+	if (schema instanceof z.ZodCodec) return getLiteralValues(schema.def.in);
+	if (schema instanceof z.ZodOptional) return getLiteralValues(schema.def.innerType);
+	return [];
+}
+function formatReason(errors) {
+	return errors.map((e) => e instanceof Error ? e.message : String(e)).join("; ");
+}
+/**
+* Reads the discriminator field value from an XML element without a full decode.
+* Handles both XML-attribute discriminators (xml.attr) and child-element discriminators.
+*/
+function peekDiscriminatorValue(discriminator, propertyOptions, ctx) {
+	const errors = [];
+	for (const options of propertyOptions) try {
+		const propCtx = {
+			name: discriminator,
+			options,
+			tagname: options.propertyTagname({
+				name: discriminator,
+				options
+			}),
+			xml: { elements: [] }
+		};
+		ctx.xml.elements.forEach((el) => {
+			if (el.type !== "element") return;
+			if (options.propertyMatch(el, propCtx)) propCtx.xml.elements.push(el);
+		});
+		if (propCtx.xml.elements.length === 0) propCtx.xml = null;
+		else if (propCtx.xml.elements.length !== 1) throw new Error("Matched multiple elements for a single property");
+		else propCtx.xml = propCtx.xml.elements[0];
+		const result = {};
+		options.decodeAsProperty({
+			options: ctx.options,
+			xml: ctx.xml,
+			property: propCtx,
+			result
+		});
+		return result[discriminator];
+	} catch (e) {
+		errors.push(e);
+	}
+	throw new XMLCodecError(`union: no option matched for decoding (${formatReason(errors)})`);
+}
+registerDefault((schema) => {
+	if (schema instanceof z.ZodDiscriminatedUnion) {
+		const discriminator = schema.def.discriminator;
+		const options = schema.def.options;
+		const optionCodecs = /* @__PURE__ */ new Map();
+		const discriminatorSchemas = [];
+		for (const option of options) {
+			const inSchema = option instanceof z.ZodCodec ? option.def.in : option;
+			if (!(inSchema instanceof z.ZodObject)) throw new TypeError(`Discriminated union members are supposed to be objects, got ${inSchema.type}`);
+			const discriminatorSchema = inSchema.shape[discriminator];
+			if (!discriminatorSchema) throw new TypeError(`Missing discriminator field "${discriminator}" in schema`);
+			discriminatorSchemas.push(discriminatorSchema);
+			const optCodec = resolveCodecOptions(inSchema);
+			for (const val of getLiteralValues(discriminatorSchema)) optionCodecs.set(val, optCodec);
+		}
+		const discriminatorOptions = discriminatorSchemas.map(resolveCodecOptions);
+		return normalizeCodecOptions(schema, {
+			decode(ctx) {
+				const { xml } = ctx;
+				if (!xml) throw new XMLCodecError(`discriminated union requires an XML element`);
+				const discValue = peekDiscriminatorValue(discriminator, discriminatorOptions, ctx);
+				const matched = optionCodecs.get(discValue);
+				if (!matched) throw new XMLCodecError(`no variant matched discriminator "${discriminator}" = "${String(discValue)}"`);
+				return matched.decode({
+					options: matched,
+					xml
+				});
+			},
+			encode(ctx) {
+				const discValue = ctx.data[discriminator];
+				const matched = optionCodecs.get(discValue);
+				if (!matched) throw new XMLCodecError(`no variant matched discriminator "${discriminator}" = "${String(discValue)}"`);
+				return matched.encode({
+					options: matched,
+					data: ctx.data
+				});
+			}
+		});
+	}
+	if (schema instanceof z.ZodUnion) {
+		const codecOptions = schema.def.options.map((option) => {
+			const inSchema = option instanceof z.ZodCodec ? option.def.in : option;
+			return resolveCodecOptions(inSchema instanceof z.ZodObject ? inSchema : option);
+		});
+		return normalizeCodecOptions(schema, {
+			decode(ctx) {
+				const errors = [];
+				for (const options of codecOptions) try {
+					return options.decode({
+						options,
+						xml: ctx.xml
+					});
+				} catch (e) {
+					errors.push(e);
+				}
+				throw new XMLCodecError(`union: no option matched for decoding (${formatReason(errors)})`);
+			},
+			encode(ctx) {
+				const errors = [];
+				for (const options of codecOptions) try {
+					return options.encode({
+						options,
+						data: ctx.data
+					});
+				} catch (e) {
+					errors.push(e);
+				}
+				throw new XMLCodecError(`union: no option matched for encoding (${formatReason(errors)})`);
+			}
+		});
+	}
+});
 //#endregion
-export { XML_STATE_KEY, decode, encode, normalizeCodecOptions, registerDefault, xmlStateSchema };
+export { XMLCodecError, decode, encode, normalizeCodecOptions, registerDefault, xmlStateSchema };
 
 //# sourceMappingURL=codec.js.map

package/dist/xml/examples.d.ts

@@ -1,41 +1,125 @@
 import { z } from 'zod';
-declare const Engine_base: import('./model').XmlModelConstructor<z.ZodObject<{
+/**
+ * Recommended base class for all xmlModel classes.
+ *
+ * Extending `XMLBase` instead of calling `xmlModel()` directly opts every subclass
+ * into round-trip preservation at no extra cost:
+ * - **Element ordering** — elements are re-emitted in source document order, not schema order.
+ * - **Unknown elements** — elements with no matching schema field are passed through verbatim.
+ *
+ * This matters whenever you read XML produced by a third party, modify a subset of fields,
+ * and write it back — plain `xmlModel()` would silently reorder elements and drop extensions.
+ *
+ * The `_xmlState` field holds the tracking state; it is intentionally excluded from XML output.
+ *
+ * @example
+ * class Device extends XMLBase.extend(
+ *   { name: z.string() },
+ *   xml.root({ tagname: "device" }),
+ * ) {}
+ */
+export declare const XMLBase: import('./model').XmlModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+}, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+}>;
+/**
+ * Like {@link XMLBase}, but also records the original `XMLElement` as `._xmlState.source`
+ * on each instance.
+ *
+ * @example
+ * const device = Device.fromXML(`<device>…</device>`);
+ * device._xmlState?.source; // XMLElement
+ */
+export declare const XMLBaseWithSource: import('./model').XmlModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState & {
+        source: import('./xml-js').XMLElement;
+    }, unknown>>;
+}, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState & {
+        source: import('./xml-js').XMLElement;
+    };
+}>;
+declare const Event_base: Omit<import('./model').XmlModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+}, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+}>, keyof import('..').ModelConstructor<S, Inst>> & import('..').ModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+    title: z.ZodString;
+    publishedAt: z.ZodCodec<z.ZodString, z.ZodDate>;
+}, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+} & {
+    title: string;
+    _xmlState?: import('./codec').XMLState;
+    publishedAt?: Date;
+}>;
+/**
+ * An event with a typed `Date` field stored as an ISO 8601 string in XML.
+ * Extends `XMLBase` so element order and unknown elements are preserved across round-trips.
+ * Demonstrates using `z.codec` to transform a raw XML string into a native JS type.
+ */
+export declare class Event extends Event_base {
+}
+declare const Engine_base: Omit<import('./model').XmlModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+}, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+}>, keyof import('..').ModelConstructor<S, Inst>> & import('..').ModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
     type: z.ZodString;
     horsepower: z.ZodNumber;
 }, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+} & {
     type: string;
     horsepower: number;
+    _xmlState?: import('./codec').XMLState;
 }>;
 /**
- * A car engine. Demonstrates a basic nested class with one XML attribute
- * (`type`) and one child element (`horsepower`).
+ * A car engine. Extends `XMLBase` so unknown vendor elements inside `<engine>`
+ * (e.g. manufacturer extensions) survive a read-modify-write cycle.
+ * Demonstrates a basic nested class with one XML attribute (`type`) and one
+ * child element (`horsepower`).
  */
 export declare class Engine extends Engine_base {
 }
-declare const Vehicle_base: import('./model').XmlModelConstructor<z.ZodObject<{
+declare const Vehicle_base: Omit<import('./model').XmlModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+}, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+}>, keyof import('..').ModelConstructor<S, Inst>> & import('..').ModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
     vin: z.ZodString;
     make: z.ZodString;
     year: z.ZodNumber;
 }, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+} & {
     vin: string;
     make: string;
     year: number;
+    _xmlState?: import('./codec').XMLState;
 }>;
 /**
- * Base vehicle class. Demonstrates `xml.attr()` for identifier fields and
- * `xml.prop()` for child-element fields. Custom methods on the class are
- * available on every parsed instance.
+ * Base vehicle class. Extends `XMLBase` so all vehicle subclasses inherit
+ * round-trip preservation — element order and unknown extensions are kept
+ * intact without any per-subclass ceremony.
+ * Demonstrates `xml.attr()` for identifier fields and custom instance methods.
  */
 export declare class Vehicle extends Vehicle_base {
     /** Returns a human-readable label for this vehicle. */
     label(): string;
 }
 declare const Car_base: Omit<typeof Vehicle, keyof import('..').ModelConstructor<S, Inst>> & import('..').ModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
     vin: z.ZodString;
     make: z.ZodString;
     year: z.ZodNumber;
     doors: z.ZodNumber;
     engine: z.ZodCodec<z.ZodObject<{
+        _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
         type: z.ZodString;
         horsepower: z.ZodNumber;
     }, z.core.$strip>, z.ZodCustom<Engine, Engine>>;
@@ -44,6 +128,7 @@ declare const Car_base: Omit<typeof Vehicle, keyof import('..').ModelConstructor
     make: string;
     year: number;
     doors: number;
+    _xmlState?: import('./codec').XMLState;
     engine?: Engine;
 }>;
 /**
@@ -57,11 +142,13 @@ declare const Car_base: Omit<typeof Vehicle, keyof import('..').ModelConstructor
 export declare class Car extends Car_base {
 }
 declare const SportCar_base: Omit<typeof Car, keyof import('..').ModelConstructor<S, Inst>> & import('..').ModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
     vin: z.ZodString;
     make: z.ZodString;
     year: z.ZodNumber;
     doors: z.ZodNumber;
     engine: z.ZodCodec<z.ZodObject<{
+        _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
         type: z.ZodString;
         horsepower: z.ZodNumber;
     }, z.core.$strip>, z.ZodCustom<Engine, Engine>>;
@@ -72,6 +159,7 @@ declare const SportCar_base: Omit<typeof Car, keyof import('..').ModelConstructo
     year: number;
     doors: number;
     topSpeed: number;
+    _xmlState?: import('./codec').XMLState;
     engine?: Engine;
 }>;
 /**
@@ -81,6 +169,7 @@ declare const SportCar_base: Omit<typeof Car, keyof import('..').ModelConstructo
 export declare class SportCar extends SportCar_base {
 }
 declare const Motorcycle_base: Omit<typeof Vehicle, keyof import('..').ModelConstructor<S, Inst>> & import('..').ModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
     vin: z.ZodString;
     make: z.ZodString;
     year: z.ZodNumber;
@@ -89,6 +178,7 @@ declare const Motorcycle_base: Omit<typeof Vehicle, keyof import('..').ModelCons
     vin: string;
     make: string;
     year: number;
+    _xmlState?: import('./codec').XMLState;
     sidecar?: boolean;
 }>;
 /**
@@ -98,28 +188,39 @@ declare const Motorcycle_base: Omit<typeof Vehicle, keyof import('..').ModelCons
  */
 export declare class Motorcycle extends Motorcycle_base {
 }
-declare const Fleet_base: import('./model').XmlModelConstructor<z.ZodObject<{
+declare const Fleet_base: Omit<import('./model').XmlModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+}, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+}>, keyof import('..').ModelConstructor<S, Inst>> & import('..').ModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
     name: z.ZodString;
     cars: z.ZodArray<z.ZodCodec<z.ZodObject<{
+        _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
         vin: z.ZodString;
         make: z.ZodString;
         year: z.ZodNumber;
         doors: z.ZodNumber;
         engine: z.ZodCodec<z.ZodObject<{
+            _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
             type: z.ZodString;
             horsepower: z.ZodNumber;
         }, z.core.$strip>, z.ZodCustom<Engine, Engine>>;
     }, z.core.$strip>, z.ZodCustom<Car, Car>>>;
     motorcycles: z.ZodArray<z.ZodCodec<z.ZodObject<{
+        _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
         vin: z.ZodString;
         make: z.ZodString;
         year: z.ZodNumber;
         sidecar: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodCustom<Motorcycle, Motorcycle>>>;
 }, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+} & {
     name: string;
     cars: Car[];
     motorcycles: Motorcycle[];
+    _xmlState?: import('./codec').XMLState;
 }>;
 /**
  * Fleet demonstrates **inline arrays** of multiple vehicle types.
@@ -130,12 +231,20 @@ export declare class Fleet extends Fleet_base {
     /** Total number of vehicles across all types in this fleet. */
     totalVehicles(): number;
 }
-declare const Showroom_base: import('./model').XmlModelConstructor<z.ZodObject<{
+declare const Showroom_base: Omit<import('./model').XmlModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+}, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+}>, keyof import('..').ModelConstructor<S, Inst>> & import('..').ModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
     name: z.ZodString;
     models: z.ZodArray<z.ZodString>;
 }, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+} & {
     name: string;
     models: string[];
+    _xmlState?: import('./codec').XMLState;
 }>;
 /**
  * A showroom holds an inventory of car model names.
@@ -157,28 +266,113 @@ declare const Showroom_base: import('./model').XmlModelConstructor<z.ZodObject<{
  */
 export declare class Showroom extends Showroom_base {
 }
-declare const CarStandalone_base: import('./model').XmlModelConstructor<z.ZodObject<{
+declare const PetrolEngine_base: Omit<import('./model').XmlModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+}, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+}>, keyof import('..').ModelConstructor<S, Inst>> & import('..').ModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+    type: z.ZodLiteral<"petrol">;
+    horsepower: z.ZodNumber;
+}, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+} & {
+    type: "petrol";
+    horsepower: number;
+    _xmlState?: import('./codec').XMLState;
+}>;
+/**
+ * A petrol engine, discriminated by `type="petrol"`.
+ */
+export declare class PetrolEngine extends PetrolEngine_base {
+}
+declare const ElectricEngine_base: Omit<import('./model').XmlModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+}, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+}>, keyof import('..').ModelConstructor<S, Inst>> & import('..').ModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+    type: z.ZodLiteral<"electric">;
+    range: z.ZodNumber;
+}, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+} & {
+    type: "electric";
+    range: number;
+    _xmlState?: import('./codec').XMLState;
+}>;
+/**
+ * An electric engine, discriminated by `type="electric"`.
+ */
+export declare class ElectricEngine extends ElectricEngine_base {
+}
+declare const UnknownEngine_base: Omit<import('./model').XmlModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+}, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+}>, keyof import('..').ModelConstructor<S, Inst>> & import('..').ModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+    type: z.ZodString;
+}, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+} & {
+    type: string;
+    _xmlState?: import('./codec').XMLState;
+}>;
+/**
+ * Fallback for unrecognised engine types. Unknown child elements are preserved
+ * through round-trips via XMLBase's state tracking.
+ */
+export declare class UnknownEngine extends UnknownEngine_base {
+}
+/**
+ * A union that matches known engine types by discriminator and falls back to
+ * `UnknownEngine` for any unrecognised `type` value.
+ */
+export declare const AnyEngine: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodCodec<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+    type: z.ZodLiteral<"petrol">;
+    horsepower: z.ZodNumber;
+}, z.core.$strip>, z.ZodCustom<PetrolEngine, PetrolEngine>>, z.ZodCodec<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+    type: z.ZodLiteral<"electric">;
+    range: z.ZodNumber;
+}, z.core.$strip>, z.ZodCustom<ElectricEngine, ElectricEngine>>], "type">, z.ZodCodec<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+    type: z.ZodString;
+}, z.core.$strip>, z.ZodCustom<UnknownEngine, UnknownEngine>>]>;
+declare const CarStandalone_base: Omit<import('./model').XmlModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
+}, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+}>, keyof import('..').ModelConstructor<S, Inst>> & import('..').ModelConstructor<z.ZodObject<{
+    _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
     vin: z.ZodString;
     make: z.ZodString;
     year: z.ZodNumber;
     doors: z.ZodNumber;
     engine: z.ZodCodec<z.ZodObject<{
+        _xmlState: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
         type: z.ZodString;
         horsepower: z.ZodNumber;
     }, z.core.$strip>, z.ZodCustom<Engine, Engine>>;
 }, z.core.$strip>, {
+    _xmlState?: import('./codec').XMLState;
+} & {
     vin: string;
     make: string;
     year: number;
     doors: number;
+    _xmlState?: import('./codec').XMLState;
     engine?: Engine;
 }>;
 /**
- * Demonstrates the alternative to `.extend()`: passing a manually extended
- * schema to `xmlModel()`. This produces a **fresh class** with no prototype
- * link to `Vehicle` — instances are **not** `instanceof Vehicle` and Vehicle's
- * methods are unavailable.
+ * Demonstrates the alternative to `Vehicle.extend()`: listing all fields
+ * manually inside `XMLBase.extend()`. This produces a class with the same
+ * XML shape as `Car` but **no prototype link to `Vehicle`** — instances are
+ * **not** `instanceof Vehicle` and Vehicle's methods are unavailable.
  *
+ * Round-trip preservation still applies because the class extends `XMLBase`.
  * Use this pattern when you want a standalone class that reuses a schema shape
  * but does not need to be part of the parent class hierarchy.
  */

package/dist/xml/index.d.ts

@@ -1,6 +1,6 @@
 export * from './xml-js';
 export { xml } from './schema-meta';
 export type { UserCodecOptions, XMLState } from './codec';
-export { registerDefault, normalizeCodecOptions } from './codec';
-export { xmlModel, XMLBase, XMLBaseWithSource, type XmlModelConstructor } from './model';
+export { registerDefault, normalizeCodecOptions, XMLCodecError, xmlStateSchema } from './codec';
+export { xmlModel, type XmlModelConstructor } from './model';
 //# sourceMappingURL=index.d.ts.map

package/dist/xml/model.d.ts

@@ -14,37 +14,5 @@ export type XmlModelConstructor<S extends z.ZodObject<any> = z.ZodObject<any>, I
     /** Converts an instance to an XML string. */
     toXMLString(instance: z.infer<S>, options?: StringifyOptions): string;
 };
-/**
- * Base class for xmlModel classes. Preserves element ordering and unknown elements
- * through `schema.parse()` for nested model instances.
- *
- * @example
- * class Device extends XMLBase.extend(
- *   { name: z.string() },
- *   xml.root({ tagname: "device" }),
- * ) {}
- */
-export declare const XMLBase: XmlModelConstructor<z.ZodObject<{
-    __xml_state: z.ZodOptional<z.ZodCustom<import('./codec').XMLState, unknown>>;
-}, z.core.$strip>, {
-    __xml_state?: import('./codec').XMLState;
-}>;
-/**
- * Like {@link XMLBase}, but also records the original `XMLElement` as `.source`
- * on each instance's XML state.
- *
- * @example
- * const device = Device.fromXML(`<device>…</device>`);
- * device[XML_STATE_KEY]?.source; // XMLElement
- */
-export declare const XMLBaseWithSource: XmlModelConstructor<z.ZodObject<{
-    __xml_state: z.ZodOptional<z.ZodCustom<import('./codec').XMLState & {
-        source: XMLElement;
-    }, unknown>>;
-}, z.core.$strip>, {
-    __xml_state?: import('./codec').XMLState & {
-        source: XMLElement;
-    };
-}>;
 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

@@ -1,45 +1,22 @@
 import { model } from "../model.js";
 import XML from "./xml-js.js";
 import { root } from "./schema-meta.js";
-import { XML_STATE_KEY, decode, encode, xmlStateSchema } from "./codec.js";
-import { z } from "zod";
+import { decode, encode } from "./codec.js";
+import "zod";
 //#region src/xml/model.ts
-/**
-* Base class for xmlModel classes. Preserves element ordering and unknown elements
-* through `schema.parse()` for nested model instances.
-*
-* @example
-* class Device extends XMLBase.extend(
-*   { name: z.string() },
-*   xml.root({ tagname: "device" }),
-* ) {}
-*/
-var XMLBase = xmlModel(z.object({ [XML_STATE_KEY]: xmlStateSchema() }));
-/**
-* Like {@link XMLBase}, but also records the original `XMLElement` as `.source`
-* on each instance's XML state.
-*
-* @example
-* const device = Device.fromXML(`<device>…</device>`);
-* device[XML_STATE_KEY]?.source; // XMLElement
-*/
-var XMLBaseWithSource = xmlModel(z.object({ [XML_STATE_KEY]: xmlStateSchema({ source: true }) }));
 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_KEY];
-			const parsed = schema.parse(inputData);
-			parsed[XML_STATE_KEY] = xmlState;
-			return this.fromData(parsed);
+			const rawData = decode(this.dataSchema, input);
+			return this.fromData(this.dataSchema.parse(rawData));
 		}
 		static toXML(instance) {
 			const data = this.toData(instance);
-			return { elements: [encode(this.dataSchema, data)] };
+			const rawData = this.dataSchema.encode(data);
+			return { elements: [encode(this.dataSchema, rawData)] };
 		}
 		static toXMLString(instance, options = {}) {
 			const xml = this.toXML(instance);
@@ -48,6 +25,6 @@ function xmlModel(schema, options) {
 	};
 }
 //#endregion
-export { XMLBase, XMLBaseWithSource, xmlModel };
+export { xmlModel };
 
 //# sourceMappingURL=model.js.map

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

@@ -41,6 +41,21 @@ export declare function root(options: UserRootOptions): z.GlobalMeta;
 export declare function prop<PS extends z.ZodType>(schema: PS, options: UserPropOptions): PS;
 export declare function prop(options: UserPropOptions): z.GlobalMeta;
 type AttributePropOptions = {
+    /**
+     * XML attribute name. Defaults to the field key in kebab-case (the same
+     * conversion applied to child element tag names). Omit `name` when the
+     * attribute name is already the kebab-cased field key.
+     *
+     * @example
+     * // field key "vin" → attribute "vin" — no name needed
+     * vin: xml.attr(z.string())
+     *
+     * // field key "vehicleId" → attribute "vehicle-id" — no name needed (kebab-case default)
+     * vehicleId: xml.attr(z.string())
+     *
+     * // field key "vehicleId" → attribute "vehicle" — name required to override
+     * vehicleId: xml.attr(z.string(), { name: "vehicle" })
+     */
     name?: string;
 };
 export declare function attr<PS extends z.ZodType>(schema: PS, options?: AttributePropOptions): PS;

package/dist/xml/schema-meta.js

@@ -1,5 +1,6 @@
 import XML from "./xml-js.js";
 import { getParentSchema, isZodType } from "../util/zod.js";
+import { kebabCase } from "../util/kebab-case.js";
 import "zod";
 //#region src/xml/schema-meta.ts
 var metaKey = "@@xml-model";
@@ -70,14 +71,14 @@ 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 { options: propOptions } = ctx.property;
+			const attrName = opts.name ?? kebabCase(ctx.property.name);
 			const attrValue = ctx.xml?.attributes?.[attrName];
-			ctx.result[name] = propOptions.schema.parse(attrValue);
+			ctx.result[ctx.property.name] = propOptions.schema.parse(attrValue);
 		},
 		encodeAsProperty(ctx) {
-			const { value, name } = ctx.property;
-			const attrName = opts.name ?? name;
+			const { value } = ctx.property;
+			const attrName = opts.name ?? kebabCase(ctx.property.name);
 			ctx.result.attributes[attrName] = value.toString();
 		}
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xml-model",
-  "version": "2.0.0-beta.5",
+  "version": "2.0.0-beta.7",
   "description": "allows transparent XML <-> Object conversion in typescript",
   "license": "MIT",
   "author": "MathisTLD",