@zvenigora/ng-eval-core 0.5.0 → 0.6.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 +539 -0
- package/README.md +39 -3
- package/fesm2022/zvenigora-ng-eval-core.mjs +196 -87
- package/fesm2022/zvenigora-ng-eval-core.mjs.map +1 -1
- package/package.json +2 -2
- package/types/zvenigora-ng-eval-core.d.ts +173 -25
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zvenigora/ng-eval-core",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.1",
|
|
4
4
|
"description": "An expression evaluator for Angular",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
"@angular/core": ">=19.0.0",
|
|
18
18
|
"acorn": "^8.11.2",
|
|
19
19
|
"acorn-walk": "^8.3.0",
|
|
20
|
-
"js-sha256": "^0.10.1"
|
|
20
|
+
"js-sha256": "^0.10.1 || ^0.11.0 || ^0.12.0 || ^1.0.0"
|
|
21
21
|
},
|
|
22
22
|
"dependencies": {
|
|
23
23
|
"tslib": "^2.3.0"
|
|
@@ -816,7 +816,17 @@ declare class EvalContext {
|
|
|
816
816
|
}
|
|
817
817
|
|
|
818
818
|
interface EvalTraceItem {
|
|
819
|
+
/**
|
|
820
|
+
* Reserved, and never set: no item this library produces carries a value
|
|
821
|
+
* here, and none has since the field was declared (`docs/backlog.md` A16).
|
|
822
|
+
* It is neither a source offset nor a timestamp. For the node's source text
|
|
823
|
+
* read `expression`; for timing totals per node type, `EvalState.nodeTimings`,
|
|
824
|
+
* filled under `trackTime`.
|
|
825
|
+
*/
|
|
819
826
|
start?: number;
|
|
827
|
+
/**
|
|
828
|
+
* Reserved, and never set - as `start`.
|
|
829
|
+
*/
|
|
820
830
|
end?: number;
|
|
821
831
|
type: string;
|
|
822
832
|
expression?: string;
|
|
@@ -848,6 +858,8 @@ declare class EvalResult {
|
|
|
848
858
|
private _isSuccess?;
|
|
849
859
|
private _isUndefined?;
|
|
850
860
|
private _trace;
|
|
861
|
+
private _tracePushCount;
|
|
862
|
+
private _traceTruncated;
|
|
851
863
|
private _context;
|
|
852
864
|
private _startDate?;
|
|
853
865
|
private _endDate?;
|
|
@@ -884,6 +896,29 @@ declare class EvalResult {
|
|
|
884
896
|
* Gets the trace of evaluated values.
|
|
885
897
|
*/
|
|
886
898
|
get trace(): EvalTrace;
|
|
899
|
+
/**
|
|
900
|
+
* Whether {@link trace} stopped short of everything this state pushed,
|
|
901
|
+
* because `options.maxTraceItems` was reached.
|
|
902
|
+
*
|
|
903
|
+
* **Latches.** Once true it stays true until {@link clearTrace}, however many
|
|
904
|
+
* evaluations run in between, because the trace does: it spans every
|
|
905
|
+
* evaluation run on this result, so a flag that cleared per walk would
|
|
906
|
+
* describe a different array than the one beside it.
|
|
907
|
+
*
|
|
908
|
+
* False under `maxTraceItems: 0`, which is a caller asking for no trace
|
|
909
|
+
* rather than a trace that lost something.
|
|
910
|
+
*/
|
|
911
|
+
get traceTruncated(): boolean;
|
|
912
|
+
/**
|
|
913
|
+
* How many values were pushed for tracing since this result was built or last
|
|
914
|
+
* cleared by {@link clearTrace} - which is what {@link trace} no longer tells
|
|
915
|
+
* you once {@link traceTruncated} is set.
|
|
916
|
+
*
|
|
917
|
+
* Counts pushes, not entries kept, so it goes on rising past the bound, and
|
|
918
|
+
* it stays accurate under `maxTraceItems: 0` - a caller who disabled tracing
|
|
919
|
+
* for the allocation still gets the walk-size figure.
|
|
920
|
+
*/
|
|
921
|
+
get tracePushCount(): number;
|
|
887
922
|
/**
|
|
888
923
|
* Gets the evaluation context.
|
|
889
924
|
*/
|
|
@@ -914,6 +949,54 @@ declare class EvalResult {
|
|
|
914
949
|
* @param context The evaluation context.
|
|
915
950
|
*/
|
|
916
951
|
constructor(context: EvalContext);
|
|
952
|
+
/**
|
|
953
|
+
* Records one traced push against `limit`, adding it to {@link trace} only
|
|
954
|
+
* while there is room.
|
|
955
|
+
*
|
|
956
|
+
* **The bound is the caller's, and that is the point.** `limit` arrives from
|
|
957
|
+
* `EvalState.maxTraceItems` - the *walk's* options - because this object
|
|
958
|
+
* cannot read them: {@link options} returns `this._context.options`, and a
|
|
959
|
+
* context can be handed to any number of evaluations carrying options none
|
|
960
|
+
* of them used. Reading the bound here would reproduce the split `CLAUDE.md`
|
|
961
|
+
* documents for `caseInsensitive`.
|
|
962
|
+
*
|
|
963
|
+
* One call, replacing the bare `trace.add` the push helpers made before, so
|
|
964
|
+
* the guarded path costs an increment and a comparison rather than a second
|
|
965
|
+
* call per node. `_traceTruncated` is written rather than tested-then-written
|
|
966
|
+
* for the same reason: it is idempotent, and a write is cheaper than a read
|
|
967
|
+
* and a branch on a path a runaway loop takes hundreds of thousands of times.
|
|
968
|
+
*
|
|
969
|
+
* @internal Not part of the published API.
|
|
970
|
+
*/
|
|
971
|
+
addTraceBounded(node: AnyNode, value: unknown, limit: number): void;
|
|
972
|
+
/**
|
|
973
|
+
* Empties {@link trace} and resets {@link traceTruncated} and
|
|
974
|
+
* {@link tracePushCount} - the only reset any of the three has.
|
|
975
|
+
*
|
|
976
|
+
* **For the caller who reuses one state.** The trace spans every evaluation
|
|
977
|
+
* run on this result rather than restarting per walk, which is deliberate
|
|
978
|
+
* (`docs/backlog.md` A15) and is what `options.maxTraceItems` bounds.
|
|
979
|
+
* A caller using the `createState` + repeated `eval` style who wants the
|
|
980
|
+
* trace to describe only the walk they just ran calls this before each one.
|
|
981
|
+
*
|
|
982
|
+
* **The array is emptied in place, not replaced.** {@link trace} has always
|
|
983
|
+
* returned the same instance for the life of the result, so a consumer
|
|
984
|
+
* holding it - `const t = state.result.trace` - keeps a live reference
|
|
985
|
+
* across this call rather than a stale snapshot.
|
|
986
|
+
*
|
|
987
|
+
* That is the **opposite** of `EvalState.resetHookBookkeeping`, which
|
|
988
|
+
* replaces its record rather than emptying it so as not to mutate a
|
|
989
|
+
* collection the caller holds a reference to - and both are right for their
|
|
990
|
+
* own goal, which is why this says so rather than leaving a reader to find
|
|
991
|
+
* one of them and read the other as a slip. Emptying in place is what
|
|
992
|
+
* *releases* memory a caller-held array would otherwise pin, and that is the
|
|
993
|
+
* whole of A12; replacing here would leave the old array, and every value in
|
|
994
|
+
* it, alive in the caller's hand.
|
|
995
|
+
*
|
|
996
|
+
* Leaves {@link expression} alone: that is one string replaced per
|
|
997
|
+
* evaluation, not an accumulator.
|
|
998
|
+
*/
|
|
999
|
+
clearTrace(): void;
|
|
917
1000
|
/**
|
|
918
1001
|
* Starts the evaluation process.
|
|
919
1002
|
*/
|
|
@@ -949,6 +1032,7 @@ declare class EvalState {
|
|
|
949
1032
|
private _walkDepth;
|
|
950
1033
|
private _iterationBudget;
|
|
951
1034
|
private _iterationsRemaining;
|
|
1035
|
+
private _maxTraceItems;
|
|
952
1036
|
private _constBindings;
|
|
953
1037
|
/**
|
|
954
1038
|
* Gets the evaluation context.
|
|
@@ -1080,6 +1164,20 @@ declare class EvalState {
|
|
|
1080
1164
|
* @internal Not part of the published API.
|
|
1081
1165
|
*/
|
|
1082
1166
|
get iterationsRemaining(): number;
|
|
1167
|
+
/**
|
|
1168
|
+
* How many values this state's trace may hold, from `options.maxTraceItems`
|
|
1169
|
+
* and defaulting to 10,000. `0` disables tracing; `Infinity` opts out.
|
|
1170
|
+
*
|
|
1171
|
+
* Filled by {@link enterWalk} on the outermost entry, exactly as the
|
|
1172
|
+
* iteration budget is - so **before the first walk this reports the default**
|
|
1173
|
+
* whatever the options said, and a caller reading it to discover what they
|
|
1174
|
+
* asked for should read it after an evaluation rather than before one.
|
|
1175
|
+
*
|
|
1176
|
+
* Read by `visitor-result.ts`'s two push helpers and nowhere else.
|
|
1177
|
+
*
|
|
1178
|
+
* @internal Not part of the published API.
|
|
1179
|
+
*/
|
|
1180
|
+
get maxTraceItems(): number;
|
|
1083
1181
|
/**
|
|
1084
1182
|
* Charges one loop iteration against the budget, throwing when it is spent.
|
|
1085
1183
|
*
|
|
@@ -1142,8 +1240,7 @@ declare class EvalState {
|
|
|
1142
1240
|
* not named for them. `EvalHooks.clear` cannot reach any of this - the
|
|
1143
1241
|
* bookkeeping belongs to the state - so without this method nothing drains
|
|
1144
1242
|
* the open-node stack at all. Frames left on it keep their AST nodes
|
|
1145
|
-
* reachable for as long as the state is
|
|
1146
|
-
* in a strong `Set`.
|
|
1243
|
+
* reachable for as long as the state is.
|
|
1147
1244
|
*
|
|
1148
1245
|
* The errors matter for the same reason under the state-first style:
|
|
1149
1246
|
* `createState` plus repeated `eval` on one state accumulates them for the
|
|
@@ -1705,19 +1802,60 @@ type EvalKnownOptions = {
|
|
|
1705
1802
|
* any hand-written rule, short enough that a browser tab stutters rather than
|
|
1706
1803
|
* freezes.
|
|
1707
1804
|
*
|
|
1708
|
-
* **It bounds time, not memory
|
|
1709
|
-
*
|
|
1710
|
-
*
|
|
1711
|
-
*
|
|
1712
|
-
*
|
|
1713
|
-
*
|
|
1714
|
-
*
|
|
1805
|
+
* **It bounds time, not memory** - {@link maxTraceItems} bounds the memory,
|
|
1806
|
+
* and before it existed this option was the only thing between a loop and an
|
|
1807
|
+
* out-of-memory. `EvalResult.trace` gained an entry per value pushed and was
|
|
1808
|
+
* reset by nothing, so a loop's trace grew as iterations x nodes - 700,007
|
|
1809
|
+
* entries for a 100,000-iteration loop, and unbounded under `Infinity`.
|
|
1810
|
+
* **That loop is not stopped by this budget**: it charges exactly the default
|
|
1811
|
+
* 100,000 and completes, so the whole allocation is paid by a walk that
|
|
1812
|
+
* returns normally. Where the budget *does* stop a loop - an unbounded
|
|
1813
|
+
* `for (;;)` - the allocation is already paid when the throw arrives.
|
|
1814
|
+
* {@link maxTraceItems} caps that by default as of 0.6.0; `docs/backlog.md`
|
|
1815
|
+
* A12 is retired and carries the measurements.
|
|
1715
1816
|
*
|
|
1716
1817
|
* Costs nothing when no loop runs: the counter is charged inside
|
|
1717
1818
|
* `for-statement.ts`'s iteration loop and nowhere else, so an expression with
|
|
1718
1819
|
* no `for` in it never reaches the instruction.
|
|
1719
1820
|
*/
|
|
1720
1821
|
maxIterations?: number;
|
|
1822
|
+
/**
|
|
1823
|
+
* How many values one {@link EvalState}'s trace may hold before it stops
|
|
1824
|
+
* growing. Defaults to `10000`.
|
|
1825
|
+
*
|
|
1826
|
+
* **A bound on memory, not a debugging preference.** `EvalResult.trace` gains
|
|
1827
|
+
* an entry per value pushed and is reset only by `EvalResult.clearTrace()`.
|
|
1828
|
+
* Before this bound, with nothing resetting it at all, a loop's trace grew as
|
|
1829
|
+
* iterations x nodes - 700,007 entries and ~34 MB for a 100,000-iteration
|
|
1830
|
+
* loop, which {@link maxIterations} does **not** stop: that loop charges
|
|
1831
|
+
* exactly the default budget of 100,000 and completes, so the allocation
|
|
1832
|
+
* happened in full on a walk that never raised. The budget bounded time and
|
|
1833
|
+
* left this unbounded; this bounds it.
|
|
1834
|
+
*
|
|
1835
|
+
* **The head is kept, and truncation is reported rather than marked.** The
|
|
1836
|
+
* first `maxTraceItems` pushes survive in order, so `trace[0]` still means
|
|
1837
|
+
* the first thing evaluated. Once a push is actually dropped,
|
|
1838
|
+
* `EvalResult.traceTruncated` turns true and stays true until `clearTrace()`;
|
|
1839
|
+
* a walk of exactly `maxTraceItems` pushes drops none and leaves it false.
|
|
1840
|
+
* `EvalResult.tracePushCount` goes on counting every push the state made -
|
|
1841
|
+
* which is the number the trace no longer tells you. No synthetic entry is
|
|
1842
|
+
* appended: every row in the trace describes a real node.
|
|
1843
|
+
*
|
|
1844
|
+
* **Per state, not per walk.** The trace spans every evaluation run on one
|
|
1845
|
+
* state, so this bounds their total. `EvalResult.clearTrace()` is how a
|
|
1846
|
+
* caller reusing a state gets a fresh one.
|
|
1847
|
+
*
|
|
1848
|
+
* `0` disables tracing - `trace.length` stays `0`, `traceTruncated` stays
|
|
1849
|
+
* `false`, and `tracePushCount` stays accurate, so the walk-size figure
|
|
1850
|
+
* survives the tracing that was turned off. `Infinity` restores the
|
|
1851
|
+
* unbounded behaviour exactly. Both are honoured rather than treated as
|
|
1852
|
+
* falsy or as opt-outs, the same way {@link maxIterations} honours them.
|
|
1853
|
+
*
|
|
1854
|
+
* Re-read on each outermost `evaluate` call rather than once, because the
|
|
1855
|
+
* options are a mutable record the caller keeps a reference to - the same
|
|
1856
|
+
* reason, and the same moment, as {@link maxIterations}' refill.
|
|
1857
|
+
*/
|
|
1858
|
+
maxTraceItems?: number;
|
|
1721
1859
|
/**
|
|
1722
1860
|
* A caller-owned {@link EvalHooks} to dispatch through, instead of the empty
|
|
1723
1861
|
* one the state creates on first access.
|
|
@@ -1729,13 +1867,13 @@ type EvalKnownOptions = {
|
|
|
1729
1867
|
* caller who wants either alongside their own registry sets it there -
|
|
1730
1868
|
* `new EvalHooks({ onHookError: 'throw' })`, or `createTimingHook().install`.
|
|
1731
1869
|
*
|
|
1732
|
-
* The
|
|
1733
|
-
* `EvalService.ngOnDestroy`
|
|
1734
|
-
*
|
|
1735
|
-
*
|
|
1736
|
-
*
|
|
1737
|
-
*
|
|
1738
|
-
*
|
|
1870
|
+
* The library never clears an adopted registry. It is yours for its whole
|
|
1871
|
+
* life, and `EvalService.ngOnDestroy` does not touch it, whichever method you
|
|
1872
|
+
* passed it to. (Up to 0.5.0, destroy cleared the registries of the states
|
|
1873
|
+
* `createState` built.) So a hook that keeps a state, by capturing it or by
|
|
1874
|
+
* storing `event.state`, keeps that state and its context reachable for as
|
|
1875
|
+
* long as the registry is. Release them in the teardown that owns the
|
|
1876
|
+
* registry, with the unsubscribe `on` / `onRead` returned or `hooks.clear()`.
|
|
1739
1877
|
*/
|
|
1740
1878
|
hooks?: EvalHooks;
|
|
1741
1879
|
/**
|
|
@@ -2026,7 +2164,7 @@ declare class ParserService implements OnDestroy {
|
|
|
2026
2164
|
parse(expr: string, options?: ParserOptions): Program | AnyNode | Expression | undefined;
|
|
2027
2165
|
private fromCacheOrParse;
|
|
2028
2166
|
static ɵfac: i0.ɵɵFactoryDeclaration<ParserService, never>;
|
|
2029
|
-
static ɵprov: i0.ɵɵInjectableDeclaration<
|
|
2167
|
+
static ɵprov: i0.ɵɵInjectableDeclaration<any>;
|
|
2030
2168
|
}
|
|
2031
2169
|
|
|
2032
2170
|
/**
|
|
@@ -2061,23 +2199,33 @@ declare abstract class BaseEval {
|
|
|
2061
2199
|
}
|
|
2062
2200
|
|
|
2063
2201
|
/**
|
|
2064
|
-
* Service for evaluating and parsing expressions
|
|
2202
|
+
* Service for evaluating and parsing expressions.
|
|
2203
|
+
*
|
|
2204
|
+
* It keeps no reference to anything you pass it or anything it hands back: a
|
|
2205
|
+
* state from `createState`, its context and an `options.hooks` registry are
|
|
2206
|
+
* yours, and are collectable once you drop them (`docs/backlog.md` A8).
|
|
2065
2207
|
*/
|
|
2066
2208
|
declare class EvalService extends BaseEval implements OnDestroy {
|
|
2067
2209
|
private _isDestroyed;
|
|
2068
|
-
private _activeContexts;
|
|
2069
|
-
private _activeStates;
|
|
2070
2210
|
protected parserService: ParserService;
|
|
2071
2211
|
/**
|
|
2072
2212
|
* Constructs a new instance of the EvalService class.
|
|
2073
2213
|
*/
|
|
2074
2214
|
constructor();
|
|
2075
2215
|
/**
|
|
2076
|
-
*
|
|
2216
|
+
* Builds a state for `eval` / `evalAsync`. The service does not keep it:
|
|
2217
|
+
* the state is yours, and so are its context and any `options.hooks`
|
|
2218
|
+
* registry it adopted (`docs/backlog.md` A8, A20). Nothing the service does
|
|
2219
|
+
* later, `ngOnDestroy` included, reaches it.
|
|
2077
2220
|
*/
|
|
2078
2221
|
createState(context?: EvalContext | Context, options?: EvalOptions): EvalState;
|
|
2079
2222
|
/**
|
|
2080
|
-
*
|
|
2223
|
+
* Marks the service destroyed, so that `createState`, `simpleEval` and
|
|
2224
|
+
* `simpleEvalAsync` throw from then on. It releases and changes nothing
|
|
2225
|
+
* else: the service holds no state, context or registry to release. Clear
|
|
2226
|
+
* a registry you passed through `options.hooks` in your own teardown, with
|
|
2227
|
+
* the unsubscribe `on` / `onRead` returned or `hooks.clear()`
|
|
2228
|
+
* (`docs/backlog.md` A8).
|
|
2081
2229
|
*/
|
|
2082
2230
|
ngOnDestroy(): void;
|
|
2083
2231
|
/**
|
|
@@ -2115,7 +2263,7 @@ declare class EvalService extends BaseEval implements OnDestroy {
|
|
|
2115
2263
|
*/
|
|
2116
2264
|
evalAsync(expression: string | AnyNode | undefined, state: EvalState): Promise<unknown | undefined>;
|
|
2117
2265
|
static ɵfac: i0.ɵɵFactoryDeclaration<EvalService, never>;
|
|
2118
|
-
static ɵprov: i0.ɵɵInjectableDeclaration<
|
|
2266
|
+
static ɵprov: i0.ɵɵInjectableDeclaration<any>;
|
|
2119
2267
|
}
|
|
2120
2268
|
|
|
2121
2269
|
/**
|
|
@@ -2274,7 +2422,7 @@ declare class CompilerService extends BaseEval implements OnDestroy {
|
|
|
2274
2422
|
*/
|
|
2275
2423
|
callAsync(fn: stateCallbackAsync | undefined, state: EvalState): Promise<unknown>;
|
|
2276
2424
|
static ɵfac: i0.ɵɵFactoryDeclaration<CompilerService, never>;
|
|
2277
|
-
static ɵprov: i0.ɵɵInjectableDeclaration<
|
|
2425
|
+
static ɵprov: i0.ɵɵInjectableDeclaration<any>;
|
|
2278
2426
|
}
|
|
2279
2427
|
|
|
2280
2428
|
/**
|
|
@@ -2296,7 +2444,7 @@ declare class DiscoveryService extends BaseEval {
|
|
|
2296
2444
|
*/
|
|
2297
2445
|
extract(expression: string | AnyNode | undefined, searchType: AnyNodeTypes): AnyNode[] | undefined;
|
|
2298
2446
|
static ɵfac: i0.ɵɵFactoryDeclaration<DiscoveryService, never>;
|
|
2299
|
-
static ɵprov: i0.ɵɵInjectableDeclaration<
|
|
2447
|
+
static ɵprov: i0.ɵɵInjectableDeclaration<any>;
|
|
2300
2448
|
}
|
|
2301
2449
|
|
|
2302
2450
|
export { ASYNC_HOOK_MESSAGE, BaseRegistry, Cache, CaseInsensitiveRegistry, CompilerService, DiscoveryService, EMPTY_COMPLETION, EvalContext, EvalHooks, EvalResult, EvalScope, EvalService, EvalState, EvalTrace, ParserService, Queue, RecursiveVisitorResultType, Registry, Stack, call, callAsync, compile, compileAsync, createDependencyTracker, createTimingHook, defaultParserOptions, evaluate, evaluateAsync, extract, extractExpression, fromContext, getContextKey, getContextValue, isRegistryContext, parse };
|