xml-model 1.3.2 → 2.0.0-beta.1

package/README.md

@@ -1,52 +1,56 @@
 # XML Model
 
-## Usage
+**[📖 Documentation](https://mathistld.github.io/xml-model/)**
 
-Needs [typescript-rtti](https://github.com/typescript-rtti/typescript-rtti) to retrieve type at runtime.
+**[🧑‍💻 Source on GitHub](https://github.com/MathisTLD/xml-model)**
 
-To build something that relies in `xml-model` with vite
+## Installation
 
-```typescript
-import { defineConfig } from "vite";
-import XMLModelVitePlugin from "xml-model/vite";
+xml-model requires [Zod v4](https://zod.dev) as a peer dependency.
 
-export default defineConfig({
-  plugins: [
-    // see options in JSDoc
-    // note that is tsconfig that includes your source files is not tsconfig.json you MUST use the tsconfig option
-    XMLModelVitePlugin(),
-  ],
-  // ... rest of the config
-});
+```bash
+npm install xml-model zod
 ```
 
-## Documentation
+<!-- #region what-is -->
 
-### Example
+## What is xml-model?
 
-```typescript
-import { Model, getModel, XML } from "xml-model";
+xml-model lets you define TypeScript classes that map directly to XML documents using [Zod](https://zod.dev) schemas. Annotate fields with `xml.attr()` for XML attributes, or use `xml.prop()` when you need to customise a child element's tagname, inline mode, or matching — plain Zod schemas work as-is for regular child elements. Then parse or serialise with a single method call.
 
-@Model({
-  fromXML(ctx) {
-    const instance = new MyClass();
-    if (ctx.properties.foo) instance.foo = ctx.properties.foo;
-    return instance;
-  },
-})
-class MyClass {
-  foo = "bar";
+```ts
+import { z } from "zod";
+import { xmlModel, xml } from "xml-model";
+
+class Book extends xmlModel(
+  z.object({
+    isbn: xml.attr(z.string(), { name: "isbn" }),
+    title: z.string(),
+    year: z.number(),
+  }),
+  { tagname: "book" },
+) {
+  label() {
+    return `${this.title} (${this.year})`;
+  }
 }
 
-const model = getModel(MyClass);
+// XML → class instance
+const book = Book.fromXML(`
+  <book isbn="978-0-7432-7356-5">
+    <title>Dune</title>
+    <year>1965</year>
+  </book>
+`);
 
-const a: MyClass = model.fromXML("<my-class><foo>test</foo></my-class>");
-console.log(JSON.stringify(a)); // {"foo":"test"}
+book.label(); // "Dune (1965)"
+book instanceof Book; // true
 
-const b = new MyClass();
-console.log(XML.stringify(model.toXML(b))); // <my-class><foo>bar</foo></my-class>
-b.foo = "other";
-console.log(XML.stringify(model.toXML(b))); // <my-class><foo>other</foo></my-class>
+// class instance → XML string
+Book.toXMLString(book);
+// <book isbn="978-0-7432-7356-5"><title>Dune</title><year>1965</year></book>
 ```
 
-See [source code](https://github.com/MathisTLD/xml-model) for more
+Field names are automatically converted to kebab-case XML tags (`publishedAt` → `<published-at>`). Extend classes with `.extend()` to build inheritance hierarchies — child instances remain `instanceof` the parent and inherit all methods.
+
+<!-- #endregion what-is -->

package/dist/index.d.ts

@@ -1,8 +1,4 @@
-import { default as XML } from './xml';
-export type { XMLElement, XMLRoot, Constructor } from './types';
-export { defaults } from './defaults';
-export { getModel, createModel, Model, Prop } from './model';
-export * from './errors';
-export * from 'typescript-rtti';
-export { XML };
+export { model, isModel } from './model';
+export type { ModelConstructor } from './model';
+export * from './xml';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,20 +1,21 @@
-import { defaults } from "./defaults.js";
-import { Model, createModel } from "./model/index.js";
-import { FromXMLConversionError, PropertyFromXMLConversionError, PropertyToXMLConversionError, ToXMLConversionError } from "./errors.js";
-export * from "typescript-rtti";
-import { default as default2 } from "./xml/index.js";
-import { Prop } from "./model/property.js";
-import { getModel } from "./model/registry.js";
+import { isModel, model } from "./model.js";
+import "./xml/index.js";
+import { XML, ZXMLCommentNode, ZXMLElementNode, ZXMLNode, ZXMLRoot, ZXMLTextNode } from "./xml/xml-js.js";
+import { normalizeCodecOptions, registerDefault } from "./xml/codec.js";
+import { xml } from "./xml/schema-meta.js";
+import { xmlModel } from "./xml/model.js";
 export {
-  FromXMLConversionError,
-  Model,
-  Prop,
-  PropertyFromXMLConversionError,
-  PropertyToXMLConversionError,
-  ToXMLConversionError,
-  default2 as XML,
-  createModel,
-  defaults,
-  getModel
+  XML,
+  ZXMLCommentNode,
+  ZXMLElementNode,
+  ZXMLNode,
+  ZXMLRoot,
+  ZXMLTextNode,
+  isModel,
+  model,
+  normalizeCodecOptions,
+  registerDefault,
+  xml,
+  xmlModel
 };
 //# sourceMappingURL=index.js.map

package/dist/model.d.ts

@@ -0,0 +1,53 @@
+import { z, GlobalMeta } from 'zod';
+/**
+ * Constructor type for model classes.
+ *
+ * `S`    — the ZodObject schema (drives field types)
+ * `Inst` — the actual instance type produced by `new`. Defaults to `z.infer<S>`.
+ *           `extend()` widens it to `InstanceType<Self> & z.infer<ExtendedSchema>`
+ *           so that parent class methods survive into child instances.
+ */
+export type ModelConstructor<S extends z.ZodObject<any> = z.ZodObject<any>, Inst extends z.infer<S> = z.infer<S>> = {
+    new (data: z.infer<S>): Inst;
+    readonly dataSchema: S;
+    /**
+     * Returns a ZodCodec that transforms parsed data into a class instance (and can go the other way around).
+     * Use inside xml.prop() or z.array(...).
+     */
+    schema<T extends abstract new (...args: any[]) => any>(this: T): z.ZodCodec<S, z.ZodCustom<InstanceType<T>, InstanceType<T>>>;
+    /**
+     * Override to customise instantiation — e.g. to inject extra constructor arguments.
+     * Called by from() instead of `new this(data)` directly.
+     */
+    fromData<T extends new (...args: any[]) => any>(this: T, data: z.output<S>): InstanceType<T>;
+    /**
+     * Returns the raw decoded data object stored on the instance — the same
+     * object that was passed to the constructor, including any non-enumerable
+     * symbol metadata (e.g. `XML_STATE`) that survived construction.
+     */
+    toData<T extends abstract new (...args: any[]) => any>(this: T, instance: InstanceType<T>): z.output<S>;
+    /**
+     * Creates a new model class that truly extends this one — inheriting its prototype
+     * chain and methods — while adding new schema fields.
+     *
+     * Pass an optional `meta` object (e.g. `xml.root({ tagname: "car" })`) to attach
+     * Zod schema metadata to the extended schema. Multiple codec metas compose with spread:
+     * `{ ...xml.root({ tagname: "car" }), ...otherCodec.meta({...}) }`
+     */
+    extend<Self extends ModelConstructor<S, Inst>, U extends z.core.$ZodLooseShape>(this: Self, extension: U, meta?: GlobalMeta): Omit<Self, keyof ModelConstructor<S, Inst>> & ModelConstructor<z.ZodObject<z.util.Extend<S["shape"], U>>, InstanceType<Self> & z.infer<z.ZodObject<z.util.Extend<S["shape"], U>>>>;
+};
+/** Stores the raw data object on model instances. */
+export declare const DATA: unique symbol;
+/** Returns true if `cls` is a class produced by `model()` (or a subclass of one). */
+export declare function isModel(cls: unknown): cls is ModelConstructor;
+/**
+ * Generic class factory. Creates a class with typed instance properties
+ * and codec-agnostic from()/to() methods.
+ *
+ * Codec-specific factories (e.g. xmlModel) wrap this and inject named helpers.
+ *
+ * @example
+ * class Book extends model(z.object({ title: z.string() })) {}
+ */
+export declare function model<S extends z.ZodObject<any>>(schema: S): ModelConstructor<S>;
+//# sourceMappingURL=model.d.ts.map

package/dist/model.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+const schemaSymbol = /* @__PURE__ */ Symbol("model:schema");
+const MODEL_MARKER = /* @__PURE__ */ Symbol("model:marker");
+const DATA = /* @__PURE__ */ Symbol("model:data");
+function isModel(cls) {
+  return typeof cls === "function" && MODEL_MARKER in cls;
+}
+function defineFieldAccessors(proto, keys) {
+  for (const key of keys) {
+    Object.defineProperty(proto, key, {
+      get() {
+        return this[DATA][key];
+      },
+      set(v) {
+        this[DATA][key] = v;
+      },
+      enumerable: true,
+      configurable: true
+    });
+  }
+}
+function model(schema) {
+  class Base {
+    static dataSchema = schema;
+    static [MODEL_MARKER] = true;
+    static schema() {
+      if (!Object.prototype.hasOwnProperty.call(this, schemaSymbol)) {
+        const codec = z.codec(this.dataSchema, z.instanceof(this), {
+          decode: (data) => {
+            return this.fromData(data);
+          },
+          encode: (instance) => {
+            return instance[DATA];
+          }
+        });
+        this[schemaSymbol] = codec;
+      }
+      return this[schemaSymbol];
+    }
+    static extend(extension, meta) {
+      let extended = this.dataSchema.extend(extension);
+      if (meta) extended = extended.meta(meta);
+      const Child = class extends this {
+        static dataSchema = extended;
+      };
+      defineFieldAccessors(Child.prototype, Object.keys(extension));
+      return Child;
+    }
+    static fromData(data) {
+      return new this(data);
+    }
+    static toData(instance) {
+      const data = instance[DATA];
+      if (!data) throw new Error("failed to retrieve instance data");
+      return data;
+    }
+    constructor(data) {
+      this[DATA] = data;
+    }
+  }
+  defineFieldAccessors(Base.prototype, Object.keys(schema.def.shape));
+  return Base;
+}
+export {
+  DATA,
+  isModel,
+  model
+};
+//# sourceMappingURL=model.js.map

package/dist/util/zod.d.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+export declare function isZodType(object: any): object is z.ZodType;
+export declare function getParentSchema(schema: z.ZodType): z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+//# sourceMappingURL=zod.d.ts.map

package/dist/util/zod.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+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;
+}
+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