@axi-engine/fields 0.2.3 → 0.3.0

package/dist/index.d.ts

@@ -139,7 +139,7 @@ interface StringField extends Field<string> {
  * @template T The type of the value this field holds.
  *
  */
-declare class DefaultField<T> implements Field<T> {
+declare class CoreField<T> implements Field<T> {
     /** A type keyword of the field */
     static readonly typeName: string;
     readonly typeName: string;
@@ -180,21 +180,21 @@ declare class DefaultField<T> implements Field<T> {
     destroy(): void;
 }
 
-interface DefaultBooleanFieldOptions extends FieldOptions<boolean> {
+interface CoreBooleanFieldOptions extends FieldOptions<boolean> {
 }
-declare class DefaultBooleanField extends DefaultField<boolean> implements BooleanField {
+declare class CoreBooleanField extends CoreField<boolean> implements BooleanField {
     static readonly typeName: string;
     readonly typeName: string;
-    constructor(name: string, initialVal: boolean, options?: DefaultBooleanFieldOptions);
+    constructor(name: string, initialVal: boolean, options?: CoreBooleanFieldOptions);
     toggle(): boolean;
 }
 
-interface DefaultStringFieldOptions extends FieldOptions<string> {
+interface CoreStringFieldOptions extends FieldOptions<string> {
 }
-declare class DefaultStringField extends DefaultField<string> implements StringField {
+declare class CoreStringField extends CoreField<string> implements StringField {
     static readonly typeName: string;
     readonly typeName: string;
-    constructor(name: string, initialVal: string, options?: DefaultStringFieldOptions);
+    constructor(name: string, initialVal: string, options?: CoreStringFieldOptions);
     append(str: string | number): this;
     prepend(str: string | number): this;
     trim(): this;
@@ -202,16 +202,16 @@ declare class DefaultStringField extends DefaultField<string> implements StringF
     clear(): void;
 }
 
-interface DefaultNumericFieldOptions extends FieldOptions<number> {
+interface CoreNumericFieldOptions extends FieldOptions<number> {
     min?: number;
     max?: number;
 }
-declare class DefaultNumericField extends DefaultField<number> implements NumericField {
+declare class CoreNumericField extends CoreField<number> implements NumericField {
     static readonly typeName: string;
     readonly typeName: string;
     get min(): number | undefined;
     get max(): number | undefined;
-    constructor(name: string, initialVal: number, options?: DefaultNumericFieldOptions);
+    constructor(name: string, initialVal: number, options?: CoreNumericFieldOptions);
     isMin(): boolean;
     isMax(): boolean;
     inc(amount?: number): void;
@@ -339,12 +339,12 @@ declare class Fields {
     upset<T extends Field<any>>(typeName: string, name: string, value: any, options?: any): T;
     /**
      * Retrieves a field by its name.
-     * @template T - The expected `Field` type to be returned.
+     * @template TField - The expected `Field` type to be returned.
      * @param {string} name - The name of the field to retrieve.
-     * @returns {T} The `Field` instance.
+     * @returns {TField} The `Field` instance.
      * @throws If the field does not exist.
      */
-    get<T extends Field<any>>(name: string): T;
+    get<TField extends Field<any>>(name: string): TField;
     /**
      * 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.
@@ -358,74 +358,18 @@ declare class Fields {
     destroy(): void;
 }
 
-declare const DefaultFields_base: _axi_engine_utils.Constructor<{
-    createGeneric<T>(name: string, initialValue: T, options?: FieldOptions<T> | undefined): DefaultField<T>;
-    upsetGeneric<T>(name: string, value: T, options?: FieldOptions<T> | undefined): DefaultField<T>;
-    getGeneric<T>(name: string): 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;
-    destroy(): void;
-} & Fields & {
-    createNumeric: (name: string, initialValue: number, options?: DefaultNumericFieldOptions | undefined) => DefaultNumericField;
-} & {
-    upsetNumeric: (name: string, value: number, options?: DefaultNumericFieldOptions | undefined) => DefaultNumericField;
-} & {
-    getNumeric: (name: string) => DefaultNumericField;
-} & {
-    createString: (name: string, initialValue: string, options?: DefaultStringFieldOptions | undefined) => DefaultStringField;
-} & {
-    upsetString: (name: string, value: string, options?: DefaultStringFieldOptions | undefined) => DefaultStringField;
-} & {
-    getString: (name: string) => DefaultStringField;
-} & {
-    createBoolean: (name: string, initialValue: boolean, options?: DefaultBooleanFieldOptions | undefined) => DefaultBooleanField;
-} & {
-    upsetBoolean: (name: string, value: boolean, options?: DefaultBooleanFieldOptions | undefined) => DefaultBooleanField;
-} & {
-    getBoolean: (name: string) => DefaultBooleanField;
-}>;
-declare class DefaultFields extends DefaultFields_base {
-}
-
 interface FieldsFactory<TFields extends Fields> {
     fields(): TFields;
 }
-declare class DefaultFieldsFactory implements FieldsFactory<DefaultFields> {
-    private readonly fieldRegistry;
-    constructor(fieldRegistry: FieldRegistry);
-    fields(): DefaultFields;
-}
+
 /**
  * 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<TFields extends Fields> extends FieldsFactory<TFields> {
+interface FieldTreeFactory<TFields extends Fields> extends FieldsFactory<TFields> {
     fields(): TFields;
     tree(): FieldTree<TFields>;
 }
-/**
- * The default factory implementation that creates standard DefaultFields and FieldTree instances.
- */
-declare class DefaultTreeNodeFactory extends DefaultFieldsFactory implements TreeNodeFactory<DefaultFields> {
-    constructor(fieldRegistry: FieldRegistry);
-    tree(): FieldTree<DefaultFields>;
-}
 
 /** A type alias for any container that can be a child node in a FieldTree */
 type TreeNode<F extends Fields> = FieldTree<F> | F;
@@ -479,9 +423,9 @@ declare class FieldTree<TFields extends Fields> {
     get nodes(): Map<string, TreeNode<TFields>>;
     /**
      * Creates an instance of FieldTree.
-     * @param {TreeNodeFactory} factory - A factory responsible for creating new nodes within the tree.
+     * @param {FieldTreeFactory} factory - A factory responsible for creating new nodes within the tree.
      */
-    constructor(factory: TreeNodeFactory<TFields>);
+    constructor(factory: FieldTreeFactory<TFields>);
     /**
      * Checks if a direct child node with the given name exists.
      * @param {string} name - The name of the direct child node.
@@ -561,7 +505,14 @@ declare class FieldTree<TFields extends Fields> {
      * @param {PathType} path - The path to the `Fields` container.
      * @returns {Fields} The existing or newly created `Fields` instance.
      */
-    getOrCreateFields(path: PathType): Fields;
+    getOrCreateFields(path: PathType): TFields;
+    /**
+     * Finds the parent node for a given path.
+     * @param path The path to the target node.
+     * @returns The parent node (either a FieldTree or Fields).
+     * @throws An error if the path is invalid or any intermediate node is not a FieldTree.
+     */
+    findParentNode(path: PathType): FieldTree<TFields> | TFields;
     /**
      * Removes all child nodes from this tree branch.
      * This method ensures that `destroy()` is called on each child node, allowing for
@@ -588,6 +539,69 @@ declare class FieldTree<TFields extends Fields> {
     private traversePath;
 }
 
+declare const CoreFields_base: _axi_engine_utils.Constructor<{
+    createGeneric<T>(name: string, initialValue: T, options?: FieldOptions<T> | undefined): CoreField<T>;
+    upsetGeneric<T>(name: string, value: T, options?: FieldOptions<T> | undefined): CoreField<T>;
+    getGeneric<T>(name: string): CoreField<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<TField extends Field<any>>(name: string): TField;
+    remove(names: string | string[]): void;
+    clear(): void;
+    destroy(): void;
+} & Fields & {
+    createNumeric: (name: string, initialValue: number, options?: CoreNumericFieldOptions | undefined) => CoreNumericField;
+} & {
+    upsetNumeric: (name: string, value: number, options?: CoreNumericFieldOptions | undefined) => CoreNumericField;
+} & {
+    getNumeric: (name: string) => CoreNumericField;
+} & {
+    createString: (name: string, initialValue: string, options?: CoreStringFieldOptions | undefined) => CoreStringField;
+} & {
+    upsetString: (name: string, value: string, options?: CoreStringFieldOptions | undefined) => CoreStringField;
+} & {
+    getString: (name: string) => CoreStringField;
+} & {
+    createBoolean: (name: string, initialValue: boolean, options?: CoreBooleanFieldOptions | undefined) => CoreBooleanField;
+} & {
+    upsetBoolean: (name: string, value: boolean, options?: CoreBooleanFieldOptions | undefined) => CoreBooleanField;
+} & {
+    getBoolean: (name: string) => CoreBooleanField;
+}>;
+declare class CoreFields extends CoreFields_base {
+}
+
+declare class CoreFieldsFactory implements FieldsFactory<CoreFields> {
+    protected readonly _fieldRegistry: FieldRegistry;
+    get fieldRegistry(): FieldRegistry;
+    constructor(fieldRegistry: FieldRegistry);
+    fields(): CoreFields;
+}
+
+declare class CoreFieldTree extends FieldTree<CoreFields> {
+}
+
+/**
+ * The default factory implementation that creates standard DefaultFields and FieldTree instances.
+ */
+declare class CoreTreeNodeFactory extends CoreFieldsFactory implements FieldTreeFactory<CoreFields> {
+    constructor(fieldRegistry: FieldRegistry);
+    tree(): CoreFieldTree;
+}
+
 /**
  * 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.
@@ -791,7 +805,7 @@ interface FieldTreeSnapshot {
 declare class FieldTreeSerializer<TFields extends Fields> {
     private readonly fieldTreeNodeFactory;
     private readonly fieldsSerializer;
-    constructor(fieldTreeNodeFactory: TreeNodeFactory<TFields>, fieldsSerializer: FieldsSerializer<TFields>);
+    constructor(fieldTreeNodeFactory: FieldTreeFactory<TFields>, fieldsSerializer: FieldsSerializer<TFields>);
     /**
      * Creates a serializable snapshot of the entire tree and its contained fields.
      * @returns A plain JavaScript object representing the complete state managed by this tree.
@@ -805,4 +819,218 @@ declare class FieldTreeSerializer<TFields extends Fields> {
     hydrate(snapshot: FieldTreeSnapshot): FieldTree<TFields>;
 }
 
-export { type BooleanField, ClampMaxPolicy, ClampMaxPolicySerializerHandler, ClampMinPolicy, ClampMinPolicySerializerHandler, ClampPolicy, ClampPolicySerializerHandler, DefaultBooleanField, type DefaultBooleanFieldOptions, DefaultField, DefaultFields, DefaultFieldsFactory, DefaultNumericField, type DefaultNumericFieldOptions, DefaultStringField, type DefaultStringFieldOptions, DefaultTreeNodeFactory, type Field, type FieldOptions, FieldRegistry, FieldSerializer, type FieldSnapshot, FieldTree, FieldTreeSerializer, type FieldTreeSnapshot, Fields, type FieldsFactory, FieldsSerializer, type FieldsSnapshot, type NumericField, Policies, type Policy, PolicySerializer, type PolicySerializerHandler, type StringField, type TreeNode, type TreeNodeFactory, clampMaxPolicy, clampMinPolicy, clampPolicy, createTypedMethodsMixin };
+interface StoreCreateFieldOptions {
+    /** Allows to explicitly specify the field type, overriding the automatic type detection. */
+    fieldType?: string;
+}
+/**
+ * Defines the primary high-level API for interacting with the state management system.
+ * It acts as a facade, simplifying access to the underlying FieldTree and providing
+ * both type-safe and dynamic methods for manipulating data.
+ */
+interface Store {
+    /**
+     * Retrieves the raw value of a Field at a specific path.
+     * @template T The expected type of the value.
+     * @param path The path to the field (e.g., 'player.stats.hp').
+     * @returns {T} The raw value stored in the field.
+     * @throws An error if the path is invalid or no field exists at the path.
+     */
+    getValue<T>(path: PathType): T;
+    /**
+     * Strictly sets the value of an *existing* Field at a specific path.
+     * @template T The type of the value being set.
+     * @param path The path to the existing field.
+     * @param val The new value to set.
+     * @returns {T} The value that was set.
+     * @throws An error if no field exists at the specified path.
+     */
+    setValue<T>(path: PathType, val: T): T;
+    /**
+     * Creates a new Field at a specified path, inferring its type from the provided value.
+     * This is a strict operation and will fail if a node already exists at the target path.
+     * @template T The type of the initial value.
+     * @param path The full path where the new field will be created.
+     * @param val The initial value for the field.
+     * @param options Optional configuration, including policies and the ability to override field type.
+     * @returns {T} value of the newly created Field instance.
+     * @throws An error if a node already exists at the path or if the parent path is invalid.
+     */
+    createValue<T>(path: PathType, val: T, options?: FieldOptions<T> & StoreCreateFieldOptions): T;
+    /**
+     * Creates new or update a Field at a specified path, inferring its type from the provided value.
+     * @template T The type of the initial value.
+     * @param path The full path where the new field will be created.
+     * @param val The initial value for the field.
+     * @param options Optional configuration, including policies and the ability to override field type.
+     * @returns {T} value of the newly created Field instance.
+     * @throws An error if a node already exists at the path or if the parent path is invalid.
+     */
+    upsetValue<T>(path: PathType, val: T, options?: FieldOptions<T> & StoreCreateFieldOptions): T;
+    /**
+     * Creates a new, strongly-typed CoreBooleanField.
+     * @throws An error if a node already exists at the path.
+     */
+    createBoolean(path: PathType, initialValue: boolean, options?: CoreBooleanFieldOptions): CoreBooleanField;
+    /**
+     * Creates a new, strongly-typed CoreNumericField.
+     * @throws An error if a node already exists at the path.
+     */
+    createNumeric(path: PathType, initialValue: number, options?: CoreNumericFieldOptions): CoreNumericField;
+    /**
+     * Creates a new, strongly-typed CoreStringField.
+     * @throws An error if a node already exists at the path.
+     */
+    createString(path: PathType, initialValue: string, options?: CoreStringFieldOptions): CoreStringField;
+    /**
+     * Creates a new, generic CoreField instance for any data type.
+     * @throws An error if a node already exists at the path.
+     */
+    createGeneric<T>(path: PathType, initialValue: T, options?: FieldOptions<T>): CoreField<T>;
+    /**
+     * Retrieves a strongly-typed CoreBooleanField instance.
+     * @throws An error if the path is invalid or the field is not of the expected type.
+     */
+    getBoolean(path: PathType): CoreBooleanField;
+    /**
+     * Retrieves a strongly-typed CoreNumericField instance.
+     * @throws An error if the path is invalid or the field is not of the expected type.
+     */
+    getNumeric(path: PathType): CoreNumericField;
+    /**
+     * Retrieves a strongly-typed CoreStringField instance.
+     * @throws An error if the path is invalid or the field is not of the expected type.
+     */
+    getString(path: PathType): CoreStringField;
+    /**
+     * Retrieves a generic CoreField instance.
+     * @throws An error if the path is invalid.
+     */
+    getGeneric<T>(path: PathType): CoreField<T>;
+    /**
+     * A generic method to retrieve a Field instance with a specific asserted type.
+     * @template TField The expected Field class or interface.
+     * @throws An error if the path is invalid or the field cannot be cast to the specified type.
+     */
+    getField<TField extends Field<any>>(path: PathType): TField;
+    /**
+     * Strictly creates a new CoreFields container.
+     * Any missing parent nodes in the path will be created automatically.
+     * @param path The path where the new Fields container will be created.
+     * @returns {CoreFields} The newly created CoreFields instance.
+     * @throws An error if a node already exists at the target path.
+     */
+    createFields(path: PathType): CoreFields;
+    /**
+     * Strictly creates a new CoreFieldTree node.
+     * Any missing parent nodes in the path will be created automatically.
+     * @param path The path where the new FieldTree node will be created.
+     * @returns {CoreFieldTree} The newly created CoreFieldTree instance.
+     * @throws An error if a node already exists at the target path.
+     */
+    createTree(path: PathType): CoreFieldTree;
+    /**
+     * Retrieves an existing CoreFields container.
+     * @param path The path to the Fields container.
+     * @returns {CoreFields} The found CoreFields instance.
+     * @throws An error if the path is invalid or the node at the path is not a Fields container.
+     */
+    getFields(path: PathType): CoreFields;
+    /**
+     * Retrieves an existing CoreFieldTree node.
+     * @param path The path to the FieldTree node.
+     * @returns {CoreFieldTree} The found CoreFieldTree instance.
+     * @throws An error if the path is invalid or the node at the path is not a FieldTree.
+     */
+    getTree(path: PathType): CoreFieldTree;
+    /**
+     * Removes the node (Field, Fields, or FieldTree) at the end of the specified path.
+     * This method does not remove parent nodes if they become empty.
+     * @param path The path to the node to remove.
+     */
+    remove(path: PathType): void;
+}
+
+interface DataStoreFieldResolver {
+    /**
+     * The typeName this resolver corresponds to in the FieldRegistry.
+     * e.g., 'numeric', 'boolean', 'vector'
+     */
+    typeName: string;
+    /**
+     * Checks if this resolver can handle the given value.
+     * @param value The value to check.
+     * @returns {boolean} True if the value is supported, otherwise false.
+     */
+    supports(value: unknown): boolean;
+}
+
+declare class DataStore implements Store {
+    private readonly tree;
+    private readonly resolvers;
+    private readonly rootFieldsName;
+    private _rootFields;
+    private get rootFields();
+    constructor(tree: CoreFieldTree);
+    registerResolver(resolver: DataStoreFieldResolver): void;
+    clearResolvers(): void;
+    getValue<T>(path: PathType): T;
+    setValue<T>(path: PathType, val: T): T;
+    createValue<T>(path: PathType, val: T, options?: FieldOptions<T> & StoreCreateFieldOptions): T;
+    upsetValue<T>(path: PathType, val: T, options?: FieldOptions<T> & StoreCreateFieldOptions): T;
+    createBoolean(path: PathType, initialValue: boolean, options?: CoreBooleanFieldOptions): CoreBooleanField;
+    createNumeric(path: PathType, initialValue: number, options?: CoreNumericFieldOptions): CoreNumericField;
+    createString(path: PathType, initialValue: string, options?: CoreStringFieldOptions): CoreStringField;
+    createGeneric<T>(path: PathType, initialValue: T, options?: FieldOptions<T>): CoreField<T>;
+    getBoolean(path: PathType): CoreBooleanField;
+    getNumeric(path: PathType): CoreNumericField;
+    getString(path: PathType): CoreStringField;
+    getGeneric<T>(path: PathType): CoreField<T>;
+    getField<TField extends Field<any>>(path: PathType): TField;
+    createFields(path: PathType): CoreFields;
+    createTree(path: PathType): CoreFieldTree;
+    getFields(path: PathType): CoreFields;
+    getTree(path: PathType): CoreFieldTree;
+    remove(path: PathType): void;
+    private isPathToRootFields;
+    private getDestinationFields;
+}
+
+/**
+ * Creates and configures a FieldRegistry with all the core field types.
+ * @returns {FieldRegistry} A pre-configured FieldRegistry instance.
+ */
+declare function createCoreFieldRegistry(): FieldRegistry;
+/**
+ * Creates and configures a PolicySerializer with handlers for core policies.
+ * @returns {PolicySerializer} A pre-configured PolicySerializer instance.
+ */
+declare function createCorePolicySerializer(): PolicySerializer;
+/**
+ * Creates a factory for CoreFieldTree and CoreFields nodes.
+ * @param {FieldRegistry} fieldRegistry - The registry to be used by the factory.
+ * @returns {CoreTreeNodeFactory} A new CoreTreeNodeFactory instance.
+ */
+declare function createCoreTreeNodeFactory(fieldRegistry: FieldRegistry): CoreTreeNodeFactory;
+/**
+ * Creates a fully configured serializer for a FieldTree.
+ * This function composes all necessary serializers (FieldTree, Fields, Field) for a complete setup.
+ * @param {CoreTreeNodeFactory} fieldTreeNodeFactory - The factory used to create new tree nodes during deserialization.
+ * @param policySerializer
+ * @returns {FieldTreeSerializer<CoreFields>} A top-level serializer for the entire field tree.
+ */
+declare function createCoreTreeSerializer(fieldTreeNodeFactory: CoreTreeNodeFactory, policySerializer?: PolicySerializer): FieldTreeSerializer<CoreFields>;
+interface CoreFieldSystemConfig {
+    registry?: FieldRegistry;
+    policySerializer?: PolicySerializer;
+}
+/**
+ * Creates a complete core setup for the field system.
+ * @returns {{factory: CoreTreeNodeFactory, serializer: FieldTreeSerializer<CoreFields>}}
+ */
+declare function createCoreFieldSystem(config?: CoreFieldSystemConfig): {
+    factory: CoreTreeNodeFactory;
+    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 };