@zvenigora/ng-eval-core 0.11.1 → 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.1",
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
 
@@ -2168,6 +2179,7 @@ interface CacheType<TValue> extends RegistryType<string, TValue> {
2168
2179
  declare class ParserService implements OnDestroy {
2169
2180
  private _parserOptions;
2170
2181
  private _cache?;
2182
+ private readonly _fingerprints;
2171
2183
  private _cacheCleanupInterval?;
2172
2184
  private _isDestroyed;
2173
2185
  /**
@@ -2180,7 +2192,9 @@ declare class ParserService implements OnDestroy {
2180
2192
  */
2181
2193
  set parserOptions(value: ParserOptions);
2182
2194
  /**
2183
- * 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.
2184
2198
  */
2185
2199
  constructor();
2186
2200
  /**
@@ -2209,6 +2223,13 @@ declare class ParserService implements OnDestroy {
2209
2223
  * @returns The parsed AST (Abstract Syntax Tree).
2210
2224
  */
2211
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
+ */
2212
2233
  private fromCacheOrParse;
2213
2234
  static ɵfac: i0.ɵɵFactoryDeclaration<ParserService, never>;
2214
2235
  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
@@ -2316,6 +2337,8 @@ declare class EvalService extends BaseEval implements OnDestroy {
2316
2337
  /**
2317
2338
  * @description
2318
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`.
2319
2342
  * @param expr expression to parse
2320
2343
  * @param options parser options
2321
2344
  */
@@ -2395,6 +2418,7 @@ declare class CompilerService extends BaseEval implements OnDestroy {
2395
2418
  private readonly _accessOrder;
2396
2419
  private _cacheCleanupInterval?;
2397
2420
  private _isDestroyed;
2421
+ private readonly _fingerprints;
2398
2422
  protected parserService: ParserService;
2399
2423
  protected evalService: EvalService;
2400
2424
  constructor();
@@ -2412,7 +2436,15 @@ declare class CompilerService extends BaseEval implements OnDestroy {
2412
2436
  private cleanupCache;
2413
2437
  /**
2414
2438
  * Generate cache key for expression. Only a string is cached, so only a
2415
- * string has a key.
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.
2416
2448
  */
2417
2449
  private generateCacheKey;
2418
2450
  /**
@@ -2421,7 +2453,8 @@ declare class CompilerService extends BaseEval implements OnDestroy {
2421
2453
  private updateAccessOrder;
2422
2454
  /**
2423
2455
  * Compiles the given expression into a state callback function. A string is
2424
- * compiled once and cached; an AST is compiled on every call.
2456
+ * compiled once and cached, unless its parse bypasses `ParserService`'s
2457
+ * cache; an AST is compiled on every call.
2425
2458
  * @param expression - The expression to compile.
2426
2459
  * @returns The compiled state callback function.
2427
2460
  * @throws Error if there is an error during compilation.
@@ -2447,8 +2480,8 @@ declare class CompilerService extends BaseEval implements OnDestroy {
2447
2480
  call(fn: stateCallback | undefined, state: EvalState): unknown;
2448
2481
  /**
2449
2482
  * Compiles the given expression into an asynchronous state callback
2450
- * function. A string is compiled once and cached; an AST is compiled on
2451
- * every call.
2483
+ * function. A string is compiled once and cached, unless its parse bypasses
2484
+ * `ParserService`'s cache; an AST is compiled on every call.
2452
2485
  * @param expression - The expression to compile.
2453
2486
  * @returns The compiled asynchronous state callback function.
2454
2487
  * @throws Error if there is an error during compilation.
@@ -2498,5 +2531,19 @@ declare class DiscoveryService extends BaseEval {
2498
2531
  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
2499
2532
  }
2500
2533
 
2501
- 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 };
2502
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 };