@axi-engine/fields 0.2.0 → 0.2.1

package/dist/index.d.mts

@@ -330,6 +330,7 @@ declare class Fields {
      * Removes all fields from the collection, ensuring each is properly destroyed.
      */
     clear(): void;
+    destroy(): void;
 }
 
 declare const DefaultFields_base: {
@@ -355,6 +356,7 @@ declare const DefaultFields_base: {
         get<T extends Field<any>>(name: string): T;
         remove(names: string | string[]): void;
         clear(): void;
+        destroy(): void;
     };
 } & {
     new (...args: any[]): {
@@ -379,6 +381,7 @@ declare const DefaultFields_base: {
         get<T extends Field<any>>(name: string): T;
         remove(names: string | string[]): void;
         clear(): void;
+        destroy(): void;
     };
 } & {
     new (...args: any[]): {
@@ -403,6 +406,7 @@ declare const DefaultFields_base: {
         get<T extends Field<any>>(name: string): T;
         remove(names: string | string[]): void;
         clear(): void;
+        destroy(): void;
     };
 } & {
     new (...args: any[]): {
@@ -426,31 +430,38 @@ declare const DefaultFields_base: {
         get<T extends Field<any>>(name: string): T;
         remove(names: string | string[]): void;
         clear(): void;
+        destroy(): void;
     };
 } & typeof Fields;
 declare class DefaultFields extends DefaultFields_base {
 }
 
+interface FieldsFactory<TFields extends Fields> {
+    fields(): TFields;
+}
+declare class DefaultFieldsFactory implements FieldsFactory<DefaultFields> {
+    private readonly fieldRegistry;
+    constructor(fieldRegistry: FieldRegistry);
+    fields(): DefaultFields;
+}
 /**
  * Defines the contract for a factory that creates nodes for a FieldTree.
  * This allows for custom implementations of Fields and FieldTree to be used.
  */
-interface TreeNodeFactory {
-    fields<T extends Fields>(): T;
-    tree<T extends FieldTree>(): T;
+interface TreeNodeFactory<TFields extends Fields> extends FieldsFactory<TFields> {
+    fields(): TFields;
+    tree(): FieldTree<TFields>;
 }
 /**
  * The default factory implementation that creates standard DefaultFields and FieldTree instances.
  */
-declare class DefaultTreeNodeFactory implements TreeNodeFactory {
-    private readonly fieldRegistry;
+declare class DefaultTreeNodeFactory extends DefaultFieldsFactory implements TreeNodeFactory<DefaultFields> {
     constructor(fieldRegistry: FieldRegistry);
-    fields: () => any;
-    tree: () => any;
+    tree(): FieldTree<DefaultFields>;
 }
 
 /** A type alias for any container that can be a child node in a FieldTree */
-type TreeOrFieldsNode = FieldTree | Fields;
+type TreeNode<F extends Fields> = FieldTree<F> | F;
 /**
  * Represents a hierarchical data structure for managing the global state of the system.
  *
@@ -459,26 +470,51 @@ type TreeOrFieldsNode = FieldTree | Fields;
  * and overall game progress. It uses a path-based system for accessing and
  * manipulating nested data, similar to a file system.
  *
- * @todo
- * - Add node removal functionality.
- * - Implement an event system for node creation/removal.
  */
-declare class FieldTree {
+declare class FieldTree<TFields extends Fields> {
     static readonly typeName = "fieldTree";
     readonly typeName = "fieldTree";
     /** @private The internal map storing child nodes (branches or leaves). */
     private readonly _nodes;
     /** @private The factory used to create new child nodes. */
     private readonly _factory;
+    /**
+     * An event emitter that fires immediately after a new node is added to this tree branch.
+     * @event
+     * @param {object} event - The event payload.
+     * @param {string} event.name - The name (key) of the added node.
+     * @param event.node - The node instance that was added.
+     * @example
+     * myTree.onAdd.subscribe(({ name, node }) => {
+     *   console.log(`Node '${name}' was added.`, node);
+     * });
+     */
+    onAdd: Emitter<[event: {
+        name: string;
+        node: TreeNode<TFields>;
+    }]>;
+    /**
+     * An event emitter that fires once after one or more nodes have been successfully removed.
+     * @event
+     * @param {object} event - The event payload.
+     * @param {string[]} event.names - An array of names of the nodes that were removed.
+     * @example
+     * myTree.onRemove.subscribe(({ names }) => {
+     *   console.log(`Nodes removed: ${names.join(', ')}`);
+     * });
+     */
+    onRemove: Emitter<[event: {
+        names: string[];
+    }]>;
     /**
      * Gets the collection of direct child nodes of this tree branch.
      */
-    get nodes(): Map<string, TreeOrFieldsNode>;
+    get nodes(): Map<string, TreeNode<TFields>>;
     /**
      * Creates an instance of FieldTree.
      * @param {TreeNodeFactory} factory - A factory responsible for creating new nodes within the tree.
      */
-    constructor(factory: TreeNodeFactory);
+    constructor(factory: TreeNodeFactory<TFields>);
     /**
      * Checks if a direct child node with the given name exists.
      * @param {string} name - The name of the direct child node.
@@ -494,18 +530,29 @@ declare class 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.
+     * @param {TreeNode} node - The node instance to add.
+     * @returns {TreeNode} The added node.
      * @throws If a node with the same name already exists.
      */
-    addNode(name: string, node: TreeOrFieldsNode): TreeOrFieldsNode;
+    addNode(name: string, node: TreeNode<TFields>): TreeNode<TFields>;
     /**
      * Retrieves a direct child node by its name.
      * @param {string} name - The name of the child node.
-     * @returns {TreeOrFieldsNode} The retrieved node.
+     * @returns {TreeNode} The retrieved node.
      * @throws If a node with the given name cannot be found.
      */
-    getNode(name: string): TreeOrFieldsNode;
+    getNode(name: string): TreeNode<TFields>;
+    /**
+     * Removes one or more nodes from this tree branch.
+     *
+     * This method first validates that all specified nodes exist. If validation passes,
+     * it recursively calls `destroy()` on each node to ensure proper cleanup of the entire subtree.
+     * Finally, it emits a single `onRemove` event with the names of all successfully removed nodes.
+     *
+     * @param {string | string[]} names - A single name or an array of names of the nodes to remove.
+     * @throws If any of the specified names do not correspond to an existing node.
+     */
+    removeNode(names: string | string[]): void;
     /**
      * Creates a new `FieldTree` (branch) node at the specified path.
      * @param {PathType} path - The path where the new `FieldTree` should be created.
@@ -513,7 +560,7 @@ declare class FieldTree {
      * @returns {FieldTree} The newly created `FieldTree` instance.
      * @throws If the path is invalid or a node already exists at the target location.
      */
-    createFieldTree<T extends FieldTree>(path: PathType, createPath?: boolean): T;
+    createFieldTree<T extends FieldTree<TFields>>(path: PathType, createPath?: boolean): T;
     /**
      * Creates a new `Fields` (leaf) container at the specified path.
      * @param {PathType} path - The path where the new `Fields` container should be created.
@@ -521,33 +568,47 @@ declare class FieldTree {
      * @returns {Fields} The newly created `Fields` instance.
      * @throws If the path is invalid or a node already exists at the target location.
      */
-    createFields<T extends Fields>(path: PathType, createPath?: boolean): T;
+    createFields(path: PathType, createPath?: boolean): TFields;
     /**
      * 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: PathType): FieldTree;
+    getFieldTree(path: PathType): FieldTree<TFields>;
     /**
      * 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.
      */
-    getFields(path: PathType): Fields;
+    getFields(path: PathType): TFields;
     /**
      * 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.
      */
-    getOrCreateFieldTree(path: PathType): FieldTree;
+    getOrCreateFieldTree(path: PathType): FieldTree<TFields>;
     /**
      * 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.
      */
     getOrCreateFields(path: PathType): Fields;
+    /**
+     * Removes all child nodes from this tree branch.
+     * This method ensures that `destroy()` is called on each child node, allowing for
+     * a full, recursive cleanup of the entire subtree.
+     */
+    clear(): void;
+    /**
+     * Performs a complete cleanup of this node and its entire subtree.
+     *
+     * It recursively destroys all child nodes by calling `clear()` and then
+     * unsubscribes all listeners from its own event emitters.
+     * This method should be called when a node is no longer needed.
+     */
+    destroy(): void;
     /**
      * @private
      * Navigates the tree to the parent of a target node.
@@ -699,30 +760,19 @@ interface FieldsSnapshot {
  * into a storable snapshot and back.
  * It delegates the actual serialization of each `Field` and `Policy` to their respective serializers.
  *
- * @todo This implementation is coupled to creating `DefaultFields` instances during hydration.
- *       To make the system fully extensible, this class should be refactored to use a
- *       `FieldsRegistry` (a `ConstructorRegistry<Fields>`). This would allow it to
- *       hydrate any custom `Fields` class (e.g., `ReactiveFields`) based on the `__type`
- *       property in the snapshot, mirroring the pattern used by `FieldSerializer`.
- *
  * @todo Implement a `patch(fields, snapshot)` method. It should perform a non-destructive
  *       update, creating new fields, removing missing ones, and patching existing ones
  *       in place, preserving the container instance itself.
  */
-declare class FieldsSerializer {
-    private readonly fieldRegistry;
-    private readonly policySerializer;
-    /**
-     * An internal instance of FieldSerializer to handle individual fields.
-     * @private
-     */
+declare class FieldsSerializer<TFields extends Fields> {
+    private readonly fieldsFactory;
     private readonly fieldSerializer;
     /**
      * 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.
+     * @param {FieldsFactory} fieldsFactory - A registry that maps string type names to Field constructors.
+     * @param {FieldSerializer} fieldSerializer - A serializer of field instances.
      */
-    constructor(fieldRegistry: FieldRegistry, policySerializer: PolicySerializer);
+    constructor(fieldsFactory: FieldsFactory<TFields>, fieldSerializer: FieldSerializer);
     /**
      * Creates a serializable snapshot of a `Fields` container.
      *
@@ -735,12 +785,11 @@ declare class FieldsSerializer {
     /**
      * 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.
+     * @returns {Fields} A new `DefaultFields` instance populated with the restored fields.
      */
-    hydrate(snapshot: FieldsSnapshot): DefaultFields;
+    hydrate(snapshot: FieldsSnapshot): TFields;
 }
 
 /**
@@ -772,21 +821,21 @@ interface FieldTreeSnapshot {
  *       updates. This method should traverse the existing tree and the snapshot,
  *       patching nodes in place to maintain object references.
  */
-declare class FieldTreeSerializer {
+declare class FieldTreeSerializer<TFields extends Fields> {
     private readonly fieldTreeNodeFactory;
     private readonly fieldsSerializer;
-    constructor(fieldTreeNodeFactory: TreeNodeFactory, fieldsSerializer: FieldsSerializer);
+    constructor(fieldTreeNodeFactory: TreeNodeFactory<TFields>, fieldsSerializer: FieldsSerializer<TFields>);
     /**
      * 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(tree: FieldTree): FieldTreeSnapshot;
+    snapshot(tree: FieldTree<TFields>): FieldTreeSnapshot;
     /**
      * Restores the state of the tree from a snapshot.
      * It intelligently creates missing nodes based on `__type` metadata and delegates hydration to child nodes.
      * @param snapshot The snapshot object to load.
      */
-    hydrate(snapshot: FieldTreeSnapshot): FieldTree;
+    hydrate(snapshot: FieldTreeSnapshot): FieldTree<TFields>;
 }
 
-export { type BooleanField, ClampMaxPolicy, ClampMaxPolicySerializerHandler, ClampMinPolicy, ClampMinPolicySerializerHandler, ClampPolicy, ClampPolicySerializerHandler, DefaultBooleanField, type DefaultBooleanFieldOptions, DefaultField, DefaultFields, DefaultNumericField, type DefaultNumericFieldOptions, DefaultStringField, type DefaultStringFieldOptions, DefaultTreeNodeFactory, type Field, type FieldOptions, FieldRegistry, FieldSerializer, type FieldSnapshot, FieldTree, FieldTreeSerializer, type FieldTreeSnapshot, Fields, FieldsSerializer, type FieldsSnapshot, type NumericField, Policies, type Policy, PolicySerializer, type PolicySerializerHandler, type StringField, type TreeNodeFactory, type TreeOrFieldsNode, clampMaxPolicy, clampMinPolicy, clampPolicy };
+export { type BooleanField, ClampMaxPolicy, ClampMaxPolicySerializerHandler, ClampMinPolicy, ClampMinPolicySerializerHandler, ClampPolicy, ClampPolicySerializerHandler, DefaultBooleanField, type DefaultBooleanFieldOptions, DefaultField, DefaultFields, DefaultFieldsFactory, DefaultNumericField, type DefaultNumericFieldOptions, DefaultStringField, type DefaultStringFieldOptions, DefaultTreeNodeFactory, type Field, type FieldOptions, FieldRegistry, FieldSerializer, type FieldSnapshot, FieldTree, FieldTreeSerializer, type FieldTreeSnapshot, Fields, type FieldsFactory, FieldsSerializer, type FieldsSnapshot, type NumericField, Policies, type Policy, PolicySerializer, type PolicySerializerHandler, type StringField, type TreeNode, type TreeNodeFactory, clampMaxPolicy, clampMinPolicy, clampPolicy };

package/dist/index.d.ts

@@ -330,6 +330,7 @@ declare class Fields {
      * Removes all fields from the collection, ensuring each is properly destroyed.
      */
     clear(): void;
+    destroy(): void;
 }
 
 declare const DefaultFields_base: {
@@ -355,6 +356,7 @@ declare const DefaultFields_base: {
         get<T extends Field<any>>(name: string): T;
         remove(names: string | string[]): void;
         clear(): void;
+        destroy(): void;
     };
 } & {
     new (...args: any[]): {
@@ -379,6 +381,7 @@ declare const DefaultFields_base: {
         get<T extends Field<any>>(name: string): T;
         remove(names: string | string[]): void;
         clear(): void;
+        destroy(): void;
     };
 } & {
     new (...args: any[]): {
@@ -403,6 +406,7 @@ declare const DefaultFields_base: {
         get<T extends Field<any>>(name: string): T;
         remove(names: string | string[]): void;
         clear(): void;
+        destroy(): void;
     };
 } & {
     new (...args: any[]): {
@@ -426,31 +430,38 @@ declare const DefaultFields_base: {
         get<T extends Field<any>>(name: string): T;
         remove(names: string | string[]): void;
         clear(): void;
+        destroy(): void;
     };
 } & typeof Fields;
 declare class DefaultFields extends DefaultFields_base {
 }
 
+interface FieldsFactory<TFields extends Fields> {
+    fields(): TFields;
+}
+declare class DefaultFieldsFactory implements FieldsFactory<DefaultFields> {
+    private readonly fieldRegistry;
+    constructor(fieldRegistry: FieldRegistry);
+    fields(): DefaultFields;
+}
 /**
  * Defines the contract for a factory that creates nodes for a FieldTree.
  * This allows for custom implementations of Fields and FieldTree to be used.
  */
-interface TreeNodeFactory {
-    fields<T extends Fields>(): T;
-    tree<T extends FieldTree>(): T;
+interface TreeNodeFactory<TFields extends Fields> extends FieldsFactory<TFields> {
+    fields(): TFields;
+    tree(): FieldTree<TFields>;
 }
 /**
  * The default factory implementation that creates standard DefaultFields and FieldTree instances.
  */
-declare class DefaultTreeNodeFactory implements TreeNodeFactory {
-    private readonly fieldRegistry;
+declare class DefaultTreeNodeFactory extends DefaultFieldsFactory implements TreeNodeFactory<DefaultFields> {
     constructor(fieldRegistry: FieldRegistry);
-    fields: () => any;
-    tree: () => any;
+    tree(): FieldTree<DefaultFields>;
 }
 
 /** A type alias for any container that can be a child node in a FieldTree */
-type TreeOrFieldsNode = FieldTree | Fields;
+type TreeNode<F extends Fields> = FieldTree<F> | F;
 /**
  * Represents a hierarchical data structure for managing the global state of the system.
  *
@@ -459,26 +470,51 @@ type TreeOrFieldsNode = FieldTree | Fields;
  * and overall game progress. It uses a path-based system for accessing and
  * manipulating nested data, similar to a file system.
  *
- * @todo
- * - Add node removal functionality.
- * - Implement an event system for node creation/removal.
  */
-declare class FieldTree {
+declare class FieldTree<TFields extends Fields> {
     static readonly typeName = "fieldTree";
     readonly typeName = "fieldTree";
     /** @private The internal map storing child nodes (branches or leaves). */
     private readonly _nodes;
     /** @private The factory used to create new child nodes. */
     private readonly _factory;
+    /**
+     * An event emitter that fires immediately after a new node is added to this tree branch.
+     * @event
+     * @param {object} event - The event payload.
+     * @param {string} event.name - The name (key) of the added node.
+     * @param event.node - The node instance that was added.
+     * @example
+     * myTree.onAdd.subscribe(({ name, node }) => {
+     *   console.log(`Node '${name}' was added.`, node);
+     * });
+     */
+    onAdd: Emitter<[event: {
+        name: string;
+        node: TreeNode<TFields>;
+    }]>;
+    /**
+     * An event emitter that fires once after one or more nodes have been successfully removed.
+     * @event
+     * @param {object} event - The event payload.
+     * @param {string[]} event.names - An array of names of the nodes that were removed.
+     * @example
+     * myTree.onRemove.subscribe(({ names }) => {
+     *   console.log(`Nodes removed: ${names.join(', ')}`);
+     * });
+     */
+    onRemove: Emitter<[event: {
+        names: string[];
+    }]>;
     /**
      * Gets the collection of direct child nodes of this tree branch.
      */
-    get nodes(): Map<string, TreeOrFieldsNode>;
+    get nodes(): Map<string, TreeNode<TFields>>;
     /**
      * Creates an instance of FieldTree.
      * @param {TreeNodeFactory} factory - A factory responsible for creating new nodes within the tree.
      */
-    constructor(factory: TreeNodeFactory);
+    constructor(factory: TreeNodeFactory<TFields>);
     /**
      * Checks if a direct child node with the given name exists.
      * @param {string} name - The name of the direct child node.
@@ -494,18 +530,29 @@ declare class 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.
+     * @param {TreeNode} node - The node instance to add.
+     * @returns {TreeNode} The added node.
      * @throws If a node with the same name already exists.
      */
-    addNode(name: string, node: TreeOrFieldsNode): TreeOrFieldsNode;
+    addNode(name: string, node: TreeNode<TFields>): TreeNode<TFields>;
     /**
      * Retrieves a direct child node by its name.
      * @param {string} name - The name of the child node.
-     * @returns {TreeOrFieldsNode} The retrieved node.
+     * @returns {TreeNode} The retrieved node.
      * @throws If a node with the given name cannot be found.
      */
-    getNode(name: string): TreeOrFieldsNode;
+    getNode(name: string): TreeNode<TFields>;
+    /**
+     * Removes one or more nodes from this tree branch.
+     *
+     * This method first validates that all specified nodes exist. If validation passes,
+     * it recursively calls `destroy()` on each node to ensure proper cleanup of the entire subtree.
+     * Finally, it emits a single `onRemove` event with the names of all successfully removed nodes.
+     *
+     * @param {string | string[]} names - A single name or an array of names of the nodes to remove.
+     * @throws If any of the specified names do not correspond to an existing node.
+     */
+    removeNode(names: string | string[]): void;
     /**
      * Creates a new `FieldTree` (branch) node at the specified path.
      * @param {PathType} path - The path where the new `FieldTree` should be created.
@@ -513,7 +560,7 @@ declare class FieldTree {
      * @returns {FieldTree} The newly created `FieldTree` instance.
      * @throws If the path is invalid or a node already exists at the target location.
      */
-    createFieldTree<T extends FieldTree>(path: PathType, createPath?: boolean): T;
+    createFieldTree<T extends FieldTree<TFields>>(path: PathType, createPath?: boolean): T;
     /**
      * Creates a new `Fields` (leaf) container at the specified path.
      * @param {PathType} path - The path where the new `Fields` container should be created.
@@ -521,33 +568,47 @@ declare class FieldTree {
      * @returns {Fields} The newly created `Fields` instance.
      * @throws If the path is invalid or a node already exists at the target location.
      */
-    createFields<T extends Fields>(path: PathType, createPath?: boolean): T;
+    createFields(path: PathType, createPath?: boolean): TFields;
     /**
      * 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: PathType): FieldTree;
+    getFieldTree(path: PathType): FieldTree<TFields>;
     /**
      * 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.
      */
-    getFields(path: PathType): Fields;
+    getFields(path: PathType): TFields;
     /**
      * 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.
      */
-    getOrCreateFieldTree(path: PathType): FieldTree;
+    getOrCreateFieldTree(path: PathType): FieldTree<TFields>;
     /**
      * 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.
      */
     getOrCreateFields(path: PathType): Fields;
+    /**
+     * Removes all child nodes from this tree branch.
+     * This method ensures that `destroy()` is called on each child node, allowing for
+     * a full, recursive cleanup of the entire subtree.
+     */
+    clear(): void;
+    /**
+     * Performs a complete cleanup of this node and its entire subtree.
+     *
+     * It recursively destroys all child nodes by calling `clear()` and then
+     * unsubscribes all listeners from its own event emitters.
+     * This method should be called when a node is no longer needed.
+     */
+    destroy(): void;
     /**
      * @private
      * Navigates the tree to the parent of a target node.
@@ -699,30 +760,19 @@ interface FieldsSnapshot {
  * into a storable snapshot and back.
  * It delegates the actual serialization of each `Field` and `Policy` to their respective serializers.
  *
- * @todo This implementation is coupled to creating `DefaultFields` instances during hydration.
- *       To make the system fully extensible, this class should be refactored to use a
- *       `FieldsRegistry` (a `ConstructorRegistry<Fields>`). This would allow it to
- *       hydrate any custom `Fields` class (e.g., `ReactiveFields`) based on the `__type`
- *       property in the snapshot, mirroring the pattern used by `FieldSerializer`.
- *
  * @todo Implement a `patch(fields, snapshot)` method. It should perform a non-destructive
  *       update, creating new fields, removing missing ones, and patching existing ones
  *       in place, preserving the container instance itself.
  */
-declare class FieldsSerializer {
-    private readonly fieldRegistry;
-    private readonly policySerializer;
-    /**
-     * An internal instance of FieldSerializer to handle individual fields.
-     * @private
-     */
+declare class FieldsSerializer<TFields extends Fields> {
+    private readonly fieldsFactory;
     private readonly fieldSerializer;
     /**
      * 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.
+     * @param {FieldsFactory} fieldsFactory - A registry that maps string type names to Field constructors.
+     * @param {FieldSerializer} fieldSerializer - A serializer of field instances.
      */
-    constructor(fieldRegistry: FieldRegistry, policySerializer: PolicySerializer);
+    constructor(fieldsFactory: FieldsFactory<TFields>, fieldSerializer: FieldSerializer);
     /**
      * Creates a serializable snapshot of a `Fields` container.
      *
@@ -735,12 +785,11 @@ declare class FieldsSerializer {
     /**
      * 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.
+     * @returns {Fields} A new `DefaultFields` instance populated with the restored fields.
      */
-    hydrate(snapshot: FieldsSnapshot): DefaultFields;
+    hydrate(snapshot: FieldsSnapshot): TFields;
 }
 
 /**
@@ -772,21 +821,21 @@ interface FieldTreeSnapshot {
  *       updates. This method should traverse the existing tree and the snapshot,
  *       patching nodes in place to maintain object references.
  */
-declare class FieldTreeSerializer {
+declare class FieldTreeSerializer<TFields extends Fields> {
     private readonly fieldTreeNodeFactory;
     private readonly fieldsSerializer;
-    constructor(fieldTreeNodeFactory: TreeNodeFactory, fieldsSerializer: FieldsSerializer);
+    constructor(fieldTreeNodeFactory: TreeNodeFactory<TFields>, fieldsSerializer: FieldsSerializer<TFields>);
     /**
      * 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(tree: FieldTree): FieldTreeSnapshot;
+    snapshot(tree: FieldTree<TFields>): FieldTreeSnapshot;
     /**
      * Restores the state of the tree from a snapshot.
      * It intelligently creates missing nodes based on `__type` metadata and delegates hydration to child nodes.
      * @param snapshot The snapshot object to load.
      */
-    hydrate(snapshot: FieldTreeSnapshot): FieldTree;
+    hydrate(snapshot: FieldTreeSnapshot): FieldTree<TFields>;
 }
 
-export { type BooleanField, ClampMaxPolicy, ClampMaxPolicySerializerHandler, ClampMinPolicy, ClampMinPolicySerializerHandler, ClampPolicy, ClampPolicySerializerHandler, DefaultBooleanField, type DefaultBooleanFieldOptions, DefaultField, DefaultFields, DefaultNumericField, type DefaultNumericFieldOptions, DefaultStringField, type DefaultStringFieldOptions, DefaultTreeNodeFactory, type Field, type FieldOptions, FieldRegistry, FieldSerializer, type FieldSnapshot, FieldTree, FieldTreeSerializer, type FieldTreeSnapshot, Fields, FieldsSerializer, type FieldsSnapshot, type NumericField, Policies, type Policy, PolicySerializer, type PolicySerializerHandler, type StringField, type TreeNodeFactory, type TreeOrFieldsNode, clampMaxPolicy, clampMinPolicy, clampPolicy };
+export { type BooleanField, ClampMaxPolicy, ClampMaxPolicySerializerHandler, ClampMinPolicy, ClampMinPolicySerializerHandler, ClampPolicy, ClampPolicySerializerHandler, DefaultBooleanField, type DefaultBooleanFieldOptions, DefaultField, DefaultFields, DefaultFieldsFactory, DefaultNumericField, type DefaultNumericFieldOptions, DefaultStringField, type DefaultStringFieldOptions, DefaultTreeNodeFactory, type Field, type FieldOptions, FieldRegistry, FieldSerializer, type FieldSnapshot, FieldTree, FieldTreeSerializer, type FieldTreeSnapshot, Fields, type FieldsFactory, FieldsSerializer, type FieldsSnapshot, type NumericField, Policies, type Policy, PolicySerializer, type PolicySerializerHandler, type StringField, type TreeNode, type TreeNodeFactory, clampMaxPolicy, clampMinPolicy, clampPolicy };

package/dist/index.js

@@ -29,6 +29,7 @@ __export(index_exports, {
   DefaultBooleanField: () => DefaultBooleanField,
   DefaultField: () => DefaultField,
   DefaultFields: () => DefaultFields,
+  DefaultFieldsFactory: () => DefaultFieldsFactory,
   DefaultNumericField: () => DefaultNumericField,
   DefaultStringField: () => DefaultStringField,
   DefaultTreeNodeFactory: () => DefaultTreeNodeFactory,
@@ -491,6 +492,11 @@ var Fields = class _Fields {
   clear() {
     this.remove(Array.from(this._fields.keys()));
   }
+  destroy() {
+    this.clear();
+    this.onAdd.clear();
+    this.onRemove.clear();
+  }
 };
 
 // src/mixins/with-boolean-fields.mixin.ts
@@ -563,6 +569,29 @@ var FieldTree = class _FieldTree {
   _nodes = /* @__PURE__ */ new Map();
   /** @private The factory used to create new child nodes. */
   _factory;
+  /**
+   * An event emitter that fires immediately after a new node is added to this tree branch.
+   * @event
+   * @param {object} event - The event payload.
+   * @param {string} event.name - The name (key) of the added node.
+   * @param event.node - The node instance that was added.
+   * @example
+   * myTree.onAdd.subscribe(({ name, node }) => {
+   *   console.log(`Node '${name}' was added.`, node);
+   * });
+   */
+  onAdd = new import_utils5.Emitter();
+  /**
+   * An event emitter that fires once after one or more nodes have been successfully removed.
+   * @event
+   * @param {object} event - The event payload.
+   * @param {string[]} event.names - An array of names of the nodes that were removed.
+   * @example
+   * myTree.onRemove.subscribe(({ names }) => {
+   *   console.log(`Nodes removed: ${names.join(', ')}`);
+   * });
+   */
+  onRemove = new import_utils5.Emitter();
   /**
    * Gets the collection of direct child nodes of this tree branch.
    */
@@ -596,19 +625,20 @@ var FieldTree = class _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.
+   * @param {TreeNode} node - The node instance to add.
+   * @returns {TreeNode} The added node.
    * @throws If a node with the same name already exists.
    */
   addNode(name, node) {
     (0, import_utils5.throwIf)(this.has(name), `Can't add node with name: '${name}', node already exists`);
     this._nodes.set(name, node);
+    this.onAdd.emit({ name, node });
     return node;
   }
   /**
    * Retrieves a direct child node by its name.
    * @param {string} name - The name of the child node.
-   * @returns {TreeOrFieldsNode} The retrieved node.
+   * @returns {TreeNode} The retrieved node.
    * @throws If a node with the given name cannot be found.
    */
   getNode(name) {
@@ -616,6 +646,29 @@ var FieldTree = class _FieldTree {
     (0, import_utils5.throwIfEmpty)(node, `Can't find node with name '${name}'`);
     return node;
   }
+  /**
+   * Removes one or more nodes from this tree branch.
+   *
+   * This method first validates that all specified nodes exist. If validation passes,
+   * it recursively calls `destroy()` on each node to ensure proper cleanup of the entire subtree.
+   * Finally, it emits a single `onRemove` event with the names of all successfully removed nodes.
+   *
+   * @param {string | string[]} names - A single name or an array of names of the nodes to remove.
+   * @throws If any of the specified names do not correspond to an existing node.
+   */
+  removeNode(names) {
+    const toRemoveNames = Array.isArray(names) ? names : [names];
+    toRemoveNames.forEach((name) => {
+      (0, import_utils5.throwIf)(!this.has(name), `Can't remove node with name: '${name}', node doesn't exists`);
+    });
+    toRemoveNames.forEach((name) => {
+      this._nodes.get(name).destroy();
+      this._nodes.delete(name);
+    });
+    if (toRemoveNames.length) {
+      this.onRemove.emit({ names: toRemoveNames });
+    }
+  }
   /**
    * Creates a new `FieldTree` (branch) node at the specified path.
    * @param {PathType} path - The path where the new `FieldTree` should be created.
@@ -686,6 +739,26 @@ var FieldTree = class _FieldTree {
     const traversedPath = this.traversePath(path, true);
     return traversedPath.branch.has(traversedPath.leafName) ? traversedPath.branch.getFields(traversedPath.leafName) : traversedPath.branch.createFields(traversedPath.leafName);
   }
+  /**
+   * Removes all child nodes from this tree branch.
+   * This method ensures that `destroy()` is called on each child node, allowing for
+   * a full, recursive cleanup of the entire subtree.
+   */
+  clear() {
+    this.removeNode(Array.from(this._nodes.keys()));
+  }
+  /**
+   * Performs a complete cleanup of this node and its entire subtree.
+   *
+   * It recursively destroys all child nodes by calling `clear()` and then
+   * unsubscribes all listeners from its own event emitters.
+   * This method should be called when a node is no longer needed.
+   */
+  destroy() {
+    this.clear();
+    this.onAdd.clear();
+    this.onRemove.clear();
+  }
   /**
    * @private
    * Navigates the tree to the parent of a target node.
@@ -718,12 +791,21 @@ var FieldTree = class _FieldTree {
 };
 
 // src/field-tree-node-factory.ts
-var DefaultTreeNodeFactory = class {
+var DefaultFieldsFactory = class {
   constructor(fieldRegistry) {
     this.fieldRegistry = fieldRegistry;
   }
-  fields = () => new DefaultFields(this.fieldRegistry);
-  tree = () => new FieldTree(this);
+  fields() {
+    return new DefaultFields(this.fieldRegistry);
+  }
+};
+var DefaultTreeNodeFactory = class extends DefaultFieldsFactory {
+  constructor(fieldRegistry) {
+    super(fieldRegistry);
+  }
+  tree() {
+    return new FieldTree(this);
+  }
 };
 
 // src/serializer/policies/clamp-policy-serializer-handler.ts
@@ -856,19 +938,13 @@ var FieldSerializer = class {
 var FieldsSerializer = class {
   /**
    * 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.
+   * @param {FieldsFactory} fieldsFactory - A registry that maps string type names to Field constructors.
+   * @param {FieldSerializer} fieldSerializer - A serializer of field instances.
    */
-  constructor(fieldRegistry, policySerializer) {
-    this.fieldRegistry = fieldRegistry;
-    this.policySerializer = policySerializer;
-    this.fieldSerializer = new FieldSerializer(this.fieldRegistry, this.policySerializer);
+  constructor(fieldsFactory, fieldSerializer) {
+    this.fieldsFactory = fieldsFactory;
+    this.fieldSerializer = fieldSerializer;
   }
-  /**
-   * An internal instance of FieldSerializer to handle individual fields.
-   * @private
-   */
-  fieldSerializer;
   /**
    * Creates a serializable snapshot of a `Fields` container.
    *
@@ -887,14 +963,13 @@ var FieldsSerializer = class {
   /**
    * 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.
+   * @returns {Fields} A new `DefaultFields` instance populated with the restored fields.
    */
   hydrate(snapshot) {
     const { __type, ...fieldsData } = snapshot;
-    const fields = new DefaultFields(this.fieldRegistry);
+    const fields = this.fieldsFactory.fields();
     for (const fieldName in fieldsData) {
       const fieldSnapshot = fieldsData[fieldName];
       const restoredField = this.fieldSerializer.hydrate(fieldSnapshot);
@@ -943,7 +1018,7 @@ var FieldTreeSerializer = class {
       }
       if (nodeData.__type === FieldTree.typeName) {
         tree.addNode(key, this.hydrate(nodeData));
-      } else {
+      } else if (nodeData.__type === Fields.typeName) {
         tree.addNode(key, this.fieldsSerializer.hydrate(nodeData));
       }
     }
@@ -961,6 +1036,7 @@ var FieldTreeSerializer = class {
   DefaultBooleanField,
   DefaultField,
   DefaultFields,
+  DefaultFieldsFactory,
   DefaultNumericField,
   DefaultStringField,
   DefaultTreeNodeFactory,

package/dist/index.mjs

@@ -443,6 +443,11 @@ var Fields = class _Fields {
   clear() {
     this.remove(Array.from(this._fields.keys()));
   }
+  destroy() {
+    this.clear();
+    this.onAdd.clear();
+    this.onRemove.clear();
+  }
 };
 
 // src/mixins/with-boolean-fields.mixin.ts
@@ -507,7 +512,7 @@ var DefaultFields = class extends WithBooleanFields(WithStringFields(WithNumeric
 };
 
 // src/field-tree.ts
-import { ensurePathArray, ensurePathString, throwIf as throwIf3, throwIfEmpty as throwIfEmpty2 } from "@axi-engine/utils";
+import { Emitter as Emitter3, ensurePathArray, ensurePathString, throwIf as throwIf3, throwIfEmpty as throwIfEmpty2 } from "@axi-engine/utils";
 var FieldTree = class _FieldTree {
   static typeName = "fieldTree";
   typeName = _FieldTree.typeName;
@@ -515,6 +520,29 @@ var FieldTree = class _FieldTree {
   _nodes = /* @__PURE__ */ new Map();
   /** @private The factory used to create new child nodes. */
   _factory;
+  /**
+   * An event emitter that fires immediately after a new node is added to this tree branch.
+   * @event
+   * @param {object} event - The event payload.
+   * @param {string} event.name - The name (key) of the added node.
+   * @param event.node - The node instance that was added.
+   * @example
+   * myTree.onAdd.subscribe(({ name, node }) => {
+   *   console.log(`Node '${name}' was added.`, node);
+   * });
+   */
+  onAdd = new Emitter3();
+  /**
+   * An event emitter that fires once after one or more nodes have been successfully removed.
+   * @event
+   * @param {object} event - The event payload.
+   * @param {string[]} event.names - An array of names of the nodes that were removed.
+   * @example
+   * myTree.onRemove.subscribe(({ names }) => {
+   *   console.log(`Nodes removed: ${names.join(', ')}`);
+   * });
+   */
+  onRemove = new Emitter3();
   /**
    * Gets the collection of direct child nodes of this tree branch.
    */
@@ -548,19 +576,20 @@ var FieldTree = class _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.
+   * @param {TreeNode} node - The node instance to add.
+   * @returns {TreeNode} The added node.
    * @throws If a node with the same name already exists.
    */
   addNode(name, node) {
     throwIf3(this.has(name), `Can't add node with name: '${name}', node already exists`);
     this._nodes.set(name, node);
+    this.onAdd.emit({ name, node });
     return node;
   }
   /**
    * Retrieves a direct child node by its name.
    * @param {string} name - The name of the child node.
-   * @returns {TreeOrFieldsNode} The retrieved node.
+   * @returns {TreeNode} The retrieved node.
    * @throws If a node with the given name cannot be found.
    */
   getNode(name) {
@@ -568,6 +597,29 @@ var FieldTree = class _FieldTree {
     throwIfEmpty2(node, `Can't find node with name '${name}'`);
     return node;
   }
+  /**
+   * Removes one or more nodes from this tree branch.
+   *
+   * This method first validates that all specified nodes exist. If validation passes,
+   * it recursively calls `destroy()` on each node to ensure proper cleanup of the entire subtree.
+   * Finally, it emits a single `onRemove` event with the names of all successfully removed nodes.
+   *
+   * @param {string | string[]} names - A single name or an array of names of the nodes to remove.
+   * @throws If any of the specified names do not correspond to an existing node.
+   */
+  removeNode(names) {
+    const toRemoveNames = Array.isArray(names) ? names : [names];
+    toRemoveNames.forEach((name) => {
+      throwIf3(!this.has(name), `Can't remove node with name: '${name}', node doesn't exists`);
+    });
+    toRemoveNames.forEach((name) => {
+      this._nodes.get(name).destroy();
+      this._nodes.delete(name);
+    });
+    if (toRemoveNames.length) {
+      this.onRemove.emit({ names: toRemoveNames });
+    }
+  }
   /**
    * Creates a new `FieldTree` (branch) node at the specified path.
    * @param {PathType} path - The path where the new `FieldTree` should be created.
@@ -638,6 +690,26 @@ var FieldTree = class _FieldTree {
     const traversedPath = this.traversePath(path, true);
     return traversedPath.branch.has(traversedPath.leafName) ? traversedPath.branch.getFields(traversedPath.leafName) : traversedPath.branch.createFields(traversedPath.leafName);
   }
+  /**
+   * Removes all child nodes from this tree branch.
+   * This method ensures that `destroy()` is called on each child node, allowing for
+   * a full, recursive cleanup of the entire subtree.
+   */
+  clear() {
+    this.removeNode(Array.from(this._nodes.keys()));
+  }
+  /**
+   * Performs a complete cleanup of this node and its entire subtree.
+   *
+   * It recursively destroys all child nodes by calling `clear()` and then
+   * unsubscribes all listeners from its own event emitters.
+   * This method should be called when a node is no longer needed.
+   */
+  destroy() {
+    this.clear();
+    this.onAdd.clear();
+    this.onRemove.clear();
+  }
   /**
    * @private
    * Navigates the tree to the parent of a target node.
@@ -670,12 +742,21 @@ var FieldTree = class _FieldTree {
 };
 
 // src/field-tree-node-factory.ts
-var DefaultTreeNodeFactory = class {
+var DefaultFieldsFactory = class {
   constructor(fieldRegistry) {
     this.fieldRegistry = fieldRegistry;
   }
-  fields = () => new DefaultFields(this.fieldRegistry);
-  tree = () => new FieldTree(this);
+  fields() {
+    return new DefaultFields(this.fieldRegistry);
+  }
+};
+var DefaultTreeNodeFactory = class extends DefaultFieldsFactory {
+  constructor(fieldRegistry) {
+    super(fieldRegistry);
+  }
+  tree() {
+    return new FieldTree(this);
+  }
 };
 
 // src/serializer/policies/clamp-policy-serializer-handler.ts
@@ -808,19 +889,13 @@ var FieldSerializer = class {
 var FieldsSerializer = class {
   /**
    * 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.
+   * @param {FieldsFactory} fieldsFactory - A registry that maps string type names to Field constructors.
+   * @param {FieldSerializer} fieldSerializer - A serializer of field instances.
    */
-  constructor(fieldRegistry, policySerializer) {
-    this.fieldRegistry = fieldRegistry;
-    this.policySerializer = policySerializer;
-    this.fieldSerializer = new FieldSerializer(this.fieldRegistry, this.policySerializer);
+  constructor(fieldsFactory, fieldSerializer) {
+    this.fieldsFactory = fieldsFactory;
+    this.fieldSerializer = fieldSerializer;
   }
-  /**
-   * An internal instance of FieldSerializer to handle individual fields.
-   * @private
-   */
-  fieldSerializer;
   /**
    * Creates a serializable snapshot of a `Fields` container.
    *
@@ -839,14 +914,13 @@ var FieldsSerializer = class {
   /**
    * 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.
+   * @returns {Fields} A new `DefaultFields` instance populated with the restored fields.
    */
   hydrate(snapshot) {
     const { __type, ...fieldsData } = snapshot;
-    const fields = new DefaultFields(this.fieldRegistry);
+    const fields = this.fieldsFactory.fields();
     for (const fieldName in fieldsData) {
       const fieldSnapshot = fieldsData[fieldName];
       const restoredField = this.fieldSerializer.hydrate(fieldSnapshot);
@@ -895,7 +969,7 @@ var FieldTreeSerializer = class {
       }
       if (nodeData.__type === FieldTree.typeName) {
         tree.addNode(key, this.hydrate(nodeData));
-      } else {
+      } else if (nodeData.__type === Fields.typeName) {
         tree.addNode(key, this.fieldsSerializer.hydrate(nodeData));
       }
     }
@@ -912,6 +986,7 @@ export {
   DefaultBooleanField,
   DefaultField,
   DefaultFields,
+  DefaultFieldsFactory,
   DefaultNumericField,
   DefaultStringField,
   DefaultTreeNodeFactory,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axi-engine/fields",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "",
   "license": "MIT",
   "keywords": [