@zvenigora/ng-eval-core 0.14.0 → 0.15.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 +149 -1
- package/README.md +43 -7
- package/fesm2022/zvenigora-ng-eval-core.mjs +741 -503
- package/fesm2022/zvenigora-ng-eval-core.mjs.map +1 -1
- package/package.json +1 -1
- package/types/zvenigora-ng-eval-core.d.ts +112 -33
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import * as i0 from '@angular/core';
|
|
2
2
|
import { OnDestroy, EnvironmentProviders } from '@angular/core';
|
|
3
3
|
import * as acorn from 'acorn';
|
|
4
|
-
import { AnyNode, Program, Expression } from 'acorn';
|
|
4
|
+
import { AnyNode, Program, Expression, Statement, ModuleDeclaration } from 'acorn';
|
|
5
5
|
|
|
6
6
|
type ParserOptions = Partial<acorn.Options> & {
|
|
7
7
|
extractExpressions?: boolean;
|
|
@@ -955,6 +955,22 @@ declare class EvalTrace extends Array<EvalTraceItem> {
|
|
|
955
955
|
type UnknownValue = unknown | Promise<unknown>;
|
|
956
956
|
/**
|
|
957
957
|
* Represents the result of an evaluation.
|
|
958
|
+
*
|
|
959
|
+
* **The outcome describes the last entry-point walk on the state**: its
|
|
960
|
+
* {@link value}, {@link error}, {@link errorMessage}, {@link isSuccess},
|
|
961
|
+
* {@link isError}, {@link isUndefined} and {@link duration}. Each entry point
|
|
962
|
+
* resets the outcome when its walk starts and writes it when the walk ends - for
|
|
963
|
+
* `evalAsync` and its kin, once the result's promises have settled, so between
|
|
964
|
+
* return and settlement a walk that did not throw reports neither success nor
|
|
965
|
+
* failure. An arrow function's body runs a walk of its own on the same state,
|
|
966
|
+
* and it changes nothing here: not while the enclosing walk runs, and not when
|
|
967
|
+
* a function the walk built is called later. Up to 0.14.1 it overwrote all of it
|
|
968
|
+
* (`docs/backlog-retired.md` A27). Two `evalAsync` runs interleaved on one
|
|
969
|
+
* state share one outcome: the later start resets it, and the last to settle
|
|
970
|
+
* writes it.
|
|
971
|
+
*
|
|
972
|
+
* The {@link trace} is not part of the outcome: it spans every evaluation run on
|
|
973
|
+
* the state, and only {@link clearTrace} resets it.
|
|
958
974
|
*/
|
|
959
975
|
declare class EvalResult {
|
|
960
976
|
private _stack;
|
|
@@ -976,27 +992,35 @@ declare class EvalResult {
|
|
|
976
992
|
*/
|
|
977
993
|
get stack(): Stack<UnknownValue>;
|
|
978
994
|
/**
|
|
979
|
-
* Gets the evaluated value
|
|
995
|
+
* Gets the evaluated value: the last entry-point walk's, and `undefined`
|
|
996
|
+
* once that walk failed or while it is pending.
|
|
980
997
|
*/
|
|
981
998
|
get value(): UnknownValue | undefined;
|
|
982
999
|
/**
|
|
983
|
-
* Gets the error
|
|
1000
|
+
* Gets the error the last entry-point walk failed with, and `undefined` once
|
|
1001
|
+
* it succeeded or while it is pending. An error an arrow function's body
|
|
1002
|
+
* threw and something in the walk caught is not the walk's.
|
|
984
1003
|
*/
|
|
985
1004
|
get error(): unknown | undefined;
|
|
986
1005
|
/**
|
|
987
|
-
* Gets
|
|
1006
|
+
* Gets {@link error}'s message when it is an `Error`, and `undefined`
|
|
1007
|
+
* otherwise.
|
|
988
1008
|
*/
|
|
989
1009
|
get errorMessage(): string | undefined;
|
|
990
1010
|
/**
|
|
991
|
-
* Gets whether the
|
|
1011
|
+
* Gets whether the last entry-point walk failed: `undefined` while it is
|
|
1012
|
+
* pending.
|
|
992
1013
|
*/
|
|
993
1014
|
get isError(): boolean | undefined;
|
|
994
1015
|
/**
|
|
995
|
-
* Gets whether the
|
|
1016
|
+
* Gets whether the last entry-point walk succeeded: `undefined` while it is
|
|
1017
|
+
* pending.
|
|
996
1018
|
*/
|
|
997
1019
|
get isSuccess(): boolean | undefined;
|
|
998
1020
|
/**
|
|
999
|
-
* Gets whether
|
|
1021
|
+
* Gets whether {@link value} is `undefined`, once the last entry-point walk
|
|
1022
|
+
* has ended - including after a failure, which clears the value. `undefined`
|
|
1023
|
+
* while it is pending.
|
|
1000
1024
|
*/
|
|
1001
1025
|
get isUndefined(): boolean | undefined;
|
|
1002
1026
|
/**
|
|
@@ -1035,7 +1059,8 @@ declare class EvalResult {
|
|
|
1035
1059
|
*/
|
|
1036
1060
|
get options(): EvalOptions;
|
|
1037
1061
|
/**
|
|
1038
|
-
* Gets the duration of the
|
|
1062
|
+
* Gets the duration of the last entry-point walk, an arrow function's body
|
|
1063
|
+
* called inside it included: `undefined` while it is pending.
|
|
1039
1064
|
* @returns The duration in milliseconds.
|
|
1040
1065
|
*/
|
|
1041
1066
|
get duration(): number | undefined;
|
|
@@ -1105,7 +1130,14 @@ declare class EvalResult {
|
|
|
1105
1130
|
*/
|
|
1106
1131
|
clearTrace(): void;
|
|
1107
1132
|
/**
|
|
1108
|
-
* Starts the evaluation process
|
|
1133
|
+
* Starts the evaluation process, and resets the outcome: {@link value},
|
|
1134
|
+
* {@link error}, {@link errorMessage}, {@link isSuccess}, {@link isError},
|
|
1135
|
+
* {@link isUndefined} and {@link duration} read `undefined` until the walk
|
|
1136
|
+
* ends. Leaves the
|
|
1137
|
+
* {@link trace}, {@link tracePushCount} and {@link traceTruncated} alone,
|
|
1138
|
+
* since the trace spans every evaluation on the state (`docs/backlog.md`
|
|
1139
|
+
* A15). Up to 0.14.1 it reset nothing, so a reused state reported the last
|
|
1140
|
+
* run's error until something overwrote it (A27).
|
|
1109
1141
|
*/
|
|
1110
1142
|
start(): void;
|
|
1111
1143
|
/**
|
|
@@ -1113,14 +1145,17 @@ declare class EvalResult {
|
|
|
1113
1145
|
*/
|
|
1114
1146
|
stop(): number | undefined;
|
|
1115
1147
|
/**
|
|
1116
|
-
* Sets the success value of the evaluation result
|
|
1148
|
+
* Sets the success value of the evaluation result, writing every outcome
|
|
1149
|
+
* field: the error and its message are cleared.
|
|
1117
1150
|
*
|
|
1118
1151
|
* @param value The value to set as the success value.
|
|
1119
1152
|
* @returns void
|
|
1120
1153
|
*/
|
|
1121
1154
|
setSuccess(value: UnknownValue): void;
|
|
1122
1155
|
/**
|
|
1123
|
-
* Sets the failure state of the evaluation result
|
|
1156
|
+
* Sets the failure state of the evaluation result, writing every outcome
|
|
1157
|
+
* field: the value is cleared, and the message is the error's when it is an
|
|
1158
|
+
* `Error`.
|
|
1124
1159
|
* @param error The error object associated with the failure.
|
|
1125
1160
|
*/
|
|
1126
1161
|
setFailure(error: unknown): void;
|
|
@@ -1218,10 +1253,9 @@ declare class EvalState {
|
|
|
1218
1253
|
*/
|
|
1219
1254
|
get hookBookkeeping(): EvalHookBookkeeping;
|
|
1220
1255
|
/**
|
|
1221
|
-
* How many
|
|
1222
|
-
*
|
|
1223
|
-
*
|
|
1224
|
-
* `evaluate` on this same state.
|
|
1256
|
+
* How many walks on this state are currently on the JavaScript stack: 0
|
|
1257
|
+
* between evaluations, 1 during an ordinary walk, and more while a nested
|
|
1258
|
+
* walk runs - an arrow-function body is a re-entrant walk on this same state.
|
|
1225
1259
|
*
|
|
1226
1260
|
* Maintained by {@link enterWalk} / {@link exitWalk}, which the entry points
|
|
1227
1261
|
* pair around their walk, the exit in a `finally` so a throw still restores
|
|
@@ -1550,10 +1584,10 @@ interface EvalHookBookkeeping {
|
|
|
1550
1584
|
*/
|
|
1551
1585
|
readonly timings: Map<AnyNodeTypes, EvalNodeTiming>;
|
|
1552
1586
|
/**
|
|
1553
|
-
* One entry per
|
|
1554
|
-
* {@link open} depth that
|
|
1587
|
+
* One entry per walk currently on the JavaScript stack: the
|
|
1588
|
+
* {@link open} depth that walk found when it started, innermost last.
|
|
1555
1589
|
*
|
|
1556
|
-
*
|
|
1590
|
+
* The walk already captured this as a local to hand to
|
|
1557
1591
|
* {@link EvalHooks.unwindTo}; it lives here as well because {@link
|
|
1558
1592
|
* EvalHooks.exit} needs it too and is called from a visitor, which has no
|
|
1559
1593
|
* route to that local. Without it `exit` cannot tell "absent from this walk"
|
|
@@ -1758,7 +1792,7 @@ declare class EvalHooks {
|
|
|
1758
1792
|
* **"Open" means open in *this* walk.** Both routes below are bounded by the
|
|
1759
1793
|
* current walk base ({@link EvalHookBookkeeping.walkBases}), so a node open
|
|
1760
1794
|
* only in an enclosing walk falls into case 3 by either route - which is the
|
|
1761
|
-
* behaviour case 3 already specifies for "not open at all".
|
|
1795
|
+
* behaviour case 3 already specifies for "not open at all". The walk is
|
|
1762
1796
|
* re-entered with the same state from an arrow-function body, so without the
|
|
1763
1797
|
* bound a nested walk closing a node it never opened would flush the
|
|
1764
1798
|
* enclosing walk's frames under `completed: false` events a consumer reads as
|
|
@@ -1791,7 +1825,7 @@ declare class EvalHooks {
|
|
|
1791
1825
|
exit(state: EvalState, node: AnyNode): void;
|
|
1792
1826
|
/**
|
|
1793
1827
|
* How many nodes the state has open. Captured as a mark before a walk, since
|
|
1794
|
-
*
|
|
1828
|
+
* the walk is re-entered with the same state from an arrow-function body.
|
|
1795
1829
|
*
|
|
1796
1830
|
* This is a method rather than a getter because the stack it measures lives
|
|
1797
1831
|
* on the state, not on this registry.
|
|
@@ -1799,18 +1833,19 @@ declare class EvalHooks {
|
|
|
1799
1833
|
depth(state: EvalState): number;
|
|
1800
1834
|
/**
|
|
1801
1835
|
* Records that a walk is starting at the state's current open depth, and
|
|
1802
|
-
* returns that depth. Called by
|
|
1803
|
-
*
|
|
1836
|
+
* returns that depth. Called on entry by every walk - `evaluate`'s, an
|
|
1837
|
+
* arrow-function body's and `evaluateAsync`'s - under a `hasHooks` guard,
|
|
1838
|
+
* and paired with {@link popWalkBase} in a `finally`.
|
|
1804
1839
|
*
|
|
1805
|
-
* The returned value is the same mark those
|
|
1840
|
+
* The returned value is the same mark those walks hand to
|
|
1806
1841
|
* {@link unwindTo}, so they capture it once rather than reading the depth
|
|
1807
1842
|
* twice.
|
|
1808
1843
|
*/
|
|
1809
1844
|
pushWalkBase(state: EvalState): number;
|
|
1810
1845
|
/**
|
|
1811
|
-
* Drops the innermost walk base. Called from the `finally` of the
|
|
1812
|
-
*
|
|
1813
|
-
*
|
|
1846
|
+
* Drops the innermost walk base. Called from the `finally` of the walk that
|
|
1847
|
+
* pushed it, so a walk that threw still restores the enclosing walk's
|
|
1848
|
+
* bound.
|
|
1814
1849
|
*/
|
|
1815
1850
|
popWalkBase(state: EvalState): void;
|
|
1816
1851
|
/**
|
|
@@ -1824,12 +1859,12 @@ declare class EvalHooks {
|
|
|
1824
1859
|
walkBase(state: EvalState): number;
|
|
1825
1860
|
/**
|
|
1826
1861
|
* Fires 'after' for every node the state has open above `mark`, innermost
|
|
1827
|
-
* first, marked incomplete. Invoked from the catch
|
|
1862
|
+
* first, marked incomplete. Invoked from the catch of every walk, so that a
|
|
1828
1863
|
* visitor which throws still leaves every 'before' matched by exactly one
|
|
1829
1864
|
* 'after'.
|
|
1830
1865
|
*
|
|
1831
1866
|
* Unwinding to a mark rather than to the bottom is what keeps a nested
|
|
1832
|
-
*
|
|
1867
|
+
* walk from draining the enclosing walk's open nodes when a host
|
|
1833
1868
|
* function swallows the nested throw.
|
|
1834
1869
|
*
|
|
1835
1870
|
* Idempotent, so the sync and async entry points can both call it.
|
|
@@ -1921,7 +1956,7 @@ type EvalKnownOptions = {
|
|
|
1921
1956
|
* returned a partial value is the failure this exists to prevent - so
|
|
1922
1957
|
* exceeding it raises `Iteration budget exhausted after <n> iterations`.
|
|
1923
1958
|
*
|
|
1924
|
-
* **Per outermost
|
|
1959
|
+
* **Per outermost walk, not per loop and not per state.** Per loop
|
|
1925
1960
|
* would not be a bound at all: two nested loops at 100,000 each is 10^10
|
|
1926
1961
|
* iterations. Per state would erode one budget across the independent
|
|
1927
1962
|
* evaluations of the `createState` + repeated `eval` style, and would leave an
|
|
@@ -1984,7 +2019,7 @@ type EvalKnownOptions = {
|
|
|
1984
2019
|
* unbounded behaviour exactly. Both are honoured rather than treated as
|
|
1985
2020
|
* falsy or as opt-outs, the same way {@link maxIterations} honours them.
|
|
1986
2021
|
*
|
|
1987
|
-
* Re-read on each outermost
|
|
2022
|
+
* Re-read on each outermost walk rather than once, because the
|
|
1988
2023
|
* options are a mutable record the caller keeps a reference to - the same
|
|
1989
2024
|
* reason, and the same moment, as {@link maxIterations}' refill.
|
|
1990
2025
|
*/
|
|
@@ -2183,11 +2218,29 @@ declare class ParserService implements OnDestroy {
|
|
|
2183
2218
|
private _cacheCleanupInterval?;
|
|
2184
2219
|
private _isDestroyed;
|
|
2185
2220
|
/**
|
|
2186
|
-
* Gets the parser options
|
|
2221
|
+
* Gets the parser options: the constructor's, or the last value given to
|
|
2222
|
+
* the setter.
|
|
2187
2223
|
*/
|
|
2188
2224
|
get parserOptions(): ParserOptions;
|
|
2189
2225
|
/**
|
|
2190
|
-
* Sets the parser options.
|
|
2226
|
+
* Sets the parser options for direct `ParserService.parse` calls, which
|
|
2227
|
+
* merge the options they are given over this value, the call's key winning,
|
|
2228
|
+
* for every key but `cacheSize`.
|
|
2229
|
+
*
|
|
2230
|
+
* `EvalService`, `CompilerService` and `DiscoveryService` pass their own
|
|
2231
|
+
* options on every parse, and those carry every key of
|
|
2232
|
+
* `defaultParserOptions`, so for each of them the service's key wins over
|
|
2233
|
+
* this value, `cacheSize` again aside. Only `cacheSize` and a key
|
|
2234
|
+
* `defaultParserOptions` does not carry reach those services through the
|
|
2235
|
+
* setter: `colonIdentifiers` is the one the README relies on
|
|
2236
|
+
* (`docs/backlog-retired.md` A30).
|
|
2237
|
+
*
|
|
2238
|
+
* `cacheSize` is read from this value alone, never from a call's or a
|
|
2239
|
+
* service's options. It sizes the parse cache once, at construction, and a
|
|
2240
|
+
* later value does not resize it. Whether a parse uses the cache is read
|
|
2241
|
+
* from it on every parse, so a later falsy one stops every parse using the
|
|
2242
|
+
* cache, the services' included.
|
|
2243
|
+
*
|
|
2191
2244
|
* @param value The parser options to set.
|
|
2192
2245
|
*/
|
|
2193
2246
|
set parserOptions(value: ParserOptions);
|
|
@@ -2353,6 +2406,10 @@ declare const extractExpression: (program: Program) => Expression | undefined;
|
|
|
2353
2406
|
/**
|
|
2354
2407
|
* Evaluates the given node and returns the result.
|
|
2355
2408
|
*
|
|
2409
|
+
* Records the walk's outcome on `state.result`. An arrow function's body,
|
|
2410
|
+
* walked on the same state whenever the function is called, records nothing
|
|
2411
|
+
* there.
|
|
2412
|
+
*
|
|
2356
2413
|
* @param node The node to evaluate.
|
|
2357
2414
|
* @param state The evaluation state.
|
|
2358
2415
|
* @returns The result of the evaluation.
|
|
@@ -2407,6 +2464,28 @@ declare const callAsync: (fn: stateCallbackAsync, state: EvalState) => Promise<u
|
|
|
2407
2464
|
*/
|
|
2408
2465
|
declare const extract: (node: AnyNode | undefined, searchType: AnyNodeTypes) => AnyNode[] | undefined;
|
|
2409
2466
|
|
|
2467
|
+
/**
|
|
2468
|
+
* Finds the first statement in a tree that evaluation would refuse.
|
|
2469
|
+
*
|
|
2470
|
+
* Evaluation refuses a statement only when the walk reaches it, so one in an
|
|
2471
|
+
* arrow function's body that is never called, or in a branch not taken, throws
|
|
2472
|
+
* nothing. This reads the whole tree instead - function bodies, untaken
|
|
2473
|
+
* branches and class bodies included - against the same table the evaluator
|
|
2474
|
+
* uses, and returns the message evaluation throws for that statement.
|
|
2475
|
+
*
|
|
2476
|
+
* "First" is source order, the lowest `start`, so a refused statement inside
|
|
2477
|
+
* another refused one is reported after it, as evaluation would meet the outer
|
|
2478
|
+
* one first.
|
|
2479
|
+
*
|
|
2480
|
+
* @param node The AST to search, as `parse` returns it.
|
|
2481
|
+
* @returns The statement and its message, or `undefined` when the tree holds
|
|
2482
|
+
* none, or `node` is `undefined`.
|
|
2483
|
+
*/
|
|
2484
|
+
declare const findUnsupportedStatement: (node: AnyNode | undefined) => {
|
|
2485
|
+
statement: Statement | ModuleDeclaration;
|
|
2486
|
+
message: string;
|
|
2487
|
+
} | undefined;
|
|
2488
|
+
|
|
2410
2489
|
/**
|
|
2411
2490
|
* CompilerService class that extends BaseEval.
|
|
2412
2491
|
* Provides methods for compiling and evaluating expressions with performance caching.
|
|
@@ -2545,5 +2624,5 @@ declare class DiscoveryService extends BaseEval {
|
|
|
2545
2624
|
*/
|
|
2546
2625
|
declare function provideColonIdentifiers(): EnvironmentProviders;
|
|
2547
2626
|
|
|
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 };
|
|
2627
|
+
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, findUnsupportedStatement, fromContext, getContextValue, parse, provideColonIdentifiers };
|
|
2549
2628
|
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 };
|