@zvenigora/ng-eval-core 0.3.0 → 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.
- package/README.md +145 -9
- package/fesm2022/zvenigora-ng-eval-core.mjs +1238 -157
- package/fesm2022/zvenigora-ng-eval-core.mjs.map +1 -1
- package/package.json +1 -1
- package/types/zvenigora-ng-eval-core.d.ts +331 -8
package/package.json
CHANGED
|
@@ -659,21 +659,70 @@ declare class EvalContext {
|
|
|
659
659
|
* implementation. A second copy of the order would drift - `getKey` already
|
|
660
660
|
* shows what that looks like when it does.
|
|
661
661
|
*
|
|
662
|
-
* A binding whose value is `undefined`
|
|
663
|
-
*
|
|
662
|
+
* A binding whose value is `undefined` is **found** here, and no longer reads
|
|
663
|
+
* as absent - see {@link scopeHolding}.
|
|
664
664
|
*
|
|
665
665
|
* @param key - The key to retrieve the value for.
|
|
666
666
|
* @returns The value bound by the innermost scope holding the key, or
|
|
667
|
-
* undefined when no pushed scope holds it.
|
|
667
|
+
* undefined when no pushed scope holds it. The two cases are no longer
|
|
668
|
+
* distinguishable from the return value alone; ask {@link hasInScopes}.
|
|
668
669
|
*/
|
|
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;
|
|
670
718
|
/**
|
|
671
719
|
* Whether any scope pushed during this evaluation *binds* the key - the
|
|
672
720
|
* question the read hooks' `scoped` flag asks.
|
|
673
721
|
*
|
|
674
|
-
* Deliberately about binding rather than about value
|
|
675
|
-
* company with {@link getFromScopes}
|
|
676
|
-
*
|
|
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.
|
|
677
726
|
* Reading the flag off the value would make it depend on the *data* - the
|
|
678
727
|
* same arrow function over `[{ name: 'a' }]` and over `[undefined]` would
|
|
679
728
|
* report different bindings, and a dependency tracker's output would vary
|
|
@@ -710,6 +759,43 @@ declare class EvalContext {
|
|
|
710
759
|
* @param value - The value of the pair.
|
|
711
760
|
*/
|
|
712
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;
|
|
713
799
|
/**
|
|
714
800
|
* Pushes a context to the scope stack.
|
|
715
801
|
* @param context - The context to push.
|
|
@@ -860,6 +946,10 @@ declare class EvalState {
|
|
|
860
946
|
private _isAsync;
|
|
861
947
|
private _hooks;
|
|
862
948
|
private _hookBookkeeping;
|
|
949
|
+
private _walkDepth;
|
|
950
|
+
private _iterationBudget;
|
|
951
|
+
private _iterationsRemaining;
|
|
952
|
+
private _constBindings;
|
|
863
953
|
/**
|
|
864
954
|
* Gets the evaluation context.
|
|
865
955
|
*/
|
|
@@ -935,9 +1025,118 @@ declare class EvalState {
|
|
|
935
1025
|
* @internal Not part of the published API.
|
|
936
1026
|
*/
|
|
937
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;
|
|
938
1136
|
/**
|
|
939
1137
|
* Drops every per-run record this state holds: the collected hook errors, the
|
|
940
|
-
* open-node stack, and the
|
|
1138
|
+
* open-node stack, the accumulated timings, and the walk bases bounding
|
|
1139
|
+
* `EvalHooks.exit`.
|
|
941
1140
|
*
|
|
942
1141
|
* It resets the whole record rather than only the errors, which is why it is
|
|
943
1142
|
* not named for them. `EvalHooks.clear` cannot reach any of this - the
|
|
@@ -1122,6 +1321,29 @@ interface EvalHookBookkeeping {
|
|
|
1122
1321
|
* would be unreachable, which is a dead option rather than a feature.
|
|
1123
1322
|
*/
|
|
1124
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[];
|
|
1125
1347
|
}
|
|
1126
1348
|
/**
|
|
1127
1349
|
* The message carried by the error raised when a hook returns a promise.
|
|
@@ -1138,6 +1360,30 @@ interface EvalHookBookkeeping {
|
|
|
1138
1360
|
* message text it would have to keep in sync by hand.
|
|
1139
1361
|
*/
|
|
1140
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;
|
|
1141
1387
|
/**
|
|
1142
1388
|
* A registry of node hooks, keyed by node type with wildcard support, and the
|
|
1143
1389
|
* dispatcher that keeps `before` and `after` balanced when a visitor throws.
|
|
@@ -1281,6 +1527,21 @@ declare class EvalHooks {
|
|
|
1281
1527
|
* every genuinely-open enclosing frame, and leave a later real failure with
|
|
1282
1528
|
* nothing to unwind.
|
|
1283
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
|
+
*
|
|
1284
1545
|
* Popping positionally instead would be correct only if every visitor
|
|
1285
1546
|
* bracketed its body exactly. `await-expression.ts` does not - it catches a
|
|
1286
1547
|
* child's synchronous throw and continues to its own `afterVisitor` - so a
|
|
@@ -1306,6 +1567,31 @@ declare class EvalHooks {
|
|
|
1306
1567
|
* on the state, not on this registry.
|
|
1307
1568
|
*/
|
|
1308
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;
|
|
1309
1595
|
/**
|
|
1310
1596
|
* Fires 'after' for every node the state has open above `mark`, innermost
|
|
1311
1597
|
* first, marked incomplete. Invoked from the catch in `evaluate`, so that a
|
|
@@ -1395,6 +1681,43 @@ type EvalKnownOptions = {
|
|
|
1395
1681
|
* key.
|
|
1396
1682
|
*/
|
|
1397
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;
|
|
1398
1721
|
/**
|
|
1399
1722
|
* A caller-owned {@link EvalHooks} to dispatch through, instead of the empty
|
|
1400
1723
|
* one the state creates on first access.
|
|
@@ -1976,5 +2299,5 @@ declare class DiscoveryService extends BaseEval {
|
|
|
1976
2299
|
static ɵprov: i0.ɵɵInjectableDeclaration<DiscoveryService>;
|
|
1977
2300
|
}
|
|
1978
2301
|
|
|
1979
|
-
export { ASYNC_HOOK_MESSAGE, BaseRegistry, Cache, CaseInsensitiveRegistry, CompilerService, DiscoveryService, 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 };
|
|
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 };
|
|
1980
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 };
|