@zvenigora/ng-eval-core 0.13.1 → 0.13.2

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,48 @@ Versions 0.1.104–0.1.107 are on npm without entries here.
14
14
 
15
15
  ---
16
16
 
17
+ ## [0.13.2] - 2026-10-22
18
+
19
+ ### Changed
20
+ - **The README states a limit of `caseInsensitive` on a context built with `new EvalContext`**: a
21
+ plain object handed to the constructor matches no case variant, even with the option passed to
22
+ the walk too, and `EvalContext.fromContext` is the way to build one that does. No code change
23
+ ([A44](../../docs/backlog.md#a44), where it was measured).
24
+
25
+ ### Fixed
26
+ - **An update converts its operand to a number once, as JavaScript does**, and uses that one
27
+ conversion for the value it writes and for its result. `x++` on `"5"` gives `5` and writes `6`,
28
+ where it gave `"5"` and wrote `"51"`; an object that does not convert to a number, or a
29
+ non-numeric string, gives `NaN` and writes `NaN`, where `++` concatenated and a postfix update
30
+ gave the operand as read; and an update of a BigInt updates it, where it threw. An operand that
31
+ cannot convert, a Symbol or a throwing `valueOf`, throws before anything is written
32
+ ([A41](../../docs/backlog-retired.md#a41)).
33
+ - **A postfix update of a listed function no longer throws after writing**: `tools.eval++` gives
34
+ `NaN` and writes `NaN`, as JavaScript does, where the write landed and the funnel then refused the
35
+ old value. The result is a number, so the funnel has nothing to refuse
36
+ ([A40](../../docs/backlog-retired.md#a40)).
37
+ - **Under `caseInsensitive`, an identifier assignment or update to a name the context resolves to
38
+ nothing writes that name**, where it wrote the key `undefined`: the string `"undefined"` on a
39
+ plain object, the value `undefined` in a `Registry`. That covers a name absent from the context
40
+ and one bound to `undefined`, as `x = 1` on `{ x: undefined }`. A context that refuses writes, as
41
+ `eval-signals`' signal context does, is now asked about the name as written, so its refusal names
42
+ it ([A43](../../docs/backlog-retired.md#a43)). The name `undefined` itself, and under
43
+ `caseInsensitive` a spelling of a literal, is refused instead: see the next entry.
44
+ - **A write that would rebind `undefined` on the context throws
45
+ `Assignment to read-only name "<name>".`**, as do, under `caseInsensitive`, a write to any
46
+ spelling of `undefined`, `null`, `true` or `false`, such as `TRUE = 0` or `Undefined++`. Up to
47
+ 0.13.1, `undefined = 1` landed on the context, and every later evaluation on it read the written
48
+ value; under `caseInsensitive` these writes went to the stray key the entry above describes. A
49
+ case variant of `undefined` is refused under a case-sensitive walk too, when the context's store
50
+ compares keys case-insensitively, as one built with `caseInsensitive` on the context alone does:
51
+ up to 0.13.1 such a write, `UNDEFINED = 1`, rebound `undefined` there. It is refused only when
52
+ nothing else binds the name: a parameter may still shadow it, and a key the context resolves to a
53
+ value other than `undefined` stays writable. A context class that overrides `set` decides these
54
+ writes itself, so a signal context still throws its own `SignalContextWriteError`
55
+ ([A46](../../docs/backlog-retired.md#a46)).
56
+
57
+ ---
58
+
17
59
  ## [0.13.1] - 2026-10-22
18
60
 
19
61
  ### Changed
@@ -266,7 +308,7 @@ ranges are `>=0.11.0 <0.13.0` and `>=0.12.0 <0.13.0`.
266
308
  - assigning over a listed function, `fetch = 1` or `obj.fetch = 1`, since an assignment reads
267
309
  its target before writing it;
268
310
  - updating one, `obj.fetch++`, which writes first and then throws, so the failed evaluation
269
- leaves its write behind ([A40](../../docs/backlog.md#a40));
311
+ leaves its write behind ([A40](../../docs/backlog-retired.md#a40));
270
312
  - an operator's operand, `x instanceof Function` or `obj.fetch != null`;
271
313
  - a conditional's test, `obj.fetch ? 1 : 0`;
272
314
  - a template interpolation, `` `${eval}` ``, and a declaration's initializer;
package/README.md CHANGED
@@ -205,7 +205,7 @@ const result = service.simpleEval('cat.action(args, cat.num, "times")', evalCont
205
205
  // 'Mister Whiskers says meow 3 times' - `this` is thisArg; cat.num still reads cat
206
206
  ```
207
207
 
208
- 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.
208
+ 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.
209
209
 
210
210
  ### Colon-joined names — `provideColonIdentifiers`
211
211
 
@@ -276,7 +276,9 @@ The project has been tested with the following node types:
276
276
  - `ObjectExpression`
277
277
  - `AssignmentExpression` — to an identifier or a member, parenthesised or not. Destructuring
278
278
  assignment, `[a, b] = arr` or `({ m } = o)`, throws `Unsupported assignment target`;
279
- before `@zvenigora/ng-eval-core` 0.7.0 it silently did nothing
279
+ before `@zvenigora/ng-eval-core` 0.7.0 it silently did nothing. An identifier write that
280
+ would shadow `undefined`, or under `caseInsensitive` a literal, throws
281
+ `Assignment to read-only name`, since 0.13.2
280
282
  - `UpdateExpression` — to an identifier or a member, parenthesised or not
281
283
  - `ArrowFunctionExpression` *potentially unsafe* (AssignmentPattern is not implemented, so a
282
284
  destructuring default — `({ a = 1 }) => a` — is rejected rather than defaulted)
@@ -693,6 +693,16 @@ const setContextValue = (context, key, value) => {
693
693
  object[key] = value;
694
694
  }
695
695
  };
696
+ /**
697
+ * Whether `store` compares its keys case-insensitively: a `Registry` built
698
+ * with `caseInsensitive`. A case-sensitive `Registry` and a plain record are
699
+ * read by exact key, whatever the options of the context that holds them.
700
+ *
701
+ * The one copy of that test. `eval-context.ts`'s `spellingIn` asks it to find
702
+ * a key's stored spelling, and `variable-declaration.ts` asks it of the store
703
+ * a write lands in (`docs/backlog-retired.md` A46).
704
+ */
705
+ const isCaseInsensitiveStore = (store) => store instanceof Registry && store.options['caseInsensitive'] === true;
696
706
 
697
707
  /**
698
708
  * Opens a node: records it as open and fires the registered 'before' hooks.
@@ -2740,12 +2750,42 @@ const popVisitorResultAsync = (node, st) => {
2740
2750
  return value;
2741
2751
  };
2742
2752
 
2753
+ /**
2754
+ * The names `identifier.ts` resolves to a built-in value under
2755
+ * `caseInsensitive`, in any spelling, when the context holds none of them.
2756
+ * ESTree parses `undefined` as an `Identifier`, and under that option a case
2757
+ * variant of `null`, `true` or `false` is one too, so each reaches the
2758
+ * identifier visitor rather than the literal one.
2759
+ */
2743
2760
  const literals = Registry.fromObject({
2744
2761
  'undefined': undefined,
2745
2762
  'null': null,
2746
2763
  'true': true,
2747
2764
  'false': false,
2748
2765
  }, { caseInsensitive: true });
2766
+ /**
2767
+ * Whether `name`, as written, is one the evaluator resolves to a built-in
2768
+ * value, for a write that would land in `store`: `undefined` in both modes,
2769
+ * and under `caseInsensitive` any spelling of a {@link literals} name.
2770
+ * Case-sensitively, `TRUE` and `NULL` are ordinary names, and `true`, `null`
2771
+ * and `false` never reach an identifier.
2772
+ *
2773
+ * **Any spelling of `undefined` also counts when the store compares keys
2774
+ * case-insensitively**, whatever the walk's mode. A case-insensitive context
2775
+ * walked with case-sensitive options is the split the README warns of, and
2776
+ * there `UNDEFINED = 1` lands in a store whose `get('undefined')` then finds
2777
+ * it, so the case-sensitive read of `undefined` would read the write. `TRUE`,
2778
+ * `NULL` and `FALSE` need no such clause: a case-sensitive walk never reads
2779
+ * them as literals. The length test keeps the lowering off every other write.
2780
+ *
2781
+ * `NaN` and `Infinity` are not among them: the evaluator resolves neither, so
2782
+ * on an empty context each reads `undefined` (`docs/backlog-retired.md` A46).
2783
+ */
2784
+ const isLiteralName = (name, caseInsensitive, store) => name === 'undefined'
2785
+ || (caseInsensitive
2786
+ ? literals.has(name)
2787
+ : name.length === 9 && name.toLowerCase() === 'undefined' && isCaseInsensitiveStore(store));
2788
+
2749
2789
  /**
2750
2790
  * Reports a resolved identifier read to the hook layer.
2751
2791
  *
@@ -3884,6 +3924,40 @@ const variableDeclarationVisitor = (node, st, callback) => {
3884
3924
  pushVisitorResult(node, st, EMPTY_COMPLETION);
3885
3925
  afterVisitor(node, st);
3886
3926
  };
3927
+ /**
3928
+ * Refuses a write that would rebind a name the evaluator resolves to a
3929
+ * built-in value - `undefined`, and under `caseInsensitive` a case variant of
3930
+ * a literal - on the context (`docs/backlog-retired.md` A46). Up to 0.13.1 a
3931
+ * write to `undefined` landed like any other key, and `identifier.ts` reads
3932
+ * the context before its literals, so every later evaluation on that context
3933
+ * read the written value; A43's fallback would have done the same for a case
3934
+ * variant of a literal.
3935
+ * A case variant of `undefined` is refused under a case-sensitive walk too,
3936
+ * when the store the write lands in - the context's original, which `set`
3937
+ * writes - compares keys case-insensitively, since its `get('undefined')`
3938
+ * would then find the write.
3939
+ *
3940
+ * Called only when no pushed scope binds the name, so a parameter or a `let`
3941
+ * may still shadow it, as in JavaScript. The cheap name test runs first, so
3942
+ * any other name pays nothing more. A key the context resolves to a value
3943
+ * other than `undefined` stays writable - one the host holds, or one a lookup
3944
+ * answers; a key held as `undefined` resolves to nothing, as A43 counts it.
3945
+ *
3946
+ * **A context class that overrides `set` decides these writes itself.** `set`
3947
+ * is resolved by class, as every method the evaluator calls on a context is
3948
+ * (`context-method.ts`), so an own property planted on the instance cannot
3949
+ * pass for an override. `eval-signals`' signal context overrides `set` to
3950
+ * refuse every key write with `SignalContextWriteError`, which `eval-forms`
3951
+ * rethrows by class past its error policy; refusing here first would have
3952
+ * replaced that error with this one.
3953
+ */
3954
+ const refuseReadOnlyName = (context, name, caseInsensitive) => {
3955
+ if (isLiteralName(name, caseInsensitive, context.original)
3956
+ && context.getKey(name) === undefined
3957
+ && prototypeMethod(context, 'set') === EvalContext.prototype.set) {
3958
+ throw new Error(`Assignment to read-only name "${name}".`);
3959
+ }
3960
+ };
3887
3961
  /**
3888
3962
  * Assigns to `key`, preferring a binding the evaluation itself created.
3889
3963
  *
@@ -3925,6 +3999,7 @@ const assignToBinding = (st, key, value, name) => {
3925
3999
  }
3926
4000
  const scope = contextScopeHolding(st.context, key);
3927
4001
  if (!scope) {
4002
+ refuseReadOnlyName(st.context, name, !!st.options?.caseInsensitive);
3928
4003
  contextSet(st.context, key, value);
3929
4004
  return;
3930
4005
  }
@@ -3978,8 +4053,12 @@ const assignmentExpressionVisitor = (node, st, callback) => {
3978
4053
  throw new Error(`Context is not set.`);
3979
4054
  }
3980
4055
  else if (target.type === 'Identifier') {
4056
+ // `getKey` gives `undefined` when `get` finds nothing - an absent name, or
4057
+ // one bound to `undefined` - and that key was written as it came
4058
+ // (`docs/backlog-retired.md` A43). The name as written is the fallback
4059
+ // `identifier.ts` already takes.
3981
4060
  const key = st.options?.caseInsensitive
3982
- ? st.context.getKey(target.name)
4061
+ ? st.context.getKey(target.name) ?? target.name
3983
4062
  : target.name;
3984
4063
  const value = func(left, right);
3985
4064
  // Scope first, the caller's object second. Before Phase 2 this was
@@ -4006,10 +4085,6 @@ const assignmentExpressionVisitor = (node, st, callback) => {
4006
4085
  afterVisitor(node, st);
4007
4086
  };
4008
4087
 
4009
- const updateOperators = {
4010
- '++': (value) => { return value + 1; },
4011
- '--': (value) => { return value - 1; },
4012
- };
4013
4088
  const updateExpressionVisitor = (node, st, callback) => {
4014
4089
  beforeVisitor(node, st);
4015
4090
  // `(a)++` under `preserveParens` arrives wrapped (`docs/backlog-retired.md` A2).
@@ -4018,29 +4093,43 @@ const updateExpressionVisitor = (node, st, callback) => {
4018
4093
  throw new Error(`Context is not set.`);
4019
4094
  }
4020
4095
  else if (target.type === 'Identifier') {
4096
+ // The fallback `assignment-expression.ts` takes, for the same reason
4097
+ // (`docs/backlog-retired.md` A43).
4021
4098
  const key = st.options?.caseInsensitive
4022
- ? st.context.getKey(target.name)
4099
+ ? st.context.getKey(target.name) ?? target.name
4023
4100
  : target.name;
4024
4101
  const value = st.context?.get(key);
4025
- const newValue = updateOperators[node.operator](value);
4102
+ // The update run natively on a copy of the operand. JavaScript converts
4103
+ // the operand to a numeric once, then adds or subtracts, and a postfix
4104
+ // update gives that converted old value. `value + 1` on the operand as
4105
+ // read concatenated a string or an object, gave a postfix result
4106
+ // unconverted, and threw on a BigInt (`docs/backlog-retired.md` A41).
4107
+ // Running the operator itself is the conversion, BigInt included, which
4108
+ // `Number()` or a unary `+` is not. It runs before the write, here and in
4109
+ // the member branch, so an operand that cannot convert - a Symbol, a
4110
+ // throwing `valueOf` - throws with nothing written.
4111
+ let updated = value;
4112
+ const old = node.operator === '++' ? updated++ : updated--;
4026
4113
  // The same redirection as `assignment-expression.ts`, and the site that
4027
4114
  // matters for `for (let i = 0; …; i++)`: without it every loop counter this
4028
4115
  // library runs would be written into the consumer's context object, and
4029
4116
  // left there.
4030
- assignToBinding(st, key, newValue, target.name);
4031
- pushVisitorResult(node, st, node.prefix ? newValue : value);
4117
+ assignToBinding(st, key, updated, target.name);
4118
+ pushVisitorResult(node, st, node.prefix ? updated : old);
4032
4119
  }
4033
4120
  else if (target.type === 'MemberExpression') {
4034
4121
  const [object, property, value] = evaluateMember(target, st, callback);
4035
- const newValue = updateOperators[node.operator](value);
4122
+ // As in the identifier branch: one native conversion, before the write.
4123
+ let updated = value;
4124
+ const old = node.operator === '++' ? updated++ : updated--;
4036
4125
  // The same consultation as `assignment-expression.ts`'s member branch.
4037
4126
  const created = st.createdObjects;
4038
4127
  if (created) {
4039
4128
  consultMemberWrite(st, created, object, property);
4040
4129
  }
4041
4130
  // Use safe property assignment to prevent prototype pollution
4042
- safeSetProperty(object, property, newValue);
4043
- pushVisitorResult(node, st, node.prefix ? newValue : value);
4131
+ safeSetProperty(object, property, updated);
4132
+ pushVisitorResult(node, st, node.prefix ? updated : old);
4044
4133
  }
4045
4134
  else {
4046
4135
  // Without this the visitor reached `afterVisitor` having pushed nothing,
@@ -5183,9 +5272,7 @@ const resolve = (context, key) => {
5183
5272
  * own spelling there.
5184
5273
  */
5185
5274
  const spellingIn = (holder, key) => {
5186
- if (holder instanceof Registry
5187
- && holder.options['caseInsensitive'] === true
5188
- && typeof key === 'string') {
5275
+ if (isCaseInsensitiveStore(holder) && typeof key === 'string') {
5189
5276
  const lowered = key.toLowerCase();
5190
5277
  for (const candidate of holder.keys) {
5191
5278
  if (typeof candidate === 'string' && candidate.toLowerCase() === lowered) {