@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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zvenigora/ng-eval-core",
3
- "version": "0.14.1",
3
+ "version": "0.15.1",
4
4
  "description": "An expression evaluator for Angular",
5
5
  "repository": {
6
6
  "type": "git",
@@ -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 that occurred during evaluation.
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 the error message associated with the evaluation error.
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 evaluation resulted in an error.
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 evaluation was successful.
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 the evaluated value is undefined.
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 evaluation result.
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 `evaluate` / `evaluateAsync` calls on this state are currently on
1222
- * the JavaScript stack: 0 between evaluations, 1 during an ordinary walk, and
1223
- * more while a nested walk runs - an arrow-function body is re-entrant
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 `evaluate` call currently on the JavaScript stack: the
1554
- * {@link open} depth that call found when it started, innermost last.
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
- * `evaluate` already captured this as a local to hand to
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". `evaluate` is
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
- * `evaluate` is re-entered with the same state from an arrow-function body.
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 `evaluate` / `evaluateAsync` on entry, under
1803
- * their `hasHooks` guard, and paired with {@link popWalkBase} in a `finally`.
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 entry points hand to
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 `evaluate`
1812
- * that pushed it, so an entry point whose walk threw still restores the
1813
- * enclosing walk's bound.
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 in `evaluate`, so that a
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
- * `evaluate` from draining the enclosing walk's open nodes when a host
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 `evaluate` call, not per loop and not per state.** Per loop
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 `evaluate` call rather than once, because the
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 };