xml-model 0.1.0

package/src/model/index.ts

@@ -0,0 +1,245 @@
+import "reflect-metadata";
+import type { Constructor } from "typescript-rtti";
+import { reflect } from "typescript-rtti";
+
+import { MiddlewareChain, resolve } from "../middleware";
+import {
+  XMLModelProperty,
+  XMLModelOptions,
+  XMLModelPropertyOptions,
+  PropertiesRecord,
+  XMLPropertiesRecord,
+} from "./types";
+import { getPropertyConversionOptions } from "./property";
+import { XMLRoot } from "../types";
+import XML from "../xml";
+import { defaults } from "../defaults";
+
+function* ParentChain(constructor: Constructor<unknown>) {
+  let parent = Object.getPrototypeOf(constructor);
+  if (parent === constructor) {
+    return;
+  }
+  while (parent) {
+    yield parent as Constructor<unknown>;
+    const _parent = Object.getPrototypeOf(constructor);
+    if (parent === _parent) {
+      return;
+    }
+    parent = _parent;
+  }
+  return;
+}
+
+function getParentModel(model: XMLModel<any>) {
+  for (const constructor of ParentChain(model.type)) {
+    const model = findModel(constructor);
+    if (model) {
+      return model as XMLModel<any>;
+    }
+  }
+  return null;
+}
+
+export interface XMLModelConversionOptions<T> {
+  fromXML?: XMLModelOptions<T>["fromXML"]["middlewares"][number];
+  tagname?: string;
+  toXML?: XMLModelOptions<T>["toXML"]["middlewares"][number];
+}
+
+export class XMLModel<T = any> {
+  options: XMLModelOptions<T>;
+  constructor(
+    readonly type: Constructor<T>,
+    options: XMLModelConversionOptions<T>
+  ) {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const model = this;
+    let parent: XMLModel<any> | null | undefined = undefined;
+    const getParent = () => {
+      if (typeof parent === "undefined") parent = getParentModel(this);
+      return parent;
+    };
+    let propertiesLoaded = false;
+    const properties: XMLModelOptions<T>["properties"] = {
+      options: new Map<XMLModelProperty<T>, XMLModelPropertyOptions<T>>(),
+      fromXML: {
+        get parent() {
+          return getParent()?.options.properties.fromXML || null;
+        },
+        middlewares: [
+          (context, next) => {
+            const record: PropertiesRecord<T> = getParent() ? next() : {};
+            properties.options.forEach((property) => {
+              const xml = context.xml;
+              const elements = property.resolveElements({
+                model,
+                xml,
+                property,
+              });
+              record[property.name] = property.fromXML({
+                model,
+                xml: context.xml,
+                property,
+                elements,
+              });
+            });
+            return record;
+          },
+        ],
+      },
+      toXML: {
+        get parent() {
+          return getParent()?.options.properties.toXML || null;
+        },
+        middlewares: [
+          (context, next) => {
+            const record: XMLPropertiesRecord<T> = getParent() ? next() : {};
+            properties.options.forEach((options) => {
+              record[options.name] = options.toXML({
+                model,
+                object: context.object,
+
+                property: options,
+                value: context.object[options.name],
+              });
+            });
+            return record;
+          },
+        ],
+      },
+    };
+    const loadProperties = () => {
+      const props = reflect(this.type).ownProperties.filter(
+        (prop) =>
+          typeof prop.host.constructor.prototype[prop.name] !== "function"
+      ); // filter out methods like String.prototype.concat etc... that are seen as properties
+
+      props.forEach((property) => {
+        const options = getPropertyConversionOptions(
+          this.type,
+          property.name as XMLModelProperty<T>
+        );
+        if (!options.ignored) {
+          properties.options.set(property.name as XMLModelProperty<T>, options);
+        }
+      });
+      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 (!getParent()) {
+      this.options.fromXML.middlewares.push((...args) =>
+        defaults.fromXML(...args)
+      );
+      this.options.toXML.middlewares.push((...args) => defaults.toXML(...args));
+    }
+    if (options.fromXML) this.options.fromXML.middlewares.push(options.fromXML);
+    if (options.toXML) this.options.toXML.middlewares.push(options.toXML);
+  }
+  fromXML(xml: XMLRoot | string) {
+    const _xml = typeof xml === "string" ? XML.parse(xml) : xml;
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    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);
+  }
+  toXML(instance: object) {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const model = this;
+    if (instance instanceof this.type || instance.constructor === this.type) {
+      // intanceof won't work with type "String" for example
+      const context = {
+        object: instance as unknown as T,
+        get properties() {
+          const propContext = {
+            object: instance,
+            model,
+          };
+          return resolve(
+            MiddlewareChain(model.options.properties.toXML),
+            propContext as any
+          );
+        },
+        model: this,
+      };
+      return resolve(MiddlewareChain(this.options.toXML), context);
+    } else {
+      throw new TypeError(
+        `provided object is not an instance of ${this.type.name}`
+      );
+    }
+  }
+  get reflectedClass() {
+    return reflect(this.type);
+  }
+}
+
+export function createModel<T>(
+  type: Constructor<T>,
+  options: XMLModelConversionOptions<T>
+): XMLModel<T> {
+  if (findModel(type)) {
+    throw new TypeError(`a model for type ${type.name} already exists`);
+  }
+  const model = new XMLModel(type, options);
+  Models.set(type, model as XMLModel<unknown>);
+  return model;
+}
+
+type ModelID<T> = Constructor<T>;
+export const Models = new Map<ModelID<unknown>, XMLModel<unknown>>();
+
+export function findModel<T>(id: ModelID<T>) {
+  return Models.get(id) as XMLModel<T> | undefined;
+}
+
+export function getModel<T>(id: ModelID<T>) {
+  const model = findModel(id);
+  if (model) return model;
+  else throw new TypeError(`couln't find model for type ${id.name}`);
+}
+
+// Model decorator
+function ModelDecoratorFactory<T>(options?: XMLModelConversionOptions<T>) {
+  return function (constructor: Constructor<T>): void {
+    findModel<T>(constructor) || createModel<T>(constructor, options || {});
+  };
+}
+export { ModelDecoratorFactory as Model };
+export { Prop } from "./property";
+
+import "../defaults/models";

