@axi-engine/fields 0.1.5 → 0.2.0

package/dist/index.d.ts

@@ -1,18 +1,13 @@
-import { ReadonlySignal, Signal } from '@preact/signals-core';
-import { AxiEventEmitter } from '@axi-engine/events';
-import { PathType } from '@axi-engine/utils';
+import * as _axi_engine_utils from '@axi-engine/utils';
+import { Subscribable, Constructor, Emitter, PathType } from '@axi-engine/utils';
 
-declare const enum FieldsNodeType {
-    fieldTree = "FieldTree",
-    fields = "Fields"
-}
-
-interface FieldPolicy<T> {
+interface Policy<T> {
     readonly id: string;
     apply: (val: T) => T;
     destroy?: () => void;
 }
-declare class ClampPolicy implements FieldPolicy<number> {
+
+declare class ClampPolicy implements Policy<number> {
     min: number;
     max: number;
     static readonly id = "clamp";
@@ -21,15 +16,9 @@ declare class ClampPolicy implements FieldPolicy<number> {
     apply(val: number): number;
     updateBounds(min: number, max: number): void;
 }
-declare class ClampMinPolicy implements FieldPolicy<number> {
-    min: number;
-    static readonly id = "clampMin";
-    readonly id = "clampMin";
-    constructor(min: number);
-    apply(val: number): number;
-    updateBounds(min: number): void;
-}
-declare class ClampMaxPolicy implements FieldPolicy<number> {
+declare function clampPolicy(min: number, max: number): ClampPolicy;
+
+declare class ClampMaxPolicy implements Policy<number> {
     max: number;
     static readonly id = "clampMax";
     readonly id = "clampMax";
@@ -37,48 +26,21 @@ declare class ClampMaxPolicy implements FieldPolicy<number> {
     apply(val: number): number;
     updateBounds(max: number): void;
 }
-declare function clampPolicy(min: number, max: number): ClampPolicy;
-declare function clampMinPolicy(min: number): ClampMinPolicy;
 declare function clampMaxPolicy(max: number): ClampMaxPolicy;
 
-/**
- * A reactive state container that wraps a value, making it observable through a Preact Signal.
- * It allows applying a pipeline of transformation or validation "policies" before any new value is set.
- *
- * @template T The type of the value this field holds.
- *
- */
-declare class Field<T> {
+declare class ClampMinPolicy implements Policy<number> {
+    min: number;
+    static readonly id = "clampMin";
+    readonly id = "clampMin";
+    constructor(min: number);
+    apply(val: number): number;
+    updateBounds(min: number): void;
+}
+declare function clampMinPolicy(min: number): ClampMinPolicy;
+
+declare class Policies<T> {
     private readonly policies;
-    private readonly _val;
-    /** A unique identifier for the field. */
-    name: string;
-    /**
-     * Creates an instance of a Field.
-     * @param name A unique identifier for the field.
-     * @param initialVal The initial value of the field.
-     * @param options Optional configuration for the field.
-     * @param options.policies An array of policies to apply to the field's value on every `set` operation.
-     */
-    constructor(name: string, initialVal: T, options?: {
-        policies?: FieldPolicy<T>[];
-    });
-    /**
-     * Gets the current raw value of the field.
-     * For reactive updates, it's recommended to use the `.signal` property instead.
-     */
-    get val(): T;
-    /**
-     * Provides readonly access to the underlying Preact Signal.
-     * Subscribe to this signal to react to value changes.
-     */
-    get signal(): ReadonlySignal<T>;
-    /**
-     * Sets a new value for the field.
-     * The provided value will be processed by all registered policies before the underlying signal is updated.
-     * @param val The new value to set.
-     */
-    set(val: T): void;
+    get items(): Map<string, Policy<T>>;
     /**
      * Retrieves a specific policy instance by its ID.
      * Useful for accessing a policy's internal state or methods.
@@ -86,30 +48,106 @@ declare class Field<T> {
      * @param id The unique ID of the policy to retrieve.
      * @returns The policy instance, or `undefined` if not found.
      */
-    getPolicy<P extends FieldPolicy<T>>(id: string): P | undefined;
+    get<P extends Policy<T>>(id: string): P | undefined;
     /**
      * Adds a new policy to the field or replaces an existing one with the same ID.
      * The new policy will be applied on the next `set()` operation.
      * If a policy with the same ID already exists, its `destroy` method will be called before it is replaced.
      * @param policy The policy instance to add.
      */
-    addPolicy(policy: FieldPolicy<T>): void;
+    add(policy: Policy<T>): this;
     /**
      * Removes a policy from the field by its ID and call `destroy` method.
      * @param policyId The unique ID of the policy to remove.
      * @returns `true` if the policy was found and removed, otherwise `false`.
      */
-    removePolicy(policyId: string): boolean;
+    remove(policyId: string): boolean;
+    isEmpty(): boolean;
     /**
      * Removes all policies from the field.
      * After this, `set()` will no longer apply any transformations to the value until new policies are added.
      */
-    clearPolicies(): void;
+    clear(): void;
     /**
      * Forces the current value to be re-processed by all policies.
      * Useful if a policy's logic has changed and you need to re-evaluate the current state.
      */
-    reapplyPolicies(): void;
+    apply(val: T): T;
+}
+
+interface FieldOptions<T> {
+    policies?: Policy<T>[];
+}
+interface Field<T> {
+    readonly typeName: string;
+    readonly name: string;
+    value: T;
+    policies: Policies<T>;
+    setValueSilently(val: T): void;
+    batchUpdate(updateFn: (currentValue: T) => T): void;
+    onChange: Subscribable<[newValue: T, oldValue: T]>;
+    destroy(): void;
+}
+interface NumericField extends Field<number> {
+    readonly min: number | undefined;
+    readonly max: number | undefined;
+    isMin(): boolean;
+    isMax(): boolean;
+    inc(val: number): void;
+    dec(val: number): void;
+}
+interface BooleanField extends Field<boolean> {
+    toggle(): boolean;
+}
+interface StringField extends Field<string> {
+    append(str: string | number): this;
+    prepend(str: string | number): this;
+    trim(): this;
+    isEmpty(): boolean;
+    clear(): void;
+}
+
+/**
+ * A state container that wraps a value.
+ * It allows applying a pipeline of transformation or validation "policies" before any new value is set.
+ *
+ * @template T The type of the value this field holds.
+ *
+ */
+declare class DefaultField<T> implements Field<T> {
+    /** A type keyword of the field */
+    static readonly typeName: string;
+    readonly typeName: string;
+    /** A unique identifier for the field. */
+    private readonly _name;
+    private _value;
+    private readonly _onChange;
+    readonly onChange: Subscribable<[newValue: T, oldvalue: T]>;
+    readonly policies: Policies<T>;
+    get name(): string;
+    /**
+     * Gets the current raw value of the field.
+     * For reactive updates, it's recommended to use the `.signal` property instead.
+     */
+    get value(): T;
+    /**
+     * Sets a new value for the field.
+     * The provided value will be processed by all registered policies before the underlying signal is updated.
+     * @param val The new value to set.
+     */
+    set value(val: T);
+    /**
+     * Creates an instance of a Field.
+     * @param name A unique identifier for the field.
+     * @param initialVal The initial value of the field.
+     * @param options Optional configuration for the field.
+     * @param options.policies An array of policies to apply to the field's value on every `set` operation.
+     * @param options.isEqual An function for compare old and new value, by default uses the strictEquals from `utils`
+     *
+     */
+    constructor(name: string, initialVal: T, options?: FieldOptions<T>);
+    setValueSilently(val: T): void;
+    batchUpdate(updateFn: (currentValue: T) => T): void;
     /**
      * Cleans up resources used by the field and its policies.
      * This should be called when the field is no longer needed to prevent memory leaks from reactive policies.
@@ -117,240 +155,638 @@ declare class Field<T> {
     destroy(): void;
 }
 
-interface NumberFieldOptions {
+interface DefaultBooleanFieldOptions extends FieldOptions<boolean> {
+}
+declare class DefaultBooleanField extends DefaultField<boolean> implements BooleanField {
+    static readonly typeName: string;
+    readonly typeName: string;
+    constructor(name: string, initialVal: boolean, options?: DefaultBooleanFieldOptions);
+    toggle(): boolean;
+}
+
+interface DefaultStringFieldOptions extends FieldOptions<string> {
+}
+declare class DefaultStringField extends DefaultField<string> implements StringField {
+    static readonly typeName: string;
+    readonly typeName: string;
+    constructor(name: string, initialVal: string, options?: DefaultStringFieldOptions);
+    append(str: string | number): this;
+    prepend(str: string | number): this;
+    trim(): this;
+    isEmpty(): boolean;
+    clear(): void;
+}
+
+interface DefaultNumericFieldOptions extends FieldOptions<number> {
     min?: number;
     max?: number;
-    policies?: FieldPolicy<number>[];
 }
-declare class NumberField extends Field<number> {
+declare class DefaultNumericField extends DefaultField<number> implements NumericField {
+    static readonly typeName: string;
+    readonly typeName: string;
     get min(): number | undefined;
     get max(): number | undefined;
-    get isMin(): boolean;
-    get isMax(): boolean;
-    constructor(name: string, initialVal: number, options?: NumberFieldOptions);
+    constructor(name: string, initialVal: number, options?: DefaultNumericFieldOptions);
+    isMin(): boolean;
+    isMax(): boolean;
     inc(amount?: number): void;
     dec(amount?: number): void;
 }
 
 /**
- * An abstract base class for managing a reactive collection of `Field` instances.
+ * A generic registry for mapping string identifiers to class constructors.
  *
- * This class is designed to be the foundation for state management systems,
- * such as managing stats, flags, or items.
+ * This utility is fundamental for building extensible systems like dependency injection containers,
+ * factories, and serialization engines where types need to be dynamically resolved.
+ *
+ * @template T - A base type that all registered constructors must produce an instance of.
+ */
+declare class ConstructorRegistry<T> {
+    private readonly items;
+    /**
+     * Registers a constructor with a unique string identifier.
+     *
+     * @param typeId - The unique identifier for the constructor (e.g., a static `typeName` property from a class).
+     * @param ctor - The class constructor to register.
+     * @returns The registry instance for chainable calls.
+     * @throws If a constructor with the same `typeId` is already registered.
+     */
+    register(typeId: string, ctor: Constructor<T>): this;
+    /**
+     * Retrieves a constructor by its identifier.
+     *
+     * @param typeId - The identifier of the constructor to retrieve.
+     * @returns The found class constructor.
+     * @throws If no constructor is found for the given `typeId`.
+     */
+    get(typeId: string): Constructor<T>;
+    /**
+     * Checks if a constructor for a given identifier is registered.
+     * @param typeId - The identifier to check.
+     * @returns `true` if a constructor is registered, otherwise `false`.
+     */
+    has(typeId: string): boolean;
+    /**
+     * Clears all registered constructors from the registry.
+     */
+    clear(): void;
+}
+
+declare class FieldRegistry extends ConstructorRegistry<Field<any>> {
+}
+
+/**
+ * A container for a collection of named `Field` instances.
  *
- * @template T The common base type for the values held by the fields in this collection.
+ * This class acts as a "leaf" node in the `FieldTree` hierarchy, managing a flat
+ * key-value store of reactive data points. It uses a `FieldRegistry` to dynamically
+ * create `Field` instances of different types.
  */
-declare abstract class BaseFields<T> {
-    protected readonly _fields: Signal<Map<string, Field<T>>>;
-    readonly events: AxiEventEmitter<"created" | "removed">;
+declare class Fields {
+    static readonly typeName = "fields";
+    readonly typeName = "fields";
+    readonly _fields: Map<string, Field<any>>;
+    readonly _fieldRegistry: FieldRegistry;
+    /**
+     * An event emitter that fires when a new field is added to the collection.
+     * @event
+     * @param {object} event - The event payload.
+     * @param {string} event.name - The name of the added field.
+     * @param {Field<any>} event.field - The `Field` instance that was added.
+     */
+    onAdd: Emitter<[event: {
+        name: string;
+        field: Field<any>;
+    }]>;
+    /**
+     * An event emitter that fires after one or more fields have been removed.
+     * @event
+     * @param {object} event - The event payload.
+     * @param {string[]} event.names - An array of names of the fields that were successfully removed.
+     */
+    onRemove: Emitter<[event: {
+        names: string[];
+    }]>;
+    /**
+     * Gets the read-only map of all `Field` instances in this container.
+     * @returns {Map<string, Field<any>>} The collection of fields.
+     */
+    get fields(): Map<string, Field<any>>;
     /**
-     * A readonly signal providing access to the current map of fields.
-     * Use this signal with `effect` to react when fields are added or removed from the collection.
-     * Avoid to change any data in the map manually.
+     * Creates an instance of Fields.
+     * @param {FieldRegistry} fieldRegistry - The registry used to create new `Field` instances.
      */
-    get fields(): ReadonlySignal<ReadonlyMap<string, Field<any>>>;
+    constructor(fieldRegistry: FieldRegistry);
     /**
      * Checks if a field with the given name exists in the collection.
-     * @param name The name of the field to check.
-     * @returns `true` if the field exists, otherwise `false`.
+     * @param {string} name The name of the field to check.
+     * @returns {boolean} `true` if the field exists, otherwise `false`.
      */
     has(name: string): boolean;
     /**
-     * Creates and adds a new `Field` to the collection.
-     * @param name The unique name for the new field.
-     * @param initialValue The initial value for the new field.
-     * @returns The newly created `Field` instance.
+     * Adds a pre-existing `Field` instance to the collection and fires the `onAdd` event.
+     * @template T - The specific `Field` type being added.
+     * @param {Field<any>} field - The `Field` instance to add.
+     * @returns {T} The added `Field` instance, cast to type `T`.
+     * @throws If a field with the same name already exists.
      */
-    create(name: string, initialValue: T): Field<T>;
+    add<T extends Field<any>>(field: Field<any>): T;
     /**
-     * Adds a pre-existing `Field` instance to the collection.
-     * Throws an error if a field with the same name already exists.
-     * @param field The `Field` instance to add.
-     * @returns The added `Field` instance.
+     * Creates a new `Field` instance of a specified type, adds it to the collection, and returns it.
+     * This is the primary factory method for creating fields within this container.
+     * @template T - The expected `Field` type to be returned.
+     * @param {string} typeName - The registered type name of the field to create (e.g., 'numeric', 'boolean').
+     * @param {string} name - The unique name for the new field.
+     * @param {*} initialValue - The initial value for the new field.
+     * @param {*} [options] - Optional configuration passed to the field's constructor.
+     * @returns {T} The newly created `Field` instance.
      */
-    add(field: Field<T>): Field<T>;
+    create<T extends Field<any>>(typeName: string, name: string, initialValue: any, options?: any): T;
     /**
-     * Retrieves a field by its name.
-     * Throws an error if the field does not exist.
-     * @param name The name of the field to retrieve.
-     * @returns The `Field` instance.
+     * Updates an existing field's value or creates a new one if it doesn't exist.
+     * @template T - The expected `Field` type.
+     * @param {string} typeName - The type name to use if a new field needs to be created.
+     * @param {string} name - The name of the field to update or create.
+     * @param {*} value - The new value to set.
+     * @param {*} [options] - Optional configuration, used only if a new field is created.
+     * @returns {T} The existing or newly created `Field` instance.
      */
-    get(name: string): Field<T>;
+    upset<T extends Field<any>>(typeName: string, name: string, value: any, options?: any): T;
     /**
-     * "Update or Insert": Updates a field's value if it exists, or creates a new one if it doesn't.
-     * @param name The name of the field.
-     * @param value The value to set.
-     * @returns The existing or newly created `Field` instance.
+     * Retrieves a field by its name.
+     * @template T - The expected `Field` type to be returned.
+     * @param {string} name - The name of the field to retrieve.
+     * @returns {T} The `Field` instance.
+     * @throws If the field does not exist.
      */
-    upset(name: string, value: T): Field<T>;
+    get<T extends Field<any>>(name: string): T;
     /**
      * Removes one or more fields from the collection.
      * This method ensures that the `destroy` method of each removed field is called to clean up its resources.
-     * @param names A single name or an array of names to remove.
+     * @param {string| string[]} names A single name or an array of names to remove.
      */
     remove(names: string | string[]): void;
     /**
      * Removes all fields from the collection, ensuring each is properly destroyed.
      */
     clear(): void;
-    /**
-     * Creates a serializable snapshot of the current state of all fields.
-     * @returns A plain JavaScript object representing the values of all fields.
-     */
-    snapshot(): Record<string, any>;
-    /**
-     * Restores the state of the fields from a snapshot.
-     * It uses the `upset` logic to create or update fields based on the snapshot data.
-     * @param snapshot The snapshot object to load.
-     */
-    hydrate(snapshot: any): void;
 }
 
-declare class Fields extends BaseFields<any> {
-    createNumber(name: string, initialValue: number, options?: NumberFieldOptions): NumberField;
-    upsetNumber(name: string, value: number, options?: NumberFieldOptions): NumberField;
-    getNumber(name: string): NumberField;
-    create<T>(name: string, initialValue: T): Field<T>;
-    upset<T>(name: string, value: T): Field<T>;
-    get<T>(name: string): Field<T>;
+declare const DefaultFields_base: {
+    new (...args: any[]): {
+        createBoolean(name: string, initialValue: boolean, options?: DefaultBooleanFieldOptions): DefaultBooleanField;
+        upsetBoolean(name: string, value: boolean, options?: DefaultBooleanFieldOptions): DefaultBooleanField;
+        getBoolean(name: string): DefaultBooleanField;
+        readonly typeName: "fields";
+        readonly _fields: Map<string, Field<any>>;
+        readonly _fieldRegistry: FieldRegistry;
+        onAdd: _axi_engine_utils.Emitter<[event: {
+            name: string;
+            field: Field<any>;
+        }]>;
+        onRemove: _axi_engine_utils.Emitter<[event: {
+            names: string[];
+        }]>;
+        get fields(): Map<string, Field<any>>;
+        has(name: string): boolean;
+        add<T extends Field<any>>(field: Field<any>): T;
+        create<T extends Field<any>>(typeName: string, name: string, initialValue: any, options?: any): T;
+        upset<T extends Field<any>>(typeName: string, name: string, value: any, options?: any): T;
+        get<T extends Field<any>>(name: string): T;
+        remove(names: string | string[]): void;
+        clear(): void;
+    };
+} & {
+    new (...args: any[]): {
+        createString(name: string, initialValue: string, options?: DefaultStringFieldOptions): DefaultStringField;
+        upsetString(name: string, value: string, options?: DefaultStringFieldOptions): DefaultStringField;
+        getString(name: string): DefaultStringField;
+        readonly typeName: "fields";
+        readonly _fields: Map<string, Field<any>>;
+        readonly _fieldRegistry: FieldRegistry;
+        onAdd: _axi_engine_utils.Emitter<[event: {
+            name: string;
+            field: Field<any>;
+        }]>;
+        onRemove: _axi_engine_utils.Emitter<[event: {
+            names: string[];
+        }]>;
+        get fields(): Map<string, Field<any>>;
+        has(name: string): boolean;
+        add<T extends Field<any>>(field: Field<any>): T;
+        create<T extends Field<any>>(typeName: string, name: string, initialValue: any, options?: any): T;
+        upset<T extends Field<any>>(typeName: string, name: string, value: any, options?: any): T;
+        get<T extends Field<any>>(name: string): T;
+        remove(names: string | string[]): void;
+        clear(): void;
+    };
+} & {
+    new (...args: any[]): {
+        createNumeric(name: string, initialValue: number, options?: DefaultNumericFieldOptions): DefaultNumericField;
+        upsetNumeric(name: string, value: number, options?: DefaultNumericFieldOptions): DefaultNumericField;
+        getNumeric(name: string): DefaultNumericField;
+        readonly typeName: "fields";
+        readonly _fields: Map<string, Field<any>>;
+        readonly _fieldRegistry: FieldRegistry;
+        onAdd: _axi_engine_utils.Emitter<[event: {
+            name: string;
+            field: Field<any>;
+        }]>;
+        onRemove: _axi_engine_utils.Emitter<[event: {
+            names: string[];
+        }]>;
+        get fields(): Map<string, Field<any>>;
+        has(name: string): boolean;
+        add<T extends Field<any>>(field: Field<any>): T;
+        create<T extends Field<any>>(typeName: string, name: string, initialValue: any, options?: any): T;
+        upset<T extends Field<any>>(typeName: string, name: string, value: any, options?: any): T;
+        get<T extends Field<any>>(name: string): T;
+        remove(names: string | string[]): void;
+        clear(): void;
+    };
+} & {
+    new (...args: any[]): {
+        createDefault<T>(name: string, initialValue: T, options?: FieldOptions<T> | undefined): DefaultField<T>;
+        upsetDefault<T>(name: string, value: T, options?: FieldOptions<T> | undefined): DefaultField<T>;
+        readonly typeName: "fields";
+        readonly _fields: Map<string, Field<any>>;
+        readonly _fieldRegistry: FieldRegistry;
+        onAdd: _axi_engine_utils.Emitter<[event: {
+            name: string;
+            field: Field<any>;
+        }]>;
+        onRemove: _axi_engine_utils.Emitter<[event: {
+            names: string[];
+        }]>;
+        get fields(): Map<string, Field<any>>;
+        has(name: string): boolean;
+        add<T extends Field<any>>(field: Field<any>): T;
+        create<T extends Field<any>>(typeName: string, name: string, initialValue: any, options?: any): T;
+        upset<T extends Field<any>>(typeName: string, name: string, value: any, options?: any): T;
+        get<T extends Field<any>>(name: string): T;
+        remove(names: string | string[]): void;
+        clear(): void;
+    };
+} & typeof Fields;
+declare class DefaultFields extends DefaultFields_base {
 }
 
-declare class TypedFields<T> extends BaseFields<T> {
+/**
+ * Defines the contract for a factory that creates nodes for a FieldTree.
+ * This allows for custom implementations of Fields and FieldTree to be used.
+ */
+interface TreeNodeFactory {
+    fields<T extends Fields>(): T;
+    tree<T extends FieldTree>(): T;
+}
+/**
+ * The default factory implementation that creates standard DefaultFields and FieldTree instances.
+ */
+declare class DefaultTreeNodeFactory implements TreeNodeFactory {
+    private readonly fieldRegistry;
+    constructor(fieldRegistry: FieldRegistry);
+    fields: () => any;
+    tree: () => any;
 }
 
 /** A type alias for any container that can be a child node in a FieldTree */
-type TreeOrFieldsContainer = FieldTree | Fields | TypedFields<any>;
-/** Describes the payload for events emitted when a container is created or removed from a FieldTree. */
-type FieldTreeContainerEvent = {
-    type: 'created' | 'removed';
-    name: string;
-    path: [];
-    node: TreeOrFieldsContainer;
-};
+type TreeOrFieldsNode = FieldTree | Fields;
 /**
- * Represents the global, persistent state of the entire game.
- * This service acts as the single source of truth for long-term data that exists
+ * Represents a hierarchical data structure for managing the global state of the system.
+ *
+ * This class acts as the single source of truth for long-term data that exists
  * across different scenes and scripts, such as player stats, inventory,
- * and overall game progress.
- * It is designed to be the foundational data layer,
- * independent of any single script's / minigames execution lifecycle.
+ * and overall game progress. It uses a path-based system for accessing and
+ * manipulating nested data, similar to a file system.
  *
- * @todo:
- * - add node removing
+ * @todo
+ * - Add node removal functionality.
+ * - Implement an event system for node creation/removal.
  */
 declare class FieldTree {
-    private readonly _items;
-    readonly events: AxiEventEmitter<"created" | "removed">;
+    static readonly typeName = "fieldTree";
+    readonly typeName = "fieldTree";
+    /** @private The internal map storing child nodes (branches or leaves). */
+    private readonly _nodes;
+    /** @private The factory used to create new child nodes. */
+    private readonly _factory;
     /**
-     * A readonly signal providing access to the map of child nodes.
-     * Use this with `effect` to react to structural changes in the tree (e.g., adding a new `Fields` container).
+     * Gets the collection of direct child nodes of this tree branch.
      */
-    get items(): ReadonlySignal<ReadonlyMap<string, TreeOrFieldsContainer>>;
-    constructor();
+    get nodes(): Map<string, TreeOrFieldsNode>;
     /**
-     * Checks if a path to a node or fields container  or field exists without creating it.
-     * @returns true if the entire path exists, false otherwise.
+     * Creates an instance of FieldTree.
+     * @param {TreeNodeFactory} factory - A factory responsible for creating new nodes within the tree.
      */
-    hasPath(path: PathType): boolean;
+    constructor(factory: TreeNodeFactory);
     /**
-     * Retrieves a child node and asserts that it is an instance of `FieldTree`.
-     * @param name The name of the child node.
-     * @returns The `FieldTree` instance.
-     * @throws If the node does not exist or is not a `FieldTree`.
+     * Checks if a direct child node with the given name exists.
+     * @param {string} name - The name of the direct child node.
+     * @returns {boolean} `true` if the node exists, otherwise `false`.
      */
-    getFieldTree(name: string): FieldTree;
+    has(name: string): boolean;
     /**
-     * Retrieves a child node and asserts that it is an instance of `Fields`.
-     * @param name The name of the child node.
-     * @returns The `Fields` instance.
-     * @throws If the node does not exist or is not a `Fields` container.
+     * Checks if a node exists at a given path, traversing the tree.
+     * @param {PathType} path - The path to check (e.g., 'player/stats' or ['player', 'stats']).
+     * @returns {boolean} `true` if the entire path resolves to a node, otherwise `false`.
      */
-    getFields(name: string): Fields;
+    hasPath(path: PathType): boolean;
     /**
-     * Retrieves a child node and asserts that it is an instance of `TypedFields`.
-     * @param name The name of the child node.
-     * @returns The `TypedFields` instance.
-     * @throws If the node does not exist or is not a `TypedFields` container.
+     * Adds a pre-existing node as a direct child of this tree branch.
+     * @param {string} name - The name to assign to the new child node.
+     * @param {TreeOrFieldsNode} node - The node instance to add.
+     * @returns {TreeOrFieldsNode} The added node.
+     * @throws If a node with the same name already exists.
      */
-    getTypedFields<T>(name: string): TypedFields<T>;
+    addNode(name: string, node: TreeOrFieldsNode): TreeOrFieldsNode;
     /**
-     * Retrieves a child node from this tree level without type checking.
-     * @param name The name of the child node.
-     * @returns The retrieved node, which can be a `FieldTree` or a `Fields` container.
+     * Retrieves a direct child node by its name.
+     * @param {string} name - The name of the child node.
+     * @returns {TreeOrFieldsNode} The retrieved node.
      * @throws If a node with the given name cannot be found.
      */
-    getNode(name: string): TreeOrFieldsContainer;
+    getNode(name: string): TreeOrFieldsNode;
     /**
-     * Creates and adds a new `FieldTree` node as a child of this one.
-     * @param name The unique name for the new `FieldTree` node.
-     * @returns The newly created `FieldTree` instance.
+     * Creates a new `FieldTree` (branch) node at the specified path.
+     * @param {PathType} path - The path where the new `FieldTree` should be created.
+     * @param {boolean} [createPath=false] - If `true`, any missing parent branches in the path will be created automatically.
+     * @returns {FieldTree} The newly created `FieldTree` instance.
+     * @throws If the path is invalid or a node already exists at the target location.
      */
-    createFieldTree(name: string): FieldTree;
+    createFieldTree<T extends FieldTree>(path: PathType, createPath?: boolean): T;
     /**
-     * Creates and adds a new `Fields` container as a child of this one.
-     * @param name The unique name for the new `Fields` container.
-     * @returns The newly created `Fields` instance.
+     * Creates a new `Fields` (leaf) container at the specified path.
+     * @param {PathType} path - The path where the new `Fields` container should be created.
+     * @param {boolean} [createPath=false] - If `true`, any missing parent branches in the path will be created automatically.
+     * @returns {Fields} The newly created `Fields` instance.
+     * @throws If the path is invalid or a node already exists at the target location.
      */
-    createFields(name: string): Fields;
+    createFields<T extends Fields>(path: PathType, createPath?: boolean): T;
     /**
-     * Creates and adds a new `TypedFields` container as a child of this one.
-     * @param name The unique name for the new `TypedFields` container.
-     * @returns The newly created `TypedFields` instance.
+     * Retrieves a `FieldTree` (branch) node from a specified path.
+     * @param {PathType} path - The path to the `FieldTree` node.
+     * @returns {FieldTree} The `FieldTree` instance at the specified path.
+     * @throws If the path is invalid or the node at the path is not a `FieldTree`.
      */
-    createTypedFields<T>(name: string): TypedFields<T>;
+    getFieldTree(path: PathType): FieldTree;
     /**
-     * Navigates through the tree using a path and returns the `Fields` container at the end.
-     * @param path The path to the `Fields` container (e.g., 'player/stats').
-     * @returns The `Fields` container at the specified path.
-     * @throws If the path is empty, or any intermediate node is not a `FieldTree`.
+     * Retrieves a `Fields` (leaf) container from a specified path.
+     * @param {PathType} path - The path to the `Fields` container.
+     * @returns {Fields} The `Fields` instance at the specified path.
+     * @throws If the path is invalid or the node at the path is not a `Fields` container.
      */
-    getFieldsByPath(path: PathType): Fields;
+    getFields(path: PathType): Fields;
     /**
-     * Creates a `Field` at a deeply nested path.
-     * The last part of the path is treated as the field name, and the preceding parts as the path to its container.
-     * @param path The full path to the new field (e.g., 'player/stats/health').
-     * @param initialValue The initial value for the new field.
-     * @returns The newly created `Field` instance.
+     * Retrieves a `FieldTree` at the specified path. If it or any part of the path doesn't exist, it will be created.
+     * @param {PathType} path - The path to the `FieldTree` node.
+     * @returns {FieldTree} The existing or newly created `FieldTree` instance.
      */
-    create<T>(path: PathType, initialValue: T): Field<T>;
+    getOrCreateFieldTree(path: PathType): FieldTree;
     /**
-     * Creates a `NumberField` at a deeply nested path.
-     * @param path The full path to the new field (e.g., 'player/stats/mana').
-     * @param initialValue The initial numeric value.
-     * @returns The newly created `NumberField` instance.
+     * Retrieves a `Fields` container at the specified path. If it or any part of the path doesn't exist, it will be created.
+     * @param {PathType} path - The path to the `Fields` container.
+     * @returns {Fields} The existing or newly created `Fields` instance.
      */
-    createNumber(path: PathType, initialValue: number): NumberField;
+    getOrCreateFields(path: PathType): Fields;
     /**
-     * Retrieves a `Field` from a deeply nested path.
-     * @param path The full path to the field (e.g., 'player/stats/name').
-     * @returns The `Field` instance at the specified path.
+     * @private
+     * Navigates the tree to the parent of a target node.
+     * This is the core traversal logic for all path-based operations.
+     * @param {PathType} path - The full path to the target node.
+     * @param {boolean} [createPath=false] - If `true`, creates missing `FieldTree` branches along the path.
+     * @returns {{branch: FieldTree, leafName: string}} An object containing the final branch (parent node) and the name of the leaf (target node).
+     * @throws If the path is empty, invalid, or contains a `Fields` container as an intermediate segment.
+     */
+    private traversePath;
+}
+
+/**
+ * Defines the contract for a handler that can serialize and deserialize a specific type of Policy.
+ * @template T - The specific Policy class this handler manages.
+ * @template S - The shape of the plain object this handler produces/consumes.
+ */
+interface PolicySerializerHandler<T extends Policy<any>, S extends object> {
+    /**
+     * Converts a Policy instance into a serializable plain object.
+     * @param policy The Policy instance to serialize.
+     * @returns A plain object representing the policy's state.
      */
-    get<T>(path: PathType): Field<T>;
+    snapshot(policy: T): S;
     /**
-     * Retrieves a `NumberField` from a deeply nested path.
-     * @param path The full path to the number field (e.g., 'player/stats/level').
-     * @returns The `NumberField` instance at the specified path.
+     * Creates a new Policy instance from a plain object.
+     * @param snapshotData The plain object containing the policy's state.
+     * @returns A new instance of the Policy.
      */
-    getNumber(path: PathType): NumberField;
+    hydrate(snapshotData: S): T;
+}
+declare class PolicySerializer {
+    private readonly handlers;
+    register(policyId: string, handler: PolicySerializerHandler<any, any>): this;
+    clearHandlers(): void;
+    /**
+     * Creates a serializable snapshot of a policy instance.
+     * The snapshot includes the policy's state and a `__type` identifier.
+     * @param policy The policy instance to snapshot.
+     * @returns A plain object ready for JSON serialization.
+     * @throws If no handler is registered for the policy's ID.
+     */
+    snapshot(policy: Policy<any>): object;
+    /**
+     * Restores a policy instance from its snapshot representation.
+     * @param snapshot The plain object snapshot, which must contain a `__type` property.
+     * @returns A new, fully functional policy instance.
+     * @throws If the snapshot is invalid or no handler is registered for its `__type`.
+     */
+    hydrate(snapshot: any): Policy<any>;
+}
+
+declare class ClampPolicySerializerHandler implements PolicySerializerHandler<ClampPolicy, {
+    min: number;
+    max: number;
+}> {
+    snapshot(policy: ClampPolicy): {
+        min: number;
+        max: number;
+    };
+    hydrate(data: {
+        min: number;
+        max: number;
+    }): ClampPolicy;
+}
+
+declare class ClampMaxPolicySerializerHandler implements PolicySerializerHandler<ClampMaxPolicy, {
+    max: number;
+}> {
+    snapshot(policy: ClampMaxPolicy): {
+        max: number;
+    };
+    hydrate(data: {
+        max: number;
+    }): ClampMaxPolicy;
+}
+
+declare class ClampMinPolicySerializerHandler implements PolicySerializerHandler<ClampMinPolicy, {
+    min: number;
+}> {
+    snapshot(policy: ClampMinPolicy): {
+        min: number;
+    };
+    hydrate(data: {
+        min: number;
+    }): ClampMinPolicy;
+}
+
+/**
+ * A plain object representation of a Field's state for serialization.
+ */
+interface FieldSnapshot {
+    __type: string;
+    name: string;
+    value: any;
+    policies?: object[];
+}
+/**
+ * Orchestrates the serialization and deserialization of Field instances.
+ *
+ * This class acts as a central point for converting complex Field objects into
+ * 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;
+    private readonly policySerializer;
+    /**
+     * Creates an instance of FieldSerializer.
+     * @param {FieldRegistry} fieldRegistry - A registry that maps string type names to Field constructors.
+     * @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
+     * the field with its value and all its policies.
+     * @param {FieldSnapshot} snapshot - The plain object snapshot to deserialize.
+     * @returns {Field<any>} A new, fully functional Field instance.
+     * @throws If the snapshot is invalid, missing a `__type`, or if the type is not registered.
+     */
+    hydrate(snapshot: FieldSnapshot): Field<any>;
+}
+
+/**
+ * A plain object representation of a Fields container's state for serialization.
+ */
+interface FieldsSnapshot {
+    __type: string;
+    [fieldName: string]: FieldSnapshot | string;
+}
+/**
+ * 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 This implementation is coupled to creating `DefaultFields` instances during hydration.
+ *       To make the system fully extensible, this class should be refactored to use a
+ *       `FieldsRegistry` (a `ConstructorRegistry<Fields>`). This would allow it to
+ *       hydrate any custom `Fields` class (e.g., `ReactiveFields`) based on the `__type`
+ *       property in the snapshot, mirroring the pattern used by `FieldSerializer`.
+ *
+ * @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.
+ */
+declare class FieldsSerializer {
+    private readonly fieldRegistry;
+    private readonly policySerializer;
+    /**
+     * An internal instance of FieldSerializer to handle individual fields.
+     * @private
+     */
+    private readonly fieldSerializer;
+    /**
+     * Creates an instance of FieldsSerializer.
+     * @param {FieldRegistry} fieldRegistry - A registry that maps string type names to Field constructors.
+     * @param {PolicySerializer} policySerializer - A serializer dedicated to handling Policy instances.
+     */
+    constructor(fieldRegistry: FieldRegistry, policySerializer: PolicySerializer);
+    /**
+     * Creates a serializable snapshot of a `Fields` container.
+     *
+     * The snapshot includes a `__type` identifier (currently hardcoded) and an array of snapshots
+     * for each `Field` within the container.
+     * @param {Fields} fields - The `Fields` instance to serialize.
+     * @returns {FieldsSnapshot} A plain object ready for JSON serialization.
+     */
+    snapshot(fields: Fields): FieldsSnapshot;
+    /**
+     * Restores a `Fields` container instance from its snapshot representation.
+     *
+     * **Limitation:** This method is currently hardcoded to always create an instance of `DefaultFields`.
+     * 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 {DefaultFields} A new `DefaultFields` instance populated with the restored fields.
+     */
+    hydrate(snapshot: FieldsSnapshot): DefaultFields;
+}
+
+/**
+ * Represents the serializable state of a `FieldTree` container.
+ *
+ * This type describes a plain object that has:
+ * 1. A required `__type` property to identify the tree's class.
+ * 2. An arbitrary number of other properties, where each key is the `name`
+ *    of a child node, and the value is the snapshot of that child node.
+ *    The `| string` is included to ensure compatibility with the `__type` property.
+ */
+interface FieldTreeSnapshot {
+    __type: string;
+    [fieldName: string]: FieldsSnapshot | FieldTreeSnapshot | string;
+}
+/**
+ * Orchestrates the recursive serialization and 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`.
+ * @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 {
+    private readonly fieldTreeNodeFactory;
+    private readonly fieldsSerializer;
+    constructor(fieldTreeNodeFactory: TreeNodeFactory, fieldsSerializer: FieldsSerializer);
     /**
      * 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(): Record<string, any>;
+    snapshot(tree: FieldTree): FieldTreeSnapshot;
     /**
      * 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: any): void;
-    /**
-     * @private
-     * Generic internal method for creating and adding a new node to the tree.
-     * @param name The name of the node to create.
-     * @param ctor The constructor for the node type (e.g., `FieldTree` or `Fields`).
-     * @returns The newly created node instance.
-     */
-    private createNode;
+    hydrate(snapshot: FieldTreeSnapshot): FieldTree;
 }
 
-export { BaseFields, ClampMaxPolicy, ClampMinPolicy, ClampPolicy, Field, type FieldPolicy, FieldTree, type FieldTreeContainerEvent, Fields, FieldsNodeType, NumberField, type NumberFieldOptions, type TreeOrFieldsContainer, TypedFields, clampMaxPolicy, clampMinPolicy, clampPolicy };
+export { type BooleanField, ClampMaxPolicy, ClampMaxPolicySerializerHandler, ClampMinPolicy, ClampMinPolicySerializerHandler, ClampPolicy, ClampPolicySerializerHandler, DefaultBooleanField, type DefaultBooleanFieldOptions, DefaultField, DefaultFields, DefaultNumericField, type DefaultNumericFieldOptions, DefaultStringField, type DefaultStringFieldOptions, DefaultTreeNodeFactory, type Field, type FieldOptions, FieldRegistry, FieldSerializer, type FieldSnapshot, FieldTree, FieldTreeSerializer, type FieldTreeSnapshot, Fields, FieldsSerializer, type FieldsSnapshot, type NumericField, Policies, type Policy, PolicySerializer, type PolicySerializerHandler, type StringField, type TreeNodeFactory, type TreeOrFieldsNode, clampMaxPolicy, clampMinPolicy, clampPolicy };