@axi-engine/fields 0.3.10 → 0.3.11

package/dist/index.d.mts

@@ -789,7 +789,7 @@ interface FieldSnapshot {
  * to resolve class constructors and a `PolicySerializer` to handle the state
  * of any attached policies.
  */
-declare class FieldSerializer {
+declare class FieldHydrator {
     private readonly fieldRegistry;
     private readonly policySerializer;
     /**
@@ -798,13 +798,6 @@ declare class FieldSerializer {
      * @param {PolicySerializer} policySerializer - A serializer dedicated to handling Policy instances.
      */
     constructor(fieldRegistry: FieldRegistry, policySerializer: PolicySerializer);
-    /**
-     * 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.
-     */
-    snapshot(field: Field<any>): FieldSnapshot;
     /**
      * Restores a Field instance from its snapshot representation.
      * It uses the `__type` property to find the correct constructor and hydrates
@@ -828,6 +821,18 @@ declare class FieldSerializer {
     private hydratePolicies;
 }
 
+declare class FieldSnapshotter {
+    readonly policySerializer: PolicySerializer;
+    constructor(policySerializer: PolicySerializer);
+    /**
+     * 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.
+     */
+    snapshot(field: Field<any>): FieldSnapshot;
+}
+
 /**
  * A plain object representation of a Fields container's state for serialization.
  */
@@ -837,25 +842,53 @@ interface FieldsSnapshot {
 }
 
 /**
- * Orchestrates the serialization and deserialization of `Fields` container instances.
- *
- * This class acts as a high-level composer, responsible for converting an entire `Fields` object
- * into a storable snapshot and back.
- * It delegates the actual serialization of each `Field` and `Policy` to their respective serializers.
- *
- * @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.
+ * Deserialization of `Fields` container instances.
+ * Responsible for converting snapshot of `Fields` object into a `Fields` instance.
  */
-declare class FieldsSerializer<TFields extends Fields> {
+declare class FieldsHydrator<TFields extends Fields> {
     private readonly fieldsFactory;
-    private readonly fieldSerializer;
+    private readonly fieldHydrator;
     /**
      * Creates an instance of FieldsSerializer.
      * @param {FieldsFactory} fieldsFactory - A registry that maps string type names to Field constructors.
-     * @param {FieldSerializer} fieldSerializer - A serializer of field instances.
+     * @param {FieldHydrator} fieldHydrator - A hydrator of field instances.
+     */
+    constructor(fieldsFactory: FieldsFactory<TFields>, fieldHydrator: FieldHydrator);
+    /**
+     * Restores a `Fields` container instance from its snapshot representation.
+     *
+     * 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 {Fields} A new `DefaultFields` instance populated with the restored fields.
+     */
+    hydrate(snapshot: FieldsSnapshot): TFields;
+    /**
+     * Synchronizes an existing `Fields` container with a snapshot.
+     *
+     * This method performs a "smart update":
+     * 1. **Removes** fields from the container that are missing in the snapshot.
+     * 2. **Patches** existing fields in-place using {@link FieldHydrator.patch}, preserving object references.
+     * 3. **Creates** (hydrates) and adds new fields that exist in the snapshot but not in the container.
+     *
+     * @param {Fields} fields - The target `Fields` container to update.
+     * @param {FieldsSnapshot} snapshot - The source snapshot containing the desired state.
      */
-    constructor(fieldsFactory: FieldsFactory<TFields>, fieldSerializer: FieldSerializer);
+    patch(fields: TFields, snapshot: FieldsSnapshot): void;
+}
+
+/**
+ * The serialization of `Fields` container instances.
+ *
+ * This class responsible for converting an entire `Fields` object
+ * into a storable snapshot.
+ */
+declare class FieldsSnapshotter {
+    private readonly fieldSnapshotter;
+    /**
+     * Creates an instance of FieldsSnapshotter.
+     * @param {FieldSnapshotter} fieldSnapshotter - A serializer of field instances.
+     */
+    constructor(fieldSnapshotter: FieldSnapshotter);
     /**
      * Creates a serializable snapshot of a `Fields` container.
      *
@@ -865,14 +898,6 @@ declare class FieldsSerializer<TFields extends Fields> {
      * @returns {FieldsSnapshot} A plain object ready for JSON serialization.
      */
     snapshot(fields: Fields): FieldsSnapshot;
-    /**
-     * Restores a `Fields` container instance from its snapshot representation.
-     *
-     * 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 {Fields} A new `DefaultFields` instance populated with the restored fields.
-     */
-    hydrate(snapshot: FieldsSnapshot): TFields;
 }
 
 /**
@@ -890,38 +915,66 @@ interface FieldTreeSnapshot {
 }
 
 /**
- * Orchestrates the recursive serialization and deserialization of `FieldTree` instances.
+ * Orchestrates the recursive deserialization of `FieldTree` instances.
  *
  * This class handles the conversion of an entire `FieldTree` object graph into a
  * plain, storable snapshot and vice-versa. It delegates the processing of `Fields`
- * leaf nodes to a dedicated `FieldsSerializer`.
+ * leaf nodes to a dedicated `FieldsHydrator`.
  * @todo Refactoring: The current implementation uses `if/else` logic in `snapshot` and `hydrate`
  *       to process different node types. A more extensible approach would be to use a
  *       registry of dedicated handlers for each node type.
  *       This would allow new node types to be supported without
  *       modifying this class, adhering to the Open/Closed Principle.
- *
- * @todo Implement a `patch(tree, snapshot)` method for recursive, non-destructive
- *       updates. This method should traverse the existing tree and the snapshot,
- *       patching nodes in place to maintain object references.
  */
-declare class FieldTreeSerializer<TFields extends Fields> {
+declare class FieldTreeHydrator<TFields extends Fields> {
     _factory: FieldTreeFactory<TFields>;
-    _fieldsSerializer: FieldsSerializer<TFields>;
+    _fieldsHydrator: FieldsHydrator<TFields>;
     get factory(): FieldTreeFactory<TFields>;
-    get fieldsSerializer(): FieldsSerializer<TFields>;
-    constructor(fieldTreeNodeFactory: FieldTreeFactory<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<TFields>): FieldTreeSnapshot;
+    get fieldsHydrator(): FieldsHydrator<TFields>;
+    constructor(fieldTreeNodeFactory: FieldTreeFactory<TFields>, fieldsHydrator: FieldsHydrator<TFields>);
     /**
      * 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<TFields>;
+    /**
+     * Synchronizes an existing `FieldTree` branch with a snapshot.
+     *
+     * This method performs a recursive update to match the tree state with the provided snapshot:
+     * 1. **Removes** child nodes that are present in the tree but missing in the snapshot.
+     * 2. **Creates** new nodes that are present in the snapshot but missing in the tree.
+     * 3. **Replaces** nodes if their type has changed (e.g., replacing a `Fields` leaf with a `FieldTree` branch).
+     * 4. **Patches** existing matching nodes in-place (recursively).
+     *
+     * @param {FieldTree} tree - The target tree instance to update.
+     * @param {FieldTreeSnapshot} snapshot - The source snapshot containing the desired state.
+     */
+    patch(tree: FieldTree<TFields>, snapshot: FieldTreeSnapshot): void;
+    /**
+     * Helper method to instantiate and add a new node to the tree based on the snapshot type.
+     *
+     * It determines whether to create a nested `FieldTree` or a `Fields` container
+     * by inspecting the `__type` property of the snapshot, hydrates it, and attaches it to the parent tree.
+     *
+     * @param {FieldTree} tree - The parent tree instance where the new node will be added.
+     * @param {string} key - The name (key) for the new node.
+     * @param {FieldsSnapshot | FieldTreeSnapshot} snapshot - The source snapshot data.
+     * @throws If the snapshot contains an unsupported or unknown `__type`.
+     */
+    private addNodeFromSnapshot;
+}
+
+/**
+ */
+declare class FieldTreeSnapshotter {
+    readonly fieldsSnapshotter: FieldsSnapshotter;
+    constructor(fieldsSnapshotter: FieldsSnapshotter);
+    /**
+     * 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: CoreFieldTree): FieldTreeSnapshot;
 }
 
 /**
@@ -1162,6 +1215,14 @@ declare class DataStore implements Store {
      * @internal Used for serialization
      */
     getInternalTree(): CoreFieldTree | undefined;
+    /**
+     * @internal Used for serialization
+     */
+    getOrCreateInternalVariables(): CoreFields;
+    /**
+     * @internal Used for serialization
+     */
+    getOrCreateInternalTree(): CoreFieldTree;
     /**
      * @private
     */
@@ -1173,29 +1234,15 @@ declare class DataStore implements Store {
 }
 
 /**
- * Handles the serialization and deserialization of DataStore instances.
  *
- * This class ensures that both components of a DataStore (the detached variables
- * and the hierarchical tree) are correctly persisted and restored. It delegates
- * the actual serialization of the inner structures to the `FieldTreeSerializer`.
  */
-declare class DataStoreSerializer {
-    private readonly fieldTreeSerializer;
+declare class DataStoreHydrator {
+    private readonly fieldsFieldTreeHydrator;
     /**
      * Creates an instance of DataStoreSerializer.
-     * @param {FieldTreeSerializer} fieldTreeSerializer - The serializer used for the underlying tree and fields.
+     * @param {FieldTreeHydrator} fieldsFieldTreeHydrator - The serializer used for the underlying tree and fields.
      */
-    constructor(fieldTreeSerializer: FieldTreeSerializer<CoreFields>);
-    /**
-     * Captures the current state of a DataStore into a serializable snapshot.
-     *
-     * It checks for the existence of internal variables and the internal tree,
-     * serializing them only if they have been initialized (lazy serialization).
-     *
-     * @param {DataStore} store - The store instance to serialize.
-     * @returns {DataStoreSnapshot} The snapshot object.
-     */
-    snapshot(store: DataStore): DataStoreSnapshot;
+    constructor(fieldsFieldTreeHydrator: FieldTreeHydrator<CoreFields>);
     /**
      * Reconstructs a DataStore instance from a snapshot.
      *
@@ -1207,6 +1254,41 @@ declare class DataStoreSerializer {
      * @returns {DataStore} A new, fully restored DataStore instance.
      */
     hydrate(snapshot: DataStoreSnapshot): DataStore;
+    /**
+     * Synchronizes a DataStore instance with a snapshot.
+     *
+     * This method ensures the DataStore's internal state matches the snapshot by:
+     * 1. **Destroying** internal containers (variables/tree) if they are missing in the snapshot.
+     * 2. **Patching** (updating/creating) contents if they exist in the snapshot.
+     *
+     * This allows for a granular update where only specific parts of the store (e.g., only variables)
+     * are modified if the snapshot contains partial data, or a full reset if parts are missing.
+     *
+     * @param {DataStore} store - The target DataStore to update.
+     * @param {DataStoreSnapshot} snapshot - The source snapshot.
+     */
+    patch(store: DataStore, snapshot: DataStoreSnapshot): void;
+}
+
+/**
+ */
+declare class DataStoreSnapshotter {
+    private readonly treeSnapshotter;
+    /**
+     * Creates an instance of DataStoreSnapshotter.
+     * @param {FieldTreeSnapshotter} treeSnapshotter - The serializer used for the underlying tree and fields.
+     */
+    constructor(treeSnapshotter: FieldTreeSnapshotter);
+    /**
+     * Captures the current state of a DataStore into a serializable snapshot.
+     *
+     * It checks for the existence of internal variables and the internal tree,
+     * serializing them only if they have been initialized (lazy serialization).
+     *
+     * @param {DataStore} store - The store instance to serialize.
+     * @returns {DataStoreSnapshot} The snapshot object.
+     */
+    snapshot(store: DataStore): DataStoreSnapshot;
 }
 
 /**
@@ -1267,20 +1349,20 @@ declare function createCoreTreeNodeFactory(fieldRegistry: FieldRegistry): CoreTr
  * This function composes all necessary serializers (FieldTree, Fields, Field) for a complete setup.
  * @param {CoreTreeNodeFactory} fieldTreeNodeFactory - The factory used to create new tree nodes during deserialization.
  * @param policySerializer
- * @returns {FieldTreeSerializer<CoreFields>} A top-level serializer for the entire field tree.
+ * @returns {FieldTreeHydrator<CoreFields>} A top-level serializer for the entire field tree.
  */
-declare function createCoreTreeSerializer(fieldTreeNodeFactory: CoreTreeNodeFactory, policySerializer?: PolicySerializer): FieldTreeSerializer<CoreFields>;
+declare function createCoreTreeSerializer(fieldTreeNodeFactory: CoreTreeNodeFactory, policySerializer?: PolicySerializer): FieldTreeHydrator<CoreFields>;
 interface CoreFieldSystemConfig {
     registry?: FieldRegistry;
     policySerializer?: PolicySerializer;
 }
 /**
  * Creates a complete core setup for the field system.
- * @returns {{factory: CoreTreeNodeFactory, serializer: FieldTreeSerializer<CoreFields>}}
+ * @returns {{factory: CoreTreeNodeFactory, serializer: FieldTreeHydrator<CoreFields>}}
  */
 declare function createCoreFieldSystem(config?: CoreFieldSystemConfig): {
     factory: CoreTreeNodeFactory;
-    serializer: FieldTreeSerializer<CoreFields>;
+    serializer: FieldTreeHydrator<CoreFields>;
 };
 
-export { type BooleanField, ClampMaxPolicy, ClampMaxPolicySerializerHandler, ClampMinPolicy, ClampMinPolicySerializerHandler, ClampPolicy, ClampPolicySerializerHandler, CoreBooleanField, type CoreBooleanFieldOptions, CoreField, type CoreFieldSystemConfig, CoreFieldTree, CoreFields, CoreFieldsFactory, CoreNumericField, type CoreNumericFieldOptions, CoreStringField, type CoreStringFieldOptions, CoreTreeNodeFactory, DataStore, DataStoreSerializer, type DataStoreSnapshot, type Field, type FieldOptions, FieldRegistry, FieldSerializer, type FieldSnapshot, FieldTree, type FieldTreeFactory, FieldTreeSerializer, type FieldTreeSnapshot, Fields, type FieldsFactory, FieldsSerializer, type FieldsSnapshot, type NumericField, Policies, type Policy, PolicySerializer, type PolicySerializerHandler, type Store, type StoreCreateFieldOptions, type StringField, type TreeNode, clampMaxPolicy, clampMinPolicy, clampPolicy, createCoreFieldRegistry, createCoreFieldSystem, createCorePolicySerializer, createCoreTreeNodeFactory, createCoreTreeSerializer, createTypedMethodsMixin, isDataStore, isFieldTree, isFields };
+export { type BooleanField, ClampMaxPolicy, ClampMaxPolicySerializerHandler, ClampMinPolicy, ClampMinPolicySerializerHandler, ClampPolicy, ClampPolicySerializerHandler, CoreBooleanField, type CoreBooleanFieldOptions, CoreField, type CoreFieldSystemConfig, CoreFieldTree, CoreFields, CoreFieldsFactory, CoreNumericField, type CoreNumericFieldOptions, CoreStringField, type CoreStringFieldOptions, CoreTreeNodeFactory, DataStore, DataStoreHydrator, type DataStoreSnapshot, DataStoreSnapshotter, type Field, FieldHydrator, type FieldOptions, FieldRegistry, type FieldSnapshot, FieldSnapshotter, FieldTree, type FieldTreeFactory, FieldTreeHydrator, type FieldTreeSnapshot, FieldTreeSnapshotter, Fields, type FieldsFactory, FieldsHydrator, type FieldsSnapshot, FieldsSnapshotter, type NumericField, Policies, type Policy, PolicySerializer, type PolicySerializerHandler, type Store, type StoreCreateFieldOptions, type StringField, type TreeNode, clampMaxPolicy, clampMinPolicy, clampPolicy, createCoreFieldRegistry, createCoreFieldSystem, createCorePolicySerializer, createCoreTreeNodeFactory, createCoreTreeSerializer, createTypedMethodsMixin, isDataStore, isFieldTree, isFields };

package/dist/index.d.ts

@@ -789,7 +789,7 @@ interface FieldSnapshot {
  * to resolve class constructors and a `PolicySerializer` to handle the state
  * of any attached policies.
  */
-declare class FieldSerializer {
+declare class FieldHydrator {
     private readonly fieldRegistry;
     private readonly policySerializer;
     /**
@@ -798,13 +798,6 @@ declare class FieldSerializer {
      * @param {PolicySerializer} policySerializer - A serializer dedicated to handling Policy instances.
      */
     constructor(fieldRegistry: FieldRegistry, policySerializer: PolicySerializer);
-    /**
-     * 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.
-     */
-    snapshot(field: Field<any>): FieldSnapshot;
     /**
      * Restores a Field instance from its snapshot representation.
      * It uses the `__type` property to find the correct constructor and hydrates
@@ -828,6 +821,18 @@ declare class FieldSerializer {
     private hydratePolicies;
 }
 
+declare class FieldSnapshotter {
+    readonly policySerializer: PolicySerializer;
+    constructor(policySerializer: PolicySerializer);
+    /**
+     * 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.
+     */
+    snapshot(field: Field<any>): FieldSnapshot;
+}
+
 /**
  * A plain object representation of a Fields container's state for serialization.
  */
@@ -837,25 +842,53 @@ interface FieldsSnapshot {
 }
 
 /**
- * Orchestrates the serialization and deserialization of `Fields` container instances.
- *
- * This class acts as a high-level composer, responsible for converting an entire `Fields` object
- * into a storable snapshot and back.
- * It delegates the actual serialization of each `Field` and `Policy` to their respective serializers.
- *
- * @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.
+ * Deserialization of `Fields` container instances.
+ * Responsible for converting snapshot of `Fields` object into a `Fields` instance.
  */
-declare class FieldsSerializer<TFields extends Fields> {
+declare class FieldsHydrator<TFields extends Fields> {
     private readonly fieldsFactory;
-    private readonly fieldSerializer;
+    private readonly fieldHydrator;
     /**
      * Creates an instance of FieldsSerializer.
      * @param {FieldsFactory} fieldsFactory - A registry that maps string type names to Field constructors.
-     * @param {FieldSerializer} fieldSerializer - A serializer of field instances.
+     * @param {FieldHydrator} fieldHydrator - A hydrator of field instances.
+     */
+    constructor(fieldsFactory: FieldsFactory<TFields>, fieldHydrator: FieldHydrator);
+    /**
+     * Restores a `Fields` container instance from its snapshot representation.
+     *
+     * 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 {Fields} A new `DefaultFields` instance populated with the restored fields.
+     */
+    hydrate(snapshot: FieldsSnapshot): TFields;
+    /**
+     * Synchronizes an existing `Fields` container with a snapshot.
+     *
+     * This method performs a "smart update":
+     * 1. **Removes** fields from the container that are missing in the snapshot.
+     * 2. **Patches** existing fields in-place using {@link FieldHydrator.patch}, preserving object references.
+     * 3. **Creates** (hydrates) and adds new fields that exist in the snapshot but not in the container.
+     *
+     * @param {Fields} fields - The target `Fields` container to update.
+     * @param {FieldsSnapshot} snapshot - The source snapshot containing the desired state.
      */
-    constructor(fieldsFactory: FieldsFactory<TFields>, fieldSerializer: FieldSerializer);
+    patch(fields: TFields, snapshot: FieldsSnapshot): void;
+}
+
+/**
+ * The serialization of `Fields` container instances.
+ *
+ * This class responsible for converting an entire `Fields` object
+ * into a storable snapshot.
+ */
+declare class FieldsSnapshotter {
+    private readonly fieldSnapshotter;
+    /**
+     * Creates an instance of FieldsSnapshotter.
+     * @param {FieldSnapshotter} fieldSnapshotter - A serializer of field instances.
+     */
+    constructor(fieldSnapshotter: FieldSnapshotter);
     /**
      * Creates a serializable snapshot of a `Fields` container.
      *
@@ -865,14 +898,6 @@ declare class FieldsSerializer<TFields extends Fields> {
      * @returns {FieldsSnapshot} A plain object ready for JSON serialization.
      */
     snapshot(fields: Fields): FieldsSnapshot;
-    /**
-     * Restores a `Fields` container instance from its snapshot representation.
-     *
-     * 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 {Fields} A new `DefaultFields` instance populated with the restored fields.
-     */
-    hydrate(snapshot: FieldsSnapshot): TFields;
 }
 
 /**
@@ -890,38 +915,66 @@ interface FieldTreeSnapshot {
 }
 
 /**
- * Orchestrates the recursive serialization and deserialization of `FieldTree` instances.
+ * Orchestrates the recursive deserialization of `FieldTree` instances.
  *
  * This class handles the conversion of an entire `FieldTree` object graph into a
  * plain, storable snapshot and vice-versa. It delegates the processing of `Fields`
- * leaf nodes to a dedicated `FieldsSerializer`.
+ * leaf nodes to a dedicated `FieldsHydrator`.
  * @todo Refactoring: The current implementation uses `if/else` logic in `snapshot` and `hydrate`
  *       to process different node types. A more extensible approach would be to use a
  *       registry of dedicated handlers for each node type.
  *       This would allow new node types to be supported without
  *       modifying this class, adhering to the Open/Closed Principle.
- *
- * @todo Implement a `patch(tree, snapshot)` method for recursive, non-destructive
- *       updates. This method should traverse the existing tree and the snapshot,
- *       patching nodes in place to maintain object references.
  */
-declare class FieldTreeSerializer<TFields extends Fields> {
+declare class FieldTreeHydrator<TFields extends Fields> {
     _factory: FieldTreeFactory<TFields>;
-    _fieldsSerializer: FieldsSerializer<TFields>;
+    _fieldsHydrator: FieldsHydrator<TFields>;
     get factory(): FieldTreeFactory<TFields>;
-    get fieldsSerializer(): FieldsSerializer<TFields>;
-    constructor(fieldTreeNodeFactory: FieldTreeFactory<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<TFields>): FieldTreeSnapshot;
+    get fieldsHydrator(): FieldsHydrator<TFields>;
+    constructor(fieldTreeNodeFactory: FieldTreeFactory<TFields>, fieldsHydrator: FieldsHydrator<TFields>);
     /**
      * 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<TFields>;
+    /**
+     * Synchronizes an existing `FieldTree` branch with a snapshot.
+     *
+     * This method performs a recursive update to match the tree state with the provided snapshot:
+     * 1. **Removes** child nodes that are present in the tree but missing in the snapshot.
+     * 2. **Creates** new nodes that are present in the snapshot but missing in the tree.
+     * 3. **Replaces** nodes if their type has changed (e.g., replacing a `Fields` leaf with a `FieldTree` branch).
+     * 4. **Patches** existing matching nodes in-place (recursively).
+     *
+     * @param {FieldTree} tree - The target tree instance to update.
+     * @param {FieldTreeSnapshot} snapshot - The source snapshot containing the desired state.
+     */
+    patch(tree: FieldTree<TFields>, snapshot: FieldTreeSnapshot): void;
+    /**
+     * Helper method to instantiate and add a new node to the tree based on the snapshot type.
+     *
+     * It determines whether to create a nested `FieldTree` or a `Fields` container
+     * by inspecting the `__type` property of the snapshot, hydrates it, and attaches it to the parent tree.
+     *
+     * @param {FieldTree} tree - The parent tree instance where the new node will be added.
+     * @param {string} key - The name (key) for the new node.
+     * @param {FieldsSnapshot | FieldTreeSnapshot} snapshot - The source snapshot data.
+     * @throws If the snapshot contains an unsupported or unknown `__type`.
+     */
+    private addNodeFromSnapshot;
+}
+
+/**
+ */
+declare class FieldTreeSnapshotter {
+    readonly fieldsSnapshotter: FieldsSnapshotter;
+    constructor(fieldsSnapshotter: FieldsSnapshotter);
+    /**
+     * 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: CoreFieldTree): FieldTreeSnapshot;
 }
 
 /**
@@ -1162,6 +1215,14 @@ declare class DataStore implements Store {
      * @internal Used for serialization
      */
     getInternalTree(): CoreFieldTree | undefined;
+    /**
+     * @internal Used for serialization
+     */
+    getOrCreateInternalVariables(): CoreFields;
+    /**
+     * @internal Used for serialization
+     */
+    getOrCreateInternalTree(): CoreFieldTree;
     /**
      * @private
     */
@@ -1173,29 +1234,15 @@ declare class DataStore implements Store {
 }
 
 /**
- * Handles the serialization and deserialization of DataStore instances.
  *
- * This class ensures that both components of a DataStore (the detached variables
- * and the hierarchical tree) are correctly persisted and restored. It delegates
- * the actual serialization of the inner structures to the `FieldTreeSerializer`.
  */
-declare class DataStoreSerializer {
-    private readonly fieldTreeSerializer;
+declare class DataStoreHydrator {
+    private readonly fieldsFieldTreeHydrator;
     /**
      * Creates an instance of DataStoreSerializer.
-     * @param {FieldTreeSerializer} fieldTreeSerializer - The serializer used for the underlying tree and fields.
+     * @param {FieldTreeHydrator} fieldsFieldTreeHydrator - The serializer used for the underlying tree and fields.
      */
-    constructor(fieldTreeSerializer: FieldTreeSerializer<CoreFields>);
-    /**
-     * Captures the current state of a DataStore into a serializable snapshot.
-     *
-     * It checks for the existence of internal variables and the internal tree,
-     * serializing them only if they have been initialized (lazy serialization).
-     *
-     * @param {DataStore} store - The store instance to serialize.
-     * @returns {DataStoreSnapshot} The snapshot object.
-     */
-    snapshot(store: DataStore): DataStoreSnapshot;
+    constructor(fieldsFieldTreeHydrator: FieldTreeHydrator<CoreFields>);
     /**
      * Reconstructs a DataStore instance from a snapshot.
      *
@@ -1207,6 +1254,41 @@ declare class DataStoreSerializer {
      * @returns {DataStore} A new, fully restored DataStore instance.
      */
     hydrate(snapshot: DataStoreSnapshot): DataStore;
+    /**
+     * Synchronizes a DataStore instance with a snapshot.
+     *
+     * This method ensures the DataStore's internal state matches the snapshot by:
+     * 1. **Destroying** internal containers (variables/tree) if they are missing in the snapshot.
+     * 2. **Patching** (updating/creating) contents if they exist in the snapshot.
+     *
+     * This allows for a granular update where only specific parts of the store (e.g., only variables)
+     * are modified if the snapshot contains partial data, or a full reset if parts are missing.
+     *
+     * @param {DataStore} store - The target DataStore to update.
+     * @param {DataStoreSnapshot} snapshot - The source snapshot.
+     */
+    patch(store: DataStore, snapshot: DataStoreSnapshot): void;
+}
+
+/**
+ */
+declare class DataStoreSnapshotter {
+    private readonly treeSnapshotter;
+    /**
+     * Creates an instance of DataStoreSnapshotter.
+     * @param {FieldTreeSnapshotter} treeSnapshotter - The serializer used for the underlying tree and fields.
+     */
+    constructor(treeSnapshotter: FieldTreeSnapshotter);
+    /**
+     * Captures the current state of a DataStore into a serializable snapshot.
+     *
+     * It checks for the existence of internal variables and the internal tree,
+     * serializing them only if they have been initialized (lazy serialization).
+     *
+     * @param {DataStore} store - The store instance to serialize.
+     * @returns {DataStoreSnapshot} The snapshot object.
+     */
+    snapshot(store: DataStore): DataStoreSnapshot;
 }
 
 /**
@@ -1267,20 +1349,20 @@ declare function createCoreTreeNodeFactory(fieldRegistry: FieldRegistry): CoreTr
  * This function composes all necessary serializers (FieldTree, Fields, Field) for a complete setup.
  * @param {CoreTreeNodeFactory} fieldTreeNodeFactory - The factory used to create new tree nodes during deserialization.
  * @param policySerializer
- * @returns {FieldTreeSerializer<CoreFields>} A top-level serializer for the entire field tree.
+ * @returns {FieldTreeHydrator<CoreFields>} A top-level serializer for the entire field tree.
  */
-declare function createCoreTreeSerializer(fieldTreeNodeFactory: CoreTreeNodeFactory, policySerializer?: PolicySerializer): FieldTreeSerializer<CoreFields>;
+declare function createCoreTreeSerializer(fieldTreeNodeFactory: CoreTreeNodeFactory, policySerializer?: PolicySerializer): FieldTreeHydrator<CoreFields>;
 interface CoreFieldSystemConfig {
     registry?: FieldRegistry;
     policySerializer?: PolicySerializer;
 }
 /**
  * Creates a complete core setup for the field system.
- * @returns {{factory: CoreTreeNodeFactory, serializer: FieldTreeSerializer<CoreFields>}}
+ * @returns {{factory: CoreTreeNodeFactory, serializer: FieldTreeHydrator<CoreFields>}}
  */
 declare function createCoreFieldSystem(config?: CoreFieldSystemConfig): {
     factory: CoreTreeNodeFactory;
-    serializer: FieldTreeSerializer<CoreFields>;
+    serializer: FieldTreeHydrator<CoreFields>;
 };
 
-export { type BooleanField, ClampMaxPolicy, ClampMaxPolicySerializerHandler, ClampMinPolicy, ClampMinPolicySerializerHandler, ClampPolicy, ClampPolicySerializerHandler, CoreBooleanField, type CoreBooleanFieldOptions, CoreField, type CoreFieldSystemConfig, CoreFieldTree, CoreFields, CoreFieldsFactory, CoreNumericField, type CoreNumericFieldOptions, CoreStringField, type CoreStringFieldOptions, CoreTreeNodeFactory, DataStore, DataStoreSerializer, type DataStoreSnapshot, type Field, type FieldOptions, FieldRegistry, FieldSerializer, type FieldSnapshot, FieldTree, type FieldTreeFactory, FieldTreeSerializer, type FieldTreeSnapshot, Fields, type FieldsFactory, FieldsSerializer, type FieldsSnapshot, type NumericField, Policies, type Policy, PolicySerializer, type PolicySerializerHandler, type Store, type StoreCreateFieldOptions, type StringField, type TreeNode, clampMaxPolicy, clampMinPolicy, clampPolicy, createCoreFieldRegistry, createCoreFieldSystem, createCorePolicySerializer, createCoreTreeNodeFactory, createCoreTreeSerializer, createTypedMethodsMixin, isDataStore, isFieldTree, isFields };
+export { type BooleanField, ClampMaxPolicy, ClampMaxPolicySerializerHandler, ClampMinPolicy, ClampMinPolicySerializerHandler, ClampPolicy, ClampPolicySerializerHandler, CoreBooleanField, type CoreBooleanFieldOptions, CoreField, type CoreFieldSystemConfig, CoreFieldTree, CoreFields, CoreFieldsFactory, CoreNumericField, type CoreNumericFieldOptions, CoreStringField, type CoreStringFieldOptions, CoreTreeNodeFactory, DataStore, DataStoreHydrator, type DataStoreSnapshot, DataStoreSnapshotter, type Field, FieldHydrator, type FieldOptions, FieldRegistry, type FieldSnapshot, FieldSnapshotter, FieldTree, type FieldTreeFactory, FieldTreeHydrator, type FieldTreeSnapshot, FieldTreeSnapshotter, Fields, type FieldsFactory, FieldsHydrator, type FieldsSnapshot, FieldsSnapshotter, type NumericField, Policies, type Policy, PolicySerializer, type PolicySerializerHandler, type Store, type StoreCreateFieldOptions, type StringField, type TreeNode, clampMaxPolicy, clampMinPolicy, clampPolicy, createCoreFieldRegistry, createCoreFieldSystem, createCorePolicySerializer, createCoreTreeNodeFactory, createCoreTreeSerializer, createTypedMethodsMixin, isDataStore, isFieldTree, isFields };