xml-model 1.3.3 → 2.0.0-beta.2

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/_virtual/_rolldown/runtime.js

@@ -0,0 +1,8 @@
+//#region \0rolldown/runtime.js
+var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, { get: (a, b) => (typeof require !== "undefined" ? require : a)[b] }) : x)(function(x) {
+	if (typeof require !== "undefined") return require.apply(this, arguments);
+	throw Error("Calling `require` for \"" + x + "\" in an environment that doesn't expose the `require` function. See https://rolldown.rs/in-depth/bundling-cjs#require-external-modules for more details.");
+});
+//#endregion
+export { __commonJSMin, __require };

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,7 @@
-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";
-export {
-  FromXMLConversionError,
-  Model,
-  Prop,
-  PropertyFromXMLConversionError,
-  PropertyToXMLConversionError,
-  ToXMLConversionError,
-  default2 as XML,
-  createModel,
-  defaults,
-  getModel
-};
-//# sourceMappingURL=index.js.map
+import { isModel, model } from "./model.js";
+import XML, { ZXMLCommentNode, ZXMLElementNode, ZXMLNode, ZXMLRoot, ZXMLTextNode } from "./xml/xml-js.js";
+import { xml } from "./xml/schema-meta.js";
+import { normalizeCodecOptions, registerDefault } from "./xml/codec.js";
+import { xmlModel } from "./xml/model.js";
+import "./xml/index.js";
+export { XML, ZXMLCommentNode, ZXMLElementNode, ZXMLNode, ZXMLRoot, ZXMLTextNode, isModel, model, normalizeCodecOptions, registerDefault, xml, xmlModel };

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,75 @@
+import { z } from "zod";
+//#region src/model.ts
+var schemaSymbol = Symbol("model:schema");
+/** Marker placed on every class returned by `model()`. Used by `isModel()`. */
+var MODEL_MARKER = Symbol("model:marker");
+/** Stores the raw data object on model instances. */
+var DATA = Symbol("model:data");
+/** Returns true if `cls` is a class produced by `model()` (or a subclass of one). */
+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
+	});
+}
+/**
+* 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() })) {}
+*/
+function model(schema) {
+	class Base {
+		static dataSchema = schema;
+		static [MODEL_MARKER] = true;
+		static schema() {
+			if (!Object.prototype.hasOwnProperty.call(this, schemaSymbol)) this[schemaSymbol] = z.codec(this.dataSchema, z.instanceof(this), {
+				decode: (data) => {
+					return this.fromData(data);
+				},
+				encode: (instance) => {
+					return instance[DATA];
+				}
+			});
+			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;
+}
+//#endregion
+export { isModel, model };
+
+//# sourceMappingURL=model.js.map