@axi-engine/fields 0.1.0

package/README.md

@@ -0,0 +1,24 @@
+# @axi-engine/fields
+
+[![NPM version](https://img.shields.io/npm/v/@axi-engine/utils.svg)](https://www.npmjs.com/package/@axi-engine/fields)
+
+
+A hierarchical, reactive state management library for Axi Engine, built on top of Preact Signals.
+
+## Description
+
+This package provides the core logic for creating, 
+managing, and observing the game state. 
+It allows you to structure your data in a tree-like hierarchy (FieldTree),
+where each piece of data (Field) is a reactive signal. 
+This is the central hub for all persistent game data, such as player stats, inventory, quest flags, and more.
+
+
+
+```bash
+npm install @axi-engine/fields
+```
+
+## API Reference
+
+Will be available when code and repository will be fully published 

package/dist/index.d.mts

@@ -0,0 +1,356 @@
+import { ReadonlySignal, Signal } from '@preact/signals-core';
+import { AxiEventEmitter } from '@axi-engine/events';
+import { PathType } from '@axi-engine/utils';
+
+declare const enum FieldsNodeType {
+    fieldTree = "FieldTree",
+    fields = "Fields"
+}
+
+interface FieldPolicy<T> {
+    readonly id: string;
+    apply: (val: T) => T;
+    destroy?: () => void;
+}
+declare class ClampPolicy implements FieldPolicy<number> {
+    min: number;
+    max: number;
+    static readonly id = "clamp";
+    readonly id = "clamp";
+    constructor(min: number, max: 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> {
+    max: number;
+    static readonly id = "clampMax";
+    readonly id = "clampMax";
+    constructor(max: 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> {
+    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;
+    /**
+     * Retrieves a specific policy instance by its ID.
+     * Useful for accessing a policy's internal state or methods.
+     * @template P The expected type of the policy.
+     * @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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    destroy(): void;
+}
+
+interface NumberFieldOptions {
+    min?: number;
+    max?: number;
+    policies?: FieldPolicy<number>[];
+}
+declare class NumberField extends Field<number> {
+    get min(): number | undefined;
+    get max(): number | undefined;
+    get isMin(): boolean;
+    get isMax(): boolean;
+    constructor(name: string, initialVal: number, options?: NumberFieldOptions);
+    inc(amount?: number): void;
+    dec(amount?: number): void;
+}
+
+/**
+ * An abstract base class for managing a reactive collection of `Field` instances.
+ *
+ * This class is designed to be the foundation for state management systems,
+ * such as managing stats, flags, or items.
+ *
+ * @template T The common base type for the values held by the fields in this collection.
+ */
+declare abstract class BaseFields<T> {
+    protected readonly _fields: Signal<Map<string, Field<T>>>;
+    readonly events: AxiEventEmitter<"created" | "removed">;
+    /**
+     * 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.
+     */
+    get fields(): ReadonlySignal<ReadonlyMap<string, Field<any>>>;
+    /**
+     * 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`.
+     */
+    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.
+     */
+    create(name: string, initialValue: T): Field<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.
+     */
+    add(field: Field<T>): Field<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.
+     */
+    get(name: string): Field<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.
+     */
+    upset(name: string, value: T): Field<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.
+     */
+    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 class TypedFields<T> extends BaseFields<T> {
+}
+
+/** 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;
+};
+/**
+ * Represents the global, persistent state of the entire game.
+ * This service 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.
+ *
+ * @todo:
+ * - add node removing
+ */
+declare class FieldTree {
+    private readonly _items;
+    readonly events: AxiEventEmitter<"created" | "removed">;
+    /**
+     * 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).
+     */
+    get items(): ReadonlySignal<ReadonlyMap<string, TreeOrFieldsContainer>>;
+    constructor();
+    /**
+     * 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.
+     */
+    hasPath(path: PathType): boolean;
+    /**
+     * 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`.
+     */
+    getFieldTree(name: string): FieldTree;
+    /**
+     * 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.
+     */
+    getFields(name: string): Fields;
+    /**
+     * 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.
+     */
+    getTypedFields<T>(name: string): TypedFields<T>;
+    /**
+     * 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.
+     * @throws If a node with the given name cannot be found.
+     */
+    getNode(name: string): TreeOrFieldsContainer;
+    /**
+     * 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.
+     */
+    createFieldTree(name: string): FieldTree;
+    /**
+     * 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.
+     */
+    createFields(name: string): Fields;
+    /**
+     * 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.
+     */
+    createTypedFields<T>(name: string): TypedFields<T>;
+    /**
+     * 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`.
+     */
+    getFieldsByPath(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.
+     */
+    create<T>(path: PathType, initialValue: T): Field<T>;
+    /**
+     * 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.
+     */
+    createNumber(path: PathType, initialValue: number): NumberField;
+    /**
+     * 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.
+     */
+    get<T>(path: PathType): Field<T>;
+    /**
+     * 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.
+     */
+    getNumber(path: PathType): NumberField;
+    /**
+     * 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>;
+    /**
+     * 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;
+}
+
+export { BaseFields, ClampMaxPolicy, ClampMinPolicy, ClampPolicy, Field, type FieldPolicy, FieldTree, type FieldTreeContainerEvent, Fields, FieldsNodeType, NumberField, type NumberFieldOptions, type TreeOrFieldsContainer, TypedFields, clampMaxPolicy, clampMinPolicy, clampPolicy };