xml-model 1.3.3 → 2.0.0-beta.2

package/dist/util/zod.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+//#region src/util/zod.ts
+function isZodType(object) {
+	return object instanceof z.ZodType;
+}
+function getParentSchema(schema) {
+	let parent;
+	if (schema instanceof z.ZodPipe) {
+		if (isZodType(schema.def.in)) parent = schema.def.in;
+	} else if (schema instanceof z.ZodOptional) {
+		if (isZodType(schema.def.innerType)) parent = schema.def.innerType;
+	} else if (schema instanceof z.ZodLazy) {
+		const value = schema.def.getter();
+		if (isZodType(value)) parent = value;
+	}
+	return parent;
+}
+//#endregion
+export { getParentSchema, isZodType };
+
+//# sourceMappingURL=zod.js.map

package/dist/xml/codec.d.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { XMLElement } from './xml-js';
+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;
+export interface CodecOptions<S extends z.ZodType> {
+    schema: S;
+    tagname(ctx: RootEncodingContext<S>): string;
+    decode(ctx: RootDecodingContext<S>): z.input<S>;
+    encode(ctx: RootEncodingContext<S>): XMLElement;
+    propertyTagname: (ctx: {
+        name: string;
+        options: CodecOptions<z.ZodType>;
+    }) => string;
+    /** if true, XML representation is not contained in a single XML tag */
+    inlineProperty: boolean;
+    propertyMatch: (el: XMLElement, ctx: {
+        name: string;
+        tagname: string;
+        options: CodecOptions<z.ZodType>;
+    }) => boolean;
+    decodeAsProperty(ctx: PropertyDecodingContext): void;
+    encodeAsProperty(ctx: PropertyEncodingContext): void;
+}
+/**
+ * Stored in schema meta under the single `@@xml-model` key.
+ * All fields are optional; `normalizeCodecOptions` fills in defaults.
+ * `tagname`/`propertyTagname` accept a string (normalized to a function).
+ * `propertyMatch` accepts a RegExp (normalized to an element-name test).
+ */
+export type UserCodecOptions<S extends z.ZodType = z.ZodType> = {
+    tagname?: string | CodecOptions<S>["tagname"];
+    decode?: CodecOptions<S>["decode"];
+    encode?: CodecOptions<S>["encode"];
+    propertyTagname?: string | CodecOptions<S>["propertyTagname"];
+    inlineProperty?: boolean;
+    propertyMatch?: RegExp | CodecOptions<S>["propertyMatch"];
+    decodeAsProperty?: CodecOptions<S>["decodeAsProperty"];
+    encodeAsProperty?: CodecOptions<S>["encodeAsProperty"];
+};
+export interface RootDecodingContext<S extends z.ZodType> {
+    options: CodecOptions<S>;
+    xml: XMLElement | null;
+}
+export interface RootEncodingContext<S extends z.ZodType> {
+    options: CodecOptions<S>;
+    data: z.output<S>;
+}
+export interface PropertyDecodingContext<S extends z.ZodObject = z.ZodObject, K extends PropKey<S> = PropKey<S>> extends RootDecodingContext<S> {
+    property: {
+        name: K;
+        options: CodecOptions<z.ZodType>;
+        tagname: string;
+        xml: XMLElement | null;
+    };
+    /** an object to be filled with input data */
+    result: Partial<z.input<S>>;
+}
+export interface PropertyEncodingContext<S extends z.ZodObject = z.ZodObject, K extends PropKey<S> = PropKey<S>> extends RootEncodingContext<S> {
+    property: {
+        name: K;
+        options: CodecOptions<z.ZodType>;
+        tagname: string;
+        value: z.output<S>[K];
+    };
+    result: XMLElement;
+}
+export declare function normalizeCodecOptions<S extends z.ZodType>(schema: S, options?: UserCodecOptions<S>): CodecOptions<S>;
+type OrderEntry = string | XMLElement;
+export interface XMLState {
+    /** Preserves element ordering and unknown elements across a decode → encode round-trip. */
+    fieldOrder: OrderEntry[];
+}
+/**
+ * Non-enumerable Symbol attached to decoded data objects (and forwarded to model instances).
+ * Groups all XML codec round-trip state under a single key.
+ */
+export declare const XML_STATE: unique symbol;
+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;
+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>;
+export {};
+//# sourceMappingURL=codec.d.ts.map

