xml-model 1.3.3 → 2.0.0-beta.1

package/dist/defaults.d.ts

@@ -1,28 +0,0 @@
-import { fromXMLContext, PropertyFromXMLContext, PropertyToXMLContext, toXMLContext, XMLModelPropertyOptions, XMLModel } from './model/types';
-import { XMLElement, XMLRoot } from './types';
-interface Defaults {
-    fromXML<T>(context: fromXMLContext<T>): T;
-    propertySourceElementsFilter<T>(...args: Parameters<XMLModelPropertyOptions<T>["isSourceElement"]>): boolean;
-    propertyResolveSourceElements<T>(context: Omit<PropertyFromXMLContext<T>, "elements">): XMLElement[];
-    propertyFromXML<T>(context: PropertyFromXMLContext<T>): T[keyof T];
-    toXML<T>(context: toXMLContext<T>): XMLRoot;
-    tagnameFromModel: (model: XMLModel) => string;
-    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,165 +0,0 @@
-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;
-    if (prop.reflected.isOptional && elements.length === 0) {
-      return void 0;
-    }
-    if (prop.model) {
-      return prop.model.fromXML({ elements });
-    }
-    const type = context.property.reflected.type;
-    if (type.is("class")) {
-      const model = getModel(type.class);
-      return model.fromXML({ elements: context.elements });
-    } else if (type.is("array")) {
-      let arrayEl = {};
-      if (!prop.inline && elements.length === 1 && elements[0].name === prop.tagname) {
-        arrayEl = elements[0];
-      } else if (prop.inline) {
-        arrayEl = { elements };
-      }
-      const els = arrayEl.elements || [];
-      const elType = type.elementType;
-      if (elType.is("class")) {
-        const model = getModel(elType.class);
-        const xmlInstances = els.map((el) => ({
-          elements: [el]
-        }));
-        return xmlInstances.map((xml) => model.fromXML(xml));
-      }
-    } else if (type.is("union") && type.types.length && type.types[0].is("literal")) {
-      const firstType = type.types[0];
-      if (firstType.is("literal")) {
-        const firstTypeCtor = firstType.value.constructor;
-        if (type.types.every((type2) => type2.is("literal") && type2.value.constructor === firstTypeCtor)) {
-          const model = getModel(firstTypeCtor);
-          return model.fromXML({ elements });
-        }
-      }
-    }
-    return void 0;
-  },
-  /**
-   * 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) => {
-      if (prop.name in properties && typeof prop.name !== "symbol") {
-        const _xml = properties[prop.name];
-        _xml.elements.forEach((el) => {
-          el.name = prop.tagname;
-          elements.push(el);
-        });
-      }
-    });
-    return {
-      elements: [
-        {
-          type: "element",
-          name: model.options.tagname,
-          elements
-        }
-      ]
-    };
-  },
-  /**
-   * 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;
-    const value = context.value;
-    if (property.reflected.isOptional && typeof value === "undefined") {
-      return { elements: [] };
-    }
-    if (property.model) {
-      return property.model.toXML(value);
-    }
-    const getXML = () => {
-      if (type.is("class")) {
-        const model = getModel(type.class);
-        return model.toXML(value);
-      } else if (type.is("array")) {
-        const elementType = type.elementType;
-        if (elementType.is("class")) {
-          const model = getModel(elementType.class);
-          const elements = [];
-          value.forEach((el) => elements.push(...model.toXML(el).elements));
-          return { elements: [{ type: "element", name: "array", elements }] };
-        }
-      } else if (type.is("union") && type.types.length && type.types[0].is("literal")) {
-        const firstType = type.types[0];
-        if (firstType.is("literal")) {
-          const firstTypeCtor = firstType.value.constructor;
-          if (type.types.every(
-            (type2) => type2.is("literal") && type2.value.constructor === firstTypeCtor
-          )) {
-            const model = getModel(firstTypeCtor);
-            return model.toXML(context.value);
-          }
-        }
-      }
-      return { elements: [] };
-    };
-    const xml = getXML();
-    if (context.property.inline)
-      return { elements: xml.elements.map((el) => el.elements || []).flat() };
-    else return xml;
-  }
-};
-export {
-  defaults
-};
-//# sourceMappingURL=defaults.js.map

package/dist/errors.d.ts

@@ -1,40 +0,0 @@
-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;
-    constructor(context: Omit<toXMLContext<T>, "properties">, propertyContext: PropertyToXMLContext<T>, cause: unknown);
-}
-//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -1,45 +0,0 @@
-class FromXMLConversionError extends Error {
-  constructor(context, error) {
-    const message = `[Model: ${context.model.type.name}] failed to convert from XML`;
-    super(message);
-    this.context = context;
-    this.error = error;
-    this.name = "FromXMLConversionError";
-  }
-}
-class PropertyFromXMLConversionError extends FromXMLConversionError {
-  constructor(context, propertyContext, error) {
-    super(context, error);
-    this.propertyContext = propertyContext;
-    this.name = "PropertyFromXMLConversionError";
-    this.message = `[Model: ${context.model.type.name}] failed to convert prop <${String(
-      propertyContext.property.name
-    )}> from XML`;
-  }
-}
-class ToXMLConversionError extends Error {
-  constructor(context, cause) {
-    const message = `[Model: ${context.model.type.name}] failed to convert to XML`;
-    super(message);
-    this.context = context;
-    this.cause = cause;
-    this.name = "ToXMLConversionError";
-  }
-}
-class PropertyToXMLConversionError extends ToXMLConversionError {
-  constructor(context, propertyContext, cause) {
-    super(context, cause);
-    this.propertyContext = propertyContext;
-    this.name = "PropertyToXMLConversionError";
-    this.message = `[Model: ${context.model.type.name}] failed to convert prop <${String(
-      propertyContext.property.name
-    )}> to XML`;
-  }
-}
-export {
-  FromXMLConversionError,
-  PropertyFromXMLConversionError,
-  PropertyToXMLConversionError,
-  ToXMLConversionError
-};
-//# sourceMappingURL=errors.js.map

package/dist/middleware.d.ts

@@ -1,10 +0,0 @@
-export type Middleware<C, T> = (context: C, next: () => T) => T;
-interface ChainableOptions<C, T> {
-    parent: ChainableOptions<C, T> | null;
-    middlewares: Middleware<C, T>[];
-}
-export declare function MiddlewareChain<C, T>(options: ChainableOptions<C, T>): Generator<Middleware<C, T>, void, unknown>;
-type MiddlewareChain<C, T> = Iterator<Middleware<C, T>>;
-export declare function resolve<C, T>(middlewares: MiddlewareChain<C, T>, context: C): T;
-export {};
-//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.js

@@ -1,25 +0,0 @@
-function* MiddlewareChain(options) {
-  do {
-    for (let index = options.middlewares.length - 1; index >= 0; index--) {
-      yield options.middlewares[index];
-    }
-    if (options.parent) options = options.parent;
-    else return;
-  } while (true);
-}
-function resolve(middlewares, context) {
-  const next = () => {
-    const { value: nextMiddleware, done } = middlewares.next();
-    if (done || !nextMiddleware) {
-      throw new Error("no more next middleware");
-    } else {
-      return nextMiddleware(context, next);
-    }
-  };
-  return next();
-}
-export {
-  MiddlewareChain,
-  resolve
-};
-//# sourceMappingURL=middleware.js.map

package/dist/model/built-ins.d.ts

@@ -1,3 +0,0 @@
-import { createModel } from '.';
-export default function registerBuiltIns(create: typeof createModel): void;
-//# sourceMappingURL=built-ins.d.ts.map

package/dist/model/built-ins.js

@@ -1,43 +0,0 @@
-import { getContent, fromContent } from "../xml/index.js";
-function registerBuiltIns(create) {
-  create(String, {
-    toXML(ctx) {
-      return {
-        elements: [fromContent(ctx.object, "string")]
-      };
-    },
-    fromXML(ctx) {
-      return String(getContent(ctx.xml.elements[0]));
-    }
-  });
-  create(Number, {
-    toXML(ctx) {
-      return {
-        elements: [fromContent(String(ctx.object), "number")]
-      };
-    },
-    fromXML(ctx) {
-      return Number(getContent(ctx.xml.elements[0]));
-    }
-  });
-  create(Boolean, {
-    toXML(ctx) {
-      return {
-        elements: [
-          {
-            type: "element",
-            name: "boolean",
-            ...fromContent(String(ctx.object))
-          }
-        ]
-      };
-    },
-    fromXML(ctx) {
-      return Boolean(getContent(ctx.xml.elements[0]));
-    }
-  });
-}
-export {
-  registerBuiltIns as default
-};
-//# sourceMappingURL=built-ins.js.map

package/dist/model/index.d.ts

@@ -1,69 +0,0 @@
-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 };
-export { Prop } from './property';
-//# sourceMappingURL=index.d.ts.map