@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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zvenigora/ng-eval-core",
3
- "version": "0.11.0",
3
+ "version": "0.12.0",
4
4
  "description": "An expression evaluator for Angular",
5
5
  "repository": {
6
6
  "type": "git",
@@ -1,5 +1,5 @@
1
1
  import * as i0 from '@angular/core';
2
- import { OnDestroy } from '@angular/core';
2
+ import { OnDestroy, EnvironmentProviders } from '@angular/core';
3
3
  import * as acorn from 'acorn';
4
4
  import { AnyNode, Program, Expression } from 'acorn';
5
5
 
@@ -7,6 +7,17 @@ type ParserOptions = Partial<acorn.Options> & {
7
7
  extractExpressions?: boolean;
8
8
  cacheSize?: number;
9
9
  ecmaVersion?: acorn.ecmaVersion;
10
+ /**
11
+ * Parses a colon-joined name such as `Q1:1:3` as one `Identifier` whose
12
+ * `name` is the whole text, by the grammar of
13
+ * `docs/colon-identifiers/phase-9-plan.md` § 3.4: an ASCII first segment
14
+ * that is not a keyword, then one or more `:segment` that may start with a
15
+ * digit, with no whitespace or comment inside. In a conditional's
16
+ * consequent such a name needs parentheses, `c ? (Q1:1) : 0`, and as an
17
+ * object key it is refused: quote it, `{'Q1:1': v}`. Off when absent, and
18
+ * an unset or `false` value parses with acorn's own parser.
19
+ */
20
+ colonIdentifiers?: boolean;
10
21
  };
11
22
  type AnyNodeTypes = acorn.AnyNode['type'];
12
23
 
@@ -673,8 +684,8 @@ declare class EvalContext {
673
684
  */
674
685
  get(key: unknown): unknown | undefined;
675
686
  /**
676
- * Step 1 of {@link get}'s resolution order on its own: the scopes pushed
677
- * during this evaluation, innermost first.
687
+ * Step 1 of {@link get}'s resolution order on its own: the scope stack,
688
+ * innermost first, whoever pushed each scope.
678
689
  *
679
690
  * {@link get} calls this rather than inlining the loop, so that the read
680
691
  * hooks' `scoped` flag and the resolution it describes are the *same*
@@ -738,8 +749,11 @@ declare class EvalContext {
738
749
  */
739
750
  scopeHolding(key: unknown): Context | undefined;
740
751
  /**
741
- * Whether any scope pushed during this evaluation *binds* the key - the
742
- * question the read hooks' `scoped` flag asks.
752
+ * Whether any scope on the scope stack *binds* the key - the question the
753
+ * read hooks' `scoped` flag asks. Every scope on the stack counts, whoever
754
+ * pushed it: an arrow call's parameters, the lexical scope of a program, a
755
+ * block or a `for` loop, and a scope a caller pushed with {@link push}
756
+ * before the walk.
743
757
  *
744
758
  * Deliberately about binding rather than about value. It no longer parts
745
759
  * company with {@link getFromScopes} over it: both go through
@@ -1449,10 +1463,13 @@ interface EvalReadEvent {
1449
1463
  readonly path?: string;
1450
1464
  readonly value: unknown;
1451
1465
  /**
1452
- * True when the key resolved from a scope pushed *during this evaluation* -
1453
- * `EvalContext.scopes`, the stack `arrow-function-expression.ts` pushes and
1454
- * pops around a call. Such a read is an arrow-function parameter binding,
1455
- * not a dependency, and a tracker should skip it.
1466
+ * True when a scope on the context's scope stack - `EvalContext.scopes`,
1467
+ * asked through `EvalContext.hasInScopes` - binds the name when it is read,
1468
+ * whoever pushed that scope. That covers an arrow-function parameter, a
1469
+ * declaration in the lexical scope the evaluator pushes for a program, a
1470
+ * block or a `for` loop, and a binding the caller pushed with
1471
+ * `EvalContext.push` before the walk. Such a read is a binding, not a
1472
+ * dependency, and a tracker should skip it.
1456
1473
  *
1457
1474
  * The definition is **lifetime, not type**: caller-registered `priorScopes`
1458
1475
  * are `EvalScope` instances holding long-lived objects and are real
@@ -2080,9 +2097,11 @@ interface EvalDependencyTracker {
2080
2097
  * rules do the filtering:
2081
2098
  *
2082
2099
  * 1. **Scope bindings are not dependencies.** A read flagged `scoped` resolved
2083
- * from a scope pushed during the walk - an arrow-function parameter. Only
2084
- * the walker can tell one from a real context read, which is why the flag
2085
- * exists; a consumer using this tracker inherits the filtering for free.
2100
+ * from a scope on the context's scope stack, whoever pushed it - an
2101
+ * arrow-function parameter, a declaration in a program, block or `for`
2102
+ * scope, or a binding the caller pushed before the walk. Only the walker
2103
+ * can tell one from a real context read, which is why the flag exists; a
2104
+ * consumer using this tracker inherits the filtering for free.
2086
2105
  * 2. **Nor is anything reached *through* one.** `item` being a binding makes
2087
2106
  * `item.name` one too, and that read carries no flag of its own: `scoped` is
2088
2107
  * set at identifier resolution, and the member hop resolves against the
@@ -2160,6 +2179,7 @@ interface CacheType<TValue> extends RegistryType<string, TValue> {
2160
2179
  declare class ParserService implements OnDestroy {
2161
2180
  private _parserOptions;
2162
2181
  private _cache?;
2182
+ private readonly _fingerprints;
2163
2183
  private _cacheCleanupInterval?;
2164
2184
  private _isDestroyed;
2165
2185
  /**
@@ -2172,7 +2192,9 @@ declare class ParserService implements OnDestroy {
2172
2192
  */
2173
2193
  set parserOptions(value: ParserOptions);
2174
2194
  /**
2175
- * Constructs a new instance of the ParserService class.
2195
+ * Constructs a new instance of the ParserService class. Its options carry
2196
+ * `colonIdentifiers: true` when the injector constructing it holds
2197
+ * `provideColonIdentifiers()`, and no such key otherwise.
2176
2198
  */
2177
2199
  constructor();
2178
2200
  /**
@@ -2201,6 +2223,13 @@ declare class ParserService implements OnDestroy {
2201
2223
  * @returns The parsed AST (Abstract Syntax Tree).
2202
2224
  */
2203
2225
  parse(expr: string, options?: ParserOptions): Program | AnyNode | Expression | undefined;
2226
+ /**
2227
+ * Serves a cached AST only to a parse whose parse-relevant options match the
2228
+ * parse that cached it: the key is the text under a digest of the
2229
+ * fingerprint of the service's options and the call's, not the text alone
2230
+ * (`docs/backlog-retired.md` A26). A parse carrying a callback or a
2231
+ * `program` neither reads nor writes the cache.
2232
+ */
2204
2233
  private fromCacheOrParse;
2205
2234
  static ɵfac: i0.ɵɵFactoryDeclaration<ParserService, never>;
2206
2235
  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
@@ -2308,6 +2337,8 @@ declare class EvalService extends BaseEval implements OnDestroy {
2308
2337
  /**
2309
2338
  * @description
2310
2339
  * Parses expression and returns ES6/ES2020 AST.
2340
+ * With `colonIdentifiers` set the parser is the colon-joined name grammar's;
2341
+ * otherwise it is acorn's own `parse`.
2311
2342
  * @param expr expression to parse
2312
2343
  * @param options parser options
2313
2344
  */
@@ -2387,6 +2418,7 @@ declare class CompilerService extends BaseEval implements OnDestroy {
2387
2418
  private readonly _accessOrder;
2388
2419
  private _cacheCleanupInterval?;
2389
2420
  private _isDestroyed;
2421
+ private readonly _fingerprints;
2390
2422
  protected parserService: ParserService;
2391
2423
  protected evalService: EvalService;
2392
2424
  constructor();
@@ -2403,7 +2435,16 @@ declare class CompilerService extends BaseEval implements OnDestroy {
2403
2435
  */
2404
2436
  private cleanupCache;
2405
2437
  /**
2406
- * Generate cache key for expression
2438
+ * Generate cache key for expression. Only a string is cached, so only a
2439
+ * string has a key: the text under the digest of the options its parse
2440
+ * uses, `ParserService`'s merged with this service's, so a change through
2441
+ * the `ParserService.parserOptions` setter reaches a string compiled before
2442
+ * it (`docs/colon-identifiers/phase-9-plan.md` § 3.2). The memo is
2443
+ * `ParserService`'s kind, and a write in place goes unseen here as there
2444
+ * (`docs/backlog.md` A34). `null` when that parse bypasses `ParserService`'s
2445
+ * cache - a callback or a `program` among its options, or a value JSON
2446
+ * cannot hold - and this cache then bypasses too, since a cached function
2447
+ * runs no callback.
2407
2448
  */
2408
2449
  private generateCacheKey;
2409
2450
  /**
@@ -2411,7 +2452,9 @@ declare class CompilerService extends BaseEval implements OnDestroy {
2411
2452
  */
2412
2453
  private updateAccessOrder;
2413
2454
  /**
2414
- * Compiles the given expression into a state callback function with caching.
2455
+ * Compiles the given expression into a state callback function. A string is
2456
+ * compiled once and cached, unless its parse bypasses `ParserService`'s
2457
+ * cache; an AST is compiled on every call.
2415
2458
  * @param expression - The expression to compile.
2416
2459
  * @returns The compiled state callback function.
2417
2460
  * @throws Error if there is an error during compilation.
@@ -2436,7 +2479,9 @@ declare class CompilerService extends BaseEval implements OnDestroy {
2436
2479
  */
2437
2480
  call(fn: stateCallback | undefined, state: EvalState): unknown;
2438
2481
  /**
2439
- * Compiles the given expression into an asynchronous state callback function with caching.
2482
+ * Compiles the given expression into an asynchronous state callback
2483
+ * function. A string is compiled once and cached, unless its parse bypasses
2484
+ * `ParserService`'s cache; an AST is compiled on every call.
2440
2485
  * @param expression - The expression to compile.
2441
2486
  * @returns The compiled asynchronous state callback function.
2442
2487
  * @throws Error if there is an error during compilation.
@@ -2486,5 +2531,19 @@ declare class DiscoveryService extends BaseEval {
2486
2531
  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
2487
2532
  }
2488
2533
 
2489
- export { ASYNC_HOOK_MESSAGE, BaseRegistry, Cache, CaseInsensitiveRegistry, CompilerService, DiscoveryService, EMPTY_COMPLETION, EvalContext, EvalHooks, EvalResult, EvalScope, EvalService, EvalState, EvalTrace, ParserService, Registry, Stack, call, callAsync, compile, compileAsync, createDependencyTracker, createTimingHook, defaultParserOptions, evaluate, evaluateAsync, extract, extractExpression, fromContext, getContextValue, parse };
2534
+ /**
2535
+ * Turns `colonIdentifiers` on for every parse through `ParserService`, and so
2536
+ * through `EvalService`, `CompilerService` and `DiscoveryService`: a
2537
+ * colon-joined name such as `Q1:1:3` parses as one identifier and reads the
2538
+ * context key of that spelling. A per-call `colonIdentifiers` overrides it.
2539
+ *
2540
+ * Belongs in the application's root providers. `ParserService` is provided in
2541
+ * the root, so in a child environment injector - a lazy route's `providers` -
2542
+ * it would reach no parse; there it throws when that injector is created.
2543
+ *
2544
+ * @returns The providers, for the application's root providers.
2545
+ */
2546
+ declare function provideColonIdentifiers(): EnvironmentProviders;
2547
+
2548
+ export { ASYNC_HOOK_MESSAGE, BaseRegistry, Cache, CaseInsensitiveRegistry, CompilerService, DiscoveryService, EMPTY_COMPLETION, EvalContext, EvalHooks, EvalResult, EvalScope, EvalService, EvalState, EvalTrace, ParserService, Registry, Stack, call, callAsync, compile, compileAsync, createDependencyTracker, createTimingHook, defaultParserOptions, evaluate, evaluateAsync, extract, extractExpression, fromContext, getContextValue, parse, provideColonIdentifiers };
2490
2549
  export type { AnyNodeTypes, BaseContext, CacheType, Context, EvalDependencyTracker, EvalHookError, EvalHookErrorPolicy, EvalHookPhase, EvalKnownOptions, EvalLookup, EvalMemberWrite, EvalNodeHook, EvalNodeHookEvent, EvalNodeTiming, EvalOptions, EvalReadEvent, EvalReadHook, EvalReadKind, EvalScopeOptions, EvalTimingHook, EvalTraceItem, ParserOptions, RegistryEntries, RegistryType, StackType, Unsubscribe, stateCallback, stateCallbackAsync };