@axi-engine/fields 0.3.10 → 0.3.12

package/dist/index.mjs

@@ -408,6 +408,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) {
@@ -764,7 +767,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 };
@@ -774,7 +777,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 };
@@ -784,7 +787,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 };
@@ -794,7 +797,7 @@ var ClampMinPolicySerializerHandler = class {
   }
 };
 
-// src/serializer/policy-serializer.ts
+// src/serializers/policy-serializer.ts
 import { Registry as Registry2, throwIfEmpty as throwIfEmpty2 } from "@axi-engine/utils";
 var PolicySerializer = class {
   handlers = new Registry2();
@@ -831,9 +834,9 @@ var PolicySerializer = class {
   }
 };
 
-// src/serializer/field-serializer.ts
+// src/serializers/field-hydrator.ts
 import { isNullOrUndefined as isNullOrUndefined2, throwIfEmpty as throwIfEmpty3 } from "@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.
@@ -843,25 +846,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
@@ -888,48 +872,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 (isNullOrUndefined2(snapshot.policies)) {
-      return void 0;
+    return isNullOrUndefined2(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.
@@ -943,45 +929,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
-import { isString } from "@axi-engine/utils";
-var FieldTreeSerializer = class {
-  _factory;
-  _fieldsSerializer;
-  get factory() {
-    return this._factory;
-  }
-  get fieldsSerializer() {
-    return this._fieldsSerializer;
-  }
-  constructor(fieldTreeNodeFactory, fieldsSerializer) {
-    this._factory = 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
+import { isString, throwError } from "@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.
@@ -995,14 +1017,93 @@ var FieldTreeSerializer = class {
       if (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 (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 {
+      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
@@ -1225,6 +1326,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
   */
@@ -1244,15 +1357,66 @@ var DataStore = class _DataStore {
   }
 };
 
-// src/serializer/data-store-serializer.ts
+// src/serializers/data-store-hydrator.ts
 import { isNullOrUndefined as isNullOrUndefined4 } from "@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 = isNullOrUndefined4(snapshot.tree) ? void 0 : this.fieldsFieldTreeHydrator.hydrate(snapshot.tree);
+    const variables = isNullOrUndefined4(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.
@@ -1269,29 +1433,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 = isNullOrUndefined4(snapshot.tree) ? void 0 : this.fieldTreeSerializer.hydrate(snapshot.tree);
-    const variables = isNullOrUndefined4(snapshot.variables) ? void 0 : this.fieldTreeSerializer.fieldsSerializer.hydrate(snapshot.variables);
-    return new DataStore(tree ? tree : this.fieldTreeSerializer.factory, variables);
-  }
 };
 
 // src/setup.ts
@@ -1314,11 +1463,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())
     )
   );
 }
@@ -1344,13 +1493,17 @@ export {
   CoreStringField,
   CoreTreeNodeFactory,
   DataStore,
-  DataStoreSerializer,
+  DataStoreHydrator,
+  DataStoreSnapshotter,
+  FieldHydrator,
   FieldRegistry,
-  FieldSerializer,
+  FieldSnapshotter,
   FieldTree,
-  FieldTreeSerializer,
+  FieldTreeHydrator,
+  FieldTreeSnapshotter,
   Fields,
-  FieldsSerializer,
+  FieldsHydrator,
+  FieldsSnapshotter,
   Policies,
   PolicySerializer,
   clampMaxPolicy,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axi-engine/fields",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "A compact, reactive state management library based on a tree of observable fields.",
   "license": "MIT",
   "repository": {
@@ -36,9 +36,9 @@
     "dequal": "^2.0.3"
   },
   "devDependencies": {
-    "@axi-engine/utils": "^0.2.6"
+    "@axi-engine/utils": "^0.2.9"
   },
   "peerDependencies": {
-    "@axi-engine/utils": "^0.2.6"
+    "@axi-engine/utils": "^0.2.9"
   }
 }