package/src/model/property.ts

@@ -0,0 +1,104 @@
+import type { Constructor } from "typescript-rtti";
+import { reflect } from "typescript-rtti";
+
+import type {
+  XMLModelProperty,
+  XMLModelPropertyOptions,
+  CreateXMLModelPropertyOptions,
+} from "./types";
+import { defaults } from "../defaults";
+
+function resolvePropertyConversionOptions<T>(
+  options: CreateXMLModelPropertyOptions<T>,
+  constructor: Constructor<T>,
+  property: XMLModelProperty<T>
+) {
+  const _options: XMLModelPropertyOptions<T> = {
+    name: property as keyof T,
+    get reflected() {
+      return reflect(constructor).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?.sourceElements) {
+    const _sourceElements = options.sourceElements;
+    if (typeof _sourceElements === "string") {
+      _options.isSourceElement = (element) => element.name === _sourceElements;
+    } else if (_sourceElements && _sourceElements instanceof RegExp) {
+      _options.isSourceElement = (element) =>
+        _sourceElements.test(element.name || "");
+    } else {
+      _options.isSourceElement = _sourceElements;
+    }
+  }
+
+  return _options;
+}
+
+const PropertyOptions = new Map<
+  Constructor<any>,
+  Map<XMLModelProperty<any>, XMLModelPropertyOptions<any>>
+>();
+
+function storePropertyConversionOptions<T>(
+  constructor: Constructor<T>,
+  property: XMLModelProperty<T>,
+  options: XMLModelPropertyOptions<T>
+) {
+  let map = PropertyOptions.get(constructor);
+  if (!map) {
+    map = new Map<
+      XMLModelProperty<unknown>,
+      XMLModelPropertyOptions<unknown>
+    >();
+    PropertyOptions.set(constructor, map);
+  }
+  map.set(property, options);
+}
+
+function findPropertyConversionOptions<T>(
+  constructor: Constructor<T>,
+  property: XMLModelProperty<T>
+) {
+  const options = PropertyOptions.get(constructor) as
+    | Map<XMLModelProperty<T>, XMLModelPropertyOptions<T>>
+    | undefined;
+  if (options) {
+    return options.get(property);
+  }
+}
+
+export function getPropertyConversionOptions<T>(
+  constructor: Constructor<T>,
+  property: XMLModelProperty<T>
+) {
+  const options = findPropertyConversionOptions(constructor, property);
+  return options || resolvePropertyConversionOptions({}, constructor, property);
+}
+
+function PropDecoratorFactory<T = any>(
+  options?: CreateXMLModelPropertyOptions<T>
+) {
+  return function (prototype: any, property: XMLModelProperty<T>) {
+    const _options = resolvePropertyConversionOptions(
+      options || {},
+      prototype.constructor,
+      property
+    );
+    storePropertyConversionOptions(prototype.constructor, property, _options);
+  };
+}
+export { PropDecoratorFactory as Prop };

package/src/model/types.ts

@@ -0,0 +1,99 @@
+import type { ReflectedProperty } from "typescript-rtti";
+import type { XMLRoot, XMLElement } from "../types";
+import type { Middleware } from "../middleware";
+import type { XMLModel } from "./index";
+
+/* PROPERTIES */
+export type XMLModelProperty<T> = Extract<keyof T, string>;
+
+export type PropertiesRecord<T> = {
+  [key in keyof T]?: T[key];
+};
+
+export type XMLPropertiesRecord<T> = {
+  [key in keyof T]?: XMLRoot;
+};
+
+export interface PropertyToXMLContext<T>
+  extends Omit<toXMLContext<T>, "properties"> {
+  property: XMLModelPropertyOptions<T>;
+  value: T[keyof T]; // FIXME ???
+}
+
+export interface PropertyFromXMLContext<T>
+  extends Omit<fromXMLContext<T>, "properties"> {
+  property: XMLModelPropertyOptions<T>;
+  elements: XMLElement[];
+}
+export interface XMLModelPropertyOptions<T> {
+  name: keyof T;
+  reflected: ReflectedProperty;
+  tagname: string;
+  ignored: boolean;
+  inline: boolean;
+  // from XML
+  isSourceElement: (
+    element: XMLElement,
+    context: Omit<PropertyFromXMLContext<T>, "elements">
+  ) => boolean;
+  resolveElements: (
+    context: Omit<PropertyFromXMLContext<T>, "elements">
+  ) => XMLElement[];
+  fromXML: (context: PropertyFromXMLContext<T>) => T[keyof T];
+  // to XML
+  toXML: (context: PropertyToXMLContext<T>) => XMLRoot;
+}
+
+export interface CreateXMLModelPropertyOptions<T> {
+  tagname?: string;
+  sourceElements?:
+    | string
+    | RegExp
+    | XMLModelPropertyOptions<T>["isSourceElement"];
+  resolveElements?: XMLModelPropertyOptions<T>["resolveElements"];
+  toXML?: XMLModelPropertyOptions<T>["toXML"];
+  fromXML?: XMLModelPropertyOptions<T>["fromXML"];
+  inline?: boolean;
+  ignore?: boolean;
+}
+
+/* MODEL */
+interface ConversionOptions<C, T> {
+  parent: ConversionOptions<C, T> | null;
+  middlewares: Middleware<C, T>[];
+}
+export interface fromXMLContext<T> {
+  xml: XMLRoot;
+  properties: PropertiesRecord<T>;
+  model: XMLModel<T>;
+}
+
+export interface toXMLContext<T> {
+  object: T;
+  properties: XMLPropertiesRecord<T>;
+  model: XMLModel<T>;
+}
+export interface XMLModelOptions<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>;
+  tagname: string;
+}
+
+export interface CreateXMLModelOptions<T> {
+  fromXML?: XMLModelOptions<T>["fromXML"]["middlewares"][number];
+  tagname?: string;
+  toXML?: XMLModelOptions<T>["toXML"]["middlewares"][number];
+}
+
+export { XMLModel };

