@zvenigora/ng-eval-core 0.2.2 → 0.4.0

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.
@@ -0,0 +1,2303 @@
1
+ import * as i0 from '@angular/core';
2
+ import { OnDestroy } from '@angular/core';
3
+ import * as acorn from 'acorn';
4
+ import { AnyNode, Program, Expression } from 'acorn';
5
+ import { WalkerCallback } from 'acorn-walk';
6
+
7
+ type ParserOptions = Partial<acorn.Options> & {
8
+ extractExpressions?: boolean;
9
+ cacheSize?: number;
10
+ ecmaVersion?: acorn.ecmaVersion;
11
+ };
12
+ type AnyNodeTypes = acorn.AnyNode['type'];
13
+
14
+ /**
15
+ * Represents a registry that stores key-value pairs.
16
+ * @template TKey - The type of the keys in the registry.
17
+ * @template TValue - The type of the values in the registry.
18
+ */
19
+ interface RegistryType<TKey, TValue> extends Iterable<[TKey, TValue]> {
20
+ type: Readonly<'Registry' | string>;
21
+ options: Readonly<{
22
+ caseInsensitive: boolean;
23
+ } | Record<string, unknown>>;
24
+ /**
25
+ * Retrieves the value associated with the specified key.
26
+ * @param key - The key to retrieve the value for.
27
+ * @returns The value associated with the key, or undefined if the key does not exist.
28
+ */
29
+ get(key: TKey): TValue | undefined;
30
+ /**
31
+ * Sets the value for the specified key.
32
+ * @param key - The key to set the value for.
33
+ * @param value - The value to set.
34
+ */
35
+ set(key: TKey, value: TValue): void;
36
+ /**
37
+ * Checks if the registry contains the specified key.
38
+ * @param key - The key to check.
39
+ * @returns True if the registry contains the key, false otherwise.
40
+ */
41
+ has(key: TKey): boolean;
42
+ /**
43
+ * Deletes the key-value pair associated with the specified key.
44
+ * @param key - The key to delete.
45
+ * @returns True if the key-value pair was deleted, false if the key does not exist.
46
+ */
47
+ delete(key: TKey): boolean;
48
+ /**
49
+ * Clears all key-value pairs from the registry.
50
+ */
51
+ clear(): void;
52
+ /**
53
+ * Gets the number of key-value pairs in the registry.
54
+ */
55
+ readonly size: number;
56
+ /**
57
+ * Gets an iterator for the keys in the registry.
58
+ */
59
+ readonly keys: IterableIterator<TKey>;
60
+ /**
61
+ * Gets an iterator for the values in the registry.
62
+ */
63
+ readonly values: IterableIterator<TValue>;
64
+ /**
65
+ * Gets an iterator for the key-value pairs in the registry.
66
+ */
67
+ readonly entries: IterableIterator<[TKey, TValue]>;
68
+ /**
69
+ * Executes a provided function once for each key-value pair in the registry.
70
+ * @param callbackfn - The function to execute for each key-value pair.
71
+ * @param thisArg - Optional value to use as `this` when executing the callback function.
72
+ */
73
+ forEach(callbackfn: (value: TValue, key: TKey, map: Map<TKey, TValue>) => void, thisArg?: unknown): void;
74
+ /**
75
+ * Returns an iterator for the entries of the registry.
76
+ * @returns An iterator that yields key-value pairs of type [TKey, unknown].
77
+ */
78
+ [Symbol.iterator](): IterableIterator<[TKey, TValue]>;
79
+ }
80
+ type RegistryEntries<TKey, TValue> = [TKey, TValue][] | Record<string | number | symbol, TValue>;
81
+
82
+ interface StackType<T> {
83
+ peek(): T;
84
+ pop(): T | undefined;
85
+ push(value: T): number;
86
+ swap(): void;
87
+ }
88
+
89
+ interface QueueType<T> {
90
+ length: number;
91
+ dequeue(): T | undefined;
92
+ enqueue(value: T): number;
93
+ peek(): T;
94
+ }
95
+
96
+ interface ScopeOptions {
97
+ global?: boolean;
98
+ caseInsensitive?: boolean;
99
+ namespace?: string;
100
+ }
101
+ interface RegistryOptionType<TKey, TValue> {
102
+ registry: Readonly<RegistryType<TKey, TValue>>;
103
+ options: Readonly<ScopeOptions>;
104
+ }
105
+ interface ScopeType<TKey, TValue> {
106
+ registries: RegistryOptionType<TKey, TValue>[];
107
+ add: (registry: RegistryOptionType<TKey, TValue>) => void;
108
+ get: (key: TKey, namespace?: string) => [TKey, TValue] | undefined;
109
+ }
110
+
111
+ /**
112
+ * Represents a registry that stores key-value pairs.
113
+ */
114
+ declare class BaseRegistry<TKey, TValue> implements RegistryType<TKey, TValue> {
115
+ private readonly _registry;
116
+ type: Readonly<string>;
117
+ /**
118
+ * Options for the base registry.
119
+ */
120
+ options: Readonly<Record<string, unknown>>;
121
+ /**
122
+ * Creates a new Registry instance.
123
+ * @param entries - Optional array of key-value pairs to initialize the registry.
124
+ */
125
+ constructor(entries?: RegistryEntries<TKey, TValue> | null);
126
+ /**
127
+ * Creates a new Registry instance from an object.
128
+ * @param object - The object containing key-value pairs.
129
+ * @returns A new Registry instance.
130
+ */
131
+ static fromObject<TKey extends string | number | symbol, TValue>(object: Record<TKey, TValue>): BaseRegistry<TKey, TValue>;
132
+ /**
133
+ * Retrieves the value associated with the specified key.
134
+ * @param key - The key to retrieve the value for.
135
+ * @returns The value associated with the key, or undefined if the key does not exist.
136
+ */
137
+ get(key: TKey): TValue | undefined;
138
+ /**
139
+ * Sets the value for the specified key.
140
+ * @param key - The key to set the value for.
141
+ * @param value - The value to set.
142
+ */
143
+ set(key: TKey, value: TValue): void;
144
+ /**
145
+ * Checks if the registry contains the specified key.
146
+ * @param key - The key to check.
147
+ * @returns True if the registry contains the key, false otherwise.
148
+ */
149
+ has(key: TKey): boolean;
150
+ /**
151
+ * Deletes the key-value pair associated with the specified key.
152
+ * @param key - The key to delete.
153
+ * @returns True if the key-value pair was deleted, false if the key does not exist.
154
+ */
155
+ delete(key: TKey): boolean;
156
+ /**
157
+ * Clears all key-value pairs from the registry.
158
+ */
159
+ clear(): void;
160
+ /**
161
+ * Gets the number of key-value pairs in the registry.
162
+ */
163
+ get size(): number;
164
+ /**
165
+ * Gets an iterator for the keys in the registry.
166
+ */
167
+ get keys(): IterableIterator<TKey>;
168
+ /**
169
+ * Gets an iterator for the values in the registry.
170
+ */
171
+ get values(): IterableIterator<TValue>;
172
+ /**
173
+ * Gets an iterator for the key-value pairs in the registry.
174
+ */
175
+ get entries(): IterableIterator<[TKey, TValue]>;
176
+ /**
177
+ * Executes a provided function once for each key-value pair in the registry.
178
+ * @param callbackfn - The function to execute for each key-value pair.
179
+ * @param thisArg - Optional value to use as `this` when executing the callback function.
180
+ */
181
+ forEach(callbackfn: (value: TValue, key: TKey, map: Map<TKey, TValue>) => void, thisArg?: TValue): void;
182
+ /**
183
+ * Returns an iterator for the entries of the registry.
184
+ * @returns An iterator that yields key-value pairs of type [TKey, TValue].
185
+ */
186
+ [Symbol.iterator](): IterableIterator<[TKey, TValue]>;
187
+ /**
188
+ * Converts a BaseRegistry instance to an object.
189
+ * @param registry The BaseRegistry instance to convert.
190
+ * @returns An object representing the key-value pairs in the registry.
191
+ */
192
+ toObject(): Record<string | number | symbol, TValue>;
193
+ }
194
+
195
+ /**
196
+ * Represents a case-insensitive registry that maps keys to values.
197
+ */
198
+ declare class CaseInsensitiveRegistry<TKey, TValue> implements RegistryType<TKey, TValue> {
199
+ private readonly registry;
200
+ private keysMap;
201
+ type: Readonly<string>;
202
+ /**
203
+ * Options for the registry.
204
+ */
205
+ options: Readonly<Record<string, unknown>>;
206
+ /**
207
+ * Creates a new instance of CaseInsensitiveRegistry.
208
+ * @param entries - Optional initial entries to populate the registry.
209
+ */
210
+ constructor(entries?: RegistryEntries<TKey, TValue> | null);
211
+ /**
212
+ * Creates a new CaseInsensitiveRegistry from an object.
213
+ * @param object - The object containing key-value pairs.
214
+ * @returns A new CaseInsensitiveRegistry instance.
215
+ */
216
+ static fromObject<TKey extends string | number | symbol, TValue>(object: Record<TKey, TValue>): CaseInsensitiveRegistry<TKey, TValue>;
217
+ /**
218
+ * Retrieves the value associated with the specified key.
219
+ * @param key - The key.
220
+ * @returns The value associated with the key, or undefined if the key is not found.
221
+ */
222
+ get(key: TKey): TValue | undefined;
223
+ /**
224
+ * Sets a key-value pair in the registry.
225
+ * @param key - The key.
226
+ * @param value - The value.
227
+ */
228
+ set(key: TKey, value: TValue): void;
229
+ /**
230
+ * Checks if the registry contains the specified key.
231
+ * @param key - The key.
232
+ * @returns True if the key is found, false otherwise.
233
+ */
234
+ has(key: TKey): boolean;
235
+ /**
236
+ * Deletes the key-value pair associated with the specified key.
237
+ * @param key - The key.
238
+ * @returns True if the key-value pair is deleted, false if the key is not found.
239
+ */
240
+ delete(key: TKey): boolean;
241
+ /**
242
+ * Clears all key-value pairs from the registry.
243
+ */
244
+ clear(): void;
245
+ /**
246
+ * Gets the number of key-value pairs in the registry.
247
+ */
248
+ get size(): number;
249
+ /**
250
+ * Gets an iterator for the keys in the registry.
251
+ */
252
+ get keys(): IterableIterator<TKey>;
253
+ /**
254
+ * Gets an iterator for the values in the registry.
255
+ */
256
+ get values(): IterableIterator<TValue>;
257
+ /**
258
+ * Gets an iterator for the key-value pairs in the registry.
259
+ */
260
+ get entries(): IterableIterator<[TKey, TValue]>;
261
+ /**
262
+ * Executes a provided function once for each key-value pair in the registry.
263
+ * @param callbackfn - The function to execute for each key-value pair.
264
+ */
265
+ forEach(callbackfn: (value: TValue, key: TKey, map: Map<TKey, TValue>) => void): void;
266
+ /**
267
+ * Returns an iterator for the entries of the registry.
268
+ * @returns An iterator that yields key-value pairs of type [string, unknown].
269
+ */
270
+ [Symbol.iterator](): IterableIterator<[TKey, TValue]>;
271
+ private getKey;
272
+ /**
273
+ * Converts a BaseRegistry instance to an object.
274
+ * @param registry The BaseRegistry instance to convert.
275
+ * @returns An object representing the key-value pairs in the registry.
276
+ */
277
+ toObject(): Record<string | number | symbol, TValue>;
278
+ }
279
+
280
+ /**
281
+ * Represents a generic registry that stores key-value pairs.
282
+ * @template TKey The type of the keys in the registry.
283
+ * @template TValue The type of the values in the registry.
284
+ */
285
+
286
+ declare class Registry<TKey, TValue> implements RegistryType<TKey, TValue> {
287
+ private readonly _registry;
288
+ type: Readonly<string>;
289
+ /**
290
+ * Options for the registry.
291
+ */
292
+ options: Readonly<Record<string, unknown>>;
293
+ /**
294
+ * Creates a new Registry instance.
295
+ * @param entries - Optional array of key-value pairs to initialize the registry.
296
+ */
297
+ constructor(entries?: RegistryEntries<TKey, TValue> | null, options?: Record<string, unknown>);
298
+ /**
299
+ * Creates a new Registry instance from an object.
300
+ * @param object - The object containing key-value pairs.
301
+ * @returns A new Registry instance.
302
+ */
303
+ static fromObject<TKey extends string | number | symbol, TValue>(object: Record<TKey, TValue>, options?: Record<string, unknown>): Registry<TKey, TValue>;
304
+ /**
305
+ * Retrieves the value associated with the specified key.
306
+ * @param key - The key to retrieve the value for.
307
+ * @returns The value associated with the key, or undefined if the key does not exist.
308
+ */
309
+ get(key: TKey): TValue | undefined;
310
+ /**
311
+ * Sets the value for the specified key.
312
+ * @param key - The key to set the value for.
313
+ * @param value - The value to set.
314
+ */
315
+ set(key: TKey, value: TValue): void;
316
+ /**
317
+ * Checks if the registry contains the specified key.
318
+ * @param key - The key to check.
319
+ * @returns True if the registry contains the key, false otherwise.
320
+ */
321
+ has(key: TKey): boolean;
322
+ /**
323
+ * Deletes the key-value pair associated with the specified key.
324
+ * @param key - The key to delete.
325
+ * @returns True if the key-value pair was deleted, false if the key does not exist.
326
+ */
327
+ delete(key: TKey): boolean;
328
+ /**
329
+ * Clears all key-value pairs from the registry.
330
+ */
331
+ clear(): void;
332
+ /**
333
+ * Gets the number of key-value pairs in the registry.
334
+ */
335
+ get size(): number;
336
+ /**
337
+ * Gets an iterator for the keys in the registry.
338
+ */
339
+ get keys(): IterableIterator<TKey>;
340
+ /**
341
+ * Gets an iterator for the values in the registry.
342
+ */
343
+ get values(): IterableIterator<TValue>;
344
+ /**
345
+ * Gets an iterator for the key-value pairs in the registry.
346
+ */
347
+ get entries(): IterableIterator<[TKey, TValue]>;
348
+ /**
349
+ * Executes a provided function once for each key-value pair in the registry.
350
+ * @param callbackfn - The function to execute for each key-value pair.
351
+ * @param thisArg - Optional value to use as `this` when executing the callback function.
352
+ */
353
+ forEach(callbackfn: (value: TValue, key: TKey, map: Map<TKey, TValue>) => void, thisArg?: TValue): void;
354
+ /**
355
+ * Returns an iterator for the entries of the registry.
356
+ * @returns An iterator that yields key-value pairs of type [TKey, TValue].
357
+ */
358
+ [Symbol.iterator](): IterableIterator<[TKey, TValue]>;
359
+ /**
360
+ * Converts a BaseRegistry instance to an object.
361
+ * @param registry The BaseRegistry instance to convert.
362
+ * @returns An object representing the key-value pairs in the registry.
363
+ */
364
+ toObject(): Record<string | number | symbol, TValue>;
365
+ }
366
+
367
+ /**
368
+ * Represents a generic queue data structure.
369
+ * @template T The type of elements stored in the queue.
370
+ */
371
+ declare class Queue<T> implements QueueType<T> {
372
+ private readonly _queue;
373
+ /**
374
+ * Creates a new instance of the Queue class.
375
+ * @param _queue Optional initial array of elements.
376
+ */
377
+ constructor(_queue?: T[]);
378
+ /**
379
+ * Gets the number of elements in the queue.
380
+ */
381
+ get length(): number;
382
+ /**
383
+ * Removes and returns the first element in the queue.
384
+ * @returns The first element in the queue, or undefined if the queue is empty.
385
+ */
386
+ dequeue(): T | undefined;
387
+ /**
388
+ * Adds an element to the end of the queue.
389
+ * @param value The element to add to the queue.
390
+ * @returns The new length of the queue.
391
+ */
392
+ enqueue(value: T): number;
393
+ /**
394
+ * Returns the first element in the queue without removing it.
395
+ * @returns The first element in the queue.
396
+ */
397
+ peek(): T;
398
+ }
399
+
400
+ /**
401
+ * Represents a stack data structure with proper memory management.
402
+ * @template T The type of elements in the stack.
403
+ */
404
+ declare class Stack<T> implements StackType<T> {
405
+ private _stack;
406
+ private _disposed;
407
+ /**
408
+ * Creates a new instance of the Stack class.
409
+ * @param _stack An optional array to initialize the stack.
410
+ */
411
+ constructor(_stack?: T[]);
412
+ /**
413
+ * Check if the stack has been disposed
414
+ */
415
+ private checkDisposed;
416
+ /**
417
+ * Gets the number of elements in the stack.
418
+ */
419
+ get length(): number;
420
+ /**
421
+ * Returns the top element of the stack without removing it.
422
+ * @returns The top element of the stack.
423
+ */
424
+ peek(): T;
425
+ /**
426
+ * Removes and returns the top element of the stack.
427
+ * @returns The top element of the stack, or undefined if the stack is empty.
428
+ */
429
+ pop(): T | undefined;
430
+ /**
431
+ * Adds an element to the top of the stack.
432
+ * @param value The element to be added to the stack.
433
+ * @returns The new length of the stack.
434
+ */
435
+ push(value: T): number;
436
+ /**
437
+ * Swaps the positions of the top two elements in the stack.
438
+ */
439
+ swap(): void;
440
+ /**
441
+ * Returns the elements of the stack as an array in reverse order.
442
+ *
443
+ * @returns An array containing the elements of the stack in reverse order.
444
+ */
445
+ asArray(): T[];
446
+ /**
447
+ * Clears all elements from the stack
448
+ */
449
+ clear(): void;
450
+ /**
451
+ * Properly dispose of the stack and clean up memory
452
+ */
453
+ dispose(): void;
454
+ /**
455
+ * Check if the stack has been disposed
456
+ */
457
+ isDisposed(): boolean;
458
+ }
459
+
460
+ /**
461
+ * Represents a cache implementation that stores key-value pairs.
462
+ * @template TValue The type of values stored in the cache.
463
+ */
464
+ declare class Cache<TValue> implements CacheType<TValue> {
465
+ private readonly _maxCacheSize;
466
+ /**
467
+ * The registry that stores the key-value pairs.
468
+ */
469
+ private readonly _registry;
470
+ /**
471
+ * The queue that keeps track of the keys in the cache.
472
+ */
473
+ private readonly _keyQueue;
474
+ type: Readonly<string>;
475
+ /**
476
+ * Options for the cache.
477
+ */
478
+ options: Readonly<Record<string, unknown>>;
479
+ /**
480
+ * Creates a new instance of the Cache class.
481
+ * @param _maxCacheSize The maximum size of the cache.
482
+ */
483
+ constructor(_maxCacheSize: number);
484
+ /**
485
+ * Gets the maximum size of the cache.
486
+ */
487
+ get maxCacheSize(): number;
488
+ /**
489
+ * Generates a hash key based on the given namespace and value.
490
+ * @param namespace The namespace for the key.
491
+ * @param value The value for the key.
492
+ * @returns The generated hash key.
493
+ */
494
+ getHashKey(namespace: string, value: string): string;
495
+ /**
496
+ * Gets the value associated with the specified key.
497
+ * @param key The key to retrieve the value for.
498
+ * @returns The value associated with the key, or undefined if the key does not exist in the cache.
499
+ */
500
+ get(key: string): TValue | undefined;
501
+ /**
502
+ * Sets the value for the specified key in the cache.
503
+ * @param key The key to set the value for.
504
+ * @param value The value to set.
505
+ */
506
+ set(key: string, value: TValue): void;
507
+ /**
508
+ * Checks if the cache contains the specified key.
509
+ * @param key The key to check.
510
+ * @returns True if the cache contains the key, false otherwise.
511
+ */
512
+ has(key: string): boolean;
513
+ /**
514
+ * Deletes the value associated with the specified key from the cache.
515
+ * @param key The key to delete.
516
+ * @returns True if the value was successfully deleted, false otherwise.
517
+ */
518
+ delete(key: string): boolean;
519
+ /**
520
+ * Clears the cache, removing all key-value pairs.
521
+ */
522
+ clear(): void;
523
+ /**
524
+ * Gets the number of key-value pairs in the cache.
525
+ */
526
+ get size(): number;
527
+ /**
528
+ * Gets an iterator for the keys in the cache.
529
+ */
530
+ get keys(): IterableIterator<string>;
531
+ /**
532
+ * Gets an iterator for the values in the cache.
533
+ */
534
+ get values(): IterableIterator<TValue>;
535
+ /**
536
+ * Gets an iterator for the entries (key-value pairs) in the cache.
537
+ */
538
+ get entries(): IterableIterator<[string, TValue]>;
539
+ /**
540
+ * Executes a provided function once for each key-value pair in the cache.
541
+ * @param callbackfn The function to execute for each key-value pair.
542
+ * @param thisArg The value to use as `this` when executing the callback function.
543
+ */
544
+ forEach(callbackfn: (value: TValue, key: string, map: Map<string, TValue>) => void, thisArg?: TValue): void;
545
+ /**
546
+ * Returns an iterator for the entries (key-value pairs) in the cache.
547
+ */
548
+ [Symbol.iterator](): IterableIterator<[string, TValue]>;
549
+ }
550
+
551
+ type EvalLookup = (key: unknown, thisArg?: unknown, options?: EvalOptions) => unknown;
552
+
553
+ interface EvalScopeOptions {
554
+ global?: boolean;
555
+ caseInsensitive?: boolean;
556
+ namespace?: string;
557
+ thisArg?: unknown;
558
+ }
559
+ /**
560
+ * Represents an evaluation scope.
561
+ */
562
+ declare class EvalScope {
563
+ type: string;
564
+ private _context;
565
+ private _options;
566
+ /**
567
+ * Gets the context of the evaluation scope.
568
+ * @returns The context object.
569
+ */
570
+ get context(): Context;
571
+ /**
572
+ * Gets the options for evaluating the scope.
573
+ * @returns The evaluation options.
574
+ */
575
+ get options(): EvalScopeOptions;
576
+ /**
577
+ * Creates a new instance of EvalScope.
578
+ * @param context - The context of the evaluation scope.
579
+ * @param options - The options for evaluating the scope.
580
+ */
581
+ constructor(context?: Context, options?: EvalScopeOptions);
582
+ /**
583
+ * Creates an instance of EvalScope from the given context and options.
584
+ *
585
+ * @param context - The context object.
586
+ * @param options - The options object.
587
+ * @returns An instance of EvalScope.
588
+ */
589
+ static fromObject(context?: Context, options?: EvalScopeOptions): EvalScope;
590
+ /**
591
+ * Gets the value of the specified key.
592
+ * @param key - The key to retrieve the value for.
593
+ * @returns The value of the specified key, or undefined if the key is not found.
594
+ */
595
+ get(key: unknown): unknown | undefined;
596
+ /**
597
+ * Sets the value of the specified key.
598
+ * @param key - The key to set the value for.
599
+ * @param value - The value to set.
600
+ */
601
+ set(key: string, value: unknown): void;
602
+ }
603
+
604
+ /**
605
+ * Represents the evaluation context for the code execution.
606
+ */
607
+ declare class EvalContext {
608
+ type: string;
609
+ private _original;
610
+ private _priorScopes;
611
+ private _scopes;
612
+ private _lookups;
613
+ private _options;
614
+ /**
615
+ * Gets the original registry.
616
+ */
617
+ get original(): Context;
618
+ /**
619
+ * Gets the scopes registry.
620
+ */
621
+ get priorScopes(): EvalScope[];
622
+ /**
623
+ * Gets the scopes registry.
624
+ */
625
+ get scopes(): Readonly<Stack<Context>>;
626
+ /**
627
+ * Gets the lookups registry.
628
+ */
629
+ get lookups(): EvalLookup[];
630
+ /**
631
+ * Gets the evaluation options.
632
+ */
633
+ get options(): EvalOptions;
634
+ /**
635
+ * Creates a new instance of EvalContext.
636
+ * @param original - The original registry or an object to create a registry from.
637
+ * @param options - The evaluation options.
638
+ */
639
+ constructor(original: Context, options: EvalOptions);
640
+ /**
641
+ * Converts the given context to an instance of EvalContext.
642
+ * @param context - The context to convert.
643
+ * @param options - The evaluation options.
644
+ * @returns The converted EvalContext instance.
645
+ */
646
+ static fromContext(context?: EvalContext | Context | undefined, options?: EvalOptions): EvalContext;
647
+ /**
648
+ * Gets the value associated with the specified key from the evaluation context.
649
+ * @param key - The key to retrieve the value for.
650
+ * @returns The value associated with the key, or undefined if not found.
651
+ */
652
+ get(key: unknown): unknown | undefined;
653
+ /**
654
+ * Step 1 of {@link get}'s resolution order on its own: the scopes pushed
655
+ * during this evaluation, innermost first.
656
+ *
657
+ * {@link get} calls this rather than inlining the loop, so that the read
658
+ * hooks' `scoped` flag and the resolution it describes are the *same*
659
+ * implementation. A second copy of the order would drift - `getKey` already
660
+ * shows what that looks like when it does.
661
+ *
662
+ * A binding whose value is `undefined` is **found** here, and no longer reads
663
+ * as absent - see {@link scopeHolding}.
664
+ *
665
+ * @param key - The key to retrieve the value for.
666
+ * @returns The value bound by the innermost scope holding the key, or
667
+ * undefined when no pushed scope holds it. The two cases are no longer
668
+ * distinguishable from the return value alone; ask {@link hasInScopes}.
669
+ */
670
+ getFromScopes(key: unknown): unknown | undefined;
671
+ /**
672
+ * The innermost pushed scope that **binds** `key`, or undefined when none
673
+ * does. The single pass behind {@link get}'s step 1, {@link getFromScopes}
674
+ * and {@link hasInScopes}, so the three cannot disagree about what the scope
675
+ * stack holds.
676
+ *
677
+ * **Binding, not value, and that is the whole point.** Reading the value and
678
+ * treating `undefined` as absent - which is what this used to do - has two
679
+ * consequences that look unrelated and are the same bug:
680
+ *
681
+ * - `let x;` could not shadow. A scope binding `x` to `undefined` fell
682
+ * through to the caller's context, so a declared-but-unset name read
683
+ * whatever the consumer happened to have under it.
684
+ * - **A plain-object scope answered for every `Object.prototype` name.**
685
+ * `getContextValue` reads a plain record as `scope[key]`, which walks the
686
+ * prototype chain, so an *empty* scope resolved `toString`, `constructor`,
687
+ * `valueOf` and friends to the prototype's own members - shadowing
688
+ * `original`, `priorScopes` and `lookups`, all four of which come later in
689
+ * {@link get}'s order. Empty as a binding surface is not empty as a lookup
690
+ * surface. `hasContextKey` is own-properties-only, which closes it.
691
+ *
692
+ * The second was invisible while only `arrow-function-expression.ts` and
693
+ * `pattern.ts` pushed scopes, because a walk that pushed none could not hit
694
+ * it; a program-level scope on every evaluation made it reachable from every
695
+ * expression, which is how it was found.
696
+ *
697
+ * It also removes an asymmetry between the two scope shapes: `fromContext`
698
+ * copies a plain record into a `Registry` when `caseInsensitive` is set, and
699
+ * a `Registry` is Map-backed, so the prototype names leaked on the
700
+ * case-sensitive path and not on the case-insensitive one. Both now ask the
701
+ * same own-key question.
702
+ *
703
+ * **Public since Phase 2 step 3, and the reason is the write sites.**
704
+ * `assignment-expression.ts` and `update-expression.ts` need the *scope* and
705
+ * not a yes/no: `const` kinds are recorded against the scope object on
706
+ * `EvalState`, so a write has to know which scope it is about to land in
707
+ * before it can decide whether the binding is reassignable. Publishing the
708
+ * single pass is what keeps that question answered by the same code as
709
+ * {@link get}'s step 1. The alternative was a second copy of the
710
+ * innermost-scope walk at each write site, which is the defect
711
+ * `docs/backlog.md` A4 and A10 already describe - two copies of one
712
+ * resolution order, drifting - reproduced on purpose.
713
+ *
714
+ * @param key - The key to look for.
715
+ * @returns The innermost scope binding the key, or undefined.
716
+ */
717
+ scopeHolding(key: unknown): Context | undefined;
718
+ /**
719
+ * Whether any scope pushed during this evaluation *binds* the key - the
720
+ * question the read hooks' `scoped` flag asks.
721
+ *
722
+ * Deliberately about binding rather than about value. It no longer parts
723
+ * company with {@link getFromScopes} over it: both go through
724
+ * {@link scopeHolding}, and `get` resolves a scope binding whatever its
725
+ * value, which is the divergence this docblock used to record as deliberate.
726
+ * Reading the flag off the value would make it depend on the *data* - the
727
+ * same arrow function over `[{ name: 'a' }]` and over `[undefined]` would
728
+ * report different bindings, and a dependency tracker's output would vary
729
+ * between two recomputes of one expression. That is the failure this flag
730
+ * exists to prevent, so presence is the correct predicate.
731
+ *
732
+ * Both queries iterate the same stack in the same direction, so neither is a
733
+ * second copy of the four-step resolution order; they answer two different
734
+ * questions about its first step.
735
+ *
736
+ * @param key - The key to look for.
737
+ * @returns True when a pushed scope holds the key, whatever its value.
738
+ */
739
+ hasInScopes(key: unknown): boolean;
740
+ /**
741
+ * Retrieves the `this` value of the specified key from the evaluation context.
742
+ * The value is searched in the original context, prior scopes, and lookup functions.
743
+ * @param key - The key to retrieve the value for.
744
+ * @returns The `this` value associated with the key, or undefined if not found.
745
+ */
746
+ getThis(key: unknown): unknown | undefined;
747
+ /**
748
+ * Retrieves the value associated with the specified key from the evaluation context.
749
+ *
750
+ * @param key - The key to retrieve the value for.
751
+ * @returns The value associated with the key, or undefined if the key is not found.
752
+ */
753
+ getKey(key: string | number | symbol): string | number | symbol | undefined;
754
+ /**
755
+ * Sets a key-value pair in the context.
756
+ * If the original context is a Registry, the key-value pair is set using the Registry's set method.
757
+ * If the original context is an Object, the key-value pair is set directly on the object.
758
+ * @param key - The key of the pair.
759
+ * @param value - The value of the pair.
760
+ */
761
+ set(key: unknown, value: unknown): void;
762
+ /**
763
+ * Assigns to the innermost pushed scope that **binds** `key`, and reports
764
+ * whether one did.
765
+ *
766
+ * The scope-aware half of the write path: `assignment-expression.ts` and
767
+ * `update-expression.ts` try this first and fall back to {@link set}. Before
768
+ * Phase 2 they only had {@link set}, which writes `_original` and consults no
769
+ * scope at all - so `(x => (x = 99))(1)` wrote `99` into the *caller's*
770
+ * object and left the arrow's parameter scope untouched.
771
+ *
772
+ * **Binding-presence, not scope-presence, and the fallback is load-bearing.**
773
+ * `eval-signals` enforces a read-only policy by subclassing this class and
774
+ * overriding {@link set} to throw, so every write that reaches the consumer's
775
+ * data goes through the one method it overrides. An implementation that wrote
776
+ * the innermost scope unconditionally - or created the binding when it was
777
+ * absent - would route such a write around that override and silently disable
778
+ * the policy of a published library, with every suite still green. Returning
779
+ * false when nothing binds the key is what keeps {@link set} reachable.
780
+ *
781
+ * What it deliberately relaxes: a write to a binding the expression itself
782
+ * created - an arrow parameter, or a `let` - no longer reaches {@link set},
783
+ * because it mutates nothing the caller owns.
784
+ *
785
+ * The write dispatches through `setContextValue` rather than through the
786
+ * prototype-pollution guard's `safeSetProperty`, and the difference is not
787
+ * cosmetic: {@link push} normalises a plain record into a `Registry` when
788
+ * `caseInsensitive` is set, and `Object.defineProperty` on a `Registry` would
789
+ * define a property on the instance while inserting nothing into its map. No
790
+ * guard is lost - this method only ever writes a key some scope already
791
+ * *binds*, and a binding can only have been created through the guarded
792
+ * declaration path, which rejects every blocklisted name.
793
+ *
794
+ * @param key - The key to assign to.
795
+ * @param value - The value to assign.
796
+ * @returns True when a pushed scope bound the key and received the write.
797
+ */
798
+ setInScope(key: unknown, value: unknown): boolean;
799
+ /**
800
+ * Pushes a context to the scope stack.
801
+ * @param context - The context to push.
802
+ * @param options - The evaluation options.
803
+ */
804
+ push(context: Context, options?: EvalOptions): void;
805
+ /**
806
+ * Pops a context from the scope stack.
807
+ */
808
+ pop(): void;
809
+ /**
810
+ * Converts the EvalContext instance to an object representation.
811
+ * If the original value is an instance of Registry, it converts it to an object using the toObject method of the registry.
812
+ * If the original value is an object, it returns the original object.
813
+ * @returns The object representation of the EvalContext instance.
814
+ */
815
+ toObject(): Record<string | number | symbol, unknown> | undefined;
816
+ }
817
+
818
+ interface EvalTraceItem {
819
+ start?: number;
820
+ end?: number;
821
+ type: string;
822
+ expression?: string;
823
+ value: unknown;
824
+ }
825
+ /**
826
+ * Represents a trace of evaluation for a specific code execution.
827
+ */
828
+ declare class EvalTrace extends Array<EvalTraceItem> {
829
+ /**
830
+ * Adds a new trace item to the evaluation trace.
831
+ * @param node - The AST node associated with the trace item.
832
+ * @param value - The value of the evaluated expression.
833
+ * @param expression - The expression being evaluated.
834
+ */
835
+ add(node: AnyNode, value?: unknown, expression?: string): void;
836
+ }
837
+
838
+ type UnknownValue = unknown | Promise<unknown>;
839
+ /**
840
+ * Represents the result of an evaluation.
841
+ */
842
+ declare class EvalResult {
843
+ private _stack;
844
+ private _value?;
845
+ private _error?;
846
+ private _errorMessage?;
847
+ private _isError?;
848
+ private _isSuccess?;
849
+ private _isUndefined?;
850
+ private _trace;
851
+ private _context;
852
+ private _startDate?;
853
+ private _endDate?;
854
+ private _expression?;
855
+ /**
856
+ * Gets the stack of evaluated values.
857
+ */
858
+ get stack(): Stack<UnknownValue>;
859
+ /**
860
+ * Gets the evaluated value.
861
+ */
862
+ get value(): UnknownValue | undefined;
863
+ /**
864
+ * Gets the error that occurred during evaluation.
865
+ */
866
+ get error(): unknown | undefined;
867
+ /**
868
+ * Gets the error message associated with the evaluation error.
869
+ */
870
+ get errorMessage(): string | undefined;
871
+ /**
872
+ * Gets whether the evaluation resulted in an error.
873
+ */
874
+ get isError(): boolean | undefined;
875
+ /**
876
+ * Gets whether the evaluation was successful.
877
+ */
878
+ get isSuccess(): boolean | undefined;
879
+ /**
880
+ * Gets whether the evaluated value is undefined.
881
+ */
882
+ get isUndefined(): boolean | undefined;
883
+ /**
884
+ * Gets the trace of evaluated values.
885
+ */
886
+ get trace(): EvalTrace;
887
+ /**
888
+ * Gets the evaluation context.
889
+ */
890
+ get context(): EvalContext;
891
+ /**
892
+ * Gets the evaluation options.
893
+ */
894
+ get options(): EvalOptions;
895
+ /**
896
+ * Gets the duration of the evaluation result.
897
+ * @returns The duration in milliseconds.
898
+ */
899
+ get duration(): number | undefined;
900
+ /**
901
+ * Gets the expression associated with the evaluation result.
902
+ * @returns The expression as a string, or undefined if no expression is associated.
903
+ */
904
+ get expression(): string | undefined;
905
+ /**
906
+ * Sets the expression for the evaluation result.
907
+ *
908
+ * @param value - The expression to be set.
909
+ */
910
+ set expression(value: string | undefined);
911
+ /**
912
+ * Creates a new instance of EvalResult.
913
+ * @param trace The trace of evaluated values.
914
+ * @param context The evaluation context.
915
+ */
916
+ constructor(context: EvalContext);
917
+ /**
918
+ * Starts the evaluation process.
919
+ */
920
+ start(): void;
921
+ /**
922
+ * Stops the evaluation and records the end date.
923
+ */
924
+ stop(): number | undefined;
925
+ /**
926
+ * Sets the success value of the evaluation result.
927
+ *
928
+ * @param value The value to set as the success value.
929
+ * @returns void
930
+ */
931
+ setSuccess(value: UnknownValue): void;
932
+ /**
933
+ * Sets the failure state of the evaluation result.
934
+ * @param error The error object associated with the failure.
935
+ */
936
+ setFailure(error: unknown): void;
937
+ }
938
+
939
+ /**
940
+ * Represents the evaluation state, which includes the context, result, and options.
941
+ */
942
+ declare class EvalState {
943
+ private _context;
944
+ private _result;
945
+ private _options;
946
+ private _isAsync;
947
+ private _hooks;
948
+ private _hookBookkeeping;
949
+ private _walkDepth;
950
+ private _iterationBudget;
951
+ private _iterationsRemaining;
952
+ private _constBindings;
953
+ /**
954
+ * Gets the evaluation context.
955
+ */
956
+ get context(): EvalContext | undefined;
957
+ /**
958
+ * Gets the evaluation result.
959
+ */
960
+ get result(): EvalResult;
961
+ /**
962
+ * Gets the evaluation options.
963
+ */
964
+ get options(): EvalOptions | undefined;
965
+ /**
966
+ * Gets whether the evaluation is asynchronous.
967
+ */
968
+ get isAsync(): boolean | undefined;
969
+ /**
970
+ * Gets the hook registry for this evaluation, creating an empty one on first
971
+ * access. A registry supplied through `options.hooks` is adopted instead.
972
+ *
973
+ * Merely reading this does not turn {@link hasHooks} on; registering does.
974
+ */
975
+ get hooks(): EvalHooks;
976
+ /**
977
+ * The dispatch guard read by `beforeVisitor` / `afterVisitor`. One field read
978
+ * and no options lookup, so the no-hooks path stays cheap.
979
+ */
980
+ get hasHooks(): boolean;
981
+ /**
982
+ * Errors raised by hooks during this evaluation and collected under the
983
+ * 'collect' policy.
984
+ *
985
+ * They live here rather than on {@link hooks} because an `EvalHooks` may be
986
+ * shared across evaluations, and an error describes one run.
987
+ *
988
+ * The array is the live one, so a reference taken before evaluating fills as
989
+ * errors arrive. Returning a shared empty array until the first collection
990
+ * would be cheaper by one allocation and wrong: the reference would silently
991
+ * stop tracking the moment anything was collected.
992
+ */
993
+ get hookErrors(): readonly EvalHookError[];
994
+ /**
995
+ * Per-node-type timings for **this state**, keyed by node type. Empty unless
996
+ * a timing hook was installed - by `options.trackTime`, or by the caller
997
+ * through `createTimingHook().install(state.hooks)`.
998
+ *
999
+ * Accumulates for the life of the state, not per `evaluate` call: under the
1000
+ * `createState` + repeated `eval` style the counts are the running totals
1001
+ * across every run on this state, which is what makes them comparable. A
1002
+ * caller who wants per-run figures uses a fresh state, or drops these along
1003
+ * with the rest of the run record via {@link resetHookBookkeeping}.
1004
+ *
1005
+ * Here rather than on the handle `createTimingHook` returns for the same
1006
+ * reason {@link hookErrors} is: timings describe one run, and an `EvalHooks`
1007
+ * may be handed to several. It is also the only place a `trackTime` caller
1008
+ * could reach them, since that installation happens in this constructor and
1009
+ * hands the handle to nobody.
1010
+ *
1011
+ * Totals are inclusive of child nodes; see `EvalNodeTiming`.
1012
+ */
1013
+ get nodeTimings(): ReadonlyMap<AnyNodeTypes, EvalNodeTiming>;
1014
+ /**
1015
+ * The per-run bookkeeping `EvalHooks` reads and writes: the open-node stack
1016
+ * and the collected errors, grouped behind a single accessor.
1017
+ *
1018
+ * The state owns this storage and `eval-hooks.ts` only type-imports the
1019
+ * state, which keeps the runtime import graph acyclic. Holding it in a
1020
+ * module-private `WeakMap` inside `eval-hooks.ts` was the alternative and was
1021
+ * rejected: `hookErrors` would then need a *runtime* import of that module
1022
+ * while it already imports this one, and the resulting cycle is a hazard in
1023
+ * the ng-packagr build.
1024
+ *
1025
+ * @internal Not part of the published API.
1026
+ */
1027
+ get hookBookkeeping(): EvalHookBookkeeping;
1028
+ /**
1029
+ * How many `evaluate` / `evaluateAsync` calls on this state are currently on
1030
+ * the JavaScript stack: 0 between evaluations, 1 during an ordinary walk, and
1031
+ * more while a nested walk runs - an arrow-function body is re-entrant
1032
+ * `evaluate` on this same state.
1033
+ *
1034
+ * Maintained by {@link enterWalk} / {@link exitWalk}, which the entry points
1035
+ * pair around their walk, the exit in a `finally` so a throw still restores
1036
+ * the count.
1037
+ *
1038
+ * **Deliberately not merged with `EvalHookBookkeeping.walkBases`**, which
1039
+ * tracks the same nesting one level down. That stack is pushed only under
1040
+ * {@link hasHooks}, because bounding `EvalHooks.exit` is meaningless with no
1041
+ * hooks to dispatch; this counter must be maintained unconditionally, because
1042
+ * § 3.4's iteration budget refills on the outermost entry and a loop is
1043
+ * bounded whether or not anyone is listening. One field cannot be both
1044
+ * guarded and unguarded, so there are two.
1045
+ *
1046
+ * @internal Not part of the published API.
1047
+ */
1048
+ get walkDepth(): number;
1049
+ /**
1050
+ * Records that a walk is starting on this state and returns the new depth, so
1051
+ * a caller can recognise the outermost entry as `=== 1` without a second
1052
+ * read.
1053
+ *
1054
+ * **Refills {@link iterationsRemaining} on the outermost entry**, which is
1055
+ * what makes § 3.4's budget per-`evaluate` rather than per-state. It happens
1056
+ * here rather than at the entry points so that both of them - and any later
1057
+ * one - get it without a second copy of the 0 -> 1 test; the depth this
1058
+ * method already owns is the only thing the decision needs.
1059
+ *
1060
+ * @internal Not part of the published API.
1061
+ */
1062
+ enterWalk(): number;
1063
+ /**
1064
+ * Records that a walk has finished. Called from the entry point's `finally`.
1065
+ *
1066
+ * @internal Not part of the published API.
1067
+ */
1068
+ exitWalk(): void;
1069
+ /**
1070
+ * How many loop iterations this evaluation may still run.
1071
+ *
1072
+ * Refilled by {@link enterWalk} on the outermost entry from
1073
+ * `options.maxIterations`, defaulting to 100,000, and spent one at a time by
1074
+ * {@link chargeIteration}. `Infinity` when the caller opted out.
1075
+ *
1076
+ * Readable mainly so a spec can assert what a walk charged: nothing in the
1077
+ * library reads it except {@link chargeIteration}, and no expression without a
1078
+ * `for` in it moves it.
1079
+ *
1080
+ * @internal Not part of the published API.
1081
+ */
1082
+ get iterationsRemaining(): number;
1083
+ /**
1084
+ * Charges one loop iteration against the budget, throwing when it is spent.
1085
+ *
1086
+ * Called from `for-statement.ts`'s iteration loop and **nowhere else**, which
1087
+ * is § 3.4's cost argument in its literal form: the no-loop path does not
1088
+ * execute a cheaper version of this check, it does not reach the call site at
1089
+ * all. The rejected alternative - a per-node fuel counter in `beforeVisitor` -
1090
+ * would have been on the hot path of every evaluation in the library, to bound
1091
+ * a recursion depth this phase does not introduce.
1092
+ *
1093
+ * The message names the **configured** budget rather than the default, since a
1094
+ * caller who set `maxIterations` needs to recognise their own number in it.
1095
+ *
1096
+ * @internal Not part of the published API.
1097
+ */
1098
+ chargeIteration(): void;
1099
+ /**
1100
+ * Records that `key` was declared `const` in `scope`, so a later write to it
1101
+ * can be rejected.
1102
+ *
1103
+ * **Keyed by the scope *object*, and beside the scope rather than in it.** A
1104
+ * metadata key written onto the scope record would itself be resolvable as a
1105
+ * binding name - `getContextValue` reads the same surface a declaration binds
1106
+ * into - so `let __kind` would be readable from an expression. A `WeakMap`
1107
+ * hanging off the state has neither problem, and it is checked at the write
1108
+ * site only, so reads pay nothing.
1109
+ *
1110
+ * **The scope passed here must be the one on the stack**, not the record a
1111
+ * visitor built to push: `EvalContext.push` routes through `fromContext`,
1112
+ * which *copies* a plain record into a `Registry` when `caseInsensitive` is
1113
+ * set. Keying on the pre-push record would file every `const` under an object
1114
+ * the write site can never produce, and `caseInsensitive` alone would lose
1115
+ * const-ness silently. `EvalContext.scopeHolding` returns the stack's object,
1116
+ * which is what both sides use.
1117
+ *
1118
+ * The entries die with the scopes: scope objects are created per block entry
1119
+ * and dropped when the block exits, so nothing here outlives the walk even
1120
+ * though the state may.
1121
+ *
1122
+ * @internal Not part of the published API.
1123
+ */
1124
+ declareConst(scope: Context, key: unknown): void;
1125
+ /**
1126
+ * Whether `key` was declared `const` in `scope`.
1127
+ *
1128
+ * Asked by `assignment-expression.ts` and `update-expression.ts` of the scope
1129
+ * the write is about to land in, so an inner `let` of a name an outer scope
1130
+ * declared `const` stays writable - the kind belongs to the binding, not to
1131
+ * the name.
1132
+ *
1133
+ * @internal Not part of the published API.
1134
+ */
1135
+ isConstBinding(scope: Context, key: unknown): boolean;
1136
+ /**
1137
+ * Drops every per-run record this state holds: the collected hook errors, the
1138
+ * open-node stack, the accumulated timings, and the walk bases bounding
1139
+ * `EvalHooks.exit`.
1140
+ *
1141
+ * It resets the whole record rather than only the errors, which is why it is
1142
+ * not named for them. `EvalHooks.clear` cannot reach any of this - the
1143
+ * bookkeeping belongs to the state - so without this method nothing drains
1144
+ * the open-node stack at all. Frames left on it keep their AST nodes
1145
+ * reachable for as long as the state is, and `EvalService` holds its states
1146
+ * in a strong `Set`.
1147
+ *
1148
+ * The errors matter for the same reason under the state-first style:
1149
+ * `createState` plus repeated `eval` on one state accumulates them for the
1150
+ * life of that state, and a thrown value can close over consumer objects.
1151
+ *
1152
+ * The record is replaced rather than emptied in place, so a caller still
1153
+ * holding the array {@link hookErrors} handed out keeps its own contents and
1154
+ * simply stops tracking - the alternative would mutate a collection the
1155
+ * caller owns a reference to.
1156
+ *
1157
+ * Calling this mid-walk is unsupported for the same reason `EvalHooks.clear`
1158
+ * is: it abandons frames the dispatcher expects to close.
1159
+ */
1160
+ resetHookBookkeeping(): void;
1161
+ /**
1162
+ * Represents the state of an evaluation.
1163
+ * @param context The evaluation context.
1164
+ * @param result The evaluation result.
1165
+ * @param options The evaluation options.
1166
+ * @param isAsync Indicates whether the evaluation is asynchronous.
1167
+ */
1168
+ constructor(context: EvalContext | undefined, result: EvalResult, options?: EvalOptions, isAsync?: boolean);
1169
+ /**
1170
+ * Creates an instance of EvalState from a given context, options, and async flag.
1171
+ *
1172
+ * @param context - The evaluation context or context object.
1173
+ * @param options - The evaluation options.
1174
+ * @param isAsync - A flag indicating whether the evaluation is asynchronous.
1175
+ * @returns The created EvalState instance.
1176
+ */
1177
+ static fromContext(context?: EvalContext | Context, options?: EvalOptions, isAsync?: boolean): EvalState;
1178
+ }
1179
+
1180
+ /**
1181
+ * The two points at which a visitor brackets its body.
1182
+ */
1183
+ type EvalHookPhase = 'before' | 'after';
1184
+ /**
1185
+ * Payload handed to a node hook.
1186
+ */
1187
+ interface EvalNodeHookEvent {
1188
+ readonly phase: EvalHookPhase;
1189
+ readonly node: AnyNode;
1190
+ readonly state: EvalState;
1191
+ /** Value pushed by the visitor; only present on 'after'. */
1192
+ readonly value?: unknown;
1193
+ /** False when this 'after' event was synthesised rather than dispatched by a visitor. */
1194
+ readonly completed: boolean;
1195
+ /**
1196
+ * The error that aborted evaluation.
1197
+ *
1198
+ * Present only on events synthesised by `unwindTo`, where evaluation really
1199
+ * did fail. Frames closed by `exit` - because an enclosing visitor moved on
1200
+ * without them - also carry `completed: false`, but no error: nothing threw,
1201
+ * and the evaluation may well succeed. Test for the property rather than
1202
+ * assuming `completed: false` implies one.
1203
+ */
1204
+ readonly error?: unknown;
1205
+ }
1206
+ /**
1207
+ * A node hook. Hooks are observers: they are called for their side effects and
1208
+ * their return value is discarded. A hook that returns a promise is *not*
1209
+ * awaited - see {@link ASYNC_HOOK_MESSAGE}.
1210
+ */
1211
+ type EvalNodeHook = (event: EvalNodeHookEvent) => void;
1212
+ /**
1213
+ * Which resolution produced a read event.
1214
+ */
1215
+ type EvalReadKind = 'identifier' | 'member';
1216
+ /**
1217
+ * Payload handed to a read hook: one resolved context read.
1218
+ *
1219
+ * Node hooks cannot report *which key* an expression read - the AST node alone
1220
+ * is not enough once case correction and computed members are in play - so this
1221
+ * is the event a dependency tracker actually needs.
1222
+ */
1223
+ interface EvalReadEvent {
1224
+ readonly kind: EvalReadKind;
1225
+ readonly node: AnyNode;
1226
+ readonly state: EvalState;
1227
+ /** The key as resolved against the context (case-corrected when caseInsensitive). */
1228
+ readonly key: string | number | symbol;
1229
+ /** The object the key was read from - the context, an EvalScope, or a plain object. */
1230
+ readonly target: unknown;
1231
+ /**
1232
+ * Dotted path when statically reconstructible (`a.b.c`), else undefined.
1233
+ *
1234
+ * Reconstructed from the source spelling, so it is *not* case-corrected even
1235
+ * when {@link key} is. Computed members (`obj[expr]`) yield undefined; their
1236
+ * `key` is still exact.
1237
+ */
1238
+ readonly path?: string;
1239
+ readonly value: unknown;
1240
+ /**
1241
+ * True when the key resolved from a scope pushed *during this evaluation* -
1242
+ * `EvalContext.scopes`, the stack `arrow-function-expression.ts` pushes and
1243
+ * pops around a call. Such a read is an arrow-function parameter binding,
1244
+ * not a dependency, and a tracker should skip it.
1245
+ *
1246
+ * The definition is **lifetime, not type**: caller-registered `priorScopes`
1247
+ * are `EvalScope` instances holding long-lived objects and are real
1248
+ * dependencies, so they are never flagged. Absent reads as "not scoped",
1249
+ * which is right for every member emission site.
1250
+ */
1251
+ readonly scoped?: boolean;
1252
+ }
1253
+ /**
1254
+ * A read hook. Like a node hook it is an observer: its return value is
1255
+ * discarded and a returned promise is not awaited.
1256
+ */
1257
+ type EvalReadHook = (event: EvalReadEvent) => void;
1258
+ /**
1259
+ * Removes the hook that returned it. Calling it more than once is a no-op.
1260
+ */
1261
+ type Unsubscribe = () => void;
1262
+ /**
1263
+ * What to do with an error raised by a hook.
1264
+ *
1265
+ * - `collect` (default) - wrap it, append it to `state.hookErrors`, keep evaluating.
1266
+ * - `throw` - rethrow it into the visitor, failing the evaluation.
1267
+ * - `ignore` - swallow it silently.
1268
+ */
1269
+ type EvalHookErrorPolicy = 'collect' | 'throw' | 'ignore';
1270
+ /**
1271
+ * An error raised by a hook, recorded under the 'collect' policy.
1272
+ *
1273
+ * `phase` is `'read'` for an error raised by a read hook: a read is neither of
1274
+ * the two node phases, and reporting one as 'before' or 'after' would mislead a
1275
+ * consumer reading the log.
1276
+ */
1277
+ interface EvalHookError {
1278
+ readonly phase: EvalHookPhase | 'read';
1279
+ readonly nodeType: AnyNodeTypes;
1280
+ readonly error: unknown;
1281
+ }
1282
+ /**
1283
+ * How long one node type took over an evaluation, accumulated by the timing
1284
+ * hook and read back as `EvalState.nodeTimings`.
1285
+ *
1286
+ * `total` is *inclusive*: a node's children are counted in its own elapsed
1287
+ * time, so the totals of nested types overlap and summing them exceeds the
1288
+ * walk's duration. Per-type comparison is what this supports; a breakdown that
1289
+ * adds up is not.
1290
+ */
1291
+ interface EvalNodeTiming {
1292
+ /** How many nodes of this type were visited. */
1293
+ readonly count: number;
1294
+ /** Inclusive elapsed milliseconds across all of them. */
1295
+ readonly total: number;
1296
+ }
1297
+ /**
1298
+ * The bookkeeping an `EvalHooks` accumulates over a single evaluation.
1299
+ *
1300
+ * It is grouped behind one accessor on `EvalState` rather than spread across
1301
+ * several members, and it lives on the state rather than on the registry: an
1302
+ * `EvalHooks` is consumer-owned and may be handed to several evaluations, so
1303
+ * anything whose lifetime is one run belongs to the run.
1304
+ *
1305
+ * @internal Not part of the published API; `EvalHooks` is its only writer.
1306
+ */
1307
+ interface EvalHookBookkeeping {
1308
+ /** Nodes whose 'before' has fired but whose 'after' has not, outermost first. */
1309
+ readonly open: AnyNode[];
1310
+ /** Hook errors recorded under the 'collect' policy. */
1311
+ readonly errors: EvalHookError[];
1312
+ /**
1313
+ * Per-node-type timings, written by the timing hook when one is installed and
1314
+ * left empty otherwise.
1315
+ *
1316
+ * It lives here rather than on the handle `createTimingHook` returns for two
1317
+ * reasons. A registry may be shared across evaluations, so totals held on the
1318
+ * handle would bleed one run into the next - the same argument that moved the
1319
+ * error list here. And `trackTime` installs the hook from inside the
1320
+ * `EvalState` constructor, where no caller ever sees the handle: totals on it
1321
+ * would be unreachable, which is a dead option rather than a feature.
1322
+ */
1323
+ readonly timings: Map<AnyNodeTypes, EvalNodeTiming>;
1324
+ /**
1325
+ * One entry per `evaluate` call currently on the JavaScript stack: the
1326
+ * {@link open} depth that call found when it started, innermost last.
1327
+ *
1328
+ * `evaluate` already captured this as a local to hand to
1329
+ * {@link EvalHooks.unwindTo}; it lives here as well because {@link
1330
+ * EvalHooks.exit} needs it too and is called from a visitor, which has no
1331
+ * route to that local. Without it `exit` cannot tell "absent from this walk"
1332
+ * from "absent from the stack" and closes frames belonging to an enclosing
1333
+ * walk.
1334
+ *
1335
+ * Pushed and popped only under `state.hasHooks`, so an evaluation with no
1336
+ * hooks pays nothing for it. An empty stack therefore reads as base 0 -
1337
+ * unbounded, which is the right answer for a walk that began before any hook
1338
+ * existed and so pushed no base.
1339
+ *
1340
+ * This is **not** `EvalState.walkDepth`, and the two cannot be merged: that
1341
+ * counter is unguarded because § 3.4's iteration budget must refill on the
1342
+ * outermost entry whether or not hooks are registered, while these bases are
1343
+ * hook bookkeeping and are absent on the default path by design. A later
1344
+ * phase reading "two counters" should read this paragraph first.
1345
+ */
1346
+ readonly walkBases: number[];
1347
+ }
1348
+ /**
1349
+ * The message carried by the error raised when a hook returns a promise.
1350
+ *
1351
+ * Hooks are synchronous by contract (§ 3.3): the walk is synchronous even under
1352
+ * `evaluateAsync`, so a returned promise is never awaited and whatever the hook
1353
+ * meant to do lands after the evaluation finished. The dispatcher reports it as
1354
+ * an error carrying this message, routed through the configured policy like any
1355
+ * other hook error - collected by default, and thrown into the visitor under
1356
+ * `'throw'`, which does fail the evaluation.
1357
+ *
1358
+ * Exported so a consumer inspecting `EvalState.hookErrors` can tell this
1359
+ * diagnostic apart from an error its own hook threw, without matching on
1360
+ * message text it would have to keep in sync by hand.
1361
+ */
1362
+ declare const ASYNC_HOOK_MESSAGE = "async hook returned a promise; it will not be awaited";
1363
+ /**
1364
+ * The completion value of a statement that produced nothing.
1365
+ *
1366
+ * JavaScript's completion-value semantics keep the last **non-empty** value, and
1367
+ * empty is not the same as `undefined`: `{ 'a'; noop() }` is `undefined` because
1368
+ * the call genuinely produced one, while `{ 'a'; ; }` is `'a'` because the empty
1369
+ * statement produced nothing at all. A statement visitor that produced no value
1370
+ * therefore pushes this rather than `undefined`, and an enclosing block keeps the
1371
+ * last value that is not this.
1372
+ *
1373
+ * It never reaches an evaluation's return value: `evaluate` and `evaluateAsync`
1374
+ * convert it to `undefined` at the walk boundary, immediately after popping the
1375
+ * result. It **is** reachable in a hook event, because `afterVisitor` reads the
1376
+ * value positionally off the top of the result stack - so an 'after' hook on a
1377
+ * statement that produced nothing observes this sentinel. Hiding it there is not
1378
+ * available: the alternatives are calling `afterVisitor` before the push, which
1379
+ * reports the neighbour's value, or normalising inside `afterVisitor`, which puts
1380
+ * a per-node cost on the hot path for a case only statements produce.
1381
+ *
1382
+ * Exported for that reason, on the precedent of {@link ASYNC_HOOK_MESSAGE}: a
1383
+ * consumer whose hook receives it can recognise it by identity rather than by
1384
+ * guessing at a value it would have to keep in sync by hand.
1385
+ */
1386
+ declare const EMPTY_COMPLETION: unique symbol;
1387
+ /**
1388
+ * A registry of node hooks, keyed by node type with wildcard support, and the
1389
+ * dispatcher that keeps `before` and `after` balanced when a visitor throws.
1390
+ *
1391
+ * It holds *registration* only. Everything whose lifetime is a single
1392
+ * evaluation - the open-node stack and the collected errors - lives on the
1393
+ * `EvalState` instead, because a consumer may hand one `EvalHooks` to several
1394
+ * evaluations and expect each to observe both.
1395
+ *
1396
+ * Hooks are synchronous by design: the walk in `evaluate` is synchronous even
1397
+ * under `evaluateAsync`, so there is no point at which a hook could be awaited.
1398
+ */
1399
+ declare class EvalHooks {
1400
+ private readonly _before;
1401
+ private readonly _after;
1402
+ private _read;
1403
+ private readonly _policy;
1404
+ private _size;
1405
+ private _active;
1406
+ /**
1407
+ * @param options The evaluation options; `onHookError` selects the error policy.
1408
+ */
1409
+ constructor(options?: EvalOptions);
1410
+ /**
1411
+ * True while no hook is registered. Read on the hot path, so it is a counter
1412
+ * rather than a walk of the registries.
1413
+ */
1414
+ get isEmpty(): boolean;
1415
+ /**
1416
+ * The dispatch guard, behind `EvalState.hasHooks`.
1417
+ *
1418
+ * Unlike {@link isEmpty} this *latches*: it turns true on the first
1419
+ * registration and only `clear` turns it off again. The guard wraps the
1420
+ * open-node stack as well as the hooks themselves, so a value that changed
1421
+ * mid-walk would leave `enter` and `exit` unpaired - which is exactly what
1422
+ * one-shot and self-unsubscribing hooks would otherwise cause.
1423
+ *
1424
+ * Calling `clear` during a walk is therefore unsupported.
1425
+ */
1426
+ get isActive(): boolean;
1427
+ /**
1428
+ * True while at least one read hook is registered.
1429
+ *
1430
+ * The second half of the read-emission guard: `st.hasHooks` says a registry
1431
+ * exists and has been used, this says a *read* hook is there to observe the
1432
+ * event. Without it a consumer that registered only 'before'/'after' hooks
1433
+ * would pay `getKey` per identifier and `readPath` plus an object literal per
1434
+ * member for events it can never see - which the timing hook turns from
1435
+ * theoretical into routine, since it latches `hasHooks` for a whole walk.
1436
+ *
1437
+ * **Non-latching, unlike {@link isActive}.** That getter latches because it
1438
+ * wraps the open-node stack, so a value changing mid-walk would leave `enter`
1439
+ * and `exit` unpaired. `dispatchRead` touches no bookkeeping, so a read guard
1440
+ * that flips mid-walk can only drop read events - never unbalance anything.
1441
+ * A one-shot or self-unsubscribing read hook is therefore safe here, and the
1442
+ * guard can report the current registration count rather than history.
1443
+ */
1444
+ get hasReadHooks(): boolean;
1445
+ /**
1446
+ * Registers a node hook.
1447
+ * @param phase Whether to fire before or after the visitor body.
1448
+ * @param type A concrete node type, or '*' for every node.
1449
+ * @param hook The hook to register.
1450
+ * @returns A function that removes this hook.
1451
+ */
1452
+ on(phase: EvalHookPhase, type: AnyNodeTypes | '*', hook: EvalNodeHook): Unsubscribe;
1453
+ /**
1454
+ * Registers a read hook, fired once per resolved context read.
1455
+ *
1456
+ * Read hooks are not keyed by node type: there are only two emission points
1457
+ * and a consumer filters on {@link EvalReadEvent.kind} if it cares.
1458
+ *
1459
+ * Registration latches {@link isActive} exactly as {@link on} does, because
1460
+ * the visitors reach their emission points through the same
1461
+ * `EvalState.hasHooks` guard.
1462
+ *
1463
+ * @param hook The hook to register.
1464
+ * @returns A function that removes this hook.
1465
+ */
1466
+ onRead(hook: EvalReadHook): Unsubscribe;
1467
+ /**
1468
+ * Removes one read hook, or every read hook when `hook` is omitted.
1469
+ */
1470
+ offRead(hook?: EvalReadHook): void;
1471
+ /**
1472
+ * Removes one hook, or every hook registered for a key when `hook` is omitted.
1473
+ */
1474
+ off(phase: EvalHookPhase, type: AnyNodeTypes | '*', hook?: EvalNodeHook): void;
1475
+ /**
1476
+ * Removes every hook from both phases and unlatches {@link isActive}.
1477
+ *
1478
+ * Per-run bookkeeping is untouched: the open-node stack and the collected
1479
+ * errors belong to the `EvalState`, not to this registry. Errors in
1480
+ * particular are a record of what already happened.
1481
+ */
1482
+ clear(): void;
1483
+ /**
1484
+ * Fires the hooks registered for a node, keyed first and wildcard second.
1485
+ *
1486
+ * Bookkeeping runs before user code on both edges: 'before' pushes the node
1487
+ * onto the open-node stack and *then* emits, 'after' pops and *then* emits.
1488
+ * The shared rule is that hook code only ever runs once the stack already
1489
+ * tells the truth about this node, because `emit` can throw - under the
1490
+ * 'throw' policy a hook's error propagates out of it. Emitting first on the
1491
+ * 'before' edge would leave a node that some hooks had already been told
1492
+ * about missing from the stack, and therefore invisible to `unwindTo`.
1493
+ *
1494
+ * @param value The value the visitor pushed; meaningful on 'after' only.
1495
+ */
1496
+ dispatch(phase: EvalHookPhase, node: AnyNode, state: EvalState, value?: unknown): void;
1497
+ /**
1498
+ * Fires the read hooks for one resolved context read.
1499
+ *
1500
+ * The event is built by the caller rather than assembled from positional
1501
+ * arguments here, so the visitors allocate nothing on the no-hooks path: the
1502
+ * whole construction sits inside their `st.hasHooks` guard.
1503
+ *
1504
+ * Touches no bookkeeping. A read is not a frame - it happens *within* a
1505
+ * node's before/after pair, so the open-node stack is none of its business.
1506
+ */
1507
+ dispatchRead(event: EvalReadEvent): void;
1508
+ /**
1509
+ * Records a node as open on the state. Called by the 'before' dispatcher
1510
+ * before its hooks fire.
1511
+ */
1512
+ enter(node: AnyNode, state: EvalState): void;
1513
+ /**
1514
+ * Closes `node`, matching it by **identity** rather than by position. Called
1515
+ * by the 'after' dispatcher before its hooks fire.
1516
+ *
1517
+ * Three cases:
1518
+ *
1519
+ * 1. `node` is on top - pop it. The ordinary path, one reference comparison.
1520
+ * 2. `node` is open but not on top - some visitor between here and there
1521
+ * never closed itself. Flush those frames innermost-first as
1522
+ * `completed: false`, then pop `node`.
1523
+ * 3. `node` is not open at all - pop nothing and emit nothing.
1524
+ *
1525
+ * Case 3 is what keeps a stray `exit` from draining the stack: the naive
1526
+ * "pop until you find it" would walk to the bottom, synthesise an event for
1527
+ * every genuinely-open enclosing frame, and leave a later real failure with
1528
+ * nothing to unwind.
1529
+ *
1530
+ * **"Open" means open in *this* walk.** Both routes below are bounded by the
1531
+ * current walk base ({@link EvalHookBookkeeping.walkBases}), so a node open
1532
+ * only in an enclosing walk falls into case 3 by either route - which is the
1533
+ * behaviour case 3 already specifies for "not open at all". `evaluate` is
1534
+ * re-entered with the same state from an arrow-function body, so without the
1535
+ * bound a nested walk closing a node it never opened would flush the
1536
+ * enclosing walk's frames under `completed: false` events a consumer reads as
1537
+ * ordinary completions, and leave that walk's own `unwindTo(mark)` with
1538
+ * nothing left to unwind.
1539
+ *
1540
+ * The bound is needed on the **identity fast path** as much as on the scan:
1541
+ * when a nested walk has opened nothing yet, the top of the stack *is* the
1542
+ * enclosing walk's node, so the cheap route crosses the boundary without ever
1543
+ * reaching the scan.
1544
+ *
1545
+ * Popping positionally instead would be correct only if every visitor
1546
+ * bracketed its body exactly. `await-expression.ts` does not - it catches a
1547
+ * child's synchronous throw and continues to its own `afterVisitor` - so a
1548
+ * positional pop closes the child's frame under the parent's name, drops the
1549
+ * child's `after` entirely, and leaks one frame onto the state for good.
1550
+ *
1551
+ * The synthesised events carry no `value` (the node never pushed one) and no
1552
+ * `error` (nothing threw; the frames are being closed because an enclosing
1553
+ * visitor moved on without them).
1554
+ *
1555
+ * They are emitted under the collect policy even when the consumer chose
1556
+ * 'throw'. That is required, not merely lenient: a rethrow here would escape
1557
+ * the flush loop before it finished popping, re-creating the leak this
1558
+ * identity check exists to prevent. A 'throw'-policy consumer sees these in
1559
+ * `state.hookErrors` instead.
1560
+ */
1561
+ exit(state: EvalState, node: AnyNode): void;
1562
+ /**
1563
+ * How many nodes the state has open. Captured as a mark before a walk, since
1564
+ * `evaluate` is re-entered with the same state from an arrow-function body.
1565
+ *
1566
+ * This is a method rather than a getter because the stack it measures lives
1567
+ * on the state, not on this registry.
1568
+ */
1569
+ depth(state: EvalState): number;
1570
+ /**
1571
+ * Records that a walk is starting at the state's current open depth, and
1572
+ * returns that depth. Called by `evaluate` / `evaluateAsync` on entry, under
1573
+ * their `hasHooks` guard, and paired with {@link popWalkBase} in a `finally`.
1574
+ *
1575
+ * The returned value is the same mark those entry points hand to
1576
+ * {@link unwindTo}, so they capture it once rather than reading the depth
1577
+ * twice.
1578
+ */
1579
+ pushWalkBase(state: EvalState): number;
1580
+ /**
1581
+ * Drops the innermost walk base. Called from the `finally` of the `evaluate`
1582
+ * that pushed it, so an entry point whose walk threw still restores the
1583
+ * enclosing walk's bound.
1584
+ */
1585
+ popWalkBase(state: EvalState): void;
1586
+ /**
1587
+ * The open depth the innermost walk in progress started at, and the floor
1588
+ * {@link exit} will not reach below.
1589
+ *
1590
+ * Zero when no base has been pushed, which leaves `exit` behaving exactly as
1591
+ * it did before the bound existed - the correct answer for a walk that began
1592
+ * before any hook was registered, since it pushed no base.
1593
+ */
1594
+ walkBase(state: EvalState): number;
1595
+ /**
1596
+ * Fires 'after' for every node the state has open above `mark`, innermost
1597
+ * first, marked incomplete. Invoked from the catch in `evaluate`, so that a
1598
+ * visitor which throws still leaves every 'before' matched by exactly one
1599
+ * 'after'.
1600
+ *
1601
+ * Unwinding to a mark rather than to the bottom is what keeps a nested
1602
+ * `evaluate` from draining the enclosing walk's open nodes when a host
1603
+ * function swallows the nested throw.
1604
+ *
1605
+ * Idempotent, so the sync and async entry points can both call it.
1606
+ *
1607
+ * A hook that throws here cannot stop the drain: while unwinding, the 'throw'
1608
+ * policy is downgraded to 'collect' - evaluation has already failed, and the
1609
+ * original error is the one worth propagating.
1610
+ */
1611
+ unwindTo(mark: number, error: unknown, state: EvalState): void;
1612
+ /**
1613
+ * Drains the state's whole open-node stack. Equivalent to `unwindTo(0, ...)`,
1614
+ * for callers that own the entire walk.
1615
+ */
1616
+ unwind(error: unknown, state: EvalState): void;
1617
+ private registry;
1618
+ private emit;
1619
+ /**
1620
+ * Iterates a copy so that a hook which unsubscribes itself does not shift the
1621
+ * list out from under the loop.
1622
+ */
1623
+ private invokeAll;
1624
+ private invoke;
1625
+ /**
1626
+ * The read counterpart of {@link invoke}. There is no unwinding equivalent
1627
+ * for reads - a read never opens a frame - so the policy always applies in
1628
+ * full.
1629
+ */
1630
+ private invokeRead;
1631
+ private handleError;
1632
+ }
1633
+
1634
+ /**
1635
+ * Represents the options for evaluating expressions.
1636
+ *
1637
+ * Deliberately a permissive record: callers pass their own keys through it, and
1638
+ * `EvalContext` / `EvalScope` forward the same object around. Narrowing it to
1639
+ * {@link EvalKnownOptions} would break every caller holding a
1640
+ * `Record<string, unknown>`, since `unknown` is not assignable to a declared
1641
+ * `boolean | undefined`. The keys the evaluator itself recognises are documented
1642
+ * on {@link EvalKnownOptions} instead, and read through a cast at the point of
1643
+ * use because a union does not index directly.
1644
+ */
1645
+ type EvalOptions = Record<string, unknown> | {
1646
+ caseInsensitive: false;
1647
+ };
1648
+ /**
1649
+ * The option keys `eval-core` itself recognises.
1650
+ *
1651
+ * Documentation with types attached rather than a constraint: an
1652
+ * {@link EvalOptions} value is *not* required to conform to this, and nothing
1653
+ * validates against it. Its purpose is to give the recognised keys one
1654
+ * discoverable declaration, and to let a caller who wants checking write
1655
+ * `const options: EvalKnownOptions = { … }` and have a typo caught.
1656
+ *
1657
+ * A type alias rather than an interface, and that is load-bearing: an interface
1658
+ * gets no implicit index signature, so it would not be assignable to
1659
+ * {@link EvalOptions}'s `Record<string, unknown>` arm and the annotated form
1660
+ * above - its only reason to exist - would not compile.
1661
+ */
1662
+ type EvalKnownOptions = {
1663
+ /**
1664
+ * Resolve context keys and property names without regard to case.
1665
+ */
1666
+ caseInsensitive?: boolean;
1667
+ /**
1668
+ * Accumulate per-node-type timings for the evaluation, readable afterwards as
1669
+ * `EvalState.nodeTimings`.
1670
+ *
1671
+ * **Turning this on makes the walk dispatch per node.** Registering the
1672
+ * timing hook from options constructs the hook registry eagerly, and
1673
+ * `EvalHooks.isActive` latches on that registration, so every node dispatches
1674
+ * for the whole evaluation. That cost is inherent to the feature - per-node
1675
+ * -type totals cannot be derived without visiting each node - and it is not
1676
+ * the zero-cost-when-unused guarantee being eroded: that guarantee is about
1677
+ * the *default* path. If a single walk-level total is all that is wanted,
1678
+ * `EvalResult.duration` already provides one for free on every evaluation.
1679
+ *
1680
+ * Honoured only when no registry is supplied through {@link hooks}; see that
1681
+ * key.
1682
+ */
1683
+ trackTime?: boolean;
1684
+ /**
1685
+ * How many loop iterations one evaluation may run before it throws. Defaults
1686
+ * to `100000`.
1687
+ *
1688
+ * **A bound on non-termination, not a performance knob.** With no `break`,
1689
+ * `continue` or `return` in the language this evaluator implements, the only
1690
+ * way out of `for (;;)` is the budget, and a runaway loop that silently
1691
+ * returned a partial value is the failure this exists to prevent - so
1692
+ * exceeding it raises `Iteration budget exhausted after <n> iterations`.
1693
+ *
1694
+ * **Per outermost `evaluate` call, not per loop and not per state.** Per loop
1695
+ * would not be a bound at all: two nested loops at 100,000 each is 10^10
1696
+ * iterations. Per state would erode one budget across the independent
1697
+ * evaluations of the `createState` + repeated `eval` style, and would leave an
1698
+ * escaped closure - an arrow that outlives its walk - carrying that walk's
1699
+ * spent budget into a later call. A nested walk *during* an evaluation, which
1700
+ * is what an arrow-function body is, shares the remaining budget with its
1701
+ * caller rather than refilling.
1702
+ *
1703
+ * `Infinity` opts out; the consequence is the caller's. The default is sized
1704
+ * in the plan's § 3.4 at roughly 0.2 s of evaluation - long enough to exceed
1705
+ * any hand-written rule, short enough that a browser tab stutters rather than
1706
+ * freezes.
1707
+ *
1708
+ * **It bounds time, not memory, and raising it trades one for the other.**
1709
+ * `EvalResult.trace` gains an entry per value pushed and is never reset, so a
1710
+ * loop's trace grows as iterations x nodes - roughly 700,000 entries for a
1711
+ * 100,000-iteration loop. The allocation happens *before* the throw, so
1712
+ * exhausting the budget costs it in full; and `Infinity` removes the only
1713
+ * thing bounding it, turning a hang into an out-of-memory. `docs/backlog.md`
1714
+ * A12 carries the measurements and the options for bounding it.
1715
+ *
1716
+ * Costs nothing when no loop runs: the counter is charged inside
1717
+ * `for-statement.ts`'s iteration loop and nowhere else, so an expression with
1718
+ * no `for` in it never reaches the instruction.
1719
+ */
1720
+ maxIterations?: number;
1721
+ /**
1722
+ * A caller-owned {@link EvalHooks} to dispatch through, instead of the empty
1723
+ * one the state creates on first access.
1724
+ *
1725
+ * Adopted as-is and never cloned, so the unsubscribe closures `on` returned
1726
+ * keep working. **Because the registry belongs to the caller, options never
1727
+ * configure it**: {@link onHookError} and {@link trackTime} apply to a
1728
+ * registry the state built, and are silently ignored when one is adopted. A
1729
+ * caller who wants either alongside their own registry sets it there -
1730
+ * `new EvalHooks({ onHookError: 'throw' })`, or `createTimingHook().install`.
1731
+ *
1732
+ * The one thing the library does *to* an adopted registry is clear it:
1733
+ * `EvalService.ngOnDestroy` empties the registries of the states it created,
1734
+ * this one included, so that a registry outliving the service cannot keep
1735
+ * those states and their AST nodes reachable. Registrations cannot be dropped
1736
+ * selectively - the closures that captured a dead state are indistinguishable
1737
+ * from the rest - so do not share one registry with a state whose lifetime is
1738
+ * meant to outlast the service.
1739
+ */
1740
+ hooks?: EvalHooks;
1741
+ /**
1742
+ * What to do with an error raised by a hook. Defaults to `'collect'`.
1743
+ *
1744
+ * Honoured only when no registry is supplied through {@link hooks}; see that
1745
+ * key.
1746
+ */
1747
+ onHookError?: EvalHookErrorPolicy;
1748
+ };
1749
+
1750
+ declare const defaultParserOptions: ParserOptions;
1751
+
1752
+ /**
1753
+ * A timing hook, ready to install on a registry.
1754
+ *
1755
+ * It carries no totals of its own: they are written to the `EvalState` being
1756
+ * evaluated and read back as `EvalState.nodeTimings`. That is what lets the
1757
+ * `trackTime` option install one from inside the `EvalState` constructor, where
1758
+ * the caller never sees this handle - and it is what keeps two evaluations
1759
+ * through a shared registry from accumulating into each other.
1760
+ */
1761
+ interface EvalTimingHook {
1762
+ /**
1763
+ * Registers the 'before'/'after' pair on `hooks`.
1764
+ *
1765
+ * @param hooks The registry to register on.
1766
+ * @returns A function that removes both halves of the pair.
1767
+ */
1768
+ install(hooks: EvalHooks): Unsubscribe;
1769
+ }
1770
+ /**
1771
+ * Creates a timing hook that accumulates inclusive per-node-type totals.
1772
+ *
1773
+ * Replaces the `console.time` / `console.timeEnd` pair the old `trackTime`
1774
+ * emitted, which mismatched its labels and produced no readable figure. The
1775
+ * readings are `performance.now()`, and nothing is written to the console.
1776
+ *
1777
+ * ```ts
1778
+ * const state = evalService.createState(context);
1779
+ * const off = createTimingHook().install(state.hooks);
1780
+ * evalService.eval('a + b * c', state);
1781
+ * state.nodeTimings.get('BinaryExpression'); // { count: 2, total: 0.081 }
1782
+ * off();
1783
+ * ```
1784
+ *
1785
+ * Equivalent to passing `{ trackTime: true }`, which installs one of these on
1786
+ * the state's own registry.
1787
+ *
1788
+ * @returns A handle whose `install` registers the pair on a registry.
1789
+ */
1790
+ declare const createTimingHook: () => EvalTimingHook;
1791
+
1792
+ /**
1793
+ * Collects the context reads an evaluation made, as a set of dotted paths.
1794
+ *
1795
+ * This is Phase 3's input: install it, evaluate, and read {@link dependencies}
1796
+ * back in the same synchronous turn - which is what wrapping a `computed()`
1797
+ * needs. Hooks are synchronous by design, so that ordering always holds.
1798
+ */
1799
+ interface EvalDependencyTracker {
1800
+ /**
1801
+ * Registers the read hook on `hooks`.
1802
+ *
1803
+ * @param hooks The registry to register on.
1804
+ * @returns A function that removes it.
1805
+ */
1806
+ install(hooks: EvalHooks): Unsubscribe;
1807
+ /**
1808
+ * The dotted paths this tracker considers dependencies, filtered per the
1809
+ * rules on {@link createDependencyTracker}. Live: it fills as reads arrive.
1810
+ */
1811
+ readonly dependencies: ReadonlySet<string>;
1812
+ /**
1813
+ * Every read seen, unfiltered and in emission order - including the scope
1814
+ * bindings, method references and computed members {@link dependencies}
1815
+ * drops. A consumer that wants to key on `target` identity rather than on
1816
+ * path strings works from here.
1817
+ */
1818
+ readonly reads: EvalReadEvent[];
1819
+ /** Empties {@link dependencies}, {@link reads} and the scope-binding names. */
1820
+ reset(): void;
1821
+ }
1822
+ /**
1823
+ * Creates a dependency tracker.
1824
+ *
1825
+ * `reads` keeps everything. `dependencies` is the filtered view, and three
1826
+ * rules do the filtering:
1827
+ *
1828
+ * 1. **Scope bindings are not dependencies.** A read flagged `scoped` resolved
1829
+ * from a scope pushed during the walk - an arrow-function parameter. Only
1830
+ * the walker can tell one from a real context read, which is why the flag
1831
+ * exists; a consumer using this tracker inherits the filtering for free.
1832
+ * 2. **Nor is anything reached *through* one.** `item` being a binding makes
1833
+ * `item.name` one too, and that read carries no flag of its own: `scoped` is
1834
+ * set at identifier resolution, and the member hop resolves against the
1835
+ * bound object rather than against a scope. So the bound names are
1836
+ * remembered and any path rooted at one is dropped.
1837
+ * 3. **A method reached through a member hop is a call target, not data.**
1838
+ * `list.map` in `list.map(item => item.name)` resolves to
1839
+ * `Array.prototype.map`; recording it would put a built-in in the dependency
1840
+ * set, while `list` - already recorded - is the thing whose change actually
1841
+ * matters. Bare identifiers are exempt, function-valued or not: a
1842
+ * context-level callable was named directly rather than reached through an
1843
+ * object, and there is no already-recorded object standing in for it.
1844
+ *
1845
+ * Two limits, both consequences of keying on path strings:
1846
+ *
1847
+ * - **A computed member contributes nothing.** `obj[expr]` has no
1848
+ * reconstructible path, and its resolved key alone is not a usable key
1849
+ * without one. It is in `reads` with an exact `key` and `target`, for a
1850
+ * consumer willing to key on identity.
1851
+ * - **Names collide.** Rule 2 keys on the *name*, so once `item` has been an
1852
+ * arrow parameter anywhere in the expression, a genuine `item.x` elsewhere in
1853
+ * it is dropped too. Path strings from different arrow bodies collide the
1854
+ * same way. § 9 hands the identity-versus-paths question to Phase 3; this is
1855
+ * the paths half of it.
1856
+ *
1857
+ * ```ts
1858
+ * const tracker = createDependencyTracker();
1859
+ * const state = evalService.createState({ a: { b: 1 }, c: 2 });
1860
+ * const off = tracker.install(state.hooks);
1861
+ *
1862
+ * evalService.eval('a.b + c', state);
1863
+ * tracker.dependencies; // Set { 'a', 'a.b', 'c' }
1864
+ *
1865
+ * tracker.reset();
1866
+ * off();
1867
+ * ```
1868
+ *
1869
+ * @returns A tracker; nothing is collected until {@link EvalDependencyTracker.install}
1870
+ * is called.
1871
+ */
1872
+ declare const createDependencyTracker: () => EvalDependencyTracker;
1873
+
1874
+ type BaseContext = Record<string | number | symbol, unknown>;
1875
+ type Context = Registry<unknown, unknown> | BaseContext;
1876
+ declare function isRegistryContext(context?: Context): boolean;
1877
+ /**
1878
+ * Converts a context object to a Context instance.
1879
+ * @param context - The context object to convert.
1880
+ * @param options - Optional evaluation options.
1881
+ * @returns The converted Context instance.
1882
+ */
1883
+ declare const fromContext: (context?: Context, options?: EvalOptions) => Context;
1884
+ /**
1885
+ * Retrieves the value associated with the specified key from the given context.
1886
+ * If the context is an instance of Registry, it uses the `get` method to retrieve the value.
1887
+ * If the context is an object, it accesses the value using the key as a property name.
1888
+ * If the context is neither an instance of Registry nor an object, it returns undefined.
1889
+ *
1890
+ * @param context The context from which to retrieve the value.
1891
+ * @param key The key associated with the value to retrieve.
1892
+ * @returns The value associated with the specified key, or undefined if not found.
1893
+ */
1894
+ declare const getContextValue: (context?: Context, key?: unknown) => unknown;
1895
+ /**
1896
+ * Retrieves the key from the given context object.
1897
+ * If the context is an instance of Registry, it searches for the key in a case-insensitive manner if specified.
1898
+ * If the context is an instance of Object, it uses the getKeyValue function to retrieve the key-value pair.
1899
+ * @param context - The context object.
1900
+ * @param key - The key to retrieve.
1901
+ * @param caseInsensitive - Specifies whether the search should be case-insensitive (only applicable for Registry instances).
1902
+ * @returns The retrieved key, or undefined if the key is not found.
1903
+ */
1904
+ declare const getContextKey: (context: Context, key: string | number | symbol, caseInsensitive: boolean) => string | number | symbol | undefined;
1905
+
1906
+ interface CacheType<TValue> extends RegistryType<string, TValue> {
1907
+ type: Readonly<'Cache' | string>;
1908
+ maxCacheSize: number;
1909
+ getHashKey: (namespace: string, value: string) => string;
1910
+ }
1911
+
1912
+ /**
1913
+ * @deprecated Use `EvalHooks` and `EvalState` instead. Nothing in the library
1914
+ * implements this interface, and no code path reads its `beforeVisitors` /
1915
+ * `afterVisitors` entries; the evaluator's state type is `EvalState` and hooks
1916
+ * are registered through `EvalState.hooks`.
1917
+ *
1918
+ * **Its two hook entries are the last published trace of a signature no
1919
+ * function in the library has any more.** They are typed to return
1920
+ * `number | undefined` because the real `beforeVisitor` / `afterVisitor` once
1921
+ * returned a timing stub - a start timestamp handed back to the closing call.
1922
+ * That stub was deleted when those functions became hook dispatchers and their
1923
+ * return type widened to `void`, which is also what `EvalNodeHook` mandates, so
1924
+ * the shape recorded here is now contradicted by every hook the library
1925
+ * actually dispatches. A reader who finds these lines has no way to discover
1926
+ * that from the code, since there is no implementation left to compare against.
1927
+ *
1928
+ * Retained so this release stays purely additive; removal is a follow-up for
1929
+ * the next breaking version.
1930
+ */
1931
+ interface RecursiveVisitorState {
1932
+ scope: Registry<unknown, unknown>;
1933
+ result: RecursiveVisitorResult<unknown | undefined>;
1934
+ option: RecursiveVisitorOptions;
1935
+ beforeVisitors?: RegistryType<AnyNodeTypes, (node: AnyNode, st: RecursiveVisitorState) => number | undefined>;
1936
+ afterVisitors?: RegistryType<AnyNodeTypes, (node: AnyNode, st: RecursiveVisitorState) => number | undefined>;
1937
+ }
1938
+ interface RecursiveVisitorOptions {
1939
+ trackTime?: boolean;
1940
+ resultType?: 'stack' | 'registry';
1941
+ }
1942
+ interface RecursiveVisitorContext {
1943
+ placeholder?: unknown;
1944
+ }
1945
+ declare enum RecursiveVisitorResultType {
1946
+ Stack = 0,
1947
+ Registry = 1
1948
+ }
1949
+ /**
1950
+ * @deprecated Use `EvalResult` instead. This exists only as the `result` member
1951
+ * of the deprecated {@link RecursiveVisitorState}; the evaluator carries its
1952
+ * value stack and trace on `EvalResult`, which is what visitors actually push
1953
+ * to and what `EvalState.result` returns.
1954
+ *
1955
+ * Retained so this release stays purely additive; removal is a follow-up for
1956
+ * the next breaking version.
1957
+ */
1958
+ type RecursiveVisitorResult<TValue> = RecursiveVisitorStackResult<TValue> | RecursiveVisitorRegistryResult<TValue>;
1959
+ interface RecursiveVisitorStackResult<TValue> {
1960
+ type: 'stack';
1961
+ stack: StackType<TValue>;
1962
+ }
1963
+ interface RecursiveVisitorRegistryResult<TValue> {
1964
+ type: 'registry';
1965
+ registry: BaseRegistry<AnyNode, TValue>;
1966
+ }
1967
+ type AggregateType = {
1968
+ Expression: acorn.Expression;
1969
+ Statement: acorn.Statement;
1970
+ Function: acorn.Function;
1971
+ Class: acorn.Class;
1972
+ Pattern: acorn.Pattern;
1973
+ ForInit: acorn.VariableDeclaration | acorn.Expression;
1974
+ };
1975
+ type RecursiveVisitor<TState> = (node: acorn.AnyNode, state: TState, callback: WalkerCallback<TState>) => void;
1976
+ type RecursiveAggregateVisitor<TState> = (node: AggregateType, state: TState, callback: WalkerCallback<TState>) => void;
1977
+
1978
+ /**
1979
+ * @description
1980
+ * Service for parsing expressions and returning ES6/ES2020 AST.
1981
+ * Implements OnDestroy for proper memory cleanup.
1982
+ */
1983
+ declare class ParserService implements OnDestroy {
1984
+ private _parserOptions;
1985
+ private _cache?;
1986
+ private _cacheCleanupInterval?;
1987
+ private _isDestroyed;
1988
+ /**
1989
+ * Gets the parser options.
1990
+ */
1991
+ get parserOptions(): ParserOptions;
1992
+ /**
1993
+ * Sets the parser options.
1994
+ * @param value The parser options to set.
1995
+ */
1996
+ set parserOptions(value: ParserOptions);
1997
+ /**
1998
+ * Constructs a new instance of the ParserService class.
1999
+ */
2000
+ constructor();
2001
+ /**
2002
+ * Setup periodic cache cleanup to prevent memory leaks
2003
+ */
2004
+ private setupCacheCleanup;
2005
+ /**
2006
+ * Clean up resources to prevent memory leaks
2007
+ */
2008
+ ngOnDestroy(): void;
2009
+ /**
2010
+ * @description
2011
+ * Returns acorn version.
2012
+ */
2013
+ get version(): string;
2014
+ /**
2015
+ * Gets the parser options.
2016
+ * @returns The parser options.
2017
+ */
2018
+ get options(): ParserOptions;
2019
+ /**
2020
+ * @description
2021
+ * Parses expression and returns ES6/ES2023 AST.
2022
+ * @param expr expression to parse
2023
+ * @param options optional parser options
2024
+ * @returns The parsed AST (Abstract Syntax Tree).
2025
+ */
2026
+ parse(expr: string, options?: ParserOptions): Program | AnyNode | Expression | undefined;
2027
+ private fromCacheOrParse;
2028
+ static ɵfac: i0.ɵɵFactoryDeclaration<ParserService, never>;
2029
+ static ɵprov: i0.ɵɵInjectableDeclaration<ParserService>;
2030
+ }
2031
+
2032
+ /**
2033
+ * Base class for evaluation.
2034
+ */
2035
+ declare abstract class BaseEval {
2036
+ protected parserService: ParserService;
2037
+ private _parserOptions;
2038
+ constructor(parserService: ParserService);
2039
+ /**
2040
+ * Gets the parser options.
2041
+ */
2042
+ protected get parserOptions(): ParserOptions;
2043
+ /**
2044
+ * Sets the parser options.
2045
+ * @param value The parser options to set.
2046
+ */
2047
+ protected set parserOptions(value: ParserOptions);
2048
+ /**
2049
+ * Parses the given expression into an abstract syntax tree (AST).
2050
+ * @param expression - The expression to parse.
2051
+ * @returns The parsed AST.
2052
+ */
2053
+ protected parse(expression: string | AnyNode | undefined): AnyNode | undefined;
2054
+ /**
2055
+ * Creates an instance of EvalState.
2056
+ * @param context - The evaluation context or context object.
2057
+ * @param options - The evaluation options.
2058
+ * @returns The created EvalState instance.
2059
+ */
2060
+ createState(context?: EvalContext | Context, options?: EvalOptions): EvalState;
2061
+ }
2062
+
2063
+ /**
2064
+ * Service for evaluating and parsing expressions with proper memory management.
2065
+ */
2066
+ declare class EvalService extends BaseEval implements OnDestroy {
2067
+ private _isDestroyed;
2068
+ private _activeContexts;
2069
+ private _activeStates;
2070
+ protected parserService: ParserService;
2071
+ /**
2072
+ * Constructs a new instance of the EvalService class.
2073
+ */
2074
+ constructor();
2075
+ /**
2076
+ * Override createState to track active contexts and states for cleanup
2077
+ */
2078
+ createState(context?: EvalContext | Context, options?: EvalOptions): EvalState;
2079
+ /**
2080
+ * Clean up resources to prevent memory leaks
2081
+ */
2082
+ ngOnDestroy(): void;
2083
+ /**
2084
+ * Evaluates the given expression.
2085
+ * @param expression The expression to evaluate.
2086
+ * @param context The evaluation context.
2087
+ * @param options The evaluation options.
2088
+ * @returns The result of the evaluation.
2089
+ */
2090
+ simpleEval(expression: string | AnyNode | undefined, context?: EvalContext | Context, options?: EvalOptions): unknown | undefined;
2091
+ /**
2092
+ * Evaluates an expression using the provided state.
2093
+ *
2094
+ * @param expression - The expression to evaluate.
2095
+ * @param state - The state object containing variables and functions used in the evaluation.
2096
+ * @returns The result of the evaluation.
2097
+ * @throws If an error occurs during evaluation.
2098
+ */
2099
+ eval(expression: string | AnyNode | undefined, state: EvalState): unknown | undefined;
2100
+ /**
2101
+ * Asynchronously evaluates the given expression.
2102
+ * @param expression The expression to evaluate.
2103
+ * @param context The evaluation context.
2104
+ * @param options The evaluation options.
2105
+ * @returns A promise that resolves to the result of the evaluation.
2106
+ */
2107
+ simpleEvalAsync(expression: string | AnyNode | undefined, context?: EvalContext | Context, options?: EvalOptions): Promise<unknown | undefined>;
2108
+ /**
2109
+ * Asynchronously evaluates an expression using the provided state.
2110
+ *
2111
+ * @param expression - The expression to evaluate. Can be a string or an AST node.
2112
+ * @param state - The evaluation state.
2113
+ * @returns A promise that resolves to the result of the evaluation.
2114
+ * @throws If an error occurs during evaluation.
2115
+ */
2116
+ evalAsync(expression: string | AnyNode | undefined, state: EvalState): Promise<unknown | undefined>;
2117
+ static ɵfac: i0.ɵɵFactoryDeclaration<EvalService, never>;
2118
+ static ɵprov: i0.ɵɵInjectableDeclaration<EvalService>;
2119
+ }
2120
+
2121
+ /**
2122
+ * @description
2123
+ * Parses expression and returns ES6/ES2020 AST.
2124
+ * @param expr expression to parse
2125
+ * @param options parser options
2126
+ */
2127
+ declare const parse: (expr: string, options: ParserOptions) => Program | AnyNode | undefined;
2128
+ /**
2129
+ * @description
2130
+ * Walks through the AST and extracts first expression.
2131
+ * @param expr expression to parse
2132
+ */
2133
+ declare const extractExpression: (program: Program) => Expression | undefined;
2134
+
2135
+ /**
2136
+ * Evaluates the given node and returns the result.
2137
+ *
2138
+ * @param node The node to evaluate.
2139
+ * @param state The evaluation state.
2140
+ * @returns The result of the evaluation.
2141
+ */
2142
+ declare const evaluate: (node: AnyNode | undefined, state: EvalState) => unknown | undefined;
2143
+ /**
2144
+ * Asynchronously evaluates the given abstract syntax tree (AST) using the provided evaluation state.
2145
+ * @param ast The abstract syntax tree to evaluate.
2146
+ * @param state The evaluation state.
2147
+ * @returns A promise that resolves to the evaluated value or undefined.
2148
+ */
2149
+ declare const evaluateAsync: (ast: AnyNode | undefined, state: EvalState) => Promise<unknown | undefined>;
2150
+
2151
+ type stateCallback = (state: EvalState) => unknown;
2152
+ type stateCallbackAsync = (state: EvalState) => Promise<unknown | undefined>;
2153
+ /**
2154
+ * Compiles the given node and returns a function that can be used to evaluate it.
2155
+ *
2156
+ * @param node The node to compile.
2157
+ * @returns A function that takes an `EvalState` and returns the result of evaluating the node.
2158
+ */
2159
+ declare const compile: (node: AnyNode | undefined) => stateCallback;
2160
+ /**
2161
+ * Compiles the given node asynchronously.
2162
+ *
2163
+ * @param node - The node to compile.
2164
+ * @returns A function that takes an `EvalState` object and returns a `Promise` that resolves to the compiled result.
2165
+ */
2166
+ declare const compileAsync: (node: AnyNode | undefined) => stateCallbackAsync;
2167
+ /**
2168
+ * Calls the provided function with the given state and returns the result.
2169
+ *
2170
+ * @param fn The function to be called.
2171
+ * @param state The state to be passed to the function.
2172
+ * @returns The result of calling the function.
2173
+ */
2174
+ declare const call: (fn: stateCallback, state: EvalState) => unknown | undefined;
2175
+ /**
2176
+ * Calls an asynchronous function with the given state and returns a promise that resolves to the result.
2177
+ * @param fn The asynchronous function to call.
2178
+ * @param state The state to pass to the function.
2179
+ * @returns A promise that resolves to the result of the function.
2180
+ */
2181
+ declare const callAsync: (fn: stateCallbackAsync, state: EvalState) => Promise<unknown | undefined>;
2182
+
2183
+ /**
2184
+ * Finds all nodes of a specific type in the given AST.
2185
+ *
2186
+ * @param ast The AST to search in.
2187
+ * @param searchType The type of nodes to search for.
2188
+ * @returns An array of nodes of the specified type if found, otherwise undefined.
2189
+ */
2190
+ declare const extract: (node: AnyNode | undefined, searchType: AnyNodeTypes) => AnyNode[] | undefined;
2191
+
2192
+ /**
2193
+ * CompilerService class that extends BaseEval.
2194
+ * Provides methods for compiling and evaluating expressions with performance caching.
2195
+ */
2196
+ declare class CompilerService extends BaseEval implements OnDestroy {
2197
+ private readonly _compilationCache;
2198
+ private readonly _maxCacheSize;
2199
+ private readonly _cacheTTL;
2200
+ private readonly _accessOrder;
2201
+ private _cacheCleanupInterval?;
2202
+ private _isDestroyed;
2203
+ protected parserService: ParserService;
2204
+ protected evalService: EvalService;
2205
+ constructor();
2206
+ /**
2207
+ * OnDestroy lifecycle hook for cleanup
2208
+ */
2209
+ ngOnDestroy(): void;
2210
+ /**
2211
+ * Setup periodic cache cleanup to prevent memory leaks and stale entries
2212
+ */
2213
+ private setupCacheCleanup;
2214
+ /**
2215
+ * Clean expired entries and enforce cache size limits
2216
+ */
2217
+ private cleanupCache;
2218
+ /**
2219
+ * Generate cache key for expression
2220
+ */
2221
+ private generateCacheKey;
2222
+ /**
2223
+ * Update access order for LRU cache
2224
+ */
2225
+ private updateAccessOrder;
2226
+ /**
2227
+ * Compiles the given expression into a state callback function with caching.
2228
+ * @param expression - The expression to compile.
2229
+ * @returns The compiled state callback function.
2230
+ * @throws Error if there is an error during compilation.
2231
+ */
2232
+ compile(expression: string | AnyNode | undefined): stateCallback | undefined;
2233
+ /**
2234
+ * Calls the given state callback function with the specified context and options.
2235
+ * @param fn - The state callback function to call.
2236
+ * @param context - The evaluation context or context object.
2237
+ * @param options - The evaluation options.
2238
+ * @returns The result of the evaluation.
2239
+ * @throws Error if there is an error during the evaluation.
2240
+ */
2241
+ simpleCall(fn: stateCallback | undefined, context?: EvalContext | Context, options?: EvalOptions): unknown;
2242
+ /**
2243
+ * Calls the provided function with the given state.
2244
+ *
2245
+ * @param fn - The function to be called.
2246
+ * @param state - The state to be passed to the function.
2247
+ * @returns The value returned by the function.
2248
+ * @throws If an error occurs during the function call.
2249
+ */
2250
+ call(fn: stateCallback | undefined, state: EvalState): unknown;
2251
+ /**
2252
+ * Compiles the given expression into an asynchronous state callback function with caching.
2253
+ * @param expression - The expression to compile.
2254
+ * @returns The compiled asynchronous state callback function.
2255
+ * @throws Error if there is an error during compilation.
2256
+ */
2257
+ compileAsync(expression: string | AnyNode | undefined): stateCallbackAsync | undefined;
2258
+ /**
2259
+ * Calls the given asynchronous state callback function with the specified context and options.
2260
+ * @param fn - The asynchronous state callback function to call.
2261
+ * @param context - The evaluation context or context object.
2262
+ * @param options - The evaluation options.
2263
+ * @returns A promise that resolves to the result of the evaluation.
2264
+ * @throws Error if there is an error during the evaluation.
2265
+ */
2266
+ simpleCallAsync(fn: stateCallbackAsync | undefined, context?: EvalContext | Context, options?: EvalOptions): Promise<unknown>;
2267
+ /**
2268
+ * Calls the provided asynchronous function with the given state.
2269
+ *
2270
+ * @param fn - The asynchronous function to call.
2271
+ * @param state - The state to pass to the function.
2272
+ * @returns A promise that resolves to the value returned by the function.
2273
+ * @throws If an error occurs during the function call.
2274
+ */
2275
+ callAsync(fn: stateCallbackAsync | undefined, state: EvalState): Promise<unknown>;
2276
+ static ɵfac: i0.ɵɵFactoryDeclaration<CompilerService, never>;
2277
+ static ɵprov: i0.ɵɵInjectableDeclaration<CompilerService>;
2278
+ }
2279
+
2280
+ /**
2281
+ * Service responsible for discovering nodes in an abstract syntax tree (AST).
2282
+ */
2283
+ declare class DiscoveryService extends BaseEval {
2284
+ protected parserService: ParserService;
2285
+ /**
2286
+ * Creates a new instance of the DiscoveryService class.
2287
+ */
2288
+ constructor();
2289
+ /**
2290
+ * Finds all nodes in the AST that match the given expression and search type.
2291
+ * @param expression The expression to search for. Can be a string or an AST node.
2292
+ * @param searchType The type of nodes to search for.
2293
+ * @param options Optional parser options.
2294
+ * @returns An array of nodes that match the search criteria, or undefined if no nodes are found.
2295
+ * @throws If an error occurs during the search process.
2296
+ */
2297
+ extract(expression: string | AnyNode | undefined, searchType: AnyNodeTypes): AnyNode[] | undefined;
2298
+ static ɵfac: i0.ɵɵFactoryDeclaration<DiscoveryService, never>;
2299
+ static ɵprov: i0.ɵɵInjectableDeclaration<DiscoveryService>;
2300
+ }
2301
+
2302
+ export { ASYNC_HOOK_MESSAGE, BaseRegistry, Cache, CaseInsensitiveRegistry, CompilerService, DiscoveryService, EMPTY_COMPLETION, EvalContext, EvalHooks, EvalResult, EvalScope, EvalService, EvalState, EvalTrace, ParserService, Queue, RecursiveVisitorResultType, Registry, Stack, call, callAsync, compile, compileAsync, createDependencyTracker, createTimingHook, defaultParserOptions, evaluate, evaluateAsync, extract, extractExpression, fromContext, getContextKey, getContextValue, isRegistryContext, parse };
2303
+ export type { AggregateType, AnyNodeTypes, BaseContext, CacheType, Context, EvalDependencyTracker, EvalHookError, EvalHookErrorPolicy, EvalHookPhase, EvalKnownOptions, EvalLookup, EvalNodeHook, EvalNodeHookEvent, EvalNodeTiming, EvalOptions, EvalReadEvent, EvalReadHook, EvalReadKind, EvalScopeOptions, EvalTimingHook, EvalTraceItem, ParserOptions, QueueType, RecursiveAggregateVisitor, RecursiveVisitor, RecursiveVisitorContext, RecursiveVisitorOptions, RecursiveVisitorRegistryResult, RecursiveVisitorResult, RecursiveVisitorStackResult, RecursiveVisitorState, RegistryEntries, RegistryOptionType, RegistryType, ScopeOptions, ScopeType, StackType, Unsubscribe, stateCallback, stateCallbackAsync };