@zvenigora/ng-eval-core 0.13.1 → 0.13.3

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
@@ -10,7 +10,58 @@ Versions 0.1.104–0.1.107 are on npm without entries here.
10
10
 
11
11
  ---
12
12
 
13
- ## [Unreleased]
13
+ ## [0.13.3] - 2026-10-23
14
+
15
+ ### Fixed
16
+ - **A logical assignment that short-circuits no longer evaluates its right side or writes**:
17
+ `a ||= f()` with `a` truthy does not call `f`, and a write policy is not asked about a write that
18
+ does not happen. A refusal on the write path, such as a `const` binding or a read-only name, no
19
+ longer fires when the assignment short-circuits and writes nothing, as in JavaScript. Logical
20
+ assignment is ES2021, and the default parser options, at `ecmaVersion: 2020`, refuse it at the
21
+ parse, so this reaches only a caller whose own parser options set `ecmaVersion` to 2021 or later
22
+ ([A45](../../docs/backlog.md#a45), part 1).
23
+
24
+ ---
25
+
26
+ ## [0.13.2] - 2026-10-22
27
+
28
+ ### Changed
29
+ - **The README states a limit of `caseInsensitive` on a context built with `new EvalContext`**: a
30
+ plain object handed to the constructor matches no case variant, even with the option passed to
31
+ the walk too, and `EvalContext.fromContext` is the way to build one that does. No code change
32
+ ([A44](../../docs/backlog.md#a44), where it was measured).
33
+
34
+ ### Fixed
35
+ - **An update converts its operand to a number once, as JavaScript does**, and uses that one
36
+ conversion for the value it writes and for its result. `x++` on `"5"` gives `5` and writes `6`,
37
+ where it gave `"5"` and wrote `"51"`; an object that does not convert to a number, or a
38
+ non-numeric string, gives `NaN` and writes `NaN`, where `++` concatenated and a postfix update
39
+ gave the operand as read; and an update of a BigInt updates it, where it threw. An operand that
40
+ cannot convert, a Symbol or a throwing `valueOf`, throws before anything is written
41
+ ([A41](../../docs/backlog-retired.md#a41)).
42
+ - **A postfix update of a listed function no longer throws after writing**: `tools.eval++` gives
43
+ `NaN` and writes `NaN`, as JavaScript does, where the write landed and the funnel then refused the
44
+ old value. The result is a number, so the funnel has nothing to refuse
45
+ ([A40](../../docs/backlog-retired.md#a40)).
46
+ - **Under `caseInsensitive`, an identifier assignment or update to a name the context resolves to
47
+ nothing writes that name**, where it wrote the key `undefined`: the string `"undefined"` on a
48
+ plain object, the value `undefined` in a `Registry`. That covers a name absent from the context
49
+ and one bound to `undefined`, as `x = 1` on `{ x: undefined }`. A context that refuses writes, as
50
+ `eval-signals`' signal context does, is now asked about the name as written, so its refusal names
51
+ it ([A43](../../docs/backlog-retired.md#a43)). The name `undefined` itself, and under
52
+ `caseInsensitive` a spelling of a literal, is refused instead: see the next entry.
53
+ - **A write that would rebind `undefined` on the context throws
54
+ `Assignment to read-only name "<name>".`**, as do, under `caseInsensitive`, a write to any
55
+ spelling of `undefined`, `null`, `true` or `false`, such as `TRUE = 0` or `Undefined++`. Up to
56
+ 0.13.1, `undefined = 1` landed on the context, and every later evaluation on it read the written
57
+ value; under `caseInsensitive` these writes went to the stray key the entry above describes. A
58
+ case variant of `undefined` is refused under a case-sensitive walk too, when the context's store
59
+ compares keys case-insensitively, as one built with `caseInsensitive` on the context alone does:
60
+ up to 0.13.1 such a write, `UNDEFINED = 1`, rebound `undefined` there. It is refused only when
61
+ nothing else binds the name: a parameter may still shadow it, and a key the context resolves to a
62
+ value other than `undefined` stays writable. A context class that overrides `set` decides these
63
+ writes itself, so a signal context still throws its own `SignalContextWriteError`
64
+ ([A46](../../docs/backlog-retired.md#a46)).
14
65
 
15
66
  ---
16
67
 
@@ -266,7 +317,7 @@ ranges are `>=0.11.0 <0.13.0` and `>=0.12.0 <0.13.0`.
266
317
  - assigning over a listed function, `fetch = 1` or `obj.fetch = 1`, since an assignment reads
267
318
  its target before writing it;
268
319
  - updating one, `obj.fetch++`, which writes first and then throws, so the failed evaluation
269
- leaves its write behind ([A40](../../docs/backlog.md#a40));
320
+ leaves its write behind ([A40](../../docs/backlog-retired.md#a40));
270
321
  - an operator's operand, `x instanceof Function` or `obj.fetch != null`;
271
322
  - a conditional's test, `obj.fetch ? 1 : 0`;
272
323
  - 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
  }
@@ -3968,6 +4043,17 @@ const assignmentExpressionVisitor = (node, st, callback) => {
3968
4043
  }
3969
4044
  callback(node.left, st);
3970
4045
  const left = popVisitorResult(node, st);
4046
+ // A logical assignment that short-circuits gives `left` and does nothing
4047
+ // more: its right side is not evaluated and nothing is written, so no write
4048
+ // policy is asked (`docs/backlog.md` A45, part 1). The rule is
4049
+ // `logical-expression.ts`'s, for `||`, `&&` and `??`.
4050
+ if ((node.operator === '||=' && left) ||
4051
+ (node.operator === '&&=' && !left) ||
4052
+ (node.operator === '??=' && left !== null && left !== undefined)) {
4053
+ pushVisitorResult(node, st, left);
4054
+ afterVisitor(node, st);
4055
+ return;
4056
+ }
3971
4057
  callback(node.right, st);
3972
4058
  const right = popVisitorResult(node, st);
3973
4059
  const func = assignmentOperators[node.operator];
@@ -3978,8 +4064,12 @@ const assignmentExpressionVisitor = (node, st, callback) => {
3978
4064
  throw new Error(`Context is not set.`);
3979
4065
  }
3980
4066
  else if (target.type === 'Identifier') {
4067
+ // `getKey` gives `undefined` when `get` finds nothing - an absent name, or
4068
+ // one bound to `undefined` - and that key was written as it came
4069
+ // (`docs/backlog-retired.md` A43). The name as written is the fallback
4070
+ // `identifier.ts` already takes.
3981
4071
  const key = st.options?.caseInsensitive
3982
- ? st.context.getKey(target.name)
4072
+ ? st.context.getKey(target.name) ?? target.name
3983
4073
  : target.name;
3984
4074
  const value = func(left, right);
3985
4075
  // Scope first, the caller's object second. Before Phase 2 this was
@@ -4006,10 +4096,6 @@ const assignmentExpressionVisitor = (node, st, callback) => {
4006
4096
  afterVisitor(node, st);
4007
4097
  };
4008
4098
 
4009
- const updateOperators = {
4010
- '++': (value) => { return value + 1; },
4011
- '--': (value) => { return value - 1; },
4012
- };
4013
4099
  const updateExpressionVisitor = (node, st, callback) => {
4014
4100
  beforeVisitor(node, st);
4015
4101
  // `(a)++` under `preserveParens` arrives wrapped (`docs/backlog-retired.md` A2).
@@ -4018,29 +4104,43 @@ const updateExpressionVisitor = (node, st, callback) => {
4018
4104
  throw new Error(`Context is not set.`);
4019
4105
  }
4020
4106
  else if (target.type === 'Identifier') {
4107
+ // The fallback `assignment-expression.ts` takes, for the same reason
4108
+ // (`docs/backlog-retired.md` A43).
4021
4109
  const key = st.options?.caseInsensitive
4022
- ? st.context.getKey(target.name)
4110
+ ? st.context.getKey(target.name) ?? target.name
4023
4111
  : target.name;
4024
4112
  const value = st.context?.get(key);
4025
- const newValue = updateOperators[node.operator](value);
4113
+ // The update run natively on a copy of the operand. JavaScript converts
4114
+ // the operand to a numeric once, then adds or subtracts, and a postfix
4115
+ // update gives that converted old value. `value + 1` on the operand as
4116
+ // read concatenated a string or an object, gave a postfix result
4117
+ // unconverted, and threw on a BigInt (`docs/backlog-retired.md` A41).
4118
+ // Running the operator itself is the conversion, BigInt included, which
4119
+ // `Number()` or a unary `+` is not. It runs before the write, here and in
4120
+ // the member branch, so an operand that cannot convert - a Symbol, a
4121
+ // throwing `valueOf` - throws with nothing written.
4122
+ let updated = value;
4123
+ const old = node.operator === '++' ? updated++ : updated--;
4026
4124
  // The same redirection as `assignment-expression.ts`, and the site that
4027
4125
  // matters for `for (let i = 0; …; i++)`: without it every loop counter this
4028
4126
  // library runs would be written into the consumer's context object, and
4029
4127
  // left there.
4030
- assignToBinding(st, key, newValue, target.name);
4031
- pushVisitorResult(node, st, node.prefix ? newValue : value);
4128
+ assignToBinding(st, key, updated, target.name);
4129
+ pushVisitorResult(node, st, node.prefix ? updated : old);
4032
4130
  }
4033
4131
  else if (target.type === 'MemberExpression') {
4034
4132
  const [object, property, value] = evaluateMember(target, st, callback);
4035
- const newValue = updateOperators[node.operator](value);
4133
+ // As in the identifier branch: one native conversion, before the write.
4134
+ let updated = value;
4135
+ const old = node.operator === '++' ? updated++ : updated--;
4036
4136
  // The same consultation as `assignment-expression.ts`'s member branch.
4037
4137
  const created = st.createdObjects;
4038
4138
  if (created) {
4039
4139
  consultMemberWrite(st, created, object, property);
4040
4140
  }
4041
4141
  // Use safe property assignment to prevent prototype pollution
4042
- safeSetProperty(object, property, newValue);
4043
- pushVisitorResult(node, st, node.prefix ? newValue : value);
4142
+ safeSetProperty(object, property, updated);
4143
+ pushVisitorResult(node, st, node.prefix ? updated : old);
4044
4144
  }
4045
4145
  else {
4046
4146
  // Without this the visitor reached `afterVisitor` having pushed nothing,
@@ -5183,9 +5283,7 @@ const resolve = (context, key) => {
5183
5283
  * own spelling there.
5184
5284
  */
5185
5285
  const spellingIn = (holder, key) => {
5186
- if (holder instanceof Registry
5187
- && holder.options['caseInsensitive'] === true
5188
- && typeof key === 'string') {
5286
+ if (isCaseInsensitiveStore(holder) && typeof key === 'string') {
5189
5287
  const lowered = key.toLowerCase();
5190
5288
  for (const candidate of holder.keys) {
5191
5289
  if (typeof candidate === 'string' && candidate.toLowerCase() === lowered) {