@vaadin/hilla-models 24.5.0-alpha5

package/.lintstagedrc.js

@@ -0,0 +1,6 @@
+import { commands, extensions } from '../../../.lintstagedrc.js';
+
+export default {
+  [`src/**/*.{${extensions}}`]: commands,
+  [`test/**/*.{${extensions}}`]: commands,
+};

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,24 @@
+# Hilla Models
+
+[![Latest Stable Version](https://img.shields.io/npm/v/@vaadin/hilla-models.svg)](https://www.npmjs.com/package/@vaadin/hilla-models)
+
+A collection of utilities to build data models that could be used for data binging, validation, backend integration etc. 
+
+A part of the Hilla project.
+
+## Installation
+
+```bash
+$ npm install @vaadin/hilla-models
+```
+
+## Contribution
+
+Read the [contributing guide](https://vaadin.com/docs/latest/contributing-docs/overview) to learn about our development process, how to propose bugfixes and improvements, and how to test your changes.
+
+## License
+
+Apache License 2.0
+
+Vaadin collects development time usage statistics to improve this product.
+For details and to opt-out, see https://github.com/vaadin/vaadin-usage-statistics.

package/builders.d.ts

@@ -0,0 +1,160 @@
+import type { EmptyObject } from 'type-fest';
+import type { ObjectModel } from './core';
+import { type AnyObject, type DefaultValueProvider, type Model, type ModelMetadata } from './model.js';
+/**
+ * The options for creating the model property.
+ */
+export type ModelBuilderPropertyOptions = Readonly<{
+    meta?: ModelMetadata;
+}>;
+declare const $model: unique symbol;
+/**
+ * The flags for the model constructor that allow to determine specific characteristics of the model.
+ */
+export type Flags = {
+    /**
+     * Defines if the model is named.
+     */
+    named: boolean;
+    /**
+     * The keys of the self-referencing properties.
+     *
+     * @remarks
+     * The problem of self-reference models is that they cannot have intermediate
+     * type because during the property definition, the model itself is in the
+     * middle of construction. That's why we define the specific type-only flag
+     * that allows us to know which model properties are self-referenced. We can
+     * safely set it in the end of building using this flag.
+     */
+    selfRefKeys: keyof any;
+};
+/**
+ * A builder class for creating all basic models.
+ *
+ * @typeParam V - The final value type of the model.
+ * @typeParam EX - The extra properties of the model.
+ * @typeParam F - The flags for the model constructor that allow to determine
+ * specific characteristics of the model.
+ */
+export declare class CoreModelBuilder<V, EX extends AnyObject = EmptyObject, F extends Flags = {
+    named: false;
+    selfRefKeys: never;
+}> {
+    protected readonly [$model]: Model<V, EX>;
+    /**
+     * @param base - The base model to extend.
+     * @param defaultValueProvider - The function that provides the default value
+     * for the model.
+     */
+    constructor(base: Model, defaultValueProvider?: (model: Model<V, EX>) => V);
+    /**
+     * Appends metadata to the model.
+     *
+     * @param value - The metadata to append.
+     * @returns The current builder instance.
+     */
+    meta(value: ModelMetadata): this;
+    /**
+     * Defines a new property on the model. The property serves the purposes of
+     * storing the extra data for specific types of models.
+     *
+     * @remarks
+     * The key of the property should be a symbol to avoid conflicts with
+     * properties defined via
+     * {@link ObjectModelBuilder}.
+     *
+     * @param key - The key of the property.
+     * @param value - The descriptor of the property.
+     * @returns The current builder instance.
+     */
+    define<DK extends symbol, DV>(key: DK, value: TypedPropertyDescriptor<DV>): CoreModelBuilder<V, EX & Readonly<Record<DK, DV>>, F>;
+    /**
+     * Sets the default value provider for the model. This is an alternative way
+     * to provide the default value for the model if for some reason using the
+     * constructor parameter is undesired.
+     *
+     * @param defaultValueProvider - The function that provides the default value
+     * for the model.
+     * @returns The current builder instance.
+     */
+    defaultValueProvider(defaultValueProvider: DefaultValueProvider<V, EX>): this;
+    /**
+     * Sets the name of the model. The name is used for debugging purposes and is
+     * displayed in the string representation. Setting the name is required;
+     * otherwise, the {@link CoreModelBuilder.build} method won't be available.
+     *
+     * @param name - The name of the model.
+     * @returns The current builder instance.
+     */
+    name(name: string): CoreModelBuilder<V, EX, {
+        named: true;
+        selfRefKeys: F['selfRefKeys'];
+    }>;
+    /**
+     * Builds the model. On the typing level, it checks if all the model parts are
+     * set correctly, and raises an error if not.
+     *
+     * @returns The model.
+     */
+    build(this: F['named'] extends true ? this : never): Model<V, EX>;
+}
+/**
+ * A builder class for creating object models.
+ *
+ * @typeParam V - The final value type of the model.
+ * @typeParam CV - The current value type of the model. It changes as the model
+ * is being built and defines if the
+ * {@link ObjectModelBuilder.build} method can be called.
+ * @typeParam EX - The extra properties of the model.
+ * @typeParam F - The flags for the model constructor that allow to determine
+ * specific characteristics of the model.
+ */
+export declare class ObjectModelBuilder<V extends AnyObject, CV extends AnyObject = EmptyObject, EX extends AnyObject = EmptyObject, F extends Flags = {
+    named: false;
+    selfRefKeys: never;
+}> extends CoreModelBuilder<V, EX, F> {
+    constructor(base: Model);
+    /**
+     * The method that should follow the {@link m.extend} method. It allows to
+     * declare the extension for the model and properly name it.
+     *
+     * @param name - The name of the model.
+     */
+    object<NV extends AnyObject>(this: F['named'] extends false ? this : never, name: string): ObjectModelBuilder<NV & V, CV, EX, {
+        named: true;
+        selfRefKeys: F['selfRefKeys'];
+    }>;
+    /**
+     * {@inheritDoc CoreModelBuilder.define}
+     */
+    ['define']: <DK extends symbol, DV>(key: DK, value: TypedPropertyDescriptor<DV>) => ObjectModelBuilder<V, CV, EX & Readonly<Record<DK, DV>>, F>;
+    /**
+     * {@inheritDoc CoreModelBuilder.meta}
+     */
+    ['meta']: (value: ModelMetadata) => this;
+    /**
+     * Defines a new model property on the model. Unlike the
+     * {@link ObjectModelBuilder.define}, this property is public and allows the
+     * user to interact with the model data structure. It also updates the current
+     * value type of the model to make it closer to the final value type.
+     *
+     * @param key - The key of the property.
+     * @param model - The model of the property value. You can also provide a
+     * function that produces the model based on the current model.
+     * @param options - Additional options for the property.
+     *
+     * @returns The current builder instance updated with the new property type.
+     * In case there is a self-referencing property, the {@link Flags.selfRefKeys}
+     * flag for the specific property is set.
+     */
+    property<PK extends string & keyof V, EXK extends AnyObject = EmptyObject>(key: PK, model: Model<V[PK], EXK> | ((model: Model<V, EX & Readonly<Record<PK, Model<V[PK], EXK>>>>) => Model<V[PK], EXK>), options?: ModelBuilderPropertyOptions): Extract<V[PK], V> extends never ? ObjectModelBuilder<V, CV & Readonly<Record<PK, V[PK]>>, EX & Readonly<Record<PK, Model<V[PK], EXK>>>, F> : ObjectModelBuilder<V, CV & Readonly<Record<PK, V[PK]>>, EX, {
+        named: F['named'];
+        selfRefKeys: F['selfRefKeys'] | PK;
+    }>;
+    /**
+     * {@inheritDoc CoreModelBuilder.build}
+     */
+    build: (this: F['named'] extends true ? (CV extends V ? this : never) : never) => ObjectModel<V, EX, F['selfRefKeys']>;
+}
+export {};
+//# sourceMappingURL=builders.d.ts.map

package/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["src/builders.ts"],"names":[],"mappings":"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"}

package/builders.js

@@ -0,0 +1,147 @@
+import {
+  $defaultValue,
+  $key,
+  $meta,
+  $name,
+  $owner
+} from "./model.js";
+const { create, defineProperty } = Object;
+const $model = Symbol("model");
+class CoreModelBuilder {
+  [$model];
+  /**
+   * @param base - The base model to extend.
+   * @param defaultValueProvider - The function that provides the default value
+   * for the model.
+   */
+  constructor(base, defaultValueProvider) {
+    this[$model] = create(base);
+    if (defaultValueProvider) {
+      this.defaultValueProvider(defaultValueProvider);
+    }
+  }
+  /**
+   * Appends metadata to the model.
+   *
+   * @param value - The metadata to append.
+   * @returns The current builder instance.
+   */
+  meta(value) {
+    this.define($meta, { value });
+    return this;
+  }
+  /**
+   * Defines a new property on the model. The property serves the purposes of
+   * storing the extra data for specific types of models.
+   *
+   * @remarks
+   * The key of the property should be a symbol to avoid conflicts with
+   * properties defined via
+   * {@link ObjectModelBuilder}.
+   *
+   * @param key - The key of the property.
+   * @param value - The descriptor of the property.
+   * @returns The current builder instance.
+   */
+  define(key, value) {
+    defineProperty(this[$model], key, value);
+    return this;
+  }
+  /**
+   * Sets the default value provider for the model. This is an alternative way
+   * to provide the default value for the model if for some reason using the
+   * constructor parameter is undesired.
+   *
+   * @param defaultValueProvider - The function that provides the default value
+   * for the model.
+   * @returns The current builder instance.
+   */
+  defaultValueProvider(defaultValueProvider) {
+    this.define($defaultValue, {
+      get() {
+        return defaultValueProvider(this);
+      }
+    });
+    return this;
+  }
+  /**
+   * Sets the name of the model. The name is used for debugging purposes and is
+   * displayed in the string representation. Setting the name is required;
+   * otherwise, the {@link CoreModelBuilder.build} method won't be available.
+   *
+   * @param name - The name of the model.
+   * @returns The current builder instance.
+   */
+  name(name) {
+    return this.define($name, { value: name });
+  }
+  /**
+   * Builds the model. On the typing level, it checks if all the model parts are
+   * set correctly, and raises an error if not.
+   *
+   * @returns The model.
+   */
+  build() {
+    return this[$model];
+  }
+}
+const propertyRegistry = /* @__PURE__ */ new WeakMap();
+class ObjectModelBuilder extends CoreModelBuilder {
+  constructor(base) {
+    super(base, (m) => {
+      const result = create(null);
+      for (const key in m) {
+        defineProperty(result, key, {
+          enumerable: true,
+          get: () => m[key][$defaultValue]
+        });
+      }
+      return result;
+    });
+  }
+  /**
+   * The method that should follow the {@link m.extend} method. It allows to
+   * declare the extension for the model and properly name it.
+   *
+   * @param name - The name of the model.
+   */
+  object(name) {
+    return this.name(name);
+  }
+  /**
+   * Defines a new model property on the model. Unlike the
+   * {@link ObjectModelBuilder.define}, this property is public and allows the
+   * user to interact with the model data structure. It also updates the current
+   * value type of the model to make it closer to the final value type.
+   *
+   * @param key - The key of the property.
+   * @param model - The model of the property value. You can also provide a
+   * function that produces the model based on the current model.
+   * @param options - Additional options for the property.
+   *
+   * @returns The current builder instance updated with the new property type.
+   * In case there is a self-referencing property, the {@link Flags.selfRefKeys}
+   * flag for the specific property is set.
+   */
+  property(key, model, options) {
+    defineProperty(this[$model], key, {
+      enumerable: true,
+      get() {
+        if (!propertyRegistry.has(this)) {
+          propertyRegistry.set(this, {});
+        }
+        const props = propertyRegistry.get(this);
+        props[key] ??= new CoreModelBuilder(
+          typeof model === "function" ? model(this) : model
+        ).define($key, { value: key }).define($owner, { value: this }).define($meta, { value: options?.meta }).build();
+        return props[key];
+      }
+    });
+    return this;
+  }
+}
+export {
+  CoreModelBuilder,
+  ObjectModelBuilder
+};
+//# sourceMappingURL=builders.js.map

package/builders.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["src/builders.ts"],
+  "sourcesContent": ["import type { EmptyObject } from 'type-fest';\nimport type { ObjectModel } from './core';\nimport {\n  $defaultValue,\n  $key,\n  $meta,\n  $name,\n  $owner,\n  type AnyObject,\n  type DefaultValueProvider,\n  type Model,\n  type ModelMetadata,\n} from './model.js';\n\nconst { create, defineProperty } = Object;\n\n/**\n * The options for creating the model property.\n */\nexport type ModelBuilderPropertyOptions = Readonly<{\n  meta?: ModelMetadata;\n}>;\n\nconst $model = Symbol('model');\n\n/**\n * The flags for the model constructor that allow to determine specific characteristics of the model.\n */\nexport type Flags = {\n  /**\n   * Defines if the model is named.\n   */\n  named: boolean;\n\n  /**\n   * The keys of the self-referencing properties.\n   *\n   * @remarks\n   * The problem of self-reference models is that they cannot have intermediate\n   * type because during the property definition, the model itself is in the\n   * middle of construction. That's why we define the specific type-only flag\n   * that allows us to know which model properties are self-referenced. We can\n   * safely set it in the end of building using this flag.\n   */\n  selfRefKeys: keyof any;\n};\n\n/**\n * A builder class for creating all basic models.\n *\n * @typeParam V - The final value type of the model.\n * @typeParam EX - The extra properties of the model.\n * @typeParam F - The flags for the model constructor that allow to determine\n * specific characteristics of the model.\n */\nexport class CoreModelBuilder<\n  V,\n  EX extends AnyObject = EmptyObject,\n  F extends Flags = { named: false; selfRefKeys: never },\n> {\n  protected readonly [$model]: Model<V, EX>;\n\n  /**\n   * @param base - The base model to extend.\n   * @param defaultValueProvider - The function that provides the default value\n   * for the model.\n   */\n  constructor(base: Model, defaultValueProvider?: (model: Model<V, EX>) => V) {\n    this[$model] = create(base);\n\n    if (defaultValueProvider) {\n      this.defaultValueProvider(defaultValueProvider);\n    }\n  }\n\n  /**\n   * Appends metadata to the model.\n   *\n   * @param value - The metadata to append.\n   * @returns The current builder instance.\n   */\n  meta(value: ModelMetadata): this {\n    this.define($meta, { value });\n    return this;\n  }\n\n  /**\n   * Defines a new property on the model. The property serves the purposes of\n   * storing the extra data for specific types of models.\n   *\n   * @remarks\n   * The key of the property should be a symbol to avoid conflicts with\n   * properties defined via\n   * {@link ObjectModelBuilder}.\n   *\n   * @param key - The key of the property.\n   * @param value - The descriptor of the property.\n   * @returns The current builder instance.\n   */\n  define<DK extends symbol, DV>(\n    key: DK,\n    value: TypedPropertyDescriptor<DV>,\n  ): CoreModelBuilder<V, EX & Readonly<Record<DK, DV>>, F> {\n    defineProperty(this[$model], key, value);\n    return this as any;\n  }\n\n  /**\n   * Sets the default value provider for the model. This is an alternative way\n   * to provide the default value for the model if for some reason using the\n   * constructor parameter is undesired.\n   *\n   * @param defaultValueProvider - The function that provides the default value\n   * for the model.\n   * @returns The current builder instance.\n   */\n  defaultValueProvider(defaultValueProvider: DefaultValueProvider<V, EX>): this {\n    this.define($defaultValue, {\n      get(this: Model<V, EX>) {\n        return defaultValueProvider(this);\n      },\n    });\n    return this;\n  }\n\n  /**\n   * Sets the name of the model. The name is used for debugging purposes and is\n   * displayed in the string representation. Setting the name is required;\n   * otherwise, the {@link CoreModelBuilder.build} method won't be available.\n   *\n   * @param name - The name of the model.\n   * @returns The current builder instance.\n   */\n  name(name: string): CoreModelBuilder<V, EX, { named: true; selfRefKeys: F['selfRefKeys'] }> {\n    return this.define($name, { value: name }) as any;\n  }\n\n  /**\n   * Builds the model. On the typing level, it checks if all the model parts are\n   * set correctly, and raises an error if not.\n   *\n   * @returns The model.\n   */\n  build(this: F['named'] extends true ? this : never): Model<V, EX> {\n    return this[$model];\n  }\n}\n\n/**\n * A registry for the property models of the object model. Since the property\n * registration is lazy, we cannot store the property models directly on the\n * object model, so the registry plays a role of a private storage for them.\n *\n * @internal\n */\nconst propertyRegistry = new WeakMap<Model, Record<string, Model>>();\n\n/**\n * A builder class for creating object models.\n *\n * @typeParam V - The final value type of the model.\n * @typeParam CV - The current value type of the model. It changes as the model\n * is being built and defines if the\n * {@link ObjectModelBuilder.build} method can be called.\n * @typeParam EX - The extra properties of the model.\n * @typeParam F - The flags for the model constructor that allow to determine\n * specific characteristics of the model.\n */\nexport class ObjectModelBuilder<\n  V extends AnyObject,\n  CV extends AnyObject = EmptyObject,\n  EX extends AnyObject = EmptyObject,\n  F extends Flags = { named: false; selfRefKeys: never },\n> extends CoreModelBuilder<V, EX, F> {\n  constructor(base: Model) {\n    super(base, (m) => {\n      const result = create(null);\n\n      // eslint-disable-next-line no-restricted-syntax\n      for (const key in m) {\n        defineProperty(result, key, {\n          enumerable: true,\n          get: () => (m[key as keyof Model<V, EX>] as Model)[$defaultValue],\n        });\n      }\n\n      return result;\n    });\n  }\n\n  /**\n   * The method that should follow the {@link m.extend} method. It allows to\n   * declare the extension for the model and properly name it.\n   *\n   * @param name - The name of the model.\n   */\n  object<NV extends AnyObject>(\n    this: F['named'] extends false ? this : never,\n    name: string,\n  ): ObjectModelBuilder<NV & V, CV, EX, { named: true; selfRefKeys: F['selfRefKeys'] }> {\n    return this.name(name) as any;\n  }\n\n  /**\n   * {@inheritDoc CoreModelBuilder.define}\n   */\n  declare ['define']: <DK extends symbol, DV>(\n    key: DK,\n    value: TypedPropertyDescriptor<DV>,\n  ) => ObjectModelBuilder<V, CV, EX & Readonly<Record<DK, DV>>, F>;\n\n  /**\n   * {@inheritDoc CoreModelBuilder.meta}\n   */\n  declare ['meta']: (value: ModelMetadata) => this;\n\n  /**\n   * Defines a new model property on the model. Unlike the\n   * {@link ObjectModelBuilder.define}, this property is public and allows the\n   * user to interact with the model data structure. It also updates the current\n   * value type of the model to make it closer to the final value type.\n   *\n   * @param key - The key of the property.\n   * @param model - The model of the property value. You can also provide a\n   * function that produces the model based on the current model.\n   * @param options - Additional options for the property.\n   *\n   * @returns The current builder instance updated with the new property type.\n   * In case there is a self-referencing property, the {@link Flags.selfRefKeys}\n   * flag for the specific property is set.\n   */\n  property<PK extends string & keyof V, EXK extends AnyObject = EmptyObject>(\n    key: PK,\n    model: Model<V[PK], EXK> | ((model: Model<V, EX & Readonly<Record<PK, Model<V[PK], EXK>>>>) => Model<V[PK], EXK>),\n    options?: ModelBuilderPropertyOptions,\n  ): // It is a workaround for the self-referencing models.\n  // If the type of the model property is not the model itself,\n  Extract<V[PK], V> extends never\n    ? // Then we simply extend the model with the property, and update the\n      // current value type of the model.\n      ObjectModelBuilder<V, CV & Readonly<Record<PK, V[PK]>>, EX & Readonly<Record<PK, Model<V[PK], EXK>>>, F>\n    : // Otherwise, we set a flag of the model that it contains a self-reference\n      // property.\n      ObjectModelBuilder<\n        V,\n        CV & Readonly<Record<PK, V[PK]>>,\n        EX,\n        {\n          // Just inheriting the current flag.\n          named: F['named'];\n          // Adding the property name to all existing self-referencing\n          // properties.\n          selfRefKeys: F['selfRefKeys'] | PK;\n        }\n      > {\n    defineProperty(this[$model], key, {\n      enumerable: true,\n      get(this: Model<V, EX & Readonly<Record<PK, Model<V[PK], EXK>>>>) {\n        if (!propertyRegistry.has(this)) {\n          propertyRegistry.set(this, {});\n        }\n\n        const props = propertyRegistry.get(this)!;\n\n        props[key] ??= new CoreModelBuilder<V[PK], EXK, { named: true; selfRefKeys: never }>(\n          typeof model === 'function' ? model(this) : model,\n        )\n          .define($key, { value: key })\n          .define($owner, { value: this })\n          .define($meta, { value: options?.meta })\n          .build();\n\n        return props[key];\n      },\n    });\n\n    return this as any;\n  }\n\n  /**\n   * {@inheritDoc CoreModelBuilder.build}\n   */\n  declare build: (\n    this: F['named'] extends true ? (CV extends V ? this : never) : never,\n  ) => ObjectModel<V, EX, F['selfRefKeys']>;\n}\n"],
+  "mappings": "AAEA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAKK;AAEP,MAAM,EAAE,QAAQ,eAAe,IAAI;AASnC,MAAM,SAAS,OAAO,OAAO;AAgCtB,MAAM,iBAIX;AAAA,EACA,CAAoB,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAO1B,YAAY,MAAa,sBAAmD;AAC1E,SAAK,MAAM,IAAI,OAAO,IAAI;AAE1B,QAAI,sBAAsB;AACxB,WAAK,qBAAqB,oBAAoB;AAAA,IAChD;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,KAAK,OAA4B;AAC/B,SAAK,OAAO,OAAO,EAAE,MAAM,CAAC;AAC5B,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAeA,OACE,KACA,OACuD;AACvD,mBAAe,KAAK,MAAM,GAAG,KAAK,KAAK;AACvC,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,qBAAqB,sBAAyD;AAC5E,SAAK,OAAO,eAAe;AAAA,MACzB,MAAwB;AACtB,eAAO,qBAAqB,IAAI;AAAA,MAClC;AAAA,IACF,CAAC;AACD,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,KAAK,MAAuF;AAC1F,WAAO,KAAK,OAAO,OAAO,EAAE,OAAO,KAAK,CAAC;AAAA,EAC3C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,QAAkE;AAChE,WAAO,KAAK,MAAM;AAAA,EACpB;AACF;AASA,MAAM,mBAAmB,oBAAI,QAAsC;AAa5D,MAAM,2BAKH,iBAA2B;AAAA,EACnC,YAAY,MAAa;AACvB,UAAM,MAAM,CAAC,MAAM;AACjB,YAAM,SAAS,OAAO,IAAI;AAG1B,iBAAW,OAAO,GAAG;AACnB,uBAAe,QAAQ,KAAK;AAAA,UAC1B,YAAY;AAAA,UACZ,KAAK,MAAO,EAAE,GAAyB,EAAY,aAAa;AAAA,QAClE,CAAC;AAAA,MACH;AAEA,aAAO;AAAA,IACT,CAAC;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAEE,MACoF;AACpF,WAAO,KAAK,KAAK,IAAI;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA8BA,SACE,KACA,OACA,SAoBI;AACJ,mBAAe,KAAK,MAAM,GAAG,KAAK;AAAA,MAChC,YAAY;AAAA,MACZ,MAAkE;AAChE,YAAI,CAAC,iBAAiB,IAAI,IAAI,GAAG;AAC/B,2BAAiB,IAAI,MAAM,CAAC,CAAC;AAAA,QAC/B;AAEA,cAAM,QAAQ,iBAAiB,IAAI,IAAI;AAEvC,cAAM,GAAG,MAAM,IAAI;AAAA,UACjB,OAAO,UAAU,aAAa,MAAM,IAAI,IAAI;AAAA,QAC9C,EACG,OAAO,MAAM,EAAE,OAAO,IAAI,CAAC,EAC3B,OAAO,QAAQ,EAAE,OAAO,KAAK,CAAC,EAC9B,OAAO,OAAO,EAAE,OAAO,SAAS,KAAK,CAAC,EACtC,MAAM;AAET,eAAO,MAAM,GAAG;AAAA,MAClB;AAAA,IACF,CAAC;AAED,WAAO;AAAA,EACT;AAQF;",
+  "names": []
+}

package/core.d.ts

@@ -0,0 +1,48 @@
+import type { EmptyObject } from 'type-fest';
+import { $enum, $itemModel, type $members, type AnyObject, type Enum, Model, type Value } from './model.js';
+/**
+ * The model of a primitive value, like `string`, `number` or `boolean`.
+ */
+export type PrimitiveModel<V = unknown> = Model<V>;
+export declare const PrimitiveModel: Model<unknown, EmptyObject>;
+/**
+ * The model of a string value.
+ */
+export type StringModel = PrimitiveModel<string>;
+export declare const StringModel: Model<string, EmptyObject>;
+/**
+ * The model of a number value.
+ */
+export type NumberModel = PrimitiveModel<number>;
+export declare const NumberModel: Model<number, EmptyObject>;
+/**
+ * The model of a boolean value.
+ */
+export type BooleanModel = PrimitiveModel<boolean>;
+export declare const BooleanModel: Model<boolean, EmptyObject>;
+/**
+ * The model of an array data.
+ */
+export type ArrayModel<M extends Model = Model> = Model<Array<Value<M>>, Readonly<{
+    [$itemModel]: M;
+}>>;
+export declare const ArrayModel: Model<unknown[], EmptyObject & Readonly<Record<typeof $itemModel, Model<unknown, EmptyObject, never>>>>;
+/**
+ * The model of an object data.
+ */
+export type ObjectModel<V, EX extends AnyObject = EmptyObject, R extends keyof any = never> = Model<V, EX, R>;
+export declare const ObjectModel: Model<Readonly<Record<never, never>>, EmptyObject>;
+/**
+ * The model of an enum data.
+ */
+export type EnumModel<T extends typeof Enum> = Model<T[keyof T], Readonly<{
+    [$enum]: T;
+}>>;
+export declare const EnumModel: Model<string, EmptyObject & Readonly<Record<typeof $enum, typeof Enum>>>;
+/**
+ * The model of a union data.
+ */
+export type UnionModel<MM extends Model[]> = Model<Value<MM[number]>, Readonly<{
+    [$members]: MM;
+}>>;
+//# sourceMappingURL=core.d.ts.map

package/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["src/core.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,IAAI,EAAE,KAAK,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAE5G;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;AACnD,eAAO,MAAM,cAAc,6BAAkF,CAAC;AAE9G;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;AACjD,eAAO,MAAM,WAAW,4BAAwE,CAAC;AAEjG;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;AACjD,eAAO,MAAM,WAAW,4BAAuE,CAAC;AAEhG;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;AACnD,eAAO,MAAM,YAAY,6BAA4E,CAAC;AAEtG;;GAEG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,KAAK,GAAG,KAAK,IAAI,KAAK,CACrD,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EACf,QAAQ,CAAC;IACP,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;CACjB,CAAC,CACH,CAAC;AAEF,eAAO,MAAM,UAAU,yGAGb,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,EAAE,SAAS,SAAS,GAAG,WAAW,EAAE,CAAC,SAAS,MAAM,GAAG,GAAG,KAAK,IAAI,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;AAE9G,eAAO,MAAM,WAAW,oDAA4E,CAAC;AAErG;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,OAAO,IAAI,IAAI,KAAK,CAClD,CAAC,CAAC,MAAM,CAAC,CAAC,EACV,QAAQ,CAAC;IACP,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;CACZ,CAAC,CACH,CAAC;AAEF,eAAO,MAAM,SAAS,0EAKZ,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,UAAU,CAAC,EAAE,SAAS,KAAK,EAAE,IAAI,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,CAAC;IAAE,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAA;CAAE,CAAC,CAAC,CAAC"}

package/core.js

@@ -0,0 +1,19 @@
+import { CoreModelBuilder } from "./builders.js";
+import { $enum, $itemModel, Model } from "./model.js";
+const PrimitiveModel = new CoreModelBuilder(Model, () => void 0).name("primitive").build();
+const StringModel = new CoreModelBuilder(PrimitiveModel, () => "").name("string").build();
+const NumberModel = new CoreModelBuilder(PrimitiveModel, () => 0).name("number").build();
+const BooleanModel = new CoreModelBuilder(PrimitiveModel, () => false).name("boolean").build();
+const ArrayModel = new CoreModelBuilder(Model, () => []).name("Array").define($itemModel, { value: Model }).build();
+const ObjectModel = new CoreModelBuilder(Model, () => ({})).name("Object").build();
+const EnumModel = new CoreModelBuilder(Model).name("Enum").define($enum, { value: {} }).defaultValueProvider((self) => Object.values(self[$enum])[0]).build();
+export {
+  ArrayModel,
+  BooleanModel,
+  EnumModel,
+  NumberModel,
+  ObjectModel,
+  PrimitiveModel,
+  StringModel
+};
+//# sourceMappingURL=core.js.map

package/core.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["src/core.ts"],
+  "sourcesContent": ["import type { EmptyObject } from 'type-fest';\nimport { CoreModelBuilder } from './builders.js';\nimport { $enum, $itemModel, type $members, type AnyObject, type Enum, Model, type Value } from './model.js';\n\n/**\n * The model of a primitive value, like `string`, `number` or `boolean`.\n */\nexport type PrimitiveModel<V = unknown> = Model<V>;\nexport const PrimitiveModel = new CoreModelBuilder(Model, (): unknown => undefined).name('primitive').build();\n\n/**\n * The model of a string value.\n */\nexport type StringModel = PrimitiveModel<string>;\nexport const StringModel = new CoreModelBuilder(PrimitiveModel, () => '').name('string').build();\n\n/**\n * The model of a number value.\n */\nexport type NumberModel = PrimitiveModel<number>;\nexport const NumberModel = new CoreModelBuilder(PrimitiveModel, () => 0).name('number').build();\n\n/**\n * The model of a boolean value.\n */\nexport type BooleanModel = PrimitiveModel<boolean>;\nexport const BooleanModel = new CoreModelBuilder(PrimitiveModel, () => false).name('boolean').build();\n\n/**\n * The model of an array data.\n */\nexport type ArrayModel<M extends Model = Model> = Model<\n  Array<Value<M>>,\n  Readonly<{\n    [$itemModel]: M;\n  }>\n>;\n\nexport const ArrayModel = new CoreModelBuilder(Model, (): unknown[] => [])\n  .name('Array')\n  .define($itemModel, { value: Model })\n  .build();\n\n/**\n * The model of an object data.\n */\nexport type ObjectModel<V, EX extends AnyObject = EmptyObject, R extends keyof any = never> = Model<V, EX, R>;\n\nexport const ObjectModel = new CoreModelBuilder(Model, (): AnyObject => ({})).name('Object').build();\n\n/**\n * The model of an enum data.\n */\nexport type EnumModel<T extends typeof Enum> = Model<\n  T[keyof T],\n  Readonly<{\n    [$enum]: T;\n  }>\n>;\n\nexport const EnumModel = new CoreModelBuilder<(typeof Enum)[keyof typeof Enum]>(Model)\n  .name('Enum')\n  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions\n  .define($enum, { value: {} as typeof Enum })\n  .defaultValueProvider((self) => Object.values(self[$enum])[0])\n  .build();\n\n/**\n * The model of a union data.\n */\nexport type UnionModel<MM extends Model[]> = Model<Value<MM[number]>, Readonly<{ [$members]: MM }>>;\n"],
+  "mappings": "AACA,SAAS,wBAAwB;AACjC,SAAS,OAAO,YAAsD,aAAyB;AAMxF,MAAM,iBAAiB,IAAI,iBAAiB,OAAO,MAAe,MAAS,EAAE,KAAK,WAAW,EAAE,MAAM;AAMrG,MAAM,cAAc,IAAI,iBAAiB,gBAAgB,MAAM,EAAE,EAAE,KAAK,QAAQ,EAAE,MAAM;AAMxF,MAAM,cAAc,IAAI,iBAAiB,gBAAgB,MAAM,CAAC,EAAE,KAAK,QAAQ,EAAE,MAAM;AAMvF,MAAM,eAAe,IAAI,iBAAiB,gBAAgB,MAAM,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM;AAY7F,MAAM,aAAa,IAAI,iBAAiB,OAAO,MAAiB,CAAC,CAAC,EACtE,KAAK,OAAO,EACZ,OAAO,YAAY,EAAE,OAAO,MAAM,CAAC,EACnC,MAAM;AAOF,MAAM,cAAc,IAAI,iBAAiB,OAAO,OAAkB,CAAC,EAAE,EAAE,KAAK,QAAQ,EAAE,MAAM;AAY5F,MAAM,YAAY,IAAI,iBAAmD,KAAK,EAClF,KAAK,MAAM,EAEX,OAAO,OAAO,EAAE,OAAO,CAAC,EAAiB,CAAC,EAC1C,qBAAqB,CAAC,SAAS,OAAO,OAAO,KAAK,KAAK,CAAC,EAAE,CAAC,CAAC,EAC5D,MAAM;",
+  "names": []
+}

