xml-model 1.3.3 → 2.0.0-beta.2

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

package/dist/model/index.js

@@ -1,264 +0,0 @@
-import "../_virtual/Reflect.js";
-import { reflect } from "typescript-rtti";
-import { ToXMLConversionError, PropertyToXMLConversionError, FromXMLConversionError, PropertyFromXMLConversionError } from "../errors.js";
-import mergeMaps from "../util/merge-maps.js";
-import { resolve, MiddlewareChain } from "../middleware.js";
-import { getPropertyConversionOptions } from "./property.js";
-import { Prop } from "./property.js";
-import XML from "../xml/index.js";
-import { defaults } from "../defaults.js";
-import { findModel, registrerModel } from "./registry.js";
-import { getModel } from "./registry.js";
-import registerBuiltIns from "./built-ins.js";
-function* ParentChain(constructor) {
-  let parent = Object.getPrototypeOf(constructor);
-  if (parent === constructor) {
-    return;
-  }
-  while (parent) {
-    yield parent;
-    const _parent = Object.getPrototypeOf(constructor);
-    if (parent === _parent) {
-      return;
-    }
-    parent = _parent;
-  }
-  return;
-}
-function getParentModel(model) {
-  if (model.options.parent) return model.options.parent;
-  for (const constructor of ParentChain(model.type)) {
-    const model2 = findModel(constructor);
-    if (model2) {
-      return model2;
-    }
-  }
-  return null;
-}
-class XMLModel {
-  constructor(type, options) {
-    this.type = type;
-    const model = this;
-    let parent = void 0;
-    const getParent = () => {
-      if (typeof parent === "undefined") parent = getParentModel(this);
-      return parent;
-    };
-    let propertiesLoaded = false;
-    const properties = {
-      options: /* @__PURE__ */ new Map(),
-      fromXML: {
-        get parent() {
-          return getParent()?.options.properties.fromXML || null;
-        },
-        middlewares: [
-          (context, next) => {
-            const record = getParent() ? next() : {};
-            properties.options.forEach((property) => {
-              const xml = context.xml;
-              const elements = property.resolveElements({
-                model,
-                xml,
-                property
-              });
-              const propertyFromXMLContext = {
-                model,
-                xml: context.xml,
-                property,
-                elements
-              };
-              try {
-                record[property.name] = property.fromXML(propertyFromXMLContext);
-              } catch (error) {
-                if (error instanceof FromXMLConversionError) {
-                  throw error;
-                } else {
-                  throw new PropertyFromXMLConversionError(context, propertyFromXMLContext, error);
-                }
-              }
-            });
-            return record;
-          }
-        ]
-      },
-      toXML: {
-        get parent() {
-          return getParent()?.options.properties.toXML || null;
-        },
-        middlewares: [
-          (context, next) => {
-            const record = getParent() ? next() : {};
-            properties.options.forEach((options2) => {
-              const propertyToXMLContext = {
-                model,
-                object: context.object,
-                property: options2,
-                value: context.object[options2.name]
-              };
-              try {
-                record[options2.name] = options2.toXML(propertyToXMLContext);
-              } catch (error) {
-                if (error instanceof ToXMLConversionError) {
-                  throw error;
-                } else {
-                  throw new PropertyToXMLConversionError(context, propertyToXMLContext, error);
-                }
-              }
-            });
-            return record;
-          }
-        ]
-      }
-    };
-    const loadProperties = () => {
-      const props = this.reflectedClass.ownProperties.filter(
-        (prop) => typeof prop.host.constructor.prototype[prop.name] !== "function"
-      );
-      props.forEach((property) => {
-        const options2 = getPropertyConversionOptions(
-          this.type,
-          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);
-        }
-      });
-      propertiesLoaded = true;
-    };
-    this.options = {
-      get properties() {
-        if (!propertiesLoaded) loadProperties();
-        return properties;
-      },
-      fromXML: {
-        middlewares: [],
-        get parent() {
-          return getParent()?.options.fromXML || null;
-        }
-      },
-      toXML: {
-        middlewares: [],
-        get parent() {
-          return getParent()?.options.toXML || null;
-        }
-      },
-      get tagname() {
-        return options.tagname || defaults.tagnameFromModel(model);
-      }
-    };
-    if (options.parent) this.options.parent = options.parent;
-    if (!getParent()) {
-      this.options.fromXML.middlewares.push((ctx) => defaults.fromXML(ctx));
-      this.options.toXML.middlewares.push((ctx) => defaults.toXML(ctx));
-    }
-    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;
-    const context = {
-      xml: _xml,
-      get properties() {
-        const propContext = {
-          xml: _xml,
-          model
-        };
-        return resolve(MiddlewareChain(model.options.properties.fromXML), propContext);
-      },
-      model
-    };
-    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) {
-      const context = {
-        object: instance,
-        get properties() {
-          const propContext = {
-            object: instance,
-            model
-          };
-          return resolve(MiddlewareChain(model.options.properties.toXML), propContext);
-        },
-        model: this
-      };
-      return resolve(MiddlewareChain(this.options.toXML), context);
-    } else {
-      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);
-    this.options.properties.options.forEach((options, key) => {
-      ownProperties.set(
-        key,
-        new Proxy(options, {
-          get: (target, p, reciever) => {
-            if (p === "model") return this;
-            else return Reflect.get(target, p, reciever);
-          }
-        })
-        // FIXME: is typing ok ?
-      );
-    });
-    const res = parent ? mergeMaps(parent.resolveAllProperties(), ownProperties) : ownProperties;
-    return res;
-  }
-}
-function createModel(type, options) {
-  if (findModel(type)) {
-    throw new TypeError(`a model for type ${type.name} already exists`);
-  }
-  const model = new XMLModel(type, options);
-  registrerModel(model);
-  return model;
-}
-function ModelDecoratorFactory(options) {
-  return function(constructor) {
-    if (!findModel(constructor)) createModel(constructor, options || {});
-  };
-}
-registerBuiltIns(createModel);
-export {
-  ModelDecoratorFactory as Model,
-  Prop,
-  XMLModel,
-  createModel,
-  getModel,
-  getParentModel
-};
-//# sourceMappingURL=index.js.map

