@zvenigora/ng-eval-core 0.5.0 → 0.6.1

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/CHANGELOG.md ADDED
@@ -0,0 +1,539 @@
1
+ # Changelog — `@zvenigora/ng-eval-core`
2
+
3
+ All notable changes to `@zvenigora/ng-eval-core` are documented in this file. The other two packages in this repository keep their own, listed in the [root changelog](../../CHANGELOG.md).
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ A heading marked "(not published to npm)" is a version that was recorded here and never published.
8
+
9
+ Versions 0.1.104–0.1.107 are on npm without entries here.
10
+
11
+ ---
12
+
13
+ ## [Unreleased]
14
+
15
+ ---
16
+
17
+ ## [0.6.1] - 2026-09-29
18
+
19
+ **A patch: two manifest-and-hygiene fixes, [F5](../../docs/backlog-retired.md#f5) and
20
+ [B3](../../docs/backlog-retired.md#b3), a dead line removed, and a README correction.** No
21
+ published symbol is added and none changes shape. `eval-signals` 0.1.3 and `eval-forms` admit it
22
+ unchanged: both declare `>=0.3.0 <0.7.0`.
23
+
24
+ ### Changed
25
+ - **The `js-sha256` peer range is widened** from `^0.10.1` to
26
+ `^0.10.1 || ^0.11.0 || ^0.12.0 || ^1.0.0`. On `0.x` a caret range admits only its own minor, so
27
+ a project already on `js-sha256` 1.0.0, the current `latest`, got an npm peer warning naming this
28
+ package. No code changed; tested against 0.10.1 and 1.0.0. [F5](../../docs/backlog-retired.md#f5).
29
+ - **`ParserService` no longer logs when its periodic cleanup clears the parse cache.** The
30
+ `console.debug('Parser cache cleared to prevent memory leaks')` is gone; the cache is still
31
+ cleared on the same condition. The published bundle now makes no `console.*` call.
32
+ [B3](../../docs/backlog-retired.md#b3).
33
+ - **Built with Angular 22.1.** The published `.d.ts` declares each service's `ɵprov` as
34
+ `ɵɵInjectableDeclaration<any>`, where 0.6.0, built with Angular 22.0, declared it with the
35
+ service's own type (`ɵɵInjectableDeclaration<ParserService>`, and so on for `EvalService`,
36
+ `CompilerService` and `DiscoveryService`). This is Angular's generated injection metadata, not
37
+ this package's API, and those four lines are the whole `.d.ts` difference from 0.6.0.
38
+ - **`CHANGELOG.md` now ships in the package**, beside `README.md`. Its links into the repository's
39
+ `docs/` resolve on GitHub, not on npm.
40
+
41
+ ### Fixed
42
+ - **The `import()` visitor's dead `afterVisitor` call is removed.** It followed an unconditional
43
+ throw, so it never ran. Behaviour is unchanged; the bundle loses that one line.
44
+ [A3](../../docs/backlog-retired.md#a3).
45
+ - **The README no longer presents `EvalScopeOptions.thisArg` as applied.** `thisArg` is accepted
46
+ and is not currently applied: a method reached through a scope's namespace, such as
47
+ `cat.action()`, is called with the scope's own object as `this`, whatever `thisArg` holds.
48
+ Nothing changes at runtime; the README's Scopes section now says this. What `thisArg` should
49
+ mean is open, as [A7](../../docs/backlog.md#a7), and answering it changes a call's receiver.
50
+
51
+ ---
52
+
53
+ ## [0.6.0] - 2026-09-26
54
+
55
+ **The trace bound, [A12](../../docs/backlog-retired.md#a12), and `EvalService`'s lifecycle,
56
+ [A8](../../docs/backlog-retired.md#a8) with [A20](../../docs/backlog-retired.md#a20), [A21](../../docs/backlog-retired.md#a21) and
57
+ [B3](../../docs/backlog-retired.md#b3).** A **minor** rather than a patch: it adds four published symbols and
58
+ changes the shape of none, and this repository has never shipped API in a patch. It does withdraw
59
+ one documented behaviour, `EvalService.ngOnDestroy` clearing your hook registries, and
60
+ *Upgrading* says what to do instead. `eval-signals 0.1.3` and `eval-forms 0.2.3` below widen
61
+ their peer ranges to admit it.
62
+
63
+ ### Added
64
+
65
+ - **`maxTraceItems`**, an evaluation option bounding how many entries `EvalResult.trace` keeps.
66
+ Defaults to **10,000** — roughly 0.5 MB. The **head** is kept in order, so `trace[0]` is still
67
+ the first value the walk pushed.
68
+ - **`EvalResult.traceTruncated`** — `true` once a push has actually been **dropped**, and it
69
+ stays true until `clearTrace()`. A walk of exactly `maxTraceItems` pushes leaves it `false`,
70
+ because nothing was lost. No entry is appended to the trace to mark truncation: every row in it
71
+ describes a real node. Under `maxTraceItems: 0` it also stays `false` — that is tracing turned
72
+ off, not a trace that lost something.
73
+ - **`EvalResult.tracePushCount`** — every push the state made since it was built or last
74
+ cleared, which is the number the trace no longer tells you once it is truncated. Accurate even
75
+ when tracing is off.
76
+ - **`EvalResult.clearTrace()`** — the only reset for the trace and both counters. It empties the
77
+ array **in place**, so a consumer holding `state.result.trace` keeps a live reference rather
78
+ than a stale snapshot.
79
+ - `EvalResult.addTraceBounded` and `EvalState.maxTraceItems`. These are `@internal`-tagged:
80
+ supported for this library's own use, not part of the contract, and not counted in the four
81
+ above. They are nonetheless reachable on published classes, so they are listed rather than
82
+ hidden.
83
+
84
+ ### Changed
85
+
86
+ - **`EvalResult.trace` stops growing past 10,000 entries by default**. It gained an
87
+ entry per pushed value and was reset by nothing, so a loop's trace grew as iterations × nodes:
88
+ 700,007 entries and ~34 MB for a 100,000-iteration loop — which the default `maxIterations`
89
+ does not stop, since it charges exactly its budget and completes. Where the budget *does* stop
90
+ a loop, the whole allocation was paid *before* the throw. The budget bounded time; nothing
91
+ bounded the memory.
92
+ - **`EvalTraceItem.start` and `end` are documented as reserved**
93
+ ([A16](../../docs/backlog-retired.md#a16)). Nothing has ever set either field. Their JSDoc now says so, and
94
+ points at `expression` and `EvalState.nodeTimings` for the source text and timing they appear
95
+ to offer. Documentation only — both fields keep their optional `number` type — but the JSDoc
96
+ ships in the `.d.ts`.
97
+ - **⚠️ `EvalService.ngOnDestroy` no longer clears any hook registry, and drains nothing**
98
+ ([A8](../../docs/backlog-retired.md#a8)). **This withdraws documented behaviour.** From 0.3.0
99
+ to 0.5.0, destroy cleared the value stack, the hook registrations and the hook bookkeeping of
100
+ every state the service had built, and that included an `EvalHooks` registry you passed through
101
+ `options.hooks`. It follows from the fix below: the service now keeps no state, so at destroy
102
+ there is none for it to reach. It marks the service destroyed, so later calls throw, and does
103
+ nothing else. This is a trade. Keeping the clear would mean the service keeping those states,
104
+ or their registries, until destroy, and that is the leak being fixed. The cost falls only on
105
+ what you keep past the root injector. That means a registry with a hook on it that keeps a
106
+ state, or a `createState` state whose hook bookkeeping you relied on destroy to reset.
107
+ *Upgrading* says what to do instead. The `hooks` JSDoc, which ships in the `.d.ts`, and the
108
+ README no longer make the promise.
109
+ - **`EvalService.ngOnDestroy` no longer logs to `console.warn`**
110
+ ([B3](../../docs/backlog-retired.md#b3)). The warn reported a drain that threw, and there is no drain.
111
+
112
+ ### Upgrading
113
+
114
+ **No expression result changes.** `eval`, `simpleEval` and their async forms return
115
+ byte-identical values. What changes is two surfaces around the result:
116
+
117
+ - **Diagnostics.** `EvalResult.trace` is bounded where it was not ([A12](../../docs/backlog-retired.md#a12)).
118
+ - **`EvalService`'s lifecycle: what it keeps, and what `ngOnDestroy` touches.** The service no
119
+ longer keeps anything you pass it or anything it hands back. That means no state, whether from
120
+ `simpleEval`, `simpleEvalAsync` or `createState`, and no context ([A8](../../docs/backlog-retired.md#a8),
121
+ [A20](../../docs/backlog-retired.md#a20)). Each is collectable once you drop it. `ngOnDestroy` marks the
122
+ service destroyed and does nothing else. It drains no state, empties none of your registries
123
+ or contexts ([A21](../../docs/backlog-retired.md#a21)), and no longer logs ([B3](../../docs/backlog-retired.md#b3)).
124
+
125
+ The first is covered by the trace paragraphs below. For the second, two changes can ask
126
+ something of you, and the next two paragraphs say what: the hook registries destroy no longer
127
+ clears, and the hook bookkeeping it no longer resets.
128
+
129
+ **If you relied on `EvalService.ngOnDestroy()` to clear an `EvalHooks` registry you passed
130
+ through `options.hooks`**, it no longer does, whichever method you passed it to
131
+ ([A8](../../docs/backlog-retired.md#a8)). From 0.3.0 to 0.5.0, the `hooks` JSDoc said:
132
+
133
+ > `EvalService.ngOnDestroy` empties the registries of the states it created, this one included,
134
+ > so that a registry outliving the service cannot keep those states and their AST nodes
135
+ > reachable.
136
+
137
+ The README said the same. You are affected only if the registry outlives the root injector
138
+ **and** a hook on it keeps a state. That covers a hook that captures one
139
+ (`hooks.on('after', '*', () => state)`), one that stores the events it receives or
140
+ `event.state`, and a `createDependencyTracker` installed on it, which stores them in `reads`. In
141
+ that case, those states and their contexts now live as long as the registry does. **Release it
142
+ yourself** when you are done with it, in the teardown that owns the registry, such as your
143
+ component's `ngOnDestroy` or a `DestroyRef.onDestroy` callback. Call the unsubscribe that `on` /
144
+ `onRead` returned, or `hooks.clear()`.
145
+
146
+ **If you keep a state from `createState` past the root injector**, destroy no longer resets its
147
+ hook bookkeeping: the errors in `hookErrors`, and any frame a walk left open. 0.5.0 reset both,
148
+ and cleared the state's value stack. If you relied on that, call `state.resetHookBookkeeping()`
149
+ yourself. The trace was never part of it. 0.5.0's destroy did not clear the trace, and
150
+ `clearTrace()` is new in this release.
151
+
152
+ **If you read `EvalResult.trace` programmatically**, two things to check. Above 10,000 pushes on
153
+ one state it now stops, and `traceTruncated` is how you detect that — a truncated trace is
154
+ otherwise indistinguishable from a complete one. And the trace spans every evaluation run on a
155
+ state, so the bound is on their **total**; `clearTrace()` is how the `createState` + repeated
156
+ `eval` style gets a trace describing one walk.
157
+
158
+ **Two values are honoured rather than treated as falsy**: `maxTraceItems: 0` disables tracing
159
+ while keeping `tracePushCount` accurate, and `Infinity` restores the previous behaviour exactly.
160
+
161
+ ### Fixed
162
+
163
+ - **`EvalService.ngOnDestroy` no longer empties your registries**
164
+ ([A21](../../docs/backlog-retired.md#a21)). It called `clear()` on every context with a `type` passed to
165
+ `createState`, `simpleEval` or `simpleEvalAsync`, including one nested under a `context`
166
+ key. So when the root injector was destroyed, in a test, per SSR request or at a
167
+ micro-frontend's teardown, every `Registry` the application had evaluated against was emptied,
168
+ even though the application still held it. It also called a `clear` method on any other object
169
+ passed in that had a `type` key and declared one, a caller's `EvalContext` subclass included. It
170
+ now changes nothing inside them, and since the two entries below it holds no reference to them
171
+ either. No exported symbol changes.
172
+ - **Under `caseInsensitive`, a context object with a `type` field is no longer kept alive by
173
+ `EvalService`** ([A20](../../docs/backlog-retired.md#a20)). `createState`, `simpleEval` and
174
+ `simpleEvalAsync` added every context with a `type`, including every `Registry` and
175
+ `EvalContext`, to a set that nothing read and that emptied only when the service was destroyed.
176
+ The set is gone. On its own that changed only one case. Under `caseInsensitive`, a plain object
177
+ or class instance is copied into a new `Registry` rather than adopted, so the set was the only
178
+ thing holding the original. It can now be garbage-collected once you drop it. Every other
179
+ context is released by the next entry, which removes the evaluation states that held them.
180
+ No exported symbol changes.
181
+ - **`EvalService` no longer keeps any evaluation state until the application ends**
182
+ ([A8](../../docs/backlog-retired.md#a8)). It added every state it built, through `simpleEval`,
183
+ `simpleEvalAsync` or `createState`, to a set that emptied only in `ngOnDestroy`. So each
184
+ state was kept for the life of the root injector, including one you had finished with and
185
+ dropped. That meant the parsed expression, the trace (up to `maxTraceItems`), and the context
186
+ you passed, with everything reachable from it. The pattern `eval-signals` documents,
187
+ `simpleEval(expr, createSignalContext(...))`, kept each signal context and the signal sources it
188
+ reads. The set is gone. A state from `simpleEval` or `simpleEvalAsync` is collectable when the
189
+ call returns, including a call that throws or a promise that rejects. One from `createState` is
190
+ collectable once you drop it. Either way your context goes with it, once nothing else holds it.
191
+ No exported symbol changes. The one documented behaviour this withdraws, destroy clearing your
192
+ hook registries, is under *Changed* and *Upgrading*.
193
+
194
+ ---
195
+
196
+ ## [0.5.0] - 2026-09-17
197
+
198
+ ### Fixed
199
+
200
+ - **Object destructuring now binds the names JavaScript binds.** `evaluateObjectPattern` took
201
+ the binding name from the pattern's **key** and then resolved the pattern's **value** as an
202
+ *expression* against the source object. For `{ a: b }` that resolved the identifier `b`
203
+ against the source and bound the name `a` to whatever came back — both halves wrong at once,
204
+ where JavaScript binds `b` to `src.a`. Shorthand `{ a }` hid it, because `key` and `value`
205
+ both name `a`, so resolving the wrong one landed on the right answer.
206
+
207
+ Affected, through **both** arrow parameters and `let`/`const` declarations:
208
+
209
+ | Pattern | before | now |
210
+ | ------- | ------ | --- |
211
+ | `{ a: b }` — read `b` | `undefined` | the source's `a` |
212
+ | `{ a: b }` — read `a` | the source's `b`, when it had one | not bound |
213
+ | `{ a: x, b: y }` | neither bound | both bound |
214
+ | `{ a: { b } }` | nothing bound | the inner `b` |
215
+ | `{ a: { b: z } }` | nothing bound | the inner `b` |
216
+ | `{ "a": q }` | `undefined` | the source's `a` |
217
+ | `{ ["a"]: q }` | `undefined` | the source's `a` |
218
+
219
+ **Most consumers saw `undefined` rather than a wrong value.** The wrong-value case needs the
220
+ renamed-*to* name to exist on the source as well — `{ a: b }` over a source carrying both
221
+ `a` and `b` — and otherwise the value name resolves to nothing. If you inverted a rename to
222
+ work around this, remove the inversion.
223
+
224
+ Shorthand `{ a }` and array patterns were correct and are unchanged. Defaults (`{ a = 1 }`)
225
+ continue to throw `AssignmentPattern is not supported as a binding target.`
226
+
227
+ - **A computed key is now evaluated.** `{ [keyName]: q }` parses with `key` an `Identifier`,
228
+ and the branch order tested `Identifier` before `computed` — so the key was taken to be the
229
+ *name it is spelled with* and the source was read at `src.keyName` instead of at
230
+ `src[keyName]`. The literal form `{ ["a"]: q }` hid it, a `Literal`'s value being its own
231
+ key. Computed keys are evaluated in the enclosing scope, as in JavaScript.
232
+
233
+ - **An object rest element now binds the remainder.** `{ a, ...r }` bound the **whole** source
234
+ to `r`, leaving a key a sibling property had already taken: `(({a, ...r}) => r.a)(src)` was
235
+ the source's `a` and is now `undefined`. Keys are excluded by their **source** name, so
236
+ `{ a: x, ...r }` removes `a`. Array rest was already correct. This is the one item here
237
+ whose old answer was a real value rather than `undefined`, so it is the one a consumer may
238
+ have been reading without knowing.
239
+
240
+ ### Changed
241
+
242
+ - **`evaluateObjectPattern` no longer pushes a scope.** It pushed the source so the value
243
+ could be resolved against it, which was the defect above; the value is now bound as a
244
+ pattern and nothing reads a scope. No consumer-visible behaviour depends on this, but it
245
+ means `pattern.ts` is no longer one of the visitors the `BL-A9` push/pop idiom applies to.
246
+
247
+ - **The prototype-pollution blocklist now applies to the source key on the way in.**
248
+ `{ __proto__: p }` and `{ constructor: { x } }` are rejected before the source property is
249
+ read, rather than at the binding write — which is what keeps the guard in front of a nested
250
+ pattern, where a plain read would have handed `Function` to the recursion. The rejection and
251
+ its message are unchanged for every form that already threw.
252
+
253
+ ### Upgrading
254
+
255
+ `0.5.0` is a minor rather than a patch because expression **results change** on the paths
256
+ above: a consumer on `^0.4.0` does not receive it unattended, and should re-run their own
257
+ expression tests when they take it. The two downstream packages widen their peer range to
258
+ admit it in the same change — `eval-signals 0.1.2` and `eval-forms 0.2.2` below — which is
259
+ what `@nx/dependency-checks` requires of a workspace release, and neither carries any other
260
+ change.
261
+
262
+ ---
263
+
264
+ ## [0.4.0] - 2026-09-15
265
+
266
+ Phase 2 of the [roadmap](../../ROADMAP.md): **statement support**. `let` and `const` declarations,
267
+ blocks, `if`/`else` and the classic three-part `for` now evaluate as statements, with JavaScript's
268
+ completion-value semantics. Design, measurements and the questions it settles are in
269
+ `docs/statements/phase-2-plan.md`; the retrospect is in `docs/statements/summary.md`.
270
+
271
+ **Read the Changed section before upgrading.** Statements were never *unsupported* — they were
272
+ walked as expressions and silently mis-evaluated, so this release changes what a dozen already-working
273
+ expressions return, and rejects a dozen more that used to return a value. If your expressions are
274
+ single expressions (`a + b * c`, `user.name`, `items.filter(…)`), nothing here reaches you.
275
+
276
+ ### Added
277
+
278
+ - **Seven statement node types**: `Program`, `ExpressionStatement`, `EmptyStatement`,
279
+ `BlockStatement`, `VariableDeclaration` (`let` / `const`), `IfStatement` and `ForStatement`.
280
+ Blocks introduce a scope; declarations bind into it and do not write the caller's context object.
281
+ - **`EMPTY_COMPLETION`**, exported. A statement that produces no value — a declaration, an `if`
282
+ that takes no branch, a `for` that runs zero iterations — pushes this sentinel rather than
283
+ `undefined`, because JavaScript's completion-value semantics keep the last *non-empty* value and
284
+ empty is not `undefined`. It never leaves an evaluation's return value, but an `after` hook on a
285
+ statement node fires before the conversion and **will** see it, so it is exported for identity
286
+ comparison on the precedent of `ASYNC_HOOK_MESSAGE`. See the
287
+ [package README](README.md#statements-and-the-empty-completion-sentinel).
288
+ - **`maxIterations`** on `EvalOptions`, defaulting to **100,000** iterations per evaluation.
289
+ Exceeding it raises `Iteration budget exhausted after <n> iterations`. The budget is per
290
+ outermost `eval` call and shared by every loop in the expression. It bounds **time, not memory**:
291
+ `result.trace` grows per pushed value and that allocation is paid before the throw.
292
+ - **`EvalContext.setInScope`**, and `EvalContext.scopeHolding` promoted from private — a write
293
+ needs the scope, not a yes/no, because `const` kinds are keyed by scope.
294
+ - `EvalHooks.pushWalkBase` / `popWalkBase` / `walkBase`, and `EvalState.walkDepth` / `enterWalk` /
295
+ `exitWalk` / `iterationsRemaining` / `chargeIteration` / `declareConst` / `isConstBinding`. These
296
+ are `@internal`-tagged: supported for this library's own use, not part of the contract. They are
297
+ nonetheless reachable on published classes, so they are listed rather than hidden.
298
+
299
+ ### Changed
300
+
301
+ **Every row below was transcribed from `statement-semantics.spec.ts` and the step-6 audit, both
302
+ run against 0.3.0 and 0.4.0 — not from the design document.**
303
+
304
+ Expressions that returned a value and now return a **different** value:
305
+
306
+ | Expression | 0.3.0 | 0.4.0 |
307
+ | ---------- | ----- | ----- |
308
+ | `let x = 1` | `1` | `undefined` |
309
+ | `let x = 1; x + 1` | `NaN` | `2` |
310
+ | `const y = 2; y` | `undefined` | `2` |
311
+ | `if (a) { 1 } else { 2 }`, `a` truthy | `2` | `1` |
312
+ | `if (a) { 1 }`, `a` falsy | `1` | `undefined` |
313
+ | `for (let i = 0; i < 3; i++) { i }` | `NaN` | `2` |
314
+ | `let [p, q] = arr` | the array | `undefined`, and `p` / `q` are now bound |
315
+
316
+ Expressions that returned a value and now **throw**:
317
+
318
+ | Expression | 0.3.0 | 0.4.0 |
319
+ | ---------- | ----- | ----- |
320
+ | `while (false) { 1 }` | `1` | `Unsupported statement type: WhileStatement` |
321
+ | `do { 1 } while (false)` | `1` | `Unsupported statement type: DoWhileStatement` |
322
+ | `for (const k in o) { k }` | `undefined` | `Unsupported statement type: ForInStatement` |
323
+ | `for (const v of arr) { v }` | `undefined` | `Unsupported statement type: ForOfStatement` |
324
+ | `switch (1) { case 1: 2 }` | `2` | `Unsupported statement type: SwitchStatement` |
325
+ | `try { 1 } catch (e) { 2 }` | `2` | `Unsupported statement type: TryStatement` |
326
+ | `throw 1` | `1`, throwing nothing | `Unsupported statement type: ThrowStatement` |
327
+ | `x: 1` | `1` | `Unsupported statement type: LabeledStatement` |
328
+ | `break` / `continue` in a loop body | `undefined` | `Unsupported statement type: …` |
329
+ | `function f() { return 1 }` | `1` | `Unsupported statement type: FunctionDeclaration` |
330
+ | `class C {}` | `undefined` | `Unsupported statement type: ClassDeclaration` |
331
+ | `var x = 1` | `1` | `Unsupported variable declaration kind: var` |
332
+ | `const y = 1; y = 2; y` | `2` | `Assignment to constant variable "y".` |
333
+ | `let { a = 1 } = o; a` | `undefined` | `AssignmentPattern is not supported as a binding target.` |
334
+ | `(toString => toString)(1)` | `1` | `Access to dangerous property "toString" is blocked…` |
335
+
336
+ **The messages above are the ones raised at the top level.** A throw from inside a called arrow
337
+ function is re-wrapped, so `(toString => toString)(1)` is caught as
338
+ `Function call error: Access to dangerous property "toString" is blocked for security reasons`, and
339
+ an unsupported statement inside a block-bodied arrow as
340
+ `Function call error: Unsupported statement type: …`. Match on a substring rather than on the start
341
+ of the message.
342
+
343
+ The last row is the widest of them: binding writes now share the prototype-pollution blocklist with
344
+ every other write site, so all thirteen blocked names are rejected as **arrow function parameters**
345
+ too — a form that has nothing to do with declarations. Only `__proto__` is an actual write vector;
346
+ the rest is kept wide so that "is this name blocked?" does not depend on which visitor reached it.
347
+
348
+ **This is a change of kind, not only of coverage.** Before 0.4.0 an unsupported statement was handed
349
+ to `acorn-walk`'s base walker, which walked the subtree as an expression and left whatever it pushed
350
+ on the value stack — which is why `throw 1` evaluated to `1` and threw nothing. There is now an
351
+ explicit dispatcher whose `default` raises.
352
+
353
+ Expressions whose **value is unchanged** and whose stranded-value count is not — listed because the
354
+ values above make it reasonable to assume otherwise:
355
+
356
+ | Expression | 0.3.0 | 0.4.0 |
357
+ | ---------- | ----- | ----- |
358
+ | `1 + 2` | `3`, 0 stranded | unchanged |
359
+ | `1; 2; 3` | `3`, **2 stranded** | `3`, 0 stranded |
360
+ | `a; b` | `'B'`, **1 stranded** | `'B'`, 0 stranded |
361
+ | `{ 1; 2 }` | `2`, **1 stranded** | `2`, 0 stranded |
362
+ | `(x => { 1 })(0)`, `(x => { 1; 2 })(0)`, `(x => { })(0)` | `1` / `2` / `undefined` | unchanged |
363
+ | `(x => { if (true) { 1 } })(0)` | `1` | `1` |
364
+
365
+ A "stranded" value is one the walk pushed that nothing popped, visible as `result.stack.length` after
366
+ an evaluation returns. It was never read, so the value was right by accident; it is now right by rule.
367
+
368
+ Other behavioural changes on already-shipped paths:
369
+
370
+ - **A write to a bare identifier consults the scope stack before the caller's context object.**
371
+ `(x => (x = 99))(1)` used to write `99` into the caller's own context and leave the arrow's
372
+ parameter untouched; it now writes the parameter. This is what makes `for`'s `i++` work.
373
+ - **A block-bodied arrow's body goes through the statement dispatcher.** Completion values are
374
+ unchanged for every supported form (the table above), but an unsupported statement inside a block
375
+ body now throws where the base walker previously evaluated it:
376
+ `(x => { while (false) { 1 } })(0)` was `1`. In the other direction,
377
+ `(x => { let y = 1; y })(0)` was `undefined` and is now `1`.
378
+ - **`EvalHooks.exit` bounds its scan to the current walk**, so a nested walk can no longer flush
379
+ frames belonging to the walk that contains it.
380
+ - **A throwing arrow body no longer strands a scope on a reused `EvalContext`.** Both scope-push
381
+ sites now pop in a `finally`. Before this, one throwing evaluation left a scope that shadowed a
382
+ source key for the life of the context — and a context is reused by design in
383
+ `@zvenigora/ng-eval-signals`. `docs/backlog.md` A9.
384
+ - **`result.trace` and the `after`-hook stream gain `Program` and `ExpressionStatement` entries on
385
+ every evaluation**, including single-expression ones. Code that counts hook events or trace
386
+ entries sees two more per walk.
387
+ - The visitor table is built once and frozen at first use rather than merged per `evaluate` call.
388
+ Every evaluation is faster; the table is process-wide shared state.
389
+
390
+ ### Fixed
391
+
392
+ - `pattern.ts` no longer writes the whole `EvalState` to the console on a destructuring path
393
+ (`docs/backlog.md` B2). Three `console.*` calls remain in the published bundle, tracked as B3.
394
+
395
+ ### Upgrading alongside `eval-signals` and `eval-forms`
396
+
397
+ **Upgrade both downstream packages with it**: `eval-signals` **0.1.1** and `eval-forms` **0.2.1**,
398
+ released alongside this one and documented above. `eval-signals` 0.1.0 and `eval-forms` 0.2.0
399
+ declare `"@zvenigora/ng-eval-core": "^0.3.0"`, which resolves to `>=0.3.0 <0.4.0` and therefore
400
+ **excludes** this release; installing 0.4.0 beside either of them raises a peer-dependency
401
+ conflict. The two patch releases widen the range and change nothing else.
402
+
403
+ Neither package was ever *incompatible* with 0.4.0 — both suites run against this evaluator on
404
+ every build and are green — so what the conflict reported was a declared range that had not caught
405
+ up. Both continue to support `eval-core` 0.3.0.
406
+
407
+ ### `@zvenigora/ng-eval-signals` — one relaxation, no release
408
+
409
+ `eval-signals` is **not** re-released and its version is unchanged at 0.1.0; this is what its
410
+ existing code does once it resolves `eval-core` 0.4.0.
411
+
412
+ A signal context rejects writes to its keys with `SignalContextWriteError`. Because writes now
413
+ consult the scope stack first, **a write to a binding the expression itself created no longer
414
+ throws** — it mutates nothing the consumer owns. Measured, with `count` a signal in the source:
415
+
416
+ | Expression | with `eval-core` 0.3.0 | with `eval-core` 0.4.0 |
417
+ | ---------- | ---------------------- | ---------------------- |
418
+ | `count = 5` | throws `SignalContextWriteError` | **unchanged** — still throws |
419
+ | `(x => (x = 5))(1)` | throws `SignalContextWriteError` | `5` |
420
+ | `let count = 5; count` | n/a — statements did not evaluate | `5`, and the source's `count` is still `1` |
421
+
422
+ The read-only guarantee is intact: it covers the keys of the signal context, and an expression's own
423
+ bindings were never among them. This is a prerequisite for `for`'s `i++` to work inside a signal.
424
+
425
+ ---
426
+
427
+ ## [0.3.0] - 2026-08-10
428
+
429
+ Phase 1 of the [roadmap](../../ROADMAP.md): a generic evaluation hook API, the prerequisite for the planned `eval-signals` and `eval-forms` libraries. Design and rationale in `docs/side-effects/phase-1-plan.md`; consumer documentation in the [package README](README.md#evaluation-hooks).
430
+
431
+ ### Added
432
+ - **Evaluation Hooks (`EvalHooks`)**: A node-type-keyed hook registry with wildcard (`'*'`) support, reached through `EvalState.hooks`. `on('before' | 'after', type, hook)` fires around each visitor body and returns an unsubscribe; every one of the 19 visitors dispatches through it. Registration is per-`EvalState`, so hooks never leak between evaluations even though `EvalService` is `providedIn: 'root'`.
433
+ - **Read Hooks (`onRead`)**: Fire once per resolved context read, reporting the key **as the context resolved it** — case-corrected under `caseInsensitive`, and exact for computed members — which the AST node alone cannot provide. Events carry `kind`, `key`, `target`, `value`, a best-effort dotted `path`, and `scoped`, which flags a read that resolved to a scope pushed *during* the evaluation (an arrow-function parameter) rather than a real dependency.
434
+ - **Built-in hooks**: `createDependencyTracker()` yields a resettable dependency set per evaluation, filtering scoped reads and any path rooted at one; `createTimingHook()` accumulates per-node-type timings.
435
+ - **`trackTime` option**: Accumulates per-node-type timings on the state, read back as `EvalState.nodeTimings`. Note this registers a hook, so it makes the walk dispatch per node; `EvalResult.duration` remains the free walk-level total.
436
+ - **Hook error policy**: `onHookError` selects `'collect'` (default — a faulty hook cannot break the evaluation it observes), `'throw'`, or `'ignore'`. Collected errors are read from `EvalState.hookErrors`. `ASYNC_HOOK_MESSAGE` is exported so a hook that returned an un-awaited promise can be told apart from an error the hook itself threw.
437
+ - **`EvalState` members**: `hooks`, `hasHooks`, `hookErrors`, `nodeTimings`, and `resetHookBookkeeping()`.
438
+ - **`EvalContext` queries**: `getFromScopes()` and `hasInScopes()`.
439
+
440
+ ### Changed
441
+ - **⚠️ `EvalHookError.phase` widened to `EvalHookPhase | 'read'`**: **The one non-additive change in this release.** Read hooks report errors through the same channel as node hooks, so the phase is no longer just `'before' | 'after'`. Nothing shipped before this version, so no released shape is broken — but a `switch (e.phase)` written against the two-value type will not be exhaustive, and this note is here so that is discovered by reading rather than at runtime. Everything else in this release is purely additive.
442
+ - **Hook dispatch is balanced across throws**: `before`/`after` stay paired on every exit path, including the ones an exception takes. A synthesised `after` carries `completed: false` and no `value`, from two distinct sources — the unwinder, which supplies the `error`, and an enclosing visitor closing without its child, which supplies **no** error on an evaluation that may still succeed. **Presence of `error` is the discriminator**, not `completed === false`.
443
+ - **`ngOnDestroy` releases hook state**: `EvalService` now clears each tracked state's hook registrations and resets its hook bookkeeping, so a long-lived caller-owned registry cannot pin destroyed states or their AST nodes. This covers the states `EvalService.createState` produced — the ones the service tracks. States built elsewhere (`CompilerService.createState`, or `EvalState.fromContext` directly) are not tracked and are not cleared, so this is not a general guarantee about every state in an application.
444
+
445
+ ### Deprecated
446
+ - **`RecursiveVisitorState` and `RecursiveVisitorResult`**: Superseded by `EvalHooks` / `EvalState` / `EvalResult`. Nothing in the library implements them, and shipping them beside the new API would publish two contradictory hook vocabularies: their `beforeVisitors` / `afterVisitors` entries are typed to return `number | undefined` — the last trace of a timing stub the library no longer has — while `EvalNodeHook` mandates `void`. Both remain exported so this release stays additive; removal is a follow-up for the next breaking version.
447
+
448
+ ---
449
+
450
+ ## [0.2.5] - 2026-08-03 (not published to npm)
451
+
452
+ ### Changed
453
+ - **Nx Monorepo Upgrade**: Migrated Nx tooling from **v22.1.3** to **v23.1.1**, bringing Angular to **v22.0.8**, TypeScript to **v6.0.3**, and Jest to **v30.3.0**. Ran the full `nx migrate` flow (47 automatic codemods) plus the migrations Nx deferred to manual review.
454
+ - **ESLint v9 Flat Config**: Converted `.eslintrc.json`/`.eslintignore` to `eslint.config.mjs` at the root and in `eval-core`, replacing the generator's `FlatCompat` shims with flat-native config (the Angular inline-template shim was fully redundant with `@nx/eslint-plugin`'s `flat/angular` preset).
455
+ - **Inferred Nx Targets**: Converted the `eval-core` project's `lint` and `test` targets from the deprecated `@nx/eslint:lint` / `@nx/jest:jest` executors to Nx's inferred targets (`@nx/eslint/plugin`, `@nx/jest/plugin` registered in `nx.json`), removing the executor deprecation warnings scheduled for Nx v24.
456
+ - **Angular Change Detection**: Applied Angular v22's `change-detection-eager` migration, adding an explicit `ChangeDetectionStrategy.Eager` to `EvalCoreComponent` to preserve its pre-v22 default behavior.
457
+
458
+ ### Fixed
459
+ - **Jest `isolatedModules`**: Removed from `eval-core`'s `tsconfig.spec.json` after confirming it broke typecheck (TS1205 on re-exported types) and isn't needed for this single-project workspace.
460
+
461
+ ---
462
+
463
+ ## [0.2.4] - 2026-08-02 (not published to npm)
464
+
465
+ ### Note
466
+ - Version bump with no recorded changelog entry at the time; folded into the [0.2.5] migration work above.
467
+
468
+ ---
469
+
470
+ ## [0.2.3] - 2026-08-01 (not published to npm)
471
+
472
+ ### Added
473
+ - **Repository Audit & Remediation Plan**: Comprehensive documentation detailing codebase audit (`docs/repository-audit.md`) and remediation execution steps (`docs/remediation-plan.md`).
474
+ - **Archive Script**: Command script (`ng-eval-archive.cmd`) for project archiving (`2026-01-02`).
475
+
476
+ ### Fixed
477
+ - **Dependency Security**: Added package overrides for `qs` dependency resolving security vulnerabilities in `package-lock.json` (`2026-01-02`).
478
+ - **Angular Peer Dependencies**: Cleaned up `peerDependencies` in `@zvenigora/ng-eval-core` by removing unused `@angular/common` dependency (`2026-08-01`).
479
+ - **Angular Dependency Injection**: Refactored `CompilerService`, `DiscoveryService`, and `EvalService` to use Angular's modern `inject()` functional dependency injection paradigm (`@angular-eslint/prefer-inject`).
480
+ - **Repository Hygiene**: Removed loose root debug scripts (`debug-ast.js`, `debug-proto.js`, `debug-prototype.js`) and cleaned up stale notes.
481
+
482
+ ---
483
+
484
+ ## [0.2.2] - 2025-11-30
485
+
486
+ ### Changed
487
+ - **Angular Framework Upgrade**: Upgraded Angular framework and dependencies to **v20.x** (v20.1.2 / Angular 20).
488
+ - **Nx Monorepo Upgrade**: Updated Nx tooling to **v22.x** (`22.0.0-beta.6`).
489
+ - **ESLint & Guidelines**: Updated ESLint rules and guidelines for Nx workspace compatibility (`AGENTS.md`).
490
+
491
+ ### Fixed
492
+ - **Repository URL**: Standardized repository URL format across `package.json`.
493
+
494
+ ---
495
+
496
+ ## [0.2.1] - 2025-11-30
497
+
498
+ ### Added
499
+ - **Angular 19 Support**: Updated peer dependencies across packages to officially support Angular 19+ (`>=19.0.0`).
500
+ - **Nx Tooling**: Upgraded build tooling to **Nx 21.4.0** and **Angular 19.2.14** (`2025-08-20`).
501
+
502
+ ### Fixed
503
+ - **ESLint Compliance**: Resolved ESLint errors following the Angular 19 migration.
504
+ - **Documentation**: Enhanced README descriptions and added automated attribution notes.
505
+
506
+ ---
507
+
508
+ ## [0.2.0] - 2025-08-20 (not published to npm)
509
+
510
+ ### Added
511
+ - **LRU Property Lookup Caching**: Implemented LRU cache for property lookups, optimizing lookup performance from $O(n)$ to $O(1)$.
512
+ - **Enhanced Visitors**: Refactored `MemberExpressionVisitor` with cached property lookups and case-insensitive resolution.
513
+ - **Security Hardening**:
514
+ - Comprehensive prototype pollution prevention (`__proto__`, `constructor`, `prototype` protections).
515
+ - Call expression execution security and strict scope boundary enforcement.
516
+ - Enhanced binary expression type safety and arithmetic error handling.
517
+ - Safe, guarded asynchronous expression evaluation and stack error tracking.
518
+ - **Memory Management**: Cross-platform memory manager compatibility and leak fixes.
519
+ - **Performance Test Suite**: Added benchmark validation test suite ensuring 100% regression-free performance across all 511 unit tests.
520
+
521
+ ---
522
+
523
+ ## [0.1.102] - 2024-01-03
524
+
525
+ ### Added
526
+ - **Expression Support**: Added support for arrow function expressions, update expressions, assignment expressions, object expressions, template literals, tagged templates, `new` expressions, `this` binding, logic expressions, arrays, and unary operations (`2023-12`).
527
+ - **AST Parsing & Caching**: Added caching mechanisms to `ParserService` utilizing `js-sha256` hashing and Acorn parser integration (`2023-12-02`).
528
+ - **Evaluation State & Trace**: Introduced `EvalState`, `EvalContext`, `EvalOptions`, `EvalResult`, and evaluation trace logging.
529
+ - **Case-Insensitive Evaluation**: Added optional case-insensitive property lookup support across scope registries.
530
+ - **Documentation**: Documented visitor pattern, evaluation functions, core services, and common AST model classes (`docs/`).
531
+
532
+ ---
533
+
534
+ ## [0.1.0] - 2023-11-26 (not published to npm)
535
+
536
+ ### Added
537
+ - **Initial Commit**: Core `@zvenigora/ng-eval-core` library initialization and basic AST evaluation engine (`2023-11-26`).
538
+ - **Angular Integration**: Basic Angular services and Angular plugin integration setup.
539
+ - **Public API**: Initial release of scope, parser, and visitor architecture.
package/README.md CHANGED
@@ -42,7 +42,9 @@ expressions.length; // 2
42
42
 
43
43
  ### Scopes — `EvalContext`, `EvalScope`, `EvalScopeOptions`
44
44
 
45
- An evaluation context may carry prior scopes, each with its own `namespace`, `thisArg` and case sensitivity. Bare identifiers are read from the context itself; a namespaced scope is reached through its namespace.
45
+ An evaluation context may carry prior scopes, each with its own `namespace` and case sensitivity. Bare identifiers are read from the context itself; a namespaced scope is reached through its namespace.
46
+
47
+ `EvalScopeOptions` also accepts `thisArg`, but it is not currently applied: no call uses it as `this`. A method reached through a namespace, such as `cat.action(...)` below, is called with the scope's own object as `this`. The example sets `thisArg` to that same object, so its output does not depend on it.
46
48
 
47
49
  ```javascript
48
50
  import { EvalContext, EvalScope, EvalScopeOptions,
@@ -141,7 +143,41 @@ try {
141
143
 
142
144
  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
145
 
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.
146
+ **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.
147
+
148
+ ### Bounding the trace
149
+
150
+ `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.
151
+
152
+ ```javascript
153
+ const state = service.createState({ a: 10 });
154
+ service.eval('2 + 3 * a', state);
155
+
156
+ state.result.trace.length; // 7
157
+ state.result.traceTruncated; // false
158
+ state.result.tracePushCount; // 7
159
+ ```
160
+
161
+ The **head** is kept, in order, so `trace[0]` is still the first thing evaluated. Once a push is actually dropped:
162
+
163
+ - **`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.
164
+ - **`state.result.tracePushCount`** goes on counting every push, which is the number the trace no longer tells you.
165
+
166
+ ```javascript
167
+ const state = service.createState({}, { maxIterations: Infinity });
168
+ service.eval('for (let i = 0; i < 100000; i++) { i }', state);
169
+
170
+ state.result.trace.length; // 10000
171
+ state.result.traceTruncated; // true
172
+ state.result.tracePushCount; // 700007
173
+ ```
174
+
175
+ Two values are special, and both are honoured rather than treated as falsy:
176
+
177
+ - **`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.
178
+ - **`Infinity`** restores the unbounded behaviour exactly.
179
+
180
+ **`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
181
 
146
182
  ### Evaluation hooks
147
183
 
@@ -242,7 +278,7 @@ Two things to know about it:
242
278
  const state = service.createState(context, { hooks });
243
279
  ```
244
280
 
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.
281
+ 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
282
 
247
283
  #### `completed: false` events
248
284