@zvenigora/ng-eval-core 0.6.0 → 0.7.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 +594 -0
- package/LICENSE +21 -0
- package/README.md +14 -7
- package/fesm2022/zvenigora-ng-eval-core.mjs +271 -314
- package/fesm2022/zvenigora-ng-eval-core.mjs.map +1 -1
- package/package.json +2 -2
- package/types/zvenigora-ng-eval-core.d.ts +30 -11
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
|
|
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
|
+
`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.
|
|
46
48
|
|
|
47
49
|
```javascript
|
|
48
50
|
import { EvalContext, EvalScope, EvalScopeOptions,
|
|
@@ -66,12 +68,12 @@ const catOptions: EvalScopeOptions = {
|
|
|
66
68
|
global: false,
|
|
67
69
|
caseInsensitive: false,
|
|
68
70
|
namespace: 'cat',
|
|
69
|
-
thisArg:
|
|
71
|
+
thisArg: { name: 'Mister Whiskers' }
|
|
70
72
|
};
|
|
71
73
|
evalContext.priorScopes.push(EvalScope.fromObject(cat, catOptions));
|
|
72
74
|
|
|
73
75
|
const result = service.simpleEval('cat.action(args, cat.num, "times")', evalContext);
|
|
74
|
-
// '
|
|
76
|
+
// 'Mister Whiskers says meow 3 times' - `this` is thisArg; cat.num still reads cat
|
|
75
77
|
```
|
|
76
78
|
|
|
77
79
|
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.
|
|
@@ -263,7 +265,7 @@ state.hookErrors; // [{ phase, nodeType, error }, ...]
|
|
|
263
265
|
|
|
264
266
|
Two things to know about it:
|
|
265
267
|
|
|
266
|
-
- **
|
|
268
|
+
- **Options-first calls cannot read collected hook errors, by design.** `simpleEval(expr, context, { hooks })` builds its state internally and never hands it back, so errors collected on it are out of reach. To read them, use the state-first style — `createState`, then `eval` — and read `state.hookErrors`. Or have a faulty hook fail the evaluation instead, with `onHookError: 'throw'` set on the `EvalHooks` you pass (see the next point).
|
|
267
269
|
- **Passing both `hooks` and `onHookError` silently ignores `onHookError`.** A registry you pass through `options.hooks` is yours, and it keeps the policy it was constructed with; options never reconfigure an adopted registry. Pass the policy where the registry is built instead:
|
|
268
270
|
|
|
269
271
|
```javascript
|
|
@@ -304,7 +306,9 @@ try { service.eval('1 + boom()', state); } catch { /* rethrown */ }
|
|
|
304
306
|
// innermost first, each carrying the error that aborted the walk
|
|
305
307
|
```
|
|
306
308
|
|
|
307
|
-
**2. An enclosing visitor moved on without its child.** The node is flushed when the enclosing one closes, and there is **no** `error` — nothing was reported as thrown, and the evaluation may still produce a value
|
|
309
|
+
**2. An enclosing visitor moved on without its child.** The node is flushed when the enclosing one closes, and there is **no** `error` — nothing was reported as thrown, and the evaluation may still produce a value.
|
|
310
|
+
|
|
311
|
+
Up to 0.6.x an `await` whose operand threw synchronously did this: it turned the throw into a rejected promise and closed without its operand. Since 0.7.0 no built-in visitor does — the throw propagates, so the same expression is now the first kind:
|
|
308
312
|
|
|
309
313
|
```javascript
|
|
310
314
|
import { CompilerService, EvalService } from '@zvenigora/ng-eval-core';
|
|
@@ -321,11 +325,14 @@ state.hooks.on('after', '*', (e) => {
|
|
|
321
325
|
|
|
322
326
|
const fn = compiler.compile('async () => await obj.__proto__');
|
|
323
327
|
const arrow = compiler.call(fn, state); // returns the closure; seen === []
|
|
324
|
-
|
|
328
|
+
try { arrow(); } catch { /* the body runs here, and throws synchronously */ }
|
|
325
329
|
|
|
326
|
-
// seen === [['MemberExpression',
|
|
330
|
+
// seen === [['MemberExpression', true], ['AwaitExpression', true]]
|
|
331
|
+
// up to 0.6.x: [['MemberExpression', false]] - completed: false, but no error
|
|
327
332
|
```
|
|
328
333
|
|
|
334
|
+
The second kind stays in the hook contract.
|
|
335
|
+
|
|
329
336
|
So: test for the `error` property, not for `completed === false`.
|
|
330
337
|
|
|
331
338
|
#### Cost
|