@zvenigora/ng-eval-core 0.9.0 → 0.10.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.9.0",
3
+ "version": "0.10.0",
4
4
  "description": "An expression evaluator for Angular",
5
5
  "repository": {
6
6
  "type": "git",
@@ -550,6 +550,46 @@ declare class Cache<TValue> implements CacheType<TValue> {
550
550
 
551
551
  type EvalLookup = (key: unknown, thisArg?: unknown, options?: EvalOptions) => unknown;
552
552
 
553
+ /**
554
+ * A member write - `o.k = v`, `o.k += v`, `o.k++` - as an `EvalContext` that
555
+ * polices member writes is asked about it, through
556
+ * `EvalContext.checkMemberWrite`, before the write happens.
557
+ */
558
+ interface EvalMemberWrite {
559
+ /**
560
+ * The object about to receive the write: the value of the member
561
+ * expression's object, `o` in `o.k = v`. Not necessarily an object - a
562
+ * write to a primitive's member reaches the policy too, ahead of the
563
+ * prototype-pollution guard that would refuse it.
564
+ */
565
+ readonly target: unknown;
566
+ /**
567
+ * The property about to be written, as the member visitor resolved it: a
568
+ * computed key evaluated, and under `caseInsensitive` corrected to the
569
+ * spelling the target holds.
570
+ */
571
+ readonly key: unknown;
572
+ /**
573
+ * Whether the walk on the **same `EvalState`** created {@link target} for
574
+ * the expression to hold. Created means one of:
575
+ *
576
+ * - an object or array literal, spread included (`{ ...o }` is new, though
577
+ * what it copies is not), or a regex literal, which is a new `RegExp` on
578
+ * each evaluation;
579
+ * - a rest value: `...rest` in an array or object pattern, or an arrow
580
+ * function's rest parameter;
581
+ * - the function an arrow-function expression evaluates to.
582
+ *
583
+ * It covers an arrow-function body, which re-enters the walk on that state,
584
+ * and an earlier `eval` on a state the caller reuses.
585
+ *
586
+ * **A call's result and a `new` result are never created**, even when they
587
+ * are new - `[1].map(f)` is - because either can hand back an existing
588
+ * object: `[o].find(x => true)` returns `o`.
589
+ */
590
+ readonly createdByEvaluation: boolean;
591
+ }
592
+
553
593
  interface EvalScopeOptions {
554
594
  global?: boolean;
555
595
  caseInsensitive?: boolean;
@@ -821,8 +861,10 @@ declare class EvalContext {
821
861
  * The write dispatches through `setContextValue` rather than through the
822
862
  * prototype-pollution guard's `safeSetProperty`, and the difference is not
823
863
  * cosmetic: {@link push} normalises a plain record into a `Registry` when
824
- * `caseInsensitive` is set, and `Object.defineProperty` on a `Registry` would
825
- * define a property on the instance while inserting nothing into its map. No
864
+ * `caseInsensitive` is set, and `safeSetProperty` writes a property onto the
865
+ * object it is given - by assignment since 0.10.0, by `Object.defineProperty`
866
+ * before - which on a `Registry` sets a property on the instance while
867
+ * inserting nothing into its map. No
826
868
  * guard is lost - this method only ever writes a key some scope already
827
869
  * *binds*, and a binding can only have been created through the guarded
828
870
  * declaration path, which rejects every blocklisted name.
@@ -832,6 +874,38 @@ declare class EvalContext {
832
874
  * @returns True when a pushed scope bound the key and received the write.
833
875
  */
834
876
  setInScope(key: unknown, value: unknown): boolean;
877
+ /**
878
+ * An opt-in policy for **member** writes - `o.k = v`, `o.k += v`, `o.k++`.
879
+ * Those never reach {@link set} or {@link setInScope}: the assignment and
880
+ * update visitors write the member straight into the object, so a context
881
+ * that overrides {@link set} to protect its keys cannot see a write made
882
+ * *through* one. This is the hook that can.
883
+ *
884
+ * **Undefined on `EvalContext`, and that is the opt-out.** A subclass that
885
+ * implements it opts in to two things, decided once per `EvalState`, when
886
+ * the state is built around this context:
887
+ *
888
+ * - the walk records every object it creates for the expression to hold -
889
+ * object, array and regex literals, rest values, arrow functions - on that
890
+ * state, in a `WeakSet` the state holds; and
891
+ * - before each member write, the assignment and update visitors call this
892
+ * with the target, the key, and whether that state's walk created the
893
+ * target - see {@link EvalMemberWrite.createdByEvaluation}, which also
894
+ * says what does not count, and why.
895
+ *
896
+ * To refuse a write, throw: nothing is written, and the error leaves the
897
+ * evaluation as thrown. Returning allows it, and the prototype-pollution
898
+ * guard still applies after. A context that does not implement this pays
899
+ * one field read at each of those sites, and nothing else.
900
+ *
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.
904
+ *
905
+ * @param write - The write about to happen.
906
+ * @throws To refuse the write.
907
+ */
908
+ checkMemberWrite?(write: EvalMemberWrite): void;
835
909
  /**
836
910
  * Pushes a context to the scope stack.
837
911
  * @param context - The context to push.
@@ -1070,6 +1144,7 @@ declare class EvalState {
1070
1144
  private _iterationsRemaining;
1071
1145
  private _maxTraceItems;
1072
1146
  private _constBindings;
1147
+ private readonly _createdObjects;
1073
1148
  /**
1074
1149
  * Gets the evaluation context.
1075
1150
  */
@@ -1267,6 +1342,26 @@ declare class EvalState {
1267
1342
  * @internal Not part of the published API.
1268
1343
  */
1269
1344
  isConstBinding(scope: Context, key: unknown): boolean;
1345
+ /**
1346
+ * The objects this state's walk created for the expression to hold -
1347
+ * object, array and regex literals, rest values, arrow functions - or
1348
+ * undefined when its context does not police member writes. See
1349
+ * `EvalContext.checkMemberWrite`, whose presence is the opt-in, and
1350
+ * `EvalMemberWrite.createdByEvaluation` for what is deliberately left out.
1351
+ *
1352
+ * **Undefined is the default path, and the reason this is a field.** It is
1353
+ * decided once, in the constructor, so each recording site and the two
1354
+ * member-write branches pay one read of it and nothing else when no policy
1355
+ * is in force: no set is allocated and no object is recorded.
1356
+ *
1357
+ * Per state rather than per `evaluate` call, deliberately: an arrow-function
1358
+ * body re-enters the walk on this same state, possibly after the outer walk
1359
+ * has returned, and an object its enclosing expression created is still that
1360
+ * expression's own. A `WeakSet`, so recording an object never keeps it alive.
1361
+ *
1362
+ * @internal Not part of the published API.
1363
+ */
1364
+ get createdObjects(): WeakSet<object> | undefined;
1270
1365
  /**
1271
1366
  * Drops every per-run record this state holds: the collected hook errors, the
1272
1367
  * open-node stack, the accumulated timings, and the walk bases bounding
@@ -2486,4 +2581,4 @@ declare class DiscoveryService extends BaseEval {
2486
2581
  }
2487
2582
 
2488
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 };
2489
- export type { AggregateType, AnyNodeTypes, BaseContext, CacheType, Context, EvalDependencyTracker, EvalHookError, EvalHookErrorPolicy, EvalHookPhase, EvalKnownOptions, EvalLookup, 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 };
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 };