@zvenigora/ng-eval-core 0.5.0 → 0.6.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zvenigora/ng-eval-core",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "An expression evaluator for Angular",
5
5
  "repository": {
6
6
  "type": "git",
@@ -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, and `EvalService` holds its states
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, and raising it trades one for the other.**
1709
- * `EvalResult.trace` gains an entry per value pushed and is never reset, so a
1710
- * loop's trace grows as iterations x nodes - roughly 700,000 entries for a
1711
- * 100,000-iteration loop. The allocation happens *before* the throw, so
1712
- * exhausting the budget costs it in full; and `Infinity` removes the only
1713
- * thing bounding it, turning a hang into an out-of-memory. `docs/backlog.md`
1714
- * A12 carries the measurements and the options for bounding it.
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 one thing the library does *to* an adopted registry is clear it:
1733
- * `EvalService.ngOnDestroy` empties the registries of the states it created,
1734
- * this one included, so that a registry outliving the service cannot keep
1735
- * those states and their AST nodes reachable. Registrations cannot be dropped
1736
- * selectively - the closures that captured a dead state are indistinguishable
1737
- * from the rest - so do not share one registry with a state whose lifetime is
1738
- * meant to outlast the service.
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
  /**
@@ -2061,23 +2199,33 @@ declare abstract class BaseEval {
2061
2199
  }
2062
2200
 
2063
2201
  /**
2064
- * Service for evaluating and parsing expressions with proper memory management.
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
- * Override createState to track active contexts and states for cleanup
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
- * Clean up resources to prevent memory leaks
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
  /**