package/index.d.ts

@@ -0,0 +1,82 @@
+import type { EmptyObject } from 'type-fest';
+import { ObjectModelBuilder } from './builders.js';
+import { ArrayModel, EnumModel, type UnionModel } from './core.js';
+import { type AnyObject, type Target, type Enum, type Extensions, Model, type References, type Value } from './model.js';
+export * from './model.js';
+export * from './core.js';
+export type * from './builders.js';
+/**
+ * The utility object that provides methods to create and manipulate models.
+ */
+declare const m: {
+    /**
+     * Attaches the given model to the target.
+     *
+     * @param model - The model to attach.
+     * @param target - The target to attach the model to. It could be a Binder
+     * instance, a Signal, or another object. However, it could never be another
+     * model.
+     */
+    attach<M extends Model>(model: M, target: Target<Value<M>>): M;
+    /**
+     * Creates a new model that extends the given base model.
+     *
+     * @param base - The base model to extend.
+     */
+    extend<M extends Model<AnyObject>>(base: M): ObjectModelBuilder<Value<M>, Value<M>, Extensions<M>, {
+        named: false;
+        selfRefKeys: References<M>;
+    }>;
+    /**
+     * Creates a new model that represents an optional value.
+     *
+     * @param base - The base model to extend.
+     */
+    optional<M extends Model>(base: M): M;
+    /**
+     * Creates a new model that represents an array of items.
+     *
+     * @param itemModel - The model of the items in the array.
+     */
+    array<M extends Model>(itemModel: M): ArrayModel<M>;
+    /**
+     * Creates a new model that represents an object.
+     *
+     * @param name - The name of the object.
+     */
+    object<T extends AnyObject>(name: string): ObjectModelBuilder<T, EmptyObject, EmptyObject, {
+        named: true;
+        selfRefKeys: never;
+    }>;
+    /**
+     * Creates a new model that represents an enum.
+     *
+     * @param obj - The enum object to represent.
+     * @param name - The name of the model.
+     */
+    enum<T extends typeof Enum>(obj: T, name: string): EnumModel<T>;
+    /**
+     * Creates a new model that represents a union of the values of the given
+     * models.
+     *
+     * @param members - The models to create the union from.
+     */
+    union<MM extends Model[]>(...members: MM): UnionModel<MM>;
+    /**
+     * Iterates over the given array model yielding an item model for each item
+     * the model value has.
+     *
+     * @param model - The array model to iterate over.
+     */
+    items<V extends Model>(model: ArrayModel<V>): Generator<V, undefined, void>;
+    /**
+     * Provides the value the given model represents. For attached models it will
+     * be the owner value or its part, for detached models it will be the default
+     * value of the model.
+     *
+     * @param model - The model to get the value from.
+     */
+    value<T>(model: Model<T>): T;
+};
+export default m;
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAoB,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAe,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EASL,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,IAAI,EACT,KAAK,UAAU,EACf,KAAK,EAEL,KAAK,UAAU,EACf,KAAK,KAAK,EACX,MAAM,YAAY,CAAC;AAEpB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,mBAAmB,eAAe,CAAC;AAmBnC;;GAEG;AACH,QAAA,MAAM,CAAC;IACL;;;;;;;OAOG;WACI,CAAC,SAAS,KAAK,SAAS,CAAC,UAAU,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAW9D;;;;OAIG;WACI,CAAC,SAAS,KAAK,CAAC,SAAS,CAAC,QACzB,CAAC,GACN,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;KAAE,CAAC;IAItG;;;;OAIG;aACM,CAAC,SAAS,KAAK,QAAQ,CAAC,GAAG,CAAC;IAMrC;;;;OAIG;UACG,CAAC,SAAS,KAAK,aAAa,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAOnD;;;;OAIG;WACI,CAAC,SAAS,SAAS,QAClB,MAAM,GACX,kBAAkB,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,EAAE;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,WAAW,EAAE,KAAK,CAAA;KAAE,CAAC;IAIvF;;;;;OAKG;SACE,CAAC,SAAS,OAAO,IAAI,OAAO,CAAC,QAAQ,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAI/D;;;;;OAKG;UACG,EAAE,SAAS,KAAK,EAAE,cAAc,EAAE,GAAG,UAAU,CAAC,EAAE,CAAC;IAOzD;;;;;OAKG;UACI,CAAC,SAAS,KAAK,SAAS,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC;IAoB5E;;;;;;OAMG;UACG,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;CAM7B,CAAC;AAEF,eAAe,CAAC,CAAC"}

