@axi-engine/fields 0.3.9 → 0.3.10

package/dist/index.d.mts

@@ -788,11 +788,6 @@ interface FieldSnapshot {
  * plain, storable data (snapshots) and vice-versa. It uses a `FieldRegistry`
  * to resolve class constructors and a `PolicySerializer` to handle the state
  * of any attached policies.
- *
- * @todo Implement a `patch(field, snapshot)` method.
- *       Unlike `hydrate`, which creates a new
- *       instance, `patch` should update the state of an *existing* field instance
- *       without breaking external references to it.
  */
 declare class FieldSerializer {
     private readonly fieldRegistry;
@@ -819,6 +814,18 @@ declare class FieldSerializer {
      * @throws If the snapshot is invalid, missing a `__type`, or if the type is not registered.
      */
     hydrate(snapshot: FieldSnapshot): Field<any>;
+    /**
+     * 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: Field<any>, snapshot: FieldSnapshot): void;
+    private hydratePolicies;
 }
 
 /**
@@ -899,8 +906,10 @@ interface FieldTreeSnapshot {
  *       patching nodes in place to maintain object references.
  */
 declare class FieldTreeSerializer<TFields extends Fields> {
-    private readonly fieldTreeNodeFactory;
-    private readonly fieldsSerializer;
+    _factory: FieldTreeFactory<TFields>;
+    _fieldsSerializer: FieldsSerializer<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.
@@ -915,6 +924,30 @@ declare class FieldTreeSerializer<TFields extends Fields> {
     hydrate(snapshot: FieldTreeSnapshot): FieldTree<TFields>;
 }
 
+/**
+ * A plain object representation of a DataStore's state, used for serialization.
+ *
+ * It captures both the detached 'flat' variables (used for stack frames/local scopes)
+ * and the hierarchical 'tree' structure (used for global/persistent data).
+ */
+interface DataStoreSnapshot {
+    /**
+     * The type identifier for the store (e.g., 'dataStore').
+     * Used for type guards and polymorphic deserialization.
+     */
+    __type: string;
+    /**
+     * Snapshot of the independent, root-level variables (CoreFields).
+     * Present only if the store contained detached variables.
+     */
+    variables?: FieldsSnapshot;
+    /**
+     * Snapshot of the nested data hierarchy (CoreFieldTree).
+     * Present only if the store managed a complex tree structure.
+     */
+    tree?: FieldTreeSnapshot;
+}
+
 interface StoreCreateFieldOptions {
     /** Allows to explicitly specify the field type, overriding the automatic type detection. */
     fieldType?: string;
@@ -925,6 +958,8 @@ interface StoreCreateFieldOptions {
  * both type-safe and dynamic methods for manipulating data.
  */
 interface Store extends DataStorage {
+    /**
+     */
     readonly typeName: string;
     /**
      * Retrieves the raw value of a Field at a specific path.
@@ -1073,14 +1108,15 @@ interface DataStoreFieldResolver {
 }
 
 declare class DataStore implements Store {
-    private readonly tree;
     static readonly typeName = "dataStore";
     readonly typeName = "dataStore";
     private readonly resolvers;
-    private readonly rootFieldsName;
-    private _rootFields;
-    private get rootFields();
-    constructor(tree: CoreFieldTree);
+    private _variables;
+    private _tree;
+    private readonly _factory;
+    private get variables();
+    private get tree();
+    constructor(treeOrFactory: CoreFieldTree | FieldTreeFactory<CoreFields>, variables?: CoreFields);
     registerResolver(resolver: DataStoreFieldResolver): void;
     clearResolvers(): void;
     getValue<T>(path: PathType): T;
@@ -1101,8 +1137,6 @@ declare class DataStore implements Store {
     getFields(path: PathType): CoreFields;
     getTree(path: PathType): CoreFieldTree;
     remove(path: PathType): void;
-    private isPathToRootFields;
-    private getDestinationFields;
     /**
      * Creates a new, independent instance of the Store with a fresh, empty data state (FieldsTree).
      *
@@ -1120,6 +1154,59 @@ declare class DataStore implements Store {
     create(path: PathType, value: unknown): void;
     upset(path: PathType, value: unknown): void;
     delete(path: PathType): void;
+    /**
+     * @internal Used for serialization
+     */
+    getInternalVariables(): CoreFields | undefined;
+    /**
+     * @internal Used for serialization
+     */
+    getInternalTree(): CoreFieldTree | undefined;
+    /**
+     * @private
+    */
+    private isPathToVariables;
+    /**
+     * @private
+     */
+    private getDestinationFields;
+}
+
+/**
+ * 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;
+    /**
+     * Creates an instance of DataStoreSerializer.
+     * @param {FieldTreeSerializer} fieldTreeSerializer - 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;
+    /**
+     * 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: DataStoreSnapshot): DataStore;
 }
 
 /**
@@ -1196,4 +1283,4 @@ declare function createCoreFieldSystem(config?: CoreFieldSystemConfig): {
     serializer: FieldTreeSerializer<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, 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, 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 };

package/dist/index.d.ts

@@ -788,11 +788,6 @@ interface FieldSnapshot {
  * plain, storable data (snapshots) and vice-versa. It uses a `FieldRegistry`
  * to resolve class constructors and a `PolicySerializer` to handle the state
  * of any attached policies.
- *
- * @todo Implement a `patch(field, snapshot)` method.
- *       Unlike `hydrate`, which creates a new
- *       instance, `patch` should update the state of an *existing* field instance
- *       without breaking external references to it.
  */
 declare class FieldSerializer {
     private readonly fieldRegistry;
@@ -819,6 +814,18 @@ declare class FieldSerializer {
      * @throws If the snapshot is invalid, missing a `__type`, or if the type is not registered.
      */
     hydrate(snapshot: FieldSnapshot): Field<any>;
+    /**
+     * 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: Field<any>, snapshot: FieldSnapshot): void;
+    private hydratePolicies;
 }
 
 /**
@@ -899,8 +906,10 @@ interface FieldTreeSnapshot {
  *       patching nodes in place to maintain object references.
  */
 declare class FieldTreeSerializer<TFields extends Fields> {
-    private readonly fieldTreeNodeFactory;
-    private readonly fieldsSerializer;
+    _factory: FieldTreeFactory<TFields>;
+    _fieldsSerializer: FieldsSerializer<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.
@@ -915,6 +924,30 @@ declare class FieldTreeSerializer<TFields extends Fields> {
     hydrate(snapshot: FieldTreeSnapshot): FieldTree<TFields>;
 }
 
+/**
+ * A plain object representation of a DataStore's state, used for serialization.
+ *
+ * It captures both the detached 'flat' variables (used for stack frames/local scopes)
+ * and the hierarchical 'tree' structure (used for global/persistent data).
+ */
+interface DataStoreSnapshot {
+    /**
+     * The type identifier for the store (e.g., 'dataStore').
+     * Used for type guards and polymorphic deserialization.
+     */
+    __type: string;
+    /**
+     * Snapshot of the independent, root-level variables (CoreFields).
+     * Present only if the store contained detached variables.
+     */
+    variables?: FieldsSnapshot;
+    /**
+     * Snapshot of the nested data hierarchy (CoreFieldTree).
+     * Present only if the store managed a complex tree structure.
+     */
+    tree?: FieldTreeSnapshot;
+}
+
 interface StoreCreateFieldOptions {
     /** Allows to explicitly specify the field type, overriding the automatic type detection. */
     fieldType?: string;
@@ -925,6 +958,8 @@ interface StoreCreateFieldOptions {
  * both type-safe and dynamic methods for manipulating data.
  */
 interface Store extends DataStorage {
+    /**
+     */
     readonly typeName: string;
     /**
      * Retrieves the raw value of a Field at a specific path.
@@ -1073,14 +1108,15 @@ interface DataStoreFieldResolver {
 }
 
 declare class DataStore implements Store {
-    private readonly tree;
     static readonly typeName = "dataStore";
     readonly typeName = "dataStore";
     private readonly resolvers;
-    private readonly rootFieldsName;
-    private _rootFields;
-    private get rootFields();
-    constructor(tree: CoreFieldTree);
+    private _variables;
+    private _tree;
+    private readonly _factory;
+    private get variables();
+    private get tree();
+    constructor(treeOrFactory: CoreFieldTree | FieldTreeFactory<CoreFields>, variables?: CoreFields);
     registerResolver(resolver: DataStoreFieldResolver): void;
     clearResolvers(): void;
     getValue<T>(path: PathType): T;
@@ -1101,8 +1137,6 @@ declare class DataStore implements Store {
     getFields(path: PathType): CoreFields;
     getTree(path: PathType): CoreFieldTree;
     remove(path: PathType): void;
-    private isPathToRootFields;
-    private getDestinationFields;
     /**
      * Creates a new, independent instance of the Store with a fresh, empty data state (FieldsTree).
      *
@@ -1120,6 +1154,59 @@ declare class DataStore implements Store {
     create(path: PathType, value: unknown): void;
     upset(path: PathType, value: unknown): void;
     delete(path: PathType): void;
+    /**
+     * @internal Used for serialization
+     */
+    getInternalVariables(): CoreFields | undefined;
+    /**
+     * @internal Used for serialization
+     */
+    getInternalTree(): CoreFieldTree | undefined;
+    /**
+     * @private
+    */
+    private isPathToVariables;
+    /**
+     * @private
+     */
+    private getDestinationFields;
+}
+
+/**
+ * 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;
+    /**
+     * Creates an instance of DataStoreSerializer.
+     * @param {FieldTreeSerializer} fieldTreeSerializer - 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;
+    /**
+     * 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: DataStoreSnapshot): DataStore;
 }
 
 /**
@@ -1196,4 +1283,4 @@ declare function createCoreFieldSystem(config?: CoreFieldSystemConfig): {
     serializer: FieldTreeSerializer<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, 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, 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 };

package/dist/index.js

@@ -35,6 +35,7 @@ __export(index_exports, {
   CoreStringField: () => CoreStringField,
   CoreTreeNodeFactory: () => CoreTreeNodeFactory,
   DataStore: () => DataStore,
+  DataStoreSerializer: () => DataStoreSerializer,
   FieldRegistry: () => FieldRegistry,
   FieldSerializer: () => FieldSerializer,
   FieldTree: () => FieldTree,
@@ -934,13 +935,35 @@ var FieldSerializer = class {
     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)));
-    }
+    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) {
+    let policies = this.hydratePolicies(snapshot);
+    field.policies.clear();
+    if (policies) {
+      policies.forEach((p) => field.policies.add(p));
+    }
+    field.value = snapshot.value;
+  }
+  hydratePolicies(snapshot) {
+    if ((0, import_utils7.isNullOrUndefined)(snapshot.policies)) {
+      return void 0;
+    }
+    const policies = [];
+    snapshot.policies.forEach((p) => policies.push(this.policySerializer.hydrate(p)));
+    return policies;
+  }
 };
 
 // src/serializer/fields-serializer.ts
@@ -991,9 +1014,17 @@ var FieldsSerializer = class {
 // src/serializer/field-tree-serializer.ts
 var import_utils8 = require("@axi-engine/utils");
 var FieldTreeSerializer = class {
+  _factory;
+  _fieldsSerializer;
+  get factory() {
+    return this._factory;
+  }
+  get fieldsSerializer() {
+    return this._fieldsSerializer;
+  }
   constructor(fieldTreeNodeFactory, fieldsSerializer) {
-    this.fieldTreeNodeFactory = fieldTreeNodeFactory;
-    this.fieldsSerializer = fieldsSerializer;
+    this._factory = fieldTreeNodeFactory;
+    this._fieldsSerializer = fieldsSerializer;
   }
   /**
    * Creates a serializable snapshot of the entire tree and its contained fields.
@@ -1019,7 +1050,7 @@ 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)) {
@@ -1036,7 +1067,7 @@ var FieldTreeSerializer = class {
 };
 
 // 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 +1090,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._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;
     }
-    return this._rootFields;
+    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 +1203,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 +1225,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 +1239,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 +1249,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 +1274,86 @@ 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;
+  }
+  /**
+   * @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/serializer/data-store-serializer.ts
+var import_utils12 = require("@axi-engine/utils");
+var DataStoreSerializer = class {
+  /**
+   * Creates an instance of DataStoreSerializer.
+   * @param {FieldTreeSerializer} fieldTreeSerializer - The serializer used for the underlying tree and fields.
+   */
+  constructor(fieldTreeSerializer) {
+    this.fieldTreeSerializer = fieldTreeSerializer;
+  }
+  /**
+   * 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.fieldTreeSerializer.fieldsSerializer.snapshot(variables);
+    }
+    const tree = store.getInternalTree();
+    if (tree) {
+      snapshot.tree = this.fieldTreeSerializer.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
 function createCoreFieldRegistry() {
@@ -1292,6 +1406,7 @@ function createCoreFieldSystem(config) {
   CoreStringField,
   CoreTreeNodeFactory,
   DataStore,
+  DataStoreSerializer,
   FieldRegistry,
   FieldSerializer,
   FieldTree,

package/dist/index.mjs

@@ -874,13 +874,35 @@ var FieldSerializer = class {
     const fieldType = snapshot.__type;
     throwIfEmpty3(fieldType, 'Invalid field snapshot: missing "__type" identifier.');
     const Ctor = this.fieldRegistry.getOrThrow(fieldType);
-    let policies;
-    if (!isNullOrUndefined2(snapshot.policies)) {
-      policies = [];
-      snapshot.policies.forEach((p) => policies.push(this.policySerializer.hydrate(p)));
-    }
+    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) {
+    let policies = this.hydratePolicies(snapshot);
+    field.policies.clear();
+    if (policies) {
+      policies.forEach((p) => field.policies.add(p));
+    }
+    field.value = snapshot.value;
+  }
+  hydratePolicies(snapshot) {
+    if (isNullOrUndefined2(snapshot.policies)) {
+      return void 0;
+    }
+    const policies = [];
+    snapshot.policies.forEach((p) => policies.push(this.policySerializer.hydrate(p)));
+    return policies;
+  }
 };
 
 // src/serializer/fields-serializer.ts
@@ -931,9 +953,17 @@ var FieldsSerializer = class {
 // 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.fieldTreeNodeFactory = fieldTreeNodeFactory;
-    this.fieldsSerializer = fieldsSerializer;
+    this._factory = fieldTreeNodeFactory;
+    this._fieldsSerializer = fieldsSerializer;
   }
   /**
    * Creates a serializable snapshot of the entire tree and its contained fields.
@@ -959,7 +989,7 @@ 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 (isString(nodeData)) {
@@ -999,24 +1029,51 @@ var StringFieldResolver = class {
   }
 };
 
+// src/guards.ts
+import { isNullOrUndefined as isNullOrUndefined3 } from "@axi-engine/utils";
+function isFields(value) {
+  return !isNullOrUndefined3(value) && value.typeName === Fields.typeName;
+}
+function isFieldTree(value) {
+  return !isNullOrUndefined3(value) && value.typeName === FieldTree.typeName;
+}
+function isDataStore(value) {
+  return !isNullOrUndefined3(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._variables;
+  }
+  get tree() {
+    if (!this._tree) {
+      this._tree = this._factory.tree();
     }
-    return this._rootFields;
+    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);
@@ -1087,8 +1144,8 @@ var DataStore = class _DataStore {
   getField(path) {
     const pathArr = ensurePathArray2(path);
     throwIfEmpty4(pathArr, `Wrong path or path is empty: ${ensurePathString2(path)}, should contain at least one path segment`);
-    if (this.isPathToRootFields(pathArr)) {
-      return this.rootFields.get(pathArr[0]);
+    if (this.isPathToVariables(pathArr)) {
+      return this.variables.get(pathArr[0]);
     }
     const fieldName = pathArr.pop();
     const fields = this.tree.getFields(pathArr);
@@ -1109,8 +1166,8 @@ var DataStore = class _DataStore {
   remove(path) {
     const pathArr = ensurePathArray2(path);
     throwIfEmpty4(pathArr, `Wrong path or path is empty: ${ensurePathString2(path)}, should contain at least one path segment`);
-    if (this.isPathToRootFields(pathArr)) {
-      this.rootFields.remove(pathArr);
+    if (this.isPathToVariables(pathArr)) {
+      this.variables.remove(pathArr);
       return;
     }
     const node = this.tree.findParentNode(pathArr);
@@ -1121,17 +1178,6 @@ var DataStore = class _DataStore {
       node.removeNode(leafName);
     }
   }
-  isPathToRootFields(path) {
-    return ensurePathArray2(path).length === 1;
-  }
-  getDestinationFields(path) {
-    const pathArr = ensurePathArray2(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).
    *
@@ -1142,13 +1188,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 = ensurePathArray2(path);
-    if (this.isPathToRootFields(pathArr)) {
-      return this.rootFields.has(pathArr[0]);
+    if (this.isPathToVariables(pathArr)) {
+      return this.variables.has(pathArr[0]);
     }
     return this.tree.hasPath(pathArr);
   }
@@ -1167,19 +1213,86 @@ 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;
+  }
+  /**
+   * @private
+  */
+  isPathToVariables(path) {
+    return ensurePathArray2(path).length === 1;
+  }
+  /**
+   * @private
+   */
+  getDestinationFields(path) {
+    const pathArr = ensurePathArray2(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
-import { isNullOrUndefined as isNullOrUndefined3 } from "@axi-engine/utils";
-function isFields(value) {
-  return !isNullOrUndefined3(value) && value.typeName === Fields.typeName;
-}
-function isFieldTree(value) {
-  return !isNullOrUndefined3(value) && value.typeName === FieldTree.typeName;
-}
-function isDataStore(value) {
-  return !isNullOrUndefined3(value) && value.typeName === DataStore.typeName;
-}
+// src/serializer/data-store-serializer.ts
+import { isNullOrUndefined as isNullOrUndefined4 } from "@axi-engine/utils";
+var DataStoreSerializer = class {
+  /**
+   * Creates an instance of DataStoreSerializer.
+   * @param {FieldTreeSerializer} fieldTreeSerializer - The serializer used for the underlying tree and fields.
+   */
+  constructor(fieldTreeSerializer) {
+    this.fieldTreeSerializer = fieldTreeSerializer;
+  }
+  /**
+   * 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.fieldTreeSerializer.fieldsSerializer.snapshot(variables);
+    }
+    const tree = store.getInternalTree();
+    if (tree) {
+      snapshot.tree = this.fieldTreeSerializer.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
 function createCoreFieldRegistry() {
@@ -1231,6 +1344,7 @@ export {
   CoreStringField,
   CoreTreeNodeFactory,
   DataStore,
+  DataStoreSerializer,
   FieldRegistry,
   FieldSerializer,
   FieldTree,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axi-engine/fields",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "A compact, reactive state management library based on a tree of observable fields.",
   "license": "MIT",
   "repository": {