@axi-engine/fields 0.1.0

package/dist/index.mjs

@@ -0,0 +1,614 @@
+// src/fields-types.ts
+var FieldsNodeType = /* @__PURE__ */ ((FieldsNodeType2) => {
+  FieldsNodeType2["fieldTree"] = "FieldTree";
+  FieldsNodeType2["fields"] = "Fields";
+  return FieldsNodeType2;
+})(FieldsNodeType || {});
+
+// src/field-policies.ts
+var _ClampPolicy = class _ClampPolicy {
+  constructor(min, max) {
+    this.min = min;
+    this.max = max;
+    this.id = _ClampPolicy.id;
+  }
+  apply(val) {
+    return Math.max(this.min, Math.min(this.max, val));
+  }
+  updateBounds(min, max) {
+    this.min = min;
+    this.max = max;
+  }
+};
+_ClampPolicy.id = "clamp";
+var ClampPolicy = _ClampPolicy;
+var _ClampMinPolicy = class _ClampMinPolicy {
+  constructor(min) {
+    this.min = min;
+    this.id = _ClampMinPolicy.id;
+  }
+  apply(val) {
+    return Math.max(this.min, val);
+  }
+  updateBounds(min) {
+    this.min = min;
+  }
+};
+_ClampMinPolicy.id = "clampMin";
+var ClampMinPolicy = _ClampMinPolicy;
+var _ClampMaxPolicy = class _ClampMaxPolicy {
+  constructor(max) {
+    this.max = max;
+    this.id = _ClampMaxPolicy.id;
+  }
+  apply(val) {
+    return Math.min(this.max, val);
+  }
+  updateBounds(max) {
+    this.max = max;
+  }
+};
+_ClampMaxPolicy.id = "clampMax";
+var ClampMaxPolicy = _ClampMaxPolicy;
+function clampPolicy(min, max) {
+  return new ClampPolicy(min, max);
+}
+function clampMinPolicy(min) {
+  return new ClampMinPolicy(min);
+}
+function clampMaxPolicy(max) {
+  return new ClampMaxPolicy(max);
+}
+
+// src/field.ts
+import { signal } from "@preact/signals-core";
+var Field = class {
+  /**
+   * 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, initialVal, options) {
+    this.policies = /* @__PURE__ */ new Map();
+    this._val = signal(initialVal);
+    this.name = name;
+    options?.policies?.forEach((policy) => this.policies.set(policy.id, policy));
+    this.set(initialVal);
+  }
+  /**
+   * Gets the current raw value of the field.
+   * For reactive updates, it's recommended to use the `.signal` property instead.
+   */
+  get val() {
+    return this._val.value;
+  }
+  /**
+   * Provides readonly access to the underlying Preact Signal.
+   * Subscribe to this signal to react to value changes.
+   */
+  get signal() {
+    return this._val;
+  }
+  /**
+   * 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) {
+    let finalVal = val;
+    this.policies.forEach((policy) => finalVal = policy.apply(finalVal));
+    this._val.value = finalVal;
+  }
+  /**
+   * 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(id) {
+    return this.policies.get(id);
+  }
+  /**
+   * 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) {
+    const existed = this.policies.get(policy.id);
+    existed?.destroy?.();
+    this.policies.set(policy.id, policy);
+  }
+  /**
+   * 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) {
+    const policyToRemove = this.policies.get(policyId);
+    if (!policyToRemove) {
+      return false;
+    }
+    policyToRemove.destroy?.();
+    return this.policies.delete(policyId);
+  }
+  /**
+   * Removes all policies from the field.
+   * After this, `set()` will no longer apply any transformations to the value until new policies are added.
+   */
+  clearPolicies() {
+    this.policies.forEach((policy) => policy.destroy?.());
+    this.policies.clear();
+  }
+  /**
+   * 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() {
+    this.set(this.val);
+  }
+  /**
+   * 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() {
+    this.clearPolicies();
+  }
+};
+
+// src/number-field.ts
+import { isNullOrUndefined } from "@axi-engine/utils";
+var NumberField = class extends Field {
+  get min() {
+    const policy = this.getPolicy(ClampPolicy.id) ?? this.getPolicy(ClampMinPolicy.id);
+    return policy?.min;
+  }
+  get max() {
+    const policy = this.getPolicy(ClampPolicy.id) ?? this.getPolicy(ClampMaxPolicy.id);
+    return policy?.max;
+  }
+  get isMin() {
+    const min = this.min;
+    return isNullOrUndefined(min) ? false : this.val <= min;
+  }
+  get isMax() {
+    const max = this.max;
+    return isNullOrUndefined(max) ? false : this.val >= max;
+  }
+  constructor(name, initialVal, options) {
+    const policies = options?.policies ?? [];
+    if (!isNullOrUndefined(options?.min) && !isNullOrUndefined(options?.max)) {
+      policies.unshift(clampPolicy(options.min, options.max));
+    } else if (!isNullOrUndefined(options?.min)) {
+      policies.unshift(clampMinPolicy(options.min));
+    } else if (!isNullOrUndefined(options?.max)) {
+      policies.unshift(clampMaxPolicy(options.max));
+    }
+    super(name, initialVal, { policies });
+  }
+  inc(amount = 1) {
+    this.set(this.val + amount);
+  }
+  dec(amount = 1) {
+    this.set(this.val - amount);
+  }
+};
+
+// src/base-fields.ts
+import { signal as signal2 } from "@preact/signals-core";
+import { AxiEventEmitter } from "@axi-engine/events";
+import { throwIf } from "@axi-engine/utils";
+var BaseFields = class {
+  constructor() {
+    this._fields = signal2(/* @__PURE__ */ new Map());
+    this.events = new AxiEventEmitter();
+  }
+  /**
+   * 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() {
+    return this._fields;
+  }
+  /**
+   * 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) {
+    return this._fields.value.has(name);
+  }
+  /**
+   * 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, initialValue) {
+    return this.add(new Field(name, initialValue));
+  }
+  /**
+   * 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) {
+    throwIf(this.has(field.name), `Field with name '${field.name}' already exists`);
+    const fieldsMap = new Map(this._fields.value);
+    fieldsMap.set(field.name, field);
+    this._fields.value = fieldsMap;
+    this.events.emit("created", {
+      fieldName: field.name,
+      field
+    });
+    return field;
+  }
+  /**
+   * 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) {
+    throwIf(!this._fields.value.has(name), `Field with name '${name}' not exists`);
+    return this._fields.value.get(name);
+  }
+  /**
+   * "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, value) {
+    if (this.has(name)) {
+      const field = this.get(name);
+      field.set(value);
+      return field;
+    }
+    return this.create(name, value);
+  }
+  /**
+   * 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) {
+    const namesToRemove = Array.isArray(names) ? names : [names];
+    const fieldsMap = new Map(this._fields.value);
+    const reallyRemoved = namesToRemove.filter((name) => {
+      const field = fieldsMap.get(name);
+      if (!field) {
+        return false;
+      }
+      field.destroy();
+      fieldsMap.delete(name);
+      return true;
+    });
+    if (!reallyRemoved.length) {
+      return;
+    }
+    this._fields.value = fieldsMap;
+    this.events.emit("removed", { fieldNames: reallyRemoved });
+  }
+  /**
+   * Removes all fields from the collection, ensuring each is properly destroyed.
+   */
+  clear() {
+    this.remove(Array.from(this._fields.value.keys()));
+  }
+  /**
+   * Creates a serializable snapshot of the current state of all fields.
+   * @returns A plain JavaScript object representing the values of all fields.
+   */
+  snapshot() {
+    const dump = {
+      __type: "Fields" /* fields */
+    };
+    this._fields.value.forEach((field, key) => dump[key] = field.val);
+    return dump;
+  }
+  /**
+   * 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) {
+    for (let key in snapshot) {
+      if (key === "__type") {
+        continue;
+      }
+      this.upset(key, snapshot[key]);
+    }
+  }
+};
+
+// src/fields.ts
+import { throwIf as throwIf2 } from "@axi-engine/utils";
+var Fields = class extends BaseFields {
+  createNumber(name, initialValue, options) {
+    return this.add(new NumberField(name, initialValue, options));
+  }
+  upsetNumber(name, value, options) {
+    if (this.has(name)) {
+      const field = this.getNumber(name);
+      field.set(value);
+      return field;
+    }
+    return this.createNumber(name, value, options);
+  }
+  getNumber(name) {
+    const field = this.get(name);
+    throwIf2(!(field instanceof NumberField), `wrong field type, field ${name} not a instance of NUmberField`);
+    return field;
+  }
+  create(name, initialValue) {
+    return this.add(new Field(name, initialValue));
+  }
+  upset(name, value) {
+    if (this.has(name)) {
+      const field = this.get(name);
+      field.set(value);
+      return field;
+    }
+    return this.create(name, value);
+  }
+  get(name) {
+    throwIf2(!this._fields.value.has(name), `Field with name '${name}' not exists`);
+    return this._fields.value.get(name);
+  }
+};
+
+// src/typed-fields.ts
+var TypedFields = class extends BaseFields {
+};
+
+// src/field-tree.ts
+import { signal as signal3 } from "@preact/signals-core";
+import { ensurePathArray, ensurePathString, throwIf as throwIf3, throwIfEmpty } from "@axi-engine/utils";
+import { AxiEventEmitter as AxiEventEmitter2 } from "@axi-engine/events";
+var FieldTree = class _FieldTree {
+  constructor() {
+    this.events = new AxiEventEmitter2();
+    this._items = signal3(/* @__PURE__ */ new Map());
+  }
+  /**
+   * 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() {
+    return this._items;
+  }
+  /**
+   * 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) {
+    const pathParts = ensurePathArray(path);
+    let currentNode = this;
+    for (let i = 0; i < pathParts.length; i++) {
+      const part = pathParts[i];
+      const nextNode = currentNode._items.value.get(part);
+      if (!nextNode) {
+        return false;
+      }
+      if (nextNode instanceof BaseFields) {
+        if (i === pathParts.length - 1) {
+          return true;
+        }
+        throwIf3(
+          pathParts.length - i > 2,
+          `Path validation failed, full path: ${ensurePathString(path)}, has extra nodes after Fields placed at: ${ensurePathString(pathParts.slice(0, i + 1))}`
+        );
+        return nextNode.has(pathParts[i + 1]);
+      }
+      currentNode = nextNode;
+    }
+    return true;
+  }
+  /**
+   * 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) {
+    const node = this.getNode(name);
+    throwIf3(!(node instanceof _FieldTree), `Node '${name}' should be instance of FieldTree`);
+    return node;
+  }
+  /**
+   * 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) {
+    const node = this.getNode(name);
+    throwIf3(!(node instanceof Fields), `Node '${name}' should be instance of Fields`);
+    return node;
+  }
+  /**
+   * 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(name) {
+    const node = this.getNode(name);
+    throwIf3(!(node instanceof TypedFields), `Node '${name}' should be instance of TypedFields`);
+    return node;
+  }
+  /**
+   * 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) {
+    const node = this._items.value.get(name);
+    throwIfEmpty(node, `Can't find node with name '${name}'`);
+    return node;
+  }
+  /**
+   * 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) {
+    return this.createNode(name, _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) {
+    return this.createNode(name, 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(name) {
+    return this.createNode(name, TypedFields);
+  }
+  /**
+   * 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) {
+    const pathParts = ensurePathArray(path);
+    throwIf3(!pathParts.length, "Empty path");
+    let container = this;
+    for (let i = 0; i < pathParts.length - 1; i++) {
+      container = container.getFieldTree(pathParts[i]);
+    }
+    return container.getFields(pathParts[pathParts.length - 1]);
+  }
+  /**
+   * 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(path, initialValue) {
+    const fullPath = [...ensurePathArray(path)];
+    const fieldName = fullPath.pop();
+    throwIf3(!fullPath.length, `Wrong path format of one field creating: '${ensurePathString(path)}', should be at least two sections`);
+    return this.getFieldsByPath(fullPath).create(fieldName, initialValue);
+  }
+  /**
+   * 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, initialValue) {
+    const fullPath = [...ensurePathArray(path)];
+    const fieldName = fullPath.pop();
+    return this.getFieldsByPath(fullPath).createNumber(fieldName, initialValue);
+  }
+  /**
+   * 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(path) {
+    const fullPath = [...ensurePathArray(path)];
+    const fieldName = fullPath.pop();
+    return this.getFieldsByPath(fullPath).get(fieldName);
+  }
+  /**
+   * 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) {
+    const fullPath = [...ensurePathArray(path)];
+    const fieldName = fullPath.pop();
+    return this.getFieldsByPath(fullPath).getNumber(fieldName);
+  }
+  /**
+   * 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() {
+    const dump = {
+      __type: "FieldTree" /* fieldTree */
+    };
+    this._items.value.forEach((node, key) => dump[key] = node.snapshot());
+    return dump;
+  }
+  /**
+   * 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) {
+    for (const key in snapshot) {
+      if (key === "__type") {
+        continue;
+      }
+      const field = snapshot[key];
+      const type = field?.__type;
+      let node = this._items.value.get(key);
+      if (!node) {
+        if (type === "Fields" /* fields */) {
+          node = this.createFields(key);
+        } else if (type === "FieldTree" /* fieldTree */) {
+          node = this.createFieldTree(key);
+        } else {
+          console.warn(`Node '${key}' in snapshot has no __type metadata. Skipping.`);
+        }
+      }
+      node?.hydrate(field);
+    }
+  }
+  /**
+   * @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.
+   */
+  createNode(name, ctor) {
+    const currentItems = this._items.value;
+    throwIf3(currentItems.has(name), `Can't create node with name: '${name}', node already exists`);
+    const res = new ctor();
+    const newItems = new Map(currentItems);
+    newItems.set(name, res);
+    this._items.value = newItems;
+    this.events.emit("created", {
+      type: "created",
+      name,
+      path: [],
+      // todo: need to decide how to pass full path
+      node: res
+    });
+    return res;
+  }
+};
+export {
+  BaseFields,
+  ClampMaxPolicy,
+  ClampMinPolicy,
+  ClampPolicy,
+  Field,
+  FieldTree,
+  Fields,
+  FieldsNodeType,
+  NumberField,
+  TypedFields,
+  clampMaxPolicy,
+  clampMinPolicy,
+  clampPolicy
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@axi-engine/fields",
+  "version": "0.1.0",
+  "description": "",
+  "license": "MIT",
+  "keywords": [
+    "axi-engine",
+    "typescript",
+    "gamedev",
+    "fields"
+  ],
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "docs": "typedoc src/index.ts --out docs/api --options ../../typedoc.json",
+    "test": "echo 'No tests yet for @axi-engine/fields'"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@preact/signals-core": "^1.12.1",
+    "@axi-engine/events": "*",
+    "@axi-engine/utils": "*"
+  }
+}