@axi-engine/fields 0.3.10 → 0.3.12

package/dist/index.js

@@ -35,13 +35,17 @@ __export(index_exports, {
   CoreStringField: () => CoreStringField,
   CoreTreeNodeFactory: () => CoreTreeNodeFactory,
   DataStore: () => DataStore,
-  DataStoreSerializer: () => DataStoreSerializer,
+  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,
@@ -469,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) {
@@ -825,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 };
@@ -835,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 };
@@ -845,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 };
@@ -855,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();
@@ -892,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.
@@ -904,25 +911,6 @@ var FieldSerializer = class {
     this.fieldRegistry = fieldRegistry;
     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.
-   * @param {Field<any>} field - The Field instance to serialize.
-   * @returns {FieldSnapshot} A plain object ready for JSON serialization.
-   */
-  snapshot(field) {
-    let snapshot = {
-      __type: field.typeName,
-      name: field.name,
-      value: field.value
-    };
-    if (!field.policies.isEmpty()) {
-      const serializedPolicies = [];
-      field.policies.items.forEach((policy) => serializedPolicies.push(this.policySerializer.snapshot(policy)));
-      snapshot.policies = serializedPolicies;
-    }
-    return snapshot;
-  }
   /**
    * Restores a Field instance from its snapshot representation.
    * It uses the `__type` property to find the correct constructor and hydrates
@@ -949,48 +937,50 @@ var FieldSerializer = class {
    * @param {FieldSnapshot} snapshot - The snapshot containing the new state.
    */
   patch(field, snapshot) {
-    let policies = this.hydratePolicies(snapshot);
     field.policies.clear();
-    if (policies) {
-      policies.forEach((p) => field.policies.add(p));
-    }
+    const policies = this.hydratePolicies(snapshot);
+    policies?.forEach((p) => field.policies.add(p));
     field.value = snapshot.value;
   }
   hydratePolicies(snapshot) {
-    if ((0, import_utils7.isNullOrUndefined)(snapshot.policies)) {
-      return void 0;
+    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.
+   * @param {Field<any>} field - The Field instance to serialize.
+   * @returns {FieldSnapshot} A plain object ready for JSON serialization.
+   */
+  snapshot(field) {
+    let snapshot = {
+      __type: field.typeName,
+      name: field.name,
+      value: field.value
+    };
+    if (!field.policies.isEmpty()) {
+      snapshot.policies = Array.from(field.policies.items.values()).map((policy) => this.policySerializer.snapshot(policy));
     }
-    const policies = [];
-    snapshot.policies.forEach((p) => policies.push(this.policySerializer.hydrate(p)));
-    return policies;
+    return snapshot;
   }
 };
 
-// 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.
@@ -1004,44 +994,80 @@ 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
+// 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 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.fieldSnapshotter.snapshot(field));
+    return res;
+  }
+};
+
+// src/serializers/field-tree-hydrator.ts
 var import_utils8 = require("@axi-engine/utils");
-var FieldTreeSerializer = class {
+var FieldTreeHydrator = class {
   _factory;
-  _fieldsSerializer;
+  _fieldsHydrator;
   get factory() {
     return this._factory;
   }
-  get fieldsSerializer() {
-    return this._fieldsSerializer;
+  get fieldsHydrator() {
+    return this._fieldsHydrator;
   }
-  constructor(fieldTreeNodeFactory, fieldsSerializer) {
+  constructor(fieldTreeNodeFactory, fieldsHydrator) {
     this._factory = fieldTreeNodeFactory;
-    this._fieldsSerializer = fieldsSerializer;
-  }
-  /**
-   * Creates a serializable snapshot of the entire tree and its contained fields.
-   * @returns A plain JavaScript object representing the complete state managed by this tree.
-   */
-  snapshot(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.fieldsSerializer.snapshot(node);
-      }
-    });
-    return res;
+    this._fieldsHydrator = fieldsHydrator;
   }
   /**
    * Restores the state of the tree from a snapshot.
@@ -1056,14 +1082,93 @@ var FieldTreeSerializer = class {
       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
@@ -1286,6 +1391,18 @@ var DataStore = class _DataStore {
   getInternalTree() {
     return this._tree;
   }
+  /**
+   * @internal Used for serialization
+   */
+  getOrCreateInternalVariables() {
+    return this.variables;
+  }
+  /**
+   * @internal Used for serialization
+   */
+  getOrCreateInternalTree() {
+    return this.tree;
+  }
   /**
    * @private
   */
@@ -1305,15 +1422,66 @@ var DataStore = class _DataStore {
   }
 };
 
-// src/serializer/data-store-serializer.ts
+// src/serializers/data-store-hydrator.ts
 var import_utils12 = require("@axi-engine/utils");
-var DataStoreSerializer = class {
+var DataStoreHydrator = class {
   /**
    * 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(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.
    */
-  constructor(fieldTreeSerializer) {
-    this.fieldTreeSerializer = fieldTreeSerializer;
+  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.
@@ -1330,29 +1498,14 @@ var DataStoreSerializer = class {
     };
     const variables = store.getInternalVariables();
     if (variables) {
-      snapshot.variables = this.fieldTreeSerializer.fieldsSerializer.snapshot(variables);
+      snapshot.variables = this.treeSnapshotter.fieldsSnapshotter.snapshot(variables);
     }
     const tree = store.getInternalTree();
     if (tree) {
-      snapshot.tree = this.fieldTreeSerializer.snapshot(tree);
+      snapshot.tree = this.treeSnapshotter.snapshot(tree);
     }
     return snapshot;
   }
-  /**
-   * 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.fieldTreeSerializer.hydrate(snapshot.tree);
-    const variables = (0, import_utils12.isNullOrUndefined)(snapshot.variables) ? void 0 : this.fieldTreeSerializer.fieldsSerializer.hydrate(snapshot.variables);
-    return new DataStore(tree ? tree : this.fieldTreeSerializer.factory, variables);
-  }
 };
 
 // src/setup.ts
@@ -1375,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())
     )
   );
 }
@@ -1406,13 +1559,17 @@ function createCoreFieldSystem(config) {
   CoreStringField,
   CoreTreeNodeFactory,
   DataStore,
-  DataStoreSerializer,
+  DataStoreHydrator,
+  DataStoreSnapshotter,
+  FieldHydrator,
   FieldRegistry,
-  FieldSerializer,
+  FieldSnapshotter,
   FieldTree,
-  FieldTreeSerializer,
+  FieldTreeHydrator,
+  FieldTreeSnapshotter,
   Fields,
-  FieldsSerializer,
+  FieldsHydrator,
+  FieldsSnapshotter,
   Policies,
   PolicySerializer,
   clampMaxPolicy,