@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/CHANGELOG.md +125 -2
- package/README.md +3 -1
- package/fesm2022/zvenigora-ng-eval-core.mjs +320 -350
- package/fesm2022/zvenigora-ng-eval-core.mjs.map +1 -1
- package/package.json +1 -1
- package/types/zvenigora-ng-eval-core.d.ts +70 -152
package/package.json
CHANGED
|
@@ -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
|
|
700
|
-
*
|
|
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
|
|
765
|
-
*
|
|
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
|
-
*
|
|
902
|
-
* `arr.
|
|
903
|
-
*
|
|
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
|
|
1470
|
-
* `EvalContext.
|
|
1471
|
-
*
|
|
1472
|
-
*
|
|
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
|
|
2101
|
-
*
|
|
2102
|
-
*
|
|
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
|
|
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
|
|
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,
|
|
2584
|
-
export type {
|
|
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 };
|