@zvenigora/ng-eval-core 0.14.1 → 0.15.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,114 @@ Versions 0.1.104–0.1.107 are on npm without entries here.
14
14
 
15
15
  ---
16
16
 
17
+ ## [0.15.0] - 2026-10-31
18
+
19
+ **An `await` gives JavaScript's answer or throws.** A minor carrying breaking changes
20
+ ([A25](../../docs/backlog-retired.md#a25), [A24](../../docs/backlog-retired.md#a24); the
21
+ [A24 plan](../../docs/a24/plan.md)), with [A27](../../docs/backlog-retired.md#a27)'s and
22
+ [A38](../../docs/backlog-retired.md#a38)'s fixes and one export, `findUnsupportedStatement`
23
+ ([D13](../../docs/backlog-retired.md#d13), the first half). No exported symbol changes shape: the
24
+ `.d.ts` differs from 0.14.1's by that function and its `acorn` types, and otherwise in JSDoc only,
25
+ A27's. What changes is behaviour — an `await` passes its operand through, with no timer, and is
26
+ refused where its value is not the result; `state.result` describes the walk the entry point ran;
27
+ and a tag receives JavaScript's frozen template object. `eval-signals` 0.8.0 and `eval-forms` 0.8.0
28
+ raise their floors to it.
29
+
30
+ ### Breaking
31
+ - **An `await` gives its operand itself** ([A25](../../docs/backlog-retired.md#a25)). It gave a
32
+ new promise racing the operand, even for one that is not thenable. So on the sync path — `eval`,
33
+ `simpleEval`, `CompilerService`'s `call` and `simpleCall`, and the exported `evaluate` and `call` —
34
+ `(async () => await p)()` is `p`, and `(async () => await 1)()` is `1`, where it was a promise
35
+ resolving to `1`. `evalAsync` resolves a promise that reaches the result, as before.
36
+ - **An `await` is evaluated only where its value is the result** ([A24](../../docs/backlog-retired.md#a24)):
37
+ as the whole expression, as an arrow function's expression body, or as the last statement of a
38
+ program or of an arrow function's block body. Anywhere else it throws `Unsupported await position:
39
+ an await is evaluated only as the result of the expression - …` when the walk reaches it, on
40
+ every entry point, and fires no hook. Up to 0.14.1 every `await` handed the walk a promise as its
41
+ value. As an operand that gave a wrong answer: `(async () => (await p) * 10)()` was `NaN`,
42
+ `(async () => (await u).name)()` was `undefined`, and `(async () => (await 1) + 1)()` was
43
+ `"[object Promise]1"`. Elsewhere `evalAsync` resolved the promise once it reached the result, so
44
+ these forms resolved, and are refused too, since in none of them is the `await`'s value the
45
+ result: `(async () => [await p])()`, `(async () => f(await p))()`,
46
+ `(async () => c ? await p : 0)()`, `(async () => await await p)()`, `await p; 1` and
47
+ `(async () => { let x = await p; x })()`. An accepted `await` keeps its hook and trace events.
48
+ `async` stays ignored: an `async` arrow returns no promise of its own. No exported shape or
49
+ `.d.ts` change.
50
+ - **No `await` is bounded in time.** Up to 0.14.1 each `await` raced its operand against a 30-second
51
+ timer that rejected with `Await expression timed out after <ms>ms`, and a `__awaitTimeout` number
52
+ on the context set the delay. Both are gone: nothing arms a timer and nothing reads the key. A host
53
+ that wants a bound wraps its own promise.
54
+
55
+ ### Added
56
+ - **`findUnsupportedStatement(node)`**, which reports the first statement in a tree that evaluation
57
+ would refuse, in source order, as `{ statement, message }`, where `message` is what evaluation
58
+ throws for it, or `undefined` when there is none (D13, the first half). Evaluation
59
+ refuses a statement only when the walk reaches it, so one in an arrow function's body never
60
+ called, or in a branch not taken, throws nothing; this reads the whole tree, function bodies and
61
+ untaken branches included. It and the evaluator read one table of the statement types and
62
+ declaration kinds evaluation supports, so the two cannot disagree, and each refusal's message is
63
+ unchanged. The `.d.ts` gains the function.
64
+
65
+ ### Fixed
66
+ - **An `await` arms no timer and leaves the caller's error as it was raised**
67
+ ([A25](../../docs/backlog-retired.md#a25)). Each evaluation of an `await` armed a `setTimeout`
68
+ of 30 000 ms and never cleared it, so under Angular's zone an application waiting for stability,
69
+ server rendering included, waited out 30 s per `await` evaluated. The delay was read from
70
+ `__awaitTimeout` on the context's `original`, documented nowhere, and missed under
71
+ `caseInsensitive`. A rejection that is an `Error` reaches the caller by identity with its message
72
+ unchanged, where ` at position <start>-<end>` was appended to it once per evaluation that saw it.
73
+ One that is not an `Error` is converted by `evalAsync` as it is with no `await`: `'x'` rejects
74
+ with an `Error` `"x"`, where the `await` made it `Await expression failed: x at position 0-17`.
75
+ 0.7.0's line on the position, below, stays as history. No exported shape or `.d.ts` change.
76
+ - **A hook firing during an `evalAsync` failure's cleanup reads `duration` as `undefined`**, as one
77
+ under `eval` has since A27: the walk has not ended. `evalAsync` stopped the clock before closing
78
+ the nodes the failure left open, so such a hook read a number.
79
+ - **`state.result` describes the walk the entry point ran, and nothing else**
80
+ ([A27](../../docs/backlog-retired.md#a27)). An arrow function's body runs a nested walk on the
81
+ same state, and up to 0.14.1 that walk recorded its own outcome over the enclosing one's: every
82
+ call of an arrow wrote `value`, `error`, the flags and the start time, mid-walk, and a closure
83
+ called after the walk wrote over the finished walk's result. The nested walk now records
84
+ nothing. So under `evalAsync`, `load(safe(() => fail()))`, where `safe` catches what its
85
+ argument throws, no longer reads `isError` `true` and `error` the caught throw at return, nor
86
+ `error` the caught throw once it has resolved to `0`; `safe(() => fail())` under `eval` reads no
87
+ `error`; `call(() => 1) + boom()` reads no `value` `1` after it throws; `duration` covers the
88
+ whole walk, where it ran from the last arrow call; and `fn = eval('x => x + 1', state)` leaves
89
+ `state.result.value` `fn` when `fn(41)` is called later, where it became `42`.
90
+ - **`EvalResult.start()` resets the outcome**: `value`, `error`, `errorMessage`, `isSuccess`,
91
+ `isError`, `isUndefined` and `duration` read `undefined` until the walk ends. It reset nothing,
92
+ so on a state reused across runs an `evalAsync` after a rejected run read `isError` `true` and the
93
+ rejected run's error at return, and kept that error after resolving; and `duration` read the
94
+ previous run's end less the new start, a negative number, while a walk was pending. The trace,
95
+ `tracePushCount` and `traceTruncated` are left alone, as before
96
+ ([A15](../../docs/backlog.md#a15)).
97
+ - **`setSuccess` and `setFailure` each write every outcome field.** `setSuccess` clears `error` and
98
+ `errorMessage`, and `setFailure` clears `value`, and its `errorMessage` is `undefined` for a
99
+ thrown value that is not an `Error`, where it kept the previous one. **`isUndefined` is
100
+ `value === undefined`**: it was `false` after every walk, so `eval('undefined')` now reads
101
+ `true`, and a failed walk, whose `value` is cleared, reads `true` as well.
102
+
103
+ No exported shape changes. The `.d.ts` differs in JSDoc only: `EvalResult`'s, which says what
104
+ the outcome describes; `evaluate`'s; and, where they said an arrow's body re-enters `evaluate`,
105
+ `EvalState.walkDepth`'s, `EvalHookBookkeeping.walkBases`', `EvalHooks`' `exit`, `depth`,
106
+ `pushWalkBase`, `popWalkBase` and `unwindTo`, and `EvalOptions`' `maxIterations` and
107
+ `maxTraceItems`, which now say a walk where they said `evaluate`. Neither downstream
108
+ package reads `state.result`'s outcome.
109
+ - **A tag receives JavaScript's template object** ([A38](../../docs/backlog-retired.md#a38)). It
110
+ was a plain array of the cooked strings, built again on every evaluation, with no `raw`. It is
111
+ now frozen, with a frozen, non-enumerable `raw` of the uncooked strings, and one object per
112
+ parsed template - the same each time a parsed or compiled expression runs, over any context;
113
+ two evaluations of one string share it only while the parse cache returns the same AST. So
114
+ `` String.raw`a\nb` `` gives `"a\\nb"` where it threw `TypeError: Cannot convert undefined or
115
+ null to object`, and `` let g = () => f`x`; g() === g() `` is `true`, while two templates with
116
+ the same text in one expression stay two objects. An invalid escape's cooked string is
117
+ `undefined`, where it was `null`. A tag that writes into the array now fails, as in strict-mode
118
+ JavaScript: `` (s => s.y = 1)`a` `` throws the engine's message wrapped with the key - in V8,
119
+ `Failed to set property "y": Cannot add property y, object is not extensible` - where it gave
120
+ `1`. The object is not recorded as created by the walk, as before, so a write policy is asked
121
+ about it with `createdByEvaluation` `false`. No exported shape or `.d.ts` change.
122
+
123
+ ---
124
+
17
125
  ## [0.14.1] - 2026-10-30
18
126
 
19
127
  **A patch that fixes [A47](../../docs/backlog-retired.md#a47)**, an arrow's parameter scope under
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
 
@@ -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`.