@zvenigora/ng-eval-core 0.11.0 → 0.12.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,7 +14,97 @@ Versions 0.1.104–0.1.107 are on npm without entries here.
14
14
 
15
15
  ---
16
16
 
17
- ## [0.11.0] - 2026-10-04
17
+ ## [0.12.0] - 2026-10-13
18
+
19
+ **Colon-joined names, opt-in — Phase 9 ([plan](../../docs/colon-identifiers/phase-9-plan.md)) — and
20
+ a parse cache that honours the options it is asked with.** A minor: two additions, the
21
+ compiled-string key that goes with them, and the [A26](../../docs/backlog-retired.md#a26) fix. No
22
+ exported symbol changes shape: the `.d.ts` differs from 0.11.1 by `ParserOptions.colonIdentifiers`,
23
+ `provideColonIdentifiers` and documentation comments, beside a private member each on
24
+ `ParserService` and `CompilerService`. The peer ranges are unchanged, `acorn ^8.11.2` included: the
25
+ grammar's spec and corpus pass at 8.11.2 (the plan's § 8 q3). `eval-signals` 0.5.1 and `eval-forms` 0.5.0 admit it;
26
+ `eval-signals` 0.4.0–0.5.0 and `eval-forms` 0.4.x declare `>=0.11.0 <0.12.0` and do not.
27
+
28
+ ### Added
29
+ - **`ParserOptions.colonIdentifiers`.** With it on, a colon-joined name such as `Q1:1` or `VP14:0`
30
+ parses as one `Identifier` whose `name` is the whole key, so it reads `context['Q1:1']`. It is
31
+ off by default, and with it off a parse is acorn's own, as before. Where JavaScript already gives
32
+ the colon a meaning, the name gives way or is refused and is never read as something else: in a
33
+ conditional's consequent it is written in parentheses, `c ? (Q1:1) : 0`, and as an object key it
34
+ is a `SyntaxError` — quote it. So under the option a compact object literal, `({a:1})`, needs a
35
+ space after the key's colon. Hooks, dependency tracking and every prototype-pollution refusal see
36
+ an ordinary identifier. The README's "Colon-joined names" gives the rule.
37
+ - **`provideColonIdentifiers()`**, which turns `colonIdentifiers` on for an application.
38
+ `ParserService` reads it when it is constructed, so every parse through `EvalService`,
39
+ `CompilerService` and `DiscoveryService` follows it, and a per-call `colonIdentifiers` overrides
40
+ it. It belongs in the root providers: in a child environment injector, such as a lazy route's, it
41
+ throws when that injector is created. `new ParserService()` outside an injection context keeps
42
+ the option off.
43
+ - **`CompilerService` keys a compiled string on the options its parse uses**, as `ParserService`
44
+ keys an AST, so a text compiled before `ParserService.parserOptions` was replaced through its
45
+ setter — with `colonIdentifiers` turned on, for one — is compiled again rather than served the
46
+ old function. A write in place into that object is not seen, as it is not for an AST
47
+ ([A34](../../docs/backlog.md#a34)). Two narrower
48
+ changes: a subclass that sets `CompilerService`'s protected per-call options is served a function
49
+ for its current ones, compiled on every call when they carry an acorn callback or `program`, and
50
+ a value JSON cannot hold, set in `ParserService.parserOptions` under a key `defaultParserOptions`
51
+ does not carry, now compiles uncached.
52
+
53
+ ### Fixed
54
+ - **`ParserService` serves a cached AST only to a parse with the options that produced it —
55
+ [A26](../../docs/backlog-retired.md#a26).** The parse cache was keyed on the expression alone, so
56
+ the first parse of a text decided what every later caller got for it, whatever options they
57
+ passed: after one `ParserService.parse('await p', { ecmaVersion: 2022, allowAwaitOutsideFunction:
58
+ true })`, `EvalService.simpleEval('await p')` returned a promise instead of throwing its
59
+ `SyntaxError`, and a direct `ParserService.parse` caller and the services, which ask for
60
+ differently shaped results, were each served the other's. The key now holds every option that
61
+ changes the parse, which is all but `cacheSize`, acorn's four callbacks and `program`. A parse
62
+ carrying a callback or a `program` neither reads nor writes the cache, so the callback runs on
63
+ every parse. A change made through the `parserOptions` setter is honoured for text already
64
+ cached; a write in place into an options object, the service's or one passed again, is not
65
+ ([A34](../../docs/backlog.md#a34)). Every published version to 0.11.1 is affected.
66
+
67
+ ---
68
+
69
+ ## [0.11.1] - 2026-10-10
70
+
71
+ **Two cache fixes: `CompilerService` no longer returns one AST's compiled function for another, and
72
+ under `caseInsensitive` a member read no longer resolves another object's spelling.** A patch. Both
73
+ caches came in with 0.2.1, so every version since is affected. No exported symbol changes shape: the
74
+ `.d.ts` differs from 0.11.0 in documentation comments only — `compile`'s and `compileAsync`'s, which
75
+ now say an AST is compiled on every call, and the four [A28](../../docs/backlog-retired.md#a28)
76
+ corrected. `eval-signals` 0.4.0–0.5.0 and `eval-forms` 0.4.x admit it: their peer range is
77
+ `>=0.11.0 <0.12.0`.
78
+
79
+ ### Changed
80
+ - `EvalReadEvent.scoped`'s JSDoc no longer says the flag marks a scope pushed during the
81
+ evaluation: it is set when any scope on the context's scope stack binds the name, one the caller
82
+ pushed with `EvalContext.push` before the walk included, and `hasInScopes`', `getFromScopes`'
83
+ and `createDependencyTracker`'s say the same ([A28](../../docs/backlog-retired.md#a28)). So does
84
+ the README's `onRead` example, whose comment said `event.scoped` was true for arrow-function
85
+ parameters. The flag's behaviour is unchanged.
86
+
87
+ ### Fixed
88
+ - **`CompilerService` no longer returns one AST's compiled function for another —
89
+ [A29](../../docs/backlog-retired.md#a29).** `compile` and `compileAsync` cached an AST under its
90
+ type, start and end and `toString()`, which is `[object Object]` for every node, so two different
91
+ expressions of one shape and span shared a function: `compile(ast('a * b'))` then
92
+ `compile(ast('c * d'))` returned `a * b`'s, which over `{ a: 1, b: 3, c: 3, d: 4 }` answered `3`,
93
+ not `12`, for as long as the cache kept it. An AST is now compiled on every call and never cached.
94
+ Affected 0.2.1–0.11.0, 0.10.1 included. A string input was never affected, and is cached as before.
95
+ - **Under `caseInsensitive`, a member read no longer resolves another object's spelling —
96
+ [A31](../../docs/backlog-retired.md#a31).** The cache of which own key a case variant names was
97
+ keyed by the object's own-key count and its first five key names, once for the whole process, so
98
+ objects that shared their first five key names could resolve each other's spelling: a read could
99
+ return the wrong property or `undefined`, and a case-variant read of a blocked name, such as
100
+ `x.CONSTRUCTOR`, could return `undefined` instead of throwing. No blocked property was ever read.
101
+ The cache is now keyed by the object itself, and a cached key is used only while it is still the
102
+ object's own. Affected 0.2.1–0.11.0, 0.10.1 included, from the same commit as A29; a read without
103
+ `caseInsensitive` never was.
104
+
105
+ ---
106
+
107
+ ## [0.11.0] - 2026-10-07
18
108
 
19
109
  **A security fix: an expression no longer resolves a name on the prototype-pollution blocklist
20
110
  against its context. Also, the member-write policy is asked about built-in methods that write,
@@ -99,7 +189,7 @@ what it sees. `eval-signals` 0.4.0 builds on the change and requires this versio
99
189
 
100
190
  ---
101
191
 
102
- ## [0.10.1] - 2026-10-05
192
+ ## [0.10.1] - 2026-10-07
103
193
 
104
194
  **A security fix: an expression no longer resolves a name on the prototype-pollution blocklist
105
195
  against its context.** A patch for every version up to 0.10.0, with no exported symbol changed.
package/README.md CHANGED
@@ -78,6 +78,51 @@ const result = service.simpleEval('cat.action(args, cat.num, "times")', evalCont
78
78
 
79
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.
80
80
 
81
+ ### Colon-joined names — `provideColonIdentifiers`
82
+
83
+ Some expression languages name their values `Q1:1` or `VP14:0`. With `colonIdentifiers` on, such a name parses as one identifier and reads the context key of the same spelling, `context['Q1:1']`. It is off by default, and with it off every expression parses as it always has.
84
+
85
+ `provideColonIdentifiers()` turns it on for an application: `ParserService` reads it when it is constructed, so every parse through `EvalService`, `CompilerService` and `DiscoveryService` follows it. Put it in the application's **root** providers. `ParserService` is provided in the root, so in a lazy route's providers, or any other child injector's, the provider would reach no parse; there it throws when that injector is created instead.
86
+
87
+ A per-call `colonIdentifiers` in the options of `ParserService.parse`, or of the exported `parse`, overrides it — and the exported `parse` sees only the options it is given. Setting `ParserService.parserOptions` to a new object is the imperative alternative: every later parse or compile follows it, of a text seen before as of a new one, while a function already compiled keeps the reading it was compiled with.
88
+
89
+ ```javascript
90
+ import { EvalService, ParserService,
91
+ provideColonIdentifiers } from '@zvenigora/ng-eval-core';
92
+
93
+ // app.config.ts: the application's root providers, not a lazy route's
94
+ export const appConfig = { providers: [provideColonIdentifiers()] };
95
+
96
+ const parser = inject(ParserService);
97
+ parser.parserOptions.colonIdentifiers; // true - the effective setting
98
+
99
+ const service = inject(EvalService);
100
+ service.simpleEval('Q1:1 + 1', { 'Q1:1': 2 }); // 3
101
+ service.simpleEval('Q1:1 + 1', { Q1: 100 }); // NaN - 'Q1:1' is a key of its own
102
+ ```
103
+
104
+ **The rule.** A colon-joined name is a first segment — an ASCII letter, `_` or `$`, then ASCII letters, digits, `_` or `$` — followed by one or more segments of the same characters, each after a `:`, which may start with a digit: `Q1:1`, `VP14:0`, `Q1:1:3`, `Q1:_x`. Nothing may sit inside it, no space, comment or line break, and the longest match wins, so `Q1:1:3` is one name. The name is an opaque key: `Q1:01` and `Q1:1` are different keys, and nothing splits one into segments. It joins wherever an identifier can stand — in an expression, after `.` and `?.` (`obj.Q1:1` reads `obj['Q1:1']`, and `sheet:A1.value` is `(sheet:A1).value`), as a binding (`let Q1:1 = 5`, `(Q1:1) => …`) and inside a template's `${…}` — and text stays text: `"Q1:1"`, a template's own text, a regex, a comment.
105
+
106
+ Some spellings keep the meaning they always had. A keyword does not start a name, so `true:1`, `this:1` and `typeof:1` are syntax errors as before, while a word acorn reads as a name, such as `let` or `async`, does start one. A first segment holding a non-ASCII character or a `\u` escape does not join, and neither does a colon followed by a non-ASCII character, so `Вопрос:1` and `Q1:Ответ` are labels; so is a colon with a space beside it: `Q1: 1` is the label `Q1`, under the option too. A non-ASCII character later in a segment ends the name there, and what follows it is a `SyntaxError`: `Q1:1é`.
107
+
108
+ **Where JavaScript already gives the colon a meaning**, the name gives way or is refused, and never reads silently as something else:
109
+
110
+ - **A conditional's consequent.** Between a `?` and the `:` that closes it, a name does not join at the conditional's own level, so `a?b:c` keeps its meaning. Put a colon-joined name there in parentheses, `c ? (Q1:1) : 0`; inside a call, an array or a template the consequent opens it joins as anywhere else, as it does in the test and the alternate: `Q1:1 ? f(Q2:2) : Q3:3`. Without the parentheses the leftover colon is a `SyntaxError` at its own position, whose message names the fix — except when the `:` that closes the conditional starts a line of its own, where it is acorn's plain `Unexpected token`.
111
+ - **An object key.** `{Q1:1}` would be `{Q1: 1}` to JavaScript and the shorthand `{'Q1:1': Q1:1}` here, so a colon-joined key is a `SyntaxError` naming both fixes. Quote a colon-named key, `{'Q1:1': v}`. A value, a computed key and a spread join as usual: `({a: Q1:1})`, `({[Q1:1]: 2})`, `({...o, k: Q1:1})`. So under the option a compact literal or pattern — `({a:1})`, `let {a:b} = o` — needs a space after the key's colon.
112
+
113
+ ```javascript
114
+ const ctx = { c: true, 'Q1:1': 5 };
115
+
116
+ service.simpleEval('c ? (Q1:1) : 0', ctx); // 5
117
+ service.simpleEval('c ? Q1:1 : 0', ctx); // throws SyntaxError: Unexpected token: a colon-joined
118
+ // name in the consequent of a conditional needs
119
+ // parentheses: (Q1:1) (1:9)
120
+ service.simpleEval("({ 'Q1:1': 2 })['Q1:1']"); // 2 - a colon-named key is quoted
121
+ service.simpleEval('({a:1}).a'); // throws SyntaxError - write ({a: 1})
122
+ ```
123
+
124
+ **Read events and dependencies stay dotted.** A colon-joined name is one segment of a `path`: reading `obj.Q2:3` reports the `key` `Q2:3` and the `path` `obj.Q2:3`, and `createDependencyTracker()` records `obj.Q2:3`. Split a path on `.`, never on `:`.
125
+
81
126
  ## Options
82
127
 
83
128
  ### Per-node timing
@@ -205,7 +250,9 @@ state.hooks.onRead((event) => {
205
250
  event.kind; // 'identifier' | 'member'
206
251
  event.key; // the resolved key
207
252
  event.path; // 'a.b' when statically reconstructible, else undefined
208
- event.scoped; // true for arrow-function parameters - not dependencies
253
+ event.scoped; // true when a scope on the context's stack binds the name - an
254
+ // arrow parameter, a let or const, or a scope pushed with
255
+ // EvalContext.push - so not a dependency
209
256
  });
210
257
  ```
211
258