Class WeakPropertyPathMap<R, V>

Associates structural PropertyPath paths with values beneath weakly held root objects.

Each root is stored as a key in an internal WeakMap, and each root value is a trie-based PropertyPathMap. This provides structural path lookup while allowing the root and its complete path map to become eligible for garbage collection when the root is no longer referenced elsewhere.

const maps = new WeakPropertyPathMap<object, DataModel>();
const document = {};

maps.set(document, ['system', 'attributes', 'hp'], hpModel);
maps.set(document, ['system', 'attributes', 'ac'], acModel);

maps.get(document, ['system', 'attributes', 'hp']);
// hpModel

Like WeakMap, this collection cannot expose global size, entries, keys, values, or iteration because weak roots are intentionally not enumerable. Every query requires a known root object. clear is supported by replacing the internal WeakMap in constant time.

  • Root keys must be non-null objects or functions.
  • Property paths use all structural and symbol semantics provided by PropertyPathMap.
  • Different roots may store identical paths without conflict.
  • undefined is a valid stored value; use has to distinguish it from an absent path.
  • Deleting the final path for a root also removes that root from the internal WeakMap immediately.

The constructor accepts the same storage and traversal limits as PropertyPathMap. Limits apply independently to each root trie, and a failed first insertion is validated before the root is retained. Aggregate limits across all roots are intentionally unavailable because tracking weak roots globally would require strong retention and violate weak-collection semantics.

Matching and subtree iterators support maxDepth, maxResults, and maxVisits through the delegated PropertyPathMap options. Candidate getters and proxy traps may execute when matching requires property reads; their exceptions are intentionally propagated.

Root lookup is expected O(1). Path operations retain the O(path length) behavior of PropertyPathMap. Trie-aware matching retains shared-prefix pruning and visits only candidate branches reachable from stored paths. Matching entry and value iterators may optionally include the property value resolved from the candidate object. Prefix-bounded matching and candidate-independent subtree iteration retain the corresponding behavior of PropertyPathMap.

Type Parameters

  • R extends object

    Weak root object type.

  • V

    Stored value type.

