@axi-engine/fields 0.3.7 → 0.3.9

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as _axi_engine_utils from '@axi-engine/utils';
-import { Subscribable, ConstructorRegistry, Emitter, Constructor, PathType, DataStorage } from '@axi-engine/utils';
+import { Subscribable, Registry, Constructor, Emitter, PathType, DataStorage } from '@axi-engine/utils';
 
 interface Policy<T> {
     readonly id: string;
@@ -75,39 +75,141 @@ 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;
 }
 
-declare class FieldRegistry extends ConstructorRegistry<Field<any>> {
+declare class FieldRegistry extends Registry<string, Constructor<Field<any>>> {
 }
 
 /**
@@ -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.
@@ -583,9 +716,8 @@ interface PolicySerializerHandler<T extends Policy<any>, S extends object> {
     hydrate(snapshotData: S): T;
 }
 declare class PolicySerializer {
-    private readonly handlers;
-    register(policyId: string, handler: PolicySerializerHandler<any, any>): this;
-    clearHandlers(): void;
+    handlers: Registry<string, PolicySerializerHandler<any, any>>;
+    register(policyId: string, handler: PolicySerializerHandler<any, any>): void;
     /**
      * Creates a serializable snapshot of a policy instance.
      * The snapshot includes the policy's state and a `__type` identifier.
@@ -648,6 +780,7 @@ interface FieldSnapshot {
     value: any;
     policies?: object[];
 }
+
 /**
  * Orchestrates the serialization and deserialization of Field instances.
  *
@@ -695,6 +828,7 @@ interface FieldsSnapshot {
     __type: string;
     [fieldName: string]: FieldSnapshot | string;
 }
+
 /**
  * Orchestrates the serialization and deserialization of `Fields` container instances.
  *
@@ -747,6 +881,7 @@ interface FieldTreeSnapshot {
     __type: string;
     [fieldName: string]: FieldsSnapshot | FieldTreeSnapshot | string;
 }
+
 /**
  * Orchestrates the recursive serialization and deserialization of `FieldTree` instances.
  *
@@ -790,6 +925,7 @@ 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.
@@ -910,6 +1046,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 {
@@ -928,6 +1074,8 @@ 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;
@@ -955,8 +1103,18 @@ declare class DataStore implements Store {
     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;
@@ -981,18 +1139,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');
@@ -1002,7 +1157,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.
@@ -1041,4 +1196,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, 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

@@ -1,5 +1,5 @@
 import * as _axi_engine_utils from '@axi-engine/utils';
-import { Subscribable, ConstructorRegistry, Emitter, Constructor, PathType, DataStorage } from '@axi-engine/utils';
+import { Subscribable, Registry, Constructor, Emitter, PathType, DataStorage } from '@axi-engine/utils';
 
 interface Policy<T> {
     readonly id: string;
@@ -75,39 +75,141 @@ 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;
 }
 
-declare class FieldRegistry extends ConstructorRegistry<Field<any>> {
+declare class FieldRegistry extends Registry<string, Constructor<Field<any>>> {
 }
 
 /**
@@ -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.
@@ -583,9 +716,8 @@ interface PolicySerializerHandler<T extends Policy<any>, S extends object> {
     hydrate(snapshotData: S): T;
 }
 declare class PolicySerializer {
-    private readonly handlers;
-    register(policyId: string, handler: PolicySerializerHandler<any, any>): this;
-    clearHandlers(): void;
+    handlers: Registry<string, PolicySerializerHandler<any, any>>;
+    register(policyId: string, handler: PolicySerializerHandler<any, any>): void;
     /**
      * Creates a serializable snapshot of a policy instance.
      * The snapshot includes the policy's state and a `__type` identifier.
@@ -648,6 +780,7 @@ interface FieldSnapshot {
     value: any;
     policies?: object[];
 }
+
 /**
  * Orchestrates the serialization and deserialization of Field instances.
  *
@@ -695,6 +828,7 @@ interface FieldsSnapshot {
     __type: string;
     [fieldName: string]: FieldSnapshot | string;
 }
+
 /**
  * Orchestrates the serialization and deserialization of `Fields` container instances.
  *
@@ -747,6 +881,7 @@ interface FieldTreeSnapshot {
     __type: string;
     [fieldName: string]: FieldsSnapshot | FieldTreeSnapshot | string;
 }
+
 /**
  * Orchestrates the recursive serialization and deserialization of `FieldTree` instances.
  *
@@ -790,6 +925,7 @@ 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.
@@ -910,6 +1046,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 {
@@ -928,6 +1074,8 @@ 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;
@@ -955,8 +1103,18 @@ declare class DataStore implements Store {
     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;
@@ -981,18 +1139,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');
@@ -1002,7 +1157,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.
@@ -1041,4 +1196,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, 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

@@ -52,9 +52,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);
 
@@ -351,7 +351,7 @@ var CoreNumericField = class _CoreNumericField extends CoreField {
 
 // src/field-registry.ts
 var import_utils3 = require("@axi-engine/utils");
-var FieldRegistry = class extends import_utils3.ConstructorRegistry {
+var FieldRegistry = class extends import_utils3.Registry {
 };
 
 // src/fields.ts
@@ -378,6 +378,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() {
@@ -425,7 +428,7 @@ var Fields = class _Fields {
    * @returns {T} The newly created `Field` instance.
    */
   create(typeName, name, initialValue, options) {
-    const Ctor = this._fieldRegistry.get(typeName);
+    const Ctor = this._fieldRegistry.getOrThrow(typeName);
     const field = new Ctor(name, initialValue, options);
     this.add(field);
     return field;
@@ -524,11 +527,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 +720,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.
@@ -820,14 +857,9 @@ var ClampMinPolicySerializerHandler = class {
 // src/serializer/policy-serializer.ts
 var import_utils6 = require("@axi-engine/utils");
 var PolicySerializer = class {
-  handlers = /* @__PURE__ */ new Map();
+  handlers = new import_utils6.Registry();
   register(policyId, handler) {
-    (0, import_utils6.throwIf)(this.handlers.has(policyId), `A handler for policy ID '${policyId}' is already registered.`);
-    this.handlers.set(policyId, handler);
-    return this;
-  }
-  clearHandlers() {
-    this.handlers.clear();
+    this.handlers.register(policyId, handler);
   }
   /**
    * Creates a serializable snapshot of a policy instance.
@@ -837,8 +869,7 @@ var PolicySerializer = class {
    * @throws If no handler is registered for the policy's ID.
    */
   snapshot(policy) {
-    const handler = this.handlers.get(policy.id);
-    (0, import_utils6.throwIfEmpty)(handler, `No serializer handler registered for policy ID: '${policy.id}'`);
+    const handler = this.handlers.getOrThrow(policy.id);
     const data = handler.snapshot(policy);
     return {
       __type: policy.id,
@@ -854,8 +885,7 @@ var PolicySerializer = class {
   hydrate(snapshot) {
     const typeId = snapshot?.__type;
     (0, import_utils6.throwIfEmpty)(typeId, 'Invalid policy snapshot: missing "__type" identifier.');
-    const handler = this.handlers.get(typeId);
-    (0, import_utils6.throwIfEmpty)(handler, `No serializer handler registered for policy ID: '${typeId}'`);
+    const handler = this.handlers.getOrThrow(typeId);
     const { __type, ...data } = snapshot;
     return handler.hydrate(data);
   }
@@ -903,7 +933,7 @@ var FieldSerializer = class {
   hydrate(snapshot) {
     const fieldType = snapshot.__type;
     (0, import_utils7.throwIfEmpty)(fieldType, 'Invalid field snapshot: missing "__type" identifier.');
-    const Ctor = this.fieldRegistry.get(fieldType);
+    const Ctor = this.fieldRegistry.getOrThrow(fieldType);
     let policies;
     if (!(0, import_utils7.isNullOrUndefined)(snapshot.policies)) {
       policies = [];
@@ -1030,13 +1060,15 @@ var StringFieldResolver = class {
 };
 
 // src/data-store.ts
-var DataStore = class {
+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;
@@ -1160,6 +1192,19 @@ var DataStore = class {
     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.tree.createDetachedTree());
+  }
+  /** code below -> implementation of the DataStore from utils */
   has(path) {
     const pathArr = (0, import_utils10.ensurePathArray)(path);
     if (this.isPathToRootFields(pathArr)) {
@@ -1167,7 +1212,6 @@ var DataStore = class {
     }
     return this.tree.hasPath(pathArr);
   }
-  /** implementation of the DataStore from utils */
   get(path) {
     return this.getField(path).value;
   }
@@ -1188,13 +1232,13 @@ var DataStore = class {
 // src/guards.ts
 var import_utils11 = require("@axi-engine/utils");
 function isFields(value) {
-  return value != null && value.typeName === Fields.typeName;
+  return !(0, import_utils11.isNullOrUndefined)(value) && value.typeName === Fields.typeName;
 }
 function isFieldTree(value) {
-  return value != null && value.typeName === FieldTree.typeName;
+  return !(0, import_utils11.isNullOrUndefined)(value) && value.typeName === FieldTree.typeName;
 }
-function isStore(value) {
-  return !(0, import_utils11.isNullOrUndefined)(value) && typeof value.createFields === "function" && typeof value.createTree === "function";
+function isDataStore(value) {
+  return !(0, import_utils11.isNullOrUndefined)(value) && value.typeName === DataStore.typeName;
 }
 
 // src/setup.ts
@@ -1265,7 +1309,7 @@ function createCoreFieldSystem(config) {
   createCoreTreeNodeFactory,
   createCoreTreeSerializer,
   createTypedMethodsMixin,
+  isDataStore,
   isFieldTree,
-  isFields,
-  isStore
+  isFields
 });

package/dist/index.mjs

@@ -290,8 +290,8 @@ var CoreNumericField = class _CoreNumericField extends CoreField {
 };
 
 // src/field-registry.ts
-import { ConstructorRegistry } from "@axi-engine/utils";
-var FieldRegistry = class extends ConstructorRegistry {
+import { Registry } from "@axi-engine/utils";
+var FieldRegistry = class extends Registry {
 };
 
 // src/fields.ts
@@ -318,6 +318,9 @@ var Fields = class _Fields {
   onRemove = new Emitter2();
   /**
    * Gets the read-only map of all `Field` instances in this container.
+   *
+   * @internal
+   *
    * @returns {Map<string, Field<any>>} The collection of fields.
    */
   get fields() {
@@ -365,7 +368,7 @@ var Fields = class _Fields {
    * @returns {T} The newly created `Field` instance.
    */
   create(typeName, name, initialValue, options) {
-    const Ctor = this._fieldRegistry.get(typeName);
+    const Ctor = this._fieldRegistry.getOrThrow(typeName);
     const field = new Ctor(name, initialValue, options);
     this.add(field);
     return field;
@@ -464,11 +467,28 @@ var FieldTree = class _FieldTree {
    */
   onRemove = new Emitter3();
   /**
-   * 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.
@@ -640,6 +660,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.
@@ -758,16 +795,11 @@ var ClampMinPolicySerializerHandler = class {
 };
 
 // src/serializer/policy-serializer.ts
-import { throwIf as throwIf3, throwIfEmpty as throwIfEmpty2 } from "@axi-engine/utils";
+import { Registry as Registry2, throwIfEmpty as throwIfEmpty2 } from "@axi-engine/utils";
 var PolicySerializer = class {
-  handlers = /* @__PURE__ */ new Map();
+  handlers = new Registry2();
   register(policyId, handler) {
-    throwIf3(this.handlers.has(policyId), `A handler for policy ID '${policyId}' is already registered.`);
-    this.handlers.set(policyId, handler);
-    return this;
-  }
-  clearHandlers() {
-    this.handlers.clear();
+    this.handlers.register(policyId, handler);
   }
   /**
    * Creates a serializable snapshot of a policy instance.
@@ -777,8 +809,7 @@ var PolicySerializer = class {
    * @throws If no handler is registered for the policy's ID.
    */
   snapshot(policy) {
-    const handler = this.handlers.get(policy.id);
-    throwIfEmpty2(handler, `No serializer handler registered for policy ID: '${policy.id}'`);
+    const handler = this.handlers.getOrThrow(policy.id);
     const data = handler.snapshot(policy);
     return {
       __type: policy.id,
@@ -794,8 +825,7 @@ var PolicySerializer = class {
   hydrate(snapshot) {
     const typeId = snapshot?.__type;
     throwIfEmpty2(typeId, 'Invalid policy snapshot: missing "__type" identifier.');
-    const handler = this.handlers.get(typeId);
-    throwIfEmpty2(handler, `No serializer handler registered for policy ID: '${typeId}'`);
+    const handler = this.handlers.getOrThrow(typeId);
     const { __type, ...data } = snapshot;
     return handler.hydrate(data);
   }
@@ -843,7 +873,7 @@ var FieldSerializer = class {
   hydrate(snapshot) {
     const fieldType = snapshot.__type;
     throwIfEmpty3(fieldType, 'Invalid field snapshot: missing "__type" identifier.');
-    const Ctor = this.fieldRegistry.get(fieldType);
+    const Ctor = this.fieldRegistry.getOrThrow(fieldType);
     let policies;
     if (!isNullOrUndefined2(snapshot.policies)) {
       policies = [];
@@ -970,13 +1000,15 @@ var StringFieldResolver = class {
 };
 
 // src/data-store.ts
-var DataStore = class {
+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;
@@ -1100,6 +1132,19 @@ var DataStore = class {
     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.tree.createDetachedTree());
+  }
+  /** code below -> implementation of the DataStore from utils */
   has(path) {
     const pathArr = ensurePathArray2(path);
     if (this.isPathToRootFields(pathArr)) {
@@ -1107,7 +1152,6 @@ var DataStore = class {
     }
     return this.tree.hasPath(pathArr);
   }
-  /** implementation of the DataStore from utils */
   get(path) {
     return this.getField(path).value;
   }
@@ -1128,13 +1172,13 @@ var DataStore = class {
 // src/guards.ts
 import { isNullOrUndefined as isNullOrUndefined3 } from "@axi-engine/utils";
 function isFields(value) {
-  return value != null && value.typeName === Fields.typeName;
+  return !isNullOrUndefined3(value) && value.typeName === Fields.typeName;
 }
 function isFieldTree(value) {
-  return value != null && value.typeName === FieldTree.typeName;
+  return !isNullOrUndefined3(value) && value.typeName === FieldTree.typeName;
 }
-function isStore(value) {
-  return !isNullOrUndefined3(value) && typeof value.createFields === "function" && typeof value.createTree === "function";
+function isDataStore(value) {
+  return !isNullOrUndefined3(value) && value.typeName === DataStore.typeName;
 }
 
 // src/setup.ts
@@ -1204,7 +1248,7 @@ export {
   createCoreTreeNodeFactory,
   createCoreTreeSerializer,
   createTypedMethodsMixin,
+  isDataStore,
   isFieldTree,
-  isFields,
-  isStore
+  isFields
 };

package/package.json

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