@zvenigora/ng-eval-core 0.14.1 → 0.15.1
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 +144 -2
- package/README.md +44 -8
- package/fesm2022/zvenigora-ng-eval-core.mjs +753 -481
- package/fesm2022/zvenigora-ng-eval-core.mjs.map +1 -1
- package/package.json +1 -1
- package/types/zvenigora-ng-eval-core.d.ts +115 -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
|
*/
|
|
@@ -2018,6 +2053,15 @@ type EvalKnownOptions = {
|
|
|
2018
2053
|
onHookError?: EvalHookErrorPolicy;
|
|
2019
2054
|
};
|
|
2020
2055
|
|
|
2056
|
+
/**
|
|
2057
|
+
* The options `EvalService` and `CompilerService` pass on every parse, as
|
|
2058
|
+
* this object itself; `ParserService` and `DiscoveryService` copy it when
|
|
2059
|
+
* constructed. Read it or copy it; do not write into it. A value written into
|
|
2060
|
+
* it is not reliably seen: the parse cache remembers it by identity, so a text
|
|
2061
|
+
* cached before the write can keep its reading, and one parsed while it held
|
|
2062
|
+
* the value can keep that reading after it is written back
|
|
2063
|
+
* (`docs/backlog-retired.md` A34).
|
|
2064
|
+
*/
|
|
2021
2065
|
declare const defaultParserOptions: ParserOptions;
|
|
2022
2066
|
|
|
2023
2067
|
/**
|
|
@@ -2185,6 +2229,15 @@ declare class ParserService implements OnDestroy {
|
|
|
2185
2229
|
/**
|
|
2186
2230
|
* Gets the parser options: the constructor's, or the last value given to
|
|
2187
2231
|
* the setter.
|
|
2232
|
+
*
|
|
2233
|
+
* Replace the object through the setter rather than write into the one this
|
|
2234
|
+
* returns: a value written into it is not reliably seen. The parse cache,
|
|
2235
|
+
* and `CompilerService`'s cache of compiled strings, remember each pair of
|
|
2236
|
+
* options objects, this one and a call's, by identity, not by their values.
|
|
2237
|
+
* A later parse through a pair seen before the write, as `EvalService`'s and
|
|
2238
|
+
* `CompilerService`'s are, keeps a cached text's earlier reading and caches
|
|
2239
|
+
* a new text as if the options had not changed; a parse through a new
|
|
2240
|
+
* call-options object sees the write (`docs/backlog-retired.md` A34).
|
|
2188
2241
|
*/
|
|
2189
2242
|
get parserOptions(): ParserOptions;
|
|
2190
2243
|
/**
|
|
@@ -2237,7 +2290,10 @@ declare class ParserService implements OnDestroy {
|
|
|
2237
2290
|
* @description
|
|
2238
2291
|
* Parses expression and returns ES6/ES2023 AST.
|
|
2239
2292
|
* @param expr expression to parse
|
|
2240
|
-
* @param options optional parser options
|
|
2293
|
+
* @param options optional parser options, merged over `parserOptions`. Pass
|
|
2294
|
+
* a new object for new options: a value written into an object already
|
|
2295
|
+
* passed is not reliably seen, since the cache remembers the object by
|
|
2296
|
+
* identity (`docs/backlog-retired.md` A34).
|
|
2241
2297
|
* @returns The parsed AST (Abstract Syntax Tree).
|
|
2242
2298
|
*/
|
|
2243
2299
|
parse(expr: string, options?: ParserOptions): Program | AnyNode | Expression | undefined;
|
|
@@ -2371,6 +2427,10 @@ declare const extractExpression: (program: Program) => Expression | undefined;
|
|
|
2371
2427
|
/**
|
|
2372
2428
|
* Evaluates the given node and returns the result.
|
|
2373
2429
|
*
|
|
2430
|
+
* Records the walk's outcome on `state.result`. An arrow function's body,
|
|
2431
|
+
* walked on the same state whenever the function is called, records nothing
|
|
2432
|
+
* there.
|
|
2433
|
+
*
|
|
2374
2434
|
* @param node The node to evaluate.
|
|
2375
2435
|
* @param state The evaluation state.
|
|
2376
2436
|
* @returns The result of the evaluation.
|
|
@@ -2425,6 +2485,28 @@ declare const callAsync: (fn: stateCallbackAsync, state: EvalState) => Promise<u
|
|
|
2425
2485
|
*/
|
|
2426
2486
|
declare const extract: (node: AnyNode | undefined, searchType: AnyNodeTypes) => AnyNode[] | undefined;
|
|
2427
2487
|
|
|
2488
|
+
/**
|
|
2489
|
+
* Finds the first statement in a tree that evaluation would refuse.
|
|
2490
|
+
*
|
|
2491
|
+
* Evaluation refuses a statement only when the walk reaches it, so one in an
|
|
2492
|
+
* arrow function's body that is never called, or in a branch not taken, throws
|
|
2493
|
+
* nothing. This reads the whole tree instead - function bodies, untaken
|
|
2494
|
+
* branches and class bodies included - against the same table the evaluator
|
|
2495
|
+
* uses, and returns the message evaluation throws for that statement.
|
|
2496
|
+
*
|
|
2497
|
+
* "First" is source order, the lowest `start`, so a refused statement inside
|
|
2498
|
+
* another refused one is reported after it, as evaluation would meet the outer
|
|
2499
|
+
* one first.
|
|
2500
|
+
*
|
|
2501
|
+
* @param node The AST to search, as `parse` returns it.
|
|
2502
|
+
* @returns The statement and its message, or `undefined` when the tree holds
|
|
2503
|
+
* none, or `node` is `undefined`.
|
|
2504
|
+
*/
|
|
2505
|
+
declare const findUnsupportedStatement: (node: AnyNode | undefined) => {
|
|
2506
|
+
statement: Statement | ModuleDeclaration;
|
|
2507
|
+
message: string;
|
|
2508
|
+
} | undefined;
|
|
2509
|
+
|
|
2428
2510
|
/**
|
|
2429
2511
|
* CompilerService class that extends BaseEval.
|
|
2430
2512
|
* Provides methods for compiling and evaluating expressions with performance caching.
|
|
@@ -2459,7 +2541,7 @@ declare class CompilerService extends BaseEval implements OnDestroy {
|
|
|
2459
2541
|
* the `ParserService.parserOptions` setter reaches a string compiled before
|
|
2460
2542
|
* it (`docs/colon-identifiers/phase-9-plan.md` § 3.2). The memo is
|
|
2461
2543
|
* `ParserService`'s kind, and a write in place goes unseen here as there
|
|
2462
|
-
* (`docs/backlog.md` A34). `null` when that parse bypasses `ParserService`'s
|
|
2544
|
+
* (`docs/backlog-retired.md` A34). `null` when that parse bypasses `ParserService`'s
|
|
2463
2545
|
* cache - a callback or a `program` among its options, or a value JSON
|
|
2464
2546
|
* cannot hold - and this cache then bypasses too, since a cached function
|
|
2465
2547
|
* runs no callback.
|
|
@@ -2563,5 +2645,5 @@ declare class DiscoveryService extends BaseEval {
|
|
|
2563
2645
|
*/
|
|
2564
2646
|
declare function provideColonIdentifiers(): EnvironmentProviders;
|
|
2565
2647
|
|
|
2566
|
-
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 };
|
|
2648
|
+
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 };
|
|
2567
2649
|
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 };
|