package/dist/xml/codec.js

@@ -0,0 +1,339 @@
+import XML from "./xml-js.js";
+import { isZodType } from "../util/zod.js";
+import { getUserOptions } from "./schema-meta.js";
+import { kebabCase } from "../util/kebab-case.js";
+import { z } from "zod";
+//#region src/xml/codec.ts
+function assertSingleElement(xml) {
+	if (xml.length !== 1) throw new Error(`Expected single XML element, got ${xml.length}`);
+}
+function normalizeCodecOptions(schema, options = {}) {
+	let _defaultOptions;
+	const defaultOptions = () => {
+		if (!_defaultOptions) {
+			_defaultOptions = resolveDefault(schema);
+			if (!_defaultOptions) throw new Error(`Failed to resolve default codec options for schema of type ${schema.type}`);
+		}
+		return _defaultOptions;
+	};
+	const userTagname = options.tagname;
+	const tagname = typeof userTagname === "string" ? () => userTagname : typeof userTagname === "function" ? userTagname : () => {
+		throw new Error("tagname is not defined");
+	};
+	const userPropTagname = options.propertyTagname;
+	const propertyTagname = typeof userPropTagname === "string" ? () => userPropTagname : typeof userPropTagname === "function" ? userPropTagname : (ctx) => kebabCase(ctx.name);
+	const inlineProperty = options.inlineProperty ?? false;
+	const userMatch = options.propertyMatch;
+	const propertyMatch = userMatch instanceof RegExp ? (el) => userMatch.test(el.name) : typeof userMatch === "function" ? userMatch : (el, ctx) => el.name === ctx.tagname;
+	const result = {
+		schema,
+		tagname,
+		decode: options.decode ?? defaultOptions().decode,
+		encode: options.encode ?? defaultOptions().encode,
+		propertyTagname,
+		inlineProperty,
+		propertyMatch,
+		decodeAsProperty: options.decodeAsProperty ?? function(ctx) {
+			const res = result.decode({
+				options: result,
+				xml: ctx.property.xml
+			});
+			ctx.result[ctx.property.name] = res;
+		},
+		encodeAsProperty: options.encodeAsProperty ?? function(ctx) {
+			const { property } = ctx;
+			const optsWithTagname = {
+				...result,
+				tagname: () => property.tagname
+			};
+			const res = result.encode({
+				options: optsWithTagname,
+				data: property.value
+			});
+			if (XML.isEmpty(res)) return;
+			if (property.options.inlineProperty) ctx.result.elements.push(...res.elements);
+			else ctx.result.elements.push(res);
+		}
+	};
+	return result;
+}
+var cache = /* @__PURE__ */ new Map();
+function resolveCodecOptions(schema) {
+	const cached = cache.get(schema);
+	if (cached) return cached;
+	const options = normalizeCodecOptions(schema, getUserOptions(schema));
+	cache.set(schema, options);
+	return options;
+}
+/**
+* Non-enumerable Symbol attached to decoded data objects (and forwarded to model instances).
+* Groups all XML codec round-trip state under a single key.
+*/
+var XML_STATE = Symbol("xml-model.state");
+function resolvePropertiesCodecOptions(schema) {
+	const shape = schema.def.shape;
+	const options = {};
+	for (const [prop, fieldSchema] of Object.entries(shape)) options[prop] = resolveCodecOptions(fieldSchema);
+	return options;
+}
+function decode(schema, xml) {
+	const options = resolveCodecOptions(schema);
+	return options.decode({
+		options,
+		xml
+	});
+}
+function encode(schema, data) {
+	const options = resolveCodecOptions(schema);
+	return options.encode({
+		options,
+		data
+	});
+}
+function registerDefault(resolve) {
+	defaults.push(resolve);
+}
+var defaults = [];
+function resolveDefault(schema) {
+	for (let index = defaults.length - 1; index >= 0; index--) {
+		const resolver = defaults[index];
+		const res = resolver(schema);
+		if (res) return res;
+	}
+}
+registerDefault((schema) => {
+	if (schema instanceof z.ZodArray) {
+		const elOptions = resolveCodecOptions(schema.def.element);
+		return normalizeCodecOptions(schema, {
+			decode(ctx) {
+				const { xml } = ctx;
+				if (!xml) return [];
+				return xml.elements.filter((el) => el.type === "element").map((el) => elOptions.decode({
+					options: elOptions,
+					xml: el
+				}));
+			},
+			encode(ctx) {
+				const values = ctx.data;
+				if (!Array.isArray(values)) throw new Error("expected array");
+				return {
+					type: "element",
+					name: ctx.options.tagname(ctx),
+					attributes: {},
+					elements: values.map((v) => elOptions.encode({
+						options: elOptions,
+						data: v
+					}))
+				};
+			}
+		});
+	}
+	if (schema instanceof z.ZodOptional) {
+		const inner = schema.def.innerType;
+		if (!isZodType(inner)) throw new Error(`Expected a ZodType, got ${inner}`);
+		const innerOptions = resolveCodecOptions(inner);
+		return normalizeCodecOptions(schema, {
+			decode(ctx) {
+				if (!ctx.xml) return void 0;
+				else return innerOptions.decode(ctx);
+			},
+			encode(ctx) {
+				if (typeof ctx.data === "undefined") return {};
+				else return innerOptions.encode(ctx);
+			}
+		});
+	}
+	if (schema instanceof z.ZodDefault) {
+		const { innerType: inner, defaultValue } = schema.def;
+		if (!isZodType(inner)) throw new Error(`Expected a ZodType, got ${inner}`);
+		const innerOptions = resolveCodecOptions(inner);
+		const getDefault = typeof schema.def.defaultValue === "function" ? schema.def.defaultValue : () => defaultValue;
+		return normalizeCodecOptions(schema, {
+			decode(ctx) {
+				if (!ctx.xml) return getDefault();
+				else return innerOptions.decode(ctx);
+			},
+			encode(ctx) {
+				return innerOptions.encode(ctx);
+			}
+		});
+	}
+	if (schema instanceof z.ZodLazy) {
+		const inner = schema.def.getter();
+		if (!isZodType(inner)) throw new Error(`Expected a ZodType, got ${inner}`);
+		return resolveDefault(inner);
+	}
+	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({
+					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
+				});
+			}
+		});
+	}
+	if (schema instanceof z.ZodLiteral) {
+		const values = schema.def.values;
+		const valuesFromString = Object.fromEntries(values.map((v) => [v.toString(), v]));
+		return normalizeCodecOptions(schema, {
+			decode(ctx) {
+				const raw = XML.getContent(ctx.xml);
+				if (!(raw in valuesFromString)) throw new Error(`Could not retrieve literal value from string "${raw}"`);
+				return valuesFromString[raw];
+			},
+			encode(ctx) {
+				return XML.fromContent(String(ctx.data), ctx.options.tagname(ctx));
+			}
+		});
+	}
+	if (schema instanceof z.ZodString) return normalizeCodecOptions(schema, {
+		decode(ctx) {
+			return XML.getContent(ctx.xml);
+		},
+		encode(ctx) {
+			return XML.fromContent(ctx.data, ctx.options.tagname(ctx));
+		}
+	});
+	if (schema instanceof z.ZodNumber) return normalizeCodecOptions(schema, {
+		decode(ctx) {
+			return Number(XML.getContent(ctx.xml));
+		},
+		encode(ctx) {
+			return XML.fromContent(ctx.data.toString(), ctx.options.tagname(ctx));
+		}
+	});
+	if (schema instanceof z.ZodBoolean) return normalizeCodecOptions(schema, {
+		decode(ctx) {
+			return XML.getContent(ctx.xml) === "true";
+		},
+		encode(ctx) {
+			return XML.fromContent(ctx.data.toString(), ctx.options.tagname(ctx));
+		}
+	});
+});
+registerDefault((schema) => {
+	if (schema instanceof z.ZodObject) {
+		const options = resolvePropertiesCodecOptions(schema);
+		return normalizeCodecOptions(schema, {
+			decode(ctx) {
+				const sequence = [];
+				const propContexts = Object.fromEntries(Object.entries(options).map(([name, propOpts]) => {
+					return [name, {
+						name,
+						options: propOpts,
+						tagname: propOpts.propertyTagname({
+							name,
+							options: propOpts
+						}),
+						xml: { elements: [] }
+					}];
+				}));
+				const seenProperties = /* @__PURE__ */ new Set();
+				for (const el of ctx.xml.elements) {
+					if (el.type !== "element") continue;
+					const matches = [];
+					for (const prop in options) {
+						const propCtx = propContexts[prop];
+						if (options[prop].propertyMatch(el, propCtx)) {
+							matches.push(prop);
+							propCtx.xml.elements.push(el);
+						}
+					}
+					if (!matches.length) {
+						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);
+							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);
+				const result = {};
+				for (const prop in options) {
+					const o = options[prop];
+					const propCtx = propContexts[prop];
+					if (!o.inlineProperty) {
+						const matches = propCtx.xml.elements;
+						if (matches.length === 0) propCtx.xml = null;
+						else {
+							assertSingleElement(matches);
+							propCtx.xml = matches[0];
+						}
+					}
+					o.decodeAsProperty({
+						options: ctx.options,
+						xml: ctx.xml,
+						property: propCtx,
+						result
+					});
+				}
+				Object.defineProperty(result, XML_STATE, {
+					value: { fieldOrder: sequence },
+					enumerable: false,
+					writable: true,
+					configurable: true
+				});
+				return result;
+			},
+			encode(ctx) {
+				const { data } = ctx;
+				const result = {
+					type: "element",
+					name: ctx.options.tagname(ctx),
+					attributes: {},
+					elements: []
+				};
+				const sequence = data[XML_STATE]?.fieldOrder ?? Object.keys(options);
+				for (const item of sequence) 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({
+								name: item,
+								options: o
+							}),
+							value: data[item]
+						},
+						result
+					});
+				} else result.elements.push(item);
+				return result;
+			}
+		});
+	}
+});
+//#endregion
+export { XML_STATE, decode, encode, normalizeCodecOptions, registerDefault };
+
+//# sourceMappingURL=codec.js.map

