@zvenigora/ng-eval-core 0.6.1 → 0.8.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.6.1",
3
+ "version": "0.8.0",
4
4
  "description": "An expression evaluator for Angular",
5
5
  "repository": {
6
6
  "type": "git",
@@ -554,6 +554,11 @@ interface EvalScopeOptions {
554
554
  global?: boolean;
555
555
  caseInsensitive?: boolean;
556
556
  namespace?: string;
557
+ /**
558
+ * The `this` for a method called on the scope's own object (`ns.fn()`), or
559
+ * for `this.fn()` when this scope supplies `fn`. Unset, `ns.fn()` receives
560
+ * the scope's object. Applied since 0.7.0; accepted and ignored before.
561
+ */
557
562
  thisArg?: unknown;
558
563
  }
559
564
  /**
@@ -656,8 +661,8 @@ declare class EvalContext {
656
661
  *
657
662
  * {@link get} calls this rather than inlining the loop, so that the read
658
663
  * hooks' `scoped` flag and the resolution it describes are the *same*
659
- * implementation. A second copy of the order would drift - `getKey` already
660
- * shows what that looks like when it does.
664
+ * implementation. A second copy of the order would drift - `getKey`'s did,
665
+ * until 0.8.0 (`docs/backlog-retired.md` A4).
661
666
  *
662
667
  * A binding whose value is `undefined` is **found** here, and no longer reads
663
668
  * as absent - see {@link scopeHolding}.
@@ -708,7 +713,7 @@ declare class EvalContext {
708
713
  * single pass is what keeps that question answered by the same code as
709
714
  * {@link get}'s step 1. The alternative was a second copy of the
710
715
  * innermost-scope walk at each write site, which is the defect
711
- * `docs/backlog.md` A4 and A10 already describe - two copies of one
716
+ * `docs/backlog-retired.md` A4 and A10 describe - two copies of one
712
717
  * resolution order, drifting - reproduced on purpose.
713
718
  *
714
719
  * @param key - The key to look for.
@@ -738,17 +743,48 @@ declare class EvalContext {
738
743
  */
739
744
  hasInScopes(key: unknown): boolean;
740
745
  /**
741
- * Retrieves the `this` value of the specified key from the evaluation context.
742
- * The value is searched in the original context, prior scopes, and lookup functions.
746
+ * Retrieves the `this` value a call of the specified key receives through
747
+ * `this.key()`.
748
+ *
749
+ * - A key the original context holds: the original context.
750
+ * - A key a prior scope resolves: that scope's `thisArg`, or undefined when
751
+ * it sets none. The first scope that resolves the key answers, as in
752
+ * {@link get}.
753
+ * - A key only a lookup resolves, or none: undefined. A lookup is a resolver,
754
+ * not an object that holds the key.
755
+ *
756
+ * Undefined means "no receiver of its own", and the member visitor then falls
757
+ * back to the object it was evaluating. Up to 0.6.x the prior-scope step
758
+ * re-tested the original context and could never answer, and the lookup step
759
+ * returned the lookup function itself (`docs/backlog-retired.md` A7).
743
760
  * @param key - The key to retrieve the value for.
744
- * @returns The `this` value associated with the key, or undefined if not found.
761
+ * @returns The `this` value associated with the key, or undefined.
745
762
  */
746
763
  getThis(key: unknown): unknown | undefined;
747
764
  /**
748
- * Retrieves the value associated with the specified key from the evaluation context.
765
+ * The key {@link get} resolves `key` to: the spelling under which the source
766
+ * that answered holds it. The read hooks report this as the key that was
767
+ * read, and the write visitors write to it under `caseInsensitive`.
749
768
  *
750
- * @param key - The key to retrieve the value for.
751
- * @returns The value associated with the key, or undefined if the key is not found.
769
+ * Resolved through {@link get}'s own chain, so the two cannot disagree:
770
+ *
771
+ * - A pushed scope, the original, or a `global` prior scope holding the key:
772
+ * the spelling that source holds it under - corrected only where the
773
+ * source is a case-insensitive `Registry`, which is the only kind that
774
+ * matches another spelling.
775
+ * - A prior scope's namespace: the namespace, as the scope declares it.
776
+ * - A lookup: the key as written, since a lookup returns no key.
777
+ * - Nothing: undefined, exactly when {@link get} finds nothing. A pushed
778
+ * scope binding the key to `undefined` counts as found, as in {@link get}.
779
+ *
780
+ * Since 0.8.0. Up to 0.7.x it walked its own copy of the chain: it never
781
+ * consulted lookups, never matched a namespace, reported keys held inside a
782
+ * non-global prior scope that {@link get} never reads, and answered a
783
+ * spelling from a source where {@link get} found no value - including every
784
+ * key at all, once a plain-object scope was pushed.
785
+ *
786
+ * @param key - The key as written.
787
+ * @returns The resolved key, or undefined when {@link get} finds nothing.
752
788
  */
753
789
  getKey(key: string | number | symbol): string | number | symbol | undefined;
754
790
  /**
@@ -1640,10 +1676,12 @@ declare class EvalHooks {
1640
1676
  * reaching the scan.
1641
1677
  *
1642
1678
  * Popping positionally instead would be correct only if every visitor
1643
- * bracketed its body exactly. `await-expression.ts` does not - it catches a
1644
- * child's synchronous throw and continues to its own `afterVisitor` - so a
1645
- * positional pop closes the child's frame under the parent's name, drops the
1646
- * child's `after` entirely, and leaks one frame onto the state for good.
1679
+ * bracketed its body exactly. Up to 0.6.x `await-expression.ts` did not - it
1680
+ * caught a child's synchronous throw and continued to its own
1681
+ * `afterVisitor` - so a positional pop closed the child's frame under the
1682
+ * parent's name, dropped the child's `after` entirely, and leaked one frame
1683
+ * onto the state for good. Since 0.7.0 no built-in visitor does that, and the
1684
+ * identity match stays as the guard against the next one.
1647
1685
  *
1648
1686
  * The synthesised events carry no `value` (the node never pushed one) and no
1649
1687
  * `error` (nothing threw; the frames are being closed because an enclosing