package/index.js

@@ -0,0 +1,125 @@
+import { CoreModelBuilder, ObjectModelBuilder } from "./builders.js";
+import { ArrayModel, EnumModel, ObjectModel } from "./core.js";
+import {
+  $defaultValue,
+  $enum,
+  $itemModel,
+  $key,
+  $members,
+  $name,
+  $optional,
+  $owner,
+  Model,
+  nothing
+} from "./model.js";
+export * from "./model.js";
+export * from "./core.js";
+const { defineProperty } = Object;
+const arrayItemModels = /* @__PURE__ */ new WeakMap();
+function getRawValue(model) {
+  if (model[$owner] instanceof Model) {
+    const parentValue = getRawValue(model[$owner]);
+    return parentValue === nothing ? nothing : parentValue[model[$key]];
+  }
+  return model[$owner].value;
+}
+const m = {
+  /**
+   * Attaches the given model to the target.
+   *
+   * @param model - The model to attach.
+   * @param target - The target to attach the model to. It could be a Binder
+   * instance, a Signal, or another object. However, it could never be another
+   * model.
+   */
+  attach(model, target) {
+    const _model = new CoreModelBuilder(model).name(`@${model[$name]}`).build();
+    defineProperty(_model, $owner, { value: target });
+    defineProperty(target, "model", { enumerable: true, configurable: true, value: model });
+    return _model;
+  },
+  /**
+   * Creates a new model that extends the given base model.
+   *
+   * @param base - The base model to extend.
+   */
+  extend(base) {
+    return new ObjectModelBuilder(base);
+  },
+  /**
+   * Creates a new model that represents an optional value.
+   *
+   * @param base - The base model to extend.
+   */
+  optional(base) {
+    return new CoreModelBuilder(base).define($optional, { value: true }).build();
+  },
+  /**
+   * Creates a new model that represents an array of items.
+   *
+   * @param itemModel - The model of the items in the array.
+   */
+  array(itemModel) {
+    return new CoreModelBuilder(ArrayModel).name(`Array<${itemModel[$name]}>`).define($itemModel, { value: itemModel }).build();
+  },
+  /**
+   * Creates a new model that represents an object.
+   *
+   * @param name - The name of the object.
+   */
+  object(name) {
+    return new ObjectModelBuilder(ObjectModel).name(name);
+  },
+  /**
+   * Creates a new model that represents an enum.
+   *
+   * @param obj - The enum object to represent.
+   * @param name - The name of the model.
+   */
+  enum(obj, name) {
+    return new CoreModelBuilder(EnumModel).define($enum, { value: obj }).name(name).build();
+  },
+  /**
+   * Creates a new model that represents a union of the values of the given
+   * models.
+   *
+   * @param members - The models to create the union from.
+   */
+  union(...members) {
+    return new CoreModelBuilder(Model, () => members[0][$defaultValue]).name(members.map((model) => model[$name]).join(" | ")).define($members, { value: members }).build();
+  },
+  /**
+   * Iterates over the given array model yielding an item model for each item
+   * the model value has.
+   *
+   * @param model - The array model to iterate over.
+   */
+  *items(model) {
+    const list = arrayItemModels.get(model) ?? [];
+    arrayItemModels.set(model, list);
+    const value = m.value(model);
+    list.length = value.length;
+    for (let i = 0; i < value.length; i++) {
+      if (!list[i]) {
+        list[i] = new CoreModelBuilder(model[$itemModel], () => value[i]).name(`${model[$itemModel][$name]}[${i}]`).define($key, { value: i }).define($owner, { value: model }).build();
+      }
+      yield list[i];
+    }
+  },
+  /**
+   * Provides the value the given model represents. For attached models it will
+   * be the owner value or its part, for detached models it will be the default
+   * value of the model.
+   *
+   * @param model - The model to get the value from.
+   */
+  value(model) {
+    const value = getRawValue(model);
+    return value === nothing ? model[$defaultValue] : value;
+  }
+};
+var src_default = m;
+export {
+  src_default as default
+};
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["src/index.ts"],
+  "sourcesContent": ["import type { EmptyObject } from 'type-fest';\nimport { CoreModelBuilder, ObjectModelBuilder } from './builders.js';\nimport { ArrayModel, EnumModel, ObjectModel, type UnionModel } from './core.js';\nimport {\n  $defaultValue,\n  $enum,\n  $itemModel,\n  $key,\n  $members,\n  $name,\n  $optional,\n  $owner,\n  type AnyObject,\n  type Target,\n  type Enum,\n  type Extensions,\n  Model,\n  nothing,\n  type References,\n  type Value,\n} from './model.js';\n\nexport * from './model.js';\nexport * from './core.js';\nexport type * from './builders.js';\n\nconst { defineProperty } = Object;\n\nconst arrayItemModels = new WeakMap<ArrayModel, Model[]>();\n\nfunction getRawValue<T>(model: Model<T>): T | typeof nothing {\n  if (model[$owner] instanceof Model) {\n    // If the current model is a property of another model, the owner is\n    // definitely an object. So we just return the part of the value of\n    // the owner.\n    const parentValue = getRawValue(model[$owner] as Model<Record<keyof any, T>>);\n    return parentValue === nothing ? nothing : parentValue[model[$key]];\n  }\n\n  // Otherwise, the owner is a Target, so we can return the full value.\n  return (model[$owner] as Target<T>).value;\n}\n\n/**\n * The utility object that provides methods to create and manipulate models.\n */\nconst m = {\n  /**\n   * Attaches the given model to the target.\n   *\n   * @param model - The model to attach.\n   * @param target - The target to attach the model to. It could be a Binder\n   * instance, a Signal, or another object. However, it could never be another\n   * model.\n   */\n  attach<M extends Model>(model: M, target: Target<Value<M>>): M {\n    const _model = new CoreModelBuilder<Value<M>, Extensions<M>, { named: false; selfRefKeys: References<M> }>(model)\n      .name(`@${model[$name]}`)\n      .build();\n    defineProperty(_model, $owner, { value: target });\n    defineProperty(target, 'model', { enumerable: true, configurable: true, value: model });\n\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion\n    return _model as any;\n  },\n\n  /**\n   * Creates a new model that extends the given base model.\n   *\n   * @param base - The base model to extend.\n   */\n  extend<M extends Model<AnyObject>>(\n    base: M,\n  ): ObjectModelBuilder<Value<M>, Value<M>, Extensions<M>, { named: false; selfRefKeys: References<M> }> {\n    return new ObjectModelBuilder(base);\n  },\n\n  /**\n   * Creates a new model that represents an optional value.\n   *\n   * @param base - The base model to extend.\n   */\n  optional<M extends Model>(base: M): M {\n    return new CoreModelBuilder<Value<M>, Extensions<M>, { named: true; selfRefKeys: References<M> }>(base)\n      .define($optional, { value: true })\n      .build() as M;\n  },\n\n  /**\n   * Creates a new model that represents an array of items.\n   *\n   * @param itemModel - The model of the items in the array.\n   */\n  array<M extends Model>(itemModel: M): ArrayModel<M> {\n    return new CoreModelBuilder<Array<Value<M>>>(ArrayModel)\n      .name(`Array<${itemModel[$name]}>`)\n      .define($itemModel, { value: itemModel })\n      .build();\n  },\n\n  /**\n   * Creates a new model that represents an object.\n   *\n   * @param name - The name of the object.\n   */\n  object<T extends AnyObject>(\n    name: string,\n  ): ObjectModelBuilder<T, EmptyObject, EmptyObject, { named: true; selfRefKeys: never }> {\n    return new ObjectModelBuilder(ObjectModel).name(name) as any;\n  },\n\n  /**\n   * Creates a new model that represents an enum.\n   *\n   * @param obj - The enum object to represent.\n   * @param name - The name of the model.\n   */\n  enum<T extends typeof Enum>(obj: T, name: string): EnumModel<T> {\n    return new CoreModelBuilder<T[keyof T]>(EnumModel).define($enum, { value: obj }).name(name).build();\n  },\n\n  /**\n   * Creates a new model that represents a union of the values of the given\n   * models.\n   *\n   * @param members - The models to create the union from.\n   */\n  union<MM extends Model[]>(...members: MM): UnionModel<MM> {\n    return new CoreModelBuilder(Model, () => members[0][$defaultValue] as Value<MM[number]>)\n      .name(members.map((model) => model[$name]).join(' | '))\n      .define($members, { value: members })\n      .build();\n  },\n\n  /**\n   * Iterates over the given array model yielding an item model for each item\n   * the model value has.\n   *\n   * @param model - The array model to iterate over.\n   */\n  *items<V extends Model>(model: ArrayModel<V>): Generator<V, undefined, void> {\n    const list = arrayItemModels.get(model) ?? [];\n    arrayItemModels.set(model, list);\n    const value = m.value(model);\n\n    list.length = value.length;\n\n    for (let i = 0; i < value.length; i++) {\n      if (!list[i]) {\n        list[i] = new CoreModelBuilder(model[$itemModel], () => value[i])\n          .name(`${model[$itemModel][$name]}[${i}]`)\n          .define($key, { value: i })\n          .define($owner, { value: model })\n          .build();\n      }\n\n      yield list[i] as V;\n    }\n  },\n\n  /**\n   * Provides the value the given model represents. For attached models it will\n   * be the owner value or its part, for detached models it will be the default\n   * value of the model.\n   *\n   * @param model - The model to get the value from.\n   */\n  value<T>(model: Model<T>): T {\n    const value = getRawValue(model);\n\n    // If the value is `nothing`, we return the default value of the model.\n    return value === nothing ? model[$defaultValue] : value;\n  },\n};\n\nexport default m;\n"],
+  "mappings": "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",
+  "names": []
+}

