@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 +138 -5
- package/README.md +8 -8
- package/fesm2022/zvenigora-ng-eval-core.mjs +161 -56
- package/fesm2022/zvenigora-ng-eval-core.mjs.map +1 -1
- package/package.json +1 -1
- package/types/zvenigora-ng-eval-core.d.ts +41 -5
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.
|
|
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
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
`
|
|
295
|
-
|
|
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
|