@axi-engine/fields 0.3.9 → 0.3.11

package/dist/index.d.ts

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