xml-model 1.3.2 → 1.3.3

package/dist/defaults.d.ts

@@ -10,6 +10,19 @@ interface Defaults {
     tagnameFromProperty<T>(property: XMLModelPropertyOptions<T>): string;
     propertyToXML<T>(context: PropertyToXMLContext<T>): XMLRoot;
 }
+/**
+ * Global defaults used by all models and properties when no override is provided.
+ *
+ * You can mutate individual entries to change library-wide behaviour — for example,
+ * replace `defaults.fromXML` to provide a base deserialization strategy instead of
+ * having to specify `fromXML` on every `@Model()`.
+ *
+ * Key behaviours:
+ * - `fromXML` — throws by default; every root model **must** provide its own implementation.
+ * - `tagnameFromModel` / `tagnameFromProperty` — convert class/property names to kebab-case.
+ * - `propertyFromXML` — handles class, array, and union-of-literal property types via runtime reflection.
+ * - `propertyToXML` — serialises class, array, and union-of-literal values; respects `inline`.
+ */
 export declare const defaults: Defaults;
 export {};
 //# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.js

@@ -1,18 +1,36 @@
 import { getModel } from "./model/registry.js";
 import { kebabCase } from "./util/kebab-case.js";
 const defaults = {
+  /**
+   * Default model-level `fromXML` handler.
+   * Always throws — models must supply their own `fromXML` or inherit one from a parent.
+   * @throws {TypeError}
+   */
   fromXML() {
     throw new TypeError(
       "you should define 'defaults.fromXML' yourself or provide a 'fromXML' function to @Model() decorator's options"
     );
   },
+  /**
+   * Collects the XML elements that are the source data for a property.
+   * Assumes `xml.elements[0]` is the wrapper element that contains all property tags.
+   */
   propertyResolveSourceElements(context) {
     const innerElements = context.xml.elements[0]?.elements || [];
     return innerElements.filter((el) => context.property.isSourceElement(el, context));
   },
+  /**
+   * Returns `true` when the element's tag name matches the property's tagname.
+   */
   propertySourceElementsFilter(element, context) {
     return context.property.tagname === element.name;
   },
+  /**
+   * Converts resolved XML elements into a typed property value.
+   * Handles class types, arrays of class types, and union-of-literal types.
+   * Returns `undefined` for optional properties with no matching elements,
+   * and also for unrecognised types.
+   */
   propertyFromXML(context) {
     const prop = context.property;
     const elements = context.elements;
@@ -54,7 +72,11 @@ const defaults = {
     }
     return void 0;
   },
-  /* Object -> XML */
+  /**
+   * Default model-level `toXML` handler.
+   * Collects serialised property fragments and wraps them in a root element
+   * named after the model's tagname.
+   */
   toXML({ properties, model }) {
     const elements = [];
     model.resolveAllProperties().forEach((prop) => {
@@ -76,12 +98,25 @@ const defaults = {
       ]
     };
   },
+  /**
+   * Derives the XML tag name for a model from its class name, converted to kebab-case.
+   * e.g. `MyClass` → `my-class`.
+   */
   tagnameFromModel(model) {
     return kebabCase(model.type.name);
   },
+  /**
+   * Derives the XML tag name for a property from its name, converted to kebab-case.
+   * e.g. `myProp` → `my-prop`.
+   */
   tagnameFromProperty(property) {
     return kebabCase(String(property.name));
   },
+  /**
+   * Converts a typed property value to an `XMLRoot` fragment.
+   * Handles class types, arrays of class types, and union-of-literal types.
+   * When the property has `inline: true`, array items are flattened into the parent element.
+   */
   propertyToXML(context) {
     const property = context.property;
     const type = property.reflected.type;

package/dist/errors.d.ts

@@ -1,21 +1,37 @@
 import { fromXMLContext, PropertyFromXMLContext, PropertyToXMLContext, toXMLContext } from './model/types';
+/**
+ * Thrown when model-level XML → object conversion fails.
+ * Wraps the original error along with the conversion context.
+ */
 export declare class FromXMLConversionError<T> extends Error {
     context: Omit<fromXMLContext<T>, "properties">;
     error: unknown;
     name: string;
     constructor(context: Omit<fromXMLContext<T>, "properties">, error: unknown);
 }
+/**
+ * Thrown when a single property's XML → value conversion fails.
+ * Extends `FromXMLConversionError` with additional property context.
+ */
 export declare class PropertyFromXMLConversionError<T> extends FromXMLConversionError<T> {
     propertyContext: PropertyFromXMLContext<T>;
     name: string;
     constructor(context: Omit<fromXMLContext<T>, "properties">, propertyContext: PropertyFromXMLContext<T>, error: unknown);
 }
+/**
+ * Thrown when model-level object → XML conversion fails.
+ * Wraps the original cause along with the conversion context.
+ */
 export declare class ToXMLConversionError<T> extends Error {
     context: Omit<toXMLContext<T>, "properties">;
     cause: unknown;
     name: string;
     constructor(context: Omit<toXMLContext<T>, "properties">, cause: unknown);
 }
+/**
+ * Thrown when a single property's value → XML conversion fails.
+ * Extends `ToXMLConversionError` with additional property context.
+ */
 export declare class PropertyToXMLConversionError<T> extends ToXMLConversionError<T> {
     propertyContext: PropertyToXMLContext<T>;
     name: string;

package/dist/model/index.d.ts

@@ -1,19 +1,67 @@
 import { Constructor } from 'typescript-rtti';
 import { XMLModelOptions, XMLModelPropertyOptions, CreateXMLModelOptions } from './types';
 import { XMLRoot } from '../types';
+/**
+ * Returns the parent `XMLModel` for the given model, walking the prototype chain
+ * if no explicit parent was set in options.
+ */
 export declare function getParentModel(model: XMLModel<any>): XMLModel<any>;
+/**
+ * Encapsulates the XML ↔ TypeScript conversion logic for a specific class.
+ *
+ * Create instances via `createModel` or the `@Model()` decorator rather than
+ * calling this constructor directly.
+ */
 export declare class XMLModel<T = any> {
     readonly type: Constructor<T>;
     options: XMLModelOptions<T>;
     constructor(type: Constructor<T>, options: CreateXMLModelOptions<T>);
+    /**
+     * Converts an XML document (string or parsed `XMLRoot`) into an instance of `T`.
+     *
+     * @param xml - Raw XML string or a pre-parsed `XMLRoot` object.
+     * @returns The converted instance produced by the model's `fromXML` middleware chain.
+     * @throws {FromXMLConversionError} When model-level conversion fails.
+     * @throws {PropertyFromXMLConversionError} When a property-level conversion fails.
+     */
     fromXML(xml: XMLRoot | string): T;
+    /**
+     * Converts an instance of `T` into an XML document.
+     *
+     * @param instance - An instance of the class this model was created for.
+     * @returns An `XMLRoot` representing the serialised object.
+     * @throws {TypeError} When `instance` is not an instance of the expected type.
+     * @throws {ToXMLConversionError} When model-level conversion fails.
+     * @throws {PropertyToXMLConversionError} When a property-level conversion fails.
+     */
     toXML(instance: unknown): XMLRoot;
+    /** The typescript-rtti reflection metadata for the model's class. */
     get reflectedClass(): import('typescript-rtti').ReflectedClass<Constructor<T>>;
+    /**
+     * Returns a merged map of all property options for this model, including inherited properties.
+     * Own properties override parent properties with the same name.
+     */
     resolveAllProperties(): Map<string, XMLModelPropertyOptions<any> & {
         model: any;
     }>;
 }
+/**
+ * Creates and registers a new `XMLModel` for the given constructor.
+ *
+ * @param type - The class constructor to create a model for.
+ * @param options - Model creation options including `fromXML` and `toXML` middlewares.
+ * @returns The newly created `XMLModel`.
+ * @throws {TypeError} When a model for this type has already been registered.
+ */
 export declare function createModel<T>(type: Constructor<T>, options: CreateXMLModelOptions<T>): XMLModel<T>;
+/**
+ * Decorator factory that registers an `XMLModel` for the decorated class.
+ *
+ * Provide at minimum a `fromXML` function unless the class inherits from a
+ * parent class that already has a model — the default `fromXML` throws.
+ *
+ * @param options - Optional model creation options.
+ */
 declare function ModelDecoratorFactory<T>(options?: CreateXMLModelOptions<T>): (constructor: Constructor<T>) => void;
 export { getModel } from './registry';
 export { ModelDecoratorFactory as Model };

package/dist/model/index.js

@@ -120,6 +120,12 @@ class XMLModel {
           property.name
         );
         if (!options2.ignored) {
+          const type2 = options2.reflected?.type;
+          if (!options2.model && type2?.is("class") && type2.class === Object) {
+            console.warn(
+              `[xml-model] Property '${String(property.name)}' on '${this.type.name}' has type Object at runtime. If its declared type is a class, make sure it is imported as a value and not with 'import type'.`
+            );
+          }
           properties.options.set(property.name, options2);
         }
       });
@@ -154,6 +160,14 @@ class XMLModel {
     if (options.fromXML) this.options.fromXML.middlewares.push(options.fromXML);
     if (options.toXML) this.options.toXML.middlewares.push(options.toXML);
   }
+  /**
+   * Converts an XML document (string or parsed `XMLRoot`) into an instance of `T`.
+   *
+   * @param xml - Raw XML string or a pre-parsed `XMLRoot` object.
+   * @returns The converted instance produced by the model's `fromXML` middleware chain.
+   * @throws {FromXMLConversionError} When model-level conversion fails.
+   * @throws {PropertyFromXMLConversionError} When a property-level conversion fails.
+   */
   fromXML(xml) {
     const _xml = typeof xml === "string" ? XML.parse(xml) : xml;
     const model = this;
@@ -170,6 +184,15 @@ class XMLModel {
     };
     return resolve(MiddlewareChain(this.options.fromXML), context);
   }
+  /**
+   * Converts an instance of `T` into an XML document.
+   *
+   * @param instance - An instance of the class this model was created for.
+   * @returns An `XMLRoot` representing the serialised object.
+   * @throws {TypeError} When `instance` is not an instance of the expected type.
+   * @throws {ToXMLConversionError} When model-level conversion fails.
+   * @throws {PropertyToXMLConversionError} When a property-level conversion fails.
+   */
   toXML(instance) {
     const model = this;
     if (instance instanceof this.type || typeof instance !== "undefined" && instance.constructor === this.type) {
@@ -189,9 +212,14 @@ class XMLModel {
       throw new TypeError(`provided object is not an instance of ${this.type.name}`);
     }
   }
+  /** The typescript-rtti reflection metadata for the model's class. */
   get reflectedClass() {
     return reflect(this.type);
   }
+  /**
+   * Returns a merged map of all property options for this model, including inherited properties.
+   * Own properties override parent properties with the same name.
+   */
   resolveAllProperties() {
     const ownProperties = /* @__PURE__ */ new Map();
     const parent = getParentModel(this);

package/dist/model/property.d.ts

@@ -1,6 +1,18 @@
 import { Constructor } from 'typescript-rtti';
 import { XMLModelProperty, XMLModelPropertyOptions, CreateXMLModelPropertyOptions } from './types';
+/**
+ * Returns the resolved conversion options for a property, using stored `@Prop()` options
+ * if available, or falling back to defaults derived from the property's type information.
+ */
 export declare function getPropertyConversionOptions<T>(constructor: Constructor<T>, property: XMLModelProperty<T>): XMLModelPropertyOptions<T>;
+/**
+ * Decorator factory that customises how a class property is converted to and from XML.
+ *
+ * Applied to properties of classes decorated with `@Model()`. All options are optional —
+ * omitting `@Prop()` entirely uses the defaults inferred from the property's TypeScript type.
+ *
+ * @param options - Property conversion options.
+ */
 declare function PropDecoratorFactory<T = any>(options?: CreateXMLModelPropertyOptions<T>): (prototype: any, property: XMLModelProperty<T>) => void;
 export { PropDecoratorFactory as Prop };
 //# sourceMappingURL=property.d.ts.map

package/dist/model/types.d.ts

@@ -2,57 +2,86 @@ import { ReflectedProperty } from 'typescript-rtti';
 import { XMLRoot, XMLElement } from '../types';
 import { Middleware } from '../middleware';
 import { XMLModel } from './index';
+/** The name of a property on type `T` (string keys only). */
 export type XMLModelProperty<T> = Extract<keyof T, string>;
+/** A partial record mapping property names to their runtime values. */
 export type PropertiesRecord<T> = {
     [key in keyof T]?: T[key];
 };
+/** A partial record mapping property names to their XML representations. */
 export type XMLPropertiesRecord<T> = {
     [key in keyof T]?: XMLRoot;
 };
+/** Context passed to a property's `toXML` conversion function. */
 export interface PropertyToXMLContext<T> extends Omit<toXMLContext<T>, "properties"> {
     property: XMLModelPropertyOptions<T>;
     value: T[keyof T];
 }
+/** Context passed to a property's `fromXML` conversion function. */
 export interface PropertyFromXMLContext<T> extends Omit<fromXMLContext<T>, "properties"> {
     property: XMLModelPropertyOptions<T>;
+    /** The XML elements resolved as source data for this property. */
     elements: XMLElement[];
 }
+/** Fully resolved runtime options for a single model property. */
 export interface XMLModelPropertyOptions<T> {
     name: keyof T;
     reflected: ReflectedProperty;
+    /** XML tag name used for this property. Derived from the property name in kebab-case by default. */
     tagname: string;
     ignored: boolean;
+    /** When `true`, array items are serialised/deserialised directly into the parent element without a wrapper tag. */
     inline: boolean;
+    /** Override model used to convert this property's value. */
     model?: XMLModel<any>;
+    /** Returns `true` when the given element should be considered a source for this property. */
     isSourceElement: (element: XMLElement, context: Omit<PropertyFromXMLContext<T>, "elements">) => boolean;
+    /** Collects the XML elements that will be passed to `fromXML` for this property. */
     resolveElements: (context: Omit<PropertyFromXMLContext<T>, "elements">) => XMLElement[];
     fromXML: (context: PropertyFromXMLContext<T>) => T[keyof T];
     toXML: (context: PropertyToXMLContext<T>) => XMLRoot;
 }
+/** User-facing options accepted by the `@Prop()` decorator and `createModel`. */
 export interface CreateXMLModelPropertyOptions<T> {
+    /** Override the XML tag name for this property. */
     tagname?: string;
+    /**
+     * Controls which XML elements are treated as the source for this property.
+     * - `string`: exact tag name match
+     * - `RegExp`: tag name pattern match
+     * - `function`: custom predicate
+     */
     sourceElements?: string | RegExp | XMLModelPropertyOptions<T>["isSourceElement"];
+    /** Custom element resolver; overrides the default source-element resolution logic. */
     resolveElements?: XMLModelPropertyOptions<T>["resolveElements"];
     toXML?: XMLModelPropertyOptions<T>["toXML"];
     fromXML?: XMLModelPropertyOptions<T>["fromXML"];
+    /** When `true`, array items are inlined directly into the parent element. */
     inline?: boolean;
+    /** When `true`, the property is excluded from XML conversion entirely. */
     ignore?: boolean;
+    /** Explicit model to use for this property's value. */
     model?: XMLModelPropertyOptions<T>["model"];
 }
 interface ConversionOptions<C, T> {
     parent: ConversionOptions<C, T> | null;
     middlewares: Middleware<C, T>[];
 }
+/** Context passed to the model-level `fromXML` middleware chain. */
 export interface fromXMLContext<T> {
     xml: XMLRoot;
+    /** Lazily computed property values derived from `xml`. */
     properties: PropertiesRecord<T>;
     model: XMLModel<T>;
 }
+/** Context passed to the model-level `toXML` middleware chain. */
 export interface toXMLContext<T> {
     object: T;
+    /** Lazily computed per-property XML fragments. */
     properties: XMLPropertiesRecord<T>;
     model: XMLModel<T>;
 }
+/** Internal fully-resolved model options (not the user-facing create options). */
 export interface XMLModelOptions<T> {
     parent?: XMLModel<T>;
     properties: {
@@ -62,12 +91,18 @@ export interface XMLModelOptions<T> {
     };
     fromXML: ConversionOptions<fromXMLContext<T>, T>;
     toXML: ConversionOptions<toXMLContext<T>, XMLRoot>;
+    /** XML tag name for the root element of this model. */
     tagname: string;
 }
+/** User-facing options for `createModel` / `@Model()`. */
 export interface CreateXMLModelOptions<T> {
+    /** Explicitly set the parent model (otherwise inferred from the prototype chain). */
     parent?: XMLModelOptions<T>["parent"];
+    /** Middleware that converts XML into an instance of `T`. Required unless a parent model provides one. */
     fromXML?: XMLModelOptions<T>["fromXML"]["middlewares"][number];
+    /** Middleware that converts an instance of `T` into XML. Optional — a default implementation is provided. */
     toXML?: XMLModelOptions<T>["toXML"]["middlewares"][number];
+    /** Override the root XML tag name. Defaults to the class name in kebab-case. */
     tagname?: XMLModelOptions<T>["tagname"];
 }
 export { XMLModel };

package/dist/types.d.ts

@@ -1,9 +1,16 @@
 export type { Constructor } from 'typescript-rtti';
+/** A record with unknown values, keyed by string, number, or symbol. */
 export type UnknownRecord = Record<string | number | symbol, unknown>;
+/** Any object type. Used instead of `UnknownRecord` because it is compatible with class instances. */
 export type UnknownObject = object;
+/** Key-value map of XML attributes. Values may be strings, numbers, or absent. */
 export interface XMLAttributes {
     [key: string]: string | number | undefined;
 }
+/**
+ * A single node in the xml-js element tree.
+ * Used as the internal representation for all XML parsing and serialisation.
+ */
 export interface XMLElement {
     type?: string;
     name?: string;
@@ -11,6 +18,7 @@ export interface XMLElement {
     elements?: Array<XMLElement>;
     text?: string | number | boolean;
 }
+/** The root of an xml-js document: a wrapper object whose `elements` array holds top-level nodes. */
 export type XMLRoot = {
     elements: XMLElement[];
 };

package/dist/vite/index.d.ts

@@ -1,8 +1,12 @@
+import { Plugin } from 'vite';
 import { RollupTypescriptOptions } from '@rollup/plugin-typescript';
 /**
+ * Vite plugin that preserves class names at build time.
+ *
  * When Building, class names are changed but the library relies on them
- * so they need to be preserved
- * @returns
+ * so they need to be preserved.
+ *
+ * @returns A Vite plugin that rewrites mangled class name expressions and enables `keepNames`.
  */
 export declare function FixClassNames(): {
     name: string;
@@ -17,26 +21,49 @@ export declare function FixClassNames(): {
         };
     };
 };
+/** Options for the `TypescriptRTTI` and `XMLModelVitePlugin` plugins. */
 export type RTTIPluginOptions = {
     /**
-     * options for @rollup/plugin-typescript
+     * Options forwarded to `@rollup/plugin-typescript`.
      *
-     * Plugin might not work if you override the `transformers` property as these options are assigned and not deep merged
+     * The plugin may not work correctly if you override the `transformers` property,
+     * as these options are shallow-merged (not deep-merged).
      */
     typescript?: RollupTypescriptOptions;
-    /** Files where the rtti transformer should be applied
+    /**
+     * Restrict RTTI transformation to files matching this pattern.
      *
-     * If not set, will include every files by default
+     * When omitted, all files are transformed.
      */
     include?: RegExp;
-    /** Files where the rtti transformer should not be applied */
+    /** Exclude files matching this pattern from RTTI transformation. */
     exclude?: RegExp;
-    /** Print debug logs */
+    /** Print debug logs from the RTTI transformer. */
     debug?: boolean;
 };
+/**
+ * Vite plugin that applies the `typescript-rtti` TypeScript transformer.
+ *
+ * This transformer emits the runtime type metadata that xml-model uses to
+ * introspect property types without manual annotations.
+ *
+ * @param options - Plugin options controlling which files are transformed.
+ * @returns A configured `@rollup/plugin-typescript` instance with the RTTI transformer injected.
+ */
 export declare function TypescriptRTTI(options?: RTTIPluginOptions): import('rollup').Plugin<any>;
+/** Alias for `RTTIPluginOptions`. */
 export type XMLModelVitePluginOptions = RTTIPluginOptions;
-export declare function XMLModelVitePlugin(options?: RTTIPluginOptions): (import('rollup').Plugin<any> | {
+/**
+ * Main xml-model Vite plugin.
+ *
+ * Combines `FixClassNames`, `TypescriptRTTI`, and an internal resolver that
+ * rewrites the `xml-model/dist/*` import paths emitted by typescript-rtti back
+ * to the canonical `xml-model/*` paths exported by the package.
+ *
+ * @param options - Options forwarded to `TypescriptRTTI`.
+ * @returns An array of Vite plugins.
+ */
+export declare function XMLModelVitePlugin(options?: RTTIPluginOptions): (Plugin<any> | import('rollup').Plugin<any> | {
     name: string;
     enforce: "post";
     transform(this: import('rollup').TransformPluginContext, code: string, id: string): {

package/dist/vite/index.js

@@ -52,7 +52,15 @@ function TypescriptRTTI(options = {}) {
   });
 }
 function XMLModelVitePlugin(options = {}) {
-  return [FixClassNames(), TypescriptRTTI(options)];
+  const distResolver = {
+    name: "xml-model-resolve-dist",
+    enforce: "pre",
+    async resolveId(id) {
+      const match = id.match(/^xml-model\/dist\/(.*)/);
+      if (match) return this.resolve(`xml-model/${match[1]}`);
+    }
+  };
+  return [FixClassNames(), TypescriptRTTI(options), distResolver];
 }
 export {
   FixClassNames,

package/dist/xml/index.d.ts

@@ -1,7 +1,34 @@
 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";
@@ -17,9 +44,29 @@ export declare function fromContent(content: string, tag: string, attributes?: X
         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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xml-model",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "allows transparent XML <-> Object conversion in typescript",
   "license": "MIT",
   "author": "MathisTLD",