package/model.d.ts

@@ -0,0 +1,136 @@
+import type { EmptyObject } from 'type-fest';
+export interface JvmTypeRef {
+    jvmType: string;
+    genericArguments?: JvmTypeRef[];
+}
+export type AnnotationValue = AnnotationValue[] | JvmTypeRef | boolean | number | string | undefined;
+export interface Annotation {
+    jvmType: string;
+    arguments: Record<string, AnnotationValue>;
+}
+/**
+ * The metadata of a model.
+ */
+export interface ModelMetadata {
+    jvmType?: string;
+    annotations?: Annotation[];
+}
+/**
+ * The target to which a model is attached. It could be a Binder instance, a
+ * Signal or another object. However, it could never be another model.
+ */
+export type Target<T = unknown> = Readonly<{
+    model?: Model<T>;
+    value: T;
+}>;
+export declare const nothing: unique symbol;
+export declare enum Enum {
+}
+export type AnyObject = Readonly<Record<never, never>>;
+/**
+ * The symbol that represents the {@link Model[$key]} property.
+ */
+export declare const $key: unique symbol;
+/**
+ * The symbol that represents the {@link Model[$name]} property.
+ */
+export declare const $name: unique symbol;
+/**
+ * The symbol that represents the {@link Model[$owner]} property.
+ */
+export declare const $owner: unique symbol;
+/**
+ * The symbol that represents the {@link Model[$meta]} property.
+ */
+export declare const $meta: unique symbol;
+/**
+ * The symbol that represents the {@link Model[$optional]} property.
+ */
+export declare const $optional: unique symbol;
+/**
+ * The symbol that represents the {@link Model[$value]} property.
+ */
+export declare const $defaultValue: unique symbol;
+/**
+ * The symbol that represents the {@link EnumModel[$enumerate]} property.
+ */
+export declare const $enum: unique symbol;
+/**
+ * The symbol that represents the {@link UnionModel[$members]} property.
+ */
+export declare const $members: unique symbol;
+/**
+ * The symbol that represents the {@link ArrayModel[$itemModel]} property.
+ */
+export declare const $itemModel: unique symbol;
+/**
+ * Extracts the value type the model represents.
+ */
+export type Value<M extends Model> = M extends Model<infer T> ? T : never;
+/**
+ * Extracts the list of extra properties of the model.
+ */
+export type Extensions<M extends Model> = M extends Model<unknown, infer EX> ? EX : EmptyObject;
+/**
+ * Extracts the list of self-referencing properties of the model.
+ */
+export type References<M extends Model> = M extends Model<unknown, AnyObject, infer R> ? R : never;
+/**
+ * A model that represents a specific type of data.
+ *
+ * @typeParam V - The type of the data described by the model.
+ * @typeParam EX - The extra properties of the model. It could be either a model
+ * that represents a property of the object the current model describe, or a
+ * model-specific metadata. It's recommended to use a symbol as a key for the
+ * metadata property to avoid the potential naming conflicts with the described
+ * object properties.
+ * @typeParam R - The keys of the self-referencing properties of the model.
+ *
+ * @remarks
+ * Since we know the full model definition only on this step, the `R` type
+ * parameter is essential to describe a model with self-reference properties.
+ */
+export type Model<V = unknown, EX extends AnyObject = EmptyObject, R extends keyof any = never> = EX & Readonly<{
+    [P in R]: Model<V, EX, R>;
+}> & Readonly<{
+    /**
+     * The key of the model in the owner model.
+     */
+    [$key]: keyof any;
+    /**
+     * The name of the model. For attached models, the name will be prefixed
+     * with the `@` symbol.
+     */
+    [$name]: string;
+    /**
+     * The owner model of the model. For detached models, the owner will always
+     * be a specific global object `detachedTarget`.
+     */
+    [$owner]: Model | Target;
+    /**
+     * The metadata of the model.
+     */
+    [$meta]?: ModelMetadata;
+    /**
+     * Whether the model is optional. It describes if the data described by
+     * this model is nullable.
+     */
+    [$optional]: boolean;
+    /**
+     * The default value of the model.
+     */
+    [$defaultValue]: V;
+    [Symbol.toStringTag]: string;
+    [Symbol.hasInstance](value: any): value is Model<V, EX, R>;
+    toString(): string;
+}>;
+/**
+ * A function that provides a default value for a model.
+ *
+ * @typeParam V - The type of the data described by the model.
+ * @typeParam EX - The extra properties of the model.
+ * @typeParam R - The keys of the self-referencing properties of the model.
+ */
+export type DefaultValueProvider<V, EX extends AnyObject = EmptyObject, R extends keyof any = never> = (model: Model<V, EX, R>) => V;
+export declare const Model: Model;
+//# sourceMappingURL=model.d.ts.map

