@zvenigora/ng-eval-core 0.10.1 → 0.11.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.10.1",
3
+ "version": "0.11.1",
4
4
  "description": "An expression evaluator for Angular",
5
5
  "repository": {
6
6
  "type": "git",
@@ -2,7 +2,6 @@ import * as i0 from '@angular/core';
2
2
  import { OnDestroy } from '@angular/core';
3
3
  import * as acorn from 'acorn';
4
4
  import { AnyNode, Program, Expression } from 'acorn';
5
- import { WalkerCallback } from 'acorn-walk';
6
5
 
7
6
  type ParserOptions = Partial<acorn.Options> & {
8
7
  extractExpressions?: boolean;
@@ -86,28 +85,6 @@ interface StackType<T> {
86
85
  swap(): void;
87
86
  }
88
87
 
89
- interface QueueType<T> {
90
- length: number;
91
- dequeue(): T | undefined;
92
- enqueue(value: T): number;
93
- peek(): T;
94
- }
95
-
96
- interface ScopeOptions {
97
- global?: boolean;
98
- caseInsensitive?: boolean;
99
- namespace?: string;
100
- }
101
- interface RegistryOptionType<TKey, TValue> {
102
- registry: Readonly<RegistryType<TKey, TValue>>;
103
- options: Readonly<ScopeOptions>;
104
- }
105
- interface ScopeType<TKey, TValue> {
106
- registries: RegistryOptionType<TKey, TValue>[];
107
- add: (registry: RegistryOptionType<TKey, TValue>) => void;
108
- get: (key: TKey, namespace?: string) => [TKey, TValue] | undefined;
109
- }
110
-
111
88
  /**
112
89
  * Represents a registry that stores key-value pairs.
113
90
  */
@@ -364,39 +341,6 @@ declare class Registry<TKey, TValue> implements RegistryType<TKey, TValue> {
364
341
  toObject(): Record<string | number | symbol, TValue>;
365
342
  }
366
343
 
367
- /**
368
- * Represents a generic queue data structure.
369
- * @template T The type of elements stored in the queue.
370
- */
371
- declare class Queue<T> implements QueueType<T> {
372
- private readonly _queue;
373
- /**
374
- * Creates a new instance of the Queue class.
375
- * @param _queue Optional initial array of elements.
376
- */
377
- constructor(_queue?: T[]);
378
- /**
379
- * Gets the number of elements in the queue.
380
- */
381
- get length(): number;
382
- /**
383
- * Removes and returns the first element in the queue.
384
- * @returns The first element in the queue, or undefined if the queue is empty.
385
- */
386
- dequeue(): T | undefined;
387
- /**
388
- * Adds an element to the end of the queue.
389
- * @param value The element to add to the queue.
390
- * @returns The new length of the queue.
391
- */
392
- enqueue(value: T): number;
393
- /**
394
- * Returns the first element in the queue without removing it.
395
- * @returns The first element in the queue.
396
- */
397
- peek(): T;
398
- }
399
-
400
344
  /**
401
345
  * Represents a stack data structure with proper memory management.
402
346
  * @template T The type of elements in the stack.
@@ -554,6 +498,10 @@ type EvalLookup = (key: unknown, thisArg?: unknown, options?: EvalOptions) => un
554
498
  * A member write - `o.k = v`, `o.k += v`, `o.k++` - as an `EvalContext` that
555
499
  * polices member writes is asked about it, through
556
500
  * `EvalContext.checkMemberWrite`, before the write happens.
501
+ *
502
+ * Since 0.11.0 the same question is asked before a call of a built-in method
503
+ * that writes into an object it is handed - `a.push(x)`, `m.set(k, v)`,
504
+ * `Object.assign(o, p)` - with {@link method} naming it.
557
505
  */
558
506
  interface EvalMemberWrite {
559
507
  /**
@@ -561,12 +509,20 @@ interface EvalMemberWrite {
561
509
  * expression's object, `o` in `o.k = v`. Not necessarily an object - a
562
510
  * write to a primitive's member reaches the policy too, ahead of the
563
511
  * prototype-pollution guard that would refuse it.
512
+ *
513
+ * For a method call, the object the method writes into: its receiver, `a`
514
+ * in `a.push(x)` - the context itself for a bare call, `p(x)`, and the
515
+ * `this` passed through `call`, `apply` or `bind`, `a` in
516
+ * `[].push.call(a, x)` - or, for `Object`'s mutators, the first argument,
517
+ * `o` in `Object.assign(o, p)`.
564
518
  */
565
519
  readonly target: unknown;
566
520
  /**
567
521
  * The property about to be written, as the member visitor resolved it: a
568
522
  * computed key evaluated, and under `caseInsensitive` corrected to the
569
523
  * spelling the target holds.
524
+ *
525
+ * Undefined for a method call, which may write any number of properties.
570
526
  */
571
527
  readonly key: unknown;
572
528
  /**
@@ -588,6 +544,27 @@ interface EvalMemberWrite {
588
544
  * object: `[o].find(x => true)` returns `o`.
589
545
  */
590
546
  readonly createdByEvaluation: boolean;
547
+ /**
548
+ * The built-in method about to make the write, when a call makes it rather
549
+ * than an assignment or an update, which leave this undefined. Named as the
550
+ * specification names it: `'Array.prototype.push'`,
551
+ * `'%TypedArray%.prototype.sort'`, `'Map.prototype.set'`,
552
+ * `'Date.prototype.setFullYear'`, `'Object.assign'`.
553
+ *
554
+ * The method is recognised by identity, not by the name it was called by: a
555
+ * method of the caller's own named `push` is not asked about, and
556
+ * `Array.prototype.push` reached under another name is. Reached through
557
+ * `Function.prototype.call`, `apply` or `bind`, it is asked about as a
558
+ * direct call of it, and `bind` is asked when it binds, since the bound
559
+ * function is new and would not be recognised when called. The methods are
560
+ * those of `Array` and the typed arrays that reorder, fill or resize them;
561
+ * `Map`, `Set`, `WeakMap` and `WeakSet`'s adders and removers; `Date`'s
562
+ * setters; and `Object`'s `assign`, `defineProperty`, `defineProperties`,
563
+ * `setPrototypeOf`, `freeze`, `seal` and `preventExtensions`.
564
+ *
565
+ * Since 0.11.0.
566
+ */
567
+ readonly method?: string;
591
568
  }
592
569
 
593
570
  interface EvalScopeOptions {
@@ -696,8 +673,8 @@ declare class EvalContext {
696
673
  */
697
674
  get(key: unknown): unknown | undefined;
698
675
  /**
699
- * Step 1 of {@link get}'s resolution order on its own: the scopes pushed
700
- * during this evaluation, innermost first.
676
+ * Step 1 of {@link get}'s resolution order on its own: the scope stack,
677
+ * innermost first, whoever pushed each scope.
701
678
  *
702
679
  * {@link get} calls this rather than inlining the loop, so that the read
703
680
  * hooks' `scoped` flag and the resolution it describes are the *same*
@@ -761,8 +738,11 @@ declare class EvalContext {
761
738
  */
762
739
  scopeHolding(key: unknown): Context | undefined;
763
740
  /**
764
- * Whether any scope pushed during this evaluation *binds* the key - the
765
- * question the read hooks' `scoped` flag asks.
741
+ * Whether any scope on the scope stack *binds* the key - the question the
742
+ * read hooks' `scoped` flag asks. Every scope on the stack counts, whoever
743
+ * pushed it: an arrow call's parameters, the lexical scope of a program, a
744
+ * block or a `for` loop, and a scope a caller pushed with {@link push}
745
+ * before the walk.
766
746
  *
767
747
  * Deliberately about binding rather than about value. It no longer parts
768
748
  * company with {@link getFromScopes} over it: both go through
@@ -898,9 +878,15 @@ declare class EvalContext {
898
878
  * guard still applies after. A context that does not implement this pays
899
879
  * one field read at each of those sites, and nothing else.
900
880
  *
901
- * What it does not see: a mutating **method** call - `arr.push(x)`,
902
- * `arr.splice(i, 1)`, `map.set(k, v)` - writes from native code and is no
903
- * member write at all.
881
+ * Since 0.11.0 it is also asked before a call of a built-in **method** that
882
+ * writes into an object it is handed - `arr.push(x)`, `arr.splice(i, 1)`,
883
+ * `map.set(k, v)`, `Object.assign(o, p)` - which writes from native code and
884
+ * reaches neither write visitor. The call visitor asks, with
885
+ * {@link EvalMemberWrite.method} naming the method and the object it writes
886
+ * as the target; refusing it means the call is not made. The same is asked
887
+ * when the method is reached through `Function.prototype.call`, `apply` or
888
+ * `bind` - for `bind`, when it binds. A method the caller wrote is not asked
889
+ * about: what it does is the caller's own code.
904
890
  *
905
891
  * @param write - The write about to happen.
906
892
  * @throws To refuse the write.
@@ -1466,10 +1452,13 @@ interface EvalReadEvent {
1466
1452
  readonly path?: string;
1467
1453
  readonly value: unknown;
1468
1454
  /**
1469
- * True when the key resolved from a scope pushed *during this evaluation* -
1470
- * `EvalContext.scopes`, the stack `arrow-function-expression.ts` pushes and
1471
- * pops around a call. Such a read is an arrow-function parameter binding,
1472
- * not a dependency, and a tracker should skip it.
1455
+ * True when a scope on the context's scope stack - `EvalContext.scopes`,
1456
+ * asked through `EvalContext.hasInScopes` - binds the name when it is read,
1457
+ * whoever pushed that scope. That covers an arrow-function parameter, a
1458
+ * declaration in the lexical scope the evaluator pushes for a program, a
1459
+ * block or a `for` loop, and a binding the caller pushed with
1460
+ * `EvalContext.push` before the walk. Such a read is a binding, not a
1461
+ * dependency, and a tracker should skip it.
1473
1462
  *
1474
1463
  * The definition is **lifetime, not type**: caller-registered `priorScopes`
1475
1464
  * are `EvalScope` instances holding long-lived objects and are real
@@ -2097,9 +2086,11 @@ interface EvalDependencyTracker {
2097
2086
  * rules do the filtering:
2098
2087
  *
2099
2088
  * 1. **Scope bindings are not dependencies.** A read flagged `scoped` resolved
2100
- * from a scope pushed during the walk - an arrow-function parameter. Only
2101
- * the walker can tell one from a real context read, which is why the flag
2102
- * exists; a consumer using this tracker inherits the filtering for free.
2089
+ * from a scope on the context's scope stack, whoever pushed it - an
2090
+ * arrow-function parameter, a declaration in a program, block or `for`
2091
+ * scope, or a binding the caller pushed before the walk. Only the walker
2092
+ * can tell one from a real context read, which is why the flag exists; a
2093
+ * consumer using this tracker inherits the filtering for free.
2103
2094
  * 2. **Nor is anything reached *through* one.** `item` being a binding makes
2104
2095
  * `item.name` one too, and that read carries no flag of its own: `scoped` is
2105
2096
  * set at identifier resolution, and the member hop resolves against the
@@ -2144,7 +2135,6 @@ declare const createDependencyTracker: () => EvalDependencyTracker;
2144
2135
 
2145
2136
  type BaseContext = Record<string | number | symbol, unknown>;
2146
2137
  type Context = Registry<unknown, unknown> | BaseContext;
2147
- declare function isRegistryContext(context?: Context): boolean;
2148
2138
  /**
2149
2139
  * Converts a context object to a Context instance.
2150
2140
  * @param context - The context object to convert.
@@ -2163,16 +2153,6 @@ declare const fromContext: (context?: Context, options?: EvalOptions) => Context
2163
2153
  * @returns The value associated with the specified key, or undefined if not found.
2164
2154
  */
2165
2155
  declare const getContextValue: (context?: Context, key?: unknown) => unknown;
2166
- /**
2167
- * Retrieves the key from the given context object.
2168
- * If the context is an instance of Registry, it searches for the key in a case-insensitive manner if specified.
2169
- * If the context is an instance of Object, it uses the getKeyValue function to retrieve the key-value pair.
2170
- * @param context - The context object.
2171
- * @param key - The key to retrieve.
2172
- * @param caseInsensitive - Specifies whether the search should be case-insensitive (only applicable for Registry instances).
2173
- * @returns The retrieved key, or undefined if the key is not found.
2174
- */
2175
- declare const getContextKey: (context: Context, key: string | number | symbol, caseInsensitive: boolean) => string | number | symbol | undefined;
2176
2156
 
2177
2157
  interface CacheType<TValue> extends RegistryType<string, TValue> {
2178
2158
  type: Readonly<'Cache' | string>;
@@ -2180,72 +2160,6 @@ interface CacheType<TValue> extends RegistryType<string, TValue> {
2180
2160
  getHashKey: (namespace: string, value: string) => string;
2181
2161
  }
2182
2162
 
2183
- /**
2184
- * @deprecated Use `EvalHooks` and `EvalState` instead. Nothing in the library
2185
- * implements this interface, and no code path reads its `beforeVisitors` /
2186
- * `afterVisitors` entries; the evaluator's state type is `EvalState` and hooks
2187
- * are registered through `EvalState.hooks`.
2188
- *
2189
- * **Its two hook entries are the last published trace of a signature no
2190
- * function in the library has any more.** They are typed to return
2191
- * `number | undefined` because the real `beforeVisitor` / `afterVisitor` once
2192
- * returned a timing stub - a start timestamp handed back to the closing call.
2193
- * That stub was deleted when those functions became hook dispatchers and their
2194
- * return type widened to `void`, which is also what `EvalNodeHook` mandates, so
2195
- * the shape recorded here is now contradicted by every hook the library
2196
- * actually dispatches. A reader who finds these lines has no way to discover
2197
- * that from the code, since there is no implementation left to compare against.
2198
- *
2199
- * Retained so this release stays purely additive; removal is a follow-up for
2200
- * the next breaking version.
2201
- */
2202
- interface RecursiveVisitorState {
2203
- scope: Registry<unknown, unknown>;
2204
- result: RecursiveVisitorResult<unknown | undefined>;
2205
- option: RecursiveVisitorOptions;
2206
- beforeVisitors?: RegistryType<AnyNodeTypes, (node: AnyNode, st: RecursiveVisitorState) => number | undefined>;
2207
- afterVisitors?: RegistryType<AnyNodeTypes, (node: AnyNode, st: RecursiveVisitorState) => number | undefined>;
2208
- }
2209
- interface RecursiveVisitorOptions {
2210
- trackTime?: boolean;
2211
- resultType?: 'stack' | 'registry';
2212
- }
2213
- interface RecursiveVisitorContext {
2214
- placeholder?: unknown;
2215
- }
2216
- declare enum RecursiveVisitorResultType {
2217
- Stack = 0,
2218
- Registry = 1
2219
- }
2220
- /**
2221
- * @deprecated Use `EvalResult` instead. This exists only as the `result` member
2222
- * of the deprecated {@link RecursiveVisitorState}; the evaluator carries its
2223
- * value stack and trace on `EvalResult`, which is what visitors actually push
2224
- * to and what `EvalState.result` returns.
2225
- *
2226
- * Retained so this release stays purely additive; removal is a follow-up for
2227
- * the next breaking version.
2228
- */
2229
- type RecursiveVisitorResult<TValue> = RecursiveVisitorStackResult<TValue> | RecursiveVisitorRegistryResult<TValue>;
2230
- interface RecursiveVisitorStackResult<TValue> {
2231
- type: 'stack';
2232
- stack: StackType<TValue>;
2233
- }
2234
- interface RecursiveVisitorRegistryResult<TValue> {
2235
- type: 'registry';
2236
- registry: BaseRegistry<AnyNode, TValue>;
2237
- }
2238
- type AggregateType = {
2239
- Expression: acorn.Expression;
2240
- Statement: acorn.Statement;
2241
- Function: acorn.Function;
2242
- Class: acorn.Class;
2243
- Pattern: acorn.Pattern;
2244
- ForInit: acorn.VariableDeclaration | acorn.Expression;
2245
- };
2246
- type RecursiveVisitor<TState> = (node: acorn.AnyNode, state: TState, callback: WalkerCallback<TState>) => void;
2247
- type RecursiveAggregateVisitor<TState> = (node: AggregateType, state: TState, callback: WalkerCallback<TState>) => void;
2248
-
2249
2163
  /**
2250
2164
  * @description
2251
2165
  * Service for parsing expressions and returning ES6/ES2020 AST.
@@ -2497,7 +2411,8 @@ declare class CompilerService extends BaseEval implements OnDestroy {
2497
2411
  */
2498
2412
  private cleanupCache;
2499
2413
  /**
2500
- * Generate cache key for expression
2414
+ * Generate cache key for expression. Only a string is cached, so only a
2415
+ * string has a key.
2501
2416
  */
2502
2417
  private generateCacheKey;
2503
2418
  /**
@@ -2505,7 +2420,8 @@ declare class CompilerService extends BaseEval implements OnDestroy {
2505
2420
  */
2506
2421
  private updateAccessOrder;
2507
2422
  /**
2508
- * Compiles the given expression into a state callback function with caching.
2423
+ * Compiles the given expression into a state callback function. A string is
2424
+ * compiled once and cached; an AST is compiled on every call.
2509
2425
  * @param expression - The expression to compile.
2510
2426
  * @returns The compiled state callback function.
2511
2427
  * @throws Error if there is an error during compilation.
@@ -2530,7 +2446,9 @@ declare class CompilerService extends BaseEval implements OnDestroy {
2530
2446
  */
2531
2447
  call(fn: stateCallback | undefined, state: EvalState): unknown;
2532
2448
  /**
2533
- * Compiles the given expression into an asynchronous state callback function with caching.
2449
+ * Compiles the given expression into an asynchronous state callback
2450
+ * function. A string is compiled once and cached; an AST is compiled on
2451
+ * every call.
2534
2452
  * @param expression - The expression to compile.
2535
2453
  * @returns The compiled asynchronous state callback function.
2536
2454
  * @throws Error if there is an error during compilation.
@@ -2580,5 +2498,5 @@ declare class DiscoveryService extends BaseEval {
2580
2498
  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
2581
2499
  }
2582
2500
 
2583
- 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 };
2584
- export type { AggregateType, AnyNodeTypes, BaseContext, CacheType, Context, EvalDependencyTracker, EvalHookError, EvalHookErrorPolicy, EvalHookPhase, EvalKnownOptions, EvalLookup, EvalMemberWrite, EvalNodeHook, EvalNodeHookEvent, EvalNodeTiming, EvalOptions, EvalReadEvent, EvalReadHook, EvalReadKind, EvalScopeOptions, EvalTimingHook, EvalTraceItem, ParserOptions, QueueType, RecursiveAggregateVisitor, RecursiveVisitor, RecursiveVisitorContext, RecursiveVisitorOptions, RecursiveVisitorRegistryResult, RecursiveVisitorResult, RecursiveVisitorStackResult, RecursiveVisitorState, RegistryEntries, RegistryOptionType, RegistryType, ScopeOptions, ScopeType, StackType, Unsubscribe, stateCallback, stateCallbackAsync };
2501
+ 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 };
2502
+ 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 };