sia-reactor 0.0.21 → 0.0.23
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/README.md +115 -89
- package/dist/{TimeTravelOverlay-DxqJL0Zk.d.ts → TimeTravelOverlay-Dglcwpg-.d.ts} +9 -8
- package/dist/{TimeTravelOverlay-CJv-S_Km.d.cts → TimeTravelOverlay-OjklzuCD.d.cts} +9 -8
- package/dist/adapters/react.cjs +74 -91
- package/dist/adapters/react.d.cts +23 -22
- package/dist/adapters/react.d.ts +23 -22
- package/dist/adapters/react.js +3 -3
- package/dist/adapters/vanilla.cjs +74 -91
- package/dist/adapters/vanilla.d.cts +4 -4
- package/dist/adapters/vanilla.d.ts +4 -4
- package/dist/adapters/vanilla.js +3 -3
- package/dist/{chunk-TFLYCXK4.js → chunk-5JNWC7Z4.js} +14 -13
- package/dist/{chunk-DP74DVRT.js → chunk-MKL3JUPO.js} +55 -15
- package/dist/{chunk-2WBPGSRL.js → chunk-MSTHQVNK.js} +61 -78
- package/dist/{index-Oie9hhE8.d.cts → index-m0aAWxhX.d.cts} +330 -218
- package/dist/{index-Oie9hhE8.d.ts → index-m0aAWxhX.d.ts} +330 -218
- package/dist/index.cjs +69 -89
- package/dist/index.d.cts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +2 -4
- package/dist/{plugins.cjs → modules.cjs} +464 -195
- package/dist/modules.d.cts +52 -0
- package/dist/modules.d.ts +52 -0
- package/dist/modules.js +619 -0
- package/dist/super.d.ts +642 -298
- package/dist/super.global.js +481 -210
- package/dist/timeTravel-DExvNb04.d.ts +352 -0
- package/dist/timeTravel-DctvcHVt.d.cts +352 -0
- package/dist/utils.cjs +59 -14
- package/dist/utils.d.cts +1 -1
- package/dist/utils.d.ts +1 -1
- package/dist/utils.js +7 -1
- package/package.json +6 -6
- package/dist/plugins.d.cts +0 -112
- package/dist/plugins.d.ts +0 -112
- package/dist/plugins.js +0 -370
- package/dist/timeTravel-B1vedDQc.d.ts +0 -76
- package/dist/timeTravel-WpgWmKu-.d.cts +0 -76
|
@@ -20,24 +20,31 @@ type NoTraverse =
|
|
|
20
20
|
| AbortSignal
|
|
21
21
|
| Inert<unknown>;
|
|
22
22
|
|
|
23
|
-
/** Dot-path union for traversable keys in `T`. */
|
|
24
|
-
type Paths<T, S extends string = ".", D extends number =
|
|
23
|
+
/** Dot-path union for traversable keys in `T` up to depth `D{11}`. */
|
|
24
|
+
type Paths<T, S extends string = ".", D extends number = MaxDepth> = [D] extends [0]
|
|
25
25
|
? never // Circuit Breaker Triggered
|
|
26
26
|
: T extends NoTraverse
|
|
27
27
|
? never
|
|
28
28
|
: T extends readonly (infer U)[]
|
|
29
|
-
? `${Extract<keyof T, number>}` | `${Extract<keyof T, number>}${S}${Paths<U, S,
|
|
29
|
+
? `${Extract<keyof T, number>}` | `${Extract<keyof T, number>}${S}${Paths<U, S, PrevDepth[D]>}`
|
|
30
30
|
: {
|
|
31
31
|
[K in keyof T & (string | number)]: T[K] extends Primitive
|
|
32
32
|
? `${K}`
|
|
33
|
-
: `${K}` | `${K}${S}${Paths<T[K], S,
|
|
33
|
+
: `${K}` | `${K}${S}${Paths<T[K], S, PrevDepth[D]>}`;
|
|
34
34
|
}[keyof T & (string | number)];
|
|
35
35
|
/** Wildcard path (`*`) or concrete dot-path. */
|
|
36
36
|
type WildPaths<T, S extends string = "."> = "*" | Paths<T, S>;
|
|
37
|
-
/** Child-path expansion for a path
|
|
38
|
-
type ChildPaths<
|
|
37
|
+
/** Child-path expansion for a path up to relative depth `D{x}`. */
|
|
38
|
+
type ChildPaths<
|
|
39
|
+
T,
|
|
40
|
+
P extends WildPaths<T>,
|
|
41
|
+
S extends string = ".",
|
|
42
|
+
D extends number = MaxDepth
|
|
43
|
+
> = P extends "*"
|
|
39
44
|
? Paths<T, S>
|
|
40
|
-
:
|
|
45
|
+
: [D] extends [AllDepth] // hardcoded since already at ts deep limits
|
|
46
|
+
? Extract<Paths<T, S, AddDepth<PathDepth<P, S>, D>>, `${P}${S}${string}`>
|
|
47
|
+
: Extract<Paths<T, S, AddDepth<PathDepth<P, S>, D>>, `${P}${S}${string}`>;
|
|
41
48
|
|
|
42
49
|
/** Leaf key name extracted from a path. */
|
|
43
50
|
type PathKey<T, P extends string = Paths<T>, S extends string = "."> = P extends "*"
|
|
@@ -86,7 +93,16 @@ type UnflattenKey<
|
|
|
86
93
|
? { [P in Head]: UnflattenKey<Tail, V, S> }
|
|
87
94
|
: { [P in K]: V };
|
|
88
95
|
|
|
89
|
-
// Helpers
|
|
96
|
+
// --- Helpers ---
|
|
97
|
+
|
|
98
|
+
/** Calculates the depth of a dot-separated path with a max of D{11}. */
|
|
99
|
+
type PathDepth<P extends string, S extends string = ".", D extends number = MaxDepth> = [
|
|
100
|
+
D
|
|
101
|
+
] extends [0]
|
|
102
|
+
? 0
|
|
103
|
+
: P extends `${infer _}${S}${infer Rest}`
|
|
104
|
+
? NextDepth[PathDepth<Rest, S, PrevDepth[D]>]
|
|
105
|
+
: 1;
|
|
90
106
|
|
|
91
107
|
/** Last segment of a path. */
|
|
92
108
|
type PathLeaf<
|
|
@@ -104,34 +120,49 @@ type PathBranch<
|
|
|
104
120
|
: Head
|
|
105
121
|
: never;
|
|
106
122
|
|
|
123
|
+
/** Converts a union of types into an intersection of types. */
|
|
107
124
|
type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
|
|
108
125
|
k: infer I
|
|
109
126
|
) => void
|
|
110
127
|
? I
|
|
111
128
|
: never;
|
|
112
129
|
|
|
130
|
+
/** Adds two depths together, respecting the max depth{11}. */
|
|
131
|
+
type AddDepth<A extends number, B extends number> = [B] extends [0]
|
|
132
|
+
? A
|
|
133
|
+
: [A] extends [MaxDepth]
|
|
134
|
+
? MaxDepth
|
|
135
|
+
: AddDepth<NextDepth[A], PrevDepth[B]>;
|
|
136
|
+
|
|
137
|
+
/** Subtracts depth B from A, respecting the min depth{0}. */
|
|
138
|
+
type SubtractDepth<A extends number, B extends number> = [B] extends [0]
|
|
139
|
+
? A
|
|
140
|
+
: [A] extends [0]
|
|
141
|
+
? 0
|
|
142
|
+
: SubtractDepth<PrevDepth[A], PrevDepth[B]>;
|
|
143
|
+
|
|
113
144
|
// --- "It's not that deep" WARRIORS ---
|
|
114
145
|
|
|
115
|
-
/** Deep key union of `T` up to depth `D{
|
|
116
|
-
type DeepKeys<T, D extends number =
|
|
146
|
+
/** Deep key union of `T` up to depth `D{11}`. */
|
|
147
|
+
type DeepKeys<T, D extends number = MaxDepth> = [D] extends [0]
|
|
117
148
|
? never
|
|
118
149
|
: T extends NoTraverse
|
|
119
150
|
? never
|
|
120
151
|
: T extends readonly any[]
|
|
121
|
-
? DeepKeys<T[number],
|
|
152
|
+
? DeepKeys<T[number], PrevDepth[D]>
|
|
122
153
|
: {
|
|
123
|
-
[K in keyof T & (string | number)]: K | DeepKeys<T[K],
|
|
154
|
+
[K in keyof T & (string | number)]: K | DeepKeys<T[K], PrevDepth[D]>;
|
|
124
155
|
}[keyof T & (string | number)];
|
|
125
156
|
|
|
126
|
-
/** Recursive merge result type for `T1` and `T2` up to depth `D{
|
|
127
|
-
type DeepMerge<T1, T2, D extends number =
|
|
157
|
+
/** Recursive merge result type for `T1` and `T2` up to depth `D{11}`. */
|
|
158
|
+
type DeepMerge<T1, T2, D extends number = MaxDepth> = [D] extends [0]
|
|
128
159
|
? never
|
|
129
160
|
: T2 extends object
|
|
130
161
|
? T1 extends object
|
|
131
162
|
? {
|
|
132
163
|
[K in keyof T1 | keyof T2]: K extends keyof T2
|
|
133
164
|
? K extends keyof T1
|
|
134
|
-
? DeepMerge<T1[K], T2[K],
|
|
165
|
+
? DeepMerge<T1[K], T2[K], PrevDepth[D]>
|
|
135
166
|
: T2[K]
|
|
136
167
|
: K extends keyof T1
|
|
137
168
|
? T1[K]
|
|
@@ -140,39 +171,139 @@ type DeepMerge<T1, T2, D extends number = RDepth> = [D] extends [0]
|
|
|
140
171
|
: T2
|
|
141
172
|
: T2;
|
|
142
173
|
|
|
143
|
-
/** Recursive partial type up to depth `D{
|
|
144
|
-
type DeepPartial<T, D extends number =
|
|
174
|
+
/** Recursive partial type up to depth `D{11}`. */
|
|
175
|
+
type DeepPartial<T, D extends number = MaxDepth> = [D] extends [0]
|
|
145
176
|
? never
|
|
146
177
|
: T extends Function
|
|
147
178
|
? T
|
|
148
179
|
: T extends Array<infer U>
|
|
149
|
-
? Array<DeepPartial<U,
|
|
180
|
+
? Array<DeepPartial<U, PrevDepth[D]>>
|
|
150
181
|
: T extends ReadonlyArray<infer U>
|
|
151
|
-
? ReadonlyArray<DeepPartial<U,
|
|
182
|
+
? ReadonlyArray<DeepPartial<U, PrevDepth[D]>>
|
|
152
183
|
: T extends object
|
|
153
|
-
? { [P in keyof T]?: DeepPartial<T[P],
|
|
184
|
+
? { [P in keyof T]?: DeepPartial<T[P], PrevDepth[D]> }
|
|
154
185
|
: T;
|
|
155
186
|
|
|
156
|
-
/** Recursive required type up to depth `D{
|
|
157
|
-
type DeepRequired<T, D extends number =
|
|
187
|
+
/** Recursive required type up to depth `D{11}`. */
|
|
188
|
+
type DeepRequired<T, D extends number = MaxDepth> = [D] extends [0]
|
|
158
189
|
? never
|
|
159
190
|
: T extends Function
|
|
160
191
|
? T
|
|
161
192
|
: T extends Array<infer U>
|
|
162
|
-
? Array<DeepRequired<U,
|
|
193
|
+
? Array<DeepRequired<U, PrevDepth[D]>>
|
|
163
194
|
: T extends ReadonlyArray<infer U>
|
|
164
|
-
? ReadonlyArray<DeepRequired<U,
|
|
195
|
+
? ReadonlyArray<DeepRequired<U, PrevDepth[D]>>
|
|
165
196
|
: T extends object
|
|
166
|
-
? { [P in keyof T]-?: DeepRequired<T[P],
|
|
197
|
+
? { [P in keyof T]-?: DeepRequired<T[P], PrevDepth[D]> }
|
|
167
198
|
: T;
|
|
168
199
|
|
|
169
200
|
// --- RECURSION LIMITERS ---
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
201
|
+
|
|
202
|
+
/** Config for defining recursive limits for all parts of the application */
|
|
203
|
+
interface DepthConfig {
|
|
204
|
+
max: 11;
|
|
205
|
+
all: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19; // observed bundler recursive limit for state trees
|
|
206
|
+
prev: [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19];
|
|
207
|
+
next: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20];
|
|
208
|
+
}
|
|
209
|
+
/** Current recursive depth limit */
|
|
210
|
+
type MaxDepth = DepthConfig["max"];
|
|
211
|
+
type AllDepth = DepthConfig["all"];
|
|
212
|
+
type PrevDepth = DepthConfig["prev"];
|
|
213
|
+
type NextDepth = DepthConfig["next"];
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* - Runtime event payload used by Reactor listener waves.
|
|
217
|
+
* - Tracks phase and current path context during propagation, mimics native `Event` API.
|
|
218
|
+
* Exposes intent controls (`resolve`/`reject`), propagation controls, and `composedPath()`.
|
|
219
|
+
* @typeParam T Root state object type.
|
|
220
|
+
* @typeParam P Target path type.
|
|
221
|
+
*/
|
|
222
|
+
declare class ReactorEvent<T extends object, P extends WildPaths<T> = WildPaths<T>> {
|
|
223
|
+
/** No active propagation phase. */
|
|
224
|
+
static readonly NONE = 0;
|
|
225
|
+
/** Capture phase: root to target parent. */
|
|
226
|
+
static readonly CAPTURING_PHASE = 1;
|
|
227
|
+
/** Target phase: target listeners run. */
|
|
228
|
+
static readonly AT_TARGET = 2;
|
|
229
|
+
/** Bubble phase: target parent to root. */
|
|
230
|
+
static readonly BUBBLING_PHASE = 3;
|
|
231
|
+
/** Current propagation phase for this event instance. */
|
|
232
|
+
eventPhase: number;
|
|
233
|
+
/** Current event type for the active propagation path, clone immediately if async */
|
|
234
|
+
type: Payload<T, P>["type"];
|
|
235
|
+
/**
|
|
236
|
+
* Current target context for the active propagation path, clone immediately if async.
|
|
237
|
+
* Also use to survive future object shape changes from nesting for a path callback.
|
|
238
|
+
*/
|
|
239
|
+
currentTarget: Payload<T, P>["currentTarget"];
|
|
240
|
+
/** Original event type before propagation remapping. */
|
|
241
|
+
readonly staticType: Exclude<Payload<T, P>["type"], "update">;
|
|
242
|
+
/** Original event target context. */
|
|
243
|
+
readonly target: Payload<T, P>["target"];
|
|
244
|
+
/** Root reactive object for this event instance wave. */
|
|
245
|
+
readonly root: Payload<T, P>["root"];
|
|
246
|
+
/** Original target path for this event instance wave. */
|
|
247
|
+
readonly path: Payload<T, P>["target"]["path"];
|
|
248
|
+
/** Current value at the event target path. */
|
|
249
|
+
readonly value: Payload<T, P>["target"]["value"];
|
|
250
|
+
/** Previous value at the event target path. */
|
|
251
|
+
readonly oldValue: Payload<T, P>["target"]["oldValue"];
|
|
252
|
+
/** Whether resolve/reject intent semantics are allowed for this event instance. */
|
|
253
|
+
readonly rejectable: boolean;
|
|
254
|
+
/** Whether this event instance wave can bubble back up to ancestors or just capture down. */
|
|
255
|
+
readonly bubbles: boolean;
|
|
256
|
+
/**
|
|
257
|
+
* `DOMHighResTimeStamp` for this event instance payload for native event parity and accuracy.
|
|
258
|
+
* Enable `eventTimeStamps` option, then use this over custom timestamps in listeners for accuracy.
|
|
259
|
+
* */
|
|
260
|
+
readonly timestamp?: number;
|
|
261
|
+
/** The `Reactor` instance that dispatched this event instance. */
|
|
262
|
+
readonly reactor: Reactor<T>;
|
|
263
|
+
protected _resolved: string;
|
|
264
|
+
protected _rejected: string;
|
|
265
|
+
protected _propagationStopped: boolean;
|
|
266
|
+
protected _immediatePropagationStopped: boolean;
|
|
267
|
+
/**
|
|
268
|
+
* @param payload Source payload for this event instance.
|
|
269
|
+
* @param reactor The `Reactor` instance creating this event instance.
|
|
270
|
+
*/
|
|
271
|
+
constructor(payload: Payload<T, P>, reactor: Reactor<T>);
|
|
272
|
+
/** Whether propagation has been stopped. */
|
|
273
|
+
get propagationStopped(): boolean;
|
|
274
|
+
/** Stops propagation to remaining listeners in later nodes/phases. */
|
|
275
|
+
stopPropagation(): void;
|
|
276
|
+
/** Whether immediate propagation has been stopped. */
|
|
277
|
+
get immediatePropagationStopped(): boolean;
|
|
278
|
+
/** Stops propagation immediately, including remaining listeners on current path. */
|
|
279
|
+
stopImmediatePropagation(): void;
|
|
280
|
+
/** Resolution message for rejectable events. */
|
|
281
|
+
get resolved(): string;
|
|
282
|
+
/**
|
|
283
|
+
* Marks a rejectable event as resolved.
|
|
284
|
+
* @param message Optional resolution message or identity.
|
|
285
|
+
* @example e.resolve("html5Tech"); // identity
|
|
286
|
+
* @example e.resolve("API Load successful"); // message
|
|
287
|
+
*/
|
|
288
|
+
resolve(message?: string): void;
|
|
289
|
+
/** Rejection reason for rejectable events. */
|
|
290
|
+
get rejected(): string;
|
|
291
|
+
/**
|
|
292
|
+
* Marks a rejectable event as rejected.
|
|
293
|
+
* @param reason Optional rejection reason or identity.
|
|
294
|
+
* @example e.resolve("html5Tech"); // identity
|
|
295
|
+
* @example e.resolve("User is not logged in"); // reason
|
|
296
|
+
*/
|
|
297
|
+
reject(reason?: string): void;
|
|
298
|
+
/**
|
|
299
|
+
* Returns event path values from target to root.
|
|
300
|
+
* @returns Composed path values in bubbling order.
|
|
301
|
+
*/
|
|
302
|
+
composedPath(): any[];
|
|
303
|
+
}
|
|
173
304
|
|
|
174
305
|
/** Reactor method names exposed on objects returned by {@link reactive}. */
|
|
175
|
-
declare const methods: readonly ["tick", "stall", "nostall", "get", "gonce", "noget", "set", "sonce", "noset", "delete", "donce", "nodelete", "watch", "wonce", "nowatch", "on", "once", "off", "snapshot", "
|
|
306
|
+
declare const methods: readonly ["tick", "stall", "nostall", "get", "gonce", "noget", "set", "sonce", "noset", "delete", "donce", "nodelete", "watch", "wonce", "nowatch", "on", "once", "off", "snapshot", "use", "reset", "destroy"];
|
|
176
307
|
type Method = (typeof methods)[number];
|
|
177
308
|
type Prefix<P extends ReactivePreferences | undefined> = P extends {
|
|
178
309
|
prefix?: infer X extends string;
|
|
@@ -202,14 +333,14 @@ type Reactive<T extends object, P extends ReactivePreferences | undefined = unde
|
|
|
202
333
|
__Reactor__: Reactor<T>;
|
|
203
334
|
};
|
|
204
335
|
/**
|
|
205
|
-
* Attaches Reactor APIs to a state object and returns its reactive proxy.
|
|
206
|
-
* If an existing `reactive()`
|
|
336
|
+
* Attaches `Reactor` APIs to a state object and returns its reactive proxy from the reactor's core.
|
|
337
|
+
* If an existing `reactive()` object is passed, it is re-returned ignoring change in preferences.
|
|
207
338
|
* @param target Source state object or an existing Reactor instance.
|
|
208
339
|
* @param build Reactor initial configuration.
|
|
209
340
|
* @param preferences Method naming preferences for exposed APIs.
|
|
210
341
|
* @returns Reactive object with mapped Reactor methods and `__Reactor__`.
|
|
211
342
|
* @example
|
|
212
|
-
* const state = reactive({ user: { name: "
|
|
343
|
+
* const state = reactive({ user: { name: "Kosi" } });
|
|
213
344
|
* state.set("user.name", (v) => v);
|
|
214
345
|
* @example
|
|
215
346
|
* const rtr = new Reactor({ count: 0 });
|
|
@@ -233,7 +364,7 @@ declare function live<T extends object>(target: T): Live<T>;
|
|
|
233
364
|
* @param target Object to test.
|
|
234
365
|
* @returns `true` when inert.
|
|
235
366
|
*/
|
|
236
|
-
declare function isInert<T extends object>(target
|
|
367
|
+
declare function isInert<T extends object>(target?: T): target is Inert<T>;
|
|
237
368
|
/**
|
|
238
369
|
* Marks an object as intent (rejectable).
|
|
239
370
|
* @param target Object to mark.
|
|
@@ -251,7 +382,7 @@ declare function state<T extends object>(target: T): State<T>;
|
|
|
251
382
|
* @param target Object to test.
|
|
252
383
|
* @returns `true` when marked as intent.
|
|
253
384
|
*/
|
|
254
|
-
declare function isIntent<T extends object>(target
|
|
385
|
+
declare function isIntent<T extends object>(target?: T): target is Intent<T>;
|
|
255
386
|
/**
|
|
256
387
|
* Marks an object as volatile (indiffable enabled).
|
|
257
388
|
* @param target Object to mark.
|
|
@@ -269,25 +400,25 @@ declare function stable<T extends object>(target: T): Stable<T>;
|
|
|
269
400
|
* @param target Object to test.
|
|
270
401
|
* @returns `true` when marked as volatile.
|
|
271
402
|
*/
|
|
272
|
-
declare function isVolatile<T extends object>(target
|
|
403
|
+
declare function isVolatile<T extends object>(target?: T): target is Volatile<T>;
|
|
273
404
|
/**
|
|
274
405
|
* Gets the raw (unproxied) version of an object if it's proxied, otherwise returns the original object.
|
|
275
406
|
* @param target Object to unwrap.
|
|
276
|
-
* @returns Raw object if proxied, else the original object.
|
|
407
|
+
* @returns Raw object if proxied, else the original object. Use `Reactor.snapshot(true)` for deep unwrapping.
|
|
277
408
|
*/
|
|
278
|
-
declare function getRaw<T extends object>(target
|
|
409
|
+
declare function getRaw<T extends object>(target?: T): T;
|
|
279
410
|
/**
|
|
280
411
|
* Gets the current structural version of an object.
|
|
281
412
|
* @param target Object to inspect.
|
|
282
413
|
* @returns Version number.
|
|
283
414
|
*/
|
|
284
|
-
declare function getVersion<T extends object>(target
|
|
415
|
+
declare function getVersion<T extends object>(target?: T): number;
|
|
285
416
|
/**
|
|
286
417
|
* Gets the current snapshot-cache version of an object.
|
|
287
418
|
* @param target Object to inspect.
|
|
288
419
|
* @returns Snapshot version number.
|
|
289
420
|
*/
|
|
290
|
-
declare function getSnapshotVersion<T extends object>(target
|
|
421
|
+
declare function getSnapshotVersion<T extends object>(target?: T): number;
|
|
291
422
|
|
|
292
423
|
// ===========================================================================
|
|
293
424
|
// CORE MARKERS & STATE WRAPPERS
|
|
@@ -333,9 +464,9 @@ interface Target<T, P extends WildPaths<T> = WildPaths<T>> {
|
|
|
333
464
|
}
|
|
334
465
|
|
|
335
466
|
/** Runtime payload union for mediated operations and update waves (Creates the IDE magic). */
|
|
336
|
-
type Payload<T, P extends WildPaths<T> = WildPaths<T
|
|
467
|
+
type Payload<T, P extends WildPaths<T> = WildPaths<T>, D extends number = MaxDepth> =
|
|
337
468
|
| DirectPayload<T, P>
|
|
338
|
-
| UpdatePayload<T, P>;
|
|
469
|
+
| UpdatePayload<T, P, D>;
|
|
339
470
|
|
|
340
471
|
interface BasePayload<T, P extends WildPaths<T> = WildPaths<T>> {
|
|
341
472
|
/**
|
|
@@ -356,24 +487,32 @@ interface DirectPayload<T, P extends WildPaths<T> = WildPaths<T>> extends BasePa
|
|
|
356
487
|
/** Target context for this payload. */
|
|
357
488
|
target: Target<T, P>;
|
|
358
489
|
}
|
|
359
|
-
interface UpdatePayload<
|
|
490
|
+
interface UpdatePayload<
|
|
491
|
+
T,
|
|
492
|
+
P extends WildPaths<T> = WildPaths<T>,
|
|
493
|
+
D extends number = MaxDepth
|
|
494
|
+
> extends BasePayload<T, P> {
|
|
360
495
|
/** Type of the operation that triggered this payload, i.e. "update" */
|
|
361
496
|
type: "update";
|
|
362
497
|
/** Target context for this payload. */
|
|
363
|
-
target: Target<T, ChildPaths<T, P>>; // Target is strictly one of the child paths!
|
|
498
|
+
target: Target<T, ChildPaths<T, P, ".", D>>; // Target is strictly one of the child paths!
|
|
364
499
|
}
|
|
365
500
|
|
|
366
501
|
/** Event union with payload-aware overrides for `type`, `path`, and value fields (Creates the IDE magic). */
|
|
367
|
-
type REvent<
|
|
502
|
+
type REvent<
|
|
503
|
+
T extends object,
|
|
504
|
+
P extends WildPaths<T> = WildPaths<T>,
|
|
505
|
+
D extends number = MaxDepth
|
|
506
|
+
> =
|
|
368
507
|
| (Omit<ReactorEvent<T, P>, OverrideEvtProp> &
|
|
369
508
|
DirectPayload<T, P> &
|
|
370
|
-
|
|
509
|
+
OverrideEvt<DirectPayload<T, P>>)
|
|
371
510
|
| (Omit<ReactorEvent<T, P>, OverrideEvtProp> &
|
|
372
|
-
UpdatePayload<T, P> &
|
|
373
|
-
|
|
511
|
+
UpdatePayload<T, P, D> &
|
|
512
|
+
OverrideEvt<UpdatePayload<T, P, D>>);
|
|
374
513
|
|
|
375
514
|
type OverrideEvtProp = "type" | "target" | "value" | "oldValue" | "path";
|
|
376
|
-
interface
|
|
515
|
+
interface OverrideEvt<PL extends { target: { path: any; value: any; oldValue?: any } }> {
|
|
377
516
|
path: PL["target"]["path"];
|
|
378
517
|
value: PL["target"]["value"];
|
|
379
518
|
oldValue: PL["target"]["oldValue"];
|
|
@@ -409,7 +548,9 @@ type Watcher<T, P extends WildPaths<T> = WildPaths<T>> = (
|
|
|
409
548
|
) => void;
|
|
410
549
|
|
|
411
550
|
/** Listener callback (batched/asynchronous by default). */
|
|
412
|
-
type Listener<T, P extends WildPaths<T> = WildPaths<T
|
|
551
|
+
type Listener<T, P extends WildPaths<T> = WildPaths<T>, D extends number = MaxDepth> = (
|
|
552
|
+
event: REvent<T, P, D>
|
|
553
|
+
) => void;
|
|
413
554
|
|
|
414
555
|
// ===========================================================================
|
|
415
556
|
// ENGINE RECORDS (Internal Storage)
|
|
@@ -417,35 +558,39 @@ type Listener<T, P extends WildPaths<T> = WildPaths<T>> = (event: REvent<T, P>)
|
|
|
417
558
|
|
|
418
559
|
type GetterRecord<T extends object, P extends WildPaths<T> = WildPaths<T>> = {
|
|
419
560
|
cb: Getter<T, P>;
|
|
420
|
-
clup: () =>
|
|
561
|
+
clup: () => boolean | undefined; // Registration Cleanup
|
|
421
562
|
sclup?: () => void; // AbortSignal Cleanup
|
|
422
563
|
} & SyncOptionsTuple;
|
|
423
564
|
|
|
424
565
|
/** Internal registry record for `set` mediators. */
|
|
425
566
|
type SetterRecord<T extends object, P extends WildPaths<T> = WildPaths<T>> = {
|
|
426
567
|
cb: Setter<T, P>;
|
|
427
|
-
clup: () =>
|
|
568
|
+
clup: () => boolean | undefined;
|
|
428
569
|
sclup?: () => void;
|
|
429
570
|
} & SyncOptionsTuple;
|
|
430
571
|
|
|
431
572
|
type DeleterRecord<T extends object, P extends WildPaths<T> = WildPaths<T>> = {
|
|
432
573
|
cb: Deleter<T, P>;
|
|
433
|
-
clup: () =>
|
|
574
|
+
clup: () => boolean | undefined;
|
|
434
575
|
sclup?: () => void;
|
|
435
576
|
} & SyncOptionsTuple;
|
|
436
577
|
|
|
437
578
|
type WatcherRecord<T extends object, P extends WildPaths<T> = WildPaths<T>> = {
|
|
438
579
|
cb: Watcher<T, P>;
|
|
439
|
-
clup: () =>
|
|
580
|
+
clup: () => boolean | undefined;
|
|
440
581
|
sclup?: () => void;
|
|
441
582
|
} & SyncOptionsTuple;
|
|
442
583
|
|
|
443
|
-
type ListenerRecord<
|
|
444
|
-
|
|
445
|
-
|
|
584
|
+
type ListenerRecord<
|
|
585
|
+
T extends object,
|
|
586
|
+
P extends WildPaths<T> = WildPaths<T>,
|
|
587
|
+
D extends number = MaxDepth
|
|
588
|
+
> = {
|
|
589
|
+
cb: Listener<T, P, D>;
|
|
590
|
+
clup: () => boolean | undefined;
|
|
446
591
|
sclup?: () => void;
|
|
447
592
|
lDepth?: number; // Listener Depth
|
|
448
|
-
} & ListenerOptionsTuple
|
|
593
|
+
} & ListenerOptionsTuple<D>;
|
|
449
594
|
|
|
450
595
|
// ===========================================================================
|
|
451
596
|
// CONFIGURATION OPTIONS
|
|
@@ -464,19 +609,20 @@ interface SyncOptionsTuple {
|
|
|
464
609
|
/** Tuple-form and shorthand boolean for mediator/watch registrations. */
|
|
465
610
|
type SyncOptions = boolean | SyncOptionsTuple;
|
|
466
611
|
|
|
467
|
-
interface ListenerOptionsTuple extends
|
|
612
|
+
interface ListenerOptionsTuple<D extends number = MaxDepth>
|
|
613
|
+
extends Omit<SyncOptionsTuple, "lazy"> {
|
|
468
614
|
/** Whether to listen on the capture phase against bubble. */
|
|
469
615
|
capture?: boolean;
|
|
470
616
|
/** Maximum path nested depth for event propagation, try `1` if listening to an array with nested objects. */
|
|
471
|
-
depth?:
|
|
617
|
+
depth?: D;
|
|
472
618
|
}
|
|
473
619
|
/** Tuple-form and shorthand boolean for listener registrations. */
|
|
474
|
-
type ListenerOptions = boolean | ListenerOptionsTuple
|
|
620
|
+
type ListenerOptions<D extends number = MaxDepth> = boolean | ListenerOptionsTuple<D>;
|
|
475
621
|
|
|
476
622
|
/** Options accepted by adapter effects (`sync: true` -> watch mode else listener mode). */
|
|
477
623
|
type EffectOptions =
|
|
478
|
-
| (SyncOptionsTuple & { sync: true })
|
|
479
|
-
| (ListenerOptionsTuple & { sync?: false });
|
|
624
|
+
| (Omit<SyncOptionsTuple, "immediate"> & { sync: true })
|
|
625
|
+
| (Omit<ListenerOptionsTuple, "immediate"> & { sync?: false });
|
|
480
626
|
|
|
481
627
|
/** Reactor bootstrap/build configuration. */
|
|
482
628
|
interface ReactorBuild<T extends object, P extends Paths<T> = Paths<T>> {
|
|
@@ -550,99 +696,7 @@ interface ReactorBuild<T extends object, P extends Paths<T> = Paths<T>> {
|
|
|
550
696
|
) => (string | symbol)[]; // "almighty" mediation
|
|
551
697
|
} // debating keeping use of the Reflect API opt-in
|
|
552
698
|
|
|
553
|
-
|
|
554
|
-
* Runtime event payload used by Reactor listener waves.
|
|
555
|
-
*
|
|
556
|
-
* Tracks phase and current path context during propagation, mimics native `Event` API.
|
|
557
|
-
* Exposes intent controls (`resolve`/`reject`), propagation controls, and `composedPath()`.
|
|
558
|
-
* @typeParam T Root state object type.
|
|
559
|
-
* @typeParam P Target path type.
|
|
560
|
-
*/
|
|
561
|
-
declare class ReactorEvent<T extends object, P extends WildPaths<T> = WildPaths<T>> {
|
|
562
|
-
/** No active propagation phase. */
|
|
563
|
-
static readonly NONE = 0;
|
|
564
|
-
/** Capture phase: root to target parent. */
|
|
565
|
-
static readonly CAPTURING_PHASE = 1;
|
|
566
|
-
/** Target phase: target listeners run. */
|
|
567
|
-
static readonly AT_TARGET = 2;
|
|
568
|
-
/** Bubble phase: target parent to root. */
|
|
569
|
-
static readonly BUBBLING_PHASE = 3;
|
|
570
|
-
/** Current propagation phase for this event instance. */
|
|
571
|
-
eventPhase: number;
|
|
572
|
-
/** Current event type for the active propagation path, clone immediately if async */
|
|
573
|
-
type: Payload<T, P>["type"];
|
|
574
|
-
/**
|
|
575
|
-
* Current target context for the active propagation path, clone immediately if async.
|
|
576
|
-
* Also use to survive future object shape changes from nesting for a path callback.
|
|
577
|
-
*/
|
|
578
|
-
currentTarget: Payload<T, P>["currentTarget"];
|
|
579
|
-
/** Original event type before propagation remapping. */
|
|
580
|
-
readonly staticType: Exclude<Payload<T, P>["type"], "update">;
|
|
581
|
-
/** Original event target context. */
|
|
582
|
-
readonly target: Payload<T, P>["target"];
|
|
583
|
-
/** Root reactive object for this event wave. */
|
|
584
|
-
readonly root: Payload<T, P>["root"];
|
|
585
|
-
/** Original target path for this event wave. */
|
|
586
|
-
readonly path: Payload<T, P>["target"]["path"];
|
|
587
|
-
/** Current value at the event target path. */
|
|
588
|
-
readonly value: Payload<T, P>["target"]["value"];
|
|
589
|
-
/** Previous value at the event target path. */
|
|
590
|
-
readonly oldValue: Payload<T, P>["target"]["oldValue"];
|
|
591
|
-
/** Whether resolve/reject intent semantics are allowed for this event. */
|
|
592
|
-
readonly rejectable: boolean;
|
|
593
|
-
/** Whether this event wave can bubble back up to ancestors or just capture down. */
|
|
594
|
-
readonly bubbles: boolean;
|
|
595
|
-
/**
|
|
596
|
-
* `DOMHighResTimeStamp` for this event payload for native event parity and accuracy.
|
|
597
|
-
* Enable `eventTimeStamps` option, then use this over custom timestamps in listeners for accuracy.
|
|
598
|
-
* */
|
|
599
|
-
readonly timestamp?: number;
|
|
600
|
-
protected _warn: (...args: any[]) => void;
|
|
601
|
-
protected _resolved: string;
|
|
602
|
-
protected _rejected: string;
|
|
603
|
-
protected _propagationStopped: boolean;
|
|
604
|
-
protected _immediatePropagationStopped: boolean;
|
|
605
|
-
/**
|
|
606
|
-
* @param payload Source payload for this event instance.
|
|
607
|
-
* @param bubbles Whether bubbling is enabled for this wave.
|
|
608
|
-
* @param canWarn Whether warning output is enabled.
|
|
609
|
-
* @param canStamp Whether timestamping is enabled.
|
|
610
|
-
*/
|
|
611
|
-
constructor(payload: Payload<T, P>, bubbles?: boolean, canStamp?: boolean, canWarn?: boolean);
|
|
612
|
-
/** Whether propagation has been stopped. */
|
|
613
|
-
get propagationStopped(): boolean;
|
|
614
|
-
/** Stops propagation to remaining listeners in later nodes/phases. */
|
|
615
|
-
stopPropagation(): void;
|
|
616
|
-
/** Whether immediate propagation has been stopped. */
|
|
617
|
-
get immediatePropagationStopped(): boolean;
|
|
618
|
-
/** Stops propagation immediately, including remaining listeners on current path. */
|
|
619
|
-
stopImmediatePropagation(): void;
|
|
620
|
-
/** Resolution message for rejectable events. */
|
|
621
|
-
get resolved(): string;
|
|
622
|
-
/**
|
|
623
|
-
* Marks a rejectable event as resolved.
|
|
624
|
-
* @param message Optional resolution message or identity.
|
|
625
|
-
* @example e.resolve("html5Tech"); // identity
|
|
626
|
-
* @example e.resolve("API Load successful"); // message
|
|
627
|
-
*/
|
|
628
|
-
resolve(message?: string): void;
|
|
629
|
-
/** Rejection reason for rejectable events. */
|
|
630
|
-
get rejected(): string;
|
|
631
|
-
/**
|
|
632
|
-
* Marks a rejectable event as rejected.
|
|
633
|
-
* @param reason Optional rejection reason or identity.
|
|
634
|
-
* @example e.resolve("html5Tech"); // identity
|
|
635
|
-
* @example e.resolve("User is not logged in"); // reason
|
|
636
|
-
*/
|
|
637
|
-
reject(reason?: string): void;
|
|
638
|
-
/**
|
|
639
|
-
* Returns event path values from target to root.
|
|
640
|
-
* @returns Composed path values in bubbling order.
|
|
641
|
-
*/
|
|
642
|
-
composedPath(): any[];
|
|
643
|
-
get canWarn(): boolean;
|
|
644
|
-
}
|
|
645
|
-
|
|
699
|
+
declare const arrRegex: RegExp;
|
|
646
700
|
/** Checks if a value type is an object for common use cases. */
|
|
647
701
|
declare function isObj<T extends object = object>(obj: any, arraycheck?: boolean): obj is T;
|
|
648
702
|
/** Checks if a value is a "Plain Old Javascript Object". */
|
|
@@ -657,57 +711,90 @@ declare function canHandle(obj: any, config?: {
|
|
|
657
711
|
/**
|
|
658
712
|
* Gets a value by path.
|
|
659
713
|
* @example
|
|
660
|
-
* const state = { user: { profile: { name: "
|
|
714
|
+
* const state = { user: { profile: { name: "Kosi" } } };
|
|
661
715
|
* const name = getAny(state, "user.profile.name");
|
|
662
716
|
*/
|
|
663
717
|
declare function getAny<T extends object, const S extends string = ".", P extends WildPaths<T, S> = WildPaths<T, S>>(source: T, key: P, separator?: S, keyFunc?: (p: string) => string): PathValue<T, P, S>;
|
|
664
718
|
/**
|
|
665
719
|
* Sets a value by path.
|
|
666
720
|
* @example
|
|
667
|
-
* const state = { user: { profile: { name: "
|
|
721
|
+
* const state = { user: { profile: { name: "Kosi" } } };
|
|
668
722
|
* setAny(state, "user.profile.name", "Grace");
|
|
669
723
|
* @example
|
|
670
724
|
* const state = { users: [] as Array<{ name?: string }> };
|
|
671
|
-
* setAny(state, "users[0].name" as any, "
|
|
725
|
+
* setAny(state, "users[0].name" as any, "Kosi");
|
|
672
726
|
*/
|
|
673
727
|
declare function setAny<T extends object, const S extends string = ".", P extends WildPaths<T, S> = WildPaths<T, S>>(target: T, key: P, value: PathValue<T, P, S>, separator?: S, keyFunc?: (p: string) => string): void;
|
|
674
728
|
/**
|
|
675
729
|
* Deletes a value by path.
|
|
676
730
|
* @example
|
|
677
|
-
* const state = { user: { profile: { name: "
|
|
731
|
+
* const state = { user: { profile: { name: "Kosi" } } };
|
|
678
732
|
* deleteAny(state, "user.profile.name");
|
|
679
733
|
*/
|
|
680
|
-
declare function deleteAny<T extends object, const S extends string = ".">(target: T, key:
|
|
734
|
+
declare function deleteAny<T extends object, const S extends string = ".", P extends WildPaths<T, S> = WildPaths<T, S>>(target: T, key: P, separator?: S, keyFunc?: (p: string) => string): void;
|
|
681
735
|
/**
|
|
682
736
|
* Checks whether a path exists.
|
|
683
737
|
* @example
|
|
684
|
-
* const state = { user: { profile: { name: "
|
|
685
|
-
* const ok = inAny(state, "user.profile.name");
|
|
738
|
+
* const state = { user: { profile: { name: "Kosi" } } };
|
|
739
|
+
* const ok = inAny(state, "user.profile.name"); // default loose typing due to it's usecase
|
|
686
740
|
*/
|
|
687
|
-
declare function inAny<T extends object, const S extends string = ".">(source: T, key:
|
|
741
|
+
declare function inAny<T extends object, const S extends string = ".", P extends string = string>(source: T, key: P, separator?: S, keyFunc?: (p: string) => string): boolean;
|
|
688
742
|
/**
|
|
689
743
|
* Converts flattened keys into nested object structure.
|
|
690
744
|
* @example
|
|
691
|
-
* const flat = { "user.name": "
|
|
745
|
+
* const flat = { "user.name": "Kosi", "user.role": "admin" };
|
|
692
746
|
* const obj = parseAnyObj(flat);
|
|
693
747
|
*/
|
|
694
748
|
declare function parseAnyObj<T extends Record<string, any>, const S extends string = ".">(obj: T, separator?: S, keyFunc?: (p: string) => string, seen?: WeakSet<WeakKey>): Unflatten<T, S>;
|
|
695
749
|
/** Normalizes boolean/object event options into a single options object. */
|
|
696
|
-
declare function parseEvtOpts<T extends object
|
|
750
|
+
declare function parseEvtOpts<T extends object, const K extends (keyof T)[] | readonly (keyof T)[], const O extends K[number] = K[0]>(options: T | boolean | undefined, opts: K, boolOpt?: O, result?: T): T & {
|
|
751
|
+
[P in O]-?: T[P];
|
|
752
|
+
};
|
|
753
|
+
interface FanoutTuple extends Partial<Record<(typeof fanoutOptsArr)[number], any>> {
|
|
754
|
+
/** Whether to merge values before fanout, useful for patching usecases. */
|
|
755
|
+
merge?: boolean;
|
|
756
|
+
/** How many levels to fan out, set based on your listener paths max dots. `true` is `Infinity`, defaults to `1` for event cascading otherwise `Infinity`. */
|
|
757
|
+
depth?: number | boolean;
|
|
758
|
+
/** Whether to assign arrays as a whole and only touch `.length` for common cases. Only works with the `path` parameter overload or in nested levels.
|
|
759
|
+
* Arrays can lead to unnecessary work as more often than not, you won't be watching index paths but waiting on the parent bubble instead.
|
|
760
|
+
* If you happen to be watching, it might be more optimal to re-set it yourself if it's only a few indexes or just turn set this to `false`. */
|
|
761
|
+
atomic?: boolean;
|
|
762
|
+
}
|
|
697
763
|
/**
|
|
698
|
-
*
|
|
764
|
+
* Unified expansion utility.
|
|
765
|
+
* Bridges Coarse (Immutable replacement) writes into Fine-grained (Reactive) writes by surgically
|
|
766
|
+
* expanding a single object write into multiple granular child operations for deep optimal xbubbling.
|
|
767
|
+
* @example
|
|
768
|
+
* // Event Mode (Cascading after-write)
|
|
769
|
+
* rtr.on("user", (e) => fanout(e, { depth: 1 })); // defaults to 1 level deep for events
|
|
699
770
|
* @example
|
|
700
|
-
*
|
|
771
|
+
* // Direct Mode (Patching before-write)
|
|
772
|
+
* fanout(state.user, { session: { id: 1, name: "Kosi", role: "admin" } }, { depth: Infinity }); // default to `Infinity` here
|
|
701
773
|
*/
|
|
702
|
-
declare function
|
|
703
|
-
|
|
704
|
-
|
|
774
|
+
declare function fanout<T extends object>(event: ReactorEvent<T> | Payload<T>, options?: {
|
|
775
|
+
crossRealms?: boolean;
|
|
776
|
+
} & FanoutTuple): void;
|
|
777
|
+
declare function fanout<T extends object>(target: T, value: Partial<T>, options?: {
|
|
778
|
+
crossRealms?: boolean;
|
|
779
|
+
} & FanoutTuple): void;
|
|
780
|
+
declare function fanout<T extends object, P extends WildPaths<T> = WildPaths<T>>(state: T, path: P, value: Partial<PathValue<T, P>>, options?: {
|
|
781
|
+
crossRealms?: boolean;
|
|
782
|
+
} & FanoutTuple): void;
|
|
783
|
+
declare const fanoutOptsArr: readonly ["merge", "depth", "atomic"];
|
|
784
|
+
/**
|
|
785
|
+
* Deep-merges object-like values, does necessary checks so use without doubts.
|
|
786
|
+
* @example
|
|
787
|
+
* const next = mergeObjs({ user: { name: "Kosi" } }, { user: { role: "admin" } }); // { ...o1, ...o2 } // o2 over o1 and deep!
|
|
788
|
+
*/
|
|
789
|
+
declare function mergeObjs<T1 extends object, T2 extends object>(o1?: T1 | null, o2?: T2 | null, config?: {
|
|
790
|
+
crossRealms?: boolean;
|
|
791
|
+
}, pojocheck?: boolean): DeepMerge<T1, T2>;
|
|
705
792
|
/** Returns [path, parent, value] records from root to the target path. */
|
|
706
793
|
declare function getTrailRecords<T extends object>(obj: T, path: WildPaths<T>, reverse?: boolean): [WildPaths<T>, PathBranchValue<T, WildPaths<T>>, PathValue<T, WildPaths<T>>][];
|
|
707
794
|
/**
|
|
708
795
|
* Deep-clones supported object structures.
|
|
709
796
|
* @example
|
|
710
|
-
* const cloned = deepClone({ user: { name: "
|
|
797
|
+
* const cloned = deepClone({ user: { name: "Kosi" } });
|
|
711
798
|
*/
|
|
712
799
|
declare function deepClone<T>(obj: T, config?: {
|
|
713
800
|
crossRealms?: boolean;
|
|
@@ -716,27 +803,57 @@ declare function deepClone<T>(obj: T, config?: {
|
|
|
716
803
|
/** Nulls all non-function instance properties across the prototype chain. */
|
|
717
804
|
declare function nuke(target: any): void;
|
|
718
805
|
|
|
719
|
-
|
|
806
|
+
type ReactorModuleId = string | number;
|
|
807
|
+
interface ReactorModuleConstructor<P extends BaseReactorModule = BaseReactorModule, T extends object = any> {
|
|
720
808
|
new (rtr: Reactor<T>, config: any): P;
|
|
721
|
-
|
|
809
|
+
moduleName: string;
|
|
722
810
|
}
|
|
723
|
-
|
|
724
|
-
|
|
811
|
+
/**
|
|
812
|
+
* Base class, extend to create custom reactor modules that can be used with a `Reactor` instance
|
|
813
|
+
* Provides common functionalities like multi-reactor management, configuration handling, and error logging.
|
|
814
|
+
* @typeParam T Root state object type of the reactors this module will manage.
|
|
815
|
+
* @typeParam Config Configuration object type for the module.
|
|
816
|
+
* @typeParam State Optional local state object type for the module.
|
|
817
|
+
*/
|
|
818
|
+
declare abstract class BaseReactorModule<T extends object = any, Config = any, State = any> {
|
|
819
|
+
static readonly moduleName: string;
|
|
725
820
|
get name(): string;
|
|
726
821
|
protected ac: AbortController;
|
|
727
|
-
readonly signal: AbortSignal;
|
|
728
|
-
|
|
822
|
+
protected readonly signal: AbortSignal;
|
|
823
|
+
protected rtrs: Map<ReactorModuleId, Reactor<any>>;
|
|
824
|
+
protected rids: WeakMap<Reactor<any>, ReactorModuleId>;
|
|
825
|
+
protected wired: boolean;
|
|
729
826
|
config: Config extends object ? Reactive<Config> : Config;
|
|
730
827
|
readonly state: State extends object ? Reactive<State> : State;
|
|
731
828
|
constructor(config?: Config, rtr?: Reactor<T>, state?: State);
|
|
732
|
-
/**
|
|
733
|
-
|
|
734
|
-
|
|
829
|
+
/**
|
|
830
|
+
* Connect to a `Reactor` instance, allows managing multiple reactors if needed.
|
|
831
|
+
* @param target `Reactor` instance or `reactive()` object to connect to.
|
|
832
|
+
* @param id Optional custom id for the reactor, prefer over default implicit index id when managing multiple reactors, supports paths to merge into a single tree.
|
|
833
|
+
* @returns Current `ReactorModule` instance for fluent chaining.
|
|
834
|
+
* @example
|
|
835
|
+
* const mod = new MyModule().attach(state1).attach(state2); // implicit index-based ids by default, add a .setup() or `Reactor.use()` when ready for init.
|
|
836
|
+
* @example
|
|
837
|
+
* const persist = new PersistModule(config).attach(sessState, "session").attach(adminState, "session.admin"); // don't use "*", causes de-serialization issues.
|
|
838
|
+
*/
|
|
839
|
+
attach(target?: Reactor<any> | Reactive<any>, id?: ReactorModuleId): this;
|
|
840
|
+
protected onAttach(_rtr: Reactor<any>, _rid?: ReactorModuleId): void;
|
|
841
|
+
/**
|
|
842
|
+
* Entry point called to initialize module wiring, calls `.attach(target, id)` first, `Reactor.use()` calls this internally.
|
|
843
|
+
* Should run as last in `.attach()` chain or after all desired reactors if using multiple; so wiring is done safely after.
|
|
844
|
+
* @param target `Reactor` instance or `reactive()` object to connect to.
|
|
845
|
+
* @param id Optional id for the reactor, prefer over default implicit index id when managing multiple reactors.
|
|
846
|
+
* @returns Current `ReactorModule` instance for fluent chaining.
|
|
847
|
+
* @example
|
|
848
|
+
* const mod = new MyModule().attach(state1).setup(state2); // if using multiple, this should run last; with same params as `.attach()` for a shorter chain
|
|
849
|
+
*/
|
|
850
|
+
setup(target?: Reactor<any> | Reactive<any>, id?: ReactorModuleId): this;
|
|
851
|
+
/** set up listeners/subscriptions and module runtime wiring. */
|
|
735
852
|
abstract wire(): void;
|
|
736
853
|
destroy(): void;
|
|
737
854
|
protected onDestroy?(): void;
|
|
738
855
|
/**
|
|
739
|
-
* Wraps a function with
|
|
856
|
+
* Wraps a function with module-scoped error logging.
|
|
740
857
|
* Use this when creating functions dynamically (for example, before attaching an anonymous listener on the fly).
|
|
741
858
|
* @example
|
|
742
859
|
* window.addEventListener("resize", this.guard(() => this.syncLayout(true)), { signal: this.signal });
|
|
@@ -744,19 +861,23 @@ declare abstract class BaseReactorPlugin<T extends object = any, Config = any, S
|
|
|
744
861
|
guard: <Fn extends Function>(fn: Fn) => Fn;
|
|
745
862
|
}
|
|
746
863
|
|
|
747
|
-
/**
|
|
748
|
-
*
|
|
749
|
-
*
|
|
864
|
+
/**
|
|
865
|
+
* - Core S.I.A runtime for path mediation, observation, and event propagation.
|
|
866
|
+
* - Provides path-level mediators (`get|set|delete`), synchronous watchers (`watch`), and batched listeners (`on`).
|
|
867
|
+
* Supports wildcard/path-based subscriptions, optional reference tracking, and module-based extensions.
|
|
750
868
|
* @typeParam T Root state object type.
|
|
751
869
|
*/
|
|
752
870
|
declare class Reactor<T extends object> {
|
|
871
|
+
/** Logger function for this reactor instance, override if desired, `this.canLog = false` resets. */
|
|
753
872
|
log: (...args: any[]) => void;
|
|
873
|
+
/** The core state object for this reactor instance. */
|
|
754
874
|
core: T;
|
|
755
|
-
|
|
875
|
+
/** The modules being used by this reactor. */
|
|
876
|
+
modules?: Set<BaseReactorModule<T>>;
|
|
877
|
+
/** Configuration options for this reactor instance. */
|
|
756
878
|
config: Omit<ReactorBuild<T>, "debug">;
|
|
879
|
+
/** Whether this reactor instance is currently batching updates, a window view into the engine timing */
|
|
757
880
|
isBatching: boolean;
|
|
758
|
-
isCascading: boolean;
|
|
759
|
-
protected isLogging: boolean;
|
|
760
881
|
protected queue?: Set<() => void>;
|
|
761
882
|
protected batch?: Map<Paths<T>, Payload<T>>;
|
|
762
883
|
protected lineage?: WeakMap<object, (object | string)[]>;
|
|
@@ -813,7 +934,7 @@ declare class Reactor<T extends object> {
|
|
|
813
934
|
*/
|
|
814
935
|
nostall(task: () => any): boolean | undefined;
|
|
815
936
|
getDepth(path: string, depth?: number): number;
|
|
816
|
-
|
|
937
|
+
getContext<P extends WildPaths<T>>(path: P): Target<T, P>;
|
|
817
938
|
protected bindSignal<Cb>(cord: GetterRecord<T> | SetterRecord<T> | DeleterRecord<T> | WatcherRecord<T> | ListenerRecord<T>, sig?: AbortSignal): Cb;
|
|
818
939
|
protected cloned<O>(target: O, raw: boolean, seen?: WeakMap<WeakKey, any>): O;
|
|
819
940
|
protected syncAdd<P extends WildPaths<T>>(key: "get" | "set" | "delete" | "watch", path: P, cb: any, opts: SyncOptions | undefined, onImmediate?: (immediate: boolean | "auto") => void): () => boolean | undefined;
|
|
@@ -877,7 +998,7 @@ declare class Reactor<T extends object> {
|
|
|
877
998
|
nodelete<P extends WildPaths<T>>(path: P, callback: Deleter<T, P>): boolean | undefined;
|
|
878
999
|
/**
|
|
879
1000
|
* Registers a watcher for a path.
|
|
880
|
-
* Watch callbacks run synchronously with the operation.
|
|
1001
|
+
* Watch callbacks run synchronously with the operation, use leaf paths for reliability as it sees exact sets; no bubbling here.
|
|
881
1002
|
* @param path Path or wildcard path.
|
|
882
1003
|
* @param callback Watch callback.
|
|
883
1004
|
* @param options Sync options.
|
|
@@ -905,9 +1026,9 @@ declare class Reactor<T extends object> {
|
|
|
905
1026
|
* @example
|
|
906
1027
|
* const cleanup = rtr.on("user.name", (e) => console.log(e.type, e.path));
|
|
907
1028
|
*/
|
|
908
|
-
on<P extends WildPaths<T
|
|
1029
|
+
on<P extends WildPaths<T>, const D extends number = MaxDepth>(path: P, callback: Listener<T, P, D>, options?: ListenerOptions<D>): ListenerRecord<T, P, D>["clup"];
|
|
909
1030
|
/** Registers an event listener for a path that only triggers once. */
|
|
910
|
-
once<P extends WildPaths<T
|
|
1031
|
+
once<P extends WildPaths<T>, const D extends number = MaxDepth>(path: P, callback: Listener<T, P, D>, options?: ListenerOptions<D>): ListenerRecord<T, P, D>["clup"];
|
|
911
1032
|
/**
|
|
912
1033
|
* Removes an event listener for a path.
|
|
913
1034
|
* @param path Path or wildcard path.
|
|
@@ -919,12 +1040,12 @@ declare class Reactor<T extends object> {
|
|
|
919
1040
|
* rtr.on("user.name", cb);
|
|
920
1041
|
* rtr.off("user.name", cb);
|
|
921
1042
|
*/
|
|
922
|
-
off<P extends WildPaths<T
|
|
1043
|
+
off<P extends WildPaths<T>, const D extends number = MaxDepth>(path: P, callback: Listener<T, P, D>, options?: ListenerOptions<D>): boolean | undefined;
|
|
923
1044
|
/**
|
|
924
1045
|
* Creates a snapshot; possibly clone of state (or a state branch).
|
|
925
1046
|
* You could alternatively use or serialize your proxied state "as is" except the environment demands no proxies or new references.
|
|
926
|
-
* @param raw Use raw (deep unproxied & uncloned) version of branch.
|
|
927
|
-
* @param branch
|
|
1047
|
+
* @param raw Use raw (deep unproxied & uncloned) version of branch, defaults to `true` if `config.smartCloning: false`.
|
|
1048
|
+
* @param branch Specific branch to clone.
|
|
928
1049
|
* @returns Snapshot deep or smart (structurally shared) clone.
|
|
929
1050
|
* @example
|
|
930
1051
|
* const snap = rtr.snapshot();
|
|
@@ -934,33 +1055,24 @@ declare class Reactor<T extends object> {
|
|
|
934
1055
|
snapshot(raw?: boolean): T;
|
|
935
1056
|
snapshot<B>(raw?: boolean, branch?: B): B;
|
|
936
1057
|
/**
|
|
937
|
-
*
|
|
938
|
-
* @param
|
|
939
|
-
* @param
|
|
940
|
-
* @
|
|
941
|
-
* rtr.on("user", (event) => rtr.cascade(event));
|
|
942
|
-
* @example
|
|
943
|
-
* rtr.watch("user", (_value, payload) => rtr.cascade(payload));
|
|
1058
|
+
* Installs a module instance.
|
|
1059
|
+
* @param target Module instance.
|
|
1060
|
+
* @param id Optional identification tag for this instance in the module.
|
|
1061
|
+
* @returns Current `Reactor` instance for fluent chaining.
|
|
944
1062
|
*/
|
|
945
|
-
|
|
946
|
-
/**
|
|
947
|
-
* Installs a plugin instance.
|
|
948
|
-
* @param plugin Plugin instance.
|
|
949
|
-
* @returns Current reactor for fluent chaining.
|
|
950
|
-
*/
|
|
951
|
-
plugIn(plugin: BaseReactorPlugin<T>): this;
|
|
952
|
-
/** Resets the reactor to its initial state. */
|
|
1063
|
+
use(target: BaseReactorModule<T>, id?: ReactorModuleId): this;
|
|
1064
|
+
/** Resets this reactor instance to its initial state. */
|
|
953
1065
|
reset(): void;
|
|
954
1066
|
destroy(): void;
|
|
955
1067
|
get canLog(): boolean;
|
|
956
1068
|
set canLog(value: boolean);
|
|
957
|
-
get
|
|
1069
|
+
get canLineageTrace(): boolean | undefined;
|
|
958
1070
|
get canSmartClone(): boolean | undefined;
|
|
959
1071
|
}
|
|
960
1072
|
|
|
961
1073
|
/**
|
|
962
|
-
* Auto-dependency tracker used to subscribe only to accessed paths.
|
|
963
|
-
* `tracked(...)` wraps a snapshot in a read-tracking proxy, and `callback(...)`
|
|
1074
|
+
* - Auto-dependency tracker used to subscribe only to accessed paths.
|
|
1075
|
+
* - `tracked(...)` wraps a snapshot in a read-tracking proxy, and `callback(...)`
|
|
964
1076
|
* binds subscriptions for collected paths using `watch` (sync) or `on` (batched).
|
|
965
1077
|
* @typeParam T Root state object type.
|
|
966
1078
|
*/
|
|
@@ -1009,9 +1121,9 @@ declare class Autotracker<T extends object> {
|
|
|
1009
1121
|
* const stop = atrkr.callback(() => console.log("changed")); // re-run after when ".user.name" changes
|
|
1010
1122
|
* @example Packaged Customization
|
|
1011
1123
|
* const atrkr = new Autotracker(); // no reactor passed
|
|
1012
|
-
* withTracker(atrkr, () => state.user.name); // import `withTracker`
|
|
1124
|
+
* withTracker(atrkr, () => state.user.name); // import `withTracker` too
|
|
1013
1125
|
* const stop = atrkr.callback(() => console.log("sync"), { sync: true }); // re-run immediately when ".user.name" changes, works on any path used from any reactor state
|
|
1014
|
-
* @example Extensive
|
|
1126
|
+
* @example Extensive Customization
|
|
1015
1127
|
* atrkr.unblock();
|
|
1016
1128
|
* const prev = CTX.autotracker;
|
|
1017
1129
|
* CTX.autotracker = atrkr; // import CTX first
|
|
@@ -1036,7 +1148,9 @@ declare function withTracker<T>(tracker: Autotracker<any>, run: () => T, rtr?: R
|
|
|
1036
1148
|
declare const CTX: {
|
|
1037
1149
|
/** Flag indicating whether the application is running in development mode. */
|
|
1038
1150
|
isDevEnv: boolean;
|
|
1039
|
-
/**
|
|
1151
|
+
/** Flag indicating whether a cascade is currently ongoing so reactors can allow all writes. */
|
|
1152
|
+
isCascading: boolean;
|
|
1153
|
+
/** Active `Autotracker` instance, override for automatic dependency collection on `Reactor` traps. */
|
|
1040
1154
|
autotracker: Autotracker<any> | null;
|
|
1041
1155
|
};
|
|
1042
1156
|
/** Marker to access underlying raw object from a proxy. */
|
|
@@ -1057,8 +1171,6 @@ declare const SSVERSION: unique symbol;
|
|
|
1057
1171
|
declare const RTR_BATCH: (callback: Function, ...args: any[]) => void;
|
|
1058
1172
|
/** Default reactor logger prefix function. */
|
|
1059
1173
|
declare const RTR_LOG: (...args: any[]) => void;
|
|
1060
|
-
/** Default event warning logger prefix function. */
|
|
1061
|
-
declare const EVT_WARN: (...args: any[]) => void;
|
|
1062
1174
|
/** Canonical option keys parsed for listener and mediator registrations. */
|
|
1063
1175
|
declare const EVT_OPTS: {
|
|
1064
1176
|
readonly LISTENER: readonly ["capture", "depth", "once", "signal", "immediate"];
|
|
@@ -1069,4 +1181,4 @@ declare const NIL: any;
|
|
|
1069
1181
|
/** Shared no-operation function. */
|
|
1070
1182
|
declare const NOOP: () => void;
|
|
1071
1183
|
|
|
1072
|
-
export { type
|
|
1184
|
+
export { type Live as $, Autotracker as A, BaseReactorModule as B, CTX as C, type DeepKeys as D, type EffectOptions as E, type FanoutTuple as F, type DeepMerge as G, type DeepPartial as H, type Inert as I, type DeepRequired as J, type Deleter as K, type DeleterRecord as L, type DepthConfig as M, type DirectPayload as N, EVT_OPTS as O, type Paths as P, type Getter as Q, Reactor as R, type GetterRecord as S, INDIFFABLE as T, INERTIA as U, type Intent as V, type WildPaths as W, type Listener as X, type ListenerOptions as Y, type ListenerOptionsTuple as Z, type ListenerRecord as _, type REvent as a, type MaxDepth as a0, NIL as a1, NOOP as a2, type NextDepth as a3, type NoTraverse as a4, type PathBranch as a5, type PathBranchValue as a6, type PathDepth as a7, type PathKey as a8, type PathLeaf as a9, type WatcherRecord as aA, getRaw as aB, getSnapshotVersion as aC, getVersion as aD, inert as aE, intent as aF, isInert as aG, isIntent as aH, isVolatile as aI, live as aJ, methods as aK, reactive as aL, stable as aM, state as aN, volatile as aO, type Payload as aa, type PrevDepth as ab, type Primitive as ac, RAW as ad, REJECTABLE as ae, RTR_BATCH as af, RTR_LOG as ag, type ReactivePreferences as ah, ReactorEvent as ai, SSVERSION as aj, type Setter as ak, type SetterRecord as al, type Stable as am, type State as an, type StrictPathKey as ao, type SubtractDepth as ap, type SyncOptions as aq, type SyncOptionsTuple as ar, TERMINATOR as as, type Target as at, type Unflatten as au, type UnionToIntersection as av, type UpdatePayload as aw, VERSION as ax, type Volatile as ay, type Watcher as az, type ReactorModuleConstructor as b, type ReactorModuleId as c, type Reactive as d, arrRegex as e, canHandle as f, deepClone as g, deleteAny as h, fanout as i, fanoutOptsArr as j, getAny as k, getTrailRecords as l, inAny as m, isObj as n, isPOJO as o, mergeObjs as p, nuke as q, parseAnyObj as r, parseEvtOpts as s, setAny as t, type ReactorBuild as u, type PathValue as v, withTracker as w, type AddDepth as x, type AllDepth as y, type ChildPaths as z };
|