package/dist/xml/examples.d.ts

@@ -0,0 +1,188 @@
+import { z } from 'zod';
+declare const Engine_base: import('./model').XmlModelConstructor<z.ZodObject<{
+    type: z.ZodString;
+    horsepower: z.ZodNumber;
+}, z.core.$strip>, {
+    type: string;
+    horsepower: number;
+}>;
+/**
+ * A car engine. 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<{
+    vin: z.ZodString;
+    make: z.ZodString;
+    year: z.ZodNumber;
+}, z.core.$strip>, {
+    vin: string;
+    make: string;
+    year: number;
+}>;
+/**
+ * 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.
+ */
+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<{
+    vin: z.ZodString;
+    make: z.ZodString;
+    year: z.ZodNumber;
+    doors: z.ZodNumber;
+    engine: z.ZodCodec<z.ZodObject<{
+        type: z.ZodString;
+        horsepower: z.ZodNumber;
+    }, z.core.$strip>, z.ZodCustom<Engine, Engine>>;
+}, z.core.$strip>, Vehicle & {
+    vin: string;
+    make: string;
+    year: number;
+    doors: number;
+    engine?: Engine;
+}>;
+/**
+ * Car extends Vehicle using `Vehicle.extend()`, which creates a **true subclass**:
+ * instances are `instanceof Vehicle` and inherit Vehicle's methods (e.g. `label()`).
+ *
+ * Demonstrates:
+ * - chaining `.extend()` to add fields to a parent model
+ * - `xml.prop(Engine)` to embed a nested xmlModel class as a child element
+ */
+export declare class Car extends Car_base {
+}
+declare const SportCar_base: Omit<typeof Car, keyof import('..').ModelConstructor<S, Inst>> & import('..').ModelConstructor<z.ZodObject<{
+    vin: z.ZodString;
+    make: z.ZodString;
+    year: z.ZodNumber;
+    doors: z.ZodNumber;
+    engine: z.ZodCodec<z.ZodObject<{
+        type: z.ZodString;
+        horsepower: z.ZodNumber;
+    }, z.core.$strip>, z.ZodCustom<Engine, Engine>>;
+    topSpeed: z.ZodNumber;
+}, z.core.$strip>, Car & {
+    vin: string;
+    make: string;
+    year: number;
+    doors: number;
+    topSpeed: number;
+    engine?: Engine;
+}>;
+/**
+ * SportCar shows that `.extend()` chains across multiple levels.
+ * Instances are `instanceof SportCar`, `instanceof Car`, and `instanceof Vehicle`.
+ */
+export declare class SportCar extends SportCar_base {
+}
+declare const Motorcycle_base: Omit<typeof Vehicle, keyof import('..').ModelConstructor<S, Inst>> & import('..').ModelConstructor<z.ZodObject<{
+    vin: z.ZodString;
+    make: z.ZodString;
+    year: z.ZodNumber;
+    sidecar: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, Vehicle & {
+    vin: string;
+    make: string;
+    year: number;
+    sidecar?: boolean;
+}>;
+/**
+ * Motorcycle extends Vehicle with an optional boolean field.
+ * When `<sidecar>` is absent from the XML the field is `undefined`;
+ * `toXMLString` omits it entirely.
+ */
+export declare class Motorcycle extends Motorcycle_base {
+}
+declare const Fleet_base: import('./model').XmlModelConstructor<z.ZodObject<{
+    name: z.ZodString;
+    cars: z.ZodArray<z.ZodCodec<z.ZodObject<{
+        vin: z.ZodString;
+        make: z.ZodString;
+        year: z.ZodNumber;
+        doors: z.ZodNumber;
+        engine: z.ZodCodec<z.ZodObject<{
+            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<{
+        vin: z.ZodString;
+        make: z.ZodString;
+        year: z.ZodNumber;
+        sidecar: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodCustom<Motorcycle, Motorcycle>>>;
+}, z.core.$strip>, {
+    name: string;
+    cars: Car[];
+    motorcycles: Motorcycle[];
+}>;
+/**
+ * Fleet demonstrates **inline arrays** of multiple vehicle types.
+ * `inline: true` places each item as a direct sibling element inside the
+ * root tag rather than wrapping them in a container element.
+ */
+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<{
+    name: z.ZodString;
+    models: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, {
+    name: string;
+    models: string[];
+}>;
+/**
+ * A showroom holds an inventory of car model names.
+ * Demonstrates a **non-inline** (wrapped) array: all items are nested inside
+ * a single `<models>` container element, as opposed to being direct siblings
+ * of the root element.
+ *
+ * ```xml
+ * <showroom name="Acme Dealers">
+ *   <models>
+ *     <model>Corolla</model>
+ *     <model>Civic</model>
+ *   </models>
+ * </showroom>
+ * ```
+ *
+ * Contrast with `Fleet`, which uses `inline: true` so each `<car>` / `<motorcycle>`
+ * is a direct child of `<fleet>` with no container wrapper.
+ */
+export declare class Showroom extends Showroom_base {
+}
+declare const CarStandalone_base: import('./model').XmlModelConstructor<z.ZodObject<{
+    vin: z.ZodString;
+    make: z.ZodString;
+    year: z.ZodNumber;
+    doors: z.ZodNumber;
+    engine: z.ZodCodec<z.ZodObject<{
+        type: z.ZodString;
+        horsepower: z.ZodNumber;
+    }, z.core.$strip>, z.ZodCustom<Engine, Engine>>;
+}, z.core.$strip>, {
+    vin: string;
+    make: string;
+    year: number;
+    doors: number;
+    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.
+ *
+ * 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.
+ */
+export declare class CarStandalone extends CarStandalone_base {
+}
+export {};
+//# sourceMappingURL=examples.d.ts.map