@axi-engine/fields 0.3.8 → 0.3.10

package/dist/index.d.mts

@@ -75,35 +75,137 @@ declare class Policies<T> {
     apply(val: T): T;
 }
 
+/**
+ * Configuration options for creating a new Field instance.
+ * @template T The type of the value stored in the field.
+ */
 interface FieldOptions<T> {
+    /**
+     * An optional array of policies to apply to this field.
+     * Policies can enforce validation rules, transform values, or handle constraints.
+     */
     policies?: Policy<T>[];
 }
+/**
+ * Represents a reactive data holder for a specific value type.
+ *
+ * A Field wraps a raw value, providing features like change observation (`onChange`),
+ * policy enforcement (validation/transformation), and metadata management (`name`, `typeName`).
+ *
+ * @template T The type of the value stored in the field.
+ */
 interface Field<T> {
+    /**
+     * A unique string identifier for the field type (e.g., 'numeric', 'boolean').
+     * Used for serialization and type guards.
+     */
     readonly typeName: string;
+    /**
+     * The name or key of this field within its parent container.
+     */
     readonly name: string;
+    /**
+     * The current value of the field.
+     * Assigning a new value triggers policies and emits the `onChange` event
+     * if the value is different from the current one.
+     */
     value: T;
+    /**
+     * The collection of policies applied to this field.
+     */
     policies: Policies<T>;
+    /**
+     * Updates the field's value without triggering the `onChange` event.
+     * Useful for internal synchronization or restoring state where side effects are undesirable.
+     * @param val The new value to set.
+     */
     setValueSilently(val: T): void;
+    /**
+     * Performs an atomic-like update using a callback function.
+     * The callback receives the current value and should return the new value.
+     * @param updateFn A function that transforms the current value into a new one.
+     */
     batchUpdate(updateFn: (currentValue: T) => T): void;
+    /**
+     * An observable stream that emits an event whenever the value changes.
+     * The payload contains the new value and the old value.
+     */
     onChange: Subscribable<[newValue: T, oldValue: T]>;
+    /**
+     * Cleans up the field, removing all listeners and releasing resources.
+     * Should be called when the field is no longer needed.
+     */
     destroy(): void;
 }
+/**
+ * A specialized Field for handling numeric values.
+ * Provides capabilities for range clamping (min/max) and arithmetic operations.
+ */
 interface NumericField extends Field<number> {
+    /** The minimum allowed value for this field, or undefined if no lower bound exists. */
     readonly min: number | undefined;
+    /** The maximum allowed value for this field, or undefined if no upper bound exists. */
     readonly max: number | undefined;
+    /**
+     * Checks if the current value is equal to or less than the minimum limit.
+     */
     isMin(): boolean;
+    /**
+     * Checks if the current value is equal to or greater than the maximum limit.
+     */
     isMax(): boolean;
+    /**
+     * Increments the current value by the specified amount.
+     * @param val The amount to add.
+     */
     inc(val: number): void;
+    /**
+     * Decrements the current value by the specified amount.
+     * @param val The amount to subtract.
+     */
     dec(val: number): void;
 }
+/**
+ * A specialized Field for handling boolean values.
+ * Provides toggle functionality.
+ */
 interface BooleanField extends Field<boolean> {
+    /**
+     * Inverts the current boolean value (true -> false, false -> true).
+     * @returns {boolean} The new value after toggling.
+     */
     toggle(): boolean;
 }
+/**
+ * A specialized Field for handling string values.
+ * Provides chainable methods for common string manipulations.
+ */
 interface StringField extends Field<string> {
+    /**
+     * Appends a string or number to the end of the current value.
+     * @param str The value to append.
+     * @returns {this} The field instance for chaining.
+     */
     append(str: string | number): this;
+    /**
+     * Prepends a string or number to the beginning of the current value.
+     * @param str The value to prepend.
+     * @returns {this} The field instance for chaining.
+     */
     prepend(str: string | number): this;
+    /**
+     * Removes whitespace from both ends of the current string value.
+     * @returns {this} The field instance for chaining.
+     */
     trim(): this;
+    /**
+     * Checks if the current string is empty (length is 0).
+     * @returns {boolean} `true` if the string is empty, otherwise `false`.
+     */
     isEmpty(): boolean;
+    /**
+     * Sets the value to an empty string.
+     */
     clear(): void;
 }
 