package/src/model.spec.ts

@@ -0,0 +1,178 @@
+import "mocha";
+import { expect, assert } from "chai";
+
+import { Model, Prop, getModel } from "./model";
+import XML from "./xml";
+import { reflect, ReflectedClass } from "typescript-rtti";
+import { UnknownRecord } from "./types";
+
+@Model({
+  fromXML({ model, properties }) {
+    return new model.type(properties);
+  },
+})
+class Book {
+  name: string;
+  nbPages: number;
+  constructor(options: { name: string; nbPages: number }) {
+    this.name = options.name;
+    this.nbPages = options.nbPages;
+  }
+  equals(book: Book) {
+    if (this.name !== book.name) return false;
+    if (this.nbPages !== book.nbPages) return false;
+    return true;
+  }
+}
+
+@Model<Library>({
+  fromXML({ model, properties }) {
+    return new model.type(properties.name, ...(properties.books as Book[]));
+  },
+})
+class Library {
+  name: string;
+  books: Book[] = [];
+  constructor(name: string, ...books: Book[]) {
+    this.name = name;
+    this.books.push(...books);
+  }
+  equals(library: Library) {
+    if (this.name !== library.name) return false;
+    if (this.books.length !== library.books.length) return false;
+    for (let index = 0; index < this.books.length; index++) {
+      if (!this.books[index].equals(library.books[index])) return false;
+    }
+    return true;
+  }
+}
+
+describe("Library Example", () => {
+  const library = new Library("test");
+  for (let i = 1; i <= 4; i++) {
+    const book = new Book({ name: `Book #${i}`, nbPages: Math.pow(10, i) });
+    library.books.push(book);
+  }
+  const libraryXMLString = XML.stringify(
+    XML.parse(
+      `<library>
+    <name>${library.name}</name>
+    <books>
+      ${library.books
+        .map(
+          (book) =>
+            `     <book>
+        <name>${book.name}</name>
+        <nb-pages>${book.nbPages}</nb-pages>
+      </book>`
+        )
+        .join("")}
+    </books>
+</library>`
+    )
+  );
+
+  it("Object -> XML", () => {
+    const xml = getModel(Library).toXML(library);
+    expect(XML.stringify(xml)).to.equal(libraryXMLString);
+  });
+  it("XML -> Object", () => {
+    const parsedLibrary = getModel(Library).fromXML(libraryXMLString);
+    expect(parsedLibrary instanceof Library).to.be.true;
+    expect(library.equals(parsedLibrary as Library)).to.be.true;
+  });
+});
+
+@Model({
+  fromXML({ model, properties }) {
+    return new model.type(properties);
+  },
+})
+class A {
+  propA: string = "";
+  propB: boolean = true;
+  @Prop({ tagname: "b", inline: true })
+  propC: B[] = [];
+  @Prop({ tagname: "propd" })
+  propD: 0 | 1 = 0;
+  equals(a: A) {
+    //
+    if (
+      this.propA !== a.propA ||
+      this.propB !== a.propB ||
+      this.propC.length !== a.propC.length ||
+      this.propD !== a.propD
+    )
+      return false;
+    for (let i = 0; i < this.propC.length; i++) {
+      if (!this.propC[i].equals(a.propC[i])) return false;
+    }
+    return true;
+  }
+  constructor(record?: UnknownRecord) {
+    if (record)
+      Object.entries(record).forEach(([key, val]) => {
+        (this[key as keyof A] as any) = val as any;
+      });
+  }
+}
+
+@Model({
+  fromXML({ model, properties }) {
+    return new model.type(properties);
+  },
+})
+class B {
+  propA: number = 0;
+  equals(b: B) {
+    return this.propA === b.propA;
+  }
+  constructor(record?: UnknownRecord) {
+    if (record)
+      Object.entries(record).forEach(([key, val]) => {
+        (this[key as keyof B] as any) = val as any;
+      });
+  }
+}
+
+describe("Edgy Cases", () => {
+  const instance = new A();
+  for (let i = 0; i < 8; i++) {
+    const b = new B();
+    b.propA = i;
+    instance.propC.push(b);
+  }
+
+  const instanceXMLString = XML.stringify(
+    XML.parse(`<a>
+  <prop-a>${instance.propA}</prop-a>
+  <prop-b>${instance.propB}</prop-b>
+  ${instance.propC.map((b) => `<b><prop-a>${b.propA}</prop-a></b>`).join("")}
+  <propd>${instance.propD}</propd>
+</a>`)
+  );
+
+  it("should give right type infos", () => {
+    const reflectedA = reflect(A) as unknown as ReflectedClass;
+    assert(reflectedA === <ReflectedClass>(<unknown>reflect(A)));
+    expect(reflectedA.getProperty("propA").type.isClass(String)).to.be.true;
+    expect(reflectedA.getProperty("propB").type.isClass(Boolean)).to.be.true;
+    const ModelAPropCType = reflectedA.getProperty("propC").type;
+    expect(
+      ModelAPropCType.is("array") && ModelAPropCType.elementType.isClass(B)
+    ).to.be.true;
+    const ModelAPropDType = reflectedA.getProperty("propD").type;
+    expect(ModelAPropDType.is("union")).to.be.true;
+  });
+
+  it("XML -> Object", () => {
+    const parsed = getModel(A).fromXML(instanceXMLString);
+    expect(parsed instanceof A).to.be.true;
+    const equals = instance.equals(parsed as A);
+    expect(equals).to.be.true;
+  });
+  it("Object -> XML", () => {
+    const xml = getModel(A).toXML(instance);
+    expect(XML.stringify(xml)).to.equal(instanceXMLString);
+  });
+});

package/src/types.ts

@@ -0,0 +1,8 @@
+export type { Constructor } from "typescript-rtti";
+
+export type UnknownRecord = Record<string | number | symbol, unknown>;
+export type UnknownObject = object; // Record<string | number | symbol, unknown>; // don't works with class' instances
+
+import type { Element as _XMLElement } from "xml-js";
+export type XMLElement = _XMLElement;
+export type XMLRoot = { elements: XMLElement[] };