package/dist/model/property.d.ts

@@ -1,18 +0,0 @@
-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/property.js

@@ -1,67 +0,0 @@
-import { reflect } from "typescript-rtti";
-import { defaults } from "../defaults.js";
-import isRegExp from "../util/is-regexp.js";
-function resolvePropertyConversionOptions(options, constructor, property) {
-  const _options = {
-    name: property,
-    get reflected() {
-      const reflectedClass = reflect(constructor);
-      return reflectedClass.getOwnProperty(property) || reflectedClass.getProperty(property);
-    },
-    get tagname() {
-      return options.tagname || defaults.tagnameFromProperty(this);
-    },
-    inline: !!options.inline,
-    ignored: !!options.ignore,
-    isSourceElement: (...args) => defaults.propertySourceElementsFilter(...args),
-    resolveElements: options.resolveElements ? options.resolveElements : (...args) => defaults.propertyResolveSourceElements(...args),
-    fromXML: (context) => (options.fromXML ?? defaults.propertyFromXML)(context),
-    toXML: (context) => (options.toXML ?? defaults.propertyToXML)(context)
-  };
-  if (options?.model) _options.model = options.model;
-  if (options?.sourceElements) {
-    const _sourceElements = options.sourceElements;
-    if (typeof _sourceElements === "string") {
-      _options.isSourceElement = (element) => element.name === _sourceElements;
-    } else if (isRegExp(_sourceElements)) {
-      _options.isSourceElement = (element) => _sourceElements.test(element.name || "");
-    } else if (_sourceElements) {
-      _options.isSourceElement = _sourceElements;
-    }
-  }
-  return _options;
-}
-const PropertyOptions = /* @__PURE__ */ new Map();
-function storePropertyConversionOptions(constructor, property, options) {
-  let map = PropertyOptions.get(constructor);
-  if (!map) {
-    map = /* @__PURE__ */ new Map();
-    PropertyOptions.set(constructor, map);
-  }
-  map.set(property, options);
-}
-function findPropertyConversionOptions(constructor, property) {
-  const options = PropertyOptions.get(constructor);
-  if (options) {
-    return options.get(property);
-  }
-}
-function getPropertyConversionOptions(constructor, property) {
-  const options = findPropertyConversionOptions(constructor, property);
-  return options ?? resolvePropertyConversionOptions({}, constructor, property);
-}
-function PropDecoratorFactory(options) {
-  return function(prototype, property) {
-    const _options = resolvePropertyConversionOptions(
-      options ?? {},
-      prototype.constructor,
-      property
-    );
-    storePropertyConversionOptions(prototype.constructor, property, _options);
-  };
-}
-export {
-  PropDecoratorFactory as Prop,
-  getPropertyConversionOptions
-};
-//# sourceMappingURL=property.js.map

package/dist/model/registry.d.ts

@@ -1,9 +0,0 @@
-import { Constructor } from 'typescript-rtti';
-import { XMLModel } from '.';
-type ModelID<T> = Constructor<T>;
-export declare const Models: Map<ModelID<unknown>, XMLModel<unknown>>;
-export declare function registrerModel(model: XMLModel<unknown>): Map<ModelID<unknown>, XMLModel<unknown>>;
-export declare function findModel<T>(id: ModelID<T>): XMLModel<T> | undefined;
-export declare function getModel<T>(id: ModelID<T>): XMLModel<T>;
-export {};
-//# sourceMappingURL=registry.d.ts.map

package/dist/model/registry.js

@@ -1,19 +0,0 @@
-const Models = /* @__PURE__ */ new Map();
-function registrerModel(model) {
-  return Models.set(model.type, model);
-}
-function findModel(id) {
-  return Models.get(id);
-}
-function getModel(id) {
-  const model = findModel(id);
-  if (model) return model;
-  else throw new TypeError(`couldn't find model for type ${id.name}`);
-}
-export {
-  Models,
-  findModel,
-  getModel,
-  registrerModel
-};
-//# sourceMappingURL=registry.js.map

package/dist/model/types.d.ts

@@ -1,109 +0,0 @@
-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: {
-        fromXML: ConversionOptions<Omit<fromXMLContext<T>, "properties">, PropertiesRecord<T>>;
-        toXML: ConversionOptions<Omit<toXMLContext<T>, "properties">, XMLPropertiesRecord<T>>;
-        options: Map<XMLModelProperty<T>, XMLModelPropertyOptions<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 };
-//# sourceMappingURL=types.d.ts.map