package/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["src/model.ts"],"names":[],"mappings":"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"}

package/model.js

@@ -0,0 +1,64 @@
+const nothing = Symbol("nothing");
+const detachedTarget = Object.create(
+  {
+    toString: () => ":detached:"
+  },
+  {
+    model: { value: void 0 },
+    value: { value: nothing }
+  }
+);
+const $key = Symbol("key");
+const $name = Symbol("name");
+const $owner = Symbol("owner");
+const $meta = Symbol("meta");
+const $optional = Symbol("optional");
+const $defaultValue = Symbol("value");
+const $enum = Symbol("enumerate");
+const $members = Symbol("members");
+const $itemModel = Symbol("itemModel");
+const Model = Object.create(null, {
+  [$key]: {
+    value: "model"
+  },
+  [$name]: {
+    value: "Model"
+  },
+  [$owner]: {
+    value: detachedTarget
+  },
+  [$meta]: {},
+  [$optional]: {
+    value: false
+  },
+  [$defaultValue]: {},
+  [Symbol.toStringTag]: {
+    get() {
+      return this[$name];
+    }
+  },
+  [Symbol.hasInstance]: {
+    value(o) {
+      return typeof o === "object" && o != null && (this === o || Object.prototype.isPrototypeOf.call(this, o));
+    }
+  },
+  toString: {
+    value() {
+      return `[${String(this[$owner])} / ${String(this[$key])}${this[$optional] ? "?" : ""}] ${this[$name]}`;
+    }
+  }
+});
+export {
+  $defaultValue,
+  $enum,
+  $itemModel,
+  $key,
+  $members,
+  $meta,
+  $name,
+  $optional,
+  $owner,
+  Model,
+  nothing
+};
+//# sourceMappingURL=model.js.map

