@zvenigora/ng-eval-core 0.4.0 → 0.6.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 CHANGED
@@ -141,7 +141,41 @@ try {
141
141
 
142
142
  The budget is refilled per outermost `eval` call, not per state — so the `createState` + repeated `eval` style does not erode one budget across independent evaluations, and an arrow function that outlives the walk that created it does not carry that walk's spent budget into a later call.
143
143
 
144
- **It bounds time, not memory.** `state.result.trace` gains an entry per pushed value and is never reset, so a long-running loop's trace grows as iterations × nodes and that allocation is paid before the throw. With `maxIterations: Infinity` there is no bound at all; prefer a large finite number.
144
+ **It bounds time; `maxTraceItems` bounds the memory.** `state.result.trace` gains an entry per pushed value, so before that bound a long-running loop's trace grew as iterations × nodes — 700,007 entries and ~36 MB for a 100,000-iteration loop evaluated through `eval`. That loop is *not* stopped by the default budget: it charges exactly 100,000 and completes. Where the budget does stop a loop, the whole allocation was paid before the throw.
145
+
146
+ ### Bounding the trace
147
+
148
+ `state.result.trace` records every value the evaluator pushes, and it spans **every evaluation run on one state**, not just the last. `maxTraceItems` bounds how many entries it keeps. It defaults to **10,000** — roughly 0.5 MB, and three orders of magnitude above anything a hand-written expression produces.
149
+
150
+ ```javascript
151
+ const state = service.createState({ a: 10 });
152
+ service.eval('2 + 3 * a', state);
153
+
154
+ state.result.trace.length; // 7
155
+ state.result.traceTruncated; // false
156
+ state.result.tracePushCount; // 7
157
+ ```
158
+
159
+ The **head** is kept, in order, so `trace[0]` is still the first thing evaluated. Once a push is actually dropped:
160
+
161
+ - **`state.result.traceTruncated`** turns `true` and stays true — no entry is appended to the trace to say so, because every row in it describes a real node. A walk of exactly `maxTraceItems` pushes leaves it `false`; nothing was lost.
162
+ - **`state.result.tracePushCount`** goes on counting every push, which is the number the trace no longer tells you.
163
+
164
+ ```javascript
165
+ const state = service.createState({}, { maxIterations: Infinity });
166
+ service.eval('for (let i = 0; i < 100000; i++) { i }', state);
167
+
168
+ state.result.trace.length; // 10000
169
+ state.result.traceTruncated; // true
170
+ state.result.tracePushCount; // 700007
171
+ ```
172
+
173
+ Two values are special, and both are honoured rather than treated as falsy:
174
+
175
+ - **`0`** disables tracing — `trace.length` stays `0` and `traceTruncated` stays `false`, while `tracePushCount` stays accurate, so a caller who turns tracing off for the allocation keeps the walk-size figure.
176
+ - **`Infinity`** restores the unbounded behaviour exactly.
177
+
178
+ **`state.result.clearTrace()`** is the only reset. It empties the trace and both counters, in place — the array `state.result.trace` returns is the same instance for the life of the result, so a reference you are holding stays live across the call. Under the `createState` + repeated `eval` style, call it before an evaluation to make the trace describe only that walk.
145
179
 
146
180
  ### Evaluation hooks
147
181
 
@@ -242,7 +276,7 @@ Two things to know about it:
242
276
  const state = service.createState(context, { hooks });
243
277
  ```
244
278
 
245
- One thing the library *does* do to a registry you own: `EvalService.ngOnDestroy()` clears the registries of the states it created, adopted ones included, so that a registry outliving the service cannot keep those states and their AST nodes reachable. Do not share one registry with a state whose lifetime is meant to outlast the service.
279
+ The library never clears a registry you own. `EvalService.ngOnDestroy()` does not touch it, whichever method you passed it to, and up to 0.5.0 it cleared the registries of the states `createState` built. So a hook that keeps a state, by capturing it or by storing `event.state`, keeps that state and its context reachable for as long as the registry is. Release them in the teardown that owns the registry, such as your component's `ngOnDestroy` or a `DestroyRef.onDestroy` callback: call the unsubscribe that `on` / `onRead` returned, or `hooks.clear()`.
246
280
 
247
281
  #### `completed: false` events
248
282
 
@@ -1259,6 +1259,33 @@ class EvalResult {
1259
1259
  get trace() {
1260
1260
  return this._trace;
1261
1261
  }
1262
+ /**
1263
+ * Whether {@link trace} stopped short of everything this state pushed,
1264
+ * because `options.maxTraceItems` was reached.
1265
+ *
1266
+ * **Latches.** Once true it stays true until {@link clearTrace}, however many
1267
+ * evaluations run in between, because the trace does: it spans every
1268
+ * evaluation run on this result, so a flag that cleared per walk would
1269
+ * describe a different array than the one beside it.
1270
+ *
1271
+ * False under `maxTraceItems: 0`, which is a caller asking for no trace
1272
+ * rather than a trace that lost something.
1273
+ */
1274
+ get traceTruncated() {
1275
+ return this._traceTruncated;
1276
+ }
1277
+ /**
1278
+ * How many values were pushed for tracing since this result was built or last
1279
+ * cleared by {@link clearTrace} - which is what {@link trace} no longer tells
1280
+ * you once {@link traceTruncated} is set.
1281
+ *
1282
+ * Counts pushes, not entries kept, so it goes on rising past the bound, and
1283
+ * it stays accurate under `maxTraceItems: 0` - a caller who disabled tracing
1284
+ * for the allocation still gets the walk-size figure.
1285
+ */
1286
+ get tracePushCount() {
1287
+ return this._tracePushCount;
1288
+ }
1262
1289
  /**
1263
1290
  * Gets the evaluation context.
1264
1291
  */
@@ -1302,10 +1329,74 @@ class EvalResult {
1302
1329
  * @param context The evaluation context.
1303
1330
  */
1304
1331
  constructor(context) {
1332
+ this._tracePushCount = 0;
1333
+ this._traceTruncated = false;
1305
1334
  this._stack = new Stack();
1306
1335
  this._trace = new EvalTrace();
1307
1336
  this._context = context;
1308
1337
  }
1338
+ /**
1339
+ * Records one traced push against `limit`, adding it to {@link trace} only
1340
+ * while there is room.
1341
+ *
1342
+ * **The bound is the caller's, and that is the point.** `limit` arrives from
1343
+ * `EvalState.maxTraceItems` - the *walk's* options - because this object
1344
+ * cannot read them: {@link options} returns `this._context.options`, and a
1345
+ * context can be handed to any number of evaluations carrying options none
1346
+ * of them used. Reading the bound here would reproduce the split `CLAUDE.md`
1347
+ * documents for `caseInsensitive`.
1348
+ *
1349
+ * One call, replacing the bare `trace.add` the push helpers made before, so
1350
+ * the guarded path costs an increment and a comparison rather than a second
1351
+ * call per node. `_traceTruncated` is written rather than tested-then-written
1352
+ * for the same reason: it is idempotent, and a write is cheaper than a read
1353
+ * and a branch on a path a runaway loop takes hundreds of thousands of times.
1354
+ *
1355
+ * @internal Not part of the published API.
1356
+ */
1357
+ addTraceBounded(node, value, limit) {
1358
+ this._tracePushCount++;
1359
+ if (this._trace.length >= limit) {
1360
+ // `limit` 0 is tracing turned off, not a trace that lost something.
1361
+ if (limit > 0) {
1362
+ this._traceTruncated = true;
1363
+ }
1364
+ return;
1365
+ }
1366
+ this._trace.add(node, value, this._expression);
1367
+ }
1368
+ /**
1369
+ * Empties {@link trace} and resets {@link traceTruncated} and
1370
+ * {@link tracePushCount} - the only reset any of the three has.
1371
+ *
1372
+ * **For the caller who reuses one state.** The trace spans every evaluation
1373
+ * run on this result rather than restarting per walk, which is deliberate
1374
+ * (`docs/backlog.md` A15) and is what `options.maxTraceItems` bounds.
1375
+ * A caller using the `createState` + repeated `eval` style who wants the
1376
+ * trace to describe only the walk they just ran calls this before each one.
1377
+ *
1378
+ * **The array is emptied in place, not replaced.** {@link trace} has always
1379
+ * returned the same instance for the life of the result, so a consumer
1380
+ * holding it - `const t = state.result.trace` - keeps a live reference
1381
+ * across this call rather than a stale snapshot.
1382
+ *
1383
+ * That is the **opposite** of `EvalState.resetHookBookkeeping`, which
1384
+ * replaces its record rather than emptying it so as not to mutate a
1385
+ * collection the caller holds a reference to - and both are right for their
1386
+ * own goal, which is why this says so rather than leaving a reader to find
1387
+ * one of them and read the other as a slip. Emptying in place is what
1388
+ * *releases* memory a caller-held array would otherwise pin, and that is the
1389
+ * whole of A12; replacing here would leave the old array, and every value in
1390
+ * it, alive in the caller's hand.
1391
+ *
1392
+ * Leaves {@link expression} alone: that is one string replaced per
1393
+ * evaluation, not an accumulator.
1394
+ */
1395
+ clearTrace() {
1396
+ this._trace.length = 0;
1397
+ this._tracePushCount = 0;
1398
+ this._traceTruncated = false;
1399
+ }
1309
1400
  /**
1310
1401
  * Starts the evaluation process.
1311
1402
  */
@@ -1970,6 +2061,32 @@ const readMaxIterations = (options) => {
1970
2061
  ? value
1971
2062
  : DEFAULT_MAX_ITERATIONS;
1972
2063
  };
2064
+ /**
2065
+ * How many values one state's trace holds when the caller names no other.
2066
+ *
2067
+ * Sized rather than picked: ~0.5 MB at the measured ~51 bytes an item,
2068
+ * which is three orders of magnitude above any
2069
+ * expression written by hand - the largest in this repository's own specs and
2070
+ * READMEs is a handful of nodes - and 70x below the 700,007 items a
2071
+ * 100,000-iteration loop produced unbounded.
2072
+ */
2073
+ const DEFAULT_MAX_TRACE_ITEMS = 10000;
2074
+ /**
2075
+ * The trace bound the options ask for, or the default.
2076
+ *
2077
+ * Same cast and same permissive fallback as {@link readMaxIterations}, for the
2078
+ * same reason: options are a record nothing validates, and a malformed value
2079
+ * must not become a *smaller* bound than the default by accident. `0` is
2080
+ * honoured - a caller who wants no trace at all is asking for something
2081
+ * coherent - and `Infinity` opts out, which is why the test is not
2082
+ * `Number.isFinite`.
2083
+ */
2084
+ const readMaxTraceItems = (options) => {
2085
+ const value = options?.['maxTraceItems'];
2086
+ return typeof value === 'number' && !Number.isNaN(value) && value >= 0
2087
+ ? value
2088
+ : DEFAULT_MAX_TRACE_ITEMS;
2089
+ };
1973
2090
  /**
1974
2091
  * Represents the evaluation state, which includes the context, result, and options.
1975
2092
  */
@@ -2115,6 +2232,12 @@ class EvalState {
2115
2232
  if (depth === 1) {
2116
2233
  this._iterationBudget = readMaxIterations(this._options);
2117
2234
  this._iterationsRemaining = this._iterationBudget;
2235
+ // Read here for the second half of the refill's reason, and not for the
2236
+ // first: the trace bound has no per-walk state to restore - it bounds the
2237
+ // state's trace, which spans every walk - but the options are the same
2238
+ // mutable record the caller holds, so a caller who raises it between two
2239
+ // evaluations on a held state is honoured exactly as they are above.
2240
+ this._maxTraceItems = readMaxTraceItems(this._options);
2118
2241
  }
2119
2242
  return depth;
2120
2243
  }
@@ -2142,6 +2265,22 @@ class EvalState {
2142
2265
  get iterationsRemaining() {
2143
2266
  return this._iterationsRemaining;
2144
2267
  }
2268
+ /**
2269
+ * How many values this state's trace may hold, from `options.maxTraceItems`
2270
+ * and defaulting to 10,000. `0` disables tracing; `Infinity` opts out.
2271
+ *
2272
+ * Filled by {@link enterWalk} on the outermost entry, exactly as the
2273
+ * iteration budget is - so **before the first walk this reports the default**
2274
+ * whatever the options said, and a caller reading it to discover what they
2275
+ * asked for should read it after an evaluation rather than before one.
2276
+ *
2277
+ * Read by `visitor-result.ts`'s two push helpers and nowhere else.
2278
+ *
2279
+ * @internal Not part of the published API.
2280
+ */
2281
+ get maxTraceItems() {
2282
+ return this._maxTraceItems;
2283
+ }
2145
2284
  /**
2146
2285
  * Charges one loop iteration against the budget, throwing when it is spent.
2147
2286
  *
@@ -2220,8 +2359,7 @@ class EvalState {
2220
2359
  * not named for them. `EvalHooks.clear` cannot reach any of this - the
2221
2360
  * bookkeeping belongs to the state - so without this method nothing drains
2222
2361
  * the open-node stack at all. Frames left on it keep their AST nodes
2223
- * reachable for as long as the state is, and `EvalService` holds its states
2224
- * in a strong `Set`.
2362
+ * reachable for as long as the state is.
2225
2363
  *
2226
2364
  * The errors matter for the same reason under the state-first style:
2227
2365
  * `createState` plus repeated `eval` on one state accumulates them for the
@@ -2249,6 +2387,7 @@ class EvalState {
2249
2387
  this._walkDepth = 0;
2250
2388
  this._iterationBudget = DEFAULT_MAX_ITERATIONS;
2251
2389
  this._iterationsRemaining = DEFAULT_MAX_ITERATIONS;
2390
+ this._maxTraceItems = DEFAULT_MAX_TRACE_ITEMS;
2252
2391
  this._context = context;
2253
2392
  this._result = result;
2254
2393
  this._options = options;
@@ -2292,10 +2431,31 @@ const defaultParserOptions = {
2292
2431
  cacheSize: 100
2293
2432
  };
2294
2433
 
2434
+ /**
2435
+ * The two push helpers each carry their own trace-bound call rather than
2436
+ * sharing one.
2437
+ *
2438
+ * **Why the read is at these two sites.** `st.maxTraceItems` is the *walk's*
2439
+ * bound. `EvalResult` cannot read it for itself: it holds a context, and a
2440
+ * context's options are not the walk's - the split `CLAUDE.md` documents for
2441
+ * `caseInsensitive`. So the option is read where `st` is in hand and passed in.
2442
+ *
2443
+ * **Why the one line is duplicated rather than factored.** A shared helper put
2444
+ * a third frame on a path taken once per node - `push` -> helper ->
2445
+ * `addTraceBounded` -> `EvalTrace.add` - to save one identical line. Measured
2446
+ * both ways at 50,000 walks of `2 + 3 * a`, the difference was inside
2447
+ * run-to-run noise, so this is not a speed claim; it is that the helper cost a
2448
+ * frame on the hot path and bought nothing, and that `addTraceBounded`'s own
2449
+ * docblock claims one call per push, which only this shape makes true.
2450
+ *
2451
+ * **The value stack is not bounded and must not be.** It is how visitors return
2452
+ * values to each other, and dropping an entry desynchronises every node above
2453
+ * it. Only the trace - which nothing in this library reads - is capped.
2454
+ */
2295
2455
  const pushVisitorResult = (node, st, value) => {
2296
2456
  const result = st.result;
2297
2457
  result.stack.push(value);
2298
- result.trace.add(node, value, st.result.expression);
2458
+ result.addTraceBounded(node, value, st.maxTraceItems);
2299
2459
  return value;
2300
2460
  };
2301
2461
  const popVisitorResult = (node, st) => {
@@ -2306,7 +2466,7 @@ const popVisitorResult = (node, st) => {
2306
2466
  const pushVisitorResultAsync = (node, st, value) => {
2307
2467
  const result = st.result;
2308
2468
  result.stack.push(value);
2309
- result.trace.add(node, value, st.result.expression);
2469
+ result.addTraceBounded(node, value, st.maxTraceItems);
2310
2470
  return value;
2311
2471
  };
2312
2472
  const popVisitorResultAsync = (node, st) => {
@@ -3825,63 +3985,115 @@ const evaluateMemberExpression = (pattern) => {
3825
3985
  }
3826
3986
  return {};
3827
3987
  };
3988
+ /**
3989
+ * The keys an object pattern has already consumed, in source-key terms.
3990
+ *
3991
+ * A rest element binds *the remainder*, so it needs the names the sibling
3992
+ * properties took - and it needs them as they appear on the **source**, which
3993
+ * is `Property.key`, not the name each one bound. For `{ a: x, ...r }` the key
3994
+ * removed from `r` is `a`; `x` was never a source key and removing it would
3995
+ * take the wrong property when the source happens to carry that name too.
3996
+ */
3997
+ const restOf = (source, taken) => {
3998
+ const object = {};
3999
+ if (!source || typeof source !== 'object') {
4000
+ return object;
4001
+ }
4002
+ const consumed = new Set(taken.map(key => String(key)));
4003
+ for (const key of Object.keys(source)) {
4004
+ if (!consumed.has(key)) {
4005
+ safeSetProperty(object, key, source[key]);
4006
+ }
4007
+ }
4008
+ return object;
4009
+ };
3828
4010
  const evaluateObjectPattern = (pattern, st, callback, arg) => {
3829
4011
  let context = {};
4012
+ const taken = [];
3830
4013
  pattern.properties.map((pattern) => {
3831
4014
  switch (pattern.type) {
3832
4015
  case 'Property':
3833
4016
  {
3834
4017
  let key;
3835
- if (pattern.key.type === 'Identifier') {
4018
+ // `computed` is tested first, and that is the whole of a third
4019
+ // defect. `{ [keyName]: q }` parses as `key` an **Identifier** named
4020
+ // `keyName`, so an `Identifier`-first chain took the name it is
4021
+ // spelled with and read `src.keyName` instead of evaluating it and
4022
+ // reading `src[keyName]`. The literal computed form `{ ["a"]: q }`
4023
+ // hid it the way shorthand hid A11 - a `Literal`'s value *is* its
4024
+ // key, so taking the wrong branch landed on the right answer. See
4025
+ // `docs/backlog.md` A14.
4026
+ if (!pattern.computed && pattern.key.type === 'Identifier') {
3836
4027
  key = pattern.key.name;
3837
4028
  }
3838
- else if (pattern.key.type === 'Literal') {
4029
+ else if (!pattern.computed && pattern.key.type === 'Literal') {
3839
4030
  key = pattern.key.value;
3840
4031
  }
3841
4032
  else {
4033
+ // Walked **before** the source property is read, and deliberately:
4034
+ // a computed key is an expression of the *enclosing* scope, not of
4035
+ // the object being destructured. `let { [keyName]: v } = src`
4036
+ // resolves `keyName` where the declaration is written, exactly as
4037
+ // JavaScript does. This is the only `callback` left in the module,
4038
+ // and nothing pushes the source as a scope any more, so there is no
4039
+ // arrangement in which it could resolve against the source.
3842
4040
  callback(pattern.key, st);
3843
4041
  key = popVisitorResult(pattern, st);
3844
4042
  if (typeof key !== 'string' && typeof key !== 'number')
3845
4043
  throw new Error(`Unsupported property key type: ${pattern.key.type}`);
3846
4044
  }
3847
- // **Where `let { a = 1 } = o` actually lands**, which is not where
3848
- // it was expected to. A default in an object pattern is parsed as
3849
- // `Property.value` of type `AssignmentPattern` - so it is handed to
3850
- // `callback` below and walked as an *expression*, and reaches neither
3851
- // of this module's two `switch` defaults. Rejecting it there would
3852
- // have left the object form of the very example that names the
3853
- // divergence still binding silently; the array form
3854
- // (`let [a = 1] = arr`) and the parameter form (`(a = 1) => a`) do go
3855
- // through `evaluatePatterns`, and are covered there.
4045
+ // **Where `let { a = 1 } = o` actually lands**, which is not where it
4046
+ // was expected to. A default in an object pattern is parsed as
4047
+ // `Property.value` of type `AssignmentPattern`, and this branch is
4048
+ // the only thing that sees it: the recursion below would hand it to
4049
+ // `evaluatePattern`, whose `AssignmentPattern` case is commented out,
4050
+ // so it would reach that function's `default` and be rejected with
4051
+ // the same message one frame further down. Kept here so the rejection
4052
+ // is attributable to the object form, and because it predates the
4053
+ // recursion - before it, nothing reached either `switch` at all and
4054
+ // the form bound silently. The array form (`let [a = 1] = arr`) and
4055
+ // the parameter form (`(a = 1) => a`) go through `evaluatePatterns`
4056
+ // and are covered there.
3856
4057
  if (pattern.value.type === 'AssignmentPattern') {
3857
4058
  unsupportedBindingTarget(pattern.value.type);
3858
4059
  }
3859
- const ctx = arg;
3860
- // `finally`, for the reason given at the other push site in
3861
- // arrow-function-expression.ts: the scope stack is on EvalContext,
3862
- // which outlives this walk, so a scope left behind here shadows a
3863
- // source key on every later evaluation against the same context.
3864
- // The `try` opens after the push, never around it.
3865
- st.context?.push(ctx);
3866
- let value;
3867
- try {
3868
- callback(pattern.value, st);
3869
- value = popVisitorResult(pattern, st);
4060
+ taken.push(key);
4061
+ // Guarded on the way *in*, which is where the blocklist has to sit
4062
+ // now that the value is a binding target rather than an expression.
4063
+ // `let { __proto__: p } = o` and `let { constructor: { x } } = o`
4064
+ // both stop here, and the nested form is why the read is guarded and
4065
+ // not only the binding name below: a plain read would hand `Function`
4066
+ // to the recursion, and `evaluateIdentifier`'s guard would then be
4067
+ // inspecting the *inner* pattern's names, by which point the escape
4068
+ // has happened.
4069
+ //
4070
+ // Tested explicitly rather than left to `safeGetProperty`, which
4071
+ // returns early for a non-object target **before** it checks the key
4072
+ // - so `(({ valueOf: v }) => v)(o)` with `o` unbound would read
4073
+ // `undefined` and bind quietly. The blocklist applies to the source
4074
+ // key whatever the source turns out to be, which is the net the
4075
+ // declaration and arrow-parameter binders already cast.
4076
+ if (isDangerousProperty(key)) {
4077
+ throw new Error(`Access to dangerous property "${String(key)}" is blocked for security reasons`);
3870
4078
  }
3871
- finally {
3872
- st.context?.pop();
3873
- }
3874
- // Guarded for the same reason `evaluateIdentifier` is: the key comes
3875
- // from the *pattern*, so `let { __proto__: p } = o` names `__proto__`
3876
- // here and a raw assignment would set this record's prototype.
3877
- const pair = {};
3878
- safeSetProperty(pair, key, value);
3879
- context = { ...context, ...pair };
4079
+ const value = safeGetProperty(arg, key);
4080
+ // The binding target, which may be a name, another object pattern,
4081
+ // or an array pattern. Recursion is the whole repair: `Property.value`
4082
+ // is a *pattern* and is bound against the source property, where it
4083
+ // used to be walked as an **expression** against the source object -
4084
+ // which resolved the wrong name and bound the wrong one. See
4085
+ // `docs/backlog.md` A11.
4086
+ const bound = evaluatePattern(pattern.value, st, callback, value);
4087
+ context = { ...context, ...bound };
3880
4088
  }
3881
4089
  break;
3882
4090
  case 'RestElement':
3883
4091
  {
3884
- const object = evaluateRestElement(pattern, st, callback, arg);
4092
+ // The remainder, not the whole source. Acorn requires the rest
4093
+ // element last in an object pattern, so `taken` is complete here.
4094
+ // Binding the whole argument left an already-destructured key on the
4095
+ // rest record - `docs/backlog.md` A13.
4096
+ const object = evaluateRestElement(pattern, st, callback, restOf(arg, taken));
3885
4097
  context = { ...context, ...object };
3886
4098
  }
3887
4099
  break;
@@ -5247,7 +5459,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.8", ngImpor
5247
5459
  }], ctorParameters: () => [] });
5248
5460
 
5249
5461
  /**
5250
- * Service for evaluating and parsing expressions with proper memory management.
5462
+ * Service for evaluating and parsing expressions.
5463
+ *
5464
+ * It keeps no reference to anything you pass it or anything it hands back: a
5465
+ * state from `createState`, its context and an `options.hooks` registry are
5466
+ * yours, and are collectable once you drop them (`docs/backlog.md` A8).
5251
5467
  */
5252
5468
  class EvalService extends BaseEval {
5253
5469
  /**
@@ -5256,88 +5472,31 @@ class EvalService extends BaseEval {
5256
5472
  constructor() {
5257
5473
  super(inject(ParserService));
5258
5474
  this._isDestroyed = false;
5259
- this._activeContexts = new Set();
5260
- this._activeStates = new Set();
5261
5475
  this.parserService = inject(ParserService);
5262
5476
  this.parserOptions = defaultParserOptions;
5263
5477
  }
5264
5478
  /**
5265
- * Override createState to track active contexts and states for cleanup
5479
+ * Builds a state for `eval` / `evalAsync`. The service does not keep it:
5480
+ * the state is yours, and so are its context and any `options.hooks`
5481
+ * registry it adopted (`docs/backlog.md` A8, A20). Nothing the service does
5482
+ * later, `ngOnDestroy` included, reaches it.
5266
5483
  */
5267
5484
  createState(context, options) {
5268
5485
  if (this._isDestroyed) {
5269
5486
  throw new Error('EvalService has been destroyed and cannot be used');
5270
5487
  }
5271
- const state = super.createState(context, options);
5272
- // Track active states for cleanup
5273
- this._activeStates.add(state);
5274
- // Track active contexts
5275
- if (context && typeof context === 'object') {
5276
- // Check if it's a Registry-based context (has type property)
5277
- if ('type' in context) {
5278
- this._activeContexts.add(context);
5279
- }
5280
- // For EvalContext, check if it has a nested context using bracket notation
5281
- if ('context' in context) {
5282
- const nestedContext = context['context'];
5283
- if (nestedContext && typeof nestedContext === 'object' && 'type' in nestedContext) {
5284
- this._activeContexts.add(nestedContext);
5285
- }
5286
- }
5287
- }
5288
- return state;
5488
+ return super.createState(context, options);
5289
5489
  }
5290
5490
  /**
5291
- * Clean up resources to prevent memory leaks
5491
+ * Marks the service destroyed, so that `createState`, `simpleEval` and
5492
+ * `simpleEvalAsync` throw from then on. It releases and changes nothing
5493
+ * else: the service holds no state, context or registry to release. Clear
5494
+ * a registry you passed through `options.hooks` in your own teardown, with
5495
+ * the unsubscribe `on` / `onRead` returned or `hooks.clear()`
5496
+ * (`docs/backlog.md` A8).
5292
5497
  */
5293
5498
  ngOnDestroy() {
5294
5499
  this._isDestroyed = true;
5295
- // Clean up all active states
5296
- for (const state of this._activeStates) {
5297
- try {
5298
- // Clear the stack in the result
5299
- if (state.result?.stack) {
5300
- state.result.stack.clear();
5301
- }
5302
- // Clear context if it has a clear method
5303
- if (state.context && typeof state.context === 'object' && 'clear' in state.context && typeof state.context.clear === 'function') {
5304
- state.context.clear();
5305
- }
5306
- // Drop hook registrations so a long-lived closure cannot pin a
5307
- // destroyed state. This matters most for a registry the caller passed
5308
- // through `options.hooks` and still holds: one that outlives the
5309
- // service keeps every state its closures captured reachable. A
5310
- // state-owned registry would die with its state regardless.
5311
- //
5312
- // Guarded on `hasHooks` rather than reading `state.hooks`, because that
5313
- // getter builds a registry on first access - allocating inside the
5314
- // method whose job is releasing memory. The guard is exact for this
5315
- // purpose: it is false only when no hook is registered, and clearing an
5316
- // empty registry does nothing.
5317
- if (state.hasHooks) {
5318
- state.hooks.clear();
5319
- }
5320
- // Bookkeeping lives on the state and `clear` cannot reach it, so the
5321
- // open-node stack and collected errors need dropping separately.
5322
- state.resetHookBookkeeping();
5323
- }
5324
- catch (error) {
5325
- console.warn('Error cleaning up EvalState:', error);
5326
- }
5327
- }
5328
- this._activeStates.clear();
5329
- // Clean up all active contexts
5330
- for (const context of this._activeContexts) {
5331
- try {
5332
- if (context && typeof context.clear === 'function') {
5333
- context.clear();
5334
- }
5335
- }
5336
- catch (error) {
5337
- console.warn('Error cleaning up Context:', error);
5338
- }
5339
- }
5340
- this._activeContexts.clear();
5341
5500
  }
5342
5501
  /**
5343
5502
  * Evaluates the given expression.
@@ -5349,6 +5508,8 @@ class EvalService extends BaseEval {
5349
5508
  simpleEval(expression, context, options) {
5350
5509
  try {
5351
5510
  const ast = this.parse(expression);
5511
+ // Through `createState`, which a subclass may override, rather than a
5512
+ // private builder (`docs/a8/plan.md` § 2.1).
5352
5513
  const state = this.createState(context, options);
5353
5514
  if (state?.result && typeof expression === 'string') {
5354
5515
  state.result.expression = expression;
@@ -5401,6 +5562,8 @@ class EvalService extends BaseEval {
5401
5562
  simpleEvalAsync(expression, context, options) {
5402
5563
  try {
5403
5564
  const ast = this.parse(expression);
5565
+ // As in `simpleEval`. The pending frame holds the state for as long as
5566
+ // the promise it awaits is reachable, and nothing else does.
5404
5567
  const state = this.createState(context, options);
5405
5568
  if (state?.result && typeof expression === 'string') {
5406
5569
  state.result.expression = expression;