@zvenigora/ng-eval-core 0.15.0 → 0.16.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/CHANGELOG.md CHANGED
@@ -14,6 +14,139 @@ Versions 0.1.104–0.1.107 are on npm without entries here.
14
14
 
15
15
  ---
16
16
 
17
+ ## [0.16.0] - 2026-11-08
18
+
19
+ **A member read lets a getter's throw reach the caller, and member reads and writes change under
20
+ `caseInsensitive`, through `this` to a `Registry`, and to an `EvalScope`.** A minor carrying
21
+ breaking changes ([A55](../../docs/backlog-retired.md#a55),
22
+ [A48](../../docs/backlog-retired.md#a48), [A51](../../docs/backlog-retired.md#a51); the
23
+ [A48 plan](../../docs/a48/plan.md)), with [A50](../../docs/backlog-retired.md#a50)'s fix and
24
+ [A49](../../docs/backlog-retired.md#a49) decided a documented limit. No exported symbol changes
25
+ shape: the `.d.ts` differs from 0.15.1's in two JSDoc blocks only, `EvalContext`'s `lookups` and
26
+ `getThis`, A49's. What changes is behaviour: what a member read does with a getter or a proxy trap
27
+ that throws, how a `caseInsensitive` member read tests and searches a key, what a write through
28
+ `this` does to a `Registry` that is the context's original, and that a member write to an
29
+ `EvalScope` is refused; each bullet below names the paths it covers. Timed against 0.15.1 on seven
30
+ paths, with no regression on any. `eval-signals` 0.9.0 and `eval-forms` 0.9.0 raise their floors to
31
+ it.
32
+
33
+ ### Breaking
34
+ - **A member read lets a getter's or a proxy `get` trap's throw reach the caller, in both case
35
+ modes.** It caught a throw from the read and gave `undefined`. Case-sensitively, over an object
36
+ whose getter `t` throws, own or inherited, `x.t` was `undefined`, `x.t || 1` was `1` and
37
+ `let {t} = x` bound `undefined`, and `x.t += 1` and `x.t++` threw at the write where `t` has no
38
+ setter and wrote `NaN` through the setter where it has one. Under `caseInsensitive` some of these
39
+ reads already threw, `x.t` over an own getter among them, and some did not, `x.t` over an inherited
40
+ one and `let {t} = x` over either. Each of these forms now throws the getter's own value, an `Error`
41
+ or not, as JavaScript does ([A55](../../docs/backlog-retired.md#a55)). A null or undefined object
42
+ still reads `undefined`.
43
+ - **Under `caseInsensitive`, a member read calls a proxy's `has` trap** for a key no own property
44
+ matches, as a member write already did; JavaScript's read calls none. A throw from that `has`
45
+ trap, or from the `ownKeys` trap of a prototype searched for a case variant, is caught, and the
46
+ key is then read as written ([A48](../../docs/backlog-retired.md#a48)).
47
+ - **Under `caseInsensitive`, a key a proxy answers by its `get` trap alone is searched for a case
48
+ variant.** For a proxy with no `has` trap, `in` does not find a key its target does not hold, so
49
+ the read searches the target's prototype for a case variant, as `=` already did: over a target
50
+ whose prototype has a method `getX`, `px.getx` reads `getX`, and `px.getx += 1` reads and writes
51
+ it; a variant that is a blocked name is refused, so over `{}` `px.tostring` throws
52
+ `Access to dangerous property "toString" is blocked for security reasons`. Up to 0.15.1 the read
53
+ tested the key by reading it, and read it as spelled. A key with no such variant, `px.q`, is read
54
+ as spelled, as before, and a case-sensitive read is unchanged
55
+ ([A48](../../docs/backlog-retired.md#a48), [A59](../../docs/backlog.md#a59)).
56
+ - **A member write to an `EvalScope` is refused.** It throws
57
+ `Write to an evaluation scope is blocked`, where up to 0.15.1 it set an own property on the
58
+ instance. A host that places an `EvalScope` in the context as a value reads it through the scope's
59
+ `get`, so `ns.k = 5`, `ns.k += 5` and `ns.k++` left the scope's context unchanged and a later `ns.k`
60
+ read the old value, and `ns._context = 9`, `ns._options = 9` or `ns.type = 9` replaced the scope's
61
+ own fields. The write is refused, in both case modes, for every form a member write takes and every
62
+ key the blocklist does not already refuse, for a subclass too, and for an `EvalScope` that is a
63
+ prior scope's `thisArg`, reached through `this`. It is refused after the right side has run and
64
+ after a write policy, `EvalContext.checkMemberWrite`, has been asked, so a policy that refuses first
65
+ still gives its own error. A namespaced scope's object, `ns.n`, is not a scope, and `ns.n.k = 7`
66
+ still writes into it; a logical assignment that writes nothing, `ns.k ||= 5` with `k` set, is not
67
+ refused ([A51](../../docs/backlog-retired.md#a51)).
68
+
69
+ ### Changed
70
+ - The README's `### Scopes` corrects two sentences. It said that a prior scope's `thisArg` changes
71
+ only the call's receiver; it now says so of a namespace, since through `this` a write can go to
72
+ `thisArg` ([A56](../../docs/backlog.md#a56)). And it said that `EvalContext.fromContext` copies a
73
+ plain object into a case-insensitive store; it now says that an object that is not an instance of
74
+ this realm's `Object`, one with a null prototype or one made in another realm, is not copied, and
75
+ is not yet read as the context in either mode ([A58](../../docs/backlog.md#a58)).
76
+ No behaviour changes. Documentation only: the README reaches the tarball.
77
+ - The README's `AssignmentExpression` entry states a limit as the contract: how many times an
78
+ expression calls a getter on the context or on a scope's object, or a lookup, is not part of it;
79
+ one can run where JavaScript reads nothing, or more than once for one read, and a registered read
80
+ hook can add a call. It said "two kinds of read remain beyond JavaScript's", with counts for each:
81
+ a getter on the context reached through `this` case-sensitively, `this.g = 1` once and
82
+ `this.g += 1` twice, and a lookup under `caseInsensitive`, `x = 1` once and `x += 1` twice. Of
83
+ those, the lookup's `x += 1` holds without a read hook only: with one, as `eval-signals`'
84
+ dependency tracking registers, it calls the lookup three times, and case-sensitively a plain `g`
85
+ calls a getter on the context twice, where JavaScript calls it once. A getter on a global
86
+ prior scope's object is called more than once for one read as well, `this.g` three times under
87
+ `caseInsensitive`. The entry keeps one example, `this.g = 1`, which holds with or without a hook.
88
+ `EvalContext`'s `lookups` JSDoc states the limit for a lookup and its `getThis` JSDoc for the
89
+ getter it reads, both in the published `.d.ts`. No behaviour changes
90
+ ([A49](../../docs/backlog-retired.md#a49)).
91
+
92
+ ### Fixed
93
+ - **Under `caseInsensitive`, `c.g` calls a getter on `c`'s prototype chain once.** The lookup tested
94
+ the key by reading it, then read it again: `c.g`, `c.g += 1`, `c.g++`, `c.g ||= 5` and
95
+ `` `${c.g}` `` called an inherited getter twice, and a proxy's `get` trap ran twice for a key no own
96
+ property matches. The key is now tested with `in`, as a member write tests it, and each of these
97
+ forms calls the getter once, and the trap runs once ([A48](../../docs/backlog-retired.md#a48)). The
98
+ read and the write now agree on the key: over an inherited `foo` whose value is `undefined`, behind
99
+ an accessor `Foo` on a nearer prototype, `p.foo` read `Foo`'s value and `p.foo += 1` wrote through
100
+ `Foo`'s setter, where `p.foo = 1` wrote `foo`; each now reads or writes `foo`.
101
+ - **A write through `this` to a `Registry` that is the context's original reaches its map, for a key
102
+ it holds.** Where the original holds `k`, `this.k = v`, `this.k += v`, `this.k ||= v` and `this.k++`
103
+ set an own property on the `Registry` instance and left its map, so a later `k` or `this.k` read the
104
+ old value: under `caseInsensitive` on the copy `EvalContext.fromContext` makes of a plain context,
105
+ and in both modes on a host's `Registry` passed as the context. The write now goes through the
106
+ `Registry`'s map, as `k = v` does, and a later read sees it
107
+ ([A50](../../docs/backlog-retired.md#a50)). Under `caseInsensitive` it stays in the copy, as an
108
+ identifier write does, and does not reach the caller's object. The same holds where the original is
109
+ a global prior scope's `thisArg` and that scope holds the key: `this.k = v` writes the original's
110
+ map, and a later `k` or `this.k` reads `v`, where up to 0.15.1 the instance took an own property and
111
+ they read the scope's value. A `Registry` reached as a value is written as any object is, as before:
112
+ `r.k = v`, and the context's own `Registry` when the host holds it in its data, `self.k = v`.
113
+
114
+ ---
115
+
116
+ ## [0.15.1] - 2026-11-02
117
+
118
+ **A patch that fixes [A33](../../docs/backlog-retired.md#a33)**, the case-insensitive lookup
119
+ cache's miss across a same-count key swap, and documents [A34](../../docs/backlog-retired.md#a34),
120
+ an options object remembered by identity. The `.d.ts` differs from 0.15.0's only in JSDoc.
121
+ `eval-signals` 0.8.0 and `eval-forms` 0.8.0 take it through their peer range; for `eval-signals` a
122
+ row witnesses it. A33's lower bound is not measured.
123
+
124
+ ### Changed
125
+ - `ParserService.parserOptions`' and `parse`'s JSDoc, a new JSDoc on `defaultParserOptions`, and
126
+ the README's colon-identifier section say that a value written into an options object is not
127
+ reliably seen: the parse cache and `CompilerService`'s remember options objects by identity, so a
128
+ later parse or compile may keep a text's reading from before the write, or cache one made after it
129
+ as if nothing had changed; replace the object instead ([A34](../../docs/backlog-retired.md#a34)). No
130
+ behaviour changes. Documentation only: the JSDoc reaches the `.d.ts` and the bundle, the README
131
+ the tarball.
132
+
133
+ ### Fixed
134
+ - **Under `caseInsensitive`, a property added in the same interval as another is deleted is
135
+ found by a case variant of its name.** The lookup cache kept an earlier miss while the object's
136
+ own-key count was unchanged: after `delete x.a; x.c = 3`, `x.C` read `undefined`, and `x.C = 9`
137
+ or `x.C += 1` made a second own key `C` beside `c`. The same miss skipped a refusal: a case
138
+ variant of a blocked own name that is not an own property of the object's immediate prototype —
139
+ `prototype` on a plain object, every blocked name but `constructor` on an instance of a class that
140
+ declares none of them, any on an object made by `Object.create(null)` or `Object.create({})` —
141
+ read `undefined` and wrote a sibling key, where it is refused when no miss was cached. The blocked
142
+ property's value was neither returned nor written. Both are now refused, and a cached miss stands
143
+ only while the object's own names are those it was made from
144
+ ([A33](../../docs/backlog-retired.md#a33)). The cache now keeps each object's own names for as long
145
+ as the object lives, for every object a `caseInsensitive` member access with a string key reaches:
146
+ about 8 to 9 bytes per own name, and about 32 per index name of an array of a million elements.
147
+
148
+ ---
149
+
17
150
  ## [0.15.0] - 2026-10-31
18
151
 
19
152
  **An `await` gives JavaScript's answer or throws.** A minor carrying breaking changes
@@ -178,8 +311,8 @@ their floors to it.
178
311
  them: `getObj()[k()] += f()` runs `getObj`, `k`, the read, `f`, then the write, where up to 0.13.3
179
312
  it evaluated the object, the key and the read a second time after `f`. A getter on the target is
180
313
  called once where it was called twice. Two are read twice where they were read four times: a
181
- prototype accessor under `caseInsensitive` ([A48](../../docs/backlog.md#a48)), and an accessor
182
- on the context reached through `this` ([A49](../../docs/backlog.md#a49)). The read events are those of that one read, `a`, then `a.b`, where each was reported
314
+ prototype accessor under `caseInsensitive` ([A48](../../docs/backlog-retired.md#a48)), and an accessor
315
+ on the context reached through `this` ([A49](../../docs/backlog-retired.md#a49)). The read events are those of that one read, `a`, then `a.b`, where each was reported
183
316
  twice; node hooks and the trace see the target's object and a computed key, and no longer the
184
317
  target node, and an identifier target not at all. The value read still passes the checks every
185
318
  read value passes, so a listed function as the target, `fetch += 1` or `obj.fetch ||= 1`, is
@@ -189,7 +322,7 @@ their floors to it.
189
322
  to 0.13.3 it read the target, and after `f` evaluated the object and the key and read the target a
190
323
  second time. A getter on the target is not called, except an accessor on the context reached
191
324
  through `this`, which is called once where it was called four times
192
- ([A49](../../docs/backlog.md#a49)); under `caseInsensitive` a lookup answering an identifier
325
+ ([A49](../../docs/backlog-retired.md#a49)); under `caseInsensitive` a lookup answering an identifier
193
326
  target's name is called once, where it was called twice (A49). A listed function as the target is overwritten
194
327
  as `obj.fetch++` overwrites one, so `fetch = 1` and `obj.fetch = 1` write `1` where they were
195
328
  refused; `fetch += 1` and `fetch ||= 1` read it, and are still refused. The read events are the
@@ -589,7 +722,7 @@ grammar's spec and corpus pass at 8.11.2 (the plan's § 8 q3). `eval-signals` 0.
589
722
  keys an AST, so a text compiled before `ParserService.parserOptions` was replaced through its
590
723
  setter — with `colonIdentifiers` turned on, for one — is compiled again rather than served the
591
724
  old function. A write in place into that object is not seen, as it is not for an AST
592
- ([A34](../../docs/backlog.md#a34)). Two narrower
725
+ ([A34](../../docs/backlog-retired.md#a34)). Two narrower
593
726
  changes: a subclass that sets `CompilerService`'s protected per-call options is served a function
594
727
  for its current ones, compiled on every call when they carry an acorn callback or `program`, and
595
728
  a value JSON cannot hold, set in `ParserService.parserOptions` under a key `defaultParserOptions`
@@ -607,7 +740,7 @@ grammar's spec and corpus pass at 8.11.2 (the plan's § 8 q3). `eval-signals` 0.
607
740
  carrying a callback or a `program` neither reads nor writes the cache, so the callback runs on
608
741
  every parse. A change made through the `parserOptions` setter is honoured for text already
609
742
  cached; a write in place into an options object, the service's or one passed again, is not
610
- ([A34](../../docs/backlog.md#a34)). Every published version to 0.11.1 is affected.
743
+ ([A34](../../docs/backlog-retired.md#a34)). Every published version to 0.11.1 is affected.
611
744
 
612
745
  ---
613
746
 
package/README.md CHANGED
@@ -175,7 +175,7 @@ expressions.length; // 2
175
175
 
176
176
  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.
177
177
 
178
- `thisArg` is the `this` a scope's methods are called with. A method called on the scope's own object, such as `cat.action(...)` below, receives `thisArg`; so does `this.fn()` when a global scope supplies `fn`. Without `thisArg`, `cat.action(...)` receives the scope's object. Only the call's receiver changes: `cat` still evaluates to the scope's object, so `cat.num` reads it and `cat.x = 1` writes to it. Up to 0.6.x `thisArg` was accepted and never applied.
178
+ `thisArg` is the `this` a scope's methods are called with. A method called on the scope's own object, such as `cat.action(...)` below, receives `thisArg`; so does `this.fn()` when a global scope supplies `fn`. Without `thisArg`, `cat.action(...)` receives the scope's object. Through a namespace, only the call's receiver changes: `cat` still evaluates to the scope's object, so `cat.num` reads it and `cat.x = 1` writes to it. Up to 0.6.x `thisArg` was accepted and never applied.
179
179
 
180
180
  ```javascript
181
181
  import { EvalContext, EvalScope, EvalScopeOptions,
@@ -207,7 +207,7 @@ const result = service.simpleEval('cat.action(args, cat.num, "times")', evalCont
207
207
  // 'Mister Whiskers says meow 3 times' - `this` is thisArg; cat.num still reads cat
208
208
  ```
209
209
 
210
- Note that an `EvalContext` may back any number of evaluations, and that `caseInsensitive` set on the context alone does not reach the walk — pass it in the evaluation options too. Even then, a plain object handed to `new EvalContext` matches no case variant: build the context with `EvalContext.fromContext(object, options)` instead, which copies the object into a case-insensitive store.
210
+ Note that an `EvalContext` may back any number of evaluations, and that `caseInsensitive` set on the context alone does not reach the walk — pass it in the evaluation options too. Even then, a plain object handed to `new EvalContext` matches no case variant: build the context with `EvalContext.fromContext(object, options)` instead, which copies the object into a case-insensitive store, unless it is not an instance of this realm's `Object` (an object with a null prototype, or one made in another realm): such an object is not copied, and `eval-core` does not yet read it as the context, in either mode.
211
211
 
212
212
  ### Colon-joined names — `provideColonIdentifiers`
213
213
 
@@ -215,7 +215,7 @@ Some expression languages name their values `Q1:1` or `VP14:0`. With `colonIdent
215
215
 
216
216
  `provideColonIdentifiers()` turns it on for an application: `ParserService` reads it when it is constructed, so every parse through `EvalService`, `CompilerService` and `DiscoveryService` follows it. Put it in the application's **root** providers. `ParserService` is provided in the root, so in a lazy route's providers, or any other child injector's, the provider would reach no parse; there it throws when that injector is created instead.
217
217
 
218
- A per-call `colonIdentifiers` in the options of `ParserService.parse`, or of the exported `parse`, overrides it — and the exported `parse` sees only the options it is given. Setting `ParserService.parserOptions` to a new object is the imperative alternative: every later parse or compile follows it, of a text seen before as of a new one, while a function already compiled keeps the reading it was compiled with.
218
+ A per-call `colonIdentifiers` in the options of `ParserService.parse`, or of the exported `parse`, overrides it — and the exported `parse` sees only the options it is given. Setting `ParserService.parserOptions` to a new object is the imperative alternative: every later parse or compile follows it, of a text seen before as of a new one, while a function already compiled keeps the reading it was compiled with. Writing into an options object instead — the one the getter returns, one passed to `parse` again, or the exported `defaultParserOptions`, which `EvalService` and `CompilerService` pass on every parse — is not reliably seen. The parse cache, and `CompilerService`'s, remember options objects by identity, not by their values, so a later parse or compile may keep a text's reading from before the write, or cache one made after it as if nothing had changed. Replace an options object; do not write into one.
219
219
 
220
220
  ```javascript
221
221
  import { EvalService, ParserService,
@@ -288,11 +288,11 @@ The project has been tested with the following node types:
288
288
  the target's value only for a compound or logical operator, then the right side, then the
289
289
  write. So `=` does not read its target, and `+=` or `||=` reads it once; up to 0.13.3 the
290
290
  target was read as an operand, and a member target was evaluated again after the right side.
291
- Three kinds of read remain beyond JavaScript's. Case-sensitive, a getter `g` on the context,
292
- reached through `this`: `this.g = 1` calls it once and `this.g += 1` twice. Under
293
- `caseInsensitive`, a lookup that answers an identifier target: `x = 1` calls it once and
294
- `x += 1` twice. And under `caseInsensitive`, a getter an instance inherits: `c.g += 1` calls it
295
- twice, as `c.g` does. Destructuring assignment, `[a, b] = arr` or `({ m } = o)`, throws
291
+ How many times an expression calls a getter on the context or on a scope's object, or a
292
+ lookup, is not part of the contract: one can run where JavaScript reads nothing, or more than
293
+ once for one read, and a registered read hook can add a call. Case-sensitively, with a getter
294
+ `g` on the context, `this.g = 1` calls it once, where JavaScript calls none. Destructuring
295
+ assignment, `[a, b] = arr` or `({ m } = o)`, throws
296
296
  `Unsupported assignment target`;
297
297
  before `@zvenigora/ng-eval-core` 0.7.0 it silently did nothing. An identifier write that
298
298
  would shadow `undefined`, or under `caseInsensitive` a literal, throws