@zvenigora/ng-eval-core 0.15.0 → 0.16.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zvenigora/ng-eval-core",
3
- "version": "0.15.0",
3
+ "version": "0.16.0",
4
4
  "description": "An expression evaluator for Angular",
5
5
  "repository": {
6
6
  "type": "git",
@@ -658,6 +658,12 @@ declare class EvalContext {
658
658
  get scopes(): Readonly<Stack<Context>>;
659
659
  /**
660
660
  * Gets the lookups registry.
661
+ *
662
+ * A lookup is called while a name is resolved, and how many times an
663
+ * expression calls it is not part of the contract
664
+ * (`docs/backlog-retired.md` A49): it can be called where JavaScript would
665
+ * read nothing, as under `caseInsensitive` by `x = 1`, or more than once for
666
+ * one read, and a registered read hook can add a call.
661
667
  */
662
668
  get lookups(): EvalLookup[];
663
669
  /**
@@ -785,9 +791,18 @@ declare class EvalContext {
785
791
  * not an object that holds the key.
786
792
  *
787
793
  * Undefined means "no receiver of its own", and the member visitor then falls
788
- * back to the object it was evaluating. Up to 0.6.x the prior-scope step
789
- * re-tested the original context and could never answer, and the lookup step
790
- * returned the lookup function itself (`docs/backlog-retired.md` A7).
794
+ * back to the object it was evaluating.
795
+ *
796
+ * It decides by reading the value, through the original or a prior scope's
797
+ * `get`, so a getter there runs where JavaScript reads nothing; how many
798
+ * times an expression calls it is not part of the contract
799
+ * (`docs/backlog-retired.md` A49). Case-sensitively, with a getter `g` on the
800
+ * context, `this.g = 1` calls it once and `this.g += 1` twice, with or
801
+ * without a read hook.
802
+ *
803
+ * Up to 0.6.x the prior-scope step re-tested the original context and could
804
+ * never answer, and the lookup step returned the lookup function itself
805
+ * (`docs/backlog-retired.md` A7).
791
806
  * @param key - The key to retrieve the value for.
792
807
  * @returns The `this` value associated with the key, or undefined.
793
808
  */
@@ -2053,6 +2068,15 @@ type EvalKnownOptions = {
2053
2068
  onHookError?: EvalHookErrorPolicy;
2054
2069
  };
2055
2070
 
2071
+ /**
2072
+ * The options `EvalService` and `CompilerService` pass on every parse, as
2073
+ * this object itself; `ParserService` and `DiscoveryService` copy it when
2074
+ * constructed. Read it or copy it; do not write into it. A value written into
2075
+ * it is not reliably seen: the parse cache remembers it by identity, so a text
2076
+ * cached before the write can keep its reading, and one parsed while it held
2077
+ * the value can keep that reading after it is written back
2078
+ * (`docs/backlog-retired.md` A34).
2079
+ */
2056
2080
  declare const defaultParserOptions: ParserOptions;
2057
2081
 
2058
2082
  /**
@@ -2220,6 +2244,15 @@ declare class ParserService implements OnDestroy {
2220
2244
  /**
2221
2245
  * Gets the parser options: the constructor's, or the last value given to
2222
2246
  * the setter.
2247
+ *
2248
+ * Replace the object through the setter rather than write into the one this
2249
+ * returns: a value written into it is not reliably seen. The parse cache,
2250
+ * and `CompilerService`'s cache of compiled strings, remember each pair of
2251
+ * options objects, this one and a call's, by identity, not by their values.
2252
+ * A later parse through a pair seen before the write, as `EvalService`'s and
2253
+ * `CompilerService`'s are, keeps a cached text's earlier reading and caches
2254
+ * a new text as if the options had not changed; a parse through a new
2255
+ * call-options object sees the write (`docs/backlog-retired.md` A34).
2223
2256
  */
2224
2257
  get parserOptions(): ParserOptions;
2225
2258
  /**
@@ -2272,7 +2305,10 @@ declare class ParserService implements OnDestroy {
2272
2305
  * @description
2273
2306
  * Parses expression and returns ES6/ES2023 AST.
2274
2307
  * @param expr expression to parse
2275
- * @param options optional parser options
2308
+ * @param options optional parser options, merged over `parserOptions`. Pass
2309
+ * a new object for new options: a value written into an object already
2310
+ * passed is not reliably seen, since the cache remembers the object by
2311
+ * identity (`docs/backlog-retired.md` A34).
2276
2312
  * @returns The parsed AST (Abstract Syntax Tree).
2277
2313
  */
2278
2314
  parse(expr: string, options?: ParserOptions): Program | AnyNode | Expression | undefined;
@@ -2520,7 +2556,7 @@ declare class CompilerService extends BaseEval implements OnDestroy {
2520
2556
  * the `ParserService.parserOptions` setter reaches a string compiled before
2521
2557
  * it (`docs/colon-identifiers/phase-9-plan.md` § 3.2). The memo is
2522
2558
  * `ParserService`'s kind, and a write in place goes unseen here as there
2523
- * (`docs/backlog.md` A34). `null` when that parse bypasses `ParserService`'s
2559
+ * (`docs/backlog-retired.md` A34). `null` when that parse bypasses `ParserService`'s
2524
2560
  * cache - a callback or a `program` among its options, or a value JSON
2525
2561
  * cannot hold - and this cache then bypasses too, since a cached function
2526
2562
  * runs no callback.