@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/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`, `thisArg` and case sensitivity. Bare identifiers are read from the context itself; a namespaced scope is reached through its 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: cat
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
- // 'Miss Kitty says meow 3 times'
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
- - **Reading `hookErrors` requires the state-first style.** `simpleEval` builds its state internally and never hands it back, so there is nowhere to read them from. Use `createState` plus `eval`.
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
- await arrow().catch(() => undefined); // the body runs here
328
+ try { arrow(); } catch { /* the body runs here, and throws synchronously */ }
325
329
 
326
- // seen === [['MemberExpression', false]] - completed: false, but no error
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