@axi-engine/fields 0.3.8 → 0.3.10

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,
@@ -52,9 +53,9 @@ __export(index_exports, {
   createCoreTreeNodeFactory: () => createCoreTreeNodeFactory,
   createCoreTreeSerializer: () => createCoreTreeSerializer,
   createTypedMethodsMixin: () => createTypedMethodsMixin,
+  isDataStore: () => isDataStore,
   isFieldTree: () => isFieldTree,
-  isFields: () => isFields,
-  isStore: () => isStore
+  isFields: () => isFields
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -378,6 +379,9 @@ var Fields = class _Fields {
   onRemove = new import_utils4.Emitter();
   /**
    * Gets the read-only map of all `Field` instances in this container.
+   *
+   * @internal
+   *
    * @returns {Map<string, Field<any>>} The collection of fields.
    */
   get fields() {
@@ -524,11 +528,28 @@ var FieldTree = class _FieldTree {
    */
   onRemove = new import_utils5.Emitter();
   /**
-   * Gets the collection of direct child nodes of this tree branch.
+   * Provides direct access to the internal node storage.
+   *
+   * @remarks
+   * This is primarily intended for **serialization**, debugging, or low-level iteration.
+   * Avoid modifying this map directly to maintain internal consistency; use {@link addNode} or {@link removeNode} instead.
+   * @internal
    */
   get nodes() {
     return this._nodes;
   }
+  /**
+   * Exposes the internal factory instance used by this tree.
+   *
+   * @remarks
+   * Direct usage of this getter is generally unnecessary.
+   * Prefer using {@link createDetachedTree} or {@link createDetachedFields} to create isolated instances.
+   *
+   * @returns {FieldTreeFactory} The factory instance.
+   */
+  get factory() {
+    return this._factory;
+  }
   /**
    * Creates an instance of FieldTree.
    * @param {FieldTreeFactory} factory - A factory responsible for creating new nodes within the tree.
@@ -700,6 +721,23 @@ var FieldTree = class _FieldTree {
     this.onAdd.clear();
     this.onRemove.clear();
   }
+  /**
+   * Creates a new, detached FieldTree instance using the same factory as this tree.
+   * This new tree has no parent and is completely isolated.
+   *
+   * @returns A new instance of the same tree type.
+   */
+  createDetachedTree() {
+    return this._factory.tree();
+  }
+  /**
+   * Creates a new, detached Fields container using the same factory.
+   *
+   * @returns
+   */
+  createDetachedFields() {
+    return this._factory.fields();
+  }
   /**
    * @private
    * Navigates the tree to the parent of a target node.
@@ -897,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
@@ -954,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.
@@ -982,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)) {
@@ -999,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");
@@ -1022,23 +1090,52 @@ 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 {
-  constructor(tree) {
-    this.tree = tree;
+var DataStore = class _DataStore {
+  static typeName = "dataStore";
+  typeName = _DataStore.typeName;
+  resolvers = [];
+  _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;
+    }
+    if (variables) {
+      this._variables = variables;
+    }
     this.registerResolver(new NumericFieldResolver());
     this.registerResolver(new BooleanFieldResolver());
     this.registerResolver(new StringFieldResolver());
   }
-  resolvers = [];
-  rootFieldsName = "__root_fields";
-  _rootFields;
-  get rootFields() {
-    if (!this._rootFields) {
-      this._rootFields = this.tree.getOrCreateFields(this.rootFieldsName);
-    }
-    return this._rootFields;
-  }
   registerResolver(resolver) {
     this.resolvers.unshift(resolver);
   }
@@ -1106,10 +1203,10 @@ var DataStore = class {
     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);
@@ -1128,10 +1225,10 @@ var DataStore = class {
     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);
@@ -1142,25 +1239,26 @@ var DataStore = class {
       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).
+   *
+   * The new instance retains the same capabilities (e.g., factory configuration)
+   * as the current one but is completely detached from the existing data hierarchy.
+   * This is useful for creating local scopes, stack frames, or temporary data contexts.
+   *
+   * @returns {DataStore} A new, isolated DataStore instance.
+   */
+  createIsolated() {
+    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);
   }
-  /** implementation of the DataStore from utils */
   get(path) {
     return this.getField(path).value;
   }
@@ -1176,19 +1274,86 @@ var DataStore = class {
   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 value != null && value.typeName === Fields.typeName;
-}
-function isFieldTree(value) {
-  return value != null && value.typeName === FieldTree.typeName;
-}
-function isStore(value) {
-  return !(0, import_utils11.isNullOrUndefined)(value) && typeof value.createFields === "function" && typeof value.createTree === "function";
-}
+// 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() {
@@ -1241,6 +1406,7 @@ function createCoreFieldSystem(config) {
   CoreStringField,
   CoreTreeNodeFactory,
   DataStore,
+  DataStoreSerializer,
   FieldRegistry,
   FieldSerializer,
   FieldTree,
@@ -1258,7 +1424,7 @@ function createCoreFieldSystem(config) {
   createCoreTreeNodeFactory,
   createCoreTreeSerializer,
   createTypedMethodsMixin,
+  isDataStore,
   isFieldTree,
-  isFields,
-  isStore
+  isFields
 });