package/model.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["src/model.ts"],
+  "sourcesContent": ["import type { EmptyObject } from 'type-fest';\n\nexport interface JvmTypeRef {\n  jvmType: string;\n  genericArguments?: JvmTypeRef[];\n}\n\nexport type AnnotationValue = AnnotationValue[] | JvmTypeRef | boolean | number | string | undefined;\n\nexport interface Annotation {\n  jvmType: string;\n  arguments: Record<string, AnnotationValue>;\n}\n\n/**\n * The metadata of a model.\n */\nexport interface ModelMetadata {\n  jvmType?: string;\n  annotations?: Annotation[];\n}\n\n/**\n * The target to which a model is attached. It could be a Binder instance, a\n * Signal or another object. However, it could never be another model.\n */\nexport type Target<T = unknown> = Readonly<{\n  model?: Model<T>;\n  value: T;\n}>;\n\nexport const nothing = Symbol('nothing');\n\nconst detachedTarget: Target = Object.create(\n  {\n    toString: () => ':detached:',\n  },\n  {\n    model: { value: undefined },\n    value: { value: nothing },\n  },\n);\n\nexport declare enum Enum {}\n\nexport type AnyObject = Readonly<Record<never, never>>; // {}\n\n/* eslint-disable tsdoc/syntax */\n/**\n * The symbol that represents the {@link Model[$key]} property.\n */\nexport const $key = Symbol('key');\n\n/**\n * The symbol that represents the {@link Model[$name]} property.\n */\nexport const $name = Symbol('name');\n\n/**\n * The symbol that represents the {@link Model[$owner]} property.\n */\nexport const $owner = Symbol('owner');\n\n/**\n * The symbol that represents the {@link Model[$meta]} property.\n */\nexport const $meta = Symbol('meta');\n\n/**\n * The symbol that represents the {@link Model[$optional]} property.\n */\nexport const $optional = Symbol('optional');\n\n/**\n * The symbol that represents the {@link Model[$value]} property.\n */\nexport const $defaultValue = Symbol('value');\n\n/**\n * The symbol that represents the {@link EnumModel[$enumerate]} property.\n */\nexport const $enum = Symbol('enumerate');\n\n/**\n * The symbol that represents the {@link UnionModel[$members]} property.\n */\nexport const $members = Symbol('members');\n\n/**\n * The symbol that represents the {@link ArrayModel[$itemModel]} property.\n */\nexport const $itemModel = Symbol('itemModel');\n\n/* eslint-enable tsdoc/syntax */\n\n/**\n * Extracts the value type the model represents.\n */\nexport type Value<M extends Model> = M extends Model<infer T> ? T : never;\n\n/**\n * Extracts the list of extra properties of the model.\n */\nexport type Extensions<M extends Model> = M extends Model<unknown, infer EX> ? EX : EmptyObject;\n\n/**\n * Extracts the list of self-referencing properties of the model.\n */\nexport type References<M extends Model> = M extends Model<unknown, AnyObject, infer R> ? R : never;\n\n/**\n * A model that represents a specific type of data.\n *\n * @typeParam V - The type of the data described by the model.\n * @typeParam EX - The extra properties of the model. It could be either a model\n * that represents a property of the object the current model describe, or a\n * model-specific metadata. It's recommended to use a symbol as a key for the\n * metadata property to avoid the potential naming conflicts with the described\n * object properties.\n * @typeParam R - The keys of the self-referencing properties of the model.\n *\n * @remarks\n * Since we know the full model definition only on this step, the `R` type\n * parameter is essential to describe a model with self-reference properties.\n */\nexport type Model<V = unknown, EX extends AnyObject = EmptyObject, R extends keyof any = never> = EX &\n  Readonly<{\n    [P in R]: Model<V, EX, R>;\n  }> &\n  Readonly<{\n    /**\n     * The key of the model in the owner model.\n     */\n    [$key]: keyof any;\n\n    /**\n     * The name of the model. For attached models, the name will be prefixed\n     * with the `@` symbol.\n     */\n    [$name]: string;\n\n    /**\n     * The owner model of the model. For detached models, the owner will always\n     * be a specific global object `detachedTarget`.\n     */\n    [$owner]: Model | Target;\n\n    /**\n     * The metadata of the model.\n     */\n    [$meta]?: ModelMetadata;\n\n    /**\n     * Whether the model is optional. It describes if the data described by\n     * this model is nullable.\n     */\n    [$optional]: boolean;\n\n    /**\n     * The default value of the model.\n     */\n    [$defaultValue]: V;\n    [Symbol.toStringTag]: string;\n    [Symbol.hasInstance](value: any): value is Model<V, EX, R>;\n    toString(): string;\n  }>;\n\n/**\n * A function that provides a default value for a model.\n *\n * @typeParam V - The type of the data described by the model.\n * @typeParam EX - The extra properties of the model.\n * @typeParam R - The keys of the self-referencing properties of the model.\n */\nexport type DefaultValueProvider<V, EX extends AnyObject = EmptyObject, R extends keyof any = never> = (\n  model: Model<V, EX, R>,\n) => V;\n\nexport const Model: Model = Object.create(null, {\n  [$key]: {\n    value: 'model',\n  },\n  [$name]: {\n    value: 'Model',\n  },\n  [$owner]: {\n    value: detachedTarget,\n  },\n  [$meta]: {},\n  [$optional]: {\n    value: false,\n  },\n  [$defaultValue]: {},\n  [Symbol.toStringTag]: {\n    get(this: Model) {\n      return this[$name];\n    },\n  },\n  [Symbol.hasInstance]: {\n    value(this: Model, o: unknown) {\n      return typeof o === 'object' && o != null && (this === o || Object.prototype.isPrototypeOf.call(this, o));\n    },\n  },\n  toString: {\n    value(this: Model) {\n      return `[${String(this[$owner])} / ${String(this[$key])}${this[$optional] ? '?' : ''}] ${this[$name]}`;\n    },\n  },\n});\n"],
+  "mappings": "AA+BO,MAAM,UAAU,OAAO,SAAS;AAEvC,MAAM,iBAAyB,OAAO;AAAA,EACpC;AAAA,IACE,UAAU,MAAM;AAAA,EAClB;AAAA,EACA;AAAA,IACE,OAAO,EAAE,OAAO,OAAU;AAAA,IAC1B,OAAO,EAAE,OAAO,QAAQ;AAAA,EAC1B;AACF;AAUO,MAAM,OAAO,OAAO,KAAK;AAKzB,MAAM,QAAQ,OAAO,MAAM;AAK3B,MAAM,SAAS,OAAO,OAAO;AAK7B,MAAM,QAAQ,OAAO,MAAM;AAK3B,MAAM,YAAY,OAAO,UAAU;AAKnC,MAAM,gBAAgB,OAAO,OAAO;AAKpC,MAAM,QAAQ,OAAO,WAAW;AAKhC,MAAM,WAAW,OAAO,SAAS;AAKjC,MAAM,aAAa,OAAO,WAAW;AAuFrC,MAAM,QAAe,OAAO,OAAO,MAAM;AAAA,EAC9C,CAAC,IAAI,GAAG;AAAA,IACN,OAAO;AAAA,EACT;AAAA,EACA,CAAC,KAAK,GAAG;AAAA,IACP,OAAO;AAAA,EACT;AAAA,EACA,CAAC,MAAM,GAAG;AAAA,IACR,OAAO;AAAA,EACT;AAAA,EACA,CAAC,KAAK,GAAG,CAAC;AAAA,EACV,CAAC,SAAS,GAAG;AAAA,IACX,OAAO;AAAA,EACT;AAAA,EACA,CAAC,aAAa,GAAG,CAAC;AAAA,EAClB,CAAC,OAAO,WAAW,GAAG;AAAA,IACpB,MAAiB;AACf,aAAO,KAAK,KAAK;AAAA,IACnB;AAAA,EACF;AAAA,EACA,CAAC,OAAO,WAAW,GAAG;AAAA,IACpB,MAAmB,GAAY;AAC7B,aAAO,OAAO,MAAM,YAAY,KAAK,SAAS,SAAS,KAAK,OAAO,UAAU,cAAc,KAAK,MAAM,CAAC;AAAA,IACzG;AAAA,EACF;AAAA,EACA,UAAU;AAAA,IACR,QAAmB;AACjB,aAAO,IAAI,OAAO,KAAK,MAAM,CAAC,CAAC,MAAM,OAAO,KAAK,IAAI,CAAC,CAAC,GAAG,KAAK,SAAS,IAAI,MAAM,EAAE,KAAK,KAAK,KAAK,CAAC;AAAA,IACtG;AAAA,EACF;AACF,CAAC;",
+  "names": []
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@vaadin/hilla-models",
+  "version": "24.5.0-alpha5",
+  "description": "Generative form models for Hilla",
+  "main": "index.js",
+  "module": "index.js",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vaadin/hilla.git",
+    "directory": "packages/ts/form-models"
+  },
+  "keywords": [
+    "Hilla",
+    "Form",
+    "Models"
+  ],
+  "scripts": {
+    "clean:build": "git clean -fx . -e .vite -e node_modules",
+    "build": "concurrently npm:build:*",
+    "build:esbuild": "tsx ../../../scripts/build.ts",
+    "build:dts": "tsc --isolatedModules -p tsconfig.build.json",
+    "build:copy": "cd src && copyfiles **/*.d.ts ..",
+    "lint": "eslint src test",
+    "lint:fix": "eslint src test --fix",
+    "test": "mocha test/**/*.spec.ts --config ../../../.mocharc.cjs",
+    "test:coverage": "c8 --experimental-monocart -c ../../../.c8rc.json npm test",
+    "test:watch": "npm run test -- --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "exports": {
+    ".": {
+      "default": "./index.js"
+    }
+  },
+  "author": "Vaadin Ltd",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/vaadin/hilla/issues"
+  },
+  "homepage": "https://hilla.dev",
+  "files": [
+    "*.{d.ts.map,d.ts,js.map,js}"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@vaadin/hilla-lit-form": "24.5.0-alpha5"
+  },
+  "peerDependencies": {
+    "react": "^18"
+  },
+  "devDependencies": {
+    "@esm-bundle/chai": "^4.3.4-fix.0",
+    "@testing-library/react": "^14.0.0",
+    "@testing-library/user-event": "^14.5.1",
+    "@types/chai": "^4.3.6",
+    "@types/chai-as-promised": "^7.1.8",
+    "@types/chai-dom": "^1.11.1",
+    "@types/chai-like": "^1.1.3",
+    "@types/mocha": "^10.0.2",
+    "@types/node": "^20.14.2",
+    "@types/react": "^18.2.23",
+    "@types/sinon": "^10.0.17",
+    "@types/sinon-chai": "^3.2.10",
+    "@types/validator": "^13.11.2",
+    "c8": "^10.1.2",
+    "chai-as-promised": "^7.1.1",
+    "chai-dom": "^1.11.0",
+    "glob": "^10.4.1",
+    "mocha": "^10.4.0",
+    "monocart-coverage-reports": "^2.8.4",
+    "sinon": "^16.0.0",
+    "sinon-chai": "^3.7.0",
+    "typescript": "5.5.2"
+  }
+}