@zvenigora/ng-eval-core 0.14.1 → 0.15.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 CHANGED
@@ -14,6 +14,148 @@ Versions 0.1.104–0.1.107 are on npm without entries here.
14
14
 
15
15
  ---
16
16
 
17
+ ## [0.15.1] - 2026-11-02
18
+
19
+ **A patch that fixes [A33](../../docs/backlog-retired.md#a33)**, the case-insensitive lookup
20
+ cache's miss across a same-count key swap, and documents [A34](../../docs/backlog-retired.md#a34),
21
+ an options object remembered by identity. The `.d.ts` differs from 0.15.0's only in JSDoc.
22
+ `eval-signals` 0.8.0 and `eval-forms` 0.8.0 take it through their peer range; for `eval-signals` a
23
+ row witnesses it. A33's lower bound is not measured.
24
+
25
+ ### Changed
26
+ - `ParserService.parserOptions`' and `parse`'s JSDoc, a new JSDoc on `defaultParserOptions`, and
27
+ the README's colon-identifier section say that a value written into an options object is not
28
+ reliably seen: the parse cache and `CompilerService`'s remember options objects by identity, so a
29
+ later parse or compile may keep a text's reading from before the write, or cache one made after it
30
+ as if nothing had changed; replace the object instead ([A34](../../docs/backlog-retired.md#a34)). No
31
+ behaviour changes. Documentation only: the JSDoc reaches the `.d.ts` and the bundle, the README
32
+ the tarball.
33
+
34
+ ### Fixed
35
+ - **Under `caseInsensitive`, a property added in the same interval as another is deleted is
36
+ found by a case variant of its name.** The lookup cache kept an earlier miss while the object's
37
+ own-key count was unchanged: after `delete x.a; x.c = 3`, `x.C` read `undefined`, and `x.C = 9`
38
+ or `x.C += 1` made a second own key `C` beside `c`. The same miss skipped a refusal: a case
39
+ variant of a blocked own name that is not an own property of the object's immediate prototype —
40
+ `prototype` on a plain object, every blocked name but `constructor` on an instance of a class that
41
+ declares none of them, any on an object made by `Object.create(null)` or `Object.create({})` —
42
+ read `undefined` and wrote a sibling key, where it is refused when no miss was cached. The blocked
43
+ property's value was neither returned nor written. Both are now refused, and a cached miss stands
44
+ only while the object's own names are those it was made from
45
+ ([A33](../../docs/backlog-retired.md#a33)). The cache now keeps each object's own names for as long
46
+ as the object lives, for every object a `caseInsensitive` member access with a string key reaches:
47
+ about 8 to 9 bytes per own name, and about 32 per index name of an array of a million elements.
48
+
49
+ ---
50
+
51
+ ## [0.15.0] - 2026-10-31
52
+
53
+ **An `await` gives JavaScript's answer or throws.** A minor carrying breaking changes
54
+ ([A25](../../docs/backlog-retired.md#a25), [A24](../../docs/backlog-retired.md#a24); the
55
+ [A24 plan](../../docs/a24/plan.md)), with [A27](../../docs/backlog-retired.md#a27)'s and
56
+ [A38](../../docs/backlog-retired.md#a38)'s fixes and one export, `findUnsupportedStatement`
57
+ ([D13](../../docs/backlog-retired.md#d13), the first half). No exported symbol changes shape: the
58
+ `.d.ts` differs from 0.14.1's by that function and its `acorn` types, and otherwise in JSDoc only,
59
+ A27's. What changes is behaviour — an `await` passes its operand through, with no timer, and is
60
+ refused where its value is not the result; `state.result` describes the walk the entry point ran;
61
+ and a tag receives JavaScript's frozen template object. `eval-signals` 0.8.0 and `eval-forms` 0.8.0
62
+ raise their floors to it.
63
+
64
+ ### Breaking
65
+ - **An `await` gives its operand itself** ([A25](../../docs/backlog-retired.md#a25)). It gave a
66
+ new promise racing the operand, even for one that is not thenable. So on the sync path — `eval`,
67
+ `simpleEval`, `CompilerService`'s `call` and `simpleCall`, and the exported `evaluate` and `call` —
68
+ `(async () => await p)()` is `p`, and `(async () => await 1)()` is `1`, where it was a promise
69
+ resolving to `1`. `evalAsync` resolves a promise that reaches the result, as before.
70
+ - **An `await` is evaluated only where its value is the result** ([A24](../../docs/backlog-retired.md#a24)):
71
+ as the whole expression, as an arrow function's expression body, or as the last statement of a
72
+ program or of an arrow function's block body. Anywhere else it throws `Unsupported await position:
73
+ an await is evaluated only as the result of the expression - …` when the walk reaches it, on
74
+ every entry point, and fires no hook. Up to 0.14.1 every `await` handed the walk a promise as its
75
+ value. As an operand that gave a wrong answer: `(async () => (await p) * 10)()` was `NaN`,
76
+ `(async () => (await u).name)()` was `undefined`, and `(async () => (await 1) + 1)()` was
77
+ `"[object Promise]1"`. Elsewhere `evalAsync` resolved the promise once it reached the result, so
78
+ these forms resolved, and are refused too, since in none of them is the `await`'s value the
79
+ result: `(async () => [await p])()`, `(async () => f(await p))()`,
80
+ `(async () => c ? await p : 0)()`, `(async () => await await p)()`, `await p; 1` and
81
+ `(async () => { let x = await p; x })()`. An accepted `await` keeps its hook and trace events.
82
+ `async` stays ignored: an `async` arrow returns no promise of its own. No exported shape or
83
+ `.d.ts` change.
84
+ - **No `await` is bounded in time.** Up to 0.14.1 each `await` raced its operand against a 30-second
85
+ timer that rejected with `Await expression timed out after <ms>ms`, and a `__awaitTimeout` number
86
+ on the context set the delay. Both are gone: nothing arms a timer and nothing reads the key. A host
87
+ that wants a bound wraps its own promise.
88
+
89
+ ### Added
90
+ - **`findUnsupportedStatement(node)`**, which reports the first statement in a tree that evaluation
91
+ would refuse, in source order, as `{ statement, message }`, where `message` is what evaluation
92
+ throws for it, or `undefined` when there is none (D13, the first half). Evaluation
93
+ refuses a statement only when the walk reaches it, so one in an arrow function's body never
94
+ called, or in a branch not taken, throws nothing; this reads the whole tree, function bodies and
95
+ untaken branches included. It and the evaluator read one table of the statement types and
96
+ declaration kinds evaluation supports, so the two cannot disagree, and each refusal's message is
97
+ unchanged. The `.d.ts` gains the function.
98
+
99
+ ### Fixed
100
+ - **An `await` arms no timer and leaves the caller's error as it was raised**
101
+ ([A25](../../docs/backlog-retired.md#a25)). Each evaluation of an `await` armed a `setTimeout`
102
+ of 30 000 ms and never cleared it, so under Angular's zone an application waiting for stability,
103
+ server rendering included, waited out 30 s per `await` evaluated. The delay was read from
104
+ `__awaitTimeout` on the context's `original`, documented nowhere, and missed under
105
+ `caseInsensitive`. A rejection that is an `Error` reaches the caller by identity with its message
106
+ unchanged, where ` at position <start>-<end>` was appended to it once per evaluation that saw it.
107
+ One that is not an `Error` is converted by `evalAsync` as it is with no `await`: `'x'` rejects
108
+ with an `Error` `"x"`, where the `await` made it `Await expression failed: x at position 0-17`.
109
+ 0.7.0's line on the position, below, stays as history. No exported shape or `.d.ts` change.
110
+ - **A hook firing during an `evalAsync` failure's cleanup reads `duration` as `undefined`**, as one
111
+ under `eval` has since A27: the walk has not ended. `evalAsync` stopped the clock before closing
112
+ the nodes the failure left open, so such a hook read a number.
113
+ - **`state.result` describes the walk the entry point ran, and nothing else**
114
+ ([A27](../../docs/backlog-retired.md#a27)). An arrow function's body runs a nested walk on the
115
+ same state, and up to 0.14.1 that walk recorded its own outcome over the enclosing one's: every
116
+ call of an arrow wrote `value`, `error`, the flags and the start time, mid-walk, and a closure
117
+ called after the walk wrote over the finished walk's result. The nested walk now records
118
+ nothing. So under `evalAsync`, `load(safe(() => fail()))`, where `safe` catches what its
119
+ argument throws, no longer reads `isError` `true` and `error` the caught throw at return, nor
120
+ `error` the caught throw once it has resolved to `0`; `safe(() => fail())` under `eval` reads no
121
+ `error`; `call(() => 1) + boom()` reads no `value` `1` after it throws; `duration` covers the
122
+ whole walk, where it ran from the last arrow call; and `fn = eval('x => x + 1', state)` leaves
123
+ `state.result.value` `fn` when `fn(41)` is called later, where it became `42`.
124
+ - **`EvalResult.start()` resets the outcome**: `value`, `error`, `errorMessage`, `isSuccess`,
125
+ `isError`, `isUndefined` and `duration` read `undefined` until the walk ends. It reset nothing,
126
+ so on a state reused across runs an `evalAsync` after a rejected run read `isError` `true` and the
127
+ rejected run's error at return, and kept that error after resolving; and `duration` read the
128
+ previous run's end less the new start, a negative number, while a walk was pending. The trace,
129
+ `tracePushCount` and `traceTruncated` are left alone, as before
130
+ ([A15](../../docs/backlog.md#a15)).
131
+ - **`setSuccess` and `setFailure` each write every outcome field.** `setSuccess` clears `error` and
132
+ `errorMessage`, and `setFailure` clears `value`, and its `errorMessage` is `undefined` for a
133
+ thrown value that is not an `Error`, where it kept the previous one. **`isUndefined` is
134
+ `value === undefined`**: it was `false` after every walk, so `eval('undefined')` now reads
135
+ `true`, and a failed walk, whose `value` is cleared, reads `true` as well.
136
+
137
+ No exported shape changes. The `.d.ts` differs in JSDoc only: `EvalResult`'s, which says what
138
+ the outcome describes; `evaluate`'s; and, where they said an arrow's body re-enters `evaluate`,
139
+ `EvalState.walkDepth`'s, `EvalHookBookkeeping.walkBases`', `EvalHooks`' `exit`, `depth`,
140
+ `pushWalkBase`, `popWalkBase` and `unwindTo`, and `EvalOptions`' `maxIterations` and
141
+ `maxTraceItems`, which now say a walk where they said `evaluate`. Neither downstream
142
+ package reads `state.result`'s outcome.
143
+ - **A tag receives JavaScript's template object** ([A38](../../docs/backlog-retired.md#a38)). It
144
+ was a plain array of the cooked strings, built again on every evaluation, with no `raw`. It is
145
+ now frozen, with a frozen, non-enumerable `raw` of the uncooked strings, and one object per
146
+ parsed template - the same each time a parsed or compiled expression runs, over any context;
147
+ two evaluations of one string share it only while the parse cache returns the same AST. So
148
+ `` String.raw`a\nb` `` gives `"a\\nb"` where it threw `TypeError: Cannot convert undefined or
149
+ null to object`, and `` let g = () => f`x`; g() === g() `` is `true`, while two templates with
150
+ the same text in one expression stay two objects. An invalid escape's cooked string is
151
+ `undefined`, where it was `null`. A tag that writes into the array now fails, as in strict-mode
152
+ JavaScript: `` (s => s.y = 1)`a` `` throws the engine's message wrapped with the key - in V8,
153
+ `Failed to set property "y": Cannot add property y, object is not extensible` - where it gave
154
+ `1`. The object is not recorded as created by the walk, as before, so a write policy is asked
155
+ about it with `createdByEvaluation` `false`. No exported shape or `.d.ts` change.
156
+
157
+ ---
158
+
17
159
  ## [0.14.1] - 2026-10-30
18
160
 
19
161
  **A patch that fixes [A47](../../docs/backlog-retired.md#a47)**, an arrow's parameter scope under
@@ -481,7 +623,7 @@ grammar's spec and corpus pass at 8.11.2 (the plan's § 8 q3). `eval-signals` 0.
481
623
  keys an AST, so a text compiled before `ParserService.parserOptions` was replaced through its
482
624
  setter — with `colonIdentifiers` turned on, for one — is compiled again rather than served the
483
625
  old function. A write in place into that object is not seen, as it is not for an AST
484
- ([A34](../../docs/backlog.md#a34)). Two narrower
626
+ ([A34](../../docs/backlog-retired.md#a34)). Two narrower
485
627
  changes: a subclass that sets `CompilerService`'s protected per-call options is served a function
486
628
  for its current ones, compiled on every call when they carry an acorn callback or `program`, and
487
629
  a value JSON cannot hold, set in `ParserService.parserOptions` under a key `defaultParserOptions`
@@ -499,7 +641,7 @@ grammar's spec and corpus pass at 8.11.2 (the plan's § 8 q3). `eval-signals` 0.
499
641
  carrying a callback or a `program` neither reads nor writes the cache, so the callback runs on
500
642
  every parse. A change made through the `parserOptions` setter is honoured for text already
501
643
  cached; a write in place into an options object, the service's or one passed again, is not
502
- ([A34](../../docs/backlog.md#a34)). Every published version to 0.11.1 is affected.
644
+ ([A34](../../docs/backlog-retired.md#a34)). Every published version to 0.11.1 is affected.
503
645
 
504
646
  ---
505
647
 
package/README.md CHANGED
@@ -116,6 +116,8 @@ const value = service.simpleCall(fn, context, options); // 3
116
116
 
117
117
  Asynchronous evaluation is limited, and based on promises. The walk itself is synchronous, and a promise is awaited once it has finished, wherever it sits in the result: the result itself, or an element or property of an array or object the expression builds.
118
118
 
119
+ **An `await` is evaluated only where its value is the result**, since 0.15.0. The walk does not suspend at it: the operand passes through unchanged, and `evalAsync` resolves a promise that reaches the result. So an `await` is accepted in three places: as the whole expression, `await p`; as an arrow function's expression body, `(async () => await p)()`; or as the last statement of a program or of an arrow function's block body, `1; await p` or `(async () => { 1; await p })()`. A top-level `await` parses only with `allowAwaitOutsideFunction`, which the services' parser options leave off. Anywhere else, as an operand, an element, an argument, an initializer, a branch, a statement that is not the last, or the operand of another `await`, it throws `Unsupported await position: an await is evaluated only as the result of the expression - …` when the walk reaches it, and fires no hook. Up to 0.14.1 an `await` there handed the walk a promise as its value: as an operand that gave a wrong answer, `(async () => (await p) * 10)()` was `NaN` where JavaScript gives 20, and elsewhere `evalAsync` resolved the promise once it reached the result, so `(async () => f(await p))()` gave 2. On the sync path an accepted `await` gives the operand itself, so `eval` returns `p` for `(async () => await p)()`. `async` is ignored: an `async` arrow is a plain function and returns no promise of its own.
120
+
119
121
  ```javascript
120
122
  import { EvalService } from '@zvenigora/ng-eval-core';
121
123
 
@@ -213,7 +215,7 @@ Some expression languages name their values `Q1:1` or `VP14:0`. With `colonIdent
213
215
 
214
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.
215
217
 
216
- 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.
217
219
 
218
220
  ```javascript
219
221
  import { EvalService, ParserService,
@@ -261,7 +263,14 @@ The project has been tested with the following node types:
261
263
  - `Identifier`
262
264
  - `Literal`
263
265
  - `CallExpression` *potentially unsafe*
264
- - `AwaitExpression`
266
+ - `AwaitExpression` — only where its value is the result: the whole expression, an arrow
267
+ function's expression body, or the last statement of a program or of an arrow function's
268
+ block body. Anywhere else it throws `Unsupported await position`, since 0.15.0. Up to 0.14.1
269
+ it handed the walk a promise there: as an operand that gave a wrong answer, and elsewhere, as
270
+ an element, an argument or an initializer among others, `evalAsync` resolved the promise once
271
+ it reached the result. Its operand passes through unchanged, and
272
+ `evalAsync` resolves a promise that reaches the result
273
+ ([Async evaluation and compilation](#async-evaluation-and-compilation))
265
274
  - `ConditionalExpression`
266
275
  - `MemberExpression`
267
276
  - `ArrayExpression`
@@ -292,7 +301,9 @@ The project has been tested with the following node types:
292
301
  `caseInsensitive` a member update writes the key its read matched, since 0.14.0: `OBJ.X++`
293
302
  on `{ obj: { x: 1 } }` writes `x`
294
303
  - `ArrowFunctionExpression` *potentially unsafe* (AssignmentPattern is not implemented, so a
295
- destructuring default — `({ a = 1 }) => a` — is rejected rather than defaulted)
304
+ destructuring default — `({ a = 1 }) => a` — is rejected rather than defaulted). `async` is
305
+ ignored: the arrow is a plain function and returns no promise of its own, so
306
+ `(async () => 1)()` is `1`
296
307
  - `SequenceExpression` — each expression in order, the value the last one's
297
308
 
298
309
  Object and array destructuring bind the names JavaScript binds, in parameter lists and in
@@ -320,12 +331,14 @@ whatever it pushed on the value stack — so `throw 1` evaluated to `1` and thre
320
331
 
321
332
  `WhileStatement`, `DoWhileStatement`, `ForInStatement`, `ForOfStatement`, `SwitchStatement`,
322
333
  `TryStatement`, `ThrowStatement`, `LabeledStatement`, `BreakStatement`, `ContinueStatement`,
323
- `FunctionDeclaration` and `ClassDeclaration` are among the rejected types. The three that
324
- imply **abrupt completion** and are reachable — `break`, `continue`, `throw` — are out by
334
+ `FunctionDeclaration` and `ClassDeclaration` are among the rejected types. The four that
335
+ imply **abrupt completion** — `break`, `continue`, `throw` and `return` — are out by
325
336
  design rather than by schedule: the evaluator has no completion record to carry them, and
326
- adding one is a redesign of the walker rather than another visitor. `return` never reaches
327
- the evaluator at all: an expression is parsed outside any function, so `return 1` is a parse
328
- error (`'return' outside of function`) both before and after 0.4.0.
337
+ adding one is a redesign of the walker rather than another visitor. An expression is parsed
338
+ outside any function, so a `return` at its top level is a parse error
339
+ (`'return' outside of function`) both before and after 0.4.0; in an arrow function's block
340
+ body it parses, and is rejected as the other three are: `(() => { return 1 })()` throws
341
+ `Unsupported statement type: ReturnStatement`.
329
342
 
330
343
  ### How statements differ from JavaScript
331
344
 
@@ -356,6 +369,29 @@ Seven deliberate divergences, each a documented rule rather than an accident:
356
369
  `Function call error: Access to dangerous property "toString" is blocked…`; since 0.7.0
357
370
  it arrives as thrown, without the prefix.
358
371
 
372
+ **A refused statement throws only when the walk reaches it**, so one in an arrow function's body
373
+ that is never called, or in a branch not taken, throws nothing. To refuse an expression before it
374
+ runs, `findUnsupportedStatement(ast)`, since 0.15.0, reads the whole tree, function bodies and
375
+ untaken branches included, against the table evaluation uses. It returns
376
+ `{ statement, message }` for the first statement in source order that evaluation would refuse,
377
+ where `message` is what evaluation throws for it, or `undefined` when there is none. Pass it the
378
+ `Program` that `parse` returns with `extractExpressions` off, as the services parse.
379
+
380
+ ```javascript
381
+ import { EvalService, findUnsupportedStatement, parse } from '@zvenigora/ng-eval-core';
382
+
383
+ const service = inject(EvalService);
384
+
385
+ const text = 'let f = () => { while (true) {} }; 1';
386
+ service.simpleEval(text); // 1 - the body is never called
387
+
388
+ const found = findUnsupportedStatement(parse(text, { ecmaVersion: 2020 }));
389
+ found.statement.type; // 'WhileStatement'
390
+ found.message; // 'Unsupported statement type: WhileStatement'
391
+
392
+ findUnsupportedStatement(parse('let x = 1; x', { ecmaVersion: 2020 })); // undefined
393
+ ```
394
+
359
395
  ## Options
360
396
 
361
397
  To change the evaluator's default behaviour, pass `options`: the last argument of `simpleEval`, `simpleCall` and `createState`.