@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 +92 -2
- package/README.md +48 -1
- package/fesm2022/zvenigora-ng-eval-core.mjs +471 -156
- package/fesm2022/zvenigora-ng-eval-core.mjs.map +1 -1
- package/package.json +1 -1
- package/types/zvenigora-ng-eval-core.d.ts +76 -17
package/package.json
CHANGED
|
@@ -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
|
|
677
|
-
*
|
|
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
|
|
742
|
-
*
|
|
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
|
|
1453
|
-
* `EvalContext.
|
|
1454
|
-
*
|
|
1455
|
-
*
|
|
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
|
|
2084
|
-
*
|
|
2085
|
-
*
|
|
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
|
|
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
|
|
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
|
-
|
|
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 };
|