Index
constructor
[toStringTag]
clear delete deleteRoot get has hasRoot matchingEntries matchingKeys matchingValues set subtreeEntries subtreeKeys subtreeValues

  • Creates a weak property-path map with limits applied independently to every live root trie.

    Because weak roots are not enumerable, aggregate limits across all live roots cannot be tracked without retaining those roots strongly. Constructor limits therefore apply per root while preserving normal weak-key collection semantics.

    Type Parameters

    • R extends object

      Weak root object type.

    • V

      Stored value type.

    Parameters

    Returns WeakPropertyPathMap<R, V>

    If options is invalid or a limit is not a non-negative safe integer.

  • get "[toStringTag]"(): string

    Provides the standard object tag used by Object.prototype.toString.

    Returns string

  • Removes every root association in constant time.

    The prior WeakMap and all path tries reachable only through it become eligible for garbage collection. Any iterator already returned by a matching or subtree method retains its direct reference to the corresponding path trie and may continue independently.

    Returns void

  • Deletes one exact property path beneath a root.

    If the removed path was the final entry beneath the root, the now-empty per-root trie is removed from the internal WeakMap. Missing roots and missing exact paths return false.

    Parameters

    • root: R

      Weak root object or function.

    • path: PropertyPath

      Dotted or exact property-key path.

    Returns boolean

    true when an exact path existed and was removed; otherwise false.

    If root is not a non-null object or function.

    If path is not a valid PropertyPath.

    If the path exceeds the configured per-root maxPathDepth.

  • Removes every path association beneath one known root.

    Parameters

    • root: R

      Weak root object or function.

    Returns boolean

    true when the root had an associated path trie; otherwise false.

    If root is not a non-null object or function.

  • Retrieves the value stored at an exact structural path beneath a root.

    undefined may mean either that the root / path is absent or that undefined is the stored value. Use has when that distinction matters.

    Parameters

    • root: R

      Weak root object or function.

    • path: PropertyPath

      Dotted or exact property-key path.

    Returns V

    Stored value or undefined when the root or exact path is absent.

    If root is not a non-null object or function.

    If path is not a valid PropertyPath.

    If the path exceeds the configured per-root maxPathDepth.

  • Determines whether an exact path stores a value beneath a root.

    Parameters

    • root: R

      Weak root object or function.

    • path: PropertyPath

      Dotted or exact property-key path.

    Returns boolean

    Whether the root exists and the exact path stores a value.

    If root is not a non-null object or function.

    If path is not a valid PropertyPath.

    If the path exceeds the configured per-root maxPathDepth.

  • Determines whether a root currently has at least one associated path.

    Roots whose final path is deleted are removed eagerly, so a true result always indicates a non-empty per-root trie.

    Parameters

    • root: R

      Weak root object or function.

    Returns boolean

    Whether the root currently owns a path trie.

    If root is not a non-null object or function.

  • Returns a trie-aware iterator of matching entries for one root.

    Matching behavior, prefix pruning, pathPrefix / stopAt bounds, maxDepth, result / visit budgets, array-index rules, inherited-property handling, optional candidate property values, and iteration order are delegated directly to PropertyPathMap.matchingEntries. A missing root behaves as an empty configured trie while still validating matching options during iterator consumption.

    Parameters

    • root: R

      Weak root object or function identifying the stored path trie.

    • data: unknown

      Candidate object or function to match against stored paths.

    • options: Match & { includePropertyValue: true }

      Matching options.

    Returns IterableIterator<[readonly PropertyKey[], V, unknown]>

    Iterator of canonical matching paths, mapped values, and optionally resolved candidate property values.

    If root, a boolean, numeric limit, or path option is invalid.

    If path bounds exceed configured limits or options.maxVisits is exceeded.

  • Returns a trie-aware iterator of matching entries for one root.

    Matching behavior, prefix pruning, pathPrefix / stopAt bounds, maxDepth, result / visit budgets, array-index rules, inherited-property handling, optional candidate property values, and iteration order are delegated directly to PropertyPathMap.matchingEntries. A missing root behaves as an empty configured trie while still validating matching options during iterator consumption.

    Parameters

    • root: R

      Weak root object or function identifying the stored path trie.

    • data: unknown

      Candidate object or function to match against stored paths.

    • Optionaloptions: Match & { includePropertyValue?: false }

      Matching options.

    Returns IterableIterator<[readonly PropertyKey[], V]>

    Iterator of canonical matching paths, mapped values, and optionally resolved candidate property values.

    If root, a boolean, numeric limit, or path option is invalid.

    If path bounds exceed configured limits or options.maxVisits is exceeded.

  • Returns a trie-aware iterator of matching entries for one root.

    Matching behavior, prefix pruning, pathPrefix / stopAt bounds, maxDepth, result / visit budgets, array-index rules, inherited-property handling, optional candidate property values, and iteration order are delegated directly to PropertyPathMap.matchingEntries. A missing root behaves as an empty configured trie while still validating matching options during iterator consumption.

    Parameters

    • root: R

      Weak root object or function identifying the stored path trie.

    • data: unknown

      Candidate object or function to match against stored paths.

    • Optionaloptions: Match

      Matching options.

    Returns IterableIterator<
        [readonly PropertyKey[], V, unknown]
        | [readonly PropertyKey[], V],
    >

    Iterator of canonical matching paths, mapped values, and optionally resolved candidate property values.

    If root, a boolean, numeric limit, or path option is invalid.

    If path bounds exceed configured limits or options.maxVisits is exceeded.

  • Returns a trie-aware iterator of canonical matching paths for one root.

    This delegates to PropertyPathMap.matchingKeys; see matchingEntries for complete matching, path-bound, and stop-bound semantics. A missing root produces an empty iterator while retaining option validation.

    Parameters

    • root: R

      Weak root object or function identifying the stored path trie.

    • data: unknown

      Candidate object or function to match against stored paths.

    • Optionaloptions: MatchKeys

      Path-only matching options.

    Returns IterableIterator<readonly PropertyKey[]>

    Iterator of canonical matching property paths.

    If root, a boolean, numeric limit, or path option is invalid.

    If path bounds exceed configured limits or options.maxVisits is exceeded.

  • Returns a trie-aware iterator of mapped values whose paths match a candidate value for one root.

    By default, mapped values are yielded directly. Set includePropertyValue to true to receive [mappedValue, propertyValue] tuples. Prefix and stop bounds are delegated to PropertyPathMap.matchingValues. A missing root produces an empty iterator while retaining normal option validation.

    Parameters

    • root: R

      Weak root object or function identifying the stored path trie.

    • data: unknown

      Candidate object or function to match against stored paths.

    • options: Match & { includePropertyValue: true }

      Matching options.

    Returns IterableIterator<[V, unknown]>

    Iterator of mapped values or mapped-value / candidate-property-value tuples.

    If root, a boolean, numeric limit, or path option is invalid.

    If path bounds exceed configured limits or options.maxVisits is exceeded.

  • Returns a trie-aware iterator of mapped values whose paths match a candidate value for one root.

    By default, mapped values are yielded directly. Set includePropertyValue to true to receive [mappedValue, propertyValue] tuples. Prefix and stop bounds are delegated to PropertyPathMap.matchingValues. A missing root produces an empty iterator while retaining normal option validation.

    Parameters

    • root: R

      Weak root object or function identifying the stored path trie.

    • data: unknown

      Candidate object or function to match against stored paths.

    • Optionaloptions: Match & { includePropertyValue?: false }

      Matching options.

    Returns IterableIterator<V>

    Iterator of mapped values or mapped-value / candidate-property-value tuples.

    If root, a boolean, numeric limit, or path option is invalid.

    If path bounds exceed configured limits or options.maxVisits is exceeded.

  • Returns a trie-aware iterator of mapped values whose paths match a candidate value for one root.

    By default, mapped values are yielded directly. Set includePropertyValue to true to receive [mappedValue, propertyValue] tuples. Prefix and stop bounds are delegated to PropertyPathMap.matchingValues. A missing root produces an empty iterator while retaining normal option validation.

    Parameters

    • root: R

      Weak root object or function identifying the stored path trie.

    • data: unknown

      Candidate object or function to match against stored paths.

    • Optionaloptions: Match

      Matching options.

    Returns IterableIterator<V | [V, unknown]>

    Iterator of mapped values or mapped-value / candidate-property-value tuples.

    If root, a boolean, numeric limit, or path option is invalid.

    If path bounds exceed configured limits or options.maxVisits is exceeded.

  • Stores a value at an exact structural path beneath a weak root.

    The per-root trie is created lazily on the first successful insertion. Invalid paths therefore cannot leave an empty root association behind. Existing roots reuse their current trie and retain all normal PropertyPathMap.set overwrite and insertion-order semantics.

    Parameters

    • root: R

      Weak root object or function.

    • path: PropertyPath

      Dotted or exact property-key path.

    • value: V

      Value to store. undefined is valid.

    Returns this

    This weak map.

    If root is not a non-null object or function.

    If path is not a valid PropertyPath.

    If the per-root path depth, entry count, or trie node count limit would be exceeded.

  • Returns a bounded subtree entry iterator for one weak root.

    Candidate-independent subtree behavior, absolute pathPrefix selection, descendant pruning through stopAt, relative maxDepth, result / visit budgets, and deterministic trie order are delegated to PropertyPathMap.subtreeEntries. A missing root behaves as an empty configured trie while still validating all options during iterator consumption.

    Parameters

    • root: R

      Weak root object or function identifying the stored path trie.

    • Optionaloptions: Subtree

      Subtree bounds.

    Returns IterableIterator<[readonly PropertyKey[], V]>

    Iterator of canonical stored paths and mapped values.

    If root, a numeric limit, or path option is invalid.

    If path bounds exceed configured limits or options.maxVisits is exceeded.

  • Returns a bounded subtree key iterator for one weak root.

    This delegates to PropertyPathMap.subtreeKeys. A missing root produces an empty iterator while retaining normal option validation.

    Parameters

    • root: R

      Weak root object or function identifying the stored path trie.

    • Optionaloptions: Subtree

      Subtree bounds.

    Returns IterableIterator<readonly PropertyKey[]>

    Iterator of canonical stored property paths.

    If root, a numeric limit, or path option is invalid.

    If path bounds exceed configured limits or options.maxVisits is exceeded.

  • Returns a bounded subtree value iterator for one weak root.

    This delegates to PropertyPathMap.subtreeValues. A missing root produces an empty iterator while retaining normal option validation.

    Parameters

    • root: R

      Weak root object or function identifying the stored path trie.

    • Optionaloptions: Subtree

      Subtree bounds.

    Returns IterableIterator<V>

    Iterator of mapped values.

    If root, a numeric limit, or path option is invalid.

    If path bounds exceed configured limits or options.maxVisits is exceeded.

Settings
Member Visibility

On This Page
Weak collection constraintsRoot and path semanticsDefensive limitsComplexity
Constructors
Accessors
Methods