@axi-engine/fields 0.3.3 → 0.3.4

package/dist/field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.js","sourceRoot":"","sources":["../src/field.ts"],"names":[],"mappings":""}

package/dist/fields-factory.d.ts

@@ -0,0 +1,5 @@
+import { Fields } from './fields';
+export interface FieldsFactory<TFields extends Fields> {
+    fields(): TFields;
+}
+//# sourceMappingURL=fields-factory.d.ts.map

package/dist/fields-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields-factory.d.ts","sourceRoot":"","sources":["../src/fields-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,MAAM,EAAC,MAAM,UAAU,CAAC;AAEhC,MAAM,WAAW,aAAa,CAAC,OAAO,SAAS,MAAM;IACnD,MAAM,IAAI,OAAO,CAAC;CACnB"}

package/dist/fields-factory.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fields-factory.js.map

package/dist/fields-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields-factory.js","sourceRoot":"","sources":["../src/fields-factory.ts"],"names":[],"mappings":""}

package/dist/fields.d.ts

@@ -0,0 +1,101 @@
+import { Emitter } from '@axi-engine/utils';
+import { FieldRegistry } from './field-registry';
+import { Field } from './field';
+/**
+ * A container for a collection of named `Field` instances.
+ *
+ * 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.
+ */
+export 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>>;
+    /**
+     * Creates an instance of Fields.
+     * @param {FieldRegistry} fieldRegistry - The registry used to create new `Field` instances.
+     */
+    constructor(fieldRegistry: FieldRegistry);
+    /**
+     * Checks if a field with the given name exists in the collection.
+     * @param {string} name The name of the field to check.
+     * @returns {boolean} `true` if the field exists, otherwise `false`.
+     */
+    has(name: string): boolean;
+    /**
+     * 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.
+     */
+    add<T extends Field<any>>(field: Field<any>): T;
+    /**
+     * 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.
+     */
+    create<T extends Field<any>>(typeName: string, name: string, initialValue: any, options?: any): T;
+    /**
+     * 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.
+     */
+    upset<T extends Field<any>>(typeName: string, name: string, value: any, options?: any): T;
+    /**
+     * Retrieves a field by its name.
+     * @template TField - The expected `Field` type to be returned.
+     * @param {string} name - The name of the field to retrieve.
+     * @returns {TField} The `Field` instance.
+     * @throws If the field does not exist.
+     */
+    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.
+     * @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;
+    destroy(): void;
+}
+//# sourceMappingURL=fields.d.ts.map

package/dist/fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,OAAO,EAAU,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAC,KAAK,EAAC,MAAM,SAAS,CAAC;AAE9B;;;;;;GAMG;AACH,qBAAa,MAAM;IACjB,MAAM,CAAC,QAAQ,CAAC,QAAQ,YAAY;IACpC,QAAQ,CAAC,QAAQ,YAAmB;IAEpC,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAa;IACtD,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC;IAEvC;;;;;;OAMG;IACH,KAAK;cACG,MAAM;eACL,KAAK,CAAC,GAAG,CAAC;QACb;IAEN;;;;;OAKG;IACH,QAAQ;eACC,MAAM,EAAE;QACX;IAEN;;;OAGG;IACH,IAAI,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAEpC;IAED;;;OAGG;gBACS,aAAa,EAAE,aAAa;IAIxC;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;IAa/C;;;;;;;;;OASG;IACH,MAAM,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,EACzB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,GAAG,EACjB,OAAO,CAAC,EAAE,GAAG,GACZ,CAAC;IAOJ;;;;;;;;OAQG;IACH,KAAK,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,EACxB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,EACV,OAAO,CAAC,EAAE,GAAG,GACZ,CAAC;IASJ;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,SAAS,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAKpD;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE;IAkB/B;;OAEG;IACH,KAAK;IAIL,OAAO;CAKR"}

package/dist/fields.js

@@ -0,0 +1,143 @@
+import { Emitter, throwIf } from '@axi-engine/utils';
+/**
+ * A container for a collection of named `Field` instances.
+ *
+ * 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.
+ */
+export class Fields {
+    static typeName = 'fields';
+    typeName = Fields.typeName;
+    _fields = new Map();
+    _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 = new Emitter();
+    /**
+     * 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 = new Emitter();
+    /**
+     * Gets the read-only map of all `Field` instances in this container.
+     * @returns {Map<string, Field<any>>} The collection of fields.
+     */
+    get fields() {
+        return this._fields;
+    }
+    /**
+     * Creates an instance of Fields.
+     * @param {FieldRegistry} fieldRegistry - The registry used to create new `Field` instances.
+     */
+    constructor(fieldRegistry) {
+        this._fieldRegistry = fieldRegistry;
+    }
+    /**
+     * Checks if a field with the given name exists in the collection.
+     * @param {string} name The name of the field to check.
+     * @returns {boolean} `true` if the field exists, otherwise `false`.
+     */
+    has(name) {
+        return this._fields.has(name);
+    }
+    /**
+     * 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.
+     */
+    add(field) {
+        throwIf(this.has(field.name), `Field with name '${field.name}' already exists`);
+        this._fields.set(field.name, field);
+        this.onAdd.emit({
+            name: field.name,
+            field: field
+        });
+        return field;
+    }
+    /**
+     * 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.
+     */
+    create(typeName, name, initialValue, options) {
+        const Ctor = this._fieldRegistry.get(typeName);
+        const field = new Ctor(name, initialValue, options);
+        this.add(field);
+        return field;
+    }
+    /**
+     * 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.
+     */
+    upset(typeName, name, value, options) {
+        if (this.has(name)) {
+            const field = this.get(name);
+            field.value = value;
+            return field;
+        }
+        return this.create(typeName, name, value, options);
+    }
+    /**
+     * Retrieves a field by its name.
+     * @template TField - The expected `Field` type to be returned.
+     * @param {string} name - The name of the field to retrieve.
+     * @returns {TField} The `Field` instance.
+     * @throws If the field does not exist.
+     */
+    get(name) {
+        throwIf(!this._fields.has(name), `Field with name '${name}' not exists`);
+        return this._fields.get(name);
+    }
+    /**
+     * 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 {string| string[]} names A single name or an array of names to remove.
+     */
+    remove(names) {
+        const namesToRemove = Array.isArray(names) ? names : [names];
+        const reallyRemoved = namesToRemove.filter(name => {
+            const field = this._fields.get(name);
+            if (!field) {
+                return false;
+            }
+            field.destroy();
+            return this._fields.delete(name);
+        });
+        if (!reallyRemoved.length) {
+            return;
+        }
+        this.onRemove.emit({ names: reallyRemoved });
+    }
+    /**
+     * Removes all fields from the collection, ensuring each is properly destroyed.
+     */
+    clear() {
+        this.remove(Array.from(this._fields.keys()));
+    }
+    destroy() {
+        this.clear();
+        this.onAdd.clear();
+        this.onRemove.clear();
+    }
+}
+//# sourceMappingURL=fields.js.map

package/dist/fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.js","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"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"}