@axi-engine/fields 0.3.3 → 0.3.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/core-field-tree-factory.d.ts +13 -0
- package/dist/core-field-tree-factory.d.ts.map +1 -0
- package/dist/core-field-tree-factory.js +14 -0
- package/dist/core-field-tree-factory.js.map +1 -0
- package/dist/core-field-tree.d.ts +5 -0
- package/dist/core-field-tree.d.ts.map +1 -0
- package/dist/core-field-tree.js +4 -0
- package/dist/core-field-tree.js.map +1 -0
- package/dist/core-fields-factory.d.ts +10 -0
- package/dist/core-fields-factory.d.ts.map +1 -0
- package/dist/core-fields-factory.js +14 -0
- package/dist/core-fields-factory.js.map +1 -0
- package/dist/core-fields.d.ts +47 -0
- package/dist/core-fields.d.ts.map +1 -0
- package/dist/core-fields.js +8 -0
- package/dist/core-fields.js.map +1 -0
- package/dist/data-store-field-resolver.d.ts +26 -0
- package/dist/data-store-field-resolver.d.ts.map +1 -0
- package/dist/data-store-field-resolver.js +21 -0
- package/dist/data-store-field-resolver.js.map +1 -0
- package/dist/data-store.d.ts +38 -0
- package/dist/data-store.d.ts.map +1 -0
- package/dist/data-store.js +141 -0
- package/dist/data-store.js.map +1 -0
- package/dist/field-definitions/core-boolean-field.d.ts +11 -0
- package/dist/field-definitions/core-boolean-field.d.ts.map +1 -0
- package/dist/field-definitions/core-boolean-field.js +13 -0
- package/dist/field-definitions/core-boolean-field.js.map +1 -0
- package/dist/field-definitions/core-field.d.ts +51 -0
- package/dist/field-definitions/core-field.d.ts.map +1 -0
- package/dist/field-definitions/core-field.js +74 -0
- package/dist/field-definitions/core-field.js.map +1 -0
- package/dist/field-definitions/core-numeric-field.d.ts +18 -0
- package/dist/field-definitions/core-numeric-field.d.ts.map +1 -0
- package/dist/field-definitions/core-numeric-field.js +45 -0
- package/dist/field-definitions/core-numeric-field.js.map +1 -0
- package/dist/field-definitions/core-string-field.d.ts +15 -0
- package/dist/field-definitions/core-string-field.d.ts.map +1 -0
- package/dist/field-definitions/core-string-field.js +27 -0
- package/dist/field-definitions/core-string-field.js.map +1 -0
- package/dist/field-definitions/index.d.ts +5 -0
- package/dist/field-definitions/index.d.ts.map +1 -0
- package/dist/field-definitions/index.js +5 -0
- package/dist/field-definitions/index.js.map +1 -0
- package/dist/field-registry.d.ts +5 -0
- package/dist/field-registry.d.ts.map +1 -0
- package/dist/field-registry.js +4 -0
- package/dist/field-registry.js.map +1 -0
- package/dist/field-tree-factory.d.ts +12 -0
- package/dist/field-tree-factory.d.ts.map +1 -0
- package/dist/field-tree-factory.js +2 -0
- package/dist/field-tree-factory.js.map +1 -0
- package/dist/field-tree.d.ts +171 -0
- package/dist/field-tree.d.ts.map +1 -0
- package/dist/field-tree.js +248 -0
- package/dist/field-tree.js.map +1 -0
- package/dist/field.d.ts +34 -0
- package/dist/field.d.ts.map +1 -0
- package/dist/field.js +2 -0
- package/dist/field.js.map +1 -0
- package/dist/fields-factory.d.ts +5 -0
- package/dist/fields-factory.d.ts.map +1 -0
- package/dist/fields-factory.js +2 -0
- package/dist/fields-factory.js.map +1 -0
- package/dist/fields.d.ts +101 -0
- package/dist/fields.d.ts.map +1 -0
- package/dist/fields.js +143 -0
- package/dist/fields.js.map +1 -0
- package/dist/index.d.mts +794 -815
- package/dist/index.d.ts +18 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +18 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +1084 -1116
- package/dist/mixins/mixin-factory.d.ts +29 -0
- package/dist/mixins/mixin-factory.d.ts.map +1 -0
- package/dist/mixins/mixin-factory.js +32 -0
- package/dist/mixins/mixin-factory.js.map +1 -0
- package/dist/mixins/with-boolean-fields.mixin.d.ts +9 -0
- package/dist/mixins/with-boolean-fields.mixin.d.ts.map +1 -0
- package/dist/mixins/with-boolean-fields.mixin.js +4 -0
- package/dist/mixins/with-boolean-fields.mixin.js.map +1 -0
- package/dist/mixins/with-default-generic-fields.mixin.d.ts +31 -0
- package/dist/mixins/with-default-generic-fields.mixin.d.ts.map +1 -0
- package/dist/mixins/with-default-generic-fields.mixin.js +15 -0
- package/dist/mixins/with-default-generic-fields.mixin.js.map +1 -0
- package/dist/mixins/with-numeric-fields.mixin.d.ts +9 -0
- package/dist/mixins/with-numeric-fields.mixin.d.ts.map +1 -0
- package/dist/mixins/with-numeric-fields.mixin.js +4 -0
- package/dist/mixins/with-numeric-fields.mixin.js.map +1 -0
- package/dist/mixins/with-string-fields.mixin.d.ts +9 -0
- package/dist/mixins/with-string-fields.mixin.d.ts.map +1 -0
- package/dist/mixins/with-string-fields.mixin.js +4 -0
- package/dist/mixins/with-string-fields.mixin.js.map +1 -0
- package/dist/policies/clamp-max-policy.d.ts +11 -0
- package/dist/policies/clamp-max-policy.d.ts.map +1 -0
- package/dist/policies/clamp-max-policy.js +18 -0
- package/dist/policies/clamp-max-policy.js.map +1 -0
- package/dist/policies/clamp-min-policy.d.ts +11 -0
- package/dist/policies/clamp-min-policy.d.ts.map +1 -0
- package/dist/policies/clamp-min-policy.js +18 -0
- package/dist/policies/clamp-min-policy.js.map +1 -0
- package/dist/policies/clamp-policy.d.ts +12 -0
- package/dist/policies/clamp-policy.d.ts.map +1 -0
- package/dist/policies/clamp-policy.js +21 -0
- package/dist/policies/clamp-policy.js.map +1 -0
- package/dist/policies/index.d.ts +6 -0
- package/dist/policies/index.d.ts.map +1 -0
- package/dist/policies/index.js +6 -0
- package/dist/policies/index.js.map +1 -0
- package/dist/policies/policies.d.ts +38 -0
- package/dist/policies/policies.d.ts.map +1 -0
- package/dist/policies/policies.js +62 -0
- package/dist/policies/policies.js.map +1 -0
- package/dist/policies/policy.d.ts +6 -0
- package/dist/policies/policy.d.ts.map +1 -0
- package/dist/policies/policy.js +2 -0
- package/dist/policies/policy.js.map +1 -0
- package/dist/serializer/field-serializer.d.ts +52 -0
- package/dist/serializer/field-serializer.d.ts.map +1 -0
- package/dist/serializer/field-serializer.js +66 -0
- package/dist/serializer/field-serializer.js.map +1 -0
- package/dist/serializer/field-tree-serializer.d.ts +50 -0
- package/dist/serializer/field-tree-serializer.d.ts.map +1 -0
- package/dist/serializer/field-tree-serializer.js +68 -0
- package/dist/serializer/field-tree-serializer.js.map +1 -0
- package/dist/serializer/fields-serializer.d.ts +49 -0
- package/dist/serializer/fields-serializer.d.ts.map +1 -0
- package/dist/serializer/fields-serializer.js +57 -0
- package/dist/serializer/fields-serializer.js.map +1 -0
- package/dist/serializer/index.d.ts +8 -0
- package/dist/serializer/index.d.ts.map +1 -0
- package/dist/serializer/index.js +8 -0
- package/dist/serializer/index.js.map +1 -0
- package/dist/serializer/policies/clamp-max-policy-serializer-handler.d.ts +13 -0
- package/dist/serializer/policies/clamp-max-policy-serializer-handler.d.ts.map +1 -0
- package/dist/serializer/policies/clamp-max-policy-serializer-handler.js +10 -0
- package/dist/serializer/policies/clamp-max-policy-serializer-handler.js.map +1 -0
- package/dist/serializer/policies/clamp-min-policy-serializer-handler.d.ts +13 -0
- package/dist/serializer/policies/clamp-min-policy-serializer-handler.d.ts.map +1 -0
- package/dist/serializer/policies/clamp-min-policy-serializer-handler.js +10 -0
- package/dist/serializer/policies/clamp-min-policy-serializer-handler.js.map +1 -0
- package/dist/serializer/policies/clamp-policy-serializer-handler.d.ts +16 -0
- package/dist/serializer/policies/clamp-policy-serializer-handler.d.ts.map +1 -0
- package/dist/serializer/policies/clamp-policy-serializer-handler.js +10 -0
- package/dist/serializer/policies/clamp-policy-serializer-handler.js.map +1 -0
- package/dist/serializer/policy-serializer.d.ts +41 -0
- package/dist/serializer/policy-serializer.d.ts.map +1 -0
- package/dist/serializer/policy-serializer.js +43 -0
- package/dist/serializer/policy-serializer.js.map +1 -0
- package/dist/setup.d.ts +41 -0
- package/dist/setup.d.ts.map +1 -0
- package/dist/setup.js +57 -0
- package/dist/setup.js.map +1 -0
- package/dist/store.d.ts +137 -0
- package/dist/store.d.ts.map +1 -0
- package/dist/store.js +2 -0
- package/dist/store.js.map +1 -0
- package/package.json +44 -44
- package/dist/index.cjs +0 -1232
- package/dist/index.d.cts +0 -1018
- package/dist/index.d.cts.map +0 -1
- package/dist/index.d.mts.map +0 -1
- package/dist/index.mjs.map +0 -1
package/dist/index.d.mts
CHANGED
|
@@ -1,86 +1,213 @@
|
|
|
1
|
-
import * as
|
|
2
|
-
import {
|
|
1
|
+
import * as _axi_engine_utils from '@axi-engine/utils';
|
|
2
|
+
import { Subscribable, ConstructorRegistry, Emitter, Constructor, PathType } from '@axi-engine/utils';
|
|
3
3
|
|
|
4
|
-
//#region src/policies/policy.d.ts
|
|
5
4
|
interface Policy<T> {
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
5
|
+
readonly id: string;
|
|
6
|
+
apply: (val: T) => T;
|
|
7
|
+
destroy?: () => void;
|
|
9
8
|
}
|
|
10
|
-
|
|
11
|
-
//#region src/policies/clamp-policy.d.ts
|
|
9
|
+
|
|
12
10
|
declare class ClampPolicy implements Policy<number> {
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
11
|
+
min: number;
|
|
12
|
+
max: number;
|
|
13
|
+
static readonly id = "clamp";
|
|
14
|
+
readonly id = "clamp";
|
|
15
|
+
constructor(min: number, max: number);
|
|
16
|
+
apply(val: number): number;
|
|
17
|
+
updateBounds(min: number, max: number): void;
|
|
20
18
|
}
|
|
21
19
|
declare function clampPolicy(min: number, max: number): ClampPolicy;
|
|
22
|
-
|
|
23
|
-
//#region src/policies/clamp-max-policy.d.ts
|
|
20
|
+
|
|
24
21
|
declare class ClampMaxPolicy implements Policy<number> {
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
22
|
+
max: number;
|
|
23
|
+
static readonly id = "clampMax";
|
|
24
|
+
readonly id = "clampMax";
|
|
25
|
+
constructor(max: number);
|
|
26
|
+
apply(val: number): number;
|
|
27
|
+
updateBounds(max: number): void;
|
|
31
28
|
}
|
|
32
29
|
declare function clampMaxPolicy(max: number): ClampMaxPolicy;
|
|
33
|
-
|
|
34
|
-
//#region src/policies/clamp-min-policy.d.ts
|
|
30
|
+
|
|
35
31
|
declare class ClampMinPolicy implements Policy<number> {
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
32
|
+
min: number;
|
|
33
|
+
static readonly id = "clampMin";
|
|
34
|
+
readonly id = "clampMin";
|
|
35
|
+
constructor(min: number);
|
|
36
|
+
apply(val: number): number;
|
|
37
|
+
updateBounds(min: number): void;
|
|
42
38
|
}
|
|
43
39
|
declare function clampMinPolicy(min: number): ClampMinPolicy;
|
|
44
|
-
|
|
45
|
-
//#region src/policies/policies.d.ts
|
|
40
|
+
|
|
46
41
|
declare class Policies<T> {
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
}
|
|
82
|
-
|
|
83
|
-
|
|
42
|
+
private readonly policies;
|
|
43
|
+
get items(): Map<string, Policy<T>>;
|
|
44
|
+
/**
|
|
45
|
+
* Retrieves a specific policy instance by its ID.
|
|
46
|
+
* Useful for accessing a policy's internal state or methods.
|
|
47
|
+
* @template P The expected type of the policy.
|
|
48
|
+
* @param id The unique ID of the policy to retrieve.
|
|
49
|
+
* @returns The policy instance, or `undefined` if not found.
|
|
50
|
+
*/
|
|
51
|
+
get<P extends Policy<T>>(id: string): P | undefined;
|
|
52
|
+
/**
|
|
53
|
+
* Adds a new policy to the field or replaces an existing one with the same ID.
|
|
54
|
+
* The new policy will be applied on the next `set()` operation.
|
|
55
|
+
* If a policy with the same ID already exists, its `destroy` method will be called before it is replaced.
|
|
56
|
+
* @param policy The policy instance to add.
|
|
57
|
+
*/
|
|
58
|
+
add(policy: Policy<T>): this;
|
|
59
|
+
/**
|
|
60
|
+
* Removes a policy from the field by its ID and call `destroy` method.
|
|
61
|
+
* @param policyId The unique ID of the policy to remove.
|
|
62
|
+
* @returns `true` if the policy was found and removed, otherwise `false`.
|
|
63
|
+
*/
|
|
64
|
+
remove(policyId: string): boolean;
|
|
65
|
+
isEmpty(): boolean;
|
|
66
|
+
/**
|
|
67
|
+
* Removes all policies from the field.
|
|
68
|
+
* After this, `set()` will no longer apply any transformations to the value until new policies are added.
|
|
69
|
+
*/
|
|
70
|
+
clear(): void;
|
|
71
|
+
/**
|
|
72
|
+
* Forces the current value to be re-processed by all policies.
|
|
73
|
+
* Useful if a policy's logic has changed and you need to re-evaluate the current state.
|
|
74
|
+
*/
|
|
75
|
+
apply(val: T): T;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
interface FieldOptions<T> {
|
|
79
|
+
policies?: Policy<T>[];
|
|
80
|
+
}
|
|
81
|
+
interface Field<T> {
|
|
82
|
+
readonly typeName: string;
|
|
83
|
+
readonly name: string;
|
|
84
|
+
value: T;
|
|
85
|
+
policies: Policies<T>;
|
|
86
|
+
setValueSilently(val: T): void;
|
|
87
|
+
batchUpdate(updateFn: (currentValue: T) => T): void;
|
|
88
|
+
onChange: Subscribable<[newValue: T, oldValue: T]>;
|
|
89
|
+
destroy(): void;
|
|
90
|
+
}
|
|
91
|
+
interface NumericField extends Field<number> {
|
|
92
|
+
readonly min: number | undefined;
|
|
93
|
+
readonly max: number | undefined;
|
|
94
|
+
isMin(): boolean;
|
|
95
|
+
isMax(): boolean;
|
|
96
|
+
inc(val: number): void;
|
|
97
|
+
dec(val: number): void;
|
|
98
|
+
}
|
|
99
|
+
interface BooleanField extends Field<boolean> {
|
|
100
|
+
toggle(): boolean;
|
|
101
|
+
}
|
|
102
|
+
interface StringField extends Field<string> {
|
|
103
|
+
append(str: string | number): this;
|
|
104
|
+
prepend(str: string | number): this;
|
|
105
|
+
trim(): this;
|
|
106
|
+
isEmpty(): boolean;
|
|
107
|
+
clear(): void;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
declare class FieldRegistry extends ConstructorRegistry<Field<any>> {
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* A container for a collection of named `Field` instances.
|
|
115
|
+
*
|
|
116
|
+
* This class acts as a "leaf" node in the `FieldTree` hierarchy, managing a flat
|
|
117
|
+
* key-value store of reactive data points. It uses a `FieldRegistry` to dynamically
|
|
118
|
+
* create `Field` instances of different types.
|
|
119
|
+
*/
|
|
120
|
+
declare class Fields {
|
|
121
|
+
static readonly typeName = "fields";
|
|
122
|
+
readonly typeName = "fields";
|
|
123
|
+
readonly _fields: Map<string, Field<any>>;
|
|
124
|
+
readonly _fieldRegistry: FieldRegistry;
|
|
125
|
+
/**
|
|
126
|
+
* An event emitter that fires when a new field is added to the collection.
|
|
127
|
+
* @event
|
|
128
|
+
* @param {object} event - The event payload.
|
|
129
|
+
* @param {string} event.name - The name of the added field.
|
|
130
|
+
* @param {Field<any>} event.field - The `Field` instance that was added.
|
|
131
|
+
*/
|
|
132
|
+
onAdd: Emitter<[event: {
|
|
133
|
+
name: string;
|
|
134
|
+
field: Field<any>;
|
|
135
|
+
}]>;
|
|
136
|
+
/**
|
|
137
|
+
* An event emitter that fires after one or more fields have been removed.
|
|
138
|
+
* @event
|
|
139
|
+
* @param {object} event - The event payload.
|
|
140
|
+
* @param {string[]} event.names - An array of names of the fields that were successfully removed.
|
|
141
|
+
*/
|
|
142
|
+
onRemove: Emitter<[event: {
|
|
143
|
+
names: string[];
|
|
144
|
+
}]>;
|
|
145
|
+
/**
|
|
146
|
+
* Gets the read-only map of all `Field` instances in this container.
|
|
147
|
+
* @returns {Map<string, Field<any>>} The collection of fields.
|
|
148
|
+
*/
|
|
149
|
+
get fields(): Map<string, Field<any>>;
|
|
150
|
+
/**
|
|
151
|
+
* Creates an instance of Fields.
|
|
152
|
+
* @param {FieldRegistry} fieldRegistry - The registry used to create new `Field` instances.
|
|
153
|
+
*/
|
|
154
|
+
constructor(fieldRegistry: FieldRegistry);
|
|
155
|
+
/**
|
|
156
|
+
* Checks if a field with the given name exists in the collection.
|
|
157
|
+
* @param {string} name The name of the field to check.
|
|
158
|
+
* @returns {boolean} `true` if the field exists, otherwise `false`.
|
|
159
|
+
*/
|
|
160
|
+
has(name: string): boolean;
|
|
161
|
+
/**
|
|
162
|
+
* Adds a pre-existing `Field` instance to the collection and fires the `onAdd` event.
|
|
163
|
+
* @template T - The specific `Field` type being added.
|
|
164
|
+
* @param {Field<any>} field - The `Field` instance to add.
|
|
165
|
+
* @returns {T} The added `Field` instance, cast to type `T`.
|
|
166
|
+
* @throws If a field with the same name already exists.
|
|
167
|
+
*/
|
|
168
|
+
add<T extends Field<any>>(field: Field<any>): T;
|
|
169
|
+
/**
|
|
170
|
+
* Creates a new `Field` instance of a specified type, adds it to the collection, and returns it.
|
|
171
|
+
* This is the primary factory method for creating fields within this container.
|
|
172
|
+
* @template T - The expected `Field` type to be returned.
|
|
173
|
+
* @param {string} typeName - The registered type name of the field to create (e.g., 'numeric', 'boolean').
|
|
174
|
+
* @param {string} name - The unique name for the new field.
|
|
175
|
+
* @param {*} initialValue - The initial value for the new field.
|
|
176
|
+
* @param {*} [options] - Optional configuration passed to the field's constructor.
|
|
177
|
+
* @returns {T} The newly created `Field` instance.
|
|
178
|
+
*/
|
|
179
|
+
create<T extends Field<any>>(typeName: string, name: string, initialValue: any, options?: any): T;
|
|
180
|
+
/**
|
|
181
|
+
* Updates an existing field's value or creates a new one if it doesn't exist.
|
|
182
|
+
* @template T - The expected `Field` type.
|
|
183
|
+
* @param {string} typeName - The type name to use if a new field needs to be created.
|
|
184
|
+
* @param {string} name - The name of the field to update or create.
|
|
185
|
+
* @param {*} value - The new value to set.
|
|
186
|
+
* @param {*} [options] - Optional configuration, used only if a new field is created.
|
|
187
|
+
* @returns {T} The existing or newly created `Field` instance.
|
|
188
|
+
*/
|
|
189
|
+
upset<T extends Field<any>>(typeName: string, name: string, value: any, options?: any): T;
|
|
190
|
+
/**
|
|
191
|
+
* Retrieves a field by its name.
|
|
192
|
+
* @template TField - The expected `Field` type to be returned.
|
|
193
|
+
* @param {string} name - The name of the field to retrieve.
|
|
194
|
+
* @returns {TField} The `Field` instance.
|
|
195
|
+
* @throws If the field does not exist.
|
|
196
|
+
*/
|
|
197
|
+
get<TField extends Field<any>>(name: string): TField;
|
|
198
|
+
/**
|
|
199
|
+
* Removes one or more fields from the collection.
|
|
200
|
+
* This method ensures that the `destroy` method of each removed field is called to clean up its resources.
|
|
201
|
+
* @param {string| string[]} names A single name or an array of names to remove.
|
|
202
|
+
*/
|
|
203
|
+
remove(names: string | string[]): void;
|
|
204
|
+
/**
|
|
205
|
+
* Removes all fields from the collection, ensuring each is properly destroyed.
|
|
206
|
+
*/
|
|
207
|
+
clear(): void;
|
|
208
|
+
destroy(): void;
|
|
209
|
+
}
|
|
210
|
+
|
|
84
211
|
/**
|
|
85
212
|
* extract field type
|
|
86
213
|
*/
|
|
@@ -89,7 +216,13 @@ type GetValueType<TField extends Field<any>> = TField extends Field<infer U> ? U
|
|
|
89
216
|
* A mapped type that creates the method signatures for a typed mixin.
|
|
90
217
|
* e.g., createBoolean, upsetBoolean, getBoolean
|
|
91
218
|
*/
|
|
92
|
-
type TypedMethods<TCtor extends Constructor<Field<any>>, TBaseName extends string> = {
|
|
219
|
+
type TypedMethods<TCtor extends Constructor<Field<any>>, TBaseName extends string> = {
|
|
220
|
+
[K in `create${TBaseName}`]: (name: string, initialValue: GetValueType<InstanceType<TCtor>>, options?: ConstructorParameters<TCtor>[2]) => InstanceType<TCtor>;
|
|
221
|
+
} & {
|
|
222
|
+
[K in `upset${TBaseName}`]: (name: string, value: GetValueType<InstanceType<TCtor>>, options?: ConstructorParameters<TCtor>[2]) => InstanceType<TCtor>;
|
|
223
|
+
} & {
|
|
224
|
+
[K in `get${TBaseName}`]: (name: string) => InstanceType<TCtor>;
|
|
225
|
+
};
|
|
93
226
|
/**
|
|
94
227
|
* A higher-order function that generates a mixin for a specific Field type.
|
|
95
228
|
* This factory removes the need to write boilerplate mixin code for every new field type.
|
|
@@ -99,41 +232,7 @@ type TypedMethods<TCtor extends Constructor<Field<any>>, TBaseName extends strin
|
|
|
99
232
|
* @returns A fully functional, typed mixin.
|
|
100
233
|
*/
|
|
101
234
|
declare function createTypedMethodsMixin<TCtor extends Constructor<Field<any>>, TBaseName extends string>(typeName: string, baseMethodName: TBaseName): <TBase extends Constructor<Fields>>(Base: TBase) => Constructor<InstanceType<TBase> & TypedMethods<TCtor, TBaseName>>;
|
|
102
|
-
|
|
103
|
-
//#region src/field.d.ts
|
|
104
|
-
interface FieldOptions<T> {
|
|
105
|
-
policies?: Policy<T>[];
|
|
106
|
-
}
|
|
107
|
-
interface Field<T> {
|
|
108
|
-
readonly typeName: string;
|
|
109
|
-
readonly name: string;
|
|
110
|
-
value: T;
|
|
111
|
-
policies: Policies<T>;
|
|
112
|
-
setValueSilently(val: T): void;
|
|
113
|
-
batchUpdate(updateFn: (currentValue: T) => T): void;
|
|
114
|
-
onChange: Subscribable<[newValue: T, oldValue: T]>;
|
|
115
|
-
destroy(): void;
|
|
116
|
-
}
|
|
117
|
-
interface NumericField extends Field<number> {
|
|
118
|
-
readonly min: number | undefined;
|
|
119
|
-
readonly max: number | undefined;
|
|
120
|
-
isMin(): boolean;
|
|
121
|
-
isMax(): boolean;
|
|
122
|
-
inc(val: number): void;
|
|
123
|
-
dec(val: number): void;
|
|
124
|
-
}
|
|
125
|
-
interface BooleanField extends Field<boolean> {
|
|
126
|
-
toggle(): boolean;
|
|
127
|
-
}
|
|
128
|
-
interface StringField extends Field<string> {
|
|
129
|
-
append(str: string | number): this;
|
|
130
|
-
prepend(str: string | number): this;
|
|
131
|
-
trim(): this;
|
|
132
|
-
isEmpty(): boolean;
|
|
133
|
-
clear(): void;
|
|
134
|
-
}
|
|
135
|
-
//#endregion
|
|
136
|
-
//#region src/field-definitions/core-field.d.ts
|
|
235
|
+
|
|
137
236
|
/**
|
|
138
237
|
* A state container that wraps a value.
|
|
139
238
|
* It allows applying a pipeline of transformation or validation "policies" before any new value is set.
|
|
@@ -142,203 +241,97 @@ interface StringField extends Field<string> {
|
|
|
142
241
|
*
|
|
143
242
|
*/
|
|
144
243
|
declare class CoreField<T> implements Field<T> {
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
}
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
244
|
+
/** A type keyword of the field */
|
|
245
|
+
static readonly typeName: string;
|
|
246
|
+
readonly typeName: string;
|
|
247
|
+
/** A unique identifier for the field. */
|
|
248
|
+
private readonly _name;
|
|
249
|
+
private _value;
|
|
250
|
+
private readonly _onChange;
|
|
251
|
+
readonly onChange: Subscribable<[newValue: T, oldvalue: T]>;
|
|
252
|
+
readonly policies: Policies<T>;
|
|
253
|
+
get name(): string;
|
|
254
|
+
/**
|
|
255
|
+
* Gets the current raw value of the field.
|
|
256
|
+
* For reactive updates, it's recommended to use the `.signal` property instead.
|
|
257
|
+
*/
|
|
258
|
+
get value(): T;
|
|
259
|
+
/**
|
|
260
|
+
* Sets a new value for the field.
|
|
261
|
+
* The provided value will be processed by all registered policies before the underlying signal is updated.
|
|
262
|
+
* @param val The new value to set.
|
|
263
|
+
*/
|
|
264
|
+
set value(val: T);
|
|
265
|
+
/**
|
|
266
|
+
* Creates an instance of a Field.
|
|
267
|
+
* @param name A unique identifier for the field.
|
|
268
|
+
* @param initialVal The initial value of the field.
|
|
269
|
+
* @param options Optional configuration for the field.
|
|
270
|
+
* @param options.policies An array of policies to apply to the field's value on every `set` operation.
|
|
271
|
+
* @param options.isEqual An function for compare old and new value, by default uses the strictEquals from `utils`
|
|
272
|
+
*
|
|
273
|
+
*/
|
|
274
|
+
constructor(name: string, initialVal: T, options?: FieldOptions<T>);
|
|
275
|
+
setValueSilently(val: T): void;
|
|
276
|
+
batchUpdate(updateFn: (currentValue: T) => T): void;
|
|
277
|
+
/**
|
|
278
|
+
* Cleans up resources used by the field and its policies.
|
|
279
|
+
* This should be called when the field is no longer needed to prevent memory leaks from reactive policies.
|
|
280
|
+
*/
|
|
281
|
+
destroy(): void;
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
interface CoreBooleanFieldOptions extends FieldOptions<boolean> {
|
|
285
|
+
}
|
|
187
286
|
declare class CoreBooleanField extends CoreField<boolean> implements BooleanField {
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
}
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
287
|
+
static readonly typeName: string;
|
|
288
|
+
readonly typeName: string;
|
|
289
|
+
constructor(name: string, initialVal: boolean, options?: CoreBooleanFieldOptions);
|
|
290
|
+
toggle(): boolean;
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
interface CoreStringFieldOptions extends FieldOptions<string> {
|
|
294
|
+
}
|
|
196
295
|
declare class CoreStringField extends CoreField<string> implements StringField {
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
}
|
|
206
|
-
|
|
207
|
-
//#region src/field-definitions/core-numeric-field.d.ts
|
|
296
|
+
static readonly typeName: string;
|
|
297
|
+
readonly typeName: string;
|
|
298
|
+
constructor(name: string, initialVal: string, options?: CoreStringFieldOptions);
|
|
299
|
+
append(str: string | number): this;
|
|
300
|
+
prepend(str: string | number): this;
|
|
301
|
+
trim(): this;
|
|
302
|
+
isEmpty(): boolean;
|
|
303
|
+
clear(): void;
|
|
304
|
+
}
|
|
305
|
+
|
|
208
306
|
interface CoreNumericFieldOptions extends FieldOptions<number> {
|
|
209
|
-
|
|
210
|
-
|
|
307
|
+
min?: number;
|
|
308
|
+
max?: number;
|
|
211
309
|
}
|
|
212
310
|
declare class CoreNumericField extends CoreField<number> implements NumericField {
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
}
|
|
223
|
-
|
|
224
|
-
//#region src/field-registry.d.ts
|
|
225
|
-
declare class FieldRegistry extends ConstructorRegistry<Field<any>> {}
|
|
226
|
-
//#endregion
|
|
227
|
-
//#region src/fields.d.ts
|
|
228
|
-
/**
|
|
229
|
-
* A container for a collection of named `Field` instances.
|
|
230
|
-
*
|
|
231
|
-
* This class acts as a "leaf" node in the `FieldTree` hierarchy, managing a flat
|
|
232
|
-
* key-value store of reactive data points. It uses a `FieldRegistry` to dynamically
|
|
233
|
-
* create `Field` instances of different types.
|
|
234
|
-
*/
|
|
235
|
-
declare class Fields {
|
|
236
|
-
static readonly typeName = "fields";
|
|
237
|
-
readonly typeName = "fields";
|
|
238
|
-
readonly _fields: Map<string, Field<any>>;
|
|
239
|
-
readonly _fieldRegistry: FieldRegistry;
|
|
240
|
-
/**
|
|
241
|
-
* An event emitter that fires when a new field is added to the collection.
|
|
242
|
-
* @event
|
|
243
|
-
* @param {object} event - The event payload.
|
|
244
|
-
* @param {string} event.name - The name of the added field.
|
|
245
|
-
* @param {Field<any>} event.field - The `Field` instance that was added.
|
|
246
|
-
*/
|
|
247
|
-
onAdd: Emitter<[event: {
|
|
248
|
-
name: string;
|
|
249
|
-
field: Field<any>;
|
|
250
|
-
}]>;
|
|
251
|
-
/**
|
|
252
|
-
* An event emitter that fires after one or more fields have been removed.
|
|
253
|
-
* @event
|
|
254
|
-
* @param {object} event - The event payload.
|
|
255
|
-
* @param {string[]} event.names - An array of names of the fields that were successfully removed.
|
|
256
|
-
*/
|
|
257
|
-
onRemove: Emitter<[event: {
|
|
258
|
-
names: string[];
|
|
259
|
-
}]>;
|
|
260
|
-
/**
|
|
261
|
-
* Gets the read-only map of all `Field` instances in this container.
|
|
262
|
-
* @returns {Map<string, Field<any>>} The collection of fields.
|
|
263
|
-
*/
|
|
264
|
-
get fields(): Map<string, Field<any>>;
|
|
265
|
-
/**
|
|
266
|
-
* Creates an instance of Fields.
|
|
267
|
-
* @param {FieldRegistry} fieldRegistry - The registry used to create new `Field` instances.
|
|
268
|
-
*/
|
|
269
|
-
constructor(fieldRegistry: FieldRegistry);
|
|
270
|
-
/**
|
|
271
|
-
* Checks if a field with the given name exists in the collection.
|
|
272
|
-
* @param {string} name The name of the field to check.
|
|
273
|
-
* @returns {boolean} `true` if the field exists, otherwise `false`.
|
|
274
|
-
*/
|
|
275
|
-
has(name: string): boolean;
|
|
276
|
-
/**
|
|
277
|
-
* Adds a pre-existing `Field` instance to the collection and fires the `onAdd` event.
|
|
278
|
-
* @template T - The specific `Field` type being added.
|
|
279
|
-
* @param {Field<any>} field - The `Field` instance to add.
|
|
280
|
-
* @returns {T} The added `Field` instance, cast to type `T`.
|
|
281
|
-
* @throws If a field with the same name already exists.
|
|
282
|
-
*/
|
|
283
|
-
add<T extends Field<any>>(field: Field<any>): T;
|
|
284
|
-
/**
|
|
285
|
-
* Creates a new `Field` instance of a specified type, adds it to the collection, and returns it.
|
|
286
|
-
* This is the primary factory method for creating fields within this container.
|
|
287
|
-
* @template T - The expected `Field` type to be returned.
|
|
288
|
-
* @param {string} typeName - The registered type name of the field to create (e.g., 'numeric', 'boolean').
|
|
289
|
-
* @param {string} name - The unique name for the new field.
|
|
290
|
-
* @param {*} initialValue - The initial value for the new field.
|
|
291
|
-
* @param {*} [options] - Optional configuration passed to the field's constructor.
|
|
292
|
-
* @returns {T} The newly created `Field` instance.
|
|
293
|
-
*/
|
|
294
|
-
create<T extends Field<any>>(typeName: string, name: string, initialValue: any, options?: any): T;
|
|
295
|
-
/**
|
|
296
|
-
* Updates an existing field's value or creates a new one if it doesn't exist.
|
|
297
|
-
* @template T - The expected `Field` type.
|
|
298
|
-
* @param {string} typeName - The type name to use if a new field needs to be created.
|
|
299
|
-
* @param {string} name - The name of the field to update or create.
|
|
300
|
-
* @param {*} value - The new value to set.
|
|
301
|
-
* @param {*} [options] - Optional configuration, used only if a new field is created.
|
|
302
|
-
* @returns {T} The existing or newly created `Field` instance.
|
|
303
|
-
*/
|
|
304
|
-
upset<T extends Field<any>>(typeName: string, name: string, value: any, options?: any): T;
|
|
305
|
-
/**
|
|
306
|
-
* Retrieves a field by its name.
|
|
307
|
-
* @template TField - The expected `Field` type to be returned.
|
|
308
|
-
* @param {string} name - The name of the field to retrieve.
|
|
309
|
-
* @returns {TField} The `Field` instance.
|
|
310
|
-
* @throws If the field does not exist.
|
|
311
|
-
*/
|
|
312
|
-
get<TField extends Field<any>>(name: string): TField;
|
|
313
|
-
/**
|
|
314
|
-
* Removes one or more fields from the collection.
|
|
315
|
-
* This method ensures that the `destroy` method of each removed field is called to clean up its resources.
|
|
316
|
-
* @param {string| string[]} names A single name or an array of names to remove.
|
|
317
|
-
*/
|
|
318
|
-
remove(names: string | string[]): void;
|
|
319
|
-
/**
|
|
320
|
-
* Removes all fields from the collection, ensuring each is properly destroyed.
|
|
321
|
-
*/
|
|
322
|
-
clear(): void;
|
|
323
|
-
destroy(): void;
|
|
324
|
-
}
|
|
325
|
-
//#endregion
|
|
326
|
-
//#region src/fields-factory.d.ts
|
|
311
|
+
static readonly typeName: string;
|
|
312
|
+
readonly typeName: string;
|
|
313
|
+
get min(): number | undefined;
|
|
314
|
+
get max(): number | undefined;
|
|
315
|
+
constructor(name: string, initialVal: number, options?: CoreNumericFieldOptions);
|
|
316
|
+
isMin(): boolean;
|
|
317
|
+
isMax(): boolean;
|
|
318
|
+
inc(amount?: number): void;
|
|
319
|
+
dec(amount?: number): void;
|
|
320
|
+
}
|
|
321
|
+
|
|
327
322
|
interface FieldsFactory<TFields extends Fields> {
|
|
328
|
-
|
|
323
|
+
fields(): TFields;
|
|
329
324
|
}
|
|
330
|
-
|
|
331
|
-
//#region src/field-tree-factory.d.ts
|
|
325
|
+
|
|
332
326
|
/**
|
|
333
327
|
* Defines the contract for a factory that creates nodes for a FieldTree.
|
|
334
328
|
* This allows for custom implementations of Fields and FieldTree to be used.
|
|
335
329
|
*/
|
|
336
330
|
interface FieldTreeFactory<TFields extends Fields> extends FieldsFactory<TFields> {
|
|
337
|
-
|
|
338
|
-
|
|
331
|
+
fields(): TFields;
|
|
332
|
+
tree(): FieldTree<TFields>;
|
|
339
333
|
}
|
|
340
|
-
|
|
341
|
-
//#region src/field-tree.d.ts
|
|
334
|
+
|
|
342
335
|
/** A type alias for any container that can be a child node in a FieldTree */
|
|
343
336
|
type TreeNode<F extends Fields> = FieldTree<F> | F;
|
|
344
337
|
/**
|
|
@@ -351,316 +344,309 @@ type TreeNode<F extends Fields> = FieldTree<F> | F;
|
|
|
351
344
|
*
|
|
352
345
|
*/
|
|
353
346
|
declare class FieldTree<TFields extends Fields> {
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
}
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
destroy(): void;
|
|
347
|
+
static readonly typeName = "fieldTree";
|
|
348
|
+
readonly typeName = "fieldTree";
|
|
349
|
+
/** @private The internal map storing child nodes (branches or leaves). */
|
|
350
|
+
private readonly _nodes;
|
|
351
|
+
/** @private The factory used to create new child nodes. */
|
|
352
|
+
private readonly _factory;
|
|
353
|
+
/**
|
|
354
|
+
* An event emitter that fires immediately after a new node is added to this tree branch.
|
|
355
|
+
* @event
|
|
356
|
+
* @param {object} event - The event payload.
|
|
357
|
+
* @param {string} event.name - The name (key) of the added node.
|
|
358
|
+
* @param event.node - The node instance that was added.
|
|
359
|
+
* @example
|
|
360
|
+
* myTree.onAdd.subscribe(({ name, node }) => {
|
|
361
|
+
* console.log(`Node '${name}' was added.`, node);
|
|
362
|
+
* });
|
|
363
|
+
*/
|
|
364
|
+
onAdd: Emitter<[event: {
|
|
365
|
+
name: string;
|
|
366
|
+
node: TreeNode<TFields>;
|
|
367
|
+
}]>;
|
|
368
|
+
/**
|
|
369
|
+
* An event emitter that fires once after one or more nodes have been successfully removed.
|
|
370
|
+
* @event
|
|
371
|
+
* @param {object} event - The event payload.
|
|
372
|
+
* @param {string[]} event.names - An array of names of the nodes that were removed.
|
|
373
|
+
* @example
|
|
374
|
+
* myTree.onRemove.subscribe(({ names }) => {
|
|
375
|
+
* console.log(`Nodes removed: ${names.join(', ')}`);
|
|
376
|
+
* });
|
|
377
|
+
*/
|
|
378
|
+
onRemove: Emitter<[event: {
|
|
379
|
+
names: string[];
|
|
380
|
+
}]>;
|
|
381
|
+
/**
|
|
382
|
+
* Gets the collection of direct child nodes of this tree branch.
|
|
383
|
+
*/
|
|
384
|
+
get nodes(): Map<string, TreeNode<TFields>>;
|
|
385
|
+
/**
|
|
386
|
+
* Creates an instance of FieldTree.
|
|
387
|
+
* @param {FieldTreeFactory} factory - A factory responsible for creating new nodes within the tree.
|
|
388
|
+
*/
|
|
389
|
+
constructor(factory: FieldTreeFactory<TFields>);
|
|
390
|
+
/**
|
|
391
|
+
* Checks if a direct child node with the given name exists.
|
|
392
|
+
* @param {string} name - The name of the direct child node.
|
|
393
|
+
* @returns {boolean} `true` if the node exists, otherwise `false`.
|
|
394
|
+
*/
|
|
395
|
+
has(name: string): boolean;
|
|
396
|
+
/**
|
|
397
|
+
* Checks if a node exists at a given path, traversing the tree.
|
|
398
|
+
* @param {PathType} path - The path to check (e.g., 'player/stats' or ['player', 'stats']).
|
|
399
|
+
* @returns {boolean} `true` if the entire path resolves to a node, otherwise `false`.
|
|
400
|
+
*/
|
|
401
|
+
hasPath(path: PathType): boolean;
|
|
402
|
+
/**
|
|
403
|
+
* Adds a pre-existing node as a direct child of this tree branch.
|
|
404
|
+
* @param {string} name - The name to assign to the new child node.
|
|
405
|
+
* @param {TreeNode} node - The node instance to add.
|
|
406
|
+
* @returns {TreeNode} The added node.
|
|
407
|
+
* @throws If a node with the same name already exists.
|
|
408
|
+
*/
|
|
409
|
+
addNode(name: string, node: TreeNode<TFields>): TreeNode<TFields>;
|
|
410
|
+
/**
|
|
411
|
+
* Retrieves a direct child node by its name.
|
|
412
|
+
* @param {string} name - The name of the child node.
|
|
413
|
+
* @returns {TreeNode} The retrieved node.
|
|
414
|
+
* @throws If a node with the given name cannot be found.
|
|
415
|
+
*/
|
|
416
|
+
getNode(name: string): TreeNode<TFields>;
|
|
417
|
+
/**
|
|
418
|
+
* Removes one or more nodes from this tree branch.
|
|
419
|
+
*
|
|
420
|
+
* This method first validates that all specified nodes exist. If validation passes,
|
|
421
|
+
* it recursively calls `destroy()` on each node to ensure proper cleanup of the entire subtree.
|
|
422
|
+
* Finally, it emits a single `onRemove` event with the names of all successfully removed nodes.
|
|
423
|
+
*
|
|
424
|
+
* @param {string | string[]} names - A single name or an array of names of the nodes to remove.
|
|
425
|
+
* @throws If any of the specified names do not correspond to an existing node.
|
|
426
|
+
*/
|
|
427
|
+
removeNode(names: string | string[]): void;
|
|
428
|
+
/**
|
|
429
|
+
* Creates a new `FieldTree` (branch) node at the specified path.
|
|
430
|
+
* @param {PathType} path - The path where the new `FieldTree` should be created.
|
|
431
|
+
* @param {boolean} [createPath=false] - If `true`, any missing parent branches in the path will be created automatically.
|
|
432
|
+
* @returns {FieldTree} The newly created `FieldTree` instance.
|
|
433
|
+
* @throws If the path is invalid or a node already exists at the target location.
|
|
434
|
+
*/
|
|
435
|
+
createFieldTree<T extends FieldTree<TFields>>(path: PathType, createPath?: boolean): T;
|
|
436
|
+
/**
|
|
437
|
+
* Creates a new `Fields` (leaf) container at the specified path.
|
|
438
|
+
* @param {PathType} path - The path where the new `Fields` container should be created.
|
|
439
|
+
* @param {boolean} [createPath=false] - If `true`, any missing parent branches in the path will be created automatically.
|
|
440
|
+
* @returns {Fields} The newly created `Fields` instance.
|
|
441
|
+
* @throws If the path is invalid or a node already exists at the target location.
|
|
442
|
+
*/
|
|
443
|
+
createFields(path: PathType, createPath?: boolean): TFields;
|
|
444
|
+
/**
|
|
445
|
+
* Retrieves a `FieldTree` (branch) node from a specified path.
|
|
446
|
+
* @param {PathType} path - The path to the `FieldTree` node.
|
|
447
|
+
* @returns {FieldTree} The `FieldTree` instance at the specified path.
|
|
448
|
+
* @throws If the path is invalid or the node at the path is not a `FieldTree`.
|
|
449
|
+
*/
|
|
450
|
+
getFieldTree(path: PathType): FieldTree<TFields>;
|
|
451
|
+
/**
|
|
452
|
+
* Retrieves a `Fields` (leaf) container from a specified path.
|
|
453
|
+
* @param {PathType} path - The path to the `Fields` container.
|
|
454
|
+
* @returns {Fields} The `Fields` instance at the specified path.
|
|
455
|
+
* @throws If the path is invalid or the node at the path is not a `Fields` container.
|
|
456
|
+
*/
|
|
457
|
+
getFields(path: PathType): TFields;
|
|
458
|
+
/**
|
|
459
|
+
* Retrieves a `FieldTree` at the specified path. If it or any part of the path doesn't exist, it will be created.
|
|
460
|
+
* @param {PathType} path - The path to the `FieldTree` node.
|
|
461
|
+
* @returns {FieldTree} The existing or newly created `FieldTree` instance.
|
|
462
|
+
*/
|
|
463
|
+
getOrCreateFieldTree(path: PathType): FieldTree<TFields>;
|
|
464
|
+
/**
|
|
465
|
+
* Retrieves a `Fields` container at the specified path. If it or any part of the path doesn't exist, it will be created.
|
|
466
|
+
* @param {PathType} path - The path to the `Fields` container.
|
|
467
|
+
* @returns {Fields} The existing or newly created `Fields` instance.
|
|
468
|
+
*/
|
|
469
|
+
getOrCreateFields(path: PathType): TFields;
|
|
470
|
+
/**
|
|
471
|
+
* Finds the parent node for a given path.
|
|
472
|
+
* @param path The path to the target node.
|
|
473
|
+
* @returns The parent node (either a FieldTree or Fields).
|
|
474
|
+
* @throws An error if the path is invalid or any intermediate node is not a FieldTree.
|
|
475
|
+
*/
|
|
476
|
+
findParentNode(path: PathType): FieldTree<TFields> | TFields;
|
|
477
|
+
/**
|
|
478
|
+
* Removes all child nodes from this tree branch.
|
|
479
|
+
* This method ensures that `destroy()` is called on each child node, allowing for
|
|
480
|
+
* a full, recursive cleanup of the entire subtree.
|
|
481
|
+
*/
|
|
482
|
+
clear(): void;
|
|
483
|
+
/**
|
|
484
|
+
* Performs a complete cleanup of this node and its entire subtree.
|
|
485
|
+
*
|
|
486
|
+
* It recursively destroys all child nodes by calling `clear()` and then
|
|
487
|
+
* unsubscribes all listeners from its own event emitters.
|
|
488
|
+
* This method should be called when a node is no longer needed.
|
|
489
|
+
*/
|
|
490
|
+
destroy(): void;
|
|
491
|
+
/**
|
|
492
|
+
* @private
|
|
493
|
+
* Navigates the tree to the parent of a target node.
|
|
494
|
+
* This is the core traversal logic for all path-based operations.
|
|
495
|
+
* @param {PathType} path - The full path to the target node.
|
|
496
|
+
* @param {boolean} [createPath=false] - If `true`, creates missing `FieldTree` branches along the path.
|
|
497
|
+
* @returns {{branch: FieldTree, leafName: string}} An object containing the final branch (parent node) and the name of the leaf (target node).
|
|
498
|
+
* @throws If the path is empty, invalid, or contains a `Fields` container as an intermediate segment.
|
|
499
|
+
*/
|
|
500
|
+
private traversePath;
|
|
501
|
+
}
|
|
502
|
+
|
|
503
|
+
declare const CoreFields_base: _axi_engine_utils.Constructor<{
|
|
504
|
+
createGeneric<T>(name: string, initialValue: T, options?: FieldOptions<T> | undefined): CoreField<T>;
|
|
505
|
+
upsetGeneric<T>(name: string, value: T, options?: FieldOptions<T> | undefined): CoreField<T>;
|
|
506
|
+
getGeneric<T>(name: string): CoreField<T>;
|
|
507
|
+
readonly typeName: "fields";
|
|
508
|
+
readonly _fields: Map<string, Field<any>>;
|
|
509
|
+
readonly _fieldRegistry: FieldRegistry;
|
|
510
|
+
onAdd: _axi_engine_utils.Emitter<[event: {
|
|
511
|
+
name: string;
|
|
512
|
+
field: Field<any>;
|
|
513
|
+
}]>;
|
|
514
|
+
onRemove: _axi_engine_utils.Emitter<[event: {
|
|
515
|
+
names: string[];
|
|
516
|
+
}]>;
|
|
517
|
+
get fields(): Map<string, Field<any>>;
|
|
518
|
+
has(name: string): boolean;
|
|
519
|
+
add<T extends Field<any>>(field: Field<any>): T;
|
|
520
|
+
create<T extends Field<any>>(typeName: string, name: string, initialValue: any, options?: any): T;
|
|
521
|
+
upset<T extends Field<any>>(typeName: string, name: string, value: any, options?: any): T;
|
|
522
|
+
get<TField extends Field<any>>(name: string): TField;
|
|
523
|
+
remove(names: string | string[]): void;
|
|
524
|
+
clear(): void;
|
|
525
|
+
destroy(): void;
|
|
534
526
|
} & Fields & {
|
|
535
|
-
|
|
527
|
+
createNumeric: (name: string, initialValue: number, options?: CoreNumericFieldOptions | undefined) => CoreNumericField;
|
|
536
528
|
} & {
|
|
537
|
-
|
|
529
|
+
upsetNumeric: (name: string, value: number, options?: CoreNumericFieldOptions | undefined) => CoreNumericField;
|
|
538
530
|
} & {
|
|
539
|
-
|
|
531
|
+
getNumeric: (name: string) => CoreNumericField;
|
|
540
532
|
} & {
|
|
541
|
-
|
|
533
|
+
createString: (name: string, initialValue: string, options?: CoreStringFieldOptions | undefined) => CoreStringField;
|
|
542
534
|
} & {
|
|
543
|
-
|
|
535
|
+
upsetString: (name: string, value: string, options?: CoreStringFieldOptions | undefined) => CoreStringField;
|
|
544
536
|
} & {
|
|
545
|
-
|
|
537
|
+
getString: (name: string) => CoreStringField;
|
|
546
538
|
} & {
|
|
547
|
-
|
|
539
|
+
createBoolean: (name: string, initialValue: boolean, options?: CoreBooleanFieldOptions | undefined) => CoreBooleanField;
|
|
548
540
|
} & {
|
|
549
|
-
|
|
541
|
+
upsetBoolean: (name: string, value: boolean, options?: CoreBooleanFieldOptions | undefined) => CoreBooleanField;
|
|
550
542
|
} & {
|
|
551
|
-
|
|
543
|
+
getBoolean: (name: string) => CoreBooleanField;
|
|
552
544
|
}>;
|
|
553
|
-
declare class CoreFields extends CoreFields_base {
|
|
554
|
-
|
|
555
|
-
|
|
545
|
+
declare class CoreFields extends CoreFields_base {
|
|
546
|
+
}
|
|
547
|
+
|
|
556
548
|
declare class CoreFieldsFactory implements FieldsFactory<CoreFields> {
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
}
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
//#region src/core-field-tree-factory.d.ts
|
|
549
|
+
protected readonly _fieldRegistry: FieldRegistry;
|
|
550
|
+
get fieldRegistry(): FieldRegistry;
|
|
551
|
+
constructor(fieldRegistry: FieldRegistry);
|
|
552
|
+
fields(): CoreFields;
|
|
553
|
+
}
|
|
554
|
+
|
|
555
|
+
declare class CoreFieldTree extends FieldTree<CoreFields> {
|
|
556
|
+
}
|
|
557
|
+
|
|
567
558
|
/**
|
|
568
559
|
* The default factory implementation that creates standard DefaultFields and FieldTree instances.
|
|
569
560
|
*/
|
|
570
561
|
declare class CoreTreeNodeFactory extends CoreFieldsFactory implements FieldTreeFactory<CoreFields> {
|
|
571
|
-
|
|
572
|
-
|
|
562
|
+
constructor(fieldRegistry: FieldRegistry);
|
|
563
|
+
tree(): CoreFieldTree;
|
|
573
564
|
}
|
|
574
|
-
|
|
575
|
-
//#region src/serializer/policy-serializer.d.ts
|
|
565
|
+
|
|
576
566
|
/**
|
|
577
567
|
* Defines the contract for a handler that can serialize and deserialize a specific type of Policy.
|
|
578
568
|
* @template T - The specific Policy class this handler manages.
|
|
579
569
|
* @template S - The shape of the plain object this handler produces/consumes.
|
|
580
570
|
*/
|
|
581
571
|
interface PolicySerializerHandler<T extends Policy<any>, S extends object> {
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
572
|
+
/**
|
|
573
|
+
* Converts a Policy instance into a serializable plain object.
|
|
574
|
+
* @param policy The Policy instance to serialize.
|
|
575
|
+
* @returns A plain object representing the policy's state.
|
|
576
|
+
*/
|
|
577
|
+
snapshot(policy: T): S;
|
|
578
|
+
/**
|
|
579
|
+
* Creates a new Policy instance from a plain object.
|
|
580
|
+
* @param snapshotData The plain object containing the policy's state.
|
|
581
|
+
* @returns A new instance of the Policy.
|
|
582
|
+
*/
|
|
583
|
+
hydrate(snapshotData: S): T;
|
|
594
584
|
}
|
|
595
585
|
declare class PolicySerializer {
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
}
|
|
615
|
-
|
|
616
|
-
//#region src/serializer/policies/clamp-policy-serializer-handler.d.ts
|
|
586
|
+
private readonly handlers;
|
|
587
|
+
register(policyId: string, handler: PolicySerializerHandler<any, any>): this;
|
|
588
|
+
clearHandlers(): void;
|
|
589
|
+
/**
|
|
590
|
+
* Creates a serializable snapshot of a policy instance.
|
|
591
|
+
* The snapshot includes the policy's state and a `__type` identifier.
|
|
592
|
+
* @param policy The policy instance to snapshot.
|
|
593
|
+
* @returns A plain object ready for JSON serialization.
|
|
594
|
+
* @throws If no handler is registered for the policy's ID.
|
|
595
|
+
*/
|
|
596
|
+
snapshot(policy: Policy<any>): object;
|
|
597
|
+
/**
|
|
598
|
+
* Restores a policy instance from its snapshot representation.
|
|
599
|
+
* @param snapshot The plain object snapshot, which must contain a `__type` property.
|
|
600
|
+
* @returns A new, fully functional policy instance.
|
|
601
|
+
* @throws If the snapshot is invalid or no handler is registered for its `__type`.
|
|
602
|
+
*/
|
|
603
|
+
hydrate(snapshot: any): Policy<any>;
|
|
604
|
+
}
|
|
605
|
+
|
|
617
606
|
declare class ClampPolicySerializerHandler implements PolicySerializerHandler<ClampPolicy, {
|
|
618
|
-
min: number;
|
|
619
|
-
max: number;
|
|
620
|
-
}> {
|
|
621
|
-
snapshot(policy: ClampPolicy): {
|
|
622
607
|
min: number;
|
|
623
608
|
max: number;
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
609
|
+
}> {
|
|
610
|
+
snapshot(policy: ClampPolicy): {
|
|
611
|
+
min: number;
|
|
612
|
+
max: number;
|
|
613
|
+
};
|
|
614
|
+
hydrate(data: {
|
|
615
|
+
min: number;
|
|
616
|
+
max: number;
|
|
617
|
+
}): ClampPolicy;
|
|
629
618
|
}
|
|
630
|
-
|
|
631
|
-
//#region src/serializer/policies/clamp-max-policy-serializer-handler.d.ts
|
|
619
|
+
|
|
632
620
|
declare class ClampMaxPolicySerializerHandler implements PolicySerializerHandler<ClampMaxPolicy, {
|
|
633
|
-
max: number;
|
|
634
|
-
}> {
|
|
635
|
-
snapshot(policy: ClampMaxPolicy): {
|
|
636
|
-
max: number;
|
|
637
|
-
};
|
|
638
|
-
hydrate(data: {
|
|
639
621
|
max: number;
|
|
640
|
-
|
|
622
|
+
}> {
|
|
623
|
+
snapshot(policy: ClampMaxPolicy): {
|
|
624
|
+
max: number;
|
|
625
|
+
};
|
|
626
|
+
hydrate(data: {
|
|
627
|
+
max: number;
|
|
628
|
+
}): ClampMaxPolicy;
|
|
641
629
|
}
|
|
642
|
-
|
|
643
|
-
//#region src/serializer/policies/clamp-min-policy-serializer-handler.d.ts
|
|
630
|
+
|
|
644
631
|
declare class ClampMinPolicySerializerHandler implements PolicySerializerHandler<ClampMinPolicy, {
|
|
645
|
-
min: number;
|
|
646
|
-
}> {
|
|
647
|
-
snapshot(policy: ClampMinPolicy): {
|
|
648
|
-
min: number;
|
|
649
|
-
};
|
|
650
|
-
hydrate(data: {
|
|
651
632
|
min: number;
|
|
652
|
-
|
|
633
|
+
}> {
|
|
634
|
+
snapshot(policy: ClampMinPolicy): {
|
|
635
|
+
min: number;
|
|
636
|
+
};
|
|
637
|
+
hydrate(data: {
|
|
638
|
+
min: number;
|
|
639
|
+
}): ClampMinPolicy;
|
|
653
640
|
}
|
|
654
|
-
|
|
655
|
-
//#region src/serializer/field-serializer.d.ts
|
|
641
|
+
|
|
656
642
|
/**
|
|
657
643
|
* A plain object representation of a Field's state for serialization.
|
|
658
644
|
*/
|
|
659
645
|
interface FieldSnapshot {
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
646
|
+
__type: string;
|
|
647
|
+
name: string;
|
|
648
|
+
value: any;
|
|
649
|
+
policies?: object[];
|
|
664
650
|
}
|
|
665
651
|
/**
|
|
666
652
|
* Orchestrates the serialization and deserialization of Field instances.
|
|
@@ -676,39 +662,38 @@ interface FieldSnapshot {
|
|
|
676
662
|
* without breaking external references to it.
|
|
677
663
|
*/
|
|
678
664
|
declare class FieldSerializer {
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
}
|
|
704
|
-
|
|
705
|
-
//#region src/serializer/fields-serializer.d.ts
|
|
665
|
+
private readonly fieldRegistry;
|
|
666
|
+
private readonly policySerializer;
|
|
667
|
+
/**
|
|
668
|
+
* Creates an instance of FieldSerializer.
|
|
669
|
+
* @param {FieldRegistry} fieldRegistry - A registry that maps string type names to Field constructors.
|
|
670
|
+
* @param {PolicySerializer} policySerializer - A serializer dedicated to handling Policy instances.
|
|
671
|
+
*/
|
|
672
|
+
constructor(fieldRegistry: FieldRegistry, policySerializer: PolicySerializer);
|
|
673
|
+
/**
|
|
674
|
+
* Creates a serializable snapshot of a Field instance.
|
|
675
|
+
* The snapshot includes the field's type, name, current value, and the state of all its policies.
|
|
676
|
+
* @param {Field<any>} field - The Field instance to serialize.
|
|
677
|
+
* @returns {FieldSnapshot} A plain object ready for JSON serialization.
|
|
678
|
+
*/
|
|
679
|
+
snapshot(field: Field<any>): FieldSnapshot;
|
|
680
|
+
/**
|
|
681
|
+
* Restores a Field instance from its snapshot representation.
|
|
682
|
+
* It uses the `__type` property to find the correct constructor and hydrates
|
|
683
|
+
* the field with its value and all its policies.
|
|
684
|
+
* @param {FieldSnapshot} snapshot - The plain object snapshot to deserialize.
|
|
685
|
+
* @returns {Field<any>} A new, fully functional Field instance.
|
|
686
|
+
* @throws If the snapshot is invalid, missing a `__type`, or if the type is not registered.
|
|
687
|
+
*/
|
|
688
|
+
hydrate(snapshot: FieldSnapshot): Field<any>;
|
|
689
|
+
}
|
|
690
|
+
|
|
706
691
|
/**
|
|
707
692
|
* A plain object representation of a Fields container's state for serialization.
|
|
708
693
|
*/
|
|
709
694
|
interface FieldsSnapshot {
|
|
710
|
-
|
|
711
|
-
|
|
695
|
+
__type: string;
|
|
696
|
+
[fieldName: string]: FieldSnapshot | string;
|
|
712
697
|
}
|
|
713
698
|
/**
|
|
714
699
|
* Orchestrates the serialization and deserialization of `Fields` container instances.
|
|
@@ -722,34 +707,33 @@ interface FieldsSnapshot {
|
|
|
722
707
|
* in place, preserving the container instance itself.
|
|
723
708
|
*/
|
|
724
709
|
declare class FieldsSerializer<TFields extends Fields> {
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
}
|
|
751
|
-
|
|
752
|
-
//#region src/serializer/field-tree-serializer.d.ts
|
|
710
|
+
private readonly fieldsFactory;
|
|
711
|
+
private readonly fieldSerializer;
|
|
712
|
+
/**
|
|
713
|
+
* Creates an instance of FieldsSerializer.
|
|
714
|
+
* @param {FieldsFactory} fieldsFactory - A registry that maps string type names to Field constructors.
|
|
715
|
+
* @param {FieldSerializer} fieldSerializer - A serializer of field instances.
|
|
716
|
+
*/
|
|
717
|
+
constructor(fieldsFactory: FieldsFactory<TFields>, fieldSerializer: FieldSerializer);
|
|
718
|
+
/**
|
|
719
|
+
* Creates a serializable snapshot of a `Fields` container.
|
|
720
|
+
*
|
|
721
|
+
* The snapshot includes a `__type` identifier (currently hardcoded) and an array of snapshots
|
|
722
|
+
* for each `Field` within the container.
|
|
723
|
+
* @param {Fields} fields - The `Fields` instance to serialize.
|
|
724
|
+
* @returns {FieldsSnapshot} A plain object ready for JSON serialization.
|
|
725
|
+
*/
|
|
726
|
+
snapshot(fields: Fields): FieldsSnapshot;
|
|
727
|
+
/**
|
|
728
|
+
* Restores a `Fields` container instance from its snapshot representation.
|
|
729
|
+
*
|
|
730
|
+
* It iterates through the field snapshots and hydrates them individually, adding them to the new container.
|
|
731
|
+
* @param {FieldsSnapshot} snapshot - The plain object snapshot to deserialize.
|
|
732
|
+
* @returns {Fields} A new `DefaultFields` instance populated with the restored fields.
|
|
733
|
+
*/
|
|
734
|
+
hydrate(snapshot: FieldsSnapshot): TFields;
|
|
735
|
+
}
|
|
736
|
+
|
|
753
737
|
/**
|
|
754
738
|
* Represents the serializable state of a `FieldTree` container.
|
|
755
739
|
*
|
|
@@ -760,8 +744,8 @@ declare class FieldsSerializer<TFields extends Fields> {
|
|
|
760
744
|
* The `| string` is included to ensure compatibility with the `__type` property.
|
|
761
745
|
*/
|
|
762
746
|
interface FieldTreeSnapshot {
|
|
763
|
-
|
|
764
|
-
|
|
747
|
+
__type: string;
|
|
748
|
+
[fieldName: string]: FieldsSnapshot | FieldTreeSnapshot | string;
|
|
765
749
|
}
|
|
766
750
|
/**
|
|
767
751
|
* Orchestrates the recursive serialization and deserialization of `FieldTree` instances.
|
|
@@ -780,26 +764,25 @@ interface FieldTreeSnapshot {
|
|
|
780
764
|
* patching nodes in place to maintain object references.
|
|
781
765
|
*/
|
|
782
766
|
declare class FieldTreeSerializer<TFields extends Fields> {
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
}
|
|
798
|
-
|
|
799
|
-
//#region src/store.d.ts
|
|
767
|
+
private readonly fieldTreeNodeFactory;
|
|
768
|
+
private readonly fieldsSerializer;
|
|
769
|
+
constructor(fieldTreeNodeFactory: FieldTreeFactory<TFields>, fieldsSerializer: FieldsSerializer<TFields>);
|
|
770
|
+
/**
|
|
771
|
+
* Creates a serializable snapshot of the entire tree and its contained fields.
|
|
772
|
+
* @returns A plain JavaScript object representing the complete state managed by this tree.
|
|
773
|
+
*/
|
|
774
|
+
snapshot(tree: FieldTree<TFields>): FieldTreeSnapshot;
|
|
775
|
+
/**
|
|
776
|
+
* Restores the state of the tree from a snapshot.
|
|
777
|
+
* It intelligently creates missing nodes based on `__type` metadata and delegates hydration to child nodes.
|
|
778
|
+
* @param snapshot The snapshot object to load.
|
|
779
|
+
*/
|
|
780
|
+
hydrate(snapshot: FieldTreeSnapshot): FieldTree<TFields>;
|
|
781
|
+
}
|
|
782
|
+
|
|
800
783
|
interface StoreCreateFieldOptions {
|
|
801
|
-
|
|
802
|
-
|
|
784
|
+
/** Allows to explicitly specify the field type, overriding the automatic type detection. */
|
|
785
|
+
fieldType?: string;
|
|
803
786
|
}
|
|
804
787
|
/**
|
|
805
788
|
* Defines the primary high-level API for interacting with the state management system.
|
|
@@ -807,176 +790,173 @@ interface StoreCreateFieldOptions {
|
|
|
807
790
|
* both type-safe and dynamic methods for manipulating data.
|
|
808
791
|
*/
|
|
809
792
|
interface Store {
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
|
|
858
|
-
|
|
859
|
-
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
|
|
885
|
-
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
|
|
899
|
-
|
|
900
|
-
|
|
901
|
-
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
|
|
925
|
-
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
}
|
|
931
|
-
|
|
932
|
-
//#region src/data-store-field-resolver.d.ts
|
|
793
|
+
/**
|
|
794
|
+
* Retrieves the raw value of a Field at a specific path.
|
|
795
|
+
* @template T The expected type of the value.
|
|
796
|
+
* @param path The path to the field (e.g., 'player.stats.hp').
|
|
797
|
+
* @returns {T} The raw value stored in the field.
|
|
798
|
+
* @throws An error if the path is invalid or no field exists at the path.
|
|
799
|
+
*/
|
|
800
|
+
getValue<T>(path: PathType): T;
|
|
801
|
+
/**
|
|
802
|
+
* Strictly sets the value of an *existing* Field at a specific path.
|
|
803
|
+
* @template T The type of the value being set.
|
|
804
|
+
* @param path The path to the existing field.
|
|
805
|
+
* @param val The new value to set.
|
|
806
|
+
* @returns {T} The value that was set.
|
|
807
|
+
* @throws An error if no field exists at the specified path.
|
|
808
|
+
*/
|
|
809
|
+
setValue<T>(path: PathType, val: T): T;
|
|
810
|
+
/**
|
|
811
|
+
* Creates a new Field at a specified path, inferring its type from the provided value.
|
|
812
|
+
* This is a strict operation and will fail if a node already exists at the target path.
|
|
813
|
+
* @template T The type of the initial value.
|
|
814
|
+
* @param path The full path where the new field will be created.
|
|
815
|
+
* @param val The initial value for the field.
|
|
816
|
+
* @param options Optional configuration, including policies and the ability to override field type.
|
|
817
|
+
* @returns {T} value of the newly created Field instance.
|
|
818
|
+
* @throws An error if a node already exists at the path or if the parent path is invalid.
|
|
819
|
+
*/
|
|
820
|
+
createValue<T>(path: PathType, val: T, options?: FieldOptions<T> & StoreCreateFieldOptions): T;
|
|
821
|
+
/**
|
|
822
|
+
* Creates new or update a Field at a specified path, inferring its type from the provided value.
|
|
823
|
+
* @template T The type of the initial value.
|
|
824
|
+
* @param path The full path where the new field will be created.
|
|
825
|
+
* @param val The initial value for the field.
|
|
826
|
+
* @param options Optional configuration, including policies and the ability to override field type.
|
|
827
|
+
* @returns {T} value of the newly created Field instance.
|
|
828
|
+
* @throws An error if a node already exists at the path or if the parent path is invalid.
|
|
829
|
+
*/
|
|
830
|
+
upsetValue<T>(path: PathType, val: T, options?: FieldOptions<T> & StoreCreateFieldOptions): T;
|
|
831
|
+
/**
|
|
832
|
+
* Creates a new, strongly-typed CoreBooleanField.
|
|
833
|
+
* @throws An error if a node already exists at the path.
|
|
834
|
+
*/
|
|
835
|
+
createBoolean(path: PathType, initialValue: boolean, options?: CoreBooleanFieldOptions): CoreBooleanField;
|
|
836
|
+
/**
|
|
837
|
+
* Creates a new, strongly-typed CoreNumericField.
|
|
838
|
+
* @throws An error if a node already exists at the path.
|
|
839
|
+
*/
|
|
840
|
+
createNumeric(path: PathType, initialValue: number, options?: CoreNumericFieldOptions): CoreNumericField;
|
|
841
|
+
/**
|
|
842
|
+
* Creates a new, strongly-typed CoreStringField.
|
|
843
|
+
* @throws An error if a node already exists at the path.
|
|
844
|
+
*/
|
|
845
|
+
createString(path: PathType, initialValue: string, options?: CoreStringFieldOptions): CoreStringField;
|
|
846
|
+
/**
|
|
847
|
+
* Creates a new, generic CoreField instance for any data type.
|
|
848
|
+
* @throws An error if a node already exists at the path.
|
|
849
|
+
*/
|
|
850
|
+
createGeneric<T>(path: PathType, initialValue: T, options?: FieldOptions<T>): CoreField<T>;
|
|
851
|
+
/**
|
|
852
|
+
* Retrieves a strongly-typed CoreBooleanField instance.
|
|
853
|
+
* @throws An error if the path is invalid or the field is not of the expected type.
|
|
854
|
+
*/
|
|
855
|
+
getBoolean(path: PathType): CoreBooleanField;
|
|
856
|
+
/**
|
|
857
|
+
* Retrieves a strongly-typed CoreNumericField instance.
|
|
858
|
+
* @throws An error if the path is invalid or the field is not of the expected type.
|
|
859
|
+
*/
|
|
860
|
+
getNumeric(path: PathType): CoreNumericField;
|
|
861
|
+
/**
|
|
862
|
+
* Retrieves a strongly-typed CoreStringField instance.
|
|
863
|
+
* @throws An error if the path is invalid or the field is not of the expected type.
|
|
864
|
+
*/
|
|
865
|
+
getString(path: PathType): CoreStringField;
|
|
866
|
+
/**
|
|
867
|
+
* Retrieves a generic CoreField instance.
|
|
868
|
+
* @throws An error if the path is invalid.
|
|
869
|
+
*/
|
|
870
|
+
getGeneric<T>(path: PathType): CoreField<T>;
|
|
871
|
+
/**
|
|
872
|
+
* A generic method to retrieve a Field instance with a specific asserted type.
|
|
873
|
+
* @template TField The expected Field class or interface.
|
|
874
|
+
* @throws An error if the path is invalid or the field cannot be cast to the specified type.
|
|
875
|
+
*/
|
|
876
|
+
getField<TField extends Field<any>>(path: PathType): TField;
|
|
877
|
+
/**
|
|
878
|
+
* Strictly creates a new CoreFields container.
|
|
879
|
+
* Any missing parent nodes in the path will be created automatically.
|
|
880
|
+
* @param path The path where the new Fields container will be created.
|
|
881
|
+
* @returns {CoreFields} The newly created CoreFields instance.
|
|
882
|
+
* @throws An error if a node already exists at the target path.
|
|
883
|
+
*/
|
|
884
|
+
createFields(path: PathType): CoreFields;
|
|
885
|
+
/**
|
|
886
|
+
* Strictly creates a new CoreFieldTree node.
|
|
887
|
+
* Any missing parent nodes in the path will be created automatically.
|
|
888
|
+
* @param path The path where the new FieldTree node will be created.
|
|
889
|
+
* @returns {CoreFieldTree} The newly created CoreFieldTree instance.
|
|
890
|
+
* @throws An error if a node already exists at the target path.
|
|
891
|
+
*/
|
|
892
|
+
createTree(path: PathType): CoreFieldTree;
|
|
893
|
+
/**
|
|
894
|
+
* Retrieves an existing CoreFields container.
|
|
895
|
+
* @param path The path to the Fields container.
|
|
896
|
+
* @returns {CoreFields} The found CoreFields instance.
|
|
897
|
+
* @throws An error if the path is invalid or the node at the path is not a Fields container.
|
|
898
|
+
*/
|
|
899
|
+
getFields(path: PathType): CoreFields;
|
|
900
|
+
/**
|
|
901
|
+
* Retrieves an existing CoreFieldTree node.
|
|
902
|
+
* @param path The path to the FieldTree node.
|
|
903
|
+
* @returns {CoreFieldTree} The found CoreFieldTree instance.
|
|
904
|
+
* @throws An error if the path is invalid or the node at the path is not a FieldTree.
|
|
905
|
+
*/
|
|
906
|
+
getTree(path: PathType): CoreFieldTree;
|
|
907
|
+
/**
|
|
908
|
+
* Removes the node (Field, Fields, or FieldTree) at the end of the specified path.
|
|
909
|
+
* This method does not remove parent nodes if they become empty.
|
|
910
|
+
* @param path The path to the node to remove.
|
|
911
|
+
*/
|
|
912
|
+
remove(path: PathType): void;
|
|
913
|
+
}
|
|
914
|
+
|
|
933
915
|
interface DataStoreFieldResolver {
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
|
|
944
|
-
|
|
945
|
-
}
|
|
946
|
-
|
|
947
|
-
//#region src/data-store.d.ts
|
|
916
|
+
/**
|
|
917
|
+
* The typeName this resolver corresponds to in the FieldRegistry.
|
|
918
|
+
* e.g., 'numeric', 'boolean', 'vector'
|
|
919
|
+
*/
|
|
920
|
+
typeName: string;
|
|
921
|
+
/**
|
|
922
|
+
* Checks if this resolver can handle the given value.
|
|
923
|
+
* @param value The value to check.
|
|
924
|
+
* @returns {boolean} True if the value is supported, otherwise false.
|
|
925
|
+
*/
|
|
926
|
+
supports(value: unknown): boolean;
|
|
927
|
+
}
|
|
928
|
+
|
|
948
929
|
declare class DataStore implements Store {
|
|
949
|
-
|
|
950
|
-
|
|
951
|
-
|
|
952
|
-
|
|
953
|
-
|
|
954
|
-
|
|
955
|
-
|
|
956
|
-
|
|
957
|
-
|
|
958
|
-
|
|
959
|
-
|
|
960
|
-
|
|
961
|
-
|
|
962
|
-
|
|
963
|
-
|
|
964
|
-
|
|
965
|
-
|
|
966
|
-
|
|
967
|
-
|
|
968
|
-
|
|
969
|
-
|
|
970
|
-
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
}
|
|
978
|
-
|
|
979
|
-
//#region src/setup.d.ts
|
|
930
|
+
private readonly tree;
|
|
931
|
+
private readonly resolvers;
|
|
932
|
+
private readonly rootFieldsName;
|
|
933
|
+
private _rootFields;
|
|
934
|
+
private get rootFields();
|
|
935
|
+
constructor(tree: CoreFieldTree);
|
|
936
|
+
registerResolver(resolver: DataStoreFieldResolver): void;
|
|
937
|
+
clearResolvers(): void;
|
|
938
|
+
getValue<T>(path: PathType): T;
|
|
939
|
+
setValue<T>(path: PathType, val: T): T;
|
|
940
|
+
createValue<T>(path: PathType, val: T, options?: FieldOptions<T> & StoreCreateFieldOptions): T;
|
|
941
|
+
upsetValue<T>(path: PathType, val: T, options?: FieldOptions<T> & StoreCreateFieldOptions): T;
|
|
942
|
+
createBoolean(path: PathType, initialValue: boolean, options?: CoreBooleanFieldOptions): CoreBooleanField;
|
|
943
|
+
createNumeric(path: PathType, initialValue: number, options?: CoreNumericFieldOptions): CoreNumericField;
|
|
944
|
+
createString(path: PathType, initialValue: string, options?: CoreStringFieldOptions): CoreStringField;
|
|
945
|
+
createGeneric<T>(path: PathType, initialValue: T, options?: FieldOptions<T>): CoreField<T>;
|
|
946
|
+
getBoolean(path: PathType): CoreBooleanField;
|
|
947
|
+
getNumeric(path: PathType): CoreNumericField;
|
|
948
|
+
getString(path: PathType): CoreStringField;
|
|
949
|
+
getGeneric<T>(path: PathType): CoreField<T>;
|
|
950
|
+
getField<TField extends Field<any>>(path: PathType): TField;
|
|
951
|
+
createFields(path: PathType): CoreFields;
|
|
952
|
+
createTree(path: PathType): CoreFieldTree;
|
|
953
|
+
getFields(path: PathType): CoreFields;
|
|
954
|
+
getTree(path: PathType): CoreFieldTree;
|
|
955
|
+
remove(path: PathType): void;
|
|
956
|
+
private isPathToRootFields;
|
|
957
|
+
private getDestinationFields;
|
|
958
|
+
}
|
|
959
|
+
|
|
980
960
|
/**
|
|
981
961
|
* Creates and configures a FieldRegistry with all the core field types.
|
|
982
962
|
* @returns {FieldRegistry} A pre-configured FieldRegistry instance.
|
|
@@ -1002,17 +982,16 @@ declare function createCoreTreeNodeFactory(fieldRegistry: FieldRegistry): CoreTr
|
|
|
1002
982
|
*/
|
|
1003
983
|
declare function createCoreTreeSerializer(fieldTreeNodeFactory: CoreTreeNodeFactory, policySerializer?: PolicySerializer): FieldTreeSerializer<CoreFields>;
|
|
1004
984
|
interface CoreFieldSystemConfig {
|
|
1005
|
-
|
|
1006
|
-
|
|
985
|
+
registry?: FieldRegistry;
|
|
986
|
+
policySerializer?: PolicySerializer;
|
|
1007
987
|
}
|
|
1008
988
|
/**
|
|
1009
989
|
* Creates a complete core setup for the field system.
|
|
1010
990
|
* @returns {{factory: CoreTreeNodeFactory, serializer: FieldTreeSerializer<CoreFields>}}
|
|
1011
991
|
*/
|
|
1012
992
|
declare function createCoreFieldSystem(config?: CoreFieldSystemConfig): {
|
|
1013
|
-
|
|
1014
|
-
|
|
993
|
+
factory: CoreTreeNodeFactory;
|
|
994
|
+
serializer: FieldTreeSerializer<CoreFields>;
|
|
1015
995
|
};
|
|
1016
|
-
|
|
1017
|
-
export { BooleanField, ClampMaxPolicy, ClampMaxPolicySerializerHandler, ClampMinPolicy, ClampMinPolicySerializerHandler, ClampPolicy, ClampPolicySerializerHandler, CoreBooleanField, CoreBooleanFieldOptions, CoreField, CoreFieldSystemConfig, CoreFieldTree, CoreFields, CoreFieldsFactory, CoreNumericField, CoreNumericFieldOptions, CoreStringField, CoreStringFieldOptions, CoreTreeNodeFactory, DataStore, Field, FieldOptions, FieldRegistry, FieldSerializer, FieldSnapshot, FieldTree, FieldTreeFactory, FieldTreeSerializer, FieldTreeSnapshot, Fields, FieldsFactory, FieldsSerializer, FieldsSnapshot, NumericField, Policies, Policy, PolicySerializer, PolicySerializerHandler, Store, StoreCreateFieldOptions, StringField, TreeNode, clampMaxPolicy, clampMinPolicy, clampPolicy, createCoreFieldRegistry, createCoreFieldSystem, createCorePolicySerializer, createCoreTreeNodeFactory, createCoreTreeSerializer, createTypedMethodsMixin };
|
|
1018
|
-
//# sourceMappingURL=index.d.mts.map
|
|
996
|
+
|
|
997
|
+
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 };
|