@@ -144,6 +246,9 @@ declare class Fields {
     }]>;
     /**
      * Gets the read-only map of all `Field` instances in this container.
+     *
+     * @internal
+     *
      * @returns {Map<string, Field<any>>} The collection of fields.
      */
     get fields(): Map<string, Field<any>>;
@@ -379,9 +484,24 @@ declare class FieldTree<TFields extends Fields> {
         names: string[];
     }]>;
     /**
-     * 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(): Map<string, TreeNode<TFields>>;
+    /**
+     * 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(): FieldTreeFactory<TFields>;
     /**
      * Creates an instance of FieldTree.
      * @param {FieldTreeFactory} factory - A factory responsible for creating new nodes within the tree.
@@ -488,6 +608,19 @@ declare class FieldTree<TFields extends Fields> {
      * This method should be called when a node is no longer needed.
      */
     destroy(): void;
+    /**
+     * 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(): FieldTree<TFields>;
+    /**
+     * Creates a new, detached Fields container using the same factory.
+     *
+     * @returns
+     */
+    createDetachedFields(): TFields;
     /**
      * @private
      * Navigates the tree to the parent of a target node.
@@ -655,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;
@@ -686,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;
 }
 
 /**
@@ -766,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.
@@ -782,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;
@@ -792,6 +958,9 @@ 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.
      * @template T The expected type of the value.
@@ -912,6 +1081,16 @@ interface Store extends DataStorage {
      * @param path The path to the node to remove.
      */
     remove(path: PathType): void;
+    /**
+     * Creates a new, independent instance of the Store.
+     *
+     * The returned store must operate on a completely separate data structure,
+     * ensuring that operations on the new instance do not affect the current one (and vice versa).
+     * Typically used for creating local execution scopes, stack frames, or sandbox environments.
+     *
+     * @returns {Store} A new, isolated Store instance.
+     */
+    createIsolated(): Store;
 }
 
 interface DataStoreFieldResolver {
@@ -929,12 +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;
@@ -955,15 +1137,76 @@ 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).
+     *
+     * 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(): DataStore;
+    /** code below -> implementation of the DataStore from utils */
     has(path: PathType): boolean;
-    /** implementation of the DataStore from utils */
     get(path: PathType): unknown;
     set(path: PathType, value: unknown): void;
     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;
 }
 
 /**
@@ -983,18 +1226,15 @@ declare function isFields(value: unknown): value is Fields;
  */
 declare function isFieldTree(value: unknown): value is FieldTree<any>;
 /**
- * Type guard that checks if an unknown value conforms to the `Store` interface.
- *
- * It performs a structural check (duck typing) by verifying the presence of methods
- * that are unique to the `Store` interface and are not part of the simpler `DataSource`
- * or `DataStorage` contracts, such as `createFields` and `createTree`.
+ * Type guard that checks if a value is an instance of the `DataStore` class.
+ * It verifies this by checking the static `typeName` property on the instance.
  *
  * @param value The `unknown` value to check.
- * @returns {boolean} `true` if the value is a `Store`-like object, `false` otherwise.
+ * @returns {boolean} `true` if the value is a `DataStore` instance, otherwise `false`.
  *
  * @example
- * function processData(source: DataSource) {
- *   if (isStore(source)) {
+ * function processData(source: DataStore) {
+ *   if (isDataStore(source)) {
  *     // Inside this block, TypeScript now knows `source` is a full `Store`.
  *     // We can safely call Store-specific methods like `createFields`.
  *     source.createFields('new.data.group');
@@ -1004,7 +1244,7 @@ declare function isFieldTree(value: unknown): value is FieldTree<any>;
  *   }
  * }
  */
-declare function isStore(value: unknown): value is Store;
+declare function isDataStore(value: unknown): value is DataStore;
 
 /**
  * Creates and configures a FieldRegistry with all the core field types.
@@ -1043,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, isFieldTree, isFields, isStore };
+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 };