@axi-engine/fields 0.1.4 → 0.2.0

package/dist/index.mjs

@@ -1,17 +1,11 @@
-// src/fields-types.ts
-var FieldsNodeType = /* @__PURE__ */ ((FieldsNodeType2) => {
-  FieldsNodeType2["fieldTree"] = "FieldTree";
-  FieldsNodeType2["fields"] = "Fields";
-  return FieldsNodeType2;
-})(FieldsNodeType || {});
-
-// src/field-policies.ts
-var _ClampPolicy = class _ClampPolicy {
+// src/policies/clamp-policy.ts
+var ClampPolicy = class _ClampPolicy {
   constructor(min, max) {
     this.min = min;
     this.max = max;
-    this.id = _ClampPolicy.id;
   }
+  static id = "clamp";
+  id = _ClampPolicy.id;
   apply(val) {
     return Math.max(this.min, Math.min(this.max, val));
   }
@@ -20,27 +14,17 @@ var _ClampPolicy = class _ClampPolicy {
     this.max = max;
   }
 };
-_ClampPolicy.id = "clamp";
-var ClampPolicy = _ClampPolicy;
-var _ClampMinPolicy = class _ClampMinPolicy {
-  constructor(min) {
-    this.min = min;
-    this.id = _ClampMinPolicy.id;
-  }
-  apply(val) {
-    return Math.max(this.min, val);
-  }
-  updateBounds(min) {
-    this.min = min;
-  }
-};
-_ClampMinPolicy.id = "clampMin";
-var ClampMinPolicy = _ClampMinPolicy;
-var _ClampMaxPolicy = class _ClampMaxPolicy {
+function clampPolicy(min, max) {
+  return new ClampPolicy(min, max);
+}
+
+// src/policies/clamp-max-policy.ts
+var ClampMaxPolicy = class _ClampMaxPolicy {
   constructor(max) {
     this.max = max;
-    this.id = _ClampMaxPolicy.id;
   }
+  static id = "clampMax";
+  id = _ClampMaxPolicy.id;
   apply(val) {
     return Math.min(this.max, val);
   }
@@ -48,58 +32,33 @@ var _ClampMaxPolicy = class _ClampMaxPolicy {
     this.max = max;
   }
 };
-_ClampMaxPolicy.id = "clampMax";
-var ClampMaxPolicy = _ClampMaxPolicy;
-function clampPolicy(min, max) {
-  return new ClampPolicy(min, max);
-}
-function clampMinPolicy(min) {
-  return new ClampMinPolicy(min);
-}
 function clampMaxPolicy(max) {
   return new ClampMaxPolicy(max);
 }
 
-// src/field.ts
-import { signal } from "@preact/signals-core";
-var Field = class {
-  /**
-   * Creates an instance of a Field.
-   * @param name A unique identifier for the field.
-   * @param initialVal The initial value of the field.
-   * @param options Optional configuration for the field.
-   * @param options.policies An array of policies to apply to the field's value on every `set` operation.
-   */
-  constructor(name, initialVal, options) {
-    this.policies = /* @__PURE__ */ new Map();
-    this._val = signal(initialVal);
-    this.name = name;
-    options?.policies?.forEach((policy) => this.policies.set(policy.id, policy));
-    this.set(initialVal);
+// src/policies/clamp-min-policy.ts
+var ClampMinPolicy = class _ClampMinPolicy {
+  constructor(min) {
+    this.min = min;
   }
-  /**
-   * Gets the current raw value of the field.
-   * For reactive updates, it's recommended to use the `.signal` property instead.
-   */
-  get val() {
-    return this._val.value;
+  static id = "clampMin";
+  id = _ClampMinPolicy.id;
+  apply(val) {
+    return Math.max(this.min, val);
   }
-  /**
-   * Provides readonly access to the underlying Preact Signal.
-   * Subscribe to this signal to react to value changes.
-   */
-  get signal() {
-    return this._val;
+  updateBounds(min) {
+    this.min = min;
   }
-  /**
-   * Sets a new value for the field.
-   * The provided value will be processed by all registered policies before the underlying signal is updated.
-   * @param val The new value to set.
-   */
-  set(val) {
-    let finalVal = val;
-    this.policies.forEach((policy) => finalVal = policy.apply(finalVal));
-    this._val.value = finalVal;
+};
+function clampMinPolicy(min) {
+  return new ClampMinPolicy(min);
+}
+
+// src/policies/policies.ts
+var Policies = class {
+  policies = /* @__PURE__ */ new Map();
+  get items() {
+    return this.policies;
   }
   /**
    * Retrieves a specific policy instance by its ID.
@@ -108,7 +67,7 @@ var Field = class {
    * @param id The unique ID of the policy to retrieve.
    * @returns The policy instance, or `undefined` if not found.
    */
-  getPolicy(id) {
+  get(id) {
     return this.policies.get(id);
   }
   /**
@@ -117,17 +76,18 @@ var Field = class {
    * If a policy with the same ID already exists, its `destroy` method will be called before it is replaced.
    * @param policy The policy instance to add.
    */
-  addPolicy(policy) {
+  add(policy) {
     const existed = this.policies.get(policy.id);
     existed?.destroy?.();
     this.policies.set(policy.id, policy);
+    return this;
   }
   /**
    * Removes a policy from the field by its ID and call `destroy` method.
    * @param policyId The unique ID of the policy to remove.
    * @returns `true` if the policy was found and removed, otherwise `false`.
    */
-  removePolicy(policyId) {
+  remove(policyId) {
     const policyToRemove = this.policies.get(policyId);
     if (!policyToRemove) {
       return false;
@@ -135,11 +95,14 @@ var Field = class {
     policyToRemove.destroy?.();
     return this.policies.delete(policyId);
   }
+  isEmpty() {
+    return this.policies.size === 0;
+  }
   /**
    * Removes all policies from the field.
    * After this, `set()` will no longer apply any transformations to the value until new policies are added.
    */
-  clearPolicies() {
+  clear() {
     this.policies.forEach((policy) => policy.destroy?.());
     this.policies.clear();
   }
@@ -147,37 +110,133 @@ var Field = class {
    * Forces the current value to be re-processed by all policies.
    * Useful if a policy's logic has changed and you need to re-evaluate the current state.
    */
-  reapplyPolicies() {
-    this.set(this.val);
+  apply(val) {
+    let finalVal = val;
+    this.policies.forEach((policy) => finalVal = policy.apply(finalVal));
+    return finalVal;
+  }
+};
+
+// src/field-definitions/default-field.ts
+import { Emitter } from "@axi-engine/utils";
+import { dequal } from "dequal";
+var DefaultField = class _DefaultField {
+  /** A type keyword of the field */
+  static typeName = "default";
+  typeName = _DefaultField.typeName;
+  /** A unique identifier for the field. */
+  _name;
+  _value;
+  _onChange = new Emitter();
+  onChange;
+  policies = new Policies();
+  get name() {
+    return this._name;
+  }
+  /**
+   * Gets the current raw value of the field.
+   * For reactive updates, it's recommended to use the `.signal` property instead.
+   */
+  get value() {
+    return this._value;
+  }
+  /**
+   * Sets a new value for the field.
+   * The provided value will be processed by all registered policies before the underlying signal is updated.
+   * @param val The new value to set.
+   */
+  set value(val) {
+    const oldVal = this._value;
+    const finalVal = this.policies.apply(val);
+    if (!dequal(this._value, finalVal)) {
+      this._value = finalVal;
+      this._onChange.emit(this._value, oldVal);
+    }
+  }
+  /**
+   * Creates an instance of a Field.
+   * @param name A unique identifier for the field.
+   * @param initialVal The initial value of the field.
+   * @param options Optional configuration for the field.
+   * @param options.policies An array of policies to apply to the field's value on every `set` operation.
+   * @param options.isEqual An function for compare old and new value, by default uses the strictEquals from `utils`
+   *
+   */
+  constructor(name, initialVal, options) {
+    this.onChange = this._onChange;
+    this._name = name;
+    options?.policies?.forEach((policy) => this.policies.add(policy));
+    this.value = initialVal;
+  }
+  setValueSilently(val) {
+    this._value = this.policies.apply(val);
+  }
+  batchUpdate(updateFn) {
+    this.value = updateFn(this.value);
   }
   /**
    * Cleans up resources used by the field and its policies.
    * This should be called when the field is no longer needed to prevent memory leaks from reactive policies.
    */
   destroy() {
-    this.clearPolicies();
+    this.policies.clear();
+    this._onChange.clear();
+  }
+};
+
+// src/field-definitions/default-boolean-field.ts
+var DefaultBooleanField = class _DefaultBooleanField extends DefaultField {
+  static typeName = "boolean";
+  typeName = _DefaultBooleanField.typeName;
+  constructor(name, initialVal, options) {
+    super(name, initialVal, options);
+  }
+  toggle() {
+    this.value = !this.value;
+    return this.value;
+  }
+};
+
+// src/field-definitions/default-string-field.ts
+var DefaultStringField = class _DefaultStringField extends DefaultField {
+  static typeName = "string";
+  typeName = _DefaultStringField.typeName;
+  constructor(name, initialVal, options) {
+    super(name, initialVal, options);
+  }
+  append(str) {
+    this.value = this.value + str;
+    return this;
+  }
+  prepend(str) {
+    this.value = str + this.value;
+    return this;
+  }
+  trim() {
+    this.value = this.value.trim();
+    return this;
+  }
+  isEmpty() {
+    return this.value.length === 0;
+  }
+  clear() {
+    this.value = "";
   }
 };
 
-// src/number-field.ts
+// src/field-definitions/default-numeric-field.ts
 import { isNullOrUndefined } from "@axi-engine/utils";
-var NumberField = class extends Field {
+var DefaultNumericField = class _DefaultNumericField extends DefaultField {
+  static typeName = "numeric";
+  typeName = _DefaultNumericField.typeName;
   get min() {
-    const policy = this.getPolicy(ClampPolicy.id) ?? this.getPolicy(ClampMinPolicy.id);
+    const policy = this.policies.get(ClampPolicy.id) ?? this.policies.get(ClampMinPolicy.id);
     return policy?.min;
   }
   get max() {
-    const policy = this.getPolicy(ClampPolicy.id) ?? this.getPolicy(ClampMaxPolicy.id);
+    const policy = this.policies.get(ClampPolicy.id) ?? this.policies.get(ClampMaxPolicy.id);
     return policy?.max;
   }
-  get isMin() {
-    const min = this.min;
-    return isNullOrUndefined(min) ? false : this.val <= min;
-  }
-  get isMax() {
-    const max = this.max;
-    return isNullOrUndefined(max) ? false : this.val >= max;
-  }
   constructor(name, initialVal, options) {
     const policies = options?.policies ?? [];
     if (!isNullOrUndefined(options?.min) && !isNullOrUndefined(options?.max)) {
@@ -189,371 +248,637 @@ var NumberField = class extends Field {
     }
     super(name, initialVal, { policies });
   }
+  isMin() {
+    const min = this.min;
+    return isNullOrUndefined(min) ? false : this.value <= min;
+  }
+  isMax() {
+    const max = this.max;
+    return isNullOrUndefined(max) ? false : this.value >= max;
+  }
   inc(amount = 1) {
-    this.set(this.val + amount);
+    this.value = this.value + amount;
   }
   dec(amount = 1) {
-    this.set(this.val - amount);
+    this.value = this.value - amount;
   }
 };
 
-// src/base-fields.ts
-import { signal as signal2 } from "@preact/signals-core";
-import { throwIf } from "@axi-engine/utils";
+// src/utils/constructor-registry.ts
+import { throwIf, throwIfEmpty } from "@axi-engine/utils";
+var ConstructorRegistry = class {
+  items = /* @__PURE__ */ new Map();
+  /**
+   * Registers a constructor with a unique string identifier.
+   *
+   * @param typeId - The unique identifier for the constructor (e.g., a static `typeName` property from a class).
+   * @param ctor - The class constructor to register.
+   * @returns The registry instance for chainable calls.
+   * @throws If a constructor with the same `typeId` is already registered.
+   */
+  register(typeId, ctor) {
+    throwIf(this.items.has(typeId), `A constructor with typeId '${typeId}' is already registered.`);
+    this.items.set(typeId, ctor);
+    return this;
+  }
+  /**
+   * Retrieves a constructor by its identifier.
+   *
+   * @param typeId - The identifier of the constructor to retrieve.
+   * @returns The found class constructor.
+   * @throws If no constructor is found for the given `typeId`.
+   */
+  get(typeId) {
+    const Ctor = this.items.get(typeId);
+    throwIfEmpty(Ctor, `No constructor found for typeId '${typeId}'`);
+    return Ctor;
+  }
+  /**
+   * Checks if a constructor for a given identifier is registered.
+   * @param typeId - The identifier to check.
+   * @returns `true` if a constructor is registered, otherwise `false`.
+   */
+  has(typeId) {
+    return this.items.has(typeId);
+  }
+  /**
+   * Clears all registered constructors from the registry.
+   */
+  clear() {
+    this.items.clear();
+  }
+};
 
-// ../events/src/event-emitter.ts
-import EventEmitter3 from "eventemitter3";
-var AxiEventEmitter = class extends EventEmitter3 {
-  // Currently, we don't need to add any custom logic.
-  // The main purpose of this class is to create an abstraction layer.
+// src/field-registry.ts
+var FieldRegistry = class extends ConstructorRegistry {
 };
 
-// src/base-fields.ts
-var BaseFields = class {
-  constructor() {
-    this._fields = signal2(/* @__PURE__ */ new Map());
-    this.events = new AxiEventEmitter();
-  }
+// src/fields.ts
+import { Emitter as Emitter2, throwIf as throwIf2 } from "@axi-engine/utils";
+var Fields = class _Fields {
+  static typeName = "fields";
+  typeName = _Fields.typeName;
+  _fields = /* @__PURE__ */ new Map();
+  _fieldRegistry;
+  /**
+   * An event emitter that fires when a new field is added to the collection.
+   * @event
+   * @param {object} event - The event payload.
+   * @param {string} event.name - The name of the added field.
+   * @param {Field<any>} event.field - The `Field` instance that was added.
+   */
+  onAdd = new Emitter2();
+  /**
+   * An event emitter that fires after one or more fields have been removed.
+   * @event
+   * @param {object} event - The event payload.
+   * @param {string[]} event.names - An array of names of the fields that were successfully removed.
+   */
+  onRemove = new Emitter2();
   /**
-   * A readonly signal providing access to the current map of fields.
-   * Use this signal with `effect` to react when fields are added or removed from the collection.
-   * Avoid to change any data in the map manually.
+   * Gets the read-only map of all `Field` instances in this container.
+   * @returns {Map<string, Field<any>>} The collection of fields.
    */
   get fields() {
     return this._fields;
   }
   /**
-   * Checks if a field with the given name exists in the collection.
-   * @param name The name of the field to check.
-   * @returns `true` if the field exists, otherwise `false`.
+   * Creates an instance of Fields.
+   * @param {FieldRegistry} fieldRegistry - The registry used to create new `Field` instances.
    */
-  has(name) {
-    return this._fields.value.has(name);
+  constructor(fieldRegistry) {
+    this._fieldRegistry = fieldRegistry;
   }
   /**
-   * Creates and adds a new `Field` to the collection.
-   * @param name The unique name for the new field.
-   * @param initialValue The initial value for the new field.
-   * @returns The newly created `Field` instance.
+   * Checks if a field with the given name exists in the collection.
+   * @param {string} name The name of the field to check.
+   * @returns {boolean} `true` if the field exists, otherwise `false`.
    */
-  create(name, initialValue) {
-    return this.add(new Field(name, initialValue));
+  has(name) {
+    return this._fields.has(name);
   }
   /**
-   * Adds a pre-existing `Field` instance to the collection.
-   * Throws an error if a field with the same name already exists.
-   * @param field The `Field` instance to add.
-   * @returns The added `Field` instance.
+   * Adds a pre-existing `Field` instance to the collection and fires the `onAdd` event.
+   * @template T - The specific `Field` type being added.
+   * @param {Field<any>} field - The `Field` instance to add.
+   * @returns {T} The added `Field` instance, cast to type `T`.
+   * @throws If a field with the same name already exists.
    */
   add(field) {
-    throwIf(this.has(field.name), `Field with name '${field.name}' already exists`);
-    const fieldsMap = new Map(this._fields.value);
-    fieldsMap.set(field.name, field);
-    this._fields.value = fieldsMap;
-    this.events.emit("created", {
-      fieldName: field.name,
+    throwIf2(this.has(field.name), `Field with name '${field.name}' already exists`);
+    this._fields.set(field.name, field);
+    this.onAdd.emit({
+      name: field.name,
       field
     });
     return field;
   }
   /**
-   * Retrieves a field by its name.
-   * Throws an error if the field does not exist.
-   * @param name The name of the field to retrieve.
-   * @returns The `Field` instance.
+   * Creates a new `Field` instance of a specified type, adds it to the collection, and returns it.
+   * This is the primary factory method for creating fields within this container.
+   * @template T - The expected `Field` type to be returned.
+   * @param {string} typeName - The registered type name of the field to create (e.g., 'numeric', 'boolean').
+   * @param {string} name - The unique name for the new field.
+   * @param {*} initialValue - The initial value for the new field.
+   * @param {*} [options] - Optional configuration passed to the field's constructor.
+   * @returns {T} The newly created `Field` instance.
    */
-  get(name) {
-    throwIf(!this._fields.value.has(name), `Field with name '${name}' not exists`);
-    return this._fields.value.get(name);
+  create(typeName, name, initialValue, options) {
+    const Ctor = this._fieldRegistry.get(typeName);
+    const field = new Ctor(name, initialValue, options);
+    this.add(field);
+    return field;
   }
   /**
-   * "Update or Insert": Updates a field's value if it exists, or creates a new one if it doesn't.
-   * @param name The name of the field.
-   * @param value The value to set.
-   * @returns The existing or newly created `Field` instance.
+   * Updates an existing field's value or creates a new one if it doesn't exist.
+   * @template T - The expected `Field` type.
+   * @param {string} typeName - The type name to use if a new field needs to be created.
+   * @param {string} name - The name of the field to update or create.
+   * @param {*} value - The new value to set.
+   * @param {*} [options] - Optional configuration, used only if a new field is created.
+   * @returns {T} The existing or newly created `Field` instance.
    */
-  upset(name, value) {
+  upset(typeName, name, value, options) {
     if (this.has(name)) {
       const field = this.get(name);
-      field.set(value);
+      field.value = value;
       return field;
     }
-    return this.create(name, value);
+    return this.create(typeName, name, value, options);
+  }
+  /**
+   * Retrieves a field by its name.
+   * @template T - The expected `Field` type to be returned.
+   * @param {string} name - The name of the field to retrieve.
+   * @returns {T} The `Field` instance.
+   * @throws If the field does not exist.
+   */
+  get(name) {
+    throwIf2(!this._fields.has(name), `Field with name '${name}' not exists`);
+    return this._fields.get(name);
   }
   /**
    * Removes one or more fields from the collection.
    * This method ensures that the `destroy` method of each removed field is called to clean up its resources.
-   * @param names A single name or an array of names to remove.
+   * @param {string| string[]} names A single name or an array of names to remove.
    */
   remove(names) {
     const namesToRemove = Array.isArray(names) ? names : [names];
-    const fieldsMap = new Map(this._fields.value);
     const reallyRemoved = namesToRemove.filter((name) => {
-      const field = fieldsMap.get(name);
+      const field = this._fields.get(name);
       if (!field) {
         return false;
       }
       field.destroy();
-      fieldsMap.delete(name);
-      return true;
+      return this._fields.delete(name);
     });
     if (!reallyRemoved.length) {
       return;
     }
-    this._fields.value = fieldsMap;
-    this.events.emit("removed", { fieldNames: reallyRemoved });
+    this.onRemove.emit({ names: reallyRemoved });
   }
   /**
    * Removes all fields from the collection, ensuring each is properly destroyed.
    */
   clear() {
-    this.remove(Array.from(this._fields.value.keys()));
-  }
-  /**
-   * Creates a serializable snapshot of the current state of all fields.
-   * @returns A plain JavaScript object representing the values of all fields.
-   */
-  snapshot() {
-    const dump = {
-      __type: "Fields" /* fields */
-    };
-    this._fields.value.forEach((field, key) => dump[key] = field.val);
-    return dump;
-  }
-  /**
-   * Restores the state of the fields from a snapshot.
-   * It uses the `upset` logic to create or update fields based on the snapshot data.
-   * @param snapshot The snapshot object to load.
-   */
-  hydrate(snapshot) {
-    for (let key in snapshot) {
-      if (key === "__type") {
-        continue;
-      }
-      this.upset(key, snapshot[key]);
-    }
+    this.remove(Array.from(this._fields.keys()));
   }
 };
 
-// src/fields.ts
-import { throwIf as throwIf2 } from "@axi-engine/utils";
-var Fields = class extends BaseFields {
-  createNumber(name, initialValue, options) {
-    return this.add(new NumberField(name, initialValue, options));
-  }
-  upsetNumber(name, value, options) {
-    if (this.has(name)) {
-      const field = this.getNumber(name);
-      field.set(value);
-      return field;
+// src/mixins/with-boolean-fields.mixin.ts
+function WithBooleanFields(Base) {
+  return class FieldsWithBoolean extends Base {
+    createBoolean(name, initialValue, options) {
+      return this.create(DefaultBooleanField.typeName, name, initialValue, options);
     }
-    return this.createNumber(name, value, options);
-  }
-  getNumber(name) {
-    const field = this.get(name);
-    throwIf2(!(field instanceof NumberField), `wrong field type, field ${name} not a instance of NUmberField`);
-    return field;
-  }
-  create(name, initialValue) {
-    return this.add(new Field(name, initialValue));
-  }
-  upset(name, value) {
-    if (this.has(name)) {
-      const field = this.get(name);
-      field.set(value);
-      return field;
+    upsetBoolean(name, value, options) {
+      return this.upset(DefaultBooleanField.typeName, name, value, options);
     }
-    return this.create(name, value);
-  }
-  get(name) {
-    throwIf2(!this._fields.value.has(name), `Field with name '${name}' not exists`);
-    return this._fields.value.get(name);
-  }
-};
+    getBoolean(name) {
+      return this.get(name);
+    }
+  };
+}
 
-// src/typed-fields.ts
-var TypedFields = class extends BaseFields {
+// src/mixins/with-string-fields.mixin.ts
+function WithStringFields(Base) {
+  return class FieldsWithString extends Base {
+    createString(name, initialValue, options) {
+      return this.create(DefaultStringField.typeName, name, initialValue, options);
+    }
+    upsetString(name, value, options) {
+      return this.upset(DefaultStringField.typeName, name, value, options);
+    }
+    getString(name) {
+      return this.get(name);
+    }
+  };
+}
+
+// src/mixins/with-numeric-fields.mixin.ts
+function WithNumericFields(Base) {
+  return class FieldsWithNumeric extends Base {
+    createNumeric(name, initialValue, options) {
+      return this.create(DefaultNumericField.typeName, name, initialValue, options);
+    }
+    upsetNumeric(name, value, options) {
+      return this.upset(DefaultNumericField.typeName, name, value, options);
+    }
+    getNumeric(name) {
+      return this.get(name);
+    }
+  };
+}
+
+// src/mixins/with-default-fields.mixin.ts
+function WithDefaultFields(Base) {
+  return class FieldsWithDefault extends Base {
+    createDefault(name, initialValue, options) {
+      return this.create(DefaultField.typeName, name, initialValue, options);
+    }
+    upsetDefault(name, value, options) {
+      return this.upset(DefaultField.typeName, name, value, options);
+    }
+  };
+}
+
+// src/default-fields.ts
+var DefaultFields = class extends WithBooleanFields(WithStringFields(WithNumericFields(WithDefaultFields(Fields)))) {
 };
 
 // src/field-tree.ts
-import { signal as signal3 } from "@preact/signals-core";
-import { ensurePathArray, ensurePathString, throwIf as throwIf3, throwIfEmpty } from "@axi-engine/utils";
+import { ensurePathArray, ensurePathString, throwIf as throwIf3, throwIfEmpty as throwIfEmpty2 } from "@axi-engine/utils";
 var FieldTree = class _FieldTree {
-  constructor() {
-    this.events = new AxiEventEmitter();
-    this._items = signal3(/* @__PURE__ */ new Map());
+  static typeName = "fieldTree";
+  typeName = _FieldTree.typeName;
+  /** @private The internal map storing child nodes (branches or leaves). */
+  _nodes = /* @__PURE__ */ new Map();
+  /** @private The factory used to create new child nodes. */
+  _factory;
+  /**
+   * Gets the collection of direct child nodes of this tree branch.
+   */
+  get nodes() {
+    return this._nodes;
   }
   /**
-   * A readonly signal providing access to the map of child nodes.
-   * Use this with `effect` to react to structural changes in the tree (e.g., adding a new `Fields` container).
+   * Creates an instance of FieldTree.
+   * @param {TreeNodeFactory} factory - A factory responsible for creating new nodes within the tree.
    */
-  get items() {
-    return this._items;
+  constructor(factory) {
+    this._factory = factory;
+  }
+  /**
+   * Checks if a direct child node with the given name exists.
+   * @param {string} name - The name of the direct child node.
+   * @returns {boolean} `true` if the node exists, otherwise `false`.
+   */
+  has(name) {
+    return this._nodes.has(name);
   }
   /**
-   * Checks if a path to a node or fields container  or field exists without creating it.
-   * @returns true if the entire path exists, false otherwise.
+   * Checks if a node exists at a given path, traversing the tree.
+   * @param {PathType} path - The path to check (e.g., 'player/stats' or ['player', 'stats']).
+   * @returns {boolean} `true` if the entire path resolves to a node, otherwise `false`.
    */
   hasPath(path) {
-    const pathParts = ensurePathArray(path);
-    let currentNode = this;
-    for (let i = 0; i < pathParts.length; i++) {
-      const part = pathParts[i];
-      const nextNode = currentNode._items.value.get(part);
-      if (!nextNode) {
-        return false;
-      }
-      if (nextNode instanceof BaseFields) {
-        if (i === pathParts.length - 1) {
-          return true;
-        }
-        throwIf3(
-          pathParts.length - i > 2,
-          `Path validation failed, full path: ${ensurePathString(path)}, has extra nodes after Fields placed at: ${ensurePathString(pathParts.slice(0, i + 1))}`
-        );
-        return nextNode.has(pathParts[i + 1]);
-      }
-      currentNode = nextNode;
-    }
-    return true;
+    const traversedPath = this.traversePath(path);
+    return traversedPath.branch.has(traversedPath.leafName);
   }
   /**
-   * Retrieves a child node and asserts that it is an instance of `FieldTree`.
-   * @param name The name of the child node.
-   * @returns The `FieldTree` instance.
-   * @throws If the node does not exist or is not a `FieldTree`.
+   * Adds a pre-existing node as a direct child of this tree branch.
+   * @param {string} name - The name to assign to the new child node.
+   * @param {TreeOrFieldsNode} node - The node instance to add.
+   * @returns {TreeOrFieldsNode} The added node.
+   * @throws If a node with the same name already exists.
    */
-  getFieldTree(name) {
-    const node = this.getNode(name);
-    throwIf3(!(node instanceof _FieldTree), `Node '${name}' should be instance of FieldTree`);
+  addNode(name, node) {
+    throwIf3(this.has(name), `Can't add node with name: '${name}', node already exists`);
+    this._nodes.set(name, node);
     return node;
   }
   /**
-   * Retrieves a child node and asserts that it is an instance of `Fields`.
-   * @param name The name of the child node.
-   * @returns The `Fields` instance.
-   * @throws If the node does not exist or is not a `Fields` container.
+   * Retrieves a direct child node by its name.
+   * @param {string} name - The name of the child node.
+   * @returns {TreeOrFieldsNode} The retrieved node.
+   * @throws If a node with the given name cannot be found.
    */
-  getFields(name) {
-    const node = this.getNode(name);
-    throwIf3(!(node instanceof Fields), `Node '${name}' should be instance of Fields`);
+  getNode(name) {
+    const node = this._nodes.get(name);
+    throwIfEmpty2(node, `Can't find node with name '${name}'`);
     return node;
   }
   /**
-   * Retrieves a child node and asserts that it is an instance of `TypedFields`.
-   * @param name The name of the child node.
-   * @returns The `TypedFields` instance.
-   * @throws If the node does not exist or is not a `TypedFields` container.
+   * Creates a new `FieldTree` (branch) node at the specified path.
+   * @param {PathType} path - The path where the new `FieldTree` should be created.
+   * @param {boolean} [createPath=false] - If `true`, any missing parent branches in the path will be created automatically.
+   * @returns {FieldTree} The newly created `FieldTree` instance.
+   * @throws If the path is invalid or a node already exists at the target location.
    */
-  getTypedFields(name) {
-    const node = this.getNode(name);
-    throwIf3(!(node instanceof TypedFields), `Node '${name}' should be instance of TypedFields`);
+  createFieldTree(path, createPath) {
+    const traversedPath = this.traversePath(path, createPath);
+    return traversedPath.branch.addNode(traversedPath.leafName, this._factory.tree());
+  }
+  /**
+   * Creates a new `Fields` (leaf) container at the specified path.
+   * @param {PathType} path - The path where the new `Fields` container should be created.
+   * @param {boolean} [createPath=false] - If `true`, any missing parent branches in the path will be created automatically.
+   * @returns {Fields} The newly created `Fields` instance.
+   * @throws If the path is invalid or a node already exists at the target location.
+   */
+  createFields(path, createPath) {
+    const traversedPath = this.traversePath(path, createPath);
+    return traversedPath.branch.addNode(traversedPath.leafName, this._factory.fields());
+  }
+  /**
+   * Retrieves a `FieldTree` (branch) node from a specified path.
+   * @param {PathType} path - The path to the `FieldTree` node.
+   * @returns {FieldTree} The `FieldTree` instance at the specified path.
+   * @throws If the path is invalid or the node at the path is not a `FieldTree`.
+   */
+  getFieldTree(path) {
+    const traversedPath = this.traversePath(path);
+    const node = traversedPath.branch.getNode(traversedPath.leafName);
+    throwIf3(
+      !(node instanceof _FieldTree),
+      `Node with name: ${traversedPath.leafName} by path: '${ensurePathString(path)}' should be instance of FieldTree`
+    );
     return node;
   }
   /**
-   * Retrieves a child node from this tree level without type checking.
-   * @param name The name of the child node.
-   * @returns The retrieved node, which can be a `FieldTree` or a `Fields` container.
-   * @throws If a node with the given name cannot be found.
+   * Retrieves a `Fields` (leaf) container from a specified path.
+   * @param {PathType} path - The path to the `Fields` container.
+   * @returns {Fields} The `Fields` instance at the specified path.
+   * @throws If the path is invalid or the node at the path is not a `Fields` container.
    */
-  getNode(name) {
-    const node = this._items.value.get(name);
-    throwIfEmpty(node, `Can't find node with name '${name}'`);
+  getFields(path) {
+    const traversedPath = this.traversePath(path);
+    const node = traversedPath.branch.getNode(traversedPath.leafName);
+    throwIf3(
+      !(node instanceof Fields),
+      `Node with name: ${traversedPath.leafName} by path: '${ensurePathString(path)}' should be instance of Fields`
+    );
     return node;
   }
   /**
-   * Creates and adds a new `FieldTree` node as a child of this one.
-   * @param name The unique name for the new `FieldTree` node.
-   * @returns The newly created `FieldTree` instance.
+   * Retrieves a `FieldTree` at the specified path. If it or any part of the path doesn't exist, it will be created.
+   * @param {PathType} path - The path to the `FieldTree` node.
+   * @returns {FieldTree} The existing or newly created `FieldTree` instance.
    */
-  createFieldTree(name) {
-    return this.createNode(name, _FieldTree);
+  getOrCreateFieldTree(path) {
+    const traversedPath = this.traversePath(path, true);
+    return traversedPath.branch.has(traversedPath.leafName) ? traversedPath.branch.getFieldTree(traversedPath.leafName) : traversedPath.branch.createFieldTree(traversedPath.leafName);
   }
   /**
-   * Creates and adds a new `Fields` container as a child of this one.
-   * @param name The unique name for the new `Fields` container.
-   * @returns The newly created `Fields` instance.
+   * Retrieves a `Fields` container at the specified path. If it or any part of the path doesn't exist, it will be created.
+   * @param {PathType} path - The path to the `Fields` container.
+   * @returns {Fields} The existing or newly created `Fields` instance.
    */
-  createFields(name) {
-    return this.createNode(name, Fields);
+  getOrCreateFields(path) {
+    const traversedPath = this.traversePath(path, true);
+    return traversedPath.branch.has(traversedPath.leafName) ? traversedPath.branch.getFields(traversedPath.leafName) : traversedPath.branch.createFields(traversedPath.leafName);
   }
   /**
-   * Creates and adds a new `TypedFields` container as a child of this one.
-   * @param name The unique name for the new `TypedFields` container.
-   * @returns The newly created `TypedFields` instance.
+   * @private
+   * Navigates the tree to the parent of a target node.
+   * This is the core traversal logic for all path-based operations.
+   * @param {PathType} path - The full path to the target node.
+   * @param {boolean} [createPath=false] - If `true`, creates missing `FieldTree` branches along the path.
+   * @returns {{branch: FieldTree, leafName: string}} An object containing the final branch (parent node) and the name of the leaf (target node).
+   * @throws If the path is empty, invalid, or contains a `Fields` container as an intermediate segment.
+   */
+  traversePath(path, createPath) {
+    const pathArr = ensurePathArray(path);
+    throwIfEmpty2(pathArr, "The path is empty");
+    const leafName = pathArr.pop();
+    let currentNode = this;
+    for (const pathPart of pathArr) {
+      let node;
+      if (currentNode.has(pathPart)) {
+        node = currentNode.getNode(pathPart);
+      } else {
+        if (createPath) {
+          node = currentNode.createFieldTree(pathPart);
+        }
+      }
+      throwIfEmpty2(node, `Can't find node with name ${pathPart} by path parsing: ${ensurePathString(path)}`);
+      throwIf3(node instanceof Fields, `Node with name ${pathPart} should be instance of FieldTree`);
+      currentNode = node;
+    }
+    return { branch: currentNode, leafName };
+  }
+};
+
+// src/field-tree-node-factory.ts
+var DefaultTreeNodeFactory = class {
+  constructor(fieldRegistry) {
+    this.fieldRegistry = fieldRegistry;
+  }
+  fields = () => new DefaultFields(this.fieldRegistry);
+  tree = () => new FieldTree(this);
+};
+
+// src/serializer/policies/clamp-policy-serializer-handler.ts
+var ClampPolicySerializerHandler = class {
+  snapshot(policy) {
+    return { min: policy.min, max: policy.max };
+  }
+  hydrate(data) {
+    return new ClampPolicy(data.min, data.max);
+  }
+};
+
+// src/serializer/policies/clamp-max-policy-serializer-handler.ts
+var ClampMaxPolicySerializerHandler = class {
+  snapshot(policy) {
+    return { max: policy.max };
+  }
+  hydrate(data) {
+    return new ClampMaxPolicy(data.max);
+  }
+};
+
+// src/serializer/policies/clamp-min-policy-serializer-handler.ts
+var ClampMinPolicySerializerHandler = class {
+  snapshot(policy) {
+    return { min: policy.min };
+  }
+  hydrate(data) {
+    return new ClampMinPolicy(data.min);
+  }
+};
+
+// src/serializer/policy-serializer.ts
+import { throwIf as throwIf4, throwIfEmpty as throwIfEmpty3 } from "@axi-engine/utils";
+var PolicySerializer = class {
+  handlers = /* @__PURE__ */ new Map();
+  register(policyId, handler) {
+    throwIf4(this.handlers.has(policyId), `A handler for policy ID '${policyId}' is already registered.`);
+    this.handlers.set(policyId, handler);
+    return this;
+  }
+  clearHandlers() {
+    this.handlers.clear();
+  }
+  /**
+   * Creates a serializable snapshot of a policy instance.
+   * The snapshot includes the policy's state and a `__type` identifier.
+   * @param policy The policy instance to snapshot.
+   * @returns A plain object ready for JSON serialization.
+   * @throws If no handler is registered for the policy's ID.
+   */
+  snapshot(policy) {
+    const handler = this.handlers.get(policy.id);
+    throwIfEmpty3(handler, `No serializer handler registered for policy ID: '${policy.id}'`);
+    const data = handler.snapshot(policy);
+    return {
+      __type: policy.id,
+      ...data
+    };
+  }
+  /**
+   * Restores a policy instance from its snapshot representation.
+   * @param snapshot The plain object snapshot, which must contain a `__type` property.
+   * @returns A new, fully functional policy instance.
+   * @throws If the snapshot is invalid or no handler is registered for its `__type`.
+   */
+  hydrate(snapshot) {
+    const typeId = snapshot?.__type;
+    throwIfEmpty3(typeId, 'Invalid policy snapshot: missing "__type" identifier.');
+    const handler = this.handlers.get(typeId);
+    throwIfEmpty3(handler, `No serializer handler registered for policy ID: '${typeId}'`);
+    const { __type, ...data } = snapshot;
+    return handler.hydrate(data);
+  }
+};
+
+// src/serializer/field-serializer.ts
+import { isNullOrUndefined as isNullOrUndefined2, throwIfEmpty as throwIfEmpty4 } from "@axi-engine/utils";
+var FieldSerializer = class {
+  /**
+   * Creates an instance of FieldSerializer.
+   * @param {FieldRegistry} fieldRegistry - A registry that maps string type names to Field constructors.
+   * @param {PolicySerializer} policySerializer - A serializer dedicated to handling Policy instances.
    */
-  createTypedFields(name) {
-    return this.createNode(name, TypedFields);
+  constructor(fieldRegistry, policySerializer) {
+    this.fieldRegistry = fieldRegistry;
+    this.policySerializer = policySerializer;
   }
   /**
-   * Navigates through the tree using a path and returns the `Fields` container at the end.
-   * @param path The path to the `Fields` container (e.g., 'player/stats').
-   * @returns The `Fields` container at the specified path.
-   * @throws If the path is empty, or any intermediate node is not a `FieldTree`.
+   * Creates a serializable snapshot of a Field instance.
+   * The snapshot includes the field's type, name, current value, and the state of all its policies.
+   * @param {Field<any>} field - The Field instance to serialize.
+   * @returns {FieldSnapshot} A plain object ready for JSON serialization.
    */
-  getFieldsByPath(path) {
-    const pathParts = ensurePathArray(path);
-    throwIf3(!pathParts.length, "Empty path");
-    let container = this;
-    for (let i = 0; i < pathParts.length - 1; i++) {
-      container = container.getFieldTree(pathParts[i]);
+  snapshot(field) {
+    let snapshot = {
+      __type: field.typeName,
+      name: field.name,
+      value: field.value
+    };
+    if (!field.policies.isEmpty()) {
+      const serializedPolicies = [];
+      field.policies.items.forEach((policy) => serializedPolicies.push(this.policySerializer.snapshot(policy)));
+      snapshot.policies = serializedPolicies;
     }
-    return container.getFields(pathParts[pathParts.length - 1]);
+    return snapshot;
   }
   /**
-   * Creates a `Field` at a deeply nested path.
-   * The last part of the path is treated as the field name, and the preceding parts as the path to its container.
-   * @param path The full path to the new field (e.g., 'player/stats/health').
-   * @param initialValue The initial value for the new field.
-   * @returns The newly created `Field` instance.
+   * Restores a Field instance from its snapshot representation.
+   * It uses the `__type` property to find the correct constructor and hydrates
+   * the field with its value and all its policies.
+   * @param {FieldSnapshot} snapshot - The plain object snapshot to deserialize.
+   * @returns {Field<any>} A new, fully functional Field instance.
+   * @throws If the snapshot is invalid, missing a `__type`, or if the type is not registered.
    */
-  create(path, initialValue) {
-    const fullPath = [...ensurePathArray(path)];
-    const fieldName = fullPath.pop();
-    throwIf3(!fullPath.length, `Wrong path format of one field creating: '${ensurePathString(path)}', should be at least two sections`);
-    return this.getFieldsByPath(fullPath).create(fieldName, initialValue);
+  hydrate(snapshot) {
+    const fieldType = snapshot.__type;
+    throwIfEmpty4(fieldType, 'Invalid field snapshot: missing "__type" identifier.');
+    const Ctor = this.fieldRegistry.get(fieldType);
+    let policies;
+    if (!isNullOrUndefined2(snapshot.policies)) {
+      policies = [];
+      snapshot.policies.forEach((p) => policies.push(this.policySerializer.hydrate(p)));
+    }
+    return new Ctor(snapshot.name, snapshot.value, { policies });
   }
+};
+
+// src/serializer/fields-serializer.ts
+var FieldsSerializer = class {
   /**
-   * Creates a `NumberField` at a deeply nested path.
-   * @param path The full path to the new field (e.g., 'player/stats/mana').
-   * @param initialValue The initial numeric value.
-   * @returns The newly created `NumberField` instance.
+   * Creates an instance of FieldsSerializer.
+   * @param {FieldRegistry} fieldRegistry - A registry that maps string type names to Field constructors.
+   * @param {PolicySerializer} policySerializer - A serializer dedicated to handling Policy instances.
    */
-  createNumber(path, initialValue) {
-    const fullPath = [...ensurePathArray(path)];
-    const fieldName = fullPath.pop();
-    return this.getFieldsByPath(fullPath).createNumber(fieldName, initialValue);
+  constructor(fieldRegistry, policySerializer) {
+    this.fieldRegistry = fieldRegistry;
+    this.policySerializer = policySerializer;
+    this.fieldSerializer = new FieldSerializer(this.fieldRegistry, this.policySerializer);
   }
   /**
-   * Retrieves a `Field` from a deeply nested path.
-   * @param path The full path to the field (e.g., 'player/stats/name').
-   * @returns The `Field` instance at the specified path.
+   * An internal instance of FieldSerializer to handle individual fields.
+   * @private
+   */
+  fieldSerializer;
+  /**
+   * Creates a serializable snapshot of a `Fields` container.
+   *
+   * The snapshot includes a `__type` identifier (currently hardcoded) and an array of snapshots
+   * for each `Field` within the container.
+   * @param {Fields} fields - The `Fields` instance to serialize.
+   * @returns {FieldsSnapshot} A plain object ready for JSON serialization.
    */
-  get(path) {
-    const fullPath = [...ensurePathArray(path)];
-    const fieldName = fullPath.pop();
-    return this.getFieldsByPath(fullPath).get(fieldName);
+  snapshot(fields) {
+    const res = {
+      __type: fields.typeName
+    };
+    fields.fields.forEach((field) => res[field.name] = this.fieldSerializer.snapshot(field));
+    return res;
   }
   /**
-   * Retrieves a `NumberField` from a deeply nested path.
-   * @param path The full path to the number field (e.g., 'player/stats/level').
-   * @returns The `NumberField` instance at the specified path.
+   * Restores a `Fields` container instance from its snapshot representation.
+   *
+   * **Limitation:** This method is currently hardcoded to always create an instance of `DefaultFields`.
+   * It iterates through the field snapshots and hydrates them individually, adding them to the new container.
+   * @param {FieldsSnapshot} snapshot - The plain object snapshot to deserialize.
+   * @returns {DefaultFields} A new `DefaultFields` instance populated with the restored fields.
    */
-  getNumber(path) {
-    const fullPath = [...ensurePathArray(path)];
-    const fieldName = fullPath.pop();
-    return this.getFieldsByPath(fullPath).getNumber(fieldName);
+  hydrate(snapshot) {
+    const { __type, ...fieldsData } = snapshot;
+    const fields = new DefaultFields(this.fieldRegistry);
+    for (const fieldName in fieldsData) {
+      const fieldSnapshot = fieldsData[fieldName];
+      const restoredField = this.fieldSerializer.hydrate(fieldSnapshot);
+      fields.add(restoredField);
+    }
+    return fields;
+  }
+};
+
+// src/serializer/field-tree-serializer.ts
+import { isString } from "@axi-engine/utils";
+var FieldTreeSerializer = class {
+  constructor(fieldTreeNodeFactory, fieldsSerializer) {
+    this.fieldTreeNodeFactory = fieldTreeNodeFactory;
+    this.fieldsSerializer = fieldsSerializer;
   }
   /**
    * Creates a serializable snapshot of the entire tree and its contained fields.
    * @returns A plain JavaScript object representing the complete state managed by this tree.
    */
-  snapshot() {
-    const dump = {
-      __type: "FieldTree" /* fieldTree */
+  snapshot(tree) {
+    const res = {
+      __type: tree.typeName
     };
-    this._items.value.forEach((node, key) => dump[key] = node.snapshot());
-    return dump;
+    tree.nodes.forEach((node, key) => {
+      if (node.typeName === tree.typeName) {
+        res[key] = this.snapshot(node);
+      } else if (node.typeName === Fields.typeName) {
+        res[key] = this.fieldsSerializer.snapshot(node);
+      }
+    });
+    return res;
   }
   /**
    * Restores the state of the tree from a snapshot.
@@ -561,60 +886,43 @@ var FieldTree = class _FieldTree {
    * @param snapshot The snapshot object to load.
    */
   hydrate(snapshot) {
-    for (const key in snapshot) {
-      if (key === "__type") {
+    const { __type, ...nodes } = snapshot;
+    const tree = this.fieldTreeNodeFactory.tree();
+    for (const key in nodes) {
+      const nodeData = nodes[key];
+      if (isString(nodeData)) {
         continue;
       }
-      const field = snapshot[key];
-      const type = field?.__type;
-      let node = this._items.value.get(key);
-      if (!node) {
-        if (type === "Fields" /* fields */) {
-          node = this.createFields(key);
-        } else if (type === "FieldTree" /* fieldTree */) {
-          node = this.createFieldTree(key);
-        } else {
-          console.warn(`Node '${key}' in snapshot has no __type metadata. Skipping.`);
-        }
+      if (nodeData.__type === FieldTree.typeName) {
+        tree.addNode(key, this.hydrate(nodeData));
+      } else {
+        tree.addNode(key, this.fieldsSerializer.hydrate(nodeData));
       }
-      node?.hydrate(field);
     }
-  }
-  /**
-   * @private
-   * Generic internal method for creating and adding a new node to the tree.
-   * @param name The name of the node to create.
-   * @param ctor The constructor for the node type (e.g., `FieldTree` or `Fields`).
-   * @returns The newly created node instance.
-   */
-  createNode(name, ctor) {
-    const currentItems = this._items.value;
-    throwIf3(currentItems.has(name), `Can't create node with name: '${name}', node already exists`);
-    const res = new ctor();
-    const newItems = new Map(currentItems);
-    newItems.set(name, res);
-    this._items.value = newItems;
-    this.events.emit("created", {
-      type: "created",
-      name,
-      path: [],
-      // todo: need to decide how to pass full path
-      node: res
-    });
-    return res;
+    return tree;
   }
 };
 export {
-  BaseFields,
   ClampMaxPolicy,
+  ClampMaxPolicySerializerHandler,
   ClampMinPolicy,
+  ClampMinPolicySerializerHandler,
   ClampPolicy,
-  Field,
+  ClampPolicySerializerHandler,
+  DefaultBooleanField,
+  DefaultField,
+  DefaultFields,
+  DefaultNumericField,
+  DefaultStringField,
+  DefaultTreeNodeFactory,
+  FieldRegistry,
+  FieldSerializer,
   FieldTree,
+  FieldTreeSerializer,
   Fields,
-  FieldsNodeType,
-  NumberField,
-  TypedFields,
+  FieldsSerializer,
+  Policies,
+  PolicySerializer,
   clampMaxPolicy,
   clampMinPolicy,
   clampPolicy