@axi-engine/fields 0.3.9 → 0.3.11

package/dist/index.js

@@ -35,12 +35,17 @@ __export(index_exports, {
   CoreStringField: () => CoreStringField,
   CoreTreeNodeFactory: () => CoreTreeNodeFactory,
   DataStore: () => DataStore,
+  DataStoreHydrator: () => DataStoreHydrator,
+  DataStoreSnapshotter: () => DataStoreSnapshotter,
+  FieldHydrator: () => FieldHydrator,
   FieldRegistry: () => FieldRegistry,
-  FieldSerializer: () => FieldSerializer,
+  FieldSnapshotter: () => FieldSnapshotter,
   FieldTree: () => FieldTree,
-  FieldTreeSerializer: () => FieldTreeSerializer,
+  FieldTreeHydrator: () => FieldTreeHydrator,
+  FieldTreeSnapshotter: () => FieldTreeSnapshotter,
   Fields: () => Fields,
-  FieldsSerializer: () => FieldsSerializer,
+  FieldsHydrator: () => FieldsHydrator,
+  FieldsSnapshotter: () => FieldsSnapshotter,
   Policies: () => Policies,
   PolicySerializer: () => PolicySerializer,
   clampMaxPolicy: () => clampMaxPolicy,
@@ -468,6 +473,9 @@ var Fields = class _Fields {
    */
   remove(names) {
     const namesToRemove = Array.isArray(names) ? names : [names];
+    if (!namesToRemove.length) {
+      return;
+    }
     const reallyRemoved = namesToRemove.filter((name) => {
       const field = this._fields.get(name);
       if (!field) {
@@ -824,7 +832,7 @@ var CoreTreeNodeFactory = class extends CoreFieldsFactory {
   }
 };
 
-// src/serializer/policies/clamp-policy-serializer-handler.ts
+// src/serializers/policies/clamp-policy-serializer-handler.ts
 var ClampPolicySerializerHandler = class {
   snapshot(policy) {
     return { min: policy.min, max: policy.max };
@@ -834,7 +842,7 @@ var ClampPolicySerializerHandler = class {
   }
 };
 
-// src/serializer/policies/clamp-max-policy-serializer-handler.ts
+// src/serializers/policies/clamp-max-policy-serializer-handler.ts
 var ClampMaxPolicySerializerHandler = class {
   snapshot(policy) {
     return { max: policy.max };
@@ -844,7 +852,7 @@ var ClampMaxPolicySerializerHandler = class {
   }
 };
 
-// src/serializer/policies/clamp-min-policy-serializer-handler.ts
+// src/serializers/policies/clamp-min-policy-serializer-handler.ts
 var ClampMinPolicySerializerHandler = class {
   snapshot(policy) {
     return { min: policy.min };
@@ -854,7 +862,7 @@ var ClampMinPolicySerializerHandler = class {
   }
 };
 
-// src/serializer/policy-serializer.ts
+// src/serializers/policy-serializer.ts
 var import_utils6 = require("@axi-engine/utils");
 var PolicySerializer = class {
   handlers = new import_utils6.Registry();
@@ -891,9 +899,9 @@ var PolicySerializer = class {
   }
 };
 
-// src/serializer/field-serializer.ts
+// src/serializers/field-hydrator.ts
 var import_utils7 = require("@axi-engine/utils");
-var FieldSerializer = class {
+var FieldHydrator = class {
   /**
    * Creates an instance of FieldSerializer.
    * @param {FieldRegistry} fieldRegistry - A registry that maps string type names to Field constructors.
@@ -903,6 +911,47 @@ var FieldSerializer = class {
     this.fieldRegistry = fieldRegistry;
     this.policySerializer = policySerializer;
   }
+  /**
+   * 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.
+   */
+  hydrate(snapshot) {
+    const fieldType = snapshot.__type;
+    (0, import_utils7.throwIfEmpty)(fieldType, 'Invalid field snapshot: missing "__type" identifier.');
+    const Ctor = this.fieldRegistry.getOrThrow(fieldType);
+    let policies = this.hydratePolicies(snapshot);
+    return new Ctor(snapshot.name, snapshot.value, { policies });
+  }
+  /**
+   * Updates an existing Field instance with data from a snapshot.
+   *
+   * This method modifies the field in-place, preserving the object reference.
+   * It updates the field's value and completely replaces its current policies
+   * with the ones defined in the snapshot.
+   *
+   * @param {Field<any>} field - The existing Field instance to update.
+   * @param {FieldSnapshot} snapshot - The snapshot containing the new state.
+   */
+  patch(field, snapshot) {
+    field.policies.clear();
+    const policies = this.hydratePolicies(snapshot);
+    policies?.forEach((p) => field.policies.add(p));
+    field.value = snapshot.value;
+  }
+  hydratePolicies(snapshot) {
+    return (0, import_utils7.isNullOrUndefined)(snapshot.policies) ? void 0 : snapshot.policies.map((p) => this.policySerializer.hydrate(p));
+  }
+};
+
+// src/serializers/field-snapshotter.ts
+var FieldSnapshotter = class {
+  constructor(policySerializer) {
+    this.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.
@@ -916,58 +965,22 @@ var FieldSerializer = class {
       value: field.value
     };
     if (!field.policies.isEmpty()) {
-      const serializedPolicies = [];
-      field.policies.items.forEach((policy) => serializedPolicies.push(this.policySerializer.snapshot(policy)));
-      snapshot.policies = serializedPolicies;
+      snapshot.policies = Array.from(field.policies.items.values()).map((policy) => this.policySerializer.snapshot(policy));
     }
     return snapshot;
   }
-  /**
-   * 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.
-   */
-  hydrate(snapshot) {
-    const fieldType = snapshot.__type;
-    (0, import_utils7.throwIfEmpty)(fieldType, 'Invalid field snapshot: missing "__type" identifier.');
-    const Ctor = this.fieldRegistry.getOrThrow(fieldType);
-    let policies;
-    if (!(0, import_utils7.isNullOrUndefined)(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 {
+// src/serializers/fields-hydrator.ts
+var FieldsHydrator = class {
   /**
    * 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, fieldSerializer) {
+  constructor(fieldsFactory, fieldHydrator) {
     this.fieldsFactory = fieldsFactory;
-    this.fieldSerializer = 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.
-   */
-  snapshot(fields) {
-    const res = {
-      __type: fields.typeName
-    };
-    fields.fields.forEach((field) => res[field.name] = this.fieldSerializer.snapshot(field));
-    return res;
+    this.fieldHydrator = fieldHydrator;
   }
   /**
    * Restores a `Fields` container instance from its snapshot representation.
@@ -981,37 +994,81 @@ var FieldsSerializer = class {
     const fields = this.fieldsFactory.fields();
     for (const fieldName in fieldsData) {
       const fieldSnapshot = fieldsData[fieldName];
-      const restoredField = this.fieldSerializer.hydrate(fieldSnapshot);
+      const restoredField = this.fieldHydrator.hydrate(fieldSnapshot);
       fields.add(restoredField);
     }
     return fields;
   }
+  /**
+   * 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.
+   */
+  patch(fields, snapshot) {
+    const { __type, ...fieldsData } = snapshot;
+    const snapshotKeys = new Set(Object.keys(fieldsData));
+    const fieldsToRemove = Array.from(fields.fields.values()).filter((f) => !snapshotKeys.has(f.name)).map((f) => f.name);
+    fields.remove(fieldsToRemove);
+    for (const fieldName in fieldsData) {
+      const fieldSnapshot = fieldsData[fieldName];
+      if (fields.has(fieldName)) {
+        const existingField = fields.get(fieldName);
+        this.fieldHydrator.patch(existingField, fieldSnapshot);
+      } else {
+        const newField = this.fieldHydrator.hydrate(fieldSnapshot);
+        fields.add(newField);
+      }
+    }
+  }
 };
 
-// src/serializer/field-tree-serializer.ts
-var import_utils8 = require("@axi-engine/utils");
-var FieldTreeSerializer = class {
-  constructor(fieldTreeNodeFactory, fieldsSerializer) {
-    this.fieldTreeNodeFactory = fieldTreeNodeFactory;
-    this.fieldsSerializer = fieldsSerializer;
+// src/serializers/fields-snapshotter.ts
+var FieldsSnapshotter = class {
+  /**
+   * Creates an instance of FieldsSnapshotter.
+   * @param {FieldSnapshotter} fieldSnapshotter - A serializer of field instances.
+   */
+  constructor(fieldSnapshotter) {
+    this.fieldSnapshotter = fieldSnapshotter;
   }
   /**
-   * 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.
+   * 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.
    */
-  snapshot(tree) {
+  snapshot(fields) {
     const res = {
-      __type: tree.typeName
+      __type: fields.typeName
     };
-    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);
-      }
-    });
+    fields.fields.forEach((field) => res[field.name] = this.fieldSnapshotter.snapshot(field));
     return res;
   }
+};
+
+// src/serializers/field-tree-hydrator.ts
+var import_utils8 = require("@axi-engine/utils");
+var FieldTreeHydrator = class {
+  _factory;
+  _fieldsHydrator;
+  get factory() {
+    return this._factory;
+  }
+  get fieldsHydrator() {
+    return this._fieldsHydrator;
+  }
+  constructor(fieldTreeNodeFactory, fieldsHydrator) {
+    this._factory = fieldTreeNodeFactory;
+    this._fieldsHydrator = fieldsHydrator;
+  }
   /**
    * Restores the state of the tree from a snapshot.
    * It intelligently creates missing nodes based on `__type` metadata and delegates hydration to child nodes.
@@ -1019,24 +1076,103 @@ var FieldTreeSerializer = class {
    */
   hydrate(snapshot) {
     const { __type, ...nodes } = snapshot;
-    const tree = this.fieldTreeNodeFactory.tree();
+    const tree = this._factory.tree();
     for (const key in nodes) {
       const nodeData = nodes[key];
       if ((0, import_utils8.isString)(nodeData)) {
         continue;
       }
-      if (nodeData.__type === FieldTree.typeName) {
-        tree.addNode(key, this.hydrate(nodeData));
-      } else if (nodeData.__type === Fields.typeName) {
-        tree.addNode(key, this.fieldsSerializer.hydrate(nodeData));
-      }
+      this.addNodeFromSnapshot(tree, key, nodeData);
     }
     return tree;
   }
+  /**
+   * 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, snapshot) {
+    const { __type, ...nodes } = snapshot;
+    const snapshotKeys = new Set(Object.keys(nodes));
+    const nodesToRemove = Array.from(tree.nodes.keys()).filter((key) => !snapshotKeys.has(key));
+    tree.removeNode(nodesToRemove);
+    for (const key in nodes) {
+      const nodeData = nodes[key];
+      if ((0, import_utils8.isString)(nodeData)) {
+        continue;
+      }
+      if (!tree.has(key)) {
+        this.addNodeFromSnapshot(tree, key, nodeData);
+      } else {
+        const treeNode = tree.getNode(key);
+        if (treeNode.typeName !== nodeData.__type) {
+          tree.removeNode(key);
+          this.addNodeFromSnapshot(tree, key, nodeData);
+        } else {
+          if (nodeData.__type === FieldTree.typeName) {
+            this.patch(treeNode, nodeData);
+          } else if (nodeData.__type === Fields.typeName) {
+            this.fieldsHydrator.patch(treeNode, nodeData);
+          }
+        }
+      }
+    }
+  }
+  /**
+   * 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`.
+   */
+  addNodeFromSnapshot(tree, key, snapshot) {
+    if (snapshot.__type === FieldTree.typeName) {
+      tree.addNode(key, this.hydrate(snapshot));
+    } else if (snapshot.__type === Fields.typeName) {
+      tree.addNode(key, this.fieldsHydrator.hydrate(snapshot));
+    } else {
+      (0, import_utils8.throwError)(`Can't hydrate node with unsupported type: ${snapshot.__type}`);
+    }
+  }
+};
+
+// src/serializers/field-tree-snapshotter.ts
+var FieldTreeSnapshotter = class {
+  constructor(fieldsSnapshotter) {
+    this.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) {
+    const res = {
+      __type: tree.typeName
+    };
+    tree.nodes.forEach((node, key) => {
+      if (node.typeName === tree.typeName) {
+        res[key] = this.snapshot(node);
+      } else if (node.typeName === Fields.typeName) {
+        res[key] = this.fieldsSnapshotter.snapshot(node);
+      }
+    });
+    return res;
+  }
 };
 
 // src/data-store.ts
-var import_utils10 = require("@axi-engine/utils");
+var import_utils11 = require("@axi-engine/utils");
 
 // src/data-store-field-resolver.ts
 var import_utils9 = require("@axi-engine/utils");
@@ -1059,24 +1195,51 @@ var StringFieldResolver = class {
   }
 };
 
+// src/guards.ts
+var import_utils10 = require("@axi-engine/utils");
+function isFields(value) {
+  return !(0, import_utils10.isNullOrUndefined)(value) && value.typeName === Fields.typeName;
+}
+function isFieldTree(value) {
+  return !(0, import_utils10.isNullOrUndefined)(value) && value.typeName === FieldTree.typeName;
+}
+function isDataStore(value) {
+  return !(0, import_utils10.isNullOrUndefined)(value) && value.typeName === DataStore.typeName;
+}
+
 // src/data-store.ts
 var DataStore = class _DataStore {
-  constructor(tree) {
-    this.tree = tree;
-    this.registerResolver(new NumericFieldResolver());
-    this.registerResolver(new BooleanFieldResolver());
-    this.registerResolver(new StringFieldResolver());
-  }
   static typeName = "dataStore";
   typeName = _DataStore.typeName;
   resolvers = [];
-  rootFieldsName = "__root_fields";
-  _rootFields;
-  get rootFields() {
-    if (!this._rootFields) {
-      this._rootFields = this.tree.getOrCreateFields(this.rootFieldsName);
+  _variables;
+  _tree;
+  _factory;
+  get variables() {
+    if (!this._variables) {
+      this._variables = this._factory.fields();
     }
-    return this._rootFields;
+    return this._variables;
+  }
+  get tree() {
+    if (!this._tree) {
+      this._tree = this._factory.tree();
+    }
+    return this._tree;
+  }
+  constructor(treeOrFactory, variables) {
+    if (!isFieldTree(treeOrFactory)) {
+      this._factory = treeOrFactory;
+    } else {
+      this._tree = treeOrFactory;
+      this._factory = this._tree.factory;
+    }
+    if (variables) {
+      this._variables = variables;
+    }
+    this.registerResolver(new NumericFieldResolver());
+    this.registerResolver(new BooleanFieldResolver());
+    this.registerResolver(new StringFieldResolver());
   }
   registerResolver(resolver) {
     this.resolvers.unshift(resolver);
@@ -1145,10 +1308,10 @@ var DataStore = class _DataStore {
     return this.getField(path);
   }
   getField(path) {
-    const pathArr = (0, import_utils10.ensurePathArray)(path);
-    (0, import_utils10.throwIfEmpty)(pathArr, `Wrong path or path is empty: ${(0, import_utils10.ensurePathString)(path)}, should contain at least one path segment`);
-    if (this.isPathToRootFields(pathArr)) {
-      return this.rootFields.get(pathArr[0]);
+    const pathArr = (0, import_utils11.ensurePathArray)(path);
+    (0, import_utils11.throwIfEmpty)(pathArr, `Wrong path or path is empty: ${(0, import_utils11.ensurePathString)(path)}, should contain at least one path segment`);
+    if (this.isPathToVariables(pathArr)) {
+      return this.variables.get(pathArr[0]);
     }
     const fieldName = pathArr.pop();
     const fields = this.tree.getFields(pathArr);
@@ -1167,10 +1330,10 @@ var DataStore = class _DataStore {
     return this.tree.getFieldTree(path);
   }
   remove(path) {
-    const pathArr = (0, import_utils10.ensurePathArray)(path);
-    (0, import_utils10.throwIfEmpty)(pathArr, `Wrong path or path is empty: ${(0, import_utils10.ensurePathString)(path)}, should contain at least one path segment`);
-    if (this.isPathToRootFields(pathArr)) {
-      this.rootFields.remove(pathArr);
+    const pathArr = (0, import_utils11.ensurePathArray)(path);
+    (0, import_utils11.throwIfEmpty)(pathArr, `Wrong path or path is empty: ${(0, import_utils11.ensurePathString)(path)}, should contain at least one path segment`);
+    if (this.isPathToVariables(pathArr)) {
+      this.variables.remove(pathArr);
       return;
     }
     const node = this.tree.findParentNode(pathArr);
@@ -1181,17 +1344,6 @@ var DataStore = class _DataStore {
       node.removeNode(leafName);
     }
   }
-  isPathToRootFields(path) {
-    return (0, import_utils10.ensurePathArray)(path).length === 1;
-  }
-  getDestinationFields(path) {
-    const pathArr = (0, import_utils10.ensurePathArray)(path);
-    if (this.isPathToRootFields(pathArr)) {
-      return { fields: this.rootFields, leafName: pathArr[0] };
-    }
-    const leafName = pathArr.pop();
-    return { fields: this.tree.getOrCreateFields(path), leafName };
-  }
   /**
    * Creates a new, independent instance of the Store with a fresh, empty data state (FieldsTree).
    *
@@ -1202,13 +1354,13 @@ var DataStore = class _DataStore {
    * @returns {DataStore} A new, isolated DataStore instance.
    */
   createIsolated() {
-    return new _DataStore(this.tree.createDetachedTree());
+    return new _DataStore(this._factory);
   }
   /** code below -> implementation of the DataStore from utils */
   has(path) {
-    const pathArr = (0, import_utils10.ensurePathArray)(path);
-    if (this.isPathToRootFields(pathArr)) {
-      return this.rootFields.has(pathArr[0]);
+    const pathArr = (0, import_utils11.ensurePathArray)(path);
+    if (this.isPathToVariables(pathArr)) {
+      return this.variables.has(pathArr[0]);
     }
     return this.tree.hasPath(pathArr);
   }
@@ -1227,19 +1379,134 @@ var DataStore = class _DataStore {
   delete(path) {
     this.remove(path);
   }
+  /**
+   * @internal Used for serialization
+   */
+  getInternalVariables() {
+    return this._variables;
+  }
+  /**
+   * @internal Used for serialization
+   */
+  getInternalTree() {
+    return this._tree;
+  }
+  /**
+   * @internal Used for serialization
+   */
+  getOrCreateInternalVariables() {
+    return this.variables;
+  }
+  /**
+   * @internal Used for serialization
+   */
+  getOrCreateInternalTree() {
+    return this.tree;
+  }
+  /**
+   * @private
+  */
+  isPathToVariables(path) {
+    return (0, import_utils11.ensurePathArray)(path).length === 1;
+  }
+  /**
+   * @private
+   */
+  getDestinationFields(path) {
+    const pathArr = (0, import_utils11.ensurePathArray)(path);
+    if (this.isPathToVariables(pathArr)) {
+      return { fields: this.variables, leafName: pathArr[0] };
+    }
+    const leafName = pathArr.pop();
+    return { fields: this.tree.getOrCreateFields(path), leafName };
+  }
 };
 
-// src/guards.ts
-var import_utils11 = require("@axi-engine/utils");
-function isFields(value) {
-  return !(0, import_utils11.isNullOrUndefined)(value) && value.typeName === Fields.typeName;
-}
-function isFieldTree(value) {
-  return !(0, import_utils11.isNullOrUndefined)(value) && value.typeName === FieldTree.typeName;
-}
-function isDataStore(value) {
-  return !(0, import_utils11.isNullOrUndefined)(value) && value.typeName === DataStore.typeName;
-}
+// src/serializers/data-store-hydrator.ts
+var import_utils12 = require("@axi-engine/utils");
+var DataStoreHydrator = class {
+  /**
+   * Creates an instance of DataStoreSerializer.
+   * @param {FieldTreeHydrator} fieldsFieldTreeHydrator - The serializer used for the underlying tree and fields.
+   */
+  constructor(fieldsFieldTreeHydrator) {
+    this.fieldsFieldTreeHydrator = fieldsFieldTreeHydrator;
+  }
+  /**
+   * Reconstructs a DataStore instance from a snapshot.
+   *
+   * If the snapshot contains a tree, the store is initialized with it.
+   * If not, the store is initialized with the factory (lazy mode), and the
+   * detached variables are injected if present.
+   *
+   * @param {DataStoreSnapshot} snapshot - The snapshot to hydrate.
+   * @returns {DataStore} A new, fully restored DataStore instance.
+   */
+  hydrate(snapshot) {
+    const tree = (0, import_utils12.isNullOrUndefined)(snapshot.tree) ? void 0 : this.fieldsFieldTreeHydrator.hydrate(snapshot.tree);
+    const variables = (0, import_utils12.isNullOrUndefined)(snapshot.variables) ? void 0 : this.fieldsFieldTreeHydrator.fieldsHydrator.hydrate(snapshot.variables);
+    return new DataStore(tree ? tree : this.fieldsFieldTreeHydrator.factory, variables);
+  }
+  /**
+   * 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, snapshot) {
+    if (!snapshot.variables) {
+      store.getInternalVariables()?.destroy();
+    } else {
+      this.fieldsFieldTreeHydrator.fieldsHydrator.patch(store.getOrCreateInternalVariables(), snapshot.variables);
+    }
+    if (!snapshot.tree) {
+      store.getInternalTree()?.destroy();
+    } else {
+      this.fieldsFieldTreeHydrator.patch(store.getOrCreateInternalTree(), snapshot.tree);
+    }
+  }
+};
+
+// src/serializers/data-store-snapshotter.ts
+var DataStoreSnapshotter = class {
+  /**
+   * Creates an instance of DataStoreSnapshotter.
+   * @param {FieldTreeSnapshotter} treeSnapshotter - The serializer used for the underlying tree and fields.
+   */
+  constructor(treeSnapshotter) {
+    this.treeSnapshotter = treeSnapshotter;
+  }
+  /**
+   * 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) {
+    let snapshot = {
+      __type: store.typeName
+    };
+    const variables = store.getInternalVariables();
+    if (variables) {
+      snapshot.variables = this.treeSnapshotter.fieldsSnapshotter.snapshot(variables);
+    }
+    const tree = store.getInternalTree();
+    if (tree) {
+      snapshot.tree = this.treeSnapshotter.snapshot(tree);
+    }
+    return snapshot;
+  }
+};
 
 // src/setup.ts
 function createCoreFieldRegistry() {
@@ -1261,11 +1528,11 @@ function createCoreTreeNodeFactory(fieldRegistry) {
   return new CoreTreeNodeFactory(fieldRegistry);
 }
 function createCoreTreeSerializer(fieldTreeNodeFactory, policySerializer) {
-  return new FieldTreeSerializer(
+  return new FieldTreeHydrator(
     fieldTreeNodeFactory,
-    new FieldsSerializer(
+    new FieldsHydrator(
       fieldTreeNodeFactory,
-      new FieldSerializer(fieldTreeNodeFactory.fieldRegistry, policySerializer ?? createCorePolicySerializer())
+      new FieldHydrator(fieldTreeNodeFactory.fieldRegistry, policySerializer ?? createCorePolicySerializer())
     )
   );
 }
@@ -1292,12 +1559,17 @@ function createCoreFieldSystem(config) {
   CoreStringField,
   CoreTreeNodeFactory,
   DataStore,
+  DataStoreHydrator,
+  DataStoreSnapshotter,
+  FieldHydrator,
   FieldRegistry,
-  FieldSerializer,
+  FieldSnapshotter,
   FieldTree,
-  FieldTreeSerializer,
+  FieldTreeHydrator,
+  FieldTreeSnapshotter,
   Fields,
-  FieldsSerializer,
+  FieldsHydrator,
+  FieldsSnapshotter,
   Policies,
   PolicySerializer,
   clampMaxPolicy,